@fragments-sdk/ui 0.1.0

package/src/components/EmptyState/EmptyState.module.scss

@@ -0,0 +1,120 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+.emptyState {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  text-align: center;
+  font-family: var(--fui-font-sans, $fui-font-sans);
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+// Size variants
+.sm {
+  padding: var(--fui-space-6, $fui-space-6) var(--fui-space-4, $fui-space-4);
+
+  .title {
+    font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  }
+
+  .description {
+    font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+    max-width: 240px;
+  }
+
+  .icon {
+    margin-bottom: var(--fui-space-2, $fui-space-2);
+  }
+
+  .actions {
+    margin-top: var(--fui-space-3, $fui-space-3);
+  }
+}
+
+.md {
+  padding: var(--fui-space-10, $fui-space-10) var(--fui-space-6, $fui-space-6);
+
+  .title {
+    font-size: var(--fui-font-size-base, $fui-font-size-base);
+  }
+
+  .description {
+    font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+    max-width: 320px;
+  }
+
+  .icon {
+    margin-bottom: var(--fui-space-3, $fui-space-3);
+  }
+
+  .actions {
+    margin-top: var(--fui-space-4, $fui-space-4);
+  }
+}
+
+.lg {
+  padding: var(--fui-space-12, $fui-space-12) var(--fui-space-8, $fui-space-8);
+
+  .title {
+    font-size: var(--fui-font-size-lg, $fui-font-size-lg);
+  }
+
+  .description {
+    font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+    max-width: 400px;
+  }
+
+  .icon {
+    margin-bottom: var(--fui-space-4, $fui-space-4);
+  }
+
+  .actions {
+    margin-top: var(--fui-space-6, $fui-space-6);
+  }
+}
+
+.icon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
+
+  // Icon sizing based on parent size variant
+  svg {
+    width: 32px;
+    height: 32px;
+  }
+
+  .lg & svg {
+    width: 40px;
+    height: 40px;
+  }
+
+  .sm & svg {
+    width: 24px;
+    height: 24px;
+  }
+}
+
+.title {
+  margin: 0;
+  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
+  color: var(--fui-text-primary, $fui-text-primary);
+  line-height: var(--fui-line-height-tight, $fui-line-height-tight);
+}
+
+.description {
+  margin: var(--fui-space-2, $fui-space-2) 0 0;
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+}
+
+.actions {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-2, $fui-space-2);
+  flex-wrap: wrap;
+  justify-content: center;
+}

package/src/components/EmptyState/index.tsx

@@ -0,0 +1,80 @@
+import * as React from 'react';
+import { Button } from '../Button';
+import styles from './EmptyState.module.scss';
+// Import globals to ensure CSS variables are defined
+import '../../styles/globals.scss';
+
+export interface EmptyStateAction {
+  /** Button label */
+  label: string;
+  /** Click handler */
+  onClick: () => void;
+  /** Button variant */
+  variant?: 'primary' | 'secondary';
+}
+
+export interface EmptyStateProps {
+  /** Main heading */
+  title: string;
+  /** Supporting description */
+  description?: string;
+  /** Optional icon element */
+  icon?: React.ReactNode;
+  /** Primary action */
+  action?: EmptyStateAction;
+  /** Secondary action */
+  secondaryAction?: EmptyStateAction;
+  /** Size variant */
+  size?: 'sm' | 'md' | 'lg';
+  /** Additional class name */
+  className?: string;
+}
+
+export const EmptyState = React.forwardRef<HTMLDivElement, EmptyStateProps>(
+  function EmptyState(
+    {
+      title,
+      description,
+      icon,
+      action,
+      secondaryAction,
+      size = 'md',
+      className,
+    },
+    ref
+  ) {
+    const classes = [styles.emptyState, styles[size], className]
+      .filter(Boolean)
+      .join(' ');
+
+    return (
+      <div ref={ref} className={classes}>
+        {icon && <div className={styles.icon}>{icon}</div>}
+        <h3 className={styles.title}>{title}</h3>
+        {description && <p className={styles.description}>{description}</p>}
+        {(action || secondaryAction) && (
+          <div className={styles.actions}>
+            {action && (
+              <Button
+                variant={action.variant ?? 'primary'}
+                onClick={action.onClick}
+                size={size === 'sm' ? 'sm' : 'md'}
+              >
+                {action.label}
+              </Button>
+            )}
+            {secondaryAction && (
+              <Button
+                variant={secondaryAction.variant ?? 'secondary'}
+                onClick={secondaryAction.onClick}
+                size={size === 'sm' ? 'sm' : 'md'}
+              >
+                {secondaryAction.label}
+              </Button>
+            )}
+          </div>
+        )}
+      </div>
+    );
+  }
+);

package/src/components/Input/Input.fragment.tsx

@@ -0,0 +1,174 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Input } from './index.js';
+
+export default defineSegment({
+  component: Input,
+
+  meta: {
+    name: 'Input',
+    description: 'Text input field for single-line user data entry',
+    category: 'forms',
+    status: 'stable',
+    tags: ['form', 'input', 'text'],
+  },
+
+  usage: {
+    when: [
+      'Collecting single-line text data from users',
+      'Email, password, phone number, or URL input',
+      'Search fields',
+      'Short form fields (name, title, etc.)',
+    ],
+    whenNot: [
+      'Multi-line text (use Textarea)',
+      'Selecting from predefined options (use Select)',
+      'Boolean input (use Checkbox or Switch)',
+      'Date/time input (use DatePicker)',
+    ],
+    guidelines: [
+      'Always provide a label for accessibility',
+      'Use appropriate input type for data validation',
+      'Show validation errors with error prop and helperText',
+      'Use placeholder for format hints, not labels',
+    ],
+    accessibility: [
+      'Labels must be associated with inputs',
+      'Error messages should be announced to screen readers',
+      'Required fields should be indicated',
+    ],
+  },
+
+  props: {
+    value: {
+      type: 'string',
+      description: 'Current input value (controlled)',
+    },
+    placeholder: {
+      type: 'string',
+      description: 'Placeholder text shown when empty',
+      constraints: ['Use for format hints only, not as a replacement for labels'],
+    },
+    type: {
+      type: 'enum',
+      values: ['text', 'email', 'password', 'number', 'tel', 'url'],
+      default: 'text',
+      description: 'HTML input type for validation and keyboard',
+    },
+    disabled: {
+      type: 'boolean',
+      default: false,
+      description: 'Whether the input is interactive',
+    },
+    error: {
+      type: 'boolean',
+      default: false,
+      description: 'Whether to show error styling',
+    },
+    label: {
+      type: 'string',
+      description: 'Label text displayed above input',
+    },
+    helperText: {
+      type: 'string',
+      description: 'Helper or error message below input',
+    },
+    onChange: {
+      type: 'function',
+      description: 'Called with new value on change',
+    },
+  },
+
+  relations: [
+    {
+      component: 'Textarea',
+      relationship: 'alternative',
+      note: 'Use Textarea for multi-line text input',
+    },
+    {
+      component: 'Select',
+      relationship: 'alternative',
+      note: 'Use Select when choosing from predefined options',
+    },
+    {
+      component: 'FormField',
+      relationship: 'parent',
+      note: 'Wrap in FormField for consistent form layout',
+    },
+  ],
+
+  contract: {
+    propsSummary: [
+      'type: text|email|password|number|tel|url (default: text)',
+      'value: string - controlled input value',
+      'label: string - accessible label text',
+      'placeholder: string - format hint only',
+      'disabled: boolean - disables interaction',
+      'error: boolean - shows error styling',
+      'helperText: string - helper/error message',
+    ],
+    scenarioTags: [
+      'form.input',
+      'form.text',
+      'form.email',
+      'form.password',
+      'form.search',
+    ],
+    a11yRules: [
+      'A11Y_INPUT_LABEL',
+      'A11Y_INPUT_ERROR',
+      'A11Y_INPUT_REQUIRED',
+    ],
+    bans: [
+      {
+        pattern: 'placeholder=.*label',
+        message: 'Use label prop for labels, not placeholder',
+      },
+    ],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Basic text input',
+      render: () => <Input label="Name" placeholder="Enter your name" />,
+    },
+    {
+      name: 'With Value',
+      description: 'Input with pre-filled value',
+      render: () => <Input label="Email" type="email" value="user@example.com" />,
+    },
+    {
+      name: 'With Helper',
+      description: 'Input with helper text',
+      render: () => (
+        <Input
+          label="Password"
+          type="password"
+          placeholder="Create a password"
+          helperText="Must be at least 8 characters"
+        />
+      ),
+    },
+    {
+      name: 'Error State',
+      description: 'Input showing validation error',
+      render: () => (
+        <Input
+          label="Email"
+          type="email"
+          value="invalid-email"
+          error
+          helperText="Please enter a valid email address"
+        />
+      ),
+    },
+    {
+      name: 'Disabled',
+      description: 'Non-interactive input',
+      render: () => (
+        <Input label="Username" value="readonly-user" disabled />
+      ),
+    },
+  ],
+});

package/src/components/Input/Input.module.scss

@@ -0,0 +1,64 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+.wrapper {
+  display: flex;
+  flex-direction: column;
+}
+
+.label {
+  @include label-text;
+  margin-bottom: var(--fui-space-1, $fui-space-1);
+}
+
+.input {
+  @include text-base;
+  @include interactive-base;
+
+  display: block;
+  width: 100%;
+  height: var(--fui-input-height, $fui-input-height);
+  padding: 0 var(--fui-space-3, $fui-space-3);
+  background-color: var(--fui-bg-elevated, $fui-bg-elevated);
+  border: 1px solid var(--fui-border-strong, $fui-border-strong);
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+
+  &::placeholder {
+    color: var(--fui-text-tertiary, $fui-text-tertiary);
+  }
+
+  &:hover:not(:disabled):not(:focus) {
+    border-color: var(--fui-text-tertiary, $fui-text-tertiary);
+  }
+
+  &:focus {
+    @include focus-ring;
+    border-color: var(--fui-color-accent, $fui-color-accent);
+  }
+
+  &:disabled,
+  &[data-disabled] {
+    background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+    color: var(--fui-text-tertiary, $fui-text-tertiary);
+  }
+}
+
+.error {
+  border-color: var(--fui-color-danger, $fui-color-danger);
+
+  &:focus {
+    border-color: var(--fui-color-danger, $fui-color-danger);
+    box-shadow:
+      0 0 0 var(--fui-focus-ring-offset, $fui-focus-ring-offset) var(--fui-bg-primary, $fui-bg-primary),
+      0 0 0 calc(var(--fui-focus-ring-offset, $fui-focus-ring-offset) + var(--fui-focus-ring-width, $fui-focus-ring-width)) var(--fui-color-danger, $fui-color-danger);
+  }
+}
+
+.helper {
+  @include helper-text;
+  margin-top: var(--fui-space-1, $fui-space-1);
+}
+
+.helperError {
+  color: var(--fui-color-danger, $fui-color-danger);
+}

package/src/components/Input/index.tsx

@@ -0,0 +1,76 @@
+import * as React from 'react';
+import { Field } from '@base-ui/react/field';
+import styles from './Input.module.scss';
+// Import globals to ensure CSS variables are defined
+import '../../styles/globals.scss';
+
+export interface InputProps {
+  value?: string;
+  defaultValue?: string;
+  placeholder?: string;
+  type?: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url';
+  disabled?: boolean;
+  error?: boolean;
+  label?: string;
+  helperText?: string;
+  onChange?: (value: string) => void;
+  onBlur?: () => void;
+  className?: string;
+  name?: string;
+  id?: string;
+}
+
+export const Input = React.forwardRef<HTMLInputElement, InputProps>(
+  function Input(
+    {
+      value,
+      defaultValue,
+      placeholder,
+      type = 'text',
+      disabled = false,
+      error = false,
+      label,
+      helperText,
+      onChange,
+      onBlur,
+      className,
+      name,
+      id,
+    },
+    ref
+  ) {
+    const inputClasses = [styles.input, error && styles.error, className]
+      .filter(Boolean)
+      .join(' ');
+
+    const helperClasses = [styles.helper, error && styles.helperError]
+      .filter(Boolean)
+      .join(' ');
+
+    return (
+      <Field.Root disabled={disabled} invalid={error} className={styles.wrapper}>
+        {label && <Field.Label className={styles.label}>{label}</Field.Label>}
+        <Field.Control
+          ref={ref}
+          type={type}
+          value={value}
+          defaultValue={defaultValue}
+          placeholder={placeholder}
+          name={name}
+          id={id}
+          onChange={(e: React.ChangeEvent<HTMLInputElement>) =>
+            onChange?.(e.target.value)
+          }
+          onBlur={onBlur}
+          className={inputClasses}
+          render={<input />}
+        />
+        {helperText && (
+          <Field.Description className={helperClasses}>
+            {helperText}
+          </Field.Description>
+        )}
+      </Field.Root>
+    );
+  }
+);

package/src/components/Menu/Menu.fragment.tsx

@@ -0,0 +1,168 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Menu } from './index.js';
+import { Button } from '../Button/index.js';
+
+export default defineSegment({
+  component: Menu,
+
+  meta: {
+    name: 'Menu',
+    description: 'Dropdown menu for actions and commands. Use for contextual actions, overflow menus, or grouped commands.',
+    category: 'overlays',
+    status: 'stable',
+    tags: ['menu', 'dropdown', 'actions', 'context-menu', 'commands'],
+    since: '0.1.0',
+  },
+
+  usage: {
+    when: [
+      'Overflow actions that dont fit in the toolbar',
+      'Context menus (right-click)',
+      'User account menus',
+      'Grouped actions with separators',
+    ],
+    whenNot: [
+      'Selecting from options (use Select)',
+      'Navigation (use Tabs or navigation components)',
+      'Form selection (use Select or RadioGroup)',
+    ],
+    guidelines: [
+      'Group related actions with Menu.Group',
+      'Use separators to divide action categories',
+      'Include keyboard shortcuts where applicable',
+      'Use danger variant for destructive actions',
+      'Keep menu items under 10-12 for usability',
+    ],
+    accessibility: [
+      'Full keyboard navigation with arrow keys',
+      'Type-ahead search for items',
+      'Focus returns to trigger on close',
+      'Proper ARIA menu roles',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      description: 'Menu trigger and content',
+      required: true,
+    },
+    open: {
+      type: 'boolean',
+      description: 'Controlled open state',
+    },
+    defaultOpen: {
+      type: 'boolean',
+      description: 'Default open state (uncontrolled)',
+      default: 'false',
+    },
+    onOpenChange: {
+      type: 'function',
+      description: 'Called when open state changes',
+    },
+    modal: {
+      type: 'boolean',
+      description: 'Whether menu is modal',
+      default: 'true',
+    },
+  },
+
+  relations: [
+    { component: 'Select', relationship: 'alternative', note: 'Use Select for form field selection' },
+    { component: 'Popover', relationship: 'alternative', note: 'Use Popover for rich non-action content' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'open: boolean - controlled open state',
+      'onOpenChange: (open) => void - state handler',
+      'Menu.Item danger: boolean - destructive styling',
+      'Menu.Item shortcut: string - keyboard shortcut text',
+    ],
+    scenarioTags: [
+      'action.menu',
+      'action.overflow',
+      'navigation.context',
+    ],
+    a11yRules: ['A11Y_MENU_KEYBOARD', 'A11Y_MENU_ROLE'],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Basic dropdown menu',
+      render: () => (
+        <Menu>
+          <Menu.Trigger asChild>
+            <Button variant="secondary">Actions</Button>
+          </Menu.Trigger>
+          <Menu.Content>
+            <Menu.Item onSelect={() => {}}>Edit</Menu.Item>
+            <Menu.Item onSelect={() => {}}>Duplicate</Menu.Item>
+            <Menu.Separator />
+            <Menu.Item danger onSelect={() => {}}>Delete</Menu.Item>
+          </Menu.Content>
+        </Menu>
+      ),
+    },
+    {
+      name: 'With Shortcuts',
+      description: 'Menu items with keyboard shortcuts',
+      render: () => (
+        <Menu>
+          <Menu.Trigger asChild>
+            <Button variant="secondary">Edit</Button>
+          </Menu.Trigger>
+          <Menu.Content>
+            <Menu.Item shortcut="Ctrl+Z" onSelect={() => {}}>Undo</Menu.Item>
+            <Menu.Item shortcut="Ctrl+Y" onSelect={() => {}}>Redo</Menu.Item>
+            <Menu.Separator />
+            <Menu.Item shortcut="Ctrl+C" onSelect={() => {}}>Copy</Menu.Item>
+            <Menu.Item shortcut="Ctrl+V" onSelect={() => {}}>Paste</Menu.Item>
+          </Menu.Content>
+        </Menu>
+      ),
+    },
+    {
+      name: 'With Groups',
+      description: 'Menu with labeled groups',
+      render: () => (
+        <Menu>
+          <Menu.Trigger asChild>
+            <Button variant="secondary">Options</Button>
+          </Menu.Trigger>
+          <Menu.Content>
+            <Menu.Group>
+              <Menu.GroupLabel>View</Menu.GroupLabel>
+              <Menu.Item onSelect={() => {}}>Zoom In</Menu.Item>
+              <Menu.Item onSelect={() => {}}>Zoom Out</Menu.Item>
+            </Menu.Group>
+            <Menu.Separator />
+            <Menu.Group>
+              <Menu.GroupLabel>Layout</Menu.GroupLabel>
+              <Menu.Item onSelect={() => {}}>Grid View</Menu.Item>
+              <Menu.Item onSelect={() => {}}>List View</Menu.Item>
+            </Menu.Group>
+          </Menu.Content>
+        </Menu>
+      ),
+    },
+    {
+      name: 'With Checkboxes',
+      description: 'Menu with toggleable options',
+      render: () => (
+        <Menu>
+          <Menu.Trigger asChild>
+            <Button variant="secondary">Display</Button>
+          </Menu.Trigger>
+          <Menu.Content>
+            <Menu.CheckboxItem defaultChecked>Show Grid</Menu.CheckboxItem>
+            <Menu.CheckboxItem defaultChecked>Show Rulers</Menu.CheckboxItem>
+            <Menu.CheckboxItem>Show Guides</Menu.CheckboxItem>
+          </Menu.Content>
+        </Menu>
+      ),
+    },
+  ],
+});