@proyecto-viviana/solid-stately 0.3.0 → 0.4.0

package/src/table/createTreeGridState.ts

@@ -0,0 +1,146 @@
+/**
+ * Tree grid state management for expandable Table rows.
+ * Based on @react-stately/table/useTreeGridState (the `UNSTABLE_` tree-grid feature).
+ *
+ * Owns the expanded-keys signal (controlled or uncontrolled), rebuilds the table
+ * collection from it, and layers the expansion API on top of {@link createTableState}.
+ */
+
+import { createMemo, createSignal, type Accessor } from "solid-js";
+import { createTableState } from "./createTableState";
+import { createTableCollection, TableCollection } from "./TableCollection";
+import type { Key } from "../collections/types";
+import type { TreeGridState, TreeGridStateOptions } from "./types";
+
+/**
+ * Creates state management for a tree grid (a table with expandable rows). Handles the
+ * expanded rows in addition to the selection, sort and focus handled by the table state.
+ */
+export function createTreeGridState<
+  T extends object,
+  C extends TableCollection<T> = TableCollection<T>,
+>(options: Accessor<TreeGridStateOptions<T, C>>): TreeGridState<T, C> {
+  const getOptions = () => options();
+
+  // Expanded keys: controlled via `UNSTABLE_expandedKeys`, otherwise the internal signal
+  // seeded from `UNSTABLE_defaultExpandedKeys`.
+  const [internalExpandedKeys, setInternalExpandedKeys] = createSignal<"all" | Set<Key>>(
+    getInitialExpanded(getOptions().UNSTABLE_defaultExpandedKeys),
+  );
+
+  const expandedKeys = createMemo<"all" | Set<Key>>(() => {
+    const controlled = getOptions().UNSTABLE_expandedKeys;
+    if (controlled !== undefined) {
+      return convertExpanded(controlled);
+    }
+    return internalExpandedKeys();
+  });
+
+  // Rebuild the tree collection whenever the expanded keys (or the data) change.
+  const collection = createMemo(
+    () =>
+      createTableCollection<T>({
+        columns: getOptions().columns,
+        rows: getOptions().rows,
+        getKey: getOptions().getKey,
+        getTextValue: getOptions().getTextValue,
+        showSelectionCheckboxes: getOptions().showSelectionCheckboxes ?? false,
+        rowHeaderColumnKeys: getOptions().rowHeaderColumnKeys,
+        expandedKeys: expandedKeys(),
+      }) as unknown as C,
+  );
+
+  const tableState = createTableState<T, C>(() => ({
+    collection: collection(),
+    disabledKeys: getOptions().disabledKeys,
+    focusMode: getOptions().focusMode,
+    selectionMode: getOptions().selectionMode,
+    selectionBehavior: getOptions().selectionBehavior,
+    disallowEmptySelection: getOptions().disallowEmptySelection,
+    selectedKeys: getOptions().selectedKeys,
+    defaultSelectedKeys: getOptions().defaultSelectedKeys,
+    onSelectionChange: getOptions().onSelectionChange,
+    sortDescriptor: getOptions().sortDescriptor,
+    onSortChange: getOptions().onSortChange,
+    showSelectionCheckboxes: getOptions().showSelectionCheckboxes,
+  }));
+
+  const toggleKey = (key: Key) => {
+    const updated = toggleExpandedKey(expandedKeys(), key, collection());
+
+    // Only own the value when uncontrolled.
+    if (getOptions().UNSTABLE_expandedKeys === undefined) {
+      setInternalExpandedKeys(updated);
+    }
+    getOptions().UNSTABLE_onExpandedChange?.(updated);
+  };
+
+  // Layer the expansion API onto the table state object, preserving the reactive getters
+  // already defined on it (spreading would eagerly evaluate them and break reactivity).
+  const treeGridState = tableState as TreeGridState<T, C>;
+  Object.defineProperty(treeGridState, "expandedKeys", {
+    get: () => expandedKeys(),
+    configurable: true,
+    enumerable: true,
+  });
+  Object.defineProperty(treeGridState, "treeColumn", {
+    get: () => collection().treeColumn ?? null,
+    configurable: true,
+    enumerable: true,
+  });
+  Object.defineProperty(treeGridState, "keyMap", {
+    get: () => collection().keyMap,
+    configurable: true,
+    enumerable: true,
+  });
+  Object.defineProperty(treeGridState, "userColumnCount", {
+    get: () => collection().userColumnCount,
+    configurable: true,
+    enumerable: true,
+  });
+  treeGridState.toggleKey = toggleKey;
+
+  return treeGridState;
+}
+
+/**
+ * Computes the next expanded-key set when a row is toggled. Mirrors the upstream
+ * `toggleKey`: collapsing from `'all'` materialises every expandable row first.
+ */
+function toggleExpandedKey<T>(
+  current: "all" | Set<Key>,
+  key: Key,
+  collection: TableCollection<T>,
+): Set<Key> {
+  let updated: Set<Key>;
+  if (current === "all") {
+    updated = new Set(
+      collection.rows
+        .filter((row) => row.type === "item" && row.isExpandable)
+        .map((row) => row.key),
+    );
+    updated.delete(key);
+  } else {
+    updated = new Set(current);
+    if (updated.has(key)) {
+      updated.delete(key);
+    } else {
+      updated.add(key);
+    }
+  }
+  return updated;
+}
+
+function getInitialExpanded(defaultExpanded?: "all" | Iterable<Key>): "all" | Set<Key> {
+  if (defaultExpanded === undefined) {
+    return new Set();
+  }
+  return convertExpanded(defaultExpanded);
+}
+
+function convertExpanded(expanded: "all" | Iterable<Key>): "all" | Set<Key> {
+  if (!expanded) {
+    return new Set<Key>();
+  }
+  return expanded === "all" ? "all" : new Set(expanded);
+}

package/src/table/index.ts

@@ -4,12 +4,15 @@
  */
 
 export { createTableState } from "./createTableState";
+export { createTreeGridState } from "./createTreeGridState";
 export { createTableColumnResizeState } from "./createTableColumnResizeState";
 export { TableCollection, createTableCollection } from "./TableCollection";
 export type {
   TableState,
   TableStateOptions,
   TableCollection as ITableCollection,
+  TreeGridState,
+  TreeGridStateOptions,
   SortDescriptor,
   SortDirection,
   Sortable,

package/src/table/types.ts

@@ -46,6 +46,8 @@ export interface TableCollection<T = unknown> extends GridCollection<T> {
   readonly head?: GridNode<T>;
   /** The node that makes up the body of the table. */
   readonly body: GridNode<T>;
+  /** The key of the column that renders the tree-grid expand/collapse affordance, if any. */
+  readonly treeColumn?: Key | null;
 }
 
 /**
@@ -64,6 +66,59 @@ export interface TableState<T, C extends TableCollection<T> = TableCollection<T>
   readonly sortDescriptor: SortDescriptor | null;
   /** Sort by the given column and direction. */
   sort(columnKey: Key, direction?: SortDirection): void;
+  /**
+   * The set of expanded row keys for tree grids. A plain table reports an empty set.
+   */
+  readonly expandedKeys: "all" | Set<Key>;
+  /**
+   * The key of the column that renders the expand/collapse affordance, or `null` for a
+   * plain (non-tree) table.
+   */
+  readonly treeColumn: Key | null;
+  /** Toggles the expanded state of a row by its key (no-op for a plain table). */
+  toggleKey(key: Key): void;
+}
+
+/**
+ * State for a tree grid (expandable rows). Mirrors `@react-stately/table`'s
+ * `UNSTABLE_useTreeGridState` return value.
+ */
+export interface TreeGridState<
+  T,
+  C extends TableCollection<T> = TableCollection<T>,
+> extends TableState<T, C> {
+  /** A set of keys for rows that are expanded. */
+  readonly expandedKeys: "all" | Set<Key>;
+  /** The key map containing nodes representing the collection's tree grid structure. */
+  readonly keyMap: Map<Key, GridNode<T>>;
+  /** The number of leaf columns provided by the user (excludes selection/drag columns). */
+  readonly userColumnCount: number;
+}
+
+/**
+ * Options for creating tree grid state. Mirrors `TreeGridStateProps` upstream; the
+ * expansion props keep the `UNSTABLE_` prefix while the feature is unstable.
+ */
+export interface TreeGridStateOptions<
+  T,
+  C extends TableCollection<T> = TableCollection<T>,
+> extends Omit<TableStateOptions<T, C>, "collection"> {
+  /** Column definitions. */
+  columns: ColumnDefinition<T>[];
+  /** Row definitions (may contain `childRows` for nested rows). */
+  rows: RowDefinition<T>[];
+  /** Function to get the key from a data item. */
+  getKey?: (item: T) => Key;
+  /** Function to get the text value from a data item. */
+  getTextValue?: (item: T, column: ColumnDefinition<T>) => string;
+  /** Set of column keys that serve as row headers. */
+  rowHeaderColumnKeys?: Set<Key>;
+  /** The currently expanded keys in the collection (controlled). */
+  UNSTABLE_expandedKeys?: "all" | Iterable<Key>;
+  /** The initial expanded keys in the collection (uncontrolled). */
+  UNSTABLE_defaultExpandedKeys?: "all" | Iterable<Key>;
+  /** Handler that is called when rows are expanded or collapsed. */
+  UNSTABLE_onExpandedChange?: (keys: Set<Key>) => void;
 }
 
 /**
@@ -77,6 +132,8 @@ export interface TableStateOptions<
   collection: C;
   /** Keys of disabled rows. */
   disabledKeys?: Iterable<Key>;
+  /** Whether `disabledKeys` applies to all interactions, or only selection. @default "all" */
+  disabledBehavior?: "selection" | "all";
   /** Focus mode: 'row' or 'cell'. */
   focusMode?: "row" | "cell";
   /** Selection mode. */
@@ -151,4 +208,13 @@ export interface TableCollectionOptions<T = unknown> {
   showSelectionCheckboxes?: boolean;
   /** Set of column keys that serve as row headers. */
   rowHeaderColumnKeys?: Set<Key>;
+  /**
+   * The set of expanded row keys. Passing this (even an empty set) builds the collection
+   * in tree-grid mode: `childRows` are walked recursively, only rows whose ancestors are
+   * all expanded are flattened into the navigable body, and {@link TableCollection.treeColumn}
+   * resolves to a real column. Omit it for a plain (non-tree) table.
+   */
+  expandedKeys?: "all" | Set<Key>;
+  /** Explicit tree column key. Defaults to the first row-header column in tree-grid mode. */
+  treeColumn?: Key | null;
 }

package/src/tabs/createTabListState.ts

@@ -199,17 +199,19 @@ export function createTabListState<T = unknown>(
   const setFocusedKey = (key: Key | null, childStrategy?: FocusStrategy) => {
     setFocusedKeyInternal(key);
     setChildFocusStrategy(childStrategy ?? null);
+  };
 
-    // In automatic mode, selecting follows focus
-    if (
-      keyboardActivation() === "automatic" &&
-      key !== null &&
-      key !== selectedKey() &&
-      !isKeyDisabled(key)
-    ) {
-      setSelectedKey(key);
+  // If the tab list doesn't have focus and the selected key changes, or if there
+  // isn't a focused key yet, move the focused key to the selected key so the
+  // roving tabIndex stays on the selected tab (mirrors useTabListState's effect).
+  let lastSelectedKey: Key | null = selectedKey();
+  createComputed(() => {
+    const sel = selectedKey();
+    if ((sel !== null && focusedKey() === null) || (!isFocused() && sel !== lastSelectedKey)) {
+      setFocusedKey(sel);
     }
-  };
+    lastSelectedKey = sel;
+  });
 
   // Keep uncontrolled selection valid as items/disabled keys change.
   createComputed(() => {

package/src/toast/createToastState.ts

@@ -31,11 +31,20 @@ export interface QueuedToast<T> {
   timeout?: number;
 }
 
+/** The kind of queue mutation that triggered a notification, passed to `wrapUpdate`. */
+export type ToastAction = "add" | "remove" | "clear";
+
 export interface ToastQueueOptions {
   /** The maximum number of toasts to display at once. */
   maxVisibleToasts?: number;
   /** Whether toasts should stack (true) or queue (false). */
   hasExitAnimation?: boolean;
+  /**
+   * Wraps each update to the visible toasts (e.g. in `document.startViewTransition()`),
+   * so the resulting re-render can be animated. Receives the action that triggered the
+   * update. Mirrors `@react-stately/toast`'s `wrapUpdate`.
+   */
+  wrapUpdate?: (fn: () => void, action: ToastAction) => void;
 }
 
 export interface ToastStateProps<T> {
@@ -125,10 +134,29 @@ export class ToastQueue<T> {
   private maxVisibleToasts: number;
   private hasExitAnimation: boolean;
   private keyCounter = 0;
+  private wrapUpdate?: (fn: () => void, action: ToastAction) => void;
 
   constructor(options: ToastQueueOptions = {}) {
     this.maxVisibleToasts = options.maxVisibleToasts ?? 5;
     this.hasExitAnimation = options.hasExitAnimation ?? false;
+    this.wrapUpdate = options.wrapUpdate;
+  }
+
+  /**
+   * Installs (or clears) the function that wraps visible-toast updates, so the
+   * resulting re-render can be animated. Used to attach `document.startViewTransition`
+   * to a shared queue (e.g. the global queue) after construction.
+   */
+  setWrapUpdate(wrapUpdate?: (fn: () => void, action: ToastAction) => void): void {
+    this.wrapUpdate = wrapUpdate;
+  }
+
+  private runWithWrapUpdate(fn: () => void, action: ToastAction): void {
+    if (this.wrapUpdate) {
+      this.wrapUpdate(fn, action);
+    } else {
+      fn();
+    }
   }
 
   /**
@@ -173,7 +201,7 @@ export class ToastQueue<T> {
     this.queue = [...this.queue.slice(0, low), toast, ...this.queue.slice(low)];
 
     // Start timer for visible toasts
-    this.updateVisibility();
+    this.updateVisibility("add");
 
     return key;
   }
@@ -193,7 +221,7 @@ export class ToastQueue<T> {
       this.queue = this.queue.map((t) =>
         t.key === key ? { ...t, timer: null, animation: "exiting" } : t,
       );
-      this.notify();
+      this.notify("remove");
     } else {
       // Remove immediately
       this.remove(key);
@@ -211,7 +239,7 @@ export class ToastQueue<T> {
     }
 
     this.queue = this.queue.filter((t) => t.key !== key);
-    this.updateVisibility();
+    this.updateVisibility("remove");
   }
 
   /**
@@ -223,7 +251,7 @@ export class ToastQueue<T> {
     }
 
     this.queue = [];
-    this.notify();
+    this.notify("clear");
   }
 
   /**
@@ -244,7 +272,7 @@ export class ToastQueue<T> {
     }
   }
 
-  private updateVisibility(): void {
+  private updateVisibility(action: ToastAction): void {
     // Mark toasts as visible or queued based on maxVisibleToasts
     const visibleCount = this.queue.filter(
       (t) => t.animation !== "queued" && t.animation !== "exiting",
@@ -277,14 +305,19 @@ export class ToastQueue<T> {
       return nextToast;
     });
 
-    this.notify();
+    this.notify(action);
   }
 
-  private notify(): void {
+  private notify(action: ToastAction = "add"): void {
     const toasts = [...this.queue];
-    for (const callback of this.subscriptions) {
-      callback(toasts);
-    }
+    // The new visible toasts are computed synchronously above; only the subscriber
+    // fan-out (which drives the re-render) is wrapped, so it can run inside a view
+    // transition. Mirrors @react-stately/toast's updateVisibleToasts.
+    this.runWithWrapUpdate(() => {
+      for (const callback of this.subscriptions) {
+        callback(toasts);
+      }
+    }, action);
   }
 }
 

package/src/toast/index.ts

@@ -6,6 +6,7 @@ export {
   type ToastOptions,
   type QueuedToast,
   type ToastQueueOptions,
+  type ToastAction,
   type ToastStateProps,
   type ToastState,
 } from "./createToastState";

package/src/tree/createTreeState.ts

@@ -6,8 +6,8 @@
  */
 
 import { createSignal, createEffect, createMemo, on, type Accessor } from "solid-js";
-import type { TreeState, TreeStateOptions, TreeCollection, TreeNode } from "./types";
-import type { Key, FocusStrategy } from "../collections/types";
+import type { TreeState, TreeStateOptions, TreeCollection } from "./types";
+import type { Key, FocusStrategy, Selection, SelectionBehavior } from "../collections/types";
 
 /**
  * Creates state management for a tree component.
@@ -66,10 +66,27 @@ export function createTreeState<T extends object, C extends TreeCollection<T> =
   });
 
   const selectionMode = createMemo(() => getOptions().selectionMode ?? "none");
-  const selectionBehavior = createMemo(() => getOptions().selectionBehavior ?? "toggle");
+  const selectionBehaviorProp = (): SelectionBehavior => getOptions().selectionBehavior ?? "toggle";
+  const [selectionBehaviorState, setSelectionBehaviorState] =
+    createSignal<SelectionBehavior>(selectionBehaviorProp());
+  const selectionBehavior = createMemo(() => selectionBehaviorState());
   const disallowEmptySelection = createMemo(() => getOptions().disallowEmptySelection ?? false);
   const disabledBehavior = createMemo(() => getOptions().disabledBehavior ?? "all");
 
+  createEffect(on(selectionBehaviorProp, (behavior) => setSelectionBehaviorState(behavior)));
+
+  createEffect(() => {
+    const keys = selectedKeys();
+    if (
+      selectionBehaviorProp() === "replace" &&
+      selectionBehaviorState() === "toggle" &&
+      keys !== "all" &&
+      keys.size === 0
+    ) {
+      setSelectionBehaviorState("replace");
+    }
+  });
+
   // Set focused key
   const setFocusedKey = (key: Key | null, strategy: FocusStrategy = "first") => {
     setFocusedKeyInternal(key);
@@ -169,7 +186,9 @@ export function createTreeState<T extends object, C extends TreeCollection<T> =
   };
 
   const toggleSelection = (key: Key) => {
-    if (isDisabled(key) && disabledBehavior() === "all") return;
+    // Disabled keys are never selectable, regardless of disabledBehavior
+    // (mirrors SelectionManager.canSelectItem, which ignores disabledBehavior).
+    if (isDisabled(key)) return;
     if (selectionMode() === "none") return;
 
     const current = selectedKeys();
@@ -203,15 +222,19 @@ export function createTreeState<T extends object, C extends TreeCollection<T> =
   };
 
   const replaceSelection = (key: Key) => {
-    if (isDisabled(key) && disabledBehavior() === "all") return;
+    if (isDisabled(key)) return;
     if (selectionMode() === "none") return;
 
     updateSelection(new Set([key]));
     setAnchorKey(key);
   };
 
+  const setSelectedKeys = (keys: Selection | Iterable<Key>) => {
+    updateSelection(normalizeSelection(keys));
+  };
+
   const extendSelection = (toKey: Key) => {
-    if (isDisabled(toKey) && disabledBehavior() === "all") return;
+    if (isDisabled(toKey)) return;
     if (selectionMode() !== "multiple") {
       replaceSelection(toKey);
       return;
@@ -330,6 +353,9 @@ export function createTreeState<T extends object, C extends TreeCollection<T> =
     get disabledKeys() {
       return disabledKeys();
     },
+    get disabledBehavior() {
+      return disabledBehavior();
+    },
     get expandedKeys() {
       return expandedKeys();
     },
@@ -351,6 +377,9 @@ export function createTreeState<T extends object, C extends TreeCollection<T> =
     get selectionBehavior() {
       return selectionBehavior();
     },
+    get disallowEmptySelection() {
+      return disallowEmptySelection();
+    },
     get selectedKeys() {
       return selectedKeys();
     },
@@ -361,6 +390,8 @@ export function createTreeState<T extends object, C extends TreeCollection<T> =
     setFocused: setIsFocused,
     toggleSelection,
     replaceSelection,
+    setSelectedKeys,
+    setSelectionBehavior: setSelectionBehaviorState,
     extendSelection,
     selectAll,
     clearSelection,

package/src/tree/types.ts

@@ -3,7 +3,7 @@
  * Based on @react-stately/tree.
  */
 
-import type { Key, FocusStrategy } from "../collections/types";
+import type { Key, FocusStrategy, Selection, SelectionBehavior } from "../collections/types";
 import type { GridNode, GridCollection } from "../grid/types";
 
 /**
@@ -81,6 +81,8 @@ export interface TreeState<T, C extends TreeCollection<T> = TreeCollection<T>> {
   readonly collection: C;
   /** Keys of disabled items. */
   readonly disabledKeys: Set<Key>;
+  /** Whether `disabledKeys` applies to all interactions, or only selection. */
+  readonly disabledBehavior: "selection" | "all";
   /** Keys of expanded items. */
   readonly expandedKeys: Set<Key>;
   /** Whether keyboard navigation is disabled. */
@@ -94,9 +96,11 @@ export interface TreeState<T, C extends TreeCollection<T> = TreeCollection<T>> {
   /** The selection mode. */
   readonly selectionMode: "none" | "single" | "multiple";
   /** How selection behaves when pressing an item. */
-  readonly selectionBehavior: "toggle" | "replace";
+  readonly selectionBehavior: SelectionBehavior;
+  /** Whether empty selection is disallowed. */
+  readonly disallowEmptySelection: boolean;
   /** The currently selected keys. */
-  readonly selectedKeys: "all" | Set<Key>;
+  readonly selectedKeys: Selection;
 
   /** Check if a key is selected. */
   isSelected(key: Key): boolean;
@@ -112,6 +116,10 @@ export interface TreeState<T, C extends TreeCollection<T> = TreeCollection<T>> {
   toggleSelection(key: Key): void;
   /** Replace selection with a key. */
   replaceSelection(key: Key): void;
+  /** Set the selected keys directly. */
+  setSelectedKeys(keys: Selection | Iterable<Key>): void;
+  /** Set how selection behaves when pressing an item. */
+  setSelectionBehavior(behavior: SelectionBehavior): void;
   /** Extend selection to a key (shift-click). */
   extendSelection(toKey: Key): void;
   /** Select all visible items. */
@@ -145,13 +153,13 @@ export interface TreeStateOptions<T, C extends TreeCollection<T> = TreeCollectio
   /** Selection mode. */
   selectionMode?: "none" | "single" | "multiple";
   /** Selection behavior. */
-  selectionBehavior?: "toggle" | "replace";
+  selectionBehavior?: SelectionBehavior;
   /** Whether empty selection is disallowed. */
   disallowEmptySelection?: boolean;
   /** Currently selected keys (controlled). */
-  selectedKeys?: "all" | Iterable<Key>;
+  selectedKeys?: Selection | Iterable<Key>;
   /** Default selected keys (uncontrolled). */
-  defaultSelectedKeys?: "all" | Iterable<Key>;
+  defaultSelectedKeys?: Selection | Iterable<Key>;
   /** Handler for selection changes. */
   onSelectionChange?: (keys: "all" | Set<Key>) => void;
   /** Currently expanded keys (controlled). */