semiotic 3.7.4 → 3.8.0

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

@@ -0,0 +1,145 @@
+import type { Datum } from "./datumTypes";
+import { type LifecycleBand, type LifecycleBandThresholds } from "../../realtime/lifecycleBands";
+/** Explicit literal wrapper for channels whose values could be field names. */
+export interface MotionEncodingConstant<TValue> {
+    constant: TValue;
+}
+/** A motion channel can read a field, calculate a value, or use a constant. */
+export type MotionEncodingAccessor<TDatum, TValue> = keyof TDatum | ((datum: TDatum, index: number) => TValue) | MotionEncodingConstant<TValue>;
+/** The clock that gives an arrival or age value meaning. */
+export type MotionTimeBasis = "event" | "ingest" | "simulation" | "presentation" | "buffer-index";
+/** Motion helpers do not convert units; related values must use the same unit. */
+export type MotionTimeUnit = "milliseconds" | "seconds" | "frames" | "index";
+/** Coordinate system in which placement or velocity values are expressed. */
+export type MotionCoordinateSpace = "data" | "world" | "screen";
+export interface MotionTimeEncoding<TDatum> {
+    /** Time at which the datum enters the represented system. */
+    arrival?: MotionEncodingAccessor<TDatum, number>;
+    basis?: MotionTimeBasis;
+    unit?: MotionTimeUnit;
+}
+export interface MotionPlacementEncoding<TDatum> {
+    x?: MotionEncodingAccessor<TDatum, number>;
+    y?: MotionEncodingAccessor<TDatum, number>;
+    lane?: MotionEncodingAccessor<TDatum, string | number>;
+    space?: MotionCoordinateSpace;
+}
+export interface MotionKinematicsEncoding<TDatum> {
+    velocityX?: MotionEncodingAccessor<TDatum, number>;
+    velocityY?: MotionEncodingAccessor<TDatum, number>;
+    space?: MotionCoordinateSpace;
+}
+export interface MotionProcessEncoding<TDatum> {
+    group?: MotionEncodingAccessor<TDatum, string | number>;
+    stage?: MotionEncodingAccessor<TDatum, string | number>;
+    target?: MotionEncodingAccessor<TDatum, string | number>;
+    work?: MotionEncodingAccessor<TDatum, number>;
+}
+export interface MotionAccessibleEncoding<TDatum> {
+    description?: MotionEncodingAccessor<TDatum, string>;
+    group?: MotionEncodingAccessor<TDatum, string>;
+    label?: MotionEncodingAccessor<TDatum, string>;
+}
+/** Runtime-neutral motion channels shared by streaming and physics adapters. */
+export interface MotionEncoding<TDatum extends Datum = Datum> {
+    id: MotionEncodingAccessor<TDatum, string | number>;
+    time?: MotionTimeEncoding<TDatum>;
+    placement?: MotionPlacementEncoding<TDatum>;
+    kinematics?: MotionKinematicsEncoding<TDatum>;
+    process?: MotionProcessEncoding<TDatum>;
+    evidence?: Record<string, MotionEncodingAccessor<TDatum, unknown>>;
+    accessible?: MotionAccessibleEncoding<TDatum>;
+}
+export interface ResolvedMotionEncodingRow<TDatum extends Datum = Datum> {
+    id: string;
+    datum: TDatum;
+    time: {
+        arrival?: number;
+        basis?: MotionTimeBasis;
+        unit?: MotionTimeUnit;
+    };
+    placement: {
+        x?: number;
+        y?: number;
+        lane?: string | number;
+        space?: MotionCoordinateSpace;
+    };
+    kinematics: {
+        velocityX?: number;
+        velocityY?: number;
+        space?: MotionCoordinateSpace;
+    };
+    process: {
+        group?: string | number;
+        stage?: string | number;
+        target?: string | number;
+        work?: number;
+    };
+    evidence: Record<string, unknown>;
+    accessible: {
+        description?: string;
+        group?: string;
+        label: string;
+    };
+}
+export interface MotionEncodingCompilation<TDatum extends Datum = Datum> {
+    rows: ResolvedMotionEncodingRow<TDatum>[];
+    byId: Map<string, ResolvedMotionEncodingRow<TDatum>>;
+}
+export interface CompileMotionEncodingOptions<TDatum extends Datum = Datum> {
+    data: readonly TDatum[];
+    encoding: MotionEncoding<TDatum>;
+}
+/** Resolve one encoding accessor without attaching it to a specific runtime. */
+export declare function resolveMotionAccessor<TDatum, TValue>(accessor: MotionEncodingAccessor<TDatum, TValue> | undefined, datum: TDatum, index: number): TValue | undefined;
+/** Resolve runtime-neutral motion channels once while preserving source data. */
+export declare function compileMotionEncoding<TDatum extends Datum = Datum>(options: CompileMotionEncodingOptions<TDatum>): MotionEncodingCompilation<TDatum>;
+export interface ResolveMotionAgeOptions {
+    now: number;
+    arrival: number;
+    /** Uses the same unit as now and arrival. */
+    ttl: number;
+    thresholds?: LifecycleBandThresholds;
+}
+export interface ResolvedMotionAge {
+    age: number;
+    /** Unbounded age / ttl ratio. Negative and invalid ages resolve to zero. */
+    progress: number;
+    lifecycle: LifecycleBand;
+}
+/**
+ * Derive age, its unbounded ttl progress, and its named lifecycle band from
+ * values on a common clock — the one-call helper for authoring custom
+ * age-based encodings (see the Motion Encodings guide, which drives an "age +
+ * lifecycle" table from it). For band-only or ramp-only needs, reach for
+ * `bandFromAge` / `opacityFromAge` directly.
+ */
+export declare function resolveMotionAge(options: ResolveMotionAgeOptions): ResolvedMotionAge;
+export type MotionAgeOpacityType = "linear" | "exponential" | "step";
+export interface MotionAgeOpacityOptions {
+    /** Age where zero is newest. */
+    age: number;
+    /** Oldest meaningful age in the same unit. */
+    extent: number;
+    type: MotionAgeOpacityType;
+    halfLife?: number;
+    threshold?: number;
+    minOpacity?: number;
+}
+/** Map an age to opacity without assuming wall, simulation, or index time. */
+export declare function opacityFromAge(options: MotionAgeOpacityOptions): number;
+export interface MotionPoint {
+    x: number;
+    y: number;
+}
+export interface ResolvedMotionVector {
+    velocityX: number;
+    velocityY: number;
+    speed: number;
+    /** atan2 angle in radians in the supplied coordinate space. */
+    direction: number;
+}
+/** Resolve cartesian velocity into speed and direction. */
+export declare function resolveMotionVector(velocityX: number, velocityY: number): ResolvedMotionVector;
+/** Derive velocity per elapsed unit between two positions. */
+export declare function deriveMotionVector(previous: MotionPoint, current: MotionPoint, elapsed: number): ResolvedMotionVector;

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

@@ -1,21 +1,3 @@
-/**
- * radialGeometry — pure math helpers for radial chart authoring.
- *
- * The original consumer is `GaugeChart`, which needs to:
- *   - Convert a sweep angle (degrees) into start-angle + radian
- *     forms that align with the convention pieScene.ts uses
- *     (0° = 12 o'clock, positive = clockwise, gap centered at the
- *     6 o'clock position).
- *   - Map a value in `[min, max]` to its angle along the arc.
- *   - Compute the arc's visible bounding box in unit-circle coords
- *     so a container can fit the arc and pick a maximum radius.
- *
- * Custom radial chart authors using `XYCustomChart` or building a
- * bespoke radial layout can reach for the same primitives without
- * reimplementing the trigonometry. Surface intentionally tight —
- * each function is a few lines of math with a documented input
- * convention.
- */
 /** Result of `sweepToAngles`. All angles are in the
  *  12-o'clock-zero, clockwise-positive convention used by pieScene
  *  and the underlying gauge implementation. */

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

@@ -0,0 +1,56 @@
+/**
+ * Responsive visualization rule grammar.
+ *
+ * This is deliberately chart-semantic, not CSS. A rule says "when this chart
+ * slot is narrow, transform the chart props this way" so agents, recipes,
+ * audits, and future HOC runtime wiring can reason about the mobile variant
+ * without executing a renderer.
+ */
+export type ResponsiveOrientation = "portrait" | "landscape";
+export interface ResponsiveRuleCondition {
+    minWidth?: number;
+    maxWidth?: number;
+    minHeight?: number;
+    maxHeight?: number;
+    minAspectRatio?: number;
+    maxAspectRatio?: number;
+    orientation?: ResponsiveOrientation;
+}
+export interface ResponsiveRuleContext {
+    width: number;
+    height?: number;
+}
+export interface ResponsiveRule<TProps extends Record<string, unknown> = Record<string, unknown>> {
+    id?: string;
+    description?: string;
+    /**
+     * Viewport/container condition. All supplied predicates must match.
+     */
+    when: ResponsiveRuleCondition;
+    /**
+     * Shallow prop transform to apply when the condition matches. Nested
+     * `margin`, `frameProps`, `mobileSemantics`, `style`, and `className` are
+     * merged by `resolveResponsiveRules`; other keys replace the base value.
+     */
+    transform: Partial<TProps> & Record<string, unknown>;
+    /**
+     * Higher priority applies later and wins on conflicts. Defaults to source
+     * order when omitted.
+     */
+    priority?: number;
+}
+export interface ResponsiveRuleMatch<TProps extends Record<string, unknown> = Record<string, unknown>> {
+    rule: ResponsiveRule<TProps>;
+    index: number;
+}
+export interface ResponsiveRuleResult<TProps extends Record<string, unknown> = Record<string, unknown>> {
+    props: TProps;
+    matches: ResponsiveRuleMatch<TProps>[];
+}
+export declare function responsiveRuleMatches(rule: ResponsiveRule, context: ResponsiveRuleContext): boolean;
+/**
+ * Resolve matching responsive rules into a transformed prop object. Pure and
+ * SSR-safe. Runtime HOCs can call this with measured container dimensions;
+ * agents and audits can call it with target phone widths.
+ */
+export declare function resolveResponsiveRules<TProps extends Record<string, unknown>>(props: TProps, context: ResponsiveRuleContext, rules?: ReadonlyArray<ResponsiveRule<TProps>> | undefined): ResponsiveRuleResult<TProps>;

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

@@ -0,0 +1,27 @@
+import type { Datum } from "./datumTypes";
+export interface SmartTooltipEntry {
+    key: string;
+    value: unknown;
+}
+export interface SmartTooltipResult {
+    /** The key the title came from, if any. */
+    titleKey?: string;
+    /** The display title (a name/label/title/id). */
+    title?: unknown;
+    /** Ordered rows to show beneath the title (type → value → rest). */
+    entries: SmartTooltipEntry[];
+}
+/**
+ * Choose a title + ordered, de-noised rows from an arbitrary datum. Pure.
+ *
+ * - Skips `_`/`__`-prefixed keys, `data`, positional/topology keys, and
+ *   non-primitive values (nested objects/arrays).
+ * - Title: the first `name`/`label`/`title` field, else `id`, else the first
+ *   string field. When a real name is used, `id` is dropped as redundant.
+ * - Rows: one type-family field, then one value-family field, then the rest in
+ *   insertion order (capped at `maxEntries`).
+ */
+export declare function smartTooltipEntries(raw: Datum | null | undefined, options?: {
+    maxEntries?: number;
+    skipPositional?: boolean;
+}): SmartTooltipResult;

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

@@ -48,6 +48,27 @@ export interface ForecastConfig {
     trainOpacity?: number;
     /** Stroke opacity for the forecast line segment (0–1). Default: 1 */
     forecastOpacity?: number;
+    /**
+     * Ramp each forecast point's opacity by its uncertainty — wider
+     * prediction interval (longer horizon) renders fainter, fusing
+     * confidence into the encoding instead of a single flat opacity.
+     * `true` ramps across `[0.15, 1]`; pass `{ min, max }` to bound the
+     * range. Honored by `createSegmentLineStyle`; overrides
+     * `forecastOpacity` per point. Mutually exclusive with
+     * `confidenceAccessor` (which wins if both are set).
+     */
+    uncertaintyOpacity?: boolean | {
+        min?: number;
+        max?: number;
+    };
+    /**
+     * Externally-supplied per-point confidence in `[0, 1]` (field name or
+     * function). When set, each forecast point's opacity is interpolated
+     * across the `uncertaintyOpacity` range (or `[0.15, 1]`) by its
+     * confidence — higher confidence, more opaque. Use when the consumer's
+     * model emits a confidence rather than a prediction interval.
+     */
+    confidenceAccessor?: string | ((d: Datum) => number);
     /**
      * Training line stroke color.
      * - `"darken"`: auto-darken the line's own color by 50% (hex colors only —
@@ -97,6 +118,20 @@ export interface ForecastConfig {
 /** Internal segment marker added to each datum */
 export declare const SEGMENT_FIELD: "__forecastSegment";
 export type SegmentType = "training" | "training-base" | "observed" | "forecast";
+/** Internal per-point opacity stamped by the uncertainty ramp. */
+export declare const FORECAST_OPACITY_FIELD: "__forecastOpacity";
+/**
+ * Stamp `__forecastOpacity` on forecast points so `createSegmentLineStyle`
+ * can fade each by its uncertainty. Two sources, confidence wins:
+ *
+ * - `confidenceAccessor` — opacity = lerp(min, max, confidence∈[0,1]).
+ * - `uncertaintyOpacity` — opacity ramped by prediction-interval width
+ *   (narrowest → max, widest → min), normalized across the given points.
+ *
+ * Mutates the supplied point objects in place; no-op when neither source
+ * is configured. Pure otherwise (only reads via the passed accessors).
+ */
+export declare function stampForecastOpacity(points: Datum[], config: ForecastConfig, getUpper: (d: Datum) => number | undefined, getLower: (d: Datum) => number | undefined): void;
 export declare function buildAnomalyAnnotations(config: AnomalyConfig): Datum[];
 export interface ForecastResult {
     processedData: Datum[];

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

@@ -2,7 +2,7 @@ import type { ReactNode } from "react";
 import type { Datum } from "./datumTypes";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { HoverData } from "../../realtime/types";
-import type { HoverHighlightMode, LinkedHoverProp, SelectionConfig } from "./types";
+import type { HoverHighlightMode, LinkedHoverProp, SelectionConfig, ResolvedMobileInteractionConfig } from "./types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { AnimateProp } from "../../stream/pipelineTransitionUtils";
 import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
@@ -65,20 +65,29 @@ export declare function buildBaseMetadataProps(input: BaseMetadataProps): BaseMe
  *   - `customClickBehavior` mirrors the click-driving subset
  *     (`onObservation`, `onClick`, `linkedHover` for cross-chart
  *     selection lock).
+ *   - `forceHoverBehavior` / `forceClickBehavior` let composed or
+ *     adapter charts (realtime, matrix cells, custom payload mappers)
+ *     keep their chart-specific callback shape while sharing the same
+ *     mobile predicates and touch-radius plumbing.
  *
  * Returning the props as a spreadable object means HOCs that don't
  * need either get an empty merge that adds nothing.
  */
 export declare function buildCustomBehaviorProps(input: {
     linkedHover?: LinkedHoverProp;
+    selection?: SelectionConfig;
     onObservation?: OnObservationCallback;
     onClick?: ((datum: Datum, position: {
         x: number;
         y: number;
     }) => void) | undefined;
+    hoverRadius?: number;
     hoverHighlight?: HoverHighlightMode;
+    forceHoverBehavior?: boolean;
+    forceClickBehavior?: boolean;
+    mobileInteraction?: ResolvedMobileInteractionConfig;
     customHoverBehavior: (d: Datum | null) => void;
-    customClickBehavior: (d: Datum | null) => void;
+    customClickBehavior?: (d: Datum | null) => void;
     /**
      * Whether `linkedHover` participates in the click predicate. Most
      * XY / ordinal HOCs say yes — `linkedHover` cross-chart selection
@@ -91,6 +100,7 @@ export declare function buildCustomBehaviorProps(input: {
 }): {
     customHoverBehavior?: (d: Datum | null) => void;
     customClickBehavior?: (d: Datum | null) => void;
+    hoverRadius?: number;
 };
 /**
  * Resolve the `tooltipContent` prop for the frame.

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

@@ -21,6 +21,8 @@ export interface TooltipFieldConfig {
 export declare function accessorName(acc: string | ((...args: any[]) => any)): string;
 export declare function formatVal(v: unknown): string;
 export declare function resolveValue(d: Datum, acc: string | ((d: Datum) => any)): unknown;
+export { smartTooltipEntries } from "./smartTooltip";
+export type { SmartTooltipEntry, SmartTooltipResult } from "./smartTooltip";
 /**
  * Build TooltipFieldConfig rows for a `band` prop config so the default
  * tooltip surfaces envelope values automatically. Reads from the

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

@@ -4,6 +4,8 @@ import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { AnimateProp } from "../../stream/pipelineTransitionUtils";
 import type { Datum } 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 */

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";
@@ -21,7 +22,7 @@ export interface ChartSetupInput {
     /** 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 */
@@ -58,12 +59,16 @@ export interface ChartSetupInput {
     }) => 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. */
     loadingContent?: ReactNode | false;
     /** Empty content override */
-    emptyContent?: ReactNode;
+    emptyContent?: ReactNode | false;
     /** Resolved width from useChartMode */
     width: number;
     /** Resolved height from useChartMode */
@@ -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,9 @@ interface ScaffoldOptions {
     enableHover?: boolean;
     showLegend?: boolean;
     title?: string;
+    mobileInteraction?: MobileInteractionProp;
+    mobileSemantics?: MobileVisualizationContract;
+    responsiveRules?: ResponsiveRule[];
     mode?: ChartMode;
     xLabel?: string;
     yLabel?: string;
@@ -39,7 +44,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,19 +58,23 @@ 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;
-    emptyContent?: ReactNode;
+    emptyContent?: ReactNode | false;
 }
 interface DataSetupResult<TFrameHandle> extends ScaffoldResult<TFrameHandle> {
     /** Sparse-filtered copy of the input data array. */

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/useOrdinalPieceStyle.d.ts

@@ -12,7 +12,7 @@ export interface OrdinalPieceStyleOptions {
     /** Theme categorical palette (from useThemeCategorical). */
     themeCategorical: string[] | undefined;
     /** colorScheme prop — array or string scheme name. */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /** Stable category-index map for default-fill cycling. */
     categoryIndexMap: Map<string, number>;
     /** User-supplied `frameProps.pieceStyle`. Accepts the looser

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

@@ -30,7 +30,7 @@ export declare function useStreamingLegend({ isPushMode, colorBy, colorScheme, s
     /** The color-by accessor (may be 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;
     /** Whether legend is requested */
     showLegend: boolean | undefined;
     /** Legend position */