npm - @ponchia/ui - Versions diffs - 0.4.0 → 0.5.0 - Mend

@ponchia/ui 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (123) hide show

package/CHANGELOG.md +352 -12
package/MIGRATIONS.json +92 -0
package/README.md +27 -17
package/annotations/index.d.ts +280 -0
package/annotations/index.js +522 -0
package/behaviors/carousel.js +197 -0
package/behaviors/combobox.js +195 -0
package/behaviors/command.js +187 -0
package/behaviors/connectors.js +96 -0
package/behaviors/crosshair.js +58 -0
package/behaviors/dialog.js +73 -0
package/behaviors/disclosure.js +25 -0
package/behaviors/dismissible.js +24 -0
package/behaviors/forms.js +158 -0
package/behaviors/glyph.js +109 -0
package/behaviors/index.d.ts +82 -1
package/behaviors/index.js +18 -1336
package/behaviors/internal.js +50 -0
package/behaviors/legend.js +46 -0
package/behaviors/menu.js +46 -0
package/behaviors/popover.js +108 -0
package/behaviors/spotlight.js +53 -0
package/behaviors/table.js +109 -0
package/behaviors/tabs.js +103 -0
package/behaviors/theme.js +82 -0
package/behaviors/toast.js +152 -0
package/classes/index.d.ts +318 -0
package/classes/index.js +352 -0
package/classes/vscode.css-custom-data.json +18 -14
package/connectors/index.d.ts +71 -0
package/connectors/index.js +179 -0
package/css/analytical.css +21 -0
package/css/annotations.css +292 -0
package/css/command.css +97 -0
package/css/connectors.css +93 -0
package/css/crosshair.css +100 -0
package/css/disclosure.css +29 -0
package/css/dots.css +2 -0
package/css/feedback.css +104 -0
package/css/fonts.css +11 -7
package/css/generated.css +117 -0
package/css/legend.css +268 -0
package/css/marks.css +144 -0
package/css/motion.css +88 -0
package/css/overlay.css +52 -1
package/css/primitives.css +18 -0
package/css/report.css +363 -0
package/css/selection.css +46 -0
package/css/sources.css +179 -0
package/css/spotlight.css +104 -0
package/css/state.css +121 -0
package/css/tokens.css +78 -60
package/css/workbench.css +83 -0
package/dist/bronto.css +1 -1
package/dist/css/analytical.css +1 -0
package/dist/css/annotations.css +1 -0
package/dist/css/command.css +1 -0
package/dist/css/connectors.css +1 -0
package/dist/css/crosshair.css +1 -0
package/dist/css/disclosure.css +1 -1
package/dist/css/dots.css +1 -1
package/dist/css/feedback.css +1 -1
package/dist/css/fonts.css +1 -1
package/dist/css/generated.css +1 -0
package/dist/css/legend.css +1 -0
package/dist/css/marks.css +1 -0
package/dist/css/motion.css +1 -1
package/dist/css/overlay.css +1 -1
package/dist/css/primitives.css +1 -1
package/dist/css/report.css +1 -0
package/dist/css/selection.css +1 -0
package/dist/css/sources.css +1 -0
package/dist/css/spotlight.css +1 -0
package/dist/css/state.css +1 -0
package/dist/css/tokens.css +1 -1
package/dist/css/workbench.css +1 -0
package/docs/adr/0001-color-system.md +26 -27
package/docs/adr/0002-scope-and-2026-baseline.md +104 -0
package/docs/adr/0003-theme-model.md +97 -0
package/docs/annotations.md +345 -0
package/docs/architecture.md +202 -0
package/docs/command.md +95 -0
package/docs/connectors.md +91 -0
package/docs/contrast.md +42 -42
package/docs/crosshair.md +63 -0
package/docs/generated.md +91 -0
package/docs/legends.md +168 -0
package/docs/marks.md +86 -0
package/docs/reference.md +418 -15
package/docs/reporting.md +305 -0
package/docs/selection.md +40 -0
package/docs/sources.md +110 -0
package/docs/spotlight.md +78 -0
package/docs/stability.md +52 -0
package/docs/state.md +85 -0
package/docs/theming.md +18 -6
package/docs/usage.md +43 -3
package/docs/workbench.md +72 -0
package/fonts/doto-400.woff2 +0 -0
package/fonts/doto-500.woff2 +0 -0
package/fonts/doto-600.woff2 +0 -0
package/fonts/doto-700.woff2 +0 -0
package/fonts/doto-800.woff2 +0 -0
package/fonts/doto-900.woff2 +0 -0
package/llms.txt +288 -8
package/package.json +95 -5
package/qwik/index.d.ts +60 -0
package/qwik/index.js +149 -0
package/react/index.d.ts +40 -14
package/react/index.js +32 -5
package/solid/index.d.ts +40 -14
package/solid/index.js +31 -3
package/tokens/index.d.ts +3 -3
package/tokens/index.js +25 -19
package/tokens/index.json +32 -28
package/tokens/resolved.json +34 -32
package/tokens/tokens.dtcg.json +22 -14
package/fonts/doto-400.ttf +0 -0
package/fonts/doto-500.ttf +0 -0
package/fonts/doto-600.ttf +0 -0
package/fonts/doto-700.ttf +0 -0
package/fonts/doto-800.ttf +0 -0
package/fonts/doto-900.ttf +0 -0

package/behaviors/toast.js ADDED Viewed

@@ -0,0 +1,152 @@
+import { hasDom, noop } from './internal.js';
+// First-toast deferral queue. The very first toast on a brand-new stack
+// is appended next frame so AT observes the empty aria-live region
+// before its first child. Any further toasts created *before* that frame
+// flushes are queued behind it so call order (FIFO) is preserved instead
+// of a synchronous later toast jumping ahead of the deferred first one.
+const toastQueue = [];
+let toastFlushScheduled = false;
+function toastStack(isAssertive) {
+  const stackSel = isAssertive
+    ? '.ui-toast-stack--assertive'
+    : '.ui-toast-stack:not(.ui-toast-stack--assertive)';
+  let stack = document.querySelector(stackSel);
+  const fresh = !stack;
+  if (!stack) {
+    stack = document.createElement('div');
+    stack.className = isAssertive ? 'ui-toast-stack ui-toast-stack--assertive' : 'ui-toast-stack';
+    stack.setAttribute('aria-live', isAssertive ? 'assertive' : 'polite');
+    if (isAssertive) stack.setAttribute('role', 'alert');
+    document.body.appendChild(stack);
+  }
+  return { stack, fresh };
+}
+function enqueueToast(place, freshStack) {
+  const canDefer = typeof requestAnimationFrame === 'function';
+  if (freshStack && canDefer) {
+    toastQueue.push(place);
+    toastFlushScheduled = true;
+    requestAnimationFrame(() => {
+      toastFlushScheduled = false;
+      for (const fn of toastQueue.splice(0)) fn();
+    });
+  } else if (toastFlushScheduled) {
+    toastQueue.push(place);
+  } else {
+    place();
+  }
+}
+function toastElement(message, { tone, title }) {
+  const el = document.createElement('div');
+  el.className = tone ? `ui-toast ui-toast--${tone}` : 'ui-toast';
+  // No per-item role: the stack itself is the live region; a nested
+  // live region risks double announcement in some SRs.
+  if (title) {
+    const t = document.createElement('p');
+    t.className = 'ui-toast__title';
+    t.textContent = title;
+    el.appendChild(t);
+  }
+  const body = document.createElement('div');
+  body.textContent = message;
+  el.appendChild(body);
+  return el;
+}
+// Remove a toast, animating its exit when — and only when — a transition
+// is actually in effect. Detached nodes, reduced-motion, and the no-CSS
+// test/SSR env all resolve to instant removal, so the dismiss contract
+// (toast gone now, the aria-live stack stays resident) is unchanged there;
+// a real browser with motion gets the CSS `.is-leaving` fade-out, with a
+// timeout fallback so an interrupted/never-firing transitionend can't strand
+// a toast in the live region.
+function removeToast(el) {
+  const reduce =
+    typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+  const cs =
+    !reduce && el.isConnected && typeof getComputedStyle === 'function'
+      ? getComputedStyle(el)
+      : null;
+  const dur = cs ? parseFloat(cs.transitionDuration) || 0 : 0;
+  if (dur <= 0) {
+    el.remove();
+    return;
+  }
+  el.classList.add('is-leaving');
+  let done = false;
+  const finish = () => {
+    if (done) return;
+    done = true;
+    el.remove();
+  };
+  el.addEventListener('transitionend', finish, { once: true });
+  const timer = setTimeout(finish, dur * 1000 + 120);
+  timer?.unref?.(); // don't keep a Node test process alive
+}
+function addToastClose(el, dismiss) {
+  const close = document.createElement('button');
+  close.type = 'button';
+  close.className = 'ui-toast__close';
+  close.setAttribute('aria-label', 'Dismiss');
+  close.addEventListener('click', dismiss);
+  el.appendChild(close);
+}
+/**
+ * Push a transient toast into a shared, screen-anchored stack. The stack
+ * is the `aria-live="polite"` region: it is created once, appended to
+ * <body>, and **kept resident even when empty** so the live region is
+ * always present before content is inserted (a freshly created region
+ * that receives its first child in the same tick is not reliably
+ * announced by VoiceOver/NVDA). On first creation the empty region is
+ * inserted and the toast is appended on the next frame for the same
+ * reason. `tone` is accent/success/warning/danger/info; `title` is an
+ * optional uppercase label; `duration` ms before auto-dismiss (0 keeps
+ * it until dismissed). Returns a function that dismisses the toast
+ * early. SSR-safe (no-op).
+ */
+export function toast(message, { tone, title, duration = 4000, assertive, closable } = {}) {
+  if (!hasDom()) return noop;
+  // Errors must interrupt: danger toasts (or an explicit `assertive`)
+  // go to a SEPARATE assertive region so they announce immediately,
+  // while status toasts stay polite. Two regions — not a per-item
+  // role=alert nested in a polite parent — avoids the double
+  // announcement that nesting causes in some screen readers.
+  const isAssertive = assertive ?? tone === 'danger';
+  const { stack, fresh: freshStack } = toastStack(isAssertive);
+  const el = toastElement(message, { tone, title });
+  // Append after a frame the *first* time so the empty live region is
+  // observed by AT before its first child arrives; once the region has
+  // been observed, later toasts append synchronously.
+  let dismissed = false;
+  // `dismissed` guard: a toast dismissed before its frame (e.g.
+  // duration:0 + immediate dismiss) must NOT be resurrected into the
+  // persistent aria-live region.
+  const place = () => {
+    if (!dismissed) stack.appendChild(el);
+  };
+  enqueueToast(place, freshStack);
+  let timer;
+  const dismiss = () => {
+    if (dismissed) return;
+    dismissed = true;
+    if (timer) clearTimeout(timer);
+    removeToast(el);
+    // The stack is a persistent live region — never removed on drain, so
+    // the next toast does not recreate (and thus mis-announce) it.
+  };
+  // A sticky toast (duration:0) is unusable without a manual close, so
+  // it gets a dismiss affordance by default; any toast can opt in via
+  // `closable`. The button carries no text node (glyph is a CSS
+  // ::before) so the toast's announced/textContent stays the message.
+  if (closable ?? duration === 0) addToastClose(el, dismiss);
+  if (duration > 0) timer = setTimeout(dismiss, duration);
+  return dismiss;
+}

package/classes/index.d.ts CHANGED Viewed

@@ -232,7 +232,215 @@ export declare const cls: {
   readonly timeline: 'ui-timeline';
   readonly timelineItem: 'ui-timeline__item';
   readonly timelineTime: 'ui-timeline__time';
+  readonly report: 'ui-report';
+  readonly reportCompact: 'ui-report--compact';
+  readonly reportNumbered: 'ui-report--numbered';
+  readonly reportCover: 'ui-report__cover';
+  readonly reportCoverCompact: 'ui-report__cover--compact';
+  readonly reportHeader: 'ui-report__header';
+  readonly reportTitle: 'ui-report__title';
+  readonly reportSubtitle: 'ui-report__subtitle';
+  readonly reportMeta: 'ui-report__meta';
+  readonly reportToc: 'ui-report__toc';
+  readonly reportSummary: 'ui-report__summary';
+  readonly reportSection: 'ui-report__section';
+  readonly reportSectionUnnumbered: 'ui-report__section--unnumbered';
+  readonly reportSectionHead: 'ui-report__section-head';
+  readonly reportFinding: 'ui-report__finding';
+  readonly reportEvidence: 'ui-report__evidence';
+  readonly reportFigure: 'ui-report__figure';
+  readonly reportCaption: 'ui-report__caption';
+  readonly reportSources: 'ui-report__sources';
+  readonly reportAppendix: 'ui-report__appendix';
+  readonly reportFootnotes: 'ui-report__footnotes';
+  readonly chart: 'ui-chart';
+  readonly chartCaption: 'ui-chart__caption';
+  readonly chartPlot: 'ui-chart__plot';
+  readonly chartBar: 'ui-chart__bar';
+  readonly chartLabel: 'ui-chart__label';
+  readonly chartTrack: 'ui-chart__track';
+  readonly chartFill: 'ui-chart__fill';
+  readonly chartFallback: 'ui-chart__fallback';
+  readonly legend: 'ui-legend';
+  readonly legendVertical: 'ui-legend--vertical';
+  readonly legendCompact: 'ui-legend--compact';
+  readonly legendGradient: 'ui-legend--gradient';
+  readonly legendDiverging: 'ui-legend--diverging';
+  readonly legendThreshold: 'ui-legend--threshold';
+  readonly legendWithValues: 'ui-legend--with-values';
+  readonly legendInteractive: 'ui-legend--interactive';
+  readonly legendTitle: 'ui-legend__title';
+  readonly legendItem: 'ui-legend__item';
+  readonly legendSwatch: 'ui-legend__swatch';
+  readonly legendSwatchCircle: 'ui-legend__swatch--circle';
+  readonly legendSwatchLine: 'ui-legend__swatch--line';
+  readonly legendSwatch1: 'ui-legend__swatch--1';
+  readonly legendSwatch2: 'ui-legend__swatch--2';
+  readonly legendSwatch3: 'ui-legend__swatch--3';
+  readonly legendSwatch4: 'ui-legend__swatch--4';
+  readonly legendSwatch5: 'ui-legend__swatch--5';
+  readonly legendSwatch6: 'ui-legend__swatch--6';
+  readonly legendSwatch7: 'ui-legend__swatch--7';
+  readonly legendSwatch8: 'ui-legend__swatch--8';
+  readonly legendSymbol: 'ui-legend__symbol';
+  readonly legendLabel: 'ui-legend__label';
+  readonly legendValue: 'ui-legend__value';
+  readonly legendCaption: 'ui-legend__caption';
+  readonly legendTrack: 'ui-legend__track';
+  readonly legendTicks: 'ui-legend__ticks';
+  readonly legendTick: 'ui-legend__tick';
+  readonly annotation: 'ui-annotation';
+  readonly annotationSubject: 'ui-annotation__subject';
+  readonly annotationConnector: 'ui-annotation__connector';
+  readonly annotationConnectorEnd: 'ui-annotation__connector-end';
+  readonly annotationNote: 'ui-annotation__note';
+  readonly annotationNoteLine: 'ui-annotation__note-line';
+  readonly annotationTitle: 'ui-annotation__title';
+  readonly annotationLabel: 'ui-annotation__label';
+  readonly annotationBadge: 'ui-annotation__badge';
+  readonly annotationLabelVariant: 'ui-annotation--label';
+  readonly annotationCallout: 'ui-annotation--callout';
+  readonly annotationElbow: 'ui-annotation--elbow';
+  readonly annotationCurve: 'ui-annotation--curve';
+  readonly annotationCircle: 'ui-annotation--circle';
+  readonly annotationRect: 'ui-annotation--rect';
+  readonly annotationThreshold: 'ui-annotation--threshold';
+  readonly annotationBadgeVariant: 'ui-annotation--badge';
+  readonly annotationBracket: 'ui-annotation--bracket';
+  readonly annotationBand: 'ui-annotation--band';
+  readonly annotationSlope: 'ui-annotation--slope';
+  readonly annotationCompare: 'ui-annotation--compare';
+  readonly annotationCluster: 'ui-annotation--cluster';
+  readonly annotationAxis: 'ui-annotation--axis';
+  readonly annotationTimeline: 'ui-annotation--timeline';
+  readonly annotationEvidence: 'ui-annotation--evidence';
+  readonly annotationAccent: 'ui-annotation--accent';
+  readonly annotationMuted: 'ui-annotation--muted';
+  readonly annotationSuccess: 'ui-annotation--success';
+  readonly annotationWarning: 'ui-annotation--warning';
+  readonly annotationDanger: 'ui-annotation--danger';
+  readonly annotationInfo: 'ui-annotation--info';
+  readonly annotationDraw: 'ui-annotation--draw';
+  readonly annotationPulse: 'ui-annotation--pulse';
+  readonly annotationReveal: 'ui-annotation--reveal';
+  readonly annotationFocus: 'ui-annotation--focus';
+  readonly mark: 'ui-mark';
+  readonly markAccent: 'ui-mark--accent';
+  readonly markSuccess: 'ui-mark--success';
+  readonly markWarning: 'ui-mark--warning';
+  readonly markDanger: 'ui-mark--danger';
+  readonly markInfo: 'ui-mark--info';
+  readonly markMuted: 'ui-mark--muted';
+  readonly markUnderline: 'ui-mark--underline';
+  readonly markBox: 'ui-mark--box';
+  readonly markStrike: 'ui-mark--strike';
+  readonly markDraw: 'ui-mark--draw';
+  readonly bracketNote: 'ui-bracket-note';
+  readonly bracketNoteLabel: 'ui-bracket-note__label';
+  readonly bracketNoteAccent: 'ui-bracket-note--accent';
+  readonly bracketNoteWarning: 'ui-bracket-note--warning';
+  readonly bracketNoteDanger: 'ui-bracket-note--danger';
+  readonly bracketNoteInfo: 'ui-bracket-note--info';
+  readonly connector: 'ui-connector';
+  readonly connectorPath: 'ui-connector__path';
+  readonly connectorEnd: 'ui-connector__end';
+  readonly connectorDashed: 'ui-connector--dashed';
+  readonly connectorAccent: 'ui-connector--accent';
+  readonly connectorMuted: 'ui-connector--muted';
+  readonly connectorSuccess: 'ui-connector--success';
+  readonly connectorWarning: 'ui-connector--warning';
+  readonly connectorDanger: 'ui-connector--danger';
+  readonly connectorInfo: 'ui-connector--info';
+  readonly connectorDraw: 'ui-connector--draw';
+  readonly spotlight: 'ui-spotlight';
+  readonly spotlightHole: 'ui-spotlight__hole';
+  readonly spotlightRing: 'ui-spotlight--ring';
+  readonly tourNote: 'ui-tour-note';
+  readonly tourNoteStep: 'ui-tour-note__step';
+  readonly tourNoteTitle: 'ui-tour-note__title';
+  readonly tourNoteBody: 'ui-tour-note__body';
+  readonly tourNoteActions: 'ui-tour-note__actions';
+  readonly crosshair: 'ui-crosshair';
+  readonly crosshairMuted: 'ui-crosshair--muted';
+  readonly crosshairLine: 'ui-crosshair__line';
+  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';
+  readonly selMaybe: 'ui-sel--maybe';
+  readonly citation: 'ui-citation';
+  readonly citationChip: 'ui-citation--chip';
+  readonly sourceList: 'ui-source-list';
+  readonly sourceListItem: 'ui-source-list__item';
+  readonly sourceCard: 'ui-source-card';
+  readonly sourceCardTitle: 'ui-source-card__title';
+  readonly sourceCardOrigin: 'ui-source-card__origin';
+  readonly sourceCardTime: 'ui-source-card__time';
+  readonly sourceCardExcerpt: 'ui-source-card__excerpt';
+  readonly sourceCardActions: 'ui-source-card__actions';
+  readonly provenance: 'ui-provenance';
+  readonly provenanceItem: 'ui-provenance__item';
+  readonly srcVerified: 'ui-src--verified';
+  readonly srcUnverified: 'ui-src--unverified';
+  readonly srcGenerated: 'ui-src--generated';
+  readonly srcReviewed: 'ui-src--reviewed';
+  readonly srcStale: 'ui-src--stale';
+  readonly srcConflict: 'ui-src--conflict';
+  readonly state: 'ui-state';
+  readonly stateLabel: 'ui-state__label';
+  readonly stateDetail: 'ui-state__detail';
+  readonly stateBusy: 'ui-state--busy';
+  readonly stateSaving: 'ui-state--saving';
+  readonly stateSaved: 'ui-state--saved';
+  readonly stateQueued: 'ui-state--queued';
+  readonly stateOffline: 'ui-state--offline';
+  readonly stateStale: 'ui-state--stale';
+  readonly stateConflict: 'ui-state--conflict';
+  readonly stateError: 'ui-state--error';
+  readonly stateLocked: 'ui-state--locked';
+  readonly stateReviewed: 'ui-state--reviewed';
+  readonly stateNeedsReview: 'ui-state--needs-review';
+  readonly syncbar: 'ui-syncbar';
+  readonly generated: 'ui-generated';
+  readonly generatedLabel: 'ui-generated__label';
+  readonly originLabel: 'ui-origin-label';
+  readonly originLabelAi: 'ui-origin-label--ai';
+  readonly reasoning: 'ui-reasoning';
+  readonly reasoningBody: 'ui-reasoning__body';
+  readonly toolLog: 'ui-tool-log';
+  readonly toolCall: 'ui-tool-call';
+  readonly toolCallName: 'ui-tool-call__name';
+  readonly toolCallStatus: 'ui-tool-call__status';
+  readonly toolCallBody: 'ui-tool-call__body';
+  readonly inspector: 'ui-inspector';
+  readonly inspectorHeader: 'ui-inspector__header';
+  readonly inspectorBody: 'ui-inspector__body';
+  readonly property: 'ui-property';
+  readonly propertyLabel: 'ui-property__label';
+  readonly propertyValue: 'ui-property__value';
+  readonly selectionbar: 'ui-selectionbar';
+  readonly selectionbarCount: 'ui-selectionbar__count';
+  readonly selectionbarActions: 'ui-selectionbar__actions';
+  readonly command: 'ui-command';
+  readonly commandInput: 'ui-command__input';
+  readonly commandList: 'ui-command__list';
+  readonly commandGroup: 'ui-command__group';
+  readonly commandItem: 'ui-command__item';
+  readonly commandShortcut: 'ui-command__shortcut';
+  readonly commandMeta: 'ui-command__meta';
+  readonly commandEmpty: 'ui-command__empty';
+  readonly printOnly: 'ui-print-only';
+  readonly screenOnly: 'ui-screen-only';
+  readonly breakBefore: 'ui-break-before';
+  readonly breakAfter: 'ui-break-after';
+  readonly keep: 'ui-keep';
+  readonly printExact: 'ui-print-exact';
   readonly kbd: 'ui-kbd';
+  readonly shortcut: 'ui-shortcut';
+  readonly shortcutSep: 'ui-shortcut__sep';
   readonly display: 'ui-display';
   readonly mono: 'ui-mono';
   readonly muted: 'ui-muted';
@@ -248,6 +456,9 @@ export declare const cls: {
   readonly animateFade: 'ui-animate-fade';
   readonly animateDot: 'ui-animate-dot';
   readonly animateMatrix: 'ui-animate-matrix';
+  readonly scrollProgress: 'ui-scroll-progress';
+  readonly scrollReveal: 'ui-scroll-reveal';
+  readonly vt: 'ui-vt';
   readonly appShell: 'ui-app-shell';
   readonly appShellFull: 'ui-app-shell--full';
   readonly appRail: 'ui-app-rail';
@@ -374,6 +585,98 @@ export interface InputIconOpts {
   /** Place the icon at the inline-end instead of the start. */
   end?: boolean;
 }
+export interface LegendOpts {
+  /** Stack entries vertically instead of the wrapping inline row. */
+  orient?: 'vertical';
+  /** Continuous colour ramp (`gradient`) or binned `threshold` key. Omit for the categorical default. */
+  type?: 'gradient' | 'threshold';
+  /** Use the 7-stop diverging ramp instead of the sequential one (gradient type). */
+  diverging?: boolean;
+  compact?: boolean;
+  /** Align a trailing `__value` column across rows. */
+  withValues?: boolean;
+  /** Entries are `<button aria-pressed>` toggles (pair with behaviors/legend.js). */
+  interactive?: boolean;
+}
+export interface LegendItemOpts {
+  /** Host-set inactive state. Equivalent to `[aria-pressed="false"]` on an interactive entry. */
+  inactive?: boolean;
+}
+export interface LegendSwatchOpts {
+  /** Categorical palette series 1–8 — sets the matching `--chart-N` colour. */
+  series?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+  shape?: 'circle' | 'line';
+}
+export interface AnnotationOpts {
+  variant?: 'label' | 'callout' | 'elbow' | 'curve' | 'circle' | 'rect' | 'threshold' | 'badge' | 'bracket' | 'band' | 'slope' | 'compare' | 'cluster' | 'axis' | 'timeline' | 'evidence';
+  tone?: 'accent' | 'muted' | 'success' | 'warning' | 'danger' | 'info';
+  motion?: 'draw' | 'pulse' | 'reveal' | 'focus';
+}
+export interface MarkOpts {
+  /** How the mark is drawn. Omit for the highlight fill. */
+  style?: 'underline' | 'box' | 'strike';
+  /** `accent` is the rationed accent; status tones for status-bearing emphasis; `muted` for de-emphasis. */
+  tone?: 'accent' | 'success' | 'warning' | 'danger' | 'info' | 'muted';
+  /** Draw-on highlight sweep (respects `prefers-reduced-motion`). */
+  motion?: 'draw';
+}
+export interface BracketNoteOpts {
+  tone?: 'accent' | 'warning' | 'danger' | 'info';
+}
+export interface ConnectorOpts {
+  tone?: 'accent' | 'muted' | 'success' | 'warning' | 'danger' | 'info';
+  dashed?: boolean;
+  /** Stroke the line in once (respects `prefers-reduced-motion`). */
+  motion?: 'draw';
+}
+export interface SpotlightOpts {
+  /** Add a ring around the cutout. */
+  ring?: boolean;
+}
+export interface CrosshairOpts {
+  /** A subtler, neutral crosshair instead of the accent. */
+  muted?: boolean;
+}
+export interface SelOpts {
+  /** Selection emphasis: `on` (selected), `off` (excluded), `maybe` (live-brush candidate). */
+  state?: 'on' | 'off' | 'maybe';
+}
+/** Trust state for the source/citation/provenance layer. Pair with an author-written label — never colour alone. */
+export type SrcState = 'verified' | 'unverified' | 'generated' | 'reviewed' | 'stale' | 'conflict';
+export interface CitationOpts {
+  /** Render as a named-source pill (leading tone dot) instead of an inline `[n]` reference. */
+  chip?: boolean;
+  state?: SrcState;
+}
+export interface SourceOpts {
+  /** Sets the source card's tone border. */
+  state?: SrcState;
+}
+export interface ProvenanceOpts {
+  /** Sets the provenance item's tone dot. */
+  state?: SrcState;
+}
+/** Canonical lifecycle state — sets the tone; pair with the canonical label (see docs/state.md). */
+export type LifecycleState =
+  | 'saving'
+  | 'saved'
+  | 'queued'
+  | 'offline'
+  | 'stale'
+  | 'conflict'
+  | 'error'
+  | 'locked'
+  | 'reviewed'
+  | 'needs-review';
+export interface StateOpts {
+  state?: LifecycleState;
+  /** Pulse the indicator for an in-progress state (saving / syncing / retrying). Reduced-motion-safe. */
+  busy?: boolean;
+}
+export interface OriginLabelOpts {
+  /** Accent-tint the label for AI/model-generated origin (vs a neutral tag). */
+  ai?: boolean;
+}
 export interface Ui {
   button(opts?: ButtonOpts): string;
@@ -402,6 +705,21 @@ export interface Ui {
   container(opts?: ContainerOpts): string;
   tag(opts?: TagOpts): string;
   inputIcon(opts?: InputIconOpts): string;
+  legend(opts?: LegendOpts): string;
+  legendItem(opts?: LegendItemOpts): string;
+  legendSwatch(opts?: LegendSwatchOpts): string;
+  annotation(opts?: AnnotationOpts): string;
+  mark(opts?: MarkOpts): string;
+  bracketNote(opts?: BracketNoteOpts): string;
+  connector(opts?: ConnectorOpts): string;
+  spotlight(opts?: SpotlightOpts): string;
+  crosshair(opts?: CrosshairOpts): string;
+  sel(opts?: SelOpts): string;
+  citation(opts?: CitationOpts): string;
+  source(opts?: SourceOpts): string;
+  provenance(opts?: ProvenanceOpts): string;
+  state(opts?: StateOpts): string;
+  originLabel(opts?: OriginLabelOpts): string;
 }
 export declare const ui: Ui;