@fusion.dev/helix-headless 0.23.0 → 0.24.0

package/dist/chat/root/chat-root.d.ts

@@ -1,6 +1,25 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
-import type { HelixHeadlessChatMessage } from '../message/chat-message.js';
+import { type HelixHeadlessChatMessage } from '../message/chat-message.js';
+/** One turn handed over as data, which is what `turns` holds. */
+export interface ChatTurn {
+    /** When it was said, as anything `Date` parses. */
+    at?: string;
+    /** Who said it: `me`, `them`, or a name the consumer styles. */
+    author?: string;
+    /**
+     * What identifies it across changes to the set.
+     *
+     * Without one a turn is known by the object it is, which holds while the
+     * consumer keeps its objects and fails the moment it maps a fresh set from a
+     * response: history then loads under the reader rather than above them.
+     */
+    key?: string;
+    /** What has happened to it, as on `helix-chat-message`. */
+    state?: 'failed' | 'sending' | 'sent' | 'streaming';
+    /** What was said, as text. */
+    text: string;
+}
 declare const HelixHeadlessChat_base: (new (...args: any[]) => import("@fusion.dev/helix-core").CollectionElement) & typeof HelixElement;
 /**
  * @summary A conversation: the turns, and where the reader is in them.
@@ -16,7 +35,29 @@ declare const HelixHeadlessChat_base: (new (...args: any[]) => import("@fusion.d
  * **Scroll ownership is the behavior everything else depends on.** A transcript
  * that grows wants to stay at the bottom, except when the reader has scrolled
  * up to read, where pinning is hostile. The rule: pin while the reader is
- * within `threshold` of the bottom, and let go the moment they leave it.
+ * within `threshold` of the bottom, and let go the moment they leave it. A turn
+ * growing under a pinned reader is not the reader leaving, so a streamed answer
+ * is followed to its last line.
+ *
+ * **History loads upward, under a reader who does not move.** With `history`
+ * set to `more`, reaching the top fires `helix-history`; the consumer sets
+ * `loading` while it fetches and prepends the older turns, and the turn the
+ * reader was looking at stays where it was on screen while the room above it
+ * grows.
+ *
+ * **A turn is announced once, when it settles**, and not by the log. A log
+ * that is a live region reads what enters it, which is every token of a stream
+ * where `aria-busy` is not honored, every page of history as it loads, and
+ * every window of a long transcript as the reader scrolls through it. So the
+ * log is `aria-live="off"`, and a status region of its own says each new turn
+ * when it has finished arriving: never the reader's own words unless they
+ * failed to send, never a turn loaded above the ones already there, and never
+ * what was in the transcript when it opened.
+ *
+ * **Turns are markup children or data, not both.** Children serve whole from a
+ * server and are what most conversations want. `turns` is for the transcript
+ * too long to hold as elements: it is drawn a window at a time, measured as it
+ * goes, and the log needs a block size of its own for that to mean anything.
  *
  * @since 0.1.0
  * @status experimental
@@ -32,15 +73,22 @@ declare const HelixHeadlessChat_base: (new (...args: any[]) => import("@fusion.d
  * @slot status - Beside the composer: somebody typing, connection lost.
  *
  * @event {HelixBeforePinEvent} helix-before-pin - Fired when the reader pins or unpins the transcript by scrolling. Cancelable.
+ * @event {HelixHistoryEvent} helix-history - Fired when the reader reaches the oldest turn while `history` is `more`, reporting where they are rather than asking.
+ * @event {HelixSendEvent} helix-send - A turn offered from the composer, or a failed one asked to go again, dispatched inside and heard here because the conversation is what a consumer holds. Cancelable: refusing it takes the decision and nothing is sent.
  *
  * @csspart actions - The controls for the conversation, at the header's trailing edge.
+ * @csspart after - The room the turns below the window would take. Data only.
+ * @csspart before - The room the turns above the window would take. Data only.
  * @csspart composer - The region the composer sits in.
  * @csspart empty - Shown when the conversation has no turns.
  * @csspart header - The region above the transcript.
+ * @csspart history - Shown at the top of the transcript while older turns are on their way.
+ * @csspart live - Where each settled turn is said, for a reader who cannot see it arrive.
  * @csspart loading - Shown while the history is still on its way.
  * @csspart log - The transcript, which is the thing that scrolls.
  * @csspart resume - The affordance offered while the reader is away from the bottom.
  * @csspart status - The status region, which is not part of the log.
+ * @csspart turn - One turn fed as data, around the message drawn for it.
  */
 export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
     /**
@@ -53,10 +101,25 @@ export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
      * patch up.
      */
     static shadowRootOptions: ShadowRootInit;
+    /** How tall a turn is assumed to be before it has been drawn, in pixels. */
+    static readonly ESTIMATE = 72;
     /**
      * Whether to open pinned, where nothing declared it.
      */
     defaultPinned: boolean;
+    /**
+     * Whether there are older turns than the ones here, and whether they are coming.
+     *
+     * `more` makes reaching the top fire `helix-history`, once per arrival;
+     * `loading` draws `history-text` above the oldest turn and fires nothing; empty
+     * says this is the start of the conversation. The consumer owns it, because
+     * only the consumer knows whether the server has anything older.
+     */
+    history: '' | 'loading' | 'more';
+    /**
+     * What to say while older turns are on their way.
+     */
+    historyText: string;
     /**
      * Accessible name for the conversation.
      */
@@ -87,12 +150,48 @@ export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
      * A hook rather than a constant, because the right number depends on how tall
      * a turn is: a transcript of one-line replies wants a smaller threshold than
      * one of paragraphs, and a reader who has scrolled up by half a message has
-     * not left.
+     * not left. The same distance from the top is what counts as reaching the
+     * history.
      */
     threshold: number;
+    /**
+     * The turns as data, for a transcript too long to hold as elements.
+     *
+     * Drawn a window at a time, so the log needs a block size. Set it or declare
+     * children, not both: while it holds anything the children are not drawn.
+     *
+     * **Read, never written**, and replaced rather than mutated: a streamed turn
+     * is a new array with the last turn's text longer, which is what tells this
+     * element to look again.
+     */
+    turns: readonly ChatTurn[];
     private pinnedState;
+    /** The last thing said, and how many times something has been. */
+    private announcement;
+    private said;
     /** Watches for turns arriving, since a manual slot hears nothing about them. */
     private watcher;
+    /** Watches the turns' own `state`, which is when one of them settles. */
+    private settling;
+    /** Watches the turns and the log for size, which scrolling does not report. */
+    private grower;
+    /** What `grower` is watching, so a render that changed nothing re-observes nothing. */
+    private watched;
+    /** The scroll offset this element last set, which the reader has not moved from. */
+    private stuckAt;
+    /** The turn at the top of the reader's view, and how far below the top it sat. */
+    private anchor;
+    /** Whether `helix-history` has been fired for this arrival at the top. */
+    private asked;
+    /**
+     * Until the first frame, what is in the transcript is what it opened with, and
+     * its box is not yet the box it will have.
+     */
+    private opening;
+    /** The newest turn already accounted for, and the turns still arriving. */
+    private newest;
+    private pending;
+    private readonly virtualize;
     /**
      * Which regions were given something, or undefined where nobody has counted.
      *
@@ -107,19 +206,34 @@ export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
      *
      * Undefined rather than empty on the way in, for `MixinCollection`'s reason:
      * the server has no children to count, and an unknown answer is not "empty".
-     * It serves every region and the first assignment on the client settles them,
+     * It serves every region and the first update on the client settles them,
      * which is a shadow-root attribute rather than a host one and so is nothing a
      * consumer's hydration compares.
      */
     private filled;
     /** Whether a region has something in it, taking unknown for yes. */
     private has;
+    /** Whether the turns are data rather than children. */
+    private get fed();
     /** The turns declared as children, in the order they are written. */
     get messages(): HelixHeadlessChatMessage[];
     /** The element that scrolls, once there is one. */
     private get log();
     /** Whether the reader is within `threshold` of the bottom right now. */
     private get atBottom();
+    /** What identifies a turn fed as data: its key, or the object it is. */
+    private identity;
+    /**
+     * The turns fed as data that are drawn, each with its place in the whole set.
+     *
+     * Read off `data-index` rather than counted, for the reason the table gives:
+     * the controller asks before `updated`, while the previous window is drawn.
+     */
+    private drawn;
+    /** The turns on screen, in order, each with what identifies it. */
+    private rendered;
+    /** Every turn as the announcer reads it. */
+    private heard;
     /**
      * Puts the transcript back at its most recent turn.
      *
@@ -128,6 +242,8 @@ export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
      * a reader asking to go to the bottom means.
      */
     resume(): void;
+    /** Scrolls to the bottom, and remembers where that was. */
+    private stick;
     /**
      * Asks to pin or unpin, and reports whether the request stood.
      *
@@ -138,6 +254,64 @@ export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
      */
     private requestPinned;
     private assign;
+    /** The children a region is assigned, by the `slot` each one names. */
+    private given;
+    /**
+     * Notes which regions were given something, before the render that hides the
+     * rest.
+     *
+     * From the children rather than the slots, so the first render has the
+     * answer: the slots exist only once a render has made them. Not on the
+     * server, where `children` is undefined, so `filled` stays unknown there, and
+     * not while hydrating what a server sent, which renders the same unknown.
+     */
+    private countRegions;
+    /**
+     * Notes which turn is at the top of the reader's view, and where.
+     *
+     * A binary search, because the turns are in order down the log: a transcript
+     * of five hundred scrolled to its end costs nine measurements, not five
+     * hundred, and this runs on every scroll.
+     */
+    private remember;
+    /**
+     * Puts the turn the reader was looking at back where they saw it.
+     *
+     * **By the turn, not by the offset.** History arriving above adds room the
+     * reader never scrolled through, so the offset they were at is now an older
+     * turn; what they were reading is the one fixed point. It is also idempotent,
+     * which is what lets it run beside the browser's own scroll anchoring where
+     * there is some: a turn the browser already put back has not moved.
+     */
+    private restore;
+    /** Fires `helix-history` once for each time the reader reaches the top. */
+    private reachHistory;
+    /**
+     * Says the turns that have settled since the last time it looked.
+     *
+     * **New means after the newest turn already accounted for.** Turns loaded
+     * above it are history and are not said; if the newest turn is gone, the set
+     * was replaced rather than added to, and nothing is said either. A single turn
+     * arriving in an empty transcript is a conversation starting and is said;
+     * several at once is a transcript loading and is not.
+     *
+     * A turn still `sending` or `streaming` waits, and is said when it settles.
+     */
+    private announce;
+    /** The turns after the newest one already accounted for, by the rules above. */
+    private arrived;
+    private phrase;
+    /** Watches what is drawn for size, re-observing only when that changed. */
+    private watchSizes;
+    /**
+     * A turn or the log changed size, which moves nothing on its own.
+     *
+     * Pinned, the bottom is followed: this is a streamed answer growing a line at
+     * a time, and it is the only notice of it, since growing content fires no
+     * scroll. Unpinned, the reader's turn is put back, which is an image loading
+     * above them in a browser without scroll anchoring.
+     */
+    private readonly handleResize;
     /**
      * A press anywhere in the way back takes the reader back.
      *
@@ -152,8 +326,18 @@ export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected willUpdate(changed: PropertyValues): void;
+    /**
+     * Keeps the window on the same turns when the set changes around them.
+     *
+     * Turns added before the first one are history, and the controller is told
+     * how many so every measurement moves with its turn. A first turn that is gone
+     * means the set was trimmed or replaced, and a measurement that now names a
+     * different turn is worse than the estimate.
+     */
+    private follow;
     protected updated(changed: PropertyValues): void;
     private readonly handleSlotChange;
+    private readonly handleSettle;
     /**
      * The reader's own scrolling, which is the only thing that unpins.
      *
@@ -172,8 +356,15 @@ export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
      * wheel does. Reading the position rather than counting events is what makes
      * that harmless, since after a programmatic scroll the position is the bottom
      * and the answer is the one that was already true.
+     *
+     * **Nor does the transcript growing under a reader who has not moved.** A
+     * pinned reader who is suddenly far from the bottom while still at the offset
+     * this element put them at has been left behind by a turn, not gone anywhere,
+     * and is followed. Leaving is moving up from there.
      */
     private readonly handleScroll;
+    /** The turns fed as data, a window of them, between the room the rest would take. */
+    private renderTurns;
     protected render(): TemplateResult;
 }
 declare global {