@usefragments/ui 1.0.0

package/src/components/Chart/Chart.contract.json

@@ -0,0 +1,129 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Chart",
+  "description": "Composable chart wrapper for recharts with theme-aware tooltips, legends, and color integration.",
+  "category": "display",
+  "tags": [
+    "chart",
+    "graph",
+    "data-visualization",
+    "recharts"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Chart/index.tsx",
+  "exportName": "ChartContainer",
+  "propsSummary": [
+    "config: object (required)",
+    "children: element (required)",
+    "summary: string",
+    "dataTable: node",
+    "style: object"
+  ],
+  "props": {
+    "config": {
+      "type": "object",
+      "description": "ChartConfig mapping data keys to labels/colors (optional icon per series)",
+      "required": true
+    },
+    "children": {
+      "type": "element",
+      "description": "A recharts chart component (LineChart, BarChart, etc.)",
+      "required": true
+    },
+    "summary": {
+      "type": "string",
+      "description": "Non-visual summary announced to assistive technology users",
+      "required": false
+    },
+    "dataTable": {
+      "type": "node",
+      "description": "Optional accessible data table or textual fallback",
+      "required": false
+    },
+    "style": {
+      "type": "object",
+      "description": "",
+      "required": false
+    }
+  },
+  "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 (and optionally icons for custom legend/tooltip UIs)",
+      "Use FUI CSS variables for colors so charts adapt to theme changes",
+      "Use ChartTooltip and ChartLegend for consistent themed overlays",
+      "ChartTooltip and ChartLegend accept custom content renderers for advanced formatting"
+    ],
+    "accessibility": [
+      "Charts include recharts accessibilityLayer by default",
+      "Provide meaningful labels in ChartConfig for screen readers",
+      "Consider providing a data table alternative for complex charts"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Line Chart",
+      "description": "Multi-series line chart showing trends over time",
+      "code": "<div style={{ width: '100%', height: 300 }}>\n  <ChartContainer\n    config={{\n      revenue: { label: 'Revenue', color: 'var(--fui-color-accent)' },\n      users: { label: 'Users', color: 'var(--fui-color-info)' },\n    }}\n  >\n    <LineChart data={monthlyData} margin={{ top: 5, right: 20, bottom: 5, left: 0 }}>\n      <CartesianGrid strokeDasharray=\"3 3\" />\n      <XAxis dataKey=\"month\" />\n      <YAxis />\n      <ChartTooltip />\n      <ChartLegend />\n      <Line type=\"monotone\" dataKey=\"revenue\" stroke=\"var(--fui-color-accent)\" strokeWidth={2} dot={false} />\n      <Line type=\"monotone\" dataKey=\"users\" stroke=\"var(--fui-color-info)\" strokeWidth={2} dot={false} />\n    </LineChart>\n  </ChartContainer>\n</div>"
+    },
+    {
+      "name": "Bar Chart",
+      "description": "Categorical bar chart comparing device sessions",
+      "code": "<div style={{ width: '100%', height: 300 }}>\n  <ChartContainer\n    config={{\n      sessions: { label: 'Sessions', color: 'var(--fui-color-accent)' },\n    }}\n  >\n    <BarChart data={deviceData} margin={{ top: 5, right: 20, bottom: 5, left: 0 }}>\n      <CartesianGrid strokeDasharray=\"3 3\" />\n      <XAxis dataKey=\"device\" />\n      <YAxis />\n      <ChartTooltip />\n      <Bar dataKey=\"sessions\" fill=\"var(--fui-color-accent)\" radius={[4, 4, 0, 0]} />\n    </BarChart>\n  </ChartContainer>\n</div>"
+    },
+    {
+      "name": "Area Chart",
+      "description": "Filled area chart showing revenue trend",
+      "code": "<div style={{ width: '100%', height: 300 }}>\n  <ChartContainer\n    config={{\n      revenue: { label: 'Revenue', color: 'var(--fui-color-accent)' },\n    }}\n  >\n    <AreaChart data={monthlyData} margin={{ top: 5, right: 20, bottom: 5, left: 0 }}>\n      <CartesianGrid strokeDasharray=\"3 3\" />\n      <XAxis dataKey=\"month\" />\n      <YAxis />\n      <ChartTooltip />\n      <Area type=\"monotone\" dataKey=\"revenue\" stroke=\"var(--fui-color-accent)\" fill=\"var(--fui-color-accent)\" fillOpacity={0.15} strokeWidth={2} />\n    </AreaChart>\n  </ChartContainer>\n</div>"
+    },
+    {
+      "name": "Pie Chart",
+      "description": "Donut chart showing browser share distribution",
+      "code": "<div style={{ width: '100%', height: 300 }}>\n  <ChartContainer\n    config={{\n      Chrome: { label: 'Chrome', color: 'var(--fui-color-accent)' },\n      Firefox: { label: 'Firefox', color: 'var(--fui-color-info)' },\n      Safari: { label: 'Safari', color: 'var(--fui-color-success)' },\n      Edge: { label: 'Edge', color: 'var(--fui-color-warning)' },\n    }}\n  >\n    <PieChart>\n      <ChartTooltip />\n      <ChartLegend />\n      <Pie\n        data={browserData}\n        dataKey=\"value\"\n        nameKey=\"name\"\n        cx=\"50%\"\n        cy=\"50%\"\n        innerRadius={60}\n        outerRadius={90}\n        strokeWidth={2}\n      >\n        {browserData.map((entry) => (\n          <Cell key={entry.name} fill={entry.color} />\n        ))}\n      </Pie>\n    </PieChart>\n  </ChartContainer>\n</div>"
+    }
+  ],
+  "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",
+      "Chart.Tooltip / Chart.Legend support custom content renderers for advanced overlays"
+    ],
+    "a11yRules": [
+      "A11Y_CHART_LABEL"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:52.043Z"
+  }
+}

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

@@ -0,0 +1,128 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' 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);
+  }
+}
+
+.srOnly {
+  @include visually-hidden;
+}
+
+// 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: calc(var(--fui-space-px, $fui-space-px) * 2);
+}
+
+.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: var(--fui-radius-full, $fui-radius-full);
+  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: var(--fui-radius-full, $fui-radius-full);
+  flex-shrink: 0;
+}
+
+.legendLabel {
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+}

package/src/components/Chart/Chart.stories.tsx

@@ -0,0 +1,119 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { BarChart, Bar, LineChart, Line, CartesianGrid, XAxis, YAxis } from 'recharts';
+import { ChartContainer, ChartTooltip, ChartLegend } from '.';
+
+/**
+ * ChartContainer is a composable wrapper for recharts charts with theme-aware
+ * tooltips, legends, and color integration. Pass a ChartConfig mapping data
+ * keys to labels and colors, with a recharts chart element as the child.
+ */
+const meta = {
+  title: 'Display/Chart',
+  component: ChartContainer,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Composable chart wrapper for recharts with theme-aware tooltips, legends, and color integration.',
+      },
+    },
+  },
+  argTypes: {
+    summary: {
+      control: 'text',
+      description: 'Non-visual summary announced to assistive technology users',
+    },
+  },
+  args: {
+    config: {
+      revenue: { label: 'Revenue', color: 'var(--fui-color-accent)' },
+    },
+    children: <BarChart data={[]} />,
+  },
+} satisfies Meta<typeof ChartContainer>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const monthlyData = [
+  { month: 'Jan', revenue: 4200, users: 1200 },
+  { month: 'Feb', revenue: 5100, users: 1500 },
+  { month: 'Mar', revenue: 4800, users: 1400 },
+  { month: 'Apr', revenue: 6300, users: 1900 },
+  { month: 'May', revenue: 7100, users: 2200 },
+  { month: 'Jun', revenue: 6800, users: 2100 },
+];
+
+const deviceData = [
+  { device: 'Desktop', sessions: 4300 },
+  { device: 'Mobile', sessions: 3100 },
+  { device: 'Tablet', sessions: 900 },
+];
+
+export const Line_: Story = {
+  name: 'Line Chart',
+  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>
+  ),
+};
+
+export const Bar_: Story = {
+  name: 'Bar Chart',
+  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>
+  ),
+};
+
+export const WithSummary: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: 300 }}>
+      <ChartContainer
+        config={{
+          sessions: { label: 'Sessions', color: 'var(--fui-color-accent)' },
+        }}
+        summary="Sessions by device: Desktop 4300, Mobile 3100, Tablet 900."
+      >
+        <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>
+  ),
+};