@usefragments/ui 1.0.0

package/src/components/Pagination/index.tsx

@@ -0,0 +1,387 @@
+'use client';
+
+import * as React from 'react';
+import styles from './Pagination.module.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export interface PaginationProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children'> {
+  children: React.ReactNode;
+  /** Total number of pages. Clamped to Math.max(0, totalPages). Renders nothing when 0. */
+  totalPages: number;
+  /** Controlled current page (1-indexed). Clamped to [1, totalPages]. */
+  page?: number;
+  /** Default page (uncontrolled). Clamped to [1, totalPages]. Default: 1 */
+  defaultPage?: number;
+  /** Called when page changes */
+  onPageChange?: (page: number) => void;
+  /** Number of pages shown at edges: default 1 */
+  edgeCount?: number;
+  /** Number of pages shown around current: default 1 */
+  siblingCount?: number;
+}
+
+export interface PaginationItemProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  children?: React.ReactNode;
+  /** Override page number (auto-assigned by context if omitted) */
+  page?: number;
+  className?: string;
+}
+
+// ============================================
+// Context
+// ============================================
+
+interface PaginationContextValue {
+  currentPage: number;
+  totalPages: number;
+  edgeCount: number;
+  siblingCount: number;
+  setPage: (page: number) => void;
+}
+
+const PaginationContext = React.createContext<PaginationContextValue | null>(null);
+
+function usePaginationContext() {
+  const ctx = React.useContext(PaginationContext);
+  if (!ctx) throw new Error('Pagination sub-components must be used within <Pagination>');
+  return ctx;
+}
+
+// ============================================
+// Page range algorithm
+// ============================================
+
+type RangeItem = number | 'ellipsis';
+
+function usePaginationRange(
+  totalPages: number,
+  currentPage: number,
+  siblingCount: number,
+  edgeCount: number,
+): RangeItem[] {
+  return React.useMemo(() => {
+    if (totalPages <= 0) return [];
+
+    // If total pages is small enough, show all pages
+    const totalSlots = edgeCount * 2 + siblingCount * 2 + 1 + 2; // edges + siblings + current + 2 ellipses
+    if (totalPages <= totalSlots) {
+      return Array.from({ length: totalPages }, (_, i) => i + 1);
+    }
+
+    const leftEdge = Array.from({ length: edgeCount }, (_, i) => i + 1);
+    const rightEdge = Array.from({ length: edgeCount }, (_, i) => totalPages - edgeCount + 1 + i);
+
+    const siblingStart = Math.max(edgeCount + 1, currentPage - siblingCount);
+    const siblingEnd = Math.min(totalPages - edgeCount, currentPage + siblingCount);
+
+    const result: RangeItem[] = [];
+
+    // Add left edge
+    for (const p of leftEdge) {
+      result.push(p);
+    }
+
+    // Left ellipsis
+    if (siblingStart > edgeCount + 1) {
+      // If there's only one gap, show the number instead of ellipsis
+      if (siblingStart === edgeCount + 2) {
+        result.push(edgeCount + 1);
+      } else {
+        result.push('ellipsis');
+      }
+    }
+
+    // Siblings + current
+    for (let i = siblingStart; i <= siblingEnd; i++) {
+      if (!result.includes(i)) {
+        result.push(i);
+      }
+    }
+
+    // Right ellipsis
+    if (siblingEnd < totalPages - edgeCount) {
+      if (siblingEnd === totalPages - edgeCount - 1) {
+        result.push(totalPages - edgeCount);
+      } else {
+        result.push('ellipsis');
+      }
+    }
+
+    // Add right edge
+    for (const p of rightEdge) {
+      if (!result.includes(p)) {
+        result.push(p);
+      }
+    }
+
+    return result;
+  }, [totalPages, currentPage, siblingCount, edgeCount]);
+}
+
+// ============================================
+// Chevron Icons
+// ============================================
+
+function ChevronLeftIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <polyline points="15 18 9 12 15 6" />
+    </svg>
+  );
+}
+
+function ChevronRightIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <polyline points="9 18 15 12 9 6" />
+    </svg>
+  );
+}
+
+// ============================================
+// Components
+// ============================================
+
+function clamp(value: number, min: number, max: number) {
+  return Math.max(min, Math.min(max, value));
+}
+
+function composeButtonClickHandlers(
+  internal: (event: React.MouseEvent<HTMLButtonElement>) => void,
+  external?: React.MouseEventHandler<HTMLButtonElement>,
+) {
+  return (event: React.MouseEvent<HTMLButtonElement>) => {
+    external?.(event);
+    if (!event.defaultPrevented) {
+      internal(event);
+    }
+  };
+}
+
+function PaginationRoot({
+  children,
+  totalPages: rawTotalPages,
+  page: controlledPage,
+  defaultPage = 1,
+  onPageChange,
+  edgeCount = 1,
+  siblingCount = 1,
+  className,
+  'aria-label': ariaLabel,
+  ...htmlProps
+}: PaginationProps) {
+  const totalPages = Math.max(0, Math.floor(rawTotalPages));
+  const [uncontrolledPage, setUncontrolledPage] = React.useState(() =>
+    totalPages > 0 ? clamp(defaultPage, 1, totalPages) : 1
+  );
+
+  const isControlled = controlledPage !== undefined;
+  const currentPage = isControlled
+    ? (totalPages > 0 ? clamp(controlledPage, 1, totalPages) : 1)
+    : (totalPages > 0 ? clamp(uncontrolledPage, 1, totalPages) : 1);
+
+  const setPage = React.useCallback(
+    (newPage: number) => {
+      if (totalPages <= 0) return;
+      const clamped = clamp(newPage, 1, totalPages);
+      if (clamped === currentPage) return;
+      if (!isControlled) {
+        setUncontrolledPage(clamped);
+      }
+      onPageChange?.(clamped);
+    },
+    [totalPages, currentPage, isControlled, onPageChange]
+  );
+
+  const contextValue = React.useMemo<PaginationContextValue>(
+    () => ({ currentPage, totalPages, edgeCount, siblingCount, setPage }),
+    [currentPage, totalPages, edgeCount, siblingCount, setPage]
+  );
+
+  if (totalPages <= 0) {
+    return (
+      <nav
+        {...htmlProps}
+        aria-label={ariaLabel ?? 'Pagination'}
+        className={[styles.pagination, className].filter(Boolean).join(' ')}
+      />
+    );
+  }
+
+  return (
+    <PaginationContext.Provider value={contextValue}>
+      <nav
+        {...htmlProps}
+        aria-label={ariaLabel ?? 'Pagination'}
+        className={[styles.pagination, className].filter(Boolean).join(' ')}
+      >
+        <ul className={styles.list}>
+          {children}
+        </ul>
+      </nav>
+    </PaginationContext.Provider>
+  );
+}
+
+function PaginationPrevious({ className, ...htmlProps }: React.ButtonHTMLAttributes<HTMLButtonElement>) {
+  const { currentPage, setPage } = usePaginationContext();
+  const disabled = currentPage <= 1;
+  const { onClick, ...buttonProps } = htmlProps;
+
+  return (
+    <li>
+      <button
+        type="button"
+        aria-label="Go to previous page"
+        disabled={disabled}
+        {...buttonProps}
+        onClick={composeButtonClickHandlers(() => setPage(currentPage - 1), onClick)}
+        className={[styles.item, styles.navButton, disabled && styles.itemDisabled, className].filter(Boolean).join(' ')}
+      >
+        <ChevronLeftIcon />
+      </button>
+    </li>
+  );
+}
+
+function PaginationNext({ className, ...htmlProps }: React.ButtonHTMLAttributes<HTMLButtonElement>) {
+  const { currentPage, totalPages, setPage } = usePaginationContext();
+  const disabled = currentPage >= totalPages;
+  const { onClick, ...buttonProps } = htmlProps;
+
+  return (
+    <li>
+      <button
+        type="button"
+        aria-label="Go to next page"
+        disabled={disabled}
+        {...buttonProps}
+        onClick={composeButtonClickHandlers(() => setPage(currentPage + 1), onClick)}
+        className={[styles.item, styles.navButton, disabled && styles.itemDisabled, className].filter(Boolean).join(' ')}
+      >
+        <ChevronRightIcon />
+      </button>
+    </li>
+  );
+}
+
+function PaginationItems() {
+  const { currentPage, totalPages, siblingCount, edgeCount, setPage } = usePaginationContext();
+  const range = usePaginationRange(totalPages, currentPage, siblingCount, edgeCount);
+  let ellipsisCount = 0;
+
+  return (
+    <>
+      {range.map((item) => {
+        if (item === 'ellipsis') {
+          ellipsisCount++;
+          return (
+            <li key={`ellipsis-${ellipsisCount}`}>
+              <span className={styles.ellipsis} aria-hidden="true">
+                &hellip;
+              </span>
+            </li>
+          );
+        }
+
+        const isActive = item === currentPage;
+        return (
+          <li key={item}>
+            <button
+              type="button"
+              aria-label={`Go to page ${item}`}
+              aria-current={isActive ? 'page' : undefined}
+              onClick={() => setPage(item)}
+              className={[styles.item, isActive && styles.itemActive].filter(Boolean).join(' ')}
+            >
+              {item}
+            </button>
+          </li>
+        );
+      })}
+    </>
+  );
+}
+
+function PaginationItem({
+  children,
+  page: pageProp,
+  className,
+  ...htmlProps
+}: PaginationItemProps) {
+  const { currentPage, setPage } = usePaginationContext();
+  const page = pageProp ?? 1;
+  const isActive = page === currentPage;
+  const { onClick, ...buttonProps } = htmlProps;
+
+  return (
+    <li>
+      <button
+        type="button"
+        aria-label={`Go to page ${page}`}
+        aria-current={isActive ? 'page' : undefined}
+        {...buttonProps}
+        onClick={composeButtonClickHandlers(() => setPage(page), onClick)}
+        className={[styles.item, isActive && styles.itemActive, className].filter(Boolean).join(' ')}
+      >
+        {children ?? page}
+      </button>
+    </li>
+  );
+}
+
+function PaginationEllipsis({ className, ...htmlProps }: React.HTMLAttributes<HTMLSpanElement>) {
+  return (
+    <li>
+      <span className={[styles.ellipsis, className].filter(Boolean).join(' ')} aria-hidden="true" {...htmlProps}>
+        &hellip;
+      </span>
+    </li>
+  );
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const Pagination = Object.assign(PaginationRoot, {
+  Previous: PaginationPrevious,
+  Next: PaginationNext,
+  Items: PaginationItems,
+  Item: PaginationItem,
+  Ellipsis: PaginationEllipsis,
+});
+
+export {
+  PaginationRoot,
+  PaginationPrevious,
+  PaginationNext,
+  PaginationItems,
+  PaginationItem,
+  PaginationEllipsis,
+};

package/src/components/Popover/Popover.contract.json

@@ -0,0 +1,163 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Popover",
+  "description": "Rich content overlay anchored to a trigger element. Use for forms, detailed information, or interactive content that should stay in context.",
+  "category": "feedback",
+  "tags": [
+    "popover",
+    "overlay",
+    "dropdown",
+    "floating",
+    "contextual"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Popover/index.tsx",
+  "exportName": "Popover",
+  "propsSummary": [
+    "children: node (required)",
+    "open: boolean",
+    "defaultOpen: boolean",
+    "onOpenChange: function",
+    "modal: boolean (default: false)"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Popover trigger and content",
+      "required": true
+    },
+    "open": {
+      "type": "boolean",
+      "description": "Controlled open state",
+      "required": false
+    },
+    "defaultOpen": {
+      "type": "boolean",
+      "description": "Default open state (uncontrolled)",
+      "default": "false",
+      "required": false
+    },
+    "onOpenChange": {
+      "type": "function",
+      "description": "Called when open state changes",
+      "required": false
+    },
+    "modal": {
+      "type": "boolean",
+      "description": "Whether to block page interaction",
+      "default": "false",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Inline editing forms",
+      "Rich preview content",
+      "Filter panels",
+      "Date/color pickers",
+      "Content that needs more space than a tooltip"
+    ],
+    "whenNot": [
+      "Simple hints (use Tooltip)",
+      "Action lists (use Menu)",
+      "Blocking user interaction (use Dialog)",
+      "System notifications (use Toast or Alert)"
+    ],
+    "guidelines": [
+      "Keep popover content focused and minimal",
+      "Include a clear way to close (X button or action buttons)",
+      "Position to avoid covering important content",
+      "Use arrow to visually connect popover to trigger",
+      "Popover.Trigger and Popover.Close support asChild for links/router-link components (single valid element child required)"
+    ],
+    "accessibility": [
+      "Focus is moved to popover content on open",
+      "Closes on Escape key",
+      "Focus returns to trigger on close"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic popover with content",
+      "code": "<Popover>\n  <Popover.Trigger asChild>\n    <Button variant=\"secondary\">Open Popover</Button>\n  </Popover.Trigger>\n  <Popover.Content>\n    <Popover.Close />\n    <Popover.Title>Popover Title</Popover.Title>\n    <Popover.Description>\n      This is a popover with some content. It can contain text, forms, or other elements.\n    </Popover.Description>\n  </Popover.Content>\n</Popover>"
+    },
+    {
+      "name": "With Form",
+      "description": "Popover containing a form",
+      "code": "<Popover>\n  <Popover.Trigger asChild>\n    <Button variant=\"secondary\">Edit Name</Button>\n  </Popover.Trigger>\n  <Popover.Content size=\"sm\">\n    <Popover.Close />\n    <Popover.Title>Edit Name</Popover.Title>\n    <Popover.Body>\n      <Input label=\"Display Name\" placeholder=\"Enter name\" />\n    </Popover.Body>\n    <Popover.Footer>\n      <Popover.Close asChild>\n        <Button variant=\"secondary\" size=\"sm\">Cancel</Button>\n      </Popover.Close>\n      <Button variant=\"primary\" size=\"sm\">Save</Button>\n    </Popover.Footer>\n  </Popover.Content>\n</Popover>"
+    },
+    {
+      "name": "With Arrow",
+      "description": "Popover with pointing arrow",
+      "code": "<Popover>\n  <Popover.Trigger asChild>\n    <Button variant=\"secondary\">Info</Button>\n  </Popover.Trigger>\n  <Popover.Content arrow>\n    <Popover.Title>Quick Tip</Popover.Title>\n    <Popover.Description>\n      This popover has an arrow pointing to its trigger element.\n    </Popover.Description>\n  </Popover.Content>\n</Popover>"
+    },
+    {
+      "name": "Positions",
+      "description": "Popover on different sides",
+      "code": "<div style={{ display: 'flex', gap: '16px', padding: '60px' }}>\n  <Popover>\n    <Popover.Trigger asChild>\n      <Button variant=\"secondary\">Top</Button>\n    </Popover.Trigger>\n    <Popover.Content side=\"top\" size=\"sm\">\n      <Popover.Description>Popover on top</Popover.Description>\n    </Popover.Content>\n  </Popover>\n  <Popover>\n    <Popover.Trigger asChild>\n      <Button variant=\"secondary\">Bottom</Button>\n    </Popover.Trigger>\n    <Popover.Content side=\"bottom\" size=\"sm\">\n      <Popover.Description>Popover on bottom</Popover.Description>\n    </Popover.Content>\n  </Popover>\n</div>"
+    },
+    {
+      "name": "Link Trigger",
+      "description": "Use asChild with a non-button trigger element",
+      "code": "<Popover>\n  <Popover.Trigger asChild>\n    <a href=\"#popover-help\">Open help</a>\n  </Popover.Trigger>\n  <Popover.Content size=\"sm\">\n    <Popover.Description>Popover trigger can be an anchor when using asChild.</Popover.Description>\n  </Popover.Content>\n</Popover>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Tooltip",
+      "relationship": "alternative",
+      "note": "Use Tooltip for brief, non-interactive hints"
+    },
+    {
+      "component": "Menu",
+      "relationship": "alternative",
+      "note": "Use Menu for action lists"
+    },
+    {
+      "component": "Dialog",
+      "relationship": "alternative",
+      "note": "Use Dialog for blocking interactions"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "open: boolean - controlled open state",
+      "onOpenChange: (open) => void - state handler",
+      "modal: boolean - blocks page interaction (default: false)",
+      "Popover.Trigger / Popover.Close asChild support non-button children",
+      "Popover.Content side: top|bottom|left|right - position"
+    ],
+    "a11yRules": [
+      "A11Y_POPOVER_FOCUS",
+      "A11Y_POPOVER_ESCAPE",
+      "A11Y_TARGET_SIZE_MIN"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Trigger",
+      "Content",
+      "Close",
+      "Title",
+      "Description",
+      "Body",
+      "Footer"
+    ],
+    "requiredChildren": [
+      "Trigger",
+      "Content"
+    ],
+    "commonPatterns": [
+      "<Popover><Popover.Trigger asChild><Button>Open</Button></Popover.Trigger><Popover.Content><Popover.Close /><Popover.Title>{title}</Popover.Title><Popover.Description>{description}</Popover.Description></Popover.Content></Popover>",
+      "<Popover><Popover.Trigger asChild><a href=\"#help\">Open help</a></Popover.Trigger><Popover.Content>...</Popover.Content></Popover>"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:02.154Z"
+  }
+}