@fragments-sdk/ui 0.3.0 → 0.5.0

package/src/components/Stack/Stack.fragment.tsx

@@ -0,0 +1,194 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Stack } from '.';
+import { Button } from '../Button';
+import { Badge } from '../Badge';
+
+export default defineSegment({
+  component: Stack,
+
+  meta: {
+    name: 'Stack',
+    description: 'Flexible layout component for arranging children in rows or columns with consistent spacing. Supports responsive direction and gap.',
+    category: 'layout',
+    status: 'stable',
+    tags: ['stack', 'layout', 'flex', 'spacing', 'responsive'],
+    since: '0.2.0',
+  },
+
+  usage: {
+    when: [
+      'Arranging elements in a row or column',
+      'Creating consistent spacing between items',
+      'Building responsive layouts',
+      'Simple flexbox-based arrangements',
+    ],
+    whenNot: [
+      'Complex grid layouts (use Grid)',
+      'Button-specific grouping (use ButtonGroup)',
+      'Page-level layout (use AppShell)',
+    ],
+    guidelines: [
+      'Use semantic elements via the "as" prop when appropriate',
+      'Leverage responsive props for mobile-first layouts',
+      'Keep spacing consistent within related sections',
+      'Consider alignment for visual balance',
+    ],
+    accessibility: [
+      'Use semantic elements (nav, section, etc.) via "as" prop',
+      'Maintains source order for screen readers',
+      'No accessibility concerns with visual arrangement',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      description: 'Elements to arrange',
+      required: true,
+    },
+    direction: {
+      type: 'string | object',
+      description: 'Stack direction: "row", "column", or responsive object',
+      default: 'column',
+    },
+    gap: {
+      type: 'string | object',
+      description: 'Spacing between items: "none", "xs", "sm", "md", "lg", "xl", or responsive object',
+      default: 'md',
+    },
+    align: {
+      type: 'enum',
+      description: 'Cross-axis alignment',
+      values: ['start', 'center', 'end', 'stretch', 'baseline'],
+    },
+    justify: {
+      type: 'enum',
+      description: 'Main-axis alignment',
+      values: ['start', 'center', 'end', 'between'],
+    },
+    wrap: {
+      type: 'boolean',
+      description: 'Allow items to wrap',
+      default: 'false',
+    },
+    as: {
+      type: 'enum',
+      description: 'HTML element to render',
+      values: ['div', 'section', 'nav', 'article', 'aside', 'header', 'footer', 'main', 'ul', 'ol'],
+      default: 'div',
+    },
+  },
+
+  relations: [
+    { component: 'Grid', relationship: 'alternative', note: 'Use Grid for complex 2D layouts' },
+    { component: 'ButtonGroup', relationship: 'sibling', note: 'ButtonGroup is specialized for buttons' },
+    { component: 'Box', relationship: 'sibling', note: 'Box for single-element styling' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'direction: row|column|{responsive} - stack direction',
+      'gap: none|xs|sm|md|lg|xl|{responsive} - spacing',
+      'align: start|center|end|stretch|baseline - cross-axis',
+      'justify: start|center|end|between - main-axis',
+      'wrap: boolean - allow wrapping',
+      'as: string - HTML element',
+    ],
+    scenarioTags: [
+      'layout.flex',
+      'spacing.consistent',
+      'responsive.layout',
+    ],
+    a11yRules: ['A11Y_SEMANTIC_ELEMENTS'],
+  },
+
+  variants: [
+    {
+      name: 'Vertical Stack',
+      description: 'Default column layout',
+      render: () => (
+        <Stack gap="sm">
+          <Badge>Item 1</Badge>
+          <Badge>Item 2</Badge>
+          <Badge>Item 3</Badge>
+        </Stack>
+      ),
+    },
+    {
+      name: 'Horizontal Stack',
+      description: 'Row layout',
+      render: () => (
+        <Stack direction="row" gap="sm">
+          <Badge>Item 1</Badge>
+          <Badge>Item 2</Badge>
+          <Badge>Item 3</Badge>
+        </Stack>
+      ),
+    },
+    {
+      name: 'Gap Sizes',
+      description: 'Different spacing options',
+      render: () => (
+        <Stack gap="lg">
+          <Stack direction="row" gap="xs">
+            <Badge variant="info">XS</Badge>
+            <Badge variant="info">Gap</Badge>
+          </Stack>
+          <Stack direction="row" gap="sm">
+            <Badge variant="info">SM</Badge>
+            <Badge variant="info">Gap</Badge>
+          </Stack>
+          <Stack direction="row" gap="md">
+            <Badge variant="info">MD</Badge>
+            <Badge variant="info">Gap</Badge>
+          </Stack>
+          <Stack direction="row" gap="lg">
+            <Badge variant="info">LG</Badge>
+            <Badge variant="info">Gap</Badge>
+          </Stack>
+        </Stack>
+      ),
+    },
+    {
+      name: 'Alignment',
+      description: 'Cross-axis and main-axis alignment',
+      render: () => (
+        <Stack gap="md">
+          <Stack direction="row" gap="sm" justify="between" style={{ width: '200px', padding: '8px', background: 'var(--fui-bg-secondary)', borderRadius: '4px' }}>
+            <Badge>Start</Badge>
+            <Badge>End</Badge>
+          </Stack>
+          <Stack direction="row" gap="sm" justify="center" style={{ width: '200px', padding: '8px', background: 'var(--fui-bg-secondary)', borderRadius: '4px' }}>
+            <Badge>Centered</Badge>
+          </Stack>
+        </Stack>
+      ),
+    },
+    {
+      name: 'Responsive',
+      description: 'Direction changes at breakpoints',
+      render: () => (
+        <Stack
+          direction={{ base: 'column', md: 'row' }}
+          gap={{ base: 'sm', md: 'lg' }}
+        >
+          <Button variant="secondary">First</Button>
+          <Button variant="secondary">Second</Button>
+          <Button variant="secondary">Third</Button>
+        </Stack>
+      ),
+    },
+    {
+      name: 'Semantic Element',
+      description: 'Using nav element for navigation',
+      render: () => (
+        <Stack as="nav" direction="row" gap="md">
+          <Button variant="ghost" size="sm">Home</Button>
+          <Button variant="ghost" size="sm">About</Button>
+          <Button variant="ghost" size="sm">Contact</Button>
+        </Stack>
+      ),
+    },
+  ],
+});

package/src/components/Stack/Stack.module.scss

@@ -0,0 +1,120 @@
+@use '../../tokens/variables' as *;
+
+.stack {
+  display: flex;
+}
+
+// Direction
+.row {
+  flex-direction: row;
+}
+
+.column {
+  flex-direction: column;
+}
+
+// Responsive direction
+.directionResponsive {
+  flex-direction: var(--fui-stack-direction, column);
+
+  @media (min-width: 640px) {
+    flex-direction: var(--fui-stack-direction-sm, var(--fui-stack-direction, column));
+  }
+
+  @media (min-width: 768px) {
+    flex-direction: var(--fui-stack-direction-md, var(--fui-stack-direction-sm, var(--fui-stack-direction, column)));
+  }
+
+  @media (min-width: 1024px) {
+    flex-direction: var(--fui-stack-direction-lg, var(--fui-stack-direction-md, var(--fui-stack-direction-sm, var(--fui-stack-direction, column))));
+  }
+
+  @media (min-width: 1280px) {
+    flex-direction: var(--fui-stack-direction-xl, var(--fui-stack-direction-lg, var(--fui-stack-direction-md, var(--fui-stack-direction-sm, var(--fui-stack-direction, column)))));
+  }
+}
+
+// Gap sizes
+.gap-xs {
+  gap: var(--fui-space-1, $fui-space-1);
+}
+
+.gap-sm {
+  gap: var(--fui-space-2, $fui-space-2);
+}
+
+.gap-md {
+  gap: var(--fui-space-3, $fui-space-3);
+}
+
+.gap-lg {
+  gap: var(--fui-space-4, $fui-space-4);
+}
+
+.gap-xl {
+  gap: var(--fui-space-6, $fui-space-6);
+}
+
+// Responsive gap
+.gapResponsive {
+  gap: var(--fui-stack-gap, 0);
+
+  @media (min-width: 640px) {
+    gap: var(--fui-stack-gap-sm, var(--fui-stack-gap, 0));
+  }
+
+  @media (min-width: 768px) {
+    gap: var(--fui-stack-gap-md, var(--fui-stack-gap-sm, var(--fui-stack-gap, 0)));
+  }
+
+  @media (min-width: 1024px) {
+    gap: var(--fui-stack-gap-lg, var(--fui-stack-gap-md, var(--fui-stack-gap-sm, var(--fui-stack-gap, 0))));
+  }
+
+  @media (min-width: 1280px) {
+    gap: var(--fui-stack-gap-xl, var(--fui-stack-gap-lg, var(--fui-stack-gap-md, var(--fui-stack-gap-sm, var(--fui-stack-gap, 0)))));
+  }
+}
+
+// Align (cross-axis)
+.align-start {
+  align-items: flex-start;
+}
+
+.align-center {
+  align-items: center;
+}
+
+.align-end {
+  align-items: flex-end;
+}
+
+.align-stretch {
+  align-items: stretch;
+}
+
+.align-baseline {
+  align-items: baseline;
+}
+
+// Justify (main-axis)
+.justify-start {
+  justify-content: flex-start;
+}
+
+.justify-center {
+  justify-content: center;
+}
+
+.justify-end {
+  justify-content: flex-end;
+}
+
+.justify-between {
+  justify-content: space-between;
+}
+
+// Wrap
+.wrap {
+  flex-wrap: wrap;
+}

package/src/components/Stack/index.tsx

@@ -0,0 +1,148 @@
+import * as React from 'react';
+import styles from './Stack.module.scss';
+import '../../styles/globals.scss';
+
+type Direction = 'row' | 'column';
+type Gap = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+/** Responsive value — either a single value or per-breakpoint overrides */
+export interface ResponsiveDirection {
+  /** Default (mobile-first) */
+  base?: Direction;
+  /** ≥640px */
+  sm?: Direction;
+  /** ≥768px */
+  md?: Direction;
+  /** ≥1024px */
+  lg?: Direction;
+  /** ≥1280px */
+  xl?: Direction;
+}
+
+/** Responsive gap value */
+export interface ResponsiveGap {
+  /** Default (mobile-first) */
+  base?: Gap;
+  /** ≥640px */
+  sm?: Gap;
+  /** ≥768px */
+  md?: Gap;
+  /** ≥1024px */
+  lg?: Gap;
+  /** ≥1280px */
+  xl?: Gap;
+}
+
+export interface StackProps {
+  children: React.ReactNode;
+  /**
+   * Stack direction.
+   * - A string for fixed direction: `"row"` or `"column"`
+   * - An object for responsive direction: `{ base: "column", md: "row" }`
+   */
+  direction?: Direction | ResponsiveDirection;
+  /**
+   * Gap between items.
+   * - A string for fixed gap: `"sm"`, `"md"`, etc.
+   * - An object for responsive gap: `{ base: "sm", md: "lg" }`
+   */
+  gap?: Gap | ResponsiveGap;
+  align?: 'start' | 'center' | 'end' | 'stretch' | 'baseline';
+  justify?: 'start' | 'center' | 'end' | 'between';
+  wrap?: boolean;
+  as?: 'div' | 'section' | 'nav' | 'article' | 'aside' | 'header' | 'footer' | 'main' | 'ul' | 'ol';
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+function isResponsiveDirection(
+  direction: StackProps['direction']
+): direction is ResponsiveDirection {
+  return typeof direction === 'object' && direction !== null;
+}
+
+function isResponsiveGap(gap: StackProps['gap']): gap is ResponsiveGap {
+  return typeof gap === 'object' && gap !== null;
+}
+
+export const Stack = React.forwardRef<HTMLElement, StackProps>(
+  function Stack(
+    {
+      children,
+      direction = 'column',
+      gap = 'md',
+      align,
+      justify,
+      wrap = false,
+      as: Component = 'div',
+      className,
+      style,
+    },
+    ref
+  ) {
+    let directionClass: string;
+    let gapClass: string | false;
+    let inlineStyle: React.CSSProperties | undefined;
+
+    // Handle responsive direction
+    if (isResponsiveDirection(direction)) {
+      directionClass = styles.directionResponsive;
+      const vars: Record<string, string> = {};
+      if (direction.base) vars['--fui-stack-direction'] = direction.base;
+      if (direction.sm) vars['--fui-stack-direction-sm'] = direction.sm;
+      if (direction.md) vars['--fui-stack-direction-md'] = direction.md;
+      if (direction.lg) vars['--fui-stack-direction-lg'] = direction.lg;
+      if (direction.xl) vars['--fui-stack-direction-xl'] = direction.xl;
+      inlineStyle = vars as unknown as React.CSSProperties;
+    } else {
+      directionClass = styles[direction];
+    }
+
+    // Handle responsive gap
+    if (isResponsiveGap(gap)) {
+      gapClass = styles.gapResponsive;
+      const gapVars: Record<string, string> = {};
+      if (gap.base && gap.base !== 'none') gapVars['--fui-stack-gap'] = `var(--fui-space-${gapToSpace(gap.base)})`;
+      if (gap.sm && gap.sm !== 'none') gapVars['--fui-stack-gap-sm'] = `var(--fui-space-${gapToSpace(gap.sm)})`;
+      if (gap.md && gap.md !== 'none') gapVars['--fui-stack-gap-md'] = `var(--fui-space-${gapToSpace(gap.md)})`;
+      if (gap.lg && gap.lg !== 'none') gapVars['--fui-stack-gap-lg'] = `var(--fui-space-${gapToSpace(gap.lg)})`;
+      if (gap.xl && gap.xl !== 'none') gapVars['--fui-stack-gap-xl'] = `var(--fui-space-${gapToSpace(gap.xl)})`;
+      inlineStyle = { ...inlineStyle, ...gapVars } as React.CSSProperties;
+    } else {
+      gapClass = gap !== 'none' && styles[`gap-${gap}`];
+    }
+
+    const classes = [
+      styles.stack,
+      directionClass,
+      gapClass,
+      align && styles[`align-${align}`],
+      justify && styles[`justify-${justify}`],
+      wrap && styles.wrap,
+      className,
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    const mergedStyle = inlineStyle ? { ...inlineStyle, ...style } : style;
+
+    return (
+      <Component ref={ref as React.Ref<never>} className={classes} style={mergedStyle}>
+        {children}
+      </Component>
+    );
+  }
+);
+
+// Map gap prop values to space variable numbers
+function gapToSpace(gap: Gap): string {
+  const map: Record<Gap, string> = {
+    none: '0',
+    xs: '1',
+    sm: '2',
+    md: '3',
+    lg: '4',
+    xl: '6',
+  };
+  return map[gap];
+}

package/src/components/Table/Table.fragment.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 import { defineSegment } from '@fragments/core';
-import { Table, createColumns } from './index.js';
-import { Badge } from '../Badge/index.js';
+import { Table, createColumns } from '.';
+import { Badge } from '../Badge';
 
 // Sample data types
 interface User {
@@ -43,7 +43,7 @@ export default defineSegment({
   meta: {
     name: 'Table',
     description: 'Data table with sorting and row selection. Use for displaying structured data that needs to be scanned, compared, or acted upon.',
-    category: 'data-display',
+    category: 'display',
     status: 'stable',
     tags: ['table', 'data', 'grid', 'list', 'sorting'],
     since: '0.1.0',
@@ -134,6 +134,13 @@ export default defineSegment({
     a11yRules: ['A11Y_TABLE_HEADERS', 'A11Y_TABLE_SORT'],
   },
 
+  ai: {
+    compositionPattern: 'simple',
+    commonPatterns: [
+      '<Table columns={[{header:"Name",accessorKey:"name"},{header:"Status",accessorKey:"status"}]} data={[{name:"Item 1",status:"Active"}]} />',
+    ],
+  },
+
   variants: [
     {
       name: 'Default',

package/src/components/Table/Table.module.scss

@@ -14,6 +14,21 @@
   -moz-osx-font-smoothing: grayscale;
 }
 
+// Caption for accessibility
+.caption {
+  padding: var(--fui-space-3, $fui-space-3) 0;
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  text-align: left;
+  caption-side: top;
+}
+
+// Visually hidden caption (screen readers only)
+.captionHidden {
+  @include visually-hidden;
+}
+
 // Size variants
 .sm {
   .th,
@@ -66,6 +81,16 @@
   gap: var(--fui-space-1, $fui-space-1);
 }
 
+// Sortable header cell (for focus styles)
+.thSortable {
+  cursor: pointer;
+
+  &:focus-visible {
+    @include focus-ring;
+    outline-offset: -2px;
+  }
+}
+
 .sortable {
   cursor: pointer;
   transition: color var(--fui-transition-fast, $fui-transition-fast);
@@ -150,3 +175,35 @@
     padding-right: var(--fui-space-4, $fui-space-4);
   }
 }
+
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .headerRow {
+    border-bottom-width: 2px;
+  }
+
+  .row {
+    border-bottom-width: 2px;
+  }
+
+  .thSortable:focus-visible {
+    outline-width: 3px;
+  }
+}
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .row {
+    transition: none;
+  }
+
+  .sortable {
+    transition: none;
+  }
+}

package/src/components/Table/index.tsx

@@ -16,7 +16,7 @@ import styles from './Table.module.scss';
 // Column definition helper type
 export type TableColumn<T> = ColumnDef<T, unknown>;
 
-export interface TableProps<T> {
+export interface TableProps<T> extends Omit<React.HTMLAttributes<HTMLTableElement>, 'onClick'> {
   /** Column definitions */
   columns: TableColumn<T>[];
   /** Data array */
@@ -41,8 +41,10 @@ export interface TableProps<T> {
   emptyMessage?: string;
   /** Size variant */
   size?: 'sm' | 'md';
-  /** Additional class name */
-  className?: string;
+  /** Visible caption for the table (recommended for accessibility) */
+  caption?: string;
+  /** Hide the caption visually but keep it for screen readers */
+  captionHidden?: boolean;
 }
 
 export function Table<T>({
@@ -59,6 +61,11 @@ export function Table<T>({
   emptyMessage = 'No data available',
   size = 'md',
   className,
+  caption,
+  captionHidden = false,
+  'aria-label': ariaLabel,
+  'aria-describedby': ariaDescribedBy,
+  ...htmlProps
 }: TableProps<T>) {
   // Internal sorting state when uncontrolled
   const [internalSorting, setInternalSorting] = React.useState<SortingState>([]);
@@ -100,29 +107,57 @@ export function Table<T>({
     );
   }
 
+  // Keyboard handler for sortable headers
+  const handleHeaderKeyDown = (
+    event: React.KeyboardEvent<HTMLTableCellElement>,
+    toggleSorting: ((event: unknown) => void) | undefined
+  ) => {
+    if (toggleSorting && (event.key === 'Enter' || event.key === ' ')) {
+      event.preventDefault();
+      toggleSorting(event);
+    }
+  };
+
   return (
     <div className={styles.wrapper}>
-      <table className={rootClasses}>
+      <table
+        {...htmlProps}
+        className={rootClasses}
+        aria-label={ariaLabel}
+        aria-describedby={ariaDescribedBy}
+      >
+        {caption && (
+          <caption className={captionHidden ? styles.captionHidden : styles.caption}>
+            {caption}
+          </caption>
+        )}
         <thead className={styles.thead}>
           {table.getHeaderGroups().map((headerGroup) => (
             <tr key={headerGroup.id} className={styles.headerRow}>
               {headerGroup.headers.map((header) => {
                 const canSort = sortable && header.column.getCanSort();
                 const sortDirection = header.column.getIsSorted();
+                const toggleSorting = canSort ? header.column.getToggleSortingHandler() : undefined;
 
                 return (
                   <th
                     key={header.id}
-                    className={styles.th}
+                    className={[styles.th, canSort && styles.thSortable].filter(Boolean).join(' ')}
                     style={{
                       width: header.getSize() !== 150 ? header.getSize() : undefined,
                     }}
-                    onClick={canSort ? header.column.getToggleSortingHandler() : undefined}
+                    scope="col"
+                    tabIndex={canSort ? 0 : undefined}
+                    role={canSort ? 'columnheader' : undefined}
+                    onClick={toggleSorting}
+                    onKeyDown={canSort ? (e) => handleHeaderKeyDown(e, toggleSorting) : undefined}
                     aria-sort={
                       sortDirection
                         ? sortDirection === 'asc'
                           ? 'ascending'
                           : 'descending'
+                        : canSort
+                        ? 'none'
                         : undefined
                     }
                   >
@@ -199,6 +234,7 @@ function SortIcon() {
       viewBox="0 0 12 12"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
+      aria-hidden="true"
     >
       <path
         d="M6 2L8.5 5H3.5L6 2Z"
@@ -222,6 +258,7 @@ function SortAscIcon() {
       viewBox="0 0 12 12"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
+      aria-hidden="true"
     >
       <path d="M6 2L8.5 5H3.5L6 2Z" fill="currentColor" />
     </svg>
@@ -236,6 +273,7 @@ function SortDescIcon() {
       viewBox="0 0 12 12"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
+      aria-hidden="true"
     >
       <path d="M6 10L3.5 7H8.5L6 10Z" fill="currentColor" />
     </svg>