@ixfx/components 0.15.5 → 0.16.1

package/dist/index-Bnm-kKGC.d.ts

@@ -0,0 +1,475 @@
+import { E as TreeSearchHost, M as TreeDataModel, a as TreeComponent, i as TreeCollapseEvent, j as TreeTickleEvent, k as TreeSelectEvent, n as TreeActivateEvent, o as TreeComponentEventMap, w as TreeNavigateOptions, x as TreeItemClickEvent, y as TreeExpandEvent } from "./tree-component-DgfkxmVY.js";
+import { a as TreeItem, n as TreeExclusivity, o as TreeNode, r as TreeFilterPredicate, s as TreeSelectionFilter, t as LoadChildrenCallback } from "./types-Jky6oNAp.js";
+import { a as ViewStateBase, n as ScrollState, t as GetViewStateOptions } from "./types-LU1u0CB8.js";
+import "./index-9ttcdwlL.js";
+import { S as ListSearchController } from "./index-CUErGhCg.js";
+import { n as TickledController } from "./tickled-controller-DodxD3eQ.js";
+import { LitElement, PropertyValues, TemplateResult, nothing } from "lit";
+import { CommandRegistry } from "@clinth/ui-commands";
+import { TraversableTree } from "@ixfx/collections";
+//#region src/miller/types.d.ts
+type MillerSelectionMode = `implicit` | `standard` | `manual` | `checked` | `vscode`;
+/** Detail for the `header-click` event fired when a column header is clicked. */
+type MillerHeaderClickDetail = {
+  /** Zero-based column index whose header was clicked. */
+  depth: number;
+  /** The header text (label of the column's parent node). */
+  label: string;
+  /**
+   * Ancestry chain from the root node down to (and including) the node
+   * whose label is shown in this header.
+   * - depth 0 → [root]
+   * - depth 1 → [root, selectedAtDepth0]
+   * - depth d → [root, sel[0], …, sel[d-1]]
+   */
+  path: Array<TreeNode>;
+};
+/** Detail for the `item-dblclick` event. */
+type MillerItemDblClickDetail = {
+  node: TreeNode;
+  depth: number;
+};
+/** Detail for the `rebase` event fired when the view root changes. */
+type MillerRebaseDetail = {
+  /** The new view root, or `undefined` when the view was restored to the full tree. */
+  viewRoot: TreeNode | undefined;
+  /**
+   * Ancestry chain from the true root down to and including the new view root.
+   * Empty when the view shows the full tree.
+   */
+  path: Array<TreeNode>;
+};
+/** Detail for the `item-rightclick` event. */
+type MillerItemRightClickDetail = {
+  node: TreeNode;
+  depth: number;
+  mouseEvent: MouseEvent;
+};
+/** Detail for the `header-rightclick` event. */
+type MillerHeaderRightClickDetail = {
+  depth: number;
+  label: string;
+  path: Array<TreeNode>;
+  mouseEvent: MouseEvent;
+};
+type MillerHeaderClickEvent = CustomEvent<MillerHeaderClickDetail>;
+type MillerItemDblClickEvent = CustomEvent<MillerItemDblClickDetail>;
+type MillerItemRightClickEvent = CustomEvent<MillerItemRightClickDetail>;
+type MillerHeaderRightClickEvent = CustomEvent<MillerHeaderRightClickDetail>;
+type MillerRebaseEvent = CustomEvent<MillerRebaseDetail>;
+/**
+ * A snapshot of all display states for a single item in the miller columns.
+ *
+ * - `selected`: the item is part of the active selection.
+ * - `open`: the item is an ancestor of the current deepest column (it is on
+ *   the currently open path, regardless of whether it is also selected).
+ * - `focused`: the keyboard cursor is currently on this item.
+ * - `isLeaf`: the item has no children and cannot be expanded.
+ */
+type MillerItemState = {
+  selected: boolean;
+  open: boolean;
+  focused: boolean;
+  isLeaf: boolean;
+};
+//#endregion
+//#region src/miller/miller-view-state.d.ts
+/**
+ * Pure view-state helpers for `ixfx-miller-*`. The element runs these
+ * whenever its data changes (new root, lazy load, `invalidateStructure()`)
+ * and on `setViewState()`; see docs/infra-view-state.md.
+ */
+/** `ixfx-miller-list` view state. */
+type MillerListViewState = ViewStateBase & {
+  /**
+   * Key of the open branch at each depth, from column 0 down, relative to the
+   * view root. A Miller view has exactly one open branch per column, so this
+   * is an ordered path rather than an `expanded` record.
+   */
+  readonly path?: readonly string[];
+  /** User-resized column widths in px, keyed by column depth. */
+  readonly columnWidths?: Readonly<Record<string, number>>;
+  /** Per-column scroll, keyed by the key of the node whose children the column lists. */
+  readonly columnScroll?: Readonly<Record<string, ScrollState>>;
+};
+//#endregion
+//#region src/miller/miller-base.d.ts
+/**
+ * Base class for Miller column components. Handles column lifecycle,
+ * column resizing, keyboard navigation, and selection modes.
+ *
+ * Subclasses must override `renderColumnContent`.
+ *
+ * ## Interaction modes (`interactionMode`)
+ *
+ * Controls how clicks map to selection changes. Default: `'standard'`.
+ *
+ * - `implicit`: Selection follows the cursor path (navigation mode).
+ * - `standard`: Single click selects; Shift+click range-selects within a column;
+ *   Cmd/Ctrl+click toggles individual items.
+ * - `manual`: Component never modifies selection. Use `selectedKeys` / `setSelected`
+ *   / `clearSelection` to drive state externally.
+ * - `checked`: Checkboxes on every item (rendered by subclass via `_isChecked` /
+ *   `_handleCheckboxClick`). Clicking the item navigates/expands; clicking the
+ *   checkbox toggles selection of the node and all loaded descendants.
+ *
+ * ## Events
+ * - `expand`: FYI event fired after a column opens. Detail: `{ node, depth }`
+ * - `collapse`: FYI event fired when a column closes. Detail: `{ node, depth }`
+ * - `header-click`: fired when a column header is clicked (requires `headers` attr).
+ *   Detail: `{ depth, label, path: MillerNode[] }`
+ * - `activate`: fired when Enter is pressed on an item. Detail: `{ node, depth }`
+ * - `select`: fired when the selection set changes. Detail: `{ selected, previous }`
+ * - `item-click`: fired on any item click. Detail: `{ node, depth }`
+ * - `tickle`: fired when an item is hovered or keyboard cursor moves to it. Detail: `{ node, depth }`
+ *
+ * ## CSS variables
+ * - `--column-bg`: var(--surface-3)
+ * - `--column-header-bg`: var(--surface-2)
+ * - `--column-header-text`: var(--surface-muted-text)
+ * - `--column-separator`: var(--surface-5)
+ * - `--column-resize-handle`: var(--surface-5)
+ * - `--column-resize-handle-hover`: var(--accent)
+ * - `--column-resize-width`: 4px
+ * - `--item-hover-bg`: var(--item-bg-tickled)
+ * - `--item-selected-bg`: var(--item-bg-selected)
+ * - `--item-selected-text`: var(--item-text-selected)
+ */
+declare class MillerBaseElement extends LitElement implements TreeComponent, TreeSearchHost {
+  #private;
+  root: TreeNode | undefined;
+  model: TreeDataModel | undefined;
+  headers: boolean;
+  /**
+   * When true, the last (rightmost) column grows to fill any remaining
+   * horizontal space in the host. All other columns size to their content
+   * (`max-content`), unless the user has manually resized them.
+   *
+   * When the user clicks into an item in the stretched column and a new
+   * column opens, the previously-last column automatically transitions back
+   * to its content-based width and the new last column stretches instead.
+   * Explicit user-resized widths (via the resize handle) always win over
+   * stretching.
+   */
+  stretchLastColumn: boolean;
+  /**
+   * Alternative node to use as the display root (Finder-style column-view
+   * rebase). When set, column 0 shows this node's children and all depths,
+   * headers, and key paths are relative to it. When `undefined` (default),
+   * the full `root` tree is shown.
+   *
+   * Prefer `rebaseTo()` / `rebaseUp()` over assigning this directly — they
+   * validate the target and report whether the view changed. Assigning a new
+   * `root` (or receiving one via `model`) silently clears the view root.
+   */
+  viewRoot: TreeNode | undefined;
+  /**
+   * Controls the column-level interaction pattern (how clicks map to column changes).
+   * This is distinct from `selectionFilter` (which restricts which node kinds are selectable).
+   * Default: `'standard'`.
+   */
+  interactionMode: MillerSelectionMode;
+  selectionFilter: TreeSelectionFilter;
+  exclusivity: TreeExclusivity;
+  /**
+   * Callback to load children for a lazy node.
+   * Superseded by `model` when both are set.
+   * If not set and `model` is not set, clicking a lazy node opens an empty column.
+   */
+  loadChildren: LoadChildrenCallback | undefined;
+  filterPredicate: TreeFilterPredicate | undefined;
+  /**
+   * Space-separated subset of `navigate select filter` — limits which
+   * incremental-search modes are offered. Unset ⇒ all three; empty ⇒ search
+   * disabled. See `docs/infra-incremental.md`.
+   */
+  searchModes: string | undefined;
+  protected _columns: TreeNode[][];
+  protected _loadingDepth: number | undefined;
+  protected _selectedByDepth: Map<number, TreeNode>;
+  protected _selectedKeys: Set<string>;
+  protected _selectedNodes: Set<TreeNode>;
+  /**
+   * Whether restoring view state may call `loadChildren` / `model` to open a
+   * saved path through branches that aren't loaded yet (one load at a time,
+   * cascading down the path). Default `true`.
+   */
+  restoreLoads: boolean;
+  /** Incremental search (navigate / select / filter). See `docs/infra-incremental.md`. */
+  readonly search: ListSearchController<{
+    node: TreeNode;
+    depth: number;
+  }>;
+  /** Command registry carrying this component's `list.search.*` commands. */
+  get registry(): CommandRegistry<unknown> | undefined;
+  tickled: TickledController<string>;
+  willUpdate(_changedProps: PropertyValues): void;
+  updated(changedProps: PropertyValues): void;
+  firstUpdated(): void;
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  /**
+   * Snapshot the open path, selection, keyboard cursor, column widths and
+   * column scroll as plain JSON, keyed by `item.key`. Includes pending state
+   * for keys not currently loaded.
+   */
+  getViewState(options?: GetViewStateOptions<MillerListViewState>): MillerListViewState;
+  /**
+   * Apply saved view state. Fields present replace the current ones; keys not
+   * loaded yet are applied as they appear — including via `loadChildren` /
+   * `model` for the saved path when `restoreLoads`.
+   */
+  setViewState(state: Partial<MillerListViewState>): void;
+  clearPendingViewState(): void;
+  /** Read current selection as an immutable set of item keys. */
+  get selectedKeys(): ReadonlySet<string>;
+  /** Replace entire selection and trigger a re-render. */
+  set selectedKeys(keys: Iterable<string>);
+  /** The most recently selected node. */
+  get selectedNode(): TreeNode | undefined;
+  set selectedNode(node: TreeNode | undefined);
+  /** Full selection set (implements TreeComponent interface). */
+  get selectedNodes(): ReadonlySet<TreeNode>;
+  /** Add `node` to the selection (respects selectionFilter). Dispatches `select` event. */
+  select(node: TreeNode): void;
+  /** Remove `node` from the selection. Dispatches `select` event. */
+  deselect(node: TreeNode): void;
+  /**
+   * Clear all selection and trigger a re-render.
+   */
+  clearSelection(): void;
+  /** Not implemented on miller-list. */
+  selectAll(): void;
+  /** Not implemented on miller-list. */
+  deselectAll(): void;
+  /**
+   * Select or deselect a single node by key.
+   * In `checked` interactionMode this also recursively selects/deselects all loaded descendants.
+   */
+  setSelected(node: TreeNode, selected: boolean): void;
+  /**
+   * Return all MillerNodes whose key is in `_selectedKeys`, searching only
+   * the currently visible columns.
+   */
+  getSelected(): TreeNode[];
+  /**
+   * Programmatically navigate to a node by key path, relative to the current
+   * view root (rebased or full tree).
+   */
+  navigateTo(keys: readonly string[], options?: TreeNavigateOptions): boolean;
+  /**
+   * Re-sync the element with children arrays patched in place (see
+   * `MillerTreeController.sync()`): columns whose selected node was removed are
+   * closed, selection entries for removed nodes are dropped, then it re-renders.
+   */
+  invalidateStructure(): void;
+  /**
+   * Programmatically navigate to the first node (breadth-first) matching a predicate.
+   */
+  navigateToNode(predicate: (node: TreeNode) => boolean): boolean;
+  /** Open the columns down to `key` and move the cursor to it, without changing the selection (search "navigate" mode). */
+  revealKey(key: string): boolean;
+  /** Replace the selection with `nodes` (search "select" mode). */
+  selectMany(nodes: Iterable<TreeNode>): void;
+  getNodes(): ReadonlyArray<{
+    node: TreeNode;
+    depth: number;
+  }>;
+  /**
+   * Rebase the view to show `target`'s children in column 0 (Finder column-view
+   * behavior on double-click), keeping the full tree in `root`.
+   *
+   * - Pass a `MillerNode` (used as-is) or a key (looked up in the full tree).
+   * - Pass `undefined` to restore the full-tree view.
+   * - Rebasing to the true root is equivalent to restoring the full view.
+   * - Leaves are refused (returns `false`).
+   *
+   * Selection is cleared; all depths, headers, and key paths are relative to
+   * the new view root. Fires a `rebase` event when the view actually changes.
+   * Returns `false` when nothing changed (unknown key, leaf, or same view).
+   */
+  rebaseTo(target: TreeNode | string | undefined): boolean;
+  /**
+   * Rebase one level up from the current view root (no-op at the full tree).
+   * Fires a `rebase` event when the view actually changes.
+   */
+  rebaseUp(): boolean;
+  protected renderColumnContent(nodes: TreeNode[], depth: number): TemplateResult | typeof nothing;
+  protected _handleItemClick(node: TreeNode, depth: number, event?: MouseEvent): void;
+  /**
+   * Called by subclasses (in `checked` interactionMode) when a checkbox is clicked.
+   */
+  protected _handleCheckboxClick(event: MouseEvent, node: TreeNode, _depth: number): void;
+  /**
+   * Called by subclasses when an item is double-clicked.
+   */
+  protected _handleItemDblClick(node: TreeNode, depth: number, _event: MouseEvent): void;
+  /**
+   * Called by subclasses when an item is right-clicked.
+   */
+  protected _handleItemRightClick(node: TreeNode, depth: number, event: MouseEvent): void;
+  /**
+   * Called by subclasses when a column header is right-clicked.
+   */
+  protected _handleHeaderRightClick(event: MouseEvent, depth: number): void;
+  protected _isSelected(node: TreeNode, depth: number): boolean;
+  protected _isOpen(node: TreeNode, depth: number): boolean;
+  /**
+   * Return the display state for an item identified by key at a given depth.
+   */
+  getItemState(key: string, depth: number): MillerItemState | undefined;
+  /**
+   * Override to provide a custom loading indicator.
+   */
+  protected renderLoadingIndicator(): TemplateResult | typeof nothing;
+  protected render(): TemplateResult<1>;
+  protected _getFocusedIndex(depth: number): number;
+  protected _isFocused(node: TreeNode, depth: number): boolean;
+  /**
+   * Called by subclasses when pointer enters an item.
+   * Fires tickle event and switches to mouse mode.
+   */
+  protected _handleItemPointerEnter(node: TreeNode, depth: number): void;
+  /**
+   * Called by subclasses when pointer leaves the column container.
+   */
+  protected _handleColumnPointerLeave(): void;
+  static styles: import("lit").CSSResult[];
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    'ixfx-miller-base': MillerBaseElement;
+  }
+}
+interface MillerBaseElementEventMap extends TreeComponentEventMap {
+  'item-click': TreeItemClickEvent;
+  'expand': TreeExpandEvent;
+  'collapse': TreeCollapseEvent;
+  'select': TreeSelectEvent;
+  'tickle': TreeTickleEvent;
+  'activate': TreeActivateEvent;
+  'item-dblclick': CustomEvent<MillerItemDblClickDetail>;
+  'item-rightclick': CustomEvent<MillerItemRightClickDetail>;
+  'header-click': CustomEvent<MillerHeaderClickDetail>;
+  'header-rightclick': CustomEvent<MillerHeaderRightClickDetail>;
+  'rebase': CustomEvent<MillerRebaseDetail>;
+}
+interface MillerBaseElement {
+  addEventListener: (<K extends keyof MillerBaseElementEventMap>(type: K, listener: (this: MillerBaseElement, event: MillerBaseElementEventMap[K]) => void, options?: boolean | AddEventListenerOptions) => void) & ((type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions) => void);
+  removeEventListener: (<K extends keyof MillerBaseElementEventMap>(type: K, listener: (this: MillerBaseElement, event: MillerBaseElementEventMap[K]) => void, options?: boolean | EventListenerOptions) => void) & ((type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions) => void);
+}
+//#endregion
+//#region src/miller/miller-list.d.ts
+/**
+ * Miller columns with a vertical list layout — items stack in rows like macOS Finder.
+ *
+ * Usage:
+ * ```html
+ * <ixfx-miller-list id="miller"></ixfx-miller-list>
+ * <script>
+ *   const el = document.getElementById('miller');
+ *   el.root = { item: { key: 'root', label: 'Root' }, children: [...] };
+ *   el.addEventListener('expand', ({ detail }) => {
+ *     detail.node.children = fetchChildren(detail.node.item.key);
+ *     el.requestUpdate();
+ *   });
+ * </script>
+ * ```
+ */
+declare class MillerListElement extends MillerBaseElement {
+  #private;
+  protected renderColumnContent(nodes: TreeNode[], depth: number): TemplateResult;
+  static styles: import("lit").CSSResult[];
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    'ixfx-miller-list': MillerListElement;
+  }
+}
+//#endregion
+//#region src/miller/miller-tree-controller.d.ts
+type MillerTreeControllerOptions<T> = {
+  /**
+   * Convert a tree node's value to a `MillerItem`.
+   * You must supply at minimum `key` and `label`.
+   * If `isLeaf` is omitted the controller infers it from whether the
+   * `TraversableTree` node has any children.
+   */
+  valueToItem: (value: T, node: TraversableTree<T>) => TreeItem;
+  /**
+   * Children loader installed on the element by `connect()`. Defaults to a
+   * synchronous read from the source tree. `sync()` never touches it.
+   */
+  loadChildren?: LoadChildrenCallback;
+};
+/**
+ * Bridges an `ixfx` `TraversableTree<T>` with an `ixfx-miller-*` component.
+ *
+ * Usage:
+ * ```ts
+ * import { Trees } from '@ixfx/collections';
+ * import { MillerTreeController } from 'ixfx-components/miller';
+ *
+ * const root = Trees.Mutable.createNode({ key: 'root', label: 'Root' });
+ * Trees.Mutable.addValue({ key: 'a', label: 'Alpha' }, root);
+ *
+ * const ctrl = new MillerTreeController(
+ *   Trees.Mutable.asDynamicTraversable(root),
+ *   document.querySelector('ixfx-miller-list'),
+ *   { valueToItem: v => ({ key: v.key, label: v.label }) }
+ * );
+ * ctrl.connect();
+ * ```
+ *
+ * Children are populated lazily: the controller provides a `loadChildren`
+ * callback that synchronously reads from the underlying tree.
+ *
+ * Call `disconnect()` to remove all event listeners and release resources.
+ */
+declare class MillerTreeController<T> {
+  #private;
+  constructor(root: TraversableTree<T>, element: MillerBaseElement, options: MillerTreeControllerOptions<T>);
+  /**
+   * Wire up the controller: sets `element.root` and provides `loadChildren` callback.
+   * Safe to call again after `disconnect()`.
+   */
+  connect(): void;
+  /** Remove all event listeners and release internal state. */
+  disconnect(): void;
+  /**
+   * Navigate the component to the first node (depth-first) in the ixfx tree
+   * whose value satisfies `predicate`.
+   *
+   * Any ancestor `MillerNode`s with unloaded children are populated
+   * synchronously before calling `element.navigateTo()`.
+   *
+   * Key paths are relative to the element's current view root: when the view
+   * is rebased, only matches at or below the view root can be reached.
+   *
+   * Returns `false` if no matching node is found.
+   */
+  navigateToValue(predicate: (value: T) => boolean, options?: TreeNavigateOptions): boolean;
+  /**
+   * Navigate using item keys **relative to the element's current view root**
+   * (the real root when not rebased). Ancestors with unloaded children are
+   * populated first. Returns `false` if a key is missing.
+   */
+  navigateToKeyPath(keys: readonly string[], options?: TreeNavigateOptions): boolean;
+  /**
+   * Navigate to the source node with this identity. Returns `false` when it is
+   * unknown or lies outside a rebased view (keys are relative to the view root).
+   */
+  navigateToIdentity(identity: unknown, options?: TreeNavigateOptions): boolean;
+  /** The source node whose item key is `key`, if it has been materialised. */
+  lookupByKey(key: string): TraversableTree<T> | undefined;
+  /**
+   * Re-derive children for every already-materialised node from the source tree
+   * and patch them in place. Children arrays are mutated (not replaced) so open
+   * columns keep their references, and `MillerNode`s are reused by key so
+   * selection survives. A rebased `viewRoot` is reset only if its node was
+   * removed. `loadChildren` is left alone. Refreshes the element once.
+   */
+  sync(): void;
+}
+//#endregion
+export { MillerRebaseEvent as _, MillerBaseElementEventMap as a, MillerHeaderClickEvent as c, MillerItemDblClickDetail as d, MillerItemDblClickEvent as f, MillerRebaseDetail as g, MillerItemState as h, MillerBaseElement as i, MillerHeaderRightClickDetail as l, MillerItemRightClickEvent as m, MillerTreeControllerOptions as n, MillerListViewState as o, MillerItemRightClickDetail as p, MillerListElement as r, MillerHeaderClickDetail as s, MillerTreeController as t, MillerHeaderRightClickEvent as u, MillerSelectionMode as v };

package/dist/{index-KN2MW_xD.d.ts → index-CUErGhCg.d.ts}

@@ -1,5 +1,5 @@
 import "./icon-CDGprSdE.js";
-import { E as TreeSearchHost } from "./tree-component-C6UHO-w9.js";
+import { E as TreeSearchHost } from "./tree-component-DgfkxmVY.js";
 import { o as TreeNode } from "./types-Jky6oNAp.js";
 import { ReactiveController, ReactiveControllerHost, TemplateResult, nothing } from "lit";
 import { FzfOptions } from "fzf";
@@ -143,7 +143,8 @@ declare class IncrSearchTreeController {
  * - `navigate` — move the cursor to the best match; ↑/↓ cycle between matches;
  *   Enter activates the current match and closes.
  * - `select` — (re)select every item whose label matches, live as you type.
- * - `filter` — hide items that don't match; restored when the popover closes.
+ * - `filter` — hide items that don't match; restored when the popover closes
+ *   (unless `stickyFilter` keeps it on Enter).
  */
 type ListSearchMode = `navigate` | `select` | `filter`;
 /** Canonical order — used for the switch-row and to normalise a requested set. */
@@ -196,6 +197,8 @@ interface ListSearchControllerOptions<TItem> {
   modes?: readonly ListSearchMode[];
   fzf?: Partial<FzfOptions<SearchItem>>;
   placeholder?: string;
+  /** Initial {@link ListSearchController.stickyFilter}. Default false. */
+  stickyFilter?: boolean;
 }
 type ListSearchHost = ReactiveControllerHost & HTMLElement & {
   renderRoot?: DocumentFragment | HTMLElement;
@@ -208,6 +211,12 @@ type ListSearchHost = ReactiveControllerHost & HTMLElement & {
  */
 declare class ListSearchController<TItem> implements ReactiveController {
   #private;
+  /**
+   * When true, Enter in `filter` mode closes the popover but keeps the filter,
+   * shown as a "Filtered: …" chip. Clear it with the chip's ×, Escape on the
+   * host, or {@link clearFilter}; click the chip to edit the query.
+   */
+  stickyFilter: boolean;
   constructor(host: ListSearchHost, options: ListSearchControllerOptions<TItem>);
   /** `false` when no modes are available — the host should register no commands and render no field. */
   get enabled(): boolean;
@@ -225,20 +234,38 @@ declare class ListSearchController<TItem> implements ReactiveController {
   get query(): string;
   get matchCount(): number;
   get matchIndex(): number;
+  /** The query of a filter kept applied after the popover closed (see {@link stickyFilter}). */
+  get keptFilter(): string | undefined;
   hostConnected(): void;
   hostDisconnected(): void;
-  /** Open the popover in `mode` (clamped to the available set). */
+  /**
+   * Open the popover in `mode` (clamped to the available set). When it is
+   * already open the query is kept: the mode switches if it differs and the
+   * input is refocused with its text selected.
+   */
   open(mode: ListSearchMode): void;
   /** Close the popover, restoring any live filter. Selection / cursor stay put. */
   close(): void;
+  /** Remove a filter kept by {@link stickyFilter}. No-op when none is kept. */
+  clearFilter(): void;
   setQuery(query: string): void;
   /** Re-interpret the current query under a new mode (undoing the old mode's effect). */
   switchMode(next: ListSearchMode): void;
+  /**
+   * Step through {@link registeredModes} (wrapping) and switch to the result.
+   * Bound to Tab / Shift+Tab in the popover input.
+   */
+  cycleMode(delta: 1 | -1): void;
+  /** Refocus the popover input (text selected) without touching the query. No-op when closed. */
+  focus(): void;
   /** One-shot: turn the current match set into the selection, staying in the current mode. */
   selectMatches(): void;
   nextMatch(): void;
   prevMatch(): void;
-  /** Enter: in `navigate` activate the current match; then close. */
+  /**
+   * Enter: in `navigate` activate the current match; then close. In `filter`
+   * with {@link stickyFilter} and a query, close but keep the filter.
+   */
   commit(): void;
   /** Rebuild the searchable item set from the adapter. Called on open and on container mutation. */
   refresh(): void;

package/dist/{index-DEVyVIn8.d.ts → index-D-lZNlHa.d.ts}

@@ -1,7 +1,9 @@
-import { A as TreeTickleEvent, C as TreeItemDblClickEvent, E as TreeSearchHost, I as ListDragPreviewRenderer, L as ListDragPreviewSourceResolver, O as TreeSelectEvent, _ as TreeDropTarget, a as TreeComponent, c as TreeDragContext, d as TreeDragStartEvent, h as TreeDropEvent, i as TreeCollapseEvent, j as TreeDataModel, l as TreeDragEndEvent, m as TreeDropDetail, n as TreeActivateEvent, o as TreeComponentEventMap, p as TreeDropContext, s as TreeDndMode, u as TreeDragOverEvent, w as TreeNavigateOptions, x as TreeItemClickEvent, y as TreeExpandEvent, z as ListNativeDragStartDetail } from "./tree-component-C6UHO-w9.js";
+import { B as ListNativeDragStartDetail, C as TreeItemDblClickEvent, D as TreeSelectAllOptions, E as TreeSearchHost, L as ListDragPreviewRenderer, M as TreeDataModel, R as ListDragPreviewSourceResolver, _ as TreeDropTarget, a as TreeComponent, c as TreeDragContext, d as TreeDragStartEvent, h as TreeDropEvent, i as TreeCollapseEvent, j as TreeTickleEvent, k as TreeSelectEvent, l as TreeDragEndEvent, m as TreeDropDetail, n as TreeActivateEvent, o as TreeComponentEventMap, p as TreeDropContext, s as TreeDndMode, u as TreeDragOverEvent, w as TreeNavigateOptions, x as TreeItemClickEvent, y as TreeExpandEvent } from "./tree-component-DgfkxmVY.js";
 import { a as TreeItem, i as TreeInteractionMode, n as TreeExclusivity, o as TreeNode, r as TreeFilterPredicate, s as TreeSelectionFilter, t as LoadChildrenCallback } from "./types-Jky6oNAp.js";
-import { S as ListSearchController } from "./index-KN2MW_xD.js";
-import { t as ListNativeDragController } from "./list-native-drag-controller-O2Nruqpi.js";
+import { a as ViewStateBase, t as GetViewStateOptions } from "./types-LU1u0CB8.js";
+import "./index-9ttcdwlL.js";
+import { S as ListSearchController } from "./index-CUErGhCg.js";
+import { t as ListNativeDragController } from "./list-native-drag-controller-D_UrXipS.js";
 import { n as TickledController } from "./tickled-controller-DodxD3eQ.js";
 import { LitElement, PropertyValues, ReactiveController, ReactiveControllerHost, TemplateResult, nothing } from "lit";
 import { CommandRegistry } from "@clinth/ui-commands";
@@ -12,6 +14,10 @@ type TreeConfig = {
   indent: number;
 };
 //#endregion
+//#region src/tree/tree-view-state.d.ts
+/** `ixfx-tree-list` view state. All fields are the shared base fields. */
+type TreeListViewState = ViewStateBase;
+//#endregion
 //#region src/tree/tree-base.d.ts
 /**
  * `auto` windows the list once it has more than `virtualizeThreshold` visible
@@ -40,6 +46,13 @@ declare class TreeBaseElement extends LitElement implements TreeComponent, TreeS
   get selectedNodes(): ReadonlySet<TreeNode>;
   filterPredicate: TreeFilterPredicate | undefined;
   disableKeyboardNavigation: boolean;
+  /**
+   * Let hover follow rows that scroll beneath a stationary pointer. Off by
+   * default: while a scroll gesture is active, row `pointerenter` is ignored so
+   * the hover cursor holds still instead of trailing the content. Hover resumes
+   * on the next real pointer movement, or when the pointer leaves the tree.
+   */
+  scrollHoverTickle: boolean;
   registry: CommandRegistry<unknown> | undefined;
   /**
    * Space-separated subset of `navigate select filter` — limits which
@@ -89,6 +102,12 @@ declare class TreeBaseElement extends LitElement implements TreeComponent, TreeS
   applyInternalDrop: boolean;
   /** Immutable: replace via `#setExpanded` so the flat-row cache is invalidated. */
   protected _expandedKeys: ReadonlySet<string>;
+  /**
+   * Whether restoring view state may call `loadChildren` / `model` to open
+   * saved branches that aren't loaded yet (one at a time, cascading down the
+   * saved path). Default `true`.
+   */
+  restoreLoads: boolean;
   /** Bumped whenever `_selectedNodes` content may have changed. */
   protected _selectionVersion: number;
   /**
@@ -103,6 +122,13 @@ declare class TreeBaseElement extends LitElement implements TreeComponent, TreeS
   /** Depths at which any loaded node carries an icon (stable across expansion). */
   protected get _depthsWithIcons(): ReadonlySet<number>;
   protected tickled: TickledController<string>;
+  /**
+   * Row `pointerenter` funnel: moves the hover cursor unless a scroll gesture
+   * is sliding rows beneath a stationary pointer (see `scrollHoverTickle`).
+   * Subclasses rendering their own rows should call this rather than the
+   * tickled controller directly.
+   */
+  protected _handleRowPointerEnter(node: TreeNode, depth: number): void;
   protected _focusedDepth: number;
   /** Incremental search (navigate / select / filter). See `docs/infra-incremental.md`. */
   readonly search: ListSearchController<{
@@ -132,11 +158,31 @@ declare class TreeBaseElement extends LitElement implements TreeComponent, TreeS
   disconnectedCallback(): void;
   getConfig(): TreeConfig;
   setConfig(config: Partial<TreeConfig>): void;
+  /**
+   * Snapshot selection, expansion, cursor and scroll as plain JSON, keyed by
+   * `item.key`. Includes pending state for keys not currently loaded.
+   */
+  getViewState(options?: GetViewStateOptions<TreeListViewState>): TreeListViewState;
+  /**
+   * Apply saved view state. Fields present replace the current ones; keys
+   * that aren't loaded yet are applied as they appear — including via
+   * `loadChildren` / `model` for saved-open branches when `restoreLoads`.
+   */
+  setViewState(state: Partial<TreeListViewState>): void;
+  clearPendingViewState(): void;
   select(node: TreeNode): void;
   deselect(node: TreeNode): void;
   clearSelection(): void;
-  selectAll(): void;
-  deselectAll(): void;
+  /**
+   * Select every selectable node in the tree, or only the matches while a
+   * `filterPredicate` is active. Nodes inside collapsed branches are included;
+   * unloaded (lazy) children are not. With `visibleOnly`, only rows that are
+   * showing are selected (Ctrl+A). In `checked` mode checking a row checks its
+   * descendants, so `visibleOnly` makes no difference there.
+   */
+  selectAll(options?: TreeSelectAllOptions): void;
+  /** Mirror of {@link selectAll}: deselect the same set of nodes it would select. */
+  deselectAll(options?: TreeSelectAllOptions): void;
   /**
    * Expand every already-loaded branch in a single update. With `maxDepth`,
    * only branches at depth < `maxDepth` are expanded (the root's children are
@@ -378,4 +424,4 @@ declare class TreeDropController implements ReactiveController {
   hostDisconnected(): void;
 }
 //#endregion
-export { TreeDropVisibleRow as a, TreeListElement as c, TreeBaseElement as d, TreeBaseElementEventMap as f, TreeDropRowInfo as i, TreeCheckboxState as l, TreeConfig as m, TreeDropControllerConfig as n, TreeController as o, TreeVirtualize as p, TreeDropResolvedDrag as r, TreeControllerOptions as s, TreeDropController as t, TreeAnimation as u };
+export { TreeDropVisibleRow as a, TreeListElement as c, TreeBaseElement as d, TreeBaseElementEventMap as f, TreeConfig as h, TreeDropRowInfo as i, TreeCheckboxState as l, TreeListViewState as m, TreeDropControllerConfig as n, TreeController as o, TreeVirtualize as p, TreeDropResolvedDrag as r, TreeControllerOptions as s, TreeDropController as t, TreeAnimation as u };