@lilydesignsystem/angular-headless 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lilydesignsystem/angular-headless",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "engines": {
     "node": "=26"
   },

package/types/lilydesignsystem-angular-headless.d.ts

@@ -3613,16 +3613,53 @@ declare class Icon {
  * 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.
  */
 declare 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). */
     readonly label: _angular_core.InputSignal<string>;
-    /** Extra CSS classes appended to the base class. */
+    /** Extra CSS classes appended after the base class. */
     readonly className: _angular_core.InputSignal<string>;
+    /** Base class token, replacing `"icon-button"` outright (not appended). */
+    readonly baseClass: _angular_core.InputSignal<string>;
+    readonly ariaHaspopup: _angular_core.InputSignal<string>;
+    readonly ariaExpanded: _angular_core.InputSignal<boolean | null>;
+    readonly ariaControls: _angular_core.InputSignal<string>;
+    readonly disabled: _angular_core.InputSignal<boolean>;
+    private rootRef?;
+    protected readonly ariaExpandedAttr: _angular_core.Signal<string | null>;
+    /** Focus the real rendered `<button>`. */
+    focus(options?: FocusOptions): void;
+    /**
+     * 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(): HTMLButtonElement | undefined;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<IconButton, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IconButton, "lily-icon-button", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IconButton, "lily-icon-button", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; "baseClass": { "alias": "baseClass"; "required": false; "isSignal": true; }; "ariaHaspopup": { "alias": "ariaHaspopup"; "required": false; "isSignal": true; }; "ariaExpanded": { "alias": "ariaExpanded"; "required": false; "isSignal": true; }; "ariaControls": { "alias": "ariaControls"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
 }
 
 /**
@@ -4306,18 +4343,70 @@ declare class LineChart {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<LineChart, "lily-line-chart", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
 }
 
+/** Navigation/focus model. Default `"roving-focus"` — currently inert (no keyboard handling), matching this component's pre-extension behaviour: nothing consumed it, so there was nothing to preserve beyond "does nothing." */
+type ListboxNavigation = "roving-focus" | "active-descendant";
 /**
  * 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).
  */
 declare class Listbox {
     readonly label: _angular_core.InputSignal<string>;
     readonly className: _angular_core.InputSignal<string>;
+    /** Base class token, replacing `"listbox"` outright (not appended). */
+    readonly baseClass: _angular_core.InputSignal<string>;
+    /** `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. */
+    readonly elementId: _angular_core.InputSignal<string>;
+    /** 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. */
+    readonly hidden: _angular_core.InputSignal<boolean>;
+    readonly navigation: _angular_core.InputSignal<ListboxNavigation>;
+    /** Arrow keys clamp instead of wrap (active-descendant mode only). */
+    readonly clamp: _angular_core.InputSignal<boolean>;
+    /** Printable-character typeahead (active-descendant mode only). */
+    readonly typeahead: _angular_core.InputSignal<boolean>;
+    /** PageUp/PageDown step size (active-descendant mode only). */
+    readonly pageSize: _angular_core.InputSignal<number>;
+    /** Virtual cursor position. Two-way bindable via `[(activeIndex)]`. -1 = none. */
+    readonly activeIndex: _angular_core.ModelSignal<number>;
+    /** Enter/Space on the active option (active-descendant mode only). */
+    readonly activate: _angular_core.OutputEmitterRef<number>;
+    /** Escape pressed (active-descendant mode only). */
+    readonly escape: _angular_core.OutputEmitterRef<void>;
+    /** 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). */
+    readonly tabOut: _angular_core.OutputEmitterRef<KeyboardEvent>;
+    private rootRef?;
+    private typeaheadBuffer;
+    private typeaheadTimer?;
+    private options;
+    protected readonly activeId: _angular_core.Signal<string | null>;
+    /** Focus the root (active-descendant mode: the listbox itself holds focus). */
+    focus(options?: FocusOptions): void;
+    private moveActive;
+    private runTypeahead;
+    protected onKeydown(event: KeyboardEvent): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<Listbox, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<Listbox, "lily-listbox", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<Listbox, "lily-listbox", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; "baseClass": { "alias": "baseClass"; "required": false; "isSignal": true; }; "elementId": { "alias": "elementId"; "required": false; "isSignal": true; }; "hidden": { "alias": "hidden"; "required": false; "isSignal": true; }; "navigation": { "alias": "navigation"; "required": false; "isSignal": true; }; "clamp": { "alias": "clamp"; "required": false; "isSignal": true; }; "typeahead": { "alias": "typeahead"; "required": false; "isSignal": true; }; "pageSize": { "alias": "pageSize"; "required": false; "isSignal": true; }; "activeIndex": { "alias": "activeIndex"; "required": false; "isSignal": true; }; }, { "activeIndex": "activeIndexChange"; "activate": "activate"; "escape": "escape"; "tabOut": "tabOut"; }, never, ["*"], true, never>;
 }
 
 /**