@usefragments/ui 1.0.0

package/src/components/NavigationMenu/useNavigationMenu.ts

@@ -0,0 +1,101 @@
+'use client';
+
+import * as React from 'react';
+import type { NavigationMenuItemInfo } from './NavigationMenuContext';
+
+export interface UseNavigationMenuOptions {
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+  delayDuration?: number;
+  skipDelayDuration?: number;
+}
+
+export function useNavigationMenu({
+  value: controlledValue,
+  defaultValue = '',
+  onValueChange,
+  delayDuration = 200,
+  skipDelayDuration = 300,
+}: UseNavigationMenuOptions) {
+  const [uncontrolledValue, setUncontrolledValue] = React.useState(defaultValue);
+  const isControlled = controlledValue !== undefined;
+  const value = isControlled ? controlledValue : uncontrolledValue;
+
+  const setValue = React.useCallback(
+    (newValue: string) => {
+      if (!isControlled) {
+        setUncontrolledValue(newValue);
+      }
+      onValueChange?.(newValue);
+    },
+    [isControlled, onValueChange]
+  );
+
+  // Hover delay timers
+  const openTimerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+  const closeTimerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Skip-delay: when moving between triggers, open instantly
+  const isRecentlyOpenRef = React.useRef(false);
+  const skipDelayTimerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Trigger registry for keyboard nav
+  const triggerRefs = React.useRef<Map<string, HTMLButtonElement>>(new Map());
+  const triggerOrder = React.useRef<string[]>([]);
+
+  // Full item order registry (includes link-only items)
+  const itemOrder = React.useRef<string[]>([]);
+
+  // Item info registry for mobile drawer
+  const itemInfoMap = React.useRef<Map<string, NavigationMenuItemInfo>>(new Map());
+
+  // Viewport sizing
+  const [viewportSize, setViewportSize] = React.useState({ width: 0, height: 0 });
+  const viewportRef = React.useRef<HTMLDivElement>(null);
+
+  // Track previous value for animation direction
+  const previousValue = React.useRef(value);
+
+  // Mobile state
+  const [mobileOpen, setMobileOpen] = React.useState(false);
+  const [mobileContentChildren, setMobileContentChildren] = React.useState<React.ReactNode>(null);
+  const [mobileBrandChildren, setMobileBrandChildren] = React.useState<React.ReactNode>(null);
+
+  // Clean up timers on unmount
+  React.useEffect(() => {
+    const openTimer = openTimerRef.current;
+    const closeTimer = closeTimerRef.current;
+    const skipDelayTimer = skipDelayTimerRef.current;
+    return () => {
+      if (openTimer) clearTimeout(openTimer);
+      if (closeTimer) clearTimeout(closeTimer);
+      if (skipDelayTimer) clearTimeout(skipDelayTimer);
+    };
+  }, []);
+
+  return {
+    value,
+    setValue,
+    delayDuration,
+    skipDelayDuration,
+    openTimerRef,
+    closeTimerRef,
+    isRecentlyOpenRef,
+    skipDelayTimerRef,
+    triggerRefs,
+    triggerOrder,
+    itemOrder,
+    itemInfoMap,
+    viewportSize,
+    setViewportSize,
+    viewportRef,
+    previousValue,
+    mobileOpen,
+    setMobileOpen,
+    mobileContentChildren,
+    setMobileContentChildren,
+    mobileBrandChildren,
+    setMobileBrandChildren,
+  };
+}

package/src/components/Pagination/Pagination.contract.json

@@ -0,0 +1,163 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Pagination",
+  "description": "Page navigation for paginated data. Supports controlled/uncontrolled, page counts, and edge/sibling customization.",
+  "category": "navigation",
+  "tags": [
+    "pagination",
+    "paging",
+    "pages",
+    "navigation"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Pagination/index.tsx",
+  "exportName": "Pagination",
+  "propsSummary": [
+    "children: node (required)",
+    "totalPages: number (required)",
+    "page: number",
+    "defaultPage: number (default: 1)",
+    "onPageChange: function",
+    "edgeCount: number (default: 1)",
+    "siblingCount: number (default: 1)"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "",
+      "required": true
+    },
+    "totalPages": {
+      "type": "number",
+      "description": "Total number of pages",
+      "required": true
+    },
+    "page": {
+      "type": "number",
+      "description": "Controlled current page (1-indexed)",
+      "required": false
+    },
+    "defaultPage": {
+      "type": "number",
+      "description": "Default page (uncontrolled)",
+      "default": "1",
+      "required": false
+    },
+    "onPageChange": {
+      "type": "function",
+      "description": "Called when page changes",
+      "required": false
+    },
+    "edgeCount": {
+      "type": "number",
+      "description": "Number of pages shown at edges",
+      "default": "1",
+      "required": false
+    },
+    "siblingCount": {
+      "type": "number",
+      "description": "Number of pages shown around current",
+      "default": "1",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Navigating through paginated data sets",
+      "Table or list pagination controls",
+      "Search results with multiple pages",
+      "Any content split across multiple pages"
+    ],
+    "whenNot": [
+      "Small lists that fit on one page",
+      "Infinite scroll patterns (use IntersectionObserver)",
+      "Tab-based navigation (use Tabs)",
+      "Step-by-step wizards (use Stepper)"
+    ],
+    "guidelines": [
+      "Place below the content being paginated",
+      "Use edgeCount to always show first/last pages",
+      "Use siblingCount to control how many pages surround the current page",
+      "Pair with Table component for data table pagination",
+      "Pagination forwards standard nav props (id, aria-*, data-*, event handlers) to the root <nav>",
+      "Previous/Next/Item buttons compose your onClick handlers; call event.preventDefault() to stop the page change"
+    ],
+    "accessibility": [
+      "Uses nav element with aria-label=\"Pagination\"",
+      "aria-current=\"page\" marks the active page",
+      "Previous/Next buttons have descriptive aria-labels",
+      "Disabled buttons at boundaries prevent invalid navigation"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic pagination with 10 pages",
+      "code": "<Pagination totalPages={10} defaultPage={1}>\n  <Pagination.Previous />\n  <Pagination.Items />\n  <Pagination.Next />\n</Pagination>"
+    },
+    {
+      "name": "With Edge Pages",
+      "description": "Shows 2 pages at each edge",
+      "code": "<Pagination totalPages={20} defaultPage={10} edgeCount={2} siblingCount={1}>\n  <Pagination.Previous />\n  <Pagination.Items />\n  <Pagination.Next />\n</Pagination>"
+    },
+    {
+      "name": "Compact",
+      "description": "No siblings, minimal display",
+      "code": "<Pagination totalPages={20} defaultPage={10} siblingCount={0}>\n  <Pagination.Previous />\n  <Pagination.Items />\n  <Pagination.Next />\n</Pagination>"
+    },
+    {
+      "name": "Controlled",
+      "description": "Controlled pagination at page 3",
+      "code": "<Pagination totalPages={5} page={3}>\n  <Pagination.Previous />\n  <Pagination.Items />\n  <Pagination.Next />\n</Pagination>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Table",
+      "relationship": "sibling",
+      "note": "Commonly paired for table pagination"
+    },
+    {
+      "component": "Listbox",
+      "relationship": "alternative",
+      "note": "Use Listbox for small sets of options"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "totalPages: number - total page count (required)",
+      "page: number - controlled current page (1-indexed)",
+      "defaultPage: number - initial page (default: 1)",
+      "onPageChange: (page) => void - page change handler",
+      "edgeCount: number - pages at edges (default: 1)",
+      "siblingCount: number - pages around current (default: 1)",
+      "Forwards standard HTML nav attributes to the root element"
+    ],
+    "a11yRules": [
+      "A11Y_NAV_LABEL",
+      "A11Y_CURRENT_PAGE"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Previous",
+      "Next",
+      "Items",
+      "Item",
+      "Ellipsis"
+    ],
+    "requiredChildren": [
+      "Items"
+    ],
+    "commonPatterns": [
+      "<Pagination totalPages={totalPages} page={currentPage} onPageChange={setPage}><Pagination.Previous /><Pagination.Items /><Pagination.Next /></Pagination>"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:01.648Z"
+  }
+}

package/src/components/Pagination/Pagination.module.scss

@@ -0,0 +1,111 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+// ============================================
+// Navigation wrapper
+// ============================================
+
+.pagination {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+// ============================================
+// List container
+// ============================================
+
+.list {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-1, $fui-space-1);
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+// ============================================
+// Page item button
+// ============================================
+
+.item {
+  @include button-reset;
+  @include text-base;
+
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: var(--fui-touch-md, $fui-touch-md);
+  height: var(--fui-touch-md, $fui-touch-md);
+  padding: 0 var(--fui-space-2, $fui-space-2);
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  color: var(--fui-text-primary, $fui-text-primary);
+  cursor: pointer;
+  transition:
+    background-color var(--fui-transition-fast, $fui-transition-fast),
+    color var(--fui-transition-fast, $fui-transition-fast);
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
+
+  &:focus-visible {
+    @include focus-ring;
+  }
+}
+
+// Active page
+.itemActive {
+  background-color: var(--fui-color-accent, $fui-color-accent);
+  color: var(--fui-color-on-accent, $fui-color-on-accent);
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-color-accent-hover, $fui-color-accent-hover);
+  }
+}
+
+// Disabled state (prev/next at boundaries)
+.itemDisabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+  pointer-events: none;
+}
+
+// ============================================
+// Nav buttons (Previous/Next)
+// ============================================
+
+.navButton {
+  svg {
+    width: var(--fui-icon-sm, $fui-icon-sm);
+    height: var(--fui-icon-sm, $fui-icon-sm);
+  }
+}
+
+// ============================================
+// Ellipsis
+// ============================================
+
+.ellipsis {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: var(--fui-touch-md, $fui-touch-md);
+  height: var(--fui-touch-md, $fui-touch-md);
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  user-select: none;
+}
+
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .itemActive {
+    outline: 2px solid var(--fui-color-accent, $fui-color-accent);
+    outline-offset: -2px;
+  }
+}

package/src/components/Pagination/Pagination.stories.tsx

@@ -0,0 +1,81 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Pagination } from '.';
+
+/**
+ * Page navigation for paginated data. Compose with `Pagination.Previous`,
+ * `Pagination.Items`, and `Pagination.Next`. Supports controlled/uncontrolled
+ * state plus edge and sibling count customization.
+ */
+const meta = {
+  title: 'Navigation/Pagination',
+  component: Pagination,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Page navigation controls for paginated data sets.',
+      },
+    },
+  },
+  args: {
+    totalPages: 10,
+    defaultPage: 1,
+    edgeCount: 1,
+    siblingCount: 1,
+    children: (
+      <>
+        <Pagination.Previous />
+        <Pagination.Items />
+        <Pagination.Next />
+      </>
+    ),
+  },
+} satisfies Meta<typeof Pagination>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { totalPages: 10, defaultPage: 1 },
+  render: (args) => (
+    <Pagination {...args}>
+      <Pagination.Previous />
+      <Pagination.Items />
+      <Pagination.Next />
+    </Pagination>
+  ),
+};
+
+export const WithEdgePages: Story = {
+  args: { totalPages: 20, defaultPage: 10, edgeCount: 2, siblingCount: 1 },
+  render: (args) => (
+    <Pagination {...args}>
+      <Pagination.Previous />
+      <Pagination.Items />
+      <Pagination.Next />
+    </Pagination>
+  ),
+};
+
+export const Compact: Story = {
+  args: { totalPages: 20, defaultPage: 10, siblingCount: 0 },
+  render: (args) => (
+    <Pagination {...args}>
+      <Pagination.Previous />
+      <Pagination.Items />
+      <Pagination.Next />
+    </Pagination>
+  ),
+};
+
+export const Controlled: Story = {
+  args: { totalPages: 5, page: 3 },
+  render: (args) => (
+    <Pagination {...args}>
+      <Pagination.Previous />
+      <Pagination.Items />
+      <Pagination.Next />
+    </Pagination>
+  ),
+};