@fragments-sdk/ui 0.8.7 → 0.8.8

package/src/components/Command/index.tsx

@@ -0,0 +1,502 @@
+'use client';
+
+import * as React from 'react';
+import styles from './Command.module.scss';
+import '../../styles/globals.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export interface CommandProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  /** Controlled search value */
+  search?: string;
+  /** Default search value */
+  defaultSearch?: string;
+  /** Called when search input changes */
+  onSearchChange?: (search: string) => void;
+  /** Custom filter function. Return 0 to hide, >0 to show (higher = better match).
+      Default: case-insensitive substring match on value + keywords */
+  filter?: (value: string, search: string, keywords?: string[]) => number;
+  /** Whether to loop keyboard navigation. Default: true */
+  loop?: boolean;
+}
+
+export interface CommandInputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+  className?: string;
+}
+
+export interface CommandListProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+}
+
+export interface CommandItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onSelect'> {
+  children: React.ReactNode;
+  /** Value used for filtering (falls back to text content) */
+  value?: string;
+  /** Extra keywords for filtering */
+  keywords?: string[];
+  /** Whether this item is disabled */
+  disabled?: boolean;
+  /** Called when item is selected (Enter or click) */
+  onItemSelect?: () => void;
+}
+
+export interface CommandGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  /** Group heading text */
+  heading?: string;
+}
+
+export interface CommandEmptyProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+}
+
+export interface CommandSeparatorProps extends React.HTMLAttributes<HTMLDivElement> {}
+
+// ============================================
+// Default filter
+// ============================================
+
+function defaultFilter(value: string, search: string, keywords?: string[]): number {
+  if (!search) return 1;
+  const searchLower = search.toLowerCase();
+  const valueLower = value.toLowerCase();
+
+  if (valueLower.includes(searchLower)) return 1;
+
+  if (keywords) {
+    for (const keyword of keywords) {
+      if (keyword.toLowerCase().includes(searchLower)) return 1;
+    }
+  }
+
+  return 0;
+}
+
+// ============================================
+// Context
+// ============================================
+
+interface ItemRegistration {
+  value: string;
+  keywords?: string[];
+}
+
+interface CommandContextValue {
+  search: string;
+  setSearch: (search: string) => void;
+  filter: (value: string, search: string, keywords?: string[]) => number;
+  scores: Map<string, number>;
+  registerItem: (id: string, registration: ItemRegistration) => void;
+  unregisterItem: (id: string) => void;
+  activeId: string | null;
+  setActiveId: (id: string | null) => void;
+  loop: boolean;
+  listRef: React.RefObject<HTMLDivElement | null>;
+  visibleCount: number;
+}
+
+const CommandContext = React.createContext<CommandContextValue | null>(null);
+
+function useCommandContext() {
+  const ctx = React.useContext(CommandContext);
+  if (!ctx) throw new Error('Command sub-components must be used within <Command>');
+  return ctx;
+}
+
+// ============================================
+// Search Icon
+// ============================================
+
+function SearchIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <circle cx="11" cy="11" r="8" />
+      <line x1="21" y1="21" x2="16.65" y2="16.65" />
+    </svg>
+  );
+}
+
+// ============================================
+// Components
+// ============================================
+
+function CommandRoot({
+  children,
+  search: controlledSearch,
+  defaultSearch = '',
+  onSearchChange,
+  filter = defaultFilter,
+  loop = true,
+  className,
+  ...htmlProps
+}: CommandProps) {
+  const [uncontrolledSearch, setUncontrolledSearch] = React.useState(defaultSearch);
+  const isControlled = controlledSearch !== undefined;
+  const search = isControlled ? controlledSearch : uncontrolledSearch;
+
+  const [items, setItems] = React.useState<Map<string, ItemRegistration>>(new Map());
+  const [activeId, setActiveId] = React.useState<string | null>(null);
+  const listRef = React.useRef<HTMLDivElement | null>(null);
+
+  const setSearch = React.useCallback(
+    (value: string) => {
+      if (!isControlled) {
+        setUncontrolledSearch(value);
+      }
+      onSearchChange?.(value);
+    },
+    [isControlled, onSearchChange]
+  );
+
+  const registerItem = React.useCallback((id: string, registration: ItemRegistration) => {
+    setItems((prev) => {
+      const next = new Map(prev);
+      next.set(id, registration);
+      return next;
+    });
+  }, []);
+
+  const unregisterItem = React.useCallback((id: string) => {
+    setItems((prev) => {
+      const next = new Map(prev);
+      next.delete(id);
+      return next;
+    });
+  }, []);
+
+  // Compute scores for all items
+  const scores = React.useMemo(() => {
+    const result = new Map<string, number>();
+    for (const [id, registration] of items) {
+      const score = filter(registration.value, search, registration.keywords);
+      result.set(id, score);
+    }
+    return result;
+  }, [items, search, filter]);
+
+  const visibleCount = React.useMemo(() => {
+    let count = 0;
+    for (const score of scores.values()) {
+      if (score > 0) count++;
+    }
+    return count;
+  }, [scores]);
+
+  // Reset active when search changes
+  React.useEffect(() => {
+    setActiveId(null);
+  }, [search]);
+
+  const contextValue = React.useMemo<CommandContextValue>(
+    () => ({
+      search,
+      setSearch,
+      filter,
+      scores,
+      registerItem,
+      unregisterItem,
+      activeId,
+      setActiveId,
+      loop,
+      listRef,
+      visibleCount,
+    }),
+    [search, setSearch, filter, scores, registerItem, unregisterItem, activeId, loop, visibleCount]
+  );
+
+  return (
+    <CommandContext.Provider value={contextValue}>
+      <div
+        {...htmlProps}
+        className={[styles.command, className].filter(Boolean).join(' ')}
+        role="search"
+      >
+        {children}
+      </div>
+    </CommandContext.Provider>
+  );
+}
+
+function CommandInput({ className, ...htmlProps }: CommandInputProps) {
+  const { search, setSearch, listRef, setActiveId, activeId, loop } = useCommandContext();
+  const inputRef = React.useRef<HTMLInputElement>(null);
+
+  const getEnabledItems = React.useCallback(() => {
+    const list = listRef.current;
+    if (!list) return [];
+    return Array.from(
+      list.querySelectorAll<HTMLElement>('[data-command-item]:not([data-disabled="true"])')
+    ).filter((el) => el.style.display !== 'none');
+  }, [listRef]);
+
+  const handleKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
+    htmlProps.onKeyDown?.(event);
+    if (event.defaultPrevented) return;
+
+    const items = getEnabledItems();
+    if (items.length === 0) return;
+
+    const currentIndex = activeId
+      ? items.findIndex((item) => item.id === activeId)
+      : -1;
+
+    switch (event.key) {
+      case 'ArrowDown': {
+        event.preventDefault();
+        if (currentIndex < 0) {
+          setActiveId(items[0].id);
+        } else if (currentIndex < items.length - 1) {
+          setActiveId(items[currentIndex + 1].id);
+        } else if (loop) {
+          setActiveId(items[0].id);
+        }
+        break;
+      }
+      case 'ArrowUp': {
+        event.preventDefault();
+        if (currentIndex < 0) {
+          setActiveId(items[items.length - 1].id);
+        } else if (currentIndex > 0) {
+          setActiveId(items[currentIndex - 1].id);
+        } else if (loop) {
+          setActiveId(items[items.length - 1].id);
+        }
+        break;
+      }
+      case 'Home': {
+        event.preventDefault();
+        setActiveId(items[0].id);
+        break;
+      }
+      case 'End': {
+        event.preventDefault();
+        setActiveId(items[items.length - 1].id);
+        break;
+      }
+      case 'Enter': {
+        event.preventDefault();
+        if (activeId) {
+          const activeItem = items.find((item) => item.id === activeId);
+          if (activeItem) {
+            activeItem.click();
+          }
+        }
+        break;
+      }
+    }
+  };
+
+  return (
+    <div className={styles.inputWrapper}>
+      <SearchIcon />
+      <input
+        ref={inputRef}
+        type="text"
+        role="combobox"
+        aria-expanded={true}
+        aria-controls="command-list"
+        aria-autocomplete="list"
+        aria-activedescendant={activeId ?? undefined}
+        autoComplete="off"
+        autoCorrect="off"
+        spellCheck={false}
+        value={search}
+        onChange={(e) => setSearch(e.target.value)}
+        onKeyDown={handleKeyDown}
+        className={[styles.input, className].filter(Boolean).join(' ')}
+        {...htmlProps}
+      />
+    </div>
+  );
+}
+
+function CommandList({ children, className, ...htmlProps }: CommandListProps) {
+  const { listRef } = useCommandContext();
+
+  return (
+    <div
+      ref={listRef}
+      id="command-list"
+      role="listbox"
+      className={[styles.list, className].filter(Boolean).join(' ')}
+      {...htmlProps}
+    >
+      {children}
+    </div>
+  );
+}
+
+function CommandItem({
+  children,
+  value: valueProp,
+  keywords,
+  disabled = false,
+  onItemSelect,
+  className,
+  ...htmlProps
+}: CommandItemProps) {
+  const { scores, registerItem, unregisterItem, activeId, setActiveId } = useCommandContext();
+  const generatedId = React.useId();
+  const itemId = (htmlProps.id as string | undefined) ?? `command-item-${generatedId}`;
+  const itemRef = React.useRef<HTMLDivElement>(null);
+
+  // Extract text content for filtering if no value prop
+  const textValue = React.useMemo(() => {
+    if (valueProp) return valueProp;
+    if (typeof children === 'string') return children;
+    return '';
+  }, [valueProp, children]);
+
+  // Register with context
+  React.useEffect(() => {
+    registerItem(itemId, { value: textValue, keywords });
+    return () => unregisterItem(itemId);
+  }, [itemId, textValue, keywords, registerItem, unregisterItem]);
+
+  const score = scores.get(itemId) ?? 1;
+  const isVisible = score > 0;
+  const isActive = activeId === itemId;
+
+  // Scroll active item into view
+  React.useEffect(() => {
+    if (isActive && itemRef.current) {
+      itemRef.current.scrollIntoView({ block: 'nearest' });
+    }
+  }, [isActive]);
+
+  const handleClick = () => {
+    if (disabled) return;
+    onItemSelect?.();
+  };
+
+  const handleMouseEnter = () => {
+    if (!disabled) {
+      setActiveId(itemId);
+    }
+  };
+
+  return (
+    <div
+      ref={itemRef}
+      {...htmlProps}
+      id={itemId}
+      role="option"
+      aria-selected={isActive}
+      aria-disabled={disabled}
+      data-command-item=""
+      data-active={isActive || undefined}
+      data-disabled={disabled || undefined}
+      onClick={handleClick}
+      onMouseEnter={handleMouseEnter}
+      className={[
+        styles.item,
+        isActive && styles.itemActive,
+        disabled && styles.itemDisabled,
+        className,
+      ]
+        .filter(Boolean)
+        .join(' ')}
+      style={{ display: isVisible ? undefined : 'none' }}
+    >
+      {children}
+    </div>
+  );
+}
+
+function CommandGroup({ children, heading, className, ...htmlProps }: CommandGroupProps) {
+  const labelId = React.useId();
+  const groupRef = React.useRef<HTMLDivElement>(null);
+  const { scores } = useCommandContext();
+  const [hasVisibleChildren, setHasVisibleChildren] = React.useState(true);
+
+  // Check if any children are visible after each score update
+  React.useEffect(() => {
+    if (!groupRef.current) return;
+    const items = groupRef.current.querySelectorAll<HTMLElement>('[data-command-item]');
+    const anyVisible = Array.from(items).some((item) => item.style.display !== 'none');
+    setHasVisibleChildren(anyVisible);
+  }, [scores]);
+
+  return (
+    <div
+      ref={groupRef}
+      {...htmlProps}
+      role="group"
+      aria-labelledby={heading ? labelId : undefined}
+      className={[styles.group, className].filter(Boolean).join(' ')}
+      style={{ display: hasVisibleChildren ? undefined : 'none' }}
+    >
+      {heading && (
+        <div id={labelId} className={styles.groupHeading}>
+          {heading}
+        </div>
+      )}
+      {children}
+    </div>
+  );
+}
+
+function CommandEmpty({ children, className, ...htmlProps }: CommandEmptyProps) {
+  const { visibleCount } = useCommandContext();
+
+  if (visibleCount > 0) return null;
+
+  return (
+    <div
+      {...htmlProps}
+      role="option"
+      aria-disabled="true"
+      aria-selected="false"
+      className={[styles.empty, className].filter(Boolean).join(' ')}
+    >
+      {children}
+    </div>
+  );
+}
+
+function CommandSeparator({ className, ...htmlProps }: CommandSeparatorProps) {
+  return (
+    <div
+      {...htmlProps}
+      role="separator"
+      className={[styles.separator, className].filter(Boolean).join(' ')}
+    />
+  );
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const Command = Object.assign(CommandRoot, {
+  Input: CommandInput,
+  List: CommandList,
+  Item: CommandItem,
+  Group: CommandGroup,
+  Empty: CommandEmpty,
+  Separator: CommandSeparator,
+});
+
+export {
+  CommandRoot,
+  CommandInput,
+  CommandList,
+  CommandItem,
+  CommandGroup,
+  CommandEmpty,
+  CommandSeparator,
+};

package/src/components/Drawer/Drawer.fragment.tsx

@@ -0,0 +1,206 @@
+import React from 'react';
+import { defineFragment } from '@fragments-sdk/cli/core';
+import { Drawer } from '.';
+import { Button } from '../Button';
+import { Stack } from '../Stack';
+import { Input } from '../Input';
+
+export default defineFragment({
+  component: Drawer,
+
+  meta: {
+    name: 'Drawer',
+    description: 'A panel that slides in from screen edges. Extends the Dialog pattern with slide animations and edge positioning.',
+    category: 'feedback',
+    status: 'stable',
+    tags: ['drawer', 'sheet', 'panel', 'sidebar', 'slide-over'],
+    since: '0.8.2',
+  },
+
+  usage: {
+    when: [
+      'Side panels for editing or creating content',
+      'Mobile-style bottom sheets for actions',
+      'Navigation panels that slide in from the left',
+      'Detail views that overlay the main content',
+    ],
+    whenNot: [
+      'Centered modal dialogs (use Dialog)',
+      'Non-blocking notifications (use Toast)',
+      'Permanent side navigation (use Sidebar)',
+      'Small contextual menus (use Menu or Popover)',
+    ],
+    guidelines: [
+      'Default to right side for content editing and forms',
+      'Use left side for navigation drawers',
+      'Use bottom for mobile-style action sheets',
+      'Provide clear close affordance (X button or cancel)',
+      'Keep drawer content focused on a single task',
+    ],
+    accessibility: [
+      'Automatically traps focus within the drawer',
+      'Closes on Escape key press',
+      'Returns focus to trigger element on close',
+      'Uses role="dialog" with proper aria attributes',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      description: 'Drawer content (use Drawer.Content, Drawer.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: 'Dialog', relationship: 'sibling', note: 'Use Dialog for centered modal overlays' },
+    { component: 'Sidebar', relationship: 'alternative', note: 'Use Sidebar for permanent side navigation' },
+    { component: 'Popover', relationship: 'alternative', note: 'Use Popover for small contextual content' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'open: boolean - controlled open state',
+      'onOpenChange: (open) => void - open state handler',
+      'modal: boolean - blocks page interaction (default: true)',
+      'Drawer.Content side: left|right|top|bottom - slide direction (default: right)',
+      'Drawer.Content size: sm|md|lg|xl|full - panel size',
+    ],
+    scenarioTags: [
+      'overlay.drawer',
+      'form.editor',
+      'navigation.panel',
+      'action.sheet',
+    ],
+    a11yRules: ['A11Y_DIALOG_FOCUS', 'A11Y_DIALOG_ESCAPE', 'A11Y_DIALOG_LABEL'],
+  },
+
+  ai: {
+    compositionPattern: 'compound',
+    subComponents: ['Trigger', 'Content', 'Close', 'Header', 'Title', 'Description', 'Body', 'Footer'],
+    requiredChildren: ['Content'],
+    commonPatterns: [
+      '<Drawer><Drawer.Trigger><Button>Open</Button></Drawer.Trigger><Drawer.Content><Drawer.Close /><Drawer.Header><Drawer.Title>{title}</Drawer.Title></Drawer.Header><Drawer.Body>{content}</Drawer.Body><Drawer.Footer><Drawer.Close asChild><Button variant="secondary">Cancel</Button></Drawer.Close><Button>Save</Button></Drawer.Footer></Drawer.Content></Drawer>',
+    ],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Right-side drawer with header, body, and footer',
+      render: () => (
+        <Drawer>
+          <Drawer.Trigger asChild>
+            <Button>Open Drawer</Button>
+          </Drawer.Trigger>
+          <Drawer.Content>
+            <Drawer.Close />
+            <Drawer.Header>
+              <Drawer.Title>Drawer Title</Drawer.Title>
+              <Drawer.Description>
+                A panel sliding in from the right.
+              </Drawer.Description>
+            </Drawer.Header>
+            <Drawer.Body>
+              <p>Drawer content goes here.</p>
+            </Drawer.Body>
+            <Drawer.Footer>
+              <Drawer.Close asChild>
+                <Button variant="secondary">Cancel</Button>
+              </Drawer.Close>
+              <Button variant="primary">Save</Button>
+            </Drawer.Footer>
+          </Drawer.Content>
+        </Drawer>
+      ),
+    },
+    {
+      name: 'Left Side',
+      description: 'Left-side drawer for navigation',
+      render: () => (
+        <Drawer>
+          <Drawer.Trigger asChild>
+            <Button variant="secondary">Open Left</Button>
+          </Drawer.Trigger>
+          <Drawer.Content side="left">
+            <Drawer.Close />
+            <Drawer.Header>
+              <Drawer.Title>Navigation</Drawer.Title>
+            </Drawer.Header>
+            <Drawer.Body>
+              <p>Left-side drawer for navigation or filters.</p>
+            </Drawer.Body>
+          </Drawer.Content>
+        </Drawer>
+      ),
+    },
+    {
+      name: 'Bottom Sheet',
+      description: 'Bottom drawer for mobile-style actions',
+      render: () => (
+        <Drawer>
+          <Drawer.Trigger asChild>
+            <Button variant="secondary">Open Bottom Sheet</Button>
+          </Drawer.Trigger>
+          <Drawer.Content side="bottom" size="sm">
+            <Drawer.Header>
+              <Drawer.Title>Actions</Drawer.Title>
+            </Drawer.Header>
+            <Drawer.Body>
+              <p>Bottom sheet for mobile-style actions.</p>
+            </Drawer.Body>
+          </Drawer.Content>
+        </Drawer>
+      ),
+    },
+    {
+      name: 'With Form',
+      description: 'Drawer with a form layout',
+      render: () => (
+        <Drawer>
+          <Drawer.Trigger asChild>
+            <Button>Edit Settings</Button>
+          </Drawer.Trigger>
+          <Drawer.Content size="md">
+            <Drawer.Close />
+            <Drawer.Header>
+              <Drawer.Title>Settings</Drawer.Title>
+              <Drawer.Description>Update your preferences.</Drawer.Description>
+            </Drawer.Header>
+            <Drawer.Body>
+              <Stack gap="md">
+                <Input label="Display Name" placeholder="Enter name" />
+                <Input label="Email" type="email" placeholder="you@example.com" />
+              </Stack>
+            </Drawer.Body>
+            <Drawer.Footer>
+              <Drawer.Close asChild>
+                <Button variant="secondary">Cancel</Button>
+              </Drawer.Close>
+              <Button variant="primary">Save Changes</Button>
+            </Drawer.Footer>
+          </Drawer.Content>
+        </Drawer>
+      ),
+    },
+  ],
+});