angular-my-report 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# @mohamed351/angular
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Banded report designer and viewer for Angular, as two standalone components.
+
+```bash
+npm install @mohamed351/angular
+```
+
+Requires Angular 19.2 or later. The styles are bundled with the components and scoped under `.myreport`, so there is no stylesheet to import and nothing leaks into your app.
+
+## Designer
+
+```ts
+import { MyReportDesignerComponent, type ReportDefinition } from '@mohamed351/angular';
+
+@Component({
+  imports: [MyReportDesignerComponent],
+  template: `<myreport-designer path="/reports/sales.report.json" [download]="false" (save)="store($event)" />`,
+  styles: `myreport-designer { height: 100vh; }`,
+})
+export class DesignerPage {
+  store(report: ReportDefinition) { /* POST it to your API */ }
+}
+```
+
+| Input | Type | Description |
+|---|---|---|
+| `path` | `string` | URL of a `.report.json` to open. |
+| `report` | `ReportDefinition \| string` | A report to open (object or JSON). Used when `path` is empty. |
+| `datasource` | `string \| array \| object` | Data to design against, replacing the report's data source. See [Data](#data). |
+| `type` | `'json' \| 'odata'` | How `datasource` is read. Default `json`. |
+| `params` | `object \| string` | Parameter values. See [Parameters](#parameters). |
+| `persistKey` | `string` | `localStorage` key to autosave to. When `path` and `report` are empty, the saved report is restored from it. |
+| `viewerUrl` | `string` | Shows a "Viewer ↗" toolbar link to this URL. |
+| `download` | `boolean` | Whether **Save** downloads a `.report.json`. Default `true`. `(save)` fires either way. |
+| `brand` | `string` | Toolbar title. Default `My Report`. |
+
+| Output | Payload |
+|---|---|
+| `save` | `ReportDefinition`, when the user clicks Save |
+| `reportChange` | `ReportDefinition`, after every edit |
+| `loaded` | `ReportDefinition`, after `path` loaded |
+| `loadError` | `string` |
+
+## Viewer
+
+```html
+<!-- the report's own data source -->
+<myreport-viewer path="/reports/sales.report.json" />
+
+<!-- JSON from your API -->
+<myreport-viewer path="/reports/sales.report.json" datasource="/api/orders" type="json" />
+
+<!-- OData: service root or full entity-set URL -->
+<myreport-viewer path="/reports/orders.report.json" datasource="https://host/odata/Orders" type="odata" />
+
+<!-- data you already have -->
+<myreport-viewer path="/reports/sales.report.json" [datasource]="orders" />
+```
+
+| Input | Type | Description |
+|---|---|---|
+| `path` | `string` | URL of the `.report.json` to show. |
+| `report` | `ReportDefinition \| string` | A report to show (object or JSON). Used when `path` is empty. |
+| `datasource` | `string \| array \| object` | The report's data. See [Data](#data). |
+| `type` | `'json' \| 'odata'` | How `datasource` is read. Default `json`. |
+| `params` | `object \| string` | Parameter values. See [Parameters](#parameters). |
+| `designerUrl` | `string` | Shows a "Designer" toolbar link to this URL. |
+| `allowOpen` | `boolean` | Shows the toolbar Open button for local `.report.json` files. Default `true`. |
+
+| Output | Payload |
+|---|---|
+| `loaded` | `ReportDefinition` |
+| `dataLoaded` | the data rows |
+| `loadError` | `string`, for a report or data load failure |
+
+The viewer has paging, zoom, find, bookmarks, thumbnails, parameters, print, and export to PDF (via the print dialog), HTML, CSV and `.report.json`.
+
+## Data
+
+`datasource` replaces the data source saved in the report. Leave it empty to use the report's own.
+
+- **URL, `type="json"`**: fetched as JSON. The report's array path (for example `data.items`) still applies. If that path is missing from the response, the array is detected automatically.
+- **URL, `type="odata"`**: an OData v2/v4 service root or entity-set URL. The report's entity set, `$select`, `$filter`, `$orderby`, `$expand` and `$top` still apply, and `nextLink` paging is followed.
+- **JSON string, array or object**: used as the data directly.
+
+Request headers (for example `Authorization`) come from the report's data source settings.
+
+## Parameters
+
+Pass values as an object (`{ Country: 'Egypt' }`), a JSON string, or a query string (`Country=Egypt&Year=2024`). They fill the report's parameters, are used as `@Country` in formulas and `{@Country}` in data source URLs, and can be changed in the viewer's parameter bar.
+
+## Also exported
+
+The report model types (`ReportDefinition`, `Band`, `ReportElement` and others), `newReport()`, `receiptReport(width)`, `loadData()` and `detectDataSource()`.
+
+## Other frameworks
+
+- React: [`@mohamed351/react`](https://www.npmjs.com/package/@mohamed351/react)
+- Any framework or plain HTML (Web Components): [`@mohamed351/elements`](https://www.npmjs.com/package/@mohamed351/elements)

package/ng-package.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "../../dist/angular",
+  "lib": { "entryFile": "src/public-api.ts" },
+  "allowedNonPeerDependencies": ["qrcode-generator"],
+  "assets": ["README.md"]
+}

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "angular-my-report",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "MyReport banded report designer and viewer for Angular: <myreport-designer> and <myreport-viewer>.",
+  "keywords": [
+    "angular",
+    "report",
+    "report-designer",
+    "report-viewer",
+    "odata",
+    "json",
+    "pdf",
+    "print"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@angular/common": ">=19.2.0 <21.0.0",
+    "@angular/core": ">=19.2.0 <21.0.0",
+    "@angular/forms": ">=19.2.0 <21.0.0"
+  },
+  "dependencies": {
+    "qrcode-generator": "^1.4.4",
+    "tslib": "^2.3.0"
+  },
+  "sideEffects": false
 }

package/src/lib/engine/barcode.ts

@@ -0,0 +1,118 @@
+import type { BarcodeSymbology } from '../model/types';
+
+export interface BarcodeResult {
+  /** One char per module: '1' = bar, '0' = space. Empty when `error` is set. */
+  modules: string;
+  /** Human-readable text printed under the bars. */
+  text: string;
+  error?: string;
+}
+
+// Code 128 symbol widths (bar, space, bar, space, bar, space) for values 0–105, then STOP (106).
+const CODE128 = [
+  '212222', '222122', '222221', '121223', '121322', '131222', '122213', '122312', '132212', '221213',
+  '221312', '231212', '112232', '122132', '122231', '113222', '123122', '123221', '223211', '221132',
+  '221231', '213212', '223112', '312131', '311222', '321122', '321221', '312212', '322112', '322211',
+  '212123', '212321', '232121', '111323', '131123', '131321', '112313', '132113', '132311', '211313',
+  '231113', '231311', '112133', '112331', '132131', '113123', '113321', '133121', '313121', '211331',
+  '231131', '213113', '213311', '213131', '311123', '311321', '331121', '312113', '312311', '332111',
+  '314111', '221411', '431111', '111224', '111422', '121124', '121421', '141122', '141221', '112214',
+  '112412', '122114', '122411', '142112', '142211', '241211', '221114', '413111', '241112', '134111',
+  '111242', '121142', '121241', '114212', '124112', '124211', '411212', '421112', '421211', '212141',
+  '214121', '412121', '111143', '111341', '131141', '114113', '114311', '411113', '411311', '113141',
+  '114131', '311141', '411131', '211412', '211214', '211232', '2331112',
+];
+const START_B = 104;
+const START_C = 105;
+const CODE_B = 100;
+const CODE_C = 99;
+const STOP = 106;
+
+const widthsToModules = (w: string) => [...w].map((n, i) => (i % 2 === 0 ? '1' : '0').repeat(Number(n))).join('');
+
+/**
+ * Code 128: code set B for text, switching to code set C for runs of 4+ digits (denser).
+ * Supports printable ASCII (32–126).
+ */
+export function encodeCode128(value: string): BarcodeResult {
+  if (!value) return { modules: '', text: '', error: 'Empty value' };
+  if (![...value].every((c) => c.charCodeAt(0) >= 32 && c.charCodeAt(0) <= 126)) {
+    return { modules: '', text: value, error: 'Code 128 supports printable ASCII only' };
+  }
+  const digitRun = (i: number) => {
+    let n = 0;
+    while (i + n < value.length && value[i + n] >= '0' && value[i + n] <= '9') n++;
+    return n;
+  };
+
+  const codes: number[] = [];
+  let set: 'B' | 'C';
+  let i = 0;
+  const first = digitRun(0);
+  if (first >= 4) {
+    set = 'C';
+    codes.push(START_C);
+  } else {
+    set = 'B';
+    codes.push(START_B);
+  }
+
+  while (i < value.length) {
+    const run = digitRun(i);
+    if (set === 'C') {
+      if (run >= 2) {
+        codes.push(Number(value.slice(i, i + 2)));
+        i += 2;
+        continue;
+      }
+      codes.push(CODE_B);
+      set = 'B';
+    }
+    // Switch to C for a run of >= 4 digits; an odd run keeps its first digit in B.
+    if (run >= 4) {
+      if (run % 2 === 1) {
+        codes.push(value.charCodeAt(i) - 32);
+        i++;
+      }
+      codes.push(CODE_C);
+      set = 'C';
+      continue;
+    }
+    codes.push(value.charCodeAt(i) - 32);
+    i++;
+  }
+
+  const checksum = codes.reduce((sum, c, idx) => sum + c * (idx === 0 ? 1 : idx), 0) % 103;
+  codes.push(checksum, STOP);
+  return { modules: codes.map((c) => widthsToModules(CODE128[c])).join(''), text: value };
+}
+
+const EAN_L = ['0001101', '0011001', '0010011', '0111101', '0100011', '0110001', '0101111', '0111011', '0110111', '0001011'];
+const EAN_R = EAN_L.map((p) => [...p].map((b) => (b === '1' ? '0' : '1')).join(''));
+const EAN_G = EAN_R.map((p) => [...p].reverse().join(''));
+const EAN_PARITY = ['LLLLLL', 'LLGLGG', 'LLGGLG', 'LLGGGL', 'LGLLGG', 'LGGLLG', 'LGGGLL', 'LGLGLG', 'LGLGGL', 'LGGLGL'];
+
+export function ean13CheckDigit(first12: string): number {
+  const sum = [...first12].reduce((s, d, i) => s + Number(d) * (i % 2 === 0 ? 1 : 3), 0);
+  return (10 - (sum % 10)) % 10;
+}
+
+/** EAN-13 from 12 digits (check digit added) or 13 digits (check digit verified). */
+export function encodeEan13(value: string): BarcodeResult {
+  const v = value.replace(/\s+/g, '');
+  if (!/^\d{12,13}$/.test(v)) return { modules: '', text: value, error: 'EAN-13 needs 12 or 13 digits' };
+  const check = ean13CheckDigit(v.slice(0, 12));
+  if (v.length === 13 && Number(v[12]) !== check) return { modules: '', text: value, error: `Invalid check digit (expected ${check})` };
+  const digits = v.slice(0, 12) + check;
+  const parity = EAN_PARITY[Number(digits[0])];
+  let m = '101';
+  for (let k = 1; k <= 6; k++) m += (parity[k - 1] === 'L' ? EAN_L : EAN_G)[Number(digits[k])];
+  m += '01010';
+  for (let k = 7; k <= 12; k++) m += EAN_R[Number(digits[k])];
+  m += '101';
+  return { modules: m, text: digits };
+}
+
+export function encodeBarcode(symbology: BarcodeSymbology, value: string): BarcodeResult {
+  return symbology === 'ean13' ? encodeEan13(value) : encodeCode128(value);
+}

package/src/lib/engine/chart.ts

@@ -0,0 +1,85 @@
+import type { ChartSpec } from '../model/types';
+import { aggregate, getPath, type Row } from './expressions';
+
+/** Validated categorical palette (light surface), assigned in fixed order — never cycled. */
+export const SERIES_COLORS = ['#2a78d6', '#eb6834', '#1baf7a', '#eda100', '#e87ba4', '#008300', '#6250d6', '#e34948'];
+export const OTHER_COLOR = '#9a9a96';
+export const MAX_SERIES = SERIES_COLORS.length;
+
+export interface ChartData {
+  categories: string[];
+  series: { name: string; values: number[]; color: string }[];
+}
+
+const toNum = (v: unknown) => (typeof v === 'number' && Number.isFinite(v) ? v : Number(v) || 0);
+
+/** Groups rows by category and aggregates each value field into a series. */
+export function chartData(spec: ChartSpec, rows: Row[]): ChartData {
+  const pie = spec.type === 'pie' || spec.type === 'doughnut';
+  const fields = (spec.valueFields.filter(Boolean).length ? spec.valueFields.filter(Boolean) : ['']).slice(0, pie ? 1 : MAX_SERIES);
+
+  const groups = new Map<string, Row[]>();
+  for (const r of rows) {
+    const key = spec.categoryField ? String(getPath(r, spec.categoryField) ?? '(blank)') : 'All';
+    let g = groups.get(key);
+    if (!g) groups.set(key, (g = []));
+    g.push(r);
+  }
+  let cats = [...groups.keys()].map((name) => ({
+    name,
+    rows: groups.get(name)!,
+    values: fields.map((f) => toNum(aggregate(spec.aggregate, f, groups.get(name)!))),
+  }));
+
+  if (spec.sort === 'category') cats.sort((a, b) => a.name.localeCompare(b.name, undefined, { numeric: true }));
+  else if (spec.sort === 'valueDesc') cats.sort((a, b) => b.values[0] - a.values[0]);
+  else if (spec.sort === 'valueAsc') cats.sort((a, b) => a.values[0] - b.values[0]);
+
+  // Pie slices beyond the palette (or maxCategories) fold into "Other"; other charts are just truncated.
+  const max = Math.max(1, pie ? Math.min(spec.maxCategories || MAX_SERIES, MAX_SERIES) : spec.maxCategories || 50);
+  if (cats.length > max) {
+    if (pie) {
+      const keep = cats.slice(0, max - 1);
+      const rest = cats.slice(max - 1).flatMap((c) => c.rows);
+      keep.push({ name: 'Other', rows: rest, values: fields.map((f) => toNum(aggregate(spec.aggregate, f, rest))) });
+      cats = keep;
+    } else {
+      cats = cats.slice(0, max);
+    }
+  }
+
+  if (pie) {
+    return {
+      categories: cats.map((c) => c.name),
+      series: [{ name: fields[0] || 'Count', values: cats.map((c) => c.values[0]), color: SERIES_COLORS[0] }],
+    };
+  }
+  return {
+    categories: cats.map((c) => c.name),
+    series: fields.map((f, i) => ({ name: f || 'Count', values: cats.map((c) => c.values[i]), color: SERIES_COLORS[i] })),
+  };
+}
+
+/** Pie slice colors: one fixed-order hue per category, "Other" in neutral gray. */
+export const sliceColor = (name: string, i: number) => (name === 'Other' ? OTHER_COLOR : SERIES_COLORS[i % MAX_SERIES]);
+
+/** "Nice" axis: rounded max and tick step for values in [min, max]. */
+export function niceScale(min: number, max: number, ticks = 5): { min: number; max: number; step: number } {
+  const lo = Math.min(0, min);
+  const hi = Math.max(0, max);
+  if (hi === lo) return { min: lo, max: lo + 1, step: 0.2 };
+  const raw = (hi - lo) / ticks;
+  const mag = Math.pow(10, Math.floor(Math.log10(raw)));
+  const norm = raw / mag;
+  const step = (norm <= 1 ? 1 : norm <= 2 ? 2 : norm <= 2.5 ? 2.5 : norm <= 5 ? 5 : 10) * mag;
+  return { min: Math.floor(lo / step) * step, max: Math.ceil(hi / step) * step, step };
+}
+
+/** Short tick label: 1.2K, 3.4M. */
+export function compactNumber(n: number): string {
+  const a = Math.abs(n);
+  if (a >= 1e9) return +(n / 1e9).toFixed(1) + 'B';
+  if (a >= 1e6) return +(n / 1e6).toFixed(1) + 'M';
+  if (a >= 1e3) return +(n / 1e3).toFixed(1) + 'K';
+  return String(+n.toFixed(2));
+}

package/src/lib/engine/chartLayout.ts

@@ -0,0 +1,265 @@
+import type { ChartSpec } from '../model/types';
+import { chartData, compactNumber, niceScale, sliceColor } from './chart';
+import { formatValue, type Row } from './expressions';
+
+/** SVG drawing primitives (coordinates in element pixels). */
+export type Prim =
+  | { t: 'path'; d: string; fill: string; stroke?: string; sw?: number; opacity?: number; title?: string }
+  | { t: 'line'; x1: number; y1: number; x2: number; y2: number; stroke: string; sw: number }
+  | { t: 'poly'; points: string; stroke: string; sw: number }
+  | { t: 'circle'; cx: number; cy: number; r: number; fill: string; stroke: string; sw: number; title?: string }
+  | { t: 'text'; x: number; y: number; text: string; anchor: 'start' | 'middle' | 'end'; size: number; weight: number; fill: string };
+
+const GRID = '#e4e4e0';
+const AXIS = '#9a9a96';
+const MUTED = '#5f5e5a';
+const SURFACE_GAP = '#ffffff';
+
+/** Rect with a rounded data end (the end away from the baseline). */
+function bar(x: number, y: number, w: number, h: number, end: 'top' | 'bottom' | 'right' | 'left'): string {
+  const r = Math.max(0, Math.min(3, w / 2, h / 2));
+  const R = (n: number) => +n.toFixed(2);
+  switch (end) {
+    case 'top':
+      return `M${R(x)},${R(y + h)}V${R(y + r)}Q${R(x)},${R(y)} ${R(x + r)},${R(y)}H${R(x + w - r)}Q${R(x + w)},${R(y)} ${R(x + w)},${R(y + r)}V${R(y + h)}Z`;
+    case 'bottom':
+      return `M${R(x)},${R(y)}V${R(y + h - r)}Q${R(x)},${R(y + h)} ${R(x + r)},${R(y + h)}H${R(x + w - r)}Q${R(x + w)},${R(y + h)} ${R(x + w)},${R(y + h - r)}V${R(y)}Z`;
+    case 'right':
+      return `M${R(x)},${R(y)}H${R(x + w - r)}Q${R(x + w)},${R(y)} ${R(x + w)},${R(y + r)}V${R(y + h - r)}Q${R(x + w)},${R(y + h)} ${R(x + w - r)},${R(y + h)}H${R(x)}Z`;
+    case 'left':
+      return `M${R(x + w)},${R(y)}H${R(x + r)}Q${R(x)},${R(y)} ${R(x)},${R(y + r)}V${R(y + h - r)}Q${R(x)},${R(y + h)} ${R(x + r)},${R(y + h)}H${R(x + w)}Z`;
+  }
+}
+
+/** Lays out a chart into SVG primitives for a w×h box. */
+export function layoutChart(spec: ChartSpec, rows: Row[], w: number, h: number, fontSize: number, textColor: string): Prim[] {
+  const P: Prim[] = [];
+  const fs = Math.max(6, fontSize);
+  const cw = fs * 0.58; // average glyph width estimate
+  const text = (x: number, y: number, s: string, anchor: 'start' | 'middle' | 'end', size = fs, weight = 400, fill = MUTED) =>
+    s && P.push({ t: 'text', x, y, text: s, anchor, size, weight, fill });
+  const fit = (s: string, maxW: number) => {
+    if (s.length * cw <= maxW) return s;
+    const n = Math.floor(maxW / cw) - 1;
+    return n < 1 ? '' : s.slice(0, n) + '…';
+  };
+  const fmt = (v: number) => formatValue(v, spec.valueFormat);
+
+  let top = 4;
+  let bottom = h - 4;
+  const left = 4;
+  const right = w - 4;
+  if (spec.title) {
+    text(w / 2, top + fs + 1, fit(spec.title, w - 8), 'middle', fs + 2, 700, textColor);
+    top += fs + 9;
+  }
+
+  const data = chartData(spec, rows);
+  const pie = spec.type === 'pie' || spec.type === 'doughnut';
+  if (!data.categories.length || bottom - top < 20) {
+    text(w / 2, (top + bottom) / 2, 'No data', 'middle');
+    return P;
+  }
+
+  // Legend (bottom): always for ≥2 series; pie slices are categories, so pies always get one.
+  const legend = pie
+    ? data.categories.map((c, i) => ({ name: c, color: sliceColor(c, i) }))
+    : data.series.length > 1
+      ? data.series.map((s) => ({ name: s.name, color: s.color }))
+      : [];
+  if (spec.showLegend && legend.length) {
+    const lineH = fs + 6;
+    const items = legend.map((l) => ({ ...l, label: fit(l.name, (right - left) / 2), width: 0 }));
+    items.forEach((it) => (it.width = 14 + it.label.length * cw + 12));
+    const lines: (typeof items)[] = [[]];
+    let x = 0;
+    for (const it of items) {
+      if (x + it.width > right - left && lines[lines.length - 1].length) {
+        lines.push([]);
+        x = 0;
+      }
+      lines[lines.length - 1].push(it);
+      x += it.width;
+    }
+    const shown = lines.slice(0, 3);
+    bottom -= shown.length * lineH + 2;
+    shown.forEach((line, li) => {
+      const total = line.reduce((s, it) => s + it.width, 0) - 12;
+      let lx = (w - total) / 2;
+      const ly = bottom + 4 + li * lineH;
+      for (const it of line) {
+        P.push({ t: 'path', d: bar(lx, ly + (lineH - 10) / 2 - 1, 10, 10, 'top'), fill: it.color });
+        text(lx + 14, ly + lineH / 2 + fs * 0.35 - 1, it.label, 'start', fs, 400, textColor);
+        lx += it.width;
+      }
+    });
+  }
+
+  if (pie) {
+    layoutPie(P, data, spec, left, top, right, bottom, fs, fmt);
+    return P;
+  }
+
+  const values = data.series.flatMap((s) => s.values);
+  const scale = niceScale(Math.min(...values), Math.max(...values));
+  const ticks: number[] = [];
+  for (let t = scale.min; t <= scale.max + scale.step / 2; t += scale.step) ticks.push(+t.toFixed(10));
+  const n = data.categories.length;
+  const sCount = data.series.length;
+  const title = (cat: string, s: { name: string }, v: number) => `${cat}${sCount > 1 || spec.valueFields.length ? ' · ' + s.name : ''}: ${fmt(v)}`;
+
+  if (spec.type === 'hbar') {
+    const labelW = Math.min((right - left) * 0.35, Math.max(...data.categories.map((c) => c.length)) * cw + 8);
+    const valueW = spec.showValues && sCount === 1 ? Math.max(...values.map((v) => fmt(v).length)) * cw + 6 : 6;
+    const x0 = left + labelW;
+    const x1 = right - valueW;
+    const y0 = top + 2;
+    const y1 = bottom - fs - 6;
+    if (x1 - x0 < 20 || y1 - y0 < 10) return P;
+    const xOf = (v: number) => x0 + ((v - scale.min) / (scale.max - scale.min)) * (x1 - x0);
+    for (const t of ticks) {
+      if (spec.showGrid) P.push({ t: 'line', x1: xOf(t), y1: y0, x2: xOf(t), y2: y1, stroke: GRID, sw: 1 });
+      text(xOf(t), y1 + fs + 3, compactNumber(t), 'middle');
+    }
+    P.push({ t: 'line', x1: xOf(0), y1: y0, x2: xOf(0), y2: y1, stroke: AXIS, sw: 1 });
+    const band = (y1 - y0) / n;
+    const every = Math.max(1, Math.ceil((fs + 2) / band));
+    const groupH = band * 0.72;
+    const barH = Math.max(1, (groupH - (sCount - 1) * 2) / sCount);
+    data.categories.forEach((cat, i) => {
+      if (i % every === 0) text(x0 - 5, y0 + i * band + band / 2 + fs * 0.35, fit(cat, labelW - 8), 'end', fs, 400, textColor);
+      data.series.forEach((s, j) => {
+        const v = s.values[i];
+        const y = y0 + i * band + (band - groupH) / 2 + j * (barH + 2);
+        const a = xOf(0);
+        const b = xOf(v);
+        const x = Math.min(a, b);
+        const bw = Math.abs(b - a);
+        if (bw > 0) P.push({ t: 'path', d: bar(x, y, bw, barH, v >= 0 ? 'right' : 'left'), fill: s.color, title: title(cat, s, v) });
+        if (spec.showValues && sCount === 1 && barH >= fs * 0.8) text(Math.max(a, b) + 4, y + barH / 2 + fs * 0.35, fmt(v), 'start', fs, 400, textColor);
+      });
+    });
+    return P;
+  }
+
+  // Vertical charts: bar, line, area.
+  const yLabelW = Math.max(...ticks.map((t) => compactNumber(t).length)) * cw + 6;
+  const x0 = left + yLabelW;
+  const x1 = right;
+  const y0 = top + (spec.showValues ? fs + 2 : 4);
+  const y1 = bottom - fs - 6;
+  if (x1 - x0 < 20 || y1 - y0 < 10) return P;
+  const yOf = (v: number) => y1 - ((v - scale.min) / (scale.max - scale.min)) * (y1 - y0);
+  for (const t of ticks) {
+    if (spec.showGrid) P.push({ t: 'line', x1: x0, y1: yOf(t), x2: x1, y2: yOf(t), stroke: GRID, sw: 1 });
+    text(x0 - 5, yOf(t) + fs * 0.35, compactNumber(t), 'end');
+  }
+  const band = (x1 - x0) / n;
+  const maxLabel = Math.max(...data.categories.map((c) => Math.min(c.length, 14))) * cw + 6;
+  // Label every bar when ~4 characters fit (truncated); otherwise thin the labels out.
+  const every = band >= cw * 4 + 4 ? 1 : Math.max(1, Math.ceil(maxLabel / band));
+  data.categories.forEach((cat, i) => {
+    if (i % every !== 0) return;
+    const cx = x0 + i * band + band / 2;
+    // Centred labels must not run past the plot edges.
+    const room = Math.min(band * every - 4, 2 * (cx - left), 2 * (right - cx));
+    text(cx, y1 + fs + 3, fit(cat, room), 'middle', fs, 400, textColor);
+  });
+
+  if (spec.type === 'bar') {
+    const groupW = band * 0.72;
+    const barW = Math.max(1, (groupW - (sCount - 1) * 2) / sCount);
+    data.categories.forEach((cat, i) => {
+      data.series.forEach((s, j) => {
+        const v = s.values[i];
+        const x = x0 + i * band + (band - groupW) / 2 + j * (barW + 2);
+        const a = yOf(0);
+        const b = yOf(v);
+        const y = Math.min(a, b);
+        const bh = Math.abs(a - b);
+        if (bh > 0) P.push({ t: 'path', d: bar(x, y, barW, bh, v >= 0 ? 'top' : 'bottom'), fill: s.color, title: title(cat, s, v) });
+        const label = fmt(v);
+        if (spec.showValues && sCount === 1 && label.length * cw <= band + 4) text(x + barW / 2, Math.min(a, b) - 4, label, 'middle', fs, 400, textColor);
+      });
+    });
+  } else {
+    const xAt = (i: number) => x0 + i * band + band / 2;
+    data.series.forEach((s) => {
+      const pts = s.values.map((v, i) => [xAt(i), yOf(v)] as const);
+      if (spec.type === 'area') {
+        const d = `M${pts[0][0]},${yOf(0)}` + pts.map(([x, y]) => `L${x},${y}`).join('') + `L${pts[pts.length - 1][0]},${yOf(0)}Z`;
+        P.push({ t: 'path', d, fill: s.color, opacity: 0.16 });
+      }
+      P.push({ t: 'poly', points: pts.map(([x, y]) => `${+x.toFixed(2)},${+y.toFixed(2)}`).join(' '), stroke: s.color, sw: 2 });
+      const markers = n <= 40;
+      pts.forEach(([x, y], i) => {
+        // Small markers carry the hover tooltip; a 2px surface ring separates them from the line.
+        P.push({ t: 'circle', cx: x, cy: y, r: markers ? 3.5 : 0.01, fill: s.color, stroke: SURFACE_GAP, sw: markers ? 1.5 : 0, title: title(data.categories[i], s, s.values[i]) });
+      });
+      if (spec.showValues && sCount === 1 && n <= 15) pts.forEach(([x, y], i) => text(x, y - 7, fmt(s.values[i]), 'middle', fs, 400, textColor));
+    });
+  }
+  P.push({ t: 'line', x1: x0, y1: yOf(0), x2: x1, y2: yOf(0), stroke: AXIS, sw: 1 });
+  return P;
+}
+
+function layoutPie(
+  P: Prim[],
+  data: ReturnType<typeof chartData>,
+  spec: ChartSpec,
+  left: number,
+  top: number,
+  right: number,
+  bottom: number,
+  fs: number,
+  fmt: (v: number) => string,
+) {
+  const vals = data.series[0].values.map((v) => Math.max(0, v));
+  const total = vals.reduce((a, b) => a + b, 0);
+  const cx = (left + right) / 2;
+  const cy = (top + bottom) / 2;
+  const r = Math.max(4, Math.min(right - left, bottom - top) / 2 - 2);
+  const ir = spec.type === 'doughnut' ? r * 0.58 : 0;
+  if (total <= 0) {
+    P.push({ t: 'text', x: cx, y: cy, text: 'No data', anchor: 'middle', size: fs, weight: 400, fill: MUTED });
+    return;
+  }
+  const pt = (a: number, rad: number) => `${+(cx + rad * Math.cos(a)).toFixed(2)},${+(cy + rad * Math.sin(a)).toFixed(2)}`;
+  let a0 = -Math.PI / 2;
+  vals.forEach((v, i) => {
+    if (v <= 0) return;
+    const cat = data.categories[i];
+    const sweep = (v / total) * Math.PI * 2;
+    const a1 = a0 + sweep;
+    const pct = (v / total) * 100;
+    const title = `${cat}: ${fmt(v)} (${pct.toFixed(1)}%)`;
+    let d: string;
+    if (sweep >= Math.PI * 2 - 1e-6) {
+      // Full circle: two half arcs.
+      d = `M${pt(0, r)}A${r},${r} 0 1 1 ${pt(Math.PI, r)}A${r},${r} 0 1 1 ${pt(0, r)}Z`;
+      if (ir) d += `M${pt(0, ir)}A${ir},${ir} 0 1 0 ${pt(Math.PI, ir)}A${ir},${ir} 0 1 0 ${pt(0, ir)}Z`;
+    } else {
+      const large = sweep > Math.PI ? 1 : 0;
+      d = ir
+        ? `M${pt(a0, r)}A${r},${r} 0 ${large} 1 ${pt(a1, r)}L${pt(a1, ir)}A${ir},${ir} 0 ${large} 0 ${pt(a0, ir)}Z`
+        : `M${cx},${cy}L${pt(a0, r)}A${r},${r} 0 ${large} 1 ${pt(a1, r)}Z`;
+    }
+    // 2px surface-colored stroke separates neighbouring slices.
+    P.push({ t: 'path', d, fill: sliceColor(cat, i), stroke: SURFACE_GAP, sw: 2, title });
+    if (spec.showValues && sweep > 0.35) {
+      const mid = (a0 + a1) / 2;
+      const lr = ir ? (r + ir) / 2 : r * 0.62;
+      P.push({
+        t: 'text',
+        x: cx + lr * Math.cos(mid),
+        y: cy + lr * Math.sin(mid) + fs * 0.35,
+        text: `${Math.round(pct)}%`,
+        anchor: 'middle',
+        size: fs,
+        weight: 700,
+        fill: '#ffffff',
+      });
+    }
+    a0 = a1;
+  });
+}