@fusion.dev/helix-headless 0.0.0-dev

package/dist/chat/message/chat-message.js

@@ -0,0 +1,271 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { customElement, HelixElement, HelixSendEvent, hostAria, relativeTime, slotFilled, TONE_MARKS, } from '@fusion.dev/helix-core';
+import { html, nothing } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
+/**
+ * @summary One turn in a conversation, and what has happened to it.
+ *
+ * @description
+ * **The states are the component.** Bubbles are paint; what a chat message has
+ * to carry is whether it is on its way, arrived, still arriving, or failed, and
+ * a failed message needs a retry that is a real action rather than a toast the
+ * reader has to catch.
+ *
+ * `streaming` is the state everything else is arranged around. A message
+ * arriving token by token changes height on every frame, so it is marked
+ * `aria-busy` while it arrives and announced once when it settles: a screen
+ * reader reading a stream character by character is unusable, and announcing on
+ * completion is the only version of this that works.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category feedback
+ * @aliases Message, Bubble, Turn
+ * @documentation https://helix.fusion.dev/components/chat
+ *
+ * @slot - What was said.
+ * @slot actions - What can be done with it: copy, retry, react.
+ * @slot avatar - Who said it.
+ * @slot sources - What it was said from: citations, documents, a retrieved page.
+ *
+ * @event {HelixSendEvent} helix-send - Fired when the reader asks to send a failed message again, and cancelable.
+ *
+ * @csspart actions - The controls offered on the turn, beside its time.
+ * @csspart avatar - The leading slot's box.
+ * @csspart body - What was said, and the line under it.
+ * @csspart content - The consumer's own markup.
+ * @csspart mark - The status glyph beside a failure.
+ * @csspart message - The whole turn.
+ * @csspart meta - The line under a turn: its time, its state, and its controls.
+ * @csspart retry - The control offered on a failed message.
+ * @csspart sources - What the turn was drawn from, under it and outside the bubble.
+ * @csspart state - What has happened to it, where that is worth saying.
+ * @csspart time - When it was said.
+ */
+let HelixHeadlessChatMessage = class HelixHeadlessChatMessage extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * When it was said, as anything `Date` parses.
+         */
+        this.at = '';
+        /**
+         * Locale for the timestamp.
+         *
+         * Empty is the runtime's own.
+         */
+        this.locale = '';
+        /**
+         * What to call each state, for a reader who cannot see it.
+         */
+        this.sendingLabel = 'Sending';
+        /**
+         * @internal
+         */
+        this.failedLabel = 'Not sent';
+        /**
+         * Label for the control offered on a failed message.
+         */
+        this.retryLabel = 'Try again';
+        /**
+         * @internal Read by the transcript to identify its children across the light
+         * DOM, which is cheaper than `instanceof`. Not a consumer's to read or set.
+         */
+        this.isChatMessage = true;
+        this.clock = undefined;
+        /**
+         * A turn's own content arrives and changes no property here.
+         *
+         * It is the streaming case that needs this rather than a tidiness one: the
+         * first token of an answer is a light-DOM child appearing under an element
+         * nothing else told to look again, and it is exactly the moment the typing
+         * indicator has to stop being drawn.
+         */
+        this.handleFill = () => {
+            this.markEmpty();
+        };
+        /**
+         * Retry is `helix-send` again, from the message rather than the composer.
+         *
+         * **Not an event of its own**, because a retry is the same request: the reader
+         * is offering what they wrote, and the only difference is which element is
+         * offering it. A listener that wants to tell them apart has `event.target`,
+         * which is the message on a retry and the composer on a first send, and that
+         * is a distinction the DOM already makes without a second name for it.
+         */
+        this.handleRetry = (event) => {
+            event.stopPropagation();
+            this.dispatchEvent(new HelixSendEvent({ value: this.textContent?.trim() ?? '' }));
+        };
+    }
+    /** The timestamp, or nothing where there is not one to read. */
+    get moment() {
+        if (this.at === '') {
+            return undefined;
+        }
+        const parsed = new Date(this.at);
+        return Number.isNaN(parsed.getTime()) ? undefined : parsed;
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        if (changed.has('at')) {
+            this.clock = Date.now();
+        }
+        /* `article` rather than `listitem`, because the transcript is a `log` and a
+           log's children are not list items: a turn is a self-contained thing a
+           reader can be moved to, which is what an article is for.
+           
+           `aria-busy` while it arrives is the whole of the streaming contract on
+           this side: the live region above it holds its announcement until the flag
+           clears, so the message is read once, whole, rather than per token. */
+        hostAria(this.internals, { role: 'article' });
+        this.toggleAttribute('aria-busy', this.state === 'streaming');
+    }
+    renderTime() {
+        const moment = this.moment;
+        if (!moment) {
+            return nothing;
+        }
+        const { text } = relativeTime(this.locale)(moment, new Date(this.clock ?? Date.now()));
+        return html `<time part="time" datetime=${moment.toISOString()}>${text}</time>`;
+    }
+    /**
+     * The status glyph, behind a seam so a tier can draw its own.
+     *
+     * `TONE_MARKS.danger` rather than a glyph chosen here: the library has one
+     * status vocabulary, `Callout`, `Toast.Item` and `Announcement` all read from
+     * it, and a reader meets these four marks in a passage, in a message and now
+     * on a turn and has to read them as the same four things. It carries the
+     * accessible name with it, which is the half that matters: `danger` is the
+     * word the API uses and "Error" is the word a reader understands.
+     */
+    renderMark() {
+        const { icon, label } = TONE_MARKS.danger;
+        return html `<svg
+      part="mark"
+      fill="currentColor"
+      viewBox=${icon.viewBox}
+      role="img"
+      aria-label=${label}
+    >
+      ${unsafeSVG(icon.content)}
+    </svg>`;
+    }
+    /**
+     * What has happened to it, in words, and the way back from a failure.
+     *
+     * A seam of its own, because the styled tier draws a failure as an icon and a
+     * consumer may want neither. `sent` says nothing: every settled message is
+     * sent, and a transcript that labels each one is a transcript of the word
+     * "sent".
+     */
+    renderState() {
+        if (this.state === 'sending') {
+            return html `<span part="state">${this.sendingLabel}</span>`;
+        }
+        if (this.state !== 'failed') {
+            return nothing;
+        }
+        /* **The mark, and not because color needs a second carrier here.** "Not
+           sent" is words, so the meaning survives without it. It is here because a
+           failure is the one state that has to be *found* rather than noticed, and a
+           shape is what a reader scanning a transcript finds. */
+        return html `<span part="state"
+      >${this.renderMark()} ${this.failedLabel}
+      <button part="retry" type="button" @click=${this.handleRetry}>${this.retryLabel}</button>
+    </span>`;
+    }
+    /**
+     * Says on each region whether anything is in it.
+     *
+     * Three of them need the answer and no selector can give it: a slot's assigned
+     * nodes are not its DOM children, so `:empty` and `:has(*)` both describe the
+     * fallback rather than the fill. `sources` and `actions` are regions that cost
+     * a gap when they are boxes at all, which most turns should not pay. `content`
+     * is the one that is not about space: a turn that is `streaming` with nothing
+     * in it yet is what the typing indicator is drawn for, and "nothing in it yet"
+     * is exactly this question.
+     */
+    markEmpty() {
+        for (const name of ['content', 'sources', 'actions']) {
+            const region = this.renderRoot?.querySelector(`[part="${name}"]`);
+            const slot = name === 'content'
+                ? this.renderRoot?.querySelector('slot:not([name])')
+                : this.renderRoot?.querySelector(`slot[name="${name}"]`);
+            const empty = !slotFilled(slot);
+            region?.toggleAttribute('data-empty', empty);
+            /* `content` keeps its box when empty, because the typing indicator is
+               painted into it. The other two are gaps nobody asked for. */
+            if (name !== 'content') {
+                region?.toggleAttribute('hidden', empty);
+            }
+        }
+    }
+    updated(changed) {
+        super.updated(changed);
+        this.markEmpty();
+    }
+    /**
+     * The turn: who said it, what was said, what it was drawn from, and its line.
+     *
+     * **`sources` and `actions` are inside the body rather than beside it**, and
+     * the second of those moved twice. `actions` was a third grid column, so a
+     * copy control on a fifteen-word turn sat at the container's trailing edge
+     * with a hundred and fifty pixels of nothing between it and the bubble it
+     * acted on, on both sides of the conversation. Moved into the body as a
+     * column of its own it was no better: a bubble spanning two auto tracks
+     * inflates both, so the controls landed under the middle of the turn.
+     *
+     * So they are inside `meta`, which is the line under a turn rather than only
+     * its timestamp, and that line is one flex row: time, state, controls, all
+     * hugging whichever edge the turn is against. Nothing has to be sized against
+     * anything else for that to hold at every width.
+     */
+    render() {
+        return html `<div part="message">
+      <span part="avatar"><slot name="avatar"></slot></span>
+      <div part="body">
+        <div part="content"><slot @slotchange=${this.handleFill}></slot></div>
+        <div part="sources"><slot name="sources" @slotchange=${this.handleFill}></slot></div>
+        <span part="meta"
+          >${this.renderTime()} ${this.renderState()}
+          <span part="actions"><slot name="actions" @slotchange=${this.handleFill}></slot></span>
+        </span>
+      </div>
+    </div>`;
+    }
+};
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessChatMessage.prototype, "author", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessChatMessage.prototype, "state", void 0);
+__decorate([
+    property()
+], HelixHeadlessChatMessage.prototype, "at", void 0);
+__decorate([
+    property()
+], HelixHeadlessChatMessage.prototype, "locale", void 0);
+__decorate([
+    property({ attribute: 'sending-label' })
+], HelixHeadlessChatMessage.prototype, "sendingLabel", void 0);
+__decorate([
+    property({ attribute: 'failed-label' })
+], HelixHeadlessChatMessage.prototype, "failedLabel", void 0);
+__decorate([
+    property({ attribute: 'retry-label' })
+], HelixHeadlessChatMessage.prototype, "retryLabel", void 0);
+__decorate([
+    state()
+], HelixHeadlessChatMessage.prototype, "clock", void 0);
+HelixHeadlessChatMessage = __decorate([
+    customElement('helix-headless-chat-message')
+], HelixHeadlessChatMessage);
+export { HelixHeadlessChatMessage };

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

@@ -0,0 +1,216 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+import type { HelixHeadlessChatMessage } from '../message/chat-message.js';
+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.
+ *
+ * @description
+ * **It has no opinion about where it sits.** A chat is asked for as a floating
+ * button, a page, a palette, a sidebar, a modal and an inline block, and none of
+ * those is a variant of a conversation: they are containers a conversation is
+ * put in, and the containers already exist. `Popover` and `SpeedDial` make the
+ * floating one, `Drawer` the sidebar, `Dialog` the modal, `Command` the palette,
+ * and a page is a page. Nothing here is positioned, nothing here has a backdrop,
+ * and nothing here owns a trigger, because a trigger opens a container and
+ * containers own their own. If a form factor needs a mode on this element, the
+ * split is wrong.
+ *
+ * **Scroll ownership is the behavior everything else depends on, and it is the
+ * most-got-wrong thing in the category.** 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, release the moment they leave it, and offer a way back. **Never scroll
+ * a reader who is reading.**
+ *
+ * The element owns it, because it is the only party that knows a message arrived
+ * and where the viewport was when it did. `pinned` is a controlled property like
+ * any other, so a consumer who wants to own it can.
+ *
+ * **The live region announces on completion, not on arrival.** The transcript is
+ * `role="log"` with `aria-live="polite"`, and a streaming message carries
+ * `aria-busy` while it arrives: a screen reader reading a stream token by token
+ * is unusable, and holding the announcement until the flag clears is the only
+ * arrangement that works. Somebody typing is a separate status region, so it
+ * never interleaves with what was said.
+ *
+ * **Not a client.** No transport, no protocol, no model. It renders a
+ * conversation and reports what the reader did.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category feedback
+ * @aliases Conversation, Transcript, Thread, Messages
+ * @documentation https://helix.fusion.dev/components/chat
+ *
+ * @slot - The turns, as `helix-chat-message` children.
+ * @slot actions - Beside the header: what can be done to the conversation itself.
+ * @slot composer - Below the transcript, where the reader writes.
+ * @slot header - Above the transcript: what this conversation is.
+ * @slot resume - The way back to the bottom, shown while the reader has scrolled away.
+ * @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.
+ *
+ * @csspart actions - The controls for the conversation, at the header's trailing edge.
+ * @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 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.
+ */
+export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
+    /**
+     * Nothing is assigned by name, so the turns land in the log and the rest does not.
+     *
+     * The messages are ordinary children a consumer writes with no `slot`, and a
+     * `role="log"` whose turns are somewhere else is a log of nothing. Manual
+     * assignment is the only way to wrap them without editing the consumer's
+     * markup, which is a change a React consumer's hydration reports and does not
+     * patch up.
+     */
+    static shadowRootOptions: ShadowRootInit;
+    /**
+     * Accessible name for the conversation.
+     */
+    label: string;
+    /**
+     * How near the bottom still counts as being at it, in pixels.
+     *
+     * 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.
+     */
+    threshold: number;
+    /**
+     * Whether the transcript follows new turns to the bottom.
+     *
+     * Set it and this element defers: the reader's scrolling fires `helix-change`
+     * and moves nothing until a new value arrives. `default-pinned` seeds a state
+     * this element then owns, and it defaults to pinned because a conversation
+     * opens at its most recent turn.
+     *
+     * **Not reflected, and the default is why.** A reflected property that
+     * defaults to true writes its attribute on upgrade whether or not the
+     * consumer wrote one, so the server serves `<helix-chat label="x">` and the
+     * client turns it into `<helix-chat label="x" pinned>`: a hydration mismatch a
+     * React consumer reports and does not patch up. Nothing needs the attribute
+     * either, because the one thing that changes with the pin is the way back, and
+     * that is a part inside the shadow tree where a stylesheet can already reach
+     * it. Measured rather than assumed: `label, pinned` after upgrade against
+     * `label` from the server.
+     *
+     *
+     */
+    get pinned(): boolean;
+    set pinned(next: boolean);
+    /**
+     * Whether to open pinned, where nothing declared it.
+     */
+    defaultPinned: boolean;
+    private pinnedState;
+    /** Watches for turns arriving, since a manual slot hears nothing about them. */
+    private watcher;
+    /**
+     * Which regions were given something, or undefined where nobody has counted.
+     *
+     * **A slot that is assigned by hand has no children, so no stylesheet can ask
+     * whether it was filled.** `[part="header"]:not(:has(> slot:has(*)))` is the
+     * rule every other collection here hides an empty region with, and `:has()`
+     * walks the DOM tree: with `slotAssignment: 'manual'` the assigned elements
+     * are children of this host and never of the slot, so the test was false for
+     * a filled header exactly as often as for an empty one and the rule never
+     * matched. Measured on a chat with nothing slotted at all: the header was 25
+     * pixels tall and drew its hairline under nothing, and so did the composer.
+     *
+     * 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,
+     * 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;
+    /** 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();
+    /**
+     * Puts the transcript back at its most recent turn.
+     *
+     * Public because the way back is a slot, so the control offering it is the
+     * consumer's and needs something to call. Pins again on the way, which is what
+     * a reader asking to go to the bottom means.
+     */
+    resume(): void;
+    /**
+     * Asks to pin or unpin, and reports whether the request stood.
+     *
+     * Announced before it is applied, so a consumer owning the pin hears the
+     * reader's scroll and decides. `property` names it, which is what
+     * `helix-before-pin`'s detail is for: a listener switching on the name is
+     * switching on something with one meaning.
+     */
+    private requestPinned;
+    private assign;
+    /**
+     * A press anywhere in the way back takes the reader back.
+     *
+     * **The affordance was inert, in the component and in every example.** The
+     * control is slotted so the consumer picks the words, and `resume()` was
+     * public "because the control offering it is the consumer's and needs
+     * something to call". True, and it left a button this element positions, lifts
+     * and shows and hides doing nothing at all until somebody wired it, which none
+     * of the five examples did: the one control whose whole job is to undo a
+     * scroll shipped as decoration.
+     *
+     * The region exists for exactly one purpose, so a press inside it has exactly
+     * one meaning and this element is entitled to act on it. `resume()` stays
+     * public for the other callers it was always for: a keyboard shortcut, or a
+     * consumer's own control somewhere else on the page.
+     */
+    private readonly handleResume;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    private readonly handleSlotChange;
+    /**
+     * The reader's own scrolling, which is the only thing that unpins.
+     *
+     * **Bound to the transcript in the template, and it has to be.** This was a
+     * capture listener on the host, on the reasoning that `scroll` does not bubble
+     * so the capture phase is the only phase that reaches it. Not bubbling is not
+     * the problem: `scroll` is not *composed*, and a non-composed event's
+     * propagation path stops at the shadow root and never includes the host, in
+     * any phase. So the listener never ran once, the pin never released, and a
+     * reader who scrolled up to re-read was pulled back to the bottom by the next
+     * turn to arrive, which this element's own description calls the most
+     * got-wrong thing in the category.
+     *
+     * Measured by dispatching both shapes at the transcript: with
+     * `composed: false`, which is what the platform sends, the host saw zero and
+     * `pinned` stayed true; with `composed: true` the host saw one and `pinned`
+     * went false. Bound here, the phase and the bubbling never come up.
+     *
+     * **The scroll this element does itself must not unpin it**, which is the
+     * subtle half: `scrollTop = scrollHeight` fires the same event a reader's
+     * 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.
+     */
+    private readonly handleScroll;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-chat': HelixHeadlessChat;
+    }
+}
+export {};