@ponchia/ui 0.6.0 → 0.6.4

package/classes/index.d.ts

@@ -79,6 +79,16 @@ export declare const cls: {
   readonly dotspinner: 'ui-dotspinner';
   readonly dotspinnerSm: 'ui-dotspinner--sm';
   readonly dotspinnerLg: 'ui-dotspinner--lg';
+  readonly waffle: 'ui-waffle';
+  readonly activity: 'ui-activity';
+  readonly level: 'ui-level';
+  readonly levelWarn: 'ui-level--warn';
+  readonly levelDanger: 'ui-level--danger';
+  readonly dotgauge: 'ui-dotgauge';
+  readonly readout: 'ui-readout';
+  readonly readoutSpacer: 'ui-readout__spacer';
+  readonly halftone: 'ui-halftone';
+  readonly dotfit: 'ui-dotfit';
   readonly field: 'ui-field';
   readonly label: 'ui-label';
   readonly input: 'ui-input';
@@ -104,7 +114,7 @@ export declare const cls: {
   readonly alert: 'ui-alert';
   readonly alertTitle: 'ui-alert__title';
   readonly alertBody: 'ui-alert__body';
-  readonly alertDismiss: 'ui-alert__dismiss';
+  readonly alertClose: 'ui-alert__close';
   readonly alertAccent: 'ui-alert--accent';
   readonly alertSuccess: 'ui-alert--success';
   readonly alertWarning: 'ui-alert--warning';
@@ -128,6 +138,9 @@ export declare const cls: {
   readonly progressIndeterminate: 'ui-progress--indeterminate';
   readonly meter: 'ui-meter';
   readonly meterFill: 'ui-meter__fill';
+  readonly meterRow: 'ui-meter__row';
+  readonly meterLabel: 'ui-meter__label';
+  readonly meterValue: 'ui-meter__value';
   readonly meterAccent: 'ui-meter--accent';
   readonly meterSuccess: 'ui-meter--success';
   readonly meterWarning: 'ui-meter--warning';
@@ -186,13 +199,14 @@ export declare const cls: {
   readonly tableDense: 'ui-table--dense';
   readonly tableComfortable: 'ui-table--comfortable';
   readonly tableLined: 'ui-table--lined';
+  readonly tableBreakAnywhere: 'ui-table--break-anywhere';
   readonly tableWrap: 'ui-table-wrap';
+  readonly tableLoading: 'ui-table-wrap--loading';
   readonly tableEmpty: 'ui-table__empty';
   readonly tableSort: 'ui-table__sort';
   readonly tableSelect: 'ui-table__select';
   readonly tableToolbar: 'ui-table__toolbar';
   readonly tableSelectable: 'ui-table--selectable';
-  readonly tableLoading: 'ui-table--loading';
   readonly panel: 'ui-panel';
   readonly panelHead: 'ui-panel__head';
   readonly surface: 'ui-surface';
@@ -369,7 +383,6 @@ export declare const cls: {
   readonly crosshairLineX: 'ui-crosshair__line--x';
   readonly crosshairLineY: 'ui-crosshair__line--y';
   readonly crosshairBadge: 'ui-crosshair__badge';
-  readonly readout: 'ui-readout';
   readonly sel: 'ui-sel';
   readonly selOn: 'ui-sel--on';
   readonly selOff: 'ui-sel--off';
@@ -393,6 +406,56 @@ export declare const cls: {
   readonly srcReviewed: 'ui-src--reviewed';
   readonly srcStale: 'ui-src--stale';
   readonly srcConflict: 'ui-src--conflict';
+  readonly diff: 'ui-diff';
+  readonly diffSplit: 'ui-diff--split';
+  readonly diffPane: 'ui-diff__pane';
+  readonly diffHunk: 'ui-diff__hunk';
+  readonly diffHead: 'ui-diff__head';
+  readonly diffRow: 'ui-diff__row';
+  readonly diffRowAdd: 'ui-diff__row--add';
+  readonly diffRowRemove: 'ui-diff__row--remove';
+  readonly diffRowContext: 'ui-diff__row--context';
+  readonly diffLn: 'ui-diff__ln';
+  readonly diffCode: 'ui-diff__code';
+  readonly code: 'ui-code';
+  readonly codeNumbered: 'ui-code--numbered';
+  readonly codeHead: 'ui-code__head';
+  readonly codeBody: 'ui-code__body';
+  readonly codeLine: 'ui-code__line';
+  readonly codeLineAdd: 'ui-code__line--add';
+  readonly codeLineRemove: 'ui-code__line--remove';
+  readonly codeLineHl: 'ui-code__line--hl';
+  readonly spark: 'ui-spark';
+  readonly sparkDots: 'ui-spark--dots';
+  readonly sparkBar: 'ui-spark__bar';
+  readonly sparkBarAccent: 'ui-spark__bar--accent';
+  readonly sparkBarPos: 'ui-spark__bar--pos';
+  readonly sparkBarNeg: 'ui-spark__bar--neg';
+  readonly sidenote: 'ui-sidenote';
+  readonly marginnote: 'ui-marginnote';
+  readonly sidenoteRef: 'ui-sidenote__ref';
+  readonly textref: 'ui-textref';
+  readonly bullet: 'ui-bullet';
+  readonly bulletMeasure: 'ui-bullet__measure';
+  readonly bulletMeasureAccent: 'ui-bullet__measure--accent';
+  readonly bulletMeasurePos: 'ui-bullet__measure--pos';
+  readonly bulletMeasureNeg: 'ui-bullet__measure--neg';
+  readonly bulletTarget: 'ui-bullet__target';
+  readonly bulletLabel: 'ui-bullet__label';
+  readonly term: 'ui-term';
+  readonly def: 'ui-def';
+  readonly glossary: 'ui-glossary';
+  readonly glossaryTerm: 'ui-glossary__term';
+  readonly glossaryDef: 'ui-glossary__def';
+  readonly toc: 'ui-toc';
+  readonly tocTitle: 'ui-toc__title';
+  readonly tocList: 'ui-toc__list';
+  readonly tocLink: 'ui-toc__link';
+  readonly tree: 'ui-tree';
+  readonly treeBranch: 'ui-tree__branch';
+  readonly treeLeaf: 'ui-tree__leaf';
+  readonly treeSummary: 'ui-tree__summary';
+  readonly treeLabel: 'ui-tree__label';
   readonly state: 'ui-state';
   readonly stateLabel: 'ui-state__label';
   readonly stateDetail: 'ui-state__detail';
@@ -690,6 +753,32 @@ export interface OriginLabelOpts {
   /** Accent-tint the label for AI/model-generated origin (vs a neutral tag). */
   ai?: boolean;
 }
+export interface DiffOpts {
+  /** Two side-by-side `.ui-diff__pane` columns (old | new) instead of the unified view. */
+  split?: boolean;
+}
+export interface DiffRowOpts {
+  /** The host-classified change kind — sets the tint and the +/− gutter glyph. */
+  change?: 'add' | 'remove' | 'context';
+}
+export interface CodeOpts {
+  /** Show the line-number gutter (counts each `.ui-code__line`). */
+  numbered?: boolean;
+}
+export interface CodeLineOpts {
+  /** The host-classified line state — `hl` is a neutral highlight, not a change.
+   *  `remove` matches `ui.diffRow`'s verb (was `del`) so the two change-review
+   *  surfaces share one vocabulary. */
+  change?: 'add' | 'remove' | 'hl';
+}
+export interface SparkBarOpts {
+  /** Emphasise / tone a single bar. The meaning must still be in the spark's aria-label. */
+  tone?: 'accent' | 'pos' | 'neg';
+}
+export interface BulletMeasureOpts {
+  /** Emphasise / tone the measure bar. The meaning must still be in the bullet's aria-label. */
+  tone?: 'accent' | 'pos' | 'neg';
+}
 
 export interface Ui {
   button(opts?: ButtonOpts): string;
@@ -733,9 +822,35 @@ export interface Ui {
   citation(opts?: CitationOpts): string;
   source(opts?: SourceOpts): string;
   provenance(opts?: ProvenanceOpts): string;
+  diff(opts?: DiffOpts): string;
+  diffRow(opts?: DiffRowOpts): string;
+  code(opts?: CodeOpts): string;
+  codeLine(opts?: CodeLineOpts): string;
+  sparkBar(opts?: SparkBarOpts): string;
+  bulletMeasure(opts?: BulletMeasureOpts): string;
   state(opts?: StateOpts): string;
   originLabel(opts?: OriginLabelOpts): string;
 }
 
 export declare const ui: Ui;
 export default ui;
+
+/** Min/max for the value-bearing fills; defaults to 0–100. */
+export interface ValueRangeOpts {
+  min?: number;
+  max?: number;
+}
+/** ARIA + style bundle to spread onto a `ui-meter`/`ui-progress` host. */
+export interface ValueAttrs {
+  role: 'meter' | 'progressbar';
+  'aria-valuenow': number;
+  'aria-valuemin': number;
+  'aria-valuemax': number;
+  style: { '--value': number };
+}
+export interface Attrs {
+  meter(value: number, opts?: ValueRangeOpts): ValueAttrs;
+  progress(value: number, opts?: ValueRangeOpts): ValueAttrs;
+}
+/** Set the painted value AND its ARIA together so they cannot drift. */
+export declare const attrs: Attrs;

package/classes/index.js

@@ -84,6 +84,17 @@ export const cls = Object.freeze({
   dotspinner: 'ui-dotspinner',
   dotspinnerSm: 'ui-dotspinner--sm',
   dotspinnerLg: 'ui-dotspinner--lg',
+  // data-bound dot surfaces (reporting/dashboard family)
+  waffle: 'ui-waffle',
+  activity: 'ui-activity',
+  level: 'ui-level',
+  levelWarn: 'ui-level--warn',
+  levelDanger: 'ui-level--danger',
+  dotgauge: 'ui-dotgauge',
+  readout: 'ui-readout',
+  readoutSpacer: 'ui-readout__spacer',
+  halftone: 'ui-halftone',
+  dotfit: 'ui-dotfit',
   // forms
   field: 'ui-field',
   label: 'ui-label',
@@ -111,7 +122,7 @@ export const cls = Object.freeze({
   alert: 'ui-alert',
   alertTitle: 'ui-alert__title',
   alertBody: 'ui-alert__body',
-  alertDismiss: 'ui-alert__dismiss',
+  alertClose: 'ui-alert__close',
   alertAccent: 'ui-alert--accent',
   alertSuccess: 'ui-alert--success',
   alertWarning: 'ui-alert--warning',
@@ -135,6 +146,9 @@ export const cls = Object.freeze({
   progressIndeterminate: 'ui-progress--indeterminate',
   meter: 'ui-meter',
   meterFill: 'ui-meter__fill',
+  meterRow: 'ui-meter__row',
+  meterLabel: 'ui-meter__label',
+  meterValue: 'ui-meter__value',
   meterAccent: 'ui-meter--accent',
   meterSuccess: 'ui-meter--success',
   meterWarning: 'ui-meter--warning',
@@ -196,13 +210,15 @@ export const cls = Object.freeze({
   tableDense: 'ui-table--dense',
   tableComfortable: 'ui-table--comfortable',
   tableLined: 'ui-table--lined',
+  tableBreakAnywhere: 'ui-table--break-anywhere',
   tableWrap: 'ui-table-wrap',
+  // Loading state goes on the WRAP, so the modifier is named for the wrap (C19).
+  tableLoading: 'ui-table-wrap--loading',
   tableEmpty: 'ui-table__empty',
   tableSort: 'ui-table__sort',
   tableSelect: 'ui-table__select',
   tableToolbar: 'ui-table__toolbar',
   tableSelectable: 'ui-table--selectable',
-  tableLoading: 'ui-table--loading',
   // shell / layout
   panel: 'ui-panel',
   panelHead: 'ui-panel__head',
@@ -414,6 +430,65 @@ export const cls = Object.freeze({
   srcReviewed: 'ui-src--reviewed',
   srcStale: 'ui-src--stale',
   srcConflict: 'ui-src--conflict',
+  // diff — line/row change-review grammar (css/diff.css)
+  diff: 'ui-diff',
+  diffSplit: 'ui-diff--split',
+  diffPane: 'ui-diff__pane',
+  diffHunk: 'ui-diff__hunk',
+  diffHead: 'ui-diff__head',
+  diffRow: 'ui-diff__row',
+  diffRowAdd: 'ui-diff__row--add',
+  diffRowRemove: 'ui-diff__row--remove',
+  diffRowContext: 'ui-diff__row--context',
+  diffLn: 'ui-diff__ln',
+  diffCode: 'ui-diff__code',
+  // code — fenced-code evidence chrome (css/code.css)
+  code: 'ui-code',
+  codeNumbered: 'ui-code--numbered',
+  codeHead: 'ui-code__head',
+  codeBody: 'ui-code__body',
+  codeLine: 'ui-code__line',
+  codeLineAdd: 'ui-code__line--add',
+  codeLineRemove: 'ui-code__line--remove',
+  codeLineHl: 'ui-code__line--hl',
+  // spark — inline datawords / microcharts (css/spark.css)
+  spark: 'ui-spark',
+  sparkDots: 'ui-spark--dots',
+  sparkBar: 'ui-spark__bar',
+  sparkBarAccent: 'ui-spark__bar--accent',
+  sparkBarPos: 'ui-spark__bar--pos',
+  sparkBarNeg: 'ui-spark__bar--neg',
+  // sidenote — Tufte margin notes (css/sidenote.css)
+  sidenote: 'ui-sidenote',
+  marginnote: 'ui-marginnote',
+  sidenoteRef: 'ui-sidenote__ref',
+  // textref — deep-link-to-cited-text provenance link (css/textref.css)
+  textref: 'ui-textref',
+  // bullet — Stephen-Few bullet graph: measure vs target vs bands (css/bullet.css)
+  bullet: 'ui-bullet',
+  bulletMeasure: 'ui-bullet__measure',
+  bulletMeasureAccent: 'ui-bullet__measure--accent',
+  bulletMeasurePos: 'ui-bullet__measure--pos',
+  bulletMeasureNeg: 'ui-bullet__measure--neg',
+  bulletTarget: 'ui-bullet__target',
+  bulletLabel: 'ui-bullet__label',
+  // term — inline glossary term + definition popover + glossary <dl> (css/term.css)
+  term: 'ui-term',
+  def: 'ui-def',
+  glossary: 'ui-glossary',
+  glossaryTerm: 'ui-glossary__term',
+  glossaryDef: 'ui-glossary__def',
+  // toc — scrollspy table-of-contents rail (css/toc.css)
+  toc: 'ui-toc',
+  tocTitle: 'ui-toc__title',
+  tocList: 'ui-toc__list',
+  tocLink: 'ui-toc__link',
+  // tree — hierarchy outline on nested <details> (css/tree.css)
+  tree: 'ui-tree',
+  treeBranch: 'ui-tree__branch',
+  treeLeaf: 'ui-tree__leaf',
+  treeSummary: 'ui-tree__summary',
+  treeLabel: 'ui-tree__label',
   // lifecycle / system state (css/state.css)
   state: 'ui-state',
   stateLabel: 'ui-state__label',
@@ -557,6 +632,95 @@ const srcTone = (state) =>
     conflict: cls.srcConflict,
   })[state] || '';
 
+// Component tone → modifier class. Same object-literal idiom as srcTone/stateTone
+// (still grep-by-class-name; the modifier set differs per component). (Q9.)
+//
+// The set differs PER COMPONENT on purpose — `muted` is a badge/num tone, not an
+// alert/toast/meter/dot one — so a caller extrapolating a universal tone (e.g.
+// `ui.alert({ tone: 'muted' })`) used to get a silent no-op: a bare, untoned
+// element with no signal that the tone was dropped. Warn at dev time instead, so
+// that "validates-but-no-ops" trap is loud rather than invisible. An omitted tone
+// is fine (returns no modifier). (component audit C12.)
+const toneClass = (component, map, tone) => {
+  if (tone == null) return '';
+  const hit = map[tone];
+  if (!hit && typeof console !== 'undefined') {
+    console.warn(
+      `[bronto] ui.${component}(): "${tone}" is not a ${component} tone (use one of: ${Object.keys(map).join(', ')}).`,
+    );
+  }
+  return hit || '';
+};
+
+const badgeTone = (tone) =>
+  toneClass(
+    'badge',
+    {
+      accent: cls.badgeAccent,
+      success: cls.badgeSuccess,
+      warning: cls.badgeWarning,
+      danger: cls.badgeDanger,
+      info: cls.badgeInfo,
+      muted: cls.badgeMuted,
+    },
+    tone,
+  );
+
+const numTone = (tone) =>
+  toneClass('num', { pos: cls.numPos, neg: cls.numNeg, muted: cls.numMuted }, tone);
+
+const dotTone = (tone) =>
+  toneClass(
+    'dot',
+    {
+      accent: cls.dotAccent,
+      success: cls.dotSuccess,
+      warning: cls.dotWarning,
+      danger: cls.dotDanger,
+      info: cls.dotInfo,
+    },
+    tone,
+  );
+
+const alertTone = (tone) =>
+  toneClass(
+    'alert',
+    {
+      accent: cls.alertAccent,
+      success: cls.alertSuccess,
+      warning: cls.alertWarning,
+      danger: cls.alertDanger,
+      info: cls.alertInfo,
+    },
+    tone,
+  );
+
+const toastTone = (tone) =>
+  toneClass(
+    'toast',
+    {
+      accent: cls.toastAccent,
+      success: cls.toastSuccess,
+      warning: cls.toastWarning,
+      danger: cls.toastDanger,
+      info: cls.toastInfo,
+    },
+    tone,
+  );
+
+const meterTone = (tone) =>
+  toneClass(
+    'meter',
+    {
+      accent: cls.meterAccent,
+      success: cls.meterSuccess,
+      warning: cls.meterWarning,
+      danger: cls.meterDanger,
+      info: cls.meterInfo,
+    },
+    tone,
+  );
+
 export const ui = {
   button: ({ variant, icon, size } = {}) =>
     j(
@@ -570,24 +734,8 @@ export const ui = {
     ),
   card: ({ accent, interactive } = {}) =>
     j(cls.card, accent && cls.cardAccent, interactive && cls.cardInteractive),
-  badge: ({ tone, dot } = {}) =>
-    j(
-      cls.badge,
-      tone === 'accent' && cls.badgeAccent,
-      tone === 'success' && cls.badgeSuccess,
-      tone === 'warning' && cls.badgeWarning,
-      tone === 'danger' && cls.badgeDanger,
-      tone === 'info' && cls.badgeInfo,
-      tone === 'muted' && cls.badgeMuted,
-      dot && cls.badgeDot,
-    ),
-  num: ({ tone } = {}) =>
-    j(
-      cls.num,
-      tone === 'pos' && cls.numPos,
-      tone === 'neg' && cls.numNeg,
-      tone === 'muted' && cls.numMuted,
-    ),
+  badge: ({ tone, dot } = {}) => j(cls.badge, badgeTone(tone), dot && cls.badgeDot),
+  num: ({ tone } = {}) => j(cls.num, numTone(tone)),
   delta: ({ dir, invert } = {}) =>
     j(
       cls.delta,
@@ -599,57 +747,25 @@ export const ui = {
   compare: ({ cols } = {}) => j(cls.compare, cols === 2 && cls.compare2up),
   chip: ({ accent } = {}) => j(cls.chip, accent && cls.chipAccent),
   link: ({ arrow, cta } = {}) => j(cls.link, arrow && cls.linkArrow, cta && cls.linkCta),
-  dot: ({ tone, live } = {}) =>
-    j(
-      cls.dot,
-      tone === 'accent' && cls.dotAccent,
-      tone === 'success' && cls.dotSuccess,
-      tone === 'warning' && cls.dotWarning,
-      tone === 'danger' && cls.dotDanger,
-      tone === 'info' && cls.dotInfo,
-      live && cls.dotLive,
-    ),
+  dot: ({ tone, live } = {}) => j(cls.dot, dotTone(tone), live && cls.dotLive),
   dotgrid: ({ accent, dense } = {}) =>
     j(cls.dotgrid, accent && cls.dotgridAccent, dense && cls.dotgridDense),
-  table: ({ density, lined } = {}) =>
+  table: ({ density, lined, breakAnywhere } = {}) =>
     j(
       cls.table,
       density === 'dense' && cls.tableDense,
       density === 'comfortable' && cls.tableComfortable,
       lined && cls.tableLined,
+      breakAnywhere && cls.tableBreakAnywhere,
     ),
   eyebrow: ({ muted, sm } = {}) => j(cls.eyebrow, muted && cls.eyebrowMuted, sm && cls.eyebrowSm),
   hint: ({ error } = {}) => j(cls.hint, error && cls.hintError),
   cluster: ({ between } = {}) => j(cls.cluster, between && cls.clusterBetween),
   stagger: ({ auto } = {}) => j(cls.stagger, auto && cls.staggerAuto),
-  alert: ({ tone } = {}) =>
-    j(
-      cls.alert,
-      tone === 'accent' && cls.alertAccent,
-      tone === 'success' && cls.alertSuccess,
-      tone === 'warning' && cls.alertWarning,
-      tone === 'danger' && cls.alertDanger,
-      tone === 'info' && cls.alertInfo,
-    ),
-  toast: ({ tone } = {}) =>
-    j(
-      cls.toast,
-      tone === 'accent' && cls.toastAccent,
-      tone === 'success' && cls.toastSuccess,
-      tone === 'warning' && cls.toastWarning,
-      tone === 'danger' && cls.toastDanger,
-      tone === 'info' && cls.toastInfo,
-    ),
+  alert: ({ tone } = {}) => j(cls.alert, alertTone(tone)),
+  toast: ({ tone } = {}) => j(cls.toast, toastTone(tone)),
   progress: ({ indeterminate } = {}) => j(cls.progress, indeterminate && cls.progressIndeterminate),
-  meter: ({ tone } = {}) =>
-    j(
-      cls.meter,
-      tone === 'accent' && cls.meterAccent,
-      tone === 'success' && cls.meterSuccess,
-      tone === 'warning' && cls.meterWarning,
-      tone === 'danger' && cls.meterDanger,
-      tone === 'info' && cls.meterInfo,
-    ),
+  meter: ({ tone } = {}) => j(cls.meter, meterTone(tone)),
   dotspinner: ({ size } = {}) =>
     j(cls.dotspinner, size === 'sm' && cls.dotspinnerSm, size === 'lg' && cls.dotspinnerLg),
   dotbar: ({ indeterminate } = {}) => j(cls.dotbar, indeterminate && cls.dotbarIndeterminate),
@@ -677,14 +793,9 @@ export const ui = {
   legendSwatch: ({ series, shape } = {}) =>
     j(
       cls.legendSwatch,
-      series === 1 && cls.legendSwatch1,
-      series === 2 && cls.legendSwatch2,
-      series === 3 && cls.legendSwatch3,
-      series === 4 && cls.legendSwatch4,
-      series === 5 && cls.legendSwatch5,
-      series === 6 && cls.legendSwatch6,
-      series === 7 && cls.legendSwatch7,
-      series === 8 && cls.legendSwatch8,
+      // Series 1–8 map to ui-legend__swatch--N; the explicit bounds-check keeps a
+      // 0/9/non-integer from coining a class the stylesheet never defines. (Q9.)
+      Number.isInteger(series) && series >= 1 && series <= 8 && cls[`legendSwatch${series}`],
       shape === 'circle' && cls.legendSwatchCircle,
       shape === 'line' && cls.legendSwatchLine,
     ),
@@ -765,8 +876,95 @@ export const ui = {
   citation: ({ chip, state } = {}) => j(cls.citation, chip && cls.citationChip, srcTone(state)),
   source: ({ state } = {}) => j(cls.sourceCard, srcTone(state)),
   provenance: ({ state } = {}) => j(cls.provenance, srcTone(state)),
+  diff: ({ split } = {}) => j(cls.diff, split && cls.diffSplit),
+  diffRow: ({ change } = {}) =>
+    j(
+      cls.diffRow,
+      change === 'add' && cls.diffRowAdd,
+      change === 'remove' && cls.diffRowRemove,
+      change === 'context' && cls.diffRowContext,
+    ),
+  code: ({ numbered } = {}) => j(cls.code, numbered && cls.codeNumbered),
+  codeLine: ({ change } = {}) =>
+    j(
+      cls.codeLine,
+      change === 'add' && cls.codeLineAdd,
+      change === 'remove' && cls.codeLineRemove,
+      change === 'hl' && cls.codeLineHl,
+    ),
+  sparkBar: ({ tone } = {}) =>
+    j(
+      cls.sparkBar,
+      tone === 'accent' && cls.sparkBarAccent,
+      tone === 'pos' && cls.sparkBarPos,
+      tone === 'neg' && cls.sparkBarNeg,
+    ),
+  bulletMeasure: ({ tone } = {}) =>
+    j(
+      cls.bulletMeasure,
+      tone === 'accent' && cls.bulletMeasureAccent,
+      tone === 'pos' && cls.bulletMeasurePos,
+      tone === 'neg' && cls.bulletMeasureNeg,
+    ),
   state: ({ state, busy } = {}) => j(cls.state, stateTone(state), busy && cls.stateBusy),
   originLabel: ({ ai } = {}) => j(cls.originLabel, ai && cls.originLabelAi),
 };
 
+// Attribute + style bundle for the data-bearing fills (`ui-meter`/`ui-progress`).
+// The class string alone paints a 0-width, unannounced bar: the fill width is a
+// UNITLESS `--value` (0–100) and AT needs role + aria-valuenow/min/max. This sets
+// the painted value and its announced value together so they can't drift, and
+// normalizes an arbitrary {min,max} to the 0–100 `--value` the CSS expects while
+// keeping aria-valuenow in the caller's real units. (component audit C8.)
+// `busyWhenIndeterminate` — a progressbar advertises aria-busy when its value is
+// unknown; a meter is never indeterminate so it passes false. (Kept a boolean
+// flag rather than testing the role string, so check:recipe-types doesn't read it
+// as a recipe option literal.)
+const valueAttrs = (role, value, min, max, busyWhenIndeterminate) => {
+  const lo = Number(min);
+  const hi = Number(max);
+  const raw = Number(value);
+  // Indeterminate: an omitted/unknown value (attrs.progress() with no argument).
+  // ARIA requires aria-valuenow be OMITTED here — emitting 0 announces "0%",
+  // indistinguishable from a real stalled-at-zero bar. A progressbar instead
+  // advertises aria-busy; a meter has no indeterminate state, so a non-finite
+  // value there is a caller error we still fail safe on by omitting the
+  // misleading 0. Pair with `ui.progress({ indeterminate: true })` for the CSS
+  // sweep. (component audit C9.)
+  if (!Number.isFinite(raw)) {
+    return busyWhenIndeterminate ? { role, 'aria-busy': 'true' } : { role };
+  }
+  const now = Math.min(hi, Math.max(lo, raw));
+  const pct = hi > lo ? ((now - lo) / (hi - lo)) * 100 : 0;
+  return {
+    role,
+    'aria-valuenow': now,
+    'aria-valuemin': lo,
+    'aria-valuemax': hi,
+    style: { '--value': Math.round(pct * 100) / 100 },
+  };
+};
+
+/**
+ * ARIA + style bundles for the value-bearing fills. Spread onto the host:
+ *   <div class={ui.meter({ tone: 'warning' })} {...attrs.meter(72)}>
+ *     <span class={cls.meterFill} />
+ *   </div>
+ * `value` is in your own units; pass `{ min, max }` (default 0–100) and the
+ * `--value` width is normalized for you. Call `attrs.progress()` with no value
+ * for an indeterminate bar (omits aria-valuenow, sets aria-busy). (audit C9.)
+ *
+ * `attrs.dotbar(value)` is the segmented analogue of `attrs.progress`: a
+ * determinate `.ui-dotbar` carries the same progress data as `.ui-progress` but,
+ * without this, was eight empty `<span>`s to AT (the segments are decorative —
+ * mark them `aria-hidden`). Same progressbar role + aria-valuenow/min/max;
+ * call with no value for the indeterminate sweep. (component audit C10.)
+ */
+export const attrs = Object.freeze({
+  meter: (value, { min = 0, max = 100 } = {}) => valueAttrs('meter', value, min, max, false),
+  progress: (value, { min = 0, max = 100 } = {}) =>
+    valueAttrs('progressbar', value, min, max, true),
+  dotbar: (value, { min = 0, max = 100 } = {}) => valueAttrs('progressbar', value, min, max, true),
+});
+
 export default ui;

package/connectors/index.d.ts

@@ -1,5 +1,6 @@
 export function finite(name: any, value: any, fallback: any): any;
 export function dimension(name: any, value: any, fallback: any): any;
+export function roundNumber(value: any): number;
 export function fmt(value: any): string;
 export function point(x: any, y: any): string;
 export function clamp(value: any, min: any, max: any): any;
@@ -67,6 +68,17 @@ export function arrowHead(p: Point, angle: number, size?: number, spread?: numbe
  * @returns {string}
  */
 export function dotMark(p: Point, radius?: number): string;
+/**
+ * An axis-aligned rectangle path from its corners (callers derive the corners
+ * from a centre or a top-left as they need). Shared by the annotation
+ * rect/band and evidence-marker subjects. (code-quality audit Q5.)
+ * @param {number} left
+ * @param {number} top
+ * @param {number} right
+ * @param {number} bottom
+ * @returns {string}
+ */
+export function rectPath(left: number, top: number, right: number, bottom: number): string;
 /**
  * Pick facing edges from the rects' relative centres.
  * @param {Rect} fromRect

package/connectors/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":"AAkDA,kEAIC;AAED,qEAIC;AAED,wCAGC;AAED,8CAEC;AAID,2DAGC;AAED;;;;;GAKG;AACH,kCAJW,IAAI,SACJ,IAAI,GACF,KAAK,CAoBjB;AAED;;;;;GAKG;AACH,mCAJW,KAAK,MACL,KAAK,GACH,MAAM,CAOlB;AAED;;;;;GAKG;AACH,mCAJW,KAAK,MACL,KAAK,GACH,MAAM,CAOlB;AAED;;;;;;GAMG;AACH,gCALW,KAAK,MACL,KAAK,SACL;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACd,MAAM,CAgBlB;AAED;;;;;;GAMG;AACH,gCALW,KAAK,MACL,KAAK,SACL;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACpB,MAAM,CAclB;AAED;;;;GAIG;AACH,qCAHW,oBAAoB,GAClB,MAAM,CAOlB;AAED;;;;;;;;GAQG;AACH,6BAPW,KAAK,SACL,MAAM,SACN,MAAM,WACN,MAAM,GAEJ,MAAM,CAalB;AAED;;;;;GAKG;AACH,2BAJW,KAAK,WACL,MAAM,GACJ,MAAM,CAUlB;AAED;;;;;GAKG;AACH,oCAJW,IAAI,UACJ,IAAI,GACF;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,EAAE,EAAE,IAAI,CAAA;CAAE,CAWpC;AAED;;;;;;;;GAQG;AACH,sCALW,KAAK,MACL,KAAK,UACL,cAAc,GACZ,MAAM,CAQlB;AAED;;;;;;GAMG;AACH,oCAHW,mBAAmB,GACjB,kBAAkB,CAW9B;AAlRD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAMH,wBAAyB,IAAI,CAAC;oBAhCjB;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE;mBACxB;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;mBACvD,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ;6BAC9C,UAAU,GAAG,OAAO,GAAG,OAAO;;UAG7B,KAAK;QACL,KAAK;;;;;;;;;;;;cAML,IAAI;YACJ,IAAI;;;;;;;;;;;;;;OAQJ,MAAM;UACN,KAAK;QACL,KAAK;;;;WACL,MAAM"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":"AAkDA,kEAIC;AAED,qEAIC;AAKD,gDAGC;AAED,wCAEC;AAED,8CAEC;AAID,2DAGC;AAED;;;;;GAKG;AACH,kCAJW,IAAI,SACJ,IAAI,GACF,KAAK,CAoBjB;AAED;;;;;GAKG;AACH,mCAJW,KAAK,MACL,KAAK,GACH,MAAM,CAOlB;AAED;;;;;GAKG;AACH,mCAJW,KAAK,MACL,KAAK,GACH,MAAM,CAOlB;AAED;;;;;;GAMG;AACH,gCALW,KAAK,MACL,KAAK,SACL;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACd,MAAM,CAgBlB;AAED;;;;;;GAMG;AACH,gCALW,KAAK,MACL,KAAK,SACL;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACpB,MAAM,CAclB;AAED;;;;GAIG;AACH,qCAHW,oBAAoB,GAClB,MAAM,CAOlB;AAED;;;;;;;;GAQG;AACH,6BAPW,KAAK,SACL,MAAM,SACN,MAAM,WACN,MAAM,GAEJ,MAAM,CAalB;AAED;;;;;GAKG;AACH,2BAJW,KAAK,WACL,MAAM,GACJ,MAAM,CAUlB;AAED;;;;;;;;;GASG;AACH,+BANW,MAAM,OACN,MAAM,SACN,MAAM,UACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;GAKG;AACH,oCAJW,IAAI,UACJ,IAAI,GACF;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,EAAE,EAAE,IAAI,CAAA;CAAE,CAWpC;AAED;;;;;;;;GAQG;AACH,sCALW,KAAK,MACL,KAAK,UACL,cAAc,GACZ,MAAM,CAQlB;AAED;;;;;;GAMG;AACH,oCAHW,mBAAmB,GACjB,kBAAkB,CAW9B;AAvSD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAMH,wBAAyB,IAAI,CAAC;oBAhCjB;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE;mBACxB;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;mBACvD,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ;6BAC9C,UAAU,GAAG,OAAO,GAAG,OAAO;;UAG7B,KAAK;QACL,KAAK;;;;;;;;;;;;cAML,IAAI;YACJ,IAAI;;;;;;;;;;;;;;OAQJ,MAAM;UACN,KAAK;QACL,KAAK;;;;WACL,MAAM"}

package/connectors/index.js

@@ -60,9 +60,16 @@ export function dimension(name, value, fallback) {
   return v;
 }
 
-export function fmt(value) {
+// Round to PRECISION, normalising -0 → 0, and return the NUMBER (the numeric
+// core `fmt` stringifies). Shared with the annotations layer for the rounded
+// coordinates it echoes back to the host. (code-quality audit Q5.)
+export function roundNumber(value) {
   const rounded = Math.round((Object.is(value, -0) ? 0 : value) * PRECISION) / PRECISION;
-  return String(Object.is(rounded, -0) ? 0 : rounded);
+  return Object.is(rounded, -0) ? 0 : rounded;
+}
+
+export function fmt(value) {
+  return String(roundNumber(value));
 }
 
 export function point(x, y) {
@@ -222,6 +229,20 @@ export function dotMark(p, radius = 3) {
   )} 0 1 1 ${point(px, py - r)}Z`;
 }
 
+/**
+ * An axis-aligned rectangle path from its corners (callers derive the corners
+ * from a centre or a top-left as they need). Shared by the annotation
+ * rect/band and evidence-marker subjects. (code-quality audit Q5.)
+ * @param {number} left
+ * @param {number} top
+ * @param {number} right
+ * @param {number} bottom
+ * @returns {string}
+ */
+export function rectPath(left, top, right, bottom) {
+  return `M${point(left, top)}H${fmt(right)}V${fmt(bottom)}H${fmt(left)}Z`;
+}
+
 /**
  * Pick facing edges from the rects' relative centres.
  * @param {Rect} fromRect