@fragments-sdk/ui 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragments-sdk/ui",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Customizable UI components built on Base UI headless primitives",
   "type": "module",
   "main": "src/index.ts",
@@ -19,7 +19,8 @@
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0"
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "recharts": ">=2.0.0 || >=3.0.0"
   },
   "dependencies": {
     "@base-ui/react": "^1.0.0",

package/src/components/Accordion/Accordion.fragment.tsx

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

package/src/components/Alert/Alert.fragment.tsx

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

package/src/components/AppShell/AppShell.fragment.tsx

@@ -1,9 +1,9 @@
 import React from 'react';
 import { defineSegment } from '@fragments/core';
-import { AppShell } from './index.js';
-import { Header } from '../Header/index.js';
-import { Sidebar } from '../Sidebar/index.js';
-import { ThemeToggle } from '../Theme/index.js';
+import { AppShell } from '.';
+import { Header } from '../Header';
+import { Sidebar } from '../Sidebar';
+import { ThemeToggle } from '../Theme';
 
 // Demo icons
 function HomeIcon() {

package/src/components/Avatar/Avatar.fragment.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import { defineSegment } from '@fragments/core';
-import { Avatar } from './index.js';
+import { Avatar } from '.';
 
 export default defineSegment({
   component: Avatar,
@@ -8,7 +8,7 @@ export default defineSegment({
   meta: {
     name: 'Avatar',
     description: 'Visual representation of a user or entity',
-    category: 'data-display',
+    category: 'display',
     status: 'stable',
     tags: ['user', 'profile', 'image', 'identity'],
   },

package/src/components/Badge/Badge.fragment.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import { defineSegment } from '@fragments/core';
-import { Badge } from './index.js';
+import { Badge } from '.';
 
 export default defineSegment({
   component: Badge,
@@ -8,7 +8,7 @@ export default defineSegment({
   meta: {
     name: 'Badge',
     description: 'Compact label for status, counts, or categorization. Draws attention to metadata without dominating the layout.',
-    category: 'feedback',
+    category: 'display',
     status: 'stable',
     tags: ['status', 'label', 'tag', 'count', 'chip'],
     since: '0.1.0',

package/src/components/Badge/Badge.module.scss

@@ -14,7 +14,7 @@
 
 // Sizes
 .sm {
-  padding: var(--fui-space-0-5, $fui-space-0-5) var(--fui-space-2, $fui-space-2);
+  padding: var(--fui-space-0-5, $fui-space-0-5) var(--fui-space-1, $fui-space-1);
   font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);
 }
 

package/src/components/Box/Box.fragment.tsx

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

package/src/components/Button/Button.fragment.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import { defineSegment } from '@fragments/core';
-import { Button } from './index.js';
+import { Button } from '.';
 
 export default defineSegment({
   component: Button,
@@ -8,7 +8,7 @@ export default defineSegment({
   meta: {
     name: 'Button',
     description: 'Interactive element for user actions and form submissions',
-    category: 'actions',
+    category: 'forms',
     status: 'stable',
     tags: ['action', 'button', 'form', 'interactive'],
   },

package/src/components/ButtonGroup/ButtonGroup.fragment.tsx

@@ -0,0 +1,153 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { ButtonGroup } from '.';
+import { Button } from '../Button';
+
+export default defineSegment({
+  component: ButtonGroup,
+
+  meta: {
+    name: 'ButtonGroup',
+    description: 'Groups related buttons together with consistent spacing and alignment. Useful for action bars, toolbars, and related button sets.',
+    category: 'forms',
+    status: 'stable',
+    tags: ['button', 'group', 'toolbar', 'actions', 'layout'],
+    since: '0.2.0',
+  },
+
+  usage: {
+    when: [
+      'Grouping related actions together',
+      'Creating toolbars or action bars',
+      'Form submit/cancel button pairs',
+      'Pagination controls',
+    ],
+    whenNot: [
+      'Unrelated buttons (use Stack instead)',
+      'Navigation links (use nav element)',
+      'Single button (no grouping needed)',
+    ],
+    guidelines: [
+      'Keep button groups focused on related actions',
+      'Use consistent button variants within a group',
+      'Consider visual hierarchy - primary action should stand out',
+      'Limit to 2-4 buttons per group for clarity',
+    ],
+    accessibility: [
+      'Group provides semantic relationship between buttons',
+      'Each button remains individually focusable',
+      'Consider using role="group" with aria-label for screen readers',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      description: 'Button elements to group together',
+      required: true,
+    },
+    gap: {
+      type: 'enum',
+      description: 'Spacing between buttons',
+      values: ['none', 'xs', 'sm', 'md'],
+      default: 'sm',
+    },
+    wrap: {
+      type: 'boolean',
+      description: 'Allow buttons to wrap to next line',
+      default: 'false',
+    },
+    align: {
+      type: 'enum',
+      description: 'Alignment of buttons',
+      values: ['start', 'center', 'end'],
+    },
+  },
+
+  relations: [
+    { component: 'Button', relationship: 'child', note: 'ButtonGroup contains Button components' },
+    { component: 'Stack', relationship: 'alternative', note: 'Use Stack for more general layout needs' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'children: ReactNode - buttons to group',
+      'gap: none|xs|sm|md - spacing between buttons',
+      'wrap: boolean - allow wrapping',
+      'align: start|center|end - alignment',
+    ],
+    scenarioTags: [
+      'layout.group',
+      'actions.toolbar',
+      'buttons.related',
+    ],
+    a11yRules: ['A11Y_GROUP_LABEL'],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Basic button group with default spacing',
+      render: () => (
+        <ButtonGroup>
+          <Button variant="secondary">Cancel</Button>
+          <Button variant="primary">Save</Button>
+        </ButtonGroup>
+      ),
+    },
+    {
+      name: 'Gap Variants',
+      description: 'Different spacing options',
+      render: () => (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+          <ButtonGroup gap="none">
+            <Button variant="secondary" size="sm">None</Button>
+            <Button variant="secondary" size="sm">Gap</Button>
+          </ButtonGroup>
+          <ButtonGroup gap="xs">
+            <Button variant="secondary" size="sm">XS</Button>
+            <Button variant="secondary" size="sm">Gap</Button>
+          </ButtonGroup>
+          <ButtonGroup gap="sm">
+            <Button variant="secondary" size="sm">SM</Button>
+            <Button variant="secondary" size="sm">Gap</Button>
+          </ButtonGroup>
+          <ButtonGroup gap="md">
+            <Button variant="secondary" size="sm">MD</Button>
+            <Button variant="secondary" size="sm">Gap</Button>
+          </ButtonGroup>
+        </div>
+      ),
+    },
+    {
+      name: 'Alignment',
+      description: 'Different alignment options',
+      render: () => (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '16px', width: '300px' }}>
+          <ButtonGroup align="start">
+            <Button variant="secondary" size="sm">Start</Button>
+            <Button variant="secondary" size="sm">Aligned</Button>
+          </ButtonGroup>
+          <ButtonGroup align="center">
+            <Button variant="secondary" size="sm">Center</Button>
+            <Button variant="secondary" size="sm">Aligned</Button>
+          </ButtonGroup>
+          <ButtonGroup align="end">
+            <Button variant="secondary" size="sm">End</Button>
+            <Button variant="secondary" size="sm">Aligned</Button>
+          </ButtonGroup>
+        </div>
+      ),
+    },
+    {
+      name: 'Form Actions',
+      description: 'Common pattern for form submit/cancel',
+      render: () => (
+        <ButtonGroup align="end">
+          <Button variant="ghost">Cancel</Button>
+          <Button variant="primary">Submit</Button>
+        </ButtonGroup>
+      ),
+    },
+  ],
+});

package/src/components/Card/Card.fragment.tsx

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

package/src/components/Chart/Chart.fragment.tsx

@@ -0,0 +1,213 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import {
+  LineChart,
+  Line,
+  BarChart,
+  Bar,
+  AreaChart,
+  Area,
+  PieChart,
+  Pie,
+  Cell,
+  XAxis,
+  YAxis,
+  CartesianGrid,
+} from 'recharts';
+import { ChartContainer, ChartTooltip, ChartLegend } from '.';
+
+// Sample data
+const monthlyData = [
+  { month: 'Jan', revenue: 4000, users: 2400 },
+  { month: 'Feb', revenue: 3000, users: 1398 },
+  { month: 'Mar', revenue: 5000, users: 3800 },
+  { month: 'Apr', revenue: 4500, users: 3200 },
+  { month: 'May', revenue: 6000, users: 4300 },
+  { month: 'Jun', revenue: 5500, users: 4100 },
+];
+
+const deviceData = [
+  { device: 'Desktop', sessions: 4500 },
+  { device: 'Mobile', sessions: 3200 },
+  { device: 'Tablet', sessions: 1800 },
+  { device: 'Other', sessions: 500 },
+];
+
+const browserData = [
+  { name: 'Chrome', value: 55, color: 'var(--fui-color-accent)' },
+  { name: 'Firefox', value: 20, color: 'var(--fui-color-info)' },
+  { name: 'Safari', value: 15, color: 'var(--fui-color-success)' },
+  { name: 'Edge', value: 10, color: 'var(--fui-color-warning)' },
+];
+
+export default defineSegment({
+  component: ChartContainer,
+
+  meta: {
+    name: 'Chart',
+    description: 'Composable chart wrapper for recharts with theme-aware tooltips, legends, and color integration.',
+    category: 'display',
+    status: 'stable',
+    tags: ['chart', 'graph', 'data-visualization', 'recharts'],
+    since: '0.3.0',
+  },
+
+  usage: {
+    when: [
+      'Displaying data trends over time',
+      'Comparing categorical data',
+      'Showing distribution or composition',
+      'Dashboard data visualizations',
+    ],
+    whenNot: [
+      'Simple numeric values (use Text or Badge)',
+      'Progress toward a goal (use Progress)',
+      'Tabular data without visualization (use Table)',
+    ],
+    guidelines: [
+      'Use ChartContainer to wrap recharts chart components',
+      'Define a ChartConfig to map data keys to labels and colors',
+      'Use FUI CSS variables for colors so charts adapt to theme changes',
+      'Use ChartTooltip and ChartLegend for consistent themed overlays',
+    ],
+    accessibility: [
+      'Charts include recharts accessibilityLayer by default',
+      'Provide meaningful labels in ChartConfig for screen readers',
+      'Consider providing a data table alternative for complex charts',
+    ],
+  },
+
+  props: {
+    config: {
+      type: 'object',
+      description: 'ChartConfig mapping data keys to labels and colors',
+    },
+    children: {
+      type: 'ReactElement',
+      description: 'A recharts chart component (LineChart, BarChart, etc.)',
+    },
+  },
+
+  relations: [
+    { component: 'Card', relationship: 'parent', note: 'Charts are typically placed inside Cards' },
+    { component: 'Progress', relationship: 'alternative', note: 'Use Progress for single-value completion' },
+    { component: 'Table', relationship: 'sibling', note: 'Combine with Table for full data views' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'config: ChartConfig - maps data keys to labels and theme colors',
+      'children: ReactElement - recharts chart component',
+    ],
+    scenarioTags: [
+      'display.chart',
+      'data.visualization',
+      'dashboard.analytics',
+    ],
+    a11yRules: ['A11Y_CHART_LABEL'],
+  },
+
+  variants: [
+    {
+      name: 'Line Chart',
+      description: 'Multi-series line chart showing trends over time',
+      render: () => (
+        <div style={{ width: '100%', height: 300 }}>
+          <ChartContainer
+            config={{
+              revenue: { label: 'Revenue', color: 'var(--fui-color-accent)' },
+              users: { label: 'Users', color: 'var(--fui-color-info)' },
+            }}
+          >
+            <LineChart data={monthlyData} margin={{ top: 5, right: 20, bottom: 5, left: 0 }}>
+              <CartesianGrid strokeDasharray="3 3" />
+              <XAxis dataKey="month" />
+              <YAxis />
+              <ChartTooltip />
+              <ChartLegend />
+              <Line type="monotone" dataKey="revenue" stroke="var(--fui-color-accent)" strokeWidth={2} dot={false} />
+              <Line type="monotone" dataKey="users" stroke="var(--fui-color-info)" strokeWidth={2} dot={false} />
+            </LineChart>
+          </ChartContainer>
+        </div>
+      ),
+    },
+    {
+      name: 'Bar Chart',
+      description: 'Categorical bar chart comparing device sessions',
+      render: () => (
+        <div style={{ width: '100%', height: 300 }}>
+          <ChartContainer
+            config={{
+              sessions: { label: 'Sessions', color: 'var(--fui-color-accent)' },
+            }}
+          >
+            <BarChart data={deviceData} margin={{ top: 5, right: 20, bottom: 5, left: 0 }}>
+              <CartesianGrid strokeDasharray="3 3" />
+              <XAxis dataKey="device" />
+              <YAxis />
+              <ChartTooltip />
+              <Bar dataKey="sessions" fill="var(--fui-color-accent)" radius={[4, 4, 0, 0]} />
+            </BarChart>
+          </ChartContainer>
+        </div>
+      ),
+    },
+    {
+      name: 'Area Chart',
+      description: 'Filled area chart showing revenue trend',
+      render: () => (
+        <div style={{ width: '100%', height: 300 }}>
+          <ChartContainer
+            config={{
+              revenue: { label: 'Revenue', color: 'var(--fui-color-accent)' },
+            }}
+          >
+            <AreaChart data={monthlyData} margin={{ top: 5, right: 20, bottom: 5, left: 0 }}>
+              <CartesianGrid strokeDasharray="3 3" />
+              <XAxis dataKey="month" />
+              <YAxis />
+              <ChartTooltip />
+              <Area type="monotone" dataKey="revenue" stroke="var(--fui-color-accent)" fill="var(--fui-color-accent)" fillOpacity={0.15} strokeWidth={2} />
+            </AreaChart>
+          </ChartContainer>
+        </div>
+      ),
+    },
+    {
+      name: 'Pie Chart',
+      description: 'Donut chart showing browser share distribution',
+      render: () => (
+        <div style={{ width: '100%', height: 300 }}>
+          <ChartContainer
+            config={{
+              Chrome: { label: 'Chrome', color: 'var(--fui-color-accent)' },
+              Firefox: { label: 'Firefox', color: 'var(--fui-color-info)' },
+              Safari: { label: 'Safari', color: 'var(--fui-color-success)' },
+              Edge: { label: 'Edge', color: 'var(--fui-color-warning)' },
+            }}
+          >
+            <PieChart>
+              <ChartTooltip />
+              <ChartLegend />
+              <Pie
+                data={browserData}
+                dataKey="value"
+                nameKey="name"
+                cx="50%"
+                cy="50%"
+                innerRadius={60}
+                outerRadius={90}
+                strokeWidth={2}
+              >
+                {browserData.map((entry) => (
+                  <Cell key={entry.name} fill={entry.color} />
+                ))}
+              </Pie>
+            </PieChart>
+          </ChartContainer>
+        </div>
+      ),
+    },
+  ],
+});

package/src/components/Chart/Chart.module.scss

@@ -0,0 +1,123 @@
+@use '../../tokens/variables' as *;
+
+// Container
+.container {
+  width: 100%;
+  height: 100%;
+  font-family: var(--fui-font-sans, $fui-font-sans);
+
+  // Override recharts defaults to use FUI tokens
+  :global(.recharts-text) {
+    fill: var(--fui-text-secondary, $fui-text-secondary);
+    font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  }
+
+  :global(.recharts-cartesian-grid) line {
+    stroke: var(--fui-border, $fui-border);
+  }
+
+  :global(.recharts-cartesian-axis-line),
+  :global(.recharts-cartesian-axis-tick-line) {
+    stroke: var(--fui-border, $fui-border);
+  }
+
+  :global(.recharts-curve.recharts-tooltip-cursor) {
+    stroke: var(--fui-border, $fui-border);
+  }
+
+  :global(.recharts-rectangle.recharts-tooltip-cursor) {
+    fill: var(--fui-bg-hover, $fui-bg-hover);
+  }
+}
+
+// Tooltip
+.tooltip {
+  background: var(--fui-bg-elevated, $fui-bg-elevated);
+  border: 1px solid var(--fui-border, $fui-border);
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+  box-shadow: var(--fui-shadow-md, $fui-shadow-md);
+  padding: var(--fui-space-2, $fui-space-2) var(--fui-space-3, $fui-space-3);
+  font-family: var(--fui-font-sans, $fui-font-sans);
+}
+
+.tooltipLabel {
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  color: var(--fui-text-primary, $fui-text-primary);
+  margin-bottom: var(--fui-space-1, $fui-space-1);
+}
+
+.tooltipItems {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.tooltipItem {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-2, $fui-space-2);
+  justify-content: space-between;
+  min-width: 100px;
+}
+
+.tooltipIndicator {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  flex-shrink: 0;
+
+  &.tooltipIndicatorLine {
+    width: 12px;
+    height: 2px;
+    border-radius: var(--fui-radius-full, $fui-radius-full);
+  }
+
+  &.tooltipIndicatorDashed {
+    width: 12px;
+    height: 0;
+    border-top: 2px dashed;
+    border-radius: 0;
+  }
+}
+
+.tooltipItemLabel {
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+}
+
+.tooltipItemValue {
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  color: var(--fui-text-primary, $fui-text-primary);
+  font-variant-numeric: tabular-nums;
+  margin-left: auto;
+}
+
+// Legend
+.legend {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: center;
+  gap: var(--fui-space-3, $fui-space-3);
+  padding-top: var(--fui-space-2, $fui-space-2);
+}
+
+.legendItem {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-1, $fui-space-1);
+}
+
+.legendDot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  flex-shrink: 0;
+}
+
+.legendLabel {
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+}