@fragments-sdk/ui 0.7.4 → 0.8.0

package/src/components/Avatar/index.tsx

@@ -54,7 +54,39 @@ function stringToColor(str: string): string {
     hash = str.charCodeAt(i) + ((hash << 5) - hash);
   }
   const hue = Math.abs(hash % 360);
-  return `hsl(${hue}, 65%, 50%)`;
+  return `hsl(${hue}, 55%, 40%)`;
+}
+
+/**
+ * Compute a contrast-safe text color (white or black) for a given HSL background.
+ * Uses WCAG relative luminance to pick whichever gives higher contrast.
+ */
+function getContrastTextColor(bgColor: string): string | undefined {
+  const match = bgColor.match(/hsl\((\d+),\s*(\d+)%,\s*(\d+)%\)/);
+  if (!match) return undefined;
+
+  const h = parseInt(match[1]);
+  const s = parseInt(match[2]) / 100;
+  const l = parseInt(match[3]) / 100;
+
+  // HSL → RGB
+  const c = (1 - Math.abs(2 * l - 1)) * s;
+  const x = c * (1 - Math.abs((h / 60) % 2 - 1));
+  const m = l - c / 2;
+  let r = 0, g = 0, b = 0;
+  if (h < 60) { r = c; g = x; }
+  else if (h < 120) { r = x; g = c; }
+  else if (h < 180) { g = c; b = x; }
+  else if (h < 240) { g = x; b = c; }
+  else if (h < 300) { r = x; b = c; }
+  else { r = c; b = x; }
+  r += m; g += m; b += m;
+
+  // Relative luminance (sRGB → linear)
+  const lin = (v: number) => v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+  const lum = 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+
+  return lum > 0.179 ? '#000000' : '#ffffff';
 }
 
 // ============================================
@@ -100,6 +132,10 @@ const AvatarBase = React.forwardRef<HTMLDivElement, AvatarProps>(
     const style: React.CSSProperties = { ...styleProp };
     if (showFallback && fallbackColor) {
       style.backgroundColor = fallbackColor;
+      const textColor = getContrastTextColor(fallbackColor);
+      if (textColor) {
+        (style as Record<string, string>)['--avatar-initials-color'] = textColor;
+      }
     }
 
     return (

package/src/components/Badge/Badge.fragment.tsx

@@ -24,8 +24,8 @@ export default defineSegment({
     whenNot: [
       'Conveying critical errors (use Alert instead)',
       'Long-form status messages (use Alert)',
-      'Interactive filtering (use chip/toggle group)',
-      'Navigation labels (use tabs or links)',
+      'Interactive filtering (use Chip/ToggleGroup)',
+      'Navigation labels (use Tabs or links)',
     ],
     guidelines: [
       'Keep badge text under 20 characters',
@@ -75,7 +75,7 @@ export default defineSegment({
 
   relations: [
     { component: 'Alert', relationship: 'alternative', note: 'Use Alert for prominent, longer messages with actions' },
-    { component: 'Tag', relationship: 'sibling', note: 'Tag is interactive (clickable/filterable); Badge is display-only' },
+    { component: 'Chip', relationship: 'sibling', note: 'Chip is interactive (clickable/filterable); Badge is display-only' },
   ],
 
   contract: {

package/src/components/Badge/Badge.module.scss

@@ -31,22 +31,22 @@
 
 .success {
   background-color: var(--fui-color-success-bg, $fui-color-success-bg);
-  color: var(--fui-color-success, $fui-color-success);
+  color: var(--fui-color-success-text, $fui-color-success-text);
 }
 
 .warning {
   background-color: var(--fui-color-warning-bg, $fui-color-warning-bg);
-  color: var(--fui-color-warning, $fui-color-warning);
+  color: var(--fui-color-warning-text, $fui-color-warning-text);
 }
 
 .error {
   background-color: var(--fui-color-danger-bg, $fui-color-danger-bg);
-  color: var(--fui-color-danger, $fui-color-danger);
+  color: var(--fui-color-danger-text, $fui-color-danger-text);
 }
 
 .info {
   background-color: var(--fui-color-info-bg, $fui-color-info-bg);
-  color: var(--fui-color-info, $fui-color-info);
+  color: var(--fui-color-info-text, $fui-color-info-text);
 }
 
 .outline {

package/src/components/Badge/Badge.test.tsx

@@ -0,0 +1,58 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, userEvent, expectNoA11yViolations } from '../../test/utils';
+import { Badge } from './index';
+
+describe('Badge', () => {
+  it('renders with children', () => {
+    render(<Badge>New</Badge>);
+    expect(screen.getByText('New')).toBeInTheDocument();
+  });
+
+  it('applies variant classes', () => {
+    const { container } = render(<Badge variant="success">OK</Badge>);
+    const badge = container.firstChild as HTMLElement;
+    expect(badge).toHaveClass('success');
+  });
+
+  it('applies size classes', () => {
+    const { container } = render(<Badge size="sm">Small</Badge>);
+    const badge = container.firstChild as HTMLElement;
+    expect(badge).toHaveClass('sm');
+  });
+
+  it('renders dot with aria-hidden', () => {
+    const { container } = render(<Badge dot>Status</Badge>);
+    const dot = container.querySelector('.dot');
+    expect(dot).toBeInTheDocument();
+    expect(dot).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  it('renders icon with aria-hidden', () => {
+    const { container } = render(<Badge icon={<svg data-testid="icon" />}>Info</Badge>);
+    const iconWrapper = container.querySelector('.icon');
+    expect(iconWrapper).toHaveAttribute('aria-hidden', 'true');
+    expect(screen.getByTestId('icon')).toBeInTheDocument();
+  });
+
+  it('renders remove button with aria-label', async () => {
+    const user = userEvent.setup();
+    const onRemove = vi.fn();
+    render(<Badge onRemove={onRemove}>Tag</Badge>);
+    const removeBtn = screen.getByRole('button', { name: 'Remove Tag' });
+    expect(removeBtn).toBeInTheDocument();
+    await user.click(removeBtn);
+    expect(onRemove).toHaveBeenCalledOnce();
+  });
+
+  it('sets role="status" and aria-label for status variants', () => {
+    const { container } = render(<Badge variant="error">Failed</Badge>);
+    const badge = container.firstChild as HTMLElement;
+    expect(badge).toHaveAttribute('role', 'status');
+    expect(badge).toHaveAttribute('aria-label', 'error: Failed');
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(<Badge>Accessible</Badge>);
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/Badge/index.tsx

@@ -13,7 +13,7 @@ export interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
   onRemove?: () => void;
 }
 
-export const Badge = React.forwardRef<HTMLSpanElement, BadgeProps>(
+const BadgeRoot = React.forwardRef<HTMLSpanElement, BadgeProps>(
   function Badge(
     {
       children,
@@ -67,3 +67,7 @@ export const Badge = React.forwardRef<HTMLSpanElement, BadgeProps>(
     );
   }
 );
+
+export const Badge = Object.assign(BadgeRoot, {
+  Root: BadgeRoot,
+});

package/src/components/Box/Box.test.tsx

@@ -0,0 +1,43 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, expectNoA11yViolations } from '../../test/utils';
+import { Box } from './index';
+
+describe('Box', () => {
+  it('renders a div by default', () => {
+    render(<Box>Content</Box>);
+    const el = screen.getByText('Content');
+    expect(el.tagName).toBe('DIV');
+  });
+
+  it('renders as a different element via "as" prop', () => {
+    render(<Box as="section">Content</Box>);
+    const el = screen.getByText('Content');
+    expect(el.tagName).toBe('SECTION');
+  });
+
+  it('forwards className and ref', () => {
+    const ref = vi.fn();
+    const { container } = render(<Box ref={ref} className="custom">Content</Box>);
+    expect(ref).toHaveBeenCalled();
+    expect(container.firstChild).toHaveClass('custom');
+  });
+
+  it('applies padding and background classes', () => {
+    const { container } = render(<Box padding="lg" background="elevated">Content</Box>);
+    const el = container.firstChild as HTMLElement;
+    expect(el).toHaveClass('p-lg');
+    expect(el).toHaveClass('bg-elevated');
+  });
+
+  it('sets width/height as inline styles', () => {
+    const { container } = render(<Box width={300} height="50%">Content</Box>);
+    const el = container.firstChild as HTMLElement;
+    expect(el.style.width).toBe('300px');
+    expect(el.style.height).toBe('50%');
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(<Box>Accessible</Box>);
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/Box/index.tsx

@@ -65,7 +65,7 @@ function toCss(value: string | number): string {
   return typeof value === 'number' ? `${value}px` : value;
 }
 
-export const Box = React.forwardRef<HTMLElement, BoxProps>(
+const BoxRoot = React.forwardRef<HTMLElement, BoxProps>(
   function Box(
     {
       children,
@@ -143,3 +143,7 @@ export const Box = React.forwardRef<HTMLElement, BoxProps>(
     );
   }
 );
+
+export const Box = Object.assign(BoxRoot, {
+  Root: BoxRoot,
+});

package/src/components/Breadcrumbs/Breadcrumbs.test.tsx

@@ -0,0 +1,75 @@
+import { describe, it, expect } from 'vitest';
+import { render, screen, userEvent, expectNoA11yViolations } from '../../test/utils';
+import { Breadcrumbs } from './index';
+
+describe('Breadcrumbs', () => {
+  it('renders a nav landmark with aria-label "Breadcrumb"', () => {
+    render(
+      <Breadcrumbs>
+        <Breadcrumbs.Item href="/">Home</Breadcrumbs.Item>
+        <Breadcrumbs.Item current>Page</Breadcrumbs.Item>
+      </Breadcrumbs>
+    );
+    expect(screen.getByRole('navigation', { name: 'Breadcrumb' })).toBeInTheDocument();
+  });
+
+  it('marks current page with aria-current="page"', () => {
+    render(
+      <Breadcrumbs>
+        <Breadcrumbs.Item href="/">Home</Breadcrumbs.Item>
+        <Breadcrumbs.Item current>Current</Breadcrumbs.Item>
+      </Breadcrumbs>
+    );
+    expect(screen.getByText('Current').closest('[aria-current="page"]')).toBeInTheDocument();
+  });
+
+  it('renders separator between items', () => {
+    render(
+      <Breadcrumbs separator=">">
+        <Breadcrumbs.Item href="/">Home</Breadcrumbs.Item>
+        <Breadcrumbs.Item current>Page</Breadcrumbs.Item>
+      </Breadcrumbs>
+    );
+    expect(screen.getByText('>')).toBeInTheDocument();
+  });
+
+  it('renders items as links when href is provided', () => {
+    render(
+      <Breadcrumbs>
+        <Breadcrumbs.Item href="/about">About</Breadcrumbs.Item>
+        <Breadcrumbs.Item current>Contact</Breadcrumbs.Item>
+      </Breadcrumbs>
+    );
+    expect(screen.getByRole('link', { name: 'About' })).toHaveAttribute('href', '/about');
+  });
+
+  it('collapses middle items when maxItems is set', async () => {
+    const user = userEvent.setup();
+    render(
+      <Breadcrumbs maxItems={2}>
+        <Breadcrumbs.Item href="/">Home</Breadcrumbs.Item>
+        <Breadcrumbs.Item href="/a">A</Breadcrumbs.Item>
+        <Breadcrumbs.Item href="/b">B</Breadcrumbs.Item>
+        <Breadcrumbs.Item current>C</Breadcrumbs.Item>
+      </Breadcrumbs>
+    );
+    // Middle items should be collapsed with an ellipsis button
+    expect(screen.getByRole('button', { name: /show collapsed/i })).toBeInTheDocument();
+    expect(screen.queryByText('A')).not.toBeInTheDocument();
+
+    // Expand collapsed items
+    await user.click(screen.getByRole('button', { name: /show collapsed/i }));
+    expect(screen.getByText('A')).toBeInTheDocument();
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(
+      <Breadcrumbs>
+        <Breadcrumbs.Item href="/">Home</Breadcrumbs.Item>
+        <Breadcrumbs.Item href="/products">Products</Breadcrumbs.Item>
+        <Breadcrumbs.Item current>Widget</Breadcrumbs.Item>
+      </Breadcrumbs>
+    );
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/Button/Button.fragment.tsx

@@ -22,7 +22,7 @@ export default defineSegment({
     ],
     whenNot: [
       'Simple navigation (use Link)',
-      'Toggling state (use Switch or Checkbox)',
+      'Toggling state (use Toggle or Checkbox)',
       'Selecting from options (use Select or RadioGroup)',
     ],
     guidelines: [
@@ -57,20 +57,21 @@ export default defineSegment({
       default: 'md',
       description: 'Button size',
     },
-    disabled: {
-      type: 'boolean',
-      default: false,
-      description: 'Whether the button is disabled',
-    },
-    onClick: {
-      type: 'function',
-      description: 'Click handler',
-    },
-    type: {
+    as: {
       type: 'enum',
-      values: ['button', 'submit', 'reset'],
+      values: ['button', 'a'],
       default: 'button',
-      description: 'HTML button type attribute',
+      description: 'Render as a native button or anchor element',
+    },
+    icon: {
+      type: 'boolean',
+      default: 'false',
+      description: 'Render as icon-only button (square aspect ratio)',
+    },
+    fullWidth: {
+      type: 'boolean',
+      default: 'false',
+      description: 'Make button full width of container',
     },
   },
 
@@ -81,9 +82,9 @@ export default defineSegment({
       note: 'Use Link for navigation without action context',
     },
     {
-      component: 'IconButton',
-      relationship: 'alternative',
-      note: 'Use IconButton for icon-only actions',
+      component: 'Icon',
+      relationship: 'complementary',
+      note: 'Use Icon inside Button for icon-leading/trailing or icon-only actions',
     },
     {
       component: 'ButtonGroup',

package/src/components/Button/Button.test.tsx

@@ -0,0 +1,53 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, userEvent, expectNoA11yViolations } from '../../test/utils';
+import { Button } from './index';
+
+describe('Button', () => {
+  it('renders with children', () => {
+    render(<Button>Click me</Button>);
+    expect(screen.getByRole('button', { name: 'Click me' })).toBeInTheDocument();
+  });
+
+  it('calls onClick when clicked', async () => {
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+    render(<Button onClick={onClick}>Click</Button>);
+    await user.click(screen.getByRole('button'));
+    expect(onClick).toHaveBeenCalledOnce();
+  });
+
+  it('applies variant classes', () => {
+    const { rerender } = render(<Button variant="primary">Btn</Button>);
+    expect(screen.getByRole('button')).toHaveClass('primary');
+
+    rerender(<Button variant="danger">Btn</Button>);
+    expect(screen.getByRole('button')).toHaveClass('danger');
+  });
+
+  it('applies size classes', () => {
+    render(<Button size="lg">Btn</Button>);
+    expect(screen.getByRole('button')).toHaveClass('lg');
+  });
+
+  it('renders as an anchor when as="a"', () => {
+    render(<Button as="a" href="/test">Link</Button>);
+    const link = screen.getByRole('link', { name: 'Link' });
+    expect(link).toHaveAttribute('href', '/test');
+  });
+
+  it('supports disabled state', () => {
+    render(<Button disabled>Disabled</Button>);
+    expect(screen.getByRole('button')).toBeDisabled();
+  });
+
+  it('forwards ref', () => {
+    const ref = vi.fn();
+    render(<Button ref={ref}>Ref</Button>);
+    expect(ref).toHaveBeenCalled();
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(<Button>Accessible</Button>);
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/Button/index.tsx

@@ -30,7 +30,7 @@ export interface ButtonAsAnchorProps
 
 export type ButtonProps = ButtonAsButtonProps | ButtonAsAnchorProps;
 
-export const Button = React.forwardRef<
+const ButtonRoot = React.forwardRef<
   HTMLButtonElement | HTMLAnchorElement,
   ButtonProps
 >(function Button(props, ref) {
@@ -83,3 +83,7 @@ export const Button = React.forwardRef<
     </BaseButton>
   );
 });
+
+export const Button = Object.assign(ButtonRoot, {
+  Root: ButtonRoot,
+});

package/src/components/ButtonGroup/ButtonGroup.test.tsx

@@ -0,0 +1,44 @@
+import { describe, it, expect } from 'vitest';
+import { render, screen, expectNoA11yViolations } from '../../test/utils';
+import { ButtonGroup } from './index';
+
+describe('ButtonGroup', () => {
+  it('renders children buttons', () => {
+    render(
+      <ButtonGroup>
+        <button>Save</button>
+        <button>Cancel</button>
+      </ButtonGroup>
+    );
+    expect(screen.getByRole('button', { name: 'Save' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Cancel' })).toBeInTheDocument();
+  });
+
+  it('applies gap class', () => {
+    const { container } = render(
+      <ButtonGroup gap="md">
+        <button>A</button>
+      </ButtonGroup>
+    );
+    expect(container.firstElementChild).toHaveClass('gap-md');
+  });
+
+  it('applies wrap class when wrap is true', () => {
+    const { container } = render(
+      <ButtonGroup wrap>
+        <button>A</button>
+      </ButtonGroup>
+    );
+    expect(container.firstElementChild).toHaveClass('wrap');
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(
+      <ButtonGroup>
+        <button>OK</button>
+        <button>Cancel</button>
+      </ButtonGroup>
+    );
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/ButtonGroup/index.tsx

@@ -10,7 +10,7 @@ export interface ButtonGroupProps {
   className?: string;
 }
 
-export const ButtonGroup = React.forwardRef<HTMLDivElement, ButtonGroupProps>(
+const ButtonGroupRoot = React.forwardRef<HTMLDivElement, ButtonGroupProps>(
   function ButtonGroup(
     {
       children,
@@ -38,3 +38,7 @@ export const ButtonGroup = React.forwardRef<HTMLDivElement, ButtonGroupProps>(
     );
   }
 );
+
+export const ButtonGroup = Object.assign(ButtonGroupRoot, {
+  Root: ButtonGroupRoot,
+});

package/src/components/Card/Card.fragment.tsx

@@ -23,7 +23,7 @@ export default defineSegment({
     whenNot: [
       'Simple text content that does not need grouping',
       'Modal or dialog content (use Dialog component)',
-      'Navigation items (use NavItem or similar)',
+      'Navigation items (use List or Sidebar patterns)',
     ],
     guidelines: [
       'Use consistent card variants within the same context',
@@ -63,14 +63,14 @@ export default defineSegment({
 
   relations: [
     {
-      component: 'CardGrid',
+      component: 'Grid',
       relationship: 'parent',
-      note: 'Use CardGrid for responsive card layouts',
+      note: 'Use Grid + Card for responsive card layouts',
     },
     {
-      component: 'ListItem',
+      component: 'List',
       relationship: 'alternative',
-      note: 'Use ListItem for linear list layouts',
+      note: 'Use List for linear, text-first layouts',
     },
   ],
 

package/src/components/Card/Card.test.tsx

@@ -0,0 +1,71 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, userEvent, expectNoA11yViolations } from '../../test/utils';
+import { Card } from './index';
+
+describe('Card', () => {
+  it('renders as <article> by default', () => {
+    render(<Card>Content</Card>);
+    expect(screen.getByRole('article')).toBeInTheDocument();
+  });
+
+  it('renders as <button> when onClick is provided', () => {
+    render(<Card onClick={() => {}}>Click me</Card>);
+    expect(screen.getByRole('button')).toBeInTheDocument();
+    expect(screen.queryByRole('article')).not.toBeInTheDocument();
+  });
+
+  it('applies variant classes', () => {
+    const { rerender } = render(<Card variant="outlined">Content</Card>);
+    expect(screen.getByRole('article')).toHaveClass('outlined');
+
+    rerender(<Card variant="elevated">Content</Card>);
+    expect(screen.getByRole('article')).toHaveClass('elevated');
+  });
+
+  it('applies padding classes', () => {
+    render(<Card padding="lg">Content</Card>);
+    expect(screen.getByRole('article')).toHaveClass('paddingLg');
+  });
+
+  it('fires onClick callback', async () => {
+    const handleClick = vi.fn();
+    const user = userEvent.setup();
+    render(<Card onClick={handleClick}>Click me</Card>);
+    await user.click(screen.getByRole('button'));
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('renders compound sub-components', () => {
+    render(
+      <Card>
+        <Card.Header>Header</Card.Header>
+        <Card.Title>Title</Card.Title>
+        <Card.Description>Description</Card.Description>
+        <Card.Body>Body</Card.Body>
+        <Card.Footer>Footer</Card.Footer>
+      </Card>
+    );
+    expect(screen.getByText('Header')).toHaveClass('header');
+    expect(screen.getByText('Title').tagName).toBe('H3');
+    expect(screen.getByText('Description').tagName).toBe('P');
+    expect(screen.getByText('Body')).toHaveClass('body');
+    expect(screen.getByText('Footer')).toHaveClass('footer');
+  });
+
+  it('adds interactive class when onClick is provided', () => {
+    render(<Card onClick={() => {}}>Content</Card>);
+    expect(screen.getByRole('button')).toHaveClass('interactive');
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(
+      <Card>
+        <Card.Header>
+          <Card.Title>Card Title</Card.Title>
+        </Card.Header>
+        <Card.Body>Card body content</Card.Body>
+      </Card>
+    );
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/Chart/Chart.fragment.tsx

@@ -83,9 +83,17 @@ export default defineSegment({
       description: 'ChartConfig mapping data keys to labels and colors',
     },
     children: {
-      type: 'ReactElement',
+      type: 'element',
       description: 'A recharts chart component (LineChart, BarChart, etc.)',
     },
+    summary: {
+      type: 'string',
+      description: 'Non-visual summary announced to assistive technology users',
+    },
+    dataTable: {
+      type: 'node',
+      description: 'Optional accessible data table or textual fallback',
+    },
   },
 
   relations: [