semiotic 3.6.0 → 3.7.1

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,9 +1,8 @@
 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/shared/withChartWrapper.d.ts

@@ -20,7 +20,7 @@ interface SafeRenderProps {
  * map into every subpath import — it would add ~7KB gz to xy/ordinal/
  * network just to power a fallback that only fires when render throws.
  */
-export declare function SafeRender({ componentName, width, height, children }: SafeRenderProps): import("react/jsx-runtime").JSX.Element;
+export declare function SafeRender({ componentName, width, height, children }: SafeRenderProps): React.JSX.Element;
 /**
  * Renders a "No data available" placeholder when data is empty.
  * Returns null when data is present or emptyContent is `false`.

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[];
+};

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

@@ -0,0 +1,292 @@
+/**
+ * BigNumber and (forward-looking) SingleValueFrame types.
+ *
+ * BigNumber ships today as a plain React component under
+ * `semiotic/value`. The type vocabulary here is intentionally a bit
+ * broader than the v1 component uses — it sketches the contract a
+ * future `SingleValueFrame`  would own,
+ * so adopters can write against types that survive the migration.
+ */
+import type * as React from "react";
+import type { Datum } from "../shared/datumTypes";
+/**
+ * Layout mode — chrome envelope around the focal value.
+ *
+ * - `tile` — dashboard cell. Label + value + comparison/target row + optional sparkline.
+ * - `presentation` — large centered value for a slide or hero card.
+ * - `inline` — value + optional delta indicator, no card chrome; flows in prose.
+ * - `thumbnail` — value only, no chrome, fixed-height. For embedding in dense grids.
+ */
+export type BigNumberMode = "tile" | "presentation" | "inline" | "thumbnail";
+/**
+ * Status level mapped to a semantic CSS variable
+ * (`--semiotic-success`, `--semiotic-warning`, `--semiotic-danger`,
+ * `--semiotic-info`, falls through to `--semiotic-text` for `neutral`).
+ */
+export type BigNumberLevel = "success" | "warning" | "danger" | "info" | "neutral";
+/**
+ * Whether a higher value is "better" semantically. Drives the
+ * sentiment of a delta — a `+5` delta is positive sentiment under
+ * "higher-is-better", negative under "lower-is-better", neutral when
+ * the direction isn't loaded.
+ */
+export type BigNumberDirection = "higher-is-better" | "lower-is-better" | "neutral";
+/**
+ * Resolved sentiment for a delta or value-vs-target. Controls whether
+ * a delta renders in success-coloured or danger-coloured ink.
+ * `"auto"` lets the component infer from `direction` + the sign of the delta.
+ */
+export type BigNumberSentiment = "auto" | "positive" | "negative" | "neutral";
+/**
+ * Number-format shortcut. `(value) => string` lets you plug in d3-format,
+ * Intl.NumberFormat, or any custom formatter.
+ *
+ * Built-in shortcuts read locale + currency + precision off the props:
+ *
+ * - `"number"`   — Intl.NumberFormat with grouping.
+ * - `"currency"` — currency style; needs `currency` prop (default USD).
+ * - `"percent"`  — multiplies × 100, suffixes "%".
+ * - `"compact"`  — Intl compact notation: 1.2M, 3.4K.
+ * - `"duration"` — formats a millisecond duration as `1h 23m 4s`.
+ */
+export type BigNumberFormat = "number" | "currency" | "percent" | "compact" | "duration" | ((value: number) => string);
+/**
+ * Threshold zone — a lower bound + status level. Zones must be sorted
+ * ascending by `at` and resolved by "highest `at` ≤ value".
+ *
+ * @example
+ * ```ts
+ * thresholds={[
+ *   { at: -Infinity, level: "danger" },
+ *   { at: 50,        level: "warning" },
+ *   { at: 80,        level: "success" },
+ * ]}
+ * ```
+ */
+export interface BigNumberThreshold {
+    /** Lower bound (inclusive) for this zone. `-Infinity` covers everything below. */
+    at: number;
+    /** Status level. Maps to a semantic CSS variable on the value text. */
+    level: BigNumberLevel;
+    /** Explicit colour override; otherwise `var(--semiotic-{level})`. */
+    color?: string;
+    /** Optional label surfaced in tooltips, the ARIA sentence, and capability output. */
+    label?: string;
+}
+/**
+ * Comparison value (vs. prior period, vs. last quarter, etc.). The
+ * delta is derived as `value - comparison.value` unless `delta` is set
+ * explicitly on the parent.
+ */
+export interface BigNumberComparison {
+    /** Prior-period value used to compute the delta. */
+    value: number;
+    /** Descriptor — e.g. `"vs last quarter"`. */
+    label?: string;
+    /** Inherit `format`/`locale`/`currency` if omitted. */
+    format?: BigNumberFormat;
+    /** Whether higher is better. Defaults to the top-level `direction`. */
+    direction?: BigNumberDirection;
+}
+/**
+ * Target / goal value. Renders as `… of {target.value}` with optional
+ * progress framing (the value's distance to target).
+ */
+export interface BigNumberTarget {
+    /** Goal value. */
+    value: number;
+    /** Descriptor — e.g. `"of Q3 target"`. */
+    label?: string;
+    /** Inherit `format`/`locale`/`currency` if omitted. */
+    format?: BigNumberFormat;
+    /** Whether higher is better. Defaults to the top-level `direction`. */
+    direction?: BigNumberDirection;
+}
+/** Imperative ref handle for streaming/push usage. */
+export interface BigNumberHandle {
+    /** Append a new datapoint; updates the focal value + extends the trend. */
+    push(input: number | BigNumberPushInput): void;
+    /** Append many in one pass. */
+    pushMany(inputs: ReadonlyArray<number | BigNumberPushInput>): void;
+    /** Reset trend buffer and focal value. */
+    clear(): void;
+    /** Current focal value. Returns the most-recently-pushed value when the
+     *  push API has been used; otherwise falls back to the `value` prop. Returns
+     *  `null` only when no push has landed AND the prop value is not finite. */
+    getValue(): number | null;
+    /** Trend buffer snapshot (most-recent-last). */
+    getData(): ReadonlyArray<BigNumberPushInput>;
+}
+export interface BigNumberPushInput {
+    value: number;
+    time?: number | Date;
+    /** Override the comparison value at this tick. */
+    comparison?: number;
+}
+/**
+ * Render slots — drop-ins for any slot in the layout. ReactNode form
+ * is rendered as-is; the function form receives the resolved context
+ * so the slot can read formatted strings without re-deriving them.
+ */
+export interface BigNumberSlotContext {
+    value: number | null;
+    formattedValue: string;
+    level: BigNumberLevel;
+    /** Resolved colour for the focal value, ready to drop into a `color` /
+     *  `stroke` / `fill` prop on an embedded Semiotic chart so its marks
+     *  match the BigNumber's threshold level. Either a hex / rgb string
+     *  or a `var(--semiotic-{level})` reference. */
+    color: string;
+    delta: number | null;
+    deltaFormatted: string | null;
+    /** Formatted percent change string (e.g. `"+20%"`), or null when undefined. */
+    deltaPercent: string | null;
+    sentiment: "positive" | "negative" | "neutral";
+    isStale: boolean;
+    /** Live push-API buffer (most-recent-last). Useful when a slot chart
+     *  should redraw on every ingest — read from this in the function
+     *  form so the chart re-renders alongside the focal value. */
+    pushBuffer: ReadonlyArray<BigNumberPushInput>;
+}
+export type BigNumberSlot = React.ReactNode | ((ctx: BigNumberSlotContext) => React.ReactNode);
+/**
+ * The full prop surface. Intentionally broad — every block here maps
+ * to a documented `SingleValueFrame` capability so users targeting
+ * the v1 component can roll forward unchanged when (if) the frame ships.
+ *
+ * Does NOT extend `BaseChartProps` because most of those (axisExtent,
+ * pointIdAccessor, linkedHover, linkedBrush, hoverHighlight, ...) are
+ * irrelevant for a single value. The contract is documented per-prop.
+ */
+export interface BigNumberProps<_TDatum extends Datum = Datum> {
+    /** The number this card exists to display. `null` / `undefined` / `NaN`
+     *  routes the card into its empty state (see `emptyContent`); this lets
+     *  consumers pass `data?.revenue` style optional values without a
+     *  conditional. */
+    value: number | null | undefined;
+    /** Top-line descriptor — e.g. `"Q3 Revenue"`. Rendered above the value. */
+    label?: string;
+    /** Secondary descriptor, smaller, below the label. */
+    caption?: string;
+    /** Format the focal value. Default `"number"`. */
+    format?: BigNumberFormat;
+    /** BCP-47 locale tag for built-in formats. Default `"en-US"`. */
+    locale?: string;
+    /** ISO 4217 code; required for `format: "currency"`. Default `"USD"`. */
+    currency?: string;
+    /** `Intl.NumberFormat` `maximumFractionDigits`. Default 0 for compact, 2 for currency, 0 elsewhere. */
+    precision?: number;
+    /** Prepend to the formatted value. */
+    prefix?: string;
+    /** Append to the formatted value. */
+    suffix?: string;
+    /** Unit label rendered after the value as small text — e.g. `"USD"`, `"req/s"`. */
+    unit?: string;
+    /** Comparison value (vs prior period). Drives delta if `delta` is not explicit. */
+    comparison?: BigNumberComparison;
+    /** Goal value; renders alongside the comparison row. */
+    target?: BigNumberTarget;
+    /** Explicit delta override; bypasses comparison.value subtraction. */
+    delta?: number;
+    /** Format the delta; defaults to `format` (inherits currency/locale). */
+    deltaFormat?: BigNumberFormat;
+    /** Also render the percent change next to the absolute delta. Default true when a comparison is present. */
+    showDeltaPercent?: boolean;
+    /** Default direction for sentiment inference. Per-comparison/target wins. */
+    direction?: BigNumberDirection;
+    /** Force sentiment classification. `"auto"` infers from `direction` + sign. Default `"auto"`. */
+    sentiment?: BigNumberSentiment;
+    /** Threshold zones — ordered ascending by `at`. Defines the level
+     *  applied to the value text via a semantic CSS variable. */
+    thresholds?: ReadonlyArray<BigNumberThreshold>;
+    /** Cap the push buffer surfaced via `getData()` / `slotCtx.pushBuffer`. Default 60. */
+    windowSize?: number;
+    /** Layout mode. Default `"tile"`. */
+    mode?: BigNumberMode;
+    /** Horizontal alignment within the card. Default `"start"` for tile,
+     *  `"center"` for presentation / thumbnail, `"inherit"` for inline. */
+    align?: "start" | "center" | "end";
+    /** Reserve width. Default 280 (tile), 540 (presentation), unset (inline/thumbnail). */
+    width?: number | string;
+    /** Reserve height. Default 184 (tile), 320 (presentation), unset (inline/thumbnail). */
+    height?: number | string;
+    /** Inner padding; number or `{top, right, bottom, left}`. */
+    padding?: number | {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+    /** Visual emphasis hint — dashboards can use this to span columns. */
+    emphasis?: "primary" | "secondary";
+    /** Override the value text colour. CSS variables work. */
+    color?: string;
+    /** Card background. CSS variables work; transparent by default in inline/thumbnail. */
+    background?: string;
+    /** Border colour. Defaults to `--semiotic-border`. */
+    borderColor?: string;
+    /** Border radius (px or any CSS length). Defaults to theme `--semiotic-border-radius`. */
+    borderRadius?: number | string;
+    /** Optional class for the outer container. */
+    className?: string;
+    /** Optional inline style — composed with the layout defaults. */
+    style?: React.CSSProperties;
+    /** Tween between value changes. `true` = 300ms ease-out + intro. */
+    animate?: boolean | {
+        duration?: number;
+        easing?: "linear" | "ease-out";
+        intro?: boolean;
+    };
+    /** Mark the card stale (dimmed) when no push occurs for this many ms. */
+    stalenessThreshold?: number;
+    /** Custom stale label appended to the ARIA sentence. Default `"stale"`. */
+    staleLabel?: string;
+    /** Replace the entire header (label + caption) slot. */
+    headerSlot?: BigNumberSlot;
+    /** Replace the focal value slot. */
+    valueSlot?: BigNumberSlot;
+    /** Replace the delta / comparison / target row. */
+    deltaSlot?: BigNumberSlot;
+    /** **Wide / rectangular** chart embedded beneath the value — e.g. a
+     *  `LineChart` / `AreaChart` in `mode="sparkline"`. The card stays
+     *  full-width and stacks the chart at full card width under the delta
+     *  row. */
+    trendSlot?: BigNumberSlot;
+    /** **Square** chart embedded beside the value — e.g. a `DonutChart` /
+     *  `PieChart` / `Scatterplot` / `Treemap`. When set, the card splits
+     *  into a left column (header + value + delta) and a right column
+     *  (the square chart). Compose with `trendSlot` to get both
+     *  (square chart on the right, wide trend along the bottom). */
+    chartSlot?: BigNumberSlot;
+    /** Reserved pixel size (square) for `chartSlot`. Defaults are
+     *  mode-keyed for sparkline scale — 44 px for `tile`, 80 px for
+     *  `presentation` — so the embedded chart reads as a corner
+     *  decoration. Pass a larger value for a hero-style anchor. */
+    chartSize?: number;
+    /** Free-form footer below the trend. */
+    footerSlot?: BigNumberSlot;
+    /** Card click. */
+    onClick?: (datum: {
+        value: number;
+        level: BigNumberLevel;
+        delta: number | null;
+    }, event: {
+        x: number;
+        y: number;
+    }) => void;
+    /** Generic observation hook — fires on click today; future SingleValueFrame work
+     *  may extend this to value-update / hover events. */
+    onObservation?: import("../../store/ObservationStore").OnObservationCallback;
+    /** Identifier surfaced on every observation event. */
+    chartId?: string;
+    /** Override the auto-generated aria-label sentence. */
+    description?: string;
+    /** Sr-only supplement appended below the auto sentence. */
+    summary?: string;
+    /** Loading skeleton overlay. */
+    loading?: boolean;
+    /** Replace the default skeleton; `false` suppresses it entirely. */
+    loadingContent?: React.ReactNode | false;
+    /** Empty-state placeholder rendered when `value` is `null`/`undefined`/`NaN`. */
+    emptyContent?: React.ReactNode | false;
+}

package/dist/components/charts/xy/MinimapChart.d.ts

@@ -1,4 +1,5 @@
 import type { Datum } from "../shared/datumTypes";
+import * as React from "react";
 import type { StreamXYFrameProps } from "../../stream/types";
 import type { LegendPosition } from "../shared/hooks";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
@@ -128,7 +129,7 @@ export interface MinimapChartProps<TDatum extends Datum = Datum> extends Omit<Ba
  * />
  * ```
  */
-export declare function MinimapChart<TDatum extends Datum = Datum>(props: MinimapChartProps<TDatum>): import("react/jsx-runtime").JSX.Element;
+export declare function MinimapChart<TDatum extends Datum = Datum>(props: MinimapChartProps<TDatum>): React.JSX.Element;
 export declare namespace MinimapChart {
     var displayName: string;
 }

package/dist/components/charts/xy/ScatterplotMatrix.d.ts

@@ -1,4 +1,5 @@
 import type { Datum } from "../shared/datumTypes";
+import * as React from "react";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 export interface ScatterplotMatrixProps<TDatum extends Datum = Datum> extends BaseChartProps {
@@ -81,7 +82,7 @@ export interface ScatterplotMatrixProps<TDatum extends Datum = Datum> extends Ba
  * />
  * ```
  */
-export declare function ScatterplotMatrix<TDatum extends Datum = Datum>(props: ScatterplotMatrixProps<TDatum>): import("react/jsx-runtime").JSX.Element;
+export declare function ScatterplotMatrix<TDatum extends Datum = Datum>(props: ScatterplotMatrixProps<TDatum>): React.JSX.Element;
 export declare namespace ScatterplotMatrix {
     var displayName: string;
 }