@fragments-sdk/ui 0.2.3 → 0.4.0

package/src/components/Listbox/Listbox.fragment.tsx

@@ -0,0 +1,191 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Listbox } from './index.js';
+
+export default defineSegment({
+  component: Listbox,
+
+  meta: {
+    name: 'Listbox',
+    description: 'Controlled listbox for search results, autocomplete dropdowns, and command menus. Provides Menu-like styling without requiring a trigger.',
+    category: 'forms',
+    status: 'stable',
+    tags: ['listbox', 'search', 'autocomplete', 'combobox', 'command', 'dropdown'],
+    since: '0.3.0',
+  },
+
+  usage: {
+    when: [
+      'Search result dropdowns',
+      'Autocomplete suggestions',
+      'Command palette results',
+      'Keyboard-navigable option lists',
+    ],
+    whenNot: [
+      'Static lists without selection (use List)',
+      'Action menus with trigger button (use Menu)',
+      'Form field selection (use Select)',
+      'Navigation menus (use Sidebar or Tabs)',
+    ],
+    guidelines: [
+      'Control open/close state externally based on input focus or query',
+      'Implement keyboard navigation (arrow keys, enter, escape) in parent',
+      'Use Listbox.Empty for no results state',
+      'Group related items with Listbox.Group when appropriate',
+    ],
+    accessibility: [
+      'Uses listbox and option ARIA roles',
+      'aria-selected indicates current selection',
+      'aria-disabled for non-interactive items',
+      'Connect to input with aria-controls for full combobox pattern',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      description: 'Listbox.Item, Listbox.Group, or Listbox.Empty components',
+      required: true,
+    },
+    'aria-label': {
+      type: 'string',
+      description: 'Accessible label for the listbox',
+    },
+    className: {
+      type: 'string',
+      description: 'Additional CSS class',
+    },
+    style: {
+      type: 'object',
+      description: 'Inline styles',
+    },
+  },
+
+  relations: [
+    { component: 'Input', relationship: 'sibling', note: 'Pair with Input for search/autocomplete patterns' },
+    { component: 'Menu', relationship: 'alternative', note: 'Use Menu when you need a trigger button' },
+    { component: 'Select', relationship: 'alternative', note: 'Use Select for form field selection' },
+    { component: 'List', relationship: 'alternative', note: 'Use List for static, non-interactive lists' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'children: ReactNode - Listbox.Item components (required)',
+      'aria-label: string - accessible label',
+      'Listbox.Item selected: boolean - highlight state',
+      'Listbox.Item disabled: boolean - non-interactive',
+    ],
+    subComponents: [
+      {
+        name: 'Listbox.Item',
+        props: [
+          'children: ReactNode - item content',
+          'selected: boolean - highlight/selected state',
+          'disabled: boolean - non-interactive',
+          'onClick: () => void - click handler',
+          'onMouseEnter: () => void - hover handler',
+        ],
+      },
+      {
+        name: 'Listbox.Group',
+        props: [
+          'children: ReactNode - grouped items',
+          'label: string - group heading',
+        ],
+      },
+      {
+        name: 'Listbox.Empty',
+        props: [
+          'children: ReactNode - empty state message',
+        ],
+      },
+    ],
+    scenarioTags: [
+      'form.search',
+      'form.autocomplete',
+      'action.command',
+      'display.results',
+    ],
+    a11yRules: ['A11Y_LISTBOX_ROLE', 'A11Y_OPTION_ROLE'],
+  },
+
+  ai: {
+    compositionPattern: 'compound',
+    subComponents: ['Item', 'Group', 'Empty'],
+    requiredChildren: ['Item'],
+    commonPatterns: [
+      '<Listbox aria-label="Search results">{results.map(item => <Listbox.Item key={item.id} selected={item.id === selectedId} onClick={() => onSelect(item)}>{item.label}</Listbox.Item>)}</Listbox>',
+    ],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Basic listbox with selectable items',
+      render: () => (
+        <Listbox aria-label="Options">
+          <Listbox.Item selected>First option</Listbox.Item>
+          <Listbox.Item>Second option</Listbox.Item>
+          <Listbox.Item>Third option</Listbox.Item>
+        </Listbox>
+      ),
+    },
+    {
+      name: 'Search Results',
+      description: 'Typical search results pattern with label and metadata',
+      render: () => (
+        <Listbox aria-label="Search results">
+          <Listbox.Item selected>
+            <span style={{ fontWeight: 500 }}>Button</span>
+            <span style={{ marginLeft: 'auto', fontSize: '0.75rem', color: 'var(--fui-text-tertiary)' }}>Components</span>
+          </Listbox.Item>
+          <Listbox.Item>
+            <span style={{ fontWeight: 500 }}>Badge</span>
+            <span style={{ marginLeft: 'auto', fontSize: '0.75rem', color: 'var(--fui-text-tertiary)' }}>Components</span>
+          </Listbox.Item>
+          <Listbox.Item>
+            <span style={{ fontWeight: 500 }}>Box</span>
+            <span style={{ marginLeft: 'auto', fontSize: '0.75rem', color: 'var(--fui-text-tertiary)' }}>Layout</span>
+          </Listbox.Item>
+        </Listbox>
+      ),
+    },
+    {
+      name: 'With Groups',
+      description: 'Grouped items with labels',
+      render: () => (
+        <Listbox aria-label="Commands">
+          <Listbox.Group label="Recent">
+            <Listbox.Item selected>Open file...</Listbox.Item>
+            <Listbox.Item>Save as...</Listbox.Item>
+          </Listbox.Group>
+          <Listbox.Group label="Actions">
+            <Listbox.Item>Copy</Listbox.Item>
+            <Listbox.Item>Paste</Listbox.Item>
+            <Listbox.Item disabled>Cut</Listbox.Item>
+          </Listbox.Group>
+        </Listbox>
+      ),
+    },
+    {
+      name: 'Empty State',
+      description: 'No results found message',
+      render: () => (
+        <Listbox aria-label="Search results">
+          <Listbox.Empty>No results found</Listbox.Empty>
+        </Listbox>
+      ),
+    },
+    {
+      name: 'With Disabled Items',
+      description: 'Mix of enabled and disabled items',
+      render: () => (
+        <Listbox aria-label="Options">
+          <Listbox.Item>Available option</Listbox.Item>
+          <Listbox.Item disabled>Disabled option</Listbox.Item>
+          <Listbox.Item>Another option</Listbox.Item>
+        </Listbox>
+      ),
+    },
+  ],
+});

package/src/components/Listbox/Listbox.module.scss

@@ -0,0 +1,97 @@
+@use '../../tokens/mixins' as *;
+
+// ============================================
+// Listbox container
+// ============================================
+
+.listbox {
+  @include surface-elevated;
+
+  min-width: 12rem;
+  padding: var(--fui-space-1, 0.25rem);
+  box-shadow: var(--fui-shadow-lg);
+  max-height: 320px;
+  overflow-y: auto;
+}
+
+// ============================================
+// Listbox item
+// ============================================
+
+.item {
+  @include button-reset;
+  @include text-base;
+
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-2, 0.5rem);
+  width: 100%;
+  padding: var(--fui-space-2, 0.5rem) var(--fui-space-3, 0.75rem);
+  border-radius: var(--fui-radius-sm, 0.25rem);
+  cursor: pointer;
+  outline: none;
+  text-align: left;
+  color: var(--fui-text-primary);
+  background: transparent;
+  border: none;
+  transition: background-color 0.1s ease;
+
+  &:hover,
+  &:focus {
+    outline: none;
+  }
+}
+
+.itemSelected {
+  background-color: var(--fui-bg-hover);
+}
+
+.itemDisabled {
+  color: var(--fui-text-tertiary);
+  cursor: not-allowed;
+}
+
+// ============================================
+// Group
+// ============================================
+
+.group {
+  &:not(:first-child) {
+    margin-top: var(--fui-space-1, 0.25rem);
+    padding-top: var(--fui-space-1, 0.25rem);
+    border-top: 1px solid var(--fui-border);
+  }
+}
+
+.groupLabel {
+  padding: var(--fui-space-1, 0.25rem) var(--fui-space-3, 0.75rem);
+  font-size: var(--fui-font-size-xs, 0.75rem);
+  font-weight: var(--fui-font-weight-medium, 500);
+  color: var(--fui-text-tertiary);
+}
+
+// ============================================
+// Empty state
+// ============================================
+
+.empty {
+  padding: var(--fui-space-3, 0.75rem);
+  font-size: var(--fui-font-size-sm, 0.875rem);
+  color: var(--fui-text-secondary);
+  text-align: center;
+}
+
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .listbox {
+    border-width: 2px;
+  }
+
+  .itemSelected {
+    outline: 2px solid var(--fui-color-accent);
+    outline-offset: -2px;
+  }
+}

package/src/components/Listbox/index.tsx

@@ -0,0 +1,121 @@
+import * as React from 'react';
+import styles from './Listbox.module.scss';
+import '../../styles/globals.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export interface ListboxProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+}
+
+export interface ListboxItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onClick'> {
+  children: React.ReactNode;
+  /** Whether this item is currently selected/highlighted */
+  selected?: boolean;
+  /** Whether this item is disabled */
+  disabled?: boolean;
+  /** Click handler */
+  onClick?: () => void;
+}
+
+export interface ListboxGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  /** Group label */
+  label?: string;
+}
+
+export interface ListboxEmptyProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+}
+
+// ============================================
+// Components
+// ============================================
+
+function ListboxRoot({
+  children,
+  className,
+  style,
+  'aria-label': ariaLabel,
+  ...htmlProps
+}: ListboxProps) {
+  const classes = [styles.listbox, className].filter(Boolean).join(' ');
+
+  return (
+    <div
+      {...htmlProps}
+      role="listbox"
+      aria-label={ariaLabel}
+      className={classes}
+      style={style}
+    >
+      {children}
+    </div>
+  );
+}
+
+function ListboxItem({
+  children,
+  selected = false,
+  disabled = false,
+  onClick,
+  onMouseEnter,
+  className,
+  style,
+  ...htmlProps
+}: ListboxItemProps) {
+  const classes = [
+    styles.item,
+    selected && styles.itemSelected,
+    disabled && styles.itemDisabled,
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <div
+      {...htmlProps}
+      role="option"
+      aria-selected={selected}
+      aria-disabled={disabled}
+      onClick={disabled ? undefined : onClick}
+      onMouseEnter={onMouseEnter}
+      className={classes}
+      style={style}
+    >
+      {children}
+    </div>
+  );
+}
+
+function ListboxGroup({ children, label, className, ...htmlProps }: ListboxGroupProps) {
+  const classes = [styles.group, className].filter(Boolean).join(' ');
+
+  return (
+    <div {...htmlProps} role="group" aria-label={label} className={classes}>
+      {label && <div className={styles.groupLabel}>{label}</div>}
+      {children}
+    </div>
+  );
+}
+
+function ListboxEmpty({ children, className, ...htmlProps }: ListboxEmptyProps) {
+  const classes = [styles.empty, className].filter(Boolean).join(' ');
+  return <div {...htmlProps} className={classes}>{children}</div>;
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const Listbox = Object.assign(ListboxRoot, {
+  Item: ListboxItem,
+  Group: ListboxGroup,
+  Empty: ListboxEmpty,
+});
+
+// Re-export individual components
+export { ListboxRoot, ListboxItem, ListboxGroup, ListboxEmpty };

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

@@ -88,6 +88,15 @@ export default defineSegment({
     a11yRules: ['A11Y_MENU_KEYBOARD', 'A11Y_MENU_ROLE'],
   },
 
+  ai: {
+    compositionPattern: 'compound',
+    subComponents: ['Trigger', 'Content', 'Item', 'CheckboxItem', 'RadioGroup', 'RadioItem', 'Group', 'GroupLabel', 'Separator'],
+    requiredChildren: ['Trigger', 'Content'],
+    commonPatterns: [
+      '<Menu><Menu.Trigger asChild><Button>Actions</Button></Menu.Trigger><Menu.Content><Menu.Item>{action1}</Menu.Item><Menu.Separator /><Menu.Item danger>{delete}</Menu.Item></Menu.Content></Menu>',
+    ],
+  },
+
   variants: [
     {
       name: 'Default',

package/src/components/Menu/Menu.module.scss

@@ -44,7 +44,7 @@
   align-items: center;
   gap: var(--fui-space-2, $fui-space-2);
   width: 100%;
-  padding: var(--fui-space-2, $fui-space-2) var(--fui-space-3, $fui-space-3);
+  padding: var(--fui-space-1, $fui-space-1) var(--fui-padding-item-md, $fui-padding-item-md);
   border-radius: var(--fui-radius-sm, $fui-radius-sm);
   cursor: pointer;
   outline: none;
@@ -188,3 +188,19 @@
     border-color: transparent transparent transparent var(--fui-text-secondary, $fui-text-secondary);
   }
 }
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .popup {
+    transition: none;
+    transform: none;
+
+    &[data-starting-style],
+    &[data-ending-style] {
+      transform: none;
+    }
+  }
+}

package/src/components/Menu/index.tsx

@@ -22,9 +22,8 @@ export interface MenuTriggerProps {
   className?: string;
 }
 
-export interface MenuContentProps {
+export interface MenuContentProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
-  className?: string;
   side?: 'top' | 'bottom' | 'left' | 'right';
   align?: 'start' | 'center' | 'end';
   sideOffset?: number;
@@ -160,6 +159,7 @@ function MenuContent({
   side = 'bottom',
   align = 'start',
   sideOffset = 4,
+  ...htmlProps
 }: MenuContentProps) {
   const popupClasses = [styles.popup, className].filter(Boolean).join(' ');
 
@@ -171,7 +171,7 @@ function MenuContent({
         sideOffset={sideOffset}
         className={styles.positioner}
       >
-        <BaseMenu.Popup className={popupClasses}>
+        <BaseMenu.Popup {...htmlProps} className={popupClasses}>
           {children}
         </BaseMenu.Popup>
       </BaseMenu.Positioner>

package/src/components/Popover/Popover.fragment.tsx

@@ -90,6 +90,15 @@ export default defineSegment({
     a11yRules: ['A11Y_POPOVER_FOCUS', 'A11Y_POPOVER_ESCAPE'],
   },
 
+  ai: {
+    compositionPattern: 'compound',
+    subComponents: ['Trigger', 'Content', 'Close', 'Title', 'Description', 'Body', 'Footer'],
+    requiredChildren: ['Trigger', 'Content'],
+    commonPatterns: [
+      '<Popover><Popover.Trigger asChild><Button>Open</Button></Popover.Trigger><Popover.Content><Popover.Close /><Popover.Title>{title}</Popover.Title><Popover.Description>{description}</Popover.Description></Popover.Content></Popover>',
+    ],
+  },
+
   variants: [
     {
       name: 'Default',

package/src/components/Popover/Popover.module.scss

@@ -14,12 +14,12 @@
 
   min-width: 12rem;
   max-width: 24rem;
-  padding: var(--fui-space-4, $fui-space-4);
+  padding: var(--fui-padding-container-md, $fui-padding-container-md);
   box-shadow: var(--fui-shadow-md, $fui-shadow-md);
 
   // Animation
   opacity: 0;
-  transform: scale(0.95) translateY(-4px);
+  transform: scale(0.95) translateY(-$fui-anim-offset-sm);
   transform-origin: var(--transform-origin);
   transition:
     opacity var(--fui-transition-fast, $fui-transition-fast),
@@ -32,22 +32,22 @@
 
   &[data-starting-style] {
     opacity: 0;
-    transform: scale(0.95) translateY(-4px);
+    transform: scale(0.95) translateY(-$fui-anim-offset-sm);
   }
 
   &[data-ending-style] {
     opacity: 0;
-    transform: scale(0.95) translateY(4px);
+    transform: scale(0.95) translateY($fui-anim-offset-sm);
   }
 
   // Adjust animation direction based on side
   &[data-side='top'] {
     &[data-starting-style] {
-      transform: scale(0.95) translateY(4px);
+      transform: scale(0.95) translateY($fui-anim-offset-sm);
     }
 
     &[data-ending-style] {
-      transform: scale(0.95) translateY(-4px);
+      transform: scale(0.95) translateY(-$fui-anim-offset-sm);
     }
   }
 
@@ -62,7 +62,7 @@
 
 // Size variants
 .sm {
-  padding: var(--fui-space-3, $fui-space-3);
+  padding: var(--fui-padding-container-sm, $fui-padding-container-sm);
   max-width: 16rem;
 }
 
@@ -71,7 +71,7 @@
 }
 
 .lg {
-  padding: var(--fui-space-5, $fui-space-5);
+  padding: var(--fui-padding-container-lg, $fui-padding-container-lg);
   max-width: 32rem;
 }
 
@@ -121,8 +121,8 @@
 
 // Arrow
 .arrow {
-  width: 10px;
-  height: 10px;
+  width: $fui-arrow-size;
+  height: $fui-arrow-size;
   transform: rotate(45deg);
   background-color: var(--fui-bg-elevated, $fui-bg-elevated);
   border: 1px solid var(--fui-border, $fui-border);
@@ -163,3 +163,26 @@
   padding-top: var(--fui-space-3, $fui-space-3);
   border-top: 1px solid var(--fui-border, $fui-border);
 }
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .popup {
+    transition: none;
+    transform: none;
+
+    &[data-starting-style],
+    &[data-ending-style] {
+      transform: none;
+    }
+
+    &[data-side='top'] {
+      &[data-starting-style],
+      &[data-ending-style] {
+        transform: none;
+      }
+    }
+  }
+}

package/src/components/Popover/index.tsx

@@ -22,14 +22,13 @@ export interface PopoverTriggerProps {
   className?: string;
 }
 
-export interface PopoverContentProps {
+export interface PopoverContentProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
   size?: 'sm' | 'md' | 'lg';
   side?: 'top' | 'bottom' | 'left' | 'right';
   align?: 'start' | 'center' | 'end';
   sideOffset?: number;
   arrow?: boolean;
-  className?: string;
 }
 
 export interface PopoverTitleProps {
@@ -42,14 +41,12 @@ export interface PopoverDescriptionProps {
   className?: string;
 }
 
-export interface PopoverBodyProps {
+export interface PopoverBodyProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
-  className?: string;
 }
 
-export interface PopoverFooterProps {
+export interface PopoverFooterProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
-  className?: string;
 }
 
 export interface PopoverCloseProps {
@@ -129,6 +126,7 @@ function PopoverContent({
   sideOffset = 8,
   arrow = false,
   className,
+  ...htmlProps
 }: PopoverContentProps) {
   const popupClasses = [
     styles.popup,
@@ -144,7 +142,7 @@ function PopoverContent({
         sideOffset={sideOffset}
         className={styles.positioner}
       >
-        <BasePopover.Popup className={popupClasses}>
+        <BasePopover.Popup {...htmlProps} className={popupClasses}>
           {children}
           {arrow && <BasePopover.Arrow className={styles.arrow} />}
         </BasePopover.Popup>
@@ -167,14 +165,14 @@ function PopoverDescription({ children, className }: PopoverDescriptionProps) {
   );
 }
 
-function PopoverBody({ children, className }: PopoverBodyProps) {
+function PopoverBody({ children, className, ...htmlProps }: PopoverBodyProps) {
   const classes = [styles.body, className].filter(Boolean).join(' ');
-  return <div className={classes}>{children}</div>;
+  return <div {...htmlProps} className={classes}>{children}</div>;
 }
 
-function PopoverFooter({ children, className }: PopoverFooterProps) {
+function PopoverFooter({ children, className, ...htmlProps }: PopoverFooterProps) {
   const classes = [styles.footer, className].filter(Boolean).join(' ');
-  return <div className={classes}>{children}</div>;
+  return <div {...htmlProps} className={classes}>{children}</div>;
 }
 
 function PopoverClose({ children, asChild, className }: PopoverCloseProps) {