@fusion.dev/helix-headless 0.0.0-dev

package/dist/chat/root/chat-root.js

@@ -0,0 +1,389 @@
+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, HelixBeforePinEvent, HelixElement, hostAria, MixinCollection, requestChange, } from '@fusion.dev/helix-core';
+import { html, nothing } from 'lit';
+import { property, state } from 'lit/decorators.js';
+/**
+ * The regions a consumer fills, in the order they are rendered.
+ *
+ * Named once because two things read the list: the manual assignment that puts
+ * a child in the region its `slot` names, and the emptiness each region is
+ * hidden on. They went out of step the first time they were written twice.
+ */
+const REGIONS = ['header', 'actions', 'resume', 'status', 'composer'];
+/**
+ * @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.
+ */
+let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixElement) {
+    constructor() {
+        super(...arguments);
+        /**
+         * Accessible name for the conversation.
+         */
+        this.label = '';
+        /**
+         * 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.
+         */
+        this.threshold = 48;
+        /**
+         * Whether to open pinned, where nothing declared it.
+         */
+        this.defaultPinned = true;
+        this.pinnedState = undefined;
+        /** Watches for turns arriving, since a manual slot hears nothing about them. */
+        this.watcher = undefined;
+        /**
+         * 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.
+         */
+        this.filled = undefined;
+        /**
+         * 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.
+         */
+        this.handleResume = () => {
+            this.resume();
+        };
+        this.handleSlotChange = () => {
+            this.assign();
+            this.requestUpdate();
+        };
+        /**
+         * 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.
+         */
+        this.handleScroll = () => {
+            const wanted = this.atBottom;
+            if (wanted !== this.pinned) {
+                this.requestPinned(wanted);
+            }
+        };
+    }
+    /**
+     * 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 { this.shadowRootOptions = {
+        ...HelixElement.shadowRootOptions,
+        slotAssignment: 'manual',
+    }; }
+    /**
+     * 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() {
+        return this.pinnedState ?? this.defaultPinned;
+    }
+    set pinned(next) {
+        const previous = this.pinned;
+        this.pinnedState = next;
+        this.requestUpdate('pinned', previous);
+    }
+    /** Whether a region has something in it, taking unknown for yes. */
+    has(name) {
+        return this.filled?.has(name) ?? true;
+    }
+    /** The turns declared as children, in the order they are written. */
+    get messages() {
+        /* `?? []` is the server: Lit's element shim carries attributes and not a
+           tree, so `children` is undefined there and spreading it throws. */
+        return [...(this.children ?? [])].filter((child) => 'isChatMessage' in child && child.isChatMessage === true);
+    }
+    /** The element that scrolls, once there is one. */
+    get log() {
+        return this.renderRoot?.querySelector?.('[part="log"]') ?? null;
+    }
+    /** Whether the reader is within `threshold` of the bottom right now. */
+    get atBottom() {
+        const log = this.log;
+        if (!log) {
+            return true;
+        }
+        return log.scrollHeight - log.scrollTop - log.clientHeight <= Math.max(0, this.threshold);
+    }
+    /**
+     * 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() {
+        const log = this.log;
+        if (log) {
+            log.scrollTop = log.scrollHeight;
+        }
+        this.requestPinned(true);
+    }
+    /**
+     * 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.
+     */
+    requestPinned(next) {
+        if (next === this.pinned) {
+            return false;
+        }
+        return requestChange({
+            apply: (value) => {
+                const previous = this.pinned;
+                this.pinnedState = value;
+                this.requestUpdate('pinned', previous);
+            },
+            event: (value) => new HelixBeforePinEvent({ value: String(value) }),
+            host: this,
+            next,
+        });
+    }
+    assign() {
+        const root = this.renderRoot;
+        const log = root?.querySelector?.('slot[name="messages"]');
+        if (!log?.assign) {
+            return;
+        }
+        const messages = this.messages;
+        log.assign(...messages);
+        const filled = new Set();
+        for (const name of REGIONS) {
+            const given = [...this.children].filter((child) => child.getAttribute('slot') === name);
+            root?.querySelector?.(`slot[name="${name}"]`)?.assign?.(...given);
+            if (given.length > 0) {
+                filled.add(name);
+            }
+        }
+        /* Compared before it is set, because this runs from `updated` and a new Set
+           every render is a new value every render, which is a render loop. */
+        const previous = this.filled;
+        if (!previous ||
+            previous.size !== filled.size ||
+            [...filled].some((name) => !previous.has(name))) {
+            this.filled = filled;
+        }
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        /* **A turn that arrives after first paint reaches nothing on its own.**
+           Slots are assigned by hand here, so appending a child assigns it to
+           nothing, fires no `slotchange`, and schedules no render: the transcript
+           went on showing "Nothing to show" over six children it already had, and
+           the one thing a conversation does is grow. Measured with `assignedElements()`
+           at zero against `children` at nine.
+    
+           `childList` and not `subtree`, which is the difference between watching a
+           conversation and watching every token of it: a streaming turn rewrites its
+           own text on every frame, and a subtree observer would re-render the whole
+           transcript each time for a change inside a child that owns it. */
+        this.watcher = new MutationObserver(this.handleSlotChange);
+        this.watcher.observe(this, { childList: true });
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.watcher?.disconnect();
+        this.watcher = undefined;
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        hostAria(this.internals, { label: this.label || 'Conversation', role: 'region' });
+    }
+    updated(changed) {
+        super.updated(changed);
+        this.assign();
+        /* After the render that added the turn, because the scroll height it is
+           being sent to does not exist until then. */
+        if (this.pinned) {
+            const log = this.log;
+            if (log) {
+                log.scrollTop = log.scrollHeight;
+            }
+        }
+    }
+    render() {
+        const away = !this.pinned;
+        /* The header stands while either half of it is filled: a conversation with
+           no title and a single control still needs the row that control sits in. */
+        const titled = this.has('header') || this.has('actions');
+        return html `<div part="header" ?hidden=${!titled}>
+        <slot name="header"></slot>
+        <span part="actions" ?hidden=${!this.has('actions')}>
+          <slot name="actions"></slot>
+        </span>
+      </div>
+      <div
+        part="log"
+        role="log"
+        aria-live="polite"
+        aria-label=${this.label || 'Conversation'}
+        aria-busy=${this.loading ? 'true' : nothing}
+        @scroll=${this.handleScroll}
+      >
+        <slot name="messages" @slotchange=${this.handleSlotChange}></slot>
+        ${this.renderStatus(this.messages.length > 0)}
+      </div>
+      <div part="resume" ?hidden=${!away || !this.has('resume')} @click=${this.handleResume}>
+        <slot name="resume"></slot>
+      </div>
+      <div part="status" role="status" ?hidden=${!this.has('status')}>
+        <slot name="status"></slot>
+      </div>
+      <div part="composer" ?hidden=${!this.has('composer')}>
+        <slot name="composer"></slot>
+      </div>`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessChat.prototype, "label", void 0);
+__decorate([
+    property({ type: Number })
+], HelixHeadlessChat.prototype, "threshold", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessChat.prototype, "pinned", null);
+__decorate([
+    property({ attribute: 'default-pinned', type: Boolean })
+], HelixHeadlessChat.prototype, "defaultPinned", void 0);
+__decorate([
+    state()
+], HelixHeadlessChat.prototype, "pinnedState", void 0);
+__decorate([
+    state()
+], HelixHeadlessChat.prototype, "filled", void 0);
+HelixHeadlessChat = __decorate([
+    customElement('helix-headless-chat')
+], HelixHeadlessChat);
+export { HelixHeadlessChat };

package/dist/checkbox/index.d.ts

@@ -0,0 +1 @@
+export * from './root/checkbox-root.js';

package/dist/checkbox/index.js

@@ -0,0 +1 @@
+export * from './root/checkbox-root.js';

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

@@ -0,0 +1,108 @@
+import { AriaForwardController, HelixFormElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+declare const HelixHeadlessCheckbox_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerCheckedInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
+/**
+ * @summary A box that is ticked, or not, or neither.
+ *
+ * @description
+ * Renders a real `<input type="checkbox">`, so the space key, the focus ring,
+ * and the indeterminate glyph come from the platform. `delegatesFocus` puts
+ * focus on it, and it serializes into the server's markup, so the control is
+ * reachable before any script loads.
+ *
+ * **The input inside a shadow root submits nothing**, because the form is on
+ * the other side of the boundary. The host is form-associated instead and
+ * reports its own value through `ElementInternals`, which is also what carries
+ * validity and what answers a form reset.
+ *
+ * A checked box submits its `value`, and an unchecked one submits nothing at
+ * all. That is what a native checkbox does, and a form built around one reads
+ * the absence rather than a `false`.
+ *
+ * `indeterminate` is presentation and nothing else. It is neither checked nor
+ * unchecked to a reader, it never submits, and the first click resolves it: a
+ * third state that survives interaction is a control nobody can finish.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category forms
+ * @aliases Tickbox, Toggle
+ * @documentation https://helix.fusion.dev/components/checkbox
+ *
+ * @slot - The label.
+ *
+ * @event {Event} change - Relayed from the input once the state has changed.
+ * @event {HelixBeforeToggleEvent} helix-before-toggle - Fired before the state changes, and cancelable.
+ * @event {Event} input - Announced once the state has moved.
+ *
+ * @csspart box - The frame the input is painted as, and the mark sits over.
+ * @csspart control - The input.
+ * @csspart feedback - What is wrong with it.
+ * @csspart field - The row the box and its label share, and the surface the card appearance draws.
+ * @csspart hint - Help under the control, while nothing is wrong.
+ * @csspart label - The label beside it.
+ * @csspart mark - The tick, or the dash when the box is indeterminate.
+ */
+export declare class HelixHeadlessCheckbox extends HelixHeadlessCheckbox_base {
+    protected readonly aria: AriaForwardController;
+    /**
+     * Value submitted when the box is checked.
+     */
+    value: string;
+    /**
+     * Whether the box shows as neither checked nor unchecked.
+     *
+     * Presentation only. It never submits, and the first change resolves it.
+     */
+    indeterminate: boolean;
+    /** Focus is delegated to the input, so the host is never the focus target. */
+    static shadowRootOptions: ShadowRootInit;
+    private readonly handleChange;
+    /** Reports the value and the validity the host stands behind. */
+    private sync;
+    /** Returns the box to the state its markup declared. */
+    formResetCallback(): void;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    /**
+     * Whether there is a label to leave room for, written to the host.
+     *
+     * The row is a flex line with a gap in it, so a label span rendered empty is
+     * still a box and still takes that gap: an unlabelled box came out with eight
+     * pixels of nothing after it. The input answers this by not rendering the
+     * element, which cannot work here, because a checkbox is named by its own
+     * content and the property is only that slot's fallback. Gating on the
+     * property would unlabel every `<helix-checkbox>Text</helix-checkbox>` ever
+     * written.
+     *
+     * So the slot is asked instead, the same way `Tooltip` asks its own: with
+     * `flatten`, because here the fallback counts, being where the property
+     * renders. Client only, so a server-rendered unlabelled checkbox carries the
+     * gap for one frame. That is a control with no accessible name, which has a
+     * worse problem than its spacing.
+     */
+    private readonly handleLabelChange;
+    /**
+     * Asks the slot, and records the answer as a state.
+     *
+     * Called on `slotchange` and after every update, and the second is not
+     * belt-and-braces: **`slotchange` does not fire when nothing is assigned.**
+     * So a checkbox labeled only by its property, which is most of them, never
+     * heard about its own label and rendered without one. Caught by the spec that
+     * asks a labeled row to be wider than a bare one.
+     *
+     * **`:state(has-label)` and not `data-has-label`, since 27 Aug 2026.** This
+     * one could never have been in server output whatever it was called, the
+     * answer coming from `assignedNodes` and a server having no tree to ask, so
+     * it was an attribute that appeared on every labeled checkbox the instant it
+     * upgraded and on none that any server sent. See `HelixElement.toggleState`.
+     */
+    private syncLabelPresence;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-checkbox': HelixHeadlessCheckbox;
+    }
+}
+export {};