@spteck/fluentui-react-charts 0.1.8

package/src/charts/steamChart/README.MD

@@ -0,0 +1,414 @@
+# SteamChart Component
+
+A specialized stream chart (stacked area chart) component built with Chart.js and Fluent UI React. This component displays data as flowing, stacked areas that create a "stream" effect, making it perfect for visualizing how different categories contribute to a total over time, with smooth transitions and the ability to toggle between raw values and percentages.
+
+## Features
+
+- **Stream Visualization**: Smooth, flowing stacked areas with curved boundaries
+- **Percentage Toggle**: Switch between raw values and percentage view
+- **Interactive Legend**: Toggle series visibility with click interactions
+- **Smooth Animations**: Fluid transitions with configurable easing
+- **Filled Areas**: Semi-transparent filled areas for better visual flow
+- **Fluent UI Integration**: Seamless integration with Fluent UI themes and design system
+- **Data Labels**: Optional display of values directly on data points
+- **Responsive Design**: Automatically adapts to container dimensions
+- **TypeScript Support**: Full TypeScript support with generic types
+- **Custom Tooltips**: Rich tooltips showing detailed breakdown information
+
+## Installation
+
+```bash
+npm install chart.js react-chartjs-2 chartjs-plugin-datalabels @fluentui/react-components
+```
+
+## Basic Usage
+
+```tsx
+import React from 'react';
+import { SteamChart } from './components/steamChart/SteamChart';
+import { webLightTheme } from '@fluentui/react-components';
+
+interface MusicStreamingData {
+  month: string;
+  pop: number;
+  rock: number;
+  jazz: number;
+  classical: number;
+  electronic: number;
+}
+
+const streamingData: MusicStreamingData[] = [
+  { month: 'Jan', pop: 45000, rock: 32000, jazz: 12000, classical: 8000, electronic: 18000 },
+  { month: 'Feb', pop: 48000, rock: 35000, jazz: 13000, classical: 9000, electronic: 20000 },
+  { month: 'Mar', pop: 52000, rock: 38000, jazz: 15000, classical: 10000, electronic: 22000 },
+  { month: 'Apr', pop: 49000, rock: 36000, jazz: 14000, classical: 11000, electronic: 25000 },
+  { month: 'May', pop: 55000, rock: 40000, jazz: 16000, classical: 12000, electronic: 28000 },
+];
+
+function App() {
+  return (
+    <div style={{ width: '800px', height: '500px' }}>
+      <SteamChart
+        data={[
+          {
+            label: 'Pop',
+            data: streamingData.map(d => ({ month: d.month, streams: d.pop }))
+          },
+          {
+            label: 'Rock',
+            data: streamingData.map(d => ({ month: d.month, streams: d.rock }))
+          },
+          {
+            label: 'Jazz',
+            data: streamingData.map(d => ({ month: d.month, streams: d.jazz }))
+          },
+          {
+            label: 'Classical',
+            data: streamingData.map(d => ({ month: d.month, streams: d.classical }))
+          },
+          {
+            label: 'Electronic',
+            data: streamingData.map(d => ({ month: d.month, streams: d.electronic }))
+          }
+        ]}
+        getPrimary={(datum) => datum.month}
+        getSecondary={(datum) => datum.streams}
+        title="Music Streaming by Genre"
+        theme={webLightTheme}
+      />
+    </div>
+  );
+}
+```
+
+## Props
+
+### SteamChartProps<T>
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `data` | `{ label: string; data: T[] }[]` | Yes | - | Array of data series with labels and data points |
+| `getPrimary` | `(datum: T) => string \| number` | Yes | - | Function to extract the x-axis category from each data point |
+| `getSecondary` | `(datum: T) => number` | Yes | - | Function to extract the y-axis value from each data point |
+| `title` | `string` | No | - | Chart title displayed at the top |
+| `showDataLabels` | `boolean` | No | `false` | Whether to show data values on data points |
+| `theme` | `Theme` | No | `webLightTheme` | Fluent UI theme object for styling |
+
+## Advanced Usage
+
+### Social Media Engagement
+
+```tsx
+interface SocialEngagement {
+  week: string;
+  facebook: number;
+  instagram: number;
+  twitter: number;
+  linkedin: number;
+  tiktok: number;
+}
+
+const engagementData: SocialEngagement[] = [
+  { week: 'Week 1', facebook: 12000, instagram: 18000, twitter: 8000, linkedin: 3000, tiktok: 25000 },
+  { week: 'Week 2', facebook: 13500, instagram: 20000, twitter: 9000, linkedin: 3500, tiktok: 28000 },
+  { week: 'Week 3', facebook: 11000, instagram: 22000, twitter: 7500, linkedin: 4000, tiktok: 32000 },
+  { week: 'Week 4', facebook: 14000, instagram: 24000, twitter: 8500, linkedin: 4500, tiktok: 35000 },
+];
+
+<SteamChart
+  data={[
+    {
+      label: 'Facebook',
+      data: engagementData.map(d => ({ week: d.week, engagement: d.facebook }))
+    },
+    {
+      label: 'Instagram',
+      data: engagementData.map(d => ({ week: d.week, engagement: d.instagram }))
+    },
+    {
+      label: 'Twitter',
+      data: engagementData.map(d => ({ week: d.week, engagement: d.twitter }))
+    },
+    {
+      label: 'LinkedIn',
+      data: engagementData.map(d => ({ week: d.week, engagement: d.linkedin }))
+    },
+    {
+      label: 'TikTok',
+      data: engagementData.map(d => ({ week: d.week, engagement: d.tiktok }))
+    }
+  ]}
+  getPrimary={(datum) => datum.week}
+  getSecondary={(datum) => datum.engagement}
+  title="Social Media Engagement by Platform"
+  showDataLabels={true}
+  theme={webLightTheme}
+/>
+```
+
+### E-commerce Sales Channels
+
+```tsx
+interface SalesChannelData {
+  quarter: string;
+  website: number;
+  mobileApp: number;
+  retailStores: number;
+  marketplace: number;
+  wholesale: number;
+}
+
+const salesData: SalesChannelData[] = [
+  { quarter: 'Q1 2024', website: 250000, mobileApp: 180000, retailStores: 320000, marketplace: 150000, wholesale: 200000 },
+  { quarter: 'Q2 2024', website: 280000, mobileApp: 220000, retailStores: 310000, marketplace: 180000, wholesale: 220000 },
+  { quarter: 'Q3 2024', website: 320000, mobileApp: 260000, retailStores: 300000, marketplace: 210000, wholesale: 240000 },
+  { quarter: 'Q4 2024', website: 380000, mobileApp: 300000, retailStores: 290000, marketplace: 250000, wholesale: 260000 },
+];
+
+<SteamChart
+  data={[
+    {
+      label: 'Website',
+      data: salesData.map(d => ({ quarter: d.quarter, sales: d.website }))
+    },
+    {
+      label: 'Mobile App',
+      data: salesData.map(d => ({ quarter: d.quarter, sales: d.mobileApp }))
+    },
+    {
+      label: 'Retail Stores',
+      data: salesData.map(d => ({ quarter: d.quarter, sales: d.retailStores }))
+    },
+    {
+      label: 'Marketplace',
+      data: salesData.map(d => ({ quarter: d.quarter, sales: d.marketplace }))
+    },
+    {
+      label: 'Wholesale',
+      data: salesData.map(d => ({ quarter: d.quarter, sales: d.wholesale }))
+    }
+  ]}
+  getPrimary={(datum) => datum.quarter}
+  getSecondary={(datum) => datum.sales}
+  title="Sales Performance by Channel"
+  theme={webLightTheme}
+/>
+```
+
+### Energy Production Sources
+
+```tsx
+interface EnergyProduction {
+  month: string;
+  solar: number;
+  wind: number;
+  hydro: number;
+  nuclear: number;
+  coal: number;
+  naturalGas: number;
+}
+
+const energyData: EnergyProduction[] = [
+  { month: 'Jan', solar: 1200, wind: 2800, hydro: 3500, nuclear: 4200, coal: 2100, naturalGas: 3200 },
+  { month: 'Feb', solar: 1400, wind: 3200, hydro: 3200, nuclear: 4200, coal: 1900, naturalGas: 3100 },
+  { month: 'Mar', solar: 1800, wind: 3600, hydro: 3800, nuclear: 4200, coal: 1700, naturalGas: 2900 },
+  { month: 'Apr', solar: 2200, wind: 3400, hydro: 4200, nuclear: 4200, coal: 1500, naturalGas: 2700 },
+];
+
+<SteamChart
+  data={[
+    {
+      label: 'Solar',
+      data: energyData.map(d => ({ month: d.month, production: d.solar }))
+    },
+    {
+      label: 'Wind',
+      data: energyData.map(d => ({ month: d.month, production: d.wind }))
+    },
+    {
+      label: 'Hydro',
+      data: energyData.map(d => ({ month: d.month, production: d.hydro }))
+    },
+    {
+      label: 'Nuclear',
+      data: energyData.map(d => ({ month: d.month, production: d.nuclear }))
+    },
+    {
+      label: 'Coal',
+      data: energyData.map(d => ({ month: d.month, production: d.coal }))
+    },
+    {
+      label: 'Natural Gas',
+      data: energyData.map(d => ({ month: d.month, production: d.naturalGas }))
+    }
+  ]}
+  getPrimary={(datum) => datum.month}
+  getSecondary={(datum) => datum.production}
+  title="Energy Production by Source (MWh)"
+  showDataLabels={true}
+  theme={webLightTheme}
+/>
+```
+
+## Data Structure
+
+The component expects data in the following format:
+
+```tsx
+interface ChartSeries<T> {
+  label: string;  // Series name (appears in legend)
+  data: T[];      // Array of data points
+}
+```
+
+Each data point `T` should contain:
+
+- A primary value (x-axis category) - string or number
+- A secondary value (y-axis value) - number
+
+## Stream Chart Characteristics
+
+### Visual Flow
+
+- **Smooth Curves**: High tension value (0.5) creates flowing stream effect
+- **Stacked Areas**: Each category flows on top of the previous ones
+- **No Borders**: Transparent borders create seamless flow between areas
+- **Organic Shape**: Natural, river-like appearance
+
+### Percentage Toggle
+
+- **Raw Values**: Shows actual numerical values
+- **Percentage View**: Shows proportional contribution (0-100%)
+- **Toggle Button**: Central button to switch between views
+- **Dynamic Scaling**: Y-axis adjusts automatically
+
+## Use Cases
+
+Steam charts are particularly effective for:
+
+### Content Consumption
+
+- **Media Streaming**: Different genres or content types over time
+- **Website Traffic**: Traffic sources and their evolution
+- **App Usage**: Feature usage patterns across time periods
+
+### Market Analysis
+
+- **Market Share**: How different players' shares flow over time
+- **Product Mix**: Sales composition with smooth transitions
+- **Demographic Changes**: Population segments over time
+
+### Resource Allocation
+
+- **Budget Distribution**: How budget allocation changes over time
+- **Team Productivity**: Contribution of different teams
+- **Energy Mix**: Renewable vs non-renewable energy sources
+
+### Communication Channels
+
+- **Social Media Engagement**: Platform-wise engagement trends
+- **Customer Support**: Channel usage patterns
+- **Marketing Channels**: Campaign performance across channels
+
+## Interactive Features
+
+### Percentage Toggle Button
+
+- Central toggle button to switch between raw values and percentages
+- Smooth transitions between view modes
+- Y-axis automatically adjusts scale and labels
+- Maintains visual flow during transitions
+
+### Legend Controls
+
+- Click legend items to show/hide data series
+- Visual feedback on hover states
+- At least one series must remain visible
+- Maintains stream flow when series are hidden
+
+### Stream Interactions
+
+- Hover effects on stream areas
+- Rich tooltips showing breakdown of values
+- Smooth animations with easing effects
+- Index-based interaction mode for better UX
+
+## Styling and Theme Integration
+
+The component uses Fluent UI theme tokens:
+
+```tsx
+// Stream styling
+backgroundColor: seriesColor (semi-transparent)
+borderColor: 'transparent'
+borderWidth: 0
+fill: true
+tension: 0.5 (high curve smoothness)
+
+// Animation
+duration: 800ms
+easing: 'easeOutQuart'
+
+// Typography
+fontFamily: theme.fontFamilyBase
+fontSize: theme.fontSizeBase200
+fontWeight: theme.fontWeightSemibold
+color: theme.colorNeutralForeground1
+
+// Toggle button
+appearance: 'secondary'
+shape: 'circular'
+size: 'small'
+width: '150px'
+```
+
+## Performance Optimizations
+
+The component includes several React optimizations:
+
+````tsx
+// Memoized color calculations
+const seriesColors = useMemo(() => {
+  return data.reduce((acc, series, idx) => {
+    const base = getFluentPalette(theme)[
+      idx % getFluentPalette(theme).length
+    ];
+    acc[series.label] = lightenColor(base, 0.3);
+    return acc;
+  }, {} as Record<string, string>);
+}, [data, getFluentPalette, lightenColor, theme]);
+
+// Memoized total calculations for percentages
+const totalPerPoint = useMemo(() => {
+  return allLabels.map(cat =>
+    data.reduce((sum, series) => {
+      const match = series.data.find(d => getPrimary(d) === cat);
+      return sum + (match ? getSecondary(match) : 0);
+    }, 0)
+  );
+}, [allLabels, data, getPrimary, getSecondary]);
+
+// Memoized chart data with percentage support
+const chartData = useMemo(() => {
+  return {
+    labels: allLabels,
+    datasets: data
+      .filter(series => visibleSeries.includes(series.label))
+      .map((series) => ({
+        label: series.label,
+        fill: true,
+        backgroundColor: seriesColors[series.label],
+        borderColor: 'transparent',
+        borderWidth: 0,
+        data: allLabels.map((cat, index) => {
+          const match = series.data.find(d => getPrimary(d) === cat);
+          const rawValue = match ? getSecondary(match) : 0;
+          const total = totalPerPoint[index] || 1;
+          return showPercent
+            ? Math.round(((rawValue / total) * 100 + Number.EPSILON) * 100) / 100
+            : Math.round((rawValue + Number.EPSILON) * 100) / 100;
+        }),
+        tension: 0.5,
+      })),
+  };
+}, [data, visibleSeries, allLabels, getPrimary, getSecondary, seriesColors, totalPerPoint, showPercent]);

package/src/charts/steamChart/SteamChart.tsx

@@ -0,0 +1,236 @@
+import {
+  CategoryScale,
+  Chart as ChartJS,
+  ChartOptions,
+  Filler,
+  Legend,
+  LineElement,
+  LinearScale,
+  PointElement,
+  Title,
+  Tooltip,
+} from 'chart.js';
+import React, { useMemo, useState } from 'react';
+import { Theme, ToggleButton, webLightTheme } from '@fluentui/react-components';
+import { createFluentTooltip, useGraphUtils } from '../../hooks/useGraphUtils';
+
+import ChartDataLabels from 'chartjs-plugin-datalabels';
+import { Line } from 'react-chartjs-2';
+import RenderLegend from '../../components/RenderLegend/RenderLegend';
+import { Stack } from '../../components/stack/Stack';
+import { useGraphGlobalStyles } from '../../graphGlobalStyles/useGraphGlobalStyles';
+
+ChartJS.register(ChartDataLabels);
+ChartJS.register(
+  LineElement,
+  PointElement,
+  Filler,       
+  CategoryScale,
+  LinearScale,
+  Tooltip,
+  Legend,
+    Title
+);
+
+export interface SteamChartProps<T> {
+  data: { label: string; data: T[] }[]; 
+  getPrimary: (datum: T) => string | number;
+  getSecondary: (datum: T) => number;
+  title?: string;
+    showDataLabels?: boolean;
+    theme?: Theme;
+}
+
+export default function SteamChart<T extends object>({
+  data,
+  getPrimary,
+  getSecondary,
+  title,
+  showDataLabels = false,
+   theme = webLightTheme,
+}: SteamChartProps<T>) {
+  const [visibleSeries, setVisibleSeries] = useState(() =>
+    data.length > 1 ? data.map(s => s.label) : [data[0]?.label]
+  );
+  const [showPercent, setShowPercent] = useState(false);
+const styles = useGraphGlobalStyles();
+ 
+  const { lightenColor, getFluentPalette } = useGraphUtils(theme);
+
+  const seriesColors = useMemo(() => {
+    return data.reduce((acc, series, idx) => {
+      const base = getFluentPalette(theme)[
+        idx % getFluentPalette(theme).length
+      ];
+      acc[series.label] = lightenColor(base, 0.3);
+      return acc;
+    }, {} as Record<string, string>);
+  }, [data, getFluentPalette, lightenColor, theme]);
+
+  const toggleSeries = React.useCallback(
+    (label: string) => {
+      setVisibleSeries(prev => {
+        const isVisible = prev.includes(label);
+        const next = isVisible
+          ? prev.filter(l => l !== label)
+          : [...prev, label];
+        return next.length === 0 ? [data[0].label] : next;
+      });
+    },
+    [data]
+  );
+
+  const allLabels = useMemo(() => {
+    const set = new Set<string | number>();
+    data.forEach(series => {
+      series.data.forEach(d => set.add(getPrimary(d)));
+    });
+    return Array.from(set);
+  }, [data, getPrimary]);
+
+  const totalPerPoint = useMemo(() => {
+    return allLabels.map(cat =>
+      data.reduce((sum, series) => {
+        const match = series.data.find(d => getPrimary(d) === cat);
+        return sum + (match ? getSecondary(match) : 0);
+      }, 0)
+    );
+  }, [allLabels, data, getPrimary, getSecondary]);
+
+  const chartData = useMemo(() => {
+    return {
+      labels: allLabels,
+      datasets: data
+        .filter(series => visibleSeries.includes(series.label))
+        .map((series, ) => ({
+          label: series.label,
+          fill: true,
+          backgroundColor: seriesColors[series.label],
+          borderColor: 'transparent',
+          borderWidth: 0,
+          data: allLabels.map((cat, index) => {
+            const match = series.data.find(d => getPrimary(d) === cat);
+            const rawValue = match ? getSecondary(match) : 0;
+            const total = totalPerPoint[index] || 1;
+            return showPercent
+              ? Math.round(((rawValue / total) * 100 + Number.EPSILON) * 100) / 100
+              : Math.round((rawValue + Number.EPSILON) * 100) / 100;
+          }),
+          tension: 0.5,
+        })),
+    };
+  }, [
+    data,
+    visibleSeries,
+    allLabels,
+    getPrimary,
+    getSecondary,
+    seriesColors,
+    totalPerPoint,
+    showPercent,
+  ]);
+
+const { fontFamily, fontSize, labelColor, gridColor } = useMemo(() => ({
+    fontFamily: theme.fontFamilyBase,
+    fontSize: parseInt(theme.fontSizeBase200.replace('px', '')) || 14,
+    labelColor: theme.colorNeutralForeground1,
+    gridColor: theme.colorNeutralStroke2,
+}), [theme]);
+
+const options = useMemo<ChartOptions<'line'>>(() => ({
+    responsive: true,
+    maintainAspectRatio: false,
+    animation: {
+        duration: 800,
+        easing: 'easeOutQuart',
+    },
+    plugins: {
+        title: {
+            display: !!title,
+            text: title,
+            font: {
+                size: 14,
+                family: theme.fontFamilyBase,
+                weight: theme.fontWeightSemibold,
+            },
+            color: theme.colorNeutralForeground1,
+            padding: {
+                top: 20,
+                bottom: 20,
+            },
+        },
+        datalabels: {
+            display: showDataLabels,
+            color: theme.colorNeutralForeground1,
+            font: {
+                family: theme.fontFamilyBase,
+                size: parseInt(theme.fontSizeBase200.replace('px', '')) || 14,
+            },
+        },
+        legend: { display: false },
+        tooltip: createFluentTooltip<'line'>(theme),
+    },
+    interaction: {
+        mode: 'index',
+        intersect: false,
+    },
+    scales: {
+        x: {
+            stacked: true,
+            ticks: {
+                color: labelColor,
+                font: { family: fontFamily, size: fontSize },
+            },
+            grid: { color: gridColor },
+        },
+        y: {
+            stacked: true,
+            ticks: {
+                callback: (value: string | number) => (showPercent ? `${value}%` : value),
+                color: labelColor,
+                font: { family: fontFamily, size: fontSize },
+            },
+            grid: { color: gridColor },
+            min: 0,
+            max: showPercent ? 100 : undefined,
+        },
+    },
+}), [
+    theme,
+    title,
+    showDataLabels,
+    createFluentTooltip,
+    labelColor,
+    fontFamily,
+    fontSize,
+    gridColor,
+    showPercent,
+]);
+
+  return (
+    <div className={styles.chartWithLegend}>
+      <div className={styles.chartArea}>
+        <Line data={chartData} options={options} />
+      </div>
+      <Stack justifyContent="center" alignItems="center" margin="7px">
+        <ToggleButton
+          onClick={() => setShowPercent(p => !p)}
+          shape="circular"
+          appearance="secondary"
+          size="small"
+          style={{ width: '150px' }}
+        >
+          {showPercent ? 'Show Raw Values' : 'Show %'}
+        </ToggleButton>
+      </Stack>
+      <div className={styles.legendArea}>
+        <RenderLegend
+          data={data}
+          visibleSeries={visibleSeries}
+          seriesColors={seriesColors}
+          toggleSeries={toggleSeries}
+        />
+      </div>
+    </div>
+  );
+}

package/src/charts/steamChart/index.ts

@@ -0,0 +1 @@
+export * from './SteamChart';