xertica-ui 2.1.2 → 2.1.3

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

@@ -0,0 +1,194 @@
+import { useState, useCallback, useMemo } from 'react';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** A page item rendered in the pagination bar. */
+export type PaginationPageItem =
+    | { type: 'page'; page: number }
+    | { type: 'ellipsis'; key: string };
+
+export interface UsePaginationProps {
+    /** Total number of items in the data set. */
+    totalItems: number;
+    /** Number of items per page. @default 10 */
+    pageSize?: number;
+    /** Initial page (1-indexed). @default 1 */
+    initialPage?: number;
+    /**
+     * Controlled current page (1-indexed).
+     * When provided, page state is managed externally via `onPageChange`.
+     */
+    page?: number;
+    /** Called whenever the page changes. */
+    onPageChange?: (page: number) => void;
+    /**
+     * Number of page buttons to show on each side of the current page.
+     * @default 1
+     */
+    siblingCount?: number;
+}
+
+export interface UsePaginationReturn {
+    // ── State ─────────────────────────────────────────────────────────────────
+    /** The currently active page (1-indexed). */
+    currentPage: number;
+    /** Total number of pages. */
+    totalPages: number;
+    /** Index of the first item on the current page (0-indexed, useful for slicing). */
+    startIndex: number;
+    /** Index of the last item on the current page (exclusive, useful for slicing). */
+    endIndex: number;
+
+    // ── Flags ─────────────────────────────────────────────────────────────────
+    /** Whether there is a previous page available. */
+    canGoPrev: boolean;
+    /** Whether there is a next page available. */
+    canGoNext: boolean;
+    /** Whether the current page is the first page. */
+    isFirstPage: boolean;
+    /** Whether the current page is the last page. */
+    isLastPage: boolean;
+
+    // ── Computed ──────────────────────────────────────────────────────────────
+    /**
+     * Ordered list of items to render in the pagination bar.
+     * Each item is either a `{ type: 'page', page: number }` or
+     * `{ type: 'ellipsis', key: string }`.
+     */
+    items: PaginationPageItem[];
+
+    // ── Handlers ──────────────────────────────────────────────────────────────
+    /** Navigate to a specific page (1-indexed, clamped to valid range). */
+    goTo: (page: number) => void;
+    /** Navigate to the next page (no-op if already on the last page). */
+    next: () => void;
+    /** Navigate to the previous page (no-op if already on the first page). */
+    prev: () => void;
+    /** Navigate to the first page. */
+    first: () => void;
+    /** Navigate to the last page. */
+    last: () => void;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Hook
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Headless hook for pagination logic.
+ *
+ * @description
+ * Computes the current page, total pages, slice indices, and the ordered list
+ * of page items (numbers + ellipses) to render. Supports both controlled and
+ * uncontrolled modes. Pair with any custom pagination UI or with the
+ * `<Pagination>` visual components.
+ *
+ * @example
+ * ```tsx
+ * const { currentPage, totalPages, items, next, prev, goTo, canGoPrev, canGoNext } =
+ *   usePagination({ totalItems: 200, pageSize: 20 });
+ * ```
+ */
+export function usePagination({
+    totalItems,
+    pageSize = 10,
+    initialPage = 1,
+    page: controlledPage,
+    onPageChange,
+    siblingCount = 1,
+}: UsePaginationProps): UsePaginationReturn {
+    const [internalPage, setInternalPage] = useState(initialPage);
+
+    const isControlled = controlledPage !== undefined;
+    const currentPage = isControlled ? controlledPage! : internalPage;
+
+    const totalPages = Math.max(1, Math.ceil(totalItems / pageSize));
+
+    const setPage = useCallback(
+        (p: number) => {
+            const clamped = Math.min(Math.max(1, p), totalPages);
+            if (!isControlled) setInternalPage(clamped);
+            onPageChange?.(clamped);
+        },
+        [isControlled, onPageChange, totalPages]
+    );
+
+    // ── Derived ───────────────────────────────────────────────────────────────
+
+    const startIndex = (currentPage - 1) * pageSize;
+    const endIndex = Math.min(startIndex + pageSize, totalItems);
+    const canGoPrev = currentPage > 1;
+    const canGoNext = currentPage < totalPages;
+    const isFirstPage = currentPage === 1;
+    const isLastPage = currentPage === totalPages;
+
+    // ── Page items (numbers + ellipses) ───────────────────────────────────────
+
+    const items = useMemo((): PaginationPageItem[] => {
+        // Always show first, last, current ± siblingCount
+        const range = (start: number, end: number): number[] =>
+            Array.from({ length: end - start + 1 }, (_, i) => start + i);
+
+        const leftSibling = Math.max(currentPage - siblingCount, 1);
+        const rightSibling = Math.min(currentPage + siblingCount, totalPages);
+
+        const showLeftEllipsis = leftSibling > 2;
+        const showRightEllipsis = rightSibling < totalPages - 1;
+
+        const result: PaginationPageItem[] = [];
+
+        // First page
+        result.push({ type: 'page', page: 1 });
+
+        if (showLeftEllipsis) {
+            result.push({ type: 'ellipsis', key: 'ellipsis-left' });
+        } else if (leftSibling === 2) {
+            result.push({ type: 'page', page: 2 });
+        }
+
+        // Sibling range (excluding first and last)
+        for (const p of range(Math.max(leftSibling, 2), Math.min(rightSibling, totalPages - 1))) {
+            result.push({ type: 'page', page: p });
+        }
+
+        if (showRightEllipsis) {
+            result.push({ type: 'ellipsis', key: 'ellipsis-right' });
+        } else if (rightSibling === totalPages - 1) {
+            result.push({ type: 'page', page: totalPages - 1 });
+        }
+
+        // Last page (only if more than 1 page)
+        if (totalPages > 1) {
+            result.push({ type: 'page', page: totalPages });
+        }
+
+        return result;
+    }, [currentPage, siblingCount, totalPages]);
+
+    // ── Handlers ──────────────────────────────────────────────────────────────
+
+    const goTo = useCallback((p: number) => setPage(p), [setPage]);
+    const next = useCallback(() => setPage(currentPage + 1), [currentPage, setPage]);
+    const prev = useCallback(() => setPage(currentPage - 1), [currentPage, setPage]);
+    const first = useCallback(() => setPage(1), [setPage]);
+    const last = useCallback(() => setPage(totalPages), [setPage, totalPages]);
+
+    return {
+        currentPage,
+        totalPages,
+        startIndex,
+        endIndex,
+        canGoPrev,
+        canGoNext,
+        isFirstPage,
+        isLastPage,
+        items,
+        goTo,
+        next,
+        prev,
+        first,
+        last,
+    };
+}

package/components/ui/popover/popover.mdx

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

package/components/ui/progress/progress.mdx

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

package/components/ui/progress/progress.tsx

@@ -1,68 +1,68 @@
-"use client";
-
-import * as React from "react";
-import * as ProgressPrimitive from "@radix-ui/react-progress";
-
-import { cn } from "../../shared/utils";
-
-type ProgressVariant = "default" | "success" | "info" | "warning" | "destructive";
-
-const trackVariants: Record<ProgressVariant, string> = {
-  default: "bg-primary/20",
-  success: "bg-success/20",
-  info: "bg-info/20",
-  warning: "bg-warning/20",
-  destructive: "bg-destructive/20",
-};
-
-const indicatorVariants: Record<ProgressVariant, string> = {
-  default: "bg-primary",
-  success: "bg-success",
-  info: "bg-info",
-  warning: "bg-warning",
-  destructive: "bg-destructive",
-};
-
-/**
- * Numeric progress bar from 0 to 100.
- *
- * @description
- * Indicates deterministic task progress (file upload %, form completion steps, etc.).
- * Built on Radix UI Progress with smooth CSS transition.
- *
- * @ai-rules
- * 1. Control progress via the `value` prop (e.g., `value={66}`).
- * 2. Use `variant` to communicate semantic state: `success`, `info`, `warning`, `destructive`.
- * 3. For indeterminate / infinite loading, use `<Loader2 className="animate-spin" />` — not `<Progress>`.
- * 4. Available variants: `default`, `success`, `info`, `warning`, `destructive`.
- */
-function Progress({
-  className,
-  value,
-  variant = "default",
-  ...props
-}: React.ComponentProps<typeof ProgressPrimitive.Root> & {
-  variant?: ProgressVariant;
-}) {
-  return (
-    <ProgressPrimitive.Root
-      data-slot="progress"
-      aria-label={props["aria-label"] || "Progresso"}
-      className={cn(
-        "relative h-2 w-full overflow-hidden rounded-full",
-        trackVariants[variant],
-        className,
-      )}
-      {...props}
-    >
-      <ProgressPrimitive.Indicator
-        data-slot="progress-indicator"
-        className={cn("h-full w-full flex-1 transition-all", indicatorVariants[variant])}
-        style={{ transform: `translateX(-${100 - (value || 0)}%)` }}
-      />
-    </ProgressPrimitive.Root>
-  );
-}
-
-export { Progress };
-export type { ProgressVariant };
+"use client";
+
+import * as React from "react";
+import * as ProgressPrimitive from "@radix-ui/react-progress";
+
+import { cn } from "../../shared/utils";
+
+type ProgressVariant = "default" | "success" | "info" | "warning" | "destructive";
+
+const trackVariants: Record<ProgressVariant, string> = {
+  default: "bg-primary/20",
+  success: "bg-success/20",
+  info: "bg-info/20",
+  warning: "bg-warning/20",
+  destructive: "bg-destructive/20",
+};
+
+const indicatorVariants: Record<ProgressVariant, string> = {
+  default: "bg-primary",
+  success: "bg-success",
+  info: "bg-info",
+  warning: "bg-warning",
+  destructive: "bg-destructive",
+};
+
+/**
+ * Numeric progress bar from 0 to 100.
+ *
+ * @description
+ * Indicates deterministic task progress (file upload %, form completion steps, etc.).
+ * Built on Radix UI Progress with smooth CSS transition.
+ *
+ * @ai-rules
+ * 1. Control progress via the `value` prop (e.g., `value={66}`).
+ * 2. Use `variant` to communicate semantic state: `success`, `info`, `warning`, `destructive`.
+ * 3. For indeterminate / infinite loading, use `<Loader2 className="animate-spin" />` — not `<Progress>`.
+ * 4. Available variants: `default`, `success`, `info`, `warning`, `destructive`.
+ */
+function Progress({
+  className,
+  value,
+  variant = "default",
+  ...props
+}: React.ComponentProps<typeof ProgressPrimitive.Root> & {
+  variant?: ProgressVariant;
+}) {
+  return (
+    <ProgressPrimitive.Root
+      data-slot="progress"
+      aria-label={props["aria-label"] || "Progresso"}
+      className={cn(
+        "relative h-2 w-full overflow-hidden rounded-full",
+        trackVariants[variant],
+        className,
+      )}
+      {...props}
+    >
+      <ProgressPrimitive.Indicator
+        data-slot="progress-indicator"
+        className={cn("h-full w-full flex-1 transition-all", indicatorVariants[variant])}
+        style={{ transform: `translateX(-${100 - (value || 0)}%)` }}
+      />
+    </ProgressPrimitive.Root>
+  );
+}
+
+export { Progress };
+export type { ProgressVariant };

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

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

package/components/ui/rating/rating.mdx

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

package/components/ui/resizable/resizable.mdx

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

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

@@ -1 +1,3 @@
 export * from './rich-text-editor';
+export { useRichTextEditor } from './use-rich-text-editor';
+export type { UseRichTextEditorProps, UseRichTextEditorReturn, ActiveFormats } from './use-rich-text-editor';

package/components/ui/rich-text-editor/rich-text-editor.stories.tsx

@@ -1,7 +1,8 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import { RichTextEditor } from './rich-text-editor';
+import { useRichTextEditor } from './use-rich-text-editor';
 import { Button } from '../button';
-import { Check, Save } from 'lucide-react';
+import { Check, Bold, Italic, Underline, Link, Unlink, Search } from 'lucide-react';
 import React, { useState } from 'react';
 
 const meta: Meta<typeof RichTextEditor> = {
@@ -132,3 +133,130 @@ export const Empty: Story = {
   ),
 };
 
+/**
+ * **Headless Hook** — demonstrates `useRichTextEditor()` with a fully custom UI.
+ *
+ * The hook manages all editor state (active formats, search, link popover,
+ * word/character counts) while you supply your own markup and toolbar.
+ * This story renders a minimal custom toolbar + `contenteditable` div
+ * without using `<RichTextEditor>` at all.
+ */
+export const HeadlessHook: Story = {
+  render: () => {
+    const [value, setValue] = useState(
+      '<p>Edit this text using the <strong>custom toolbar</strong> below.</p>'
+    );
+
+    const {
+      editorRef,
+      linkInputRef,
+      activeFormats,
+      isLinkOpen,
+      linkUrl,
+      setLinkUrl,
+      wordCount,
+      characterCount,
+      execCommand,
+      handleInput,
+      updateActiveFormats,
+      handleCreateLink,
+      handleUnlink,
+      onLinkPopoverOpenChange,
+    } = useRichTextEditor({ value, onChange: setValue });
+
+    const btnClass = (active: boolean) =>
+      `px-2 py-1 rounded text-sm border transition-colors ${active
+        ? 'bg-primary text-primary-foreground border-primary'
+        : 'bg-background text-foreground border-border hover:bg-muted'
+      }`;
+
+    return (
+      <div className="w-full max-w-2xl mx-auto p-6 space-y-4">
+        <div className="text-sm text-muted-foreground font-medium">
+          Custom headless editor — built with <code className="bg-muted px-1 rounded">useRichTextEditor()</code>
+        </div>
+
+        {/* Custom toolbar */}
+        <div className="flex items-center gap-1 p-2 border border-border rounded-lg bg-muted/30 flex-wrap">
+          <button
+            className={btnClass(activeFormats.bold)}
+            onMouseDown={(e) => { e.preventDefault(); execCommand('bold'); }}
+            title="Bold"
+          >
+            <Bold className="w-4 h-4" />
+          </button>
+          <button
+            className={btnClass(activeFormats.italic)}
+            onMouseDown={(e) => { e.preventDefault(); execCommand('italic'); }}
+            title="Italic"
+          >
+            <Italic className="w-4 h-4" />
+          </button>
+          <button
+            className={btnClass(activeFormats.underline)}
+            onMouseDown={(e) => { e.preventDefault(); execCommand('underline'); }}
+            title="Underline"
+          >
+            <Underline className="w-4 h-4" />
+          </button>
+
+          <div className="w-px h-5 bg-border mx-1" />
+
+          {/* Link controls */}
+          <div className="relative flex items-center gap-1">
+            <button
+              className={btnClass(isLinkOpen || activeFormats.link)}
+              onMouseDown={(e) => { e.preventDefault(); onLinkPopoverOpenChange(!isLinkOpen); }}
+              title="Insert link"
+            >
+              <Link className="w-4 h-4" />
+            </button>
+            {activeFormats.link && (
+              <button
+                className={btnClass(false)}
+                onMouseDown={(e) => { e.preventDefault(); handleUnlink(); }}
+                title="Remove link"
+              >
+                <Unlink className="w-4 h-4" />
+              </button>
+            )}
+            {isLinkOpen && (
+              <div className="absolute top-full left-0 mt-1 z-50 bg-popover border border-border rounded-lg shadow-lg p-3 flex gap-2 w-72">
+                <input
+                  ref={linkInputRef}
+                  type="url"
+                  value={linkUrl}
+                  onChange={(e) => setLinkUrl(e.target.value)}
+                  placeholder="https://example.com"
+                  className="flex-1 text-sm border border-border rounded px-2 py-1 bg-background"
+                  onKeyDown={(e) => { if (e.key === 'Enter') handleCreateLink(); }}
+                />
+                <Button size="sm" onClick={handleCreateLink}>Apply</Button>
+              </div>
+            )}
+          </div>
+        </div>
+
+        {/* Custom contenteditable editor */}
+        <div
+          ref={editorRef}
+          contentEditable
+          suppressContentEditableWarning
+          onInput={handleInput}
+          onKeyUp={updateActiveFormats}
+          onMouseUp={updateActiveFormats}
+          className="min-h-[200px] p-4 border border-border rounded-lg bg-background focus:outline-none focus:ring-2 focus:ring-ring text-sm"
+          style={{ lineHeight: 1.6 }}
+          dangerouslySetInnerHTML={{ __html: value }}
+        />
+
+        {/* Custom footer with counts */}
+        <div className="flex items-center justify-between text-xs text-muted-foreground px-1">
+          <span>Words: <strong>{wordCount}</strong></span>
+          <span>Characters: <strong>{characterCount}</strong></span>
+        </div>
+      </div>
+    );
+  },
+};
+