@fragments-sdk/ui 0.4.0 → 0.6.0

package/src/components/ColorPicker/ColorPicker.fragment.tsx

@@ -0,0 +1,196 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { ColorPicker } from '.';
+
+export default defineSegment({
+  component: ColorPicker,
+
+  meta: {
+    name: 'ColorPicker',
+    description: 'Color selection control with hex input and visual picker. Displays a swatch that opens a full color picker on click.',
+    category: 'forms',
+    status: 'stable',
+    tags: ['color', 'picker', 'input', 'hex', 'swatch', 'theme'],
+    since: '0.2.0',
+  },
+
+  usage: {
+    when: [
+      'Theme customization interfaces',
+      'Brand color selection',
+      'Design tool color inputs',
+      'User preference settings for colors',
+    ],
+    whenNot: [
+      'Predefined color options only (use RadioGroup with swatches)',
+      'Simple color display without editing (use a colored Badge)',
+      'Color indication only (use semantic color tokens)',
+    ],
+    guidelines: [
+      'Always provide a label to describe what the color is for',
+      'Use description to explain color usage or constraints',
+      'Consider providing color presets alongside the picker for common choices',
+      'Validate hex format (#RRGGBB) on input',
+    ],
+    accessibility: [
+      'Label is associated with the color input',
+      'Swatch button has appropriate aria-label',
+      'Color picker popup is keyboard accessible',
+      'Hex input allows direct text entry',
+    ],
+  },
+
+  props: {
+    value: {
+      type: 'string',
+      description: 'Controlled color value in hex format (#RRGGBB)',
+    },
+    defaultValue: {
+      type: 'string',
+      description: 'Default color for uncontrolled usage',
+      default: '#000000',
+    },
+    onChange: {
+      type: 'function',
+      description: 'Called with new color value when changed',
+    },
+    label: {
+      type: 'string',
+      description: 'Label text above the picker',
+    },
+    description: {
+      type: 'string',
+      description: 'Helper text below the picker',
+    },
+    disabled: {
+      type: 'boolean',
+      description: 'Disable the color picker',
+      default: 'false',
+    },
+    size: {
+      type: 'enum',
+      description: 'Size variant',
+      values: ['sm', 'md'],
+      default: 'md',
+    },
+    showInput: {
+      type: 'boolean',
+      description: 'Show the hex input field',
+      default: 'true',
+    },
+  },
+
+  relations: [
+    { component: 'Input', relationship: 'sibling', note: 'ColorPicker is a specialized input for colors' },
+    { component: 'RadioGroup', relationship: 'alternative', note: 'Use RadioGroup for predefined color choices' },
+    { component: 'Field', relationship: 'parent', note: 'ColorPicker uses Field internally for structure' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'value: string - controlled hex color (#RRGGBB)',
+      'defaultValue: string - initial color for uncontrolled usage',
+      'onChange: (color: string) => void - change handler',
+      'label: string - field label',
+      'description: string - helper text',
+      'disabled: boolean - disable interaction',
+      'size: sm|md - size variant',
+      'showInput: boolean - show hex input field',
+    ],
+    scenarioTags: [
+      'forms.color',
+      'input.specialized',
+      'theme.customization',
+    ],
+    a11yRules: ['A11Y_LABEL_REQUIRED', 'A11Y_FOCUS_VISIBLE'],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Basic color picker with label',
+      render: () => (
+        <ColorPicker
+          label="Brand Color"
+          defaultValue="#3b82f6"
+        />
+      ),
+    },
+    {
+      name: 'With Description',
+      description: 'Color picker with helper text',
+      render: () => (
+        <ColorPicker
+          label="Primary Color"
+          defaultValue="#10b981"
+          description="This color will be used for buttons and links"
+        />
+      ),
+    },
+    {
+      name: 'Controlled',
+      description: 'Controlled color picker that logs changes',
+      render: () => {
+        const [color, setColor] = React.useState('#ef4444');
+        return (
+          <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+            <ColorPicker
+              label="Accent Color"
+              value={color}
+              onChange={setColor}
+            />
+            <div style={{ fontSize: '14px', color: 'var(--fui-text-secondary)' }}>
+              Selected: {color}
+            </div>
+          </div>
+        );
+      },
+    },
+    {
+      name: 'Multiple Pickers',
+      description: 'Multiple color pickers for theme configuration',
+      render: () => (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '240px' }}>
+          <ColorPicker label="Primary" defaultValue="#3b82f6" />
+          <ColorPicker label="Success" defaultValue="#22c55e" />
+          <ColorPicker label="Warning" defaultValue="#f59e0b" />
+          <ColorPicker label="Danger" defaultValue="#ef4444" />
+        </div>
+      ),
+    },
+    {
+      name: 'Compact',
+      description: 'Small size with swatch only (no input)',
+      render: () => (
+        <div style={{ display: 'flex', gap: '8px', alignItems: 'center' }}>
+          <ColorPicker defaultValue="#ef4444" size="sm" showInput={false} />
+          <ColorPicker defaultValue="#f59e0b" size="sm" showInput={false} />
+          <ColorPicker defaultValue="#22c55e" size="sm" showInput={false} />
+          <ColorPicker defaultValue="#3b82f6" size="sm" showInput={false} />
+        </div>
+      ),
+    },
+    {
+      name: 'Sizes',
+      description: 'Different size variants',
+      render: () => (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '240px' }}>
+          <ColorPicker label="Small" defaultValue="#3b82f6" size="sm" />
+          <ColorPicker label="Medium (default)" defaultValue="#3b82f6" size="md" />
+        </div>
+      ),
+    },
+    {
+      name: 'Disabled',
+      description: 'Disabled color picker',
+      render: () => (
+        <ColorPicker
+          label="Locked Color"
+          defaultValue="#64748b"
+          description="This color cannot be changed"
+          disabled
+        />
+      ),
+    },
+  ],
+});

package/src/components/ColorPicker/ColorPicker.module.scss

@@ -6,6 +6,31 @@
   flex-direction: column;
 }
 
+// Size variants
+.sizeSm {
+  .inputWrapper {
+    gap: var(--fui-space-1, $fui-space-1);
+  }
+
+  .swatch {
+    width: $fui-touch-sm;
+    height: $fui-touch-sm;
+  }
+
+  .hexInput {
+    min-width: 80px;
+    flex: 0 0 auto;
+  }
+
+  .label {
+    font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  }
+}
+
+.sizeMd {
+  // Default size - no overrides needed
+}
+
 .label {
   @include label-text;
   margin-bottom: var(--fui-space-1, $fui-space-1);
@@ -40,31 +65,16 @@
   }
 }
 
-.input {
-  @include text-base;
-  @include interactive-base;
+// Hex input wrapper (using Input component)
+.hexInput {
   flex: 1;
-  height: 36px;
-  padding: 0 var(--fui-space-2, $fui-space-2);
-  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);
-  font-family: var(--fui-font-mono, $fui-font-mono);
-  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
-
-  &: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);
-  }
+  min-width: 0;
+}
 
-  &:disabled {
-    background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
-    color: var(--fui-text-tertiary, $fui-text-tertiary);
-  }
+// Style the actual input field inside Input component
+.hexInputField {
+  font-family: var(--fui-font-mono, $fui-font-mono) !important;
+  text-transform: lowercase;
 }
 
 .positioner {

package/src/components/ColorPicker/index.tsx

@@ -2,16 +2,27 @@ import * as React from 'react';
 import { HexColorPicker } from 'react-colorful';
 import { Popover as BasePopover } from '@base-ui/react/popover';
 import { Field } from '@base-ui/react/field';
+import { Input } from '../Input';
 import styles from './ColorPicker.module.scss';
 import '../../styles/globals.scss';
 
 export interface ColorPickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'> {
+  /** Label text above the picker */
   label?: string;
+  /** Controlled color value in hex format (#RRGGBB) */
   value?: string;
+  /** Default color for uncontrolled usage */
   defaultValue?: string;
+  /** Called with new color value when changed */
   onChange?: (color: string) => void;
+  /** Helper text below the picker */
   description?: string;
+  /** Disable the color picker */
   disabled?: boolean;
+  /** Size variant */
+  size?: 'sm' | 'md';
+  /** Show the hex input field */
+  showInput?: boolean;
 }
 
 export const ColorPicker = React.forwardRef<HTMLDivElement, ColorPickerProps>(
@@ -23,6 +34,8 @@ export const ColorPicker = React.forwardRef<HTMLDivElement, ColorPickerProps>(
       onChange,
       description,
       disabled = false,
+      size = 'md',
+      showInput = true,
       className,
       ...htmlProps
     },
@@ -45,8 +58,7 @@ export const ColorPicker = React.forwardRef<HTMLDivElement, ColorPickerProps>(
       onChange?.(color);
     };
 
-    const handleInputChange = (e: React.ChangeEvent<HTMLInputElement>) => {
-      const newValue = e.target.value;
+    const handleInputChange = (newValue: string) => {
       setInputValue(newValue);
 
       // Only update if it's a valid hex color
@@ -63,12 +75,18 @@ export const ColorPicker = React.forwardRef<HTMLDivElement, ColorPickerProps>(
       }
     };
 
+    const wrapperClasses = [
+      styles.wrapper,
+      styles[`size${size.charAt(0).toUpperCase() + size.slice(1)}`],
+      className,
+    ].filter(Boolean).join(' ');
+
     return (
       <Field.Root
         ref={ref}
         {...htmlProps}
         disabled={disabled}
-        className={[styles.wrapper, className].filter(Boolean).join(' ')}
+        className={wrapperClasses}
       >
         {label && <Field.Label className={styles.label}>{label}</Field.Label>}
         <div className={styles.inputWrapper}>
@@ -77,6 +95,7 @@ export const ColorPicker = React.forwardRef<HTMLDivElement, ColorPickerProps>(
               className={styles.swatch}
               style={{ backgroundColor: displayValue }}
               disabled={disabled}
+              aria-label={label ? `Edit ${label} color` : 'Edit color'}
             />
             <BasePopover.Portal>
               <BasePopover.Positioner side="bottom" align="start" sideOffset={4} className={styles.positioner}>
@@ -86,15 +105,18 @@ export const ColorPicker = React.forwardRef<HTMLDivElement, ColorPickerProps>(
               </BasePopover.Positioner>
             </BasePopover.Portal>
           </BasePopover.Root>
-          <input
-            type="text"
-            value={inputValue}
-            onChange={handleInputChange}
-            onBlur={handleInputBlur}
-            disabled={disabled}
-            className={styles.input}
-            spellCheck={false}
-          />
+          {showInput && (
+            <Input
+              value={inputValue}
+              onChange={handleInputChange}
+              onBlur={handleInputBlur}
+              disabled={disabled}
+              size={size}
+              className={styles.hexInput}
+              inputClassName={styles.hexInputField}
+              aria-label={label ? `${label} hex value` : 'Hex value'}
+            />
+          )}
         </div>
         {description && (
           <Field.Description className={styles.description}>

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

@@ -0,0 +1,220 @@
+import React, { useState } from 'react';
+import { defineSegment } from '@fragments/core';
+import { Combobox } from '.';
+
+// Stateful wrapper for interactive demos
+function StatefulCombobox(props: React.ComponentProps<typeof Combobox> & {
+  children: React.ReactNode;
+  initialValue?: string | string[];
+}) {
+  const { initialValue, children, ...rest } = props;
+  const [value, setValue] = useState<string | string[] | null>(initialValue ?? (props.multiple ? [] : null));
+  return (
+    <Combobox {...rest} value={value} onValueChange={setValue}>
+      {children}
+    </Combobox>
+  );
+}
+
+export default defineSegment({
+  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: 'string',
+      description: 'Controlled selected value (string for single, string[] for multiple)',
+    },
+    defaultValue: {
+      type: 'string',
+      description: 'Default selected value (uncontrolled)',
+    },
+    onValueChange: {
+      type: 'function',
+      description: 'Called when selection changes',
+    },
+    multiple: {
+      type: 'boolean',
+      description: 'Allow multiple selections with chips',
+      default: 'false',
+    },
+    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',
+      'multiple: boolean - enable multi-select with chips',
+      'placeholder: string - input placeholder text',
+      'disabled: boolean - disable combobox',
+      'autoHighlight: boolean - auto-highlight first match',
+    ],
+    scenarioTags: [
+      'form.combobox',
+      'form.autocomplete',
+      'form.multiselect',
+      'input.search',
+    ],
+    a11yRules: ['A11Y_COMBOBOX_KEYBOARD', 'A11Y_COMBOBOX_LABEL'],
+  },
+
+  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>',
+    ],
+  },
+
+  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: 'Disabled',
+      description: 'Disabled combobox',
+      render: () => (
+        <Combobox disabled placeholder="Search...">
+          <Combobox.Input />
+          <Combobox.Content>
+            <Combobox.Item value="1">Option 1</Combobox.Item>
+          </Combobox.Content>
+        </Combobox>
+      ),
+    },
+  ],
+});