@usefragments/ui 1.0.0

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

@@ -0,0 +1,113 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+// ============================================
+// Listbox container
+// ============================================
+
+.listbox {
+  @include surface-elevated;
+  @include popup-container;
+
+  // Item height derived from text-base font + vertical padding (matches Select/Combobox)
+  --_item-h: calc(
+    var(--fui-font-size-sm, #{$fui-font-size-sm}) *
+      var(--fui-line-height-normal, #{$fui-line-height-normal}) +
+      var(--fui-space-2, #{$fui-space-2}) * 2
+  );
+
+  min-width: 12rem;
+  // Show N items + half-peek scroll hint (default 4.5 items)
+  max-height: calc(
+    var(--_item-h) * var(--fui-select-max-items, 4.5) + var(--fui-space-1, #{$fui-space-1}) * 2
+  );
+  overflow-y: auto;
+  border-color: var(--fui-form-group-border, $fui-border);
+
+  &:focus-visible {
+    @include focus-ring;
+  }
+}
+
+// ============================================
+// Listbox item
+// ============================================
+
+.item {
+  @include popup-item;
+
+  text-align: left;
+
+  // Pointer-hover and keyboard-active share the one neutral highlight (see _mixins).
+  &:hover,
+  &[data-highlighted] {
+    @include popup-item-highlight;
+  }
+
+  // Listbox items are individually focusable, so keep the keyboard ring on top.
+  &:focus-visible {
+    @include focus-ring;
+  }
+}
+
+.itemSelected {
+  @include popup-item-selected;
+}
+
+.itemActive {
+  &:not(.itemSelected) {
+    @include popup-item-highlight;
+  }
+}
+
+.itemActive.itemSelected {
+  @include popup-item-selected;
+}
+
+.itemDisabled {
+  @include popup-item-disabled;
+}
+
+// ============================================
+// Group
+// ============================================
+
+.group {
+  &:not(:first-child) {
+    margin-top: var(--fui-space-1, $fui-space-1);
+    padding-top: var(--fui-space-1, $fui-space-1);
+    border-top: 1px solid var(--fui-border, $fui-border);
+  }
+}
+
+.groupLabel {
+  @include popup-group-label;
+}
+
+// ============================================
+// Empty state
+// ============================================
+
+.empty {
+  @include text-base;
+
+  padding: var(--fui-space-2, $fui-space-2) var(--fui-space-3, $fui-space-3);
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
+  text-align: center;
+}
+
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .listbox {
+    border-width: 2px;
+  }
+
+  .itemSelected,
+  .itemActive {
+    outline: 2px solid var(--fui-color-accent, $fui-color-accent);
+    outline-offset: -2px;
+  }
+}

package/src/components/Listbox/Listbox.stories.tsx

@@ -0,0 +1,81 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Listbox } from '.';
+
+/**
+ * Controlled listbox for search results, autocomplete dropdowns, and command menus.
+ * Compose with `Listbox.Item`, `Listbox.Group`, and `Listbox.Empty`; provides
+ * arrow/home/end keyboard navigation when focused.
+ */
+const meta = {
+  title: 'Forms/Listbox',
+  component: Listbox,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Controlled option list for search results, autocomplete, and command menus.',
+      },
+    },
+  },
+  args: {
+    'aria-label': 'Options',
+    children: (
+      <>
+        <Listbox.Item selected>First option</Listbox.Item>
+        <Listbox.Item>Second option</Listbox.Item>
+        <Listbox.Item>Third option</Listbox.Item>
+      </>
+    ),
+  },
+} satisfies Meta<typeof Listbox>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: (args) => (
+    <Listbox {...args}>
+      <Listbox.Item selected>First option</Listbox.Item>
+      <Listbox.Item>Second option</Listbox.Item>
+      <Listbox.Item>Third option</Listbox.Item>
+    </Listbox>
+  ),
+};
+
+export const WithGroups: Story = {
+  args: { 'aria-label': 'Commands' },
+  render: (args) => (
+    <Listbox {...args}>
+      <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>
+  ),
+};
+
+export const WithDisabledItems: Story = {
+  render: (args) => (
+    <Listbox {...args}>
+      <Listbox.Item>Available option</Listbox.Item>
+      <Listbox.Item disabled>Disabled option</Listbox.Item>
+      <Listbox.Item>Another option</Listbox.Item>
+    </Listbox>
+  ),
+};
+
+export const EmptyState: Story = {
+  args: { 'aria-label': 'Search results' },
+  render: (args) => (
+    <Listbox {...args}>
+      <Listbox.Empty>No results found</Listbox.Empty>
+    </Listbox>
+  ),
+};

package/src/components/Listbox/index.tsx

@@ -0,0 +1,309 @@
+'use client';
+
+import * as React from 'react';
+import styles from './Listbox.module.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?: (event: React.MouseEvent<HTMLDivElement>) => 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;
+}
+
+interface ListboxContextValue {
+  activeId: string | null;
+  setActiveId: (id: string | null) => void;
+}
+
+const ListboxContext = React.createContext<ListboxContextValue | null>(null);
+
+// ============================================
+// Components
+// ============================================
+
+function ListboxRoot({
+  children,
+  className,
+  style,
+  'aria-label': ariaLabel,
+  tabIndex,
+  onKeyDown,
+  onFocus,
+  ...htmlProps
+}: ListboxProps) {
+  const classes = [styles.listbox, className].filter(Boolean).join(' ');
+  const listboxRef = React.useRef<HTMLDivElement>(null);
+  const [activeId, setActiveId] = React.useState<string | null>(null);
+
+  const getEnabledOptions = React.useCallback(() => {
+    const listbox = listboxRef.current;
+    if (!listbox) return [] as HTMLDivElement[];
+
+    return Array.from(
+      listbox.querySelectorAll<HTMLDivElement>('[role="option"]')
+    ).filter((option) => option.getAttribute('aria-disabled') !== 'true');
+  }, []);
+
+  const moveActive = React.useCallback(
+    (direction: 'next' | 'prev' | 'first' | 'last') => {
+      const options = getEnabledOptions();
+      if (options.length === 0) return;
+
+      if (direction === 'first') {
+        setActiveId(options[0].id);
+        return;
+      }
+
+      if (direction === 'last') {
+        setActiveId(options[options.length - 1].id);
+        return;
+      }
+
+      const currentIndex = activeId
+        ? options.findIndex((option) => option.id === activeId)
+        : -1;
+
+      if (direction === 'next') {
+        const nextIndex = currentIndex < 0 ? 0 : (currentIndex + 1) % options.length;
+        setActiveId(options[nextIndex].id);
+      } else {
+        const prevIndex = currentIndex < 0
+          ? options.length - 1
+          : (currentIndex - 1 + options.length) % options.length;
+        setActiveId(options[prevIndex].id);
+      }
+    },
+    [activeId, getEnabledOptions]
+  );
+
+  React.useEffect(() => {
+    if (!activeId) return;
+    const listbox = listboxRef.current;
+    if (!listbox) return;
+
+    const escapedId = typeof CSS !== 'undefined' && typeof CSS.escape === 'function'
+      ? CSS.escape(activeId)
+      : activeId.replace(/["\\]/g, '\\$&');
+    const activeOption = listbox.querySelector<HTMLElement>(`#${escapedId}`);
+    if (!activeOption) return;
+
+    const frame = window.requestAnimationFrame(() => {
+      activeOption.scrollIntoView({ block: 'nearest' });
+    });
+
+    return () => {
+      window.cancelAnimationFrame(frame);
+    };
+  }, [activeId]);
+
+  const selectActiveItem = React.useCallback(() => {
+    if (!activeId) return;
+    const listbox = listboxRef.current;
+    if (!listbox) return;
+
+    const escapedId = typeof CSS !== 'undefined' && typeof CSS.escape === 'function'
+      ? CSS.escape(activeId)
+      : activeId.replace(/["\\]/g, '\\$&');
+    const activeOption = listbox.querySelector<HTMLElement>(`#${escapedId}`);
+    if (activeOption && activeOption.getAttribute('aria-disabled') !== 'true') {
+      activeOption.click();
+    }
+  }, [activeId]);
+
+  const setDefaultActiveIfNeeded = React.useCallback(() => {
+    if (activeId) return;
+    const options = getEnabledOptions();
+    if (options.length === 0) return;
+
+    const selectedOption = options.find((option) => option.getAttribute('aria-selected') === 'true');
+    setActiveId((selectedOption ?? options[0]).id);
+  }, [activeId, getEnabledOptions]);
+
+  const handleKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
+    onKeyDown?.(event);
+    if (event.defaultPrevented) return;
+
+    switch (event.key) {
+      case 'ArrowDown':
+        event.preventDefault();
+        moveActive('next');
+        break;
+      case 'ArrowUp':
+        event.preventDefault();
+        moveActive('prev');
+        break;
+      case 'Home':
+        event.preventDefault();
+        moveActive('first');
+        break;
+      case 'End':
+        event.preventDefault();
+        moveActive('last');
+        break;
+      case 'Enter':
+      case ' ':
+        event.preventDefault();
+        selectActiveItem();
+        break;
+      default:
+        break;
+    }
+  };
+
+  const handleFocus = (event: React.FocusEvent<HTMLDivElement>) => {
+    setDefaultActiveIfNeeded();
+    onFocus?.(event);
+  };
+
+  const contextValue = React.useMemo<ListboxContextValue>(
+    () => ({
+      activeId,
+      setActiveId,
+    }),
+    [activeId]
+  );
+
+  return (
+    <ListboxContext.Provider value={contextValue}>
+      <div
+        ref={listboxRef}
+        {...htmlProps}
+        role="listbox"
+        aria-label={ariaLabel}
+        aria-activedescendant={activeId ?? undefined}
+        tabIndex={tabIndex ?? 0}
+        className={classes}
+        style={style}
+        onKeyDown={handleKeyDown}
+        onFocus={handleFocus}
+      >
+        {children}
+      </div>
+    </ListboxContext.Provider>
+  );
+}
+
+function ListboxItem({
+  children,
+  selected = false,
+  disabled = false,
+  onClick,
+  onKeyDown,
+  onMouseEnter,
+  className,
+  style,
+  ...htmlProps
+}: ListboxItemProps) {
+  const context = React.useContext(ListboxContext);
+  const generatedId = React.useId();
+  const itemId = (htmlProps.id as string | undefined) ?? `listbox-item-${generatedId}`;
+  const classes = [
+    styles.item,
+    selected && styles.itemSelected,
+    disabled && styles.itemDisabled,
+    context?.activeId === itemId && styles.itemActive,
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  const handleMouseEnter = (event: React.MouseEvent<HTMLDivElement>) => {
+    if (!disabled) {
+      context?.setActiveId(itemId);
+    }
+    onMouseEnter?.(event);
+  };
+
+  const handleKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
+    onKeyDown?.(event);
+    if (event.defaultPrevented || disabled) return;
+    if (event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault();
+      event.currentTarget.click();
+    }
+  };
+
+  return (
+    <div
+      {...htmlProps}
+      id={itemId}
+      role="option"
+      aria-selected={selected}
+      aria-disabled={disabled}
+      data-active={context?.activeId === itemId || undefined}
+      onClick={disabled ? undefined : onClick}
+      onKeyDown={handleKeyDown}
+      onMouseEnter={handleMouseEnter}
+      className={classes}
+      style={style}
+    >
+      {children}
+    </div>
+  );
+}
+
+function ListboxGroup({ children, label, className, ...htmlProps }: ListboxGroupProps) {
+  const classes = [styles.group, className].filter(Boolean).join(' ');
+  const labelId = React.useId();
+
+  return (
+    <div
+      {...htmlProps}
+      role="group"
+      aria-labelledby={label ? labelId : undefined}
+      className={classes}
+    >
+      {label && <div id={labelId} className={styles.groupLabel}>{label}</div>}
+      {children}
+    </div>
+  );
+}
+
+function ListboxEmpty({ children, className, ...htmlProps }: ListboxEmptyProps) {
+  const classes = [styles.empty, className].filter(Boolean).join(' ');
+  return (
+    <div
+      {...htmlProps}
+      role="option"
+      aria-disabled="true"
+      aria-selected="false"
+      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/Loading/Loading.contract.json

@@ -0,0 +1,167 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Loading",
+  "description": "Versatile loading indicator with multiple variants for showing progress or waiting states",
+  "category": "feedback",
+  "tags": [
+    "loading",
+    "spinner",
+    "progress",
+    "feedback",
+    "indicator",
+    "async"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Loading/index.tsx",
+  "exportName": "Loading",
+  "propsSummary": [
+    "size: sm|md|lg|xl (default: md)",
+    "variant: spinner|dots|pulse (default: spinner)",
+    "label: string (default: Loading...)",
+    "centered: boolean (default: false)",
+    "fill: boolean (default: false)",
+    "overlay: boolean (default: false)",
+    "color: accent|current|muted (default: accent)"
+  ],
+  "props": {
+    "size": {
+      "type": "enum",
+      "description": "Size of the loading indicator",
+      "default": "md",
+      "required": false,
+      "values": [
+        "sm",
+        "md",
+        "lg",
+        "xl"
+      ]
+    },
+    "variant": {
+      "type": "enum",
+      "description": "Visual style of the loading animation",
+      "default": "spinner",
+      "required": false,
+      "values": [
+        "spinner",
+        "dots",
+        "pulse"
+      ]
+    },
+    "label": {
+      "type": "string",
+      "description": "Accessible label for screen readers",
+      "default": "Loading...",
+      "required": false
+    },
+    "centered": {
+      "type": "boolean",
+      "description": "Whether to center the loading indicator in its container",
+      "default": "false",
+      "required": false
+    },
+    "fill": {
+      "type": "boolean",
+      "description": "Whether to fill the parent container",
+      "default": "false",
+      "required": false
+    },
+    "overlay": {
+      "type": "boolean",
+      "description": "Whether to show with a backdrop overlay",
+      "default": "false",
+      "required": false
+    },
+    "color": {
+      "type": "enum",
+      "description": "Color variant - accent uses theme color, current inherits text color",
+      "default": "accent",
+      "required": false,
+      "values": [
+        "accent",
+        "current",
+        "muted"
+      ]
+    }
+  },
+  "usage": {
+    "when": [
+      "Indicating content is being fetched or processed",
+      "Showing a pending state while waiting for an async operation",
+      "Displaying loading state for buttons, forms, or page sections",
+      "Full-screen loading during initial app/page load"
+    ],
+    "whenNot": [
+      "For showing determinate progress - use Progress component instead",
+      "For showing skeleton placeholders - use Skeleton component instead",
+      "For AI-specific thinking states - use ThinkingIndicator instead"
+    ],
+    "guidelines": [
+      "Use spinner variant for general loading states",
+      "Use dots variant for chat/messaging contexts",
+      "Use pulse variant for subtle, ambient loading",
+      "Always provide a meaningful label for screen readers",
+      "Consider using Loading.Screen for initial page loads",
+      "Use Loading.Inline when loading indicator should flow with text"
+    ],
+    "accessibility": [
+      "Component uses role=\"status\" and aria-live=\"polite\"",
+      "Always provide descriptive label prop for screen readers",
+      "Animations respect prefers-reduced-motion preference"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Default spinner loading indicator",
+      "code": "<Loading />"
+    },
+    {
+      "name": "Sizes",
+      "description": "Loading indicators in different sizes",
+      "code": "<div style={{ display: 'flex', alignItems: 'center', gap: '24px' }}>\n  <Loading size=\"sm\" />\n  <Loading size=\"md\" />\n  <Loading size=\"lg\" />\n  <Loading size=\"xl\" />\n</div>"
+    },
+    {
+      "name": "Dots",
+      "description": "Bouncing dots animation",
+      "code": "<Loading variant=\"dots\" />"
+    },
+    {
+      "name": "Pulse",
+      "description": "Pulsing circle animation",
+      "code": "<Loading variant=\"pulse\" />"
+    },
+    {
+      "name": "Colors",
+      "description": "Different color variants",
+      "code": "<div style={{ display: 'flex', alignItems: 'center', gap: '24px' }}>\n  <Loading color=\"accent\" />\n  <Loading color=\"muted\" />\n  <span style={{ color: '#3b82f6' }}>\n    <Loading color=\"current\" />\n  </span>\n</div>"
+    },
+    {
+      "name": "Inline",
+      "description": "Inline loading indicator that flows with text",
+      "code": "<p style={{ margin: 0 }}>\n  Processing your request <Loading.Inline /> please wait...\n</p>"
+    },
+    {
+      "name": "Centered",
+      "description": "Centered in container",
+      "code": "<div style={{ width: '200px', height: '100px', border: '1px dashed #ccc', borderRadius: '8px' }}>\n  <Loading centered fill />\n</div>"
+    },
+    {
+      "name": "Screen",
+      "description": "Full-screen loading state with optional label",
+      "code": "<div style={{ position: 'relative', width: '300px', height: '200px', border: '1px solid #ccc', borderRadius: '8px', overflow: 'hidden', transform: 'scale(1)' }}>\n  <Loading.Screen size=\"lg\" label=\"Loading application...\" showLabel />\n</div>"
+    }
+  ],
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Inline",
+      "Screen"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:05.576Z"
+  }
+}