semiotic 3.7.5 → 3.8.1

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

@@ -0,0 +1,205 @@
+/**
+ * Declarative, threshold-aware style rules for data marks.
+ *
+ * A `StyleRule[]` is an ordered list of `{ when, style }` pairs. Every rule
+ * whose `when` condition matches a datum contributes its `style`; styles are
+ * merged in list order so — for any single property — the **last applicable
+ * rule wins**. This is the CSS-cascade mental model: send as many rules as
+ * you like, and the last one that applies to a given property is the one you
+ * see. A datum that matches no rule keeps the chart's resolved base style.
+ *
+ * `when` is intentionally permissive: it can be a predicate function (full
+ * control), a declarative numeric/categorical threshold (no code), or simply
+ * omitted / `true` (an unconditional base layer). Threshold conditions read a
+ * numeric value from `field` (falling back to the chart-provided value, e.g.
+ * a bar's `valueAccessor`), so `{ when: { gt: 10 }, style: {...} }` "styles
+ * every bar taller than 10" with no accessor boilerplate.
+ *
+ * The engine is chart-agnostic — it operates on a raw datum plus a small
+ * context (`value`, `category`, `index`). Bar-family HOCs feed it through
+ * `useOrdinalPieceStyle`, but any renderer with a datum and a numeric value
+ * can reuse it.
+ */
+import type { Datum } from "./datumTypes";
+import type { HatchFill } from "./hatchFill";
+/** The style a rule applies. `fill` may be a solid color or a {@link HatchFill}. */
+export interface StyleRuleStyle {
+    /** Solid color string, a CSS var, or a declarative hatch descriptor. */
+    fill?: string | HatchFill;
+    fillOpacity?: number;
+    stroke?: string;
+    strokeWidth?: number;
+    strokeDasharray?: string;
+    opacity?: number;
+}
+/**
+ * A declarative numeric / categorical condition. All present operators must
+ * hold (logical AND). The compared value is chosen in this order:
+ *   1. `axis` — a resolved context channel (`"x"` / `"y"` / `"value"`), so a
+ *      rule can target either axis of an XY chart regardless of the accessor
+ *      field name (e.g. `{ axis: "y", gt: 10 }`).
+ *   2. `field` — a raw datum property (`datum[field]`).
+ *   3. otherwise the host-resolved context value (`ctx.value` — the bar value,
+ *      the y value for XY, the node/feature/body value, etc.).
+ */
+export interface StyleRuleThreshold {
+    /**
+     * Compare against a resolved context channel rather than a raw field. Use to
+     * target an XY chart's `"x"` or `"y"` axis without knowing the accessor's
+     * field name. `"value"` is the same channel the field-less default uses.
+     */
+    axis?: "x" | "y" | "value";
+    /** Datum field to compare. Defaults to the host-resolved context value. */
+    field?: string;
+    /** value > n */
+    gt?: number;
+    /** value >= n */
+    gte?: number;
+    /** value < n */
+    lt?: number;
+    /** value <= n */
+    lte?: number;
+    /** value === n (numeric or string equality) */
+    eq?: number | string;
+    /** value !== n */
+    ne?: number | string;
+    /** min <= value <= max (inclusive) */
+    within?: [number, number];
+    /** value < min OR value > max */
+    outside?: [number, number];
+    /** value is one of the listed values */
+    in?: Array<number | string>;
+}
+/**
+ * Context passed to predicate / style functions and threshold resolution.
+ * Which channels are populated depends on the chart family:
+ *  - ordinal bars: `value` (bar value), `category` (stack/group key)
+ *  - XY: `value` (= `y`), `x`, `y`
+ *  - network nodes: `value` (node size/value), `category` (group / colorBy)
+ *  - geo features: `value` (feature value), `category`
+ *  - physics particles: `value` (body value), `category` (colorBy group)
+ */
+export interface StyleRuleContext {
+    /** Primary numeric value the host resolved (bar value; XY y; node/feature/body value). */
+    value: number | undefined;
+    /** Resolved x value (XY family). */
+    x?: number;
+    /** Resolved y value (XY family; usually equals `value`). */
+    y?: number;
+    /** Resolved size value (bubble / symbol `sizeBy`, node size), when known. */
+    size?: number;
+    /** Category / series / stack / group key, when the host knows one. */
+    category?: string;
+    /** Positional index, when the host provides one. */
+    index?: number;
+}
+/** A `when` predicate: full programmatic control over matching. */
+export type StyleRulePredicate = (datum: Datum, ctx: StyleRuleContext) => boolean;
+/**
+ * One declarative style rule. `when` may be:
+ *  - a **predicate** `(datum, ctx) => boolean`
+ *  - a **threshold** object (`{ gt, lte, within, in, … }`)
+ *  - `true` / omitted — always matches (an unconditional base layer)
+ *  - `false` — never matches (temporarily disable a rule)
+ */
+export interface StyleRule {
+    /** Optional stable id — handy for legends, debugging, and docs. */
+    id?: string;
+    /** Match condition. Omitted / `true` ⇒ always applies. */
+    when?: StyleRulePredicate | StyleRuleThreshold | boolean;
+    /** Style to apply when matched. Object, or a per-datum function. */
+    style: StyleRuleStyle | ((datum: Datum, ctx: StyleRuleContext) => StyleRuleStyle);
+    /** Optional human label (legend / documentation only). */
+    label?: string;
+}
+/**
+ * Build a stable-ish resolver that reads a numeric value from a datum via a
+ * string field or accessor function — the value threshold rules compare
+ * against when their `field` is omitted. Memoize the result in the host
+ * component keyed on the accessor (string accessors are already stable).
+ */
+export declare function makeRuleValueResolver(accessor: string | ((d: Datum) => unknown) | undefined): (d: Datum) => number | undefined;
+/**
+ * Build the XY `StyleRuleContext` resolver from x/y accessors: populates
+ * `value` (= y), `x`, and `y` so thresholds can target either axis via
+ * `{ axis: "x" }` / `{ axis: "y" }` regardless of the accessor field names.
+ * Shared by the XY client hooks and the XY server render configs. Memoize in
+ * the host keyed on the accessors.
+ */
+export declare function makeXYRuleContext(xAccessor: string | ((d: Datum) => unknown) | undefined, yAccessor: string | ((d: Datum) => unknown) | undefined): (d: Datum, category?: string) => StyleRuleContext;
+/**
+ * Build the network-node `StyleRuleContext` resolver: `value` from a numeric
+ * field (defaults to the node's `value`) and `category` from the `colorBy`
+ * group. Rules resolve against the raw node object (unwrap `RealtimeNode.data`
+ * first). Shared by network client HOCs and the network server configs.
+ */
+export declare function makeNodeRuleContext(colorBy: string | ((d: Datum) => unknown) | undefined, valueAccessor?: string | ((d: Datum) => unknown)): (raw: Datum) => StyleRuleContext;
+/**
+ * Evaluate a declarative threshold against a datum + context. Returns `false`
+ * when the compared value can't be resolved to a finite number (except for the
+ * purely categorical `eq`/`ne`/`in` operators, which also accept strings).
+ */
+export declare function matchesThreshold(threshold: StyleRuleThreshold, datum: Datum, ctx: StyleRuleContext): boolean;
+/** Does a single rule's `when` condition match this datum? */
+export declare function ruleMatches(rule: StyleRule, datum: Datum, ctx: StyleRuleContext): boolean;
+/**
+ * Resolve an ordered rule list to a single merged style. Every matching
+ * rule's style is spread in list order, so for any given property the last
+ * applicable rule wins. Returns an empty object when nothing matches (the
+ * host chart's base style is then used unchanged).
+ */
+export declare function resolveStyleRules(datum: Datum, rules: ReadonlyArray<StyleRule> | undefined, ctx: StyleRuleContext): StyleRuleStyle;
+/** A per-mark style function the pipelines accept (`fill` may be a HatchFill). */
+type MarkStyleFn = (d: Datum, arg?: string) => StyleRuleStyle;
+/**
+ * Client-side composition: wrap a base per-mark style function so declarative
+ * rules layer OVER its output (rules win per property), matching the ordinal
+ * `useOrdinalPieceStyle` behavior for every other family. The base style runs
+ * first (resolving the mark's base color); the merged rule style is spread on
+ * top. Returns the base function unchanged when there are no rules, so it's a
+ * zero-cost pass-through in the common case.
+ *
+ * `buildContext` populates the `StyleRuleContext` channels the family's rules
+ * read (`value`, `x`, `y`, `category`…). `unwrap` handles frames whose style
+ * callbacks receive a wrapper rather than the raw datum (e.g. network's
+ * `RealtimeNode`, whose user object lives on `.data`) — rules and
+ * `buildContext` see the unwrapped raw datum, while the base function still
+ * receives the original argument.
+ */
+export declare function composeStyleRules<A = string>(baseStyleFn: ((d: Datum, arg?: A) => Datum) | undefined, rules: ReadonlyArray<StyleRule> | undefined, buildContext: (raw: Datum, arg?: A) => StyleRuleContext, unwrap?: (d: Datum) => Datum): (d: Datum, arg?: A) => Datum;
+/**
+ * Compose style rules into a per-mark style function. It resolves the merged
+ * rule style from a per-datum `StyleRuleContext` (built by `buildContext`),
+ * then overlays a user-supplied style function (which wins). Marks left
+ * unmatched return an empty style so the frame's own base-color resolver fills
+ * them.
+ *
+ * This is the family-agnostic primitive behind the server render path (which
+ * builds frame props directly instead of going through a HOC hook). Each
+ * family supplies the `buildContext` that populates the channels its threshold
+ * rules read — `value` for bars, `{ value, x, y }` for XY, node value/group
+ * for network, etc. — so all families share one rule-resolution core.
+ *
+ * @param arg the second style-fn argument (ordinal category / stack key). It is
+ *   passed through to `buildContext` and the user style fn unchanged.
+ */
+export declare function makeStyleRuleStyleFn(rules: ReadonlyArray<StyleRule> | undefined, buildContext: (d: Datum, arg?: string) => StyleRuleContext, userStyleFn?: MarkStyleFn): MarkStyleFn | undefined;
+/**
+ * Network-flavored server helper: resolves rules against the raw node (the
+ * server frame passes a `RealtimeNode` wrapper whose user object is on
+ * `.data`), with `{ value, category }` context from `makeNodeRuleContext`. A
+ * user `nodeStyle` overlays and wins. `undefined` when there are no rules.
+ */
+export declare function styleRulesToNodeStyle(rules: ReadonlyArray<StyleRule> | undefined, colorBy: string | ((d: Datum) => unknown) | undefined, valueAccessor: string | ((d: Datum) => unknown) | undefined, userNodeStyle?: (d: Datum, arg?: number) => Datum): ((d: Datum, arg?: number) => Datum) | undefined;
+/**
+ * XY-flavored server helper: `{ value: y, x, y }` context from `makeXYRuleContext`.
+ * Feeds `pointStyle` / `lineStyle`. A user style overlays and wins.
+ */
+export declare function styleRulesToXYStyle(rules: ReadonlyArray<StyleRule> | undefined, xAccessor: string | ((d: Datum) => unknown) | undefined, yAccessor: string | ((d: Datum) => unknown) | undefined, userStyle?: MarkStyleFn): MarkStyleFn | undefined;
+/**
+ * Ordinal-flavored {@link makeStyleRuleStyleFn}: the context is
+ * `{ value: valueAccessor(d), category }` — the bar/piece value plus the
+ * stack/group key. Kept as sugar for the ordinal server config.
+ */
+export declare function styleRulesToPieceStyle(rules: ReadonlyArray<StyleRule> | undefined, valueAccessor: string | ((d: Datum) => unknown) | undefined, userPieceStyle?: MarkStyleFn): MarkStyleFn | undefined;
+export {};

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

@@ -0,0 +1,7 @@
+import type { Datum } from "./datumTypes";
+export declare function parseDateLikeString(value: string): number;
+export declare function coerceDateLikeValue(value: unknown): number;
+export declare function coerceTemporalStringRows(data: Datum[] | undefined, fieldName: string | undefined): {
+    data: Datum[] | undefined;
+    failed: boolean;
+};

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

@@ -1,9 +1,16 @@
 import * as React from "react";
 import type { HoverData } from "../../realtime/types";
 import type { Datum } from "./datumTypes";
+export type TooltipValue = string | number | boolean | Date | Datum | Datum[] | null | undefined;
+type TooltipAccessor = string | {
+    bivarianceHack(datum: Datum): TooltipValue;
+}["bivarianceHack"];
+type TooltipFormatter = {
+    bivarianceHack(value: TooltipValue, index?: number, allTicks?: number[]): React.ReactNode;
+}["bivarianceHack"];
 export interface TooltipFieldConfig {
     label: string;
-    accessor: string | ((d: any) => any);
+    accessor: TooltipAccessor;
     role?: "title" | "x" | "y" | "color" | "size" | "group" | "value";
     /** Per-field formatter. HOCs pass `xFormat`/`yFormat`/`valueFormat` here so
      *  the default tooltip renders values consistently with the axis. Typed
@@ -12,15 +19,15 @@ export interface TooltipFieldConfig {
      *  (`(d, index?, allTicks?) => ReactNode`). A ReactNode return renders
      *  as-is in the tooltip span. If the formatter throws, the tooltip
      *  falls back to the built-in `formatVal`. */
-    format?: (v: any, ...rest: any[]) => React.ReactNode;
+    format?: TooltipFormatter;
 }
 /**
  * Extract a display name from an accessor.
  * Strings return themselves; functions return "value".
  */
-export declare function accessorName(acc: string | ((...args: any[]) => any)): string;
+export declare function accessorName(acc: TooltipAccessor): string;
 export declare function formatVal(v: unknown): string;
-export declare function resolveValue(d: Datum, acc: string | ((d: Datum) => any)): unknown;
+export declare function resolveValue(d: Datum, acc: TooltipAccessor): TooltipValue;
 export { smartTooltipEntries } from "./smartTooltip";
 export type { SmartTooltipEntry, SmartTooltipResult } from "./smartTooltip";
 /**
@@ -33,7 +40,13 @@ export type { SmartTooltipEntry, SmartTooltipResult } from "./smartTooltip";
  * Returns an empty array when band is not configured, so the spread at
  * the call site is a no-op for the common case.
  */
-export declare function bandTooltipFields(band: unknown, valueFormat?: (v: any, ...rest: any[]) => React.ReactNode): TooltipFieldConfig[];
+export declare function bandTooltipFields(band: {
+    y0Accessor?: TooltipAccessor;
+    y1Accessor?: TooltipAccessor;
+} | Array<{
+    y0Accessor?: TooltipAccessor;
+    y1Accessor?: TooltipAccessor;
+}> | null | undefined, valueFormat?: TooltipFormatter): TooltipFieldConfig[];
 /**
  * Build a default tooltipContent function for StreamXYFrame HOCs.
  * Receives HoverData ({ data, time, value, x, y }) and renders
@@ -48,13 +61,13 @@ export declare function buildDefaultTooltip(fields: TooltipFieldConfig[]): (hove
  *   (PieChart/DonutChart wrap data in arrays). Default: `d.data || d`.
  */
 export declare function buildOrdinalTooltip({ categoryAccessor, valueAccessor, groupAccessor, groupLabel, pieData, valueFormat, }: {
-    categoryAccessor: string | ((d: Datum) => any);
-    valueAccessor: string | ((d: Datum) => any);
-    groupAccessor?: string | ((d: Datum) => any);
+    categoryAccessor: TooltipAccessor;
+    valueAccessor: TooltipAccessor;
+    groupAccessor?: TooltipAccessor;
     groupLabel?: string;
     pieData?: boolean;
     /** Same formatter the HOC passes to the value axis. Threaded here so the
      *  default tooltip shows values consistently with the axis ("$450k", not
      *  "450000"). Override by passing a custom `tooltip` prop. */
-    valueFormat?: (v: any, ...rest: any[]) => React.ReactNode;
+    valueFormat?: TooltipFormatter;
 }): (d: Datum) => React.ReactNode;

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

@@ -2,8 +2,10 @@ import type React from "react";
 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 { Datum, DatumValue } from "./datumTypes";
 import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
+import type { ResponsiveRule } from "./responsiveRules";
+import type { MobileVisualizationContract } from "./auditMobileVisualization";
 /**
  * Selection consumption config — makes this chart react to a named selection
  */
@@ -44,7 +46,7 @@ export type LinkedBrushProp = string | {
  * Chart display mode — controls default chrome, size, and interaction.
  * User-provided props always override mode defaults.
  */
-export type ChartMode = "primary" | "context" | "sparkline";
+export type ChartMode = "primary" | "context" | "sparkline" | "mobile";
 /**
  * Hover highlighting mode.
  * `true` and `"series"` both dim non-hovered series/categories; the string
@@ -52,6 +54,46 @@ export type ChartMode = "primary" | "context" | "sparkline";
  * more explicit per-series mode.
  */
 export type HoverHighlightMode = boolean | "series";
+export type MobileClearSelectionBehavior = "backgroundTap" | "none";
+export type MobileSnapBehavior = "nearestDatum" | "none";
+export type MobileStandardControlKind = "brush" | "zoom" | "legend";
+export type MobileStandardControlsMode = boolean | "all" | MobileStandardControlKind | MobileStandardControlKind[];
+/**
+ * Touch-first interaction policy for phone-sized chart slots.
+ *
+ * This is intentionally shared by built-in charts, custom charts, audits, and
+ * generated/interoperable chart manifests so mobile behavior is not a
+ * second-class per-component escape hatch.
+ */
+export interface MobileInteractionConfig {
+    /** Explicitly enable or disable mobile interaction for an object config. */
+    enabled?: boolean;
+    /** Convert tap/click on a datum into a persistent selection when possible. */
+    tapToSelect?: boolean;
+    /** Convert hover-linked detail into a tap-lockable state on touch devices. */
+    tapToLockTooltip?: boolean;
+    /** Clear the mobile interaction state when the frame reports a background tap. */
+    clearSelection?: MobileClearSelectionBehavior;
+    /** Comfortable touch target in CSS pixels. Defaults to 44 when mobile is active. */
+    targetSize?: number;
+    /** Hit-testing strategy for imprecise touch input. */
+    snap?: MobileSnapBehavior;
+    /** Preferred brush handle size in CSS pixels for mobile brush affordances. */
+    brushHandleSize?: number;
+    /** Signals that a brush/zoom/legend gesture has a standard-control alternative. */
+    standardControls?: MobileStandardControlsMode;
+}
+export type MobileInteractionProp = boolean | MobileInteractionConfig;
+export interface ResolvedMobileInteractionConfig {
+    enabled: boolean;
+    tapToSelect: boolean;
+    tapToLockTooltip: boolean;
+    clearSelection: MobileClearSelectionBehavior;
+    targetSize: number;
+    snap: MobileSnapBehavior;
+    brushHandleSize: number;
+    standardControls: MobileStandardControlsMode;
+}
 /**
  * Base props shared across all chart components
  */
@@ -72,6 +114,12 @@ export interface BaseChartProps {
     responsiveWidth?: boolean;
     /** Auto-match height to parent container (requires parent with explicit height). Default: false */
     responsiveHeight?: boolean;
+    /** Semantic responsive transformations keyed by measured chart slot, not CSS alone. */
+    responsiveRules?: ResponsiveRule[];
+    /** Phone/mobile contract consumed by audits, recipes, adapters, and agents. */
+    mobileSemantics?: MobileVisualizationContract;
+    /** Touch-first interaction policy for phone-sized chart slots. */
+    mobileInteraction?: MobileInteractionProp;
     /** CSS class name for the chart container */
     className?: string;
     /** Chart title displayed at the top */
@@ -116,10 +164,7 @@ export interface BaseChartProps {
     accessibleTable?: boolean;
     /** Callback when a data element is clicked. Receives the original datum and pixel coordinates.
      * For lines, receives the line data; for bars, the bar datum; for pie slices, the slice datum. */
-    onClick?: (datum: any, event: {
-        x: number;
-        y: number;
-    }) => void;
+    onClick?: DatumClickHandler;
     /** Dim non-hovered series when hovering a data mark. Requires `colorBy`. */
     hoverHighlight?: HoverHighlightMode;
     /** Max pixel distance for hover/click hit testing. Default 30. Increase for sparse charts, decrease for dense ones. */
@@ -150,6 +195,12 @@ export interface BaseChartProps {
      *  - Network / geo / hierarchy charts: no-op (no continuous axis). */
     axisExtent?: import("./axisExtent").AxisExtentMode;
 }
+export type DatumClickHandler = {
+    bivarianceHack(datum: Datum, event: {
+        x: number;
+        y: number;
+    }): void;
+}["bivarianceHack"];
 /**
  * Axis configuration props
  */
@@ -172,7 +223,7 @@ export type CategoryFormatFn = (label: string, index?: number) => string | React
  * Accessor type - can be a property name or a function
  * @deprecated Use DataAccessor from generalTypes for generic type safety
  */
-export type Accessor<T = any> = string | ((d: any, i?: number) => T);
+export type Accessor<T = DatumValue> = string | ((d: Datum, i?: number) => T);
 /**
  * Generic accessor type that provides autocomplete when TDatum is specified.
  * Uses Datum in the function param so HOC charts can pass

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

@@ -3,6 +3,11 @@ import type { Datum } from "./datumTypes";
 import type { Accessor, ChartAccessor } from "./types";
 import type { SelectionHookResult } from "./selectionUtils";
 import type { HoverData } from "../../stream/types";
+import type { BandConfig } from "../../stream/types";
+import { type StyleRule, type StyleRuleContext } from "./styleRules";
+import type { HatchFill } from "./hatchFill";
+/** Values a resolved area/line style may carry (`fill` can be a HatchFill). */
+type AreaStyleValue = string | number | HatchFill | CanvasPattern | undefined;
 export interface AreaSeriesSetupOptions<TDatum extends Datum = Datum> {
     /** Sparse-filtered data array (the HOC's `safeData`). */
     safeData: TDatum[];
@@ -54,14 +59,22 @@ export interface AreaSeriesSetupOptions<TDatum extends Datum = Datum> {
     groupField?: Accessor<string> | ChartAccessor<TDatum, string>;
     /** Optional band prop — when set, the default tooltip surfaces a
      *  pair of rows per band (low + high). Threaded through verbatim. */
-    band?: unknown;
+    band?: BandConfig<TDatum> | Array<BandConfig<TDatum>>;
+    /**
+     * Declarative style rules, merged on top of the resolved area fill/stroke
+     * (last-applicable rule wins). Per-series: resolves against the series'
+     * sample datum. A rule `fill` may be a color or a HatchFill.
+     */
+    styleRules?: ReadonlyArray<StyleRule>;
+    /** Build the `StyleRuleContext` for a series sample datum. */
+    ruleContext?: (d: Datum) => StyleRuleContext;
 }
 export interface AreaSeriesSetupResult<TDatum extends Datum = Datum> {
     /** Flat data array ready for `<StreamXYFrame data={…} />`. Empty
      *  when the HOC is in push mode (no `data` prop). */
     flattenedData: TDatum[];
     /** Selection-aware line/area style fn. */
-    lineStyle: (d: Datum) => Record<string, string | number>;
+    lineStyle: (d: Datum) => Record<string, AreaStyleValue>;
     /** Selection-aware point style fn — `undefined` when `showPoints`
      *  is false so the HOC can spread it conditionally. */
     pointStyle: ((d: Datum) => Record<string, string | number>) | undefined;
@@ -76,3 +89,4 @@ export interface AreaSeriesSetupResult<TDatum extends Datum = Datum> {
  * verbatim before extraction.
  */
 export declare function useAreaSeriesSetup<TDatum extends Datum = Datum>(options: AreaSeriesSetupOptions<TDatum>): AreaSeriesSetupResult<TDatum>;
+export {};

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

@@ -1,7 +1,8 @@
 import type { Datum } from "./datumTypes";
 import { useChartLegendAndMargin, useLegendInteraction, DEFAULT_COLOR } from "./hooks";
 import type { LegendInteractionMode, LegendPosition } from "./hooks";
-import type { Accessor, SelectionConfig, LinkedHoverProp, HoverHighlightMode } from "./types";
+import type { Accessor, SelectionConfig, LinkedHoverProp, HoverHighlightMode, MobileInteractionProp, ResolvedMobileInteractionConfig } from "./types";
+import type { MobileVisualizationContract } from "./auditMobileVisualization";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { PartialMargin } from "../../types/marginType";
 import type { SelectionHookResult } from "./selectionUtils";
@@ -17,11 +18,11 @@ export interface ChartSetupInput {
     /** The data array used for color scale and category extraction */
     data: Array<Datum>;
     /** The original data prop (may be undefined) — used for empty-state check */
-    rawData: unknown[] | undefined;
+    rawData: Array<Datum | null | undefined> | undefined;
     /** The color-by accessor (may be an "actual" colorBy derived from stackBy/groupBy/categoryAccessor) */
     colorBy: Accessor<string> | undefined;
     /** Color scheme name or custom array — undefined lets useColorScale consult the theme */
-    colorScheme: string | string[] | undefined;
+    colorScheme: string | string[] | Record<string, string> | undefined;
     /** Legend interaction mode */
     legendInteraction: LegendInteractionMode | undefined;
     /** Legend position override */
@@ -52,12 +53,16 @@ export interface ChartSetupInput {
         right: number;
     };
     /** onClick callback */
-    onClick?: (datum: any, event: {
+    onClick?: (datum: Datum, event: {
         x: number;
         y: number;
     }) => void;
     /** Dim non-hovered series on data mark hover */
     hoverHighlight?: HoverHighlightMode;
+    /** Touch-first interaction policy for phone-sized chart slots */
+    mobileInteraction?: MobileInteractionProp;
+    /** Mobile semantic contract for generated/audited/mobile-aware chart behavior */
+    mobileSemantics?: MobileVisualizationContract;
     /** Loading state */
     loading: boolean | undefined;
     /** Custom content rendered in place of the default skeleton while `loading` is true. */
@@ -95,6 +100,8 @@ export interface ChartSetupResult {
     customHoverBehavior: (d: Datum | null) => void;
     /** Custom click behavior callback for the frame */
     customClickBehavior: (d: Datum | null) => void;
+    /** Resolved touch-first policy for chart wrappers and stream-prop helpers */
+    mobileInteraction: ResolvedMobileInteractionConfig;
     /** Legend config (or undefined if no legend) */
     legend: ReturnType<typeof useChartLegendAndMargin>["legend"];
     /** Computed margin with legend-aware adjustments */

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

@@ -1,7 +1,9 @@
 import type { Ref, RefObject, ReactElement, ReactNode } from "react";
 import { useChartMode } from "./hooks";
 import { type ChartSetupResult } from "./useChartSetup";
-import type { ChartMode, SelectionConfig, LinkedHoverProp } from "./types";
+import type { Accessor, ChartMode, SelectionConfig, LinkedHoverProp, MobileInteractionProp } from "./types";
+import type { MobileVisualizationContract } from "./auditMobileVisualization";
+import type { ResponsiveRule } from "./responsiveRules";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import { type PartialMargin, type MarginType } from "../../types/marginType";
 import type { Datum } from "./datumTypes";
@@ -17,7 +19,7 @@ interface ScaffoldOptions {
     /** Ref forwarded by the HOC. The hook binds the imperative handle internally. */
     imperativeRef: Ref<RealtimeFrameHandle> | undefined;
     /** Which `useFrameImperativeHandle` variant to bind. XY/ordinal frames share "xy". */
-    imperativeVariant: "xy" | "network";
+    imperativeVariant: "xy" | "network" | "geo-points";
     /** Margin shorthand or sided form from the HOC's `margin` prop. */
     margin: PartialMargin | undefined;
     width?: number;
@@ -26,6 +28,12 @@ interface ScaffoldOptions {
     enableHover?: boolean;
     showLegend?: boolean;
     title?: string;
+    description?: string;
+    summary?: string;
+    accessibleTable?: boolean;
+    mobileInteraction?: MobileInteractionProp;
+    mobileSemantics?: MobileVisualizationContract;
+    responsiveRules?: ResponsiveRule[];
     mode?: ChartMode;
     xLabel?: string;
     yLabel?: string;
@@ -39,7 +47,7 @@ interface ScaffoldResult<TFrameHandle> {
     normalizedMargin: Partial<MarginType> | undefined;
 }
 /**
- * Scaffold shared by all three custom-layout HOCs: imperative-handle
+ * Scaffold shared by all four custom-layout HOCs: imperative-handle
  * binding, chart-mode resolution, margin normalization. Network HOCs
  * stop here; data-shaped HOCs layer `useChartSetup` on top via
  * `useCustomChartSetup`.
@@ -53,15 +61,19 @@ interface DataSetupOptions extends ScaffoldOptions {
     /** Whether the hover callback should unwrap the datum (ordinal/network = true, XY = false). */
     unwrapData: boolean;
     /** Color scheme threaded into useChartSetup's color resolution. */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
+    /** Semantic color accessor for legend, linked-hover series mode, and frame color config. */
+    colorBy?: Accessor<string>;
     /** Pass-through chart-setup inputs. */
     selection?: SelectionConfig;
     linkedHover?: LinkedHoverProp;
     onObservation?: OnObservationCallback;
-    onClick?: (datum: any, ev: {
+    onClick?: (datum: Datum, ev: {
         x: number;
         y: number;
     }) => void;
+    mobileInteraction?: MobileInteractionProp;
+    mobileSemantics?: MobileVisualizationContract;
     chartId?: string;
     loading?: boolean;
     loadingContent?: ReactNode | false;

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

@@ -1,4 +1,4 @@
-import type { Ref, RefObject, DependencyList } from "react";
+import type { Ref, RefObject } from "react";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 type FrameVariant = "xy" | "network" | "geo-points" | "geo-lines";
 interface Options {
@@ -15,7 +15,6 @@ interface Options {
     variant: FrameVariant;
     frameRef: RefObject<unknown>;
     overrides?: Partial<RealtimeFrameHandle>;
-    deps?: DependencyList;
 }
 /**
  * Wire up the HOC's exposed `ref` to the inner frame ref using the

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

@@ -30,11 +30,11 @@ export declare function resolveAccessorFn<T>(accessor: string | ((d: Datum) => T
  * Interpolates from red → gray → blue for odd, red → blue for even.
  */
 export declare function defaultDivergingScheme(n: number, themeDivergingSchemeName?: string): string[];
-export declare function aggregateData(data: any[], levels: string[], getCat: (d: Datum) => string, getScore: ((d: Datum) => number) | null, getLevel: ((d: Datum) => string) | null, getCount: ((d: Datum) => number) | null): AggregatedRow[];
+export declare function aggregateData(data: Datum[], levels: string[], getCat: (d: Datum) => string, getScore: ((d: Datum) => number) | null, getLevel: ((d: Datum) => string) | null, getCount: ((d: Datum) => number) | null): AggregatedRow[];
 export declare function toDivergingValues(rows: AggregatedRow[], levels: string[]): AggregatedRow[];
 export declare function orderForDiverging(rows: AggregatedRow[], levels: string[]): AggregatedRow[];
 interface UseLikertAggregationConfig {
-    data: any[] | undefined;
+    data: Datum[] | undefined;
     levels: string[];
     categoryAccessor?: string | ((d: Datum) => string);
     valueAccessor?: string | ((d: Datum) => number);
@@ -47,9 +47,9 @@ interface UseLikertAggregationResult {
     /** Pre-processed data for static mode */
     processedData: AggregatedRow[];
     /** Re-aggregate all accumulated data (call from push handlers) */
-    reAggregate: (rawData: any[]) => void;
+    reAggregate: (rawData: Datum[]) => void;
     /** Ref holding accumulated raw data for push mode */
-    accumulatorRef: MutableRefObject<any[]>;
+    accumulatorRef: MutableRefObject<Datum[]>;
 }
 /**
  * Encapsulates Likert-specific data aggregation:

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

@@ -1,6 +1,7 @@
 import type { ReactNode, ReactElement } from "react";
 import type { Datum } from "./datumTypes";
-import type { Accessor, ChartAccessor, SelectionConfig, LinkedHoverProp } from "./types";
+import type { Accessor, ChartAccessor, SelectionConfig, LinkedHoverProp, MobileInteractionProp, ResolvedMobileInteractionConfig } from "./types";
+import type { MobileVisualizationContract } from "./auditMobileVisualization";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { PartialMargin, MarginType } from "../../types/marginType";
 import { useChartSelection, useChartLegendAndMargin } from "./hooks";
@@ -23,7 +24,7 @@ export interface NetworkChartSetupInput<TNode extends Datum = Datum, TEdge exten
     /** Edge target accessor (used by `inferNodesFromEdges`). */
     targetAccessor?: ChartAccessor<TEdge, string>;
     colorBy?: Accessor<string>;
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /** `undefined` defaults to "auto" (on when colorBy is set). */
     showLegend?: boolean;
     legendPosition?: LegendPosition;
@@ -35,6 +36,8 @@ export interface NetworkChartSetupInput<TNode extends Datum = Datum, TEdge exten
         x: number;
         y: number;
     }) => void;
+    mobileInteraction?: MobileInteractionProp;
+    mobileSemantics?: MobileVisualizationContract;
     /** Used by useChartSelection for chart-type-stamped observation events. */
     chartType: string;
     chartId?: string;
@@ -94,6 +97,7 @@ export interface NetworkChartSetupResult {
     legend: ReturnType<typeof useChartLegendAndMargin>["legend"];
     margin: MarginType;
     legendPosition: LegendPosition;
+    mobileInteraction: ResolvedMobileInteractionConfig;
     customHoverBehavior: ReturnType<typeof useChartSelection>["customHoverBehavior"];
     customClickBehavior: ReturnType<typeof useChartSelection>["customClickBehavior"];
     /**

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

@@ -1,4 +1,5 @@
 import type { ChartAccessor } from "./types";
+import type { Datum } from "./datumTypes";
 export interface OrdinalBrushInput {
     brushProp: boolean | undefined;
     onBrushProp: ((extent: {
@@ -8,7 +9,7 @@ export interface OrdinalBrushInput {
         name: string;
         rField?: string;
     } | undefined;
-    valueAccessor: ChartAccessor<any, number>;
+    valueAccessor: ChartAccessor<Datum, number>;
 }
 export interface OrdinalBrushResult {
     hasBrush: boolean;