nexus-shared 2.0.0 → 3.0.0

package/dist/Helpers/ChatHooks.js

@@ -0,0 +1,175 @@
+"use client";
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { apiChatPlace, apiChatSource, chatSummaries } from "../Services/ChatApi.js";
+import { chatPlaceSummary, chatScopeKey } from "./ChatHelpers.js";
+import { ChatStore } from "./ChatStore.js";
+/** Whether the page is in front: a background tab stops polling and starts again when it comes back. */
+const pageIsActive = () => typeof document === "undefined" || document.visibilityState !== "hidden";
+/**
+ * One conversation, kept for as long as the scope stays the same.
+ *
+ * @example
+ * const { store, state } = useChat({ scope, enabled: open });
+ * state.messages.map(…);
+ * store.send(text);
+ */
+export function useChat(options) {
+    const { scope, conversationId, source, pageSize, pollInterval, summary, participants, enabled = true } = options;
+    // The reader is part of the key: the same record read by somebody else is another conversation's unread count. So is
+    // the conversation, because one record can hold several and each has its own messages, counts and unread line.
+    const key = `${chatScopeKey(scope)}:${String(scope.userId)}${conversationId === undefined ? "" : `:${String(conversationId)}`}`;
+    const summaries = chatSummaries();
+    // Read while rendering, so a store built below starts with what the page already knows.
+    const latest = useRef({ scope, source, summary, participants });
+    latest.current = { scope, source, summary, participants };
+    const store = useMemo(() => {
+        const { scope: at, source: from, summary: counts, participants: people } = latest.current;
+        const made = new ChatStore({
+            source: from ?? apiChatSource(at, conversationId === undefined ? undefined : { conversationId }),
+            userId: at.userId,
+            pageSize,
+            pollInterval,
+            ...(counts && { summary: counts }),
+            isActive: pageIsActive,
+            // The icon in the list behind the panel follows the panel: a message sent, a conversation read. A record with
+            // several conversations is counted by the place instead (`useChatPlace`), since one icon stands for all of them.
+            onSummary: next => {
+                if (conversationId === undefined)
+                    summaries.set(at, next);
+            },
+        });
+        if (people)
+            made.setParticipants(people);
+        return made;
+        // A new store only for another conversation. `source`, `summary`, and `participants` reach it below.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [key, pageSize, pollInterval, summaries, conversationId]);
+    useEffect(() => {
+        if (source)
+            store.setSource(source);
+    }, [store, source]);
+    useEffect(() => {
+        if (participants)
+            store.setParticipants(participants);
+    }, [store, participants]);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        void store.load();
+        store.start();
+        return () => store.stop();
+    }, [store, enabled]);
+    useEffect(() => () => store.dispose(), [store]);
+    const state = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+    return { store, state };
+}
+/**
+ * The conversations one record holds. A leave request can carry several — the manager and the applicant in one, the
+ * managers between themselves in another — and this is the list behind the switch, the New chat form, and the one
+ * count the trigger icon shows for the record as a whole.
+ */
+export function useChatPlace(options) {
+    const { scope, place, conversations: given, enabled = true } = options;
+    const key = `${chatScopeKey(scope)}:${String(scope.userId)}`;
+    const summaries = chatSummaries();
+    const [conversations, setConversations] = useState(given ?? []);
+    const [loading, setLoading] = useState(false);
+    const [creating, setCreating] = useState(false);
+    const [error, setError] = useState(null);
+    const latest = useRef({ scope, place, given });
+    latest.current = { scope, place, given };
+    const source = useMemo(() => latest.current.place ?? apiChatPlace(latest.current.scope), [key, place]); // eslint-disable-line react-hooks/exhaustive-deps
+    useEffect(() => {
+        if (given)
+            setConversations(given);
+    }, [given]);
+    // The record's one count is every conversation in it added up, which is what the icon in a list stands for.
+    useEffect(() => {
+        if (conversations.length > 0)
+            summaries.set(latest.current.scope, chatPlaceSummary(conversations));
+    }, [summaries, conversations]);
+    const reload = useCallback(async () => {
+        if (latest.current.given)
+            return;
+        setLoading(true);
+        try {
+            const list = await source.conversations();
+            setConversations(list);
+            setError(null);
+        }
+        catch (failure) {
+            setError(failure instanceof Error ? failure.message : "The conversations could not be read.");
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [source]);
+    useEffect(() => {
+        if (enabled)
+            void reload();
+    }, [enabled, reload]);
+    const create = useCallback(async (request) => {
+        if (!source.create)
+            return null;
+        setCreating(true);
+        try {
+            const made = await source.create(request);
+            // A one-to-one that already existed comes back instead of a second one, so it is put in place, not added twice.
+            setConversations(held => [made, ...held.filter(one => String(one.id) !== String(made.id))]);
+            setError(null);
+            return made;
+        }
+        catch (failure) {
+            setError(failure instanceof Error ? failure.message : "The conversation could not be started.");
+            return null;
+        }
+        finally {
+            setCreating(false);
+        }
+    }, [source]);
+    const apply = useCallback((conversationId, summary) => {
+        setConversations(held => {
+            const at = held.findIndex(one => String(one.id) === String(conversationId));
+            if (at === -1)
+                return held;
+            const before = held[at].summary;
+            if (before && before.messageCount === summary.messageCount && before.unreadCount === summary.unreadCount && before.lastMessageAt === summary.lastMessageAt)
+                return held;
+            const next = [...held];
+            next[at] = { ...held[at], summary };
+            return next;
+        });
+    }, []);
+    return { conversations, loading, error, canCreate: typeof source.create === "function", creating, reload, create, searchParticipants: source.participants, apply };
+}
+/**
+ * The counts one trigger icon draws itself from. Without `given`, it asks the page's cache, which collects every icon
+ * that mounted in the same moment and fills them in one call per domain. With `given` — a list whose rows already
+ * carry the counts — nothing is asked at all.
+ */
+export function useChatSummary(scope, given) {
+    const summaries = chatSummaries();
+    const key = `${chatScopeKey(scope)}:${String(scope.userId)}`;
+    const at = useRef(scope);
+    at.current = scope;
+    const subscribe = useCallback((listener) => summaries.subscribe(at.current, listener), [summaries, key]); // eslint-disable-line react-hooks/exhaustive-deps
+    const read = useCallback(() => summaries.get(at.current), [summaries, key]); // eslint-disable-line react-hooks/exhaustive-deps
+    const server = useCallback(() => undefined, []);
+    const held = useSyncExternalStore(subscribe, read, server);
+    // Counts the page knows are put into the cache, so the icon starts right and then follows the panel: reading a
+    // conversation clears its badge even though the row behind it still carries the number it was loaded with. They are
+    // put in again only when the page's own numbers change, never on a render that merely repeated them.
+    const seeded = useRef(null);
+    useEffect(() => {
+        if (!given) {
+            summaries.want(at.current);
+            return;
+        }
+        const before = seeded.current;
+        if (before && before.key === key && before.messageCount === given.messageCount && before.unreadCount === given.unreadCount)
+            return;
+        seeded.current = { key, messageCount: given.messageCount, unreadCount: given.unreadCount };
+        summaries.set(at.current, given);
+    }, [summaries, key, given]);
+    return { summary: held ?? given, state: held ? "ready" : given ? "ready" : summaries.stateOf(scope) };
+}

package/dist/Helpers/ChatStore.d.ts

@@ -0,0 +1,132 @@
+import type { ChatDraft, ChatHistory, ChatId, ChatMessage, ChatParticipant, ChatParticipantPage, ChatParticipantQuery, ChatSource, ChatSummary } from "../Interfaces/ChatInterfaces.ts";
+export interface ChatStoreOptions {
+    source: ChatSource;
+    /** Who is reading: their messages sit on the right, and the unread count is theirs. */
+    userId: ChatId;
+    /** Messages per page. Default 30. */
+    pageSize?: number;
+    /** Milliseconds between checks for new messages, while `start()` is on. 0 turns it off; a source that watches never polls. Default 15,000. */
+    pollInterval?: number;
+    /** The counts the page already had, so the panel opens with its header filled. */
+    summary?: ChatSummary;
+    /** Every time the counts change, so the trigger icon in the list behind the panel follows them. */
+    onSummary?: (summary: ChatSummary) => void;
+    /** Whether polling should happen now; the panel passes the tab's visibility. Default: always. */
+    isActive?: () => boolean;
+    /** The moment a message being sent is drawn with. Default: now. For tests. */
+    now?: () => string;
+}
+/**
+ * What the conversation's source can do. A panel hides what a source cannot serve, rather than offering a button that
+ * answers nothing: no Delete without `remove`, no people column without `participants`.
+ */
+export interface ChatFeatures {
+    participants: boolean;
+    addParticipants: boolean;
+    markRead: boolean;
+    remove: boolean;
+    watch: boolean;
+}
+/** What a source can do, read from the source itself. */
+export declare function chatFeaturesOf(source: ChatSource): ChatFeatures;
+/** Everything the panel draws, replaced as a whole whenever any of it changes. */
+export interface ChatSnapshot {
+    messages: readonly ChatMessage[];
+    participants: readonly ChatParticipant[];
+    summary: ChatSummary;
+    /** Whether this user may write here. */
+    canSend: boolean;
+    /** What the source can do. */
+    features: ChatFeatures;
+    /** The first page is on its way. */
+    loading: boolean;
+    /** A page has arrived at least once, so the counts here are this conversation's and not the empty ones it started with. */
+    loaded: boolean;
+    /** A page of older messages is on its way. */
+    loadingOlder: boolean;
+    /** Older messages remain above. */
+    hasMore: boolean;
+    /** Why the last read failed, shown in the thread with Retry. Sending failures sit on their own message. */
+    error: string | null;
+    /** How many messages are on their way. */
+    sending: number;
+    /** How many failed and are waiting to be sent again or dropped. */
+    failed: number;
+    /** The message the "New messages" line goes before. Set when the conversation opens, and left alone while it is read. */
+    unreadFrom: ChatId | null;
+    /** Grows on every change, so a snapshot is never equal to the one before it. */
+    revision: number;
+}
+export declare class ChatStore {
+    private options;
+    private listeners;
+    private snapshot;
+    private messages;
+    private pending;
+    private revision;
+    private loaded;
+    private poll;
+    private unwatch;
+    private running;
+    private readPast;
+    private aborts;
+    private clientSequence;
+    constructor(options: ChatStoreOptions);
+    readonly subscribe: (listener: () => void) => (() => void);
+    readonly getSnapshot: () => ChatSnapshot;
+    /** The newest message the server knows about: what the read mark and a refresh count from. */
+    private newestSaved;
+    private oldest;
+    private set;
+    /** Puts the messages and the ones still on their way together, newest last, and tells the snapshot. */
+    private commit;
+    private announce;
+    /** The counts after the messages changed: the server's, with what this browser knows added. */
+    private recount;
+    private track;
+    /** The newest page. Call it when the conversation opens, and again to start over. */
+    load(): Promise<void>;
+    /** One page of older messages, above the ones held. */
+    loadOlder(): Promise<void>;
+    /** Whatever was written since the newest message held. Polling and the Retry button both call it. */
+    refresh(): Promise<void>;
+    /** Messages that arrived on their own: a poll, or a source that watches. */
+    readonly take: (incoming: readonly ChatMessage[], page?: Pick<ChatHistory, "summary" | "participants">) => void;
+    private pageSize;
+    /** Sends a message. It is on screen before the call starts; if the call fails it stays, with Retry beside it. */
+    send(body: string, extras?: {
+        replyToId?: ChatId | null;
+        files?: readonly File[];
+    }): Promise<boolean>;
+    /** Sends a failed message again, with the text it was written with. */
+    readonly retry: (clientId: string) => Promise<boolean>;
+    /** Drops a failed message. Nothing was saved, so nothing is deleted. */
+    readonly discard: (clientId: string) => void;
+    /** The text of a failed message, so the composer can put it back for editing. */
+    draftOf(clientId: string): ChatDraft | undefined;
+    private deliver;
+    /** Removes a message the user may remove. */
+    remove(messageId: ChatId): Promise<boolean>;
+    /** Says the user has read everything held. Clears the count; the line stays until the conversation is opened again. */
+    markRead(): Promise<void>;
+    /** Takes the "New messages" line away, once it has been seen. */
+    readonly clearUnreadLine: () => void;
+    /** Searches the people in the conversation and the ones who could join. Empty when the source has no search. */
+    readonly searchParticipants: (query: ChatParticipantQuery) => Promise<ChatParticipantPage>;
+    /** Adds people, and keeps the ones the source answers with. */
+    addParticipants(ids: readonly ChatId[]): Promise<boolean>;
+    /** Participants the page already has, so the panel needs no call. */
+    readonly setParticipants: (participants: readonly ChatParticipant[]) => void;
+    /**
+     * Points the store at another source, keeping the messages it holds. A page that builds its source while it renders
+     * hands in a new object every time; this takes it without starting the conversation over, and keeps the store's own
+     * reading of what the source can do (a search, a read mark, Delete) true.
+     */
+    readonly setSource: (source: ChatSource) => void;
+    /** Starts watching for new messages: the source's own watch, else a poll. */
+    start(): void;
+    /** Stops watching. The messages stay. */
+    stop(): void;
+    /** Stops everything and drops the calls on their way. The messages and unsent drafts stay, for a panel that reopens. */
+    dispose(): void;
+}