@usefragments/ui 1.0.0

package/src/components/Breadcrumbs/Breadcrumbs.module.scss

@@ -0,0 +1,121 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' 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);
+}
+
+// Ordered list container
+.list {
+  display: inline-flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: var(--fui-space-1, $fui-space-1);
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+// Individual breadcrumb item (li)
+.item {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--fui-space-1, $fui-space-1);
+  min-width: 0;
+}
+
+// Link styling
+.link {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--fui-space-1, $fui-space-1);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  text-decoration: none;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  max-width: 200px;
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+  padding: var(--fui-space-0-5, $fui-space-0-5) var(--fui-space-1, $fui-space-1);
+  margin: calc(-1 * var(--fui-space-0-5, $fui-space-0-5)) calc(-1 * var(--fui-space-1, $fui-space-1));
+  transition: color var(--fui-transition-fast, $fui-transition-fast),
+    background-color var(--fui-transition-fast, $fui-transition-fast);
+
+  &:hover {
+    color: var(--fui-text-primary, $fui-text-primary);
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
+
+  &:focus-visible {
+    @include focus-ring;
+  }
+}
+
+// Current page (not a link)
+.current {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--fui-space-1, $fui-space-1);
+  color: var(--fui-text-primary, $fui-text-primary);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  max-width: 200px;
+}
+
+// Separator between items
+.separator {
+  display: inline-flex;
+  align-items: center;
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  user-select: none;
+  flex-shrink: 0;
+}
+
+// Ellipsis button for collapsed items
+.ellipsis {
+  @include touch-target;
+
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  background: none;
+  border: 1px solid var(--fui-border, $fui-border);
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  cursor: pointer;
+  padding: var(--fui-space-0-5, $fui-space-0-5) var(--fui-space-2, $fui-space-2);
+  font-family: inherit;
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  line-height: 1;
+  transition: color var(--fui-transition-fast, $fui-transition-fast),
+    background-color var(--fui-transition-fast, $fui-transition-fast);
+
+  &:hover {
+    color: var(--fui-text-primary, $fui-text-primary);
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
+
+  &:focus-visible {
+    @include focus-ring;
+  }
+}
+
+// Icon within an item
+.icon {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+  width: var(--fui-icon-md, $fui-icon-md);
+  height: var(--fui-icon-md, $fui-icon-md);
+
+  svg {
+    width: 100%;
+    height: 100%;
+  }
+}

package/src/components/Breadcrumbs/Breadcrumbs.stories.tsx

@@ -0,0 +1,87 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Breadcrumbs } from '.';
+
+/**
+ * Breadcrumbs show the current page location within a hierarchy and let users
+ * navigate back through parent pages. It is a compound component: compose
+ * Breadcrumbs.Item children, marking the last one with `current`.
+ */
+const meta = {
+  title: 'Navigation/Breadcrumbs',
+  component: Breadcrumbs,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Breadcrumb navigation showing the current page location within a hierarchy.',
+      },
+    },
+  },
+  argTypes: {
+    maxItems: {
+      control: 'number',
+      description: 'Maximum visible items before collapsing middle items with ellipsis',
+    },
+    label: {
+      control: 'text',
+      description: 'Custom aria-label for the breadcrumb nav landmark',
+    },
+  },
+  args: {
+    children: (
+      <>
+        <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
+        <Breadcrumbs.Item href="#">Products</Breadcrumbs.Item>
+        <Breadcrumbs.Item current>Current Page</Breadcrumbs.Item>
+      </>
+    ),
+  },
+} satisfies Meta<typeof Breadcrumbs>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <Breadcrumbs>
+      <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">Products</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">Category</Breadcrumbs.Item>
+      <Breadcrumbs.Item current>Current Page</Breadcrumbs.Item>
+    </Breadcrumbs>
+  ),
+};
+
+export const Collapsed: Story = {
+  render: () => (
+    <Breadcrumbs maxItems={3}>
+      <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">Category</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">Subcategory</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">Section</Breadcrumbs.Item>
+      <Breadcrumbs.Item current>Current Page</Breadcrumbs.Item>
+    </Breadcrumbs>
+  ),
+};
+
+export const CustomSeparator: Story = {
+  render: () => (
+    <Breadcrumbs separator=">">
+      <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">Settings</Breadcrumbs.Item>
+      <Breadcrumbs.Item current>Profile</Breadcrumbs.Item>
+    </Breadcrumbs>
+  ),
+};
+
+export const CustomLandmarkLabel: Story = {
+  render: () => (
+    <Breadcrumbs label="Documentation breadcrumbs">
+      <Breadcrumbs.Item href="#">Docs</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">Components</Breadcrumbs.Item>
+      <Breadcrumbs.Item current>Breadcrumbs</Breadcrumbs.Item>
+    </Breadcrumbs>
+  ),
+};

package/src/components/Breadcrumbs/index.tsx

@@ -0,0 +1,205 @@
+'use client';
+
+import * as React from 'react';
+import styles from './Breadcrumbs.module.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export interface BreadcrumbsProps extends React.HTMLAttributes<HTMLElement> {
+  children: React.ReactNode;
+  /** Custom separator between items (default: '/') */
+  separator?: React.ReactNode;
+  /** Maximum visible items before collapsing middle items with ellipsis */
+  maxItems?: number;
+  /** Accessible label for the breadcrumb nav landmark (default: "Breadcrumb") */
+  label?: string;
+}
+
+export interface BreadcrumbsItemProps extends React.HTMLAttributes<HTMLLIElement> {
+  children: React.ReactNode;
+  /** URL to navigate to (renders <a> if provided) */
+  href?: string;
+  /** Icon element to display before the label */
+  icon?: React.ReactNode;
+  /** Marks this item as the current page */
+  current?: boolean;
+}
+
+export interface BreadcrumbsSeparatorProps {
+  children?: React.ReactNode;
+  className?: string;
+}
+
+// ============================================
+// Context for separator
+// ============================================
+
+const BreadcrumbsSeparatorContext = React.createContext<React.ReactNode>('/');
+
+// ============================================
+// Components
+// ============================================
+
+function BreadcrumbsRoot({
+  children,
+  separator = '/',
+  maxItems,
+  label = 'Breadcrumb',
+  className,
+  'aria-label': ariaLabel,
+  ...htmlProps
+}: BreadcrumbsProps) {
+  const classes = [styles.root, className].filter(Boolean).join(' ');
+
+  let items = React.Children.toArray(children).filter(React.isValidElement);
+
+  // Collapse middle items if maxItems is set
+  let collapsed = false;
+  let collapsedItems: React.ReactElement[] = [];
+  if (maxItems != null && maxItems > 1 && items.length > maxItems) {
+    collapsed = true;
+    const first = items.slice(0, 1);
+    const last = items.slice(-(maxItems - 1));
+    collapsedItems = items.slice(1, items.length - (maxItems - 1)) as React.ReactElement[];
+    items = [...first, ...last];
+  }
+
+  return (
+    <BreadcrumbsSeparatorContext.Provider value={separator}>
+      <nav {...htmlProps} aria-label={ariaLabel ?? label} className={classes}>
+        <ol className={styles.list}>
+          {items.map((item, index) => {
+            const isFirst = index === 0;
+            const showEllipsis = collapsed && index === 1;
+
+            return (
+              <React.Fragment key={(item as React.ReactElement).key ?? index}>
+                {!isFirst && (
+                  <li role="presentation" aria-hidden="true" className={styles.separator}>
+                    {separator}
+                  </li>
+                )}
+                {showEllipsis && (
+                  <EllipsisItem items={collapsedItems} separator={separator} />
+                )}
+                {item}
+              </React.Fragment>
+            );
+          })}
+        </ol>
+      </nav>
+    </BreadcrumbsSeparatorContext.Provider>
+  );
+}
+
+function EllipsisItem({
+  items,
+  separator,
+}: {
+  items: React.ReactElement[];
+  separator: React.ReactNode;
+}) {
+  const [expanded, setExpanded] = React.useState(false);
+
+  if (expanded) {
+    return (
+      <>
+        {items.map((item, i) => (
+          <React.Fragment key={item.key ?? `collapsed-${i}`}>
+            {item}
+            <li role="presentation" aria-hidden="true" className={styles.separator}>
+              {separator}
+            </li>
+          </React.Fragment>
+        ))}
+      </>
+    );
+  }
+
+  return (
+    <>
+      <li className={styles.item}>
+        <button
+          type="button"
+          className={styles.ellipsis}
+          aria-label="Show collapsed breadcrumbs"
+          onClick={() => setExpanded(true)}
+        >
+          &hellip;
+        </button>
+      </li>
+      <li role="presentation" aria-hidden="true" className={styles.separator}>
+        {separator}
+      </li>
+    </>
+  );
+}
+
+function BreadcrumbsItem({
+  children,
+  href,
+  icon,
+  current = false,
+  className,
+  ...htmlProps
+}: BreadcrumbsItemProps) {
+  const classes = [styles.item, className].filter(Boolean).join(' ');
+
+  const iconEl = icon ? <span className={styles.icon}>{icon}</span> : null;
+
+  if (current) {
+    return (
+      <li className={classes} {...htmlProps}>
+        <span className={styles.current} aria-current="page">
+          {iconEl}
+          {children}
+        </span>
+      </li>
+    );
+  }
+
+  if (href) {
+    return (
+      <li className={classes} {...htmlProps}>
+        <a href={href} className={styles.link}>
+          {iconEl}
+          {children}
+        </a>
+      </li>
+    );
+  }
+
+  return (
+    <li className={classes} {...htmlProps}>
+      <span className={styles.link}>
+        {iconEl}
+        {children}
+      </span>
+    </li>
+  );
+}
+
+function BreadcrumbsSeparator({ children, className }: BreadcrumbsSeparatorProps) {
+  const defaultSeparator = React.useContext(BreadcrumbsSeparatorContext);
+  const classes = [styles.separator, className].filter(Boolean).join(' ');
+
+  return (
+    <span className={classes} role="presentation" aria-hidden="true">
+      {children ?? defaultSeparator}
+    </span>
+  );
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const Breadcrumbs = Object.assign(BreadcrumbsRoot, {
+  Item: BreadcrumbsItem,
+  Separator: BreadcrumbsSeparator,
+});
+
+// Re-export individual components
+export { BreadcrumbsRoot, BreadcrumbsItem, BreadcrumbsSeparator };

package/src/components/Button/Button.contract.json

@@ -0,0 +1,212 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Button",
+  "description": "Interactive element for user actions and form submissions",
+  "category": "forms",
+  "tags": [
+    "action",
+    "button",
+    "form",
+    "interactive"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Button/index.tsx",
+  "exportName": "Button",
+  "propsSummary": [
+    "as: button|a",
+    "children: node (required)",
+    "variant: primary|secondary|ghost|link|danger|outlined|outline|icon (default: \"primary\")",
+    "size: xs|sm|md|lg (default: \"md\")",
+    "icon: boolean",
+    "fullWidth: boolean",
+    "asChild: boolean"
+  ],
+  "props": {
+    "as": {
+      "type": "enum",
+      "description": "Render as a native button or anchor element",
+      "default": "button",
+      "required": false,
+      "values": [
+        "button",
+        "a"
+      ]
+    },
+    "children": {
+      "type": "node",
+      "description": "Button label content",
+      "required": true
+    },
+    "variant": {
+      "type": "enum",
+      "description": "Visual style variant (\"icon\" is a convenience alias for outlined + icon-only layout, \"link\" is accent-coloured + transparent for tertiary CTAs)",
+      "default": "\"primary\"",
+      "required": false,
+      "values": [
+        "primary",
+        "secondary",
+        "ghost",
+        "link",
+        "danger",
+        "outlined",
+        "outline",
+        "icon"
+      ],
+      "constraints": [
+        "Only one primary button per context"
+      ]
+    },
+    "size": {
+      "type": "enum",
+      "description": "Button size (\"xs\" is for inline row-action controls where \"sm\" is too tall)",
+      "default": "\"md\"",
+      "required": false,
+      "values": [
+        "xs",
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "icon": {
+      "type": "boolean",
+      "description": "Render as icon-only button (square aspect ratio). Useful with any visual variant; variant=\"icon\" is the default outlined icon-only shortcut.",
+      "default": "false",
+      "required": false
+    },
+    "fullWidth": {
+      "type": "boolean",
+      "description": "Make button full width of container",
+      "default": "false",
+      "required": false
+    },
+    "asChild": {
+      "type": "boolean",
+      "description": "Merge button styling onto child element (e.g. Next.js Link)",
+      "default": "false",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Triggering an action (save, submit, delete, etc.)",
+      "Form submission",
+      "Opening dialogs or menus",
+      "Navigation when action context is needed"
+    ],
+    "whenNot": [
+      "Simple navigation (use Link)",
+      "Toggling state (use Switch or Checkbox)",
+      "Selecting from options (use Select or RadioGroup)"
+    ],
+    "guidelines": [
+      "Use Primary for the main action in a context",
+      "Only one Primary button per section/form",
+      "Use Danger variant for destructive actions",
+      "Loading state should disable the button",
+      "When using asChild, pass interaction and accessibility props directly on Button (they are forwarded to the child element)",
+      "Use variant=\"icon\" for the default icon-only action button, or combine icon={true} with another visual variant when needed"
+    ],
+    "accessibility": [
+      "Button text should describe the action",
+      "Avoid generic labels like \"Click here\"",
+      "Icon-only buttons need aria-label"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Primary",
+      "description": "Default action button for primary actions",
+      "code": "<Button variant=\"primary\">Save Changes</Button>"
+    },
+    {
+      "name": "Secondary",
+      "description": "Less prominent action button",
+      "code": "<Button variant=\"secondary\">Cancel</Button>"
+    },
+    {
+      "name": "Ghost",
+      "description": "Minimal visual weight for subtle actions",
+      "code": "<Button variant=\"ghost\">Learn More</Button>"
+    },
+    {
+      "name": "Link",
+      "description": "Accent-coloured transparent button for tertiary CTAs",
+      "code": "<Button variant=\"link\">View all →</Button>"
+    },
+    {
+      "name": "Danger",
+      "description": "Destructive action requiring attention",
+      "code": "<Button variant=\"danger\">Delete Item</Button>"
+    },
+    {
+      "name": "Outline",
+      "description": "Bordered button with transparent background",
+      "code": "<Button variant=\"outline\">View Details</Button>"
+    },
+    {
+      "name": "Icon",
+      "description": "Convenience icon-only button alias (ghost + square icon sizing)",
+      "code": "<Button variant=\"icon\" aria-label=\"Add item\">\n  <span aria-hidden>+</span>\n</Button>"
+    },
+    {
+      "name": "Sizes",
+      "description": "Available size options",
+      "code": "<div style={{ display: 'flex', gap: '8px', alignItems: 'center' }}>\n  <Button size=\"xs\" variant=\"icon\" aria-label=\"Dismiss\">\u00d7</Button>\n  <Button size=\"sm\">Small</Button>\n  <Button size=\"md\">Medium</Button>\n  <Button size=\"lg\">Large</Button>\n</div>"
+    },
+    {
+      "name": "Disabled",
+      "description": "Non-interactive state",
+      "code": "<Button disabled>Cannot Click</Button>"
+    },
+    {
+      "name": "As Child",
+      "description": "Compose button styles onto another interactive element while preserving forwarded props",
+      "code": "<Button asChild variant=\"outlined\" aria-label=\"Open billing settings\">\n  <a href=\"#billing-settings\">Billing Settings</a>\n</Button>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Link",
+      "relationship": "alternative",
+      "note": "Use Link for navigation without action context"
+    },
+    {
+      "component": "Icon",
+      "relationship": "complementary",
+      "note": "Use Icon inside Button for icon-leading/trailing or icon-only actions"
+    },
+    {
+      "component": "ButtonGroup",
+      "relationship": "parent",
+      "note": "Use ButtonGroup for related action sets"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "variant: primary|secondary|ghost|link|danger|outlined|outline|icon (default: primary, icon = outlined + icon-only, link = accent transparent)",
+      "size: xs|sm|md|lg (default: md, xs for inline row-action controls)",
+      "disabled: boolean - disables interaction",
+      "type: button|submit|reset (default: button)",
+      "onClick: (event) => void - action handler",
+      "asChild: boolean - composes styles/props onto a child element (links/router links)",
+      "icon: boolean - icon-only square layout (can be combined with visual variants)"
+    ],
+    "a11yRules": [
+      "A11Y_BTN_LABEL",
+      "A11Y_BTN_FOCUS"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:51.517Z"
+  }
+}