@micha.bigler/ui-core-micha 2.26.3 → 2.28.1

package/tests/PasswordSetForm.test.jsx

@@ -0,0 +1,70 @@
+// @vitest-environment jsdom
+import React from 'react';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key, fallback) => (typeof fallback === 'string' ? fallback : key) }),
+}));
+
+import { PasswordSetForm } from '../src/components/PasswordSetForm';
+
+afterEach(() => {
+  cleanup();
+});
+
+function fillAndSubmit(password1, password2) {
+  fireEvent.change(screen.getByLabelText('Auth.NEW_PASSWORD_LABEL'), { target: { value: password1 } });
+  fireEvent.change(screen.getByLabelText('Auth.PASSWORD_CONFIRM_LABEL'), { target: { value: password2 } });
+  fireEvent.click(screen.getByRole('button', { name: 'Auth.PASSWORD_SET_BUTTON' }));
+}
+
+describe('PasswordSetForm', () => {
+  it('renders the default password-rules helperText', () => {
+    render(<PasswordSetForm onSubmit={vi.fn()} />);
+    expect(screen.getAllByText('Auth.PASSWORD_RULES_HINT').length).toBeGreaterThan(0);
+  });
+
+  it('lets a caller override the helperText via passwordRulesHint', () => {
+    render(<PasswordSetForm onSubmit={vi.fn()} passwordRulesHint="Custom rule text" />);
+    expect(screen.getAllByText('Custom rule text').length).toBeGreaterThan(0);
+    expect(screen.queryByText('Auth.PASSWORD_RULES_HINT')).toBeNull();
+  });
+
+  it('blocks submit and shows the local error for a password shorter than 8 characters', () => {
+    const onSubmit = vi.fn();
+    render(<PasswordSetForm onSubmit={onSubmit} />);
+    fillAndSubmit('short1', 'short1');
+    expect(screen.getByText('Auth.PASSWORD_TOO_SHORT_LOCAL')).toBeTruthy();
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  it('blocks submit and shows the local error for an entirely numeric password', () => {
+    const onSubmit = vi.fn();
+    render(<PasswordSetForm onSubmit={onSubmit} />);
+    fillAndSubmit('12345678', '12345678');
+    expect(screen.getByText('Auth.PASSWORD_NUMERIC_LOCAL')).toBeTruthy();
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  it('calls onSubmit for a valid, non-numeric password of sufficient length', () => {
+    const onSubmit = vi.fn();
+    render(<PasswordSetForm onSubmit={onSubmit} />);
+    fillAndSubmit('correct-horse-1', 'correct-horse-1');
+    expect(onSubmit).toHaveBeenCalledWith('correct-horse-1');
+  });
+
+  it('honours a custom minPasswordLength for an app with a looser backend policy', () => {
+    const onSubmit = vi.fn();
+    render(<PasswordSetForm onSubmit={onSubmit} minPasswordLength={4} />);
+    fillAndSubmit('ab12', 'ab12');
+    expect(onSubmit).toHaveBeenCalledWith('ab12');
+  });
+
+  it('allows an entirely numeric password when allowNumericPassword is set', () => {
+    const onSubmit = vi.fn();
+    render(<PasswordSetForm onSubmit={onSubmit} allowNumericPassword />);
+    fillAndSubmit('12345678', '12345678');
+    expect(onSubmit).toHaveBeenCalledWith('12345678');
+  });
+});

package/tests/TimeSeriesChart.test.jsx

@@ -38,19 +38,15 @@ const SAMPLE_DATA = {
 function renderChart(props = {}) {
   const i18n = i18next.createInstance();
   i18n.init({ lng: 'en', resources, interpolation: { escapeValue: false } });
-  return render(
+  const wrap = (chartProps) => (
     <ThemeProvider theme={createTheme()}>
       <I18nextProvider i18n={i18n}>
-        <TimeSeriesChart
-          title="Activity"
-          xAxisLabel="Day"
-          yAxisLabel="Count"
-          data={SAMPLE_DATA}
-          {...props}
-        />
+        <TimeSeriesChart title="Activity" xAxisLabel="Day" yAxisLabel="Count" data={SAMPLE_DATA} {...chartProps} />
       </I18nextProvider>
-    </ThemeProvider>,
+    </ThemeProvider>
   );
+  const view = render(wrap(props));
+  return { ...view, rerenderWith: (nextProps) => view.rerender(wrap(nextProps)) };
 }
 
 describe('TimeSeriesChart', () => {
@@ -128,4 +124,63 @@ describe('TimeSeriesChart', () => {
     renderChart({ loading: true });
     expect(screen.getByLabelText('Loading chart.')).toBeTruthy();
   });
+
+  // CHART-3 regression: visibleKeys must not be captured only at first mount.
+  // Reproduces the live bug — host mounts with empty data, fetches
+  // asynchronously, then rerenders with real data. Before the fix this stayed
+  // on ChartFrame's empty state forever even with real series present.
+  it('CHART-3: renders the chart once data arrives after an empty-data mount', () => {
+    const { rerenderWith } = renderChart({ data: { xLabels: [], series: [] } });
+    expect(screen.getByText('No data available.')).toBeTruthy();
+    expect(screen.queryByTestId('mui-bar-chart')).toBeNull();
+
+    rerenderWith({ data: SAMPLE_DATA });
+
+    expect(screen.queryByText('No data available.')).toBeNull();
+    const props = chartSpy.mock.calls.at(-1)[0];
+    expect(props.series).toHaveLength(2);
+  });
+
+  it('CHART-3: preserves a manual toggle-off across a data update that keeps the same key', () => {
+    const { rerenderWith } = renderChart({ data: SAMPLE_DATA });
+
+    fireEvent.click(screen.getByRole('checkbox', { name: 'Users' }));
+    let props = chartSpy.mock.calls.at(-1)[0];
+    expect(props.series.map((series) => series.label)).toEqual(['Presence hours']);
+
+    rerenderWith({
+      data: {
+        xLabels: ['Mon', 'Tue', 'Wed', 'Thu'],
+        series: [
+          { key: 'users', label: 'Users', data: [1, 2, 3, 4] },
+          { key: 'presence', label: 'Presence hours', data: [4, 5, 6, 7] },
+        ],
+      },
+    });
+
+    props = chartSpy.mock.calls.at(-1)[0];
+    expect(props.series.map((series) => series.label)).toEqual(['Presence hours']);
+  });
+
+  it('CHART-3: a series key appearing later defaults to visible while an earlier toggle-off survives', () => {
+    const { rerenderWith } = renderChart({
+      data: { xLabels: ['Mon'], series: [{ key: 'users', label: 'Users', data: [1] }] },
+    });
+
+    fireEvent.click(screen.getByRole('checkbox', { name: 'Users' }));
+    expect(screen.getByText('No data available.')).toBeTruthy();
+
+    rerenderWith({
+      data: {
+        xLabels: ['Mon'],
+        series: [
+          { key: 'users', label: 'Users', data: [1] },
+          { key: 'presence', label: 'Presence hours', data: [2] },
+        ],
+      },
+    });
+
+    const props = chartSpy.mock.calls.at(-1)[0];
+    expect(props.series.map((series) => series.label)).toEqual(['Presence hours']);
+  });
 });

package/tests/authErrorCodeRendering.test.jsx

@@ -0,0 +1,77 @@
+// @vitest-environment jsdom
+import React from 'react';
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { I18nextProvider } from 'react-i18next';
+import i18next from 'i18next';
+
+const authApi = vi.hoisted(() => ({
+  changePassword: vi.fn(),
+}));
+
+vi.mock('../src/auth/authApi', () => authApi);
+vi.mock('../src/utils/authService', () => ({ startSocialLogin: vi.fn() }));
+
+import { authTranslations } from '../src/i18n/authTranslations';
+import { AuthContext } from '../src/auth/AuthContext';
+import { SecurityComponent } from '../src/components/SecurityComponent';
+
+const translations = Object.fromEntries(
+  Object.entries(authTranslations).map(([key, value]) => [key, value.en]),
+);
+
+const i18n = i18next.createInstance();
+i18n.init({
+  lng: 'en',
+  fallbackLng: 'en',
+  resources: { en: { translation: translations } },
+  keySeparator: false,
+  nsSeparator: false,
+  interpolation: { escapeValue: false },
+});
+
+function renderSecurity() {
+  return render(
+    <I18nextProvider i18n={i18n}>
+      <AuthContext.Provider value={{ authMethods: { password_change: true } }}>
+        <SecurityComponent />
+      </AuthContext.Provider>
+    </I18nextProvider>,
+  );
+}
+
+function submitPasswordChange() {
+  fireEvent.change(screen.getByLabelText(/Current password/), { target: { value: 'currentpw' } });
+  fireEvent.change(screen.getByLabelText(/New password/), { target: { value: 'a-fine-new-password' } });
+  fireEvent.click(screen.getByRole('button', { name: 'Change password' }));
+}
+
+afterEach(() => {
+  cleanup();
+  authApi.changePassword.mockReset();
+});
+
+describe('SecurityComponent — backend auth error code rendering', () => {
+  it('shows translated human text, not the raw code, for a mapped error', async () => {
+    authApi.changePassword.mockRejectedValue({ code: 'enter_current_password' });
+    renderSecurity();
+
+    submitPasswordChange();
+
+    await waitFor(() => {
+      expect(screen.getByText('The current password is incorrect.')).toBeTruthy();
+    });
+    expect(screen.queryByText('enter_current_password')).toBeNull();
+  });
+
+  it('falls back to the generic failure message when the backend sends no code at all', async () => {
+    authApi.changePassword.mockRejectedValue(new Error('network failure'));
+    renderSecurity();
+
+    submitPasswordChange();
+
+    await waitFor(() => {
+      expect(screen.getByText('The password could not be changed.')).toBeTruthy();
+    });
+  });
+});

package/tests/authTranslations.test.js

@@ -0,0 +1,52 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest';
+import { authTranslations } from '../src/i18n/authTranslations';
+
+const REQUIRED_LOCALES = ['de', 'fr', 'en'];
+
+const AUTH1_KEYS = [
+  'Auth.PASSWORD_RULES_HINT',
+  'Auth.PASSWORD_TOO_SHORT_LOCAL',
+  'Auth.PASSWORD_NUMERIC_LOCAL',
+];
+
+// Raw backend error codes (allauth-headless + Django password validators), keyed
+// verbatim so the existing `t(err.code)` call sites resolve as a drop-in. See AUTH-2.
+const AUTH2_CODE_KEYS = [
+  'email_password_mismatch',
+  'username_password_mismatch',
+  'phone_password_mismatch',
+  'too_many_login_attempts',
+  'invalid_login',
+  'account_inactive',
+  'enter_current_password',
+  'password_too_short',
+  'password_too_common',
+  'password_entirely_numeric',
+  'password_too_similar',
+  'incorrect_code',
+];
+
+describe('authTranslations — AUTH-1 password-rules keys', () => {
+  it.each(AUTH1_KEYS)('%s has de/fr/en entries', (key) => {
+    expect(authTranslations[key]).toBeDefined();
+    for (const locale of REQUIRED_LOCALES) {
+      expect(authTranslations[key][locale]).toBeTruthy();
+    }
+  });
+});
+
+describe('authTranslations — AUTH-2 raw backend error codes', () => {
+  it.each(AUTH2_CODE_KEYS)('%s has de/fr/en entries', (code) => {
+    expect(authTranslations[code]).toBeDefined();
+    for (const locale of REQUIRED_LOCALES) {
+      expect(authTranslations[code][locale]).toBeTruthy();
+    }
+  });
+
+  it('does not shadow the existing generic Auth.*_FAILED fallbacks', () => {
+    expect(authTranslations['Auth.PASSWORD_CHANGE_FAILED']).toBeDefined();
+    expect(authTranslations['Auth.LOGIN_FAILED']).toBeDefined();
+    expect(authTranslations['Auth.MFA_AUTHENTICATE_FAILED']).toBeDefined();
+  });
+});

package/work-orders/AUTH-1.md

@@ -0,0 +1,74 @@
+# WORK ORDER AUTH-1 — Password forms: state the rules (proactive helperText + inline validator)
+
+Tier 2 (touches `ui-core-micha` = shared-core). ucm-only, **zero per-app work** (consumers get it
+on their next ucm pin-bump). Origin: Spesix field report 2026-08-06 — a first-time admin setting a
+password from an invitation link could not tell what the password had to satisfy; the only way to
+learn the rules was to submit and read the rejection.
+
+## A. Envelope (authoritative WHAT / WHY)
+
+### Goal
+Tell the user the password rules **before** they submit, and give **instant frontend feedback** on
+the two most common failures — so the invitation/first-contact screen no longer rejects people
+without ever saying what it wants.
+
+### Scope — exactly the two forms that take a NEW password
+- `src/components/PasswordSetForm.jsx` (invitation set + reset-confirm).
+- `src/components/PasswordChangeForm.jsx`.
+- **NOT** `PasswordResetRequestForm.jsx` — verified it takes **email only** (`type="email"`,
+  `onSubmit(email)`), no password field. The Spesix report listed it by mistake.
+
+### Deliverable 1 — proactive helperText (the rules, stated)
+- Render `helperText` on the **new-password** `TextField` in both forms, default =
+  `t('Auth.PASSWORD_RULES_HINT')`.
+- Add `Auth.PASSWORD_RULES_HINT` to `src/i18n/authTranslations.ts` in **de/fr/en**, stating the
+  baseline the template ships with. The baseline is authoritative from dcm
+  `settings_base.py:493-498` (the 4 Django defaults): **min 8 chars · not entirely numeric · not a
+  common password · not too similar to personal info.** Suggested de: „Mindestens 8 Zeichen, nicht
+  nur Zahlen, kein gängiges Passwort." (keep it concise; the similarity rule is niche — translator
+  finalises).
+- Add an **optional prop** `passwordRulesHint` (string) to both forms — overrides the default so an
+  app that configures custom validators can pass matching text. This is the "Better" variant: cheap
+  effort, removes the only real objection (divergence from a customised backend).
+
+### Deliverable 2 — inline validator (signal before the backend rejects)
+Before calling `onSubmit(...)`, validate the two rules that are cheap and faithful to replicate,
+reusing the existing local-error mechanism (`localErrorKey` — the forms already do this for
+empty/mismatch):
+- **min length 8** → `Auth.PASSWORD_TOO_SHORT_LOCAL`,
+- **not entirely numeric** → `Auth.PASSWORD_NUMERIC_LOCAL`.
+Add both keys (de/fr/en). **Deliberately NOT** replicating CommonPassword (needs the ~20k list in
+the browser) or UserAttributeSimilarity (needs user attributes the set-from-invite form doesn't
+have) — those stay backend-enforced; the helperText already warns about them, and AUTH-2 will
+translate their backend rejection. This is a **best-effort UX layer, not a security boundary** —
+the backend stays authoritative (frontend permissive, backend decides).
+
+### Non-goals
+- Don't change the backend or the validators. Don't touch `PasswordResetRequestForm`. Don't touch
+  the `onSubmit` contract or add API-error rendering (that's the deferred reactive error-prop, out
+  of scope). No new screen → **no prototype** (trivial addition per `frontend-design`).
+
+### Tier / rollout
+Tier 2 (shared-core). ucm has **no staging** → publish-from-main: land on `main` → **minor version
+bump** (2.26.4 → 2.27.0) → consumers adopt on their own pin-bump. **Spesix is pinned at 2.5.0**
+(far behind) — it won't receive this until it does a separate, larger ucm pin-bump; that's an
+app-side decision, not part of this WO.
+
+### Required tests
+ucm component tests: helperText renders on both forms (and the `passwordRulesHint` prop overrides);
+the inline validator blocks submit + shows the right message for a <8-char and an all-numeric
+password; de/fr/en keys present for all 3 new strings.
+
+## B. Implementation map (seed)
+- `src/components/PasswordSetForm.jsx` (new-password `TextField` ~L48) + `PasswordChangeForm.jsx` —
+  add `helperText` + the pre-`onSubmit` length/numeric check via `localErrorKey`; add the
+  `passwordRulesHint` prop.
+- `src/i18n/authTranslations.ts` — 3 new keys × de/fr/en: `PASSWORD_RULES_HINT`,
+  `PASSWORD_TOO_SHORT_LOCAL`, `PASSWORD_NUMERIC_LOCAL`.
+- `package.json` — minor bump at finalize (Orchestrator, on green).
+
+**Review:** Tier 2 → independent `reviewer` + **`ui_reviewer`** (frontend diff, i18n coverage).
+**Directive:** implementer leaves the diff; Orchestrator reviews + bumps the version + commits on
+green. Codex out until 2026-08-06 → direct Claude.
+
+**Companion:** AUTH-2 (translate the backend auth error codes — the *reactive* half, broader).

package/work-orders/AUTH-2.md

@@ -0,0 +1,74 @@
+# WORK ORDER AUTH-2 — Translate backend auth error codes (stop leaking raw codes to users)
+
+Tier 2 (touches `ui-core-micha` = shared-core). ucm-only, **zero per-app work** for the core (the
+components already call `t(err.code)` — they just lack the translations). Found alongside the
+AUTH-1 password report: ucm surfaces raw backend error **codes**, not human text.
+
+## A. Envelope (authoritative WHAT / WHY)
+
+### Problem (verified)
+`src/auth/apiClient.jsx:107-124` extracts `err.code` (a machine code) from the backend/allauth
+response. Components then render it as an i18n key: `setErrorKey(err.code || 'Auth.X_FAILED')` →
+`t(errorKey)` (e.g. `SecurityComponent.jsx:60/71`, `ProfileComponent.jsx:143`,
+`MfaLoginComponent.jsx:53`), or `t(err?.code || 'Auth.X_FAILED', 'fallback')`. **The i18n
+catalogue has no entries for these codes** (grep for `email_password_mismatch` / `password_too_*`
+= empty), so i18next returns the key unchanged and the user sees the literal
+**`email_password_mismatch`** (or a generic fallback that hides the specific reason). This affects
+**all** rendering auth screens — login, change-password, MFA, profile — not just passwords.
+
+### Goal
+Render translated, human text for the known backend auth error codes, so the specific reason
+(including the password rules AUTH-1's frontend validator can't replicate — common-password,
+similarity) shows wherever a ucm component already renders an auth error. Because the components
+already `t(err.code)`, this is achieved by **adding the translations** — no component change, no
+app change.
+
+### Deliverable
+1. **Enumerate the backend auth error codes** actually emitted — from allauth-headless + Django
+   password-validator codes, confirmed against real responses (don't guess the full set). Known
+   starters: `email_password_mismatch`, `password_too_short`, `password_too_common`,
+   `password_entirely_numeric` (verify exact spelling), `password_too_similar`, and the current-
+   password / incorrect-password codes surfaced by the change-password flow.
+2. Add i18n entries for each, **de/fr/en**, in `src/i18n/authTranslations.ts`, **keyed by the raw
+   code string** (so the existing `t(err.code)` resolves as a drop-in — no component edit).
+3. Keep the generic `Auth.X_FAILED` fallback for unknown/unmapped codes (no regression).
+
+### Design note — keying (decision to confirm in planning)
+Raw-code keys (`"password_too_short": {...}`) are the **drop-in** fix matching the existing
+`t(err.code)` calls — pure ucm, no backend change. Cleaner but two-repo alternative: have dcm's
+exception handler set a namespaced `i18nKey` per error (apiClient already reads `data.i18nKey`,
+`apiClient.jsx:107`) → ucm keys become `Auth.ERROR.*`. Prefer the drop-in unless the operator wants
+the namespaced contract.
+
+### Scope boundary (honest)
+This fixes screens that **render** the error (login, change-password via `SecurityComponent`, MFA,
+profile). It does **NOT** reach the invitation **`PasswordSetForm`** — that form **delegates**
+`onSubmit` and renders no API error at all; its proactive coverage is AUTH-1 (helperText +
+validator), and its full reactive display would need the deferred per-app error-prop.
+
+### Non-goals
+No component/contract change (translations only, unless the namespaced-`i18nKey` option is chosen →
+then a small dcm touch). No new error surfaces. Don't remove the generic fallbacks.
+
+### Tier / rollout
+Tier 2 (shared-core). Publish-from-main → minor bump → consumers adopt on pin-bump. Zero per-app
+for the core.
+
+### Required tests
+`t(<code>)` resolves to translated text for each mapped code (de/fr/en); an unmapped code still
+falls back to the generic `Auth.*_FAILED`; a representative render path (e.g. `SecurityComponent`
+change-password error) shows human text, not the raw code.
+
+## B. Implementation map (seed)
+- `src/i18n/authTranslations.ts` — add the enumerated code→text entries (de/fr/en).
+- (verification only) `src/auth/apiClient.jsx:107-124` + the `setErrorKey(err.code…)` /
+  `t(err.code…)` call sites — confirm they resolve against the new entries; no edit expected.
+- `package.json` — minor bump at finalize.
+- (optional, if namespaced-`i18nKey` chosen) `django-core-micha` auth exception handler — set
+  `i18nKey` per error.
+
+**Review:** Tier 2 → `reviewer` + **`ui_reviewer`** (i18n/translation coverage — the whole point).
+**Directive:** implementer leaves the diff; Orchestrator reviews + bumps version + commits on
+green. Codex out until 2026-08-06 → direct Claude.
+
+**Companion:** AUTH-1 (the proactive helperText + inline validator — the other half).

package/work-orders/CHART-3.md

@@ -0,0 +1,163 @@
+# WORK ORDER CHART-3 (ui-core-micha) — fix TimeSeriesChart rendering nothing on async data load
+
+**EXECUTION DIRECTIVE.** If you are the implementer reading this as your own spec, this section is not
+addressed to you — it tells the Orchestrator how to invoke you; you ARE that invocation, do not shell
+out to `codex exec`. Orchestrator: implement through `codex exec` in the background, invoked **directly
+via Bash** (never the `debugger`/`*_coder` Agent wrappers) with **both** flags `--skip-git-repo-check`
+and `--dangerously-bypass-approvals-and-sandbox`, prompt passed as a positional argument from this
+file. Fall back to direct Claude implementation only on Codex quota / rate-limit / non-zero exit.
+
+Bug-fix WO on the landed CHART-2. Found live in jg-ferien's "Aktivität" screen (ACT-3 consumer): the
+toolbar (range picker + series checkboxes) renders correctly, but the chart body never appears —
+`ChartFrame`'s empty-state `Alert` shows permanently, even once real data has loaded.
+
+## TIER
+Tier 2 — shared-core UI consumed by every app that adopts `TimeSeriesChart`.
+Independent `reviewer` + `ui_reviewer` mandatory.
+
+## WHY
+
+`TimeSeriesChart` initializes `visibleKeys` via a **lazy `useState` initializer** that reads
+`seriesConfig` (derived from the `data` prop) only once, at first mount:
+
+```js
+const [visibleKeys, setVisibleKeys] = useState(
+  () => new Set(seriesConfig.map((series) => series.key)),
+);
+```
+
+jg-ferien's `ActivitySection.jsx` mounts `TimeSeriesChart` with `data = { xLabels: [], series: [] }`
+(its own initial `useState`), then fetches asynchronously in a `useEffect` and updates `data` only
+once the API call resolves — the standard "mount empty, fill later" pattern. Because the lazy
+initializer never re-runs on prop updates, `visibleKeys` stays a permanently empty `Set` even after
+real series arrive. Downstream:
+
+```js
+const visibleSeries = seriesConfig.filter((series) => visibleKeys.has(series.key)); // always []
+const isDataEmpty = seriesConfig.length === 0 || visibleSeries.length === 0;        // always true
+```
+
+`isDataEmpty` is permanently `true`, so `ChartFrame` renders its empty-state `Alert` forever, no
+matter how much data loads. The toolbar renders fine because the range picker and the series
+checkboxes are driven directly off the live `seriesConfig`, not off `visibleKeys` — only the chart
+body is gated on the stale set. This reproduces on every host that fetches asynchronously after
+mount (the overwhelmingly common case), not just jg-ferien.
+
+## SCOPE
+
+**Fix `visibleKeys` to track newly-appeared series without discarding a user's manual toggle.**
+
+Required behaviour:
+1. When `data`/`seriesConfig` changes and introduces a series key not seen before, that key must
+   become visible by default (matches current first-mount behaviour, just not mount-only).
+2. A series key the user has manually toggled off must **stay off** across a range change that
+   still includes that key (e.g. don't reset all toggles to "all visible" on every `data` update —
+   that would silently undo the user's own toggle, a second bug of the opposite kind).
+3. A key that disappears from `seriesConfig` (e.g. a range change that drops a series) and later
+   reappears is treated as new for step 1 (simplest correct behaviour; do not attempt to remember
+   toggle state for absent keys unless it falls out naturally from the fix).
+
+This is a "seen this key before, default it visible; otherwise respect the user's own toggle" sync,
+not a full rewrite of the toggle model — `toggleSeries`, the checkbox rendering, and the empty-state
+logic in SCOPE stay as they are; only the initialization/sync of `visibleKeys` changes.
+
+## NON-GOALS / DO NOT TOUCH
+- Do not change `ChartFrame`, `BarChart`, `LineChart`, or the palette.
+- Do not change the range-picker or the range-to-granularity mapping (`RANGE_OPTIONS`).
+- Do not add an `onSeriesToggle` callback or any other new prop/API surface — this is a bug fix
+  within the existing component contract, not a scope extension.
+- Do not touch `chartsTranslations.ts` — this WO is unrelated to i18n (a separate, already-diagnosed
+  issue in a different repo is being fixed independently).
+
+## RISKS
+- The fix must not reintroduce the mount-time bug in a different form (e.g. resetting on every
+  render, or resetting on every `data` change including in-place mutations of the same series set —
+  that would silently discard the user's manual toggles on every range change, which is the
+  behaviour test 2 below exists to catch).
+- Every host that has adopted `TimeSeriesChart` since CHART-2 shipped is affected by this fix
+  (currently only jg-ferien via ACT-3); this changes rendering behaviour for all of them, in the
+  correct direction (chart now actually renders).
+
+## REQUIRED TESTS TO WRITE
+Narrow and behavioural, extending `tests/TimeSeriesChart.test.jsx`. Do NOT run the full suite.
+
+1. **Regression test for this exact bug**: mount `TimeSeriesChart` with empty `data`
+   (`{ xLabels: [], series: [] }`), then rerender with populated `data` (real `xLabels`/`series`) —
+   assert the chart body renders (not `ChartFrame`'s empty state), i.e. `isEmpty` becomes `false`
+   and `BarChart` receives the new series. This must fail against the current code and pass after
+   the fix — it is the non-vacuity check for this WO.
+2. **Toggle persistence across a data update**: toggle one series off, then rerender with updated
+   `data` that still contains that series key (e.g. a value change, same keys) — assert that series
+   is still filtered out (the user's manual toggle was not reset by the data update).
+3. **New series key appearing later defaults to visible**: mount with one series, rerender with a
+   second series key added — assert the new key is visible by default while any prior manual toggle
+   on the first key is preserved.
+
+**Non-vacuity:** test 1 must fail against the current `visibleKeys` lazy-initializer code (verify
+this before considering the fix complete) — it is reproducing the exact live bug from jg-ferien.
+
+## CONTEXT PACKAGE — verified current state (Orchestrator, Implementation map)
+
+Work from this package; do not explore broadly from scratch — open only the named files to verify.
+
+**File to change: `src/components/charts/TimeSeriesChart.jsx`.**
+
+Current state (verified, full relevant slice):
+```js
+const seriesConfig = data?.series || [];
+
+const [range, setRange] = useState(defaultRange);
+// Series identity (keys) is assumed stable for a given chart instance — the
+// toggle set is initialized once from the first data the chart receives.
+const [visibleKeys, setVisibleKeys] = useState(
+  () => new Set(seriesConfig.map((series) => series.key)),
+);
+```
+(`TimeSeriesChart.jsx:52-59`) — the comment above `visibleKeys` states the now-disproven assumption
+("series identity is stable for a given chart instance") that this WO corrects; update or remove it
+to match the new behaviour.
+
+`toggleSeries` (`:68-75`), `visibleSeries`/`visiblePalette`/`isDataEmpty` derivation (`:77-84`), and
+the checkbox rendering (`:103-123`) are all downstream of `visibleKeys` and should not need changes
+— only how `visibleKeys` is initialized/kept in sync with `seriesConfig` changes.
+
+**Suggested shape (not prescriptive — implement whatever satisfies SCOPE correctly):** replace the
+lazy `useState` with a `useEffect` keyed on the set of series keys in `seriesConfig`, that adds any
+newly-seen key to `visibleKeys` (defaulting it visible) without touching keys already present in the
+set — e.g. track previously-seen keys in a ref to detect "new" vs "toggled off", since a key
+present in both old and new `seriesConfig` but absent from `visibleKeys` must stay absent (it was a
+deliberate user toggle-off, not a fresh key). Keep `visibleKeys`'s existing `Set`-of-keys shape,
+`toggleSeries`'s update pattern, and the checkbox/empty-state code untouched.
+
+**Test file to extend: `tests/TimeSeriesChart.test.jsx`** — matches `tests/ChartFrame.test.jsx`/
+`tests/BarChart.test.jsx` conventions: `// @vitest-environment jsdom` header, vitest +
+`@testing-library/react`, `afterEach(cleanup)`, a minimal per-file `i18next.createInstance()` +
+`I18nextProvider`, wrapped in `ThemeProvider theme={createTheme()}`. Use `rerender()` from
+`@testing-library/react`'s `render()` return value to simulate the host updating `data` after mount
+(this is the exact scenario CHART-2's own tests never covered — they only mounted once with
+synchronous populated data).
+
+## TARGET REPO
+`C:\Users\biglmi\Documents\webapps\ui-core-micha`. Branch `main`. Publish per the repo's release
+flow (patch bump — bug fix, no interface change); consumer pin bumps are separate, out of scope.
+
+## TEST SCOPE FOR THE GATE (orchestrator)
+`tests/TimeSeriesChart.test.jsx` only. Not the full suite.
+
+## MINI-HANDOVER (pastable)
+
+> Repo: `C:\Users\biglmi\Documents\webapps\ui-core-micha` (branch `main`).
+> Work order: `work-orders/CHART-3.md` — read it fully, then follow the `orchestrate-codex` skill.
+>
+> Bug fix on CHART-2's `TimeSeriesChart`: `visibleKeys` is initialized once via a lazy `useState`
+> from whatever `data` is at first mount, so any host that fetches asynchronously after mount (the
+> normal case) ends up with a permanently-empty `visibleKeys` and the chart body never renders —
+> `ChartFrame`'s empty state shows forever even once real data arrives. Fix the sync so newly-seen
+> series keys default to visible while a user's manual toggle-off on an already-seen key survives a
+> data update. Regression test 1 is the non-vacuity check — verify it fails against current code
+> first.
+
+## PROGRESS CONTRACT
+Emit `PLAN: <steps>` up front, then a single-line `PROGRESS: [<n>/<total>] <action>` before every
+relevant action and `PROGRESS: [<n>/<total>] done` on completion, spaced so no gap exceeds ~2 min,
+stdout unbuffered, and exactly one final `RESULT: DONE|BLOCKED <reason>`.