semiotic 3.7.5 → 3.8.1

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

@@ -1,6 +1,15 @@
 import type { Datum } from "./datumTypes";
 import type { Accessor, ChartAccessor } from "./types";
 import type { SelectionHookResult } from "./selectionUtils";
+import { type StyleRule } from "./styleRules";
+import type { HatchFill } from "./hatchFill";
+/**
+ * Values a resolved piece style may carry. Wider than the axis-style
+ * `string | number` because `fill` can be a declarative {@link HatchFill}
+ * descriptor or a raw `CanvasPattern`.
+ */
+type PieceStyleValue = string | number | HatchFill | CanvasPattern | undefined;
+type PieceStyleObject = Record<string, PieceStyleValue>;
 export interface OrdinalPieceStyleOptions {
     /** colorBy accessor — string field name or function */
     colorBy?: Accessor<string> | ChartAccessor<Datum, string>;
@@ -12,7 +21,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
@@ -65,6 +74,19 @@ export interface OrdinalPieceStyleOptions {
     effectiveSelectionHook: SelectionHookResult | null | undefined;
     /** Resolved selection config (typically `setup.resolvedSelection`). */
     resolvedSelection: import("./types").SelectionConfig | undefined;
+    /**
+     * Declarative, threshold-aware style rules. Evaluated per piece and merged
+     * on top of the resolved base fill (last-applicable rule wins per property).
+     * The user's `frameProps.pieceStyle` still overrides these, and top-level
+     * primitive props (`stroke`/`strokeWidth`/`opacity`) override everything.
+     */
+    styleRules?: ReadonlyArray<StyleRule>;
+    /**
+     * Resolve the numeric value a threshold rule compares against for a datum
+     * (typically the chart's `valueAccessor` output). Lets `{ when: { gt: 10 } }`
+     * work with no `field` on the threshold.
+     */
+    resolveRuleValue?: (d: Datum) => number | undefined;
 }
 /**
  * Build a memoized `pieceStyle` function that the chart can pass
@@ -84,4 +106,5 @@ export interface OrdinalPieceStyleOptions {
  * })
  * ```
  */
-export declare function useOrdinalPieceStyle(options: OrdinalPieceStyleOptions): (d: Datum, category?: string) => Record<string, string | number | undefined>;
+export declare function useOrdinalPieceStyle(options: OrdinalPieceStyleOptions): (d: Datum, category?: string) => PieceStyleObject;
+export {};

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

@@ -30,14 +30,14 @@ 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 */
     legendPosition?: LegendPosition;
 }): {
     wrapPush: (originalPush: (d: Datum) => void) => (datum: Datum) => void;
-    wrapPushMany: (originalPushMany: (d: any[]) => void) => (data: any[]) => void;
+    wrapPushMany: (originalPushMany: (data: Datum[]) => void) => (data: Datum[]) => void;
     resetCategories: () => void;
     categories: string[];
     categoryDomainProps: {

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

@@ -0,0 +1,49 @@
+import type { Datum } from "./datumTypes";
+/**
+ * The slice of a chart's imperative handle this hook drives. Every Semiotic
+ * push-API handle (realtime + non-realtime HOCs) satisfies it structurally;
+ * each method is optional so the hook degrades gracefully on handles that
+ * only support a subset (e.g. append-only).
+ */
+export interface SyncedPushHandle<T = Datum> {
+    push?: (datum: T) => unknown;
+    pushMany?: (data: T[]) => unknown;
+    update?: (id: string, updater: (datum: T) => T) => unknown;
+    remove?: (id: string | string[]) => unknown;
+    clear?: () => unknown;
+}
+/** An id accessor: a field name, or a function of the row (and its index). */
+export type PushIdAccessor<T> = keyof T | ((datum: T, index: number) => string | number | null | undefined);
+export interface SyncedPushDataOptions<T = Datum> {
+    /**
+     * Identifies a row so it can be updated/removed in place. A field name
+     * (`"id"`) or a function. Omit it and rows are keyed by index — fine for
+     * append-mostly streams, but reorders/removals then read positionally.
+     */
+    id?: PushIdAccessor<T>;
+    /**
+     * Clear the buffer and re-sync from scratch whenever this value changes.
+     * Use it for things that invalidate the whole series — a theme remount, a
+     * mode switch, a new data source. The handle identity changing (chart
+     * remount) always forces a reset too.
+     */
+    resetKey?: unknown;
+}
+/**
+ * Pure reconciliation: bring `handle`'s buffer from `previousById` to `rows`,
+ * issuing the minimal push/update/remove calls, and return the new id→row map.
+ *
+ * Exported for direct use and unit testing. The hook is a thin
+ * effect wrapper around this. Rows are matched by `getId`; a row whose
+ * reference changed is `update`d in place (or removed + re-pushed when the
+ * handle has no `update`).
+ */
+export declare function syncPushBuffer<T = Datum>(handle: SyncedPushHandle<T>, previousById: Map<string, T>, rows: ReadonlyArray<T>, getId: ((datum: T, index: number) => string) | null): Map<string, T>;
+/**
+ * Mirror a controlled React array into a push-API chart's buffer.
+ *
+ * @param ref      The same ref you pass to the chart's `ref` prop.
+ * @param data     The rows the chart should currently show.
+ * @param options  `id` accessor and optional `resetKey`.
+ */
+export declare function useSyncedPushData<T = Datum>(ref: React.RefObject<SyncedPushHandle<T> | null>, data: ReadonlyArray<T>, options?: SyncedPushDataOptions<T>): void;

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

@@ -1,6 +1,7 @@
 import type { Datum } from "./datumTypes";
 import type { Accessor, ChartAccessor } from "./types";
 import type { SelectionHookResult, SelectionStyleConfig } from "./selectionUtils";
+import { type StyleRule, type StyleRuleContext } from "./styleRules";
 export interface XYLineStyleOptions {
     /**
      * Base stroke width. The top-level `strokeWidth` override below
@@ -33,6 +34,15 @@ export interface XYLineStyleOptions {
     effectiveSelectionHook?: SelectionHookResult | null;
     /** Resolved selection style config (matched/unmatched style overrides). */
     resolvedSelection?: SelectionStyleConfig;
+    /**
+     * Declarative style rules, merged on top of the resolved base stroke/fill
+     * (last-applicable rule wins). NOTE: line styles resolve per-SERIES against
+     * a representative sample datum (the series' first point), so a rule's
+     * `ctx.x`/`ctx.y` reflect that sample point, not every vertex.
+     */
+    styleRules?: ReadonlyArray<StyleRule>;
+    /** Build the `StyleRuleContext` for a series' sample datum + group key. */
+    ruleContext?: (d: Datum, group?: string) => StyleRuleContext;
 }
 /**
  * Returns a memoized `lineStyle` callback that the XY frame's

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

@@ -1,6 +1,11 @@
 import type { Datum } from "./datumTypes";
 import type { Accessor, ChartAccessor } from "./types";
 import type { SelectionHookResult } from "./selectionUtils";
+import { type StyleRule, type StyleRuleContext } from "./styleRules";
+import type { HatchFill } from "./hatchFill";
+/** Values a resolved point style may carry (`fill` can be a HatchFill). */
+type PointStyleValue = string | number | HatchFill | CanvasPattern | undefined;
+type PointStyleObject = Record<string, PointStyleValue>;
 export interface XYPointStyleOptions {
     /** colorBy accessor — string field name or function. */
     colorBy?: Accessor<string> | ChartAccessor<Datum, string>;
@@ -46,6 +51,18 @@ export interface XYPointStyleOptions {
     effectiveSelectionHook: SelectionHookResult | null | undefined;
     /** Resolved selection config (typically `setup.resolvedSelection`). */
     resolvedSelection: import("./types").SelectionConfig | undefined;
+    /**
+     * Declarative style rules, evaluated per point and merged on top of the
+     * resolved base fill (last-applicable rule wins). Same engine and precedence
+     * as the ordinal bar `styleRules`.
+     */
+    styleRules?: ReadonlyArray<StyleRule>;
+    /**
+     * Build the `StyleRuleContext` for a point — populate `value`/`x`/`y` from
+     * the chart's accessors so thresholds can target either axis
+     * (`{ axis: "x", gt: 5 }`). Called only when `styleRules` is set.
+     */
+    ruleContext?: (d: Datum) => StyleRuleContext;
     /**
      * For ConnectedScatterplot-style charts whose color depends on the
      * point's position in an ordered sequence, the resolver may need
@@ -84,4 +101,5 @@ export interface XYPointStyleOptions {
  * })
  * ```
  */
-export declare function useXYPointStyle(options: XYPointStyleOptions): (d: Datum) => Record<string, string | number | undefined>;
+export declare function useXYPointStyle(options: XYPointStyleOptions): (d: Datum) => PointStyleObject;
+export {};

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

@@ -9,22 +9,24 @@ import type { Datum } from "./datumTypes";
  * Samples first, last, and a middle element to catch common mistakes
  * (wrong field names, missing data) without iterating the entire dataset.
  */
-type AccessorLike = string | ((...args: any[]) => any);
+type AccessorResult = string | number | boolean | Date | Datum | null | undefined;
+type AccessorLike = string | ((datum: Datum, index?: number) => AccessorResult);
+type ChartDataInput = ReadonlyArray<Datum> | Datum | string | number | boolean | null | undefined;
 interface ArrayDataValidation {
     componentName: string;
-    data: any;
+    data: ChartDataInput;
     accessors?: Record<string, AccessorLike | undefined>;
     requiredProps?: Datum;
 }
 interface ObjectDataValidation {
     componentName: string;
-    data: any | undefined | null;
+    data: ChartDataInput;
     dataLabel?: string;
 }
 interface NetworkDataValidation {
     componentName: string;
-    nodes?: any[] | undefined | null;
-    edges?: any[] | undefined | null;
+    nodes?: ReadonlyArray<Datum> | null;
+    edges?: ReadonlyArray<Datum> | null;
     nodesRequired?: boolean;
     edgesRequired?: boolean;
     accessors?: Record<string, AccessorLike | undefined>;

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

@@ -1,13 +1,11 @@
 /**
- * Per-component prop specifications for validation.
+ * Runtime validation map derived from the Chart Spec Registry.
  *
- * Pure data — one ComponentSpec entry per Semiotic HOC chart.
- * Shared prop fragments (commonProps, xyAxisProps, etc.) are composed
- * via spread to keep individual entries concise.
+ * The generated module contains only the fields consumed by `validateProps`.
+ * Keeping the docs/schema-rich registry out of this runtime import path saves
+ * it from every AI and utility bundle while preserving VALIDATION_MAP's public
+ * object shape. Regenerate after chart-spec edits with:
  *
- * Consumed by: validateProps.ts (validation engine), diagnoseConfig.ts,
- *              chartConfig.ts. Schema/validation parity is locked by the
- *              Chart Spec Registry (`check:chart-specs`).
+ *   npm run docs:chart-specs:schema
  */
-import type { ComponentSpec } from "./validateProps";
-export declare const VALIDATION_MAP: Record<string, ComponentSpec>;
+export { VALIDATION_MAP } from "./validationMap.generated";

package/dist/components/charts/shared/validationMap.generated.d.ts

@@ -0,0 +1,6 @@
+/**
+ * AUTO-GENERATED from chartSpecs.ts by scripts/regenerate-schema.ts.
+ * Do not edit by hand; run `npm run docs:chart-specs:schema`.
+ */
+import type { ComponentSpec } from "./validateProps";
+export declare const VALIDATION_MAP: Record<string, ComponentSpec>;

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

@@ -1,4 +1,5 @@
 import * as React from "react";
+import type { Datum, DatumValue } from "./datumTypes";
 interface SafeRenderProps {
     componentName: string;
     width: number;
@@ -25,7 +26,7 @@ export declare function SafeRender({ componentName, width, height, children }: S
  * Renders a "No data available" placeholder when data is empty.
  * Returns null when data is present or emptyContent is `false`.
  */
-export declare function renderEmptyState(data: any[] | undefined | null, width: number, height: number, emptyContent?: React.ReactNode | false): React.ReactElement | null;
+export declare function renderEmptyState(data: Datum[] | undefined | null, width: number, height: number, emptyContent?: React.ReactNode | false): React.ReactElement | null;
 /**
  * Renders a loading placeholder while `loading` is true.
  *
@@ -39,7 +40,7 @@ export declare function renderEmptyState(data: any[] | undefined | null, width:
  */
 export declare function renderLoadingState(loading: boolean | undefined, width: number, height: number, loadingContent?: React.ReactNode | false): React.ReactElement | null;
 /** Warn if a string accessor isn't found in the first data element */
-export declare function warnMissingField(componentName: string, data: any[] | undefined, accessorName: string, accessorValue: any): void;
+export declare function warnMissingField(componentName: string, data: Datum[] | undefined, accessorName: string, accessorValue: DatumValue): void;
 /** Warn if data looks like the wrong shape for this chart type */
-export declare function warnDataShape(componentName: string, data: any[] | undefined, expectedKeys: string[], hint: string): void;
+export declare function warnDataShape(componentName: string, data: Array<Datum | string | number | boolean | null | undefined> | undefined, expectedKeys: string[], hint: string): void;
 export {};

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

@@ -0,0 +1,22 @@
+import type { BigNumberFormat, BigNumberTarget } from "./types";
+export interface TargetPresentation {
+    label: string | undefined;
+    percent: string | null;
+    formattedValue: string;
+    text: string;
+}
+interface UseTargetPresentationOptions {
+    target: BigNumberTarget | undefined;
+    value: number | null | undefined;
+    format: BigNumberFormat | undefined;
+    locale: string | undefined;
+    currency: string | undefined;
+    precision: number | undefined;
+}
+/**
+ * Format a finite target once for both visible chrome and the accessible
+ * sentence. Invalid target values are omitted rather than announcing NaN or
+ * infinity.
+ */
+export declare function useTargetPresentation({ target, value, format, locale, currency, precision }: UseTargetPresentationOptions): TargetPresentation | null;
+export {};

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

@@ -70,7 +70,7 @@ export interface BigNumberThreshold {
     level: BigNumberLevel;
     /** Explicit colour override; otherwise `var(--semiotic-{level})`. */
     color?: string;
-    /** Optional label surfaced in tooltips, the ARIA sentence, and capability output. */
+    /** Optional label appended to the generated ARIA sentence. */
     label?: string;
 }
 /**
@@ -252,11 +252,10 @@ export interface BigNumberProps<_TDatum extends Datum = Datum> {
      *  full-width and stacks the chart at full card width under the delta
      *  row. */
     trendSlot?: BigNumberSlot;
-    /** **Square** chart embedded beside the value — e.g. a `DonutChart` /
-     *  `PieChart` / `Scatterplot` / `Treemap`. When set, the card splits
-     *  into a left column (header + value + delta) and a right column
-     *  (the square chart). Compose with `trendSlot` to get both
-     *  (square chart on the right, wide trend along the bottom). */
+    /** **Square** chart anchored as a top-right card decoration — e.g. a
+     *  `DonutChart` / `PieChart` / `Scatterplot` / `Treemap`. The header
+     *  reserves its corner; choose `chartSize` to leave room for large values
+     *  or compose with `trendSlot` for a wide chart along the bottom. */
     chartSlot?: BigNumberSlot;
     /** Reserved pixel size (square) for `chartSlot`. Defaults are
      *  mode-keyed for sparkline scale — 44 px for `tile`, 80 px for

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

@@ -5,6 +5,7 @@ import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
+import { type StyleRule } from "../shared/styleRules";
 import type { ForecastConfig, AnomalyConfig } from "../shared/statisticalOverlays";
 export interface SemanticGradientStop {
     /** Percent from baseline to line/top. 0 = baseline, 100 = line/top. */
@@ -64,7 +65,14 @@ export interface AreaChartProps<TDatum extends Datum = Datum> extends BaseChartP
      * Color scheme for categorical data or custom colors array
      * @default "category10"
      */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
+    /**
+     * Declarative, threshold-aware area styling. Ordered `{ when, style }`
+     * rules; last applicable rule wins. Per-SERIES (resolves against the series'
+     * sample datum). A rule `fill` may be a color or a HatchFill — hatch an
+     * "uncertain"/"projected" series. Layers over the resolved series color.
+     */
+    styleRules?: StyleRule[];
     /**
      * Curve interpolation type
      * @default "monotoneX"

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

@@ -5,6 +5,7 @@ import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
+import { type StyleRule } from "../shared/styleRules";
 import { type RegressionProp } from "../shared/regressionUtils";
 /**
  * BubbleChart component props
@@ -55,7 +56,15 @@ export interface BubbleChartProps<TDatum extends Datum = Datum> extends BaseChar
      * Color scheme for categorical data or custom colors array
      * @default "category10"
      */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
+    /**
+     * Declarative, threshold-aware bubble styling. Ordered `{ when, style }`
+     * rules; last applicable rule wins per property. `when` accepts a predicate
+     * (`ctx` = `{ value, x, y, size, category }`), a declarative threshold
+     * (`{ axis: "x"|"y", gt, … }`), or `true`. A rule's `fill` may be a color or
+     * a HatchFill. Layers over the resolved base color.
+     */
+    styleRules?: StyleRule[];
     /**
      * Bubble opacity
      * @default 0.6

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

@@ -5,6 +5,7 @@ import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { LegendInteractionMode } from "../shared/hooks";
+import { type StyleRule } from "../shared/styleRules";
 import { type RegressionProp } from "../shared/regressionUtils";
 import type { ForecastConfig, AnomalyConfig } from "../shared/statisticalOverlays";
 /**
@@ -25,6 +26,12 @@ export interface ConnectedScatterplotProps<TDatum extends Datum = Datum> extends
     orderAccessor?: string | ((d: TDatum) => number | Date);
     /** Label for the ordering metric in tooltips @default "Order" or the accessor field name */
     orderLabel?: string;
+    /**
+     * Declarative, threshold-aware point styling (see Scatterplot). Ordered
+     * `{ when, style }` rules; last applicable rule wins. Layers over the
+     * order-derived base fill.
+     */
+    styleRules?: StyleRule[];
     /** Point radius @default 4 */
     pointRadius?: number;
     /** Enable hover annotations @default true */

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

@@ -5,6 +5,7 @@ import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
+export { computeDifferenceSegments } from "./differenceSegments";
 /**
  * DifferenceChart props
  */
@@ -75,57 +76,6 @@ export interface DifferenceChartProps<TDatum extends Datum = Datum> extends Base
     /** Pass-through StreamXYFrame props. */
     frameProps?: Partial<Omit<StreamXYFrameProps, "chartType" | "data" | "size">>;
 }
-/**
- * Crossover-segmented record used by the area pipeline. One row per
- * vertex along either the upper or lower boundary; `__diffSegment` is a
- * group key per segment so the area scene builder produces one polygon
- * per id with the correct fill color.
- */
-interface SegmentRow {
-    __x: number;
-    /** Upper boundary y value (max of A, B). The area pipeline reads this. */
-    __y: number;
-    /** Lower boundary y value (min of A, B) — picked up as per-datum y0. */
-    __y0: number;
-    /** Segment id. Format: `"seg-<index>-<winner>"`. */
-    __diffSegment: string;
-    /** Which series is on top in this segment ("A" or "B"). Drives fill. */
-    __diffWinner: "A" | "B";
-    /** Original A value at this x (or interpolated at crossovers). */
-    __valA: number;
-    /** Original B value at this x (or interpolated at crossovers). */
-    __valB: number;
-    /** Original datum (for tooltip lookup at non-crossover vertices). */
-    __sourceDatum?: Datum;
-}
-/**
- * Walk sorted data, splitting at each A↔B crossover. Inserts an
- * interpolated vertex on BOTH sides of every crossover so adjacent
- * segments meet at a zero-width point (no jagged edges).
- *
- * Non-finite rows are skipped; the algorithm tracks the most recent
- * VALID non-tie row (not the index neighbor) for crossover detection,
- * so a non-finite gap doesn't drop a crossover that straddles it.
- *
- * Tie rows (a === b) are handled distinctly from non-tie rows:
- *
- *   - When a tie row sits BETWEEN two non-tie rows with the SAME
- *     winner, the tie is emitted in that winner's segment as a
- *     zero-width vertex.
- *   - When a tie row sits between non-tie rows with DIFFERENT winners,
- *     the FIRST tie of the run becomes the crossover vertex. The old
- *     segment closes at the tie's x, the new segment opens at the same
- *     point, and any subsequent tie rows (multi-tie runs) carry into
- *     the new segment as zero-width vertices.
- *
- * This preserves the data's actual zero-difference point: if the user
- * supplied a tie row explicitly, the fill switches color exactly at
- * that x rather than at a linear-interpolated x that ignored the tie.
- *
- * Exported for direct unit-testing — the area pipeline depends on the
- * exact crossover-vertex shape produced here.
- */
-export declare function computeDifferenceSegments<TDatum extends Datum>(raw: TDatum[], getX: (d: TDatum) => number, getA: (d: TDatum) => number, getB: (d: TDatum) => number): SegmentRow[];
 /**
  * DifferenceChart — fills the area between two series with a color
  * that switches based on which series is higher at each x. Crossover
@@ -169,4 +119,3 @@ export declare const DifferenceChart: {
     <TDatum extends Datum = Datum>(props: DifferenceChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
     displayName?: string;
 };
-export {};

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

@@ -43,7 +43,7 @@ export interface HeatmapProps<TDatum extends Datum = Datum> extends BaseChartPro
     /**
      * Format function for x-axis tick labels
      */
-    xFormat?: (d: any, index?: number, allTicks?: number[]) => string;
+    xFormat?: (d: string | number | Date, index?: number, allTicks?: number[]) => string;
     /**
      * Format function for y-axis tick labels
      */
@@ -64,7 +64,7 @@ export interface HeatmapProps<TDatum extends Datum = Datum> extends BaseChartPro
      * customColorScale={scaleSequential(interpolatePlasma).domain([0, 100])}
      * ```
      */
-    customColorScale?: any;
+    customColorScale?: (value: number) => string;
     /**
      * Show values in cells
      * @default false

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

@@ -5,6 +5,7 @@ import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
+import { type StyleRule } from "../shared/styleRules";
 import type { AnomalyConfig, ForecastConfig } from "../shared/statisticalOverlays";
 /**
  * LineChart component props
@@ -73,7 +74,17 @@ export interface LineChartProps<TDatum extends Datum = Datum> extends BaseChartP
      * Color scheme for categorical data or custom colors array
      * @default "category10"
      */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
+    /**
+     * Declarative, threshold-aware line styling. Ordered `{ when, style }`
+     * rules; last applicable rule wins per property. NOTE: line styles resolve
+     * per-SERIES against the series' first data point, so a rule's `ctx.x`/`ctx.y`
+     * reflect that sample, not every vertex (use it to recolor a whole series by
+     * a representative value). `when` accepts a predicate, a threshold
+     * (`{ axis: "x"|"y", … }`), or `true`. A rule `stroke`/`fill` may be a color
+     * or a HatchFill. Layers over the resolved series color.
+     */
+    styleRules?: StyleRule[];
     /**
      * Curve interpolation type
      * @default "linear"

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

@@ -37,7 +37,7 @@ export interface MinimapChartProps<TDatum extends Datum = Datum> extends Omit<Ba
     /** Color-by field or function */
     colorBy?: ChartAccessor<TDatum, string>;
     /** Color scheme (default: "category10") */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /** Curve type (default: "linear") */
     curve?: "linear" | "monotoneX" | "monotoneY" | "step" | "stepAfter" | "stepBefore" | "basis" | "cardinal" | "catmullRom";
     /** Line stroke width (default: 2) */

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

@@ -28,12 +28,12 @@ export interface MultiAxisLineChartProps<TDatum extends Datum = Datum> extends B
     /** Array of data points shared by both series */
     data?: TDatum[];
     /** Field name or function to access x values @default "x" */
-    xAccessor?: ChartAccessor<TDatum, number>;
+    xAccessor?: ChartAccessor<TDatum, number | Date | string>;
     /** Series configuration — exactly 2 for dual-axis mode.
      *  If not exactly 2, renders as a normal line chart with a console warning. */
     series: MultiAxisSeriesConfig<TDatum>[];
     /** Color scheme or custom colors array @default "category10" */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /** Enable hover annotations @default true */
     enableHover?: boolean;
     /** Curve interpolation @default "monotoneX" */

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

@@ -5,6 +5,7 @@ import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
+import { type StyleRule } from "../shared/styleRules";
 /**
  * Quadrant label and color configuration
  */
@@ -69,7 +70,13 @@ export interface QuadrantChartProps<TDatum extends Datum = Datum> extends BaseCh
     /** Field name or function to determine point color */
     colorBy?: ChartAccessor<TDatum, string>;
     /** Color scheme for categorical data @default "category10" */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
+    /**
+     * Declarative, threshold-aware point styling (see Scatterplot). Ordered
+     * `{ when, style }` rules; last applicable rule wins. Layers over the
+     * quadrant-derived base fill; `frameProps.pointStyle` still overrides.
+     */
+    styleRules?: StyleRule[];
     /** Field name or function to determine point size */
     sizeBy?: ChartAccessor<TDatum, number>;
     /** Min and max radius for points @default [3, 15] */

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

@@ -6,6 +6,7 @@ import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
+import { type StyleRule } from "../shared/styleRules";
 import { type RegressionProp } from "../shared/regressionUtils";
 import type { ForecastConfig, AnomalyConfig } from "../shared/statisticalOverlays";
 /**
@@ -25,7 +26,16 @@ export interface ScatterplotProps<TDatum extends Datum = Datum> extends BaseChar
     /** Field name or function to determine point color */
     colorBy?: ChartAccessor<TDatum, string>;
     /** Color scheme for categorical data or custom colors array @default "category10" */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
+    /**
+     * Declarative, threshold-aware point styling. Ordered `{ when, style }`
+     * rules; the last applicable rule wins per property. `when` accepts a
+     * predicate `(datum, ctx) => boolean` (`ctx` = `{ value, x, y, category }`),
+     * a declarative threshold (`{ axis: "x"|"y", gt, lte, within, in, … }` —
+     * target either axis regardless of accessor field name), or `true`. A rule's
+     * `fill` may be a color or a HatchFill. Layers over the resolved base color.
+     */
+    styleRules?: StyleRule[];
     /** Field name or function to determine point size */
     sizeBy?: ChartAccessor<TDatum, number>;
     /** Min and max radius for points @default [3, 15] */

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

@@ -12,7 +12,7 @@ export interface ScatterplotMatrixProps<TDatum extends Datum = Datum> extends Ba
     /** Field or function to determine point color */
     colorBy?: ChartAccessor<TDatum, string>;
     /** Color scheme @default "category10" */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /** Size of each cell in pixels @default 150 */
     cellSize?: number;
     /** Gap between cells in pixels @default 4 */
@@ -39,6 +39,16 @@ export interface ScatterplotMatrixProps<TDatum extends Datum = Datum> extends Ba
     showLegend?: boolean;
     /** Field or function to identify each data point in tooltips. Defaults to "Row {index}" */
     idAccessor?: string | ((d: TDatum) => string);
+    /**
+     * Called when a point in any cell is clicked. Receives the clicked row datum
+     * and its grid-relative pixel position `{ x, y }` — the same coordinate space
+     * as `onObservation`. Fires in hover mode (the default); in brush mode the
+     * drag-select overlay captures pointer events, so clicks are not delivered.
+     */
+    onClick?: (datum: TDatum, event: {
+        x: number;
+        y: number;
+    }) => void;
 }
 /**
  * ScatterplotMatrix (SPLOM) — multi-dimensional scatter visualization