@fragments-sdk/ui 0.13.0 → 0.15.1

package/src/components/Avatar/Avatar.fragment.tsx

@@ -1,202 +0,0 @@
-import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
-import { Avatar } from '.';
-import { Stack } from '../Stack';
-
-export default defineFragment({
-  component: Avatar,
-
-  meta: {
-    name: 'Avatar',
-    description: 'Visual representation of a user or entity',
-    category: 'display',
-    status: 'stable',
-    tags: ['user', 'profile', 'image', 'identity'],
-  },
-
-  usage: {
-    when: [
-      'Displaying user profile pictures',
-      'Showing team member lists',
-      'Representing entities in lists or cards',
-      'User identification in comments or messages',
-    ],
-    whenNot: [
-      'Decorative images (use Image)',
-      'Logo display (use Logo component)',
-      'Large profile headers (use custom layout)',
-    ],
-    guidelines: [
-      'Always provide alt text or name for accessibility',
-      'Use consistent sizes within the same context',
-      'Provide fallback initials when image may not load',
-      'Use Avatar.Group for multiple avatars in a row',
-    ],
-    accessibility: [
-      'Include meaningful alt text describing the user',
-      'Initials should be derived from name for screen readers',
-      'Decorative avatars should have empty alt',
-    ],
-  },
-
-  props: {
-    src: {
-      type: 'string',
-      description: 'Image source URL',
-    },
-    alt: {
-      type: 'string',
-      description: 'Alt text for the image',
-    },
-    name: {
-      type: 'string',
-      description: 'Full name - used to generate initials',
-    },
-    initials: {
-      type: 'string',
-      description: 'Fallback initials (1-2 characters)',
-    },
-    size: {
-      type: 'enum',
-      values: ['xs', 'sm', 'md', 'lg', 'xl'],
-      default: 'md',
-      description: 'Size variant',
-    },
-    customSize: {
-      type: 'string',
-      description: 'Custom avatar size (number in px or CSS size string like "2.25rem"), overrides size width/height',
-    },
-    shape: {
-      type: 'enum',
-      values: ['circle', 'square'],
-      default: 'circle',
-      description: 'Shape variant',
-    },
-    color: {
-      type: 'string',
-      description: 'Custom background color for fallback avatar',
-    },
-    imageStyle: {
-      type: 'string',
-      description: 'Inline style object applied to the underlying image element',
-    },
-  },
-
-  relations: [
-    {
-      component: 'Avatar',
-      relationship: 'parent',
-      note: 'Use Avatar.Group for stacked avatar displays',
-    },
-  ],
-
-  contract: {
-    propsSummary: [
-      'src: string - image URL',
-      'name: string - used for initials fallback',
-      'size: xs|sm|md|lg|xl (default: md)',
-      'customSize: number|string - custom size override',
-      'imageStyle: CSSProperties - inline image styling',
-      'shape: circle|square (default: circle)',
-    ],
-    scenarioTags: [
-      'profile.display',
-      'list.user',
-      'comment.author',
-    ],
-    a11yRules: [
-      'A11Y_IMG_ALT',
-    ],
-    bans: [],
-  },
-
-  variants: [
-    {
-      name: 'Default',
-      description: 'Avatar with image',
-      code: `import { Avatar } from '@/components/Avatar';
-
-<Avatar
-  src="https://i.pravatar.cc/150?u=jane"
-  alt="Jane Doe"
-  name="Jane Doe"
-/>`,
-      render: () => (
-        <Avatar
-          src="https://i.pravatar.cc/150?u=jane"
-          alt="Jane Doe"
-          name="Jane Doe"
-        />
-      ),
-    },
-    {
-      name: 'With Initials',
-      description: 'Fallback when no image is provided',
-      code: `import { Avatar } from '@/components/Avatar';
-
-<Avatar name="John Smith" />`,
-      render: () => <Avatar name="John Smith" />,
-    },
-    {
-      name: 'Sizes',
-      description: 'Available size options',
-      code: `import { Avatar } from '@/components/Avatar';
-import { Stack } from '@/components/Stack';
-
-<Stack direction="row" gap="sm" align="center" wrap>
-  <Avatar name="XS" size="xs" />
-  <Avatar name="SM" size="sm" />
-  <Avatar name="MD" size="md" />
-  <Avatar name="LG" size="lg" />
-  <Avatar name="XL" size="xl" />
-</Stack>`,
-      render: () => (
-        <Stack direction="row" gap="sm" align="center" wrap>
-          <Avatar name="XS" size="xs" />
-          <Avatar name="SM" size="sm" />
-          <Avatar name="MD" size="md" />
-          <Avatar name="LG" size="lg" />
-          <Avatar name="XL" size="xl" />
-        </Stack>
-      ),
-    },
-    {
-      name: 'Custom Size',
-      description: 'Set an exact avatar size',
-      code: `import { Avatar } from '@/components/Avatar';
-
-<Avatar name="Conan McNicholl" customSize={36} />`,
-      render: () => <Avatar name="Conan McNicholl" customSize={36} />,
-    },
-    {
-      name: 'Square Shape',
-      description: 'Square variant for app icons or brands',
-      code: `import { Avatar } from '@/components/Avatar';
-
-<Avatar name="App" shape="square" />`,
-      render: () => <Avatar name="App" shape="square" />,
-    },
-    {
-      name: 'Group',
-      description: 'Multiple avatars stacked together',
-      code: `import { Avatar } from '@/components/Avatar';
-
-<Avatar.Group max={3} size="md">
-  <Avatar name="Alice Johnson" />
-  <Avatar name="Bob Smith" />
-  <Avatar name="Carol Williams" />
-  <Avatar name="David Brown" />
-  <Avatar name="Eve Davis" />
-</Avatar.Group>`,
-      render: () => (
-        <Avatar.Group max={3} size="md">
-          <Avatar name="Alice Johnson" />
-          <Avatar name="Bob Smith" />
-          <Avatar name="Carol Williams" />
-          <Avatar name="David Brown" />
-          <Avatar name="Eve Davis" />
-        </Avatar.Group>
-      ),
-    },
-  ],
-});

package/src/components/Avatar/Avatar.test.tsx

@@ -1,58 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { render, screen, expectNoA11yViolations } from '../../test/utils';
-import { Avatar } from './index';
-
-describe('Avatar', () => {
-  it('renders an image when src is provided', () => {
-    render(<Avatar src="https://example.com/photo.jpg" alt="Jane Doe" />);
-    const img = screen.getByRole('img');
-    expect(img).toHaveAttribute('src', 'https://example.com/photo.jpg');
-    expect(img).toHaveAttribute('alt', 'Jane Doe');
-  });
-
-  it('renders initials from the name prop when no src', () => {
-    render(<Avatar name="John Smith" />);
-    expect(screen.getByText('JS')).toBeInTheDocument();
-  });
-
-  it('renders explicit initials prop over name-derived initials', () => {
-    render(<Avatar name="John Smith" initials="AB" />);
-    expect(screen.getByText('AB')).toBeInTheDocument();
-  });
-
-  it('renders Avatar.Group and limits visible avatars with max', () => {
-    render(
-      <Avatar.Group max={2}>
-        <Avatar name="Alice" />
-        <Avatar name="Bob" />
-        <Avatar name="Charlie" />
-        <Avatar name="Diana" />
-      </Avatar.Group>
-    );
-    // 2 visible + 1 overflow indicator
-    expect(screen.getByText('+2')).toBeInTheDocument();
-  });
-
-  it('applies a custom avatar size when customSize is provided', () => {
-    render(<Avatar name="Jane Doe" customSize={36} data-testid="avatar" />);
-    const avatar = screen.getByTestId('avatar');
-    expect(avatar).toHaveStyle({ width: '36px', height: '36px' });
-  });
-
-  it('applies imageStyle to the avatar image element', () => {
-    render(
-      <Avatar
-        src="https://example.com/photo.jpg"
-        alt="Jane Doe"
-        imageStyle={{ objectPosition: 'center 24%', transform: 'scale(1.4)' }}
-      />
-    );
-    const img = screen.getByRole('img');
-    expect(img).toHaveStyle({ objectPosition: 'center 24%', transform: 'scale(1.4)' });
-  });
-
-  it('has no accessibility violations', async () => {
-    const { container } = render(<Avatar name="Jane Doe" />);
-    await expectNoA11yViolations(container);
-  });
-});

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

@@ -1,197 +0,0 @@
-import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
-import { Badge } from '.';
-import { Stack } from '../Stack';
-
-export default defineFragment({
-  component: Badge,
-
-  meta: {
-    name: 'Badge',
-    description: 'Compact label for status, counts, or categorization. Draws attention to metadata without dominating the layout.',
-    category: 'display',
-    status: 'stable',
-    tags: ['status', 'label', 'tag', 'count', 'chip'],
-    since: '0.1.0',
-  },
-
-  usage: {
-    when: [
-      'Showing item status (active, pending, archived)',
-      'Displaying counts or quantities inline',
-      'Categorizing or tagging content',
-      'Highlighting new or updated items',
-    ],
-    whenNot: [
-      'Conveying critical errors (use Alert instead)',
-      'Long-form status messages (use Alert)',
-      'Interactive filtering (use Chip/ToggleGroup)',
-      'Navigation labels (use Tabs or links)',
-    ],
-    guidelines: [
-      'Keep badge text under 20 characters',
-      'Use dot variant for live status indicators',
-      'Pair success/error variants with meaningful labels, not just colors',
-      'Use onRemove for user-created tags only, not system-generated badges',
-    ],
-    accessibility: [
-      'Badge text must be meaningful without relying on color alone',
-      'Removable badges must have accessible dismiss button labels',
-      'Avoid using badges as the sole indicator of important state changes',
-    ],
-  },
-
-  props: {
-    children: {
-      type: 'node',
-      description: 'Badge label text',
-      required: true,
-    },
-    variant: {
-      type: 'enum',
-      description: 'Visual style indicating severity or category',
-      values: ['default', 'success', 'warning', 'error', 'info', 'outline'],
-      default: 'default',
-    },
-    size: {
-      type: 'enum',
-      description: 'Badge size',
-      values: ['sm', 'md'],
-      default: 'md',
-    },
-    dot: {
-      type: 'boolean',
-      description: 'Show a colored dot indicator before the label',
-      default: 'false',
-    },
-    icon: {
-      type: 'node',
-      description: 'Optional icon element before the text',
-    },
-    onRemove: {
-      type: 'function',
-      description: 'Makes the badge removable. Called when X is clicked.',
-    },
-  },
-
-  relations: [
-    { component: 'Alert', relationship: 'alternative', note: 'Use Alert for prominent, longer messages with actions' },
-    { component: 'Chip', relationship: 'sibling', note: 'Chip is interactive (clickable/filterable); Badge is display-only' },
-  ],
-
-  contract: {
-    propsSummary: [
-      'children: ReactNode - badge label (required)',
-      'variant: default|success|warning|error|info|outline - visual style',
-      'size: sm|md - badge size',
-      'dot: boolean - show status dot indicator',
-      'onRemove: () => void - makes badge removable',
-    ],
-    scenarioTags: [
-      'feedback.status',
-      'display.label',
-      'display.count',
-      'content.tag',
-    ],
-    a11yRules: ['A11Y_BADGE_CONTRAST', 'A11Y_BADGE_DISMISS', 'A11Y_TARGET_SIZE_MIN'],
-  },
-
-  variants: [
-    {
-      name: 'Default',
-      description: 'Neutral badge for general labels',
-      code: `import { Badge } from '@/components/Badge';
-
-<Badge>Default</Badge>`,
-      render: () => <Badge>Default</Badge>,
-    },
-    {
-      name: 'Status Variants',
-      description: 'All severity variants for different contexts',
-      code: `import { Badge } from '@/components/Badge';
-import { Stack } from '@/components/Stack';
-
-<Stack direction="row" gap="sm" wrap>
-  <Badge variant="default">Default</Badge>
-  <Badge variant="success">Active</Badge>
-  <Badge variant="warning">Pending</Badge>
-  <Badge variant="error">Failed</Badge>
-  <Badge variant="info">New</Badge>
-</Stack>`,
-      render: () => (
-        <Stack direction="row" gap="sm" wrap>
-          <Badge variant="default">Default</Badge>
-          <Badge variant="success">Active</Badge>
-          <Badge variant="warning">Pending</Badge>
-          <Badge variant="error">Failed</Badge>
-          <Badge variant="info">New</Badge>
-        </Stack>
-      ),
-    },
-    {
-      name: 'With Dot',
-      description: 'Live status indicators using dot prefix',
-      code: `import { Badge } from '@/components/Badge';
-import { Stack } from '@/components/Stack';
-
-<Stack direction="row" gap="sm" wrap>
-  <Badge variant="success" dot>Online</Badge>
-  <Badge variant="warning" dot>Away</Badge>
-  <Badge variant="error" dot>Offline</Badge>
-</Stack>`,
-      render: () => (
-        <Stack direction="row" gap="sm" wrap>
-          <Badge variant="success" dot>Online</Badge>
-          <Badge variant="warning" dot>Away</Badge>
-          <Badge variant="error" dot>Offline</Badge>
-        </Stack>
-      ),
-    },
-    {
-      name: 'Outline',
-      description: 'Minimal bordered badge for neutral emphasis',
-      code: `import { Badge } from '@/components/Badge';
-
-<Badge variant="outline">Outline</Badge>`,
-      render: () => <Badge variant="outline">Outline</Badge>,
-    },
-    {
-      name: 'Small Size',
-      description: 'Compact badges for dense UIs',
-      code: `import { Badge } from '@/components/Badge';
-import { Stack } from '@/components/Stack';
-
-<Stack direction="row" gap="sm" align="center" wrap>
-  <Badge size="sm" variant="info">v2.1</Badge>
-  <Badge size="sm" variant="success">Stable</Badge>
-  <Badge size="md" variant="info">Standard</Badge>
-</Stack>`,
-      render: () => (
-        <Stack direction="row" gap="sm" align="center" wrap>
-          <Badge size="sm" variant="info">v2.1</Badge>
-          <Badge size="sm" variant="success">Stable</Badge>
-          <Badge size="md" variant="info">Standard</Badge>
-        </Stack>
-      ),
-    },
-    {
-      name: 'Removable',
-      description: 'User-created tags that can be dismissed',
-      code: `import { Badge } from '@/components/Badge';
-import { Stack } from '@/components/Stack';
-
-<Stack direction="row" gap="sm" wrap>
-  <Badge variant="info" onRemove={() => {}}>React</Badge>
-  <Badge variant="info" onRemove={() => {}}>TypeScript</Badge>
-  <Badge variant="info" onRemove={() => {}}>CSS</Badge>
-</Stack>`,
-      render: () => (
-        <Stack direction="row" gap="sm" wrap>
-          <Badge variant="info" onRemove={() => {}}>React</Badge>
-          <Badge variant="info" onRemove={() => {}}>TypeScript</Badge>
-          <Badge variant="info" onRemove={() => {}}>CSS</Badge>
-        </Stack>
-      ),
-    },
-  ],
-});

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

@@ -1,58 +0,0 @@
-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/BentoGrid/BentoGrid.fragment.tsx

@@ -1,147 +0,0 @@
-import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
-import { BentoGrid } from '.';
-
-export default defineFragment({
-  component: BentoGrid,
-
-  meta: {
-    name: 'BentoGrid',
-    description: 'Asymmetric grid layout with responsive spans and built-in surface styling for bento-style feature sections',
-    category: 'layout',
-    status: 'stable',
-    tags: ['bento', 'grid', 'layout', 'responsive', 'feature-grid', 'asymmetric'],
-  },
-
-  usage: {
-    when: [
-      'Asymmetric feature grids with hero + supporting items',
-      'Dashboard overviews where cards have different visual weight',
-      'Marketing pages with mixed-size content blocks',
-      'Any layout where items need per-breakpoint column/row spans',
-    ],
-    whenNot: [
-      'Uniform grids where all items are the same size (use Grid)',
-      'Form layouts with labeled fields (use Grid)',
-      'Simple stacked content (use Stack)',
-    ],
-    guidelines: [
-      'Use colSpan/rowSpan with responsive objects for layouts that adapt across breakpoints',
-      'The hero item typically uses colSpan={2} rowSpan={2} at lg and above',
-      'Items include built-in surface styling — no need to wrap children in Card',
-      'Grid auto-collapses: 3→2 columns below lg, all→1 column below sm',
-    ],
-    accessibility: [
-      'Grid is purely visual — it does not affect reading order or semantics',
-      'Ensure logical source order matches visual order for screen readers',
-      'Hover effects are disabled when prefers-reduced-motion is set',
-      'Border thickness increases in prefers-contrast: more mode',
-    ],
-  },
-
-  props: {
-    children: {
-      type: 'node',
-      description: 'BentoGrid.Item children',
-    },
-    columns: {
-      type: 'enum',
-      values: ['2', '3', '4'],
-      default: '3',
-      description: 'Number of columns — auto-collapses responsively (3→2→1)',
-    },
-    gap: {
-      type: 'enum',
-      values: ['none', 'xs', 'sm', 'md', 'lg', 'xl'],
-      default: 'md',
-      description: 'Gap between grid items, mapped to spacing tokens',
-    },
-  },
-
-  relations: [
-    {
-      component: 'Grid',
-      relationship: 'alternative',
-      note: 'Use Grid for uniform layouts; BentoGrid for asymmetric spans with built-in surfaces',
-    },
-    {
-      component: 'Card',
-      relationship: 'sibling',
-      note: 'BentoGrid.Item has built-in surface styling similar to Card',
-    },
-  ],
-
-  contract: {
-    propsSummary: [
-      'columns: 2|3|4 (default: 3) — auto-collapses responsively',
-      'gap: none|xs|sm|md|lg|xl (default: md)',
-      'BentoGrid.Item colSpan: 1|2|3 | { base, sm, md, lg, xl }',
-      'BentoGrid.Item rowSpan: 1|2|3 | { base, sm, md, lg, xl }',
-    ],
-    scenarioTags: [
-      'layout.bento',
-      'layout.asymmetric',
-      'layout.responsive',
-      'pattern.feature-grid',
-      'pattern.dashboard',
-      'pattern.marketing',
-    ],
-  },
-
-  variants: [
-    {
-      name: 'Default',
-      description: 'Basic 3-column uniform bento grid',
-      render: () => (
-        <BentoGrid columns={3} gap="md">
-          <BentoGrid.Item>Item 1</BentoGrid.Item>
-          <BentoGrid.Item>Item 2</BentoGrid.Item>
-          <BentoGrid.Item>Item 3</BentoGrid.Item>
-          <BentoGrid.Item>Item 4</BentoGrid.Item>
-          <BentoGrid.Item>Item 5</BentoGrid.Item>
-          <BentoGrid.Item>Item 6</BentoGrid.Item>
-        </BentoGrid>
-      ),
-    },
-    {
-      name: 'Hero Layout',
-      description: '2×2 hero item with 4 supporting items in a 3-column grid',
-      render: () => (
-        <BentoGrid columns={3} gap="md">
-          <BentoGrid.Item colSpan={{ base: 1, lg: 2 }} rowSpan={{ base: 1, lg: 2 }}>
-            Hero content
-          </BentoGrid.Item>
-          <BentoGrid.Item>Item 2</BentoGrid.Item>
-          <BentoGrid.Item>Item 3</BentoGrid.Item>
-          <BentoGrid.Item>Item 4</BentoGrid.Item>
-          <BentoGrid.Item>Item 5</BentoGrid.Item>
-        </BentoGrid>
-      ),
-    },
-    {
-      name: 'Two Column',
-      description: '2-column bento with a wide item',
-      render: () => (
-        <BentoGrid columns={2} gap="md">
-          <BentoGrid.Item>Item 1</BentoGrid.Item>
-          <BentoGrid.Item>Item 2</BentoGrid.Item>
-          <BentoGrid.Item colSpan={2}>Wide item</BentoGrid.Item>
-          <BentoGrid.Item>Item 4</BentoGrid.Item>
-          <BentoGrid.Item>Item 5</BentoGrid.Item>
-        </BentoGrid>
-      ),
-    },
-    {
-      name: 'Full-Width Banner',
-      description: '3-column grid with a full-width item spanning all columns',
-      render: () => (
-        <BentoGrid columns={3} gap="md">
-          <BentoGrid.Item>Item 1</BentoGrid.Item>
-          <BentoGrid.Item>Item 2</BentoGrid.Item>
-          <BentoGrid.Item>Item 3</BentoGrid.Item>
-          <BentoGrid.Item colSpan={3}>Full-width banner</BentoGrid.Item>
-        </BentoGrid>
-      ),
-    },
-  ],
-});