@fragments-sdk/ui 0.4.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/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',

package/src/components/Tabs/Tabs.fragment.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import { defineSegment } from '@fragments/core';
-import { Tabs } from './index.js';
+import { Tabs } from '.';
 
 export default defineSegment({
   component: Tabs,

package/src/components/Tabs/Tabs.module.scss

@@ -35,8 +35,8 @@
   border-bottom: none;
   background-color: var(--fui-bg-secondary, $fui-bg-secondary);
   border-radius: var(--fui-radius-lg, $fui-radius-lg);
-  padding: 4px;
-  gap: 4px;
+  padding: var(--fui-space-0-75, $fui-space-0-75);
+  gap: var(--fui-space-0-75, $fui-space-0-75);
   width: fit-content;
 }
 

package/src/components/Text/Text.fragment.tsx

@@ -0,0 +1,188 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Text } from '.';
+
+export default defineSegment({
+  component: Text,
+
+  meta: {
+    name: 'Text',
+    description: 'Typography component for rendering text with consistent styling. Supports various sizes, weights, colors, and semantic elements.',
+    category: 'display',
+    status: 'stable',
+    tags: ['text', 'typography', 'heading', 'paragraph', 'font'],
+    since: '0.2.0',
+  },
+
+  usage: {
+    when: [
+      'Displaying text with specific typography styles',
+      'Creating headings, paragraphs, or labels',
+      'Text that needs truncation or line clamping',
+      'Consistent typography across the application',
+    ],
+    whenNot: [
+      'Complex rich text (use a rich text editor)',
+      'Code display (use CodeBlock)',
+      'Interactive text (use Link or Button)',
+    ],
+    guidelines: [
+      'Use semantic elements (h1-h6, p) via the "as" prop',
+      'Maintain heading hierarchy for accessibility',
+      'Use color variants sparingly for visual hierarchy',
+      'Consider truncation for user-generated content',
+    ],
+    accessibility: [
+      'Use proper heading levels (h1-h6) for document structure',
+      'Semantic elements convey meaning to screen readers',
+      'Truncated text should have full content in title/tooltip',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      description: 'Text content',
+      required: true,
+    },
+    as: {
+      type: 'enum',
+      description: 'HTML element to render',
+      values: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'p', 'span', 'label', 'div', 'strong', 'em', 'small', 'code'],
+      default: 'span',
+    },
+    size: {
+      type: 'enum',
+      description: 'Font size',
+      values: ['2xs', 'xs', 'sm', 'base', 'lg', 'xl', '2xl'],
+    },
+    weight: {
+      type: 'enum',
+      description: 'Font weight',
+      values: ['normal', 'medium', 'semibold'],
+    },
+    color: {
+      type: 'enum',
+      description: 'Text color',
+      values: ['primary', 'secondary', 'tertiary'],
+    },
+    font: {
+      type: 'enum',
+      description: 'Font family',
+      values: ['sans', 'mono'],
+      default: 'sans',
+    },
+    truncate: {
+      type: 'boolean',
+      description: 'Truncate with ellipsis on overflow',
+    },
+    lineClamp: {
+      type: 'number',
+      description: 'Number of lines before truncating (requires truncate)',
+    },
+  },
+
+  relations: [
+    { component: 'Link', relationship: 'sibling', note: 'Use Link for clickable text' },
+    { component: 'CodeBlock', relationship: 'alternative', note: 'Use CodeBlock for code display' },
+    { component: 'Badge', relationship: 'sibling', note: 'Use Badge for labels/tags' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'as: string - HTML element',
+      'size: 2xs|xs|sm|base|lg|xl|2xl - font size',
+      'weight: normal|medium|semibold - font weight',
+      'color: primary|secondary|tertiary - text color',
+      'font: sans|mono - font family',
+      'truncate: boolean - enable truncation',
+      'lineClamp: number - max lines',
+    ],
+    scenarioTags: [
+      'typography.text',
+      'display.content',
+      'semantic.elements',
+    ],
+    a11yRules: ['A11Y_HEADING_HIERARCHY', 'A11Y_SEMANTIC_ELEMENTS'],
+  },
+
+  variants: [
+    {
+      name: 'Sizes',
+      description: 'Different text sizes',
+      render: () => (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+          <Text size="2xs">Extra extra small (2xs)</Text>
+          <Text size="xs">Extra small (xs)</Text>
+          <Text size="sm">Small (sm)</Text>
+          <Text size="base">Base size</Text>
+          <Text size="lg">Large (lg)</Text>
+          <Text size="xl">Extra large (xl)</Text>
+          <Text size="2xl">Extra extra large (2xl)</Text>
+        </div>
+      ),
+    },
+    {
+      name: 'Weights',
+      description: 'Different font weights',
+      render: () => (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+          <Text weight="normal">Normal weight</Text>
+          <Text weight="medium">Medium weight</Text>
+          <Text weight="semibold">Semibold weight</Text>
+        </div>
+      ),
+    },
+    {
+      name: 'Colors',
+      description: 'Different text colors',
+      render: () => (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+          <Text color="primary">Primary color (default)</Text>
+          <Text color="secondary">Secondary color</Text>
+          <Text color="tertiary">Tertiary color</Text>
+        </div>
+      ),
+    },
+    {
+      name: 'Semantic Elements',
+      description: 'Using appropriate HTML elements',
+      render: () => (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+          <Text as="h1" size="2xl" weight="semibold">Heading 1</Text>
+          <Text as="h2" size="xl" weight="semibold">Heading 2</Text>
+          <Text as="h3" size="lg" weight="medium">Heading 3</Text>
+          <Text as="p" color="secondary">
+            This is a paragraph of text that demonstrates the Text component
+            with semantic paragraph element.
+          </Text>
+        </div>
+      ),
+    },
+    {
+      name: 'Monospace',
+      description: 'Monospace font for code-like text',
+      render: () => (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+          <Text font="mono" size="sm">const greeting = "Hello, World!";</Text>
+          <Text font="mono" size="sm" color="secondary">npm install @fragments-sdk/ui</Text>
+        </div>
+      ),
+    },
+    {
+      name: 'Truncation',
+      description: 'Text truncation with ellipsis',
+      render: () => (
+        <div style={{ width: '200px', display: 'flex', flexDirection: 'column', gap: '12px' }}>
+          <Text truncate>
+            This is a very long text that will be truncated with an ellipsis when it overflows.
+          </Text>
+          <Text truncate lineClamp={2}>
+            This text will be clamped to two lines. Any content beyond two lines
+            will be hidden and replaced with an ellipsis at the end.
+          </Text>
+        </div>
+      ),
+    },
+  ],
+});

package/src/components/Textarea/Textarea.fragment.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import { defineSegment } from '@fragments/core';
-import { Textarea } from './index.js';
+import { Textarea } from '.';
 
 export default defineSegment({
   component: Textarea,

package/src/components/Theme/Theme.fragment.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import { defineSegment } from '@fragments/core';
-import { ThemeProvider, ThemeToggle, useTheme } from './index.js';
+import { ThemeProvider, ThemeToggle, useTheme } from '.';
 
 // Demo component to show hook usage
 function ThemeDemo() {
@@ -20,7 +20,7 @@ export default defineSegment({
   meta: {
     name: 'Theme',
     description: 'Theme management system with provider, toggle, and hook pattern. Supports light, dark, and system modes with localStorage persistence.',
-    category: 'layout',
+    category: 'navigation',
     status: 'stable',
     tags: ['theme', 'dark-mode', 'light-mode', 'provider', 'toggle'],
     since: '0.5.0',

package/src/components/Theme/ThemeToggle.module.scss

@@ -8,7 +8,7 @@
 .toggleGroup {
   display: inline-flex;
   gap: var(--fui-space-1, $fui-space-1);
-  padding: 2px;
+  padding: var(--fui-space-0-5, $fui-space-0-5);
   background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
   border-radius: var(--fui-radius-md, $fui-radius-md);
 }
@@ -47,36 +47,36 @@
 // Size variants
 .sizeSm {
   .toggleButton {
-    width: 26px;
-    height: 22px;
+    width: var(--fui-theme-toggle-sm-width, $fui-theme-toggle-sm-width);
+    height: var(--fui-theme-toggle-sm-height, $fui-theme-toggle-sm-height);
 
     svg {
-      width: 12px;
-      height: 12px;
+      width: var(--fui-theme-toggle-sm-icon, $fui-theme-toggle-sm-icon);
+      height: var(--fui-theme-toggle-sm-icon, $fui-theme-toggle-sm-icon);
     }
   }
 }
 
 .sizeMd {
   .toggleButton {
-    width: 32px;
-    height: 28px;
+    width: var(--fui-theme-toggle-md-width, $fui-theme-toggle-md-width);
+    height: var(--fui-theme-toggle-md-height, $fui-theme-toggle-md-height);
 
     svg {
-      width: 14px;
-      height: 14px;
+      width: var(--fui-theme-toggle-md-icon, $fui-theme-toggle-md-icon);
+      height: var(--fui-theme-toggle-md-icon, $fui-theme-toggle-md-icon);
     }
   }
 }
 
 .sizeLg {
   .toggleButton {
-    width: 40px;
-    height: 34px;
+    width: var(--fui-theme-toggle-lg-width, $fui-theme-toggle-lg-width);
+    height: var(--fui-theme-toggle-lg-height, $fui-theme-toggle-lg-height);
 
     svg {
-      width: 18px;
-      height: 18px;
+      width: var(--fui-theme-toggle-lg-icon, $fui-theme-toggle-lg-icon);
+      height: var(--fui-theme-toggle-lg-icon, $fui-theme-toggle-lg-icon);
     }
   }
 }

package/src/components/ThinkingIndicator/ThinkingIndicator.fragment.tsx

@@ -0,0 +1,182 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { ThinkingIndicator } from '.';
+
+export default defineSegment({
+  component: ThinkingIndicator,
+
+  meta: {
+    name: 'ThinkingIndicator',
+    description: 'Animated indicator showing AI is processing',
+    category: 'ai',
+    status: 'stable',
+    tags: ['thinking', 'loading', 'ai', 'processing', 'indicator', 'animation'],
+  },
+
+  usage: {
+    when: [
+      'AI is processing a request and generating a response',
+      'Need visual feedback during async AI operations',
+      'Want to show multi-step progress for complex AI tasks',
+      'Indicating streaming is about to begin',
+    ],
+    whenNot: [
+      'Simple loading states (use Progress or Skeleton)',
+      'Form submission loading (use Button loading state)',
+      'Page-level loading (use Progress or Skeleton)',
+    ],
+    guidelines: [
+      'Use active prop to control visibility',
+      'Choose variant based on context (dots for chat, spinner for actions)',
+      'Enable showElapsed for longer operations',
+      'Use steps for multi-step AI workflows (tool calls, research)',
+    ],
+    accessibility: [
+      'Uses role="status" and aria-live="polite"',
+      'Provides aria-label for screen readers',
+      'Animations respect prefers-reduced-motion',
+      'Elapsed time uses tabular numbers for stability',
+    ],
+  },
+
+  props: {
+    active: {
+      type: 'boolean',
+      default: 'true',
+      description: 'Whether thinking is active',
+    },
+    label: {
+      type: 'string',
+      default: '"Thinking..."',
+      description: 'Status text',
+    },
+    variant: {
+      type: '"dots" | "pulse" | "spinner"',
+      default: '"dots"',
+      description: 'Animation style',
+    },
+    showElapsed: {
+      type: 'boolean',
+      default: 'false',
+      description: 'Show elapsed time',
+    },
+    steps: {
+      type: 'ThinkingStep[]',
+      description: 'Multi-step progress array',
+    },
+  },
+
+  relations: [
+    {
+      component: 'Message',
+      relationship: 'sibling',
+      note: 'Show ThinkingIndicator while waiting for assistant message',
+    },
+    {
+      component: 'ConversationList',
+      relationship: 'parent',
+      note: 'Typically placed at bottom of ConversationList',
+    },
+    {
+      component: 'Progress',
+      relationship: 'alternative',
+      note: 'Use Progress for determinate progress',
+    },
+  ],
+
+  contract: {
+    propsSummary: [
+      'active: boolean - whether indicator is visible (default: true)',
+      'label: string - status text (default: "Thinking...")',
+      'variant: "dots" | "pulse" | "spinner" - animation style',
+      'showElapsed: boolean - show elapsed time',
+      'steps: ThinkingStep[] - multi-step progress',
+    ],
+    scenarioTags: [
+      'ui.loading',
+      'ui.indicator',
+      'ai.thinking',
+      'ai.processing',
+    ],
+    a11yRules: [
+      'A11Y_ARIA_LIVE',
+      'A11Y_MOTION_PREFERENCE',
+    ],
+    bans: [],
+  },
+
+  variants: [
+    {
+      name: 'Dots (Default)',
+      description: 'Bouncing dots animation',
+      render: () => (
+        <ThinkingIndicator variant="dots" label="Thinking..." />
+      ),
+    },
+    {
+      name: 'Pulse',
+      description: 'Pulsing ring animation',
+      render: () => (
+        <ThinkingIndicator variant="pulse" label="Processing..." />
+      ),
+    },
+    {
+      name: 'Spinner',
+      description: 'Rotating spinner animation',
+      render: () => (
+        <ThinkingIndicator variant="spinner" label="Loading..." />
+      ),
+    },
+    {
+      name: 'With Elapsed Time',
+      description: 'Shows time since started',
+      render: () => (
+        <ThinkingIndicator
+          variant="dots"
+          label="Generating response..."
+          showElapsed
+        />
+      ),
+    },
+    {
+      name: 'Multi-Step Progress',
+      description: 'Shows progress through multiple steps',
+      render: () => (
+        <ThinkingIndicator
+          variant="spinner"
+          label="Working..."
+          steps={[
+            { id: '1', label: 'Analyzing request', status: 'complete' },
+            { id: '2', label: 'Searching knowledge base', status: 'active' },
+            { id: '3', label: 'Generating response', status: 'pending' },
+          ]}
+        />
+      ),
+    },
+    {
+      name: 'With Error Step',
+      description: 'Shows a step that encountered an error',
+      render: () => (
+        <ThinkingIndicator
+          variant="spinner"
+          label="Retrying..."
+          steps={[
+            { id: '1', label: 'Connecting to API', status: 'complete' },
+            { id: '2', label: 'Fetching data', status: 'error' },
+            { id: '3', label: 'Retrying with fallback', status: 'active' },
+          ]}
+        />
+      ),
+    },
+    {
+      name: 'Custom Label',
+      description: 'Custom status text',
+      render: () => (
+        <ThinkingIndicator
+          variant="dots"
+          label="Claude is writing code..."
+        />
+      ),
+    },
+  ],
+});