@fragments-sdk/ui 0.13.0 → 0.15.1

package/src/components/Toast/Toast.fragment.tsx

@@ -1,223 +0,0 @@
-import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
-import { Toast, ToastProvider, useToast } from '.';
-
-// Demo component that triggers toasts
-function ToastDemo() {
-  const { success, error, warning, info } = useToast();
-
-  return (
-    <div style={{ display: 'flex', gap: 'var(--fui-space-1)', flexWrap: 'wrap' }}>
-      <button
-        onClick={() => success('Success!', 'Your changes have been saved.')}
-        style={{ padding: 'var(--fui-space-1) var(--fui-space-2)', borderRadius: 'var(--fui-radius-md)', border: '1px solid var(--fui-color-success)', background: 'var(--fui-color-success-bg)', color: 'var(--fui-color-success)', cursor: 'pointer' }}
-      >
-        Success Toast
-      </button>
-      <button
-        onClick={() => error('Error', 'Something went wrong. Please try again.')}
-        style={{ padding: 'var(--fui-space-1) var(--fui-space-2)', borderRadius: 'var(--fui-radius-md)', border: '1px solid var(--fui-color-danger)', background: 'var(--fui-color-danger-bg)', color: 'var(--fui-color-danger)', cursor: 'pointer' }}
-      >
-        Error Toast
-      </button>
-      <button
-        onClick={() => warning('Warning', 'This action cannot be undone.')}
-        style={{ padding: 'var(--fui-space-1) var(--fui-space-2)', borderRadius: 'var(--fui-radius-md)', border: '1px solid var(--fui-color-warning)', background: 'var(--fui-color-warning-bg)', color: 'var(--fui-color-warning)', cursor: 'pointer' }}
-      >
-        Warning Toast
-      </button>
-      <button
-        onClick={() => info('Info', 'New features are available.')}
-        style={{ padding: 'var(--fui-space-1) var(--fui-space-2)', borderRadius: 'var(--fui-radius-md)', border: '1px solid var(--fui-color-info)', background: 'var(--fui-color-info-bg)', color: 'var(--fui-color-info)', cursor: 'pointer' }}
-      >
-        Info Toast
-      </button>
-    </div>
-  );
-}
-
-// Wrapped demo with provider
-function ToastDemoWrapper() {
-  return (
-    <ToastProvider position="bottom-right" duration={5000}>
-      <ToastDemo />
-    </ToastProvider>
-  );
-}
-
-export default defineFragment({
-  component: Toast,
-
-  meta: {
-    name: 'Toast',
-    description: 'Brief, non-blocking notification messages',
-    category: 'feedback',
-    status: 'stable',
-    tags: ['notification', 'alert', 'message', 'feedback'],
-  },
-
-  usage: {
-    when: [
-      'Providing feedback after an action',
-      'Showing success/error status of operations',
-      'Non-critical information that doesn\'t require action',
-      'Temporary messages that auto-dismiss',
-    ],
-    whenNot: [
-      'Critical errors requiring user action (use Dialog)',
-      'Persistent information (use Alert)',
-      'Inline validation (use form error states)',
-      'System-wide announcements (use Banner)',
-    ],
-    guidelines: [
-      'Keep messages brief and actionable',
-      'Use appropriate variant for the message type',
-      'Auto-dismiss after reasonable duration (3-5s)',
-      'Allow manual dismissal for longer messages',
-      'Limit number of simultaneous toasts',
-    ],
-    accessibility: [
-      'Use role="alert" for important messages',
-      'Ensure sufficient display time for reading',
-      'Don\'t rely solely on color for meaning',
-      'Provide dismiss button with accessible label',
-    ],
-  },
-
-  props: {
-    title: {
-      type: 'string',
-      description: 'Toast title',
-    },
-    description: {
-      type: 'string',
-      description: 'Additional message content',
-    },
-    variant: {
-      type: 'enum',
-      values: ['default', 'success', 'error', 'warning', 'info'],
-      default: 'default',
-      description: 'Visual variant indicating message type',
-    },
-    duration: {
-      type: 'number',
-      default: 5000,
-      description: 'Auto-dismiss duration in ms (0 = no auto-dismiss)',
-    },
-    action: {
-      type: 'object',
-      description: 'Optional action button { label, onClick }',
-    },
-    onDismiss: {
-      type: 'function',
-      description: 'Callback when toast should be dismissed',
-    },
-    onPause: {
-      type: 'function',
-      description: 'Callback when auto-dismiss timer should pause',
-    },
-    onResume: {
-      type: 'function',
-      description: 'Callback when auto-dismiss timer should resume',
-    },
-  },
-
-  relations: [
-    {
-      component: 'Alert',
-      relationship: 'alternative',
-      note: 'Use Alert for persistent inline messages',
-    },
-    {
-      component: 'Dialog',
-      relationship: 'alternative',
-      note: 'Use Dialog for messages requiring user action',
-    },
-  ],
-
-  contract: {
-    propsSummary: [
-      'title: string - toast title',
-      'description: string - additional message',
-      'variant: default|success|error|warning|info',
-      'duration: number - ms before auto-dismiss',
-      'action: { label, onClick } - optional action',
-    ],
-    scenarioTags: [
-      'feedback.success',
-      'feedback.error',
-      'feedback.notification',
-    ],
-    a11yRules: [
-      'A11Y_ALERT_ROLE',
-      'A11Y_TARGET_SIZE_MIN',
-    ],
-    bans: [],
-  },
-
-  variants: [
-    {
-      name: 'Default',
-      description: 'Interactive toast demo - click buttons to trigger toasts',
-      render: () => <ToastDemoWrapper />,
-    },
-    {
-      name: 'Success',
-      description: 'Success message variant',
-      render: () => (
-        <Toast
-          title="Success!"
-          description="Your changes have been saved."
-          variant="success"
-        />
-      ),
-    },
-    {
-      name: 'Error',
-      description: 'Error message variant',
-      render: () => (
-        <Toast
-          title="Error"
-          description="Failed to save changes. Please try again."
-          variant="error"
-        />
-      ),
-    },
-    {
-      name: 'Warning',
-      description: 'Warning message variant',
-      render: () => (
-        <Toast
-          title="Warning"
-          description="This action cannot be undone."
-          variant="warning"
-        />
-      ),
-    },
-    {
-      name: 'Info',
-      description: 'Informational message variant',
-      render: () => (
-        <Toast
-          title="New Update"
-          description="Version 2.0 is now available."
-          variant="info"
-        />
-      ),
-    },
-    {
-      name: 'With Action',
-      description: 'Toast with an action button',
-      render: () => (
-        <Toast
-          title="File deleted"
-          description="The file has been moved to trash."
-          action={{
-            label: 'Undo',
-            onClick: () => console.log('Undo clicked'),
-          }}
-        />
-      ),
-    },
-  ],
-});

package/src/components/Toast/Toast.test.tsx

@@ -1,192 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { render, screen, userEvent, act, waitFor, expectNoA11yViolations } from '../../test/utils';
-import { Toast, useToast, ToastProvider } from './index';
-
-// Helper component to trigger toasts via the hook
-function ToastTrigger({
-  variant,
-  title = 'Test Toast',
-  description,
-  duration,
-  action,
-}: {
-  variant?: 'default' | 'success' | 'error' | 'warning' | 'info';
-  title?: string;
-  description?: string;
-  duration?: number;
-  action?: { label: string; onClick: () => void };
-}) {
-  const { toast } = useToast();
-  return (
-    <button
-      onClick={() => toast({ title, description, variant, duration, action })}
-    >
-      Show Toast
-    </button>
-  );
-}
-
-function renderWithProvider(
-  ui: React.ReactElement,
-  providerProps: Partial<React.ComponentProps<typeof ToastProvider>> = {}
-) {
-  return render(
-    <ToastProvider {...providerProps}>
-      {ui}
-    </ToastProvider>
-  );
-}
-
-describe('Toast', () => {
-  beforeEach(() => {
-    vi.useFakeTimers({ shouldAdvanceTime: true });
-  });
-
-  afterEach(() => {
-    vi.useRealTimers();
-  });
-
-  it('renders a toast when triggered via useToast hook', async () => {
-    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
-    renderWithProvider(<ToastTrigger title="Hello Toast" />);
-
-    await user.click(screen.getByRole('button', { name: /show toast/i }));
-
-    await waitFor(() => {
-      expect(screen.getByText('Hello Toast')).toBeInTheDocument();
-    });
-  });
-
-  it('renders title and description', async () => {
-    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
-    renderWithProvider(
-      <ToastTrigger title="Title" description="Description text" />
-    );
-
-    await user.click(screen.getByRole('button', { name: /show toast/i }));
-
-    await waitFor(() => {
-      expect(screen.getByText('Title')).toBeInTheDocument();
-      expect(screen.getByText('Description text')).toBeInTheDocument();
-    });
-  });
-
-  it('uses role="alert" for error variant', async () => {
-    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
-    renderWithProvider(<ToastTrigger variant="error" title="Error!" />);
-
-    await user.click(screen.getByRole('button', { name: /show toast/i }));
-
-    await waitFor(() => {
-      expect(screen.getByRole('alert')).toBeInTheDocument();
-    });
-  });
-
-  it('uses role="alert" for warning variant', async () => {
-    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
-    renderWithProvider(<ToastTrigger variant="warning" title="Warning!" />);
-
-    await user.click(screen.getByRole('button', { name: /show toast/i }));
-
-    await waitFor(() => {
-      expect(screen.getByRole('alert')).toBeInTheDocument();
-    });
-  });
-
-  it('uses role="status" for default/success/info variants', async () => {
-    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
-    renderWithProvider(<ToastTrigger variant="success" title="Success!" />);
-
-    await user.click(screen.getByRole('button', { name: /show toast/i }));
-
-    await waitFor(() => {
-      expect(screen.getByRole('status')).toBeInTheDocument();
-    });
-  });
-
-  it('dismiss button has aria-label', async () => {
-    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
-    renderWithProvider(<ToastTrigger title="Dismissable" />);
-
-    await user.click(screen.getByRole('button', { name: /show toast/i }));
-
-    await waitFor(() => {
-      expect(screen.getByRole('button', { name: /dismiss notification/i })).toBeInTheDocument();
-    });
-  });
-
-  it('dismisses when dismiss button is clicked', async () => {
-    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
-    renderWithProvider(<ToastTrigger title="To Dismiss" duration={0} />);
-
-    await user.click(screen.getByRole('button', { name: /show toast/i }));
-
-    await waitFor(() => {
-      expect(screen.getByText('To Dismiss')).toBeInTheDocument();
-    });
-
-    await user.click(screen.getByRole('button', { name: /dismiss notification/i }));
-
-    await waitFor(() => {
-      expect(screen.queryByText('To Dismiss')).not.toBeInTheDocument();
-    });
-  });
-
-  it('auto-dismisses after duration', async () => {
-    renderWithProvider(
-      <ToastTrigger title="Auto Dismiss" duration={3000} />,
-      { duration: 3000 }
-    );
-
-    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
-    await user.click(screen.getByRole('button', { name: /show toast/i }));
-
-    await waitFor(() => {
-      expect(screen.getByText('Auto Dismiss')).toBeInTheDocument();
-    });
-
-    await act(async () => {
-      vi.advanceTimersByTime(4000);
-    });
-
-    await waitFor(() => {
-      expect(screen.queryByText('Auto Dismiss')).not.toBeInTheDocument();
-    });
-  });
-
-  it('renders action button when action is provided', async () => {
-    const onClick = vi.fn();
-    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
-    renderWithProvider(
-      <ToastTrigger
-        title="With Action"
-        duration={0}
-        action={{ label: 'Undo', onClick }}
-      />
-    );
-
-    await user.click(screen.getByRole('button', { name: /show toast/i }));
-
-    await waitFor(() => {
-      expect(screen.getByRole('button', { name: /undo/i })).toBeInTheDocument();
-    });
-
-    await user.click(screen.getByRole('button', { name: /undo/i }));
-    expect(onClick).toHaveBeenCalled();
-  });
-
-  it('has no accessibility violations', async () => {
-    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
-    const { container } = renderWithProvider(
-      <ToastTrigger title="Accessible Toast" variant="info" />
-    );
-
-    await user.click(screen.getByRole('button', { name: /show toast/i }));
-
-    await waitFor(() => {
-      expect(screen.getByText('Accessible Toast')).toBeInTheDocument();
-    });
-
-    await expectNoA11yViolations(container);
-  });
-});

package/src/components/Toggle/Toggle.fragment.tsx

@@ -1,178 +0,0 @@
-import React, { useState } from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
-import { Switch } from '.';
-
-// Stateful wrapper for interactive demos
-function StatefulSwitch(props: React.ComponentProps<typeof Switch>) {
-  const [checked, setChecked] = useState(props.checked ?? false);
-  return <Switch {...props} checked={checked} onChange={setChecked} />;
-}
-
-export default defineFragment({
-  component: Switch,
-
-  meta: {
-    name: 'Switch',
-    description: 'Binary on/off switch for settings and preferences. Provides immediate visual feedback and is ideal for options that take effect instantly.',
-    category: 'forms',
-    status: 'stable',
-    tags: ['switch', 'toggle', 'boolean', 'settings', 'preference'],
-    since: '0.1.0',
-  },
-
-  usage: {
-    when: [
-      'Binary settings that take effect immediately (e.g., dark mode, notifications)',
-      'Enabling/disabling features in a settings panel',
-      'Options where the result is immediately visible',
-      'Mobile-friendly boolean inputs',
-    ],
-    whenNot: [
-      'Multiple options in a group (use checkbox group)',
-      'Selection requires form submission to take effect (use checkbox)',
-      'Yes/No questions in forms (use radio buttons)',
-      'Complex multi-state options (use select or radio)',
-    ],
-    guidelines: [
-      'Switch should always have a visible label explaining what it controls',
-      'The "on" state should be the positive/enabling action',
-      'Changes should take effect immediately - no save button needed',
-      'Include a description for switches whose effect isn\'t obvious from the label',
-      'Group related switches visually in settings panels',
-    ],
-    accessibility: [
-      'Uses role="switch" with aria-checked for proper semantics',
-      'Must have an accessible label (visible or aria-label)',
-      'Focus indicator must be clearly visible',
-      'State change must be announced by screen readers',
-    ],
-  },
-
-  props: {
-    checked: {
-      type: 'boolean',
-      description: 'Whether the switch is in the on state',
-      default: 'false',
-    },
-    onChange: {
-      type: 'function',
-      description: 'Callback with new checked state: (checked: boolean) => void',
-    },
-    onCheckedChange: {
-      type: 'function',
-      description: 'Alias for onChange (Radix convention): (checked: boolean) => void',
-    },
-    label: {
-      type: 'string',
-      description: 'Visible label text',
-    },
-    description: {
-      type: 'string',
-      description: 'Helper text shown below the label',
-    },
-    disabled: {
-      type: 'boolean',
-      description: 'Whether the switch is non-interactive',
-      default: 'false',
-    },
-    size: {
-      type: 'enum',
-      description: 'Switch track size',
-      values: ['sm', 'md'],
-      default: 'md',
-    },
-  },
-
-  relations: [
-    { component: 'Input', relationship: 'sibling', note: 'Input handles text/number entry; Switch handles boolean state' },
-    { component: 'Checkbox', relationship: 'alternative', note: 'Use Checkbox when change requires form submission' },
-  ],
-
-  contract: {
-    propsSummary: [
-      'checked: boolean - on/off state',
-      'onChange: (checked) => void - state change handler (or onCheckedChange)',
-      'label: string - visible label text',
-      'description: string - helper text below label',
-      'disabled: boolean - non-interactive state',
-      'size: sm|md - switch size',
-    ],
-    scenarioTags: [
-      'form.boolean',
-      'settings.switch',
-      'settings.preference',
-      'form.switch',
-    ],
-    a11yRules: ['A11Y_SWITCH_ROLE', 'A11Y_SWITCH_LABEL', 'A11Y_SWITCH_FOCUS', 'A11Y_TARGET_SIZE_MIN'],
-  },
-
-  variants: [
-    {
-      name: 'Default Off',
-      description: 'Switch in the off state',
-      render: () => <StatefulSwitch label="Email notifications" />,
-      args: { label: 'Email notifications' },
-    },
-    {
-      name: 'Checked',
-      description: 'Switch in the on state',
-      render: () => <StatefulSwitch checked label="Dark mode" />,
-      args: { checked: true, label: 'Dark mode' },
-    },
-    {
-      name: 'With Description',
-      description: 'Switch with explanatory helper text',
-      render: () => (
-        <StatefulSwitch
-          checked
-          label="Auto-save"
-          description="Automatically save changes as you type"
-        />
-      ),
-      args: { checked: true, label: 'Auto-save', description: 'Automatically save changes as you type' },
-    },
-    {
-      name: 'Small Size',
-      description: 'Compact switch for dense settings panels',
-      render: () => (
-        <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
-          <StatefulSwitch size="sm" checked label="Show line numbers" />
-          <StatefulSwitch size="sm" label="Word wrap" />
-          <StatefulSwitch size="sm" checked label="Minimap" />
-        </div>
-      ),
-    },
-    {
-      name: 'Disabled States',
-      description: 'Non-interactive switches showing both states',
-      render: () => (
-        <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
-          <Switch disabled label="Premium feature (upgrade required)" />
-          <Switch disabled checked label="System managed (read-only)" />
-        </div>
-      ),
-    },
-    {
-      name: 'Settings Panel',
-      description: 'Multiple switches in a realistic settings layout',
-      render: () => (
-        <div style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '320px' }}>
-          <StatefulSwitch
-            checked
-            label="Push notifications"
-            description="Receive push notifications on your device"
-          />
-          <StatefulSwitch
-            checked
-            label="Email digest"
-            description="Weekly summary of your activity"
-          />
-          <StatefulSwitch
-            label="Marketing emails"
-            description="Product updates and promotional offers"
-          />
-        </div>
-      ),
-    },
-  ],
-});

package/src/components/Toggle/Toggle.test.tsx

@@ -1,68 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { render, screen, userEvent, expectNoA11yViolations } from '../../test/utils';
-import { Switch } from './index';
-
-describe('Switch', () => {
-  it('renders a switch role', () => {
-    render(<Switch aria-label="Dark mode" />);
-    expect(screen.getByRole('switch')).toBeInTheDocument();
-  });
-
-  it('is unchecked by default', () => {
-    render(<Switch aria-label="Dark mode" />);
-    expect(screen.getByRole('switch')).not.toBeChecked();
-  });
-
-  it('renders as checked when checked prop is true', () => {
-    render(<Switch aria-label="Dark mode" checked onChange={() => {}} />);
-    expect(screen.getByRole('switch')).toBeChecked();
-  });
-
-  it('renders label text', () => {
-    render(<Switch label="Dark mode" />);
-    expect(screen.getByText('Dark mode')).toBeInTheDocument();
-  });
-
-  it('renders description text', () => {
-    render(<Switch label="Notifications" description="Enable push alerts" />);
-    expect(screen.getByText('Enable push alerts')).toBeInTheDocument();
-  });
-
-  it('disables the switch', () => {
-    render(<Switch aria-label="Dark mode" disabled />);
-    expect(screen.getByRole('switch')).toHaveAttribute('aria-disabled', 'true');
-  });
-
-  it('calls onChange with the new value on click', async () => {
-    const handleChange = vi.fn();
-    const user = userEvent.setup();
-    render(<Switch aria-label="Dark mode" onChange={handleChange} />);
-    await user.click(screen.getByRole('switch'));
-    expect(handleChange).toHaveBeenCalled();
-    expect(handleChange.mock.calls[0][0]).toBe(true);
-  });
-
-  it('calls onCheckedChange alias when toggled', async () => {
-    const handleChange = vi.fn();
-    const user = userEvent.setup();
-    render(<Switch aria-label="Dark mode" onCheckedChange={handleChange} />);
-    await user.click(screen.getByRole('switch'));
-    expect(handleChange).toHaveBeenCalled();
-    expect(handleChange.mock.calls[0][0]).toBe(true);
-  });
-
-  it('prefers onChange over onCheckedChange when both provided', async () => {
-    const onChange = vi.fn();
-    const onCheckedChange = vi.fn();
-    const user = userEvent.setup();
-    render(<Switch aria-label="Test" onChange={onChange} onCheckedChange={onCheckedChange} />);
-    await user.click(screen.getByRole('switch'));
-    expect(onChange).toHaveBeenCalled();
-    expect(onCheckedChange).not.toHaveBeenCalled();
-  });
-
-  it('has no accessibility violations', async () => {
-    const { container } = render(<Switch aria-label="Accessible switch" />);
-    await expectNoA11yViolations(container);
-  });
-});