@fragments-sdk/ui 0.3.0 → 0.5.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

@@ -0,0 +1,119 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+.wrapper {
+  display: flex;
+  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);
+}
+
+.inputWrapper {
+  display: flex;
+  gap: var(--fui-space-2, $fui-space-2);
+  align-items: center;
+}
+
+.swatch {
+  @include button-reset;
+  @include interactive-base;
+  width: 40px;
+  height: 36px;
+  border: 1px solid var(--fui-border, $fui-border);
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+  flex-shrink: 0;
+
+  &:hover:not(:disabled) {
+    border-color: var(--fui-border-strong, $fui-border-strong);
+  }
+
+  &:focus-visible {
+    @include focus-ring;
+  }
+
+  &:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+}
+
+// Hex input wrapper (using Input component)
+.hexInput {
+  flex: 1;
+  min-width: 0;
+}
+
+// Style the actual input field inside Input component
+.hexInputField {
+  font-family: var(--fui-font-mono, $fui-font-mono) !important;
+  text-transform: lowercase;
+}
+
+.positioner {
+  z-index: 100;
+  outline: none;
+}
+
+.popup {
+  background-color: var(--fui-bg-elevated, $fui-bg-elevated);
+  border: 1px solid var(--fui-border, $fui-border);
+  border-radius: var(--fui-radius-lg, $fui-radius-lg);
+  box-shadow: var(--fui-shadow-md, $fui-shadow-md);
+  padding: var(--fui-space-2, $fui-space-2);
+
+  // react-colorful styling overrides
+  :global(.react-colorful) {
+    width: 200px;
+    height: 200px;
+  }
+
+  :global(.react-colorful__saturation) {
+    border-radius: var(--fui-radius-md, $fui-radius-md);
+    margin-bottom: var(--fui-space-2, $fui-space-2);
+  }
+
+  :global(.react-colorful__hue) {
+    height: 12px;
+    border-radius: var(--fui-radius-sm, $fui-radius-sm);
+  }
+
+  :global(.react-colorful__pointer) {
+    width: 16px;
+    height: 16px;
+    border: 2px solid white;
+    box-shadow: 0 1px 4px rgba(0, 0, 0, 0.3);
+  }
+}
+
+.description {
+  @include helper-text;
+  margin-top: var(--fui-space-1, $fui-space-1);
+}

package/src/components/ColorPicker/index.tsx

@@ -0,0 +1,129 @@
+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>(
+  function ColorPicker(
+    {
+      label,
+      value,
+      defaultValue = '#000000',
+      onChange,
+      description,
+      disabled = false,
+      size = 'md',
+      showInput = true,
+      className,
+      ...htmlProps
+    },
+    ref
+  ) {
+    const [internalValue, setInternalValue] = React.useState(defaultValue);
+    const [inputValue, setInputValue] = React.useState(value ?? defaultValue);
+    const displayValue = value !== undefined ? value : internalValue;
+
+    // Sync input value when controlled value changes
+    React.useEffect(() => {
+      if (value !== undefined) {
+        setInputValue(value);
+      }
+    }, [value]);
+
+    const handleChange = (color: string) => {
+      setInternalValue(color);
+      setInputValue(color);
+      onChange?.(color);
+    };
+
+    const handleInputChange = (newValue: string) => {
+      setInputValue(newValue);
+
+      // Only update if it's a valid hex color
+      if (/^#[0-9A-Fa-f]{6}$/.test(newValue)) {
+        setInternalValue(newValue);
+        onChange?.(newValue);
+      }
+    };
+
+    const handleInputBlur = () => {
+      // Reset to valid value on blur if invalid
+      if (!/^#[0-9A-Fa-f]{6}$/.test(inputValue)) {
+        setInputValue(displayValue);
+      }
+    };
+
+    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={wrapperClasses}
+      >
+        {label && <Field.Label className={styles.label}>{label}</Field.Label>}
+        <div className={styles.inputWrapper}>
+          <BasePopover.Root>
+            <BasePopover.Trigger
+              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}>
+                <BasePopover.Popup className={styles.popup}>
+                  <HexColorPicker color={displayValue} onChange={handleChange} />
+                </BasePopover.Popup>
+              </BasePopover.Positioner>
+            </BasePopover.Portal>
+          </BasePopover.Root>
+          {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}>
+            {description}
+          </Field.Description>
+        )}
+      </Field.Root>
+    );
+  }
+);

package/src/components/ConversationList/ConversationList.fragment.tsx

@@ -0,0 +1,202 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { ConversationList } from '.';
+import { Message } from '../Message';
+
+export default defineSegment({
+  component: ConversationList,
+
+  meta: {
+    name: 'ConversationList',
+    description: 'Scrollable message container with auto-scroll and history loading',
+    category: 'ai',
+    status: 'stable',
+    tags: ['conversation', 'chat', 'messages', 'scroll', 'ai', 'list'],
+  },
+
+  usage: {
+    when: [
+      'Building a chat interface with multiple messages',
+      'Need auto-scroll behavior when new messages arrive',
+      'Require infinite scroll for loading message history',
+      'Want date separators between message groups',
+    ],
+    whenNot: [
+      'Simple list of items without chat context (use List)',
+      'Single message display (use Message directly)',
+      'Non-scrolling message layout',
+    ],
+    guidelines: [
+      'Use autoScroll="smart" for best UX (only auto-scrolls when near bottom)',
+      'Implement onScrollTop for loading older messages',
+      'Provide an emptyState for new conversations',
+      'Use DateSeparator between messages from different days',
+    ],
+    accessibility: [
+      'Uses proper ARIA roles for separators',
+      'Typing indicator has aria-label',
+      'Smooth scroll respects reduced motion preferences',
+      'Keyboard navigation works within scrollable container',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'ReactNode',
+      description: 'Message components',
+      required: true,
+    },
+    autoScroll: {
+      type: 'boolean | "smart"',
+      default: '"smart"',
+      description: 'Auto-scroll behavior: true (always), false (never), or "smart" (only when near bottom)',
+    },
+    onScrollTop: {
+      type: 'function',
+      description: 'Callback when user scrolls to top (for loading history)',
+    },
+    loadingHistory: {
+      type: 'boolean',
+      default: 'false',
+      description: 'Show loading spinner at top when loading history',
+    },
+    emptyState: {
+      type: 'ReactNode',
+      description: 'Content to show when conversation is empty',
+    },
+    scrollTopThreshold: {
+      type: 'number',
+      default: '50',
+      description: 'Pixels from top to trigger onScrollTop',
+    },
+    scrollBottomThreshold: {
+      type: 'number',
+      default: '100',
+      description: 'Pixels from bottom for smart auto-scroll',
+    },
+  },
+
+  relations: [
+    {
+      component: 'Message',
+      relationship: 'child',
+      note: 'ConversationList contains Message components',
+    },
+    {
+      component: 'ThinkingIndicator',
+      relationship: 'child',
+      note: 'Show ThinkingIndicator at bottom while awaiting response',
+    },
+    {
+      component: 'Prompt',
+      relationship: 'sibling',
+      note: 'Typically paired with Prompt for input',
+    },
+  ],
+
+  contract: {
+    propsSummary: [
+      'children: ReactNode - Message components',
+      'autoScroll: boolean | "smart" - scroll behavior (default: "smart")',
+      'onScrollTop: () => void - callback for loading history',
+      'loadingHistory: boolean - show history loading spinner',
+      'emptyState: ReactNode - empty conversation content',
+    ],
+    scenarioTags: [
+      'ui.chat',
+      'ui.conversation',
+      'ai.assistant',
+      'layout.scroll',
+    ],
+    a11yRules: [
+      'A11Y_ARIA_ROLES',
+      'A11Y_MOTION_PREFERENCE',
+    ],
+    bans: [],
+  },
+
+  variants: [
+    {
+      name: 'Basic',
+      description: 'Simple conversation with messages',
+      render: () => (
+        <div style={{ height: '300px', border: '1px solid #e4e4e7', borderRadius: '8px' }}>
+          <ConversationList>
+            <Message role="user">
+              <Message.Content>Hello!</Message.Content>
+            </Message>
+            <Message role="assistant">
+              <Message.Content>Hi there! How can I help you today?</Message.Content>
+            </Message>
+            <Message role="user">
+              <Message.Content>Can you explain React hooks?</Message.Content>
+            </Message>
+          </ConversationList>
+        </div>
+      ),
+    },
+    {
+      name: 'With Date Separators',
+      description: 'Messages grouped by date',
+      render: () => (
+        <div style={{ height: '300px', border: '1px solid #e4e4e7', borderRadius: '8px' }}>
+          <ConversationList>
+            <ConversationList.DateSeparator date={new Date(Date.now() - 86400000)} />
+            <Message role="user">
+              <Message.Content>A message from yesterday</Message.Content>
+            </Message>
+            <ConversationList.DateSeparator date={new Date()} />
+            <Message role="assistant">
+              <Message.Content>And a message from today!</Message.Content>
+            </Message>
+          </ConversationList>
+        </div>
+      ),
+    },
+    {
+      name: 'With Typing Indicator',
+      description: 'Shows assistant is typing',
+      render: () => (
+        <div style={{ height: '300px', border: '1px solid #e4e4e7', borderRadius: '8px' }}>
+          <ConversationList>
+            <Message role="user">
+              <Message.Content>What is TypeScript?</Message.Content>
+            </Message>
+            <ConversationList.TypingIndicator name="Assistant" />
+          </ConversationList>
+        </div>
+      ),
+    },
+    {
+      name: 'Loading History',
+      description: 'Loading older messages',
+      render: () => (
+        <div style={{ height: '300px', border: '1px solid #e4e4e7', borderRadius: '8px' }}>
+          <ConversationList loadingHistory>
+            <Message role="user">
+              <Message.Content>This is the latest message</Message.Content>
+            </Message>
+          </ConversationList>
+        </div>
+      ),
+    },
+    {
+      name: 'Empty State',
+      description: 'No messages yet',
+      render: () => (
+        <div style={{ height: '300px', border: '1px solid #e4e4e7', borderRadius: '8px' }}>
+          <ConversationList
+            emptyState={
+              <div style={{ textAlign: 'center', color: '#71717a', padding: '2rem' }}>
+                <p>No messages yet</p>
+                <p style={{ fontSize: '12px' }}>Start a conversation!</p>
+              </div>
+            }
+          >
+            {/* No messages */}
+          </ConversationList>
+        </div>
+      ),
+    },
+  ],
+});