@fragments-sdk/ui 0.7.4 → 0.8.0

package/src/components/Prompt/Prompt.fragment.tsx

@@ -37,6 +37,11 @@ export default defineSegment({
   },
 
   props: {
+    children: {
+      type: 'node',
+      description: 'Prompt composition using Prompt sub-components',
+      required: true,
+    },
     value: {
       type: 'string',
       description: 'Controlled input value',
@@ -88,6 +93,12 @@ export default defineSegment({
       default: 'true',
       description: 'Submit on Enter (Shift+Enter for newline)',
     },
+    variant: {
+      type: 'enum',
+      values: ['default', 'fixed', 'sticky'],
+      default: 'default',
+      description: 'Visual/positioning variant',
+    },
   },
 
   relations: [

package/src/components/Prompt/Prompt.test.tsx

@@ -0,0 +1,89 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, userEvent, expectNoA11yViolations } from '../../test/utils';
+import { Prompt } from './index';
+
+function renderPrompt(props: {
+  onSubmit?: (v: string) => void;
+  placeholder?: string;
+  disabled?: boolean;
+  defaultValue?: string;
+} = {}) {
+  return render(
+    <Prompt
+      placeholder={props.placeholder ?? 'Ask something...'}
+      onSubmit={props.onSubmit}
+      disabled={props.disabled}
+      defaultValue={props.defaultValue}
+    >
+      <Prompt.Textarea />
+      <Prompt.Toolbar>
+        <Prompt.Actions>
+          <Prompt.ActionButton aria-label="Attach file">Attach</Prompt.ActionButton>
+        </Prompt.Actions>
+      </Prompt.Toolbar>
+      <Prompt.Submit />
+    </Prompt>
+  );
+}
+
+describe('Prompt', () => {
+  it('renders a textarea with placeholder', () => {
+    renderPrompt({ placeholder: 'Type here...' });
+    expect(screen.getByPlaceholderText('Type here...')).toBeInTheDocument();
+  });
+
+  it('renders compound sub-components (Toolbar, Actions)', () => {
+    renderPrompt();
+    expect(screen.getByRole('button', { name: /attach file/i })).toBeInTheDocument();
+  });
+
+  it('renders submit button', () => {
+    renderPrompt();
+    expect(screen.getByRole('button', { name: /submit/i })).toBeInTheDocument();
+  });
+
+  it('disables submit when value is empty', () => {
+    renderPrompt();
+    expect(screen.getByRole('button', { name: /submit/i })).toBeDisabled();
+  });
+
+  it('enables submit when user types text', async () => {
+    const user = userEvent.setup();
+    renderPrompt();
+    const textarea = screen.getByPlaceholderText('Ask something...');
+    await user.type(textarea, 'Hello');
+    expect(screen.getByRole('button', { name: /submit/i })).not.toBeDisabled();
+  });
+
+  it('calls onSubmit when submit button is clicked', async () => {
+    const user = userEvent.setup();
+    const handleSubmit = vi.fn();
+    renderPrompt({ onSubmit: handleSubmit, defaultValue: 'Test message' });
+
+    await user.click(screen.getByRole('button', { name: /submit/i }));
+    expect(handleSubmit).toHaveBeenCalledWith('Test message');
+  });
+
+  it('submits on Enter key by default (submitOnEnter)', async () => {
+    const user = userEvent.setup();
+    const handleSubmit = vi.fn();
+    renderPrompt({ onSubmit: handleSubmit });
+
+    const textarea = screen.getByPlaceholderText('Ask something...');
+    await user.type(textarea, 'Hello');
+    await user.keyboard('{Enter}');
+    expect(handleSubmit).toHaveBeenCalledWith('Hello');
+  });
+
+  it('disables all controls when disabled prop is true', () => {
+    renderPrompt({ disabled: true });
+    expect(screen.getByPlaceholderText('Ask something...')).toBeDisabled();
+    expect(screen.getByRole('button', { name: /attach file/i })).toBeDisabled();
+    expect(screen.getByRole('button', { name: /submit/i })).toBeDisabled();
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = renderPrompt();
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/RadioGroup/RadioGroup.fragment.tsx

@@ -40,6 +40,11 @@ export default defineSegment({
   },
 
   props: {
+    children: {
+      type: 'node',
+      description: 'RadioGroup.Item elements',
+      required: true,
+    },
     value: {
       type: 'string',
       description: 'Controlled selected value',

package/src/components/RadioGroup/RadioGroup.test.tsx

@@ -0,0 +1,105 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, userEvent, expectNoA11yViolations } from '../../test/utils';
+import { RadioGroup } from './index';
+
+describe('RadioGroup', () => {
+  it('renders a radiogroup role', () => {
+    render(
+      <RadioGroup label="Color">
+        <RadioGroup.Item value="red" label="Red" />
+        <RadioGroup.Item value="blue" label="Blue" />
+      </RadioGroup>
+    );
+    expect(screen.getByRole('radiogroup')).toBeInTheDocument();
+  });
+
+  it('renders radio items', () => {
+    render(
+      <RadioGroup label="Color">
+        <RadioGroup.Item value="red" label="Red" />
+        <RadioGroup.Item value="blue" label="Blue" />
+      </RadioGroup>
+    );
+    expect(screen.getAllByRole('radio')).toHaveLength(2);
+  });
+
+  it('selects a radio on click', async () => {
+    const user = userEvent.setup();
+    render(
+      <RadioGroup label="Color">
+        <RadioGroup.Item value="red" label="Red" />
+        <RadioGroup.Item value="blue" label="Blue" />
+      </RadioGroup>
+    );
+    const radios = screen.getAllByRole('radio');
+    await user.click(radios[1]);
+    expect(radios[1]).toBeChecked();
+  });
+
+  it('renders the group label', () => {
+    render(
+      <RadioGroup label="Choose a color">
+        <RadioGroup.Item value="red" label="Red" />
+      </RadioGroup>
+    );
+    expect(screen.getByText('Choose a color')).toBeInTheDocument();
+  });
+
+  it('sets defaultValue as the initially selected radio', () => {
+    render(
+      <RadioGroup label="Color" defaultValue="blue">
+        <RadioGroup.Item value="red" label="Red" />
+        <RadioGroup.Item value="blue" label="Blue" />
+      </RadioGroup>
+    );
+    const radios = screen.getAllByRole('radio');
+    expect(radios[1]).toBeChecked();
+  });
+
+  it('disables all items when disabled prop is set', () => {
+    render(
+      <RadioGroup label="Color" disabled>
+        <RadioGroup.Item value="red" label="Red" />
+        <RadioGroup.Item value="blue" label="Blue" />
+      </RadioGroup>
+    );
+    const radios = screen.getAllByRole('radio');
+    radios.forEach((radio) => expect(radio).toHaveAttribute('aria-disabled', 'true'));
+  });
+
+  it('disables individual items', () => {
+    render(
+      <RadioGroup label="Color">
+        <RadioGroup.Item value="red" label="Red" disabled />
+        <RadioGroup.Item value="blue" label="Blue" />
+      </RadioGroup>
+    );
+    const radios = screen.getAllByRole('radio');
+    expect(radios[0]).toHaveAttribute('aria-disabled', 'true');
+    expect(radios[1]).not.toHaveAttribute('aria-disabled', 'true');
+  });
+
+  it('calls onValueChange with the selected value', async () => {
+    const handleChange = vi.fn();
+    const user = userEvent.setup();
+    render(
+      <RadioGroup label="Color" onValueChange={handleChange}>
+        <RadioGroup.Item value="red" label="Red" />
+        <RadioGroup.Item value="blue" label="Blue" />
+      </RadioGroup>
+    );
+    await user.click(screen.getAllByRole('radio')[0]);
+    expect(handleChange).toHaveBeenCalled();
+    expect(handleChange.mock.calls[0][0]).toBe('red');
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(
+      <RadioGroup label="Accessible group">
+        <RadioGroup.Item value="a" label="Option A" />
+        <RadioGroup.Item value="b" label="Option B" />
+      </RadioGroup>
+    );
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/ScrollArea/ScrollArea.fragment.tsx

@@ -0,0 +1,185 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { ScrollArea } from '.';
+
+const tags = ['Tag 1', 'Tag 2', 'Tag 3', 'Tag 4', 'Tag 5', 'Tag 6', 'Tag 7', 'Tag 8', 'Tag 9', 'Tag 10', 'Tag 11', 'Tag 12', 'Tag 13', 'Tag 14', 'Tag 15'];
+
+export default defineSegment({
+  component: ScrollArea,
+
+  meta: {
+    name: 'ScrollArea',
+    description: 'A styled scrollable container with thin scrollbars and optional fade indicators.',
+    category: 'layout',
+    status: 'stable',
+    tags: ['scroll', 'overflow', 'scrollbar', 'container', 'layout'],
+    since: '0.4.0',
+  },
+
+  usage: {
+    when: [
+      'Content overflows its container and needs scrolling',
+      'Horizontal tab bars or chip lists that may overflow',
+      'Scrollable panels, sidebars, or dropdown content',
+      'Any area where native scrollbars look too heavy',
+    ],
+    whenNot: [
+      'Page-level scrolling (use native body scroll)',
+      'Very short content that never overflows',
+    ],
+    guidelines: [
+      'Use `orientation` to constrain scroll direction',
+      'Use `showFades` to hint at hidden content beyond the viewport',
+      'The `hover` scrollbar visibility keeps the UI clean until the user interacts',
+      'Combine with `orientation="horizontal"` for tab bars and chip rows',
+    ],
+    accessibility: [
+      'Preserves native scroll behavior and keyboard support',
+      'Scrollbar is visible on focus for keyboard users',
+      'Respects prefers-reduced-motion for fade transitions',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      description: 'Scrollable content',
+      required: true,
+    },
+    orientation: {
+      type: 'enum',
+      description: 'Scroll direction',
+      values: ['horizontal', 'vertical', 'both'],
+      default: 'vertical',
+    },
+    scrollbarVisibility: {
+      type: 'enum',
+      description: 'When to show the scrollbar',
+      values: ['auto', 'always', 'hover'],
+      default: 'auto',
+    },
+    showFades: {
+      type: 'boolean',
+      description: 'Show gradient fade indicators at scroll edges',
+      default: false,
+    },
+  },
+
+  contract: {
+    propsSummary: [
+      'orientation: horizontal|vertical|both - scroll direction',
+      'scrollbarVisibility: auto|always|hover - scrollbar display mode',
+      'showFades: boolean - gradient edge indicators',
+    ],
+    scenarioTags: ['layout.scroll', 'container.scroll'],
+    a11yRules: [],
+  },
+
+  ai: {
+    compositionPattern: 'wrapper',
+    requiredChildren: [],
+    commonPatterns: [
+      '<ScrollArea orientation="horizontal"><div style={{ display: "flex", gap: 8 }}>{items}</div></ScrollArea>',
+      '<ScrollArea style={{ height: 300 }}>{longContent}</ScrollArea>',
+    ],
+  },
+
+  variants: [
+    {
+      name: 'Vertical',
+      description: 'Vertical scrollable area with thin scrollbar.',
+      code: `<ScrollArea style={{ height: '200px' }}>
+  {/* Long content */}
+</ScrollArea>`,
+      render: () => (
+        <div style={{ height: '200px', width: '300px', border: '1px solid var(--fui-border)' }}>
+          <ScrollArea style={{ height: '200px' }}>
+            <div style={{ padding: '16px' }}>
+              {Array.from({ length: 20 }).map((_, i) => (
+                <p key={i} style={{ margin: '0 0 12px', color: 'var(--fui-text-secondary)', fontSize: '14px' }}>
+                  Item {i + 1} — Lorem ipsum dolor sit amet
+                </p>
+              ))}
+            </div>
+          </ScrollArea>
+        </div>
+      ),
+    },
+    {
+      name: 'Horizontal',
+      description: 'Horizontal scrollable area for overflowing inline content like tabs or chips.',
+      code: `<ScrollArea orientation="horizontal">
+  <div style={{ display: 'flex', gap: '8px' }}>
+    {tags.map(tag => <Chip key={tag}>{tag}</Chip>)}
+  </div>
+</ScrollArea>`,
+      render: () => (
+        <div style={{ width: '400px', border: '1px solid var(--fui-border)', borderRadius: '8px' }}>
+          <ScrollArea orientation="horizontal">
+            <div style={{ display: 'flex', gap: '8px', padding: '12px', whiteSpace: 'nowrap' }}>
+              {tags.map(tag => (
+                <span key={tag} style={{
+                  padding: '4px 12px',
+                  borderRadius: '16px',
+                  backgroundColor: 'var(--fui-bg-secondary)',
+                  color: 'var(--fui-text-secondary)',
+                  fontSize: '13px',
+                  flexShrink: 0,
+                }}>
+                  {tag}
+                </span>
+              ))}
+            </div>
+          </ScrollArea>
+        </div>
+      ),
+    },
+    {
+      name: 'With Fades',
+      description: 'Fade indicators show when content is scrollable in either direction.',
+      code: `<ScrollArea orientation="horizontal" showFades>
+  {/* Overflowing content */}
+</ScrollArea>`,
+      render: () => (
+        <div style={{ width: '400px', border: '1px solid var(--fui-border)', borderRadius: '8px' }}>
+          <ScrollArea orientation="horizontal" showFades>
+            <div style={{ display: 'flex', gap: '8px', padding: '12px', whiteSpace: 'nowrap' }}>
+              {tags.map(tag => (
+                <span key={tag} style={{
+                  padding: '4px 12px',
+                  borderRadius: '16px',
+                  backgroundColor: 'var(--fui-bg-secondary)',
+                  color: 'var(--fui-text-secondary)',
+                  fontSize: '13px',
+                  flexShrink: 0,
+                }}>
+                  {tag}
+                </span>
+              ))}
+            </div>
+          </ScrollArea>
+        </div>
+      ),
+    },
+    {
+      name: 'Hover Scrollbar',
+      description: 'Scrollbar is hidden until the user hovers over the scroll area.',
+      code: `<ScrollArea scrollbarVisibility="hover" style={{ height: '200px' }}>
+  {/* Content */}
+</ScrollArea>`,
+      render: () => (
+        <div style={{ height: '200px', width: '300px', border: '1px solid var(--fui-border)' }}>
+          <ScrollArea scrollbarVisibility="hover" style={{ height: '200px' }}>
+            <div style={{ padding: '16px' }}>
+              {Array.from({ length: 20 }).map((_, i) => (
+                <p key={i} style={{ margin: '0 0 12px', color: 'var(--fui-text-secondary)', fontSize: '14px' }}>
+                  Item {i + 1} — Hover to reveal scrollbar
+                </p>
+              ))}
+            </div>
+          </ScrollArea>
+        </div>
+      ),
+    },
+  ],
+});

package/src/components/ScrollArea/ScrollArea.module.scss

@@ -0,0 +1,136 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+// ============================================
+// ScrollArea Root
+// ============================================
+
+.root {
+  position: relative;
+  overflow: hidden;
+}
+
+// ============================================
+// Fade masks — applied to the viewport via CSS mask-image.
+// This fades out the actual content at the edges, which is
+// far more visible than overlaying a gradient pseudo-element.
+// ============================================
+
+.fadeMaskEnd {
+  &.horizontal {
+    mask-image: linear-gradient(to right, black calc(100% - 48px), transparent 100%);
+  }
+
+  &.vertical {
+    mask-image: linear-gradient(to bottom, black calc(100% - 32px), transparent 100%);
+  }
+
+  &.both {
+    mask-image: linear-gradient(to right, black calc(100% - 48px), transparent 100%);
+  }
+}
+
+.fadeMaskStart {
+  &.horizontal {
+    mask-image: linear-gradient(to left, black calc(100% - 48px), transparent 100%);
+  }
+
+  &.vertical {
+    mask-image: linear-gradient(to top, black calc(100% - 32px), transparent 100%);
+  }
+
+  &.both {
+    mask-image: linear-gradient(to left, black calc(100% - 48px), transparent 100%);
+  }
+}
+
+.fadeMaskBoth {
+  &.horizontal {
+    mask-image: linear-gradient(to right, transparent, black 48px, black calc(100% - 48px), transparent 100%);
+  }
+
+  &.vertical {
+    mask-image: linear-gradient(to bottom, transparent, black 32px, black calc(100% - 32px), transparent 100%);
+  }
+
+  &.both {
+    mask-image: linear-gradient(to right, transparent, black 48px, black calc(100% - 48px), transparent 100%);
+  }
+}
+
+// ============================================
+// Viewport (scrollable area)
+// ============================================
+
+.viewport {
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+  scrollbar-width: thin;
+  scrollbar-color: var(--fui-border-strong, $fui-border-strong) transparent;
+
+  // Webkit custom scrollbar
+  &::-webkit-scrollbar {
+    width: 6px;
+    height: 6px;
+  }
+
+  &::-webkit-scrollbar-track {
+    background: transparent;
+  }
+
+  &::-webkit-scrollbar-thumb {
+    background-color: var(--fui-border-strong, $fui-border-strong);
+    border-radius: var(--fui-radius-full, $fui-radius-full);
+
+    &:hover {
+      background-color: var(--fui-text-tertiary, $fui-text-tertiary);
+    }
+  }
+}
+
+// Orientation variants
+.horizontal {
+  overflow-x: auto;
+  overflow-y: hidden;
+}
+
+.vertical {
+  overflow-x: hidden;
+  overflow-y: auto;
+}
+
+.both {
+  overflow: auto;
+}
+
+// ============================================
+// Scrollbar visibility modes
+// ============================================
+
+// Always show scrollbar
+.scrollbarAlways {
+  &::-webkit-scrollbar-thumb {
+    background-color: var(--fui-border-strong, $fui-border-strong);
+  }
+}
+
+// Only show scrollbar on hover
+.scrollbarHover {
+  scrollbar-width: none;
+
+  &::-webkit-scrollbar {
+    width: 0;
+    height: 0;
+  }
+
+  &:hover {
+    scrollbar-width: thin;
+
+    &::-webkit-scrollbar {
+      width: 6px;
+      height: 6px;
+    }
+  }
+}
+

package/src/components/ScrollArea/ScrollArea.test.tsx

@@ -0,0 +1,38 @@
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { ScrollArea } from '.';
+
+describe('ScrollArea', () => {
+  it('renders children', () => {
+    render(<ScrollArea>Test content</ScrollArea>);
+    expect(screen.getByText('Test content')).toBeInTheDocument();
+  });
+
+  it('sets data-orientation attribute', () => {
+    const { container } = render(
+      <ScrollArea orientation="horizontal">Content</ScrollArea>
+    );
+    expect(container.firstChild).toHaveAttribute('data-orientation', 'horizontal');
+  });
+
+  it('defaults to vertical orientation', () => {
+    const { container } = render(<ScrollArea>Content</ScrollArea>);
+    expect(container.firstChild).toHaveAttribute('data-orientation', 'vertical');
+  });
+
+  it('passes through HTML attributes', () => {
+    render(
+      <ScrollArea data-testid="scroll-area" style={{ height: '200px' }}>
+        Content
+      </ScrollArea>
+    );
+    expect(screen.getByTestId('scroll-area')).toBeInTheDocument();
+  });
+
+  it('applies custom className', () => {
+    const { container } = render(
+      <ScrollArea className="custom-class">Content</ScrollArea>
+    );
+    expect(container.firstChild).toHaveClass('custom-class');
+  });
+});