xertica-ui 2.1.2 → 2.1.4

package/components/ui/stepper/use-stepper.ts

@@ -0,0 +1,137 @@
+import { useState, useCallback } from 'react';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface UseStepperProps {
+    /** Total number of steps. */
+    totalSteps: number;
+    /** Initial active step (1-indexed). @default 1 */
+    initialStep?: number;
+    /**
+     * Controlled current step (1-indexed).
+     * When provided, step state is managed externally via `onStepChange`.
+     */
+    step?: number;
+    /** Called whenever the active step changes. */
+    onStepChange?: (step: number) => void;
+    /**
+     * Optional async guard called before advancing to the next step.
+     * Return `true` to allow the transition, `false` to block it.
+     * Useful for running form validation before moving forward.
+     */
+    onBeforeNext?: (currentStep: number) => boolean | Promise<boolean>;
+}
+
+export interface UseStepperReturn {
+    // ── State ─────────────────────────────────────────────────────────────────
+    /** The currently active step (1-indexed). */
+    currentStep: number;
+    /** Total number of steps. */
+    totalSteps: number;
+
+    // ── Flags ─────────────────────────────────────────────────────────────────
+    /** Whether the current step is the first step. */
+    isFirstStep: boolean;
+    /** Whether the current step is the last step. */
+    isLastStep: boolean;
+    /** Whether navigation to the previous step is possible. */
+    canGoPrev: boolean;
+    /** Whether navigation to the next step is possible. */
+    canGoNext: boolean;
+
+    // ── Handlers ──────────────────────────────────────────────────────────────
+    /**
+     * Advance to the next step.
+     * If `onBeforeNext` is provided, it is awaited first; the step only
+     * advances when the guard returns `true`.
+     */
+    next: () => Promise<void>;
+    /** Go back to the previous step (no-op if already on step 1). */
+    prev: () => void;
+    /** Jump directly to a specific step (1-indexed, clamped to valid range). */
+    goTo: (step: number) => void;
+    /** Jump to the first step. */
+    reset: () => void;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Hook
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Headless hook for multi-step wizard / stepper logic.
+ *
+ * @description
+ * Manages the active step state, navigation guards, and derived flags for
+ * multi-step flows. Supports both controlled and uncontrolled modes.
+ * Pair with the `<Stepper>` / `<Step>` visual components or any custom UI.
+ *
+ * @example
+ * ```tsx
+ * const { currentStep, totalSteps, next, prev, isFirstStep, isLastStep } =
+ *   useStepper({ totalSteps: 3, onBeforeNext: () => form.trigger() });
+ * ```
+ */
+export function useStepper({
+    totalSteps,
+    initialStep = 1,
+    step: controlledStep,
+    onStepChange,
+    onBeforeNext,
+}: UseStepperProps): UseStepperReturn {
+    const [internalStep, setInternalStep] = useState(initialStep);
+
+    const isControlled = controlledStep !== undefined;
+    const currentStep = isControlled ? controlledStep! : internalStep;
+
+    const setStep = useCallback(
+        (s: number) => {
+            const clamped = Math.min(Math.max(1, s), totalSteps);
+            if (!isControlled) setInternalStep(clamped);
+            onStepChange?.(clamped);
+        },
+        [isControlled, onStepChange, totalSteps]
+    );
+
+    // ── Derived ───────────────────────────────────────────────────────────────
+
+    const isFirstStep = currentStep === 1;
+    const isLastStep = currentStep === totalSteps;
+    const canGoPrev = currentStep > 1;
+    const canGoNext = currentStep < totalSteps;
+
+    // ── Handlers ──────────────────────────────────────────────────────────────
+
+    const next = useCallback(async () => {
+        if (!canGoNext) return;
+        if (onBeforeNext) {
+            const allowed = await onBeforeNext(currentStep);
+            if (!allowed) return;
+        }
+        setStep(currentStep + 1);
+    }, [canGoNext, currentStep, onBeforeNext, setStep]);
+
+    const prev = useCallback(() => {
+        if (!canGoPrev) return;
+        setStep(currentStep - 1);
+    }, [canGoPrev, currentStep, setStep]);
+
+    const goTo = useCallback((s: number) => setStep(s), [setStep]);
+
+    const reset = useCallback(() => setStep(1), [setStep]);
+
+    return {
+        currentStep,
+        totalSteps,
+        isFirstStep,
+        isLastStep,
+        canGoPrev,
+        canGoNext,
+        next,
+        prev,
+        goTo,
+        reset,
+    };
+}

package/components/ui/tree-view/index.ts

@@ -1 +1,4 @@
-export * from './tree-view';
+export { TreeView } from './tree-view';
+export type { TreeViewProps } from './tree-view';
+export { useTreeView } from './use-tree-view';
+export type { TreeNode, UseTreeViewProps, UseTreeViewReturn } from './use-tree-view';

package/components/ui/tree-view/tree-view.stories.tsx

@@ -1,7 +1,9 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import { TreeView } from './tree-view';
-import { Folder, File, Code, Database, Globe } from 'lucide-react';
-import React from 'react';
+import { useTreeView, type TreeNode } from './use-tree-view';
+import { Folder, File, Code, Database, Globe, ChevronRight, ChevronDown } from 'lucide-react';
+import React, { useState } from 'react';
+import { cn } from '../../shared/utils';
 
 const meta: Meta<typeof TreeView> = {
   title: 'UI/TreeView',
@@ -12,7 +14,7 @@ const meta: Meta<typeof TreeView> = {
 export default meta;
 type Story = StoryObj<typeof TreeView>;
 
-const fileTree = [
+const fileTree: TreeNode[] = [
   {
     id: "root",
     label: "Project",
@@ -54,7 +56,111 @@ export const Default: Story = {
   },
   render: (args) => (
     <div className="w-[300px] rounded-lg border p-4">
-      <TreeView {...args} onSelect={(node) => console.log("Selected:", node)} />
+      <TreeView {...args} onNodeSelect={(node) => console.log("Selected:", node)} />
     </div>
   ),
 };
+
+/**
+ * ## useTreeView — Headless Hook
+ *
+ * Use `useTreeView` when you need the full tree logic (expand/collapse,
+ * keyboard navigation, selection) but want to render a completely custom UI.
+ * The example below renders a flat indented list with custom styling instead
+ * of the default `<TreeView>` component.
+ *
+ * ```tsx
+ * import { useTreeView } from '@xertica/ui/tree-view';
+ *
+ * const { expanded, effectiveSelectedId, toggleExpand, handleSelect, handleKeyDown, getNodeRef } =
+ *   useTreeView({ data, onNodeSelect });
+ * ```
+ */
+export const HeadlessHook: Story = {
+  name: 'useTreeView (headless)',
+  render: () => {
+    const [selectedId, setSelectedId] = useState<string | undefined>(undefined);
+
+    const {
+      expanded,
+      effectiveSelectedId,
+      getNodeRef,
+      toggleExpand,
+      handleSelect,
+      handleKeyDown,
+    } = useTreeView({
+      data: fileTree,
+      defaultExpanded: ['root', 'src'],
+      selectedNodeId: selectedId,
+      onNodeSelect: (node) => {
+        setSelectedId(node.id);
+        console.log('Selected:', node.label);
+      },
+    });
+
+    const renderNode = (node: TreeNode, level: number): React.ReactNode => {
+      const hasChildren = !!(node.children?.length);
+      const isExpanded = expanded.has(node.id);
+      const isSelected = node.id === effectiveSelectedId;
+
+      return (
+        <div key={node.id}>
+          <button
+            ref={getNodeRef(node.id)}
+            role="treeitem"
+            aria-expanded={hasChildren ? isExpanded : undefined}
+            aria-selected={isSelected}
+            tabIndex={isSelected ? 0 : -1}
+            onClick={() => {
+              if (hasChildren) toggleExpand(node.id);
+              handleSelect(node);
+            }}
+            onKeyDown={(e) => handleKeyDown(e, node)}
+            style={{ paddingLeft: `${level * 16 + 8}px` }}
+            className={cn(
+              'flex w-full items-center gap-1.5 rounded py-1 pr-2 text-left text-sm transition-colors',
+              'hover:bg-accent focus:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+              isSelected
+                ? 'bg-primary text-primary-foreground font-semibold'
+                : 'text-foreground'
+            )}
+          >
+            {hasChildren ? (
+              <span className="flex-shrink-0">
+                {isExpanded
+                  ? <ChevronDown className="h-3.5 w-3.5" />
+                  : <ChevronRight className="h-3.5 w-3.5" />}
+              </span>
+            ) : (
+              <span className="w-3.5 flex-shrink-0" />
+            )}
+            {node.icon && <span className="flex-shrink-0 opacity-70">{node.icon}</span>}
+            <span>{node.label}</span>
+          </button>
+
+          {hasChildren && isExpanded && (
+            <div role="group">
+              {node.children!.map((child) => renderNode(child, level + 1))}
+            </div>
+          )}
+        </div>
+      );
+    };
+
+    return (
+      <div className="w-[280px] space-y-1 rounded-xl border bg-card p-3 shadow-sm">
+        <p className="mb-2 px-2 text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+          Explorer
+        </p>
+        <div role="tree">
+          {fileTree.map((node) => renderNode(node, 0))}
+        </div>
+        {selectedId && (
+          <p className="mt-3 border-t pt-2 px-2 text-xs text-muted-foreground">
+            Selected: <span className="font-medium text-foreground">{selectedId}</span>
+          </p>
+        )}
+      </div>
+    );
+  },
+};

package/components/ui/tree-view/tree-view.tsx

@@ -1,13 +1,7 @@
 import * as React from "react";
 import { ChevronRight, ChevronDown } from "lucide-react";
 import { cn } from "../../shared/utils";
-
-export interface TreeNode {
-  id: string;
-  label: string;
-  icon?: React.ReactNode;
-  children?: TreeNode[];
-}
+import { useTreeView, type TreeNode } from "./use-tree-view";
 
 interface TreeViewProps extends React.HTMLAttributes<HTMLDivElement> {
   data: TreeNode[];
@@ -29,6 +23,8 @@ interface TreeViewProps extends React.HTMLAttributes<HTMLDivElement> {
  * and collapsed independently. Supports custom icons per node, controlled
  * selection, and full WAI-ARIA keyboard navigation.
  *
+ * Headless logic is available via `useTreeView` for custom tree UIs.
+ *
  * @ai-rules
  * 1. Each `TreeNode` must have a unique `id`.
  * 2. Leaf nodes (no `children`) do not render expand arrows.
@@ -38,114 +34,14 @@ interface TreeViewProps extends React.HTMLAttributes<HTMLDivElement> {
  */
 const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
   ({ className, data, onNodeClick, onNodeSelect, defaultExpanded = [], selectedNodeId, ...props }, ref) => {
-    const [expanded, setExpanded] = React.useState<Set<string>>(new Set(defaultExpanded));
-    const [internalSelectedId, setInternalSelectedId] = React.useState<string | undefined>(undefined);
-    const nodeRefs = React.useRef<Map<string, HTMLButtonElement>>(new Map());
-
-    const isControlled = selectedNodeId !== undefined;
-    const effectiveSelectedId = isControlled ? selectedNodeId : internalSelectedId;
-
-    const toggleExpand = (nodeId: string) => {
-      setExpanded(prev => {
-        const next = new Set(prev);
-        next.has(nodeId) ? next.delete(nodeId) : next.add(nodeId);
-        return next;
-      });
-    };
-
-    // Build an ordered list of all currently visible nodes (respects expand state)
-    const getVisibleNodes = React.useCallback((): TreeNode[] => {
-      const result: TreeNode[] = [];
-      const traverse = (nodes: TreeNode[]) => {
-        for (const node of nodes) {
-          result.push(node);
-          if (node.children?.length && expanded.has(node.id)) traverse(node.children);
-        }
-      };
-      traverse(data);
-      return result;
-    }, [data, expanded]);
-
-    // Find the parent of a given node id
-    const findParent = (nodes: TreeNode[], targetId: string): TreeNode | null => {
-      for (const n of nodes) {
-        if (n.children?.some(c => c.id === targetId)) return n;
-        if (n.children) {
-          const found = findParent(n.children, targetId);
-          if (found) return found;
-        }
-      }
-      return null;
-    };
-
-    const handleSelect = (node: TreeNode) => {
-      if (!isControlled) setInternalSelectedId(node.id);
-      onNodeSelect?.(node);
-      onNodeClick?.(node);
-    };
-
-    const handleKeyDown = (e: React.KeyboardEvent, node: TreeNode) => {
-      const visibleNodes = getVisibleNodes();
-      const idx = visibleNodes.findIndex(n => n.id === node.id);
-      const hasChildren = !!(node.children?.length);
-      const isExpanded = expanded.has(node.id);
-
-      const focusNode = (id: string) => {
-        nodeRefs.current.get(id)?.focus();
-      };
-
-      switch (e.key) {
-        case 'ArrowDown': {
-          e.preventDefault();
-          const next = visibleNodes[idx + 1];
-          if (next) focusNode(next.id);
-          break;
-        }
-        case 'ArrowUp': {
-          e.preventDefault();
-          const prev = visibleNodes[idx - 1];
-          if (prev) focusNode(prev.id);
-          break;
-        }
-        case 'ArrowRight': {
-          e.preventDefault();
-          if (hasChildren && !isExpanded) {
-            toggleExpand(node.id);
-          } else if (hasChildren && isExpanded && node.children?.length) {
-            focusNode(node.children[0].id);
-          }
-          break;
-        }
-        case 'ArrowLeft': {
-          e.preventDefault();
-          if (hasChildren && isExpanded) {
-            toggleExpand(node.id);
-          } else {
-            const parent = findParent(data, node.id);
-            if (parent) focusNode(parent.id);
-          }
-          break;
-        }
-        case 'Home': {
-          e.preventDefault();
-          if (visibleNodes.length > 0) focusNode(visibleNodes[0].id);
-          break;
-        }
-        case 'End': {
-          e.preventDefault();
-          const last = visibleNodes[visibleNodes.length - 1];
-          if (last) focusNode(last.id);
-          break;
-        }
-        case 'Enter':
-        case ' ': {
-          e.preventDefault();
-          if (hasChildren) toggleExpand(node.id);
-          handleSelect(node);
-          break;
-        }
-      }
-    };
+    const {
+      expanded,
+      effectiveSelectedId,
+      getNodeRef,
+      toggleExpand,
+      handleSelect,
+      handleKeyDown,
+    } = useTreeView({ data, defaultExpanded, selectedNodeId, onNodeClick, onNodeSelect });
 
     return (
       <div ref={ref} className={cn("w-full", className)} role="tree" {...props}>
@@ -159,7 +55,7 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
             onToggle={toggleExpand}
             onSelect={handleSelect}
             onKeyDown={handleKeyDown}
-            nodeRefs={nodeRefs}
+            getNodeRef={getNodeRef}
           />
         ))}
       </div>
@@ -176,11 +72,11 @@ interface TreeNodeComponentProps {
   onToggle: (nodeId: string) => void;
   onSelect: (node: TreeNode) => void;
   onKeyDown: (e: React.KeyboardEvent, node: TreeNode) => void;
-  nodeRefs: React.MutableRefObject<Map<string, HTMLButtonElement>>;
+  getNodeRef: (nodeId: string) => (el: HTMLButtonElement | null) => void;
 }
 
 const TreeNodeComponent: React.FC<TreeNodeComponentProps> = ({
-  node, level, expanded, selectedId, onToggle, onSelect, onKeyDown, nodeRefs,
+  node, level, expanded, selectedId, onToggle, onSelect, onKeyDown, getNodeRef,
 }) => {
   const hasChildren = !!(node.children?.length);
   const isExpanded = expanded.has(node.id);
@@ -191,15 +87,10 @@ const TreeNodeComponent: React.FC<TreeNodeComponentProps> = ({
     onSelect(node);
   };
 
-  const setRef = (el: HTMLButtonElement | null) => {
-    if (el) nodeRefs.current.set(node.id, el);
-    else nodeRefs.current.delete(node.id);
-  };
-
   return (
     <div role="none">
       <button
-        ref={setRef}
+        ref={getNodeRef(node.id)}
         role="treeitem"
         aria-expanded={hasChildren ? isExpanded : undefined}
         aria-selected={isSelected}
@@ -235,7 +126,7 @@ const TreeNodeComponent: React.FC<TreeNodeComponentProps> = ({
               onToggle={onToggle}
               onSelect={onSelect}
               onKeyDown={onKeyDown}
-              nodeRefs={nodeRefs}
+              getNodeRef={getNodeRef}
             />
           ))}
         </div>
@@ -246,3 +137,4 @@ const TreeNodeComponent: React.FC<TreeNodeComponentProps> = ({
 
 export { TreeView };
 export type { TreeViewProps };
+export type { TreeNode } from './use-tree-view';