xertica-ui 2.1.2 → 2.1.3

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/switch/switch.mdx

@@ -10,14 +10,14 @@ import * as SwitchStories from './switch.stories';
 
 <Primary />
 
----
-
-## Variations
-
-<Stories />
-
----
-
+---
+
+## Variations
+
+<Stories />
+
+---
+
 ## AI Best Practices
 
 > [!IMPORTANT]

package/components/ui/switch/switch.stories.tsx

@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react';
-import { expect, userEvent, within } from 'storybook/test';
+import { expect, userEvent, within } from 'storybook/test';
 import { Switch } from './switch';
 import { Label } from '../label';
 import React from 'react';
@@ -66,22 +66,22 @@ export const Sizes: Story = {
       </div>
     </div>
   ),
-};
-
-export const Toggle: Story = {
-  render: () => (
-    <div className="flex items-center space-x-2">
-      <Switch id="play-switch" />
-      <Label htmlFor="play-switch">Airplane Mode</Label>
-    </div>
-  ),
-  play: async ({ canvasElement }) => {
-    const canvas = within(canvasElement);
-    const switchEl = canvas.getByRole('switch');
-    await expect(switchEl).toHaveAttribute('aria-checked', 'false');
-    await userEvent.click(switchEl);
-    await expect(switchEl).toHaveAttribute('aria-checked', 'true');
-    await userEvent.click(switchEl);
-    await expect(switchEl).toHaveAttribute('aria-checked', 'false');
-  },
-};
+};
+
+export const Toggle: Story = {
+  render: () => (
+    <div className="flex items-center space-x-2">
+      <Switch id="play-switch" />
+      <Label htmlFor="play-switch">Airplane Mode</Label>
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const switchEl = canvas.getByRole('switch');
+    await expect(switchEl).toHaveAttribute('aria-checked', 'false');
+    await userEvent.click(switchEl);
+    await expect(switchEl).toHaveAttribute('aria-checked', 'true');
+    await userEvent.click(switchEl);
+    await expect(switchEl).toHaveAttribute('aria-checked', 'false');
+  },
+};

package/components/ui/table/table.mdx

@@ -10,14 +10,14 @@ import * as TableStories from './table.stories';
 
 <Primary />
 
----
-
-## Variations
-
-<Stories />
-
----
-
+---
+
+## Variations
+
+<Stories />
+
+---
+
 ## AI Best Practices
 
 > [!IMPORTANT]

package/components/ui/tabs/tabs.mdx

@@ -10,14 +10,14 @@ import * as TabsStories from './tabs.stories';
 
 <Primary />
 
----
-
-## Variations
-
-<Stories />
-
----
-
+---
+
+## Variations
+
+<Stories />
+
+---
+
 ## AI Best Practices
 
 > [!IMPORTANT]

package/components/ui/tabs/tabs.stories.tsx

@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react';
-import { expect, userEvent, within } from 'storybook/test';
+import { expect, userEvent, within } from 'storybook/test';
 import { Tabs, TabsList, TabsTrigger, TabsContent } from './tabs';
 import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from '../card';
 import { Button } from '../button';
@@ -107,28 +107,28 @@ export const Analytics: Story = {
       </TabsContent>
     </Tabs>
   ),
-};
-
-export const SwitchTab: Story = {
-  args: { defaultValue: 'account', className: 'w-[400px]' },
-  render: (args) => (
-    <Tabs {...args}>
-      <TabsList className="grid w-full grid-cols-2">
-        <TabsTrigger value="account">Account</TabsTrigger>
-        <TabsTrigger value="password">Password</TabsTrigger>
-      </TabsList>
-      <TabsContent value="account"><p className="p-4 text-sm">Account content</p></TabsContent>
-      <TabsContent value="password"><p className="p-4 text-sm">Password content</p></TabsContent>
-    </Tabs>
-  ),
-  play: async ({ canvasElement }) => {
-    const canvas = within(canvasElement);
-    const accountTab = canvas.getByRole('tab', { name: 'Account' });
-    const passwordTab = canvas.getByRole('tab', { name: 'Password' });
-    await expect(accountTab).toHaveAttribute('aria-selected', 'true');
-    await expect(passwordTab).toHaveAttribute('aria-selected', 'false');
-    await userEvent.click(passwordTab);
-    await expect(passwordTab).toHaveAttribute('aria-selected', 'true');
-    await expect(accountTab).toHaveAttribute('aria-selected', 'false');
-  },
-};
+};
+
+export const SwitchTab: Story = {
+  args: { defaultValue: 'account', className: 'w-[400px]' },
+  render: (args) => (
+    <Tabs {...args}>
+      <TabsList className="grid w-full grid-cols-2">
+        <TabsTrigger value="account">Account</TabsTrigger>
+        <TabsTrigger value="password">Password</TabsTrigger>
+      </TabsList>
+      <TabsContent value="account"><p className="p-4 text-sm">Account content</p></TabsContent>
+      <TabsContent value="password"><p className="p-4 text-sm">Password content</p></TabsContent>
+    </Tabs>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const accountTab = canvas.getByRole('tab', { name: 'Account' });
+    const passwordTab = canvas.getByRole('tab', { name: 'Password' });
+    await expect(accountTab).toHaveAttribute('aria-selected', 'true');
+    await expect(passwordTab).toHaveAttribute('aria-selected', 'false');
+    await userEvent.click(passwordTab);
+    await expect(passwordTab).toHaveAttribute('aria-selected', 'true');
+    await expect(accountTab).toHaveAttribute('aria-selected', 'false');
+  },
+};

package/components/ui/textarea/textarea.mdx

@@ -10,14 +10,14 @@ import * as TextareaStories from './textarea.stories';
 
 <Primary />
 
----
-
-## Variations
-
-<Stories />
-
----
-
+---
+
+## Variations
+
+<Stories />
+
+---
+
 ## AI Best Practices
 
 > [!IMPORTANT]

package/components/ui/timeline/timeline.mdx

@@ -10,14 +10,14 @@ import * as TimelineStories from './timeline.stories';
 
 <Primary />
 
----
-
-## Variations
-
-<Stories />
-
----
-
+---
+
+## Variations
+
+<Stories />
+
+---
+
 ## AI Best Practices
 
 > [!IMPORTANT]

package/components/ui/toggle/toggle.mdx

@@ -10,14 +10,14 @@ import * as ToggleStories from './toggle.stories';
 
 <Primary />
 
----
-
-## Variations
-
-<Stories />
-
----
-
+---
+
+## Variations
+
+<Stories />
+
+---
+
 ## AI Best Practices
 
 > [!IMPORTANT]

package/components/ui/toggle-group/toggle-group.mdx

@@ -10,14 +10,14 @@ import * as ToggleGroupStories from './toggle-group.stories';
 
 <Primary />
 
----
-
-## Variations
-
-<Stories />
-
----
-
+---
+
+## Variations
+
+<Stories />
+
+---
+
 ## AI Best Practices
 
 > [!IMPORTANT]

package/components/ui/tooltip/tooltip.mdx

@@ -10,14 +10,14 @@ import * as TooltipStories from './tooltip.stories';
 
 <Primary />
 
----
-
-## Variations
-
-<Stories />
-
----
-
+---
+
+## Variations
+
+<Stories />
+
+---
+
 ## AI Best Practices
 
 > [!IMPORTANT]

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.mdx

@@ -10,14 +10,14 @@ import * as TreeViewStories from './tree-view.stories';
 
 <Primary />
 
----
-
-## Variations
-
-<Stories />
-
----
-
+---
+
+## Variations
+
+<Stories />
+
+---
+
 ## AI Best Practices
 
 > [!IMPORTANT]

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>
+    );
+  },
+};