xertica-ui 2.1.2 → 2.1.3

package/docs/components/sidebar.md

@@ -6,6 +6,14 @@ The `Sidebar` is the primary vertical navigation panel of the application shell.
 
 It is a responsive component that can be expanded or collapsed as an icon-only strip, fully integrated with the `LayoutContext` for state management.
 
+The component ships with **three usage patterns** to cover different levels of customization:
+
+| Pattern | When to use |
+|---|---|
+| **Monolithic API** (`<Sidebar />`) | Standard usage — pass props, get a fully-featured sidebar |
+| **Compound Component API** (`<Sidebar.Root>` + sub-components) | Custom layouts — compose only the parts you need |
+| **Headless Hook** (`useSidebar()`) | Full control — manage state yourself, render anything |
+
 ---
 
 ## Variants
@@ -36,6 +44,8 @@ Designed for complex tools, agents, or multi-context navigation.
 
 ## Props
 
+### `<Sidebar />` (Monolithic API)
+
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `expanded` | `boolean` | `auto` | Controlled state. Defaults to `LayoutContext` or local state. |
@@ -47,8 +57,45 @@ Designed for complex tools, agents, or multi-context navigation.
 | `search` | `SidebarSearchConfig` | — | Search bar configuration (assistant variant). |
 | `logo` | `ReactNode` | — | Logo shown when expanded. |
 | `logoCollapsed` | `ReactNode` | — | Logo shown when collapsed. |
-| `width` | `number` | `256` | Expanded sidebar width in pixels. |
+| `width` | `number` | `280` | Expanded sidebar width in pixels. |
 | `footer` | `SidebarFooterConfig` | — | Footer visibility flags (`showUser`, `showSettings`, `showLogout`). |
+| `showFooter` | `boolean` | `true` for default, `false` for assistant | Whether to render the footer section. |
+
+### `<Sidebar.Root />` (Compound Component)
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `expanded` | `boolean` | `auto` | Controlled expansion state. |
+| `onToggle` | `() => void` | `auto` | Toggle callback. |
+| `navigate` | `(path: string) => void` | `window.location.href` | Navigation handler. |
+| `location` | `{ pathname: string }` | `window.location` | Current location for active state. |
+| `width` | `number` | `280` | Expanded width in pixels. |
+| `children` | `ReactNode` | — | Sub-components: `Sidebar.Header`, `Sidebar.Nav`, `Sidebar.Footer`, `Sidebar.Search`. |
+
+### `useSidebar()` (Headless Hook)
+
+```ts
+import { useSidebar } from 'xertica-ui/layout';
+
+const {
+  expanded,          // boolean — current expansion state
+  setExpanded,       // (value: boolean | fn) => void
+  toggleExpanded,    // () => void
+  isMobileViewport,  // boolean
+  hasOverflow,       // boolean — nav items overflow the container
+  visibleItems,      // RouteGroup[] — items that fit in the nav
+  overflowItems,     // RouteGroup[] — items that overflow
+  openSubmenu,       // string | null
+  setOpenSubmenu,    // (id: string | null) => void
+  isFilterOpen,      // boolean
+  setIsFilterOpen,   // (open: boolean) => void
+  navRef,            // RefObject<HTMLElement> — attach to nav container
+  navigationGroups,  // RouteGroup[] — the resolved groups passed in
+} = useSidebar({
+  defaultExpanded: true,
+  navigationGroups: myGroups,
+});
+```
 
 ### RouteConfig
 
@@ -61,11 +108,21 @@ Designed for complex tools, agents, or multi-context navigation.
 | `actions` | `ActionMenuItem[]` | Contextual action menu items (ellipsis button — assistant variant) |
 | `description` | `ReactNode` | Auxiliary content shown when the route is active (assistant variant) |
 
+### RouteGroup
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | `string` | Unique identifier |
+| `label` | `string` | Group title |
+| `icon` | `ComponentType` | Group icon |
+| `items` | `RouteConfig[]` | Navigation items in the group |
+| `actions` | `ActionMenuItem[]` | Context menu for the entire group |
+
 ---
 
 ## Examples
 
-### Default Variant — Flat Routes
+### 1. Monolithic API — Flat Routes
 
 ```tsx
 import { Sidebar } from 'xertica-ui/layout';
@@ -94,7 +151,7 @@ export function MySidebar() {
 }
 ```
 
-### Default Variant — Groups with Children
+### 2. Monolithic API — Groups with Children
 
 ```tsx
 import { BarChart, Users, Settings, Home } from 'lucide-react';
@@ -129,15 +186,107 @@ import { BarChart, Users, Settings, Home } from 'lucide-react';
 />
 ```
 
+### 3. Compound Component API
+
+Use this when you need to inject custom content between sections or reorder the layout:
+
+```tsx
+import { Sidebar } from 'xertica-ui/layout';
+import { Home, BarChart } from 'lucide-react';
+
+export function CustomSidebar({ expanded, onToggle }) {
+  return (
+    <Sidebar.Root
+      expanded={expanded}
+      onToggle={onToggle}
+      width={280}
+      location={{ pathname: window.location.pathname }}
+      navigate={(path) => window.location.href = path}
+    >
+      {/* Toggle button + logo */}
+      <Sidebar.Header logo={<MyLogo />} logoCollapsed={<MyIcon />} />
+
+      {/* Custom content injected between header and nav */}
+      <div className="px-4 py-2">
+        <span className="text-xs text-sidebar-foreground/60">v2.0.0</span>
+      </div>
+
+      {/* Navigation */}
+      <Sidebar.Nav
+        navigationGroups={[
+          {
+            id: 'main',
+            items: [
+              { path: '/home', label: 'Home', icon: Home },
+              { path: '/dashboard', label: 'Dashboard', icon: BarChart },
+            ],
+          },
+        ]}
+      />
+
+      {/* Footer */}
+      <Sidebar.Footer
+        user={{ name: 'Admin', email: 'admin@example.com' }}
+        onLogout={() => signOut()}
+        showUser
+        showSettings
+        showLogout
+      />
+    </Sidebar.Root>
+  );
+}
+```
+
+### 4. Headless Hook — Fully Custom UI
+
+Use `useSidebar` when you need complete control over the rendered output:
+
+```tsx
+import { useSidebar } from 'xertica-ui/layout';
+import { Home, BarChart } from 'lucide-react';
+
+const groups = [
+  {
+    id: 'main',
+    items: [
+      { path: '/home', label: 'Home', icon: Home },
+      { path: '/dashboard', label: 'Dashboard', icon: BarChart },
+    ],
+  },
+];
+
+export function MyCustomSidebar() {
+  const { expanded, toggleExpanded, navigationGroups } = useSidebar({
+    defaultExpanded: true,
+    navigationGroups: groups,
+  });
+
+  return (
+    <aside style={{ width: expanded ? 280 : 80 }}>
+      <button onClick={toggleExpanded}>Toggle</button>
+      <nav>
+        {navigationGroups.flatMap(g => g.items).map(item => (
+          <a key={item.path} href={item.path}>
+            {expanded ? item.label : null}
+          </a>
+        ))}
+      </nav>
+    </aside>
+  );
+}
+```
+
 ---
 
 ## AI Rules
 
-- **State Management** — Always use `useLayout()` to keep the Sidebar synchronized with the main content padding. Avoid managing `expanded` locally.
+- **State Management** — Always use `useLayout()` to keep the Sidebar synchronized with the main content padding. Avoid managing `expanded` locally unless using the Headless Hook pattern.
 - **Icons** — Pass the icon **component source** (e.g., `HomeIcon`), not a rendered element.
 - **Groups** — Use `navigationGroups` in `default` variant for structured navigation with labels. Use `routes` for flat lists.
 - **Children** — Add `children` to a `RouteConfig` to expose sub-routes via a ChevronRight button at the end of the item. Do not nest more than 2 levels.
 - **Assistant Mode** — Use `fixedArea` to place high-priority "Create" buttons so they remain visible regardless of scrolling.
+- **Compound Components** — Use `<Sidebar.Root>` + sub-components when you need to inject custom content between sections or reorder the layout.
+- **Headless Hook** — Use `useSidebar()` only when you need a completely custom sidebar UI that shares none of the default rendering.
 
 ---
 

package/docs/components/stepper.md

@@ -4,6 +4,20 @@
 
 A visual multi-step progress indicator that shows the user's current position within a sequential process. Uses a composable primitive pattern: `<Stepper>` wraps one or more `<Step>` children, automatically inferring the total number of steps.
 
+The package also exports a **headless `useStepper` hook** for building fully custom step-navigation UIs — including async validation guards before advancing — while reusing all the step-state logic.
+
+---
+
+## Exports
+
+| Export | Description |
+|---|---|
+| `Stepper` | Visual step indicator component |
+| `Step` | Individual step item |
+| `useStepper` | Headless hook — all step navigation logic, no UI |
+| `UseStepperProps` | TypeScript props type for the hook |
+| `UseStepperReturn` | TypeScript return type for the hook |
+
 ---
 
 ## When to Use
@@ -43,6 +57,7 @@ A visual multi-step progress indicator that shows the user's current position wi
 | Prop | Type | Required | Description |
 |---|---|---|---|
 | `currentStep` | `number` | **Yes** | The currently active step (1-indexed) |
+| `orientation` | `'horizontal' \| 'vertical'` | No | Layout direction (default: `'horizontal'`) |
 | `className` | `string` | No | Additional CSS classes |
 
 ### `Step`
@@ -52,16 +67,9 @@ A visual multi-step progress indicator that shows the user's current position wi
 | `step` | `number` | **Yes** | Position of this step (1-indexed, must match order) |
 | `label` | `string` | **Yes** | Step label text |
 | `description` | `string` | No | Optional supplementary text below the label |
+| `error` | `boolean` | No | When `true`, renders the step in error state (red) |
 | `className` | `string` | No | Additional CSS classes |
 
-### `useStepper()` (hook)
-
-```typescript
-const { currentStep, totalSteps } = useStepper();
-```
-
-Access the stepper context from within a custom `Step` child component.
-
 ---
 
 ## Examples
@@ -97,7 +105,7 @@ const [currentStep, setCurrentStep] = useState(1);
       onClick={() => setCurrentStep(s => Math.min(3, s + 1))}
       disabled={currentStep === 3}
     >
-      {currentStep === 2 ? 'Finish' : 'Next'}
+      {currentStep === 3 ? 'Finish' : 'Next'}
     </Button>
   </div>
 </div>
@@ -105,14 +113,151 @@ const [currentStep, setCurrentStep] = useState(1);
 
 ---
 
+## `useStepper` Hook
+
+A headless hook that manages step navigation state. Supports both **uncontrolled** (internal state) and **controlled** (external `step` prop) modes, plus an optional async `onBeforeNext` guard for validating the current step before advancing.
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `totalSteps` | `number` | — | **Required.** Total number of steps in the flow |
+| `initialStep` | `number` | `1` | Starting step (uncontrolled mode only) |
+| `step` | `number` | — | Controlled current step — when provided, the hook uses this value instead of internal state |
+| `onStepChange` | `(step: number) => void` | — | Called whenever the step changes |
+| `onBeforeNext` | `(currentStep: number) => boolean \| Promise<boolean>` | — | Optional async guard — return `false` (or resolve to `false`) to block advancing to the next step |
+
+### Return Value
+
+| Property | Type | Description |
+|---|---|---|
+| `currentStep` | `number` | The currently active step (1-indexed) |
+| `totalSteps` | `number` | Total number of steps |
+| `isFirstStep` | `boolean` | Whether the current step is the first step |
+| `isLastStep` | `boolean` | Whether the current step is the last step |
+| `canGoPrev` | `boolean` | Whether navigating to the previous step is possible |
+| `canGoNext` | `boolean` | Whether navigating to the next step is possible |
+| `next` | `() => Promise<void>` | Advance to the next step (runs `onBeforeNext` guard if provided) |
+| `prev` | `() => void` | Go back to the previous step |
+| `goTo` | `(step: number) => void` | Jump to a specific step number |
+| `reset` | `() => void` | Reset to the initial step |
+
+### Uncontrolled Example
+
+```tsx
+import { useStepper, Stepper, Step, Button } from 'xertica-ui/ui';
+
+function OnboardingWizard() {
+  const { currentStep, isFirstStep, isLastStep, next, prev } = useStepper({
+    totalSteps: 3,
+  });
+
+  return (
+    <div className="space-y-8">
+      <Stepper currentStep={currentStep}>
+        <Step step={1} label="Account" />
+        <Step step={2} label="Plan" />
+        <Step step={3} label="Confirm" />
+      </Stepper>
+
+      <div className="min-h-[200px]">
+        {currentStep === 1 && <AccountForm />}
+        {currentStep === 2 && <PlanSelector />}
+        {currentStep === 3 && <ConfirmationSummary />}
+      </div>
+
+      <div className="flex justify-between">
+        <Button variant="outline" onClick={prev} disabled={isFirstStep}>
+          Previous
+        </Button>
+        <Button onClick={next} disabled={isLastStep}>
+          {isLastStep ? 'Finish' : 'Next'}
+        </Button>
+      </div>
+    </div>
+  );
+}
+```
+
+### With Async Validation Guard
+
+```tsx
+import { useStepper, Stepper, Step, Button } from 'xertica-ui/ui';
+import { useForm } from 'react-hook-form';
+
+function ValidatedWizard() {
+  const form = useForm();
+
+  const { currentStep, isFirstStep, isLastStep, next, prev } = useStepper({
+    totalSteps: 3,
+    onBeforeNext: async (step) => {
+      // Validate only the fields relevant to the current step
+      const fieldsPerStep: Record<number, string[]> = {
+        1: ['email', 'password'],
+        2: ['plan'],
+      };
+      const fields = fieldsPerStep[step];
+      if (!fields) return true;
+      return form.trigger(fields as never[]);
+    },
+  });
+
+  return (
+    <div className="space-y-8">
+      <Stepper currentStep={currentStep}>
+        <Step step={1} label="Account" />
+        <Step step={2} label="Plan" />
+        <Step step={3} label="Confirm" />
+      </Stepper>
+
+      <form>{/* step content */}</form>
+
+      <div className="flex justify-between">
+        <Button variant="outline" onClick={prev} disabled={isFirstStep}>
+          Previous
+        </Button>
+        <Button onClick={next}>
+          {isLastStep ? 'Submit' : 'Next'}
+        </Button>
+      </div>
+    </div>
+  );
+}
+```
+
+### Controlled Example
+
+```tsx
+import { useStepper } from 'xertica-ui/ui';
+import { useState } from 'react';
+
+function ControlledWizard() {
+  const [step, setStep] = useState(1);
+
+  const { currentStep, next, prev, isFirstStep, isLastStep } = useStepper({
+    totalSteps: 4,
+    step,               // controlled
+    onStepChange: setStep,
+  });
+
+  // currentStep === step at all times
+  return (/* ... */);
+}
+```
+
+---
+
 ## AI Rules
 
-- `step` props are **1-indexed** — the first step is `step={1}`, not `step={0}`.
+- `step` props on `<Step>` are **1-indexed** — the first step is `step={1}`, not `step={0}`.
 - Each `<Step>` `step` prop must match its position sequentially: `1, 2, 3, ...`.
 - `currentStep` on `<Stepper>` must be a number from `1` to the total number of steps.
 - Always render the navigation buttons (Previous/Next) below the Stepper.
-- Disable "Previous" on step `1` and "Next" on the final step.
-- Validate the current step's form data **before** advancing `currentStep`.
+- Disable "Previous" on step `1` (`isFirstStep`) and "Next" on the final step (`isLastStep`).
+- Use `onBeforeNext` for async form validation — return `false` to block advancing.
+- `next()` is **async** — always `await` it or use it as an `onClick` handler directly (React handles the Promise).
+- In controlled mode, pass both `step` and `onStepChange` — omitting `onStepChange` makes the hook read-only.
+- Use `reset()` to return to step 1 after a successful submission.
 
 ---
 

package/docs/components/tree-view.md

@@ -2,7 +2,21 @@
 
 ## Overview
 
-An interactive hierarchical tree component for displaying and navigating nested data structures — file systems, organizational charts, category trees, and recursive navigation menus.
+An interactive hierarchical tree component for displaying and navigating nested data structures — file systems, organizational charts, category trees, and recursive navigation menus. Supports keyboard navigation (Arrow keys, Home, End, Space), expand/collapse, and single-node selection.
+
+The package also exports a **headless `useTreeView` hook** for building fully custom tree UIs while reusing all the expand/collapse, selection, keyboard navigation, and focus management logic.
+
+---
+
+## Exports
+
+| Export | Description |
+|---|---|
+| `TreeView` | Ready-to-use hierarchical tree component |
+| `useTreeView` | Headless hook — all logic, no UI |
+| `TreeNode` | TypeScript type for a single tree node |
+| `UseTreeViewProps` | TypeScript props type for the hook |
+| `UseTreeViewReturn` | TypeScript return type for the hook |
 
 ---
 
@@ -17,13 +31,18 @@ An interactive hierarchical tree component for displaying and navigating nested
 
 ## Props
 
+### `TreeView`
+
 | Prop | Type | Required | Description |
 |---|---|---|---|
 | `data` | `TreeNode[]` | **Yes** | The tree data structure |
-| `onSelect` | `(node: TreeNode) => void` | No | Selection handler |
+| `defaultExpanded` | `string[]` | No | Node IDs to expand on initial render |
+| `selectedNodeId` | `string` | No | Controlled selected node ID |
+| `onNodeClick` | `(node: TreeNode) => void` | No | Called when any node is clicked |
+| `onNodeSelect` | `(node: TreeNode) => void` | No | Called when a node is selected (leaf or branch) |
 | `className` | `string` | No | Additional CSS classes |
 
-### TreeNode
+### `TreeNode`
 
 ```typescript
 interface TreeNode {
@@ -31,7 +50,6 @@ interface TreeNode {
   label: string;
   icon?: ReactNode;
   children?: TreeNode[];
-  disabled?: boolean;
 }
 ```
 
@@ -39,6 +57,8 @@ interface TreeNode {
 
 ## Examples
 
+### File System Browser
+
 ```tsx
 import { TreeView } from 'xertica-ui/ui';
 import { Folder, File } from 'lucide-react';
@@ -65,14 +85,152 @@ const tree = [
 
 <TreeView
   data={tree}
-  onSelect={(node) => console.log('Selected:', node.id)}
+  onNodeSelect={(node) => console.log('Selected:', node.id)}
+/>
+```
+
+### Pre-expanded Nodes
+
+```tsx
+<TreeView
+  data={tree}
+  defaultExpanded={['src', 'components']}
+  onNodeSelect={(node) => setSelectedFile(node.id)}
 />
 ```
 
 ---
 
+## `useTreeView` Hook
+
+A headless hook that manages expand/collapse state, selection, keyboard navigation, and focus refs for a tree structure. Use it when the `<TreeView>` component's visual design doesn't fit your needs.
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `data` | `TreeNode[]` | — | **Required.** The tree data structure |
+| `defaultExpanded` | `string[]` | `[]` | Node IDs to expand on initial render |
+| `selectedNodeId` | `string` | — | Controlled selected node ID — when provided, the hook uses this value instead of internal state |
+| `onNodeClick` | `(node: TreeNode) => void` | — | Called when any node is clicked |
+| `onNodeSelect` | `(node: TreeNode) => void` | — | Called when a node is selected |
+
+### Return Value
+
+| Property | Type | Description |
+|---|---|---|
+| `expanded` | `Set<string>` | Set of currently expanded node IDs |
+| `effectiveSelectedId` | `string \| undefined` | The currently selected node ID (controlled or internal) |
+| `nodeRefs` | `Map<string, HTMLButtonElement>` | Map of node ID → DOM button element refs |
+| `getNodeRef` | `(nodeId: string) => (el: HTMLButtonElement \| null) => void` | Ref callback factory — attach to each node's button element |
+| `toggleExpand` | `(nodeId: string) => void` | Toggle the expand/collapse state of a node |
+| `handleSelect` | `(node: TreeNode) => void` | Handle node selection (updates internal state and calls callbacks) |
+| `handleKeyDown` | `(e: KeyboardEvent, node: TreeNode) => void` | Full keyboard navigation handler — attach to each node's `onKeyDown` |
+| `getVisibleNodes` | `() => TreeNode[]` | Returns the flat list of currently visible (non-collapsed) nodes in DOM order |
+
+### Keyboard Navigation
+
+The `handleKeyDown` handler implements the WAI-ARIA tree pattern:
+
+| Key | Action |
+|---|---|
+| `ArrowDown` | Move focus to the next visible node |
+| `ArrowUp` | Move focus to the previous visible node |
+| `ArrowRight` | Expand a collapsed branch node; or move to first child if already expanded |
+| `ArrowLeft` | Collapse an expanded branch node; or move to parent if already collapsed |
+| `Home` | Move focus to the first node in the tree |
+| `End` | Move focus to the last visible node in the tree |
+| `Space` | Select the focused node |
+
+### Custom Tree Example
+
+```tsx
+import { useTreeView, TreeNode } from 'xertica-ui/ui';
+import { ChevronRight, ChevronDown, Folder, File } from 'lucide-react';
+import { cn } from '@/shared/utils';
+
+function CustomTree({ data }: { data: TreeNode[] }) {
+  const {
+    expanded,
+    effectiveSelectedId,
+    getNodeRef,
+    toggleExpand,
+    handleSelect,
+    handleKeyDown,
+  } = useTreeView({
+    data,
+    defaultExpanded: [],
+    onNodeSelect: (node) => console.log('Selected:', node.id),
+  });
+
+  const renderNode = (node: TreeNode, level: number): React.ReactNode => {
+    const hasChildren = !!node.children?.length;
+    const isExpanded = expanded.has(node.id);
+    const isSelected = effectiveSelectedId === node.id;
+
+    return (
+      <div key={node.id}>
+        <button
+          ref={getNodeRef(node.id)}
+          role="treeitem"
+          aria-expanded={hasChildren ? isExpanded : undefined}
+          aria-selected={isSelected}
+          onClick={() => {
+            if (hasChildren) toggleExpand(node.id);
+            handleSelect(node);
+          }}
+          onKeyDown={(e) => handleKeyDown(e, node)}
+          style={{ paddingLeft: `${level * 16}px` }}
+          className={cn(
+            "flex w-full items-center gap-2 rounded px-2 py-1 text-sm",
+            isSelected
+              ? "bg-primary text-primary-foreground"
+              : "hover:bg-accent"
+          )}
+        >
+          {hasChildren ? (
+            isExpanded
+              ? <ChevronDown className="size-4 shrink-0" />
+              : <ChevronRight className="size-4 shrink-0" />
+          ) : (
+            <span className="size-4 shrink-0" />
+          )}
+          {node.icon}
+          <span>{node.label}</span>
+        </button>
+
+        {hasChildren && isExpanded && (
+          <div role="group">
+            {node.children!.map(child => renderNode(child, level + 1))}
+          </div>
+        )}
+      </div>
+    );
+  };
+
+  return (
+    <div role="tree" className="w-full">
+      {data.map(node => renderNode(node, 0))}
+    </div>
+  );
+}
+```
+
+---
+
 ## AI Rules
 
-- Each `TreeNode` must have a unique `id` — the component uses it to track expand/collapse state.
+- Each `TreeNode` must have a unique `id` — the component uses it to track expand/collapse state and selection.
 - Leaf nodes (no `children`) do not show expand arrows.
 - Use `lucide-react` icons with `className="size-4"` consistently across all tree nodes.
+- When using `useTreeView`, attach `getNodeRef(node.id)` as the `ref` on each node's button — keyboard navigation (`handleKeyDown`) requires DOM refs to move focus.
+- Attach `handleKeyDown` to `onKeyDown` on every node button — omitting it breaks keyboard accessibility.
+- `getVisibleNodes()` returns only nodes that are currently visible (not inside a collapsed branch) — use it to compute `ArrowDown`/`ArrowUp` targets.
+- For controlled selection, pass `selectedNodeId` — the hook will use it as `effectiveSelectedId` instead of internal state.
+- `expanded` is a `Set<string>` — use `expanded.has(nodeId)` to check if a node is expanded.
+
+---
+
+## Related Components
+
+- [`Sidebar`](./sidebar.md) — Uses TreeView-style navigation for nested menu items