@skdx/web-components 0.26.0

package/dist/tree/Tree.d.cts

@@ -0,0 +1,253 @@
+import { LitElement } from 'lit';
+/**
+ * The text typeahead matches a node against: its `data-text-value` if it has
+ * one, else its *own* label text.
+ *
+ * `internal/typeahead`'s shared `itemText` is the wrong tool for a tree: a node
+ * renders its `<skdx-tree-item-indicator>` before its label, so a chevron would
+ * read as `"▸src"` and typing `s` would match nothing; and an expanded node
+ * contains its whole subtree, so its text would trail every descendant's.
+ * Skipping the `aria-hidden` indicator and the nested `role="group"` leaves
+ * exactly the label — with the same `data-text-value` precedence that every
+ * matcher in this repo honours first.
+ *
+ * @internal
+ */
+export declare function treeNodeLabel(item: HTMLElement): string;
+/** How many nodes a {@link SkdxTree} allows selected at once: one, many, or no selection. */
+export type SkdxTreeSelectionMode = 'single' | 'multiple' | 'none';
+/**
+ * Whether selecting a node also selects its subtree. `'descendants'` turns the
+ * tree into a tri-state checkbox tree: toggling a node applies to every one of
+ * its descendants, and a parent reports `aria-checked` of `true`, `false`, or
+ * `"mixed"` derived from them.
+ */
+export type SkdxTreeSelectionPropagation = 'none' | 'descendants';
+/** A node's tri-state checkbox value, as reported on `aria-checked`. */
+export type SkdxTreeCheckedState = boolean | 'mixed';
+/** Default `getLoadedLabel`: `"src loaded"`. */
+export declare function defaultGetLoadedLabel(nodeId: string): string;
+/**
+ * `<skdx-tree>` — the Web Components implementation of the shared Tree
+ * contract (see `@skdx/shared`'s `treeContract`). Follows the WAI-ARIA
+ * `treeview` pattern: renders `role="tree"` with `aria-multiselectable` when
+ * `selection-mode` is `"multiple"`. Owns expanded/selected/active-node
+ * state and hands it down to `<skdx-tree-item>` / `<skdx-tree-group>` /
+ * `<skdx-tree-item-indicator>` via `this.closest('skdx-tree')` (there is no
+ * cross-shadow-root context mechanism in Web Components), re-syncing them
+ * via an internal broadcast event.
+ *
+ * A single tab stop uses roving tabindex over the currently *visible* items
+ * only — `<skdx-tree-group>` physically removes its children from the DOM
+ * while collapsed (true unmounting, not just hiding), so they're naturally
+ * excluded. Arrow Up/Down/Home/End move focus; Arrow Right expands a
+ * collapsed node (or moves to its first child if already expanded); Arrow
+ * Left collapses an expanded node (or moves focus to its parent); Enter/
+ * Space select the focused node; printable characters run typeahead over the
+ * visible nodes' labels; `*` expands every collapsed sibling of the focused
+ * node. Under `selection-mode="multiple"`, Shift+Arrow Up/Down moves focus
+ * and toggles the node it lands on, Shift+Home/End selects through to the
+ * first/last node, Ctrl+A selects every visible node, and Ctrl+Arrow Up/Down
+ * moves focus without touching the selection.
+ *
+ * Expansion and selection each work controlled (`expanded-ids`/
+ * `selected-ids` properties + listening for `expanded-ids-change`/
+ * `selected-ids-change`) or uncontrolled (`default-expanded-ids`/
+ * `default-selected-ids`).
+ *
+ * `loadChildren` lazily populates a branch the first time it expands, marking
+ * the node `aria-busy` meanwhile and announcing when its children arrive.
+ * `selection-propagation="descendants"` turns it into a tri-state checkbox tree.
+ *
+ * @example
+ * ```html
+ * <skdx-tree default-expanded-ids='["src"]'>
+ *   <skdx-tree-item node-id="src">
+ *     <skdx-tree-item-indicator>▸</skdx-tree-item-indicator>
+ *     src
+ *     <skdx-tree-group>
+ *       <skdx-tree-item node-id="src/index.ts">index.ts</skdx-tree-item>
+ *     </skdx-tree-group>
+ *   </skdx-tree-item>
+ * </skdx-tree>
+ * ```
+ *
+ * @fires expanded-ids-change - Fired with the whole new expanded set as an `string[]` whenever a node is expanded or collapsed.
+ * @fires selected-ids-change - Fired with the whole new selected set as an `string[]` whenever the selection changes.
+ */
+export declare class SkdxTree extends LitElement {
+    static styles: import("lit").CSSResult;
+    /** `"single"`, `"multiple"`, or `"none"` (not selectable, just expand/collapse). */
+    selectionMode: SkdxTreeSelectionMode;
+    /** Expanded node ids, for controlled usage. Listen for `expanded-ids-change`. */
+    expandedIds?: string[];
+    /**
+     * Initially expanded node ids, for uncontrolled usage. A JSON array
+     * attribute (Lit's default `Array` converter — same convention as
+     * `<skdx-tags-input>`'s `value`), e.g. `default-expanded-ids='["src"]'`.
+     */
+    defaultExpandedIds: string[];
+    /** Selected node ids, for controlled usage. Listen for `selected-ids-change`. */
+    selectedIds?: string[];
+    /**
+     * Initially selected node ids, for uncontrolled usage. A JSON array
+     * attribute (Lit's default `Array` converter), e.g. `default-selected-ids='["src"]'`.
+     */
+    defaultSelectedIds: string[];
+    /**
+     * Turns the tree into a tri-state checkbox tree: toggling a node selects or
+     * deselects its whole subtree, and each node reports `aria-checked` of
+     * `true`/`false`/`"mixed"` derived from its descendants. Only meaningful
+     * with `selection-mode="multiple"`; ignored otherwise.
+     *
+     * Propagation reaches *rendered* descendants only — `<skdx-tree-group>`
+     * detaches its children while collapsed, so their `<skdx-tree-item>`s
+     * disconnect, unregister, and cannot be toggled.
+     */
+    selectionPropagation: SkdxTreeSelectionPropagation;
+    /**
+     * Loads a node's children the first time it is expanded. Return a promise to
+     * mark the node busy (`aria-busy="true"` plus `data-loading`) until it
+     * settles; when it resolves, `getLoadedLabel` is announced through the shared
+     * live announcer. A rejected promise clears the busy state, announces
+     * nothing, and leaves the node eligible to retry on the next expand.
+     *
+     * The node still needs a `<skdx-tree-group>` child to be expandable at all —
+     * render an empty one and fill it in when the promise resolves. Set as a
+     * property, not an attribute.
+     */
+    loadChildren?: (nodeId: string) => void | Promise<void>;
+    /**
+     * Formats the message announced when a lazily-loaded node's children arrive —
+     * newly rendered children are otherwise silent. Return an empty string to
+     * announce nothing. Set as a property, not an attribute.
+     */
+    getLoadedLabel: (nodeId: string) => string;
+    private _uncontrolledExpanded;
+    private _uncontrolledSelected;
+    private _activeNodeId;
+    private _loadingIds;
+    private _initialized;
+    /**
+     * Nodes whose `loadChildren` has already been kicked off. Not `@state`:
+     * nothing renders from it, and it must be readable synchronously inside the
+     * same `setExpanded` call that writes it.
+     */
+    private readonly _requested;
+    /** `nodeId` → its parent's id (or `null` at the top level), for the tri-state tree only. */
+    private readonly _nodeParents;
+    /** The letter-key search buffer behind the treeview typeahead. */
+    private readonly _typeahead;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(changed: Map<string, unknown>): void;
+    private syncHostAttrs;
+    /** @internal Resolved expanded node ids, controlled or uncontrolled. */
+    get expandedIdSet(): Set<string>;
+    /** @internal Resolved selected node ids, controlled or uncontrolled. */
+    get selectedIdSet(): Set<string>;
+    /** @internal Currently active (roving-tabindex) node id, or `null`. */
+    get activeNodeId(): string | null;
+    /** @internal Whether `nodeId`'s `loadChildren` call is still pending. */
+    isLoading(nodeId: string): boolean;
+    /**
+     * @internal Called by each `<skdx-tree-item>` on connect so the root can walk
+     * the node hierarchy without touching the DOM. Unconditional even though only
+     * the tri-state checkbox tree reads the hierarchy: gating it on
+     * `selection-propagation` would leave every already-connected item
+     * unregistered when the attribute flips after mount, and the tri-state would
+     * silently derive from an empty hierarchy.
+     */
+    registerNode(nodeId: string, parentId: string | null): void;
+    /** @internal Called by each `<skdx-tree-item>` on disconnect. */
+    unregisterNode(nodeId: string): void;
+    /**
+     * Re-renders every item after the hierarchy moved — but only when something
+     * renders from it. Registration itself is unconditional (see
+     * {@link registerNode}); telling the items about it is not, because a
+     * broadcast re-runs every item's `sync()`, which re-fires the group's
+     * mount/unmount, which connects and disconnects items, which registers and
+     * unregisters them again. Only the tri-state tree reads the hierarchy, so
+     * only it pays for that round trip.
+     */
+    private _broadcastHierarchy;
+    /** Parent id → its registered child ids. */
+    private get childrenByParent();
+    /**
+     * @internal Every registered descendant of `nodeId`.
+     *
+     * ponytail: only *rendered* descendants count — `<skdx-tree-group>` detaches
+     * its children while collapsed, so a collapsed subtree's items disconnect and
+     * unregister. That is the intended ceiling. Persist the full hierarchy in
+     * your own data and drive `selectedIds` controlled if collapsed branches must
+     * participate.
+     */
+    descendantsOf(nodeId: string): string[];
+    /**
+     * @internal Tri-state value for a node: derived from its registered
+     * descendants when it has any, otherwise its own membership in the selected
+     * set. Always `false` unless `selection-propagation` is `"descendants"`.
+     */
+    checkedState(nodeId: string): SkdxTreeCheckedState;
+    /** @internal Marks `nodeId` as the roving-tabindex stop. */
+    setActiveNodeId(nodeId: string): void;
+    /**
+     * @internal Keeps the roving tab stop on a node that actually exists: seeds
+     * the first currently-visible item unless one of them still claims the active
+     * id.
+     *
+     * The check is "does any visible item claim the id", not "is the id unset":
+     * the item holding the stop can go away — collapsing its branch unmounts it —
+     * leaving the id pointing at a node that is no longer rendered, which an
+     * `activeNodeId !== null` guard reads as nothing to do. No item would then
+     * carry `tabindex="0"` and the whole tree would drop out of the tab order,
+     * with nothing on screen to explain it. Called by every `<skdx-tree-item>` on
+     * connect *and* disconnect, so it re-runs whenever the item set changes.
+     */
+    ensureActiveNodeId(): void;
+    /**
+     * @internal Writes `aria-posinset`/`aria-setsize` onto every rendered item,
+     * counting the siblings under each `data-skdx-tree-parent-id` in document
+     * order — siblings at one level, not a flat index over the tree. Required
+     * rather than optional here because `<skdx-tree-group>` *detaches* a collapsed
+     * subtree: assistive tech cannot infer a set it cannot see.
+     *
+     * Written straight onto the elements, like every other attribute an item
+     * carries in this package, and driven from `<skdx-tree-item>`'s connect and
+     * disconnect — the one pair of moments the sibling set can change. A root
+     * broadcast is deliberately not used: it re-runs every item's `sync()`, which
+     * re-fires a group's mount/unmount, which connects and disconnects items
+     * again.
+     */
+    syncNodePositions(): void;
+    /**
+     * @internal Expands every id in one update, for `*`. Not a loop over
+     * {@link setExpanded}, which would dispatch one `expanded-ids-change` per
+     * sibling and, while `expandedIds` is set from outside, resolve each call
+     * against the same unchanged array. Each node still gets its own
+     * `loadChildren` kickoff.
+     */
+    expandMany(nodeIds: string[]): void;
+    /**
+     * @internal Adds every id to the selection in one update, for the range keys
+     * (Shift+Home/End, Ctrl+A) that would otherwise dispatch one change event per
+     * node. Plain union — `selection-propagation` deliberately doesn't apply: a
+     * range is already an explicit list of nodes, not one node standing in for
+     * its subtree.
+     */
+    selectMany(nodeIds: string[]): void;
+    /** @internal Expands or collapses `nodeId`, kicking off `loadChildren` the first time it expands. */
+    setExpanded(nodeId: string, expand: boolean): void;
+    private _startLoad;
+    /** @internal Toggles `nodeId`'s selection, respecting `selectionMode` and `selectionPropagation`. */
+    toggleSelected(nodeId: string): void;
+    private _broadcast;
+    private readonly handleFocusIn;
+    private readonly handleKeyDown;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-tree': SkdxTree;
+    }
+}

package/dist/tree/Tree.d.ts

@@ -0,0 +1,253 @@
+import { LitElement } from 'lit';
+/**
+ * The text typeahead matches a node against: its `data-text-value` if it has
+ * one, else its *own* label text.
+ *
+ * `internal/typeahead`'s shared `itemText` is the wrong tool for a tree: a node
+ * renders its `<skdx-tree-item-indicator>` before its label, so a chevron would
+ * read as `"▸src"` and typing `s` would match nothing; and an expanded node
+ * contains its whole subtree, so its text would trail every descendant's.
+ * Skipping the `aria-hidden` indicator and the nested `role="group"` leaves
+ * exactly the label — with the same `data-text-value` precedence that every
+ * matcher in this repo honours first.
+ *
+ * @internal
+ */
+export declare function treeNodeLabel(item: HTMLElement): string;
+/** How many nodes a {@link SkdxTree} allows selected at once: one, many, or no selection. */
+export type SkdxTreeSelectionMode = 'single' | 'multiple' | 'none';
+/**
+ * Whether selecting a node also selects its subtree. `'descendants'` turns the
+ * tree into a tri-state checkbox tree: toggling a node applies to every one of
+ * its descendants, and a parent reports `aria-checked` of `true`, `false`, or
+ * `"mixed"` derived from them.
+ */
+export type SkdxTreeSelectionPropagation = 'none' | 'descendants';
+/** A node's tri-state checkbox value, as reported on `aria-checked`. */
+export type SkdxTreeCheckedState = boolean | 'mixed';
+/** Default `getLoadedLabel`: `"src loaded"`. */
+export declare function defaultGetLoadedLabel(nodeId: string): string;
+/**
+ * `<skdx-tree>` — the Web Components implementation of the shared Tree
+ * contract (see `@skdx/shared`'s `treeContract`). Follows the WAI-ARIA
+ * `treeview` pattern: renders `role="tree"` with `aria-multiselectable` when
+ * `selection-mode` is `"multiple"`. Owns expanded/selected/active-node
+ * state and hands it down to `<skdx-tree-item>` / `<skdx-tree-group>` /
+ * `<skdx-tree-item-indicator>` via `this.closest('skdx-tree')` (there is no
+ * cross-shadow-root context mechanism in Web Components), re-syncing them
+ * via an internal broadcast event.
+ *
+ * A single tab stop uses roving tabindex over the currently *visible* items
+ * only — `<skdx-tree-group>` physically removes its children from the DOM
+ * while collapsed (true unmounting, not just hiding), so they're naturally
+ * excluded. Arrow Up/Down/Home/End move focus; Arrow Right expands a
+ * collapsed node (or moves to its first child if already expanded); Arrow
+ * Left collapses an expanded node (or moves focus to its parent); Enter/
+ * Space select the focused node; printable characters run typeahead over the
+ * visible nodes' labels; `*` expands every collapsed sibling of the focused
+ * node. Under `selection-mode="multiple"`, Shift+Arrow Up/Down moves focus
+ * and toggles the node it lands on, Shift+Home/End selects through to the
+ * first/last node, Ctrl+A selects every visible node, and Ctrl+Arrow Up/Down
+ * moves focus without touching the selection.
+ *
+ * Expansion and selection each work controlled (`expanded-ids`/
+ * `selected-ids` properties + listening for `expanded-ids-change`/
+ * `selected-ids-change`) or uncontrolled (`default-expanded-ids`/
+ * `default-selected-ids`).
+ *
+ * `loadChildren` lazily populates a branch the first time it expands, marking
+ * the node `aria-busy` meanwhile and announcing when its children arrive.
+ * `selection-propagation="descendants"` turns it into a tri-state checkbox tree.
+ *
+ * @example
+ * ```html
+ * <skdx-tree default-expanded-ids='["src"]'>
+ *   <skdx-tree-item node-id="src">
+ *     <skdx-tree-item-indicator>▸</skdx-tree-item-indicator>
+ *     src
+ *     <skdx-tree-group>
+ *       <skdx-tree-item node-id="src/index.ts">index.ts</skdx-tree-item>
+ *     </skdx-tree-group>
+ *   </skdx-tree-item>
+ * </skdx-tree>
+ * ```
+ *
+ * @fires expanded-ids-change - Fired with the whole new expanded set as an `string[]` whenever a node is expanded or collapsed.
+ * @fires selected-ids-change - Fired with the whole new selected set as an `string[]` whenever the selection changes.
+ */
+export declare class SkdxTree extends LitElement {
+    static styles: import("lit").CSSResult;
+    /** `"single"`, `"multiple"`, or `"none"` (not selectable, just expand/collapse). */
+    selectionMode: SkdxTreeSelectionMode;
+    /** Expanded node ids, for controlled usage. Listen for `expanded-ids-change`. */
+    expandedIds?: string[];
+    /**
+     * Initially expanded node ids, for uncontrolled usage. A JSON array
+     * attribute (Lit's default `Array` converter — same convention as
+     * `<skdx-tags-input>`'s `value`), e.g. `default-expanded-ids='["src"]'`.
+     */
+    defaultExpandedIds: string[];
+    /** Selected node ids, for controlled usage. Listen for `selected-ids-change`. */
+    selectedIds?: string[];
+    /**
+     * Initially selected node ids, for uncontrolled usage. A JSON array
+     * attribute (Lit's default `Array` converter), e.g. `default-selected-ids='["src"]'`.
+     */
+    defaultSelectedIds: string[];
+    /**
+     * Turns the tree into a tri-state checkbox tree: toggling a node selects or
+     * deselects its whole subtree, and each node reports `aria-checked` of
+     * `true`/`false`/`"mixed"` derived from its descendants. Only meaningful
+     * with `selection-mode="multiple"`; ignored otherwise.
+     *
+     * Propagation reaches *rendered* descendants only — `<skdx-tree-group>`
+     * detaches its children while collapsed, so their `<skdx-tree-item>`s
+     * disconnect, unregister, and cannot be toggled.
+     */
+    selectionPropagation: SkdxTreeSelectionPropagation;
+    /**
+     * Loads a node's children the first time it is expanded. Return a promise to
+     * mark the node busy (`aria-busy="true"` plus `data-loading`) until it
+     * settles; when it resolves, `getLoadedLabel` is announced through the shared
+     * live announcer. A rejected promise clears the busy state, announces
+     * nothing, and leaves the node eligible to retry on the next expand.
+     *
+     * The node still needs a `<skdx-tree-group>` child to be expandable at all —
+     * render an empty one and fill it in when the promise resolves. Set as a
+     * property, not an attribute.
+     */
+    loadChildren?: (nodeId: string) => void | Promise<void>;
+    /**
+     * Formats the message announced when a lazily-loaded node's children arrive —
+     * newly rendered children are otherwise silent. Return an empty string to
+     * announce nothing. Set as a property, not an attribute.
+     */
+    getLoadedLabel: (nodeId: string) => string;
+    private _uncontrolledExpanded;
+    private _uncontrolledSelected;
+    private _activeNodeId;
+    private _loadingIds;
+    private _initialized;
+    /**
+     * Nodes whose `loadChildren` has already been kicked off. Not `@state`:
+     * nothing renders from it, and it must be readable synchronously inside the
+     * same `setExpanded` call that writes it.
+     */
+    private readonly _requested;
+    /** `nodeId` → its parent's id (or `null` at the top level), for the tri-state tree only. */
+    private readonly _nodeParents;
+    /** The letter-key search buffer behind the treeview typeahead. */
+    private readonly _typeahead;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(changed: Map<string, unknown>): void;
+    private syncHostAttrs;
+    /** @internal Resolved expanded node ids, controlled or uncontrolled. */
+    get expandedIdSet(): Set<string>;
+    /** @internal Resolved selected node ids, controlled or uncontrolled. */
+    get selectedIdSet(): Set<string>;
+    /** @internal Currently active (roving-tabindex) node id, or `null`. */
+    get activeNodeId(): string | null;
+    /** @internal Whether `nodeId`'s `loadChildren` call is still pending. */
+    isLoading(nodeId: string): boolean;
+    /**
+     * @internal Called by each `<skdx-tree-item>` on connect so the root can walk
+     * the node hierarchy without touching the DOM. Unconditional even though only
+     * the tri-state checkbox tree reads the hierarchy: gating it on
+     * `selection-propagation` would leave every already-connected item
+     * unregistered when the attribute flips after mount, and the tri-state would
+     * silently derive from an empty hierarchy.
+     */
+    registerNode(nodeId: string, parentId: string | null): void;
+    /** @internal Called by each `<skdx-tree-item>` on disconnect. */
+    unregisterNode(nodeId: string): void;
+    /**
+     * Re-renders every item after the hierarchy moved — but only when something
+     * renders from it. Registration itself is unconditional (see
+     * {@link registerNode}); telling the items about it is not, because a
+     * broadcast re-runs every item's `sync()`, which re-fires the group's
+     * mount/unmount, which connects and disconnects items, which registers and
+     * unregisters them again. Only the tri-state tree reads the hierarchy, so
+     * only it pays for that round trip.
+     */
+    private _broadcastHierarchy;
+    /** Parent id → its registered child ids. */
+    private get childrenByParent();
+    /**
+     * @internal Every registered descendant of `nodeId`.
+     *
+     * ponytail: only *rendered* descendants count — `<skdx-tree-group>` detaches
+     * its children while collapsed, so a collapsed subtree's items disconnect and
+     * unregister. That is the intended ceiling. Persist the full hierarchy in
+     * your own data and drive `selectedIds` controlled if collapsed branches must
+     * participate.
+     */
+    descendantsOf(nodeId: string): string[];
+    /**
+     * @internal Tri-state value for a node: derived from its registered
+     * descendants when it has any, otherwise its own membership in the selected
+     * set. Always `false` unless `selection-propagation` is `"descendants"`.
+     */
+    checkedState(nodeId: string): SkdxTreeCheckedState;
+    /** @internal Marks `nodeId` as the roving-tabindex stop. */
+    setActiveNodeId(nodeId: string): void;
+    /**
+     * @internal Keeps the roving tab stop on a node that actually exists: seeds
+     * the first currently-visible item unless one of them still claims the active
+     * id.
+     *
+     * The check is "does any visible item claim the id", not "is the id unset":
+     * the item holding the stop can go away — collapsing its branch unmounts it —
+     * leaving the id pointing at a node that is no longer rendered, which an
+     * `activeNodeId !== null` guard reads as nothing to do. No item would then
+     * carry `tabindex="0"` and the whole tree would drop out of the tab order,
+     * with nothing on screen to explain it. Called by every `<skdx-tree-item>` on
+     * connect *and* disconnect, so it re-runs whenever the item set changes.
+     */
+    ensureActiveNodeId(): void;
+    /**
+     * @internal Writes `aria-posinset`/`aria-setsize` onto every rendered item,
+     * counting the siblings under each `data-skdx-tree-parent-id` in document
+     * order — siblings at one level, not a flat index over the tree. Required
+     * rather than optional here because `<skdx-tree-group>` *detaches* a collapsed
+     * subtree: assistive tech cannot infer a set it cannot see.
+     *
+     * Written straight onto the elements, like every other attribute an item
+     * carries in this package, and driven from `<skdx-tree-item>`'s connect and
+     * disconnect — the one pair of moments the sibling set can change. A root
+     * broadcast is deliberately not used: it re-runs every item's `sync()`, which
+     * re-fires a group's mount/unmount, which connects and disconnects items
+     * again.
+     */
+    syncNodePositions(): void;
+    /**
+     * @internal Expands every id in one update, for `*`. Not a loop over
+     * {@link setExpanded}, which would dispatch one `expanded-ids-change` per
+     * sibling and, while `expandedIds` is set from outside, resolve each call
+     * against the same unchanged array. Each node still gets its own
+     * `loadChildren` kickoff.
+     */
+    expandMany(nodeIds: string[]): void;
+    /**
+     * @internal Adds every id to the selection in one update, for the range keys
+     * (Shift+Home/End, Ctrl+A) that would otherwise dispatch one change event per
+     * node. Plain union — `selection-propagation` deliberately doesn't apply: a
+     * range is already an explicit list of nodes, not one node standing in for
+     * its subtree.
+     */
+    selectMany(nodeIds: string[]): void;
+    /** @internal Expands or collapses `nodeId`, kicking off `loadChildren` the first time it expands. */
+    setExpanded(nodeId: string, expand: boolean): void;
+    private _startLoad;
+    /** @internal Toggles `nodeId`'s selection, respecting `selectionMode` and `selectionPropagation`. */
+    toggleSelected(nodeId: string): void;
+    private _broadcast;
+    private readonly handleFocusIn;
+    private readonly handleKeyDown;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-tree': SkdxTree;
+    }
+}

package/dist/tree/Tree.js

@@ -0,0 +1,5 @@
+var E=Object.defineProperty;var x=Object.getOwnPropertyDescriptor;var a=(o,c,e,s)=>{for(var t=s>1?void 0:s?x(c,e):c,i=o.length-1,n;i>=0;i--)(n=o[i])&&(t=(s?n(c,e,t):n(t))||t);return s&&t&&E(c,e,t),t};import{css as S,html as w,LitElement as A}from"lit";import{property as u,state as p}from"lit/decorators.js";import{customElement as I}from"../internal/define.js";import{directionalKey as M}from"../internal/direction.js";import{isTypeaheadKey as L,Typeahead as k}from"../internal/typeahead.js";import{announce as C}from"../utils/live-announcer.js";var y='[role="treeitem"]:not([data-disabled])',v='[role="treeitem"]';function h(o){return o.getAttribute("data-skdx-tree-node-id")??""}function H(o){let c=o.getAttribute("data-text-value");if(c!==null)return c;let e="";for(let s of Array.from(o.childNodes)){let t=s.nodeType===1?s:null;t&&(t.getAttribute("role")==="group"||t.getAttribute("aria-hidden")==="true")||(e+=s.textContent??"")}return e}function P(o){return`${o} loaded`}var r=class extends A{constructor(){super(...arguments);this.selectionMode="single";this.defaultExpandedIds=[];this.defaultSelectedIds=[];this.selectionPropagation="none";this.getLoadedLabel=P;this._uncontrolledExpanded=new Set;this._uncontrolledSelected=new Set;this._activeNodeId=null;this._loadingIds=new Set;this._initialized=!1;this._requested=new Set;this._nodeParents=new Map;this._typeahead=new k;this.handleFocusIn=e=>{let t=e.target.closest?.('[role="treeitem"]');if(t&&!t.hasAttribute("data-disabled")){let i=t.getAttribute("data-skdx-tree-node-id");i&&this.setActiveNodeId(i)}};this.handleKeyDown=e=>{let s=e.target;if(!s.matches?.('[role="treeitem"]'))return;let t=Array.from(this.querySelectorAll(y)),i=t.indexOf(s),n=this.selectionMode==="multiple",l=M(e.key,this);if(n&&e.shiftKey&&(l==="ArrowDown"||l==="ArrowUp")){e.preventDefault();let d=t[i+(l==="ArrowDown"?1:-1)];d&&(d.focus(),this.toggleSelected(h(d)));return}if(n&&e.shiftKey&&(e.key==="Home"||e.key==="End")){e.preventDefault();let d=e.key==="Home"?0:t.length-1;this.selectMany(t.slice(Math.min(i,d),Math.max(i,d)+1).map(h)),t[d]?.focus();return}if(n&&(e.ctrlKey||e.metaKey)&&e.key.toLowerCase()==="a"){e.preventDefault(),this.selectMany(t.map(h));return}if(l==="ArrowDown"){e.preventDefault(),t[i+1]?.focus();return}if(l==="ArrowUp"){e.preventDefault(),t[i-1]?.focus();return}if(l==="Home"){e.preventDefault(),t[0]?.focus();return}if(l==="End"){e.preventDefault(),t[t.length-1]?.focus();return}let f=h(s),m=s.hasAttribute("aria-expanded"),b=s.getAttribute("aria-expanded")==="true",g=s.getAttribute("data-skdx-tree-parent-id")||"";if(l==="ArrowRight")e.preventDefault(),m&&!b?this.setExpanded(f,!0):t[i+1]?.focus();else if(l==="ArrowLeft")e.preventDefault(),m&&b?this.setExpanded(f,!1):g&&t.find(_=>h(_)===g)?.focus();else if(e.key==="Enter"||e.key===" ")e.preventDefault(),this.toggleSelected(f);else if(e.key==="*")e.preventDefault(),this.expandMany(Array.from(this.querySelectorAll(v)).filter(d=>(d.getAttribute("data-skdx-tree-parent-id")||"")===g&&d.getAttribute("aria-expanded")==="false").map(h));else if(L(e)){let d=this._typeahead.match(e.key,t.map(H),i);if(d===-1)return;e.preventDefault(),t[d]?.focus()}}}connectedCallback(){super.connectedCallback(),this._initialized||(this._uncontrolledExpanded=new Set(this.defaultExpandedIds),this._uncontrolledSelected=new Set(this.defaultSelectedIds),this._initialized=!0),this.setAttribute("role","tree"),this.syncHostAttrs(),this.addEventListener("keydown",this.handleKeyDown),this.addEventListener("focusin",this.handleFocusIn)}disconnectedCallback(){this.removeEventListener("keydown",this.handleKeyDown),this.removeEventListener("focusin",this.handleFocusIn),this._typeahead.clear(),super.disconnectedCallback()}updated(e){(e.has("expandedIds")||e.has("selectedIds")||e.has("selectionMode")||e.has("selectionPropagation"))&&(this.syncHostAttrs(),this._broadcast())}syncHostAttrs(){this.selectionMode==="multiple"?this.setAttribute("aria-multiselectable","true"):this.removeAttribute("aria-multiselectable")}get expandedIdSet(){return this.expandedIds!==void 0?new Set(this.expandedIds):this._uncontrolledExpanded}get selectedIdSet(){return this.selectedIds!==void 0?new Set(this.selectedIds):this._uncontrolledSelected}get activeNodeId(){return this._activeNodeId}isLoading(e){return this._loadingIds.has(e)}registerNode(e,s){this._nodeParents.get(e)!==s&&(this._nodeParents.set(e,s),this._broadcastHierarchy())}unregisterNode(e){this._nodeParents.delete(e)&&this._broadcastHierarchy()}_broadcastHierarchy(){this.selectionPropagation==="descendants"&&this._broadcast()}get childrenByParent(){let e=new Map;for(let[s,t]of this._nodeParents){if(t===null)continue;let i=e.get(t);i?i.push(s):e.set(t,[s])}return e}descendantsOf(e){let s=this.childrenByParent,t=[],i=[...s.get(e)??[]];for(;i.length>0;){let n=i.pop();t.push(n),i.push(...s.get(n)??[])}return t}checkedState(e){if(this.selectionPropagation!=="descendants")return!1;let s=this.selectedIdSet,t=this.descendantsOf(e);if(t.length===0)return s.has(e);let i=t.filter(n=>s.has(n)).length;return i===0?!1:i===t.length?!0:"mixed"}setActiveNodeId(e){this._activeNodeId!==e&&(this._activeNodeId=e,this._broadcast())}ensureActiveNodeId(){let e=Array.from(this.querySelectorAll(y),t=>t.getAttribute("data-skdx-tree-node-id")).filter(t=>t!==null&&t!==""),s=e[0];s===void 0||this._activeNodeId!==null&&e.includes(this._activeNodeId)||this.setActiveNodeId(s)}syncNodePositions(){let e=new Map;for(let s of this.querySelectorAll(v)){let t=s.getAttribute("data-skdx-tree-parent-id")??"",i=e.get(t);i?i.push(s):e.set(t,[s])}for(let s of e.values())s.forEach((t,i)=>{t.setAttribute("aria-posinset",String(i+1)),t.setAttribute("aria-setsize",String(s.length))})}expandMany(e){if(e.length===0)return;let s=new Set(this.expandedIdSet);for(let t of e)s.add(t);this.expandedIds===void 0&&(this._uncontrolledExpanded=s),this.dispatchEvent(new CustomEvent("expanded-ids-change",{detail:[...s],bubbles:!0,composed:!0}));for(let t of e)this._startLoad(t,!0);this._broadcast()}selectMany(e){if(this.selectionMode!=="multiple")return;let s=new Set(this.selectedIdSet);for(let t of e)s.add(t);this.selectedIds===void 0&&(this._uncontrolledSelected=s),this.dispatchEvent(new CustomEvent("selected-ids-change",{detail:[...s],bubbles:!0,composed:!0})),this._broadcast()}setExpanded(e,s){let t=this.expandedIdSet,i=s?new Set(t).add(e):new Set([...t].filter(n=>n!==e));this.expandedIds===void 0&&(this._uncontrolledExpanded=i),this.dispatchEvent(new CustomEvent("expanded-ids-change",{detail:[...i],bubbles:!0,composed:!0})),this._startLoad(e,s),this._broadcast()}_startLoad(e,s){let t=this.loadChildren;if(!s||!t||this._requested.has(e))return;this._requested.add(e),this._loadingIds=new Set(this._loadingIds).add(e);let i=()=>{let n=new Set(this._loadingIds);n.delete(e),this._loadingIds=n,this._broadcast()};Promise.resolve(t(e)).then(()=>{i(),C(this.getLoadedLabel(e))},()=>{this._requested.delete(e),i()})}toggleSelected(e){if(this.selectionMode==="none")return;let s=this.selectedIdSet,t;if(this.selectionMode==="multiple"&&this.selectionPropagation==="descendants"){let i=this.checkedState(e)!==!0;t=new Set(s);for(let n of[e,...this.descendantsOf(e)])i?t.add(n):t.delete(n)}else this.selectionMode==="single"?t=new Set([e]):(t=new Set(s),t.has(e)?t.delete(e):t.add(e));this.selectedIds===void 0&&(this._uncontrolledSelected=t),this.dispatchEvent(new CustomEvent("selected-ids-change",{detail:[...t],bubbles:!0,composed:!0})),this._broadcast()}_broadcast(){this.dispatchEvent(new CustomEvent("skdx-tree-internal-update"))}render(){return w`<slot></slot>`}};r.styles=S`
+    :host {
+      display: block;
+    }
+  `,a([u({type:String,attribute:"selection-mode"})],r.prototype,"selectionMode",2),a([u({attribute:!1})],r.prototype,"expandedIds",2),a([u({type:Array,attribute:"default-expanded-ids"})],r.prototype,"defaultExpandedIds",2),a([u({attribute:!1})],r.prototype,"selectedIds",2),a([u({type:Array,attribute:"default-selected-ids"})],r.prototype,"defaultSelectedIds",2),a([u({type:String,attribute:"selection-propagation"})],r.prototype,"selectionPropagation",2),a([u({attribute:!1})],r.prototype,"loadChildren",2),a([u({attribute:!1})],r.prototype,"getLoadedLabel",2),a([p()],r.prototype,"_uncontrolledExpanded",2),a([p()],r.prototype,"_uncontrolledSelected",2),a([p()],r.prototype,"_activeNodeId",2),a([p()],r.prototype,"_loadingIds",2),r=a([I("skdx-tree","tree","root")],r);export{r as SkdxTree,P as defaultGetLoadedLabel,H as treeNodeLabel};

package/dist/tree/TreeGroup.cjs

@@ -0,0 +1,5 @@
+"use strict";var d=Object.defineProperty;var h=Object.getOwnPropertyDescriptor;var u=Object.getOwnPropertyNames;var v=Object.prototype.hasOwnProperty;var C=(r,e)=>{for(var i in e)d(r,i,{get:e[i],enumerable:!0})},y=(r,e,i,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let t of u(e))!v.call(r,t)&&t!==i&&d(r,t,{get:()=>e[t],enumerable:!(n=h(e,t))||n.enumerable});return r};var b=r=>y(d({},"__esModule",{value:!0}),r),c=(r,e,i,n)=>{for(var t=n>1?void 0:n?h(e,i):e,l=r.length-1,a;l>=0;l--)(a=r[l])&&(t=(n?a(e,i,t):a(t))||t);return n&&t&&d(e,i,t),t};var k={};C(k,{SkdxTreeGroup:()=>s});module.exports=b(k);var o=require("lit"),m=require("lit/decorators.js"),p=require("../internal/define.cjs"),f=require("../internal/styles.cjs");var s=class extends o.LitElement{constructor(){super(...arguments);this.forceMount=!1;this.parentItem=null;this.cachedChildren=null;this.onParentUpdate=()=>this.sync()}connectedCallback(){super.connectedCallback(),this.setAttribute("role","group"),this.parentItem=this.closest("skdx-tree-item"),this.parentItem?.addEventListener("skdx-tree-item-internal-update",this.onParentUpdate),this.sync()}disconnectedCallback(){this.parentItem?.removeEventListener("skdx-tree-item-internal-update",this.onParentUpdate),super.disconnectedCallback()}sync(){let i=this.forceMount||(this.parentItem?.expanded??!1);if(i&&this.cachedChildren){for(let n of this.cachedChildren)this.appendChild(n);this.cachedChildren=null}else if(!i&&!this.cachedChildren&&this.childNodes.length>0){this.cachedChildren=Array.from(this.childNodes);for(let n of this.cachedChildren)this.removeChild(n)}}render(){return o.html`<slot></slot>`}};s.styles=[f.hiddenHostStyles,o.css`
+      :host {
+        display: block;
+      }
+    `],c([(0,m.property)({type:Boolean,attribute:"force-mount"})],s.prototype,"forceMount",2),s=c([(0,p.customElement)("skdx-tree-group","tree","group")],s);0&&(module.exports={SkdxTreeGroup});

package/dist/tree/TreeGroup.d.cts

@@ -0,0 +1,39 @@
+import { LitElement } from 'lit';
+/**
+ * `<skdx-tree-group>` — collapsible container for a `<skdx-tree-item>`'s
+ * child `<skdx-tree-item>`s: renders `role="group"`. Its light-DOM children
+ * are physically detached from the DOM while the parent item is collapsed
+ * (unless `force-mount`) and re-inserted on expansion — true unmounting, not
+ * merely hiding, matching the shared contract's "roving tabindex over
+ * currently-visible items only" requirement.
+ *
+ * @example
+ * ```html
+ * <skdx-tree-item node-id="src">
+ *   src
+ *   <skdx-tree-group>
+ *     <skdx-tree-item node-id="src/index.ts">index.ts</skdx-tree-item>
+ *   </skdx-tree-group>
+ * </skdx-tree-item>
+ * ```
+ */
+export declare class SkdxTreeGroup extends LitElement {
+    static styles: import("lit").CSSResult[];
+    /**
+     * Keep this group's children mounted even while the parent
+     * `<skdx-tree-item>` is collapsed, instead of detaching them.
+     */
+    forceMount: boolean;
+    private parentItem;
+    private cachedChildren;
+    private readonly onParentUpdate;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private sync;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-tree-group': SkdxTreeGroup;
+    }
+}

package/dist/tree/TreeGroup.d.ts

@@ -0,0 +1,39 @@
+import { LitElement } from 'lit';
+/**
+ * `<skdx-tree-group>` — collapsible container for a `<skdx-tree-item>`'s
+ * child `<skdx-tree-item>`s: renders `role="group"`. Its light-DOM children
+ * are physically detached from the DOM while the parent item is collapsed
+ * (unless `force-mount`) and re-inserted on expansion — true unmounting, not
+ * merely hiding, matching the shared contract's "roving tabindex over
+ * currently-visible items only" requirement.
+ *
+ * @example
+ * ```html
+ * <skdx-tree-item node-id="src">
+ *   src
+ *   <skdx-tree-group>
+ *     <skdx-tree-item node-id="src/index.ts">index.ts</skdx-tree-item>
+ *   </skdx-tree-group>
+ * </skdx-tree-item>
+ * ```
+ */
+export declare class SkdxTreeGroup extends LitElement {
+    static styles: import("lit").CSSResult[];
+    /**
+     * Keep this group's children mounted even while the parent
+     * `<skdx-tree-item>` is collapsed, instead of detaching them.
+     */
+    forceMount: boolean;
+    private parentItem;
+    private cachedChildren;
+    private readonly onParentUpdate;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private sync;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-tree-group': SkdxTreeGroup;
+    }
+}

package/dist/tree/TreeGroup.js

@@ -0,0 +1,5 @@
+var a=Object.defineProperty;var c=Object.getOwnPropertyDescriptor;var l=(s,n,r,e)=>{for(var t=e>1?void 0:e?c(n,r):n,o=s.length-1,d;o>=0;o--)(d=s[o])&&(t=(e?d(n,r,t):d(t))||t);return e&&t&&a(n,r,t),t};import{css as h,html as m,LitElement as p}from"lit";import{property as f}from"lit/decorators.js";import{customElement as u}from"../internal/define.js";import{hiddenHostStyles as v}from"../internal/styles.js";var i=class extends p{constructor(){super(...arguments);this.forceMount=!1;this.parentItem=null;this.cachedChildren=null;this.onParentUpdate=()=>this.sync()}connectedCallback(){super.connectedCallback(),this.setAttribute("role","group"),this.parentItem=this.closest("skdx-tree-item"),this.parentItem?.addEventListener("skdx-tree-item-internal-update",this.onParentUpdate),this.sync()}disconnectedCallback(){this.parentItem?.removeEventListener("skdx-tree-item-internal-update",this.onParentUpdate),super.disconnectedCallback()}sync(){let r=this.forceMount||(this.parentItem?.expanded??!1);if(r&&this.cachedChildren){for(let e of this.cachedChildren)this.appendChild(e);this.cachedChildren=null}else if(!r&&!this.cachedChildren&&this.childNodes.length>0){this.cachedChildren=Array.from(this.childNodes);for(let e of this.cachedChildren)this.removeChild(e)}}render(){return m`<slot></slot>`}};i.styles=[v,h`
+      :host {
+        display: block;
+      }
+    `],l([f({type:Boolean,attribute:"force-mount"})],i.prototype,"forceMount",2),i=l([u("skdx-tree-group","tree","group")],i);export{i as SkdxTreeGroup};

package/dist/tree/TreeItem.cjs

@@ -0,0 +1,5 @@
+"use strict";var l=Object.defineProperty;var p=Object.getOwnPropertyDescriptor;var g=Object.getOwnPropertyNames;var k=Object.prototype.hasOwnProperty;var x=(r,i)=>{for(var e in i)l(r,e,{get:i[e],enumerable:!0})},A=(r,i,e,t)=>{if(i&&typeof i=="object"||typeof i=="function")for(let s of g(i))!k.call(r,s)&&s!==e&&l(r,s,{get:()=>i[s],enumerable:!(t=p(i,s))||t.enumerable});return r};var I=r=>A(l({},"__esModule",{value:!0}),r),c=(r,i,e,t)=>{for(var s=t>1?void 0:t?p(i,e):i,n=r.length-1,o;n>=0;n--)(o=r[n])&&(s=(t?o(i,e,s):o(s))||s);return t&&s&&l(i,e,s),s};var f={};x(f,{SkdxTreeItem:()=>d});module.exports=I(f);var a=require("lit"),u=require("lit/decorators.js"),m=require("../internal/define.cjs"),b=require("../internal/styles.cjs");var d=class extends a.LitElement{constructor(){super(...arguments);this.nodeId="";this.disabled=!1;this.root=null;this.onRootUpdate=()=>this.sync();this.handleClick=e=>{this.disabled||this.isFromNestedItem(e)||(this.root?.toggleSelected(this.nodeId),this.toggleExpanded())}}get hasChildren(){return this.querySelector(":scope > skdx-tree-group")!==null}get expanded(){return this.root?.expandedIdSet.has(this.nodeId)??!1}get selected(){return this.root?.selectedIdSet.has(this.nodeId)??!1}connectedCallback(){super.connectedCallback(),this.root=this.closest("skdx-tree"),this.root?.addEventListener("skdx-tree-internal-update",this.onRootUpdate),this.addEventListener("click",this.handleClick),this.root?.registerNode(this.nodeId,this.computeParentId()||null),this.sync(),this.root?.ensureActiveNodeId(),this.root?.syncNodePositions()}disconnectedCallback(){this.root?.removeEventListener("skdx-tree-internal-update",this.onRootUpdate),this.removeEventListener("click",this.handleClick),this.root?.unregisterNode(this.nodeId),super.disconnectedCallback(),this.root?.ensureActiveNodeId(),this.root?.syncNodePositions()}updated(e){(e.has("disabled")||e.has("nodeId"))&&this.sync()}toggleExpanded(){this.hasChildren&&this.root?.setExpanded(this.nodeId,!this.expanded)}isFromNestedItem(e){return e.target.closest('[role="treeitem"]')!==this}computeDepth(){let e=1,t=this.parentElement;for(;t;)t.tagName==="SKDX-TREE-ITEM"&&e++,t=t.parentElement;return e}computeParentId(){return this.closest("skdx-tree-group")?.closest("skdx-tree-item")?.getAttribute("data-skdx-tree-node-id")??""}sync(){let e=this.hasChildren,t=this.expanded,s=this.selected,n=this.root?.selectionMode??"single";if(this.setAttribute("role","treeitem"),this.setAttribute("aria-level",String(this.computeDepth())),n==="none"?this.removeAttribute("aria-selected"):this.setAttribute("aria-selected",String(s)),e?this.setAttribute("aria-expanded",String(t)):this.removeAttribute("aria-expanded"),this.disabled?(this.setAttribute("aria-disabled","true"),this.setAttribute("data-disabled","")):(this.removeAttribute("aria-disabled"),this.removeAttribute("data-disabled")),e?this.setAttribute("data-state",t?"expanded":"collapsed"):this.removeAttribute("data-state"),this.root?.isLoading(this.nodeId)?(this.setAttribute("aria-busy","true"),this.setAttribute("data-loading","")):(this.removeAttribute("aria-busy"),this.removeAttribute("data-loading")),this.root?.selectionPropagation==="descendants"){let h=this.root.checkedState(this.nodeId);this.setAttribute("aria-checked",h==="mixed"?"mixed":String(h)),this.setAttribute("data-checked",h==="mixed"?"indeterminate":h?"checked":"unchecked")}else this.removeAttribute("aria-checked"),this.removeAttribute("data-checked");this.setAttribute("data-skdx-tree-node-id",this.nodeId);let o=this.computeParentId();o?this.setAttribute("data-skdx-tree-parent-id",o):this.removeAttribute("data-skdx-tree-parent-id");let v=this.root?.activeNodeId===this.nodeId;this.tabIndex=this.disabled?-1:v?0:-1,this.dispatchEvent(new CustomEvent("skdx-tree-item-internal-update"))}render(){return a.html`<slot></slot>`}};d.styles=[b.hiddenHostStyles,a.css`
+      :host {
+        display: block;
+      }
+    `],c([(0,u.property)({type:String,attribute:"node-id"})],d.prototype,"nodeId",2),c([(0,u.property)({type:Boolean,reflect:!0})],d.prototype,"disabled",2),d=c([(0,m.customElement)("skdx-tree-item","tree","item")],d);0&&(module.exports={SkdxTreeItem});