@aceshooting/lyra-ui 1.2.0 → 2.1.0

package/dist/components/tree/tree.d.ts

@@ -35,15 +35,18 @@ export declare class LyraTree extends LyraElement {
     private get nodeElements();
     private childrenOf;
     /**
-     * Memoized result of the last `visibleNodeElements()` walk. Every keydown
-     * (ArrowUp/Down/Home/End especially) reads the full visible-node list, and
-     * rebuilding it means a `shadowRoot.querySelectorAll` per currently-expanded
-     * node -- invalidated below on the only two things that can change which
-     * nodes are visible: a `data` reassignment, or a node expanding/collapsing.
+     * Every currently *visible* (ancestor-expanded) node, top-to-bottom.
+     *
+     * Recomputed on every call rather than memoized: `item`/`expanded` are
+     * plain public settable properties on `<lyra-tree-node>` (not just
+     * reachable through this class's own `data` setter or the bubbling
+     * `lyra-node-toggle` event), so a cache keyed off those two entry points
+     * alone would go stale the moment a caller mutated a node directly --
+     * e.g. `node.item = { ...node.item, children: [...] }` to append a child
+     * in place. This walk only runs from user-paced `keydown` handling (never
+     * a hot render-loop path), so the cost of a `shadowRoot.querySelectorAll`
+     * per currently-expanded node is not worth trading for that staleness risk.
      */
-    private cachedVisible;
-    private invalidateVisibleCache;
-    /** Every currently *visible* (ancestor-expanded) node, top-to-bottom. */
     private visibleNodeElements;
     private findItem;
     protected willUpdate(changed: PropertyValues): void;
@@ -94,8 +97,20 @@ export declare class LyraTree extends LyraElement {
      */
     protected getUpdateComplete(): Promise<boolean>;
     private onTreeKeyDown;
-    /** Expand every node in the tree, recursively. */
-    expandAll(): void;
+    /**
+     * Expand every node in the tree, recursively. Resolves once every
+     * descendant has actually finished expanding (not just had `expanded` set)
+     * -- callers that immediately read `visibleNodeElements()`-derived state
+     * (or call `collapseAll()` right after) should `await` this instead of
+     * firing it and moving on.
+     *
+     * Guarded on `n.hasChildren`, matching `expand()`'s own invariant -- a leaf
+     * node's `expanded` must never be set to `true`, since `collapse()` (and
+     * this method's own counterpart, `collapseAll()`) refuse to act on a node
+     * that's `!hasChildren`, which would otherwise leave the leaf permanently
+     * stuck with a reflected `expanded` attribute nothing can clear.
+     */
+    expandAll(): Promise<void>;
     /**
      * Collapse every node in the tree, recursively. Goes through each node's
      * own `collapse()` (rather than assigning `expanded` directly) so its

package/dist/components/tree/tree.js

@@ -7,7 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { LyraElement } from '../../internal/lyra-element.js';
-import { defineElement } from '../../internal/prefix.js';
+import { defineElement, tag } from '../../internal/prefix.js';
 import { isRtl } from '../../internal/rtl.js';
 import { styles } from './tree.styles.js';
 import { cascadeUpdateComplete } from './update-cascade.js';
@@ -38,14 +38,6 @@ export class LyraTree extends LyraElement {
         this.activeId = null;
         /** Set by `willUpdate()` when a `data` reassignment removes the node that currently holds real DOM focus; consumed by `updated()` to refocus the newly-designated `activeId` node once it's actually focusable. */
         this.pendingFocusId = null;
-        /**
-         * Memoized result of the last `visibleNodeElements()` walk. Every keydown
-         * (ArrowUp/Down/Home/End especially) reads the full visible-node list, and
-         * rebuilding it means a `shadowRoot.querySelectorAll` per currently-expanded
-         * node -- invalidated below on the only two things that can change which
-         * nodes are visible: a `data` reassignment, or a node expanding/collapsing.
-         */
-        this.cachedVisible = null;
         /**
          * A mouse click always lands directly on the node it interacts with --
          * `select()`/`expand()`/`collapse()` all emit their own node's id --
@@ -62,8 +54,6 @@ export class LyraTree extends LyraElement {
          * same-value, no-op assignment for them.
          */
         this.onNodeActivate = (e) => {
-            if (e.type === 'lyra-node-toggle')
-                this.invalidateVisibleCache();
             this.activeId = e.detail.id;
         };
         this.onTreeKeyDown = (e) => {
@@ -133,18 +123,25 @@ export class LyraTree extends LyraElement {
     }
     static { this.styles = [LyraElement.styles, styles]; }
     get nodeElements() {
-        return [...this.querySelectorAll('lyra-tree-node')];
+        return [...this.querySelectorAll(tag('tree-node'))];
     }
     childrenOf(node) {
-        return [...(node.shadowRoot?.querySelectorAll('lyra-tree-node') ?? [])];
+        return [...(node.shadowRoot?.querySelectorAll(tag('tree-node')) ?? [])];
     }
-    invalidateVisibleCache() {
-        this.cachedVisible = null;
-    }
-    /** Every currently *visible* (ancestor-expanded) node, top-to-bottom. */
+    /**
+     * Every currently *visible* (ancestor-expanded) node, top-to-bottom.
+     *
+     * Recomputed on every call rather than memoized: `item`/`expanded` are
+     * plain public settable properties on `<lyra-tree-node>` (not just
+     * reachable through this class's own `data` setter or the bubbling
+     * `lyra-node-toggle` event), so a cache keyed off those two entry points
+     * alone would go stale the moment a caller mutated a node directly --
+     * e.g. `node.item = { ...node.item, children: [...] }` to append a child
+     * in place. This walk only runs from user-paced `keydown` handling (never
+     * a hot render-loop path), so the cost of a `shadowRoot.querySelectorAll`
+     * per currently-expanded node is not worth trading for that staleness risk.
+     */
     visibleNodeElements() {
-        if (this.cachedVisible)
-            return this.cachedVisible;
         const acc = [];
         const walk = (nodes) => {
             for (const n of nodes) {
@@ -154,7 +151,6 @@ export class LyraTree extends LyraElement {
             }
         };
         walk(this.nodeElements);
-        this.cachedVisible = acc;
         return acc;
     }
     findItem(items, id) {
@@ -169,7 +165,6 @@ export class LyraTree extends LyraElement {
     }
     willUpdate(changed) {
         if (changed.has('data')) {
-            this.invalidateVisibleCache();
             // `document.activeElement` collapses to the outermost light-DOM node
             // even when the real focus target is a nested descendant several
             // shadow roots down, so this also catches a focused nested node whose
@@ -206,7 +201,7 @@ export class LyraTree extends LyraElement {
         let previousSibling = null;
         for (const item of this.data) {
             const reused = !seen.has(item.id) ? existingById.get(item.id) : undefined;
-            const node = reused ?? document.createElement('lyra-tree-node');
+            const node = reused ?? document.createElement(tag('tree-node'));
             node.item = item;
             node.depth = 0;
             seen.add(item.id);
@@ -263,16 +258,29 @@ export class LyraTree extends LyraElement {
         }
         return result;
     }
-    /** Expand every node in the tree, recursively. */
-    expandAll() {
-        const setAll = (nodes) => {
-            for (const n of nodes) {
-                n.expanded = true;
-                this.invalidateVisibleCache();
-                void n.updateComplete.then(() => setAll(this.childrenOf(n)));
-            }
+    /**
+     * Expand every node in the tree, recursively. Resolves once every
+     * descendant has actually finished expanding (not just had `expanded` set)
+     * -- callers that immediately read `visibleNodeElements()`-derived state
+     * (or call `collapseAll()` right after) should `await` this instead of
+     * firing it and moving on.
+     *
+     * Guarded on `n.hasChildren`, matching `expand()`'s own invariant -- a leaf
+     * node's `expanded` must never be set to `true`, since `collapse()` (and
+     * this method's own counterpart, `collapseAll()`) refuse to act on a node
+     * that's `!hasChildren`, which would otherwise leave the leaf permanently
+     * stuck with a reflected `expanded` attribute nothing can clear.
+     */
+    async expandAll() {
+        const setAll = async (nodes) => {
+            await Promise.all(nodes.map(async (n) => {
+                if (n.hasChildren)
+                    n.expanded = true;
+                await n.updateComplete;
+                await setAll(this.childrenOf(n));
+            }));
         };
-        setAll(this.nodeElements);
+        await setAll(this.nodeElements);
     }
     /**
      * Collapse every node in the tree, recursively. Goes through each node's

package/dist/components/typing-indicator/typing-indicator.d.ts

@@ -0,0 +1,70 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+export type TypingIndicatorVariant = 'dots' | 'pulse' | 'cursor';
+export type TypingIndicatorSize = 'sm' | 'md';
+/**
+ * `<lyra-typing-indicator>` — a purely presentational "assistant is
+ * responding" presence cue. No events, no interactivity: a consumer mounts
+ * it while a response is being generated and removes it (or hides it) once
+ * real content has arrived.
+ *
+ * Three visual variants share one component rather than three separate tags
+ * because callers pick between them along a single axis — how the
+ * surrounding surface wants the cue to read — and nothing else about the
+ * component differs:
+ * - `dots` (default) — three dots with a staggered bounce, the classic
+ *   "typing…" affordance for a standalone status line.
+ * - `pulse` — a single breathing dot, a quieter cue for a tighter space
+ *   (e.g. next to an avatar).
+ * - `cursor` — a blinking vertical bar, meant to sit inline at the tail end
+ *   of streamed text that is still being appended to.
+ *
+ * Accessibility: this indicator typically mounts and unmounts around a real
+ * generation lifecycle (appears when a response starts, disappears once one
+ * arrives) rather than emitting a stream of updates of its own, so it does
+ * *not* route through `<lyra-live-region>`/`Announcer`
+ * (`../../internal/announcer.js`) — that machinery exists to coalesce many
+ * rapidly-changing announcements into one, and there is only ever a single
+ * announcement here: the mount itself. A plain `role="status"` plus an
+ * accessible name derived from `label` is sufficient, set both as an
+ * `aria-label` on the host *and* as a visually-hidden text node in the
+ * shadow tree, so the name survives even if only one of the two is picked up
+ * by a given assistive-tech/browser pairing. An empty or whitespace-only
+ * `label` falls back to the default "Thinking…" copy in both places, rather
+ * than leaving the component with no accessible name at all. The animated dots/pulse/cursor
+ * shape is `aria-hidden="true"` — it's decorative; `label` is the entire
+ * accessible content, so nothing narrates individual animation frames.
+ *
+ * @customElement lyra-typing-indicator
+ * @csspart base - The decorative (`aria-hidden`) wrapper around the animated shape.
+ * @csspart dot - Each of the three dots in the `dots` variant.
+ * @csspart pulse - The single pulsing dot in the `pulse` variant.
+ * @csspart cursor - The blinking bar in the `cursor` variant.
+ */
+export declare class LyraTypingIndicator extends LyraElement {
+    static styles: import("lit").CSSResultGroup[];
+    /** Which decorative presentation to render. */
+    variant: TypingIndicatorVariant;
+    /** Accessible name, exposed via `role="status"`. Not re-announced on every
+     *  animation frame — only mount (and any later change to this property)
+     *  produces a new announcement. An empty or whitespace-only value falls
+     *  back to the default "Thinking…" copy (see `accessibleLabel`) so the
+     *  component never loses its accessible name. */
+    label: string;
+    /** Compact sizing for dense layouts (e.g. inline with a message bubble). */
+    size: TypingIndicatorSize;
+    /** The accessible name actually used, falling back to the default
+     *  "Thinking…" copy when `label` is set to an empty or whitespace-only
+     *  string -- otherwise both the `aria-label` and the sr-only text node
+     *  would go blank, leaving this purely-decorative component with no
+     *  accessible name at all. */
+    private get accessibleLabel();
+    protected willUpdate(changed: PropertyValues): void;
+    render(): TemplateResult;
+    private renderShape;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-typing-indicator': LyraTypingIndicator;
+    }
+}

package/dist/components/typing-indicator/typing-indicator.js

@@ -0,0 +1,108 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    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 { html } from 'lit';
+import { property } from 'lit/decorators.js';
+import { LyraElement } from '../../internal/lyra-element.js';
+import { defineElement } from '../../internal/prefix.js';
+import { srOnly } from '../../internal/a11y.js';
+import { styles } from './typing-indicator.styles.js';
+/**
+ * `<lyra-typing-indicator>` — a purely presentational "assistant is
+ * responding" presence cue. No events, no interactivity: a consumer mounts
+ * it while a response is being generated and removes it (or hides it) once
+ * real content has arrived.
+ *
+ * Three visual variants share one component rather than three separate tags
+ * because callers pick between them along a single axis — how the
+ * surrounding surface wants the cue to read — and nothing else about the
+ * component differs:
+ * - `dots` (default) — three dots with a staggered bounce, the classic
+ *   "typing…" affordance for a standalone status line.
+ * - `pulse` — a single breathing dot, a quieter cue for a tighter space
+ *   (e.g. next to an avatar).
+ * - `cursor` — a blinking vertical bar, meant to sit inline at the tail end
+ *   of streamed text that is still being appended to.
+ *
+ * Accessibility: this indicator typically mounts and unmounts around a real
+ * generation lifecycle (appears when a response starts, disappears once one
+ * arrives) rather than emitting a stream of updates of its own, so it does
+ * *not* route through `<lyra-live-region>`/`Announcer`
+ * (`../../internal/announcer.js`) — that machinery exists to coalesce many
+ * rapidly-changing announcements into one, and there is only ever a single
+ * announcement here: the mount itself. A plain `role="status"` plus an
+ * accessible name derived from `label` is sufficient, set both as an
+ * `aria-label` on the host *and* as a visually-hidden text node in the
+ * shadow tree, so the name survives even if only one of the two is picked up
+ * by a given assistive-tech/browser pairing. An empty or whitespace-only
+ * `label` falls back to the default "Thinking…" copy in both places, rather
+ * than leaving the component with no accessible name at all. The animated dots/pulse/cursor
+ * shape is `aria-hidden="true"` — it's decorative; `label` is the entire
+ * accessible content, so nothing narrates individual animation frames.
+ *
+ * @customElement lyra-typing-indicator
+ * @csspart base - The decorative (`aria-hidden`) wrapper around the animated shape.
+ * @csspart dot - Each of the three dots in the `dots` variant.
+ * @csspart pulse - The single pulsing dot in the `pulse` variant.
+ * @csspart cursor - The blinking bar in the `cursor` variant.
+ */
+export class LyraTypingIndicator extends LyraElement {
+    constructor() {
+        super(...arguments);
+        /** Which decorative presentation to render. */
+        this.variant = 'dots';
+        /** Accessible name, exposed via `role="status"`. Not re-announced on every
+         *  animation frame — only mount (and any later change to this property)
+         *  produces a new announcement. An empty or whitespace-only value falls
+         *  back to the default "Thinking…" copy (see `accessibleLabel`) so the
+         *  component never loses its accessible name. */
+        this.label = 'Thinking…';
+        /** Compact sizing for dense layouts (e.g. inline with a message bubble). */
+        this.size = 'md';
+    }
+    static { this.styles = [LyraElement.styles, styles, srOnly]; }
+    /** The accessible name actually used, falling back to the default
+     *  "Thinking…" copy when `label` is set to an empty or whitespace-only
+     *  string -- otherwise both the `aria-label` and the sr-only text node
+     *  would go blank, leaving this purely-decorative component with no
+     *  accessible name at all. */
+    get accessibleLabel() {
+        return this.label.trim() || 'Thinking…';
+    }
+    willUpdate(changed) {
+        this.setAttribute('role', 'status');
+        if (changed.has('label')) {
+            this.setAttribute('aria-label', this.accessibleLabel);
+        }
+    }
+    render() {
+        return html `
+      <span part="base" aria-hidden="true">${this.renderShape()}</span>
+      <span class="sr-only">${this.accessibleLabel}</span>
+    `;
+    }
+    renderShape() {
+        switch (this.variant) {
+            case 'pulse':
+                return html `<span part="pulse"></span>`;
+            case 'cursor':
+                return html `<span part="cursor"></span>`;
+            case 'dots':
+            default:
+                return html `<span part="dot"></span><span part="dot"></span><span part="dot"></span>`;
+        }
+    }
+}
+__decorate([
+    property({ reflect: true })
+], LyraTypingIndicator.prototype, "variant", void 0);
+__decorate([
+    property()
+], LyraTypingIndicator.prototype, "label", void 0);
+__decorate([
+    property({ reflect: true })
+], LyraTypingIndicator.prototype, "size", void 0);
+defineElement('typing-indicator', LyraTypingIndicator);

package/dist/components/typing-indicator/typing-indicator.styles.d.ts

@@ -0,0 +1 @@
+export declare const styles: import("lit").CSSResult;

package/dist/components/typing-indicator/typing-indicator.styles.js

@@ -0,0 +1,132 @@
+import { css } from 'lit';
+// `--lyra-transition-base` is used (rather than `--lyra-transition-fast`) as
+// the animation-cycle length for every variant below: it's the token the
+// rest of the library reserves for slightly-more-noticeable motion (gauge
+// fill, dialog/popover open), whereas `-fast` is reserved for snappy
+// discrete state flips (checkbox check, switch thumb). A continuous ambient
+// loop reads calmer at the longer of the two. Note this token is a *compound*
+// value (`180ms ease-out`, duration + timing-function together, exactly like
+// every `transition:` shorthand elsewhere in this library) so it can only
+// ever be spliced into the `animation:` *shorthand* below, never assigned to
+// `animation-duration` alone -- that longhand requires a bare `<time>` and
+// would silently invalidate (collapsing the duration to 0) if given the
+// compound value. For the same reason no extra timing-function keyword can
+// follow it in the shorthand: the token already supplies one.
+export const styles = css `
+  :host {
+    display: inline-flex;
+    align-items: center;
+    vertical-align: middle;
+    line-height: 1;
+    --lyra-typing-dot-size: var(--lyra-space-s);
+    --lyra-typing-gap: var(--lyra-space-xs);
+    --lyra-typing-cursor-width: 0.125rem;
+    --lyra-typing-cursor-height: 1em;
+  }
+  :host([size='sm']) {
+    --lyra-typing-dot-size: 0.375rem;
+    --lyra-typing-gap: 0.1875rem;
+    --lyra-typing-cursor-width: 0.09375rem;
+  }
+
+  [part='base'] {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--lyra-typing-gap);
+  }
+
+  /* -- dots -------------------------------------------------------------- */
+  [part='dot'] {
+    inline-size: var(--lyra-typing-dot-size);
+    block-size: var(--lyra-typing-dot-size);
+    border-radius: 50%;
+    background: currentColor;
+    opacity: 0.5;
+    animation: lyra-typing-dot-bounce var(--lyra-transition-base) infinite;
+  }
+  /* Fixed (not token-derived) stagger offsets -- --lyra-transition-base is
+     a compound "duration timing-function" value like every other transition
+     token in this library, so it can't be decomposed via calc() to derive a
+     fraction of just its duration; these two delays approximate a third and
+     two-thirds of that token's own fallback duration. */
+  [part='dot']:nth-child(2) {
+    animation-delay: 60ms;
+  }
+  [part='dot']:nth-child(3) {
+    animation-delay: 120ms;
+  }
+  @keyframes lyra-typing-dot-bounce {
+    0%,
+    80%,
+    100% {
+      transform: translateY(0);
+      opacity: 0.5;
+    }
+    40% {
+      transform: translateY(-35%);
+      opacity: 1;
+    }
+  }
+
+  /* -- pulse --------------------------------------------------------------
+     A single breathing dot, meant for tighter spaces than three dots allow. */
+  [part='pulse'] {
+    inline-size: var(--lyra-typing-dot-size);
+    block-size: var(--lyra-typing-dot-size);
+    border-radius: 50%;
+    background: currentColor;
+    opacity: 1;
+    transform: scale(1);
+    animation: lyra-typing-pulse var(--lyra-transition-base) infinite;
+  }
+  @keyframes lyra-typing-pulse {
+    0%,
+    100% {
+      transform: scale(0.85);
+      opacity: 0.55;
+    }
+    50% {
+      transform: scale(1);
+      opacity: 1;
+    }
+  }
+
+  /* -- cursor -------------------------------------------------------------
+     A blinking vertical bar for inline placement at the tail of streamed
+     text. The two adjacent keyframe stops (49% / 50%) hold identical values
+     either side of an instant flip, so the blink still reads as a sharp
+     on/off even though the token's ease-out timing-function is in effect
+     across the whole animation. */
+  [part='cursor'] {
+    inline-size: var(--lyra-typing-cursor-width);
+    block-size: var(--lyra-typing-cursor-height);
+    background: currentColor;
+    border-radius: var(--lyra-typing-cursor-width);
+    opacity: 1;
+    animation: lyra-typing-cursor-blink var(--lyra-transition-base) infinite;
+  }
+  @keyframes lyra-typing-cursor-blink {
+    0%,
+    49% {
+      opacity: 1;
+    }
+    50%,
+    100% {
+      opacity: 0;
+    }
+  }
+
+  /* Every variant collapses to its plain, fully-visible resting state
+     under reduced motion -- never a static mid-animation frame (e.g. a
+     permanently-invisible cursor, had the blink's "off" half been frozen
+     instead). */
+  @media (prefers-reduced-motion: reduce) {
+    [part='dot'],
+    [part='pulse'],
+    [part='cursor'] {
+      animation: none !important;
+      opacity: 1;
+      transform: none;
+    }
+  }
+`;