@usefragments/ui 1.0.0

package/src/components/Link/index.tsx

@@ -0,0 +1,102 @@
+import * as React from 'react';
+import styles from './Link.module.scss';
+
+function composeEventHandlers<T extends (...args: any[]) => void>(
+  childHandler: T | undefined,
+  parentHandler: T | undefined
+) {
+  if (!childHandler) return parentHandler;
+  if (!parentHandler) return childHandler;
+  return ((...args: Parameters<T>) => {
+    childHandler(...args);
+    parentHandler(...args);
+  }) as T;
+}
+
+export interface LinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+  children: React.ReactNode;
+  /** Visual variant */
+  variant?: 'default' | 'subtle' | 'muted';
+  /** Underline style */
+  underline?: 'always' | 'hover' | 'none';
+  /** Open in new tab (adds rel="noopener noreferrer") */
+  external?: boolean;
+  /**
+   * Render as child element (polymorphic). When true, clones the single child
+   * and merges link props onto it. Useful for rendering as Next.js Link, etc.
+   */
+  asChild?: boolean;
+  /** Additional class name */
+  className?: string;
+  /** Inline styles */
+  style?: React.CSSProperties;
+}
+
+const LinkRoot = React.forwardRef<HTMLAnchorElement, LinkProps>(
+  function Link(
+    {
+      children,
+      variant = 'default',
+      underline = 'hover',
+      external = false,
+      asChild = false,
+      className,
+      style,
+      target,
+      rel,
+      ...props
+    },
+    ref
+  ) {
+    const classes = [
+      styles.link,
+      styles[variant],
+      styles[`underline-${underline}`],
+      className,
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    // Handle external links
+    const externalProps = external
+      ? {
+          target: target || '_blank',
+          rel: rel || 'noopener noreferrer',
+        }
+      : { target, rel };
+
+    if (asChild && React.isValidElement(children)) {
+      const childProps = children.props as Record<string, unknown>;
+      const mergedProps: Record<string, unknown> = {
+        ref,
+        className: childProps.className
+          ? `${classes} ${childProps.className}`
+          : classes,
+        style: { ...style, ...(childProps.style as React.CSSProperties | undefined) },
+        ...externalProps,
+        ...props,
+      };
+
+      for (const [key, parentValue] of Object.entries({ ...externalProps, ...props })) {
+        if (!key.startsWith('on') || typeof parentValue !== 'function') continue;
+        const childValue = childProps[key];
+        if (typeof childValue !== 'function') continue;
+        mergedProps[key] = composeEventHandlers(
+          childValue as (...args: unknown[]) => void,
+          parentValue as (...args: unknown[]) => void
+        );
+      }
+      return React.cloneElement(children, mergedProps);
+    }
+
+    return (
+      <a ref={ref} className={classes} style={style} {...externalProps} {...props}>
+        {children}
+      </a>
+    );
+  }
+);
+
+export const Link = Object.assign(LinkRoot, {
+  Root: LinkRoot,
+});

package/src/components/List/List.contract.json

@@ -0,0 +1,154 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "List",
+  "description": "Compound component for rendering ordered or unordered lists with consistent styling. Supports bullet, numbered, and icon-prefixed items.",
+  "category": "display",
+  "tags": [
+    "list",
+    "items",
+    "bullet",
+    "ordered",
+    "unordered"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/List/index.tsx",
+  "exportName": "List",
+  "propsSummary": [
+    "children: node (required)",
+    "as: ul|ol (default: ul)",
+    "variant: none|disc|decimal|icon (default: disc)",
+    "gap: none|xs|sm|md|lg (default: sm)",
+    "style: object"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "List.Item components",
+      "required": true
+    },
+    "as": {
+      "type": "enum",
+      "description": "List type",
+      "default": "ul",
+      "required": false,
+      "values": [
+        "ul",
+        "ol"
+      ]
+    },
+    "variant": {
+      "type": "enum",
+      "description": "List style variant",
+      "default": "disc",
+      "required": false,
+      "values": [
+        "none",
+        "disc",
+        "decimal",
+        "icon"
+      ]
+    },
+    "gap": {
+      "type": "enum",
+      "description": "Spacing between items",
+      "default": "sm",
+      "required": false,
+      "values": [
+        "none",
+        "xs",
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "style": {
+      "type": "object",
+      "description": "",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Feature lists with checkmarks or icons",
+      "Ordered steps or instructions",
+      "Navigation lists in sidebars",
+      "Pricing plan feature comparisons"
+    ],
+    "whenNot": [
+      "Interactive selection lists (use Menu or Select)",
+      "Data tables with columns (use Table)",
+      "Cards in a grid (use Grid with Card)",
+      "Navigation tabs (use Tabs)"
+    ],
+    "guidelines": [
+      "Use as=\"ol\" for sequential or numbered content",
+      "Use variant=\"icon\" with meaningful icons for feature lists",
+      "Keep list items concise and parallel in structure",
+      "Use consistent icons within a single list"
+    ],
+    "accessibility": [
+      "Use semantic list elements (ul, ol) for screen reader support",
+      "List items are automatically announced with count",
+      "Icons are decorative; ensure text conveys meaning",
+      "Avoid deeply nested lists (3+ levels)"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Bullet List",
+      "description": "Default unordered list with bullets",
+      "code": "<List variant=\"disc\">\n  <List.Item>First item</List.Item>\n  <List.Item>Second item</List.Item>\n  <List.Item>Third item</List.Item>\n</List>"
+    },
+    {
+      "name": "Numbered List",
+      "description": "Ordered list with numbers",
+      "code": "<List as=\"ol\" variant=\"decimal\">\n  <List.Item>Create your account</List.Item>\n  <List.Item>Configure your settings</List.Item>\n  <List.Item>Start building</List.Item>\n</List>"
+    },
+    {
+      "name": "Icon List",
+      "description": "List with custom icons per item",
+      "code": "<List variant=\"icon\">\n  <List.Item icon={<Check weight=\"bold\" color=\"var(--fui-color-success)\" />}>\n    Unlimited projects\n  </List.Item>\n  <List.Item icon={<Check weight=\"bold\" color=\"var(--fui-color-success)\" />}>\n    Priority support\n  </List.Item>\n  <List.Item icon={<Check weight=\"bold\" color=\"var(--fui-color-success)\" />}>\n    Advanced analytics\n  </List.Item>\n</List>"
+    },
+    {
+      "name": "No Style",
+      "description": "Plain list without markers",
+      "code": "<List variant=\"none\" gap=\"md\">\n  <List.Item>Dashboard</List.Item>\n  <List.Item>Settings</List.Item>\n  <List.Item>Profile</List.Item>\n</List>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Icon",
+      "relationship": "child",
+      "note": "Use Icon as List.Item icon prop"
+    },
+    {
+      "component": "Stack",
+      "relationship": "alternative",
+      "note": "Use Stack for non-semantic vertical lists"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "children: List.Item[] - list items (required)",
+      "as: ul|ol - list type",
+      "variant: none|disc|decimal|icon - list style",
+      "gap: none|xs|sm|md|lg - item spacing"
+    ],
+    "a11yRules": [
+      "A11Y_LIST_SEMANTIC",
+      "A11Y_LIST_NESTING"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Item"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:59.915Z"
+  }
+}

package/src/components/List/List.module.scss

@@ -0,0 +1,71 @@
+@use '../../tokens/variables' as *;
+
+.list {
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+}
+
+// Variants
+.none {
+  list-style: none;
+}
+
+.disc {
+  list-style: disc;
+  padding-left: var(--fui-space-2, $fui-space-2);
+}
+
+.decimal {
+  list-style: decimal;
+  padding-left: var(--fui-space-2, $fui-space-2);
+}
+
+.icon {
+  list-style: none;
+}
+
+// Gap variants
+.gap-none {
+  gap: 0;
+}
+
+.gap-xs {
+  gap: var(--fui-space-1, $fui-space-1);
+}
+
+.gap-sm {
+  gap: var(--fui-space-2, $fui-space-2);
+}
+
+.gap-md {
+  gap: var(--fui-space-3, $fui-space-3);
+}
+
+.gap-lg {
+  gap: var(--fui-space-4, $fui-space-4);
+}
+
+// List item
+.item {
+  color: var(--fui-text-primary, $fui-text-primary);
+}
+
+.iconItem {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--fui-space-2, $fui-space-2);
+}
+
+.iconWrapper {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+}
+
+.itemContent {
+  flex: 1;
+}

package/src/components/List/List.stories.tsx

@@ -0,0 +1,95 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { List } from '.';
+
+/**
+ * Compound component for ordered or unordered lists with consistent styling.
+ * Compose with `List.Item`. Supports bullet, numbered, icon, and unstyled variants.
+ */
+const meta = {
+  title: 'Display/List',
+  component: List,
+  tags: ['autodocs', 'canonical'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Renders ordered or unordered lists with consistent styling.',
+      },
+    },
+  },
+  argTypes: {
+    as: {
+      control: 'select',
+      options: ['ul', 'ol'],
+      description: 'Underlying list element',
+    },
+    variant: {
+      control: 'select',
+      options: ['none', 'disc', 'decimal', 'icon'],
+      description: 'List style variant',
+    },
+    gap: {
+      control: 'select',
+      options: ['none', 'xs', 'sm', 'md', 'lg'],
+      description: 'Spacing between items',
+    },
+  },
+  args: {
+    variant: 'disc',
+    gap: 'sm',
+    children: (
+      <>
+        <List.Item>First item</List.Item>
+        <List.Item>Second item</List.Item>
+        <List.Item>Third item</List.Item>
+      </>
+    ),
+  },
+} satisfies Meta<typeof List>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Bullet: Story = {
+  args: { variant: 'disc' },
+  render: (args) => (
+    <List {...args}>
+      <List.Item>First item</List.Item>
+      <List.Item>Second item</List.Item>
+      <List.Item>Third item</List.Item>
+    </List>
+  ),
+};
+
+export const Numbered: Story = {
+  args: { as: 'ol', variant: 'decimal' },
+  render: (args) => (
+    <List {...args}>
+      <List.Item>Create your account</List.Item>
+      <List.Item>Configure your settings</List.Item>
+      <List.Item>Start building</List.Item>
+    </List>
+  ),
+};
+
+export const IconList: Story = {
+  args: { variant: 'icon' },
+  render: (args) => (
+    <List {...args}>
+      <List.Item icon={<span aria-hidden>✓</span>}>Unlimited projects</List.Item>
+      <List.Item icon={<span aria-hidden>✓</span>}>Priority support</List.Item>
+      <List.Item icon={<span aria-hidden>✓</span>}>Advanced analytics</List.Item>
+    </List>
+  ),
+};
+
+export const Unstyled: Story = {
+  args: { variant: 'none', gap: 'md' },
+  render: (args) => (
+    <List {...args}>
+      <List.Item>Dashboard</List.Item>
+      <List.Item>Settings</List.Item>
+      <List.Item>Profile</List.Item>
+    </List>
+  ),
+};

package/src/components/List/index.tsx

@@ -0,0 +1,107 @@
+'use client';
+
+import * as React from 'react';
+import styles from './List.module.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export interface ListProps extends React.HTMLAttributes<HTMLUListElement | HTMLOListElement> {
+  children: React.ReactNode;
+  /** List type */
+  as?: 'ul' | 'ol';
+  /** List style variant */
+  variant?: 'none' | 'disc' | 'decimal' | 'icon';
+  /** Spacing between items */
+  gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg';
+}
+
+export interface ListItemProps extends React.HTMLAttributes<HTMLLIElement> {
+  children: React.ReactNode;
+  /** Icon to display (only used with variant="icon") */
+  icon?: React.ReactNode;
+}
+
+// ============================================
+// Context
+// ============================================
+
+interface ListContextValue {
+  variant: NonNullable<ListProps['variant']>;
+}
+
+const ListContext = React.createContext<ListContextValue>({ variant: 'disc' });
+
+function useListContext() {
+  return React.useContext(ListContext);
+}
+
+// ============================================
+// Components
+// ============================================
+
+function ListRoot({
+  children,
+  as: Component = 'ul',
+  variant = 'disc',
+  gap = 'sm',
+  className,
+  style,
+  ...htmlProps
+}: ListProps) {
+  const classes = [
+    styles.list,
+    styles[variant],
+    styles[`gap-${gap}`],
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <ListContext.Provider value={{ variant }}>
+      <Component {...htmlProps} className={classes} style={style}>
+        {children}
+      </Component>
+    </ListContext.Provider>
+  );
+}
+
+function ListItem({ children, icon, className, style, ...htmlProps }: ListItemProps) {
+  const { variant } = useListContext();
+
+  const classes = [
+    styles.item,
+    variant === 'icon' && styles.iconItem,
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  if (variant === 'icon' && icon) {
+    return (
+      <li {...htmlProps} className={classes} style={style}>
+        <span className={styles.iconWrapper}>{icon}</span>
+        <span className={styles.itemContent}>{children}</span>
+      </li>
+    );
+  }
+
+  return (
+    <li {...htmlProps} className={classes} style={style}>
+      {children}
+    </li>
+  );
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const List = Object.assign(ListRoot, {
+  Item: ListItem,
+});
+
+// Re-export individual components for tree-shaking
+export { ListRoot, ListItem, useListContext };

package/src/components/Listbox/Listbox.contract.json

@@ -0,0 +1,158 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Listbox",
+  "description": "Controlled listbox for search results, autocomplete dropdowns, and command menus. Provides Menu-like styling without requiring a trigger.",
+  "category": "forms",
+  "tags": [
+    "listbox",
+    "search",
+    "autocomplete",
+    "combobox",
+    "command",
+    "dropdown"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Listbox/index.tsx",
+  "exportName": "Listbox",
+  "propsSummary": [
+    "children: node (required)",
+    "style: object",
+    "tabIndex: number",
+    "onFocus: function",
+    "onKeyDown: function"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Listbox.Item, Listbox.Group, or Listbox.Empty components",
+      "required": true
+    },
+    "style": {
+      "type": "object",
+      "description": "",
+      "required": false
+    },
+    "tabIndex": {
+      "type": "number",
+      "description": "",
+      "required": false
+    },
+    "onFocus": {
+      "type": "function",
+      "description": "",
+      "required": false
+    },
+    "onKeyDown": {
+      "type": "function",
+      "description": "",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Search result dropdowns",
+      "Autocomplete suggestions",
+      "Command palette results",
+      "Keyboard-navigable option lists"
+    ],
+    "whenNot": [
+      "Static lists without selection (use List)",
+      "Action menus with trigger button (use Menu)",
+      "Form field selection (use Select)",
+      "Navigation menus (use Sidebar or Tabs)"
+    ],
+    "guidelines": [
+      "Control open/close state externally based on input focus or query",
+      "Listbox provides arrow/home/end + Enter/Space keyboard navigation when focused",
+      "Use Listbox.Empty for no results state",
+      "Group related items with Listbox.Group when appropriate"
+    ],
+    "accessibility": [
+      "Uses listbox and option ARIA roles",
+      "aria-selected indicates current selection",
+      "aria-disabled for non-interactive items",
+      "Connect to input with aria-controls for full combobox pattern"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic listbox with selectable items",
+      "code": "<Listbox aria-label=\"Options\">\n  <Listbox.Item selected>First option</Listbox.Item>\n  <Listbox.Item>Second option</Listbox.Item>\n  <Listbox.Item>Third option</Listbox.Item>\n</Listbox>"
+    },
+    {
+      "name": "Search Results",
+      "description": "Typical search results pattern with label and metadata",
+      "code": "<Listbox aria-label=\"Search results\">\n  <Listbox.Item selected>\n    <span style={{ fontWeight: 500 }}>Button</span>\n    <span style={{ marginLeft: 'auto', fontSize: '0.75rem', color: 'var(--fui-text-tertiary)' }}>Components</span>\n  </Listbox.Item>\n  <Listbox.Item>\n    <span style={{ fontWeight: 500 }}>Badge</span>\n    <span style={{ marginLeft: 'auto', fontSize: '0.75rem', color: 'var(--fui-text-tertiary)' }}>Components</span>\n  </Listbox.Item>\n  <Listbox.Item>\n    <span style={{ fontWeight: 500 }}>Box</span>\n    <span style={{ marginLeft: 'auto', fontSize: '0.75rem', color: 'var(--fui-text-tertiary)' }}>Layout</span>\n  </Listbox.Item>\n</Listbox>"
+    },
+    {
+      "name": "With Groups",
+      "description": "Grouped items with labels",
+      "code": "<Listbox aria-label=\"Commands\">\n  <Listbox.Group label=\"Recent\">\n    <Listbox.Item selected>Open file...</Listbox.Item>\n    <Listbox.Item>Save as...</Listbox.Item>\n  </Listbox.Group>\n  <Listbox.Group label=\"Actions\">\n    <Listbox.Item>Copy</Listbox.Item>\n    <Listbox.Item>Paste</Listbox.Item>\n    <Listbox.Item disabled>Cut</Listbox.Item>\n  </Listbox.Group>\n</Listbox>"
+    },
+    {
+      "name": "Empty State",
+      "description": "No results found message",
+      "code": "<Listbox aria-label=\"Search results\">\n  <Listbox.Empty>No results found</Listbox.Empty>\n</Listbox>"
+    },
+    {
+      "name": "With Disabled Items",
+      "description": "Mix of enabled and disabled items",
+      "code": "<Listbox aria-label=\"Options\">\n  <Listbox.Item>Available option</Listbox.Item>\n  <Listbox.Item disabled>Disabled option</Listbox.Item>\n  <Listbox.Item>Another option</Listbox.Item>\n</Listbox>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Input",
+      "relationship": "sibling",
+      "note": "Pair with Input for search/autocomplete patterns"
+    },
+    {
+      "component": "Menu",
+      "relationship": "alternative",
+      "note": "Use Menu when you need a trigger button"
+    },
+    {
+      "component": "Select",
+      "relationship": "alternative",
+      "note": "Use Select for form field selection"
+    },
+    {
+      "component": "List",
+      "relationship": "alternative",
+      "note": "Use List for static, non-interactive lists"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "children: ReactNode - Listbox.Item components (required)",
+      "aria-label: string - accessible label",
+      "Listbox.Item selected: boolean - highlight state",
+      "Listbox.Item disabled: boolean - non-interactive"
+    ],
+    "a11yRules": [
+      "A11Y_LISTBOX_ROLE",
+      "A11Y_OPTION_ROLE"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Item",
+      "Group",
+      "Empty"
+    ],
+    "requiredChildren": [
+      "Item"
+    ],
+    "commonPatterns": [
+      "<Listbox aria-label=\"Search results\">{results.map(item => <Listbox.Item key={item.id} selected={item.id === selectedId} onClick={() => onSelect(item)}>{item.label}</Listbox.Item>)}</Listbox>"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:05.924Z"
+  }
+}