Stoat for Web & Friends

Welcome to the developer documentation for the Stoat for Web project and general guidelines for other platforms we build for.

This is very much incomplete and needs more work!

Documentation Contribution Guidelines

This list is also very much incomplete, but it’ll grow as time goes on:

• Convert all assets to WebP when contributing new images.

Contribution Guide

If you have not yet read it, read the main contribution guide.

You can get started with Stoat for Web by following the development guide on the repository.

Contribution Policy

Since this project is still heavily in development, things may change rapidly at little notice, so it’s recommended that you join the Stoat server and the Stoat development server where you can talk in #Stoat for Web about this project.

If something is explicitly marked as ‘help wanted’, then you can likely just pick up the issue and contribute a PR, however, you should make sure to communicate this on the issue so others don’t start on the same issue as you, causing issues later.

Otherwise, feel free to come ask about what you’d like to contribute and run it past a maintainer so that we can check if there are any potential conflicts.

Feature Matrix

Comparison of implemented features across Revolt’s clients.

Conversations Sidebar

The conversations sidebar shows a short navigation menu to:

• Home
• Friends
• Saved Notes

With a list of direct and group conversations below (descending order by last message ID with a fallback to channel ID).

The conversations sidebar as it appears in Stoat for Web

Server Sidebar

The server sidebar is composed of the server banner with the title on top, and a list of categories and channels below.

Categories may be collapsed, and continue to show the active channels when collapsed

The server sidebar as it appears in Stoat for Web

Ordered Channels Algorithm

• Initialise a set $U$ of uncategorised channel IDs from server channels the client may access.
• Initialise an empty list of categories $C$
• If server.categories are defined, for each category:
  • Remove all the channels defined in the category from set $U$
  • Add category to list $C$
• If the set $U$ is not empty:
  • Find the “default” category if it exists in $C$
  • Merge the “default” category channels if they exist with and preceding the set $U$
  • Create a category with id=“default” and add it to the start of the list $C$ if it does not exist
• Return the list $C$

Text Channels

Message Grouping Algorithm

Within this algorithm, tail refers to whether the message omits displaying the user’s avatar / username.

This algorithm expects that the rendering of the output list is reversed, if you need it from oldest to newest: either reverse at the end or adapt the logic.

1. Let L be the list of messages ordered from newest to oldest
2. Let E be the list of elements to be rendered
3. Let blockedMessages be a counter initialized to 0
4. Let insertedUnreadDivider be a flag initialized to false
5. Let lastReadId be the ID of the last read message (or “0” if none)
6. For each message M in L:
   1. Let tail be true
   2. Let date be null
   3. Let next be the next item in list L
   4. If next is not null:
      1. Let adate and bdate be the times the message M and the next message were created respectively
      2. If adate and bdate are not the same day:
         1. Let date be adate
      3. Let tail be false if one of the following conditions is satisfied:
         • Message M and next do not have the same author
         • The difference between bdate and adate is equal to or over 7 minutes (420000ms)
         • The masquerades for message M and next do not match
         • Message M or next is a system message
         • Message M replies to one or more messages
         • next is before the last read message and the unread divider hasn’t been inserted yet
   5. Else if next is null:
      1. Let tail be false
   6. If the unread divider hasn’t been inserted and message M is before the last read message:
      1. Let insertedUnreadDivider be true
      2. Push an unread divider to list E
         (type id: 1; cache key: true)
   7. If the author of message M has a “Blocked” relationship:
      1. Increment blockedMessages
   8. Else:
      1. If blockedMessages > 0:
         1. Push blocked message count to list E
            (type id: 2; count: blockedMessages)
         2. Reset blockedMessages to 0
      2. Push the message to list E
         (type id: 0; cache key: message id:tail)
   9. If date is not null:
      1. Push date formatted as “MMMM D, YYYY” to list E
         (type id: 1; cache key: formatted date)
7. If blockedMessages > 0 after processing all messages:
   1. Push blocked message count to list E
      (type id: 2; count: blockedMessages)
8. If the first element in E is an unread divider (type id: 1):
   1. Remove it from E (to avoid showing it alone at the bottom)

Element Type IDs

• Type 0: Message entry with tail flag and message content
• Type 1: Message divider (either date divider or unread divider)
• Type 2: Blocked messages counter showing the number of consecutive blocked messages

Note: the Stoat client also caches the objects produced for list E by pushing each object into a Map by their given cache key above, then retrieving them the next time the code is run OR creating a new object if one is not present. This prevents Solid.js from completely rebuilding the DOM whenever the message list updates.

Message View

The message view is finnicky but important to get right, below is the high-level specification:

• The message chunk size is 50.
• A skeleton of messages is displayed where no messages have been loaded and may appear. This includes before initial load, at the top of the list (if more can be loaded), and at the bottom of the list (if more can be loaded).
• If there are no more messages at the top of the channel, there is a conversation start indicator.
• On initial load, a chunk of messages is requested.
• Scroll position is sticky to the bottom of the message view.
• New messages are added to the end when at the bottom of the message view.
• Messages are updated when edited or deleted.
• Scroll position is stable when loading / unloading messages.
• Scrolling into the top or bottom skeletons should load more messages in that direction.
• Up to 150 messages should be rendered (on or off screen) at any given moment.
• Ability to jump and centre to a particular message / unread message.
• Ability to jump to the latest messages.
• On failure to load messages, there should be an exponential backoff.
• There should be locks & signals that prevent double-fetching and cancel unrelated fetches if a new fetch (e.g. up instead of down, end instead of up/down) is initiated.

Session Lifecycle

To ensure reliability for users on Stoat, clients should implement the following rigid specification for maintaining a session. At a high-level, it should be implemented as a state machine.

flowchart TD
subgraph LOGGED_IN[Logged In - Display Client UI]
CONNECTED
CONNECTING
RECONNECTING
DISCONNECTED
OFFLINE
...
end

subgraph LOGGED_OUT[Logged Out - Display Auth Flow or Loading Indicator]
READY
LOGGING_IN
ONBOARDING
DISPOSE
ERROR
end

READY -->|LOGIN_UNCACHED| LOGGING_IN
READY -->|LOGIN_CACHED| CONNECTING
LOGGING_IN -->|NO_USER| ONBOARDING
LOGGING_IN -->|PERMANENT_FAILURE| ERROR
LOGGING_IN -->|TEMPORARY_FAILURE| ERROR
ONBOARDING -->|CANCEL| DISPOSE
DISPOSE -->|READY| READY
ERROR -->|DISMISS| DISPOSE

LOGGING_IN -->|SOCKET_CONNECTED| CONNECTED
RECONNECTING -->|SOCKET_CONNECTED| CONNECTED
CONNECTING -->|SOCKET_CONNECTED| CONNECTED

ONBOARDING -->|USER_CREATED| LOGGING_IN
CONNECTED -->|TEMPORARY_FAILURE| DISCONNECTED
DISCONNECTED -->|RETRY| RECONNECTING
DISCONNECTED -->|DEVICE_OFFLINE| OFFLINE
RECONNECTING -->|TEMPORARY_FAILURE| DISCONNECTED
CONNECTING -->|TEMPORARY_FAILURE| DISCONNECTED
CONNECTING -->|PERMANENT_FAILURE| ERROR
RECONNECTING -->|PERMANENT_FAILURE| ERROR
OFFLINE -->|DEVICE_ONLINE| RECONNECTING

... -->|LOGOUT| DISPOSE

Implementation Details

The table below describes how each node should behave.

• All nodes SHOULD have corresponding visual feedback.
• Nodes MAY have effects on entry.
• You SHOULD keep track of additional state such as:
  • Number of connection failures

^† Please use the formula $ (2^x-1) \pm 20 % \textsf{ seconds} $ for the delay where $ x $ is failure count.

// JavaScript implementation
let retryIn =
  (Math.pow(2, connectionFailureCount) - 1) * (0.8 + Math.random() * 0.4);
let retryInMs = retryIn * 1e3;
setTimeout(() => reconnect(), retryInMs);

The following listeners need to be registered that emit the given transitions:

Socket Details

When implementing your WebSocket connection, you should also implement the following:

• A heartbeat mechanism that sends the Ping event every 30 seconds, and disconnects if a Pong event is not received within 10 seconds.
• A connection timeout mechanism that drops the WebSocket connection if no message is received within 10 seconds of initiating the connection.

User Experience Considerations

• While not strictly relevant to session lifecycle, if you encounter BlockedByShield during login, you should provide a link to the relevant support article.
• Upon encountering a permanent error (session invalid), you should use the known user information to fetch their current flags. This way the message can be tailored to display if: they have been logged out, they disabled their account, their account has been suspended, or their account has been banned.
• When a logout event is received externally, show some sort of indicator that they have been logged out beyond just kicking them to the login screen.
• If the connection failure count reaches $ 3 $ or more, query the health service for any outage information. This point is WIP, need considerations about increasing polling rate while connection failures are high, etc.

Using Lingui

Import the macro package wherever you wish to use Lingui, prefer to use the JSX syntax:

import { Trans } from "@lingui-solid/solid/macro";

<Trans>Hi, I am a string!</Trans>

<Trans>There are {5} users in queue.</Trans>

But if necessary, you can use the hook where strings are needed:

import { useLingui } from "@lingui-solid/solid/macro";

const { t } = useLingui();

t`Hello, chat!`;

t`There are {3} people in your walls.`;

If your use case doesn’t fit here, ask a maintainer for guidance.

Plurals

Use the Plural component:

import { Plural } from "@lingui-solid/solid/macro";

<Plural
  value={5}
  one="# Member"
  other="# Members"
/>

Learn more in the Lingui documentation.

Updating catalogs

To update the catalogs, one must run:

pnpm --filter client lingui:extract && \
pnpm --filter client lingui:compile

NB. don’t run this yourself!
A maintainer will do this regularly & after merge down to main!

Using Dayjs

To use localised dayjs functions (or use any imported plugin), use the time hook:

import { useTime } from "@revolt/i18n";

function Component() {
  const dayjs = useTime();

  return <span>Time at initial render: {dayjs().format("LT")}</span>
}

Translating Errors

To handle an API error, use the hook:

import { useError } from "@revolt/i18n";

const err = useError();

<span>{err(someErrorObject)}</span>;

General Guidelines

This needs expanding on, but some key points!

• types.ts contains all the type information for modals
• modals.tsx contains all the component mounting code
• modals/*.tsx are all the individual modals
• All modals should use the Dialog component except in special circumstance
• If you take user input, use Form2 (ex. EditUsername)
• If you are performing an action, use Tanstack Mutations (ex. ChannelToggleMature)
  NB. take care to use mutateAsync instead of mutate to keep dialog open while pending
  NB. bind onError to showError from useModals()
• Do not mix Tanstack and Form2, you’re either using one or the other
  They both provide the necessary UX flows, e.g. ‘pending’ actions

Your action onClick handlers can return one of the following:

• A Promise<any> which on resolution will close the dialog, otherwise will do nothing.
• A non-false value which will close the dialog.
• The value false which will prevent the dialog from closing.

Reference Guide

WIP: currently undergoing some work on this…

Colour

The following Material colour roles are accessible through the CSS variables var(--md-sys-color-*):

TODO: extension with online,idle,focus,busy,invisible

Roundness

Border radius values are provided as var(--borderRadius-none|xs|sm|md|lg|li|xl|xli|xxl|full|circle), these correspond to the corner radius scale in Material 3 expressive design.

Learn more here about how to apply the scale: https://m3.material.io/styles/shape/corner-radius-scale

Gaps

Gap values are provided as var(--gap-none|xxs|xs|s|sm|md|lg|x|xl|xxl)

Fonts

Font values are provided by:

• Primary: var(--fonts-primary)
• Monospace: var(--fonts-monospace)

Typography

Typography tokens are currently fixed.

Transitions

Two transition speeds are specified (in format, <time> <easing>):

• Fast: var(--transitions-fast)
• Medium: var(--transitions-medium)

Using Form2

Form2 is the primary and recommended way to handle any complex user input to request pipeline.

It is intended to supersede <Form /> with the design goals of making form declarations a bit more involved to avoid complex implicit behaviours from forming, essentially following KISS philosophy.

@todo add information about how to display general errors!

In general, usage looks as follows:

// create your group using solid-forms
const group = createFormGroup({ .. });

// define your handler
// NB. can be a Promise<..>
async function yourSubmitHandler() {
  // do something with group.controls.<control>.value, ..

  if (somethingWrong) {
    throw "error";
    // inserted into errors as 'error'
  }
}

// define a handler to reset the form (if you need this functionality)
function onReset() {
  // group.controls.<control>.setValue(/* whatever it should be / now is */)
}

const submit = Form2.useSubmitHandler(editGroup, onSubmit, onReset);

Then create the form itself in the JSX code:

<form onSubmit={submit}>
  // use a wrapper for TextField that implements control:
  <Form2.TextField
    name="name"
    control={group.controls.name}
    label={t("i18n.key")}
  />
  // include an image picker:
  <Form2.FileInput control={group.controls.icon} accept="image/*" />
  // use the provided buttons for best integration:
  <Row>
    // if appropriate, allow the user to reset the form back to original state
    <Form2.Reset group={editGroup} onReset={onReset} />
    // in-built submission button:
    <Form2.Submit group={editGroup}>
      <Trans>Save</Trans>
    </Form2.Submit>
    // you should also indicate when submission is pending:
    <Show when={editGroup.isPending}>
      <CircularProgress />
    </Show>
  </Row>
</form>

There are examples provided throughout the code, just search for <Form2 in the codebase.

@todo explain this but…

when using with Modals, use !Form2.canSubmit for action