semiotic 3.8.0 → 3.8.2

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

@@ -1,5 +1,6 @@
 import type { ReactNode } from "react";
 import type { Datum } from "./datumTypes";
+import type { SemanticClickBehavior, SemanticHoverBehavior } from "./semanticInteractions";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { HoverData } from "../../realtime/types";
 import type { HoverHighlightMode, LinkedHoverProp, SelectionConfig, ResolvedMobileInteractionConfig } from "./types";
@@ -86,8 +87,8 @@ export declare function buildCustomBehaviorProps(input: {
     forceHoverBehavior?: boolean;
     forceClickBehavior?: boolean;
     mobileInteraction?: ResolvedMobileInteractionConfig;
-    customHoverBehavior: (d: Datum | null) => void;
-    customClickBehavior?: (d: Datum | null) => void;
+    customHoverBehavior: SemanticHoverBehavior;
+    customClickBehavior?: SemanticClickBehavior;
     /**
      * Whether `linkedHover` participates in the click predicate. Most
      * XY / ordinal HOCs say yes — `linkedHover` cross-chart selection
@@ -98,8 +99,9 @@ export declare function buildCustomBehaviorProps(input: {
      */
     linkedHoverInClickPredicate?: boolean;
 }): {
-    customHoverBehavior?: (d: Datum | null) => void;
-    customClickBehavior?: (d: Datum | null) => void;
+    customHoverBehavior?: SemanticHoverBehavior;
+    customClickBehavior?: SemanticClickBehavior;
+    annotationObservationCallback?: OnObservationCallback;
     hoverRadius?: number;
 };
 /**

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/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,7 +2,7 @@ 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";
@@ -164,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. */
@@ -198,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
  */
@@ -220,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

@@ -18,7 +18,7 @@ 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 */
@@ -53,7 +53,7 @@ export interface ChartSetupInput {
         right: number;
     };
     /** onClick callback */
-    onClick?: (datum: any, event: {
+    onClick?: (datum: Datum, event: {
         x: number;
         y: number;
     }) => void;

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

@@ -28,6 +28,9 @@ interface ScaffoldOptions {
     enableHover?: boolean;
     showLegend?: boolean;
     title?: string;
+    description?: string;
+    summary?: string;
+    accessibleTable?: boolean;
     mobileInteraction?: MobileInteractionProp;
     mobileSemantics?: MobileVisualizationContract;
     responsiveRules?: ResponsiveRule[];

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/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;

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>;
@@ -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

@@ -37,7 +37,7 @@ export declare function useStreamingLegend({ isPushMode, colorBy, colorScheme, s
     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/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,2 +1,11 @@
-import type { ComponentSpec } from "./validateProps";
-export declare const VALIDATION_MAP: Record<string, ComponentSpec>;
+/**
+ * Runtime validation map derived from the Chart Spec Registry.
+ *
+ * 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:
+ *
+ *   npm run docs:chart-specs:schema
+ */
+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>;