@tribepad/themis 1.0.0

package/src/elements/Chart/Chart.stories.tsx

@@ -0,0 +1,616 @@
+/**
+ * Chart Component - Storybook Stories
+ *
+ * Interactive examples and documentation for the Chart component.
+ * Demonstrates bar and line charts with accessibility features.
+ *
+ * @see chart-prd.md DOC-002 (Storybook Stories Requirements)
+ * @see Storybook (when running)
+ */
+
+import { type ReactElement } from 'react';
+import type { Meta, StoryObj } from '@storybook/nextjs';
+import { Chart } from './Chart';
+import type { DataSeries } from './Chart.types';
+
+const meta = {
+  title: 'Elements/Chart',
+  component: Chart,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Accessible, keyboard-interactive chart component supporting bar and line types. Features 2D keyboard navigation, screen reader announcements, and WCAG 2.2 AAA compliance.\n\n**Key Features:**\n- Keyboard navigation with Arrow keys (Left/Right/Up/Down)\n- Screen reader announcements via aria-live region\n- Hidden data table fallback for screen readers\n- Tooltip on focus/hover\n- Maximum 5 series per chart',
+      },
+    },
+  },
+  argTypes: {
+    type: {
+      control: 'select',
+      options: ['bar', 'line'],
+      description: 'Chart type: bar or line',
+    },
+    variant: {
+      control: 'select',
+      options: ['default', 'muted'],
+      description: 'Visual variant for the chart container',
+    },
+    showTooltip: {
+      control: 'boolean',
+      description: 'Show tooltip on focus/hover',
+    },
+    showGrid: {
+      control: 'boolean',
+      description: 'Show grid lines',
+    },
+    showLegend: {
+      control: 'boolean',
+      description: 'Show legend (auto: shown when >1 series)',
+    },
+    announceTrends: {
+      control: 'boolean',
+      description: 'Announce trend percentages to screen readers',
+    },
+    trendUpFormat: {
+      control: 'text',
+      description: 'ICU format string for upward trend (use {percent} placeholder)',
+    },
+    trendDownFormat: {
+      control: 'text',
+      description: 'ICU format string for downward trend (use {percent} placeholder)',
+    },
+    startAtZero: {
+      control: 'boolean',
+      description: 'Y-axis starts at zero',
+    },
+  },
+} satisfies Meta<typeof Chart>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ============================================================================
+// Sample Data
+// ============================================================================
+
+const singleSeriesData: DataSeries[] = [
+  {
+    name: 'Revenue',
+    data: [
+      { label: 'Jan', value: 4200 },
+      { label: 'Feb', value: 4800 },
+      { label: 'Mar', value: 5100 },
+      { label: 'Apr', value: 4900 },
+      { label: 'May', value: 5600 },
+      { label: 'Jun', value: 6200 },
+    ],
+  },
+];
+
+const multiSeriesData: DataSeries[] = [
+  {
+    name: 'Revenue',
+    data: [
+      { label: 'Q1', value: 14100 },
+      { label: 'Q2', value: 16700 },
+      { label: 'Q3', value: 15200 },
+      { label: 'Q4', value: 18900 },
+    ],
+  },
+  {
+    name: 'Expenses',
+    pattern: 'dashed',
+    data: [
+      { label: 'Q1', value: 11200 },
+      { label: 'Q2', value: 12100 },
+      { label: 'Q3', value: 11800 },
+      { label: 'Q4', value: 13500 },
+    ],
+  },
+];
+
+const applicationsData: DataSeries[] = [
+  {
+    name: 'Applications',
+    data: [
+      { label: 'Mon', value: 45 },
+      { label: 'Tue', value: 62 },
+      { label: 'Wed', value: 58 },
+      { label: 'Thu', value: 71 },
+      { label: 'Fri', value: 53 },
+    ],
+  },
+];
+
+const hiringPipelineData: DataSeries[] = [
+  {
+    name: 'New',
+    data: [
+      { label: 'Week 1', value: 120 },
+      { label: 'Week 2', value: 145 },
+      { label: 'Week 3', value: 132 },
+      { label: 'Week 4', value: 158 },
+    ],
+  },
+  {
+    name: 'Screening',
+    pattern: 'dashed',
+    data: [
+      { label: 'Week 1', value: 85 },
+      { label: 'Week 2', value: 92 },
+      { label: 'Week 3', value: 88 },
+      { label: 'Week 4', value: 95 },
+    ],
+  },
+  {
+    name: 'Interview',
+    pattern: 'dotted',
+    data: [
+      { label: 'Week 1', value: 32 },
+      { label: 'Week 2', value: 38 },
+      { label: 'Week 3', value: 35 },
+      { label: 'Week 4', value: 42 },
+    ],
+  },
+];
+
+// ============================================================================
+// Default Story
+// ============================================================================
+
+/**
+ * Default Bar Chart
+ * Single series bar chart showing monthly revenue data.
+ */
+export const Default: Story = {
+  args: {
+    data: singleSeriesData,
+    type: 'bar',
+    title: 'Monthly Revenue',
+    description: 'Revenue data for the first half of 2024',
+    xAxisLabel: 'Month',
+    yAxisLabel: 'Revenue (£)',
+  },
+};
+
+// ============================================================================
+// Chart Types
+// ============================================================================
+
+/**
+ * Bar Chart
+ * Standard bar chart with single series.
+ */
+export const BarChart: Story = {
+  args: {
+    data: applicationsData,
+    type: 'bar',
+    title: 'Daily Applications',
+    description: 'Number of job applications received per day',
+    xAxisLabel: 'Day',
+    yAxisLabel: 'Applications',
+  },
+};
+
+/**
+ * Line Chart
+ * Line chart with single series.
+ */
+export const LineChart: Story = {
+  args: {
+    data: singleSeriesData,
+    type: 'line',
+    title: 'Revenue Trend',
+    description: 'Revenue trend over the first half of 2024',
+    xAxisLabel: 'Month',
+    yAxisLabel: 'Revenue (£)',
+  },
+};
+
+// ============================================================================
+// Multi-Series Charts
+// ============================================================================
+
+/**
+ * Multi-Series Bar Chart
+ * Bar chart comparing revenue vs expenses.
+ */
+export const MultiSeriesBar: Story = {
+  args: {
+    data: multiSeriesData,
+    type: 'bar',
+    title: 'Quarterly Revenue vs Expenses',
+    description: 'Comparison of revenue and expenses by quarter',
+    xAxisLabel: 'Quarter',
+    yAxisLabel: 'Amount (£)',
+  },
+};
+
+/**
+ * Multi-Series Line Chart
+ * Line chart with multiple series showing different line patterns.
+ */
+export const MultiSeriesLine: Story = {
+  args: {
+    data: multiSeriesData,
+    type: 'line',
+    title: 'Quarterly Financial Trends',
+    description: 'Revenue and expenses trends over quarters',
+    xAxisLabel: 'Quarter',
+    yAxisLabel: 'Amount (£)',
+  },
+};
+
+/**
+ * Three Series Line Chart
+ * Hiring pipeline with three data series.
+ */
+export const ThreeSeriesLine: Story = {
+  args: {
+    data: hiringPipelineData,
+    type: 'line',
+    title: 'Hiring Pipeline Progress',
+    description: 'Candidates at each stage of the hiring process',
+    xAxisLabel: 'Week',
+    yAxisLabel: 'Candidates',
+  },
+};
+
+// ============================================================================
+// Variant Options
+// ============================================================================
+
+/**
+ * Muted Variant
+ * Chart with muted background styling.
+ */
+export const MutedVariant: Story = {
+  args: {
+    data: singleSeriesData,
+    type: 'bar',
+    title: 'Monthly Revenue',
+    description: 'Revenue data with muted background',
+    xAxisLabel: 'Month',
+    yAxisLabel: 'Revenue (£)',
+    variant: 'muted',
+  },
+};
+
+/**
+ * Without Grid
+ * Chart without grid lines for minimal appearance.
+ */
+export const WithoutGrid: Story = {
+  args: {
+    data: singleSeriesData,
+    type: 'line',
+    title: 'Revenue Trend',
+    description: 'Clean chart without grid lines',
+    xAxisLabel: 'Month',
+    yAxisLabel: 'Revenue (£)',
+    showGrid: false,
+  },
+};
+
+/**
+ * Without Tooltip
+ * Chart with tooltip disabled.
+ */
+export const WithoutTooltip: Story = {
+  args: {
+    data: singleSeriesData,
+    type: 'bar',
+    title: 'Monthly Revenue',
+    description: 'Chart without hover/focus tooltips',
+    xAxisLabel: 'Month',
+    yAxisLabel: 'Revenue (£)',
+    showTooltip: false,
+  },
+};
+
+/**
+ * Force Legend on Single Series
+ * Shows legend even with single series.
+ */
+export const ForceLegend: Story = {
+  args: {
+    data: singleSeriesData,
+    type: 'bar',
+    title: 'Monthly Revenue',
+    description: 'Single series with legend forced on',
+    xAxisLabel: 'Month',
+    yAxisLabel: 'Revenue (£)',
+    showLegend: true,
+  },
+};
+
+/**
+ * Hide Legend on Multi-Series
+ * Hides legend even with multiple series.
+ */
+export const HideLegend: Story = {
+  args: {
+    data: multiSeriesData,
+    type: 'bar',
+    title: 'Revenue vs Expenses',
+    description: 'Multi-series chart with legend hidden',
+    xAxisLabel: 'Quarter',
+    yAxisLabel: 'Amount (£)',
+    showLegend: false,
+  },
+};
+
+// ============================================================================
+// Accessibility Features
+// ============================================================================
+
+/**
+ * With Trend Announcements
+ * Announces percentage changes between points for screen readers.
+ */
+export const WithTrendAnnouncements: Story = {
+  args: {
+    data: singleSeriesData,
+    type: 'line',
+    title: 'Revenue Trend',
+    description: 'Use arrow keys to navigate and hear trend percentages',
+    xAxisLabel: 'Month',
+    yAxisLabel: 'Revenue (£)',
+    announceTrends: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Navigate with arrow keys to hear percentage changes announced by screen readers. Example: "Feb, £4,800, up 14% from previous. 2 of 6."',
+      },
+    },
+  },
+};
+
+/**
+ * With Custom Trend Translations (French)
+ * Demonstrates multilingual support with ICU format strings.
+ */
+export const WithCustomTrendTranslations: Story = {
+  args: {
+    data: singleSeriesData,
+    type: 'line',
+    title: 'Tendance des Revenus',
+    description: 'Utilisez les touches fléchées pour naviguer',
+    xAxisLabel: 'Mois',
+    yAxisLabel: 'Revenus (€)',
+    announceTrends: true,
+    trendUpFormat: 'en hausse de {percent}%',
+    trendDownFormat: 'en baisse de {percent}%',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Demonstrates custom trend translations using ICU format strings. The `{percent}` placeholder is replaced with the calculated percentage. Example: "en hausse de 14%"',
+      },
+    },
+  },
+};
+
+/**
+ * Keyboard Navigation Demo
+ * Demonstrates keyboard navigation features.
+ */
+export const KeyboardNavigation: Story = {
+  args: {
+    data: multiSeriesData,
+    type: 'line',
+    title: 'Interactive Chart',
+    description:
+      'Tab to focus, use arrow keys: Left/Right to move between points, Up/Down between series',
+    xAxisLabel: 'Quarter',
+    yAxisLabel: 'Amount (£)',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '**Keyboard Navigation:**\n- Tab: Focus the chart\n- Arrow Left/Right: Navigate between points\n- Arrow Up/Down: Navigate between series\n- Home/End: Jump to first/last point\n- Enter/Space: Select a point\n- Escape: Clear selection',
+      },
+    },
+  },
+};
+
+// ============================================================================
+// Y-Axis Options
+// ============================================================================
+
+/**
+ * Y-Axis Not Starting at Zero
+ * Shows data without forcing the Y-axis to start at zero.
+ */
+export const YAxisNotAtZero: Story = {
+  args: {
+    data: [
+      {
+        name: 'Temperature',
+        data: [
+          { label: 'Mon', value: 18 },
+          { label: 'Tue', value: 21 },
+          { label: 'Wed', value: 19 },
+          { label: 'Thu', value: 22 },
+          { label: 'Fri', value: 20 },
+        ],
+      },
+    ],
+    type: 'line',
+    title: 'Weekly Temperature',
+    description: 'Y-axis scaled to show variation without starting at zero',
+    xAxisLabel: 'Day',
+    yAxisLabel: 'Temperature (°C)',
+    startAtZero: false,
+  },
+};
+
+// ============================================================================
+// Line Patterns
+// ============================================================================
+
+/**
+ * Line Patterns
+ * Demonstrates different line patterns for accessibility.
+ */
+export const LinePatterns: Story = {
+  args: {
+    data: [
+      {
+        name: 'Solid Line',
+        pattern: 'solid',
+        data: [
+          { label: 'Jan', value: 100 },
+          { label: 'Feb', value: 120 },
+          { label: 'Mar', value: 110 },
+        ],
+      },
+      {
+        name: 'Dashed Line',
+        pattern: 'dashed',
+        data: [
+          { label: 'Jan', value: 80 },
+          { label: 'Feb', value: 95 },
+          { label: 'Mar', value: 85 },
+        ],
+      },
+      {
+        name: 'Dotted Line',
+        pattern: 'dotted',
+        data: [
+          { label: 'Jan', value: 60 },
+          { label: 'Feb', value: 70 },
+          { label: 'Mar', value: 65 },
+        ],
+      },
+    ],
+    type: 'line',
+    title: 'Line Pattern Comparison',
+    description: 'Different line patterns help distinguish series for colorblind users',
+    xAxisLabel: 'Month',
+    yAxisLabel: 'Value',
+  },
+};
+
+// ============================================================================
+// Real-World Examples
+// ============================================================================
+
+/**
+ * Candidate Pipeline
+ * Real-world recruiting dashboard example.
+ */
+export const CandidatePipeline: Story = {
+  render: function CandidatePipelineChart(): ReactElement {
+    const pipelineData: DataSeries[] = [
+      {
+        name: 'Applied',
+        data: [
+          { label: 'Jan', value: 245 },
+          { label: 'Feb', value: 312 },
+          { label: 'Mar', value: 287 },
+          { label: 'Apr', value: 341 },
+        ],
+      },
+      {
+        name: 'Interviewed',
+        pattern: 'dashed',
+        data: [
+          { label: 'Jan', value: 78 },
+          { label: 'Feb', value: 92 },
+          { label: 'Mar', value: 85 },
+          { label: 'Apr', value: 98 },
+        ],
+      },
+      {
+        name: 'Offered',
+        pattern: 'dotted',
+        data: [
+          { label: 'Jan', value: 12 },
+          { label: 'Feb', value: 18 },
+          { label: 'Mar', value: 15 },
+          { label: 'Apr', value: 21 },
+        ],
+      },
+    ];
+
+    return (
+      <div className="space-y-4">
+        <h2 className="text-xl font-bold">Recruiting Dashboard</h2>
+        <Chart
+          data={pipelineData}
+          type="line"
+          title="Candidate Pipeline"
+          description="Monthly breakdown of candidates at each pipeline stage"
+          xAxisLabel="Month"
+          yAxisLabel="Candidates"
+          announceTrends
+        />
+      </div>
+    );
+  },
+};
+
+/**
+ * Time to Hire
+ * Average time to hire by department.
+ */
+export const TimeToHire: Story = {
+  args: {
+    data: [
+      {
+        name: 'Time to Hire',
+        data: [
+          { label: 'Engineering', value: 42 },
+          { label: 'Sales', value: 28 },
+          { label: 'Marketing', value: 35 },
+          { label: 'Operations', value: 31 },
+          { label: 'Finance', value: 38 },
+        ],
+      },
+    ],
+    type: 'bar',
+    title: 'Average Time to Hire by Department',
+    description: 'Average number of days from application to offer by department',
+    xAxisLabel: 'Department',
+    yAxisLabel: 'Days',
+  },
+};
+
+// ============================================================================
+// All Themes
+// ============================================================================
+
+/**
+ * All Themes
+ * Preview chart in all 4 themes.
+ */
+export const AllThemes: Story = {
+  render: () => (
+    <div className="grid grid-cols-2 gap-8">
+      {(['light', 'dark', 'highContrast', 'colorblind'] as const).map((theme) => (
+        <div
+          key={theme}
+          data-theme={theme}
+          className="p-4 border rounded bg-[var(--background)] text-[var(--foreground)]"
+        >
+          <h3 className="font-bold mb-2 capitalize">{theme} Theme</h3>
+          <Chart
+            data={applicationsData}
+            type="bar"
+            title="Applications"
+            description={`Chart in ${theme} theme`}
+            xAxisLabel="Day"
+            yAxisLabel="Count"
+          />
+        </div>
+      ))}
+    </div>
+  ),
+};