@fragments-sdk/ui 0.13.0 → 0.15.1

package/src/components/Command/Command.fragment.tsx

@@ -1,237 +0,0 @@
-import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
-import { Command } from '.';
-import { Dialog } from '../Dialog';
-import { Button } from '../Button';
-
-export default defineFragment({
-  component: Command,
-
-  meta: {
-    name: 'Command',
-    description: 'A searchable command palette for quick actions. Combines an input with a filterable, keyboard-navigable list of actions.',
-    category: 'navigation',
-    status: 'stable',
-    tags: ['command', 'palette', 'search', 'spotlight', 'quick-actions', 'cmdk'],
-    since: '0.8.2',
-  },
-
-  usage: {
-    when: [
-      'Quick-access command palettes (Ctrl+K)',
-      'Searchable action menus',
-      'Inline command lists with filtering',
-      'Application-wide search interfaces',
-    ],
-    whenNot: [
-      'Simple dropdown menus (use Menu)',
-      'Form field selection (use Select or Combobox)',
-      'Static navigation (use Sidebar or Tabs)',
-      'Search with complex result types (build custom)',
-    ],
-    guidelines: [
-      'Compose inside Dialog for modal command palette usage',
-      'Use Command.Group to organize items by category',
-      'Provide Command.Empty for no-results feedback',
-      'Use keywords prop for items that should match on aliases',
-      'Keep item labels short and action-oriented',
-    ],
-    accessibility: [
-      'Uses combobox + listbox ARIA pattern',
-      'Keyboard navigation with ArrowUp/ArrowDown, Enter to select',
-      'Home/End jump to first/last item',
-      'aria-activedescendant tracks focused item',
-    ],
-  },
-
-  props: {
-    children: {
-      type: 'node',
-      description: 'Command.Input, Command.List, and other sub-components',
-      required: true,
-    },
-    search: {
-      type: 'string',
-      description: 'Controlled search value',
-    },
-    defaultSearch: {
-      type: 'string',
-      description: 'Default search value (uncontrolled)',
-      default: "''",
-    },
-    onSearchChange: {
-      type: 'function',
-      description: 'Called when search input changes',
-    },
-    filter: {
-      type: 'function',
-      description: 'Custom filter function. Return 0 to hide, >0 to show.',
-    },
-    loop: {
-      type: 'boolean',
-      description: 'Whether to loop keyboard navigation',
-      default: 'true',
-    },
-  },
-
-  relations: [
-    { component: 'Dialog', relationship: 'sibling', note: 'Compose inside Dialog for modal command palette' },
-    { component: 'Listbox', relationship: 'sibling', note: 'Command uses Listbox-like keyboard navigation internally' },
-    { component: 'Combobox', relationship: 'alternative', note: 'Use Combobox for form field selection with search' },
-  ],
-
-  contract: {
-    propsSummary: [
-      'search: string - controlled search value',
-      'onSearchChange: (search) => void - search change handler',
-      'filter: (value, search, keywords?) => number - custom filter',
-      'loop: boolean - loop keyboard navigation (default: true)',
-      'Command.Item value: string - filter match value',
-      'Command.Item keywords: string[] - extra filter terms',
-      'Command.Item onItemSelect: () => void - selection handler',
-    ],
-    subComponents: [
-      {
-        name: 'Command.Input',
-        props: ['placeholder: string', 'className: string'],
-      },
-      {
-        name: 'Command.List',
-        props: ['children: ReactNode'],
-      },
-      {
-        name: 'Command.Item',
-        props: [
-          'value: string - filter value',
-          'keywords: string[] - extra keywords',
-          'disabled: boolean',
-          'onItemSelect: () => void',
-        ],
-      },
-      {
-        name: 'Command.Group',
-        props: ['heading: string - group label', 'children: ReactNode'],
-      },
-      {
-        name: 'Command.Empty',
-        props: ['children: ReactNode - empty state message'],
-      },
-      {
-        name: 'Command.Separator',
-        props: [],
-      },
-    ],
-    scenarioTags: [
-      'navigation.command',
-      'search.palette',
-      'action.quick',
-    ],
-    a11yRules: ['A11Y_COMBOBOX_ROLE', 'A11Y_LISTBOX_ROLE', 'A11Y_ACTIVE_DESCENDANT'],
-  },
-
-  ai: {
-    compositionPattern: 'compound',
-    subComponents: ['Input', 'List', 'Item', 'Group', 'Empty', 'Separator'],
-    requiredChildren: ['Input', 'List'],
-    commonPatterns: [
-      '<Dialog><Dialog.Trigger><Button>Open Palette</Button></Dialog.Trigger><Dialog.Content size="sm"><Command><Command.Input placeholder="Search..." /><Command.List><Command.Group heading="Actions"><Command.Item onItemSelect={() => {}}>Action 1</Command.Item></Command.Group><Command.Empty>No results.</Command.Empty></Command.List></Command></Dialog.Content></Dialog>',
-    ],
-  },
-
-  variants: [
-    {
-      name: 'Default',
-      description: 'Inline command list with search',
-      render: () => (
-        <div style={{ maxWidth: '400px', width: '100%' }}>
-          <Command>
-            <Command.Input placeholder="Type a command..." />
-            <Command.List>
-              <Command.Item onItemSelect={() => {}}>Open File</Command.Item>
-              <Command.Item onItemSelect={() => {}}>Save Document</Command.Item>
-              <Command.Item onItemSelect={() => {}}>Print</Command.Item>
-              <Command.Empty>No results found.</Command.Empty>
-            </Command.List>
-          </Command>
-        </div>
-      ),
-    },
-    {
-      name: 'Dialog Command Palette',
-      description: 'Command palette inside a Dialog',
-      render: () => (
-        <Dialog>
-          <Dialog.Trigger asChild>
-            <Button variant="secondary">Open Command Palette</Button>
-          </Dialog.Trigger>
-          <Dialog.Content size="sm">
-            <Command>
-              <Command.Input placeholder="Search commands..." />
-              <Command.List>
-                <Command.Group heading="Actions">
-                  <Command.Item onItemSelect={() => {}}>New File</Command.Item>
-                  <Command.Item onItemSelect={() => {}}>Open Recent</Command.Item>
-                </Command.Group>
-                <Command.Separator />
-                <Command.Group heading="Settings">
-                  <Command.Item onItemSelect={() => {}}>Preferences</Command.Item>
-                  <Command.Item onItemSelect={() => {}}>Keyboard Shortcuts</Command.Item>
-                </Command.Group>
-                <Command.Empty>No results found.</Command.Empty>
-              </Command.List>
-            </Command>
-          </Dialog.Content>
-        </Dialog>
-      ),
-    },
-    {
-      name: 'With Groups',
-      description: 'Organized by category groups',
-      render: () => (
-        <div style={{ maxWidth: '400px', width: '100%' }}>
-          <Command>
-            <Command.Input placeholder="Search..." />
-            <Command.List>
-              <Command.Group heading="Suggestions">
-                <Command.Item onItemSelect={() => {}}>Calendar</Command.Item>
-                <Command.Item onItemSelect={() => {}}>Calculator</Command.Item>
-              </Command.Group>
-              <Command.Separator />
-              <Command.Group heading="Settings">
-                <Command.Item onItemSelect={() => {}}>Profile</Command.Item>
-                <Command.Item onItemSelect={() => {}}>Billing</Command.Item>
-                <Command.Item disabled onItemSelect={() => {}}>
-                  Team (coming soon)
-                </Command.Item>
-              </Command.Group>
-              <Command.Empty>No results found.</Command.Empty>
-            </Command.List>
-          </Command>
-        </div>
-      ),
-    },
-    {
-      name: 'With Icons',
-      description: 'Items with leading icons',
-      render: () => (
-        <div style={{ maxWidth: '400px', width: '100%' }}>
-          <Command>
-            <Command.Input placeholder="What do you need?" />
-            <Command.List>
-              <Command.Item onItemSelect={() => {}}>
-                <span style={{ marginRight: '0.5rem', fontSize: '1rem' }}>+</span> New Document
-              </Command.Item>
-              <Command.Item onItemSelect={() => {}}>
-                <span style={{ marginRight: '0.5rem', fontSize: '1rem' }}>{'>'}</span> Open Folder
-              </Command.Item>
-              <Command.Item onItemSelect={() => {}}>
-                <span style={{ marginRight: '0.5rem', fontSize: '1rem' }}>?</span> Search
-              </Command.Item>
-              <Command.Empty>No results found.</Command.Empty>
-            </Command.List>
-          </Command>
-        </div>
-      ),
-    },
-  ],
-});

package/src/components/Command/Command.test.tsx

@@ -1,456 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { render, screen, userEvent, waitFor, expectNoA11yViolations } from '../../test/utils';
-import { Command } from './index';
-import { Dialog } from '../Dialog';
-
-function renderCommand(props: Partial<React.ComponentProps<typeof Command>> = {}) {
-  return render(
-    <Command {...props}>
-      <Command.Input placeholder="Type a command..." />
-      <Command.List>
-        <Command.Item onItemSelect={() => {}}>Open File</Command.Item>
-        <Command.Item onItemSelect={() => {}}>Save Document</Command.Item>
-        <Command.Item onItemSelect={() => {}}>Print</Command.Item>
-        <Command.Empty>No results found.</Command.Empty>
-      </Command.List>
-    </Command>
-  );
-}
-
-describe('Command', () => {
-  it('renders input and items', () => {
-    renderCommand();
-
-    expect(screen.getByPlaceholderText('Type a command...')).toBeInTheDocument();
-    expect(screen.getByText('Open File')).toBeInTheDocument();
-    expect(screen.getByText('Save Document')).toBeInTheDocument();
-    expect(screen.getByText('Print')).toBeInTheDocument();
-  });
-
-  it('typing filters items', async () => {
-    const user = userEvent.setup();
-    renderCommand();
-
-    const input = screen.getByPlaceholderText('Type a command...');
-    await user.type(input, 'open');
-
-    await waitFor(() => {
-      expect(screen.getByText('Open File')).toBeVisible();
-      expect(screen.getByText('Save Document')).not.toBeVisible();
-      expect(screen.getByText('Print')).not.toBeVisible();
-    });
-  });
-
-  it('filtered-out items are hidden', async () => {
-    const user = userEvent.setup();
-    renderCommand();
-
-    const input = screen.getByPlaceholderText('Type a command...');
-    await user.type(input, 'save');
-
-    await waitFor(() => {
-      expect(screen.getByText('Save Document')).toBeVisible();
-      expect(screen.getByText('Open File')).not.toBeVisible();
-    });
-  });
-
-  it('empty state shows when no matches', async () => {
-    const user = userEvent.setup();
-    renderCommand();
-
-    const input = screen.getByPlaceholderText('Type a command...');
-    await user.type(input, 'zzzzz');
-
-    await waitFor(() => {
-      expect(screen.getByText('No results found.')).toBeInTheDocument();
-    });
-  });
-
-  it('groups auto-hide when all children filtered', async () => {
-    const user = userEvent.setup();
-    render(
-      <Command>
-        <Command.Input placeholder="Search..." />
-        <Command.List>
-          <Command.Group heading="Files">
-            <Command.Item onItemSelect={() => {}}>Open File</Command.Item>
-          </Command.Group>
-          <Command.Group heading="Edit">
-            <Command.Item onItemSelect={() => {}}>Copy</Command.Item>
-            <Command.Item onItemSelect={() => {}}>Paste</Command.Item>
-          </Command.Group>
-          <Command.Empty>No results.</Command.Empty>
-        </Command.List>
-      </Command>
-    );
-
-    const input = screen.getByPlaceholderText('Search...');
-    await user.type(input, 'copy');
-
-    await waitFor(() => {
-      // "Files" group should be hidden since "Open File" doesn't match "copy"
-      const filesGroup = screen.getByText('Files').closest('[role="group"]');
-      expect(filesGroup).toHaveStyle({ display: 'none' });
-
-      // "Edit" group should be visible since "Copy" matches
-      const editGroup = screen.getByText('Edit').closest('[role="group"]');
-      expect(editGroup).not.toHaveStyle({ display: 'none' });
-    });
-  });
-
-  it('custom filter function works', async () => {
-    const user = userEvent.setup();
-    const customFilter = vi.fn((value: string, search: string) => {
-      // Only match exact start
-      return value.toLowerCase().startsWith(search.toLowerCase()) ? 1 : 0;
-    });
-
-    render(
-      <Command filter={customFilter}>
-        <Command.Input placeholder="Search..." />
-        <Command.List>
-          <Command.Item onItemSelect={() => {}}>Apple</Command.Item>
-          <Command.Item onItemSelect={() => {}}>Banana</Command.Item>
-          <Command.Item onItemSelect={() => {}}>Apricot</Command.Item>
-          <Command.Empty>No results.</Command.Empty>
-        </Command.List>
-      </Command>
-    );
-
-    const input = screen.getByPlaceholderText('Search...');
-    await user.type(input, 'ap');
-
-    await waitFor(() => {
-      expect(screen.getByText('Apple')).toBeVisible();
-      expect(screen.getByText('Apricot')).toBeVisible();
-      expect(screen.getByText('Banana')).not.toBeVisible();
-    });
-  });
-
-  it('ArrowDown/ArrowUp navigates items', async () => {
-    const user = userEvent.setup();
-    renderCommand();
-
-    const input = screen.getByPlaceholderText('Type a command...');
-    input.focus();
-
-    await user.keyboard('{ArrowDown}');
-
-    await waitFor(() => {
-      const activeItem = document.querySelector('[data-active="true"]');
-      expect(activeItem).toBeTruthy();
-      expect(activeItem?.textContent).toBe('Open File');
-    });
-
-    await user.keyboard('{ArrowDown}');
-
-    await waitFor(() => {
-      const activeItem = document.querySelector('[data-active="true"]');
-      expect(activeItem?.textContent).toBe('Save Document');
-    });
-
-    await user.keyboard('{ArrowUp}');
-
-    await waitFor(() => {
-      const activeItem = document.querySelector('[data-active="true"]');
-      expect(activeItem?.textContent).toBe('Open File');
-    });
-  });
-
-  it('Enter selects active item (calls onItemSelect)', async () => {
-    const user = userEvent.setup();
-    const onItemSelect = vi.fn();
-
-    render(
-      <Command>
-        <Command.Input placeholder="Search..." />
-        <Command.List>
-          <Command.Item onItemSelect={onItemSelect}>First</Command.Item>
-          <Command.Item onItemSelect={() => {}}>Second</Command.Item>
-        </Command.List>
-      </Command>
-    );
-
-    const input = screen.getByPlaceholderText('Search...');
-    input.focus();
-
-    await user.keyboard('{ArrowDown}');
-    await user.keyboard('{Enter}');
-
-    expect(onItemSelect).toHaveBeenCalledTimes(1);
-  });
-
-  it('click selects item', async () => {
-    const user = userEvent.setup();
-    const onItemSelect = vi.fn();
-
-    render(
-      <Command>
-        <Command.Input placeholder="Search..." />
-        <Command.List>
-          <Command.Item onItemSelect={onItemSelect}>Click Me</Command.Item>
-        </Command.List>
-      </Command>
-    );
-
-    await user.click(screen.getByText('Click Me'));
-    expect(onItemSelect).toHaveBeenCalledTimes(1);
-  });
-
-  it('disabled items are skipped in keyboard nav', async () => {
-    const user = userEvent.setup();
-    render(
-      <Command>
-        <Command.Input placeholder="Search..." />
-        <Command.List>
-          <Command.Item onItemSelect={() => {}}>First</Command.Item>
-          <Command.Item disabled onItemSelect={() => {}}>Disabled</Command.Item>
-          <Command.Item onItemSelect={() => {}}>Third</Command.Item>
-        </Command.List>
-      </Command>
-    );
-
-    const input = screen.getByPlaceholderText('Search...');
-    input.focus();
-
-    await user.keyboard('{ArrowDown}');
-    await waitFor(() => {
-      const activeItem = document.querySelector('[data-active="true"]');
-      expect(activeItem?.textContent).toBe('First');
-    });
-
-    await user.keyboard('{ArrowDown}');
-    await waitFor(() => {
-      const activeItem = document.querySelector('[data-active="true"]');
-      // Skips "Disabled", goes to "Third"
-      expect(activeItem?.textContent).toBe('Third');
-    });
-  });
-
-  it('Home/End jump to first/last', async () => {
-    const user = userEvent.setup();
-    renderCommand();
-
-    const input = screen.getByPlaceholderText('Type a command...');
-    input.focus();
-
-    await user.keyboard('{End}');
-    await waitFor(() => {
-      const activeItem = document.querySelector('[data-active="true"]');
-      expect(activeItem?.textContent).toBe('Print');
-    });
-
-    await user.keyboard('{Home}');
-    await waitFor(() => {
-      const activeItem = document.querySelector('[data-active="true"]');
-      expect(activeItem?.textContent).toBe('Open File');
-    });
-  });
-
-  it('loop={false} stops at boundaries', async () => {
-    const user = userEvent.setup();
-    render(
-      <Command loop={false}>
-        <Command.Input placeholder="Search..." />
-        <Command.List>
-          <Command.Item onItemSelect={() => {}}>First</Command.Item>
-          <Command.Item onItemSelect={() => {}}>Last</Command.Item>
-        </Command.List>
-      </Command>
-    );
-
-    const input = screen.getByPlaceholderText('Search...');
-    input.focus();
-
-    // Navigate to last
-    await user.keyboard('{ArrowDown}');
-    await user.keyboard('{ArrowDown}');
-
-    await waitFor(() => {
-      const activeItem = document.querySelector('[data-active="true"]');
-      expect(activeItem?.textContent).toBe('Last');
-    });
-
-    // Try to go past last — should stay on Last
-    await user.keyboard('{ArrowDown}');
-    await waitFor(() => {
-      const activeItem = document.querySelector('[data-active="true"]');
-      expect(activeItem?.textContent).toBe('Last');
-    });
-  });
-
-  it('search value controlled mode', async () => {
-    const user = userEvent.setup();
-    const onSearchChange = vi.fn();
-
-    render(
-      <Command search="open" onSearchChange={onSearchChange}>
-        <Command.Input placeholder="Search..." />
-        <Command.List>
-          <Command.Item onItemSelect={() => {}}>Open File</Command.Item>
-          <Command.Item onItemSelect={() => {}}>Save</Command.Item>
-          <Command.Empty>No results.</Command.Empty>
-        </Command.List>
-      </Command>
-    );
-
-    await waitFor(() => {
-      expect(screen.getByText('Open File')).toBeVisible();
-      expect(screen.getByText('Save')).not.toBeVisible();
-    });
-
-    // Type in input triggers onSearchChange
-    const input = screen.getByPlaceholderText('Search...');
-    await user.type(input, 'x');
-    expect(onSearchChange).toHaveBeenCalled();
-  });
-
-  it('items with keywords match on keywords', async () => {
-    const user = userEvent.setup();
-    render(
-      <Command>
-        <Command.Input placeholder="Search..." />
-        <Command.List>
-          <Command.Item keywords={['shortcut', 'hotkey']} onItemSelect={() => {}}>
-            Keyboard Settings
-          </Command.Item>
-          <Command.Item onItemSelect={() => {}}>Display Settings</Command.Item>
-          <Command.Empty>No results.</Command.Empty>
-        </Command.List>
-      </Command>
-    );
-
-    const input = screen.getByPlaceholderText('Search...');
-    await user.type(input, 'hotkey');
-
-    await waitFor(() => {
-      expect(screen.getByText('Keyboard Settings')).toBeVisible();
-      expect(screen.getByText('Display Settings')).not.toBeVisible();
-    });
-  });
-
-  it('compose inside Dialog (command palette usage)', async () => {
-    const user = userEvent.setup();
-    render(
-      <Dialog>
-        <Dialog.Trigger>Open Palette</Dialog.Trigger>
-        <Dialog.Content size="sm">
-          <Command>
-            <Command.Input placeholder="Search commands..." />
-            <Command.List>
-              <Command.Item onItemSelect={() => {}}>New File</Command.Item>
-              <Command.Item onItemSelect={() => {}}>Open Recent</Command.Item>
-            </Command.List>
-          </Command>
-        </Dialog.Content>
-      </Dialog>
-    );
-
-    await user.click(screen.getByRole('button', { name: /open palette/i }));
-
-    await waitFor(() => {
-      expect(screen.getByPlaceholderText('Search commands...')).toBeInTheDocument();
-      expect(screen.getByText('New File')).toBeInTheDocument();
-      expect(screen.getByText('Open Recent')).toBeInTheDocument();
-    });
-  });
-
-  it('uses unique list ids for multiple command instances', () => {
-    render(
-      <>
-        <Command>
-          <Command.Input placeholder="First search" />
-          <Command.List>
-            <Command.Item onItemSelect={() => {}}>One</Command.Item>
-          </Command.List>
-        </Command>
-        <Command>
-          <Command.Input placeholder="Second search" />
-          <Command.List>
-            <Command.Item onItemSelect={() => {}}>Two</Command.Item>
-          </Command.List>
-        </Command>
-      </>
-    );
-
-    const inputs = [
-      screen.getByPlaceholderText('First search'),
-      screen.getByPlaceholderText('Second search'),
-    ];
-    const listIds = inputs.map((input) => input.getAttribute('aria-controls'));
-
-    expect(listIds[0]).toBeTruthy();
-    expect(listIds[1]).toBeTruthy();
-    expect(listIds[0]).not.toBe(listIds[1]);
-    expect(document.getElementById(listIds[0]!)).toBeInTheDocument();
-    expect(document.getElementById(listIds[1]!)).toBeInTheDocument();
-  });
-
-  it('filters rich-label items using extracted text content', async () => {
-    const user = userEvent.setup();
-    render(
-      <Command>
-        <Command.Input placeholder="Search..." />
-        <Command.List>
-          <Command.Item onItemSelect={() => {}}>
-            <span>Open</span> File
-          </Command.Item>
-          <Command.Item onItemSelect={() => {}}>Save</Command.Item>
-        </Command.List>
-      </Command>
-    );
-
-    await user.type(screen.getByPlaceholderText('Search...'), 'open');
-
-    await waitFor(() => {
-      expect(screen.getByText('Save')).not.toBeVisible();
-      expect(screen.getByText('Open')).toBeVisible();
-    });
-  });
-
-  it('composes item and group html props without dropping handlers/styles', async () => {
-    const user = userEvent.setup();
-    const itemClick = vi.fn();
-    const itemKeyDown = vi.fn();
-    const itemMouseEnter = vi.fn();
-
-    render(
-      <Command>
-        <Command.Input placeholder="Search..." />
-        <Command.List>
-          <Command.Group heading="Files" data-testid="group" style={{ opacity: 0.5 }}>
-            <Command.Item
-              onItemSelect={() => {}}
-              data-testid="item"
-              onClick={itemClick}
-              onKeyDown={itemKeyDown}
-              onMouseEnter={itemMouseEnter}
-              tabIndex={0}
-              style={{ color: 'rgb(255, 0, 0)' }}
-            >
-              Open File
-            </Command.Item>
-          </Command.Group>
-        </Command.List>
-      </Command>
-    );
-
-    const item = screen.getByTestId('item');
-    await user.hover(item);
-    await user.click(item);
-    item.focus();
-    await user.keyboard('{Enter}');
-
-    expect(itemMouseEnter).toHaveBeenCalled();
-    expect(itemClick).toHaveBeenCalled();
-    expect(itemKeyDown).toHaveBeenCalled();
-    expect(item).toHaveStyle({ color: 'rgb(255, 0, 0)' });
-    expect(screen.getByTestId('group')).toHaveStyle({ opacity: '0.5' });
-  });
-
-  it('has no accessibility violations', async () => {
-    const { container } = renderCommand();
-
-    await expectNoA11yViolations(container);
-  });
-});