semiotic 3.5.4 → 3.7.0

package/dist/components/charts/shared/annotationHierarchy.d.ts

@@ -0,0 +1,42 @@
+import * as React from "react";
+import type { Datum } from "./datumTypes";
+export type AnnotationEmphasis = "primary" | "secondary";
+/** A rendered annotation node paired with the source annotation it came
+ *  from, so hierarchy treatment can read metadata after the per-type rule has
+ *  produced the node. */
+export interface AnnotationRenderPair {
+    node: React.ReactNode;
+    annotation: Datum;
+}
+/**
+ * Reveal CSS for M3 progressive disclosure. Density-deferred notes are hidden
+ * (opacity 0) until the chart they belong to is hovered or focused. The
+ * selectors are scoped to each frame's stable wrapper class so a chart only
+ * reveals its *own* deferred notes; `:focus-within` covers keyboard users who
+ * focus the canvas (the canvas lives inside the wrapper). Style rules are
+ * document-global regardless of where the `<style>` tag lands, so injecting it
+ * inside the (pointer-events:none) overlay svg is fine. Identical across charts
+ * — duplicate injections are harmless.
+ */
+export declare const ANNOTATION_DISCLOSURE_REVEAL_CSS: string;
+/**
+ * Apply annotation hierarchy — Rahman et al.'s "Hierarchy" consideration,
+ * reusing the same `emphasis` token charts already accept (`"primary"` /
+ * `"secondary"`). A `secondary` annotation dims, shrinks note text through
+ * inherited SVG font-size, and yields z-order; a `primary` one paints at full
+ * weight and on top.
+ *
+ * If no explicit emphasis is declared, annotations with
+ * `provenance.confidence` get an inferred reading order: confidence
+ * descending, then authored array order. The visual output uses that order as
+ * a subtle opacity gradient, with higher-confidence notes painted later.
+ *
+ * Type-agnostic: it wraps whatever the per-type rule produced, so all
+ * annotation types get hierarchy without each rule knowing about it.
+ *
+ * Zero-overhead and structure-preserving when no annotation declares an
+ * explicit emphasis or provenance confidence: the original nodes are returned
+ * untouched (same keys, same order), so existing charts render identically.
+ * Opacity composes multiplicatively with lifecycle freshness opacity.
+ */
+export declare function applyAnnotationEmphasis(pairs: ReadonlyArray<AnnotationRenderPair>): React.ReactNode[];

package/dist/components/charts/shared/annotationResolvers.d.ts

@@ -3,8 +3,8 @@ import type { Datum } from "./datumTypes";
  * Coordinate resolution helpers for annotations.
  *
  * Resolves data coordinates to pixel positions, respecting anchor modes
- * (fixed, latest, sticky), pointId matching, and bounds checking for
- * streaming charts where data scrolls off-screen.
+ * (fixed, latest, sticky, semantic), pointId / stableId matching, and
+ * bounds checking for streaming charts where data scrolls off-screen.
  *
  * Dependencies: types (AnnotationContext)
  * Consumed by: annotationRules.tsx (all annotation type renderers)
@@ -17,6 +17,7 @@ export declare function resolveY(ann: Datum, context: AnnotationContext): number
  * - "fixed" (default): resolve from annotation's own fields
  * - "latest": resolve from the most recent datum in the buffer
  * - "sticky": resolve from annotation fields; if not found, use cached position
+ * - "semantic": resolve from provenance.stableId; if not found, use recorded fields
  */
 export declare function resolveAnchoredPosition(ann: Datum, index: number, context: AnnotationContext): {
     x: number;

package/dist/components/charts/shared/annotationRules.d.ts

@@ -1,4 +1,20 @@
 import * as React from "react";
 import type { AnnotationContext } from "../../realtime/types";
 import type { Datum } from "./datumTypes";
+export { applyAnnotationEmphasis, type AnnotationRenderPair } from "./annotationHierarchy";
+type AnnotationRule = (annotation: Datum, index: number, context: AnnotationContext) => React.ReactNode | null;
+/**
+ * Run the SVG-overlay annotation pass: dispatch each annotation through the
+ * user's `svgAnnotationRules` (falling back to the default rules), drop the
+ * ones that render nothing, then apply emphasis hierarchy. Shared verbatim by
+ * the XY and ordinal overlays so the dispatch/filter/hierarchy logic lives in
+ * one place.
+ *
+ * Falsy-node semantics match the pre-emphasis `.filter(Boolean)` exactly: a
+ * rule returning `null`/`undefined` ("skip", e.g. the default rules' out-of-
+ * bounds path) — or any other falsy node (`0`/`""`/`false`) — produces no
+ * annotation and is dropped. A user rule that returns `null`/`undefined` falls
+ * through to the default rule, preserving the existing override contract.
+ */
+export declare function renderAnnotationPass(annotations: ReadonlyArray<Datum>, defaultRule: AnnotationRule, userRule: AnnotationRule | undefined, context: AnnotationContext): React.ReactNode[];
 export declare function createDefaultAnnotationRules(_frameType: "xy" | "ordinal" | "network"): (annotation: Datum, index: number, context: AnnotationContext) => React.ReactNode | null;

package/dist/components/charts/shared/annotationTypes.d.ts

@@ -0,0 +1,14 @@
+import type { Datum } from "./datumTypes";
+/**
+ * Note-like annotations compete for placement and density budgets. Keep this
+ * taxonomy centralized because layout, diagnostics, and accessibility checks
+ * all need to agree on what counts as a note.
+ */
+export declare const NOTE_ANNOTATION_TYPES: readonly ["label", "callout", "callout-circle", "callout-rect", "text", "widget"];
+export type NoteAnnotationType = (typeof NOTE_ANNOTATION_TYPES)[number];
+/** Note types whose default renderer draws a connector unless disabled. */
+export declare const CONNECTOR_ANNOTATION_TYPES: readonly ["label", "callout", "callout-circle", "callout-rect"];
+export declare function annotationType(annotation: Datum): string;
+export declare function isNoteAnnotation(annotation: Datum): boolean;
+export declare function annotationDisablesConnector(annotation: Datum): boolean;
+export declare function annotationDrawsConnector(annotation: Datum): boolean;

package/dist/components/charts/shared/auditAccessibility.d.ts

@@ -0,0 +1,90 @@
+import type { Datum } from "./datumTypes";
+export type A11yPrinciple = "perceivable" | "operable" | "understandable" | "robust" | "compromising" | "assistive" | "flexible";
+/**
+ * - `pass`  — satisfied (by config or by Semiotic's built-ins)
+ * - `fail`  — a problem we can prove from the config
+ * - `warn`  — a likely problem or a default worth revisiting
+ * - `manual`— can't be settled statically; run the named Chartability test
+ * - `not-applicable` — heuristic doesn't apply to this chart
+ */
+export type A11yStatus = "pass" | "fail" | "warn" | "manual" | "not-applicable";
+export interface A11yFinding {
+    /** Stable id, `principle.heuristic-slug` (e.g. "perceivable.low-contrast"). */
+    id: string;
+    principle: A11yPrinciple;
+    /** The Chartability heuristic name, verbatim. */
+    heuristic: string;
+    /** Chartability flags 14 of 50 heuristics as critical. */
+    critical: boolean;
+    status: A11yStatus;
+    message: string;
+    /** How to fix or, for `manual`, the test to run. */
+    fix?: string;
+}
+export interface AccessibilityAuditResult {
+    component: string;
+    /** No critical heuristic is in a `fail` state. (warn/manual don't break this.) */
+    ok: boolean;
+    summary: {
+        criticalsPassed: number;
+        /** Critical heuristics actually evaluated (excludes not-applicable). */
+        criticalsEvaluated: number;
+        fails: number;
+        warnings: number;
+        manual: number;
+        passes: number;
+    };
+    findings: A11yFinding[];
+    /** Always points back to the source framework. */
+    reference: string;
+}
+export interface AuditAccessibilityOptions {
+    /**
+     * Whether the chart is wrapped in a ChartContainer (or otherwise exposes a
+     * data-download / copy-config affordance). Lets the audit credit the
+     * "downloadable table" and "shareable state" heuristics. ChartContainer is
+     * the opt-in layer for full-accessibility chrome (title, caption,
+     * description), so several heuristics soften their remediation toward it.
+     * Default false.
+     */
+    inChartContainer?: boolean;
+    /**
+     * Whether ChartContainer's `describe` option (auto-generated L1–L3 description
+     * via describeChart) is enabled. Lets the "features described" heuristic pass.
+     * Default false.
+     */
+    describe?: boolean;
+    /**
+     * Whether ChartContainer's `navigable` option (a structured, screen-reader-
+     * navigable tree via buildNavigationTree/AccessibleNavTree) is enabled. Lets
+     * the "navigable structure" heuristic pass — including for hierarchy charts.
+     * Default false.
+     */
+    navigable?: boolean;
+}
+/**
+ * Audit a Semiotic chart configuration against the Chartability heuristics.
+ * Pure, SSR-safe, no DOM. See module docstring for what static analysis can
+ * and cannot determine.
+ */
+export declare function auditAccessibility(component: string, props: Datum, options?: AuditAccessibilityOptions): AccessibilityAuditResult;
+/**
+ * Distil an audit result into terse caveat strings — the author-actionable
+ * `fail` and `warn` findings, one line each. Lets the recommender (and an AI
+ * agent) read *receivability* caveats ("8 slices is too many," "color-only
+ * encoding") from the same channel as the perceptual caveats a capability
+ * descriptor already declares, instead of two disconnected surfaces.
+ *
+ * Pure. Pair with {@link auditAccessibility}:
+ * ```ts
+ * const caveats = accessibilityCaveats(auditAccessibility("PieChart", props))
+ * ```
+ *
+ * @param onlyCritical When true, restrict to critical heuristics (the 14 that
+ *   Chartability flags). Default false — include all fail/warn findings.
+ */
+export declare function accessibilityCaveats(result: AccessibilityAuditResult, { onlyCritical }?: {
+    onlyCritical?: boolean;
+}): string[];
+/** Render an audit result as a human-readable report (used by --audit-a11y + MCP). */
+export declare function formatAccessibilityAudit(result: AccessibilityAuditResult): string;

package/dist/components/charts/shared/chartSpecs.d.ts

@@ -1,43 +1,8 @@
-/**
- * Single source of truth for per-chart prop specifications.
- *
- * Three downstream consumers used to maintain their own per-chart entries:
- *   - `ai/schema.json`                                    (LLM tool definitions)
- *   - `src/components/charts/shared/validationMap.ts`     (runtime prop validation)
- *   - `ai/componentMetadata.cjs`                          (category buckets)
- *
- * Today, `ai/schema.json` is generated from this registry — run
- * `npm run docs:chart-specs:schema` to refresh it after editing a spec.
- * `validationMap.ts` and `ai/componentMetadata.cjs` are still hand-edited
- * but are gated for parity by the registry: `check:chart-specs` (run via
- * `npm run check:chart-specs`) regenerates each chart's schema/
- * validation/metadata entries with the pure functions in
- * `scripts/lib/chart-specs-generators.mjs` and fails the build on any
- * drift, including unexpected adds or removes that bypass the registry.
- *
- * Design notes:
- *   - Shared prop bags (common, xyAxis, ordinalAxis) live in `PROP_BAGS` and
- *     are referenced by name in each spec so common surface stays in one place.
- *   - The runtime PropType set ("string" | "number" | "boolean" | "array" |
- *     "object" | "function") is broader than JSON Schema's, but the schema
- *     generator emits whatever types this registry declares — including
- *     "function" inside type unions (canonical entries like
- *     `RidgelinePlot.tooltip: ["function", "object"]` and
- *     `SwimlaneChart.onBrush: "function"` already use this convention; LLMs
- *     read the union and pick a non-function alternative when they can't
- *     supply a function value). For props that are purely callbacks or
- *     escape hatches an LLM cannot meaningfully populate, tag the spec
- *     with `omitFromSchema: true` to keep it in validationMap but out of
- *     schema.json. `description` and `default` annotations surface in
- *     schema.json (and MCP responses) but are dropped from validationMap
- *     (which only reads `type` and `enum`).
- */
 export type PropType = "string" | "number" | "boolean" | "array" | "object" | "function";
 export type DataShape = "array" | "object" | "network" | "realtime" | "none";
-export type ChartCategory = "xy" | "ordinal" | "network" | "geo" | "realtime";
+export type ChartCategory = "xy" | "ordinal" | "network" | "geo" | "realtime" | "value";
 /**
- * Capability tags for runtime behavior. Driven by the
- * `hoc-frame-architecture-audit` Phase 1: each chart declares which
+ * Capability tags for runtime behavior. Each chart declares which
  * features it actually supports so docs, AI/MCP tools, and CI gates
  * can read structured truth instead of inferring it from the source.
  *

package/dist/components/charts/shared/diagnoseConfig.d.ts

@@ -9,10 +9,8 @@ export interface DiagnosisResult {
     ok: boolean;
     diagnoses: Diagnosis[];
 }
-/**
- * Run anti-pattern diagnostics on a Semiotic chart configuration.
- *
- * Returns actionable diagnoses with severity, code, message, and fix instruction.
- * Runs validateProps internally — validation errors are included as diagnoses.
- */
+/** WCAG contrast ratio between two hex colors. Exported for reuse by the
+ *  accessibility audit (auditAccessibility.ts) — single source of truth for the
+ *  contrast math. Returns null if either color isn't a parseable hex. */
+export declare function contrastRatio(hex1: string, hex2: string): number | null;
 export declare function diagnoseConfig(componentName: string, props: Datum): DiagnosisResult;

package/dist/components/charts/shared/selectionUtils.d.ts

@@ -8,8 +8,10 @@ import type { Datum } from "./datumTypes";
 export interface NormalizedLinkedHover {
     name: string;
     fields: string[];
-    mode?: "field" | "x-position";
+    mode?: "field" | "x-position" | "series";
     xField?: string;
+    /** Explicit series-identity field for `mode: "series"`; overrides the auto-resolved one. */
+    seriesField?: string;
 }
 export interface NormalizedLinkedBrush {
     name: string;
@@ -26,8 +28,9 @@ export interface NormalizedLinkedBrush {
 export declare function normalizeLinkedHover(prop: boolean | string | {
     name?: string;
     fields?: string[];
-    mode?: "field" | "x-position";
+    mode?: "field" | "x-position" | "series";
     xField?: string;
+    seriesField?: string;
 } | undefined, fallbackFields?: string[]): NormalizedLinkedHover | null;
 /**
  * Normalize the linkedBrush prop into a consistent config object.

package/dist/components/charts/shared/streamPropsHelpers.d.ts

@@ -5,6 +5,7 @@ import type { HoverData } from "../../realtime/types";
 import type { HoverHighlightMode, LinkedHoverProp, SelectionConfig } from "./types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { AnimateProp } from "../../stream/pipelineTransitionUtils";
+import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
 /**
  * The frames accept `tooltipContent: (d: HoverData) => ReactNode`,
  * which is a slightly wider parameter than the `TooltipContentFn`
@@ -48,6 +49,7 @@ export interface BaseMetadataProps {
      *  this to the frame. Bundling it here avoids a parallel helper
      *  + 22 separate adoption edits. */
     axisExtent?: import("./axisExtent").AxisExtentMode;
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
 }
 export declare function buildBaseMetadataProps(input: BaseMetadataProps): BaseMetadataProps;
 /**

package/dist/components/charts/shared/types.d.ts

@@ -3,6 +3,7 @@ import type { PartialMargin } from "../../types/marginType";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { AnimateProp } from "../../stream/pipelineTransitionUtils";
 import type { Datum } from "./datumTypes";
+import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
 /**
  * Selection consumption config — makes this chart react to a named selection
  */
@@ -25,8 +26,9 @@ export interface SelectionConfig {
 export type LinkedHoverProp = boolean | string | {
     name?: string;
     fields?: string[];
-    mode?: "field" | "x-position";
+    mode?: "field" | "x-position" | "series";
     xField?: string;
+    seriesField?: string;
 };
 /**
  * Linked brush config
@@ -128,6 +130,8 @@ export interface BaseChartProps {
     dataIdAccessor?: string | ((d: Datum) => string);
     /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */
     emphasis?: "primary" | "secondary";
+    /** Opt into annotation placement assistance. Preserves authored dx/dy by default. */
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
     /** Enable declarative bounded animation (enter/exit/update transitions + intro).
      * `true` uses defaults (300ms ease-out, intro enabled). Object form allows customization.
      * Set `{ intro: false }` to disable the animated intro on first render. */

package/dist/components/charts/value/BigNumber.capability.d.ts

@@ -0,0 +1,13 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+/**
+ * BigNumber capability descriptor.
+ *
+ * `fits()` accepts datasets that resolve to a single focal value:
+ *   - exactly one row with a numeric field, or
+ *   - any dataset where a `total` / `value` aggregation makes sense
+ *     and the suggestion engine has already declared the scale `tiny`.
+ *
+ * At tiny scale BigNumber is the catalog's "honest" answer: when you
+ * have one number, a chart is the wrong abstraction — show the number.
+ */
+export declare const BigNumberCapability: ChartCapability;

package/dist/components/charts/value/BigNumber.d.ts

@@ -0,0 +1,14 @@
+/**
+ * BigNumber — the focal-value HOC behind `semiotic/value`.
+ *
+ * A plain React component (no Stream Frame underneath). This ships as a forward-looking React
+ * component that already honours the contracts a `SingleValueFrame`
+ * would inherit (format cascade, threshold zones via semantic theme
+ * roles, comparison anchoring, sentence-form ARIA, push API + staleness).
+ */
+import * as React from "react";
+import type { BigNumberHandle, BigNumberProps } from "./types";
+export declare const BigNumber: (props: BigNumberProps & {
+    ref?: React.ForwardedRef<BigNumberHandle>;
+}) => React.ReactElement | null;
+export default BigNumber;

package/dist/components/charts/value/formatting.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Number-format cascade for BigNumber.
+ *
+ * Resolves a `BigNumberFormat` shortcut (or custom fn) against the
+ * card's locale + currency + precision props and returns a memoizable
+ * formatter. All built-ins use `Intl.NumberFormat` so locale + grouping
+ * behave correctly without bundling a separate number-format library.
+ */
+import type { BigNumberFormat } from "./types";
+export interface FormatContext {
+    locale?: string;
+    currency?: string;
+    precision?: number;
+    notation?: Intl.NumberFormatOptions["notation"];
+}
+/**
+ * Build a `(value) => string` formatter from a shortcut + context.
+ * Custom-function shortcuts are returned as-is.
+ */
+export declare function buildFormatter(format: BigNumberFormat | undefined, ctx?: FormatContext): (value: number) => string;
+/**
+ * Format a millisecond duration as a short human string:
+ * `2h 14m`, `45s`, `12ms`. Useful for latency-style KPIs.
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * Decorate a formatted number with prefix/suffix. Empty strings are
+ * skipped without padding.
+ */
+export declare function decorate(formatted: string, prefix: string | undefined, suffix: string | undefined): string;
+/**
+ * Format a signed delta — always carry an explicit + on positive values
+ * so the sign-as-information stays legible. Zero renders as `"0"`
+ * unformatted-by-sign (no `+0`).
+ */
+export declare function formatSignedDelta(delta: number, formatter: (value: number) => string): string;
+/**
+ * Format a percent change. `from` of 0 yields `null` (undefined ratio).
+ */
+export declare function formatDeltaPercent(from: number, to: number, locale?: string, precision?: number): string | null;

package/dist/components/charts/value/thresholdSparkline.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Threshold zone resolution + inline sparkline path builder for
+ * BigNumber. Lifted out so the component file stays focused on layout.
+ */
+import type { BigNumberLevel, BigNumberThreshold } from "./types";
+/**
+ * Resolve a numeric value against an ordered threshold list. Zones are
+ * tested by "highest `at` whose bound is ≤ value." `-Infinity` works
+ * as a "catch-all" lower zone.
+ *
+ * Returns `null` when no threshold fits (caller falls back to neutral).
+ */
+export declare function resolveThreshold(value: number, thresholds: ReadonlyArray<BigNumberThreshold> | undefined): BigNumberThreshold | null;
+/**
+ * Map a level + explicit-color override to a CSS color string. The
+ * neutral level falls through to `--semiotic-text` so the value reads
+ * as the regular text colour when no thresholds fire.
+ */
+export declare function colorForLevel(level: BigNumberLevel, explicit?: string): string;
+export interface SparklinePoint {
+    x: number;
+    y: number;
+}
+/**
+ * Build the SVG path string for a polyline sparkline. Maps values into
+ * a [0..width] × [0..height] box; auto-fits the y-domain by default.
+ *
+ * Empty / single-point input returns an empty string.
+ */
+export declare function buildSparklinePath(values: ReadonlyArray<number>, opts: {
+    width: number;
+    height: number;
+    padding?: number;
+    yMin?: number;
+    yMax?: number;
+}): {
+    line: string;
+    area: string;
+    points: SparklinePoint[];
+};