@fusion.dev/helix-headless 0.0.0-dev

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

@@ -0,0 +1,160 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @summary Where the reader writes their turn.
+ *
+ * @description
+ * **A separate element because it is separately replaceable.** A consumer with
+ * attachments, slash commands or a model picker replaces the composer and keeps
+ * the transcript, which is only possible if the two were never one component.
+ *
+ * **Enter sends and Shift+Enter opens a line, and it is configurable rather than
+ * decided.** The convention is near-universal in messaging and near-inverted in
+ * anything that is really a document editor, and a component that picks one
+ * makes the other consumer reimplement the composer. `submit-on` takes `enter`
+ * or `button`, and the second is what a long-form composer wants.
+ *
+ * The composer clears only when nobody refused the send, because a composer that
+ * empties itself and then hears the request failed has thrown away the only copy
+ * of what the reader wrote.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category forms
+ * @aliases Message box, Prompt input
+ * @documentation https://helix.fusion.dev/components/chat
+ *
+ * @slot end - Under the field, beside the send control.
+ * @slot start - Under the field, at the leading edge: attachments, a model picker.
+ *
+ * @event {HelixSendEvent} helix-send - Fired when the reader offers their turn, and cancelable.
+ *
+ * @csspart composer - The whole composer.
+ * @csspart end - The trailing slot's box.
+ * @csspart field - The text field.
+ * @csspart mark - The glyph inside the send control.
+ * @csspart send - The control that offers the turn.
+ * @csspart start - The leading slot's box.
+ * @csspart tools - The row under the field.
+ */
+export declare class HelixHeadlessChatComposer extends HelixElement {
+    /**
+     * What the reader has written.
+     *
+     * Read it, or set it to seed a draft.
+     */
+    value: string;
+    /**
+     * Shown in an empty field.
+     */
+    placeholder: string;
+    /**
+     * What sends: pressing Enter, or only the control.
+     *
+     * `enter` is the messaging convention and makes Shift+Enter the line break.
+     * `button` is what a composer holding several paragraphs wants, where Enter
+     * has to mean a new line and nothing else.
+     */
+    submitOn: 'button' | 'enter';
+    /**
+     * Whether the composer refuses input, while a turn is in flight say.
+     */
+    disabled: boolean;
+    /**
+     * Accessible name for the field.
+     */
+    label: string;
+    /**
+     * Label for the control that sends.
+     */
+    sendLabel: string;
+    /**
+     * How many rows the field opens at.
+     *
+     * It grows from there.
+     */
+    rows: number;
+    private draft;
+    /**
+     * @internal Read by the transcript to find the composer among its children.
+     */
+    readonly isChatComposer = true;
+    /** What is in the field, whoever last wrote it. */
+    private get text();
+    /**
+     * Offers what is written, and reports whether it stood.
+     *
+     * Public because a consumer's own send control is as likely to ask as this
+     * element's is, and because a keyboard shortcut somewhere else on the page is
+     * a reasonable way to send.
+     */
+    send(): boolean;
+    /**
+     * Says on each tool box whether anything is in it.
+     *
+     * They are boxes in a flex row, so an empty one still takes the gap beside it
+     * and the send control drifts inward by one for every slot a consumer left
+     * alone. No selector can ask this: a slot's assigned nodes are not its DOM
+     * children, so `:empty` describes the fallback rather than the fill.
+     */
+    private markEmpty;
+    protected updated(changed: PropertyValues): void;
+    protected willUpdate(changed: PropertyValues): void;
+    /**
+     * The control that offers the turn, behind a seam so a tier can draw its own.
+     *
+     * **A glyph with the label as its accessible name, rather than the label as
+     * text.** The word "Send" beside a field is the widest thing in the row and
+     * says nothing a return key does not, and every composer a reader has used in
+     * the last five years marks it rather than spells it. The return glyph is the
+     * mark because Enter is what actually sends, which `submit-on` says out loud:
+     * the control and the key are one affordance and should look like it.
+     *
+     * `send-label` is unchanged and is now the accessible name rather than the
+     * visible one, so a screen reader hears the same word it always did.
+     */
+    protected renderSend(): TemplateResult;
+    /**
+     * The field, and a row of tools under it.
+     *
+     * **One row was the wrong shape and it got worse the more a composer had to
+     * carry.** Everything sat on a single line: an attachment control, the field,
+     * a stop control and a send button, so the field was squeezed from both sides
+     * and every tool a consumer added took width away from the thing being typed
+     * into. Under it, the field spans the whole composer at every width and the
+     * tools have a line of their own to grow along.
+     *
+     * Send is at the trailing end of that line rather than in the field, which is
+     * the same corner and costs no overlay: a control positioned inside a
+     * scrolling textarea either covers the last line of a long draft or scrolls
+     * away with it.
+     */
+    protected render(): TemplateResult;
+    /**
+     * Records the draft, and stops the textarea speaking in this element's name.
+     *
+     * **The stop is not incidental.** `input` is composed by specification, so the
+     * `<textarea>` in this shadow root sent its own past this host and on through
+     * whatever `<helix-chat>` it is slotted into, and neither element declares an
+     * `input`: a consumer binding one on either received an undeclared event whose
+     * target was a control they cannot reach. What a composer offers is
+     * `helix-send`, once, when the reader is done. See 308.
+     */
+    private readonly handleInput;
+    private readonly handleSend;
+    /**
+     * Enter sends where that is what `submit-on` says, and never mid-composition.
+     *
+     * **`isComposing` is the part that is easy to leave out and breaks a whole
+     * writing system.** A reader typing Japanese, Chinese or Korean presses Enter
+     * to accept the candidate their input method is offering, and a composer that
+     * reads it as send fires off a half-finished word every time. The flag is on
+     * the event for exactly this and costs one condition.
+     */
+    private readonly handleKey;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-chat-composer': HelixHeadlessChatComposer;
+    }
+}

package/dist/chat/composer/chat-composer.js

@@ -0,0 +1,273 @@
+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, slotFilled, } from '@fusion.dev/helix-core';
+import { arrowElbowDownLeft } from '@fusion.dev/helix-icons';
+import { html } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
+/**
+ * @summary Where the reader writes their turn.
+ *
+ * @description
+ * **A separate element because it is separately replaceable.** A consumer with
+ * attachments, slash commands or a model picker replaces the composer and keeps
+ * the transcript, which is only possible if the two were never one component.
+ *
+ * **Enter sends and Shift+Enter opens a line, and it is configurable rather than
+ * decided.** The convention is near-universal in messaging and near-inverted in
+ * anything that is really a document editor, and a component that picks one
+ * makes the other consumer reimplement the composer. `submit-on` takes `enter`
+ * or `button`, and the second is what a long-form composer wants.
+ *
+ * The composer clears only when nobody refused the send, because a composer that
+ * empties itself and then hears the request failed has thrown away the only copy
+ * of what the reader wrote.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category forms
+ * @aliases Message box, Prompt input
+ * @documentation https://helix.fusion.dev/components/chat
+ *
+ * @slot end - Under the field, beside the send control.
+ * @slot start - Under the field, at the leading edge: attachments, a model picker.
+ *
+ * @event {HelixSendEvent} helix-send - Fired when the reader offers their turn, and cancelable.
+ *
+ * @csspart composer - The whole composer.
+ * @csspart end - The trailing slot's box.
+ * @csspart field - The text field.
+ * @csspart mark - The glyph inside the send control.
+ * @csspart send - The control that offers the turn.
+ * @csspart start - The leading slot's box.
+ * @csspart tools - The row under the field.
+ */
+let HelixHeadlessChatComposer = class HelixHeadlessChatComposer extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * What the reader has written.
+         *
+         * Read it, or set it to seed a draft.
+         */
+        this.value = '';
+        /**
+         * Shown in an empty field.
+         */
+        this.placeholder = '';
+        /**
+         * What sends: pressing Enter, or only the control.
+         *
+         * `enter` is the messaging convention and makes Shift+Enter the line break.
+         * `button` is what a composer holding several paragraphs wants, where Enter
+         * has to mean a new line and nothing else.
+         */
+        this.submitOn = 'enter';
+        /**
+         * Whether the composer refuses input, while a turn is in flight say.
+         */
+        this.disabled = false;
+        /**
+         * Accessible name for the field.
+         */
+        this.label = 'Message';
+        /**
+         * Label for the control that sends.
+         */
+        this.sendLabel = 'Send';
+        /**
+         * How many rows the field opens at.
+         *
+         * It grows from there.
+         */
+        this.rows = 1;
+        this.draft = '';
+        /**
+         * @internal Read by the transcript to find the composer among its children.
+         */
+        this.isChatComposer = true;
+        /**
+         * Records the draft, and stops the textarea speaking in this element's name.
+         *
+         * **The stop is not incidental.** `input` is composed by specification, so the
+         * `<textarea>` in this shadow root sent its own past this host and on through
+         * whatever `<helix-chat>` it is slotted into, and neither element declares an
+         * `input`: a consumer binding one on either received an undeclared event whose
+         * target was a control they cannot reach. What a composer offers is
+         * `helix-send`, once, when the reader is done. See 308.
+         */
+        this.handleInput = (event) => {
+            event.stopPropagation();
+            this.draft = event.target.value;
+        };
+        this.handleSend = () => {
+            this.send();
+        };
+        /**
+         * Enter sends where that is what `submit-on` says, and never mid-composition.
+         *
+         * **`isComposing` is the part that is easy to leave out and breaks a whole
+         * writing system.** A reader typing Japanese, Chinese or Korean presses Enter
+         * to accept the candidate their input method is offering, and a composer that
+         * reads it as send fires off a half-finished word every time. The flag is on
+         * the event for exactly this and costs one condition.
+         */
+        this.handleKey = (event) => {
+            if (event.key !== 'Enter' || this.submitOn !== 'enter') {
+                return;
+            }
+            if (event.shiftKey || event.isComposing) {
+                return;
+            }
+            event.preventDefault();
+            this.send();
+        };
+    }
+    /** What is in the field, whoever last wrote it. */
+    get text() {
+        return this.draft || this.value;
+    }
+    /**
+     * Offers what is written, and reports whether it stood.
+     *
+     * Public because a consumer's own send control is as likely to ask as this
+     * element's is, and because a keyboard shortcut somewhere else on the page is
+     * a reasonable way to send.
+     */
+    send() {
+        const value = this.text.trim();
+        if (value === '' || this.disabled) {
+            return false;
+        }
+        if (!this.dispatchEvent(new HelixSendEvent({ value }))) {
+            return false;
+        }
+        /* Cleared only here, after nobody refused. A composer that empties itself
+           first and hears about the failure afterwards has thrown away the only copy
+           of what the reader wrote. */
+        this.draft = '';
+        this.value = '';
+        return true;
+    }
+    /**
+     * Says on each tool box whether anything is in it.
+     *
+     * They are boxes in a flex row, so an empty one still takes the gap beside it
+     * and the send control drifts inward by one for every slot a consumer left
+     * alone. No selector can ask this: a slot's assigned nodes are not its DOM
+     * children, so `:empty` describes the fallback rather than the fill.
+     */
+    markEmpty() {
+        for (const name of ['start', 'end']) {
+            const region = this.renderRoot?.querySelector(`[part="${name}"]`);
+            const empty = !slotFilled(this.renderRoot?.querySelector(`slot[name="${name}"]`));
+            region?.toggleAttribute('data-empty', empty);
+            region?.toggleAttribute('hidden', empty);
+        }
+    }
+    updated(changed) {
+        super.updated(changed);
+        this.markEmpty();
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        hostAria(this.internals, { label: this.label, role: 'group' });
+    }
+    /**
+     * The control that offers the turn, behind a seam so a tier can draw its own.
+     *
+     * **A glyph with the label as its accessible name, rather than the label as
+     * text.** The word "Send" beside a field is the widest thing in the row and
+     * says nothing a return key does not, and every composer a reader has used in
+     * the last five years marks it rather than spells it. The return glyph is the
+     * mark because Enter is what actually sends, which `submit-on` says out loud:
+     * the control and the key are one affordance and should look like it.
+     *
+     * `send-label` is unchanged and is now the accessible name rather than the
+     * visible one, so a screen reader hears the same word it always did.
+     */
+    renderSend() {
+        return html `<button
+      part="send"
+      type="button"
+      aria-label=${this.sendLabel}
+      ?disabled=${this.disabled}
+      @click=${this.handleSend}
+    >
+      <svg
+        part="mark"
+        fill="currentColor"
+        viewBox=${arrowElbowDownLeft.viewBox}
+        aria-hidden="true"
+      >
+        ${unsafeSVG(arrowElbowDownLeft.content)}
+      </svg>
+    </button>`;
+    }
+    /**
+     * The field, and a row of tools under it.
+     *
+     * **One row was the wrong shape and it got worse the more a composer had to
+     * carry.** Everything sat on a single line: an attachment control, the field,
+     * a stop control and a send button, so the field was squeezed from both sides
+     * and every tool a consumer added took width away from the thing being typed
+     * into. Under it, the field spans the whole composer at every width and the
+     * tools have a line of their own to grow along.
+     *
+     * Send is at the trailing end of that line rather than in the field, which is
+     * the same corner and costs no overlay: a control positioned inside a
+     * scrolling textarea either covers the last line of a long draft or scrolls
+     * away with it.
+     */
+    render() {
+        return html `<div part="composer">
+      <textarea
+        part="field"
+        .value=${this.text}
+        aria-label=${this.label}
+        placeholder=${this.placeholder}
+        rows=${this.rows}
+        ?disabled=${this.disabled}
+        @input=${this.handleInput}
+        @keydown=${this.handleKey}
+      ></textarea>
+      <div part="tools">
+        <span part="start"><slot name="start"></slot></span>
+        <span part="end"><slot name="end"></slot></span>
+        ${this.renderSend()}
+      </div>
+    </div>`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessChatComposer.prototype, "value", void 0);
+__decorate([
+    property()
+], HelixHeadlessChatComposer.prototype, "placeholder", void 0);
+__decorate([
+    property({ attribute: 'submit-on' })
+], HelixHeadlessChatComposer.prototype, "submitOn", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessChatComposer.prototype, "disabled", void 0);
+__decorate([
+    property()
+], HelixHeadlessChatComposer.prototype, "label", void 0);
+__decorate([
+    property({ attribute: 'send-label' })
+], HelixHeadlessChatComposer.prototype, "sendLabel", void 0);
+__decorate([
+    property({ type: Number })
+], HelixHeadlessChatComposer.prototype, "rows", void 0);
+__decorate([
+    state()
+], HelixHeadlessChatComposer.prototype, "draft", void 0);
+HelixHeadlessChatComposer = __decorate([
+    customElement('helix-headless-chat-composer')
+], HelixHeadlessChatComposer);
+export { HelixHeadlessChatComposer };

package/dist/chat/index.d.ts

@@ -0,0 +1,3 @@
+export { HelixHeadlessChatComposer } from './composer/chat-composer.js';
+export { HelixHeadlessChatMessage } from './message/chat-message.js';
+export { HelixHeadlessChat } from './root/chat-root.js';

package/dist/chat/index.js

@@ -0,0 +1,3 @@
+export { HelixHeadlessChatComposer } from './composer/chat-composer.js';
+export { HelixHeadlessChatMessage } from './message/chat-message.js';
+export { HelixHeadlessChat } from './root/chat-root.js';

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

@@ -0,0 +1,170 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { nothing, type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @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.
+ */
+export declare class HelixHeadlessChatMessage extends HelixElement {
+    /**
+     * Who said it.
+     *
+     * Free text rather than a two-value union, because a conversation is not
+     * always two-sided: a transcript with a system turn, a tool call and three
+     * participants is the ordinary case for anything worth building this for.
+     * `me` and `them` are the conventional values and the stylesheet knows them;
+     * anything else is a name the consumer styles.
+     */
+    author?: string;
+    /**
+     * What has happened to it.
+     *
+     * Reflected, because every one of the four is a visual state and a stylesheet
+     * has no other way to know. Absent is a settled message with nothing to
+     * report, which is what most of a transcript is, and it is the absence of the
+     * attribute rather than a value of it: there is no initializer, so nothing is
+     * reflected until something happens.
+     */
+    state?: 'failed' | 'sending' | 'sent' | 'streaming';
+    /**
+     * When it was said, as anything `Date` parses.
+     */
+    at: string;
+    /**
+     * Locale for the timestamp.
+     *
+     * Empty is the runtime's own.
+     */
+    locale: string;
+    /**
+     * What to call each state, for a reader who cannot see it.
+     */
+    sendingLabel: string;
+    /**
+     * @internal
+     */
+    failedLabel: string;
+    /**
+     * Label for the control offered on a failed message.
+     */
+    retryLabel: string;
+    /**
+     * @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.
+     */
+    readonly isChatMessage = true;
+    private clock;
+    /** The timestamp, or nothing where there is not one to read. */
+    private get moment();
+    protected willUpdate(changed: PropertyValues): void;
+    private renderTime;
+    /**
+     * 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.
+     */
+    protected renderMark(): TemplateResult;
+    /**
+     * 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".
+     */
+    protected renderState(): TemplateResult | typeof nothing;
+    /**
+     * 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.
+     */
+    private markEmpty;
+    protected updated(changed: PropertyValues): void;
+    /**
+     * 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.
+     */
+    protected render(): TemplateResult;
+    /**
+     * 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.
+     */
+    private readonly handleFill;
+    /**
+     * 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.
+     */
+    private readonly handleRetry;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-chat-message': HelixHeadlessChatMessage;
+    }
+}