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

package/tests/messagingComposer.test.jsx

@@ -0,0 +1,111 @@
+// @vitest-environment jsdom
+import React from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+
+vi.mock('react-i18next', () => ({ useTranslation: () => ({ t: (key, options) => options?.message ? `${key}:${options.message}` : (options?.sender ? `${key}:${options.sender}` : key) }) }));
+
+const realtimeSubscribers = new Map();
+vi.mock('../src/notifications/realtime', () => ({
+  useRealtime: () => ({
+    subscribe: (envelope, handler) => { realtimeSubscribers.set(envelope, handler); return () => realtimeSubscribers.delete(envelope); },
+    onReconnect: () => () => {},
+  }),
+}));
+function dispatchMessagingFrame(frame) { realtimeSubscribers.get('messaging')?.(frame); }
+
+import { AuthContext } from '../src/auth/AuthContext';
+import { AttachmentList } from '../src/messaging/AttachmentList';
+import { Composer } from '../src/messaging/Composer';
+import { messagingReducer, MessagingProvider, useMessaging } from '../src/messaging/MessagingProvider';
+
+function State() { const { cache } = useMessaging(); return <output data-testid="cache">{JSON.stringify(cache)}</output>; }
+function makeApi() {
+  return {
+    listConversations: vi.fn().mockResolvedValue({ results: [] }), listMessages: vi.fn().mockResolvedValue({ results: [] }), getUnreadCount: vi.fn().mockResolvedValue({ unread_count: 0, by_conversation: {} }),
+    createMessage: vi.fn(), uploadAttachments: vi.fn(), getAttachment: vi.fn().mockResolvedValue(new Blob(['file'])), getAttachmentThumbnail: vi.fn().mockResolvedValue(new Blob(['image'], { type: 'image/png' })),
+  };
+}
+function renderComposer(api, { userId } = {}) {
+  const tree = <MessagingProvider api={api} active={false}><Composer conversationId={7} /><State /></MessagingProvider>;
+  return render(userId ? <AuthContext.Provider value={{ user: { id: userId, username: 'me' } }}>{tree}</AuthContext.Provider> : tree);
+}
+function typeAndSend(text = 'hello') { fireEvent.change(screen.getByLabelText('MessagingComposer.MESSAGE'), { target: { value: text } }); fireEvent.click(screen.getByRole('button', { name: 'MessagingComposer.SEND' })); }
+const state = () => JSON.parse(screen.getByTestId('cache').textContent);
+
+afterEach(() => { cleanup(); realtimeSubscribers.clear(); });
+
+describe('Composer optimistic send and attachments', () => {
+  it('reconciles REST then websocket confirmation into exactly one row', () => {
+    const pending = { id: 'local-r1', conversation_id: 7, client_request_id: 'r1', status: 'pending' };
+    const rest = { id: 88, conversation_id: 7, body: 'hello', client_request_id: 'r1' };
+    let next = messagingReducer({ conversations: {}, messages: {}, cursors: { conversations: null, messages: {}, threads: {} } }, { type: 'messageOptimistic', message: pending });
+    next = messagingReducer(next, { type: 'messageReconciled', message: rest });
+    next = messagingReducer(next, { type: 'frame', frame: { type: 'message', conversation_id: 7, message: rest } });
+    expect(Object.values(next.messages)).toHaveLength(1);
+    expect(next.messages[88].client_request_id).toBe('r1');
+  });
+
+  it('reconciles websocket then REST confirmation into exactly one row', () => {
+    const pending = { id: 'local-r2', conversation_id: 7, client_request_id: 'r2', status: 'pending' };
+    const websocket = { id: 89, conversation_id: 7, body: 'hello', client_request_id: 'r2' };
+    let next = messagingReducer({ conversations: {}, messages: {}, cursors: { conversations: null, messages: {}, threads: {} } }, { type: 'messageOptimistic', message: pending });
+    next = messagingReducer(next, { type: 'frame', frame: { type: 'message', conversation_id: 7, message: websocket } });
+    next = messagingReducer(next, { type: 'messageReconciled', message: websocket });
+    expect(Object.values(next.messages)).toHaveLength(1);
+    expect(next.messages[89].client_request_id).toBe('r2');
+  });
+
+  it('retries a failed send with the same idempotency key and optimistic row', async () => {
+    const api = makeApi(); api.createMessage.mockRejectedValueOnce(new Error('offline')).mockResolvedValueOnce({ id: 90, conversation_id: 7, body: 'hello' });
+    renderComposer(api); typeAndSend(); await screen.findByRole('alert'); const first = api.createMessage.mock.calls[0][1].client_request_id;
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingComposer.RETRY' }));
+    await waitFor(() => expect(api.createMessage).toHaveBeenCalledTimes(2));
+    expect(api.createMessage.mock.calls[1][1].client_request_id).toBe(first);
+    await waitFor(() => expect(Object.keys(state().messages)).toEqual(['90']));
+  });
+
+  it('shows the server validation message for a rejected attachment upload', async () => {
+    // dcm's ConversationAttachmentView translates a rejected upload into a
+    // field-keyed {"files": [...]} body (the MSG-2 chunk-4 fix), not {detail}.
+    const api = makeApi(); api.uploadAttachments.mockRejectedValue({ response: { data: { files: ['File type application/octet-stream is not allowed.'] } } });
+    renderComposer(api); const input = document.querySelector('input[type=file]'); const file = new File(['x'], 'bad.exe', { type: 'application/octet-stream' });
+    fireEvent.change(input, { target: { files: [file] } }); fireEvent.click(screen.getByRole('button', { name: 'MessagingComposer.SEND' }));
+    await screen.findByText('MessagingComposer.UPLOAD_ERROR:File type application/octet-stream is not allowed.');
+  });
+
+  it('shows the server validation message when it arrives as {detail} (the text-message error shape)', async () => {
+    const api = makeApi(); api.createMessage.mockRejectedValue({ response: { data: { detail: 'Posting is not permitted.' } } });
+    renderComposer(api); typeAndSend('hello');
+    await screen.findByText('MessagingComposer.SEND_ERROR:Posting is not permitted.');
+  });
+
+  it('populates the optimistic row with the current user as sender, not "unknown sender"', async () => {
+    let resolveCreate; const api = makeApi(); api.createMessage.mockReturnValue(new Promise((resolve) => { resolveCreate = resolve; }));
+    renderComposer(api, { userId: 9 }); typeAndSend('hello');
+    await waitFor(() => expect(Object.keys(state().messages)).toHaveLength(1));
+    const [optimistic] = Object.values(state().messages);
+    expect(optimistic.status).toBe('pending');
+    expect(optimistic.sender).toEqual({ id: 9, display_name: 'me' });
+    resolveCreate({ id: 91, conversation_id: 7, body: 'hello' });
+  });
+
+  it('end-to-end: a real in-flight send reconciled by a WS frame arriving before the REST response settles produces exactly one row', async () => {
+    let resolveCreate; const api = makeApi(); api.createMessage.mockReturnValue(new Promise((resolve) => { resolveCreate = resolve; }));
+    renderComposer(api); typeAndSend('hello');
+    await waitFor(() => expect(Object.keys(state().messages)).toHaveLength(1));
+    const requestId = api.createMessage.mock.calls[0][1].client_request_id;
+    // The WS frame for this message's creation arrives while the REST POST is still in flight.
+    act(() => dispatchMessagingFrame({ envelope: 'messaging', type: 'message', conversation_id: 7, message: { id: 91, conversation_id: 7, body: 'hello', client_request_id: requestId } }));
+    expect(Object.keys(state().messages)).toEqual(['91']);
+    // The REST response for the same send resolves afterward and must not create a second row.
+    await act(async () => resolveCreate({ id: 91, conversation_id: 7, body: 'hello', client_request_id: requestId }));
+    expect(Object.keys(state().messages)).toEqual(['91']);
+  });
+
+  it('mounts Composer and AttachmentList independently', async () => {
+    const api = makeApi(); const { unmount } = renderComposer(api); expect(screen.getByLabelText('MessagingComposer.LABEL')).toBeTruthy(); unmount();
+    render(<MessagingProvider api={api} active={false}><AttachmentList attachments={[{ id: 1, filename: 'note.pdf', content_type: 'application/pdf' }]} /></MessagingProvider>);
+    expect(screen.getByLabelText('MessagingAttachments.LABEL')).toBeTruthy();
+  });
+});

package/tests/messagingExports.test.js

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+import { AttachmentList, Composer, ConversationLaunchers, ConversationList, MessageBubble, MessagingProvider, MessagingScopeConfig, messagingTranslations, PollCard, ReactionBar, ReadTicks, Thread, useMessaging } from '../src/index';
+
+describe('messaging barrel exports', () => {
+  it('exports the provider, hook, standalone list and launchers', () => {
+    expect(MessagingProvider).toBeDefined();
+    expect(useMessaging).toBeDefined();
+    expect(ConversationList).toBeDefined();
+    expect(ConversationLaunchers).toBeDefined();
+    expect(Thread).toBeDefined();
+    expect(MessageBubble).toBeDefined();
+    expect(ReadTicks).toBeDefined();
+    expect(Composer).toBeDefined();
+    expect(AttachmentList).toBeDefined();
+    expect(ReactionBar).toBeDefined();
+    expect(PollCard).toBeDefined();
+    expect(MessagingScopeConfig).toBeDefined();
+    expect(messagingTranslations).toBeDefined();
+  });
+});

package/tests/messagingInteractions.test.jsx

@@ -0,0 +1,112 @@
+// @vitest-environment jsdom
+import React from 'react';
+import { afterEach, 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?.message ? `${key}:${options.message}` : key }) }));
+vi.mock('../src/notifications/realtime', () => ({ useRealtime: () => ({ subscribe: () => () => {}, onReconnect: () => () => {} }) }));
+
+import { Composer } from '../src/messaging/Composer';
+import { MessagingProvider, useMessaging } from '../src/messaging/MessagingProvider';
+import { PollCard } from '../src/messaging/PollCard';
+import { ReactionBar } from '../src/messaging/ReactionBar';
+import { MessagingScopeConfig } from '../src/messaging/MessagingScopeConfig';
+
+function CacheState() { const { cache } = useMessaging(); return <output data-testid="cache">{JSON.stringify(cache)}</output>; }
+
+const baseApi = () => ({ listConversations: vi.fn().mockResolvedValue({ results: [] }), listMessages: vi.fn().mockResolvedValue({ results: [] }), getUnreadCount: vi.fn().mockResolvedValue({ unread_count: 0, by_conversation: {} }), addReaction: vi.fn(), removeReaction: vi.fn(), votePoll: vi.fn(), closePoll: vi.fn(), createPoll: vi.fn() });
+afterEach(cleanup);
+
+describe('messaging reactions and polls', () => {
+  it('round-trips add and remove reactions through the cache-backed API', async () => {
+    const api = baseApi(); api.addReaction.mockResolvedValue({ reactions: [{ emoji: '👍', count: 1, reacted: true }] }); api.removeReaction.mockResolvedValue({ reactions: [] });
+    const { rerender } = render(<MessagingProvider api={api} active={false}><ReactionBar message={{ id: 7, reactions: [{ emoji: '👍', count: 1, reacted: false }] }} /></MessagingProvider>);
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingReactions.TOGGLE' })); await waitFor(() => expect(api.addReaction).toHaveBeenCalledWith(7, '👍'));
+    rerender(<MessagingProvider api={api} active={false}><ReactionBar message={{ id: 7, reactions: [{ emoji: '👍', count: 1, reacted: true }] }} /></MessagingProvider>);
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingReactions.TOGGLE' })); await waitFor(() => expect(api.removeReaction).toHaveBeenCalledWith(7, '👍'));
+  });
+
+  it('uses single selection for a single poll and preserves selections for a multi poll', async () => {
+    const single = baseApi(); single.votePoll.mockResolvedValue({ poll: { id: 1, options: [] } });
+    const { unmount } = render(<MessagingProvider api={single} active={false}><PollCard message={{ id: 7, poll: { id: 1, question: 'One', options: [{ id: 1, text: 'A' }, { id: 2, text: 'B' }], allow_multiple: false }}} /></MessagingProvider>);
+    const choices = screen.getAllByRole('checkbox'); fireEvent.click(choices[0]); fireEvent.click(choices[1]); fireEvent.click(screen.getByRole('button', { name: 'MessagingPoll.VOTE' })); await waitFor(() => expect(single.votePoll).toHaveBeenCalledWith(1, [2])); unmount();
+    const multiple = baseApi(); multiple.votePoll.mockResolvedValue({ poll: { id: 2, options: [] } }); render(<MessagingProvider api={multiple} active={false}><PollCard message={{ id: 8, poll: { id: 2, question: 'Many', options: [{ id: 1, text: 'A' }, { id: 2, text: 'B' }], allow_multiple: true }}} /></MessagingProvider>);
+    const multiChoices = screen.getAllByRole('checkbox'); fireEvent.click(multiChoices[0]); fireEvent.click(multiChoices[1]); fireEvent.click(screen.getByRole('button', { name: 'MessagingPoll.VOTE' })); await waitFor(() => expect(multiple.votePoll).toHaveBeenCalledWith(2, [1, 2]));
+  });
+
+  it('only exposes close to the creator/capability and surfaces a forbidden close', async () => {
+    const api = baseApi(); api.closePoll.mockRejectedValue({ response: { data: { detail: 'Not permitted' } } });
+    const { rerender } = render(<MessagingProvider api={api} active={false}><PollCard message={{ id: 7, poll: { id: 1, question: 'Q', options: [], created_by: 2 }}} /></MessagingProvider>);
+    expect(screen.queryByRole('button', { name: 'MessagingPoll.CLOSE' })).toBeNull();
+    rerender(<MessagingProvider api={api} active={false}><PollCard canClose message={{ id: 7, poll: { id: 1, question: 'Q', options: [] }}} /></MessagingProvider>);
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingPoll.CLOSE' })); await screen.findByRole('alert');
+  });
+
+  it('creates polls with an idempotency key', async () => {
+    const api = baseApi(); api.createPoll.mockResolvedValue({ id: 70, conversation_id: 4, poll: { id: 1 } });
+    render(<MessagingProvider api={api} active={false}><Composer conversationId={4} /></MessagingProvider>);
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingPoll.CREATE' })); fireEvent.change(screen.getByLabelText('MessagingPoll.QUESTION'), { target: { value: 'Where?' } });
+    const options = screen.getAllByLabelText(/MessagingPoll.OPTION/); fireEvent.change(options[0], { target: { value: 'Here' } }); fireEvent.change(options[1], { target: { value: 'There' } });
+    fireEvent.click(screen.getAllByRole('button', { name: 'MessagingPoll.CREATE' })[0]); await waitFor(() => expect(api.createPoll).toHaveBeenCalled());
+    expect(api.createPoll.mock.calls[0][2].idempotencyKey).toBeTruthy();
+  });
+
+  it('mounts the scope config as an independent provider collaborator', async () => {
+    const api = baseApi(); api.getConversationConfig = vi.fn().mockResolvedValue({ dm_policy: 'all', group_chat_enabled: true, everyone_can_post: false });
+    render(<MessagingProvider api={api} active={false}><MessagingScopeConfig conversationId={4} /></MessagingProvider>);
+    await screen.findByLabelText('MessagingConfig.LABEL');
+    expect(api.getConversationConfig).toHaveBeenCalledWith(4);
+  });
+
+  it('creates an announcement with a title, body and host-supplied link target', async () => {
+    const api = baseApi(); api.createMessage = vi.fn().mockResolvedValue({ id: 90, conversation_id: 4, kind: 'announcement', title: 'Heads up' });
+    render(<MessagingProvider api={api} active={false}><Composer conversationId={4} allowAnnouncement linkTarget="/events/4/info" /></MessagingProvider>);
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingAnnouncement.CREATE' }));
+    fireEvent.change(screen.getByLabelText('MessagingAnnouncement.TITLE'), { target: { value: 'Heads up' } });
+    fireEvent.change(screen.getByLabelText('MessagingAnnouncement.BODY'), { target: { value: 'Schedule changed.' } });
+    fireEvent.click(screen.getAllByRole('button', { name: 'MessagingAnnouncement.SEND' })[0]);
+    await waitFor(() => expect(api.createMessage).toHaveBeenCalled());
+    const [, payload] = api.createMessage.mock.calls[0];
+    expect(payload).toMatchObject({ kind: 'announcement', title: 'Heads up', body: 'Schedule changed.', link_target: '/events/4/info' });
+  });
+
+  it('carries title and link_target into the optimistic row, not just the final REST payload', async () => {
+    const api = baseApi(); api.createMessage = vi.fn().mockReturnValue(new Promise(() => {}));
+    render(<MessagingProvider api={api} active={false}><Composer conversationId={4} allowAnnouncement linkTarget="/events/4/info" /><CacheState /></MessagingProvider>);
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingAnnouncement.CREATE' }));
+    fireEvent.change(screen.getByLabelText('MessagingAnnouncement.TITLE'), { target: { value: 'Heads up' } });
+    fireEvent.click(screen.getAllByRole('button', { name: 'MessagingAnnouncement.SEND' })[0]);
+    await waitFor(() => {
+      const [optimistic] = Object.values(JSON.parse(screen.getByTestId('cache').textContent).messages);
+      expect(optimistic.status).toBe('pending');
+      expect(optimistic.title).toBe('Heads up');
+      expect(optimistic.link_target).toBe('/events/4/info');
+    });
+  });
+
+  it('does not offer announcement composing unless the host opts in', () => {
+    const api = baseApi();
+    render(<MessagingProvider api={api} active={false}><Composer conversationId={4} /></MessagingProvider>);
+    expect(screen.queryByRole('button', { name: 'MessagingAnnouncement.CREATE' })).toBeNull();
+  });
+
+  it('disables the chip while pending, then rolls back and re-enables it on API failure', async () => {
+    let rejectAdd; const api = baseApi(); api.addReaction.mockReturnValue(new Promise((_, reject) => { rejectAdd = reject; }));
+    render(<MessagingProvider api={api} active={false}><ReactionBar message={{ id: 7, reactions: [{ emoji: '👍', count: 1, reacted: false }] }} /></MessagingProvider>);
+    const chip = screen.getByRole('button', { name: 'MessagingReactions.TOGGLE' });
+    fireEvent.click(chip);
+    await waitFor(() => expect(chip.className.includes('Mui-disabled')).toBe(true));
+    rejectAdd({ response: { data: { detail: 'Reactions disabled' } } });
+    await screen.findByRole('alert');
+    expect(chip.className.includes('Mui-disabled')).toBe(false);
+  });
+
+  it('ignores a second click on the same reaction while the first toggle is still in flight', async () => {
+    let resolveAdd; const api = baseApi(); api.addReaction.mockReturnValue(new Promise((resolve) => { resolveAdd = resolve; }));
+    render(<MessagingProvider api={api} active={false}><ReactionBar message={{ id: 7, reactions: [{ emoji: '👍', count: 1, reacted: false }] }} /></MessagingProvider>);
+    const chip = screen.getByRole('button', { name: 'MessagingReactions.TOGGLE' });
+    fireEvent.click(chip); fireEvent.click(chip);
+    resolveAdd({ reactions: [{ emoji: '👍', count: 2, reacted: true }] });
+    await waitFor(() => expect(api.addReaction).toHaveBeenCalledTimes(1));
+  });
+});

package/tests/realtime.test.jsx

@@ -37,6 +37,13 @@ function StreamConsumer({ envelope, testId }) {
   return <output data-testid={testId}>{JSON.stringify(received)}</output>;
 }
 
+function ReconnectConsumer() {
+  const { onReconnect } = useRealtime();
+  const [count, setCount] = React.useState(0);
+  React.useEffect(() => onReconnect(() => setCount((current) => current + 1)), [onReconnect]);
+  return <output data-testid="reconnect-count">{count}</output>;
+}
+
 function NotificationsConsumer() {
   const notifications = useNotifications();
   return (
@@ -181,6 +188,26 @@ describe('realtime primitive (NOTIF-13)', () => {
     }
   });
 
+  it('additively signals consumers when a closed connection re-establishes', async () => {
+    vi.useFakeTimers();
+    try {
+      render(
+        <AuthContext.Provider value={{ user: { id: 4 } }}>
+          <NotificationsProvider><ReconnectConsumer /></NotificationsProvider>
+        </AuthContext.Provider>,
+      );
+      await vi.waitFor(() => expect(MockWebSocket.instances).toHaveLength(1));
+      MockWebSocket.instances[0].onopen();
+      expect(screen.getByTestId('reconnect-count').textContent).toBe('0');
+      MockWebSocket.instances[0].onclose();
+      await vi.advanceTimersByTimeAsync(1_000);
+      MockWebSocket.instances[1].onopen();
+      await vi.waitFor(() => expect(screen.getByTestId('reconnect-count').textContent).toBe('1'));
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it("NotificationsProvider's public context value is unchanged", async () => {
     renderWithStreams();
     await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1));

package/vite.config.mjs

@@ -0,0 +1,6 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+});

package/work-orders/CHART-1.md

@@ -0,0 +1,285 @@
+# CHART-1 — Shared chart kit: themed `ChartFrame` + MUI X-Charts Bar/Line presets
+
+- **Repo:** `ui-core-micha` (`@micha.bigler/ui-core-micha`), branch `main` (library, publish-from-main; no `develop`)
+- **Tier:** 2 (new shared-library public API + a dependency change + governance-anchored contract)
+- **Status:** done (f1b3614)
+- **Workstream:** `CHART-*` (chart / data-viz kit)
+
+> This file has two halves. **Part A (Envelope)** below is authored by the Expertenchat and is the
+> authoritative WHAT/WHY — changing it is a scope change that returns to the operator. **Part B
+> (Implementation map)** is filled by the Orchestrator on `git pull` from repo knowledge, refined
+> against the landed code, without altering Part A.
+
+---
+
+## Part A — Envelope (authoritative WHAT/WHY)
+
+### Goal (Ziel)
+
+Build the **shared chart kit** that this stack's governance already references as a not-yet-existing
+dependency (`.codex/skills/frontend-engineering/SKILL.md` §"Charts / data-viz": *"use the shared
+chart kit (a themed `ChartFrame` + MUI X-Charts primitives) once it exists"*; `ui_reviewer`
+checklist mirrors it). Today every hram Results/Research panel re-implements the same
+`Paper + title + toolbar + loading/error/empty + fixed-height box + export buttons` scaffolding
+(~20 panels, ~200 lines of boilerplate each), and there is no reusable frame. This WO delivers the
+reusable estate-wide primitives so charts stop being the recurring quality trap.
+
+### Expected outcome
+
+A new additive, barrel-exported (`src/index.js`) chart module in `ui-core-micha`, published as an
+additive **minor** version bump (`2.12.0 → 2.15.0`, publish-from-main per the dcm/ucm publish
+topology), providing exactly:
+
+1. **`ChartFrame` — the chart-type-agnostic scaffolding.** This is the primary value; it wraps *any*
+   chart body via `children` (an MUI X-Charts primitive **or** a bespoke raw-`<svg>` body), so it
+   serves all ~20 hram panels including the SVG specialists. It owns:
+   - a `Paper` container (default `variant="outlined"`, matching hram's Research panels),
+   - `title` (required) + optional `subtitle`,
+   - a `toolbar` slot (`ReactNode`, rendered in the header row — for the panels' `ToggleButtonGroup`/
+     selectors),
+   - mutually-exclusive state rendering with precedence **loading → error → empty → children**:
+     `loading` (spinner), `error` (`Alert severity="error"`), `isEmpty` + `emptyMessage`
+     (`Alert severity="info"`),
+   - a **responsive, container-sized** chart area (governance: *"container-sized, not fixed px"*),
+     with an optional `minHeight`/`aspect` fallback so migrated panels don't reflow unexpectedly,
+   - optional **Export SVG / Export PNG** controls in the footer (consolidating the per-panel export
+     hram already hand-rolls), shown only when export is enabled, operating on the rendered chart
+     container,
+   - basic **a11y** (frame `title`/`aria-label`, `role="img"` or equivalent on the chart region).
+   All of ChartFrame's own user-facing strings (empty/error defaults, export button labels) go
+   through `react-i18next` — no hardcoded copy.
+
+2. **`BarChart` preset** — a thin wrapper over MUI X-Charts `BarChart` that bakes in the governance
+   chart contract so callers cannot forget it: **axis labels on both axes (with units)** required via
+   props, **legend auto-shown only when >1 series**, **tooltip on**, **theme-token colours** (accepts
+   a caller palette / per-series colours, defaults to the kit's neutral palette — never hardcoded
+   hex), **responsive container**. Must cover the variants hram actually uses: single-series, grouped
+   (multi-metric), and stacked (incl. the dual-axis case in `GenericAnalysisPlot`).
+
+3. **`LineChart` preset** — same contract, for multi-series time-series (covers
+   `ResultsTimelinePanel` / `ExpertTimelinePanel`).
+
+4. **Neutral palette + locale-aware formatter helpers** — a theme-aware (light **and** dark)
+   categorical + sequential palette and number formatters (percentage, compact, ratio) that the
+   presets default to and that apps may pass through. The kit provides the **neutral default and the
+   pass-through seam only**; domain palettes and domain labels stay in the consuming app (see
+   non-goals).
+
+**Acceptance = the `ui_reviewer` chart checklist is satisfiable by construction:** any chart built
+with the presets has axis labels (both axes), a legend when multi-series, a tooltip, theme-token
+colours, container-sized responsiveness, i18n-able labels, and empty/loading states + basic a11y
+from the frame.
+
+### Scope
+
+- New chart module (e.g. `src/components/charts/`), exported from `src/index.js` (additive only).
+- `ChartFrame`, `BarChart`, `LineChart`, and the neutral palette/formatter helpers.
+- Add `@mui/x-charts` as a **`peerDependency`** (see Precondition — this is the one approval-gated
+  item). Peer, not a direct dep, so the consuming app owns the version and there is no double-bundle;
+  hram already depends on `@mui/x-charts` and satisfies the peer.
+- Kit-owned strings wired through the existing ucm `react-i18next` setup (`src/i18n`).
+- Additive minor version bump + publish (`2.15.0`).
+
+### Non-goals / do-not-touch (explicit)
+
+- **No SVG chart primitives in v1.** No generic scatter/bubble, tornado, heatmap, confidence-interval,
+  or Pareto-frontier component. hram's bespoke SVG panels keep their own `<svg>` **body**, rendered
+  **inside `ChartFrame`** (so they gain the shared frame + export). This is a **deliberately surfaced
+  partial state**, not a silent half-solution: retiring the raw SVG by lifting these into MUI
+  X-Charts / kit primitives is a tracked future **CHART-2**, gated separately. (Governance's
+  "extend the kit, don't hand-roll" is the direction; v1 intentionally does not yet cover these.)
+- **No geo/maps** — `react-leaflet` stays app-side.
+- **No tables** — MUI `Table` stays app-side.
+- **No domain palettes or domain labels** — hram's `dataViz` palette (coverage/dalys/cost/…) and its
+  `Results.*` i18n keys stay in hram; the kit ships only the neutral default + pass-through seam.
+- **Do not migrate hram in this WO.** hram adoption (pin bump + panel migration) is a separate
+  follow-on WO in the `hram` repo, gated on `2.15.0` being published (see Precondition).
+- Do not touch auth, CI, or any existing ucm export beyond additively adding the chart exports.
+
+### Precondition / execution-gate / ordering
+
+1. **Dependency-change approval (blocking):** adding `@mui/x-charts` as a `peerDependency` is a
+   dependency change → **explicit operator approval required before the Orchestrator adds it**
+   (AGENTS.md "Require explicit approval before touching: dependency changes").
+2. **Publish before adoption:** the kit lands + publishes as the **next free additive minor**. At
+   authoring, `2.13.0` (NOTIF-13) and `2.14.0` (NOTIF-12) are already claimed, so the target is
+   `2.15.0` — but the registry is the source of truth (publish-from-main; the ucm `version_check`
+   compares against it). The Orchestrator confirms the next free minor against the registry at
+   publish time and adjusts if the NOTIF workstream has advanced further; then confirms it is live
+   before any consumer pins it (per the dcm/ucm publish-topology note).
+3. **hram adoption is gated** on `2.15.0` published; its follow-on WO pins `ui-core-micha >= 2.15.0`.
+
+### Risks
+
+- **API-fit risk (primary):** ChartFrame's props must let all ~20 hram panels — including the
+  SVG-bodied ones — slot in as `children` without escape hatches; if the frame is too opinionated the
+  migration fights it. Mitigation: frame stays deliberately thin and children-based; the presets, not
+  the frame, own chart specifics.
+- **Responsive vs. fixed height:** governance wants container-sized; hram currently hardcodes
+  `height: 300`. The frame defaults responsive but must offer a `minHeight`/`aspect` fallback so the
+  later migration doesn't silently reflow every panel.
+- **Export consolidation:** hram hand-rolls per-panel SVG/PNG export. A generic export from a
+  container ref must handle both an MUI X-Charts body (SVG under the hood) and a raw-`<svg>` body.
+  **Reuse hram's existing export mechanism / a stdlib-level approach; do NOT add a heavy new
+  dependency for PNG rendering without separate approval** (that would be another dependency gate).
+  If a clean generic export can't be done without a new dep, ship the SVG-serialize path and defer
+  PNG — surface the choice, don't silently drop it.
+- **Theme/dark-mode:** the neutral palette must resolve correctly in both light and dark MUI themes.
+- **i18n:** no hardcoded user-facing strings in the kit; all through ucm's `react-i18next`.
+
+### Required tests to WRITE (narrow — component-level, scoped to this change)
+
+Written as part of implementation (the implementer writes the test code); **run only by the
+Orchestrator**. Use ucm's existing frontend test setup (Vitest + React Testing Library, per prior
+ucm WOs). Scoped to the new components — not the ucm full suite.
+
+- **ChartFrame:** renders `title`/`subtitle`; `loading` shows the spinner and hides children;
+  `error` shows an error Alert; `isEmpty` shows `emptyMessage`; **state precedence
+  loading → error → empty → children** holds; the `toolbar` slot renders; export controls appear
+  only when export is enabled and invoke the handler / produce output; a11y `title`/`aria`/role
+  present on the chart region.
+- **BarChart preset:** axis labels render on **both** axes; **legend appears only when >1 series**;
+  tooltip is enabled; colours come from theme tokens / passed palette (assert **no hardcoded hex**);
+  container is responsive (not a fixed px width); single, grouped, and stacked variants each render.
+- **LineChart preset:** multi-series renders; both-axis labels; legend when multi-series; tooltip on.
+- **Palette + formatters:** neutral palette resolves in both light and dark theme; number formatters
+  are locale-aware (percentage + compact) across at least two locales.
+- **i18n:** the kit's own strings resolve via i18n, not hardcoded (missing-key / alternate-locale
+  check).
+
+(Do **not** run the ucm full suite for this WO — that is the promotion gate's job. Run only the new
+components' scoped tests, once, as the per-WO gate, alongside the single independent review on the
+full assembled diff.)
+
+---
+
+## Part B — Implementation map (filled by the Orchestrator on `git pull`)
+
+**Dependency approval:** operator explicitly approved adding `@mui/x-charts` as a `peerDependency`
+(2026-07-30, in-chat). Cleared to proceed.
+
+**Target version:** current `package.json` `version` is `2.14.0` (NOTIF-12 already published) →
+next free additive minor is **`2.15.0`**, matching the Envelope's target. Confirm still free against
+the npm registry immediately before publish.
+
+### Named files to change
+
+- `src/components/charts/ChartFrame.jsx` — new. Frame component (Paper/title/toolbar/state
+  precedence/export/a11y).
+- `src/components/charts/BarChart.jsx` — new. Preset over `@mui/x-charts` `BarChart`.
+- `src/components/charts/LineChart.jsx` — new. Preset over `@mui/x-charts` `LineChart`.
+- `src/components/charts/palette.js` — new. Neutral theme-aware categorical + sequential palette,
+  resolved from the active MUI theme (light/dark), NOT hardcoded hex in consumer-visible API.
+- `src/components/charts/formatters.js` — new. Locale-aware number formatters (percentage, compact,
+  ratio) built on `Intl.NumberFormat`, driven off `i18next.language`.
+- `src/components/charts/exportChart.js` — new. Generic SVG/PNG export util operating on a container
+  `ref`, mirroring hram's `XMLSerializer` → `Blob` → (PNG: `canvas` 2x-scale) → anchor-download
+  pattern (see hram `AllocationPerformancePanel.jsx` `handleExportSvg`/`handleExportPng`, no new
+  dependency).
+- `src/index.js` — add barrel exports for `ChartFrame`, `BarChart`, `LineChart`, palette/formatter
+  helpers, additive only, alongside the existing "Components" export block (~lines 1-72).
+- `src/i18n/chartsTranslations.ts` — new namespace, mirrors the existing
+  `notificationsTranslations.ts` shape (`{ 'ChartFrame.KEY': { de, fr, en, sw } }`); register it
+  wherever `notificationsTranslations`/`onboardingTranslations` are aggregated into the i18n bundle.
+- `package.json` — add `"@mui/x-charts": "^8.0.0"` (or the loosest range compatible with hram's
+  pinned `8.28.2`) to `peerDependencies`; bump `"version"` to `2.15.0` (confirm free at publish time
+  per above); add `@mui/x-charts` to `devDependencies` too (peer deps aren't auto-installed, tests
+  need it present).
+- `tests/ChartFrame.test.jsx`, `tests/BarChart.test.jsx`, `tests/LineChart.test.jsx`,
+  `tests/chartsPalette.test.js` (or similar) — new, in the existing `/tests/` root dir (not
+  co-located), `@vitest-environment jsdom` pragma, Vitest + RTL per `tests/NotificationSettings.test.jsx`
+  conventions.
+
+### Architecture/contract slice
+
+- **Component style:** plain `.jsx` (no TypeScript, no PropTypes — JSDoc only), MUI `sx` prop for
+  styling, functional components with hooks. Mirror `src/components/ProfileComponent.jsx`.
+- **i18n:** `useTranslation()` from `react-i18next`; keys namespaced `Category.KEY_NAME` (e.g.
+  `ChartFrame.EXPORT_SVG_LABEL`, `ChartFrame.EMPTY_DEFAULT`). Translation objects are flat
+  `{ key: { de, fr, en, sw } }` dictionaries per `src/i18n/notificationsTranslations.ts` — follow
+  that exact shape for `chartsTranslations.ts`, all four locales required.
+- **Barrel export:** `src/index.js` groups exports by category with comment headers (Auth Context,
+  API/Services, Layouts, Pages, Components, Translations, Notifications, Onboarding) — add a
+  `// Charts` section, export components + `chartsTranslations` alongside the others.
+- **Theme:** no centralized theme file exists in ucm today (components rely on the MUI default
+  theme via `sx` and `useTheme()`). The palette module must read `theme.palette.mode` via
+  `useTheme()` to select light/dark variants — do not assume a specific app theme shape beyond
+  standard MUI.
+- **Peer deps:** current `peerDependencies` list (`@mui/material ^7.3.11`, `react ^19.2.6`, etc.) —
+  add `@mui/x-charts` alongside, do not touch existing entries.
+- **hram reference (adoption target, NOT touched in this WO):** `hram/frontend/src/components/
+  OutputComponents/Results/ResultsTimelinePanel.jsx` and `ExpertTimelinePanel.jsx` show the
+  Paper→Typography(h6)→toolbar(ToggleButtonGroup)→loading/error/empty(Alert)→chart→footer skeleton
+  ChartFrame must replicate structurally; `AllocationPerformancePanel.jsx` (~lines 198-238) has the
+  reference export functions; `hram/frontend/src/.../theme.js` `dataViz` palette (~lines 20-30) is
+  the domain palette that stays app-side — the kit's neutral palette is a separate, generic
+  categorical/sequential set, not a copy of `dataViz`.
+
+### Key snippets (for the implementer to mirror, not copy verbatim)
+
+hram's existing Paper/title/toolbar/state scaffolding (`ResultsTimelinePanel.jsx`/
+`ExpertTimelinePanel.jsx`):
+```jsx
+<Paper variant="outlined" sx={{ p: 2 }}>
+  <Box sx={{ display: "flex", alignItems: "center", justifyContent: "space-between" }}>
+    <Typography variant="h6">{t("...")}</Typography>
+    <ToggleButtonGroup exclusive size="small" ...>...</ToggleButtonGroup>
+  </Box>
+  {loading && <CircularProgress />}
+  {error && <Alert severity="error">...</Alert>}
+  {isEmpty && <Alert severity="info">...</Alert>}
+  {!loading && !error && !isEmpty && children}
+</Paper>
+```
+hram's export pattern (`AllocationPerformancePanel.jsx`): `XMLSerializer().serializeToString(svgRef.current)`
+→ `Blob(['image/svg+xml'])` → anchor download for SVG; for PNG, load the SVG blob into an `Image`,
+draw to a 2x-scaled `<canvas>` with a white background fill, then `canvas.toBlob()` → anchor download.
+`exportChart.js` should generalize this to accept a container ref (find the first `<svg>` descendant)
+so it works for both an MUI X-Charts body and a raw-`<svg>` body.
+
+### Invariants / do-not-touch / pitfalls
+
+- Additive exports only — do not modify or remove any existing `src/index.js` export line.
+- `@mui/x-charts` is a **peerDependency**, never a direct `dependency` (hram supplies its own
+  installed copy; ucm must not double-bundle it).
+- No hardcoded hex/palette values in the public API surface — palette resolves from
+  `useTheme().palette.mode`; tests must assert this (e.g. render under both a light and dark MUI
+  theme, assert different resolved values).
+- Container-sized/responsive by default — do not hardcode chart pixel width; offer `minHeight`/
+  `aspect` as an opt-in fallback only.
+- Every user-facing string in the kit goes through `t('ChartFrame....')` — no literal English
+  strings in JSX.
+- Do not touch hram, `dataViz`, or any hram i18n keys — this WO is ucm-only.
+- State precedence is strict: `loading` beats `error` beats `isEmpty` beats `children` — write the
+  test asserting this order, not just each state individually.
+- No new heavy dependency for PNG export (e.g. no `html2canvas`/`dom-to-image`) — reuse the
+  serialize+canvas approach; if a clean generic path is not achievable without a new dep, ship
+  SVG-export only and explicitly note PNG deferred in the `RESULT:` — do not silently drop it.
+
+### Progress contract
+
+Codex must emit: one `PLAN: <step1> | <step2> | …` line up front; a single-line
+`PROGRESS: [<n>/<total>] <present-tense action>` before every file/edit/step and `… done` on
+completion, spaced so no gap exceeds ~2 min; exactly one final `RESULT: DONE|BLOCKED <reason>`.
+stdout unbuffered.
+
+### Execution directive
+
+Implement through `codex exec` in the background, invoked **directly via Bash** (never the
+`debugger`/`*_coder` Agent wrappers), with **both** `--skip-git-repo-check` and
+`--dangerously-bypass-approvals-and-sandbox`, prompt passed as a positional argument read from this
+committed file (`"$(cat work-orders/CHART-1.md)"`). cwd = `ui-core-micha` repo root (this repo),
+**never** the workspace root `…/webapps`. Fall back to direct Claude implementation only on Codex
+quota/rate-limit/non-zero exit. Codex WRITES the required tests but MUST NOT RUN them and MUST NOT
+run any review or `git add`/`commit`/`push` — leave the working tree uncommitted for the
+Orchestrator's independent review, which runs after Codex finishes.
+
+---
+
+## Pastable mini-handover (for the fresh Orchestrator session)
+
+> Orchestrator: implement `work-orders/CHART-1.md` in `ui-core-micha` (branch `main`). `git pull`
+> first, read the WO, then follow the `orchestrate-codex` skill (Codex-first, fill Part B, run your
+> own independent review + scoped tests, commit on green). NOTE the blocking precondition: adding
+> `@mui/x-charts` as a `peerDependency` is a dependency change needing explicit operator approval
+> before it is added.