@micha.bigler/ui-core-micha 2.14.0 → 2.15.0

package/src/components/charts/formatters.js

@@ -0,0 +1,39 @@
+import { useTranslation } from 'react-i18next';
+
+export function formatPercentage(value, locale, options = {}) {
+  return new Intl.NumberFormat(locale, {
+    style: 'percent',
+    maximumFractionDigits: 1,
+    ...options,
+  }).format(value);
+}
+
+export function formatCompact(value, locale, options = {}) {
+  return new Intl.NumberFormat(locale, {
+    notation: 'compact',
+    maximumFractionDigits: 1,
+    ...options,
+  }).format(value);
+}
+
+export function formatRatio(value, locale, options = {}) {
+  return new Intl.NumberFormat(locale, {
+    maximumFractionDigits: 2,
+    ...options,
+  }).format(value);
+}
+
+/** Creates locale-aware formatter functions for use in chart axes and tooltips. */
+export function createChartFormatters(locale) {
+  return {
+    percentage: (value, options) => formatPercentage(value, locale, options),
+    compact: (value, options) => formatCompact(value, locale, options),
+    ratio: (value, options) => formatRatio(value, locale, options),
+  };
+}
+
+/** Resolves formatter locale from the active react-i18next instance. */
+export function useChartFormatters() {
+  const { i18n } = useTranslation();
+  return createChartFormatters(i18n.language);
+}

package/src/components/charts/palette.js

@@ -0,0 +1,24 @@
+import { useTheme } from '@mui/material/styles';
+
+/**
+ * Returns neutral chart colours derived only from the active MUI theme.
+ * Consumers may replace either array with their own domain palette.
+ */
+export function getNeutralChartPalette(theme) {
+  const palette = theme.palette;
+  const isDark = palette.mode === 'dark';
+
+  return {
+    categorical: isDark
+      ? [palette.primary.light, palette.secondary.light, palette.info.light, palette.success.light, palette.warning.light]
+      : [palette.primary.main, palette.secondary.main, palette.info.main, palette.success.main, palette.warning.main],
+    sequential: isDark
+      ? [palette.action.disabled, palette.text.secondary, palette.primary.light, palette.primary.main, palette.primary.dark]
+      : [palette.action.disabled, palette.divider, palette.text.secondary, palette.primary.light, palette.primary.main],
+  };
+}
+
+/** Resolves the kit's neutral palette from the nearest MUI ThemeProvider. */
+export function useNeutralChartPalette() {
+  return getNeutralChartPalette(useTheme());
+}

package/src/i18n/chartsTranslations.ts

@@ -0,0 +1,38 @@
+export const chartsTranslations = {
+  'ChartFrame.LOADING': {
+    de: 'Diagramm wird geladen.',
+    fr: 'Chargement du graphique.',
+    en: 'Loading chart.',
+    sw: 'Inapakia chati.',
+  },
+  'ChartFrame.EMPTY_DEFAULT': {
+    de: 'Keine Daten verfügbar.',
+    fr: 'Aucune donnée disponible.',
+    en: 'No data available.',
+    sw: 'Hakuna data inayopatikana.',
+  },
+  'ChartFrame.ERROR_DEFAULT': {
+    de: 'Das Diagramm konnte nicht geladen werden.',
+    fr: 'Impossible de charger le graphique.',
+    en: 'The chart could not be loaded.',
+    sw: 'Chati haikuweza kupakiwa.',
+  },
+  'ChartFrame.EXPORT_SVG_LABEL': {
+    de: 'SVG exportieren',
+    fr: 'Exporter en SVG',
+    en: 'Export SVG',
+    sw: 'Hamisha SVG',
+  },
+  'ChartFrame.EXPORT_PNG_LABEL': {
+    de: 'PNG exportieren',
+    fr: 'Exporter en PNG',
+    en: 'Export PNG',
+    sw: 'Hamisha PNG',
+  },
+  'ChartFrame.EXPORT_ERROR': {
+    de: 'Das Diagramm konnte nicht exportiert werden.',
+    fr: 'Impossible d’exporter le graphique.',
+    en: 'The chart could not be exported.',
+    sw: 'Chati haikuweza kuhamishwa.',
+  },
+};

package/src/index.js

@@ -39,10 +39,23 @@ export { AuthFactorRequirementCard } from './components/AuthFactorRequirementCar
 export { AccessCodeSingleUseToggle } from './components/AccessCodeSingleUseToggle';
 export { QrSignupManager } from './components/QrSignupManager';
 
-// --- 6. Translations ---
+// --- 6. Charts ---
+export { ChartFrame } from './components/charts/ChartFrame';
+export { BarChart } from './components/charts/BarChart';
+export { LineChart } from './components/charts/LineChart';
+export { getNeutralChartPalette, useNeutralChartPalette } from './components/charts/palette';
+export {
+  formatPercentage,
+  formatCompact,
+  formatRatio,
+  createChartFormatters,
+  useChartFormatters,
+} from './components/charts/formatters';
+
+// --- 7. Translations ---
 export { authTranslations } from './i18n/authTranslations';
 
-// --- 7. Notifications ---
+// --- 8. Notifications ---
 export { NotificationSettings } from './notifications/NotificationSettings';
 export * from './notifications/api';
 export { NotificationsProvider, useNotifications } from './notifications/NotificationsProvider';
@@ -51,7 +64,7 @@ export { NotificationBell } from './notifications/NotificationBell';
 export { PopupSurface } from './notifications/PopupSurface';
 export { getNotificationFeed, getUnreadCount, markNotifications } from './notifications/feedApi';
 
-// --- 8. Onboarding ---
+// --- 9. Onboarding ---
 export * from './onboarding/api';
 export { selectActiveSteps } from './onboarding/stepSelection';
 export {
@@ -66,6 +79,7 @@ export { CompleteNameStep } from './onboarding/steps/CompleteNameStep';
 export { BrowserPushStep } from './onboarding/steps/BrowserPushStep';
 export { PwaInstallStep } from './onboarding/steps/PwaInstallStep';
 
-// --- 9. Translations ---
+// --- 10. Translations ---
 export { notificationsTranslations } from './i18n/notificationsTranslations';
 export { onboardingTranslations } from './i18n/onboardingTranslations';
+export { chartsTranslations } from './i18n/chartsTranslations';

package/tests/BarChart.test.jsx

@@ -0,0 +1,55 @@
+// @vitest-environment jsdom
+import React from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import { ThemeProvider, createTheme } from '@mui/material/styles';
+
+const chartSpy = vi.hoisted(() => vi.fn((props) => <div data-testid="mui-bar-chart" data-props={JSON.stringify(props)} />));
+vi.mock('@mui/x-charts/BarChart', () => ({ BarChart: chartSpy }));
+
+import { BarChart } from '../src/components/charts/BarChart';
+
+function renderChart(props) {
+  return render(
+    <ThemeProvider theme={createTheme({ palette: { primary: { main: 'rgb(1, 2, 3)' } } })}>
+      <BarChart xAxisLabel="Year" yAxisLabel="Value (kg)" {...props} />
+    </ThemeProvider>,
+  );
+}
+
+describe('BarChart preset', () => {
+  afterEach(cleanup);
+
+  it('passes both axis labels, tooltip, responsive sizing, and hides a single-series legend', () => {
+    renderChart({ series: [{ data: [1, 2] }] });
+    const props = chartSpy.mock.calls[0][0];
+
+    expect(props.xAxis[0].label).toBe('Year');
+    expect(props.yAxis[0].label).toBe('Value (kg)');
+    expect(props.slotProps).toEqual({ tooltip: { trigger: 'axis' } });
+    expect(props.hideLegend).toBe(true);
+    expect(screen.getByTestId('bar-chart-container').getAttribute('style') || '').not.toContain('px');
+  });
+
+  it.each([
+    ['grouped', [{ data: [1] }, { data: [2] }], undefined],
+    ['stacked', [{ data: [1], stack: 'total' }, { data: [2], stack: 'total' }], undefined],
+    ['dual axis', [{ data: [1], yAxisKey: 'secondary' }, { data: [2] }], [{ id: 'primary' }, { id: 'secondary' }]],
+  ])('renders the %s variant with a legend for multiple series', (_name, series, yAxis) => {
+    renderChart({ series, yAxis });
+    const props = chartSpy.mock.calls.at(-1)[0];
+    expect(props.hideLegend).toBe(false);
+    expect(props.series).toEqual(series);
+  });
+
+  it('passes a caller palette through without substituting a hardcoded colour', () => {
+    renderChart({ series: [{ data: [1] }], palette: ['var(--application-chart-colour)'] });
+    expect(chartSpy.mock.calls.at(-1)[0].colors).toEqual(['var(--application-chart-colour)']);
+  });
+
+  it('requires labels for both axes', () => {
+    expect(() => render(
+      <ThemeProvider theme={createTheme()}><BarChart series={[]} xAxisLabel="Year" /></ThemeProvider>,
+    )).toThrow('BarChart requires xAxisLabel and yAxisLabel.');
+  });
+});

package/tests/ChartFrame.test.jsx

@@ -0,0 +1,122 @@
+// @vitest-environment jsdom
+import React from 'react';
+import i18next from 'i18next';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { I18nextProvider } from 'react-i18next';
+import { ThemeProvider, createTheme } from '@mui/material/styles';
+
+const chartExport = vi.hoisted(() => ({
+  exportChartSvg: vi.fn(() => new Blob()),
+  exportChartPng: vi.fn(() => Promise.resolve(new Blob())),
+}));
+
+vi.mock('../src/components/charts/exportChart', () => chartExport);
+
+import { ChartFrame } from '../src/components/charts/ChartFrame';
+
+const resources = {
+  en: {
+    translation: {
+      'ChartFrame.LOADING': 'Loading chart.',
+      'ChartFrame.EMPTY_DEFAULT': 'No data available.',
+      'ChartFrame.ERROR_DEFAULT': 'The chart could not be loaded.',
+      'ChartFrame.EXPORT_SVG_LABEL': 'Export SVG',
+      'ChartFrame.EXPORT_PNG_LABEL': 'Export PNG',
+      'ChartFrame.EXPORT_ERROR': 'The chart could not be exported.',
+    },
+  },
+  fr: {
+    translation: {
+      'ChartFrame.LOADING': 'Chargement du graphique.',
+      'ChartFrame.EMPTY_DEFAULT': 'Aucune donnée disponible.',
+      'ChartFrame.ERROR_DEFAULT': 'Impossible de charger le graphique.',
+      'ChartFrame.EXPORT_SVG_LABEL': 'Exporter en SVG',
+      'ChartFrame.EXPORT_PNG_LABEL': 'Exporter en PNG',
+      'ChartFrame.EXPORT_ERROR': 'Impossible d’exporter le graphique.',
+    },
+  },
+};
+
+function renderFrame(props = {}, language = 'en') {
+  const i18n = i18next.createInstance();
+  i18n.init({ lng: language, resources, interpolation: { escapeValue: false } });
+  return render(
+    <ThemeProvider theme={createTheme()}>
+      <I18nextProvider i18n={i18n}>
+        <ChartFrame title="Chart title" subtitle="Chart subtitle" {...props}>
+          <svg data-testid="chart-body" />
+        </ChartFrame>
+      </I18nextProvider>
+    </ThemeProvider>,
+  );
+}
+
+describe('ChartFrame', () => {
+  afterEach(cleanup);
+
+  it('renders its title, subtitle, toolbar, and accessible chart region', () => {
+    renderFrame({ toolbar: <button type="button">Period selector</button> });
+
+    expect(screen.getByText('Chart title')).toBeTruthy();
+    expect(screen.getByText('Chart subtitle')).toBeTruthy();
+    expect(screen.getByRole('button', { name: 'Period selector' })).toBeTruthy();
+    expect(screen.getByRole('img', { name: 'Chart title' })).toBeTruthy();
+  });
+
+  it('lets a custom ariaLabel override the title as the accessible name', () => {
+    renderFrame({ ariaLabel: 'Custom accessible description' });
+
+    expect(screen.getByRole('img', { name: 'Custom accessible description' })).toBeTruthy();
+    expect(screen.queryByRole('img', { name: 'Chart title' })).toBeNull();
+  });
+
+  it('enforces loading, error, empty, then children state precedence', () => {
+    const loading = renderFrame({ loading: true, error: 'Failure', isEmpty: true });
+    expect(screen.getByLabelText('Loading chart.')).toBeTruthy();
+    expect(screen.queryByText('Failure')).toBeNull();
+    expect(screen.queryByTestId('chart-body')).toBeNull();
+    loading.unmount();
+
+    const failure = renderFrame({ error: 'Failure', isEmpty: true });
+    expect(screen.getByText('Failure')).toBeTruthy();
+    expect(screen.queryByTestId('chart-body')).toBeNull();
+    failure.unmount();
+
+    renderFrame();
+    expect(screen.getByTestId('chart-body')).toBeTruthy();
+  });
+
+  it('renders an empty message before children when empty', () => {
+    renderFrame({ isEmpty: true, emptyMessage: 'No observations' });
+    expect(screen.getByText('No observations')).toBeTruthy();
+    expect(screen.queryByTestId('chart-body')).toBeNull();
+  });
+
+  it('shows export controls only when enabled and invokes the SVG callback', () => {
+    const onExportSvg = vi.fn();
+    const disabled = renderFrame();
+    expect(screen.queryByRole('button', { name: 'Export SVG' })).toBeNull();
+    disabled.unmount();
+
+    renderFrame({ exportOptions: { png: false }, onExportSvg });
+    fireEvent.click(screen.getByRole('button', { name: 'Export SVG' }));
+    expect(chartExport.exportChartSvg).toHaveBeenCalledOnce();
+    expect(onExportSvg).toHaveBeenCalledOnce();
+    expect(screen.queryByRole('button', { name: 'Export PNG' })).toBeNull();
+  });
+
+  it('invokes the PNG callback when the PNG export control is used', async () => {
+    const onExportPng = vi.fn();
+    renderFrame({ exportOptions: true, onExportPng });
+
+    fireEvent.click(screen.getByRole('button', { name: 'Export PNG' }));
+    await vi.waitFor(() => expect(chartExport.exportChartPng).toHaveBeenCalledOnce());
+    await vi.waitFor(() => expect(onExportPng).toHaveBeenCalledOnce());
+  });
+
+  it('uses resolved i18n strings for its own empty state', () => {
+    renderFrame({ isEmpty: true }, 'fr');
+    expect(screen.getByText('Aucune donnée disponible.')).toBeTruthy();
+  });
+});

package/tests/LineChart.test.jsx

@@ -0,0 +1,33 @@
+// @vitest-environment jsdom
+import React from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render } from '@testing-library/react';
+import { ThemeProvider, createTheme } from '@mui/material/styles';
+
+const chartSpy = vi.hoisted(() => vi.fn(() => <div data-testid="mui-line-chart" />));
+vi.mock('@mui/x-charts/LineChart', () => ({ LineChart: chartSpy }));
+
+import { LineChart } from '../src/components/charts/LineChart';
+
+describe('LineChart preset', () => {
+  afterEach(cleanup);
+
+  it('renders multi-series time data with labelled axes, legend, and tooltip', () => {
+    render(
+      <ThemeProvider theme={createTheme()}>
+        <LineChart
+          xAxisLabel="Date"
+          yAxisLabel="Rate (%)"
+          xAxis={[{ scaleType: 'point', data: ['2026-01', '2026-02'] }]}
+          series={[{ data: [1, 2] }, { data: [2, 3] }]}
+        />
+      </ThemeProvider>,
+    );
+
+    const props = chartSpy.mock.calls[0][0];
+    expect(props.xAxis[0].label).toBe('Date');
+    expect(props.yAxis[0].label).toBe('Rate (%)');
+    expect(props.hideLegend).toBe(false);
+    expect(props.slotProps).toEqual({ tooltip: { trigger: 'axis' } });
+  });
+});

package/tests/chartsPalette.test.js

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createChartFormatters,
+  formatCompact,
+  formatPercentage,
+  getNeutralChartPalette,
+} from '../src/index';
+
+describe('chart palette and formatters', () => {
+  it('resolves different neutral palettes from light and dark MUI themes without literal API colours', () => {
+    const tokenTheme = (mode) => ({
+      palette: {
+        mode,
+        primary: { main: `${mode}-primary-main`, light: `${mode}-primary-light`, dark: `${mode}-primary-dark` },
+        secondary: { main: `${mode}-secondary-main`, light: `${mode}-secondary-light` },
+        info: { main: `${mode}-info-main`, light: `${mode}-info-light` },
+        success: { main: `${mode}-success-main`, light: `${mode}-success-light` },
+        warning: { main: `${mode}-warning-main`, light: `${mode}-warning-light` },
+        action: { disabled: `${mode}-action-disabled` },
+        text: { secondary: `${mode}-text-secondary` },
+        divider: `${mode}-divider`,
+      },
+    });
+    const light = getNeutralChartPalette(tokenTheme('light'));
+    const dark = getNeutralChartPalette(tokenTheme('dark'));
+
+    expect(light.categorical).not.toEqual(dark.categorical);
+    expect(light.categorical).toHaveLength(5);
+    expect(light.categorical).toContain('light-primary-main');
+    expect(light.categorical.every((colour) => !colour.includes('#'))).toBe(true);
+  });
+
+  it('formats percentage and compact numbers according to the requested locale', () => {
+    expect(formatPercentage(0.25, 'en-US')).toBe('25%');
+    expect(formatPercentage(0.25, 'de-DE')).toContain('25');
+    expect(formatCompact(12500, 'en-US')).toMatch(/12.5K|13K/);
+    expect(createChartFormatters('fr-FR').ratio(1.5)).toContain('1');
+  });
+});