@aceshooting/lyra-ui 1.0.0 → 1.1.0

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

@@ -19,42 +19,91 @@ export interface TreeItem {
  * `<lyra-tree-node>`'s own shadow root still reaches this listener.
  *
  * @customElement lyra-tree
- * @event lyra-node-toggle - `detail: { id, expanded }`, re-emitted from a child `<lyra-tree-node>`.
- * @event lyra-node-select - `detail: { id }`, re-emitted from a child `<lyra-tree-node>`.
+ * @event lyra-node-toggle - `detail: { id, expanded }`, dispatched by a descendant `<lyra-tree-node>` and observed here (bubbling, composed) to keep the roving-tabindex `activeId` in sync.
+ * @event lyra-node-select - `detail: { id }`, dispatched by a descendant `<lyra-tree-node>` and observed here (bubbling, composed) to keep the roving-tabindex `activeId` in sync.
  * @csspart base
  * @slot - `<lyra-tree-node>` elements (top-level tree items).
  */
 export declare class LyraTree extends LyraElement {
     static styles: import("lit").CSSResultGroup[];
     data: TreeItem[];
+    /** Accessible name for the tree -- `role="tree"` lives on an internal element, not the host, so `aria-label`/`aria-labelledby` set directly on `<lyra-tree>` would not label it. */
+    label: string;
     private activeId;
+    /** 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. */
+    private pendingFocusId;
     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.
+     */
+    private cachedVisible;
+    private invalidateVisibleCache;
     /** Every currently *visible* (ancestor-expanded) node, top-to-bottom. */
     private visibleNodeElements;
     private findItem;
     protected willUpdate(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
-    /** Unchanged from the existing implementation — by-id reconciliation of top-level items. */
+    /** By-id reconciliation of top-level items: reuses/reorders existing `<lyra-tree-node>` elements and removes ones no longer present in `data`. */
     private syncNodes;
     private focusNode;
     /**
-     * `updated()` only pushes the new `activeId` to *top-level* nodes; a
-     * nested node only receives it once its ancestor chain's own renders
-     * cascade it down (one more pending update per depth level). Cascade
-     * `updateComplete` itself to match: awaiting `<lyra-tree>`'s (or any
-     * `<lyra-tree-node>`'s — see the matching override there) `updateComplete`
-     * now transitively waits for every visible descendant node's own update,
-     * not just this element's. Without this, `focusNode()`'s `.focus()` call
-     * can run while a nested target is still mid-cascade (no `tabindex`
-     * attribute committed yet), and `.focus()` on an element with no
-     * `tabindex` attribute at all is a silent no-op.
+     * A mouse click always lands directly on the node it interacts with --
+     * `select()`/`expand()`/`collapse()` all emit their own node's id --
+     * independent of whatever `activeId` currently holds. Sync `activeId` to
+     * that id here so a click always becomes the tree's new roving-tabindex
+     * target: this keeps it aligned with real DOM focus, keeps the next
+     * arrow-key press relative to the item the user just clicked (rather than
+     * a stale `activeId`), and keeps `activeId` valid when a click collapses
+     * an ancestor of the previously-active node -- the collapsed node's own
+     * id (always still visible, since collapsing never removes a node's own
+     * top-level or already-rendered self) replaces the now-hidden descendant's
+     * id, so at least one node keeps a roving tabindex of 0. Keyboard-driven
+     * toggles/selects always target the already-active node, so this is a
+     * same-value, no-op assignment for them.
+     */
+    private onNodeActivate;
+    /**
+     * `updated()` only pushes the new `activeId` to *top-level* nodes; nested
+     * nodes only receive it once their ancestor chain's own renders cascade it
+     * down (one more pending update per depth level). Cascade `updateComplete`
+     * to match (see `cascadeUpdateComplete`), so `focusNode()`'s `.focus()`
+     * call never runs while a nested target is still mid-cascade -- `.focus()`
+     * on an element with no `tabindex` attribute committed yet is a silent
+     * no-op.
+     *
+     * The `pendingFocusId` refocus (set by `willUpdate()` when a `data`
+     * reassignment removes the node that currently holds real DOM focus) is
+     * also resolved *here*, after the cascade above, rather than from
+     * `updated()` firing a detached `void this.updateComplete.then(...)` of
+     * its own: `updateComplete`'s getter (see the base class) calls this
+     * method fresh on *every* access rather than caching one promise, so a
+     * second, independent invocation started from inside `updated()` isn't
+     * the same promise chain a caller's own `await el.updateComplete` is
+     * following -- both ultimately settle once the same underlying update
+     * resolves, but as separate chains their `.then()` continuations aren't
+     * ordered against each other, so a caller's `await` can win the race and
+     * observe focus *not yet* restored. Doing the refocus inline, before this
+     * method's own `await` chain resolves, makes it unconditionally part of
+     * whatever `updateComplete` promise every caller (this class's own
+     * `focusNode()` included) is already waiting on.
      */
     protected getUpdateComplete(): Promise<boolean>;
     private onTreeKeyDown;
-    /** Expand every node in the tree, recursively. (unchanged) */
+    /** Expand every node in the tree, recursively. */
     expandAll(): void;
-    /** Collapse every node in the tree. (unchanged) */
+    /**
+     * Collapse every node in the tree, recursively. Goes through each node's
+     * own `collapse()` (rather than assigning `expanded` directly) so its
+     * `lyra-node-toggle` emit reaches `onNodeActivate` -- that keeps `activeId`
+     * re-synced to a node that's still visible after collapsing, even when the
+     * roving-tabindex target was a nested descendant whose ancestor's
+     * `role="group"` is about to disappear.
+     */
     collapseAll(): void;
     render(): TemplateResult;
 }

package/dist/components/tree/tree.js

@@ -4,11 +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 { html } from 'lit';
+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 { isRtl } from '../../internal/rtl.js';
 import { styles } from './tree.styles.js';
+import { cascadeUpdateComplete } from './update-cascade.js';
 import './tree-node.js';
 /**
  * `<lyra-tree>` — an expand/collapse hierarchy for graph/document navigation.
@@ -22,8 +24,8 @@ import './tree-node.js';
  * `<lyra-tree-node>`'s own shadow root still reaches this listener.
  *
  * @customElement lyra-tree
- * @event lyra-node-toggle - `detail: { id, expanded }`, re-emitted from a child `<lyra-tree-node>`.
- * @event lyra-node-select - `detail: { id }`, re-emitted from a child `<lyra-tree-node>`.
+ * @event lyra-node-toggle - `detail: { id, expanded }`, dispatched by a descendant `<lyra-tree-node>` and observed here (bubbling, composed) to keep the roving-tabindex `activeId` in sync.
+ * @event lyra-node-select - `detail: { id }`, dispatched by a descendant `<lyra-tree-node>` and observed here (bubbling, composed) to keep the roving-tabindex `activeId` in sync.
  * @csspart base
  * @slot - `<lyra-tree-node>` elements (top-level tree items).
  */
@@ -31,13 +33,50 @@ export class LyraTree extends LyraElement {
     constructor() {
         super(...arguments);
         this.data = [];
+        /** Accessible name for the tree -- `role="tree"` lives on an internal element, not the host, so `aria-label`/`aria-labelledby` set directly on `<lyra-tree>` would not label it. */
+        this.label = '';
         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 --
+         * independent of whatever `activeId` currently holds. Sync `activeId` to
+         * that id here so a click always becomes the tree's new roving-tabindex
+         * target: this keeps it aligned with real DOM focus, keeps the next
+         * arrow-key press relative to the item the user just clicked (rather than
+         * a stale `activeId`), and keeps `activeId` valid when a click collapses
+         * an ancestor of the previously-active node -- the collapsed node's own
+         * id (always still visible, since collapsing never removes a node's own
+         * top-level or already-rendered self) replaces the now-hidden descendant's
+         * id, so at least one node keeps a roving tabindex of 0. Keyboard-driven
+         * toggles/selects always target the already-active node, so this is a
+         * 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) => {
             const visible = this.visibleNodeElements();
             if (visible.length === 0)
                 return;
             const currentIndex = visible.findIndex((n) => n.item.id === this.activeId);
             const current = currentIndex >= 0 ? visible[currentIndex] : visible[0];
+            // Expand/step-in and collapse/step-out are physical-direction actions --
+            // swap which arrow key does which in RTL, matching split.ts/time-range.ts.
+            const rtl = isRtl(this);
+            const expandKey = rtl ? 'ArrowLeft' : 'ArrowRight';
+            const collapseKey = rtl ? 'ArrowRight' : 'ArrowLeft';
             switch (e.key) {
                 case 'ArrowDown':
                     e.preventDefault();
@@ -55,12 +94,12 @@ export class LyraTree extends LyraElement {
                     e.preventDefault();
                     this.focusNode(visible[visible.length - 1]);
                     break;
-                case 'ArrowRight':
+                case expandKey:
                     e.preventDefault();
                     if (!current.hasChildren)
                         break;
                     if (!current.expanded) {
-                        current.expand(); // focus stays put; a 2nd ArrowRight steps into the first child
+                        current.expand(); // focus stays put; a 2nd press steps into the first child
                     }
                     else {
                         const child = visible[currentIndex + 1];
@@ -68,7 +107,7 @@ export class LyraTree extends LyraElement {
                             this.focusNode(child);
                     }
                     break;
-                case 'ArrowLeft':
+                case collapseKey:
                     e.preventDefault();
                     if (current.hasChildren && current.expanded) {
                         current.collapse();
@@ -99,8 +138,13 @@ export class LyraTree extends LyraElement {
     childrenOf(node) {
         return [...(node.shadowRoot?.querySelectorAll('lyra-tree-node') ?? [])];
     }
+    invalidateVisibleCache() {
+        this.cachedVisible = null;
+    }
     /** Every currently *visible* (ancestor-expanded) node, top-to-bottom. */
     visibleNodeElements() {
+        if (this.cachedVisible)
+            return this.cachedVisible;
         const acc = [];
         const walk = (nodes) => {
             for (const n of nodes) {
@@ -110,6 +154,7 @@ export class LyraTree extends LyraElement {
             }
         };
         walk(this.nodeElements);
+        this.cachedVisible = acc;
         return acc;
     }
     findItem(items, id) {
@@ -124,10 +169,20 @@ 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
+            // top-level ancestor is about to be removed.
+            const focused = this.nodeElements.find((n) => n === document.activeElement);
             this.syncNodes();
             if (!this.activeId || !this.findItem(this.data, this.activeId)) {
                 this.activeId = this.data[0]?.id ?? null;
             }
+            // `node.remove()` inside `syncNodes()` (per the DOM spec) already moved
+            // real focus off `focused` and onto <body> by this point; record the
+            // newly-resolved `activeId` so `updated()` can restore focus to it.
+            this.pendingFocusId = focused && !focused.isConnected ? this.activeId : null;
         }
     }
     updated(changed) {
@@ -140,7 +195,7 @@ export class LyraTree extends LyraElement {
             });
         }
     }
-    /** Unchanged from the existing implementation — by-id reconciliation of top-level items. */
+    /** By-id reconciliation of top-level items: reuses/reorders existing `<lyra-tree-node>` elements and removes ones no longer present in `data`. */
     syncNodes() {
         const existingById = new Map();
         for (const node of this.nodeElements) {
@@ -174,45 +229,78 @@ export class LyraTree extends LyraElement {
         node.focus();
     }
     /**
-     * `updated()` only pushes the new `activeId` to *top-level* nodes; a
-     * nested node only receives it once its ancestor chain's own renders
-     * cascade it down (one more pending update per depth level). Cascade
-     * `updateComplete` itself to match: awaiting `<lyra-tree>`'s (or any
-     * `<lyra-tree-node>`'s — see the matching override there) `updateComplete`
-     * now transitively waits for every visible descendant node's own update,
-     * not just this element's. Without this, `focusNode()`'s `.focus()` call
-     * can run while a nested target is still mid-cascade (no `tabindex`
-     * attribute committed yet), and `.focus()` on an element with no
-     * `tabindex` attribute at all is a silent no-op.
+     * `updated()` only pushes the new `activeId` to *top-level* nodes; nested
+     * nodes only receive it once their ancestor chain's own renders cascade it
+     * down (one more pending update per depth level). Cascade `updateComplete`
+     * to match (see `cascadeUpdateComplete`), so `focusNode()`'s `.focus()`
+     * call never runs while a nested target is still mid-cascade -- `.focus()`
+     * on an element with no `tabindex` attribute committed yet is a silent
+     * no-op.
+     *
+     * The `pendingFocusId` refocus (set by `willUpdate()` when a `data`
+     * reassignment removes the node that currently holds real DOM focus) is
+     * also resolved *here*, after the cascade above, rather than from
+     * `updated()` firing a detached `void this.updateComplete.then(...)` of
+     * its own: `updateComplete`'s getter (see the base class) calls this
+     * method fresh on *every* access rather than caching one promise, so a
+     * second, independent invocation started from inside `updated()` isn't
+     * the same promise chain a caller's own `await el.updateComplete` is
+     * following -- both ultimately settle once the same underlying update
+     * resolves, but as separate chains their `.then()` continuations aren't
+     * ordered against each other, so a caller's `await` can win the race and
+     * observe focus *not yet* restored. Doing the refocus inline, before this
+     * method's own `await` chain resolves, makes it unconditionally part of
+     * whatever `updateComplete` promise every caller (this class's own
+     * `focusNode()` included) is already waiting on.
      */
     async getUpdateComplete() {
         const result = await super.getUpdateComplete();
-        await Promise.all(this.nodeElements.map((n) => n.updateComplete));
+        await cascadeUpdateComplete(this.nodeElements);
+        if (this.pendingFocusId != null) {
+            const id = this.pendingFocusId;
+            this.pendingFocusId = null;
+            this.nodeElements.find((n) => n.item.id === id)?.focus();
+        }
         return result;
     }
-    /** Expand every node in the tree, recursively. (unchanged) */
+    /** 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)));
             }
         };
         setAll(this.nodeElements);
     }
-    /** Collapse every node in the tree. (unchanged) */
+    /**
+     * Collapse every node in the tree, recursively. Goes through each node's
+     * own `collapse()` (rather than assigning `expanded` directly) so its
+     * `lyra-node-toggle` emit reaches `onNodeActivate` -- that keeps `activeId`
+     * re-synced to a node that's still visible after collapsing, even when the
+     * roving-tabindex target was a nested descendant whose ancestor's
+     * `role="group"` is about to disappear.
+     */
     collapseAll() {
         const setAll = (nodes) => {
             for (const n of nodes) {
                 setAll(this.childrenOf(n));
-                n.expanded = false;
+                n.collapse();
             }
         };
         setAll(this.nodeElements);
     }
     render() {
         return html `
-      <div part="base" role="tree" @keydown=${this.onTreeKeyDown}>
+      <div
+        part="base"
+        role="tree"
+        aria-label=${this.label || nothing}
+        @keydown=${this.onTreeKeyDown}
+        @lyra-node-toggle=${this.onNodeActivate}
+        @lyra-node-select=${this.onNodeActivate}
+      >
         <slot></slot>
       </div>
     `;
@@ -221,6 +309,9 @@ export class LyraTree extends LyraElement {
 __decorate([
     property({ attribute: false })
 ], LyraTree.prototype, "data", void 0);
+__decorate([
+    property()
+], LyraTree.prototype, "label", void 0);
 __decorate([
     state()
 ], LyraTree.prototype, "activeId", void 0);

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

@@ -3,3 +3,7 @@ declare const meta: Meta;
 export default meta;
 type Story = StoryObj;
 export declare const Default: Story;
+/** Demonstrates the imperative `expandAll()`/`collapseAll()` methods. */
+export declare const ExpandCollapseAll: Story;
+/** A single branch nested well past the 8rem indentation cap, so the capped indent and truncated label are both visible without expanding anything by hand. */
+export declare const DeeplyNested: Story;

package/dist/components/tree/tree.stories.js

@@ -18,5 +18,35 @@ const meta = {
 };
 export default meta;
 export const Default = {
-    render: () => html `<lyra-tree style="max-width: 20rem" .data=${data}></lyra-tree>`,
+    render: () => html `<lyra-tree style="max-width: 20rem" label="File explorer" .data=${data}></lyra-tree>`,
+};
+/** Demonstrates the imperative `expandAll()`/`collapseAll()` methods. */
+export const ExpandCollapseAll = {
+    render: () => {
+        const getTree = () => document.getElementById('imperative-tree');
+        return html `
+      <div style="display:flex; flex-direction:column; gap:1rem; max-width:20rem">
+        <div style="display:flex; gap:0.5rem">
+          <button @click=${() => getTree().expandAll()}>Expand all</button>
+          <button @click=${() => getTree().collapseAll()}>Collapse all</button>
+        </div>
+        <lyra-tree id="imperative-tree" label="File explorer" .data=${data}></lyra-tree>
+      </div>
+    `;
+    },
+};
+const buildDeepData = (depth) => {
+    let node = { id: `d${depth}`, label: `A very long deeply-nested label all the way at depth ${depth}` };
+    for (let d = depth - 1; d >= 0; d--) {
+        node = { id: `d${d}`, label: `Level ${d} node with a fairly long descriptive label`, children: [node] };
+    }
+    return [node];
+};
+/** A single branch nested well past the 8rem indentation cap, so the capped indent and truncated label are both visible without expanding anything by hand. */
+export const DeeplyNested = {
+    render: () => html `<lyra-tree style="max-width: 20rem" label="Deeply nested example" .data=${buildDeepData(12)}></lyra-tree>`,
+    play: async ({ canvasElement }) => {
+        const tree = canvasElement.querySelector('lyra-tree');
+        tree.expandAll();
+    },
 };

package/dist/components/tree/update-cascade.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Both `<lyra-tree>` and `<lyra-tree-node>` override `getUpdateComplete()` to
+ * additionally await their currently-known child `<lyra-tree-node>`
+ * elements' own `updateComplete`. A nested node only receives a pushed-down
+ * property (like `activeId`, and the `tabIndex` derived from it) once its
+ * own render has committed -- one more pending update per depth level -- so
+ * without this, code that awaits a parent's `updateComplete` (e.g.
+ * `focusNode()`) could run before an arbitrarily-nested descendant has
+ * actually settled.
+ */
+export declare function cascadeUpdateComplete(children: Iterable<{
+    updateComplete: Promise<unknown>;
+}>): Promise<void>;

package/dist/components/tree/update-cascade.js

@@ -0,0 +1,13 @@
+/**
+ * Both `<lyra-tree>` and `<lyra-tree-node>` override `getUpdateComplete()` to
+ * additionally await their currently-known child `<lyra-tree-node>`
+ * elements' own `updateComplete`. A nested node only receives a pushed-down
+ * property (like `activeId`, and the `tabIndex` derived from it) once its
+ * own render has committed -- one more pending update per depth level -- so
+ * without this, code that awaits a parent's `updateComplete` (e.g.
+ * `focusNode()`) could run before an arbitrarily-nested descendant has
+ * actually settled.
+ */
+export async function cascadeUpdateComplete(children) {
+    await Promise.all([...children].map((child) => child.updateComplete));
+}

package/dist/components/widget/widget.d.ts

@@ -11,7 +11,16 @@ import { LyraElement } from '../../internal/lyra-element.js';
  * @slot actions - Header action controls, rendered before the collapse/expand buttons.
  * @event lyra-collapse-change - `detail: boolean` (the new `collapsed` state).
  * @event lyra-fullscreen-change - `detail: boolean` (the new `fullscreen` state).
- * @csspart base, header, title, label, sublabel, actions, body, backdrop
+ * @csspart base - The panel root (dialog role + backdrop when fullscreen).
+ * @csspart header - The header row containing the title, actions, and toggle buttons.
+ * @csspart title - The wrapper around the label/sublabel.
+ * @csspart label - The panel title text.
+ * @csspart sublabel - The panel subtitle text.
+ * @csspart actions - The wrapper around the `actions` slot.
+ * @csspart collapse-button - The collapse/expand toggle button.
+ * @csspart fullscreen-button - The fullscreen toggle button.
+ * @csspart body - The wrapper around the default slot (the panel body).
+ * @csspart backdrop - The fullscreen scrim behind the panel.
  */
 export declare class LyraWidget extends LyraElement {
     static styles: import("lit").CSSResultGroup[];
@@ -24,12 +33,17 @@ export declare class LyraWidget extends LyraElement {
     private hasActionsSlot;
     private releaseScrollLock?;
     private lastTrigger?;
+    private readonly bodyId;
     protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    connectedCallback(): void;
     disconnectedCallback(): void;
     private onActionsSlotChange;
     private toggleCollapsed;
     private toggleFullscreen;
     private onDocKeyDown;
+    private getFocusableElements;
+    private getActiveElement;
     private onBackdropClick;
     render(): TemplateResult;
 }