@fragments-sdk/ui 0.6.5 → 0.7.0

package/src/components/Breadcrumbs/Breadcrumbs.fragment.tsx

@@ -0,0 +1,162 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Breadcrumbs } from '.';
+
+export default defineSegment({
+  component: Breadcrumbs,
+
+  meta: {
+    name: 'Breadcrumbs',
+    description: 'Breadcrumb navigation showing the current page location within a hierarchy. Helps users navigate back through parent pages.',
+    category: 'navigation',
+    status: 'stable',
+    tags: ['breadcrumbs', 'navigation', 'hierarchy', 'wayfinding'],
+    since: '0.7.0',
+  },
+
+  usage: {
+    when: [
+      'Showing hierarchical page location (e.g., Home > Category > Product)',
+      'Allowing quick navigation to parent pages',
+      'Multi-level content structures like documentation or e-commerce',
+    ],
+    whenNot: [
+      'Flat navigation with no hierarchy (use Tabs or Header nav)',
+      'Step-by-step wizards (use Stepper)',
+      'Primary navigation (use Sidebar or Header)',
+    ],
+    guidelines: [
+      'Always include the current page as the last, non-linked item',
+      'Keep labels short and descriptive',
+      'Use maxItems to collapse long paths, keeping first and last visible',
+      'The separator defaults to "/" but can be customized',
+    ],
+    accessibility: [
+      'Uses <nav aria-label="Breadcrumb"> for landmark navigation',
+      'Current page is marked with aria-current="page"',
+      'Separators are hidden from screen readers with aria-hidden',
+      'Ellipsis button has aria-label for collapsed items',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      description: 'Breadcrumb items (use Breadcrumbs.Item)',
+      required: true,
+    },
+    separator: {
+      type: 'node',
+      description: 'Custom separator between items',
+      default: '"/"',
+    },
+    maxItems: {
+      type: 'number',
+      description: 'Maximum visible items before collapsing middle items with ellipsis',
+    },
+  },
+
+  relations: [
+    { component: 'Tabs', relationship: 'alternative', note: 'Use Tabs for flat, non-hierarchical navigation' },
+    { component: 'Sidebar', relationship: 'complementary', note: 'Breadcrumbs complement sidebar navigation for deep hierarchies' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'separator: ReactNode - custom separator (default "/")',
+      'maxItems: number - collapse middle items with ellipsis',
+      'Breadcrumbs.Item href: string - makes item a link',
+      'Breadcrumbs.Item current: boolean - marks current page',
+      'Breadcrumbs.Item icon: ReactNode - icon before label',
+    ],
+    scenarioTags: [
+      'navigation.breadcrumbs',
+      'navigation.hierarchy',
+      'wayfinding.location',
+    ],
+    a11yRules: ['A11Y_NAV_LANDMARK', 'A11Y_ARIA_CURRENT'],
+  },
+
+  ai: {
+    compositionPattern: 'compound',
+    subComponents: ['Item', 'Separator'],
+    requiredChildren: ['Item'],
+    commonPatterns: [
+      '<Breadcrumbs><Breadcrumbs.Item href="/">Home</Breadcrumbs.Item><Breadcrumbs.Item href="/products">Products</Breadcrumbs.Item><Breadcrumbs.Item current>Widget</Breadcrumbs.Item></Breadcrumbs>',
+    ],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Basic breadcrumb navigation',
+      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>
+      ),
+    },
+    {
+      name: 'With Icons',
+      description: 'Breadcrumbs with icons on items',
+      render: () => (
+        <Breadcrumbs>
+          <Breadcrumbs.Item
+            href="#"
+            icon={
+              <svg viewBox="0 0 16 16" fill="currentColor">
+                <path d="M8 1.25l-7 6v7.5c0 .138.112.25.25.25H5.5V10h5v5h4.25a.25.25 0 0 0 .25-.25v-7.5l-7-6z" />
+              </svg>
+            }
+          >
+            Home
+          </Breadcrumbs.Item>
+          <Breadcrumbs.Item
+            href="#"
+            icon={
+              <svg viewBox="0 0 16 16" fill="currentColor">
+                <path d="M1.75 1A1.75 1.75 0 0 0 0 2.75v10.5C0 14.216.784 15 1.75 15h12.5A1.75 1.75 0 0 0 16 13.25v-8.5A1.75 1.75 0 0 0 14.25 3H7.5a.25.25 0 0 1-.2-.1l-.9-1.2C6.07 1.26 5.55 1 5 1H1.75z" />
+              </svg>
+            }
+          >
+            Documents
+          </Breadcrumbs.Item>
+          <Breadcrumbs.Item current>Report.pdf</Breadcrumbs.Item>
+        </Breadcrumbs>
+      ),
+    },
+    {
+      name: 'Collapsed',
+      description: 'Long breadcrumb trail collapsed with ellipsis',
+      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>
+      ),
+    },
+    {
+      name: 'Custom Separator',
+      description: 'Breadcrumbs with a custom chevron separator',
+      render: () => (
+        <Breadcrumbs
+          separator={
+            <svg width="12" height="12" viewBox="0 0 16 16" fill="currentColor">
+              <path fillRule="evenodd" d="M6.22 3.22a.75.75 0 0 1 1.06 0l4.25 4.25a.75.75 0 0 1 0 1.06l-4.25 4.25a.75.75 0 0 1-1.06-1.06L9.94 8 6.22 4.28a.75.75 0 0 1 0-1.06z" />
+            </svg>
+          }
+        >
+          <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
+          <Breadcrumbs.Item href="#">Settings</Breadcrumbs.Item>
+          <Breadcrumbs.Item current>Profile</Breadcrumbs.Item>
+        </Breadcrumbs>
+      ),
+    },
+  ],
+});

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

@@ -0,0 +1,120 @@
+@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);
+}
+
+// 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 {
+    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);
+  }
+}
+
+// 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 {
+  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 {
+    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);
+  }
+}
+
+// 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/index.tsx

@@ -0,0 +1,202 @@
+'use client';
+
+import * as React from 'react';
+import styles from './Breadcrumbs.module.scss';
+import '../../styles/globals.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;
+}
+
+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,
+  className,
+  ...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 aria-label="Breadcrumb" className={classes} {...htmlProps}>
+        <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/Chip/Chip.fragment.tsx

@@ -0,0 +1,175 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Chip } from '.';
+
+export default defineSegment({
+  component: Chip,
+
+  meta: {
+    name: 'Chip',
+    description: 'Interactive pill-shaped element for filtering, selecting, and tagging. Supports single and multi-select via Chip.Group.',
+    category: 'forms',
+    status: 'stable',
+    tags: ['chip', 'tag', 'filter', 'selection', 'multi-select', 'action'],
+    since: '0.7.0',
+  },
+
+  usage: {
+    when: [
+      'Filtering content by categories or tags',
+      'Multi-select scenarios like choosing interests or skills',
+      'Toggling options in a compact pill-shaped control',
+      'Displaying removable user-applied filters',
+    ],
+    whenNot: [
+      'Display-only status labels (use Badge)',
+      'Navigation between views (use Tabs)',
+      'Binary on/off state (use Toggle)',
+      'Primary call-to-action (use Button)',
+    ],
+    guidelines: [
+      'Keep chip labels short (1-3 words)',
+      'Use Chip.Group for multi-select sets with shared state',
+      'Use onRemove only when users should be able to dismiss the chip',
+      'Pair avatar chips with user-related selections (assignees, reviewers)',
+    ],
+    accessibility: [
+      'Chips use role="option" with aria-selected for selection state',
+      'Chip.Group uses role="listbox" with aria-multiselectable',
+      'Remove buttons include descriptive aria-label with chip text',
+      'Disabled chips are properly excluded from interaction',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      description: 'Chip label text',
+      required: true,
+    },
+    variant: {
+      type: 'enum',
+      description: 'Visual style variant',
+      values: ['filled', 'outlined', 'soft'],
+      default: 'filled',
+    },
+    size: {
+      type: 'enum',
+      description: 'Chip size',
+      values: ['sm', 'md'],
+      default: 'md',
+    },
+    selected: {
+      type: 'boolean',
+      description: 'Whether the chip is in a selected state',
+      default: 'false',
+    },
+    disabled: {
+      type: 'boolean',
+      description: 'Disables the chip',
+      default: 'false',
+    },
+    icon: {
+      type: 'node',
+      description: 'Icon element rendered before the label',
+    },
+    avatar: {
+      type: 'node',
+      description: 'Avatar element rendered before the label',
+    },
+    onRemove: {
+      type: 'function',
+      description: 'Makes chip removable. Called when X is clicked.',
+    },
+    value: {
+      type: 'string',
+      description: 'Value identifier used by Chip.Group for selection tracking',
+    },
+  },
+
+  relations: [
+    { component: 'Badge', relationship: 'sibling', note: 'Badge is display-only; Chip is interactive' },
+    { component: 'ToggleGroup', relationship: 'alternative', note: 'Use ToggleGroup for mutually exclusive options' },
+    { component: 'Button', relationship: 'alternative', note: 'Use Button for primary actions, Chip for selection/filtering' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'children: ReactNode - chip label (required)',
+      'variant: filled|outlined|soft - visual style',
+      'size: sm|md - chip size',
+      'selected: boolean - selection state',
+      'icon/avatar: ReactNode - leading visual',
+      'onRemove: () => void - makes chip removable',
+      'value: string - identifier for Chip.Group',
+    ],
+    scenarioTags: [
+      'actions.filter',
+      'actions.select',
+      'actions.tag',
+      'input.multi-select',
+    ],
+    a11yRules: ['A11Y_CHIP_SELECTION', 'A11Y_CHIP_DISMISS'],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Basic filled chip',
+      render: () => <Chip>Default</Chip>,
+    },
+    {
+      name: 'Selected',
+      description: 'Chip in selected state across variants',
+      render: () => (
+        <div style={{ display: 'flex', gap: '8px', flexWrap: 'wrap' }}>
+          <Chip selected>Filled</Chip>
+          <Chip variant="outlined" selected>Outlined</Chip>
+          <Chip variant="soft" selected>Soft</Chip>
+        </div>
+      ),
+    },
+    {
+      name: 'With Avatar',
+      description: 'Chip with a leading avatar image',
+      render: () => (
+        <Chip avatar={<img src="https://i.pravatar.cc/32?u=chip" alt="" />}>
+          Jane Doe
+        </Chip>
+      ),
+    },
+    {
+      name: 'With Remove',
+      description: 'Removable chip with dismiss button',
+      render: () => (
+        <div style={{ display: 'flex', gap: '8px' }}>
+          <Chip onRemove={() => {}}>React</Chip>
+          <Chip onRemove={() => {}}>TypeScript</Chip>
+          <Chip onRemove={() => {}}>SCSS</Chip>
+        </div>
+      ),
+    },
+    {
+      name: 'Chip Group',
+      description: 'Multi-select chip set with shared state',
+      render: () => (
+        <Chip.Group defaultValue={['react']}>
+          <Chip value="react">React</Chip>
+          <Chip value="vue">Vue</Chip>
+          <Chip value="angular">Angular</Chip>
+          <Chip value="svelte">Svelte</Chip>
+        </Chip.Group>
+      ),
+    },
+    {
+      name: 'Disabled',
+      description: 'Chip in disabled state',
+      render: () => (
+        <div style={{ display: 'flex', gap: '8px' }}>
+          <Chip disabled>Disabled</Chip>
+          <Chip disabled selected>Disabled Selected</Chip>
+        </div>
+      ),
+    },
+  ],
+});