@micha.bigler/ui-core-micha 3.0.1 → 3.1.1

package/tests/chart-api-census.test.js

@@ -0,0 +1,366 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { findChartApiUsage, runCensus, TARGET_PROPS } from '../scripts/chart-api-census.mjs';
+
+const IMPORT_LINE = "import { BarChart, LineChart, ScatterChart, TimeSeriesChart, ChartFrame } from '@micha.bigler/ui-core-micha';\n";
+
+function propsFound(entry) {
+  return TARGET_PROPS.filter((p) => entry.props[p]);
+}
+
+// UCM-CHART-14: this WO exists because a grep could not see JSX structure. First-round fixtures
+// (below) cover what broke the ad-hoc scans behind this series' wrong consumer counts (see
+// work-orders/UCM-CHART-14.md's own table of six). A second, independent review round (both
+// `reviewer` and `ui_reviewer`) found the FIRST version of this file could itself produce a WRONG,
+// non-UNPARSED answer -- worse than honest UNPARSED -- and that two of these very fixtures did not
+// actually exercise the trap their name claimed. Both are fixed; the second-round traps are in the
+// next describe block. Each fixture asserts the EXACT props found, not just "found something".
+describe('findChartApiUsage -- traps that broke ad-hoc grep scans (UCM-CHART-14)', () => {
+  it('trap 1: an arrow function inside a prop value does not truncate the tag at its own "=>"', () => {
+    const source = `${IMPORT_LINE}
+      function Panel() {
+        return (
+          <ScatterChart
+            getPointStyle={(point) => ({ hollow: point.isStatusQuo, color: point.isStatusQuo ? undefined : '#123' })}
+            aspect={1.8}
+          />
+        );
+      }
+    `;
+    const [entry] = findChartApiUsage(source);
+    expect(entry.component).toBe('ScatterChart');
+    expect(entry.unparsed).toBe(false);
+    expect(propsFound(entry)).toEqual(['aspect']);
+  });
+
+  // Second-round finding: the original fixture put the comment BETWEEN two already-closed tags
+  // (JSX children), never exercising an open tag's own attribute-scan while a comment is active.
+  // This version puts both a line comment AND a block comment, each carrying an apostrophe, INSIDE
+  // the attribute list itself -- the position that actually needs string/comment tracking to be
+  // correct, since a naive apostrophe could be misread as a string-open.
+  it('trap 2: an apostrophe inside a comment WITHIN the attribute list does not desynchronise string tracking', () => {
+    const source = `${IMPORT_LINE}
+      function Panel() {
+        return (
+          <ChartFrame
+            // don't confuse this line comment's apostrophe with a string open
+            minHeight={300}
+            /* it's a block comment here too */
+            title="Body weight"
+          />
+        );
+      }
+    `;
+    const [entry] = findChartApiUsage(source);
+    expect(entry.component).toBe('ChartFrame');
+    expect(propsFound(entry)).toEqual(['minHeight']);
+  });
+
+  // Second-round finding: the original fixture's nested keys (`angle`/`left`/`top`) were not even
+  // in TARGET_PROPS, so a parser that falsely collected ANY nested key would still have passed.
+  // This version nests `aspect` and `height` themselves as object keys several levels deep -- the
+  // exact prop names the census is looking for -- so a depth-tracking bug that leaks nested keys
+  // up as top-level attributes is now something this test can actually catch.
+  it('trap 3: nested braces are tracked by depth -- a nested key with a TARGET PROP NAME is never mistaken for a top-level attribute', () => {
+    const source = `${IMPORT_LINE}
+      function Panel() {
+        return (
+          <BarChart
+            xAxis={[{ scaleType: 'band', tickLabelStyle: { aspect: 'not-real', height: 999 } }]}
+            margin={{ top: 8 }}
+          />
+        );
+      }
+    `;
+    const [entry] = findChartApiUsage(source);
+    // `margin` IS a top-level attribute (found); the nested `aspect`/`height` keys -- despite being
+    // real TARGET_PROPS names -- must never surface as attributes of the tag itself.
+    expect(propsFound(entry)).toEqual(['margin']);
+  });
+
+  it('trap 4: a prop many lines below the component name is still attributed to the same tag', () => {
+    const source = `${IMPORT_LINE}
+      function Panel() {
+        return (
+          <ChartFrame
+            title="Body weight"
+            subtitle="Last 12 months"
+            variant="outlined"
+            titleVariant="h6"
+            exportOptions
+            meta="Updated daily"
+            aspect={1.8}
+          >
+            {children}
+          </ChartFrame>
+        );
+      }
+    `;
+    const [entry] = findChartApiUsage(source);
+    expect(entry.component).toBe('ChartFrame');
+    expect(propsFound(entry)).toEqual(['aspect']);
+  });
+});
+
+// Second review round -- the four NEW traps that surfaced against the first version's three-pass
+// design (a raw regex tag-open search with no string/comment context, and no regex-literal
+// tracking at all). All four are wrong-answer risks, not merely UNPARSED risks -- exactly the
+// class of bug this WO's own F1 finding is about (a false measurement nobody flagged).
+describe('findChartApiUsage -- second-round traps: string/comment-blind matching and regex literals', () => {
+  it('does not count JSX-looking text inside a STRING literal as a real element', () => {
+    const source = `${IMPORT_LINE}
+      const example = '<BarChart aspect />';
+      function Panel() {
+        return <LineChart margin={{ top: 1 }} />;
+      }
+    `;
+    const entries = findChartApiUsage(source);
+    expect(entries).toHaveLength(1);
+    expect(entries[0].component).toBe('LineChart');
+  });
+
+  it('does not count JSX-looking text inside a LINE comment as a real element', () => {
+    const source = `${IMPORT_LINE}
+      // <BarChart aspect />
+      function Panel() {
+        return <LineChart margin={{ top: 1 }} />;
+      }
+    `;
+    const entries = findChartApiUsage(source);
+    expect(entries).toHaveLength(1);
+    expect(entries[0].component).toBe('LineChart');
+  });
+
+  it('does not count JSX-looking text inside a BLOCK comment as a real element', () => {
+    const source = `${IMPORT_LINE}
+      /* an old example: <BarChart aspect /> -- removed */
+      function Panel() {
+        return <LineChart margin={{ top: 1 }} />;
+      }
+    `;
+    const entries = findChartApiUsage(source);
+    expect(entries).toHaveLength(1);
+    expect(entries[0].component).toBe('LineChart');
+  });
+
+  // The concrete case found in review: a regex literal's `}`/`>` characters must not be read as
+  // real brace/tag-close tokens, or a later real prop on the same tag gets silently dropped.
+  it('a regex literal in a prop value does not corrupt brace depth or close the tag early', () => {
+    const source = `${IMPORT_LINE}
+      function Panel() {
+        return (
+          <BarChart
+            data={/[}>]/}
+            aspect={1.8}
+          />
+        );
+      }
+    `;
+    const [entry] = findChartApiUsage(source);
+    expect(entry.unparsed).toBe(false);
+    expect(propsFound(entry)).toEqual(['aspect']);
+  });
+
+  // A component nested INSIDE another target component's own prop expression -- the outer tag's
+  // scan must not swallow the inner one, and each must report its OWN props independently.
+  it('finds a target component nested inside another target component\'s prop expression', () => {
+    const source = `${IMPORT_LINE}
+      function Panel() {
+        return (
+          <ChartFrame minHeight={300} content={<BarChart aspect={1.8} />} />
+        );
+      }
+    `;
+    const entries = findChartApiUsage(source);
+    const frame = entries.find((e) => e.component === 'ChartFrame');
+    const bar = entries.find((e) => e.component === 'BarChart');
+    expect(entries).toHaveLength(2);
+    expect(propsFound(frame)).toEqual(['minHeight']);
+    expect(propsFound(bar)).toEqual(['aspect']);
+  });
+
+  // Regression test for a bug this WO's OWN verification run found (not review, an actual real-
+  // world run against hram): the regex-literal heuristic originally included `<`/`>` in the set of
+  // characters that can precede a regex-starting `/`. Every JSX CLOSING tag (`</Something>`) has a
+  // `/` immediately after a `<` -- so `</ChartFrame>` itself was misread as opening a regex
+  // literal, silently corrupting brace depth for the rest of the file and turning every multi-line
+  // `<ChartFrame>...</ChartFrame>` usage in the estate into a false UNPARSED. This fixture is
+  // shaped like the real file that exposed it: a target component with real JSX children,
+  // including an interleaved NON-target component's own closing tag before the target's own.
+  it('a target component with real JSX children (own closing tag, and a sibling non-target closing tag) is not corrupted by the </Tag> regex-heuristic bug', () => {
+    const source = `${IMPORT_LINE}
+      function Panel() {
+        return (
+          <ChartFrame minHeight={320} toolbar={<Toolbar><Button>Go</Button></Toolbar>}>
+            <ScatterChart aspect={1.8}>
+              <ScatterReferenceLine from={{ x: 0, y: 0 }} to={{ x: 1, y: 1 }} />
+            </ScatterChart>
+          </ChartFrame>
+        );
+      }
+    `;
+    const entries = findChartApiUsage(source);
+    const frame = entries.find((e) => e.component === 'ChartFrame');
+    const scatter = entries.find((e) => e.component === 'ScatterChart');
+    expect(frame).toBeDefined();
+    expect(frame.unparsed).toBe(false);
+    expect(propsFound(frame)).toEqual(['minHeight']);
+    expect(scatter).toBeDefined();
+    expect(scatter.unparsed).toBe(false);
+    expect(propsFound(scatter)).toEqual(['aspect']);
+  });
+});
+
+describe('findChartApiUsage -- import resolution and non-traps', () => {
+  it('only counts components actually imported from @micha.bigler/ui-core-micha -- a same-named local component is not a consumer', () => {
+    const source = `
+      import { BarChart } from './my-local-chart';
+      function Panel() {
+        return <BarChart aspect={1.8} />;
+      }
+    `;
+    expect(findChartApiUsage(source)).toEqual([]);
+  });
+
+  it('resolves an aliased import back to its canonical export name', () => {
+    const source = `
+      import { BarChart as Bar } from '@micha.bigler/ui-core-micha';
+      function Panel() {
+        return <Bar aspect={1.8} />;
+      }
+    `;
+    const [entry] = findChartApiUsage(source);
+    expect(entry.component).toBe('BarChart');
+    expect(propsFound(entry)).toEqual(['aspect']);
+  });
+
+  it('reports no elements in a file with no matching import at all (the fast path)', () => {
+    expect(findChartApiUsage('const BarChart = 1; const x = <BarChart aspect={1} />;')).toEqual([]);
+  });
+
+  it('reports a boolean-shorthand attribute (no value) the same as a valued one', () => {
+    const source = `${IMPORT_LINE}
+      const el = <ChartFrame minHeight />;
+    `;
+    const [entry] = findChartApiUsage(source);
+    expect(propsFound(entry)).toEqual(['minHeight']);
+  });
+
+  it('finds a clean element with none of the target props as an entry with an empty prop list', () => {
+    const source = `${IMPORT_LINE}
+      const el = <BarChart xAxisLabel="Month" series={[]} />;
+    `;
+    const [entry] = findChartApiUsage(source);
+    expect(entry.unparsed).toBe(false);
+    expect(propsFound(entry)).toEqual([]);
+  });
+
+  it('finds multiple distinct elements in the same file, each with its own props', () => {
+    const source = `${IMPORT_LINE}
+      const a = <BarChart aspect={1} />;
+      const b = <LineChart margin={{ top: 1 }} />;
+    `;
+    const entries = findChartApiUsage(source);
+    expect(entries).toHaveLength(2);
+    expect(entries[0].component).toBe('BarChart');
+    expect(entries[1].component).toBe('LineChart');
+  });
+});
+
+// Definition of Done: "A tag it cannot close is reported as UNPARSED, never skipped and never
+// counted as clean" -- a census that silently drops what it cannot read is the failure it exists
+// to prevent.
+describe('findChartApiUsage -- UNPARSED, never silently skipped', () => {
+  it('reports a tag that never closes as UNPARSED rather than dropping it', () => {
+    const source = `${IMPORT_LINE}
+      const el = <BarChart aspect={1.8} xAxisLabel="Month unterminated
+    `; // no closing `>` or `/>` anywhere after this point
+    const entries = findChartApiUsage(source);
+    expect(entries).toHaveLength(1);
+    expect(entries[0].unparsed).toBe(true);
+    expect(entries[0].component).toBe('BarChart');
+  });
+
+  it('keeps scanning after an UNPARSED tag and still finds a later, well-formed one', () => {
+    // An unmatched `{` (not a string) leaves brace depth permanently elevated but string tracking
+    // intact -- so a LATER tag, opening at that same (now-baseline) depth, can still close
+    // correctly relative to it. `BarChart` never returns to its own start depth and is UNPARSED;
+    // `LineChart` opens and closes entirely within the leaked depth and is found correctly.
+    const source = `${IMPORT_LINE}
+      const broken = <BarChart aspect={1.8} xAxis={{ scaleType: 'band';
+      const el2 = <LineChart margin={{ top: 1 }} />;
+    `;
+    const entries = findChartApiUsage(source);
+    const bar = entries.find((e) => e.component === 'BarChart');
+    const lineChart = entries.find((e) => e.component === 'LineChart');
+    expect(bar.unparsed).toBe(true);
+    expect(lineChart).toBeDefined();
+    expect(lineChart.unparsed).toBe(false);
+    expect(propsFound(lineChart)).toEqual(['margin']);
+  });
+
+  // An UNTERMINATED STRING is a genuinely different case from an unmatched brace: nothing can
+  // recover from it without guessing where the string was meant to end, so honestly reporting
+  // "nothing found after this point" is the correct behaviour, not a bug -- the alternative (the
+  // first version of this scanner's per-tag-independent design) would have silently RESYNCHRONISED
+  // past a real syntax error, which is exactly the kind of confident-but-wrong answer this WO's
+  // second review round exists to rule out.
+  it('an unterminated string desyncs the rest of the file -- reported as UNPARSED, not silently resynchronised', () => {
+    const source = `${IMPORT_LINE}
+      const broken = <BarChart aspect={1.8} xAxisLabel="unterminated;
+      const el2 = <LineChart margin={{ top: 1 }} />;
+    `;
+    const entries = findChartApiUsage(source);
+    expect(entries).toHaveLength(1);
+    expect(entries[0].component).toBe('BarChart');
+    expect(entries[0].unparsed).toBe(true);
+  });
+});
+
+describe('runCensus -- filesystem walking degrades gracefully (UCM-CHART-14 Risks)', () => {
+  let workspaceRoot;
+
+  afterEach(() => {
+    if (workspaceRoot) rmSync(workspaceRoot, { recursive: true, force: true });
+  });
+
+  it('reports "not present" for a sibling with no frontend/src or src, and never throws', () => {
+    workspaceRoot = mkdtempSync(join(tmpdir(), 'ucm-census-'));
+    mkdirSync(join(workspaceRoot, 'empty-repo'));
+
+    const result = runCensus(workspaceRoot);
+    const entry = result.apps.find((a) => a.app === 'empty-repo');
+    expect(entry.present).toBe(false);
+  });
+
+  it('finds a real usage under frontend/src, and reports a clean sibling with no ucm import as present with zero entries', () => {
+    workspaceRoot = mkdtempSync(join(tmpdir(), 'ucm-census-'));
+    const appSrc = join(workspaceRoot, 'sample-app', 'frontend', 'src');
+    mkdirSync(appSrc, { recursive: true });
+    writeFileSync(
+      join(appSrc, 'Panel.jsx'),
+      `${IMPORT_LINE}\nconst el = <BarChart aspect={1.8} />;\n`,
+    );
+    mkdirSync(join(workspaceRoot, 'clean-app', 'src'), { recursive: true });
+    writeFileSync(join(workspaceRoot, 'clean-app', 'src', 'index.js'), 'export const x = 1;\n');
+
+    const result = runCensus(workspaceRoot);
+    const sample = result.apps.find((a) => a.app === 'sample-app');
+    const clean = result.apps.find((a) => a.app === 'clean-app');
+    expect(sample.present).toBe(true);
+    expect(sample.entries).toHaveLength(1);
+    expect(sample.entries[0].props.aspect).toBe(true);
+    expect(clean.present).toBe(true);
+    expect(clean.entries).toHaveLength(0);
+  });
+
+  it('excludes ui-core-micha itself from the sibling walk by default', () => {
+    workspaceRoot = mkdtempSync(join(tmpdir(), 'ucm-census-'));
+    mkdirSync(join(workspaceRoot, 'ui-core-micha', 'src'), { recursive: true });
+
+    const result = runCensus(workspaceRoot);
+    expect(result.apps.find((a) => a.app === 'ui-core-micha')).toBeUndefined();
+  });
+});

package/tests/chartDefaults.test.js

@@ -292,6 +292,15 @@ describe('removed chart props throw in dev, naming their replacement (UCM-CHART-
       .toThrow(/BarChart.*minHeight.*Use size instead\./s);
   });
 
+  // UCM-CHART-13 (codex review finding): a shared helper hardcoding one WO/version string would
+  // misattribute the removal for a different call site's own, different removal.
+  it('defaults removedIn to UCM-CHART-12/v3.0.0 (the four presets\' own call sites), but a caller can override it', () => {
+    expect(() => assertRemovedChartProp('BarChart', 'minHeight', 320, 'Use size instead.'))
+      .toThrow(/UCM-CHART-12, v3\.0\.0/);
+    expect(() => assertRemovedChartProp('ChartFrame', 'aspect', 1.8, 'Use size instead.', 'UCM-CHART-13, v3.1.0'))
+      .toThrow(/UCM-CHART-13, v3\.1\.0/);
+  });
+
   it('assertRemovedChartProp stays inert in production', () => {
     const original = process.env.NODE_ENV;
     process.env.NODE_ENV = 'production';

package/work-orders/UCM-CHART-13.md

@@ -0,0 +1,122 @@
+# UCM-CHART-13 — A card has no size of its own. Remove `height` and `aspect` from `ChartFrame`.
+
+- **Repo:** `ui-core-micha`, branch `main`
+- **Tier:** 3 — shared-core API removal, **four measured consumer call sites** (see below). Breaking:
+  `4.0.0`, sequenced with `FM-CHART-1`.
+- **Status:** planned
+- **Workstream:** `CHART-*`
+- **Files:** `src/components/charts/ChartFrame.jsx` and its tests.
+
+> **Why. Twice reversed — the reasoning below is what settled it, not the earlier prop-inventory.**
+>
+> Draft 1 said remove `height` **and** `aspect`, on the grounds that both were dead code. That
+> premise was wrong: `aspect` **is** applied — `ChartFrame.jsx:136-139` sets
+> `sx={{ width: '100%', minHeight, aspectRatio: aspect, ... }}`.
+>
+> Draft 2 therefore kept `aspect`. **That was the worse error**, and the operator caught it: it
+> reintroduces through the card exactly what `UCM-CHART-12` removed from the chart.
+>
+> **The structural argument, which neither earlier draft made.** After the migration a consumer
+> looks like this:
+>
+> ```jsx
+> <ChartFrame minHeight={320} aspect="960 / 380">   // height derived from WIDTH
+>   <LineChart size="tall" />                        // height from a TOKEN
+> </ChartFrame>
+> ```
+>
+> **Two independent size sources for nested boxes that have to agree.** Before the migration they
+> were coherent — same ratio on both. Afterwards the frame tracks width and the chart tracks a token,
+> and they coincide only by accident. Whichever way they diverge is a defect this series already has
+> a name for: the frame taller than its content is dead space, the frame shorter is the
+> `UCM-CHART-9` overflow.
+>
+> **A card must have no size of its own.** Its height is its content's height, with `minHeight` as a
+> floor so an empty or loading state does not collapse. That is what `UCM-CHART-9` established — it
+> found the defect at a fixed `height`; `aspect` is the same defect derived from width instead of
+> stated directly.
+>
+> | prop | applied today | verdict |
+> |---|---|---|
+> | `minHeight` | yes (`:138`) | **stays** — the floor, and the only legitimate one |
+> | `aspect` | yes (`:139`) | **goes** — a second size source on a box that must follow its content |
+> | `height` | no — only feeds a warning | **goes** — accepted and silently ignored |
+>
+> **This one has consumer impact**, unlike draft 2's claim: four `ChartFrame`s pass `aspect` —
+> `fitness-monitor/BodyHistoryPage.jsx:328, :449` and `EnvironmentPage.jsx:250, :284`. They are
+> migrated by `FM-CHART-1`, not here.
+
+## Part A — Envelope (authoritative WHAT/WHY)
+
+### Goal
+
+`ChartFrame` has no size source of its own. Its height is its content's height, floored by
+`minHeight`. `aspect` and `height` are gone.
+
+### Definition of Done
+
+- [ ] **`aspect` removed** from the signature and from the applied `sx` (`:139`). A card that sizes
+      itself from its width can be shorter than its content (the `UCM-CHART-9` overflow) or taller
+      (dead space); both are defects this series already has names for.
+- [ ] **`height` removed** from `ChartFrame`'s signature, and `warnOnChartFrameHeightMismatch` deleted
+      with it — the warning exists only to explain a prop that should not be accepted in the first
+      place. **A prop that is accepted and silently ignored is worse than one that errors**: it lets a
+      caller believe the card was sized when it was not, which is precisely the `UCM-CHART-9`
+      regression in slow motion.
+- [ ] **`minHeight` stays, unchanged.** It is the one justified prop: a card with a loading or empty
+      state would otherwise collapse, and `UCM-CHART-9` established the floor as correct. Do not
+      touch its behaviour.
+- [ ] **Passing `height` or `aspect` to `ChartFrame` is a dev-mode error naming what to do instead**
+      — `minHeight` for a floor, or `size` on the chart *inside* the frame if the caller meant the
+      chart's height. Consistent with how `UCM-CHART-12` treats the presets' removed props.
+- [ ] **`docs/CHART-LAYOUT.md`'s "What stays unchanged" entry is made precise.** It lists the frame's
+      `minHeight`/`height`/`aspect` as retained without saying which are applied. Replace it: the frame
+      keeps **`minHeight` only**, as a floor; it has no size source of its own, and a chart's height
+      comes from its `size` token.
+
+### Non-goals
+
+- Do not change `minHeight`'s semantics, and do not give `ChartFrame` a `size` token. The frame is
+  not a chart (`UCM-CHART-9`); its height follows its content with a floor, and that is correct.
+- Do not touch the four presets. `UCM-CHART-12` settled them.
+- No consumer migration here. The four `ChartFrame`s passing `aspect` are fitness-monitor's, and
+  `FM-CHART-1` removes them — **sequence this after `FM-CHART-1`, or land both together**, or those
+  four cards hit the new error.
+
+### Risks
+
+- **`height` is free — no consumer passes it and it does nothing.** `aspect` is not: four cards
+  depend on it and lose their shape when it goes. That is intended (their height becomes their
+  content's), but it is a **visible change in fitness-monitor**, so `FM-CHART-1`'s rendered two-width
+  check is what confirms it, not this WO's unit tests.
+- **Re-run the consumer scan by reading the call sites, not by grepping.** Both earlier drafts of this
+  WO were wrong about `aspect` — once from a grep that matched nothing, once from a `head`-truncated
+  grep that cut off the line where it is applied. Open the files.
+
+### Tests to WRITE — narrow
+
+- `ChartFrame` with `minHeight`: floor applied, `UCM-CHART-9`'s existing assertions unchanged.
+- `ChartFrame` given `height` or `aspect`: dev-mode error naming the replacement, and **no
+  `aspectRatio` or `height` on the box**.
+- **A `ChartFrame` whose content is taller than `minHeight` grows to fit** — `UCM-CHART-9`'s
+  regression test, unchanged, and now the only thing that decides the card's height.
+- The `UCM-CHART-9` regression test (content taller than the floor grows the box) stays green,
+  unchanged.
+
+No full suite.
+
+---
+
+## Part B — Implementation map
+
+> **TO BE FILLED BY THE ORCHESTRATOR** on `git pull`. Must carry `ChartFrame.jsx`'s signature
+> (`:56-58`), the applied `sx` (`:138`), `warnOnChartFrameHeightMismatch` (`:27-35`), the
+> `docs/CHART-LAYOUT.md` line to correct, the absolute working directory, the progress contract, and
+> the preamble. **Do not dispatch while this placeholder stands.**
+
+---
+
+## Part C — Orchestrator-only
+
+> **TO BE FILLED BY THE ORCHESTRATOR.** Review routing, register maintenance, registry publish
+> verification, commit, and the execution directive with its self-address guard.