semiotic 3.7.4 → 3.8.0

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

@@ -0,0 +1,20 @@
+export declare const HIERARCHY_CHARTS: Set<string>;
+export declare const NETWORK_CHARTS: Set<string>;
+export declare const BAR_AREA_CHARTS: Set<string>;
+export declare const TREND_SERIES_CHARTS: Set<string>;
+export declare const ORDINAL_BAR_CHARTS: Set<string>;
+export declare const CURVE_CHARTS: Set<string>;
+export declare const PIE_CHARTS: Set<string>;
+export declare const PART_TO_WHOLE_ACCESSORS: Record<string, string>;
+export declare const PART_TO_WHOLE_CHARTS: Set<string>;
+export declare const NORMALIZED_STACK_ACCESSORS: Record<string, string>;
+export declare const VALUE_CHARTS: Set<string>;
+export declare const XY_WITH_AXES_CHARTS: Set<string>;
+export declare const PHYSICS_MOTION_CHARTS: Set<string>;
+export declare const CONTINUOUS_MOTION_CHARTS: Set<string>;
+export declare const PHYSICS_SETTLED_CHARTS: Set<string>;
+export declare const PHYSICS_DIAGNOSTIC_CHARTS: Set<string>;
+export declare const REALTIME_CHARTS: Set<string>;
+export declare const DUAL_AXIS_CHARTS: Set<string>;
+export declare const GEO_CHARTS: Set<string>;
+export declare const POINT_TARGET_RADIUS_PROP: Record<string, string>;

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

@@ -0,0 +1,165 @@
+/**
+ * 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, `validationMap.ts` is derived directly from this registry, and
+ * `ai/schema.json` is generated from it — run `npm run docs:chart-specs:schema`
+ * to refresh the schema after editing a spec. `componentMetadata.cjs` is still
+ * hand-edited but 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" | "physics" | "value";
+/**
+ * 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.
+ *
+ * All fields are required so a new chart entry can't omit them
+ * silently — the audit's anti-goal "Do not make registry metadata
+ * aspirational. It should describe real runtime behavior and be
+ * checked." applies here.
+ */
+export interface ChartCapabilities {
+    /**
+     * Render pipeline. `canvas` for Stream-Frame-driven charts that
+     * paint to canvas with SVG overlays for chrome (the common case).
+     * `svg` for charts that are pure SVG (none today, but reserved).
+     * `hybrid` for charts that use both — currently every Stream-Frame
+     * HOC qualifies as hybrid; reserve `canvas` for any future
+     * canvas-only fallback.
+     */
+    renderModes: Array<"canvas" | "svg" | "hybrid">;
+    /** Renders a legend swatch column when `colorBy` (or equivalent)
+     *  resolves to non-empty categories. */
+    supportsLegend: boolean;
+    /** Reads from a `selection` prop and dims/highlights matching
+     *  marks via `wrapStyleWithSelection` or equivalent. */
+    supportsSelection: boolean;
+    /** Produces a hover-driven selection (used by linked crosshair /
+     *  cross-filter patterns) via `linkedHover`. */
+    supportsLinkedHover: boolean;
+    /** Exposes a ref handle (`push`, `pushMany`, etc.) so consumers
+     *  can mutate the data list without re-rendering. Hierarchy
+     *  charts (Treemap/CirclePack/TreeDiagram/OrbitDiagram) and
+     *  pure-synthetic charts (GaugeChart) declare false. */
+    supportsPush: boolean;
+    /** Renders to a static SVG via `renderChart()` from `semiotic/server`
+     *  through a registered entry in `serverChartConfigs.ts`. SSR-only
+     *  charts (none yet) and HOC-SSR exclusions also declare false. */
+    supportsSSR: boolean;
+    /**
+     * How color is consumed by the chart's data marks.
+     * - `categorical`: discrete buckets, paired with a `colorBy` accessor.
+     * - `sequential`: continuous scale (heatmap intensity, choropleth value).
+     * - `threshold`: stepped scale with explicit breakpoints (gauge zones).
+     * - `continuous`: smooth interpolation along a 1-D path (gradient fill).
+     * - `none`: chart doesn't use color encoding (sparkline, pure layout).
+     */
+    colorModel: "categorical" | "sequential" | "threshold" | "continuous" | "none";
+    /**
+     * Where the geometry comes from.
+     * - `plugin`: a built-in plugin in the frame (sankey/force/chord/tree
+     *   for network; bar/pie/swarm/etc. for ordinal; line/area/etc. for XY).
+     * - `custom`: emitted via the frame's customLayout escape hatch
+     *   (ProcessSankey via `customNetworkLayout`, NetworkCustomChart,
+     *   XYCustomChart, OrdinalCustomChart).
+     * - `synthetic`: no layout — the chart constructs its scene from
+     *   the input value(s) directly (GaugeChart computes arc geometry).
+     */
+    layoutMode: "plugin" | "custom" | "synthetic";
+    /**
+     * Free-form tag list for opt-in features that don't fit the
+     * boolean shape — e.g. "particles", "forecast", "anomaly", "brush",
+     * "streamgraph", "minimap". Used by docs feature tables and
+     * potential capability-driven AI suggestions.
+     */
+    specialFeatures: string[];
+}
+export interface ChartPropSpec {
+    /** Allowed runtime types. May be a single value or a union. */
+    type: PropType | PropType[];
+    /** Allowed enum values for string-typed props. */
+    enum?: readonly string[];
+    /** Default value surfaced in schema.json (and shown in MCP getSchema). */
+    default?: unknown;
+    /** Schema-side description; surfaces in LLM tool definitions. */
+    description?: string;
+    /**
+     * When true, the prop is included in validationMap but omitted from
+     * schema.json. Use for handler/callback props (`onClick`, `tooltip`)
+     * and pass-through escape hatches (`frameProps`) that LLMs shouldn't
+     * be asked to populate.
+     */
+    omitFromSchema?: boolean;
+}
+export interface ChartSpec {
+    /** Component name, must match the React export. */
+    name: string;
+    category: ChartCategory;
+    /** Human-readable description for schema.tools[].function.description. */
+    description: string;
+    /** Statically-required props. Push-mode optionality lives in behaviorContracts. */
+    required: string[];
+    /** Drives validation dispatch (validateArrayData / validateNetworkData / …). */
+    dataShape: DataShape;
+    /** Accessor props validated against the data shape at runtime. */
+    dataAccessors: string[];
+    /**
+     * Shared prop bags this chart composes. Bag props are merged in left-to-right
+     * order; chart-specific `ownProps` win on key collision.
+     */
+    propBags: ReadonlyArray<keyof typeof PROP_BAGS>;
+    /** Chart-specific prop spec, overlaid on top of the composed bags. */
+    ownProps: Record<string, ChartPropSpec>;
+    /**
+     * Capability matrix — declarative facts about runtime behavior.
+     * Drives docs feature tables, capability-aware AI/MCP tools, and
+     * the `check:capabilities` drift gate (which verifies, e.g., that
+     * a chart claiming `supportsSSR: true` has a matching entry in
+     * `serverChartConfigs.ts`).
+     */
+    capabilities: ChartCapabilities;
+}
+export declare const PROP_BAGS: {
+    readonly common: Record<string, ChartPropSpec>;
+    readonly xyAxis: Record<string, ChartPropSpec>;
+    readonly ordinalAxis: Record<string, ChartPropSpec>;
+    readonly realtime: Record<string, ChartPropSpec>;
+    readonly physics: Record<string, ChartPropSpec>;
+};
+export declare const ORIENTATION_ENUM: readonly ["vertical", "horizontal"];
+export declare const HORIZONTAL_VERTICAL_ENUM: readonly ["horizontal", "vertical"];
+export declare const LEGEND_POSITION_ENUM: readonly ["right", "left", "top", "bottom"];
+export declare const CURVE_ENUM: readonly ["linear", "monotoneX", "monotoneY", "step", "stepAfter", "stepBefore", "basis", "cardinal", "catmullRom"];
+export declare const CHART_MODE_ENUM: readonly ["primary", "context", "sparkline"];
+/**
+ * Compose a chart's full prop set (bags + ownProps) in deterministic order.
+ * ownProps wins on key collision so a chart can override a shared default.
+ */
+export declare function composeProps(spec: ChartSpec): Record<string, ChartPropSpec>;

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

@@ -1,131 +1,12 @@
-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" | "value";
 /**
- * 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.
+ * Single source of truth for per-chart prop specifications.
  *
- * All fields are required so a new chart entry can't omit them
- * silently — the audit's anti-goal "Do not make registry metadata
- * aspirational. It should describe real runtime behavior and be
- * checked." applies here.
+ * Spec entries are split by family (`chartSpecsXY.ts`, etc.); this module
+ * re-exports types/helpers and composes `CHART_SPECS`.
+ *
+ * See `chartSpecCore.ts` for types, prop bags, and `composeProps`.
  */
-export interface ChartCapabilities {
-    /**
-     * Render pipeline. `canvas` for Stream-Frame-driven charts that
-     * paint to canvas with SVG overlays for chrome (the common case).
-     * `svg` for charts that are pure SVG (none today, but reserved).
-     * `hybrid` for charts that use both — currently every Stream-Frame
-     * HOC qualifies as hybrid; reserve `canvas` for any future
-     * canvas-only fallback.
-     */
-    renderModes: Array<"canvas" | "svg" | "hybrid">;
-    /** Renders a legend swatch column when `colorBy` (or equivalent)
-     *  resolves to non-empty categories. */
-    supportsLegend: boolean;
-    /** Reads from a `selection` prop and dims/highlights matching
-     *  marks via `wrapStyleWithSelection` or equivalent. */
-    supportsSelection: boolean;
-    /** Produces a hover-driven selection (used by linked crosshair /
-     *  cross-filter patterns) via `linkedHover`. */
-    supportsLinkedHover: boolean;
-    /** Exposes a ref handle (`push`, `pushMany`, etc.) so consumers
-     *  can mutate the data list without re-rendering. Hierarchy
-     *  charts (Treemap/CirclePack/TreeDiagram/OrbitDiagram) and
-     *  pure-synthetic charts (GaugeChart) declare false. */
-    supportsPush: boolean;
-    /** Renders to a static SVG via `renderChart()` from `semiotic/server`
-     *  through a registered entry in `serverChartConfigs.ts`. SSR-only
-     *  charts (none yet) and HOC-SSR exclusions also declare false. */
-    supportsSSR: boolean;
-    /**
-     * How color is consumed by the chart's data marks.
-     * - `categorical`: discrete buckets, paired with a `colorBy` accessor.
-     * - `sequential`: continuous scale (heatmap intensity, choropleth value).
-     * - `threshold`: stepped scale with explicit breakpoints (gauge zones).
-     * - `continuous`: smooth interpolation along a 1-D path (gradient fill).
-     * - `none`: chart doesn't use color encoding (sparkline, pure layout).
-     */
-    colorModel: "categorical" | "sequential" | "threshold" | "continuous" | "none";
-    /**
-     * Where the geometry comes from.
-     * - `plugin`: a built-in plugin in the frame (sankey/force/chord/tree
-     *   for network; bar/pie/swarm/etc. for ordinal; line/area/etc. for XY).
-     * - `custom`: emitted via the frame's customLayout escape hatch
-     *   (ProcessSankey via `customNetworkLayout`, NetworkCustomChart,
-     *   XYCustomChart, OrdinalCustomChart).
-     * - `synthetic`: no layout — the chart constructs its scene from
-     *   the input value(s) directly (GaugeChart computes arc geometry).
-     */
-    layoutMode: "plugin" | "custom" | "synthetic";
-    /**
-     * Free-form tag list for opt-in features that don't fit the
-     * boolean shape — e.g. "particles", "forecast", "anomaly", "brush",
-     * "streamgraph", "minimap". Used by docs feature tables and
-     * potential capability-driven AI suggestions.
-     */
-    specialFeatures: string[];
-}
-export interface ChartPropSpec {
-    /** Allowed runtime types. May be a single value or a union. */
-    type: PropType | PropType[];
-    /** Allowed enum values for string-typed props. */
-    enum?: readonly string[];
-    /** Default value surfaced in schema.json (and shown in MCP getSchema). */
-    default?: unknown;
-    /** Schema-side description; surfaces in LLM tool definitions. */
-    description?: string;
-    /**
-     * When true, the prop is included in validationMap but omitted from
-     * schema.json. Use for handler/callback props (`onClick`, `tooltip`)
-     * and pass-through escape hatches (`frameProps`) that LLMs shouldn't
-     * be asked to populate.
-     */
-    omitFromSchema?: boolean;
-}
-export interface ChartSpec {
-    /** Component name, must match the React export. */
-    name: string;
-    category: ChartCategory;
-    /** Human-readable description for schema.tools[].function.description. */
-    description: string;
-    /** Statically-required props. Push-mode optionality lives in behaviorContracts. */
-    required: string[];
-    /** Drives validation dispatch (validateArrayData / validateNetworkData / …). */
-    dataShape: DataShape;
-    /** Accessor props validated against the data shape at runtime. */
-    dataAccessors: string[];
-    /**
-     * Shared prop bags this chart composes. Bag props are merged in left-to-right
-     * order; chart-specific `ownProps` win on key collision.
-     */
-    propBags: ReadonlyArray<keyof typeof PROP_BAGS>;
-    /** Chart-specific prop spec, overlaid on top of the composed bags. */
-    ownProps: Record<string, ChartPropSpec>;
-    /**
-     * Capability matrix — declarative facts about runtime behavior.
-     * Drives docs feature tables, capability-aware AI/MCP tools, and
-     * the `check:capabilities` drift gate (which verifies, e.g., that
-     * a chart claiming `supportsSSR: true` has a matching entry in
-     * `serverChartConfigs.ts`).
-     */
-    capabilities: ChartCapabilities;
-}
-export declare const PROP_BAGS: {
-    readonly common: Record<string, ChartPropSpec>;
-    readonly xyAxis: Record<string, ChartPropSpec>;
-    readonly ordinalAxis: Record<string, ChartPropSpec>;
-    readonly realtime: Record<string, ChartPropSpec>;
-};
-export declare const ORIENTATION_ENUM: readonly ["vertical", "horizontal"];
-export declare const HORIZONTAL_VERTICAL_ENUM: readonly ["horizontal", "vertical"];
-export declare const LEGEND_POSITION_ENUM: readonly ["right", "left", "top", "bottom"];
-export declare const CURVE_ENUM: readonly ["linear", "monotoneX", "monotoneY", "step", "stepAfter", "stepBefore", "basis", "cardinal", "catmullRom"];
-export declare const CHART_MODE_ENUM: readonly ["primary", "context", "sparkline"];
+export type { PropType, DataShape, ChartCategory, ChartCapabilities, ChartPropSpec, ChartSpec, } from "./chartSpecCore";
+export { PROP_BAGS, ORIENTATION_ENUM, HORIZONTAL_VERTICAL_ENUM, LEGEND_POSITION_ENUM, CURVE_ENUM, CHART_MODE_ENUM, composeProps, } from "./chartSpecCore";
+import type { ChartSpec } from "./chartSpecCore";
 export declare const CHART_SPECS: Record<string, ChartSpec>;
-/**
- * Compose a chart's full prop set (bags + ownProps) in deterministic order.
- * ownProps wins on key collision so a chart can override a shared default.
- */
-export declare function composeProps(spec: ChartSpec): Record<string, ChartPropSpec>;

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

@@ -0,0 +1,2 @@
+import type { ChartSpec } from "./chartSpecCore";
+export declare const GEO_CHART_SPECS: Record<string, ChartSpec>;

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

@@ -0,0 +1,2 @@
+import type { ChartSpec } from "./chartSpecCore";
+export declare const NETWORK_CHART_SPECS: Record<string, ChartSpec>;

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

@@ -0,0 +1,2 @@
+import type { ChartSpec } from "./chartSpecCore";
+export declare const ORDINAL_CHART_SPECS: Record<string, ChartSpec>;

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

@@ -0,0 +1,2 @@
+import type { ChartSpec } from "./chartSpecCore";
+export declare const PHYSICS_CHART_SPECS: Record<string, ChartSpec>;

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

@@ -0,0 +1,2 @@
+import type { ChartSpec } from "./chartSpecCore";
+export declare const REALTIME_CHART_SPECS: Record<string, ChartSpec>;

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

@@ -0,0 +1,2 @@
+import type { ChartSpec } from "./chartSpecCore";
+export declare const VALUE_CHART_SPECS: Record<string, ChartSpec>;

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

@@ -0,0 +1,2 @@
+import type { ChartSpec } from "./chartSpecCore";
+export declare const XY_CHART_SPECS: Record<string, ChartSpec>;

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

@@ -0,0 +1,3 @@
+/** WCAG contrast ratio between two hex colors.
+ *  Returns null if either color isn't a parseable hex. */
+export declare function contrastRatio(hex1: string, hex2: string): number | null;

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

@@ -53,6 +53,8 @@ export declare const interpolateInferno: (t: number) => string;
 export declare const interpolateMagma: (t: number) => string;
 export declare const interpolateCividis: (t: number) => string;
 export declare const interpolateTurbo: (t: number) => string;
+export declare const SEQUENTIAL_INTERPOLATORS: Record<string, (t: number) => string>;
+export declare function getSequentialInterpolator(scheme: string | undefined): (t: number) => string;
 export declare const interpolateRdBu: (t: number) => string;
 export declare const interpolatePiYG: (t: number) => string;
 export declare const interpolatePRGn: (t: number) => string;

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

@@ -2,18 +2,7 @@ import type { Datum } from "./datumTypes";
 /**
  * Predefined color schemes
  */
-export declare const COLOR_SCHEMES: {
-    category10: readonly string[];
-    tableau10: readonly string[];
-    set3: readonly string[];
-    blues: (t: number) => string;
-    reds: (t: number) => string;
-    greens: (t: number) => string;
-    oranges: (t: number) => string;
-    purples: (t: number) => string;
-    viridis: (t: number) => string;
-    plasma: (t: number) => string;
-};
+export declare const COLOR_SCHEMES: Record<string, readonly string[] | ((t: number) => string)>;
 /**
  * Default colors for charts
  */
@@ -46,6 +35,21 @@ export declare const DEPTH_PALETTE_COLORS: string[];
  * ```
  */
 export declare function getColor(dataPoint: Datum, colorBy: string | ((d: Datum) => string), colorScale?: (v: string) => string): string;
+/**
+ * Look up a color for `key` in an explicit `{ category: color }` map.
+ *
+ * Guards against two hazards of a naive `key in map` lookup on a
+ * user-supplied object: inherited prototype keys (e.g. `"toString"`,
+ * `"constructor"`) must NOT register as mapped categories, and a mapped
+ * value that isn't a usable color string (a function, number, `""`) must
+ * not leak into a fill/stroke. Returns `undefined` when the key is unmapped
+ * or its value isn't a non-empty string, so callers apply their own default.
+ *
+ * Single source of truth for object-map `colorScheme` resolution across
+ * `createColorScale`, `resolveDefaultFill`, `buildResolveColor`,
+ * `buildColorScale`, and `CategoryColorProvider`.
+ */
+export declare function resolveExplicitColor(map: Record<string, unknown>, key: string | undefined | null): string | undefined;
 /**
  * Creates a color scale function from data
  *
@@ -60,7 +64,7 @@ export declare function getColor(dataPoint: Datum, colorBy: string | ((d: Datum)
  * const color = colorScale('A') // Returns color for category 'A'
  * ```
  */
-export declare function createColorScale(data: Array<Datum>, colorBy: string, scheme?: string | string[]): (v: string) => string;
+export declare function createColorScale(data: Array<Datum>, colorBy: string, scheme?: string | string[] | Record<string, string>): (v: string) => string;
 /**
  * Generates a size function based on sizeBy configuration.
  *

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

@@ -0,0 +1,4 @@
+import type { Datum } from "./datumTypes";
+import type { Diagnosis } from "./diagnoseTypes";
+export declare function checkAnnotationConnectors(_component: string, props: Datum, out: Diagnosis[]): void;
+export declare function checkAnnotationDensity(_component: string, props: Datum, out: Diagnosis[]): void;

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

@@ -1,16 +1,11 @@
 import type { Datum } from "./datumTypes";
-export interface Diagnosis {
-    severity: "error" | "warning";
-    code: string;
-    message: string;
-    fix: string;
-}
-export interface DiagnosisResult {
-    ok: boolean;
-    diagnoses: Diagnosis[];
-}
-/** 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;
+import type { DiagnosisResult } from "./diagnoseTypes";
+export { contrastRatio } from "./colorContrast";
+export type { Diagnosis, DiagnosisResult } from "./diagnoseTypes";
+/**
+ * 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.
+ */
 export declare function diagnoseConfig(componentName: string, props: Datum): DiagnosisResult;

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

@@ -0,0 +1,9 @@
+import type { Datum } from "./datumTypes";
+import type { Diagnosis } from "./diagnoseTypes";
+export declare function checkInvertedAxis(_component: string, props: Datum, out: Diagnosis[]): void;
+export declare function checkDualAxisUnlabeled(component: string, props: Datum, out: Diagnosis[]): void;
+export declare function checkCherryPickedWindow(component: string, props: Datum, out: Diagnosis[]): void;
+export declare function checkPartToWholeNegative(component: string, props: Datum, out: Diagnosis[]): void;
+export declare function checkNonPassingCurve(component: string, props: Datum, out: Diagnosis[]): void;
+export declare function checkExtremeAspectRatio(component: string, props: Datum, out: Diagnosis[]): void;
+export declare function checkPieTooManySlices(component: string, props: Datum, out: Diagnosis[]): void;

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

@@ -0,0 +1,3 @@
+import type { Datum } from "./datumTypes";
+import type { Diagnosis } from "./diagnoseTypes";
+export declare function checkPhysicsConfig(component: string, props: Datum, out: Diagnosis[]): void;

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

@@ -0,0 +1,10 @@
+export interface Diagnosis {
+    severity: "error" | "warning";
+    code: string;
+    message: string;
+    fix: string;
+}
+export interface DiagnosisResult {
+    ok: boolean;
+    diagnoses: Diagnosis[];
+}

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

@@ -1,14 +1,25 @@
 import { createLegend } from "./legendUtils";
 import type { SelectionHookResult } from "./selectionUtils";
 import type { OnObservationCallback } from "../../store/ObservationStore";
-import type { Accessor, SelectionConfig, LinkedHoverProp, ChartMode, HoverHighlightMode } from "./types";
+import type { Accessor, SelectionConfig, LinkedHoverProp, ChartMode, HoverHighlightMode, MobileInteractionProp, ResolvedMobileInteractionConfig } from "./types";
 import type { MarginType, PartialMargin } from "../../types/marginType";
 import type { TransitionConfig } from "../../stream/types";
 import type { Datum } from "./datumTypes";
+import type { MobileVisualizationContract } from "./auditMobileVisualization";
+import type { ResponsiveRule } from "./responsiveRules";
 /**
  * Default fill color used when no colorBy is specified
  */
 export declare const DEFAULT_COLOR = "#007bff";
+export declare const MOBILE_INTERACTION_TARGET_SIZE = 44;
+export declare const MOBILE_INTERACTION_MIN_HIT_RADIUS = 24;
+export declare const MOBILE_INTERACTION_DEFAULTS: ResolvedMobileInteractionConfig;
+export declare const DISABLED_MOBILE_INTERACTION: ResolvedMobileInteractionConfig;
+export declare function resolveMobileInteraction(input: MobileInteractionProp | undefined, context?: {
+    mode?: ChartMode;
+    width?: number;
+    mobileSemantics?: MobileVisualizationContract;
+}): ResolvedMobileInteractionConfig;
 /**
  * Returns the theme's categorical palette, or undefined if no ThemeProvider or
  * the palette is empty. Safe to call outside a ThemeProvider (returns undefined).
@@ -30,7 +41,7 @@ export declare function useThemeDiverging(): string | undefined;
  * Priority: color prop > theme categorical > colorScheme > DEFAULT_COLOR.
  * When a palette is available, cycles through colors by category name.
  */
-export declare function resolveDefaultFill(color: string | undefined, themeCategorical: string[] | undefined, colorScheme: string | string[] | undefined, category: string | undefined, categoryIndexMap: Map<string, number>): string;
+export declare function resolveDefaultFill(color: string | undefined, themeCategorical: string[] | undefined, colorScheme: string | string[] | Record<string, string> | undefined, category: string | undefined, categoryIndexMap: Map<string, number>): string;
 /**
  * Resolve an accessor (string key or function) into a function.
  * Used across chart components to normalize `valueAccessor`, `categoryAccessor`, etc.
@@ -41,7 +52,7 @@ export declare function resolveAccessor<T = any>(accessor: string | ((d: Datum,
  * Returns undefined when colorBy is absent or data is empty (push API mode).
  * Supports both string and function accessors for colorBy.
  */
-export declare function useColorScale(data: Array<Datum>, colorBy: string | ((d: any, i?: number) => any) | undefined, colorScheme?: string | string[]): ((v: string) => string) | undefined;
+export declare function useColorScale(data: Array<Datum>, colorBy: string | ((d: any, i?: number) => any) | undefined, colorScheme?: string | string[] | Record<string, string>): ((v: string) => string) | undefined;
 /**
  * Hook to sort data by a value accessor.
  * Used by BarChart and DotPlot.
@@ -64,7 +75,7 @@ export declare function useSortedData(data: Array<Datum>, sort: boolean | "asc"
  * @param unwrapData - Deprecated / no-op. Hover data is always unwrapped
  *   (stream frames wrap the raw datum in { data, time, value, x, y }).
  */
-export declare function useChartSelection({ selection, linkedHover, fallbackFields, unwrapData: _unwrapData, onObservation, chartType, chartId, onClick, hoverHighlight, colorByField, }: {
+export declare function useChartSelection({ selection, linkedHover, fallbackFields, unwrapData: _unwrapData, onObservation, chartType, chartId, onClick, hoverHighlight, colorByField, mobileInteraction, }: {
     selection?: SelectionConfig;
     linkedHover?: LinkedHoverProp;
     fallbackFields?: string[];
@@ -78,6 +89,7 @@ export declare function useChartSelection({ selection, linkedHover, fallbackFiel
     }) => void;
     hoverHighlight?: HoverHighlightMode;
     colorByField?: string;
+    mobileInteraction?: ResolvedMobileInteractionConfig;
 }): {
     activeSelectionHook: SelectionHookResult | null;
     hoverSelectionHook: SelectionHookResult | null;
@@ -161,8 +173,15 @@ interface ChartModeInput {
     valueLabel?: string;
     /** When truthy, enableHover is forced true regardless of mode (LinkedCharts needs hover) */
     linkedHover?: any;
+    /** Optional mobile interaction policy surfaced through useChartMode for custom wrappers. */
+    mobileInteraction?: MobileInteractionProp;
+    /** Optional mobile semantic contract surfaced through useChartMode for custom wrappers. */
+    mobileSemantics?: MobileVisualizationContract;
+    /** Semantic responsive transformations resolved before mode defaults. */
+    responsiveRules?: ResponsiveRule[];
 }
-interface ChartModeResult {
+/** Result of {@link useChartMode} — exported so declaration emit can name it. */
+export interface ChartModeResult {
     width: number;
     height: number;
     showAxes: boolean;
@@ -186,6 +205,10 @@ interface ChartModeResult {
     };
     /** True when mode is context or sparkline — the "hide interactive chrome" union. */
     compactMode: boolean;
+    /** Resolved touch-first behavior for mobile-capable wrappers. */
+    mobileInteraction: ResolvedMobileInteractionConfig;
+    /** Mobile semantic contract after matching responsive rules are applied. */
+    mobileSemantics: MobileVisualizationContract | undefined;
 }
 /**
  * Resolve chart display mode into concrete prop defaults.

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

@@ -0,0 +1,3 @@
+export declare function getMinMax(values: ReadonlyArray<number>): [number, number];
+export declare function getMin(values: ReadonlyArray<number>, fallback?: number): number;
+export declare function getMax(values: ReadonlyArray<number>, fallback?: number): number;