@fusion.dev/helix-headless 0.218.0 → 0.220.0

package/dist/breadcrumbs/breadcrumb/breadcrumb.d.ts

@@ -37,7 +37,7 @@ import { type CSSResultGroup, nothing, type PropertyValues, type TemplateResult
  * @slot end - Content after the label and outside the link, such as a switcher's
  * menu trigger, a count, or a mark. It can hold a control, and it is not read as
  * part of the link's accessible name.
- * @slot separator - Replaces the chevron shown before this item.
+ * @slot separator - Replaces the mark shown before this item, a chevron or the trail's `separator`.
  * @slot start - Content before the label, such as an icon.
  *
  * @event {HelixSelectEvent} helix-select - A plain press on the crumb's link, with its `href` as the value, before the browser follows it. Cancelable: cancel it to keep the browser from following, as a client-side router does.
@@ -46,7 +46,7 @@ import { type CSSResultGroup, nothing, type PropertyValues, type TemplateResult
  * @csspart fold-separator - The chevron before that button.
  * @csspart link - The crumb itself, which is an `<a>` where `href` is set.
  * @csspart separator - The separator preceding the item.
- * @csspart separator-mark - The chevron between crumbs, shown when no separator is slotted.
+ * @csspart separator-mark - The chevron between crumbs, or the slash under the trail's `separator="slash"`, shown when no separator is slotted.
  *
  * @cssstate current - While the crumb is the current page, marked `current` or the last of a trail with none marked.
  * @cssstate end - While the `end` slot holds something, so a stylesheet can join
@@ -96,6 +96,11 @@ export declare class HelixHeadlessBreadcrumb extends HelixElement {
      * `current`, so this one is said to be the current page.
      */
     implied: boolean;
+    /**
+     * @internal Set by the trail from its `separator`: the mark this crumb draws
+     * before itself and before its fold button.
+     */
+    mark: 'chevron' | 'slash';
     /** @internal Set by the trail: what a press on the fold's button does. */
     onFold: (() => void) | undefined;
     /**
@@ -140,6 +145,12 @@ export declare class HelixHeadlessBreadcrumb extends HelixElement {
      * without reimplementing the crumb, its link and its current-page branch.
      */
     protected renderSeparator(): TemplateResult;
+    /**
+     * The trail's mark: a chevron, mirrored on a right-to-left page because it
+     * points the way the trail runs, or a slash, which is a character and is
+     * written the same way in either direction.
+     */
+    private renderMark;
     protected render(): TemplateResult;
 }
 declare global {

package/dist/breadcrumbs/breadcrumb/breadcrumb.js

@@ -12,6 +12,7 @@ let HelixHeadlessBreadcrumb = class HelixHeadlessBreadcrumb extends HelixElement
         this.folded = false;
         this.foldLabel = '';
         this.implied = false;
+        this.mark = 'chevron';
         this.onFold = undefined;
         this.rel = '';
         this.target = '';
@@ -48,10 +49,7 @@ let HelixHeadlessBreadcrumb = class HelixHeadlessBreadcrumb extends HelixElement
         if (this.fold === 0) {
             return nothing;
         }
-        return html `<span part="fold-separator" aria-hidden="true"
-        ><svg data-mirror fill="currentColor" viewBox=${caretRight.viewBox}>
-          ${unsafeSVG(caretRight.content)}
-        </svg></span
+        return html `<span part="fold-separator" aria-hidden="true">${this.renderMark()}</span
       ><button part="expand" type="button" aria-label=${this.foldLabel} @click=${() => this.onFold?.()}>
         …
       </button>`;
@@ -64,11 +62,20 @@ let HelixHeadlessBreadcrumb = class HelixHeadlessBreadcrumb extends HelixElement
         this.toggleState('end', slotFilled(slotNamed(this.renderRoot, 'end')));
     }
     renderSeparator() {
-        return html `<slot name="separator"
-      ><svg part="separator-mark" data-mirror fill="currentColor" viewBox=${caretRight.viewBox}>
-        ${unsafeSVG(caretRight.content)}
-      </svg></slot
-    >`;
+        return html `<slot name="separator">${this.renderMark(true)}</slot>`;
+    }
+    renderMark(named = false) {
+        if (this.mark === 'slash') {
+            return named
+                ? html `<span part="separator-mark" data-mark="slash">/</span>`
+                : html `<span data-mark="slash">/</span>`;
+        }
+        const chevron = unsafeSVG(caretRight.content);
+        return named
+            ? html `<svg part="separator-mark" data-mirror fill="currentColor" viewBox=${caretRight.viewBox}>
+          ${chevron}
+        </svg>`
+            : html `<svg data-mirror fill="currentColor" viewBox=${caretRight.viewBox}>${chevron}</svg>`;
     }
     render() {
         const label = html `<slot name="start"></slot><slot></slot>`;
@@ -105,6 +112,9 @@ __decorate([
 __decorate([
     property({ attribute: false })
 ], HelixHeadlessBreadcrumb.prototype, "implied", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessBreadcrumb.prototype, "mark", void 0);
 __decorate([
     property()
 ], HelixHeadlessBreadcrumb.prototype, "rel", void 0);

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

@@ -64,7 +64,7 @@ export interface BreadcrumbItem {
  * @csspart crumb-fold-separator - The chevron before that button.
  * @csspart crumb-link - The link, or the current page's words, of a crumb drawn from `items`.
  * @csspart crumb-separator - The separator before a crumb drawn from `items`.
- * @csspart crumb-separator-mark - The chevron before a crumb drawn from `items`.
+ * @csspart crumb-separator-mark - The chevron, or the slash under `separator="slash"`, before a crumb drawn from `items`.
  * @csspart expand - The button in the folded crumb that shows the whole trail.
  * @csspart list - The ordered list.
  */
@@ -100,6 +100,21 @@ export declare class HelixHeadlessBreadcrumbs extends HelixElement {
      * 2, so the first crumb and the current page always show.
      */
     maxItems?: number;
+    /**
+     * The mark between one crumb and the next, for the whole trail. Unset is a
+     * chevron; `slash` is a slash, as a path or a repository and its branch is
+     * written.
+     *
+     * **On the trail rather than on each crumb**, because the marks are one
+     * decision: a trail whose separators differ from crumb to crumb is a
+     * mistake, and a trail drawn from `items` has no crumb of yours to set it
+     * on. A crumb's own `separator` slot still replaces its mark, for the rare
+     * crumb that needs something else.
+     *
+     * Optional and reflected, per the rule that a reflected property takes no
+     * default, so a stylesheet can select on it.
+     */
+    separator?: 'slash';
     /** Whether a reader has asked to see the whole of a folded trail. */
     private expanded;
     /** The crumbs slotted into the trail, in order. */

package/dist/breadcrumbs/root/breadcrumbs-root.js

@@ -43,6 +43,7 @@ let HelixHeadlessBreadcrumbs = class HelixHeadlessBreadcrumbs extends HelixEleme
                     crumb.fold = index === 0 ? fold : 0;
                     crumb.foldLabel = index === 0 ? label : '';
                     crumb.onFold = index === 0 && fold > 0 ? this.unfold : undefined;
+                    crumb.mark = this.separator ?? 'chevron';
                 });
             });
         };
@@ -87,6 +88,7 @@ let HelixHeadlessBreadcrumbs = class HelixHeadlessBreadcrumbs extends HelixEleme
             : html `<${crumb}
             part="crumb crumb-collapsed"
             exportparts="expand: crumb-expand, fold-separator: crumb-fold-separator, link: crumb-link, separator: crumb-separator, separator-mark: crumb-separator-mark"
+            .mark=${this.separator ?? 'chevron'}
             ><button
               part="expand"
               type="button"
@@ -105,6 +107,7 @@ let HelixHeadlessBreadcrumbs = class HelixHeadlessBreadcrumbs extends HelixEleme
         rel=${item.rel ?? nothing}
         target=${item.target ?? nothing}
         ?current=${index === last}
+        .mark=${this.separator ?? 'chevron'}
         >${item.label}</${crumb}
       >`;
         return html `${repeat(first, ({ index }) => index, draw)}${fold}${repeat(rest, ({ index }) => index, draw)}`;
@@ -129,6 +132,9 @@ __decorate([
 __decorate([
     property({ attribute: 'max-items', converter: numberConverter('max-items', undefined) })
 ], HelixHeadlessBreadcrumbs.prototype, "maxItems", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessBreadcrumbs.prototype, "separator", void 0);
 __decorate([
     state()
 ], HelixHeadlessBreadcrumbs.prototype, "expanded", void 0);

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

@@ -35,6 +35,10 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * Set `pending` while the action a press started is still running. The button
  * keeps focus and refuses presses, and a reader on it hears `pending-label`.
  *
+ * Set `focusable-when-disabled` on a disabled button whose reason a Tooltip
+ * gives. It stays in the tab order and takes hover, so the tooltip opens, and
+ * it refuses every press.
+ *
  * Every press that acts sends `helix-press` with what pressed it in
  * `detail.pointerType`: `mouse`, `pen`, `touch`, `keyboard`, or `virtual` for
  * a screen reader's press or a script's `click()`, as React Aria's `onPress`
@@ -146,6 +150,35 @@ export declare class HelixHeadlessButton extends HelixFormElementBase {
      * anything a consumer sets.
      */
     focusable: boolean;
+    /**
+     * Whether a disabled button stays in the tab order, so a tooltip around it
+     * can say why it is disabled.
+     *
+     * Set it on a button whose reason a Tooltip gives, such as a Save with no
+     * changes to save. While the button is disabled, it keeps focus and takes
+     * hover, and it refuses every press: a click, Enter and Space, and Enter in
+     * a field of its form. The click does not reach your listeners, and a submit
+     * button submits nothing. The inner control carries `aria-disabled` in place
+     * of the native `disabled`, so a screen reader still says it is unavailable.
+     * The styled button keeps the disabled look.
+     *
+     * Leave it unset on a button with no reason to give. A plain disabled button
+     * leaves the tab order, as a native one does, and a keyboard reader skips a
+     * stop that does nothing. Set `pending` for the wait after a press.
+     */
+    focusableWhenDisabled: boolean;
+    /**
+     * @internal Whether the button is disabled and kept in the tab order by
+     * `focusableWhenDisabled`, so the inner control takes `aria-disabled` and
+     * refuses presses itself.
+     */
+    protected get heldDisabled(): boolean;
+    /**
+     * @internal Whether the inner control refuses a press it still receives:
+     * the button is pending, or disabled and kept in the tab order. A subclass
+     * that draws its own control, as `CopyButton` does, binds to it.
+     */
+    protected get refusesPress(): boolean;
     /**
      * Where this button's submission goes, overriding the form's own.
      *

package/dist/button/root/button-root.js

@@ -30,6 +30,7 @@ let HelixHeadlessButton = class HelixHeadlessButton extends HelixFormElementBase
         this.command = '';
         this.commandFor = '';
         this.focusable = true;
+        this.focusableWhenDisabled = false;
         this.formAction = '';
         this.formEnctype = '';
         this.formMethod = '';
@@ -48,7 +49,7 @@ let HelixHeadlessButton = class HelixHeadlessButton extends HelixFormElementBase
             }
         };
         this.handleClick = (event) => {
-            if (this.pending) {
+            if (this.refusesPress) {
                 event.preventDefault();
                 event.stopImmediatePropagation();
                 return;
@@ -83,6 +84,12 @@ let HelixHeadlessButton = class HelixHeadlessButton extends HelixFormElementBase
     get forwardsLabel() {
         return true;
     }
+    get heldDisabled() {
+        return this.isDisabled && this.focusableWhenDisabled;
+    }
+    get refusesPress() {
+        return this.pending || this.heldDisabled;
+    }
     sayPending() {
         const focused = this.renderRoot?.activeElement != null;
         if (!focused && this.status.said === '') {
@@ -207,11 +214,11 @@ let HelixHeadlessButton = class HelixHeadlessButton extends HelixFormElementBase
       aria-expanded=${this.expanded === undefined ? nothing : String(this.expanded)}
       aria-haspopup=${this.popup ?? nothing}
       aria-busy=${this.pending ? 'true' : nothing}
-      aria-disabled=${this.pending ? 'true' : nothing}
+      aria-disabled=${this.refusesPress ? 'true' : nothing}
       aria-label=${this.label || nothing}
       command=${this.command || nothing}
       tabindex=${stop}
-      ?disabled=${this.isDisabled}
+      ?disabled=${this.isDisabled && !this.heldDisabled}
       @click=${this.handleClick}
       @keydown=${this.notePress}
       @pointerdown=${this.notePress}
@@ -235,6 +242,9 @@ __decorate([
 __decorate([
     property({ attribute: false })
 ], HelixHeadlessButton.prototype, "focusable", void 0);
+__decorate([
+    property({ attribute: 'focusable-when-disabled', type: Boolean })
+], HelixHeadlessButton.prototype, "focusableWhenDisabled", void 0);
 __decorate([
     property({ attribute: 'formaction' })
 ], HelixHeadlessButton.prototype, "formAction", void 0);

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

@@ -2,6 +2,7 @@ import { type CanvasView, HelixElement, type ViewportPanDetail, type ViewportWay
 import { type PropertyValues, type TemplateResult } from 'lit';
 import type { StaticValue } from 'lit/static-html.js';
 import '../../icon-button/index.js';
+import '../../tooltip/index.js';
 import { type CanvasArrangeOptions } from '../arrange.js';
 import { type CanvasDocument, type CanvasRoute, type CanvasTone } from './canvas-document.js';
 export type { CanvasArrangeOptions } from '../arrange.js';
@@ -210,6 +211,16 @@ declare const HelixHeadlessCanvas_base: (new (...args: any[]) => import("@fusion
  * @csspart pan-up-spinner - The ring `pan-up` turns while it is pending.
  * @csspart pan-up-text - The box `pan-up`'s glyph sits in.
  * @csspart region - The named region the board is drawn in.
+ * @csspart tooltip-arrow - The arrow of the tooltip that names each button, forwarded from `Tooltip`.
+ * @csspart tooltip-arrow-bottom - The arrow while the bubble is below its button, on the bubble's top edge. Set together with `tooltip-arrow`.
+ * @csspart tooltip-arrow-left - The arrow while the bubble is left of its button, on the bubble's right edge. Set together with `tooltip-arrow`.
+ * @csspart tooltip-arrow-right - The arrow while the bubble is right of its button, on the bubble's left edge. Set together with `tooltip-arrow`.
+ * @csspart tooltip-arrow-top - The arrow while the bubble is above its button, on the bubble's bottom edge. Set together with `tooltip-arrow`.
+ * @csspart tooltip-surface - The bubble of the tooltip that names each button, forwarded from `Tooltip`.
+ * @csspart tooltip-surface-bottom - The bubble while it is below its button. Set together with `tooltip-surface`.
+ * @csspart tooltip-surface-left - The bubble while it is left of its button. Set together with `tooltip-surface`.
+ * @csspart tooltip-surface-right - The bubble while it is right of its button. Set together with `tooltip-surface`.
+ * @csspart tooltip-surface-top - The bubble while it is above its button. Set together with `tooltip-surface`.
  * @csspart viewport - The box the board is drawn inside.
  * @csspart zoom-in - The button that zooms in.
  * @csspart zoom-in-button - `zoom-in`'s inner button.

package/dist/canvas/root/canvas-root.js

@@ -3,6 +3,7 @@ import { assignSlots, auditName, capturePointer, customElement, formatPercent, f
 import { html, nothing, svg } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import '../../icon-button/index.js';
+import '../../tooltip/index.js';
 import { arrangement } from '../arrange.js';
 import { descriptionOf } from '../describe.js';
 import { HelixHeadlessCanvasEdge } from '../edge/canvas-edge.js';

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

@@ -1,13 +1,21 @@
 import { HelixFormElement } from '@fusion.dev/helix-core';
-import { type PropertyValues, type TemplateResult } from 'lit';
+import { nothing, type PropertyValues, type TemplateResult } from 'lit';
+import '../../tooltip/index.js';
+/**
+ * How long `example` shows before the next one replaces it, in milliseconds:
+ * `EXAMPLE_SHOWN`, and `EXAMPLE_PER_CHARACTER` more for each character past
+ * `EXAMPLE_SHORT`, up to `EXAMPLE_LONGEST`. A longer example takes longer to
+ * read.
+ */
+export declare function exampleShown(example: string): number;
 declare const HelixHeadlessChatComposer_base: (new (...args: any[]) => import("@fusion.dev/helix-core").VoiceElement) & typeof HelixFormElement;
 /**
  * @summary A field for writing a turn in a conversation.
  *
  * @description
  * The composer is a separate element so you can replace it. If you need
- * attachments, slash commands, or a model picker, replace the composer and keep
- * the transcript.
+ * slash commands or a layout of your own, replace the composer and keep the
+ * transcript.
  *
  * By default, Enter sends and Shift+Enter starts a new line, the convention in
  * messaging apps. Document editors mostly use the opposite, so `submit-on`
@@ -47,33 +55,71 @@ declare const HelixHeadlessChatComposer_base: (new (...args: any[]) => import("@
  * `typing-timeout` milliseconds. Pass it on to show "is typing" to the other
  * side.
  *
+ * **`busy` says a reply is on its way**, and turns the send button into a
+ * stop button, named by `stop-label`, that sends `helix-stop`. The field
+ * stays open so the reader can write the next turn, and Enter does not send
+ * it until `busy` is cleared. With `queue`, Enter sends while `busy` too, for
+ * a page that holds a turn until the reply ends or hands it to the reply
+ * under way; the button stays the stop button.
+ *
+ * **The `idle` slot takes the send button's place while there is nothing to
+ * send**: the field is empty, `attached` is not set, and no reply is on its
+ * way. Put the action an empty draft offers there, such as a button that
+ * starts a voice conversation. The send button comes back as soon as there
+ * is a draft. Where focus was on the one that goes, it moves to the one that
+ * comes, so a keyboard reader stays in the same place.
+ *
+ * **What the draft carries goes in `attachments`**, inside the box and above
+ * the field, such as thumbnails of attached images and cards for attached
+ * files. The region takes no room while nothing is in it. A press on its
+ * empty space keeps the reader in the field, and a press on a control in it,
+ * such as a button that removes an attachment, goes to that control. Set
+ * `attached` as well, so the send button shows for a draft with no text.
+ *
  * @since 0.1.0
  * @status stable
  * @category forms
  * @aliases Message box, Prompt input
  * @documentation https://fusion.dev/helix/components/chat
  *
+ * @slot attachments - What the draft carries, such as images or files, inside the box and above the field.
  * @slot end - Content under the field, beside the send button.
+ * @slot idle - A control shown in place of the send button while the draft is empty and no reply is on its way, such as a button that starts a voice conversation.
  * @slot start - Content under the field at the leading edge, such as an attachment button or a model picker.
  *
  * @event {HelixBeforeListenEvent} helix-before-listen - The dictation button was pressed. Cancelable: cancel it to keep the composer from listening.
  * @event {HelixListenEvent} helix-listen - Dictation settled on a phrase and put it in the draft, after the draft's own `input`.
  * @event {HelixSendEvent} helix-send - Fired when the user sends their turn, and cancelable.
+ * @event {HelixStopEvent} helix-stop - Fired when the user presses the stop button, shown in place of the send button while `busy` is set.
  * @event {HelixTypingEvent} helix-typing - The user started or stopped writing, with `typing` saying which, as the composer's `typing` does.
  * @event {Event} input - The user changed the text. Read it from `value`, for a typing indicator or a saved draft. Bubbles and is composed, as a native field's is.
  *
+ * @csspart attachments - The box around the `attachments` slot, above the field. It is hidden while the slot is empty.
  * @csspart composer - The whole composer.
  * @csspart end - The box around the `end` slot.
  * @csspart feedback - The `feedback` message, under the field while it is set.
  * @csspart field - The text field.
- * @csspart mark - The icon inside the send button.
- * @csspart send - The send button.
+ * @csspart idle - The box around the `idle` slot, shown in the send button's place while the draft is empty.
+ * @csspart mark - The icon inside the send button, a return key, or a square while `busy`.
+ * @csspart reason-arrow - The arrow of the bubble that says `send-reason`, forwarded from `Tooltip`.
+ * @csspart reason-arrow-bottom - The arrow while the bubble is below the send button, on the bubble's top edge. Set together with `reason-arrow`.
+ * @csspart reason-arrow-left - The arrow while the bubble is left of the send button, on the bubble's right edge. Set together with `reason-arrow`.
+ * @csspart reason-arrow-right - The arrow while the bubble is right of the send button, on the bubble's left edge. Set together with `reason-arrow`.
+ * @csspart reason-arrow-top - The arrow while the bubble is above the send button, on the bubble's bottom edge. Set together with `reason-arrow`.
+ * @csspart reason-surface - The bubble that says `send-reason` over the send button, forwarded from `Tooltip`.
+ * @csspart reason-surface-bottom - The bubble while it is below the send button. Set together with `reason-surface`.
+ * @csspart reason-surface-left - The bubble while it is left of the send button. Set together with `reason-surface`.
+ * @csspart reason-surface-right - The bubble while it is right of the send button. Set together with `reason-surface`.
+ * @csspart reason-surface-top - The bubble while it is above the send button. Set together with `reason-surface`.
+ * @csspart send - The send button, which is the stop button while `busy`.
  * @csspart start - The box around the `start` slot.
  * @csspart tools - The row under the field.
  * @csspart voice - The dictation button, under `voice`, before the send button.
  * @csspart voice-listening - The dictation button while it listens. Set alongside `voice`.
  * @csspart voice-status - What a screen reader hears as dictation starts and stops, drawn for no one else.
  *
+ * @cssstate example-entering - The example in the empty field has just replaced the one before it, for an entrance. It holds for 350 milliseconds. See `placeholders`.
+ * @cssstate example-leaving - The example in the empty field is giving way to the next one, for an exit. It holds for 250 milliseconds, and the next example becomes the placeholder 100 milliseconds in, so the two can cross. See `placeholders`.
  * @cssstate invalid - The draft fails `required`, `minlength`, `maxlength`, or a custom error, and the reader has tried to send or submit it, or edited the field and left it. Or `feedback` is set.
  * @cssstate listening - While the composer listens for dictation. The element sets `--dictation-level` on itself meanwhile, from 0 to 1, for a meter.
  */
@@ -84,6 +130,22 @@ export declare class HelixHeadlessChatComposer extends HelixHeadlessChatComposer
      * `registerWords('de', { 'helix-chat-composer': { sendLabel: 'Senden' } })`.
      */
     static words: string;
+    /**
+     * Whether the draft holds something besides its text, such as an attached
+     * file. The draft then counts as one though the field is empty, so the
+     * send button shows in place of the `idle` slot.
+     */
+    attached: boolean;
+    /**
+     * Whether a reply is on its way. While set, the send button is a stop
+     * button that sends `helix-stop`, and the draft does not send.
+     *
+     * **The same button rather than one beside it**, because sending and
+     * stopping are never both possible: while a reply is on its way there is
+     * nothing to send to, and the place the reader's eye goes to act is the
+     * place that can act. The field stays open for the next turn.
+     */
+    busy: boolean;
     /**
      * A message about the draft, shown under the field. While set, the composer
      * is invalid, does not send, and does not submit, as a field's `feedback`
@@ -107,6 +169,35 @@ export declare class HelixHeadlessChatComposer extends HelixHeadlessChatComposer
      * Placeholder text shown in an empty field.
      */
     placeholder: string;
+    /**
+     * Examples the empty field shows in turn, in place of `placeholder`, such
+     * as tasks a reader might ask for. Each shows for 6.5 seconds, and a longer
+     * one shows longer, up to 10 seconds.
+     *
+     * **Each is the field's placeholder in its turn**, so a screen reader that
+     * reaches the field hears the one showing. The swap runs through
+     * `:state(example-leaving)`, as one example leaves, and
+     * `:state(example-entering)`, as the next arrives.
+     *
+     * **They move only while nobody is about to write, and while the reader
+     * can see them.** An empty field without focus moves on. Focus or text
+     * holds the example showing, and an example already leaving finishes its
+     * turn. A composer scrolled out of view holds its example, and the example
+     * gets its full time again when the composer comes back. Where the reader
+     * asked for less motion, or the page paused its motion, the first example
+     * stays.
+     */
+    placeholders: readonly string[];
+    /**
+     * Whether Enter sends while `busy`, for a page that queues the turn or
+     * hands it to the reply under way.
+     *
+     * Off by default, because a page that does neither would drop the turn: it
+     * has nowhere to put a message while a reply is coming. The button stays
+     * the stop button either way, since stopping is still the one thing it
+     * should do while a reply is on its way.
+     */
+    queue: boolean;
     /**
      * Whether the form needs a draft to submit. An empty draft never sends,
      * required or not.
@@ -118,10 +209,28 @@ export declare class HelixHeadlessChatComposer extends HelixHeadlessChatComposer
      * It grows from there.
      */
     rows: number;
+    /**
+     * Whether the draft waits to be sent, such as while an attachment is still
+     * read. The send button is unavailable and Enter does not send, while the
+     * field stays open. The stop button shown while `busy` still stops.
+     */
+    sendDisabled: boolean;
     /**
      * Label for the send button.
      */
     sendLabel: string;
+    /**
+     * Why the draft waits, such as "Reading photo.jpg", shown in a tooltip on
+     * the send button while `send-disabled` is set. The button then stays in
+     * the tab order and takes the pointer, with `aria-disabled` in place of
+     * `disabled`, so the reason can be reached by keyboard and by pointer, as
+     * Button's `focusable-when-disabled` does. A press still sends nothing.
+     */
+    sendReason: string;
+    /**
+     * Label for the stop button shown while `busy`.
+     */
+    stopLabel: string;
     /**
      * What sends the turn: `enter` for the Enter key, or `button` for the send
      * button only.
@@ -164,6 +273,29 @@ export declare class HelixHeadlessChatComposer extends HelixHeadlessChatComposer
     private edited;
     /** Whether the composer shows that its draft is wrong. */
     private shownInvalid;
+    /** Which of `placeholders` the empty field shows. */
+    private example;
+    /**
+     * Which of `placeholders` is on its way out while the next comes in, so a
+     * tier can draw the two at once.
+     */
+    private leavingExample;
+    /** Whether the field holds focus, which holds the examples still. */
+    private focused;
+    /** Whether any of the composer is in view, which the examples need to move. */
+    private onScreen;
+    /** Watches the composer come into view and go out of it. */
+    private sight;
+    /** The wait before the example showing leaves, while the examples move. */
+    private turning;
+    /** The wait before the next example appears, part way through the exit. */
+    private crossing;
+    /** The exit of the example leaving, while it runs. */
+    private leaving;
+    /** The entrance of the example arriving, while it runs. */
+    private entering;
+    /** Stops listening to the page's motion switch. */
+    private unmoved;
     /** The pause after which the user has stopped writing. */
     private readonly pause;
     /**
@@ -204,8 +336,90 @@ export declare class HelixHeadlessChatComposer extends HelixHeadlessChatComposer
      * 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.
+     * Re-marked on `slotchange` as well as after a render, so a control a
+     * framework renders after the first render is shown.
      */
     private markEmpty;
+    /**
+     * Whether the `idle` slot shows in the send button's place: a child is in
+     * it, the draft is empty, and no reply is on its way. Read off the children
+     * where they are known, and drawn again as the slot's contents change. A
+     * server cannot know them, so it serves the send button, which a hydrating
+     * render keeps until `finishHydration` reads them.
+     */
+    private get idling();
+    /**
+     * Whether anything is slotted in `attachments`, where the children are
+     * known. A server cannot know them, so it serves the region hidden and
+     * takes no gap above the field for an empty draft, the common case.
+     * `markEmpty` keeps it right after every render and on `slotchange`.
+     */
+    private get carrying();
+    /**
+     * A press on the attachments' empty space, such as the gap between two
+     * thumbnails, keeps the reader in the field, so the next key they press is
+     * typed. A press on a control of their own, such as a button that removes
+     * an attachment, is left to that control.
+     */
+    private readonly handleAttachmentsDown;
+    /** Where focus was as an update began: on the send button, in the idle control, or elsewhere. */
+    private focusedOn;
+    /** Reads which control holds focus, before an update swaps them. */
+    private noteFocus;
+    /** Moves focus to the control that came, where it was on the one that went. */
+    private keepFocus;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /** Notes focus coming and going, which holds the examples or frees them. */
+    private readonly handleFocus;
+    /** The examples drawn over the field: the one showing, and the one leaving while they cross. */
+    private renderExamples;
+    /** The example the empty field shows, or `placeholder` where there are none. */
+    private get shownPlaceholder();
+    /**
+     * Starts the examples moving, or stops them, as the list, the field, and
+     * the page allow.
+     *
+     * **Each turn is timed by the example showing**, so a long one stays up
+     * longer. **Focus holds the examples and leaves a turn under way to
+     * finish**, so the field never shows half an exit. Text, reduced motion, a
+     * paused page, scrolling out of view, and leaving the document stop them at
+     * once.
+     */
+    private turnExamples;
+    /**
+     * Starts the example showing on its way out. The next appears part way
+     * through the exit, and the one leaving goes once its exit ends.
+     */
+    private leaveExample;
+    /** Shows the next example, on its way in, and times the turn after it. */
+    private arriveExample;
+    private stopExamples;
+    /**
+     * Called as the example showing has landed: its entrance ended, or the
+     * examples stopped. A tier that holds anything for the swap lets it go
+     * here. The headless tier holds nothing.
+     */
+    protected exampleLanded(): void;
+    /**
+     * What the tier above draws over the empty field while `placeholders` holds
+     * two examples or more, behind a seam so a tier can draw the swap the
+     * field's own placeholder cannot. `example` is the field's placeholder, and
+     * `leaving` the one on its way out, each with its place in `placeholders`.
+     * For the first 100 milliseconds of an exit the two are the same example,
+     * and after that they cross. The headless tier draws nothing, and its field
+     * shows each example as its placeholder.
+     *
+     * **The field keeps its placeholder either way**, so whatever is drawn
+     * here is decoration, and the field is what a screen reader reaches.
+     */
+    protected renderExample(_example: {
+        index: number;
+        text: string;
+    }, _leaving?: {
+        index: number;
+        text: string;
+    }): TemplateResult | typeof nothing;
     protected updated(changed: PropertyValues): void;
     protected firstUpdated(changed: PropertyValues): void;
     protected willUpdate(changed: PropertyValues): void;
@@ -226,7 +440,7 @@ export declare class HelixHeadlessChatComposer extends HelixHeadlessChatComposer
      */
     protected renderSend(): TemplateResult;
     /**
-     * The field, and a row of tools under it.
+     * What the draft carries, the field, and a row of tools under it.
      *
      * **The tools take a line of their own rather than sharing the field's.** On
      * one line every tool a consumer adds takes width away from the thing being
@@ -254,6 +468,7 @@ export declare class HelixHeadlessChatComposer extends HelixHeadlessChatComposer
      */
     private readonly handleInput;
     private readonly handleSend;
+    private readonly handleStop;
     /**
      * Enter sends where that is what `submit-on` says, and never mid-composition.
      *