@fusion.dev/helix-headless 0.147.0 → 0.149.0

package/dist/canvas/snap.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Where a card lands on a board that snaps: the arithmetic of a ruling, kept
+ * apart from the board that applies it.
+ *
+ * Every value is in the document's own units, and a step of nothing, zero or
+ * less is no snapping at all, so a board without `snap` moves exactly as it
+ * did before there was one.
+ */
+/** A box on the board, in the document's own units. */
+export interface SnapBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * A value at the nearest multiple of `step`, or the value as it is where there
+ * is no step. A drag lets go wherever the hand is, and lands on the line
+ * nearest it.
+ */
+export declare const snapTo: (value: number, step: number | undefined) => number;
+/**
+ * The next multiple of `step` from `value`, the way a key points: `way` is `1`
+ * or `-1`.
+ *
+ * **On to the next line, and never back onto the same one.** A card sitting
+ * between two lines goes to the line ahead of it, and one on a line goes a
+ * whole step, so every press moves the card and every press lands on a line.
+ */
+export declare const stepTo: (value: number, way: number, step: number) => number;
+/**
+ * A box resized from a corner, with the edges that corner moves snapped, and
+ * held to a least size.
+ *
+ * Only the moving edges: the corner opposite the one in hand stays where it
+ * was, as it does without a ruling. Where the line nearest is inside the least
+ * size, the box stays at the least size rather than turning inside out.
+ */
+export declare const snapBox: (box: SnapBox, start: SnapBox, corner: string, step: number | undefined, least: {
+    width: number;
+    height: number;
+}) => SnapBox;

package/dist/canvas/snap.js

@@ -0,0 +1,32 @@
+const snaps = (step) => step !== undefined && Number.isFinite(step) && step > 0;
+export const snapTo = (value, step) => snaps(step) ? Math.round(value / step) * step : value;
+export const stepTo = (value, way, step) => {
+    if (way === 0) {
+        return value;
+    }
+    const at = value / step;
+    const near = Math.round(at);
+    const on = Math.abs(at - near) < 1e-9 ? near : at;
+    return (way > 0 ? Math.floor(on) + 1 : Math.ceil(on) - 1) * step;
+};
+export const snapBox = (box, start, corner, step, least) => {
+    if (!snaps(step)) {
+        return box;
+    }
+    const left = corner.endsWith('left');
+    const top = corner.startsWith('top');
+    const right = start.x + start.width;
+    const bottom = start.y + start.height;
+    const width = left
+        ? Math.max(least.width, right - snapTo(box.x, step))
+        : Math.max(least.width, snapTo(box.x + box.width, step) - start.x);
+    const height = top
+        ? Math.max(least.height, bottom - snapTo(box.y, step))
+        : Math.max(least.height, snapTo(box.y + box.height, step) - start.y);
+    return {
+        height,
+        width,
+        x: left ? right - width : start.x,
+        y: top ? bottom - height : start.y,
+    };
+};

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

@@ -1,4 +1,4 @@
-import { HelixElement } from '@fusion.dev/helix-core';
+import { ChildrenController, HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
  * @summary Shows one slide of several, with controls to move between them.
@@ -94,6 +94,11 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @cssstate dragging - While a mouse drags the track, under `mouse-drag`.
  */
 export declare class HelixHeadlessCarousel extends HelixElement {
+    /**
+     * The key this family's words are registered under, its styled tag:
+     * `registerWords('de', { 'helix-carousel': { nextLabel: 'Nächste Folie' } })`.
+     */
+    static words: string;
     /**
      * Manual, so each slide can be wrapped without its markup being touched.
      *
@@ -727,9 +732,10 @@ export declare class HelixHeadlessCarousel extends HelixElement {
      * that changes an assignment is this component calling `assign`, so a slide
      * appended by a consumer would reach no slot, render nowhere and be counted by
      * nothing. A default slot needs no watcher, taking whatever is there; a manual
-     * one does. `Chat` watches for the same reason.
+     * one does. `Chat` watches for the same reason, through the same core
+     * controller.
      */
-    private watcher;
+    protected readonly childWatch: ChildrenController;
     connectedCallback(): void;
     disconnectedCallback(): void;
     /** Pauses without forgetting that the reader wanted it running. */

package/dist/carousel/root/carousel-root.js

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     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 { capturePointer, customElement, fillTemplate, HelixActivateEvent, HelixElement, HelixSelectEvent, hostAria, inlineStep, isRtl, requestChange, } from '@fusion.dev/helix-core';
+import { ChildrenController, capturePointer, customElement, formatWords, HelixActivateEvent, HelixElement, HelixSelectEvent, hostAria, inlineStep, isRtl, requestChange, words, } from '@fusion.dev/helix-core';
 import { caretLeft, caretRight, play, stop } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -185,13 +185,14 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
         };
         this.scrollFrame = 0;
         this.stopped = false;
-        this.watcher = undefined;
+        this.childWatch = new ChildrenController(this);
         this.pause = () => {
             if (!this.stopped) {
                 this.rotating = false;
             }
         };
     }
+    static { this.words = 'helix-carousel'; }
     static { this.shadowRootOptions = {
         ...HelixElement.shadowRootOptions,
         slotAssignment: 'manual',
@@ -388,8 +389,6 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
         super.connectedCallback();
         this.addEventListener('focusin', this.pause);
         this.addEventListener('pointerenter', this.pause);
-        this.watcher = new MutationObserver(() => this.requestUpdate());
-        this.watcher.observe(this, { childList: true });
         this.watchPane();
         if (this.hasUpdated) {
             this.runTimer();
@@ -403,8 +402,6 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
         }
         this.removeEventListener('focusin', this.pause);
         this.removeEventListener('pointerenter', this.pause);
-        this.watcher?.disconnect();
-        this.watcher = undefined;
         this.sizes?.disconnect();
         this.sizes = undefined;
         this.watched = undefined;
@@ -419,7 +416,7 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
         if (changed.has('index')) {
             this.showing = undefined;
             if (this.hasUpdated) {
-                this.said = fillTemplate(this.slideLabel, {
+                this.said = formatWords(this, 'slideLabel', {
                     count: this.slides.length,
                     index: this.index + 1,
                 });
@@ -569,7 +566,7 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
             part="slide"
             role="group"
             aria-roledescription=${this.slideRoleLabel || nothing}
-            aria-label=${fillTemplate(this.slideLabel, { count: this.slides.length, index: index + 1 })}
+            aria-label=${formatWords(this, 'slideLabel', { count: this.slides.length, index: index + 1 })}
             style=${this.paneStyle(index, last, stops)}
           >
             <slot
@@ -580,14 +577,14 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
       </div>
       ${''}<span part="live" aria-live=${rotating ? 'off' : 'polite'}>${this.said}</span>
       ${this.slides.length > 1 && this.across !== undefined
-            ? html `<div part="indicators" role="group" aria-label=${fillTemplate(this.indicatorsLabel, { label: this.label })}>
+            ? html `<div part="indicators" role="group" aria-label=${formatWords(this, 'indicatorsLabel', { label: this.label })}>
               ${''}
               ${stops.map((stop, at) => {
                 const current = at === showing;
                 return html `<button
                   part="indicator${current ? ' indicator-current' : ''}"
                   type="button"
-                  aria-label=${fillTemplate(this.indicatorLabel, { index: at + 1 })}
+                  aria-label=${formatWords(this, 'indicatorLabel', { index: at + 1 })}
                   aria-current=${at === place ? 'true' : nothing}
                   tabindex=${at === place ? '0' : '-1'}
                   ?data-current=${current}
@@ -612,15 +609,18 @@ __decorate([
     property({ type: Number })
 ], HelixHeadlessCarousel.prototype, "index", null);
 __decorate([
+    words,
     property({ attribute: 'indicator-label' })
 ], HelixHeadlessCarousel.prototype, "indicatorLabel", void 0);
 __decorate([
+    words,
     property({ attribute: 'indicators-label' })
 ], HelixHeadlessCarousel.prototype, "indicatorsLabel", void 0);
 __decorate([
     property({ type: Number })
 ], HelixHeadlessCarousel.prototype, "interval", void 0);
 __decorate([
+    words,
     property()
 ], HelixHeadlessCarousel.prototype, "label", void 0);
 __decorate([
@@ -630,6 +630,7 @@ __decorate([
     property({ attribute: 'mouse-drag', reflect: true, type: Boolean })
 ], HelixHeadlessCarousel.prototype, "mouseDrag", void 0);
 __decorate([
+    words,
     property({ attribute: 'next-label' })
 ], HelixHeadlessCarousel.prototype, "nextLabel", void 0);
 __decorate([
@@ -642,24 +643,30 @@ __decorate([
     property({ attribute: 'per-view', converter: COUNT_OR_AUTO, reflect: true })
 ], HelixHeadlessCarousel.prototype, "perView", void 0);
 __decorate([
+    words,
     property({ attribute: 'previous-label' })
 ], HelixHeadlessCarousel.prototype, "previousLabel", void 0);
 __decorate([
+    words,
     property({ attribute: 'role-label' })
 ], HelixHeadlessCarousel.prototype, "roleLabel", void 0);
 __decorate([
+    words,
     property({ attribute: 'slide-label' })
 ], HelixHeadlessCarousel.prototype, "slideLabel", void 0);
 __decorate([
+    words,
     property({ attribute: 'slide-role-label' })
 ], HelixHeadlessCarousel.prototype, "slideRoleLabel", void 0);
 __decorate([
     property({ attribute: 'slides-per-move', type: Number })
 ], HelixHeadlessCarousel.prototype, "slidesPerMove", void 0);
 __decorate([
+    words,
     property({ attribute: 'start-label' })
 ], HelixHeadlessCarousel.prototype, "startLabel", void 0);
 __decorate([
+    words,
     property({ attribute: 'stop-label' })
 ], HelixHeadlessCarousel.prototype, "stopLabel", void 0);
 __decorate([

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

@@ -47,6 +47,11 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @csspart tools - The row under the field.
  */
 export declare class HelixHeadlessChatComposer extends HelixFormElement {
+    /**
+     * The key this part's words are registered under, its styled tag:
+     * `registerWords('de', { 'helix-chat-composer': { sendLabel: 'Senden' } })`.
+     */
+    static words: string;
     /**
      * The field's name, read by screen readers.
      */

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

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     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, DelayController, HelixFormElement, HelixSendEvent, HelixTypingEvent, hostAria, markRegion, } from '@fusion.dev/helix-core';
+import { customElement, DelayController, HelixFormElement, HelixSendEvent, HelixTypingEvent, hostAria, markRegion, words, } from '@fusion.dev/helix-core';
 import { arrowElbowDownLeft } from '@fusion.dev/helix-icons';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
@@ -43,6 +43,7 @@ let HelixHeadlessChatComposer = class HelixHeadlessChatComposer extends HelixFor
             this.send();
         };
     }
+    static { this.words = 'helix-chat-composer'; }
     get typing() {
         return this.writing;
     }
@@ -136,6 +137,7 @@ let HelixHeadlessChatComposer = class HelixHeadlessChatComposer extends HelixFor
     }
 };
 __decorate([
+    words,
     property()
 ], HelixHeadlessChatComposer.prototype, "label", void 0);
 __decorate([
@@ -145,6 +147,7 @@ __decorate([
     property({ type: Number })
 ], HelixHeadlessChatComposer.prototype, "rows", void 0);
 __decorate([
+    words,
     property({ attribute: 'send-label' })
 ], HelixHeadlessChatComposer.prototype, "sendLabel", void 0);
 __decorate([

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

@@ -3,8 +3,8 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 /**
  * What a turn that did not send is called, where nobody said otherwise.
  *
- * Exported because the transcript says it too: a failure is announced in the
- * words the turn shows, and two defaults for one phrase are two phrases.
+ * @deprecated The English of `failed-label`, which is now a word property:
+ * register its words with `registerWords`. Removed in the next major version.
  */
 export declare const FAILED_LABEL = "Not sent";
 /**
@@ -55,6 +55,11 @@ export declare const FAILED_LABEL = "Not sent";
  * @csspart time - The turn's time.
  */
 export declare class HelixHeadlessChatMessage extends HelixElement {
+    /**
+     * The key this part's words are registered under, its styled tag:
+     * `registerWords('de', { 'helix-chat-message': { retryLabel: 'Erneut versuchen' } })`.
+     */
+    static words: string;
     /**
      * The turn's time, in any format `Date` parses.
      */
@@ -82,9 +87,8 @@ export declare class HelixHeadlessChatMessage extends HelixElement {
      */
     failedLabel: string;
     /**
-     * Locale for the timestamp.
-     *
-     * Empty is the runtime's own.
+     * The locale the timestamp and the words are in, as a BCP 47 tag such as
+     * `de`. Empty reads the nearest `lang`, then the browser's language.
      */
     locale: string;
     /**

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

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     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, markRegion, RelativeClockController, relativeTime, requestChange, TONE_MARKS, } from '@fusion.dev/helix-core';
+import { customElement, HelixElement, HelixSendEvent, hostAria, markRegion, RelativeClockController, relativeTime, requestChange, TONE_MARKS, words, wordsLocale, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
@@ -15,7 +15,7 @@ let HelixHeadlessChatMessage = class HelixHeadlessChatMessage extends HelixEleme
         super(...arguments);
         this.at = '';
         this.authorLabel = '';
-        this.failedLabel = FAILED_LABEL;
+        this.failedLabel = 'Not sent';
         this.locale = '';
         this.retryLabel = 'Try again';
         this.sendingLabel = 'Sending';
@@ -24,7 +24,7 @@ let HelixHeadlessChatMessage = class HelixHeadlessChatMessage extends HelixEleme
         this.clock = new RelativeClockController(this, {
             expires: (now) => {
                 const moment = this.moment;
-                return moment ? relativeTime(this.locale)(moment, now).next : undefined;
+                return moment ? relativeTime(wordsLocale(this))(moment, now).next : undefined;
             },
         });
         this.handleFill = () => {
@@ -49,6 +49,7 @@ let HelixHeadlessChatMessage = class HelixHeadlessChatMessage extends HelixEleme
             });
         };
     }
+    static { this.words = 'helix-chat-message'; }
     get moment() {
         if (this.at === '') {
             return undefined;
@@ -66,7 +67,7 @@ let HelixHeadlessChatMessage = class HelixHeadlessChatMessage extends HelixEleme
     }
     get reading() {
         const moment = this.moment;
-        return moment ? relativeTime(this.locale)(moment, new Date(this.clock.now)).text : '';
+        return moment ? relativeTime(wordsLocale(this))(moment, new Date(this.clock.now)).text : '';
     }
     get name() {
         return turnName(authorWords(this.author, this.authorLabel, this.turnWords), this.reading, this.turnWords);
@@ -142,15 +143,18 @@ __decorate([
     property({ attribute: 'author-label' })
 ], HelixHeadlessChatMessage.prototype, "authorLabel", void 0);
 __decorate([
+    words,
     property({ attribute: 'failed-label' })
 ], HelixHeadlessChatMessage.prototype, "failedLabel", void 0);
 __decorate([
     property()
 ], HelixHeadlessChatMessage.prototype, "locale", void 0);
 __decorate([
+    words,
     property({ attribute: 'retry-label' })
 ], HelixHeadlessChatMessage.prototype, "retryLabel", void 0);
 __decorate([
+    words,
     property({ attribute: 'sending-label' })
 ], HelixHeadlessChatMessage.prototype, "sendingLabel", void 0);
 __decorate([

package/dist/chat/naming.js

@@ -1,4 +1,4 @@
-import { fillTemplate } from '@fusion.dev/helix-core';
+import { formatMessage } from '@fusion.dev/helix-core';
 export const TURN_WORDS = { me: 'You', sentence: '{author}, {time}', turn: 'Message' };
 export const authorWords = (author, authorLabel, words) => {
     if (authorLabel !== '') {
@@ -10,5 +10,5 @@ export const authorWords = (author, authorLabel, words) => {
     return author === undefined || author === 'them' ? '' : author;
 };
 export const turnName = (author, time, words) => author !== '' && time !== ''
-    ? fillTemplate(words.sentence, { author, time })
+    ? formatMessage(words.sentence, { author, time }, '')
     : author || time || words.turn;

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

@@ -1,6 +1,6 @@
-import { HelixElement } from '@fusion.dev/helix-core';
+import { ChildrenController, HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
-import { type HelixHeadlessChatMessage } from '../message/chat-message.js';
+import type { HelixHeadlessChatMessage } from '../message/chat-message.js';
 /** One turn handed over as data, which is what `turns` holds. */
 export interface ChatTurn {
     /** When it was said, as anything `Date` parses. */
@@ -128,6 +128,11 @@ declare const HelixHeadlessChat_base: (new (...args: any[]) => import("@fusion.d
  * @csspart typing - The words that say who is typing, in the status band, while `typing` names someone.
  */
 export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
+    /**
+     * The key this family's words are registered under, its styled tag:
+     * `registerWords('de', { 'helix-chat': { typingLabel: '{author} schreibt' } })`.
+     */
+    static words: string;
     /**
      * Slots are assigned manually, so only the turns go into the log.
      *
@@ -159,6 +164,19 @@ export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
      * so a default of true had no attribute that turned it off.
      */
     defaultPinned: boolean;
+    /**
+     * What a turn from `turns` that did not send says, and what a screen reader
+     * hears before its words. A turn you write as a child says its own
+     * `failed-label`.
+     */
+    failedLabel: string;
+    /**
+     * What a screen reader hears for a turn that did not send. `{failed}` is the
+     * turn's `failed-label` and `{text}` is its words.
+     */
+    failedTurnLabel: string;
+    /** The conversation's name, read by screen readers, where `label` is empty. */
+    fallbackLabel: string;
     /**
      * Whether there are older turns to load, and whether they are loading.
      *
@@ -253,8 +271,18 @@ export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
      * a turn is told again only when they change.
      */
     private words;
-    /** Watches for turns arriving, since a manual slot hears nothing about them. */
-    private watcher;
+    /**
+     * Watches for turns arriving, since a manual slot hears nothing about them.
+     *
+     * **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. Children only,
+     * never a turn's own text, which a streaming turn rewrites every frame.
+     */
+    protected readonly childWatch: ChildrenController;
     /** Watches the turns' own `state`, which is when one of them settles. */
     private settling;
     /** Watches the turns and the log for size, which scrolling does not report. */
@@ -366,6 +394,14 @@ export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
      * turn; what they were reading is the one fixed point. It is also idempotent,
      * which is what lets it run beside the browser's own scroll anchoring where
      * there is some: a turn the browser already put back has not moved.
+     *
+     * **A transcript fed as data writes no scroll offset while the reader
+     * scrolls.** Turns drawn above the reader for the first time come out taller
+     * or shorter than the estimate, and a write to `scrollTop` to make up for
+     * them ends a fling on iOS. While the reader scrolls, the controller holds
+     * them instead, in its spacer above the window, and squares the scroll offset
+     * once the log is still. The turn noted before a scroll whose event has not
+     * arrived is out of date, so that counts as scrolling too.
      */
     private restore;
     /** Fires `helix-history` once for each time the reader reaches the top. */