@fusion.dev/helix-headless 0.144.0 → 0.146.0

package/dist/object-inspector/rows.js

@@ -0,0 +1,119 @@
+export const branchy = (value) => value !== null && typeof value === 'object';
+export const entries = (value) => Array.isArray(value) ? value.map((item, at) => [String(at), item]) : Object.entries(value);
+export const child = (path, key) => `${path}/${key.replaceAll('~', '~0').replaceAll('/', '~1')}`;
+export const ancestorsOf = (path) => {
+    const cuts = [];
+    for (let at = path.indexOf('/'); at !== -1; at = path.indexOf('/', at + 1)) {
+        cuts.push(path.slice(0, at));
+    }
+    return cuts;
+};
+const words = (value) => (branchy(value) ? '' : String(value));
+export const search = (root, query) => {
+    const found = new Set();
+    const wanted = query.trim().toLocaleLowerCase();
+    if (wanted === '' || root === undefined) {
+        return found;
+    }
+    const visit = (value, path, key) => {
+        if (key?.toLocaleLowerCase().includes(wanted) ||
+            words(value).toLocaleLowerCase().includes(wanted)) {
+            found.add(path);
+        }
+        if (branchy(value)) {
+            for (const [name, item] of entries(value)) {
+                visit(item, child(path, name), name);
+            }
+        }
+    };
+    visit(root, '');
+    return found;
+};
+export const flatten = (root, opened, found) => {
+    const rows = [];
+    if (root === undefined) {
+        return rows;
+    }
+    const trail = new Set([...(found ?? [])].flatMap(ancestorsOf));
+    const visit = (value, path, depth, position, siblings, under, key) => {
+        const branch = branchy(value);
+        const open = branch && opened.has(path);
+        const match = found?.has(path) === true;
+        rows.push({
+            branch,
+            depth,
+            match,
+            open,
+            path,
+            position,
+            siblings,
+            value,
+            ...(key === undefined ? {} : { key }),
+        });
+        if (!open) {
+            return;
+        }
+        const inside = under || match || !found;
+        const children = entries(value)
+            .map(([name, item]) => [name, item, child(path, name)])
+            .filter(([, , at]) => inside || found?.has(at) || trail.has(at));
+        children.forEach(([name, item, at], index) => {
+            visit(item, at, depth + 1, index + 1, children.length, inside && !!found, name);
+        });
+    };
+    if (!found || found.has('') || trail.has('')) {
+        visit(root, '', 0, 1, 1, false);
+    }
+    return rows;
+};
+export const seed = (root, depth, known = new Set(), opened = new Set()) => {
+    const open = new Set();
+    const branches = new Set();
+    const visit = (value, path, level) => {
+        if (!branchy(value)) {
+            return;
+        }
+        branches.add(path);
+        if (known.has(path) ? opened.has(path) : level < depth) {
+            open.add(path);
+        }
+        for (const [name, item] of entries(value)) {
+            visit(item, child(path, name), level + 1);
+        }
+    };
+    visit(root, '', 0);
+    return { branches, opened: open };
+};
+export const cursorFor = (rows, path, cursor, filtered) => {
+    const at = (one) => rows.findIndex((row) => row.path === one);
+    const own = path === undefined ? -1 : at(path);
+    if (own >= 0 || path === undefined) {
+        return own >= 0 ? own : Math.min(cursor, Math.max(0, rows.length - 1));
+    }
+    const match = filtered ? rows.findIndex((row) => row.match) : -1;
+    const around = ancestorsOf(path)
+        .reverse()
+        .map(at)
+        .find((one) => one >= 0);
+    return match >= 0 ? match : (around ?? 0);
+};
+export const withAncestors = (opened, branches, paths) => {
+    const next = new Set(opened);
+    for (const path of paths) {
+        for (const above of ancestorsOf(path)) {
+            if (branches.has(above)) {
+                next.add(above);
+            }
+        }
+    }
+    return next;
+};
+export const siblingBranches = (rows, row) => {
+    const parent = row.path.slice(0, row.path.lastIndexOf('/'));
+    return rows
+        .filter((one) => one.branch &&
+        !one.open &&
+        one.depth === row.depth &&
+        one.path.slice(0, one.path.lastIndexOf('/')) === parent)
+        .map((one) => one.path);
+};

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

@@ -63,9 +63,11 @@ export declare class HelixHeadlessOption extends HelixElement {
     /**
      * Whether this is the option the keyboard is on.
      *
-     * Written by the listbox, which writes it once a reader moves the highlight.
-     * It shows as `:state(active)`, and as a `data-active` attribute for the
-     * stylesheets written before the state existed.
+     * Written by the listbox once a reader moves the highlight. Style it with
+     * `:state(active)`, or `::part(item-active)` for an option inside another
+     * component's shadow root. The `data-active` attribute sets it from markup;
+     * it is also written back for stylesheets from before the state, and no
+     * stylesheet of the library's own selects it.
      */
     active: boolean;
     /**

package/dist/outline/levels.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The levels of a flat run of links, as the nested lists they describe.
+ *
+ * A contents list written flat, `<a data-level="2">`, says its depth in an
+ * attribute that only a stylesheet reads. The outline turns the run into lists
+ * inside list items in its shadow root, so a screen reader hears the levels a
+ * nested `<ul>` would have given it, with the links left where they are.
+ */
+/** One link in the tree: its place in the run, and the links nested under it. */
+export interface Branch {
+    /** The link's position in the flat run, counted from zero. */
+    index: number;
+    /** The links one level or more deeper that follow it, before the next at its level. */
+    children: Branch[];
+}
+/**
+ * The level a link's `data-level` asks for, a whole number from 1.
+ *
+ * Absent, empty, or not a number is the top level, which is how the outline
+ * has always read a link without one.
+ */
+export declare const levelOf: (value: string | null) => number;
+/**
+ * Nests a run of levels.
+ *
+ * Each link goes under the nearest link before it with a lower level, and to
+ * the top where there is none. A jump of two levels nests one list deeper and
+ * not two, since a list item with no link of its own would be read as an empty
+ * entry. A run that starts deeper than 1 starts at the top all the same.
+ */
+export declare const nest: (levels: readonly number[]) => Branch[];

package/dist/outline/levels.js

@@ -0,0 +1,23 @@
+export const levelOf = (value) => {
+    const level = Number.parseInt(value ?? '', 10);
+    return Number.isFinite(level) && level >= 1 ? level : 1;
+};
+export const nest = (levels) => {
+    const top = [];
+    const open = [];
+    levels.forEach((level, index) => {
+        const branch = { children: [], index };
+        while (open.length > 0 && (open.at(-1)?.level ?? 0) >= level) {
+            open.pop();
+        }
+        const parent = open.at(-1);
+        if (parent) {
+            parent.branch.children.push(branch);
+        }
+        else {
+            top.push(branch);
+        }
+        open.push({ branch, level });
+    });
+    return top;
+};

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

@@ -1,5 +1,6 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
+import { type Branch } from '../levels.js';
 /**
  * @summary Links to the headings on the page, with the section in view marked.
  *
@@ -12,8 +13,15 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * the same page.
  *
  * Write the anchors flat, with `data-level` for their depth, or nested in
- * lists, `<ul><li><a>`. A screen reader hears a nested list's levels; it hears
- * `data-level` as a flat run of links.
+ * lists, `<ul><li><a>`. A screen reader hears the levels either way: the
+ * outline puts a flat run into lists inside list items of its own, nested by
+ * `data-level`, and leaves the links where they are. A link without
+ * `data-level` is at the top level.
+ *
+ * A heading slotted into `heading` names the navigation, in place of `label`.
+ *
+ * In a contents rail with a scrollbar of its own, `follow` keeps the link of
+ * the section in view showing as the reader scrolls the page.
  *
  * The current section is decided by the headings' positions. An
  * `IntersectionObserver` with a band near the top fails both ways: when
@@ -27,13 +35,24 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @documentation https://fusion.dev/helix/components/outline
  *
  * @slot - The links, as anchors with fragment hrefs, or lists holding them.
+ * @slot heading - A heading above the links, such as "On this page". It names the navigation.
  *
  * @event {HelixActivateEvent} helix-activate - Fired when the section in view changes, with its id as the value. It reports the scroll position and cannot be prevented.
  *
+ * @csspart heading - The box holding the `heading` slot, above the navigation.
  * @csspart indicator - The mark that moves to the section in view.
  * @csspart nav - The navigation landmark.
  */
 export declare class HelixHeadlessOutline extends HelixElement {
+    /**
+     * Manual, so each link in a flat run can be put in a list item of its own.
+     *
+     * The list items are slots, which lay out as nothing at all, so each link is
+     * still laid out as a child of the navigation exactly where it was, and the
+     * consumer's markup is not touched. A run holding anything but links, a
+     * `<ul>` among them, goes to one plain slot as before.
+     */
+    static shadowRootOptions: ShadowRootInit;
     private readonly indicator;
     /**
      * How the page scrolls to a section when its link is clicked.
@@ -58,7 +77,15 @@ export declare class HelixHeadlessOutline extends HelixElement {
      */
     behavior: ScrollBehavior;
     /**
-     * The navigation's name, read by screen readers.
+     * Keeps the link of the section in view in view itself, in an outline
+     * longer than the box it scrolls in, such as a contents rail with a
+     * scrollbar of its own. Only that box moves: never the page, and never the
+     * box the sections scroll in.
+     */
+    follow: boolean;
+    /**
+     * The navigation's name, read by screen readers. A heading in the `heading`
+     * slot names it in place of this.
      */
     label: string;
     /**
@@ -92,6 +119,11 @@ export declare class HelixHeadlessOutline extends HelixElement {
      */
     private reading;
     private observer;
+    /**
+     * Watches the children, which a manual root is not told about: a link
+     * arriving, leaving or changing its level changes the lists drawn for them.
+     */
+    private childWatch;
     /**
      * The links, in document order. Empty on the server, which has no tree.
      *
@@ -101,6 +133,18 @@ export declare class HelixHeadlessOutline extends HelixElement {
      * nothing was announced, and nothing said why.
      */
     private get links();
+    /** The children that are the content, which is all of them but the heading. */
+    private get content();
+    /**
+     * The links of a flat run, which the render puts into lists, or `undefined`
+     * where the content is anything else.
+     *
+     * Anything else is a list a consumer wrote, which already has its levels, a
+     * slot forwarded from a component around this one, or a server's render and
+     * the hydration of one, which cannot know the children. A root a server sent
+     * routes by name, so it keeps the plain slot after hydration too.
+     */
+    private get run();
     /**
      * What each link points at, paired with the link, skipping anything missing.
      *
@@ -120,6 +164,14 @@ export declare class HelixHeadlessOutline extends HelixElement {
     private mark;
     /** Where the destination is set, whether measured or asked for. */
     private markTo;
+    /**
+     * Scrolls the box the links scroll in to show `link`, under `follow`.
+     *
+     * The nearest box above the link that scrolls, and only where it is the
+     * rail's own: the page, the box the sections scroll in, or a box holding it
+     * would move the reading under the reader, which is the scroll this marks.
+     */
+    private reveal;
     /**
      * Whether the page has no more scroll left.
      *
@@ -250,8 +302,39 @@ export declare class HelixHeadlessOutline extends HelixElement {
     private unland;
     connectedCallback(): void;
     protected firstUpdated(changed: PropertyValues): void;
+    /**
+     * Puts each child in its slot, on a root this element made.
+     *
+     * A link of a flat run goes to the slot inside its list item, and anything
+     * else, with the text between, to the plain slot. A root a server sent
+     * routes by name and needs none of it.
+     */
+    private assign;
+    /** Whether the heading is what names the navigation. */
+    private namedByHeading;
+    /**
+     * Names the navigation by what is in the `heading` slot, in place of `label`.
+     *
+     * An element reference, because the heading is in the light DOM and the
+     * `<nav>` in this shadow root, which an IDREF cannot cross. A browser without
+     * element reflection keeps `label`.
+     */
+    private readonly nameByHeading;
     protected updated(changed: PropertyValues): void;
     protected render(): TemplateResult;
+    /**
+     * A list for a run of links, with a list item for each, nested by level.
+     *
+     * **Slots, because a slot lays out as nothing.** A list and its items drawn
+     * as boxes would put each link inside an item, out of the navigation's own
+     * flex column, and every outline styled against that column would move. A
+     * slot is `display: contents`, keeps a role it is given, and shows its
+     * children while nothing is assigned to it, so the items nest in the
+     * accessibility tree and nowhere else. Measured in Chromium: every link at the
+     * same box with and without the lists, and each item at the level its
+     * nesting gives it.
+     */
+    protected renderList(branches: Branch[]): TemplateResult;
 }
 declare global {
     interface HTMLElementTagNameMap {

package/dist/outline/root/outline-root.js

@@ -4,9 +4,11 @@ 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, elementById, HelixActivateEvent, HelixElement, IndicatorController, } from '@fusion.dev/helix-core';
-import { html } from 'lit';
+import { customElement, elementById, HelixActivateEvent, HelixElement, IndicatorController, plainClick, reflectElements, scrollItemIntoView, } from '@fusion.dev/helix-core';
+import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
+import { levelOf, nest } from '../levels.js';
+const isFragment = (element) => element instanceof HTMLAnchorElement && element.getAttribute('href')?.startsWith('#') === true;
 let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
     constructor() {
         super(...arguments);
@@ -16,6 +18,7 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
             surface: () => this.partNamed('nav'),
         });
         this.behavior = 'auto';
+        this.follow = false;
         this.label = 'On this page';
         this.offset = 0;
         this.reading = '';
@@ -30,10 +33,7 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
             });
         };
         this.handleClick = (event) => {
-            if (event.defaultPrevented || event.button !== 0) {
-                return;
-            }
-            if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
+            if (event.defaultPrevented || !plainClick(event)) {
                 return;
             }
             const link = event.target?.closest?.('a[href^="#"]');
@@ -72,16 +72,38 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
             this.watch();
             this.indicator.place();
         };
+        this.namedByHeading = false;
+        this.nameByHeading = () => {
+            const slot = this.renderRoot?.querySelector?.('slot[name="heading"]');
+            this.namedByHeading = reflectElements(this.partNamed('nav'), 'ariaLabelledByElements', slot?.assignedElements({ flatten: true }) ?? [], this.namedByHeading);
+        };
     }
+    static { this.shadowRootOptions = {
+        ...HelixElement.shadowRootOptions,
+        slotAssignment: 'manual',
+    }; }
     get current() {
         return this.reading;
     }
     get links() {
-        const slot = this.renderRoot?.querySelector('slot');
-        const fragment = (element) => element instanceof HTMLAnchorElement && element.getAttribute('href')?.startsWith('#') === true;
-        return (slot?.assignedElements({ flatten: true }) ?? []).flatMap((element) => fragment(element)
+        const slots = [
+            ...(this.renderRoot?.querySelectorAll?.('slot[data-link], nav > slot:not([role])') ?? []),
+        ];
+        return slots
+            .flatMap((slot) => slot.assignedElements({ flatten: true }))
+            .flatMap((element) => isFragment(element)
             ? [element]
-            : [...element.querySelectorAll('a[href^="#"]')].filter(fragment));
+            : [...element.querySelectorAll('a[href^="#"]')].filter(isFragment));
+    }
+    get content() {
+        return this.knownChildren.filter((child) => child.slot !== 'heading');
+    }
+    get run() {
+        const content = this.content;
+        if (this.assignsByName || content.length === 0 || !content.every(isFragment)) {
+            return undefined;
+        }
+        return content;
     }
     get sections() {
         return this.links.flatMap((link) => {
@@ -118,9 +140,26 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
         if (next !== this.reading) {
             this.reading = next;
             this.indicator.place();
+            if (this.follow && active) {
+                this.reveal(active.link);
+            }
             this.dispatchEvent(new HelixActivateEvent({ value: next }));
         }
     }
+    reveal(link) {
+        const sections = this.scroller;
+        const page = this.page;
+        for (let node = link.parentElement; node && node !== page; node = node.parentElement) {
+            const { overflowY } = getComputedStyle(node);
+            if (!/auto|scroll|overlay/.test(overflowY) || node.scrollHeight <= node.clientHeight) {
+                continue;
+            }
+            if (node !== sections && !node.contains(sections)) {
+                scrollItemIntoView(link, { scroller: node });
+            }
+            return;
+        }
+    }
     get atEnd() {
         const doc = this.scroller;
         return Math.ceil(doc.scrollTop + doc.clientHeight) >= doc.scrollHeight - 1;
@@ -163,6 +202,8 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
     }
     disconnectedCallback() {
         super.disconnectedCallback();
+        this.childWatch?.disconnect();
+        this.childWatch = undefined;
         this.removeEventListener('click', this.handleClick);
         document.removeEventListener('scroll', this.handleScroll, true);
         if (this.frame !== 0) {
@@ -183,6 +224,12 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
     }
     connectedCallback() {
         super.connectedCallback();
+        this.childWatch = new MutationObserver(() => this.requestUpdate());
+        this.childWatch.observe(this, {
+            attributeFilter: ['data-level', 'href', 'slot'],
+            childList: true,
+            subtree: true,
+        });
         this.addEventListener('click', this.handleClick);
         document.addEventListener('scroll', this.handleScroll, {
             capture: true,
@@ -195,9 +242,32 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
     firstUpdated(changed) {
         super.firstUpdated(changed);
         this.watch();
+        this.finishHydration();
+    }
+    assign() {
+        if (this.assignsByName) {
+            return;
+        }
+        const root = this.renderRoot;
+        const heading = root?.querySelector?.('slot[name="heading"]');
+        heading?.assign?.(...this.knownChildren.filter((child) => child.slot === 'heading'));
+        const run = this.run;
+        if (run) {
+            for (const slot of root?.querySelectorAll?.('slot[data-link]') ?? []) {
+                const link = run[Number(slot.dataset.link)];
+                if (link) {
+                    slot.assign(link);
+                }
+            }
+            return;
+        }
+        const plain = root?.querySelector?.('nav > slot:not([role])');
+        plain?.assign?.(...[...this.childNodes].filter((node) => node instanceof Element ? node.slot !== 'heading' : node instanceof Text));
     }
     updated(changed) {
         super.updated(changed);
+        this.assign();
+        this.nameByHeading();
         if (changed.has('offset')) {
             this.reach();
             this.mark();
@@ -208,15 +278,28 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
         this.indicator.place();
     }
     render() {
-        return html `<nav part="nav" aria-label=${this.label}>
-      <slot @slotchange=${this.handleSlotChange}></slot>
+        const run = this.run;
+        return html `<div part="heading"><slot name="heading" @slotchange=${this.nameByHeading}></slot></div>
+      <nav part="nav" aria-label=${this.label} @slotchange=${this.handleSlotChange}>
+      ${run ? this.renderList(nest(run.map((link) => levelOf(link.getAttribute('data-level'))))) : html `<slot></slot>`}
       <span part="indicator" aria-hidden="true"></span>
     </nav>`;
     }
+    renderList(branches) {
+        return html `<slot role="list"
+      >${branches.map((branch) => html `<slot role="listitem"
+            ><slot data-link=${branch.index}></slot
+            >${branch.children.length > 0 ? this.renderList(branch.children) : nothing}</slot
+          >`)}</slot
+    >`;
+    }
 };
 __decorate([
     property()
 ], HelixHeadlessOutline.prototype, "behavior", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessOutline.prototype, "follow", void 0);
 __decorate([
     property()
 ], HelixHeadlessOutline.prototype, "label", void 0);

package/dist/pagination/size/pagination-size.d.ts

@@ -1,4 +1,4 @@
-import { HelixElement } from '@fusion.dev/helix-core';
+import { HelixFormElement } from '@fusion.dev/helix-core';
 import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 import '../../option/index.js';
 import '../../select/index.js';
@@ -28,6 +28,11 @@ import '../../select/index.js';
  * Re-querying and returning to page one is up to you, because only you know
  * whether the current position should be kept.
  *
+ * It takes part in a form. Give it a `name` and the size in force is submitted
+ * under that name, so a `GET` form carries it in the address beside the page.
+ * A form reset returns it to `default-value`, and `disabled`, or a disabled
+ * `<fieldset>` around it, turns the select off.
+ *
  * @since 0.1.0
  * @status stable
  * @aliases Page size, Rows per page
@@ -44,6 +49,7 @@ import '../../select/index.js';
  * @csspart control-label - The label beside the number.
  * @csspart control-listbox - The list inside the panel.
  * @csspart control-listbox-empty - The text shown when the filter hides every option.
+ * @csspart control-listbox-error - The inner list's `error` part, shown while its `load-error` is set.
  * @csspart control-listbox-feedback - The inner list's message that says what is wrong with the value.
  * @csspart control-listbox-filter-icon - The icon beside the filter field.
  * @csspart control-listbox-filter-mark - The default icon beside the filter field, shown when none is slotted.
@@ -67,7 +73,7 @@ import '../../select/index.js';
  *
  * @cssstate empty - While there are no sizes to offer.
  */
-export declare class HelixHeadlessPaginationSize extends HelixElement {
+export declare class HelixHeadlessPaginationSize extends HelixFormElement {
     /**
      * The size to start on when `value` is not set.
      */
@@ -115,6 +121,10 @@ export declare class HelixHeadlessPaginationSize extends HelixElement {
      * after it, and a refused size still sent it.
      */
     private readonly stopNative;
+    /** Returns to the size the markup declared, as a native `<select>` does on a reset. */
+    formResetCallback(): void;
+    /** Takes back the size a browser restores with the form, or the declared one. */
+    formStateRestoreCallback(state: string | File | FormData | null): void;
     protected willUpdate(changed: PropertyValues): void;
     /**
      * The control itself, which is the whole of this part, behind a seam the styled tier can move.

package/dist/pagination/size/pagination-size.js

@@ -4,13 +4,13 @@ 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, formatNumbers, HelixBeforeChangeEvent, HelixElement, requestChange, } from '@fusion.dev/helix-core';
+import { customElement, formatNumbers, HelixBeforeChangeEvent, HelixFormElement, requestChange, } from '@fusion.dev/helix-core';
 import { nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { html } from 'lit/static-html.js';
 import '../../option/index.js';
 import '../../select/index.js';
-let HelixHeadlessPaginationSize = class HelixHeadlessPaginationSize extends HelixElement {
+let HelixHeadlessPaginationSize = class HelixHeadlessPaginationSize extends HelixFormElement {
     constructor() {
         super(...arguments);
         this.defaultValue = 0;
@@ -29,8 +29,8 @@ let HelixHeadlessPaginationSize = class HelixHeadlessPaginationSize extends Heli
                     const previous = this.value;
                     this.valueState = size;
                     this.requestUpdate('value', previous);
-                    this.dispatchEvent(new Event('input', { bubbles: true, composed: true }));
-                    this.dispatchEvent(new Event('change', { bubbles: true, composed: false }));
+                    this.announceInput();
+                    this.announceChange();
                 },
                 event: (size) => new HelixBeforeChangeEvent({ value: String(size) }),
                 host: this,
@@ -68,9 +68,23 @@ let HelixHeadlessPaginationSize = class HelixHeadlessPaginationSize extends Heli
         const options = this.options;
         return options.includes(this.value) ? this.value : (options[0] ?? 0);
     }
+    formResetCallback() {
+        super.formResetCallback();
+        const previous = this.value;
+        this.valueState = undefined;
+        this.requestUpdate('value', previous);
+    }
+    formStateRestoreCallback(state) {
+        const size = typeof state === 'string' ? Number.parseInt(state, 10) : Number.NaN;
+        const previous = this.value;
+        this.valueState = Number.isFinite(size) && size > 0 ? size : undefined;
+        this.requestUpdate('value', previous);
+    }
     willUpdate(changed) {
         super.willUpdate(changed);
         this.toggleState('empty', this.options.length === 0);
+        const current = this.current;
+        this.internals.setFormValue(current > 0 ? String(current) : null);
     }
     renderSelect() {
         const select = this.tag('select');
@@ -79,13 +93,14 @@ let HelixHeadlessPaginationSize = class HelixHeadlessPaginationSize extends Heli
       part="control"
       exportparts="feedback: control-feedback, hint: control-hint, indicator: control-indicator,
         label: control-label, listbox: control-listbox, listbox-empty: control-listbox-empty,
-        listbox-feedback: control-listbox-feedback, listbox-filter-icon: control-listbox-filter-icon,
+        listbox-error: control-listbox-error, listbox-feedback: control-listbox-feedback, listbox-filter-icon: control-listbox-filter-icon,
         listbox-filter-mark: control-listbox-filter-mark, listbox-hint: control-listbox-hint,
         listbox-items: control-listbox-items, listbox-label: control-listbox-label,
         listbox-live: control-listbox-live, listbox-loading: control-listbox-loading, listbox-search: control-listbox-search,
         listbox-search-field: control-listbox-search-field, surface: control-surface,
         trigger: control-trigger, value: control-value"
       label=${this.label}
+      ?disabled=${this.isDisabled}
       .value=${String(this.current)}
       @helix-before-change=${this.handleChange}
       @input=${this.stopNative}

package/dist/pin-input/code.d.ts

@@ -0,0 +1,10 @@
+import type { PinCase, PinType } from './root/pin-input-root.js';
+/**
+ * Typed or pasted text as the code's characters: trimmed, with what `type`
+ * refuses dropped, and its letters cased as `letterCase` asks. Web Awesome's
+ * OTP input takes the same `case`.
+ *
+ * `numeric` keeps digits, `alphanumeric` keeps ASCII letters and digits, and
+ * `text` keeps everything.
+ */
+export declare const cleanCode: (text: string, type: PinType, letterCase?: PinCase) => string;

package/dist/pin-input/code.js

@@ -0,0 +1,13 @@
+export const cleanCode = (text, type, letterCase = 'preserve') => {
+    const trimmed = text.trim();
+    const kept = type === 'numeric'
+        ? trimmed.replace(/\D/g, '')
+        : type === 'alphanumeric'
+            ? trimmed.replace(/[^0-9A-Za-z]/g, '')
+            : trimmed;
+    return letterCase === 'upper'
+        ? kept.toUpperCase()
+        : letterCase === 'lower'
+            ? kept.toLowerCase()
+            : kept;
+};