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

package/src/notifications/realtime.jsx

@@ -33,6 +33,7 @@ export { RealtimeContext };
 export function useRealtimeCore({ active, wsUrl }) {
   const socketRef = useRef(null);
   const subscribersRef = useRef(new Map());
+  const reconnectSubscribersRef = useRef(new Set());
 
   const subscribe = useCallback((envelope, handler) => {
     const subscribers = subscribersRef.current;
@@ -50,12 +51,21 @@ export function useRealtimeCore({ active, wsUrl }) {
     };
   }, []);
 
+  // Additive lifecycle signal for domains whose REST projections must be
+  // refreshed after the one shared transport reconnects. It deliberately does
+  // not alter the socket/backoff ownership or the envelope subscriber API.
+  const onReconnect = useCallback((handler) => {
+    reconnectSubscribersRef.current.add(handler);
+    return () => reconnectSubscribersRef.current.delete(handler);
+  }, []);
+
   useEffect(() => {
     if (!active) return undefined;
 
     let isActive = true;
     let reconnectTimer = null;
     let backoffMs = INITIAL_BACKOFF_MS;
+    let hasConnected = false;
 
     const handleMessage = (event) => {
       let data;
@@ -85,6 +95,16 @@ export function useRealtimeCore({ active, wsUrl }) {
 
       socket.onopen = () => {
         backoffMs = INITIAL_BACKOFF_MS;
+        if (hasConnected) {
+          reconnectSubscribersRef.current.forEach((handler) => {
+            try {
+              handler();
+            } catch (error) {
+              console.error('Realtime reconnect subscriber error', error);
+            }
+          });
+        }
+        hasConnected = true;
       };
       socket.onmessage = handleMessage;
       socket.onerror = () => {
@@ -114,5 +134,5 @@ export function useRealtimeCore({ active, wsUrl }) {
     };
   }, [active, wsUrl]);
 
-  return { subscribe };
+  return { subscribe, onReconnect };
 }

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/ConversationList.test.jsx

@@ -0,0 +1,66 @@
+// @vitest-environment jsdom
+import React from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+
+vi.mock('react-i18next', () => ({ useTranslation: () => ({ t: (key) => key }) }));
+vi.mock('../src/notifications/realtime', () => ({ useRealtime: () => ({ subscribe: () => () => {}, onReconnect: () => () => {} }) }));
+
+import { ConversationList } from '../src/messaging/ConversationList';
+import { MessagingProvider } from '../src/messaging/MessagingProvider';
+
+function renderList(api, props = {}) {
+  return render(<MessagingProvider api={api}><ConversationList onOpen={props.onOpen} {...props} /></MessagingProvider>);
+}
+
+describe('ConversationList', () => {
+  let api;
+  beforeEach(() => {
+    api = {
+      listConversations: vi.fn().mockResolvedValue({ results: [{ id: 1, title: 'First', unread_count: 2, last_message: { body: 'Hello' } }], next_cursor: 'opaque-cursor' }),
+      getUnreadCount: vi.fn().mockResolvedValue({ unread_count: 2, by_conversation: { 1: 2 } }),
+      listMessages: vi.fn().mockResolvedValue({ results: [] }),
+      archiveConversation: vi.fn().mockResolvedValue({ id: 1, archived: true }),
+      patchConversationPreferences: vi.fn().mockResolvedValue({ id: 1, muted: true }),
+      createGroupConversation: vi.fn().mockResolvedValue({ id: 4, title: 'Volunteers', kind: 'group' }),
+      createBroadcastConversation: vi.fn().mockResolvedValue({ id: 5, title: 'Announcements', kind: 'broadcast' }),
+    };
+  });
+  afterEach(cleanup);
+
+  it('loads the next opaque cursor page without offset assumptions', async () => {
+    api.listConversations.mockResolvedValueOnce({ results: [{ id: 1, title: 'First' }], next_cursor: 'opaque-cursor' }).mockResolvedValueOnce({ results: [{ id: 2, title: 'Second' }], next_cursor: null });
+    renderList(api);
+    await screen.findByText('First');
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingList.LOAD_MORE' }));
+    await screen.findByText('Second');
+    // Append, not replace: the first page's item must still be present.
+    expect(screen.getByText('First')).toBeTruthy();
+    expect(api.listConversations).toHaveBeenLastCalledWith({ cursor: 'opaque-cursor' });
+  });
+
+  it('opens host-provided group and broadcast launchers into normalized list state', async () => {
+    const onOpen = vi.fn();
+    renderList(api, { onOpen, groupLaunchers: [{ id: 'volunteers', label: 'Volunteers', payload: { title: 'Volunteers' } }], broadcastLauncher: { label: 'Announcements', payload: {} } });
+    await screen.findByText('First');
+    fireEvent.click(screen.getByRole('button', { name: 'Volunteers' }));
+    await waitFor(() => expect(api.createGroupConversation).toHaveBeenCalledWith({ title: 'Volunteers' }));
+    expect(onOpen).toHaveBeenCalledWith(expect.objectContaining({ id: 4 }));
+    fireEvent.click(screen.getByRole('button', { name: 'Announcements' }));
+    await waitFor(() => expect(api.createBroadcastConversation).toHaveBeenCalled());
+    // Once opened it becomes a normal (unread/preview-bearing) list row; the
+    // static launcher button must not keep showing it a second time.
+    await waitFor(() => expect(screen.queryByRole('button', { name: 'Announcements' })).toBeNull());
+  });
+
+  it('wires mute and archive through participant APIs', async () => {
+    renderList(api);
+    await screen.findByText('First');
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingList.ACTIONS' }));
+    fireEvent.click(screen.getByText('MessagingList.MUTE'));
+    await waitFor(() => expect(api.patchConversationPreferences).toHaveBeenCalledWith(1, { muted: true }));
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingList.ACTIONS' }));
+    fireEvent.click(screen.getByText('MessagingList.ARCHIVE'));
+    await waitFor(() => expect(api.archiveConversation).toHaveBeenCalledWith(1, true));
+  });
+});

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/MessagingProvider.test.jsx

@@ -0,0 +1,50 @@
+// @vitest-environment jsdom
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+import { act, render, screen, waitFor } from '@testing-library/react';
+
+import { RealtimeContext } from '../src/notifications/realtime';
+import { MessagingProvider, useMessaging } from '../src/messaging/MessagingProvider';
+
+function Harness() { const { cache } = useMessaging(); return <output data-testid="cache">{JSON.stringify(cache)}</output>; }
+function makeTransport() {
+  const handlers = new Set(); const reconnectHandlers = new Set();
+  return { subscribe: vi.fn((_envelope, handler) => { handlers.add(handler); return () => handlers.delete(handler); }), onReconnect: vi.fn((handler) => { reconnectHandlers.add(handler); return () => reconnectHandlers.delete(handler); }), frame: (frame) => handlers.forEach((handler) => handler(frame)), reconnect: () => reconnectHandlers.forEach((handler) => handler()) };
+}
+function renderProvider({ transport = makeTransport(), api, activeConversationId = 1, active } = {}) {
+  const props = { api, activeConversationId, ...(active === undefined ? {} : { active }) };
+  render(<RealtimeContext.Provider value={transport}><MessagingProvider {...props}><Harness /></MessagingProvider></RealtimeContext.Provider>);
+  return transport;
+}
+const cache = () => JSON.parse(screen.getByTestId('cache').textContent);
+
+describe('MessagingProvider', () => {
+  it('deduplicates repeated event IDs and only changes the affected message slice', async () => {
+    const api = { listConversations: vi.fn().mockResolvedValue({ results: [{ id: 1 }, { id: 2 }] }), listMessages: vi.fn().mockResolvedValue({ results: [{ id: 10, conversation_id: 2, body: 'unchanged' }] }), getUnreadCount: vi.fn().mockResolvedValue({ unread_count: 0, by_conversation: {} }) };
+    const transport = renderProvider({ api }); await waitFor(() => expect(api.listConversations).toHaveBeenCalled());
+    const frame = { envelope: 'messaging', type: 'message', event_id: 'once', conversation_id: 1, message: { id: 11, body: 'new' } };
+    act(() => { transport.frame(frame); transport.frame(frame); });
+    expect(Object.keys(cache().messages)).toEqual(['10', '11']);
+    expect(cache().messages['10'].body).toBe('unchanged');
+  });
+
+  it('refetches list, active thread and unread state when Layer 1 reconnects', async () => {
+    const api = { listConversations: vi.fn().mockResolvedValue({ results: [] }), listMessages: vi.fn().mockResolvedValue({ results: [] }), getUnreadCount: vi.fn().mockResolvedValue({ unread_count: 0, by_conversation: {} }) };
+    const transport = renderProvider({ api }); await waitFor(() => expect(api.listMessages).toHaveBeenCalledTimes(1));
+    await act(async () => transport.reconnect());
+    await waitFor(() => { expect(api.listConversations).toHaveBeenCalledTimes(2); expect(api.listMessages).toHaveBeenLastCalledWith(1); expect(api.getUnreadCount).toHaveBeenCalledTimes(2); });
+  });
+
+  it('does not call the authenticated-only REST surface while active=false, and starts fetching once it flips true', async () => {
+    const api = { listConversations: vi.fn().mockResolvedValue({ results: [] }), listMessages: vi.fn().mockResolvedValue({ results: [] }), getUnreadCount: vi.fn().mockResolvedValue({ unread_count: 0, by_conversation: {} }) };
+    const transport = makeTransport();
+    const { rerender } = render(<RealtimeContext.Provider value={transport}><MessagingProvider api={api} activeConversationId={1} active={false}><Harness /></MessagingProvider></RealtimeContext.Provider>);
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(api.listConversations).not.toHaveBeenCalled();
+    expect(api.listMessages).not.toHaveBeenCalled();
+    expect(api.getUnreadCount).not.toHaveBeenCalled();
+
+    rerender(<RealtimeContext.Provider value={transport}><MessagingProvider api={api} activeConversationId={1} active><Harness /></MessagingProvider></RealtimeContext.Provider>);
+    await waitFor(() => expect(api.listConversations).toHaveBeenCalledTimes(1));
+  });
+});

package/tests/Thread.test.jsx

@@ -0,0 +1,100 @@
+// @vitest-environment jsdom
+import React from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+
+vi.mock('react-i18next', () => ({ useTranslation: () => ({ t: (key, options) => options?.count != null ? `${key}:${options.count}` : key }) }));
+vi.mock('../src/notifications/realtime', () => ({ useRealtime: () => ({ subscribe: () => () => {}, onReconnect: () => () => {} }) }));
+
+import { AuthContext } from '../src/auth/AuthContext';
+import { MessageBubble } from '../src/messaging/MessageBubble';
+import { MessagingProvider } from '../src/messaging/MessagingProvider';
+import { ReadTicks } from '../src/messaging/ReadTicks';
+import { Thread } from '../src/messaging/Thread';
+
+function makeApi() {
+  return {
+    listConversations: vi.fn().mockResolvedValue({ results: [{ id: 1, kind: 'group' }] }),
+    getUnreadCount: vi.fn().mockResolvedValue({ unread_count: 0, by_conversation: {} }),
+    listMessages: vi.fn().mockResolvedValue({ results: [{ id: 2, conversation_id: 1, body: 'Visible message', created_at: '2026-07-31T10:00:00Z' }], next_cursor: 'signed-opaque-cursor' }),
+    listThread: vi.fn().mockResolvedValue({ results: [] }),
+    getReadStatus: vi.fn().mockResolvedValue({ all_read: false, delivered_count: 2 }),
+  };
+}
+function renderThread(api, { userId = 9 } = {}) {
+  return render(
+    <AuthContext.Provider value={{ user: { id: userId } }}>
+      <MessagingProvider api={api} activeConversationId={1}><Thread conversationId={1} /></MessagingProvider>
+    </AuthContext.Provider>,
+  );
+}
+
+describe('messaging Thread surfaces', () => {
+  let api;
+  beforeEach(() => { api = makeApi(); });
+  afterEach(cleanup);
+
+  it('uses the opaque message cursor and shows a rejected older page as an error', async () => {
+    api.listMessages.mockResolvedValueOnce({ results: [{ id: 2, conversation_id: 1, body: 'Visible message' }], next_cursor: 'signed-opaque-cursor' }).mockRejectedValueOnce(new Error('bad cursor'));
+    renderThread(api);
+    await screen.findByText('Visible message');
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingThread.LOAD_OLDER' }));
+    await screen.findByRole('alert');
+    expect(api.listMessages).toHaveBeenLastCalledWith(1, { cursor: 'signed-opaque-cursor' });
+    expect(screen.getByText('Visible message')).toBeTruthy();
+  });
+
+  it('renders deleted content as a redacted placeholder', () => {
+    render(<MessageBubble message={{ id: 4, body: 'Stale secret', deleted_at: '2026-07-31T10:00:00Z' }} />);
+    expect(screen.getByText('MessagingThread.DELETED')).toBeTruthy();
+    expect(screen.queryByText('Stale secret')).toBeNull();
+  });
+
+  it('renders aggregate read state and never exposes supplied recipient details for a direct conversation', async () => {
+    api.getReadStatus.mockResolvedValue({ all_read: false, delivered_count: 2, recipient_detail: [{ display_name: 'Private recipient' }] });
+    render(<MessagingProvider api={api} active={false}><ReadTicks messageId={2} conversation={{ id: 1, kind: 'direct' }} /></MessagingProvider>);
+    await screen.findByLabelText('MessagingReadTicks.DELIVERED:2');
+    expect(screen.queryByText('Private recipient')).toBeNull();
+  });
+
+  it('renders supplied recipient detail for a non-direct conversation (the permitted case)', async () => {
+    api.getReadStatus.mockResolvedValue({ all_read: false, delivered_count: 2, recipient_detail: [{ display_name: 'Visible recipient' }] });
+    render(<MessagingProvider api={api} active={false}><ReadTicks messageId={2} conversation={{ id: 1, kind: 'group' }} /></MessagingProvider>);
+    const tick = await screen.findByLabelText('MessagingReadTicks.DELIVERED:2');
+    fireEvent.mouseOver(tick);
+    await screen.findByText('Visible recipient');
+  });
+
+  it('only mounts ReadTicks (and its REST call) for the current user\'s own messages, not every message in the timeline', async () => {
+    api.listMessages.mockResolvedValue({
+      results: [
+        { id: 2, conversation_id: 1, body: 'Mine', created_at: '2026-07-31T10:00:00Z', sender: { id: 9 } },
+        { id: 3, conversation_id: 1, body: 'Theirs', created_at: '2026-07-31T10:01:00Z', sender: { id: 42 } },
+      ],
+      next_cursor: null,
+    });
+    renderThread(api, { userId: 9 });
+    await screen.findByText('Mine');
+    await screen.findByText('Theirs');
+    await waitFor(() => expect(api.getReadStatus).toHaveBeenCalledTimes(1));
+    expect(api.getReadStatus).toHaveBeenCalledWith(2);
+  });
+
+  it('does not mount ReadTicks (or fire a REST call) for a still-pending optimistic own message', async () => {
+    api.listMessages.mockResolvedValue({
+      results: [{ id: 'local-r9', conversation_id: 1, body: 'Sending...', created_at: '2026-07-31T10:00:00Z', sender: { id: 9 }, status: 'pending', client_request_id: 'r9' }],
+      next_cursor: null,
+    });
+    renderThread(api, { userId: 9 });
+    await screen.findByText('Sending...');
+    expect(api.getReadStatus).not.toHaveBeenCalled();
+  });
+
+  it('mounts Thread and ReadTicks independently', async () => {
+    renderThread(api);
+    await screen.findByLabelText('MessagingThread.TIMELINE');
+    cleanup();
+    render(<MessagingProvider api={api} active={false}><ReadTicks messageId={2} conversation={{ id: 1, kind: 'group' }} /></MessagingProvider>);
+    await waitFor(() => expect(screen.getByLabelText('MessagingReadTicks.DELIVERED:2')).toBeTruthy());
+  });
+});

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');
+  });
+});

package/tests/messagingApi.test.js

@@ -0,0 +1,32 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const client = vi.hoisted(() => ({ get: vi.fn(), post: vi.fn(), patch: vi.fn(), delete: vi.fn() }));
+vi.mock('../src/auth/apiClient', () => ({ default: client }));
+
+import * as api from '../src/messaging/api';
+
+const response = { data: { ok: true } };
+beforeEach(() => { vi.clearAllMocks(); Object.values(client).forEach((method) => method.mockResolvedValue(response)); });
+
+describe('messaging API contract', () => {
+  it('uses the published conversations and message routes', async () => {
+    await api.listConversations({ scope_kind: 'container', cursor: 'opaque' });
+    await api.createDirectConversation({ target_user_id: 8 });
+    await api.createGroupConversation({ title: 'Group' }); await api.createBroadcastConversation({}); await api.createManagedConversation({}); await api.createObjectThreadConversation({});
+    await api.getConversationConfig(1); await api.patchConversationConfig(1, {}); await api.archiveConversation(1, true); await api.patchConversationPreferences(1, {});
+    await api.listMessages(1, { cursor: 'opaque' }); await api.createMessage(1, { body: 'x' }, { idempotencyKey: 'key' }); await api.uploadAttachments(1, new FormData()); await api.createPoll(1, {});
+    expect(client.get).toHaveBeenCalledWith('/api/messaging/conversations/', { params: { scope_kind: 'container', cursor: 'opaque' } });
+    expect(client.post).toHaveBeenCalledWith('/api/messaging/conversations/direct/', { target_user_id: 8 });
+    expect(client.post).toHaveBeenCalledWith('/api/messaging/conversations/1/messages/', { body: 'x' }, { headers: { 'Idempotency-Key': 'key' } });
+    expect(client.get).toHaveBeenCalledWith('/api/messaging/conversations/1/messages/', { params: { cursor: 'opaque' } });
+  });
+
+  it('uses the published detail, receipt, poll and attachment routes', async () => {
+    await api.getMessage(2); await api.patchMessage(2, {}); await api.deleteMessage(2); await api.addReaction(2, '👍'); await api.removeReaction(2, '👍');
+    await api.listThread(2, { cursor: 'opaque' }); await api.markThreadRead(2); await api.markConversationRead(3); await api.getReadStatus(2); await api.votePoll(4, [5]); await api.closePoll(4); await api.getAttachment(6); await api.getAttachmentThumbnail(6); await api.getUnreadCount();
+    expect(client.delete).toHaveBeenCalledWith('/api/messaging/messages/2/reactions/%F0%9F%91%8D/');
+    expect(client.get).toHaveBeenCalledWith('/api/messaging/messages/2/thread/', { params: { cursor: 'opaque' } });
+    expect(client.post).toHaveBeenCalledWith('/api/messaging/conversations/3/read/', {});
+    expect(client.get).toHaveBeenCalledWith('/api/messaging/unread-count/');
+  });
+});