@ixfx/components 0.15.4 → 0.16.0

package/dist/miller.d.ts

@@ -1,437 +1,4 @@
-import { A as TreeTickleEvent, D as TreeSelectDetail, E as TreeSearchHost, O as TreeSelectEvent, a as TreeComponent, b as TreeItemClickDetail, i as TreeCollapseEvent, j as TreeDataModel, k as TreeTickleDetail, n as TreeActivateEvent, o as TreeComponentEventMap, r as TreeCollapseDetail, t as TreeActivateDetail, v as TreeExpandDetail, w as TreeNavigateOptions, x as TreeItemClickEvent, y as TreeExpandEvent } from "./tree-component-C6UHO-w9.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 { S as ListSearchController } from "./index-BPTuCRGb.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`;
-type MillerConfig = {
-  columnWidths: Record<number, number>;
-};
-/** 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-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>;
-  /** 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>;
-  updated(changedProps: PropertyValues): void;
-  connectedCallback(): void;
-  disconnectedCallback(): void;
-  getConfig(): MillerConfig;
-  setConfig(config: MillerConfig): 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 { type TreeActivateDetail as MillerActivateDetail, type TreeActivateEvent as MillerActivateEvent, MillerBaseElement, MillerBaseElementEventMap, type TreeCollapseDetail as MillerCollapseDetail, type TreeCollapseEvent as MillerCollapseEvent, MillerConfig, type TreeExpandDetail as MillerExpandDetail, type TreeExpandEvent as MillerExpandEvent, MillerHeaderClickDetail, MillerHeaderClickEvent, MillerHeaderRightClickDetail, MillerHeaderRightClickEvent, type TreeItem as MillerItem, type TreeItemClickDetail as MillerItemClickDetail, type TreeItemClickEvent as MillerItemClickEvent, MillerItemDblClickDetail, MillerItemDblClickEvent, MillerItemRightClickDetail, MillerItemRightClickEvent, MillerItemState, MillerListElement, type TreeNode as MillerNode, MillerRebaseDetail, MillerRebaseEvent, type TreeSelectDetail as MillerSelectDetail, type TreeSelectEvent as MillerSelectEvent, MillerSelectionMode, type TreeTickleDetail as MillerTickleDetail, type TreeTickleEvent as MillerTickleEvent, MillerTreeController, MillerTreeControllerOptions };
+import { A as TreeTickleDetail, O as TreeSelectDetail, b as TreeItemClickDetail, i as TreeCollapseEvent, j as TreeTickleEvent, k as TreeSelectEvent, n as TreeActivateEvent, r as TreeCollapseDetail, t as TreeActivateDetail, v as TreeExpandDetail, x as TreeItemClickEvent, y as TreeExpandEvent } from "./tree-component-DgfkxmVY.js";
+import { a as TreeItem, o as TreeNode } from "./types-Jky6oNAp.js";
+import { _ as MillerRebaseEvent, a as MillerBaseElementEventMap, c as MillerHeaderClickEvent, d as MillerItemDblClickDetail, f as MillerItemDblClickEvent, g as MillerRebaseDetail, h as MillerItemState, i as MillerBaseElement, l as MillerHeaderRightClickDetail, m as MillerItemRightClickEvent, n as MillerTreeControllerOptions, o as MillerListViewState, p as MillerItemRightClickDetail, r as MillerListElement, s as MillerHeaderClickDetail, t as MillerTreeController, u as MillerHeaderRightClickEvent, v as MillerSelectionMode } from "./index-CYRc6Dah.js";
+export { type TreeActivateDetail as MillerActivateDetail, type TreeActivateEvent as MillerActivateEvent, MillerBaseElement, MillerBaseElementEventMap, type TreeCollapseDetail as MillerCollapseDetail, type TreeCollapseEvent as MillerCollapseEvent, type TreeExpandDetail as MillerExpandDetail, type TreeExpandEvent as MillerExpandEvent, MillerHeaderClickDetail, MillerHeaderClickEvent, MillerHeaderRightClickDetail, MillerHeaderRightClickEvent, type TreeItem as MillerItem, type TreeItemClickDetail as MillerItemClickDetail, type TreeItemClickEvent as MillerItemClickEvent, MillerItemDblClickDetail, MillerItemDblClickEvent, MillerItemRightClickDetail, MillerItemRightClickEvent, MillerItemState, MillerListElement, type MillerListViewState, type TreeNode as MillerNode, MillerRebaseDetail, MillerRebaseEvent, type TreeSelectDetail as MillerSelectDetail, type TreeSelectEvent as MillerSelectEvent, MillerSelectionMode, type TreeTickleDetail as MillerTickleDetail, type TreeTickleEvent as MillerTickleEvent, MillerTreeController, MillerTreeControllerOptions };