@fragments-sdk/ui 0.7.5 → 0.8.1

package/src/components/TableOfContents/TableOfContents.module.scss

@@ -0,0 +1,66 @@
+@use '../../tokens/variables' as *;
+
+// Root nav wrapper
+.root {
+  font-family: var(--fui-font-sans, $fui-font-sans);
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+}
+
+// Title text ("On This Page")
+.title {
+  margin: 0;
+  padding: 0 0 var(--fui-space-2, $fui-space-2) 0;
+}
+
+// List container
+.list {
+  display: flex;
+  flex-direction: column;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+// Individual item
+.item {
+  display: block;
+}
+
+// Link styling shared by all items
+.link {
+  display: block;
+  padding: var(--fui-space-1, $fui-space-1) 0 var(--fui-space-1, $fui-space-1) var(--fui-space-3, $fui-space-3);
+  border-left: 2px solid transparent;
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+  text-decoration: none;
+  transition: color var(--fui-transition-fast, $fui-transition-fast),
+    border-color var(--fui-transition-fast, $fui-transition-fast);
+
+  &:hover {
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+
+  &:focus-visible {
+    outline: var(--fui-focus-ring-width, $fui-focus-ring-width) solid var(--fui-focus-ring-color, $fui-focus-ring-color);
+    outline-offset: var(--fui-focus-ring-offset, $fui-focus-ring-offset);
+    border-radius: var(--fui-radius-sm, $fui-radius-sm);
+  }
+}
+
+// Indent for depth > 2 (h3s)
+.indent {
+  padding-left: var(--fui-space-6, $fui-space-6);
+}
+
+// Active state
+.active {
+  border-left-color: var(--fui-color-accent, $fui-color-accent);
+  color: var(--fui-color-accent, $fui-color-accent);
+
+  &:hover {
+    color: var(--fui-color-accent, $fui-color-accent);
+  }
+}

package/src/components/TableOfContents/TableOfContents.test.tsx

@@ -0,0 +1,126 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, userEvent, expectNoA11yViolations } from '../../test/utils';
+import { TableOfContents } from './index';
+
+describe('TableOfContents', () => {
+  it('renders a nav landmark with default aria-label', () => {
+    render(
+      <TableOfContents>
+        <TableOfContents.Item id="intro">Intro</TableOfContents.Item>
+      </TableOfContents>
+    );
+    expect(screen.getByRole('navigation', { name: 'Table of contents' })).toBeInTheDocument();
+  });
+
+  it('renders the default "On This Page" title', () => {
+    render(
+      <TableOfContents>
+        <TableOfContents.Item id="intro">Intro</TableOfContents.Item>
+      </TableOfContents>
+    );
+    expect(screen.getByText('On This Page')).toBeInTheDocument();
+  });
+
+  it('renders a custom title', () => {
+    render(
+      <TableOfContents title="Contents">
+        <TableOfContents.Item id="intro">Intro</TableOfContents.Item>
+      </TableOfContents>
+    );
+    expect(screen.getByText('Contents')).toBeInTheDocument();
+    expect(screen.queryByText('On This Page')).not.toBeInTheDocument();
+  });
+
+  it('hides the title when hideTitle is true', () => {
+    render(
+      <TableOfContents hideTitle>
+        <TableOfContents.Item id="intro">Intro</TableOfContents.Item>
+      </TableOfContents>
+    );
+    expect(screen.queryByText('On This Page')).not.toBeInTheDocument();
+  });
+
+  it('renders a custom aria-label', () => {
+    render(
+      <TableOfContents label="Page sections">
+        <TableOfContents.Item id="intro">Intro</TableOfContents.Item>
+      </TableOfContents>
+    );
+    expect(screen.getByRole('navigation', { name: 'Page sections' })).toBeInTheDocument();
+  });
+
+  it('renders items as links with correct href', () => {
+    render(
+      <TableOfContents>
+        <TableOfContents.Item id="setup">Setup</TableOfContents.Item>
+        <TableOfContents.Item id="props">Props</TableOfContents.Item>
+      </TableOfContents>
+    );
+    expect(screen.getByRole('link', { name: 'Setup' })).toHaveAttribute('href', '#setup');
+    expect(screen.getByRole('link', { name: 'Props' })).toHaveAttribute('href', '#props');
+  });
+
+  it('marks active item with aria-current', () => {
+    render(
+      <TableOfContents>
+        <TableOfContents.Item id="setup" active>Setup</TableOfContents.Item>
+        <TableOfContents.Item id="props">Props</TableOfContents.Item>
+      </TableOfContents>
+    );
+    expect(screen.getByRole('link', { name: 'Setup' })).toHaveAttribute('aria-current', 'true');
+    expect(screen.getByRole('link', { name: 'Props' })).not.toHaveAttribute('aria-current');
+  });
+
+  it('scrolls to heading on click', async () => {
+    const scrollIntoViewMock = vi.fn();
+    const heading = document.createElement('h2');
+    heading.id = 'setup';
+    heading.scrollIntoView = scrollIntoViewMock;
+    document.body.appendChild(heading);
+
+    const user = userEvent.setup();
+    render(
+      <TableOfContents>
+        <TableOfContents.Item id="setup">Setup</TableOfContents.Item>
+      </TableOfContents>
+    );
+
+    await user.click(screen.getByRole('link', { name: 'Setup' }));
+    expect(scrollIntoViewMock).toHaveBeenCalledWith({ behavior: 'smooth' });
+
+    document.body.removeChild(heading);
+  });
+
+  it('renders items in a list', () => {
+    render(
+      <TableOfContents>
+        <TableOfContents.Item id="a">A</TableOfContents.Item>
+        <TableOfContents.Item id="b">B</TableOfContents.Item>
+        <TableOfContents.Item id="c">C</TableOfContents.Item>
+      </TableOfContents>
+    );
+    expect(screen.getByRole('list')).toBeInTheDocument();
+    expect(screen.getAllByRole('listitem')).toHaveLength(3);
+  });
+
+  it('passes additional className to root', () => {
+    const { container } = render(
+      <TableOfContents className="custom-class">
+        <TableOfContents.Item id="a">A</TableOfContents.Item>
+      </TableOfContents>
+    );
+    expect(container.querySelector('.custom-class')).toBeInTheDocument();
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(
+      <TableOfContents>
+        <TableOfContents.Item id="intro">Introduction</TableOfContents.Item>
+        <TableOfContents.Item id="setup" active>Setup</TableOfContents.Item>
+        <TableOfContents.Item id="api" indent>API Reference</TableOfContents.Item>
+        <TableOfContents.Item id="examples">Examples</TableOfContents.Item>
+      </TableOfContents>
+    );
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/TableOfContents/index.tsx

@@ -0,0 +1,110 @@
+'use client';
+
+import * as React from 'react';
+import styles from './TableOfContents.module.scss';
+import { Text } from '../Text';
+import '../../styles/globals.scss';
+
+// ============================================
+// 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;
+  /** Indent level — use for sub-headings (h3, h4, etc.) */
+  indent?: boolean;
+}
+
+// ============================================
+// Components
+// ============================================
+
+function TableOfContentsRoot({
+  children,
+  label = 'Table of contents',
+  title = 'On This Page',
+  hideTitle = false,
+  className,
+  ...htmlProps
+}: TableOfContentsProps) {
+  const classes = [styles.root, className].filter(Boolean).join(' ');
+
+  return (
+    <nav aria-label={label} className={classes} {...htmlProps}>
+      {!hideTitle && (
+        <Text as="p" variant="section-label" className={styles.title}>
+          {title}
+        </Text>
+      )}
+      <ul className={styles.list}>
+        {children}
+      </ul>
+    </nav>
+  );
+}
+
+function TableOfContentsItem({
+  children,
+  id,
+  active = false,
+  indent = false,
+  className,
+  onClick,
+  ...htmlProps
+}: TableOfContentsItemProps) {
+  const linkClasses = [
+    styles.link,
+    indent && styles.indent,
+    active && styles.active,
+    className,
+  ].filter(Boolean).join(' ');
+
+  const handleClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
+    e.preventDefault();
+    const el = document.getElementById(id);
+    if (el) {
+      el.scrollIntoView({ behavior: 'smooth' });
+      history.replaceState(null, '', `#${id}`);
+    }
+    onClick?.(e);
+  };
+
+  return (
+    <li className={styles.item}>
+      <a
+        href={`#${id}`}
+        className={linkClasses}
+        onClick={handleClick}
+        aria-current={active ? 'true' : undefined}
+        {...htmlProps}
+      >
+        {children}
+      </a>
+    </li>
+  );
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const TableOfContents = Object.assign(TableOfContentsRoot, {
+  Item: TableOfContentsItem,
+});
+
+// Re-export individual components
+export { TableOfContentsRoot, TableOfContentsItem };

package/src/components/Tabs/Tabs.fragment.tsx

@@ -1,8 +1,8 @@
 import React from 'react';
-import { defineSegment } from '@fragments/core';
+import { defineFragment } from '@fragments/core';
 import { Tabs } from '.';
 
-export default defineSegment({
+export default defineFragment({
   component: Tabs,
 
   meta: {

package/src/components/Text/Text.fragment.tsx

@@ -1,8 +1,8 @@
 import React from 'react';
-import { defineSegment } from '@fragments/core';
+import { defineFragment } from '@fragments/core';
 import { Text } from '.';
 
-export default defineSegment({
+export default defineFragment({
   component: Text,
 
   meta: {

package/src/components/Text/Text.module.scss

@@ -1,4 +1,5 @@
 @use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
 
 .text {
   font-family: var(--fui-font-sans, $fui-font-sans);
@@ -6,6 +7,11 @@
   margin: 0;
 }
 
+// Variants
+.variant-section-label {
+  @include section-label-text;
+}
+
 // Font sizes
 .size-2xs {
   font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);

package/src/components/Text/Text.test.tsx

@@ -22,6 +22,11 @@ describe('Text', () => {
     expect(el).toHaveClass('color-secondary');
   });
 
+  it('applies section-label variant class', () => {
+    render(<Text variant="section-label">Label</Text>);
+    expect(screen.getByText('Label')).toHaveClass('variant-section-label');
+  });
+
   it('applies truncate class', () => {
     render(<Text truncate>Long text that should truncate</Text>);
     expect(screen.getByText('Long text that should truncate')).toHaveClass('truncate');

package/src/components/Text/index.tsx

@@ -5,6 +5,7 @@ import '../../styles/globals.scss';
 export interface TextProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color'> {
   children: React.ReactNode;
   as?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span' | 'label' | 'div' | 'strong' | 'em' | 'small' | 'mark' | 'del' | 'ins' | 'sub' | 'sup' | 'time' | 'address' | 'blockquote' | 'cite' | 'code' | 'abbr';
+  variant?: 'section-label';
   size?: '2xs' | 'xs' | 'sm' | 'base' | 'lg' | 'xl' | '2xl';
   weight?: 'normal' | 'medium' | 'semibold';
   color?: 'primary' | 'secondary' | 'tertiary';
@@ -15,11 +16,12 @@ export interface TextProps extends Omit<React.HTMLAttributes<HTMLElement>, 'colo
   lineClamp?: number;
 }
 
-export const Text = React.forwardRef<HTMLElement, TextProps>(
+const TextRoot = React.forwardRef<HTMLElement, TextProps>(
   function Text(
     {
       children,
       as: Component = 'span',
+      variant,
       size,
       weight,
       color,
@@ -34,6 +36,7 @@ export const Text = React.forwardRef<HTMLElement, TextProps>(
   ) {
     const classes = [
       styles.text,
+      variant && styles[`variant-${variant}`],
       size && styles[`size-${size}`],
       weight && styles[`weight-${weight}`],
       color && styles[`color-${color}`],
@@ -56,3 +59,7 @@ export const Text = React.forwardRef<HTMLElement, TextProps>(
     );
   }
 );
+
+export const Text = Object.assign(TextRoot, {
+  Root: TextRoot,
+});

package/src/components/Textarea/Textarea.fragment.tsx

@@ -1,8 +1,8 @@
 import React from 'react';
-import { defineSegment } from '@fragments/core';
+import { defineFragment } from '@fragments/core';
 import { Textarea } from '.';
 
-export default defineSegment({
+export default defineFragment({
   component: Textarea,
 
   meta: {
@@ -52,6 +52,14 @@ export default defineSegment({
       default: 3,
       description: 'Number of visible text rows',
     },
+    minRows: {
+      type: 'number',
+      description: 'Minimum number of rows when auto-resizing',
+    },
+    maxRows: {
+      type: 'number',
+      description: 'Maximum number of rows when auto-resizing',
+    },
     label: {
       type: 'string',
       description: 'Label text above the textarea',

package/src/components/Textarea/index.tsx

@@ -49,7 +49,7 @@ function mergeAriaIds(...ids: Array<string | undefined>): string | undefined {
   return merged.length > 0 ? merged : undefined;
 }
 
-export const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
+const TextareaRoot = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
   function Textarea(
     {
       value,
@@ -143,3 +143,7 @@ export const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
     );
   }
 );
+
+export const Textarea = Object.assign(TextareaRoot, {
+  Root: TextareaRoot,
+});

package/src/components/Theme/Theme.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineSegment } from '@fragments/core';
+import { defineFragment } from '@fragments/core';
 import { ThemeProvider, ThemeToggle, useTheme } from '.';
 
 // Demo component to show hook usage
@@ -14,7 +14,7 @@ function ThemeDemo() {
   );
 }
 
-export default defineSegment({
+export default defineFragment({
   component: ThemeProvider,
 
   meta: {

package/src/components/Theme/ThemeToggle.module.scss

@@ -2,7 +2,7 @@
 @use '../../tokens/mixins' as *;
 
 // ============================================
-// Theme Toggle - Segmented Button Group
+// Theme Toggle - Fragmented Button Group
 // ============================================
 
 .toggleGroup {

package/src/components/Theme/index.tsx

@@ -254,7 +254,7 @@ function ThemeProvider({
 }
 
 /**
- * ThemeToggle - Segmented button group to toggle between light and dark themes
+ * ThemeToggle - Fragmented button group to toggle between light and dark themes
  *
  * Can be used in two modes:
  * 1. Uncontrolled (default): Uses ThemeProvider context to get/set theme
@@ -340,4 +340,11 @@ function ThemeToggle({
 // Exports
 // ============================================
 
+export const Theme = Object.assign(ThemeProvider, {
+  Root: ThemeProvider,
+  Provider: ThemeProvider,
+  Toggle: ThemeToggle,
+  useTheme,
+});
+
 export { ThemeProvider, ThemeToggle, useTheme };

package/src/components/ThinkingIndicator/ThinkingIndicator.fragment.tsx

@@ -1,8 +1,8 @@
 import React from 'react';
-import { defineSegment } from '@fragments/core';
+import { defineFragment } from '@fragments/core';
 import { ThinkingIndicator } from '.';
 
-export default defineSegment({
+export default defineFragment({
   component: ThinkingIndicator,
 
   meta: {
@@ -51,7 +51,8 @@ export default defineSegment({
       description: 'Status text',
     },
     variant: {
-      type: '"dots" | "pulse" | "spinner"',
+      type: 'enum',
+      values: ['dots', 'pulse', 'spinner'],
       default: '"dots"',
       description: 'Animation style',
     },
@@ -61,7 +62,7 @@ export default defineSegment({
       description: 'Show elapsed time',
     },
     steps: {
-      type: 'ThinkingStep[]',
+      type: 'array',
       description: 'Multi-step progress array',
     },
   },

package/src/components/Toast/Toast.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineSegment } from '@fragments/core';
+import { defineFragment } from '@fragments/core';
 import { Toast, ToastProvider, useToast } from '.';
 
 // Demo component that triggers toasts
@@ -45,7 +45,7 @@ function ToastDemoWrapper() {
   );
 }
 
-export default defineSegment({
+export default defineFragment({
   component: Toast,
 
   meta: {
@@ -108,6 +108,18 @@ export default defineSegment({
       type: 'object',
       description: 'Optional action button { label, onClick }',
     },
+    onDismiss: {
+      type: 'function',
+      description: 'Callback when toast should be dismissed',
+    },
+    onPause: {
+      type: 'function',
+      description: 'Callback when auto-dismiss timer should pause',
+    },
+    onResume: {
+      type: 'function',
+      description: 'Callback when auto-dismiss timer should resume',
+    },
   },
 
   relations: [

package/src/components/Toggle/Toggle.fragment.tsx

@@ -1,5 +1,5 @@
 import React, { useState } from 'react';
-import { defineSegment } from '@fragments/core';
+import { defineFragment } from '@fragments/core';
 import { Toggle } from '.';
 
 // Stateful wrapper for interactive demos
@@ -8,7 +8,7 @@ function StatefulToggle(props: React.ComponentProps<typeof Toggle>) {
   return <Toggle {...props} checked={checked} onChange={setChecked} />;
 }
 
-export default defineSegment({
+export default defineFragment({
   component: Toggle,
 
   meta: {

package/src/components/Toggle/index.tsx

@@ -20,7 +20,7 @@ export interface ToggleProps {
   'aria-describedby'?: string;
 }
 
-export const Toggle = React.forwardRef<HTMLButtonElement, ToggleProps>(
+const ToggleRoot = React.forwardRef<HTMLButtonElement, ToggleProps>(
   function Toggle(
     {
       checked,
@@ -90,3 +90,7 @@ export const Toggle = React.forwardRef<HTMLButtonElement, ToggleProps>(
     );
   }
 );
+
+export const Toggle = Object.assign(ToggleRoot, {
+  Root: ToggleRoot,
+});

package/src/components/ToggleGroup/ToggleGroup.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineSegment } from '@fragments/core';
+import { defineFragment } from '@fragments/core';
 import { ToggleGroup } from '.';
 
 function DefaultExample() {
@@ -92,7 +92,7 @@ function DisabledItemExample() {
   );
 }
 
-export default defineSegment({
+export default defineFragment({
   component: ToggleGroup,
 
   meta: {
@@ -100,7 +100,7 @@ export default defineSegment({
     description: 'A group of toggle buttons where only one can be selected at a time. Useful for switching between views, modes, or options.',
     category: 'forms',
     status: 'stable',
-    tags: ['toggle', 'group', 'segmented', 'control', 'tabs', 'switch'],
+    tags: ['toggle', 'group', 'fragmented', 'control', 'tabs', 'switch'],
     since: '0.2.0',
   },
 
@@ -108,7 +108,7 @@ export default defineSegment({
     when: [
       'Switching between mutually exclusive views or modes',
       'Selecting one option from a small set (2-5 options)',
-      'Segmented controls like view switchers',
+      'Fragmented controls like view switchers',
       'Filter or sort options',
     ],
     whenNot: [
@@ -185,7 +185,7 @@ export default defineSegment({
     scenarioTags: [
       'forms.selection',
       'input.toggle',
-      'control.segmented',
+      'control.fragmented',
     ],
     a11yRules: ['A11Y_GROUP_ROLE', 'A11Y_KEYBOARD_ACCESSIBLE'],
   },

package/src/components/Tooltip/Tooltip.fragment.tsx

@@ -1,9 +1,9 @@
 import React from 'react';
-import { defineSegment } from '@fragments/core';
+import { defineFragment } from '@fragments/core';
 import { Tooltip } from '.';
 import { Button } from '../Button';
 
-export default defineSegment({
+export default defineFragment({
   component: Tooltip,
 
   meta: {
@@ -74,6 +74,11 @@ export default defineSegment({
       description: 'Delay before showing (ms)',
       default: '400',
     },
+    closeDelay: {
+      type: 'number',
+      description: 'Delay before hiding (ms)',
+      default: '0',
+    },
     arrow: {
       type: 'boolean',
       description: 'Show arrow pointing to trigger',
@@ -84,6 +89,19 @@ export default defineSegment({
       description: 'Disable the tooltip',
       default: 'false',
     },
+    open: {
+      type: 'boolean',
+      description: 'Controlled open state',
+    },
+    defaultOpen: {
+      type: 'boolean',
+      description: 'Default open state',
+      default: 'false',
+    },
+    onOpenChange: {
+      type: 'function',
+      description: 'Callback when open state changes',
+    },
   },
 
   relations: [