@usefragments/ui 1.0.0

package/src/components/TableOfContents/TableOfContents.stories.tsx

@@ -0,0 +1,120 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { TableOfContents } from '.';
+
+/**
+ * TableOfContents is the canonical in-page navigation primitive — a sticky
+ * sidebar of heading links with a continuous hierarchy rail and active-segment
+ * highlighting. Use it for docs, long-form content, or filterable grouped
+ * lists; agents should compose `TableOfContents.Item`/`TableOfContents.Group`
+ * rather than hand-rolling a nav landmark.
+ */
+const meta = {
+  title: 'Navigation/TableOfContents',
+  component: TableOfContents,
+  tags: ['autodocs', 'canonical'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Sticky sidebar navigation for long-form content or filterable lists. Prefer this over a hand-rolled in-page nav.',
+      },
+    },
+  },
+  argTypes: {
+    title: { control: 'text', description: 'Visible title above the list' },
+    label: { control: 'text', description: 'Accessible label for the nav landmark' },
+    hideTitle: { control: 'boolean', description: 'Hide the visible title' },
+  },
+  args: {
+    title: 'On This Page',
+    children: (
+      <>
+        <TableOfContents.Item id="introduction">Introduction</TableOfContents.Item>
+        <TableOfContents.Item id="getting-started">Getting Started</TableOfContents.Item>
+        <TableOfContents.Item id="api-reference">API Reference</TableOfContents.Item>
+      </>
+    ),
+  },
+} satisfies Meta<typeof TableOfContents>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: (args) => (
+    <TableOfContents {...args}>
+      <TableOfContents.Item id="introduction">Introduction</TableOfContents.Item>
+      <TableOfContents.Item id="getting-started">Getting Started</TableOfContents.Item>
+      <TableOfContents.Item id="installation" indent>
+        Installation
+      </TableOfContents.Item>
+      <TableOfContents.Item id="configuration" indent>
+        Configuration
+      </TableOfContents.Item>
+      <TableOfContents.Item id="api-reference">API Reference</TableOfContents.Item>
+      <TableOfContents.Item id="examples">Examples</TableOfContents.Item>
+    </TableOfContents>
+  ),
+};
+
+export const NestedGroups: Story = {
+  render: () => (
+    <TableOfContents title="Components">
+      <TableOfContents.Item id="all" active>
+        All
+      </TableOfContents.Item>
+      <TableOfContents.Group label="Primitives" trailing={<span>3</span>}>
+        <TableOfContents.Item id="button">Button</TableOfContents.Item>
+        <TableOfContents.Item id="card">Card</TableOfContents.Item>
+        <TableOfContents.Item id="input">Input</TableOfContents.Item>
+      </TableOfContents.Group>
+      <TableOfContents.Group label="Custom" defaultOpen={false}>
+        <TableOfContents.Item id="features">Features</TableOfContents.Item>
+        <TableOfContents.Item id="plans">Plans</TableOfContents.Item>
+      </TableOfContents.Group>
+    </TableOfContents>
+  ),
+};
+
+export const WithActiveItem: Story = {
+  render: () => (
+    <TableOfContents>
+      <TableOfContents.Item id="overview">Overview</TableOfContents.Item>
+      <TableOfContents.Item id="setup" active>
+        Setup
+      </TableOfContents.Item>
+      <TableOfContents.Item id="usage" indent>
+        Basic Usage
+      </TableOfContents.Item>
+      <TableOfContents.Item id="advanced" indent>
+        Advanced
+      </TableOfContents.Item>
+      <TableOfContents.Item id="props">Props</TableOfContents.Item>
+      <TableOfContents.Item id="accessibility">Accessibility</TableOfContents.Item>
+    </TableOfContents>
+  ),
+};
+
+export const CustomTitle: Story = {
+  render: () => (
+    <TableOfContents title="Contents">
+      <TableOfContents.Item id="chapter-1">Chapter 1: The Beginning</TableOfContents.Item>
+      <TableOfContents.Item id="chapter-2">Chapter 2: The Middle</TableOfContents.Item>
+      <TableOfContents.Item id="chapter-3">Chapter 3: The End</TableOfContents.Item>
+    </TableOfContents>
+  ),
+};
+
+export const NoTitle: Story = {
+  args: { hideTitle: true },
+  render: (args) => (
+    <TableOfContents {...args}>
+      <TableOfContents.Item id="section-a">Section A</TableOfContents.Item>
+      <TableOfContents.Item id="section-b" active>
+        Section B
+      </TableOfContents.Item>
+      <TableOfContents.Item id="section-c">Section C</TableOfContents.Item>
+    </TableOfContents>
+  ),
+};

package/src/components/TableOfContents/index.tsx

@@ -0,0 +1,266 @@
+'use client';
+
+import * as React from 'react';
+import styles from './TableOfContents.module.scss';
+import { Text } from '../Text';
+
+// ============================================
+// Types
+// ============================================
+
+export interface TableOfContentsProps extends React.HTMLAttributes<HTMLElement> {
+  children: React.ReactNode;
+  /** Label for the nav landmark (default: "Table of contents") */
+  label?: string;
+  /** Title displayed above the list (default: "On This Page") */
+  title?: string;
+  /** Hide the title */
+  hideTitle?: boolean;
+}
+
+export interface TableOfContentsItemProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'children'> {
+  children: React.ReactNode;
+  /** The heading ID to link to */
+  id: string;
+  /** Whether this item is currently active/visible */
+  active?: boolean;
+  /** Force depth=1 indent for items not nested in a Group. */
+  indent?: boolean;
+  /** Optional leading element (icon, dot, etc.) — rendered before the label */
+  leading?: React.ReactNode;
+  /** Optional trailing element (count, badge, etc.) — rendered after the label */
+  trailing?: React.ReactNode;
+}
+
+export interface TableOfContentsGroupProps {
+  children: React.ReactNode;
+  /** Label rendered in the group header row */
+  label: React.ReactNode;
+  /** Optional trailing element on the header row (e.g., count badge) */
+  trailing?: React.ReactNode;
+  /** Optional leading element on the header row (e.g., icon) */
+  leading?: React.ReactNode;
+  /** Whether the group is initially open (uncontrolled). Defaults to true. */
+  defaultOpen?: boolean;
+  /** Controlled open state */
+  open?: boolean;
+  /** Callback fired when open state changes */
+  onOpenChange?: (open: boolean) => void;
+  /** Allow toggling open/closed via the header button. Defaults to true. */
+  collapsible?: boolean;
+  /** Disable expand/collapse — header renders as a non-interactive label */
+  disabled?: boolean;
+  /** Highlight the group label in accent — typically when a child is active. */
+  active?: boolean;
+}
+
+// ============================================
+// Context — tracks nesting depth for the rail
+// ============================================
+
+interface TocContextValue {
+  depth: number;
+}
+
+const TocContext = React.createContext<TocContextValue>({ depth: 0 });
+
+// ============================================
+// Icons
+// ============================================
+
+function ChevronIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="10"
+      height="10"
+      viewBox="0 0 256 256"
+      fill="currentColor"
+      aria-hidden="true"
+    >
+      <path d="M181.66,133.66l-80,80a8,8,0,0,1-11.32-11.32L164.69,128,90.34,53.66a8,8,0,0,1,11.32-11.32l80,80A8,8,0,0,1,181.66,133.66Z" />
+    </svg>
+  );
+}
+
+// ============================================
+// Components
+// ============================================
+
+function TableOfContentsRoot({
+  children,
+  label = 'Table of contents',
+  title = 'On This Page',
+  hideTitle = false,
+  className,
+  'aria-label': ariaLabel,
+  ...htmlProps
+}: TableOfContentsProps) {
+  const classes = [styles.root, className].filter(Boolean).join(' ');
+
+  return (
+    <nav {...htmlProps} aria-label={ariaLabel ?? label} className={classes}>
+      {!hideTitle && (
+        <Text as="p" variant="section-label" className={styles.title}>
+          {title}
+        </Text>
+      )}
+      <TocContext.Provider value={{ depth: 0 }}>
+        <ul className={styles.list}>{children}</ul>
+      </TocContext.Provider>
+    </nav>
+  );
+}
+
+function TableOfContentsItem({
+  children,
+  id,
+  active = false,
+  indent = false,
+  leading,
+  trailing,
+  className,
+  onClick,
+  href: _href,
+  ...htmlProps
+}: TableOfContentsItemProps) {
+  const { depth } = React.useContext(TocContext);
+  const effectiveDepth = depth > 0 ? depth : indent ? 1 : 0;
+
+  const linkClasses = [
+    styles.link,
+    active && styles.active,
+    className,
+  ].filter(Boolean).join(' ');
+
+  const handleClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
+    onClick?.(e);
+    if (e.defaultPrevented) return;
+
+    e.preventDefault();
+    const el = document.getElementById(id);
+    if (el) {
+      el.scrollIntoView({ behavior: 'smooth' });
+      window.history.replaceState(null, '', `#${id}`);
+    }
+  };
+
+  return (
+    <li
+      className={styles.item}
+      data-depth={effectiveDepth}
+      data-active={active || undefined}
+    >
+      <a
+        {...htmlProps}
+        href={`#${id}`}
+        className={linkClasses}
+        onClick={handleClick}
+        aria-current={active ? 'location' : undefined}
+      >
+        {leading != null && <span className={styles.leading}>{leading}</span>}
+        <span className={styles.linkLabel}>{children}</span>
+        {trailing != null && <span className={styles.trailing}>{trailing}</span>}
+      </a>
+    </li>
+  );
+}
+
+function useControlledOpen(
+  controlled: boolean | undefined,
+  defaultValue: boolean,
+  onChange: ((open: boolean) => void) | undefined,
+): [boolean, (next: boolean) => void] {
+  const [internal, setInternal] = React.useState(defaultValue);
+  const isControlled = controlled !== undefined;
+  const value = isControlled ? controlled : internal;
+  const setValue = React.useCallback(
+    (next: boolean) => {
+      if (!isControlled) setInternal(next);
+      onChange?.(next);
+    },
+    [isControlled, onChange],
+  );
+  return [value, setValue];
+}
+
+// Group renders a Fragment: its header <li> and its children become direct
+// siblings in the parent <ul>, which lets CSS adjacency selectors detect
+// depth transitions and draw the opening/closing elbows.
+function TableOfContentsGroup({
+  children,
+  label,
+  leading,
+  trailing,
+  defaultOpen = true,
+  open: controlledOpen,
+  onOpenChange,
+  collapsible = true,
+  disabled = false,
+  active = false,
+}: TableOfContentsGroupProps) {
+  const { depth } = React.useContext(TocContext);
+  const [open, setOpen] = useControlledOpen(controlledOpen, defaultOpen, onOpenChange);
+
+  const isToggleable = collapsible && !disabled;
+  const isOpen = isToggleable ? open : true;
+
+  const headerClasses = [
+    styles.groupHeader,
+    isToggleable && styles.groupHeaderInteractive,
+    active && styles.groupHeaderActive,
+  ].filter(Boolean).join(' ');
+
+  const headerContent = (
+    <>
+      {isToggleable && (
+        <span className={styles.groupChevron} data-open={isOpen || undefined} aria-hidden="true">
+          <ChevronIcon />
+        </span>
+      )}
+      {leading != null && <span className={styles.leading}>{leading}</span>}
+      <span className={styles.groupLabel}>{label}</span>
+      {trailing != null && <span className={styles.trailing}>{trailing}</span>}
+    </>
+  );
+
+  return (
+    <>
+      <li
+        className={styles.groupHeaderRow}
+        data-depth={depth}
+        data-active={active || undefined}
+      >
+        {isToggleable ? (
+          <button
+            type="button"
+            className={headerClasses}
+            onClick={() => setOpen(!open)}
+            aria-expanded={isOpen}
+          >
+            {headerContent}
+          </button>
+        ) : (
+          <div className={headerClasses}>{headerContent}</div>
+        )}
+      </li>
+      {isOpen && (
+        <TocContext.Provider value={{ depth: depth + 1 }}>
+          {children}
+        </TocContext.Provider>
+      )}
+    </>
+  );
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const TableOfContents = Object.assign(TableOfContentsRoot, {
+  Item: TableOfContentsItem,
+  Group: TableOfContentsGroup,
+});
+
+// Re-export individual components
+export { TableOfContentsRoot, TableOfContentsItem, TableOfContentsGroup };

package/src/components/Tabs/Tabs.contract.json

@@ -0,0 +1,159 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Tabs",
+  "description": "Organize content into switchable panels. Use for related content that benefits from a compact, navigable layout.",
+  "category": "navigation",
+  "tags": [
+    "tabs",
+    "navigation",
+    "panels",
+    "content-switcher"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Tabs/index.tsx",
+  "exportName": "Tabs",
+  "propsSummary": [
+    "children: node (required)",
+    "defaultValue: string",
+    "value: string",
+    "onValueChange: function",
+    "orientation: horizontal|vertical (default: horizontal)",
+    "variant: underline|pills (default: underline)"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Tab list and panels (use Tabs.List, Tabs.Tab, Tabs.Panel)",
+      "required": true
+    },
+    "defaultValue": {
+      "type": "string",
+      "description": "Initially active tab (uncontrolled)",
+      "required": false
+    },
+    "value": {
+      "type": "string",
+      "description": "Controlled active tab value",
+      "required": false
+    },
+    "onValueChange": {
+      "type": "function",
+      "description": "Called when active tab changes",
+      "required": false
+    },
+    "orientation": {
+      "type": "enum",
+      "description": "Tab list orientation",
+      "default": "horizontal",
+      "required": false,
+      "values": [
+        "horizontal",
+        "vertical"
+      ]
+    },
+    "variant": {
+      "type": "enum",
+      "description": "Default visual style for Tabs.List (can be overridden on Tabs.List)",
+      "default": "underline",
+      "required": false,
+      "values": [
+        "underline",
+        "pills"
+      ]
+    }
+  },
+  "usage": {
+    "when": [
+      "Organizing related content into sections",
+      "Reducing page scrolling by grouping content",
+      "Settings pages with multiple categories",
+      "Dashboard views with different data perspectives"
+    ],
+    "whenNot": [
+      "Primary navigation (use sidebar or header nav)",
+      "Sequential steps (use Stepper or wizard)",
+      "Comparing content side-by-side",
+      "Very long lists of options (use Select or Menu)"
+    ],
+    "guidelines": [
+      "Keep tab labels short (1-2 words)",
+      "Order tabs by usage frequency or logical sequence",
+      "Avoid more than 5-6 tabs; consider sub-navigation for more",
+      "Tab content should be roughly equivalent in scope",
+      "Use pills variant for contained sections, underline for page-level tabs"
+    ],
+    "accessibility": [
+      "Keyboard navigation with arrow keys",
+      "Tab panels are properly labeled",
+      "Focus management follows WAI-ARIA tabs pattern"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Underline",
+      "description": "Default underline style tabs",
+      "code": "<Tabs defaultValue=\"overview\" variant=\"underline\">\n  <Tabs.List>\n    <Tabs.Tab value=\"overview\">Overview</Tabs.Tab>\n    <Tabs.Tab value=\"analytics\">Analytics</Tabs.Tab>\n    <Tabs.Tab value=\"settings\">Settings</Tabs.Tab>\n  </Tabs.List>\n  <Tabs.Panel value=\"overview\">\n    <p>Overview content goes here.</p>\n  </Tabs.Panel>\n  <Tabs.Panel value=\"analytics\">\n    <p>Analytics content goes here.</p>\n  </Tabs.Panel>\n  <Tabs.Panel value=\"settings\">\n    <p>Settings content goes here.</p>\n  </Tabs.Panel>\n</Tabs>"
+    },
+    {
+      "name": "Pills",
+      "description": "Pill-style tabs for contained sections",
+      "code": "<Tabs defaultValue=\"all\" variant=\"pills\">\n  <Tabs.List>\n    <Tabs.Tab value=\"all\">All</Tabs.Tab>\n    <Tabs.Tab value=\"active\">Active</Tabs.Tab>\n    <Tabs.Tab value=\"archived\">Archived</Tabs.Tab>\n  </Tabs.List>\n  <Tabs.Panel value=\"all\">\n    <p>Showing all items.</p>\n  </Tabs.Panel>\n  <Tabs.Panel value=\"active\">\n    <p>Showing active items only.</p>\n  </Tabs.Panel>\n  <Tabs.Panel value=\"archived\">\n    <p>Showing archived items.</p>\n  </Tabs.Panel>\n</Tabs>"
+    },
+    {
+      "name": "With Disabled",
+      "description": "Tabs with a disabled option",
+      "code": "<Tabs defaultValue=\"general\" variant=\"underline\">\n  <Tabs.List>\n    <Tabs.Tab value=\"general\">General</Tabs.Tab>\n    <Tabs.Tab value=\"security\">Security</Tabs.Tab>\n    <Tabs.Tab value=\"billing\" disabled>Billing</Tabs.Tab>\n  </Tabs.List>\n  <Tabs.Panel value=\"general\">\n    <p>General settings panel.</p>\n  </Tabs.Panel>\n  <Tabs.Panel value=\"security\">\n    <p>Security settings panel.</p>\n  </Tabs.Panel>\n</Tabs>"
+    },
+    {
+      "name": "List Variant Override",
+      "description": "Tabs sets a default variant, and Tabs.List can override it per list",
+      "code": "<Tabs defaultValue=\"overview\" variant=\"pills\">\n  <Tabs.List variant=\"underline\">\n    <Tabs.Tab value=\"overview\">Overview</Tabs.Tab>\n    <Tabs.Tab value=\"activity\">Activity</Tabs.Tab>\n  </Tabs.List>\n  <Tabs.Panel value=\"overview\">\n    <p>Root sets pills, but this list overrides to underline.</p>\n  </Tabs.Panel>\n  <Tabs.Panel value=\"activity\">\n    <p>Per-list variant override example.</p>\n  </Tabs.Panel>\n</Tabs>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Select",
+      "relationship": "alternative",
+      "note": "Use Select for many options in compact space"
+    },
+    {
+      "component": "Menu",
+      "relationship": "alternative",
+      "note": "Use Menu for action-based navigation"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "value: string - controlled active tab",
+      "defaultValue: string - initial active tab",
+      "onValueChange: (value) => void - tab change handler",
+      "variant: underline|pills - default style for Tabs.List",
+      "Tabs.List variant?: underline|pills - optional per-list override"
+    ],
+    "a11yRules": [
+      "A11Y_TABS_KEYBOARD",
+      "A11Y_TABS_LABELS"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "List",
+      "Tab",
+      "Panel"
+    ],
+    "requiredChildren": [
+      "List",
+      "Panel"
+    ],
+    "commonPatterns": [
+      "<Tabs defaultValue=\"tab1\"><Tabs.List><Tabs.Tab value=\"tab1\">{label1}</Tabs.Tab><Tabs.Tab value=\"tab2\">{label2}</Tabs.Tab></Tabs.List><Tabs.Panel value=\"tab1\">{content1}</Tabs.Panel><Tabs.Panel value=\"tab2\">{content2}</Tabs.Panel></Tabs>"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:04.871Z"
+  }
+}