@fragments-sdk/ui 0.14.0 → 0.15.1

package/src/components/Combobox/Combobox.fragment.tsx

@@ -1,332 +0,0 @@
-import React, { useState } from 'react';
-import { defineFragment } from '@fragments-sdk/core';
-import { Combobox, type ComboboxMultipleProps, type ComboboxSingleProps } from '.';
-
-// Stateful wrapper for interactive demos
-function StatefulCombobox(
-  props:
-    | (Omit<React.ComponentProps<typeof Combobox>, 'value' | 'onValueChange'> & {
-        children: React.ReactNode;
-        multiple: true;
-        initialValue?: string[];
-      })
-    | (Omit<React.ComponentProps<typeof Combobox>, 'value' | 'onValueChange'> & {
-        children: React.ReactNode;
-        multiple?: false;
-        initialValue?: string;
-      })
-) {
-  const { initialValue, children, ...rest } = props;
-
-  if (props.multiple) {
-    const [value, setValue] = useState<string[]>(
-      Array.isArray(initialValue) ? initialValue : []
-    );
-    const multiProps = rest as Omit<React.ComponentProps<typeof Combobox>, 'value' | 'onValueChange'> & {
-      multiple: true;
-    };
-    const MultiCombobox = Combobox as unknown as (props: ComboboxMultipleProps) => React.JSX.Element;
-    return (
-      <MultiCombobox {...(multiProps as ComboboxMultipleProps)} multiple value={value} onValueChange={setValue}>
-        {children}
-      </MultiCombobox>
-    );
-  }
-
-  const [value, setValue] = useState<string | null>(
-    typeof initialValue === 'string' ? initialValue : null
-  );
-  const singleProps = rest as Omit<React.ComponentProps<typeof Combobox>, 'value' | 'onValueChange'> & {
-    multiple?: false;
-  };
-  const SingleCombobox = Combobox as unknown as (props: ComboboxSingleProps) => React.JSX.Element;
-  return (
-    <SingleCombobox {...(singleProps as ComboboxSingleProps)} value={value} onValueChange={setValue}>
-      {children}
-    </SingleCombobox>
-  );
-}
-
-export default defineFragment({
-  component: Combobox,
-
-  meta: {
-    name: 'Combobox',
-    description: 'Searchable select input that filters a dropdown list of options as you type. Supports single and multiple selection with chips.',
-    category: 'forms',
-    status: 'stable',
-    tags: ['combobox', 'autocomplete', 'search', 'select', 'typeahead', 'form', 'multiselect'],
-    since: '0.1.0',
-  },
-
-  usage: {
-    when: [
-      'Users need to search/filter through many options',
-      'Large option lists where scrolling is impractical',
-      'When users might know what they are looking for',
-      'Autocomplete or typeahead functionality',
-      'Multiple selections from a searchable list',
-    ],
-    whenNot: [
-      'Few options (under 5) - use Select or RadioGroup',
-      'Free-form text with no predefined options - use Input',
-      'Non-searchable single selection - use Select',
-      'Actions, not selection - use Menu',
-    ],
-    guidelines: [
-      'Include a placeholder that explains what to search for',
-      'Provide an empty state message when no results match',
-      'Group related options with Combobox.Group for large lists',
-      'Keep option text concise and searchable',
-      'Use multiple prop for multi-select with chip display',
-    ],
-    accessibility: [
-      'Full keyboard navigation support (arrow keys, enter, escape)',
-      'Type-ahead filtering within options',
-      'Proper ARIA combobox roles and attributes',
-      'Screen reader announcements for filtered results',
-      'Chip removal via keyboard in multi-select mode',
-    ],
-  },
-
-  props: {
-    children: {
-      type: 'node',
-      description: 'Combobox input and content',
-      required: true,
-    },
-    value: {
-      type: 'union',
-      description: 'Controlled selected value (string for single, string[] for multiple)',
-    },
-    defaultValue: {
-      type: 'union',
-      description: 'Default selected value (uncontrolled)',
-    },
-    onValueChange: {
-      type: 'function',
-      description: 'Called when selection changes',
-    },
-    onChange: {
-      type: 'function',
-      description: 'Alias for onValueChange',
-    },
-    multiple: {
-      type: 'boolean',
-      description: 'Allow multiple selections with chips',
-      default: 'false',
-    },
-    open: {
-      type: 'boolean',
-      description: 'Controlled open state of the dropdown',
-    },
-    defaultOpen: {
-      type: 'boolean',
-      description: 'Initial open state for uncontrolled usage',
-      default: 'false',
-    },
-    onOpenChange: {
-      type: 'function',
-      description: 'Called when dropdown open state changes',
-    },
-    placeholder: {
-      type: 'string',
-      description: 'Placeholder text for the input',
-    },
-    disabled: {
-      type: 'boolean',
-      description: 'Disable the combobox',
-      default: 'false',
-    },
-    autoHighlight: {
-      type: 'boolean',
-      description: 'Auto-highlight first matching item while filtering',
-      default: 'true',
-    },
-  },
-
-  relations: [
-    { component: 'Select', relationship: 'alternative', note: 'Use Select when search/filtering is not needed' },
-    { component: 'Input', relationship: 'sibling', note: 'Use Input for free-form text entry' },
-    { component: 'Listbox', relationship: 'sibling', note: 'Use Listbox for inline option lists' },
-  ],
-
-  contract: {
-    propsSummary: [
-      'value: string | string[] - controlled selected value',
-      'onValueChange: (value) => void - selection handler',
-      'onChange: (value) => void - alias for onValueChange',
-      'multiple: boolean - enable multi-select with chips',
-      'When multiple=true, value/defaultValue must be string[] (single mode uses string|null)',
-      'placeholder: string - input placeholder text',
-      'disabled: boolean - disable combobox',
-      'autoHighlight: boolean - auto-highlight first match',
-      'Combobox.Input showTrigger: boolean - hide built-in trigger when using Combobox.Trigger explicitly',
-      'maxVisibleItems: number - max visible options before scrolling (default 4)',
-    ],
-    scenarioTags: [
-      'form.combobox',
-      'form.autocomplete',
-      'form.multiselect',
-      'input.search',
-    ],
-    a11yRules: ['A11Y_COMBOBOX_KEYBOARD', 'A11Y_COMBOBOX_LABEL', 'A11Y_TARGET_SIZE_MIN'],
-  },
-
-  ai: {
-    compositionPattern: 'compound',
-    subComponents: ['Input', 'Trigger', 'Content', 'Item', 'ItemIndicator', 'Empty', 'Group', 'GroupLabel'],
-    requiredChildren: ['Input', 'Content'],
-    commonPatterns: [
-      '<Combobox placeholder="Search..."><Combobox.Input /><Combobox.Content><Combobox.Item value="opt1">{label1}</Combobox.Item><Combobox.Item value="opt2">{label2}</Combobox.Item></Combobox.Content></Combobox>',
-      '<Combobox multiple placeholder="Select items..."><Combobox.Input /><Combobox.Content><Combobox.Item value="opt1">{label1}</Combobox.Item><Combobox.Item value="opt2">{label2}</Combobox.Item></Combobox.Content></Combobox>',
-      '<Combobox placeholder="Search..."><Combobox.Input showTrigger={false} /><Combobox.Trigger aria-label="Open" /><Combobox.Content>...</Combobox.Content></Combobox>',
-    ],
-  },
-
-  variants: [
-    {
-      name: 'Default',
-      description: 'Basic searchable select',
-      render: () => (
-        <StatefulCombobox placeholder="Select a fruit">
-          <Combobox.Input />
-          <Combobox.Content>
-            <Combobox.Item value="apple">Apple</Combobox.Item>
-            <Combobox.Item value="banana">Banana</Combobox.Item>
-            <Combobox.Item value="orange">Orange</Combobox.Item>
-            <Combobox.Item value="grape">Grape</Combobox.Item>
-          </Combobox.Content>
-        </StatefulCombobox>
-      ),
-    },
-    {
-      name: 'Multiple Selection',
-      description: 'Multi-select with chips',
-      render: () => (
-        <StatefulCombobox multiple placeholder="Select fruits...">
-          <Combobox.Input />
-          <Combobox.Content>
-            <Combobox.Item value="apple">Apple</Combobox.Item>
-            <Combobox.Item value="banana">Banana</Combobox.Item>
-            <Combobox.Item value="orange">Orange</Combobox.Item>
-            <Combobox.Item value="grape">Grape</Combobox.Item>
-            <Combobox.Item value="mango">Mango</Combobox.Item>
-            <Combobox.Item value="kiwi">Kiwi</Combobox.Item>
-          </Combobox.Content>
-        </StatefulCombobox>
-      ),
-    },
-    {
-      name: 'With Groups',
-      description: 'Options organized into groups',
-      render: () => (
-        <StatefulCombobox placeholder="Search countries...">
-          <Combobox.Input />
-          <Combobox.Content>
-            <Combobox.Group>
-              <Combobox.GroupLabel>North America</Combobox.GroupLabel>
-              <Combobox.Item value="us">United States</Combobox.Item>
-              <Combobox.Item value="ca">Canada</Combobox.Item>
-              <Combobox.Item value="mx">Mexico</Combobox.Item>
-            </Combobox.Group>
-            <Combobox.Group>
-              <Combobox.GroupLabel>Europe</Combobox.GroupLabel>
-              <Combobox.Item value="uk">United Kingdom</Combobox.Item>
-              <Combobox.Item value="de">Germany</Combobox.Item>
-              <Combobox.Item value="fr">France</Combobox.Item>
-            </Combobox.Group>
-          </Combobox.Content>
-        </StatefulCombobox>
-      ),
-    },
-    {
-      name: 'With Empty State',
-      description: 'Shows message when no results match',
-      render: () => (
-        <StatefulCombobox placeholder="Search programming languages...">
-          <Combobox.Input />
-          <Combobox.Content>
-            <Combobox.Empty>No results found</Combobox.Empty>
-            <Combobox.Item value="js">JavaScript</Combobox.Item>
-            <Combobox.Item value="ts">TypeScript</Combobox.Item>
-            <Combobox.Item value="py">Python</Combobox.Item>
-            <Combobox.Item value="rs">Rust</Combobox.Item>
-            <Combobox.Item value="go">Go</Combobox.Item>
-          </Combobox.Content>
-        </StatefulCombobox>
-      ),
-    },
-    {
-      name: 'Scrollable List',
-      description: 'Long list with scroll hint — shows 4 items with half-peek of the 5th',
-      render: () => (
-        <StatefulCombobox placeholder="Search languages...">
-          <Combobox.Input />
-          <Combobox.Content>
-            <Combobox.Empty>No results found</Combobox.Empty>
-            <Combobox.Item value="js">JavaScript</Combobox.Item>
-            <Combobox.Item value="ts">TypeScript</Combobox.Item>
-            <Combobox.Item value="py">Python</Combobox.Item>
-            <Combobox.Item value="rs">Rust</Combobox.Item>
-            <Combobox.Item value="go">Go</Combobox.Item>
-            <Combobox.Item value="rb">Ruby</Combobox.Item>
-            <Combobox.Item value="java">Java</Combobox.Item>
-            <Combobox.Item value="swift">Swift</Combobox.Item>
-            <Combobox.Item value="kt">Kotlin</Combobox.Item>
-            <Combobox.Item value="cpp">C++</Combobox.Item>
-          </Combobox.Content>
-        </StatefulCombobox>
-      ),
-    },
-    {
-      name: 'Custom Max Visible Items',
-      description: 'Show 6 items before scrolling with half-peek scroll hint',
-      render: () => (
-        <StatefulCombobox placeholder="Search cities...">
-          <Combobox.Input />
-          <Combobox.Content maxVisibleItems={6}>
-            <Combobox.Empty>No results found</Combobox.Empty>
-            <Combobox.Item value="nyc">New York</Combobox.Item>
-            <Combobox.Item value="lon">London</Combobox.Item>
-            <Combobox.Item value="tok">Tokyo</Combobox.Item>
-            <Combobox.Item value="par">Paris</Combobox.Item>
-            <Combobox.Item value="syd">Sydney</Combobox.Item>
-            <Combobox.Item value="ber">Berlin</Combobox.Item>
-            <Combobox.Item value="tor">Toronto</Combobox.Item>
-            <Combobox.Item value="sin">Singapore</Combobox.Item>
-            <Combobox.Item value="dub">Dubai</Combobox.Item>
-            <Combobox.Item value="sao">São Paulo</Combobox.Item>
-          </Combobox.Content>
-        </StatefulCombobox>
-      ),
-    },
-    {
-      name: 'Disabled',
-      description: 'Disabled combobox',
-      render: () => (
-        <Combobox disabled placeholder="Search...">
-          <Combobox.Input />
-          <Combobox.Content>
-            <Combobox.Item value="1">Option 1</Combobox.Item>
-          </Combobox.Content>
-        </Combobox>
-      ),
-    },
-    {
-      name: 'Explicit Trigger',
-      description: 'Hide the built-in input trigger when rendering a separate Combobox.Trigger',
-      render: () => (
-        <StatefulCombobox placeholder="Search assignees...">
-          <Combobox.Input showTrigger={false} />
-          <Combobox.Trigger aria-label="Open assignee list" />
-          <Combobox.Content>
-            <Combobox.Item value="alice">Alice</Combobox.Item>
-            <Combobox.Item value="bob">Bob</Combobox.Item>
-            <Combobox.Item value="carol">Carol</Combobox.Item>
-          </Combobox.Content>
-        </StatefulCombobox>
-      ),
-    },
-  ],
-});

package/src/components/Combobox/Combobox.test.tsx

@@ -1,278 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { render, screen, userEvent, expectNoA11yViolations } from '../../test/utils';
-import { Combobox } from './index';
-
-type RenderComboboxProps =
-  | { onValueChange?: (v: string | null) => void; multiple?: false; placeholder?: string }
-  | { onValueChange?: (v: string[]) => void; multiple: true; placeholder?: string };
-
-function renderCombobox(props: RenderComboboxProps = {}) {
-  if (props.multiple) {
-    return render(
-      <Combobox
-        placeholder={props.placeholder ?? 'Search...'}
-        onValueChange={props.onValueChange}
-        multiple
-      >
-        <Combobox.Input />
-        <Combobox.Content>
-          <Combobox.Item value="react">React</Combobox.Item>
-          <Combobox.Item value="vue">Vue</Combobox.Item>
-          <Combobox.Item value="angular">Angular</Combobox.Item>
-          <Combobox.Empty>No results found</Combobox.Empty>
-        </Combobox.Content>
-      </Combobox>
-    );
-  }
-
-  return render(
-    <Combobox
-      placeholder={props.placeholder ?? 'Search...'}
-      onValueChange={props.onValueChange}
-    >
-      <Combobox.Input />
-      <Combobox.Content>
-        <Combobox.Item value="react">React</Combobox.Item>
-        <Combobox.Item value="vue">Vue</Combobox.Item>
-        <Combobox.Item value="angular">Angular</Combobox.Item>
-        <Combobox.Empty>No results found</Combobox.Empty>
-      </Combobox.Content>
-    </Combobox>
-  );
-}
-
-describe('Combobox', () => {
-  it('renders an input and a trigger button', () => {
-    renderCombobox();
-    expect(screen.getByRole('combobox')).toBeInTheDocument();
-  });
-
-  it('shows placeholder text', () => {
-    renderCombobox({ placeholder: 'Type to search' });
-    expect(screen.getByPlaceholderText('Type to search')).toBeInTheDocument();
-  });
-
-  it('opens dropdown and shows options when trigger is clicked', async () => {
-    const user = userEvent.setup();
-    renderCombobox();
-    // Click the combobox input to open
-    await user.click(screen.getByRole('combobox'));
-    expect(await screen.findByRole('option', { name: 'React' })).toBeInTheDocument();
-    expect(await screen.findByRole('option', { name: 'Vue' })).toBeInTheDocument();
-  });
-
-  it('selects an option on click', async () => {
-    const user = userEvent.setup();
-    const onChange = vi.fn();
-    renderCombobox({ onValueChange: onChange });
-
-    await user.click(screen.getByRole('combobox'));
-    const option = await screen.findByRole('option', { name: 'React' });
-    await user.click(option);
-    expect(onChange).toHaveBeenCalledWith('react');
-  });
-
-  it('filters options based on input text', async () => {
-    const user = userEvent.setup();
-    renderCombobox();
-
-    const input = screen.getByRole('combobox');
-    await user.click(input);
-    await user.type(input, 'rea');
-    // React should be visible, Vue/Angular may be filtered out
-    expect(await screen.findByRole('option', { name: 'React' })).toBeInTheDocument();
-  });
-
-  it('renders groups and group labels', async () => {
-    const user = userEvent.setup();
-    render(
-      <Combobox placeholder="Search">
-        <Combobox.Input />
-        <Combobox.Content>
-          <Combobox.Group>
-            <Combobox.GroupLabel>Frameworks</Combobox.GroupLabel>
-            <Combobox.Item value="react">React</Combobox.Item>
-          </Combobox.Group>
-        </Combobox.Content>
-      </Combobox>
-    );
-    await user.click(screen.getByRole('combobox'));
-    expect(await screen.findByText('Frameworks')).toBeInTheDocument();
-  });
-
-  it('forwards html props to item and labels', async () => {
-    const user = userEvent.setup();
-    render(
-      <Combobox placeholder="Search">
-        <Combobox.Input />
-        <Combobox.Content>
-          <Combobox.Group id="framework-group">
-            <Combobox.GroupLabel id="framework-group-label">Frameworks</Combobox.GroupLabel>
-            <Combobox.Item id="react-option" value="react">React</Combobox.Item>
-          </Combobox.Group>
-        </Combobox.Content>
-      </Combobox>
-    );
-
-    await user.click(screen.getByRole('combobox'));
-    expect(await screen.findByRole('option', { name: 'React' })).toHaveAttribute('id', 'react-option');
-    expect(screen.getByText('Frameworks')).toHaveAttribute('id', 'framework-group-label');
-    expect(screen.getByText('Frameworks').closest('#framework-group')).toBeInTheDocument();
-  });
-
-  it('supports multiple selection mode', async () => {
-    const user = userEvent.setup();
-    const onChange = vi.fn<(value: string[]) => void>();
-    renderCombobox({ multiple: true, onValueChange: onChange });
-
-    await user.click(screen.getByRole('combobox'));
-    const option = await screen.findByRole('option', { name: 'React' });
-    await user.click(option);
-    expect(onChange).toHaveBeenCalled();
-  });
-
-  it('uses text content for non-string item labels', async () => {
-    render(
-      <Combobox multiple value={['react']} defaultOpen>
-        <Combobox.Input />
-        <Combobox.Content>
-          <Combobox.Item value="react">
-            <span>React</span>
-          </Combobox.Item>
-        </Combobox.Content>
-      </Combobox>
-    );
-
-    expect((await screen.findAllByText('React')).length).toBeGreaterThan(0);
-    expect(screen.queryByText('[object Object]')).not.toBeInTheDocument();
-  });
-
-  it('has no accessibility violations', async () => {
-    const { container } = render(
-      <Combobox placeholder="Search...">
-        <Combobox.Input aria-label="Search frameworks" />
-        <Combobox.Content>
-          <Combobox.Item value="react">React</Combobox.Item>
-        </Combobox.Content>
-      </Combobox>
-    );
-    // The internal Base UI trigger button lacks aria-label by design (it's a
-    // decorative chevron next to the labeled input). Disable button-name for
-    // this component-level test.
-    await expectNoA11yViolations(container, {
-      disabledRules: ['button-name'],
-    });
-  });
-
-  describe('keyboard & focus', () => {
-    it('ArrowDown opens the dropdown from input', async () => {
-      const user = userEvent.setup();
-      renderCombobox();
-
-      const input = screen.getByRole('combobox');
-      await user.click(input);
-      // Close it first, then reopen with keyboard
-      await user.keyboard('{Escape}');
-      await user.keyboard('{ArrowDown}');
-      expect(await screen.findByRole('option', { name: 'React' })).toBeInTheDocument();
-    });
-
-    it('options are rendered in listbox when open', async () => {
-      const user = userEvent.setup();
-      renderCombobox();
-
-      await user.click(screen.getByRole('combobox'));
-      expect(await screen.findByRole('option', { name: 'React' })).toBeInTheDocument();
-      expect(screen.getByRole('option', { name: 'Vue' })).toBeInTheDocument();
-      expect(screen.getByRole('option', { name: 'Angular' })).toBeInTheDocument();
-    });
-
-    it('input has aria-expanded when dropdown is open', async () => {
-      const user = userEvent.setup();
-      renderCombobox();
-
-      const input = screen.getByRole('combobox');
-      await user.click(input);
-      await screen.findByRole('option', { name: 'React' });
-      expect(input).toHaveAttribute('aria-expanded', 'true');
-    });
-
-    it('clicking an option selects it', async () => {
-      const user = userEvent.setup();
-      const onChange = vi.fn();
-      renderCombobox({ onValueChange: onChange });
-
-      await user.click(screen.getByRole('combobox'));
-      const option = await screen.findByRole('option', { name: 'Vue' });
-      await user.click(option);
-      expect(onChange).toHaveBeenCalledWith('vue');
-    });
-
-    it('Escape closes the dropdown', async () => {
-      const user = userEvent.setup();
-      renderCombobox();
-
-      await user.click(screen.getByRole('combobox'));
-      await screen.findByRole('option', { name: 'React' });
-
-      await user.keyboard('{Escape}');
-      expect(screen.queryByRole('option')).not.toBeInTheDocument();
-    });
-
-    it('focus stays on input after Escape', async () => {
-      const user = userEvent.setup();
-      renderCombobox();
-
-      const input = screen.getByRole('combobox');
-      await user.click(input);
-      await screen.findByRole('option', { name: 'React' });
-
-      await user.keyboard('{Escape}');
-      expect(input).toHaveFocus();
-    });
-
-    it('typing filters results to show matching option', async () => {
-      const user = userEvent.setup();
-      renderCombobox();
-
-      const input = screen.getByRole('combobox');
-      await user.click(input);
-      await user.type(input, 'rea');
-
-      // React should be visible after filtering
-      expect(await screen.findByRole('option', { name: 'React' })).toBeInTheDocument();
-    });
-
-    it('Escape after filtering closes the dropdown', async () => {
-      const user = userEvent.setup();
-      renderCombobox();
-
-      const input = screen.getByRole('combobox');
-      await user.click(input);
-      await user.type(input, 'vue');
-      await screen.findByRole('option', { name: 'Vue' });
-
-      await user.keyboard('{Escape}');
-      expect(screen.queryByRole('option')).not.toBeInTheDocument();
-    });
-  });
-
-  it('updates chip label when selected option is removed', async () => {
-    const renderDemo = (showReact: boolean) => (
-      <Combobox multiple value={['react']} defaultOpen>
-        <Combobox.Input />
-        <Combobox.Content>
-          {showReact && <Combobox.Item value="react">React</Combobox.Item>}
-          <Combobox.Item value="vue">Vue</Combobox.Item>
-        </Combobox.Content>
-      </Combobox>
-    );
-
-    const { rerender } = render(renderDemo(true));
-
-    await screen.findAllByText('React');
-    rerender(renderDemo(false));
-
-    expect(await screen.findByText('react')).toBeInTheDocument();
-  });
-});