xertica-ui 2.1.2 → 2.1.4

package/docs/components/rich-text-editor.md

@@ -4,6 +4,13 @@
 
 A lightweight, native WYSIWYG (What You See Is What You Get) document text editor built into the Xertica UI framework. It utilizes the browser's native `contentEditable` architecture and `document.execCommand` under the hood to provide essential text formatting without the overhead of massive third-party rendering engines.
 
+The component ships in **two usage patterns**:
+
+| Pattern | When to use |
+|---|---|
+| `<RichTextEditor />` | Drop-in editor with full toolbar and status bar — zero configuration needed |
+| `useRichTextEditor()` | Headless hook — bring your own toolbar, layout, and styling |
+
 ---
 
 ## Features
@@ -38,6 +45,12 @@ A lightweight, native WYSIWYG (What You See Is What You Get) document text edito
 | `allowLists` | `boolean` | `true` | No | Whether to show list functionality in the toolbar. |
 | `showWordCount` | `boolean` | `true` | No | Whether to show the word count in the footer. |
 | `showCharacterCount` | `boolean` | `true` | No | Whether to show the character count in the footer. |
+| `disabled` | `boolean` | `false` | No | Disables all editing and applies opacity-50. Hides the toolbar. |
+| `readOnly` | `boolean` | `false` | No | Makes the editor non-editable while keeping full visual fidelity. Hides the toolbar. |
+| `onFocus` | `() => void` | — | No | Called when the editor area receives focus. |
+| `onBlur` | `() => void` | — | No | Called when the editor area loses focus. |
+| `minHeight` | `string` | — | No | Minimum height of the editable area (CSS value, e.g. `"200px"`). |
+| `maxHeight` | `string` | — | No | Maximum height of the editable area (CSS value, e.g. `"600px"`). |
 
 ---
 
@@ -70,6 +83,143 @@ export function EditorExample() {
 }
 ```
 
+### Minimal Toolbar
+
+```tsx
+<RichTextEditor
+  value={content}
+  onChange={setContent}
+  allowHeadings={false}
+  allowAlignment={false}
+  allowLists={false}
+  allowLinks={false}
+  allowSearch={false}
+  showWordCount={false}
+  showCharacterCount={false}
+/>
+```
+
+---
+
+## Headless Hook — `useRichTextEditor()`
+
+Use the headless hook when you need full control over the editor's UI — custom toolbar layout, custom styling, or embedding the editor logic inside a larger component.
+
+### Import
+
+```tsx
+import { useRichTextEditor } from 'xertica-ui/ui';
+```
+
+### Hook Props
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `string` | Yes | Current HTML value of the editor |
+| `onChange` | `(value: string) => void` | No | Called whenever the editor content changes |
+
+### Hook Return Value
+
+| Property | Type | Description |
+|---|---|---|
+| `editorRef` | `RefObject<HTMLDivElement>` | Attach to the `contenteditable` div |
+| `searchInputRef` | `RefObject<HTMLInputElement>` | Attach to the search `<input>` |
+| `linkInputRef` | `RefObject<HTMLInputElement>` | Attach to the link URL `<input>` |
+| `activeFormats` | `ActiveFormats` | Map of currently active formatting commands |
+| `isSearchOpen` | `boolean` | Whether the inline search bar is open |
+| `setIsSearchOpen` | `(open: boolean) => void` | Toggle the search bar |
+| `searchQuery` | `string` | Current search query string |
+| `setSearchQuery` | `(query: string) => void` | Update the search query |
+| `linkUrl` | `string` | Current link URL being edited |
+| `setLinkUrl` | `(url: string) => void` | Update the link URL |
+| `isLinkOpen` | `boolean` | Whether the link popover is open |
+| `wordCount` | `number` | Word count of the editor content |
+| `characterCount` | `number` | Character count of the editor content |
+| `updateActiveFormats` | `() => void` | Re-read the current selection and update `activeFormats` |
+| `execCommand` | `(command: string, value?: string) => void` | Execute a `document.execCommand` and sync state |
+| `handleInput` | `() => void` | Call on every `input` event of the editor |
+| `performSearch` | `(text: string, backward?: boolean) => void` | Search forward or backward |
+| `handleCreateLink` | `() => void` | Create or update a hyperlink at the current selection |
+| `handleUnlink` | `() => void` | Remove the hyperlink at the current cursor position |
+| `onLinkPopoverOpenChange` | `(open: boolean) => void` | Handle link popover open/close |
+
+### `ActiveFormats` Type
+
+```typescript
+interface ActiveFormats {
+  bold: boolean;
+  italic: boolean;
+  underline: boolean;
+  justifyLeft: boolean;
+  justifyCenter: boolean;
+  justifyRight: boolean;
+  insertUnorderedList: boolean;
+  insertOrderedList: boolean;
+  link: boolean;
+  h1: boolean;
+  h2: boolean;
+  h3: boolean;
+  p: boolean;
+}
+```
+
+### Headless Hook Example
+
+```tsx
+import { useState } from 'react';
+import { useRichTextEditor } from 'xertica-ui/ui';
+
+function MyMinimalEditor({ value, onChange }) {
+  const {
+    editorRef,
+    activeFormats,
+    execCommand,
+    handleInput,
+    wordCount,
+  } = useRichTextEditor({ value, onChange });
+
+  return (
+    <div className="border rounded-lg overflow-hidden">
+      {/* Custom minimal toolbar */}
+      <div className="flex gap-1 p-2 border-b bg-muted/30">
+        <button
+          onClick={() => execCommand('bold')}
+          className={activeFormats.bold ? 'font-bold text-primary' : 'text-muted-foreground'}
+        >
+          B
+        </button>
+        <button
+          onClick={() => execCommand('italic')}
+          className={activeFormats.italic ? 'italic text-primary' : 'text-muted-foreground'}
+        >
+          I
+        </button>
+        <button
+          onClick={() => execCommand('underline')}
+          className={activeFormats.underline ? 'underline text-primary' : 'text-muted-foreground'}
+        >
+          U
+        </button>
+      </div>
+
+      {/* Editor area */}
+      <div
+        ref={editorRef}
+        contentEditable
+        onInput={handleInput}
+        className="p-4 min-h-[200px] focus:outline-none"
+        data-placeholder="Start typing..."
+      />
+
+      {/* Custom footer */}
+      <div className="px-4 py-1 border-t text-xs text-muted-foreground">
+        {wordCount} words
+      </div>
+    </div>
+  );
+}
+```
+
 ---
 
 ## Component Architecture Notes
@@ -77,3 +227,17 @@ export function EditorExample() {
 - **Data Binding:** The editor takes `value` *only for its initial render mount*, then operates autonomously internally. It uses continuous `innerHTML` tracking out to the `onChange` event. Avoid forcefully re-rendering the component from the top-down while typing, as it can cause cursor jump displacement.
 - **Radix UI Interaction:** The `DropdownMenu` inside the toolbar is customized with `modal={false}` and intercepts `onPointerDown` events on its MenuItems. This is a critical technical choice that prevents modern React Portals from stealing DOM focus away from the `contentEditable` area when selecting Headings.
 - **CSS Encapsulation:** Core semantic elements (`h1`, `h2`, `h3`, `p`, `ul`, `b`, `i`) are uniquely targeted via the internal `.prose-editor` stylesheet, freeing the global scope from collisions.
+- **Headless Hook:** All state, refs, and DOM-manipulation logic live in `useRichTextEditor`. The `RichTextEditor` component is a thin presentation layer on top of this hook.
+
+---
+
+## AI Rules
+
+```
+- ALWAYS use `useRichTextEditor()` when building a custom editor UI — never re-implement `execCommand` logic manually.
+- The `editorRef` from the hook MUST be attached to the `contenteditable` div.
+- Call `handleInput` on every `onInput` event of the editor div to keep `onChange` and `activeFormats` in sync.
+- `execCommand` already calls `handleInput` internally — do not call both for the same action.
+- `wordCount` and `characterCount` are computed from `editorRef.current.innerText` — they update after `handleInput` is called.
+- The `activeFormats` object reflects the formatting state at the current cursor position. Use it to highlight active toolbar buttons.
+```

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