xertica-ui 2.1.2 → 2.1.4

package/components/ui/rich-text-editor/use-rich-text-editor.ts

@@ -0,0 +1,439 @@
+import { useRef, useState, useEffect, useCallback } from 'react';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export 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;
+}
+
+export interface UseRichTextEditorProps {
+    /** Current HTML value of the editor */
+    value: string;
+    /** Called whenever the editor content changes */
+    onChange?: (value: string) => void;
+}
+
+export interface UseRichTextEditorReturn {
+    // ── Refs ──────────────────────────────────────────────────────────────────
+    /** Attach to the `contenteditable` div */
+    editorRef: React.RefObject<HTMLDivElement>;
+    /** Attach to the search `<input>` */
+    searchInputRef: React.RefObject<HTMLInputElement>;
+    /** Attach to the link URL `<input>` */
+    linkInputRef: React.RefObject<HTMLInputElement>;
+
+    // ── State ─────────────────────────────────────────────────────────────────
+    /** Map of currently active formatting commands */
+    activeFormats: ActiveFormats;
+    /** Whether the inline search bar is open */
+    isSearchOpen: boolean;
+    setIsSearchOpen: (open: boolean) => void;
+    /** Current search query string */
+    searchQuery: string;
+    setSearchQuery: (query: string) => void;
+    /** Current link URL being edited */
+    linkUrl: string;
+    setLinkUrl: (url: string) => void;
+    /** Whether the link popover is open */
+    isLinkOpen: boolean;
+    /**
+     * True when the popover was opened with a non-collapsed text selection
+     * (or with the cursor inside an existing link). Use this to decide whether
+     * to show the link-insert form vs. the "select text first" hint.
+     */
+    hasSavedSelection: boolean;
+
+    // ── Computed ──────────────────────────────────────────────────────────────
+    /** Word count of the editor content */
+    wordCount: number;
+    /** Character count of the editor content */
+    characterCount: number;
+
+    // ── Handlers ──────────────────────────────────────────────────────────────
+    /** Re-read the current selection and update `activeFormats` */
+    updateActiveFormats: () => void;
+    /** Execute a `document.execCommand` and sync state */
+    execCommand: (command: string, value?: string) => void;
+    /** Called on every `input` event of the editor */
+    handleInput: () => void;
+    /** Search forward or backward for `searchQuery` */
+    performSearch: (text: string, backward?: boolean) => void;
+    /** Create or update a hyperlink at the current selection */
+    handleCreateLink: () => void;
+    /** Remove the hyperlink at the current cursor position */
+    handleUnlink: () => void;
+    /** Handle link popover open/close (saves selection, pre-fills URL) */
+    onLinkPopoverOpenChange: (open: boolean) => void;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Hook
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * `useRichTextEditor` — Headless hook for the RichTextEditor component.
+ *
+ * Encapsulates all state, refs, and DOM-manipulation logic for a
+ * `contenteditable`-based rich text editor. Use this hook when you need to
+ * build a fully custom editor UI while reusing the same formatting logic as
+ * the default `RichTextEditor` component.
+ *
+ * @example
+ * ```tsx
+ * import { useRichTextEditor } from 'xertica-ui/ui';
+ *
+ * function MyEditor({ value, onChange }) {
+ *   const {
+ *     editorRef,
+ *     activeFormats,
+ *     execCommand,
+ *     handleInput,
+ *     wordCount,
+ *   } = useRichTextEditor({ value, onChange });
+ *
+ *   return (
+ *     <div>
+ *       <button
+ *         onClick={() => execCommand('bold')}
+ *         style={{ fontWeight: activeFormats.bold ? 'bold' : 'normal' }}
+ *       >
+ *         B
+ *       </button>
+ *       <div
+ *         ref={editorRef}
+ *         contentEditable
+ *         onInput={handleInput}
+ *       />
+ *       <span>{wordCount} words</span>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useRichTextEditor({
+    value,
+    onChange,
+}: UseRichTextEditorProps): UseRichTextEditorReturn {
+
+    // ── Refs ────────────────────────────────────────────────────────────────────
+    const editorRef = useRef<HTMLDivElement>(null);
+    const searchInputRef = useRef<HTMLInputElement>(null);
+    const linkInputRef = useRef<HTMLInputElement>(null);
+    const savedSelection = useRef<Range | null>(null);
+
+    // ── State ───────────────────────────────────────────────────────────────────
+    const [activeFormats, setActiveFormats] = useState<ActiveFormats>({
+        bold: false,
+        italic: false,
+        underline: false,
+        justifyLeft: false,
+        justifyCenter: false,
+        justifyRight: false,
+        insertUnorderedList: false,
+        insertOrderedList: false,
+        link: false,
+        h1: false,
+        h2: false,
+        h3: false,
+        p: true,
+    });
+    const [isSearchOpen, setIsSearchOpen] = useState(false);
+    const [searchQuery, setSearchQuery] = useState('');
+    const [linkUrl, setLinkUrl] = useState('https://');
+    const [isLinkOpen, setIsLinkOpen] = useState(false);
+    const [hasSavedSelection, setHasSavedSelection] = useState(false);
+
+    // ── Helpers ─────────────────────────────────────────────────────────────────
+
+    const findParentTag = useCallback((node: Node | null, tagName: string): HTMLElement | null => {
+        let current = node;
+        while (current && current !== editorRef.current) {
+            if (current.nodeName === tagName) return current as HTMLElement;
+            current = current.parentNode;
+        }
+        return null;
+    }, []);
+
+    const updateActiveFormats = useCallback(() => {
+        let formatBlock = '';
+        try {
+            formatBlock = document.queryCommandValue('formatBlock');
+        } catch (_e) { /* ignore */ }
+
+        const selection = window.getSelection();
+        const anchorNode = selection?.anchorNode;
+        const focusNode = selection?.focusNode;
+
+        setActiveFormats({
+            bold: document.queryCommandState('bold'),
+            italic: document.queryCommandState('italic'),
+            underline: document.queryCommandState('underline'),
+            justifyLeft: document.queryCommandState('justifyLeft'),
+            justifyCenter: document.queryCommandState('justifyCenter'),
+            justifyRight: document.queryCommandState('justifyRight'),
+            insertUnorderedList: document.queryCommandState('insertUnorderedList'),
+            insertOrderedList: document.queryCommandState('insertOrderedList'),
+            link: !!(findParentTag(anchorNode || null, 'A') || findParentTag(focusNode || null, 'A')),
+            h1: formatBlock === 'h1' || formatBlock === 'H1',
+            h2: formatBlock === 'h2' || formatBlock === 'H2',
+            h3: formatBlock === 'h3' || formatBlock === 'H3',
+            p: formatBlock === 'p' || formatBlock === 'P' || formatBlock === 'div' || formatBlock === 'DIV' || formatBlock === '',
+        });
+    }, [findParentTag]);
+
+    // ── Effects ─────────────────────────────────────────────────────────────────
+
+    // Initialize editor content and listen for selection changes
+    useEffect(() => {
+        if (editorRef.current && editorRef.current.innerHTML !== value) {
+            editorRef.current.innerHTML = value;
+        }
+
+        const handleSelectionChange = () => {
+            if (document.activeElement === editorRef.current) {
+                updateActiveFormats();
+            }
+        };
+
+        document.addEventListener('selectionchange', handleSelectionChange);
+        return () => document.removeEventListener('selectionchange', handleSelectionChange);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+
+    // ── Computed ────────────────────────────────────────────────────────────────
+
+    const wordCount = (() => {
+        const text = editorRef.current?.innerText || '';
+        return text.trim() ? text.trim().split(/\s+/).length : 0;
+    })();
+
+    const characterCount = (() => {
+        const text = editorRef.current?.innerText || '';
+        return text.trim() ? text.length : 0;
+    })();
+
+    // ── Handlers ────────────────────────────────────────────────────────────────
+
+    const handleInput = useCallback(() => {
+        if (editorRef.current) {
+            onChange?.(editorRef.current.innerHTML);
+            updateActiveFormats();
+        }
+    }, [onChange, updateActiveFormats]);
+
+    const execCommand = useCallback((command: string, val: string = '') => {
+        document.execCommand(command, false, val);
+        updateActiveFormats();
+        editorRef.current?.focus();
+        if (editorRef.current) {
+            onChange?.(editorRef.current.innerHTML);
+        }
+    }, [onChange, updateActiveFormats]);
+
+    const performSearch = useCallback((text: string, backward = false) => {
+        if (!text || !editorRef.current) return;
+
+        const editor = editorRef.current;
+        const selection = window.getSelection();
+        if (!selection) return;
+
+        const walker = document.createTreeWalker(editor, NodeFilter.SHOW_TEXT);
+        const segments: Array<{ node: Text; start: number }> = [];
+        let offset = 0;
+        let node: Node | null;
+        while ((node = walker.nextNode())) {
+            segments.push({ node: node as Text, start: offset });
+            offset += (node as Text).length;
+        }
+        const fullText = segments.reduce((acc, s) => acc + (s.node.textContent ?? ''), '');
+
+        let searchFrom = 0;
+        if (selection.rangeCount > 0) {
+            const range = selection.getRangeAt(0);
+            if (editor.contains(range.startContainer)) {
+                const seg = segments.find(s => s.node === range.startContainer);
+                if (seg) {
+                    searchFrom = backward
+                        ? seg.start + range.startOffset - 1
+                        : seg.start + range.endOffset;
+                }
+            }
+        }
+
+        const lowerFull = fullText.toLowerCase();
+        const lowerQuery = text.toLowerCase();
+        let matchStart = -1;
+
+        if (backward) {
+            matchStart = lowerFull.lastIndexOf(lowerQuery, Math.max(0, searchFrom));
+            if (matchStart === -1) matchStart = lowerFull.lastIndexOf(lowerQuery);
+        } else {
+            matchStart = lowerFull.indexOf(lowerQuery, searchFrom);
+            if (matchStart === -1) matchStart = lowerFull.indexOf(lowerQuery);
+        }
+
+        if (matchStart === -1) return;
+
+        const matchEnd = matchStart + text.length;
+        const range = document.createRange();
+        let startSet = false;
+        let endSet = false;
+
+        for (let i = 0; i < segments.length && !endSet; i++) {
+            const seg = segments[i];
+            const segEnd = seg.start + seg.node.length;
+
+            if (!startSet && matchStart < segEnd && matchStart >= seg.start) {
+                range.setStart(seg.node, matchStart - seg.start);
+                startSet = true;
+            }
+            if (startSet && matchEnd <= segEnd) {
+                range.setEnd(seg.node, matchEnd - seg.start);
+                endSet = true;
+            }
+        }
+
+        if (startSet && endSet) {
+            selection.removeAllRanges();
+            selection.addRange(range);
+            (range.startContainer as Element).parentElement?.scrollIntoView?.({ block: 'nearest' });
+        }
+    }, []);
+
+    const handleCreateLink = useCallback(() => {
+        if (savedSelection.current) {
+            const selection = window.getSelection();
+            selection?.removeAllRanges();
+            selection?.addRange(savedSelection.current);
+        }
+
+        const selection = window.getSelection();
+        const anchorNode = selection?.anchorNode;
+        const existingLink = findParentTag(anchorNode || null, 'A');
+
+        if (existingLink) {
+            if (linkUrl) {
+                existingLink.setAttribute('href', linkUrl);
+                existingLink.setAttribute('target', '_blank');
+                existingLink.setAttribute('rel', 'noopener noreferrer');
+                existingLink.style.color = 'hsl(var(--primary))';
+                existingLink.style.textDecoration = 'underline';
+                existingLink.style.cursor = 'pointer';
+            }
+            handleInput();
+            setIsLinkOpen(false);
+            savedSelection.current = null;
+            return;
+        }
+
+        if (!selection || selection.rangeCount === 0 || selection.isCollapsed) {
+            return;
+        }
+
+        if (linkUrl) {
+            document.execCommand('createLink', false, linkUrl);
+            setTimeout(() => {
+                const anchor = findParentTag(window.getSelection()?.anchorNode || null, 'A');
+                if (anchor) {
+                    anchor.setAttribute('target', '_blank');
+                    anchor.setAttribute('rel', 'noopener noreferrer');
+                    anchor.style.color = 'hsl(var(--primary))';
+                    anchor.style.textDecoration = 'underline';
+                    anchor.style.cursor = 'pointer';
+                }
+                handleInput();
+            }, 10);
+            setIsLinkOpen(false);
+            savedSelection.current = null;
+        }
+    }, [linkUrl, findParentTag, handleInput]);
+
+    const handleUnlink = useCallback(() => {
+        const selection = window.getSelection();
+        const anchorNode = selection?.anchorNode;
+        const existingLink = findParentTag(anchorNode || null, 'A');
+
+        if (existingLink) {
+            const parent = existingLink.parentNode;
+            while (existingLink.firstChild) {
+                parent?.insertBefore(existingLink.firstChild, existingLink);
+            }
+            parent?.removeChild(existingLink);
+            handleInput();
+        } else {
+            document.execCommand('unlink', false, '');
+        }
+    }, [findParentTag, handleInput]);
+
+    const onLinkPopoverOpenChange = useCallback((open: boolean) => {
+        if (open) {
+            const selection = window.getSelection();
+            const anchorNode = selection?.anchorNode;
+            const focusNode = selection?.focusNode;
+            const existingLink = findParentTag(anchorNode || null, 'A') || findParentTag(focusNode || null, 'A');
+
+            if (existingLink) {
+                setLinkUrl(existingLink.getAttribute('href') || 'https://');
+            } else {
+                setLinkUrl('https://');
+            }
+
+            // Save the selection whenever there is one (collapsed or not) so
+            // handleCreateLink can restore it after the popover steals focus.
+            // Also mark hasSavedSelection so the UI can show the insert form.
+            if (selection && selection.rangeCount > 0 && (!selection.isCollapsed || existingLink)) {
+                savedSelection.current = selection.getRangeAt(0).cloneRange();
+                setHasSavedSelection(true);
+            } else {
+                savedSelection.current = null;
+                setHasSavedSelection(false);
+            }
+            setTimeout(() => linkInputRef.current?.focus(), 100);
+        } else {
+            setHasSavedSelection(false);
+        }
+        setIsLinkOpen(open);
+    }, [findParentTag]);
+
+    return {
+        // Refs
+        editorRef,
+        searchInputRef,
+        linkInputRef,
+        // State
+        activeFormats,
+        isSearchOpen,
+        setIsSearchOpen,
+        searchQuery,
+        setSearchQuery,
+        linkUrl,
+        setLinkUrl,
+        isLinkOpen,
+        hasSavedSelection,
+        // Computed
+        wordCount,
+        characterCount,
+        // Handlers
+        updateActiveFormats,
+        execCommand,
+        handleInput,
+        performSearch,
+        handleCreateLink,
+        handleUnlink,
+        onLinkPopoverOpenChange,
+    };
+}

package/components/ui/stepper/index.ts

@@ -1 +1,3 @@
-export * from './stepper';
+export { Stepper, Step, useStepperContext } from './stepper';
+export { useStepper } from './use-stepper';
+export type { UseStepperProps, UseStepperReturn } from './use-stepper';

package/components/ui/stepper/stepper.stories.tsx

@@ -1,8 +1,11 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import { Stepper, Step } from './stepper';
+import { useStepper } from './use-stepper';
 import { Button } from '../button';
 import { Card, CardContent, CardFooter, CardHeader, CardTitle } from '../card';
 import React, { useState } from 'react';
+import { Check } from 'lucide-react';
+import { cn } from '../../shared/utils';
 
 const meta: Meta<typeof Stepper> = {
   title: 'UI/Stepper',
@@ -56,3 +59,116 @@ export const Default: Story = {
     );
   },
 };
+
+/**
+ * ## useStepper — Headless Hook
+ *
+ * Use `useStepper` when you need step navigation logic (next/prev/goTo,
+ * async validation guard, first/last flags) but want to render a completely
+ * custom step indicator UI — or when the step controls live far away from
+ * the `<Stepper>` visual component.
+ *
+ * The `onBeforeNext` guard lets you run async form validation before the
+ * step advances. Return `false` to block the transition.
+ *
+ * ```tsx
+ * import { useStepper } from '@xertica/ui/stepper';
+ *
+ * const { currentStep, totalSteps, next, prev, isFirstStep, isLastStep } =
+ *   useStepper({ totalSteps: 3, onBeforeNext: () => form.trigger() });
+ * ```
+ */
+export const HeadlessHook: Story = {
+  name: 'useStepper (headless)',
+  render: () => {
+    const steps = [
+      { id: 1, label: 'Personal Info', content: 'Fill in your name and email.' },
+      { id: 2, label: 'Address', content: 'Enter your shipping address.' },
+      { id: 3, label: 'Review', content: 'Confirm your details before submitting.' },
+    ];
+
+    const {
+      currentStep,
+      totalSteps,
+      next,
+      prev,
+      goTo,
+      isFirstStep,
+      isLastStep,
+      canGoPrev,
+    } = useStepper({
+      totalSteps: steps.length,
+      // Simulate async validation — always passes in this demo
+      onBeforeNext: async (step) => {
+        console.log(`Validating step ${step}…`);
+        await new Promise((r) => setTimeout(r, 300));
+        return true;
+      },
+    });
+
+    return (
+      <div className="w-[520px] space-y-6">
+        {/* Custom step indicator — pill style */}
+        <nav aria-label="Progress" className="flex items-center gap-2">
+          {steps.map((step, idx) => {
+            const isCompleted = step.id < currentStep;
+            const isActive = step.id === currentStep;
+            return (
+              <React.Fragment key={step.id}>
+                <button
+                  onClick={() => goTo(step.id)}
+                  className={cn(
+                    'flex items-center gap-2 rounded-full px-3 py-1.5 text-sm font-medium transition-colors',
+                    isActive && 'bg-primary text-primary-foreground',
+                    isCompleted && 'bg-primary/20 text-primary hover:bg-primary/30',
+                    !isActive && !isCompleted && 'bg-muted text-muted-foreground hover:bg-muted/80'
+                  )}
+                  aria-current={isActive ? 'step' : undefined}
+                >
+                  {isCompleted ? (
+                    <Check className="h-3.5 w-3.5" />
+                  ) : (
+                    <span className="flex h-4 w-4 items-center justify-center rounded-full border border-current text-xs">
+                      {step.id}
+                    </span>
+                  )}
+                  {step.label}
+                </button>
+                {idx < steps.length - 1 && (
+                  <div className={cn('h-px flex-1', step.id < currentStep ? 'bg-primary' : 'bg-border')} />
+                )}
+              </React.Fragment>
+            );
+          })}
+        </nav>
+
+        {/* Step content */}
+        <div className="rounded-xl border bg-card p-6 shadow-sm">
+          <h3 className="mb-1 font-semibold">{steps[currentStep - 1].label}</h3>
+          <p className="text-sm text-muted-foreground">{steps[currentStep - 1].content}</p>
+
+          <div className="mt-6 flex h-20 items-center justify-center rounded-lg border border-dashed text-sm text-muted-foreground">
+            Step {currentStep} of {totalSteps} — form fields go here
+          </div>
+        </div>
+
+        {/* Navigation controls */}
+        <div className="flex justify-between">
+          <Button variant="outline" onClick={prev} disabled={!canGoPrev}>
+            Back
+          </Button>
+          <Button onClick={() => next()}>
+            {isLastStep ? 'Submit' : 'Continue'}
+          </Button>
+        </div>
+
+        {isFirstStep && (
+          <p className="text-center text-xs text-muted-foreground">
+            Step navigation is driven entirely by <code>useStepper</code> — no{' '}
+            <code>&lt;Stepper&gt;</code> component used.
+          </p>
+        )}
+      </div>
+    );
+  },
+};

package/components/ui/stepper/stepper.tsx

@@ -10,9 +10,9 @@ interface StepperContextValue {
 
 const StepperContext = React.createContext<StepperContextValue | undefined>(undefined);
 
-const useStepper = () => {
+const useStepperContext = () => {
   const context = React.useContext(StepperContext);
-  if (!context) throw new Error("useStepper must be used within a Stepper");
+  if (!context) throw new Error("useStepperContext must be used within a Stepper");
   return context;
 };
 
@@ -69,7 +69,7 @@ interface StepProps extends React.HTMLAttributes<HTMLDivElement> {
 
 const Step = React.forwardRef<HTMLDivElement, StepProps>(
   ({ step, label, description, error = false, className, ...props }, ref) => {
-    const { currentStep, totalSteps, orientation } = useStepper();
+    const { currentStep, totalSteps, orientation } = useStepperContext();
     const isActive = step === currentStep;
     const isCompleted = step < currentStep && !error;
     const isFirst = step === 1;
@@ -146,4 +146,4 @@ const Step = React.forwardRef<HTMLDivElement, StepProps>(
 );
 Step.displayName = "Step";
 
-export { Stepper, Step, useStepper };
+export { Stepper, Step, useStepperContext };