@rivetjs/cdk 0.0.0-stage → 0.1.0-alpha.0

package/tree/control.js

@@ -0,0 +1,166 @@
+// Ported from Angular CDK tree (src/cdk/tree/control/tree-control.ts, base-tree-control.ts,
+// flat-tree-control.ts, nested-tree-control.ts), MIT, © Google LLC.
+//
+// Tree controls (deprecated upstream in favour of `levelAccessor` / `childrenAccessor`, still public):
+// expansion state of a tree's data nodes in a multi-selection `SelectionModel`, with recursive
+// expand / collapse for flat (level-based) and nested (children-based) trees.
+// Rivet:
+// - `Observable<T[]>` children → any subscribable (`{ subscribe(fn) }`); RxJS `take(1)` +
+//   `filter(Boolean)` → the first truthy emission only.
+// - Constructor parameter properties → explicit fields (strip-only TypeScript).
+import { SelectionModel } from "../collections/selection-model.js";
+const isSubscribable = (value) => value != null && typeof value === "object" && typeof value.subscribe === "function";
+/**
+ * Base tree control. It has basic toggle/expand/collapse operations on a single data node.
+ *
+ * @deprecated Use one of levelAccessor or childrenAccessor.
+ */
+export class BaseTreeControl {
+    /** Saved data node for `expandAll` action. */
+    dataNodes;
+    /** A selection model with multi-selection to track expansion status. */
+    expansionModel = new SelectionModel(true);
+    /** Returns the identifier by which a dataNode should be tracked, should its reference change. */
+    trackBy;
+    /** Get depth of a given data node, return the level number. This is for flat tree node. */
+    getLevel;
+    /** Whether the data node is expandable. Returns true if expandable. This is for flat tree node. */
+    isExpandable;
+    /** Gets a stream that emits whenever the given data node's children change. */
+    getChildren;
+    /** Toggles one single data node's expanded/collapsed state. */
+    toggle(dataNode) {
+        this.expansionModel.toggle(this._trackByValue(dataNode));
+    }
+    /** Expands one single data node. */
+    expand(dataNode) {
+        this.expansionModel.select(this._trackByValue(dataNode));
+    }
+    /** Collapses one single data node. */
+    collapse(dataNode) {
+        this.expansionModel.deselect(this._trackByValue(dataNode));
+    }
+    /** Whether a given data node is expanded or not. Returns true if the data node is expanded. */
+    isExpanded(dataNode) {
+        return this.expansionModel.isSelected(this._trackByValue(dataNode));
+    }
+    /** Toggles a subtree rooted at `node` recursively. */
+    toggleDescendants(dataNode) {
+        if (this.expansionModel.isSelected(this._trackByValue(dataNode)))
+            this.collapseDescendants(dataNode);
+        else
+            this.expandDescendants(dataNode);
+    }
+    /** Collapse all dataNodes in the tree. */
+    collapseAll() {
+        this.expansionModel.clear();
+    }
+    /** Expands a subtree rooted at given data node recursively. */
+    expandDescendants(dataNode) {
+        const toBeProcessed = [dataNode];
+        toBeProcessed.push(...this.getDescendants(dataNode));
+        this.expansionModel.select(...toBeProcessed.map((value) => this._trackByValue(value)));
+    }
+    /** Collapses a subtree rooted at given data node recursively. */
+    collapseDescendants(dataNode) {
+        const toBeProcessed = [dataNode];
+        toBeProcessed.push(...this.getDescendants(dataNode));
+        this.expansionModel.deselect(...toBeProcessed.map((value) => this._trackByValue(value)));
+    }
+    _trackByValue(value) {
+        return this.trackBy ? this.trackBy(value) : value;
+    }
+}
+/**
+ * Flat tree control. Able to expand/collapse a subtree recursively for flattened tree.
+ *
+ * @deprecated Use one of levelAccessor or childrenAccessor instead.
+ */
+export class FlatTreeControl extends BaseTreeControl {
+    options;
+    /** Construct with flat tree data node functions getLevel and isExpandable. */
+    constructor(getLevel, isExpandable, options) {
+        super();
+        this.getLevel = getLevel;
+        this.isExpandable = isExpandable;
+        this.options = options;
+        if (this.options)
+            this.trackBy = this.options.trackBy;
+    }
+    /**
+     * Gets a list of the data node's subtree of descendent data nodes. The `dataNodes` of the
+     * TreeControl must be flattened tree nodes with correct levels.
+     */
+    getDescendants(dataNode) {
+        const startIndex = this.dataNodes.indexOf(dataNode);
+        const results = [];
+        // Descendants have a greater level than the node; an equal level is a sibling, a smaller one a
+        // sibling of an ancestor.
+        for (let i = startIndex + 1; i < this.dataNodes.length && this.getLevel(dataNode) < this.getLevel(this.dataNodes[i]); i++) {
+            results.push(this.dataNodes[i]);
+        }
+        return results;
+    }
+    /** Expands all data nodes in the tree (`dataNodes` must be all flattened data nodes). */
+    expandAll() {
+        this.expansionModel.select(...this.dataNodes.map((node) => this._trackByValue(node)));
+    }
+}
+/**
+ * Nested tree control. Able to expand/collapse a subtree recursively for NestedNode type.
+ *
+ * @deprecated Use one of levelAccessor or childrenAccessor instead.
+ */
+export class NestedTreeControl extends BaseTreeControl {
+    options;
+    /** Construct with nested tree function getChildren. */
+    constructor(getChildren, options) {
+        super();
+        this.getChildren = getChildren;
+        this.options = options;
+        if (this.options)
+            this.trackBy = this.options.trackBy;
+        if (this.options?.isExpandable)
+            this.isExpandable = this.options.isExpandable;
+    }
+    /** Expands all dataNodes in the tree (`dataNodes` must be all root level data nodes). */
+    expandAll() {
+        this.expansionModel.clear();
+        const allNodes = this.dataNodes.reduce((accumulator, dataNode) => [...accumulator, ...this.getDescendants(dataNode), dataNode], []);
+        this.expansionModel.select(...allNodes.map((node) => this._trackByValue(node)));
+    }
+    /** Gets a list of descendant dataNodes of a subtree rooted at given data node recursively. */
+    getDescendants(dataNode) {
+        const descendants = [];
+        this._getDescendants(descendants, dataNode);
+        // Remove the node itself
+        return descendants.splice(1);
+    }
+    /** A helper function to get descendants recursively. */
+    _getDescendants(descendants, dataNode) {
+        descendants.push(dataNode);
+        const childrenNodes = this.getChildren(dataNode);
+        if (Array.isArray(childrenNodes)) {
+            childrenNodes.forEach((child) => this._getDescendants(descendants, child));
+        }
+        else if (isSubscribable(childrenNodes)) {
+            // take(1) + filter(Boolean): the first truthy emission.
+            let done = false;
+            let sync = true;
+            let subscription = undefined;
+            const unsubscribe = () => (typeof subscription === "function" ? subscription() : subscription?.unsubscribe());
+            subscription = childrenNodes.subscribe((children) => {
+                if (done || !children)
+                    return;
+                done = true;
+                if (!sync)
+                    unsubscribe();
+                for (const child of children)
+                    this._getDescendants(descendants, child);
+            });
+            sync = false;
+            if (done)
+                unsubscribe();
+        }
+    }
+}

package/tree/index.d.ts

@@ -0,0 +1,154 @@
+import { type CollectionProps, type SectionProps } from "../collections/components.jsx";
+import { type TreeState } from "../collections/tree-state.js";
+import type { DisabledBehavior, Key, Selection, SelectionBehavior, SelectionMode } from "../collections/types.js";
+import type { Signal } from "@rivetjs/reactivity";
+import { type ContextValue, type RefValue, type RenderProps, type SlotProps, type StyleRenderProps } from "../slots/index.jsx";
+import { type GlobalDOMAttributes } from "../utils/dom-props.js";
+import { type DOMRenderProps } from "../utils/render.js";
+import { type LoadMoreSentinelProps } from "../utils/load-more-sentinel.jsx";
+import type { HoverEvents } from "../utils/types.js";
+import { type LinkDOMProps } from "../utils/links.jsx";
+import { type GridListHeaderProps } from "../grid-list/index.jsx";
+import { type AriaTreeItemOptions, type AriaTreeOptions } from "./behaviour.jsx";
+export { TreeCollection } from "./collection.js";
+export type { TreeState } from "../collections/tree-state.js";
+type MaybeAccessor<T> = T | (() => T);
+/** Render props of `Tree` (accessors; `@selector` = the matching attribute). */
+export interface TreeRenderProps {
+    /** Whether the tree has no items and should display its empty state. @selector [data-empty] */
+    isEmpty: () => boolean;
+    /** Whether the tree is currently focused. @selector [data-focused] */
+    isFocused: () => boolean;
+    /** Whether the tree is currently keyboard focused. @selector [data-focus-visible] */
+    isFocusVisible: () => boolean;
+    /** The type of selection that is allowed in the collection. @selector [data-selection-mode="single | multiple"] */
+    selectionMode: () => SelectionMode;
+    /** Whether the tree allows dragging. @selector [data-allows-dragging] */
+    allowsDragging: () => boolean;
+    /** Whether the tree is currently the active drop target. @selector [data-drop-target] */
+    isDropTarget: () => boolean;
+    /** State of the tree. */
+    state: TreeState<unknown>;
+}
+export interface TreeEmptyStateRenderProps extends Omit<TreeRenderProps, "isEmpty"> {
+}
+export interface TreeProps<T> extends Omit<AriaTreeOptions, "ref" | "keyboardDelegate" | "layoutDelegate" | "isVirtualized" | "descriptionId" | "getRowText" | "disabledBehavior">, CollectionProps<T>, StyleRenderProps<TreeRenderProps>, DOMRenderProps<"div", TreeRenderProps>, SlotProps, GlobalDOMAttributes<HTMLDivElement> {
+    /** The type of selection that is allowed in the collection. Default "none". */
+    selectionMode?: SelectionMode | undefined;
+    /** How multiple selection should behave in the tree. Default "toggle". */
+    selectionBehavior?: SelectionBehavior | undefined;
+    /** The currently selected keys: a plain value (controlled) or a Signal (two-way). */
+    selectedKeys?: Signal<Selection> | "all" | Iterable<Key> | undefined;
+    /** The initial selected keys (uncontrolled). */
+    defaultSelectedKeys?: "all" | Iterable<Key> | undefined;
+    /** Handler that is called when the selection changes. */
+    onSelectionChange?: ((keys: Selection) => void) | undefined;
+    /** Whether the collection allows empty selection. */
+    disallowEmptySelection?: boolean | undefined;
+    /** The item keys that are disabled. */
+    disabledKeys?: Iterable<Key> | undefined;
+    /** Whether `disabledKeys` applies to all interactions, or only selection. Default "all". */
+    disabledBehavior?: DisabledBehavior | undefined;
+    /** The currently expanded keys: a plain value (controlled) or a Signal (two-way). */
+    expandedKeys?: Signal<Set<Key>> | Iterable<Key> | undefined;
+    /** The initial expanded keys (uncontrolled). */
+    defaultExpandedKeys?: Iterable<Key> | undefined;
+    /** Handler that is called when items are expanded or collapsed. */
+    onExpandedChange?: ((keys: Set<Key>) => void) | undefined;
+    /** Provides content to display when there are no items in the tree. */
+    renderEmptyState?: ((props: TreeEmptyStateRenderProps) => unknown) | undefined;
+    ref?: RefValue<HTMLDivElement> | undefined;
+}
+/** RAC `TreeContext`: props for the Trees inside a component, optionally per `slot`. */
+export declare const TreeContext: import("@rivetjs/reactivity").Context<ContextValue<TreeProps<any>, HTMLDivElement>>;
+/** RAC `TreeStateContext`: the state of the enclosing Tree. */
+export declare const TreeStateContext: import("@rivetjs/reactivity").Context<TreeState<any> | null>;
+/**
+ * A tree provides users with a way to navigate nested hierarchical information, with support for
+ * keyboard navigation and selection.
+ */
+export declare function Tree<T>(inProps: TreeProps<T>): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+/** Render props of `TreeItem` / `TreeItemContent` (accessors; `@selector` = the matching attribute). */
+export interface TreeItemRenderProps {
+    /** @selector [data-hovered] */
+    isHovered: () => boolean;
+    /** @selector [data-pressed] */
+    isPressed: () => boolean;
+    /** @selector [data-selected] */
+    isSelected: () => boolean;
+    /** @selector [data-focused] */
+    isFocused: () => boolean;
+    /** @selector [data-focus-visible] */
+    isFocusVisible: () => boolean;
+    /** @selector [data-disabled] */
+    isDisabled: () => boolean;
+    /** @selector [data-selection-mode="single | multiple"] */
+    selectionMode: () => SelectionMode;
+    selectionBehavior: () => SelectionBehavior;
+    /** @selector [data-allows-dragging] */
+    allowsDragging: () => boolean;
+    /** @selector [data-dragging] */
+    isDragging: () => boolean;
+    /** @selector [data-drop-target] */
+    isDropTarget: () => boolean;
+    /** Whether the tree item is expanded. @selector [data-expanded] */
+    isExpanded: () => boolean;
+    /** Whether the tree item has child tree items. @selector [data-has-child-items] */
+    hasChildItems: () => boolean;
+    /** What level the tree item has within the tree. @selector [data-level="number"] */
+    level: () => number;
+    /** Whether the tree item's children have keyboard focus. @selector [data-focus-visible-within] */
+    isFocusVisibleWithin: () => boolean;
+    /** The state of the tree. */
+    state: TreeState<unknown>;
+    /** The unique id of the tree row. */
+    id: Key;
+}
+export interface TreeItemContentRenderProps extends TreeItemRenderProps {
+}
+/** RAC `TreeItemContentContext`: the render props of the enclosing TreeItem. */
+export declare const TreeItemContentContext: import("@rivetjs/reactivity").Context<TreeItemContentRenderProps | null>;
+export interface TreeItemContentProps {
+    /** The children of the component. A function may be provided to alter the children based on component state. */
+    children: RenderProps<TreeItemContentRenderProps>["children"];
+}
+/** The content of a TreeItem (everything but its child rows); children may be a function of the item's render props. */
+export declare const TreeItemContent: (props: TreeItemContentProps) => unknown;
+export interface TreeItemProps<T = object> extends StyleRenderProps<TreeItemRenderProps>, DOMRenderProps<"div", TreeItemRenderProps>, LinkDOMProps, HoverEvents, Pick<AriaTreeItemOptions, "hasChildItems" | "focusMode" | "allowsArrowNavigation">, Omit<GlobalDOMAttributes<HTMLDivElement>, "onClick"> {
+    /** The unique id of the tree row. */
+    id?: Key | undefined;
+    /** The object value that this tree item represents. When using dynamic collections, this is set automatically. */
+    value?: T | undefined;
+    /** A string representation of the tree item's contents, used for features like typeahead. */
+    textValue: string;
+    /** An accessibility label for this tree item. */
+    "aria-label"?: string | undefined;
+    /** The content of the tree item along with any nested children (TreeItemContent, TreeItems, Collection). */
+    children: unknown;
+    /** Whether the item is disabled. */
+    isDisabled?: boolean | undefined;
+    /** Handler that is called when a user performs an action on this tree item. */
+    onAction?: (() => void) | undefined;
+    ref?: RefValue<HTMLDivElement> | undefined;
+}
+/** A TreeItem represents an individual item in a Tree. */
+export declare const TreeItem: <T>(props: TreeItemProps<T>) => unknown;
+export interface TreeLoadMoreItemRenderProps {
+    /** What level the tree item has within the tree. @selector [data-level] */
+    level: () => number;
+}
+export interface TreeLoadMoreItemProps extends Omit<LoadMoreSentinelProps, "collection" | "direction">, RenderProps<TreeLoadMoreItemRenderProps> {
+    /** Whether or not the loading spinner should be rendered (a value or an accessor). */
+    isLoading?: MaybeAccessor<boolean | undefined>;
+}
+/** A sentinel row: calls `onLoadMore` when scrolled near, and renders its children while `isLoading`. */
+export declare const TreeLoadMoreItem: (props: TreeLoadMoreItemProps) => unknown;
+export interface TreeSectionProps<T> extends SectionProps<T>, DOMRenderProps<"div", undefined>, Omit<GlobalDOMAttributes<HTMLDivElement>, "style" | `data-${string}`> {
+    ref?: RefValue<HTMLDivElement> | undefined;
+}
+/** A TreeSection represents a section within a Tree. */
+export declare const TreeSection: <T>(props: TreeSectionProps<T>) => unknown;
+export interface TreeHeaderProps extends GridListHeaderProps {
+}
+/** The header of a TreeSection (a GridListHeader with class `rv-TreeHeader`). */
+export declare const TreeHeader: (props: TreeHeaderProps) => unknown;