@fragments-sdk/ui 0.1.0

package/src/components/Checkbox/Checkbox.fragment.tsx

@@ -0,0 +1,166 @@
+import React, { useState } from 'react';
+import { defineSegment } from '@fragments/core';
+import { Checkbox } from './index.js';
+
+// Stateful wrapper for interactive demos
+function StatefulCheckbox(props: React.ComponentProps<typeof Checkbox>) {
+  const [checked, setChecked] = useState(props.checked ?? props.defaultChecked ?? false);
+  return <Checkbox {...props} checked={checked} onCheckedChange={setChecked} />;
+}
+
+export default defineSegment({
+  component: Checkbox,
+
+  meta: {
+    name: 'Checkbox',
+    description: 'Binary toggle for form fields. Use for options that require explicit submission, unlike Toggle which takes effect immediately.',
+    category: 'forms',
+    status: 'stable',
+    tags: ['checkbox', 'form', 'boolean', 'selection', 'input'],
+    since: '0.1.0',
+  },
+
+  usage: {
+    when: [
+      'Form fields requiring explicit submission',
+      'Multi-select from a list of options',
+      'Terms and conditions acceptance',
+      'Filter or preference checklists',
+    ],
+    whenNot: [
+      'Immediate effect settings (use Toggle)',
+      'Single selection from options (use RadioGroup)',
+      'Selecting from many options (use Select)',
+    ],
+    guidelines: [
+      'Always include a visible label',
+      'Use description for additional context when needed',
+      'Group related checkboxes visually',
+      'Use indeterminate state for parent/child relationships',
+    ],
+    accessibility: [
+      'Proper label association',
+      'Keyboard accessible (Space to toggle)',
+      'Visible focus indicator',
+      'Indeterminate state properly announced',
+    ],
+  },
+
+  props: {
+    checked: {
+      type: 'boolean',
+      description: 'Controlled checked state',
+    },
+    defaultChecked: {
+      type: 'boolean',
+      description: 'Default checked state (uncontrolled)',
+    },
+    onCheckedChange: {
+      type: 'function',
+      description: 'Called when checked state changes',
+    },
+    indeterminate: {
+      type: 'boolean',
+      description: 'Indeterminate state (partial selection)',
+      default: 'false',
+    },
+    disabled: {
+      type: 'boolean',
+      description: 'Disable the checkbox',
+      default: 'false',
+    },
+    label: {
+      type: 'string',
+      description: 'Label text',
+    },
+    description: {
+      type: 'string',
+      description: 'Description text below the label',
+    },
+    size: {
+      type: 'enum',
+      description: 'Checkbox size',
+      values: ['sm', 'md', 'lg'],
+      default: 'md',
+    },
+  },
+
+  relations: [
+    { component: 'Toggle', relationship: 'alternative', note: 'Use Toggle for immediate-effect settings' },
+    { component: 'Input', relationship: 'sibling', note: 'Checkbox handles boolean; Input handles text' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'checked: boolean - controlled checked state',
+      'onCheckedChange: (checked) => void - change handler',
+      'indeterminate: boolean - partial selection state',
+      'label: string - checkbox label',
+      'description: string - helper text',
+    ],
+    scenarioTags: [
+      'form.checkbox',
+      'form.boolean',
+      'selection.multi',
+    ],
+    a11yRules: ['A11Y_CHECKBOX_LABEL', 'A11Y_CHECKBOX_FOCUS'],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Basic checkbox with label',
+      render: () => <StatefulCheckbox label="Accept terms and conditions" />,
+    },
+    {
+      name: 'With Description',
+      description: 'Checkbox with helper text',
+      render: () => (
+        <StatefulCheckbox
+          label="Email notifications"
+          description="Receive email updates about your account activity"
+        />
+      ),
+    },
+    {
+      name: 'Checked',
+      description: 'Pre-checked checkbox',
+      render: () => <StatefulCheckbox defaultChecked label="Subscribe to newsletter" />,
+    },
+    {
+      name: 'Indeterminate',
+      description: 'Partial selection state',
+      render: () => (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+          <Checkbox indeterminate label="Select all" />
+          <div style={{ marginLeft: '24px', display: 'flex', flexDirection: 'column', gap: '8px' }}>
+            <StatefulCheckbox defaultChecked label="Option 1" />
+            <StatefulCheckbox label="Option 2" />
+            <StatefulCheckbox defaultChecked label="Option 3" />
+          </div>
+        </div>
+      ),
+    },
+    {
+      name: 'Sizes',
+      description: 'Available size options',
+      render: () => (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+          <StatefulCheckbox size="sm" label="Small checkbox" />
+          <StatefulCheckbox size="md" label="Medium checkbox" />
+          <StatefulCheckbox size="lg" label="Large checkbox" />
+        </div>
+      ),
+    },
+    {
+      name: 'Disabled',
+      description: 'Non-interactive states',
+      render: () => (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+          <Checkbox disabled label="Disabled unchecked" />
+          <Checkbox disabled checked label="Disabled checked" />
+        </div>
+      ),
+    },
+  ],
+});

package/src/components/Checkbox/Checkbox.module.scss

@@ -0,0 +1,144 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+// Wrapper for checkbox + label
+.wrapper {
+  display: inline-flex;
+  align-items: flex-start;
+  gap: var(--fui-space-2, $fui-space-2);
+  cursor: pointer;
+  font-family: var(--fui-font-sans, $fui-font-sans);
+
+  &[data-disabled] {
+    cursor: not-allowed;
+    opacity: 0.5;
+  }
+}
+
+// The checkbox box itself
+.checkbox {
+  @include interactive-base;
+
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 1rem;
+  height: 1rem;
+  margin-top: 2px; // Align with text baseline
+  background-color: var(--fui-bg-elevated, $fui-bg-elevated);
+  border: 1px solid var(--fui-border-strong, $fui-border-strong);
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+  cursor: inherit;
+
+  &:hover:not([data-disabled]) {
+    border-color: var(--fui-text-tertiary, $fui-text-tertiary);
+  }
+
+  &[data-checked],
+  &[data-indeterminate] {
+    background-color: var(--fui-color-accent, $fui-color-accent);
+    border-color: var(--fui-color-accent, $fui-color-accent);
+  }
+
+  &[data-checked]:hover:not([data-disabled]),
+  &[data-indeterminate]:hover:not([data-disabled]) {
+    background-color: var(--fui-color-accent-hover, $fui-color-accent-hover);
+    border-color: var(--fui-color-accent-hover, $fui-color-accent-hover);
+  }
+
+  &[data-invalid] {
+    border-color: var(--fui-color-danger, $fui-color-danger);
+  }
+
+  &[data-invalid][data-checked],
+  &[data-invalid][data-indeterminate] {
+    background-color: var(--fui-color-danger, $fui-color-danger);
+    border-color: var(--fui-color-danger, $fui-color-danger);
+  }
+}
+
+// Size variants
+.sm {
+  width: 0.875rem;
+  height: 0.875rem;
+  border-radius: 3px;
+  margin-top: 3px;
+}
+
+.md {
+  // Default size
+}
+
+.lg {
+  width: 1.25rem;
+  height: 1.25rem;
+  margin-top: 0;
+}
+
+// Indicator (checkmark or dash)
+.indicator {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--fui-text-inverse, $fui-text-inverse);
+
+  svg {
+    width: 0.75rem;
+    height: 0.75rem;
+  }
+
+  // Animation
+  opacity: 0;
+  transform: scale(0.8);
+  transition:
+    opacity var(--fui-transition-fast, $fui-transition-fast),
+    transform var(--fui-transition-fast, $fui-transition-fast);
+
+  [data-checked] > &,
+  [data-indeterminate] > & {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+
+// Size variant indicators
+.sm .indicator svg {
+  width: 0.625rem;
+  height: 0.625rem;
+}
+
+.lg .indicator svg {
+  width: 0.875rem;
+  height: 0.875rem;
+}
+
+// Label content
+.content {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.label {
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  color: var(--fui-text-primary, $fui-text-primary);
+  line-height: var(--fui-line-height-tight, $fui-line-height-tight);
+  user-select: none;
+}
+
+.labelSm {
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+}
+
+.labelLg {
+  font-size: var(--fui-font-size-base, $fui-font-size-base);
+}
+
+.description {
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+}

package/src/components/Checkbox/index.tsx

@@ -0,0 +1,166 @@
+import * as React from 'react';
+import { Checkbox as BaseCheckbox } from '@base-ui/react/checkbox';
+import styles from './Checkbox.module.scss';
+// Import globals to ensure CSS variables are defined
+import '../../styles/globals.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export interface CheckboxProps {
+  /** Whether the checkbox is checked */
+  checked?: boolean;
+  /** Default checked state (uncontrolled) */
+  defaultChecked?: boolean;
+  /** Callback when checked state changes */
+  onCheckedChange?: (checked: boolean) => void;
+  /** Whether the checkbox is in an indeterminate state */
+  indeterminate?: boolean;
+  /** Whether the checkbox is disabled */
+  disabled?: boolean;
+  /** Whether the checkbox is required */
+  required?: boolean;
+  /** Size variant */
+  size?: 'sm' | 'md' | 'lg';
+  /** Label text */
+  label?: string;
+  /** Description text below the label */
+  description?: string;
+  /** Name attribute for form submission */
+  name?: string;
+  /** Value attribute for form submission */
+  value?: string;
+  /** Additional class name */
+  className?: string;
+  /** ID for the checkbox input */
+  id?: string;
+}
+
+// ============================================
+// Icons
+// ============================================
+
+function CheckIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="3"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <polyline points="20 6 9 17 4 12" />
+    </svg>
+  );
+}
+
+function MinusIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="3"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <line x1="5" y1="12" x2="19" y2="12" />
+    </svg>
+  );
+}
+
+// ============================================
+// Component
+// ============================================
+
+export const Checkbox = React.forwardRef<HTMLButtonElement, CheckboxProps>(
+  function Checkbox(
+    {
+      checked,
+      defaultChecked,
+      onCheckedChange,
+      indeterminate = false,
+      disabled = false,
+      required = false,
+      size = 'md',
+      label,
+      description,
+      name,
+      value,
+      className,
+      id,
+    },
+    ref
+  ) {
+    const checkboxClasses = [
+      styles.checkbox,
+      size === 'sm' && styles.sm,
+      size === 'lg' && styles.lg,
+    ].filter(Boolean).join(' ');
+
+    const labelClasses = [
+      styles.label,
+      size === 'sm' && styles.labelSm,
+      size === 'lg' && styles.labelLg,
+    ].filter(Boolean).join(' ');
+
+    const wrapperClasses = [styles.wrapper, className].filter(Boolean).join(' ');
+
+    // If no label/description, render just the checkbox
+    if (!label && !description) {
+      return (
+        <BaseCheckbox.Root
+          ref={ref}
+          checked={checked}
+          defaultChecked={defaultChecked}
+          onCheckedChange={onCheckedChange}
+          indeterminate={indeterminate}
+          disabled={disabled}
+          required={required}
+          name={name}
+          value={value}
+          id={id}
+          className={[checkboxClasses, className].filter(Boolean).join(' ')}
+        >
+          <BaseCheckbox.Indicator className={styles.indicator} keepMounted>
+            {indeterminate ? <MinusIcon /> : <CheckIcon />}
+          </BaseCheckbox.Indicator>
+        </BaseCheckbox.Root>
+      );
+    }
+
+    return (
+      <label className={wrapperClasses} data-disabled={disabled || undefined}>
+        <BaseCheckbox.Root
+          ref={ref}
+          checked={checked}
+          defaultChecked={defaultChecked}
+          onCheckedChange={onCheckedChange}
+          indeterminate={indeterminate}
+          disabled={disabled}
+          required={required}
+          name={name}
+          value={value}
+          id={id}
+          className={checkboxClasses}
+        >
+          <BaseCheckbox.Indicator className={styles.indicator} keepMounted>
+            {indeterminate ? <MinusIcon /> : <CheckIcon />}
+          </BaseCheckbox.Indicator>
+        </BaseCheckbox.Root>
+        <div className={styles.content}>
+          <span className={labelClasses}>{label}</span>
+          {description && (
+            <span className={styles.description}>{description}</span>
+          )}
+        </div>
+      </label>
+    );
+  }
+);

package/src/components/Dialog/Dialog.fragment.tsx

@@ -0,0 +1,179 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Dialog } from './index.js';
+import { Button } from '../Button/index.js';
+
+export default defineSegment({
+  component: Dialog,
+
+  meta: {
+    name: 'Dialog',
+    description: 'Modal overlay for focused user interactions. Use for confirmations, forms, or content requiring full attention.',
+    category: 'overlays',
+    status: 'stable',
+    tags: ['modal', 'dialog', 'overlay', 'popup', 'confirmation'],
+    since: '0.1.0',
+  },
+
+  usage: {
+    when: [
+      'Confirming destructive actions (delete, discard changes)',
+      'Collecting focused input (forms, settings)',
+      'Displaying content that requires acknowledgment',
+      'Multi-step workflows that need isolation',
+    ],
+    whenNot: [
+      'Simple tooltips or hints (use Tooltip)',
+      'Contextual menus (use Menu or Popover)',
+      'Non-blocking notifications (use Toast or Alert)',
+      'Simple confirmation that can be inline (use Alert)',
+    ],
+    guidelines: [
+      'Keep dialog content focused on a single task',
+      'Provide clear primary and secondary actions',
+      'Use descriptive title that explains the purpose',
+      'Allow dismissal via backdrop click or close button for non-critical dialogs',
+      'Trap focus within the dialog for accessibility',
+    ],
+    accessibility: [
+      'Automatically traps focus within the dialog',
+      'Closes on Escape key press',
+      'Returns focus to trigger element on close',
+      'Uses role="dialog" with proper aria attributes',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      description: 'Dialog content (use Dialog.Content, Dialog.Header, etc.)',
+      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 to render as modal (blocks interaction with rest of page)',
+      default: 'true',
+    },
+  },
+
+  relations: [
+    { component: 'Popover', relationship: 'alternative', note: 'Use Popover for non-modal contextual content' },
+    { component: 'Menu', relationship: 'alternative', note: 'Use Menu for action lists' },
+    { component: 'Alert', relationship: 'sibling', note: 'Use Alert for inline notifications' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'open: boolean - controlled open state',
+      'onOpenChange: (open) => void - open state handler',
+      'modal: boolean - blocks page interaction (default: true)',
+      'Dialog.Content size: sm|md|lg|xl|full - dialog width',
+    ],
+    scenarioTags: [
+      'overlay.modal',
+      'form.dialog',
+      'action.confirm',
+      'workflow.step',
+    ],
+    a11yRules: ['A11Y_DIALOG_FOCUS', 'A11Y_DIALOG_ESCAPE', 'A11Y_DIALOG_LABEL'],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Basic dialog with header, body, and footer',
+      render: () => (
+        <Dialog>
+          <Dialog.Trigger asChild>
+            <Button>Open Dialog</Button>
+          </Dialog.Trigger>
+          <Dialog.Content>
+            <Dialog.Close />
+            <Dialog.Header>
+              <Dialog.Title>Dialog Title</Dialog.Title>
+              <Dialog.Description>
+                A brief description of what this dialog is for.
+              </Dialog.Description>
+            </Dialog.Header>
+            <Dialog.Body>
+              <p>Dialog content goes here. You can include forms, text, or any other content.</p>
+            </Dialog.Body>
+            <Dialog.Footer>
+              <Dialog.Close asChild>
+                <Button variant="secondary">Cancel</Button>
+              </Dialog.Close>
+              <Button variant="primary">Confirm</Button>
+            </Dialog.Footer>
+          </Dialog.Content>
+        </Dialog>
+      ),
+    },
+    {
+      name: 'Confirmation',
+      description: 'Destructive action confirmation',
+      render: () => (
+        <Dialog>
+          <Dialog.Trigger asChild>
+            <Button variant="danger">Delete Item</Button>
+          </Dialog.Trigger>
+          <Dialog.Content size="sm">
+            <Dialog.Header>
+              <Dialog.Title>Delete item?</Dialog.Title>
+              <Dialog.Description>
+                This action cannot be undone. The item will be permanently removed.
+              </Dialog.Description>
+            </Dialog.Header>
+            <Dialog.Footer>
+              <Dialog.Close asChild>
+                <Button variant="secondary">Cancel</Button>
+              </Dialog.Close>
+              <Button variant="danger">Delete</Button>
+            </Dialog.Footer>
+          </Dialog.Content>
+        </Dialog>
+      ),
+    },
+    {
+      name: 'Large',
+      description: 'Large dialog for complex content',
+      render: () => (
+        <Dialog>
+          <Dialog.Trigger asChild>
+            <Button>Open Large Dialog</Button>
+          </Dialog.Trigger>
+          <Dialog.Content size="lg">
+            <Dialog.Close />
+            <Dialog.Header>
+              <Dialog.Title>Settings</Dialog.Title>
+              <Dialog.Description>
+                Configure your application preferences.
+              </Dialog.Description>
+            </Dialog.Header>
+            <Dialog.Body>
+              <p>This dialog has more space for complex forms or content layouts.</p>
+            </Dialog.Body>
+            <Dialog.Footer>
+              <Dialog.Close asChild>
+                <Button variant="secondary">Cancel</Button>
+              </Dialog.Close>
+              <Button variant="primary">Save Changes</Button>
+            </Dialog.Footer>
+          </Dialog.Content>
+        </Dialog>
+      ),
+    },
+  ],
+});