@lilydesignsystem/angular-headless 0.1.0 → 0.2.0

package/fesm2022/lilydesignsystem-angular-headless.mjs

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { input, ChangeDetectionStrategy, Component, model } from '@angular/core';
+import { input, ChangeDetectionStrategy, Component, model, computed, ViewChild, output } from '@angular/core';
 
 /**
  * AccordionCheckbox — a checkbox option that reveals an accordion panel when checked
@@ -6793,28 +6793,100 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.4", ngImpor
  * IconButton — a button containing only an icon with a required accessible label
  *
  * Headless Angular component. Renders the semantic HTML root with the
- * kebab-case class hook `icon-button` and the consumer-provided `className`.
- * Ships zero CSS; the consumer styles via the class hook.
+ * kebab-case class hook `icon-button` (or `baseClass`) and the consumer-
+ * provided `className`. Ships zero CSS; the consumer styles via the class
+ * hook.
+ *
+ * The `lily-icon-button` selector tag itself is `display: contents`
+ * unconditionally, on every usage — it is a semantics-free structural
+ * wrapper (Angular's component selector always emits a real host element;
+ * there is no Svelte-`<svelte:element>`/no-wrapper-root equivalent), so it
+ * must never participate in layout or box generation. This is the same
+ * "structurally required inline style" exception documented in
+ * spec/headless/index.md for `ThemeProvider`, applied here for the same
+ * reason: composing `<lily-icon-button>` inside a consumer's own template
+ * (e.g. a `*-picker` component) must not insert a visible extra box
+ * between the picker's root and its real `<button>`.
+ *
+ * `baseClass`, `ariaHaspopup`/`ariaExpanded`/`ariaControls`, and `focus()`
+ * exist specifically so a composing consumer can reproduce an exact
+ * `class="{helper}-button" aria-haspopup aria-expanded aria-controls`
+ * contract and call `.focus()` on the real button — Angular has no
+ * generic spread-onto-inputs mechanism (see picker-bar's own contract
+ * note), so these are named inputs rather than a rest-prop spread.
  */
 class IconButton {
-    /** Optional aria-label override. */
+    /** Accessible label (REQUIRED for icon-only buttons in practice; enforced by convention, not the type system, to match the button's own required aria-label contract). */
     label = input("", /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "label" }] : /* istanbul ignore next */ []));
-    /** Extra CSS classes appended to the base class. */
+    /** Extra CSS classes appended after the base class. */
     className = input("", /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "className" }] : /* istanbul ignore next */ []));
+    /** Base class token, replacing `"icon-button"` outright (not appended). */
+    baseClass = input("icon-button", /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "baseClass" }] : /* istanbul ignore next */ []));
+    ariaHaspopup = input("", /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "ariaHaspopup" }] : /* istanbul ignore next */ []));
+    ariaExpanded = input(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "ariaExpanded" }] : /* istanbul ignore next */ []));
+    ariaControls = input("", /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "ariaControls" }] : /* istanbul ignore next */ []));
+    disabled = input(false, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "disabled" }] : /* istanbul ignore next */ []));
+    rootRef;
+    ariaExpandedAttr = computed(() => {
+        const v = this.ariaExpanded();
+        return v === null ? null : String(v);
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "ariaExpandedAttr" }] : /* istanbul ignore next */ []));
+    /** Focus the real rendered `<button>`. */
+    focus(options) {
+        this.rootRef?.nativeElement.focus(options);
+    }
+    /**
+     * The real rendered `<button>` element. `focus()` covers the common
+     * case; this exists for a consumer that needs the raw node itself —
+     * e.g. remembering it as a focus-restoration target, or an
+     * `instanceof HTMLElement` / `.contains()` check — where a behaviour
+     * method alone isn't enough.
+     */
+    get element() {
+        return this.rootRef?.nativeElement;
+    }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: IconButton, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.1.0", version: "22.1.4", type: IconButton, isStandalone: true, selector: "lily-icon-button", inputs: { label: { classPropertyName: "label", publicName: "label", isSignal: true, isRequired: false, transformFunction: null }, className: { classPropertyName: "className", publicName: "className", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0, template: `<button class="icon-button {{ className() }}" type="button" [attr.aria-label]="label() || null"><ng-content /></button>`, isInline: true, changeDetection: i0.ChangeDetectionStrategy.OnPush });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.1.0", version: "22.1.4", type: IconButton, isStandalone: true, selector: "lily-icon-button", inputs: { label: { classPropertyName: "label", publicName: "label", isSignal: true, isRequired: false, transformFunction: null }, className: { classPropertyName: "className", publicName: "className", isSignal: true, isRequired: false, transformFunction: null }, baseClass: { classPropertyName: "baseClass", publicName: "baseClass", isSignal: true, isRequired: false, transformFunction: null }, ariaHaspopup: { classPropertyName: "ariaHaspopup", publicName: "ariaHaspopup", isSignal: true, isRequired: false, transformFunction: null }, ariaExpanded: { classPropertyName: "ariaExpanded", publicName: "ariaExpanded", isSignal: true, isRequired: false, transformFunction: null }, ariaControls: { classPropertyName: "ariaControls", publicName: "ariaControls", isSignal: true, isRequired: false, transformFunction: null }, disabled: { classPropertyName: "disabled", publicName: "disabled", isSignal: true, isRequired: false, transformFunction: null } }, host: { styleAttribute: "display: contents" }, viewQueries: [{ propertyName: "rootRef", first: true, predicate: ["root"], descendants: true }], ngImport: i0, template: `<button
+    #root
+    class="{{ baseClass() }} {{ className() }}"
+    type="button"
+    [attr.aria-label]="label() || null"
+    [attr.aria-haspopup]="ariaHaspopup() || null"
+    [attr.aria-expanded]="ariaExpandedAttr()"
+    [attr.aria-controls]="ariaControls() || null"
+    [disabled]="disabled()"
+  ><ng-content /></button>`, isInline: true, changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: IconButton, decorators: [{
             type: Component,
             args: [{
                     selector: "lily-icon-button",
                     standalone: true,
-                    template: `<button class="icon-button {{ className() }}" type="button" [attr.aria-label]="label() || null"><ng-content /></button>`,
+                    template: `<button
+    #root
+    class="{{ baseClass() }} {{ className() }}"
+    type="button"
+    [attr.aria-label]="label() || null"
+    [attr.aria-haspopup]="ariaHaspopup() || null"
+    [attr.aria-expanded]="ariaExpandedAttr()"
+    [attr.aria-controls]="ariaControls() || null"
+    [disabled]="disabled()"
+  ><ng-content /></button>`,
+                    host: { style: "display: contents" },
                     changeDetection: ChangeDetectionStrategy.OnPush,
                 }]
-        }], propDecorators: { label: [{ type: i0.Input, args: [{ isSignal: true, alias: "label", required: false }] }], className: [{ type: i0.Input, args: [{ isSignal: true, alias: "className", required: false }] }] } });
+        }], propDecorators: { label: [{ type: i0.Input, args: [{ isSignal: true, alias: "label", required: false }] }], className: [{ type: i0.Input, args: [{ isSignal: true, alias: "className", required: false }] }], baseClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "baseClass", required: false }] }], ariaHaspopup: [{ type: i0.Input, args: [{ isSignal: true, alias: "ariaHaspopup", required: false }] }], ariaExpanded: [{ type: i0.Input, args: [{ isSignal: true, alias: "ariaExpanded", required: false }] }], ariaControls: [{ type: i0.Input, args: [{ isSignal: true, alias: "ariaControls", required: false }] }], disabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "disabled", required: false }] }], rootRef: [{
+                type: ViewChild,
+                args: ["root"]
+            }] } });
 
 /**
  * IconList — an ordered list of icon list item components
@@ -8173,26 +8245,197 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.4", ngImpor
  * Listbox — a list of selectable options with keyboard navigation
  *
  * Headless Angular component. Renders the semantic HTML root with the
- * kebab-case class hook `listbox` and the consumer-provided `className`.
- * Ships zero CSS; the consumer styles via the class hook.
+ * kebab-case class hook `listbox` (or `baseClass`) and the consumer-
+ * provided `className`. Ships zero CSS; the consumer styles via the class
+ * hook.
+ *
+ * `navigation="active-descendant"` (opt-in; default `"roving-focus"` is
+ * unchanged) implements the full WAI-ARIA APG listbox keyboard contract
+ * via a virtual cursor: the root itself holds focus and tracks
+ * `activeIndex` (a two-way `model()`, this catalog's established
+ * bindable-state idiom — see `picker-bar`'s own contract note), mirrored
+ * to `aria-activedescendant`. `clamp` (vs. wrap), `typeahead`, `pageSize`
+ * paging, and `activate`/`escape`/`tabOut` outputs let a composing
+ * consumer (e.g. a `*-picker` component) decide what "select" / "cancel"
+ * / "leave" mean, the same division of responsibility as the Svelte
+ * version this was ported from.
+ *
+ * Like `IconButton`, the `lily-listbox` selector tag itself is
+ * `display: contents` unconditionally — a semantics-free structural
+ * wrapper around the real `role="listbox"` element, so composing it
+ * inside another component's template inserts no extra layout box. See
+ * `IconButton`'s doc comment for the full `display: contents` reasoning
+ * (mirrors the `ThemeProvider` precedent in spec/headless/index.md).
  */
 class Listbox {
     label = input("", /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "label" }] : /* istanbul ignore next */ []));
     className = input("", /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "className" }] : /* istanbul ignore next */ []));
+    /** Base class token, replacing `"listbox"` outright (not appended). */
+    baseClass = input("listbox", /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "baseClass" }] : /* istanbul ignore next */ []));
+    /** `id` for the real inner `role="listbox"` element — named `elementId`, not `id`, because the host tag's own native `id` attribute (set directly on `<lily-listbox id="...">` by a consumer) is a separate, unrelated thing once `display: contents` puts a real wrapper element between the host and the inner listbox. Needed so a composing consumer's `aria-controls`/`document.getElementById` can reach the real element. */
+    elementId = input("", /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "elementId" }] : /* istanbul ignore next */ []));
+    /** Sets `hidden` on the real inner element. Angular has no generic spread-onto-inputs mechanism (see `IconButton`'s doc comment), so this is a named input rather than a rest-prop spread. */
+    hidden = input(false, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "hidden" }] : /* istanbul ignore next */ []));
+    navigation = input("roving-focus", /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "navigation" }] : /* istanbul ignore next */ []));
+    /** Arrow keys clamp instead of wrap (active-descendant mode only). */
+    clamp = input(false, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "clamp" }] : /* istanbul ignore next */ []));
+    /** Printable-character typeahead (active-descendant mode only). */
+    typeahead = input(false, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "typeahead" }] : /* istanbul ignore next */ []));
+    /** PageUp/PageDown step size (active-descendant mode only). */
+    pageSize = input(10, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "pageSize" }] : /* istanbul ignore next */ []));
+    /** Virtual cursor position. Two-way bindable via `[(activeIndex)]`. -1 = none. */
+    activeIndex = model(-1, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "activeIndex" }] : /* istanbul ignore next */ []));
+    /** Enter/Space on the active option (active-descendant mode only). */
+    activate = output();
+    /** Escape pressed (active-descendant mode only). */
+    escape = output();
+    /** Tab pressed, emitted before the key is processed — never prevented, so the consumer can move focus first (e.g. to a trigger button) before the browser's default Tab computes its target (active-descendant mode only). */
+    tabOut = output();
+    rootRef;
+    typeaheadBuffer = "";
+    typeaheadTimer;
+    options() {
+        return this.rootRef
+            ? Array.from(this.rootRef.nativeElement.querySelectorAll("[role='option']"))
+            : [];
+    }
+    activeId = computed(() => {
+        if (this.navigation() !== "active-descendant")
+            return null;
+        const i = this.activeIndex();
+        if (i < 0)
+            return null;
+        return this.options()[i]?.id || null;
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "activeId" }] : /* istanbul ignore next */ []));
+    /** Focus the root (active-descendant mode: the listbox itself holds focus). */
+    focus(options) {
+        this.rootRef?.nativeElement.focus(options);
+    }
+    moveActive(delta) {
+        const count = this.options().length;
+        if (count === 0)
+            return;
+        const next = this.activeIndex() + delta;
+        this.activeIndex.set(this.clamp() ? Math.min(Math.max(next, 0), count - 1) : ((next % count) + count) % count);
+    }
+    runTypeahead(char) {
+        const opts = this.options();
+        if (opts.length === 0)
+            return;
+        const lower = char.toLowerCase();
+        const sameCharRun = this.typeaheadBuffer === "" || [...this.typeaheadBuffer].every((c) => c === lower);
+        this.typeaheadBuffer += lower;
+        clearTimeout(this.typeaheadTimer);
+        this.typeaheadTimer = setTimeout(() => (this.typeaheadBuffer = ""), 500);
+        const query = sameCharRun ? lower : this.typeaheadBuffer;
+        const anchor = this.activeIndex() < 0 ? 0 : this.activeIndex();
+        const start = sameCharRun ? anchor + 1 : anchor;
+        for (let n = 0; n < opts.length; n++) {
+            const i = (start + n) % opts.length;
+            if ((opts[i].textContent ?? "").trim().toLowerCase().startsWith(query)) {
+                this.activeIndex.set(i);
+                return;
+            }
+        }
+    }
+    onKeydown(event) {
+        if (this.navigation() !== "active-descendant")
+            return;
+        switch (event.key) {
+            case "ArrowDown":
+                event.preventDefault();
+                this.moveActive(1);
+                break;
+            case "ArrowUp":
+                event.preventDefault();
+                this.moveActive(-1);
+                break;
+            case "Home":
+                event.preventDefault();
+                this.activeIndex.set(this.options().length ? 0 : -1);
+                break;
+            case "End":
+                event.preventDefault();
+                this.activeIndex.set(this.options().length - 1);
+                break;
+            case "PageDown":
+                event.preventDefault();
+                this.moveActive(this.pageSize());
+                break;
+            case "PageUp":
+                event.preventDefault();
+                this.moveActive(-this.pageSize());
+                break;
+            case "Enter":
+            case " ":
+                event.preventDefault();
+                if (this.activeIndex() >= 0)
+                    this.activate.emit(this.activeIndex());
+                break;
+            case "Escape":
+                event.preventDefault();
+                this.escape.emit();
+                break;
+            case "Tab":
+                this.tabOut.emit(event);
+                break;
+            default:
+                if (this.typeahead() &&
+                    event.key.length === 1 &&
+                    !event.ctrlKey &&
+                    !event.metaKey &&
+                    !event.altKey) {
+                    this.runTypeahead(event.key);
+                }
+        }
+    }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: Listbox, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.1.0", version: "22.1.4", type: Listbox, isStandalone: true, selector: "lily-listbox", inputs: { label: { classPropertyName: "label", publicName: "label", isSignal: true, isRequired: false, transformFunction: null }, className: { classPropertyName: "className", publicName: "className", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0, template: `<div class="listbox {{ className() }}" [attr.aria-label]="label() || null"><ng-content /></div>`, isInline: true, changeDetection: i0.ChangeDetectionStrategy.OnPush });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.1.0", version: "22.1.4", type: Listbox, isStandalone: true, selector: "lily-listbox", inputs: { label: { classPropertyName: "label", publicName: "label", isSignal: true, isRequired: false, transformFunction: null }, className: { classPropertyName: "className", publicName: "className", isSignal: true, isRequired: false, transformFunction: null }, baseClass: { classPropertyName: "baseClass", publicName: "baseClass", isSignal: true, isRequired: false, transformFunction: null }, elementId: { classPropertyName: "elementId", publicName: "elementId", isSignal: true, isRequired: false, transformFunction: null }, hidden: { classPropertyName: "hidden", publicName: "hidden", isSignal: true, isRequired: false, transformFunction: null }, navigation: { classPropertyName: "navigation", publicName: "navigation", isSignal: true, isRequired: false, transformFunction: null }, clamp: { classPropertyName: "clamp", publicName: "clamp", isSignal: true, isRequired: false, transformFunction: null }, typeahead: { classPropertyName: "typeahead", publicName: "typeahead", isSignal: true, isRequired: false, transformFunction: null }, pageSize: { classPropertyName: "pageSize", publicName: "pageSize", isSignal: true, isRequired: false, transformFunction: null }, activeIndex: { classPropertyName: "activeIndex", publicName: "activeIndex", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { activeIndex: "activeIndexChange", activate: "activate", escape: "escape", tabOut: "tabOut" }, host: { styleAttribute: "display: contents" }, viewQueries: [{ propertyName: "rootRef", first: true, predicate: ["root"], descendants: true }], ngImport: i0, template: `<div
+    #root
+    [id]="elementId() || null"
+    class="{{ baseClass() }} {{ className() }}"
+    role="listbox"
+    [attr.aria-label]="label() || null"
+    [attr.tabindex]="navigation() === 'active-descendant' ? -1 : null"
+    [attr.aria-activedescendant]="activeId()"
+    [attr.hidden]="hidden() ? '' : null"
+    (keydown)="onKeydown($event)"
+  ><ng-content /></div>`, isInline: true, changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: Listbox, decorators: [{
             type: Component,
             args: [{
                     selector: "lily-listbox",
                     standalone: true,
-                    template: `<div class="listbox {{ className() }}" [attr.aria-label]="label() || null"><ng-content /></div>`,
-                    changeDetection: ChangeDetectionStrategy.OnPush,
-                }]
-        }], propDecorators: { label: [{ type: i0.Input, args: [{ isSignal: true, alias: "label", required: false }] }], className: [{ type: i0.Input, args: [{ isSignal: true, alias: "className", required: false }] }] } });
+                    template: `<div
+    #root
+    [id]="elementId() || null"
+    class="{{ baseClass() }} {{ className() }}"
+    role="listbox"
+    [attr.aria-label]="label() || null"
+    [attr.tabindex]="navigation() === 'active-descendant' ? -1 : null"
+    [attr.aria-activedescendant]="activeId()"
+    [attr.hidden]="hidden() ? '' : null"
+    (keydown)="onKeydown($event)"
+  ><ng-content /></div>`,
+                    host: { style: "display: contents" },
+                    changeDetection: ChangeDetectionStrategy.OnPush,
+                }]
+        }], propDecorators: { label: [{ type: i0.Input, args: [{ isSignal: true, alias: "label", required: false }] }], className: [{ type: i0.Input, args: [{ isSignal: true, alias: "className", required: false }] }], baseClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "baseClass", required: false }] }], elementId: [{ type: i0.Input, args: [{ isSignal: true, alias: "elementId", required: false }] }], hidden: [{ type: i0.Input, args: [{ isSignal: true, alias: "hidden", required: false }] }], navigation: [{ type: i0.Input, args: [{ isSignal: true, alias: "navigation", required: false }] }], clamp: [{ type: i0.Input, args: [{ isSignal: true, alias: "clamp", required: false }] }], typeahead: [{ type: i0.Input, args: [{ isSignal: true, alias: "typeahead", required: false }] }], pageSize: [{ type: i0.Input, args: [{ isSignal: true, alias: "pageSize", required: false }] }], activeIndex: [{ type: i0.Input, args: [{ isSignal: true, alias: "activeIndex", required: false }] }, { type: i0.Output, args: ["activeIndexChange"] }], activate: [{ type: i0.Output, args: ["activate"] }], escape: [{ type: i0.Output, args: ["escape"] }], tabOut: [{ type: i0.Output, args: ["tabOut"] }], rootRef: [{
+                type: ViewChild,
+                args: ["root"]
+            }] } });
 
 /**
  * Loading — a loading indicator, such as text, or image, or animation