@ponchia/ui 0.4.1 → 0.6.0

package/MIGRATIONS.json

@@ -0,0 +1,106 @@
+{
+  "$comment": "Machine-readable rename/removal map for @ponchia/ui upgrades (classes, attributes, and tokens). Generated-by-hand from CHANGELOG BREAKING sections; consumed by docs/migrations/*.md and any codemod/sed recipe. 'safe' rules are mechanically rewritable (whole-token, no semantic change); 'manual' rules need human judgement (concept moved or removed, not a 1:1 rename).",
+  "migrations": [
+    {
+      "from": "0.2",
+      "to": "0.3",
+      "summary": "Entire non-ui-* legacy vocabulary removed; everything is now under the .ui-* contract and the check-classes drift gate.",
+      "safe": [
+        { "old": "skip-link", "new": "ui-skiplink" },
+        { "old": "site-nav", "new": "ui-sitenav" },
+        { "old": "site-menu", "new": "ui-sitemenu" },
+        { "old": "theme-toggle", "new": "ui-themetoggle", "prefix": true },
+        { "old": "app-shell", "new": "ui-app-shell", "prefix": true },
+        { "old": "app-rail", "new": "ui-app-rail", "prefix": true },
+        { "old": "app-topbar", "new": "ui-app-topbar", "prefix": true },
+        { "old": "app-toolbar", "new": "ui-app-toolbar", "prefix": true },
+        { "old": "app-nav", "new": "ui-app-nav", "prefix": true },
+        { "old": "app-panel", "new": "ui-app-panel", "prefix": true },
+        { "old": "app-content", "new": "ui-app-content", "prefix": true },
+        { "old": "app-main", "new": "ui-app-main", "prefix": true },
+        { "old": "app-metrics", "new": "ui-app-metrics", "prefix": true },
+        { "old": "app-metric", "new": "ui-app-metric", "prefix": true },
+        { "old": "app-empty-state", "new": "ui-app-empty-state", "prefix": true }
+      ],
+      "manual": [
+        {
+          "old": "hero / project-* / post-card / essay-* / page-* / home-* / signal-panel / worklog-summary",
+          "new": "the ui-* content layer",
+          "note": "Long-form content: .ui-prose / .ui-quote. Cards: .ui-card. Layout: .ui-grid / .ui-stack. Site chrome: the ui-site* shell. No 1:1 mapping — re-compose with the content primitives."
+        },
+        {
+          "old": "callout",
+          "new": "ui-alert",
+          "note": "Tone modifiers differ (.ui-alert--info/-success/-warning/-danger); re-pick the tone."
+        },
+        {
+          "old": "metric-tile",
+          "new": "ui-app-metric",
+          "note": "Now scoped to the admin shell vocabulary; standalone stat usage should wrap in .ui-app-metrics."
+        },
+        {
+          "old": "tag-list / tag",
+          "new": "ui-tags / ui-tag",
+          "note": "Compact variant .tag-list--compact → .ui-tags--compact; verify accent-on-accent contrast (see CHANGELOG 0.3.0 a11y fix)."
+        }
+      ],
+      "codemod": "See docs/migrations/0.2-to-0.3.md for a ready-to-run ripgrep+sed recipe covering the 'safe' rules."
+    },
+    {
+      "from": "0.3",
+      "to": "0.4",
+      "summary": "Additive colour-system release (ADR-0001); the default dist/bronto.css renders identically. No class or attribute renames. One orphan token pair removed.",
+      "safe": [],
+      "manual": [
+        {
+          "old": "--orange / --orange-soft",
+          "new": "(removed — re-declare in a consumer :root override if referenced)",
+          "note": "Orphan token pair: defined in the token mirrors but referenced by no shipped component and documented nowhere, and untiered under the new colour model. Removed under the CONTRIBUTING 'provably-unreferenced surface' exception. If you used it: :root { --orange: #a85f32; --orange-soft: rgb(168 95 50 / 0.13); }"
+        }
+      ],
+      "codemod": "No class codemod needed (no renames). See docs/migrations/0.3-to-0.4.md; audit usage with: rg -- '--orange' ."
+    },
+    {
+      "from": "0.4",
+      "to": "0.5",
+      "summary": "Adds the analytical-primitives suite (annotations, legend, marks, connectors, spotlight, crosshair, selection + the analytical.css roll-up); all additive/opt-in. Three breaking changes: the chart data key moved out of the report kit into the standalone Legends layer (`.ui-chart__legend`/`.ui-chart__swatch` removed); annotation arrowheads now render via the shared connectors geometry kernel (a small visual path change, no API change); and the marks/bracket-note rationed-accent tone was renamed `evidence`→`accent` to match the annotation/connector tone vocabulary (`.ui-annotation--evidence` stays — it's a marker variant, not a tone).",
+      "safe": [
+        { "old": "ui-chart__swatch", "new": "ui-legend__swatch" },
+        { "old": "ui-mark--evidence", "new": "ui-mark--accent" },
+        { "old": "ui-bracket-note--evidence", "new": "ui-bracket-note--accent" }
+      ],
+      "manual": [
+        {
+          "old": "ui.mark({ tone: 'evidence' }) / ui.bracketNote({ tone: 'evidence' })",
+          "new": "tone: 'accent'",
+          "note": "The rationed-accent tone option on the mark/bracket-note recipes is now 'accent' (was 'evidence'), matching ui.connector/ui.annotation. Do NOT rewrite ui.annotation({ variant: 'evidence' }) or the 'evidence' subject marker — those are a marker shape, not a tone, and are unchanged."
+        },
+        {
+          "old": "ui-chart__legend",
+          "new": "ui-legend",
+          "note": "Also import '@ponchia/ui/css/legend.css' beside report.css, and wrap each entry's content as <li class=\"ui-legend__item\"> … <span class=\"ui-legend__label\">…</span>. The swatch's --chart-color/--chart-pattern inline contract is unchanged; the categorical --chart-N colour is also available via .ui-legend__swatch--N. See docs/legends.md."
+        },
+        {
+          "old": "connectorEndArrow (annotations)",
+          "new": "connectorEndArrow (unchanged API)",
+          "note": "No code change needed. The function signature is identical; only the rendered arrowhead path differs slightly now that it shares the connectors geometry kernel. Re-baseline any exact-path SVG snapshot tests of annotation arrowheads."
+        }
+      ],
+      "codemod": "rg -l 'ui-chart__legend|ui-chart__swatch' then s/ui-chart__swatch/ui-legend__swatch/g and rework the ul.ui-chart__legend wrapper into ul.ui-legend with li.ui-legend__item rows. See docs/legends.md."
+    },
+    {
+      "from": "0.5",
+      "to": "0.6",
+      "summary": "Charting realignment. The local static bar-chart renderer (.ui-chart*) is removed — a chart needs scales + data binding, out of scope for the analytical layer. bronto is now a themeable target for Vega-Lite (@ponchia/ui/vega), the same tokens-as-data path as Mermaid/D2. The --chart-* data-viz palette, tokens/charts.json, and the .ui-legend layer are unchanged.",
+      "safe": [],
+      "manual": [
+        {
+          "old": "ui-chart / ui-chart__plot / ui-chart__bar / ui-chart__label / ui-chart__track / ui-chart__fill / ui-chart__fallback / ui-chart__caption",
+          "new": "a Vega-Lite chart themed with @ponchia/ui/vega, or a token-themed inline <svg>",
+          "note": "No 1:1 class mapping — the renderer is removed. For a real chart: import '@ponchia/ui/vega', pass brontoVegaConfig(theme) to vega-embed, and place the result in a <figure class=\"ui-report__figure\"> with a <figcaption class=\"ui-report__caption\"> and a <ul class=\"ui-legend\"> key (see docs/vega.md). For a frozen/print chart: hand-author an inline <svg> using the --chart-N palette tokens for fills. The --chart-value inline knob is gone; --chart-color/--chart-pattern remain on .ui-legend__swatch."
+        }
+      ],
+      "codemod": "No codemod — the .ui-chart* renderer has no replacement class. rg -l 'ui-chart\\\\b|ui-chart__' to find call sites, then rebuild each as a Vega-Lite chart (@ponchia/ui/vega) or a token-themed inline <svg>. See docs/vega.md."
+    }
+  ]
+}

package/README.md

@@ -3,12 +3,24 @@
 [![npm](https://img.shields.io/npm/v/@ponchia/ui?logo=npm)](https://www.npmjs.com/package/@ponchia/ui)
 [![npm provenance](https://img.shields.io/badge/npm-provenance-blue?logo=npm)](https://www.npmjs.com/package/@ponchia/ui#provenance)
 [![runtime deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen)](https://github.com/Ponchia/bronto-ui/blob/main/package.json)
-[![dist](https://img.shields.io/badge/dist-~75kB%20%2F%20~13kB%20gzip-informational)](https://github.com/Ponchia/bronto-ui/blob/main/scripts/check-dist.mjs)
+[![dist](https://img.shields.io/badge/dist-~76kB%20%2F%20~13kB%20gzip-informational)](https://github.com/Ponchia/bronto-ui/blob/main/scripts/check-dist.mjs)
 [![CI](https://github.com/Ponchia/bronto-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/Ponchia/bronto-ui/actions/workflows/ci.yml)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Ponchia/bronto-ui/badge)](https://scorecard.dev/viewer/?uri=github.com/Ponchia/bronto-ui)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/Ponchia/bronto-ui/blob/main/LICENSE)
 
-**A CSS-first, framework-agnostic UI framework built on token-driven restraint — monochrome by default, one rationed accent, dot-matrix display type, hairline borders. Color is _tiered_: we don't decorate with it, we signal with it. The "Nothing"-inspired look is the default skin, not the architecture — opt-in colorways (amber CRT · phosphor green · e-ink), a dot-matrix icon set, and a colourblind-safe data-viz palette prove the one knob is real. Zero runtime dependencies; re-brand the whole thing with one CSS variable.**
+**A CSS-first design system for interfaces that explain themselves.** It works in
+plain HTML, every modern framework, and print/PDF, with no component runtime to
+adopt and zero runtime dependencies.
+
+The look is a deliberate stance: a neutral monochrome canvas with one rationed
+accent (colour signals, it never decorates), dot-matrix display type, and
+hairline borders — all re-skinnable from a single `--accent` knob (opt-in
+amber-CRT, phosphor-green, and e-ink colorways).
+
+Beyond the standard component set it ships an opt-in analytical & report layer —
+SVG annotations, legends, leader-line connectors, a guided-focus spotlight, text
+marks, a colourblind-safe data-viz palette, and a static/PDF report grammar — for
+dashboards and LLM-authored reports.
 
 ### [Live demo →](https://ponchia.github.io/bronto-ui/)  ·  [Theme playground →](https://ponchia.github.io/bronto-ui/demo/theme-playground.html)
 
@@ -18,7 +30,18 @@ The demo is the kitchen sink — every component, light/dark, RTL, live theming.
 
 ## What it is
 
-`@ponchia/ui` ships its design as **CSS**, not components. You drop in one stylesheet and style with semantic `ui-*` classes; an optional thin layer of typed class-name recipes and SSR-safe vanilla behaviors sits on top for the few things that genuinely need JS (theme persistence, dialogs, toasts, disclosure). The guiding principle is **color is rationed, structure carries meaning** — layout, type weight and the hairline do the work before a hue does, and the accent is a spotlight, not a paint bucket. Because everything lives in a single `@layer bronto`, your own un-layered CSS overrides the framework with no specificity fight and no `!important`.
+`@ponchia/ui` ships its design as CSS, not components. You drop in one stylesheet
+and style with semantic `ui-*` classes; an optional thin layer of typed
+class-name recipes and SSR-safe vanilla behaviors sits on top for the few things
+that genuinely need JS (theme persistence, dialogs, toasts, disclosure).
+
+The guiding principle is that **colour is rationed and structure carries
+meaning** — layout, type weight, and the hairline do the work before a hue does,
+and the accent is a spotlight, not a paint bucket. Because everything lives in a
+single `@layer bronto`, your own un-layered CSS overrides the framework with no
+specificity fight and no `!important`.
+
+It ships a complete, accessible **standard component set** — but that's not where it competes. Its differentiator is an opt-in **analytical & communication layer** for interfaces that make complex work legible: annotations, legends, connectors, marks, a guided-focus spotlight, lifecycle/system-state and source-provenance vocabularies, and a static/PDF report grammar. Each owns only its visual grammar and pure geometry — no chart engine, no state, no hit-testing. See **[docs/frontier-primitives.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/frontier-primitives.md)** for the thesis.
 
 ## Install
 
@@ -34,7 +57,7 @@ Or drop it in with no build step, straight from a CDN:
 
 ## Quick start
 
-**1. Load the CSS.** One flattened, minified bundle — the whole framework, one request (~75 kB raw / ~13 kB gzip):
+**1. Load the CSS.** One flattened, minified bundle — the whole standard component set, one request (~76 kB raw / ~13 kB gzip):
 
 ```css
 @import '@ponchia/ui';            /* via a bundler */
@@ -47,6 +70,8 @@ Or drop it in with no build step, straight from a CDN:
 
 > Prefer source leaves through a bundler? Use `@import '@ponchia/ui/css'` (a thin `@import` fan-out) instead. Both resolve the Doto `@font-face` with relative URLs, so there's no `/fonts` path assumption.
 
+> The bundle is the standard component set. The opt-in analytical & report layers — `report.css`, `dataviz.css`, `annotations.css`, `legend.css`, and the rest — are **not** in `bronto.css`; link each one you need from `dist/css/`. For LLM-authored static reports see [docs/reporting.md](docs/reporting.md).
+
 **2. Write markup with `ui-*` classes** (primary is the default button; modifiers are opt-in):
 
 ```html
@@ -100,6 +125,7 @@ Arrows, chevrons, check/close/plus/minus, search/menu/gear, info/warning/bell/lo
 - **Disclosure & nav** — tabs, accordion, segmented, breadcrumb, pagination, `ui-steps`, `ui-timeline`, `ui-pagehead`, `ui-kbd`.
 - **Shells** — an admin dashboard shell (`ui-app-*`) and a content/marketing site shell (`ui-site*`, `ui-container`).
 - **Prose** — `.ui-prose` styles raw, unclassed semantic HTML (Markdown / CMS / LLM output) with zero classes.
+- **Analytical & communication primitives** _(opt-in)_ — `@ponchia/ui/css/analytical.css`: SVG **annotations** (subject/connector/note), standalone **legends**/data-keys, text/evidence **marks**, leader-line **connectors** (+ a pure `@ponchia/ui/connectors` geometry kernel), a guided-focus **spotlight**, a **crosshair**/readout, and a cross-cutting **selection** vocabulary. Each owns its visual grammar + pure geometry and refuses scales/state/hit-testing — figures that explain themselves, not a chart engine. Plus standalone **`source`/provenance** (trust) and **lifecycle `state`** leaves.
 - **Reports** _(opt-in)_ — `@ponchia/ui/css/report.css`, a static/PDF-first report grammar for LLM-authored HTML: covers, sections, findings, evidence, figures, chart wrappers and print utilities.
 - **Motion & dots** — the dot-matrix motif kit: dot grid, status dots, dot loaders, the orbital spinner, matrix reveal — all reduced-motion aware.
 - **Glyphs** — `@ponchia/ui/glyphs`, a 48-glyph dot-matrix icon set on the `.ui-dotmatrix` primitive (display marks + crisp `solid` inline icons + one-node `.ui-icon` mask rendering).
@@ -117,7 +143,7 @@ Everything accent-colored derives from a single `--accent` variable via `color-m
 .promo  { --accent: #16a34a; }   /* …or just this section green */
 ```
 
-Buttons, focus rings, dot motifs, accent borders and soft fills all follow automatically. Light/dark is `data-theme="light"` / `"dark"` on `<html>` (defaults to `prefers-color-scheme`); `data-density` and `data-contrast` give density and contrast presets. A full re-skin (radius, display face, dot density, surfaces) is a handful more token overrides — the "Nothing" look is the **default skin, not the architecture**.
+Buttons, focus rings, dot motifs, accent borders and soft fills all follow automatically. Light/dark is `data-theme="light"` / `"dark"` on `<html>` (defaults to `prefers-color-scheme`); `data-density` and `data-contrast` give density and contrast presets. A full re-skin (radius, display face, dot density, surfaces) is a handful more token overrides — the default monochrome look is **one skin, not the architecture**.
 
 **One system, many skins.** That the knob is real isn't a claim — it ships: drop in `@ponchia/ui/css/skins.css` and set `data-bronto-skin="amber-crt | phosphor-green | e-ink"` on `<html>` for a complete, contrast-gated recolour (the derived accent family, focus ring, dot-matrix and glyphs all follow). Colour is governed in **tiers** — neutral canvas · one accent · locked status · display expression · opt-in data-viz — so it always earns its place; the full constitution is **[ADR-0001](https://github.com/Ponchia/bronto-ui/blob/main/docs/adr/0001-color-system.md)**.
 
@@ -165,7 +191,7 @@ Recent-evergreen, by design. The framework targets the modern web platform — c
 
 ## Versioning
 
-Pre-1.0 and deliberately so. **Until `1.0.0`, breaking changes ship in the _minor_** (`0.x.0`); patches (`0.x.y`) are always non-breaking. Pin with the patch range — at `0.x`, `~0.4.0` (and equivalently `^0.4.0`) resolves to `>=0.4.0 <0.5.0`, giving you safe patches while holding back the next breaking minor. Every breaking change is called out under a **BREAKING** heading in the **[CHANGELOG](https://github.com/Ponchia/bronto-ui/blob/main/CHANGELOG.md)** with a migration note.
+Pre-1.0 and deliberately so. **Until `1.0.0`, breaking changes ship in the _minor_** (`0.x.0`); patches (`0.x.y`) are always non-breaking. Pin with the patch range — at `0.x`, `~0.6.0` (and equivalently `^0.6.0`) resolves to `>=0.6.0 <0.7.0`, giving you safe patches while holding back the next breaking minor. Every breaking change is called out under a **BREAKING** heading in the **[CHANGELOG](https://github.com/Ponchia/bronto-ui/blob/main/CHANGELOG.md)** with a migration note.
 
 Contractual (changes are breaking): token **names** and documented token roles, `.ui-*` class and recipe names, `data-bronto-*` attributes, exported behavior/glyph/binding function names and each behavior's cleanup contract. Not contractual (may change any release): exact token **values** and generated colour math outputs (visual tuning) unless a doc explicitly says the value is stable, plus internal leaf-file / `@layer` boundaries. See **[docs/stability.md](https://github.com/Ponchia/bronto-ui/blob/main/docs/stability.md)** for the full public-surface matrix.
 
@@ -175,10 +201,10 @@ Release candidates publish to the `next` dist-tag, never to `latest` — opt in
 
 - **[Live demo](https://ponchia.github.io/bronto-ui/)** · **[Theme playground](https://ponchia.github.io/bronto-ui/demo/theme-playground.html)**
 - **[Class reference](https://github.com/Ponchia/bronto-ui/blob/main/docs/reference.md)** · **[Usage guide](https://github.com/Ponchia/bronto-ui/blob/main/docs/usage.md)** · **[Theming](https://github.com/Ponchia/bronto-ui/blob/main/docs/theming.md)** · **[Contrast](https://github.com/Ponchia/bronto-ui/blob/main/docs/contrast.md)** · **[Color system (ADR-0001)](https://github.com/Ponchia/bronto-ui/blob/main/docs/adr/0001-color-system.md)** · **[Scope & 2026 baseline (ADR-0002)](https://github.com/Ponchia/bronto-ui/blob/main/docs/adr/0002-scope-and-2026-baseline.md)**
-- **[CHANGELOG](https://github.com/Ponchia/bronto-ui/blob/main/CHANGELOG.md)** · **[Roadmap](https://github.com/Ponchia/bronto-ui/blob/main/ROADMAP.md)** · **[Contributing](https://github.com/Ponchia/bronto-ui/blob/main/CONTRIBUTING.md)**
+- **[CHANGELOG](https://github.com/Ponchia/bronto-ui/blob/main/CHANGELOG.md)** · **[Roadmap](https://github.com/Ponchia/bronto-ui/blob/main/ROADMAP.md)** · **[Contributing](https://github.com/Ponchia/bronto-ui/blob/main/CONTRIBUTING.md)** · **[Repository layout](https://github.com/Ponchia/bronto-ui/blob/main/docs/architecture.md#repository-layout)**
 
 ## License
 
 [MIT](https://github.com/Ponchia/bronto-ui/blob/main/LICENSE) © Ponchia.
 
-The bundled **Doto** font (`fonts/*.ttf`) is © 2024 The Doto Project Authors and licensed separately under the [SIL Open Font License 1.1](https://github.com/Ponchia/bronto-ui/blob/main/fonts/OFL.txt) — see `fonts/OFL.txt`.
+The bundled **Doto** font (`fonts/*.woff2`) is © 2024 The Doto Project Authors and licensed separately under the [SIL Open Font License 1.1](https://github.com/Ponchia/bronto-ui/blob/main/fonts/OFL.txt) — see `fonts/OFL.txt`.

package/annotations/index.d.ts

@@ -0,0 +1,402 @@
+/**
+ * @param {Partial<AnnotationPoint>} [point]
+ * @returns {string}
+ */
+export function annotationTransform({ x, y }?: Partial<AnnotationPoint>): string;
+/**
+ * @param {NoteTransformOptions} [options]
+ * @returns {string}
+ */
+export function noteTransform({ dx, dy, x, y, align, valign, width, height, }?: NoteTransformOptions): string;
+/**
+ * @param {NotePlacementOptions} options
+ * @returns {NotePlacement}
+ */
+export function notePlacement({ x, y, width, height, bounds, padding, gap, preferred, inset, }?: NotePlacementOptions): NotePlacement;
+/**
+ * @param {CircleSubjectOptions} options
+ * @returns {string}
+ */
+export function circleSubjectPath({ radius }?: CircleSubjectOptions): string;
+/**
+ * @param {RectSubjectOptions} options
+ * @returns {string}
+ */
+export function rectSubjectPath({ width, height, x, y, padding }?: RectSubjectOptions): string;
+/**
+ * @param {ThresholdOptions} options
+ * @returns {string}
+ */
+export function thresholdPath({ x1, y1, x2, y2 }?: ThresholdOptions): string;
+/**
+ * @param {AxisThresholdOptions} options
+ * @returns {string}
+ */
+export function axisThresholdPath({ orientation, value, start, end }?: AxisThresholdOptions): string;
+/**
+ * @param {BracketSubjectOptions} options
+ * @returns {string}
+ */
+export function bracketSubjectPath({ x1, y1, x2, y2, depth }?: BracketSubjectOptions): string;
+/**
+ * @param {BandSubjectOptions} options
+ * @returns {string}
+ */
+export function bandSubjectPath({ x, y, width, height, padding }?: BandSubjectOptions): string;
+/**
+ * @param {SlopeSubjectOptions} options
+ * @returns {string}
+ */
+export function slopeSubjectPath({ x1, y1, x2, y2 }?: SlopeSubjectOptions): string;
+/**
+ * @param {ComparisonBraceOptions} options
+ * @returns {string}
+ */
+export function comparisonBracePath({ x1, y1, x2, y2, depth }?: ComparisonBraceOptions): string;
+/**
+ * @param {OutlierClusterOptions} options
+ * @returns {string}
+ */
+export function outlierClusterPath({ points, radius }?: OutlierClusterOptions): string;
+/**
+ * @param {TimelineEventOptions} [options]
+ * @returns {string}
+ */
+export function timelineEventPath({ size, direction }?: TimelineEventOptions): string;
+/**
+ * @param {EvidenceMarkerOptions} [options]
+ * @returns {string}
+ */
+export function evidenceMarkerPath({ x, y, width, height, padding }?: EvidenceMarkerOptions): string;
+/**
+ * @param {ConnectorEndDotOptions} options
+ * @returns {string}
+ */
+export function connectorEndDot({ x, y, radius }?: ConnectorEndDotOptions): string;
+/**
+ * @param {ConnectorEndArrowOptions} options
+ * @returns {string}
+ */
+export function connectorEndArrow({ x1, y1, x2, y2, size, spread }?: ConnectorEndArrowOptions): string;
+/**
+ * @param {ConnectorOptions} opts
+ * @returns {string}
+ */
+export function connectorLine(opts?: ConnectorOptions): string;
+/**
+ * @param {ConnectorOptions} opts
+ * @returns {string}
+ */
+export function connectorElbow(opts?: ConnectorOptions): string;
+/**
+ * @param {ConnectorOptions} opts
+ * @returns {string}
+ */
+export function connectorCurve(opts?: ConnectorOptions): string;
+/**
+ * @param {AnnotationPartsOptions} [opts]
+ * @returns {AnnotationParts}
+ */
+export function annotationParts(opts?: AnnotationPartsOptions): AnnotationParts;
+/**
+ * Declutter labels along ONE axis: nudge overlapping labels apart so each keeps
+ * `gap` from its neighbours, sweeping up from `min`; if the run overflows `max`
+ * it slides up to fit. Deterministic and order-preserving — NOT a general 2-D
+ * collision solver (with more labels than the range holds, the overflow past
+ * `min` is the caller's to resolve: fewer labels, a longer axis, or rotation).
+ *
+ * `items`: `[{ pos, size }]` — `pos` is the desired centre coordinate along the
+ * axis, `size` the label's extent along it. Returns the adjusted centre per
+ * input item, in the original order.
+ *
+ * @param {DeclutterLabelItem[]} items
+ * @param {DeclutterLabelsOptions} [opts]
+ * @returns {number[]}
+ */
+export function declutterLabels(items: DeclutterLabelItem[], opts?: DeclutterLabelsOptions): number[];
+/**
+ * Direct labeling: declutter labels along one axis and draw a leader line from
+ * each true anchor to its placed label. This is the 1-D core of Labella,
+ * completed with leaders via the shared connector kernel — deterministic and
+ * pure. It owns no scales (map data → figure coords first), no DOM, no
+ * nearest-anchor matching, and no 2-D placement; those stay the host's job.
+ *
+ * Each `items[i]` is `{ anchor: {x, y}, size, key? }`: `anchor` is the true
+ * data point in figure coordinates, `size` is the label's extent along the
+ * layout `axis`. Labels declutter along `axis` ('y' = a vertical column,
+ * default) and sit at the fixed `cross` coordinate on the other axis. Returns,
+ * in input order, the placed label point `{x, y}`, the echoed `anchor` and
+ * `key`, and the leader path `d` (anchor → label; `''` if they coincide) ready
+ * for a `<path class="ui-annotation__connector">`.
+ *
+ * @param {DirectLabelItem[]} items
+ * @param {DirectLabelsOptions} [opts]
+ * @returns {DirectLabel[]}
+ */
+export function directLabels(items: DirectLabelItem[], opts?: DirectLabelsOptions): DirectLabel[];
+export type AnnotationPoint = {
+    x: number;
+    y: number;
+};
+export type AnnotationOffset = {
+    dx: number;
+    dy: number;
+};
+export type AnnotationConnectorType = "callout" | "elbow" | "curve";
+export type AnnotationAlign = "start" | "middle" | "end";
+export type AnnotationValign = "top" | "middle" | "bottom";
+export type AxisOrientation = "horizontal" | "vertical";
+export type TimelineDirection = "up" | "down" | "left" | "right";
+export type CircleSubject = {
+    type: "circle";
+    radius: number;
+    radiusPadding?: number | undefined;
+};
+export type RectSubject = {
+    type: "rect";
+    width: number;
+    height: number;
+    x?: number | undefined;
+    y?: number | undefined;
+    padding?: number | undefined;
+};
+export type ConnectorSubject = CircleSubject | RectSubject;
+export type ConnectorOptions = AnnotationOffset & {
+    subject?: ConnectorSubject;
+    mid?: number;
+};
+export type CircleSubjectOptions = {
+    radius: number;
+};
+export type RectSubjectOptions = {
+    width: number;
+    height: number;
+    x?: number | undefined;
+    y?: number | undefined;
+    padding?: number | undefined;
+};
+export type ThresholdOptions = {
+    x1?: number | undefined;
+    y1?: number | undefined;
+    x2: number;
+    y2: number;
+};
+export type AxisThresholdOptions = {
+    orientation?: AxisOrientation | undefined;
+    value?: number | undefined;
+    start?: number | undefined;
+    end: number;
+};
+export type BracketSubjectOptions = {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    depth?: number | undefined;
+};
+export type BandSubjectOptions = {
+    x?: number | undefined;
+    y?: number | undefined;
+    width: number;
+    height: number;
+    padding?: number | undefined;
+};
+export type SlopeSubjectOptions = {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+};
+export type ComparisonBraceOptions = {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    depth?: number | undefined;
+};
+export type OutlierClusterOptions = {
+    points: AnnotationPoint[];
+    radius?: number | undefined;
+};
+export type TimelineEventOptions = {
+    size?: number | undefined;
+    direction?: TimelineDirection | undefined;
+};
+export type EvidenceMarkerOptions = {
+    x?: number | undefined;
+    y?: number | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
+    padding?: number | undefined;
+};
+export type ConnectorEndDotOptions = AnnotationPoint & {
+    radius?: number;
+};
+export type ConnectorEndArrowOptions = {
+    x1?: number | undefined;
+    y1?: number | undefined;
+    x2: number;
+    y2: number;
+    size?: number | undefined;
+    /**
+     * Half-angle of the arrowhead in radians (default
+     * 0.32 ≈ a crisp 37° included angle). Larger = blunter.
+     */
+    spread?: number | undefined;
+};
+export type NoteTransformOptions = {
+    dx?: number | undefined;
+    dy?: number | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+    align?: AnnotationAlign | undefined;
+    valign?: AnnotationValign | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
+};
+export type AnnotationBounds = {
+    x?: number | undefined;
+    y?: number | undefined;
+    width: number;
+    height: number;
+};
+export type NotePlacementOptions = {
+    x?: number | undefined;
+    y?: number | undefined;
+    width: number;
+    height: number;
+    bounds: AnnotationBounds;
+    padding?: number | undefined;
+    gap?: number | undefined;
+    preferred?: "top" | "right" | "bottom" | "left" | undefined;
+    /**
+     * Extra margin (user units) the note must keep from
+     * the bounds edge, on top of `padding`. Reserve the note's title stroke-halo
+     * (~3) or a leader stub so a placement that "fits" doesn't clip. Default 0.
+     */
+    inset?: number | undefined;
+};
+export type NotePlacement = {
+    dx: number;
+    dy: number;
+    align: AnnotationAlign;
+    valign: AnnotationValign;
+    transform: string;
+};
+export type AnnotationPartsSubject = (CircleSubject | RectSubject | ({
+    type: "threshold";
+} & ThresholdOptions) | ({
+    type: "bracket";
+} & BracketSubjectOptions) | ({
+    type: "band";
+} & BandSubjectOptions) | ({
+    type: "slope";
+} & SlopeSubjectOptions) | ({
+    type: "compare";
+} & ComparisonBraceOptions) | ({
+    type: "cluster";
+} & OutlierClusterOptions) | ({
+    type: "axis";
+} & AxisThresholdOptions) | ({
+    type: "timeline";
+} & TimelineEventOptions) | ({
+    type: "evidence";
+} & EvidenceMarkerOptions));
+export type AnnotationPartsOptions = {
+    type?: AnnotationConnectorType | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+    dx?: number | undefined;
+    dy?: number | undefined;
+    subject?: AnnotationPartsSubject | undefined;
+};
+export type AnnotationParts = {
+    transform: string;
+    subject: string;
+    connector: string;
+    note: string;
+};
+export type DeclutterLabelItem = {
+    /**
+     * Desired centre coordinate along the axis.
+     */
+    pos: number;
+    /**
+     * The label's extent along the axis.
+     */
+    size: number;
+};
+export type DeclutterLabelsOptions = {
+    /**
+     * Minimum gap kept between adjacent labels. Default 0.
+     */
+    gap?: number | undefined;
+    /**
+     * Lower bound of the axis. Default -Infinity.
+     */
+    min?: number | undefined;
+    /**
+     * Upper bound of the axis. Default Infinity.
+     */
+    max?: number | undefined;
+};
+export type DirectLabelItem = {
+    /**
+     * The true data point the label refers to (figure coordinates).
+     */
+    anchor: AnnotationPoint;
+    /**
+     * The label's extent along the layout axis.
+     */
+    size: number;
+    /**
+     * Optional identifier, echoed back on the matching output (input order).
+     */
+    key?: string | number | undefined;
+};
+export type DirectLabelsOptions = {
+    /**
+     * Axis the labels declutter along. 'y' = a vertical column. Default 'y'.
+     */
+    axis?: "x" | "y" | undefined;
+    /**
+     * Fixed coordinate on the other axis where the label column/row sits. Default 0.
+     */
+    cross?: number | undefined;
+    /**
+     * Minimum gap kept between adjacent labels. Default 0.
+     */
+    gap?: number | undefined;
+    /**
+     * Lower bound of the layout axis. Default -Infinity.
+     */
+    min?: number | undefined;
+    /**
+     * Upper bound of the layout axis. Default Infinity.
+     */
+    max?: number | undefined;
+    /**
+     * Leader-line shape. Default 'straight'.
+     */
+    shape?: "straight" | "elbow" | "curve" | undefined;
+};
+export type DirectLabel = {
+    /**
+     * Placed label point — the leader's label-side end.
+     */
+    x: number;
+    y: number;
+    /**
+     * The echoed input anchor.
+     */
+    anchor: AnnotationPoint;
+    /**
+     * The echoed input key, if any.
+     */
+    key?: string | number | undefined;
+    /**
+     * SVG path for the leader (anchor → label point); '' if they coincide.
+     */
+    d: string;
+};
+//# sourceMappingURL=index.d.ts.map

package/annotations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":"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"}