@fragments-sdk/ui 0.7.4 → 0.8.0

package/src/components/Dialog/Dialog.test.tsx

@@ -0,0 +1,277 @@
+import { describe, it, expect } from 'vitest';
+import { render, screen, userEvent, waitFor, expectNoA11yViolations } from '../../test/utils';
+import { Dialog } from './index';
+
+function renderDialog(props: Partial<React.ComponentProps<typeof Dialog>> = {}) {
+  return render(
+    <Dialog {...props}>
+      <Dialog.Trigger>Open Dialog</Dialog.Trigger>
+      <Dialog.Content>
+        <Dialog.Header>
+          <Dialog.Title>Dialog Title</Dialog.Title>
+          <Dialog.Close />
+        </Dialog.Header>
+        <Dialog.Body>
+          <Dialog.Description>Dialog description text</Dialog.Description>
+          <p>Body content</p>
+        </Dialog.Body>
+        <Dialog.Footer>
+          <Dialog.Close asChild>
+            <button>Cancel</button>
+          </Dialog.Close>
+        </Dialog.Footer>
+      </Dialog.Content>
+    </Dialog>
+  );
+}
+
+describe('Dialog', () => {
+  it('opens when trigger is clicked', async () => {
+    const user = userEvent.setup();
+    renderDialog();
+
+    expect(screen.queryByText('Dialog Title')).not.toBeInTheDocument();
+
+    await user.click(screen.getByRole('button', { name: /open dialog/i }));
+    await waitFor(() => {
+      expect(screen.getByText('Dialog Title')).toBeInTheDocument();
+    });
+  });
+
+  it('closes when close button is clicked', async () => {
+    const user = userEvent.setup();
+    renderDialog({ defaultOpen: true });
+
+    await waitFor(() => {
+      expect(screen.getByText('Dialog Title')).toBeInTheDocument();
+    });
+
+    const closeButton = screen.getByRole('button', { name: /close dialog/i });
+    await user.click(closeButton);
+
+    await waitFor(() => {
+      expect(screen.queryByText('Dialog Title')).not.toBeInTheDocument();
+    });
+  });
+
+  it('close button has aria-label', async () => {
+    renderDialog({ defaultOpen: true });
+
+    await waitFor(() => {
+      expect(screen.getByRole('button', { name: /close dialog/i })).toBeInTheDocument();
+    });
+  });
+
+  it('renders title and description', async () => {
+    renderDialog({ defaultOpen: true });
+
+    await waitFor(() => {
+      expect(screen.getByText('Dialog Title')).toBeInTheDocument();
+      expect(screen.getByText('Dialog description text')).toBeInTheDocument();
+    });
+  });
+
+  it('renders compound sub-components (Header, Body, Footer)', async () => {
+    renderDialog({ defaultOpen: true });
+
+    await waitFor(() => {
+      expect(screen.getByText('Body content')).toBeInTheDocument();
+      expect(screen.getByRole('button', { name: /cancel/i })).toBeInTheDocument();
+    });
+  });
+
+  it('supports size variant prop', async () => {
+    render(
+      <Dialog defaultOpen>
+        <Dialog.Trigger>Open</Dialog.Trigger>
+        <Dialog.Content size="lg">
+          <Dialog.Title>Large Dialog</Dialog.Title>
+        </Dialog.Content>
+      </Dialog>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('Large Dialog')).toBeInTheDocument();
+    });
+  });
+
+  it('renders as modal by default', async () => {
+    renderDialog({ defaultOpen: true });
+
+    await waitFor(() => {
+      expect(screen.getByText('Dialog Title')).toBeInTheDocument();
+    });
+  });
+
+  it('has no accessibility violations when open', async () => {
+    const { container } = renderDialog({ defaultOpen: true });
+
+    await waitFor(() => {
+      expect(screen.getByText('Dialog Title')).toBeInTheDocument();
+    });
+
+    await expectNoA11yViolations(container, {
+      // Base UI focus guard spans have role="button" without labels.
+      disabledRules: ['aria-command-name'],
+    });
+  });
+
+  describe('keyboard & focus', () => {
+    it('Escape closes dialog (WCAG 2.1.1)', async () => {
+      const user = userEvent.setup();
+      renderDialog({ defaultOpen: true });
+
+      await waitFor(() => {
+        expect(screen.getByText('Dialog Title')).toBeInTheDocument();
+      });
+
+      await user.keyboard('{Escape}');
+
+      await waitFor(() => {
+        expect(screen.queryByText('Dialog Title')).not.toBeInTheDocument();
+      });
+    });
+
+    it('focus moves into dialog on open (WCAG 2.4.3)', async () => {
+      const user = userEvent.setup();
+      renderDialog();
+
+      await user.click(screen.getByRole('button', { name: /open dialog/i }));
+
+      await waitFor(() => {
+        expect(screen.getByText('Dialog Title')).toBeInTheDocument();
+      });
+
+      await waitFor(() => {
+        const dialog = screen.getByRole('dialog');
+        expect(dialog.contains(document.activeElement)).toBe(true);
+      });
+    });
+
+    it('focus returns to trigger on Escape (WCAG 2.4.3)', async () => {
+      const user = userEvent.setup();
+      renderDialog();
+
+      const trigger = screen.getByRole('button', { name: /open dialog/i });
+      await user.click(trigger);
+
+      await waitFor(() => {
+        expect(screen.getByText('Dialog Title')).toBeInTheDocument();
+      });
+
+      await user.keyboard('{Escape}');
+
+      await waitFor(() => {
+        expect(screen.queryByText('Dialog Title')).not.toBeInTheDocument();
+      });
+
+      await waitFor(() => {
+        expect(trigger).toHaveFocus();
+      });
+    });
+
+    it('focus returns to trigger on Close button click (WCAG 2.4.3)', async () => {
+      const user = userEvent.setup();
+      renderDialog();
+
+      const trigger = screen.getByRole('button', { name: /open dialog/i });
+      await user.click(trigger);
+
+      await waitFor(() => {
+        expect(screen.getByText('Dialog Title')).toBeInTheDocument();
+      });
+
+      const closeButton = screen.getByRole('button', { name: /close dialog/i });
+      await user.click(closeButton);
+
+      await waitFor(() => {
+        expect(screen.queryByText('Dialog Title')).not.toBeInTheDocument();
+      });
+
+      await waitFor(() => {
+        expect(trigger).toHaveFocus();
+      });
+    });
+
+    it('Tab cycles within dialog (focus trap) (WCAG 2.1.2)', async () => {
+      const user = userEvent.setup();
+      renderDialog({ defaultOpen: true });
+
+      await waitFor(() => {
+        expect(screen.getByText('Dialog Title')).toBeInTheDocument();
+      });
+
+      const dialog = screen.getByRole('dialog');
+      const closeButton = screen.getByRole('button', { name: /close dialog/i });
+      const cancelButton = screen.getByRole('button', { name: /cancel/i });
+
+      // Tab through focusable elements — focus should stay inside dialog
+      await user.tab();
+      await user.tab();
+      await user.tab();
+
+      await waitFor(() => {
+        expect(dialog.contains(document.activeElement)).toBe(true);
+      });
+
+      // Verify that close and cancel buttons are reachable
+      // Focus one of them directly and confirm containment
+      closeButton.focus();
+      expect(dialog.contains(document.activeElement)).toBe(true);
+
+      cancelButton.focus();
+      expect(dialog.contains(document.activeElement)).toBe(true);
+    });
+
+    it('Shift+Tab cycles backward (WCAG 2.1.2)', async () => {
+      const user = userEvent.setup();
+      renderDialog({ defaultOpen: true });
+
+      await waitFor(() => {
+        expect(screen.getByText('Dialog Title')).toBeInTheDocument();
+      });
+
+      const dialog = screen.getByRole('dialog');
+
+      // Shift+Tab backward multiple times — focus should remain trapped
+      await user.keyboard('{Shift>}{Tab}{/Shift}');
+      await user.keyboard('{Shift>}{Tab}{/Shift}');
+      await user.keyboard('{Shift>}{Tab}{/Shift}');
+
+      await waitFor(() => {
+        expect(dialog.contains(document.activeElement)).toBe(true);
+      });
+    });
+
+    it('role="dialog" is present when open (WCAG 4.1.2)', async () => {
+      renderDialog({ defaultOpen: true });
+
+      await waitFor(() => {
+        expect(screen.getByRole('dialog')).toBeInTheDocument();
+      });
+    });
+
+    it('Cancel button closes dialog and returns focus (WCAG 2.4.3)', async () => {
+      const user = userEvent.setup();
+      renderDialog();
+
+      const trigger = screen.getByRole('button', { name: /open dialog/i });
+      await user.click(trigger);
+
+      await waitFor(() => {
+        expect(screen.getByText('Dialog Title')).toBeInTheDocument();
+      });
+
+      const cancelButton = screen.getByRole('button', { name: /cancel/i });
+      await user.click(cancelButton);
+
+      await waitFor(() => {
+        expect(screen.queryByText('Dialog Title')).not.toBeInTheDocument();
+      });
+
+      await waitFor(() => {
+        expect(trigger).toHaveFocus();
+      });
+    });
+  });
+});

package/src/components/EmptyState/EmptyState.test.tsx

@@ -0,0 +1,67 @@
+import { describe, it, expect } from 'vitest';
+import { render, screen, expectNoA11yViolations } from '../../test/utils';
+import { EmptyState } from './index';
+
+describe('EmptyState', () => {
+  it('renders children', () => {
+    render(
+      <EmptyState>
+        <EmptyState.Title>No results</EmptyState.Title>
+      </EmptyState>
+    );
+    expect(screen.getByText('No results')).toBeInTheDocument();
+  });
+
+  it('renders all compound sub-components', () => {
+    render(
+      <EmptyState>
+        <EmptyState.Icon>ICON</EmptyState.Icon>
+        <EmptyState.Title>Empty</EmptyState.Title>
+        <EmptyState.Description>Nothing to show</EmptyState.Description>
+        <EmptyState.Actions><button>Add item</button></EmptyState.Actions>
+      </EmptyState>
+    );
+    expect(screen.getByText('ICON')).toHaveClass('icon');
+    expect(screen.getByText('Empty').tagName).toBe('H3');
+    expect(screen.getByText('Nothing to show').tagName).toBe('P');
+    expect(screen.getByRole('button', { name: 'Add item' })).toBeInTheDocument();
+  });
+
+  it('applies size class', () => {
+    const { container } = render(
+      <EmptyState size="lg">
+        <EmptyState.Title>Large</EmptyState.Title>
+      </EmptyState>
+    );
+    expect(container.firstElementChild).toHaveClass('lg');
+  });
+
+  it('applies custom className', () => {
+    const { container } = render(
+      <EmptyState className="custom">
+        <EmptyState.Title>Custom</EmptyState.Title>
+      </EmptyState>
+    );
+    expect(container.firstElementChild).toHaveClass('custom');
+  });
+
+  it('defaults to md size', () => {
+    const { container } = render(
+      <EmptyState>
+        <EmptyState.Title>Default</EmptyState.Title>
+      </EmptyState>
+    );
+    expect(container.firstElementChild).toHaveClass('md');
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(
+      <EmptyState>
+        <EmptyState.Icon>ICON</EmptyState.Icon>
+        <EmptyState.Title>No items found</EmptyState.Title>
+        <EmptyState.Description>Try adjusting your search</EmptyState.Description>
+      </EmptyState>
+    );
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/Field/Field.fragment.tsx

@@ -42,6 +42,11 @@ export default defineSegment({
   },
 
   props: {
+    children: {
+      type: 'node',
+      description: 'Field content (Label, Control, Description, Error)',
+      required: true,
+    },
     name: {
       type: 'string',
       description: 'Field name, used for error distribution from Form',
@@ -67,10 +72,6 @@ export default defineSegment({
       type: 'number',
       description: 'Debounce time in ms for onChange validation',
     },
-    className: {
-      type: 'string',
-      description: 'Additional CSS class',
-    },
   },
 
   relations: [

package/src/components/Field/Field.test.tsx

@@ -0,0 +1,65 @@
+import { describe, it, expect } from 'vitest';
+import { render, screen, expectNoA11yViolations } from '../../test/utils';
+import { Field } from './index';
+
+describe('Field', () => {
+  it('renders children inside the field root', () => {
+    render(
+      <Field>
+        <Field.Label>Username</Field.Label>
+        <Field.Control><input /></Field.Control>
+      </Field>
+    );
+    expect(screen.getByText('Username')).toBeInTheDocument();
+    expect(screen.getByRole('textbox')).toBeInTheDocument();
+  });
+
+  it('associates label with control', () => {
+    render(
+      <Field>
+        <Field.Label>Username</Field.Label>
+        <Field.Control><input /></Field.Control>
+      </Field>
+    );
+    expect(screen.getByRole('textbox')).toHaveAccessibleName('Username');
+  });
+
+  it('renders description text', () => {
+    render(
+      <Field>
+        <Field.Label>Email</Field.Label>
+        <Field.Control><input /></Field.Control>
+        <Field.Description>We will never share your email.</Field.Description>
+      </Field>
+    );
+    expect(screen.getByText('We will never share your email.')).toBeInTheDocument();
+  });
+
+  it('sets aria-invalid on control when invalid', () => {
+    render(
+      <Field invalid>
+        <Field.Label>Email</Field.Label>
+        <Field.Control><input /></Field.Control>
+      </Field>
+    );
+    expect(screen.getByRole('textbox')).toHaveAttribute('aria-invalid', 'true');
+  });
+
+  it('exposes compound component pattern', () => {
+    expect(Field.Label).toBeDefined();
+    expect(Field.Control).toBeDefined();
+    expect(Field.Description).toBeDefined();
+    expect(Field.Error).toBeDefined();
+    expect(Field.Validity).toBeDefined();
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(
+      <Field>
+        <Field.Label>Accessible field</Field.Label>
+        <Field.Control><input /></Field.Control>
+      </Field>
+    );
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/Fieldset/Fieldset.fragment.tsx

@@ -43,14 +43,15 @@ export default defineSegment({
   },
 
   props: {
+    children: {
+      type: 'node',
+      description: 'Fieldset content including Fieldset.Legend and form fields',
+      required: true,
+    },
     disabled: {
       type: 'boolean',
       description: 'Disables all fields within the fieldset',
     },
-    className: {
-      type: 'string',
-      description: 'Additional CSS class',
-    },
   },
 
   relations: [

package/src/components/Fieldset/Fieldset.test.tsx

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest';
+import { render, screen, expectNoA11yViolations } from '../../test/utils';
+import { Fieldset } from './index';
+
+describe('Fieldset', () => {
+  it('renders a fieldset element', () => {
+    render(
+      <Fieldset>
+        <Fieldset.Legend>Personal Info</Fieldset.Legend>
+        <input aria-label="Name" />
+      </Fieldset>
+    );
+    // Base UI renders a fieldset element
+    const fieldset = screen.getByRole('group');
+    expect(fieldset).toBeInTheDocument();
+  });
+
+  it('renders a legend', () => {
+    render(
+      <Fieldset>
+        <Fieldset.Legend>Contact Details</Fieldset.Legend>
+      </Fieldset>
+    );
+    expect(screen.getByText('Contact Details')).toBeInTheDocument();
+  });
+
+  it('passes disabled prop to fieldset element', () => {
+    const { container } = render(
+      <Fieldset disabled>
+        <Fieldset.Legend>Settings</Fieldset.Legend>
+        <input aria-label="Option" />
+      </Fieldset>
+    );
+    const fieldset = container.querySelector('fieldset');
+    expect(fieldset).toBeInTheDocument();
+    expect(fieldset).toHaveAttribute('data-disabled', '');
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(
+      <Fieldset>
+        <Fieldset.Legend>Accessible fieldset</Fieldset.Legend>
+        <input aria-label="Field" />
+      </Fieldset>
+    );
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/Form/Form.fragment.tsx

@@ -48,6 +48,11 @@ export default defineSegment({
   },
 
   props: {
+    children: {
+      type: 'node',
+      description: 'Form content',
+      required: true,
+    },
     errors: {
       type: 'object',
       description: 'Server-side errors keyed by field name',
@@ -60,9 +65,10 @@ export default defineSegment({
       type: 'function',
       description: 'Called with field name when errors should be cleared',
     },
-    className: {
-      type: 'string',
-      description: 'Additional CSS class',
+    validationMode: {
+      type: 'enum',
+      description: 'When field validation should run',
+      values: ['onSubmit', 'onBlur', 'onChange'],
     },
   },
 

package/src/components/Form/Form.test.tsx

@@ -0,0 +1,41 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, userEvent, expectNoA11yViolations } from '../../test/utils';
+import { Form } from './index';
+
+describe('Form', () => {
+  it('renders a form element', () => {
+    const { container } = render(<Form>content</Form>);
+    expect(container.querySelector('form')).toBeInTheDocument();
+  });
+
+  it('calls onFormSubmit when submitted', async () => {
+    const handleSubmit = vi.fn((e: React.FormEvent) => e.preventDefault());
+    const user = userEvent.setup();
+    render(
+      <Form onFormSubmit={handleSubmit} aria-label="Test form">
+        <button type="submit">Submit</button>
+      </Form>
+    );
+    await user.click(screen.getByRole('button', { name: 'Submit' }));
+    expect(handleSubmit).toHaveBeenCalledTimes(1);
+  });
+
+  it('renders children', () => {
+    render(
+      <Form aria-label="Test form">
+        <span>Child content</span>
+      </Form>
+    );
+    expect(screen.getByText('Child content')).toBeInTheDocument();
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(
+      <Form aria-label="Accessible form">
+        <label htmlFor="f">Name</label>
+        <input id="f" />
+      </Form>
+    );
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/Form/index.tsx

@@ -19,7 +19,7 @@ export interface FormProps extends Omit<React.HTMLAttributes<HTMLFormElement>, '
 // Component
 // ============================================
 
-export function Form({
+function FormRoot({
   children,
   errors,
   onFormSubmit,
@@ -51,3 +51,7 @@ export function Form({
     </BaseForm>
   );
 }
+
+export const Form = Object.assign(FormRoot, {
+  Root: FormRoot,
+});

package/src/components/Grid/Grid.fragment.tsx

@@ -39,6 +39,10 @@ export default defineSegment({
   },
 
   props: {
+    children: {
+      type: 'node',
+      description: 'Grid items and content',
+    },
     columns: {
       type: 'union',
       description: 'Number of columns: a number (1-12), a responsive object { base, sm, md, lg, xl }, or "auto" for auto-fill',

package/src/components/Grid/Grid.test.tsx

@@ -0,0 +1,65 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, expectNoA11yViolations } from '../../test/utils';
+import { Grid } from './index';
+
+describe('Grid', () => {
+  it('renders children', () => {
+    render(
+      <Grid>
+        <div>Item 1</div>
+        <div>Item 2</div>
+      </Grid>
+    );
+    expect(screen.getByText('Item 1')).toBeInTheDocument();
+    expect(screen.getByText('Item 2')).toBeInTheDocument();
+  });
+
+  it('applies fixed column class', () => {
+    const { container } = render(<Grid columns={3}>Content</Grid>);
+    expect(container.firstChild).toHaveClass('columns3');
+  });
+
+  it('applies responsive column CSS variables', () => {
+    const { container } = render(
+      <Grid columns={{ base: 1, md: 2, lg: 3 }}>Content</Grid>
+    );
+    const el = container.firstChild as HTMLElement;
+    expect(el).toHaveClass('columnsResponsive');
+    expect(el.style.getPropertyValue('--fui-grid-cols')).toBe('1');
+    expect(el.style.getPropertyValue('--fui-grid-cols-md')).toBe('2');
+    expect(el.style.getPropertyValue('--fui-grid-cols-lg')).toBe('3');
+  });
+
+  it('applies gap classes', () => {
+    const { container } = render(<Grid gap="lg">Content</Grid>);
+    expect(container.firstChild).toHaveClass('gapLg');
+  });
+
+  it('forwards ref', () => {
+    const ref = vi.fn();
+    render(<Grid ref={ref}>Content</Grid>);
+    expect(ref).toHaveBeenCalled();
+  });
+
+  it('renders Grid.Item with colSpan', () => {
+    const { container } = render(
+      <Grid columns={3}>
+        <Grid.Item colSpan={2}>Wide</Grid.Item>
+        <Grid.Item>Normal</Grid.Item>
+      </Grid>
+    );
+    const wideItem = screen.getByText('Wide').parentElement ?? screen.getByText('Wide');
+    // The item that contains "Wide" should have colSpan class
+    expect(container.querySelector('.colSpan2')).toBeInTheDocument();
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(
+      <Grid columns={2}>
+        <Grid.Item>A</Grid.Item>
+        <Grid.Item>B</Grid.Item>
+      </Grid>
+    );
+    await expectNoA11yViolations(container);
+  });
+});