semiotic 3.8.0 → 3.8.1

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

@@ -0,0 +1,35 @@
+import * as React from "react";
+import type { Datum } from "./datumTypes";
+import type { OnObservationCallback, ObservationInputType } from "../../store/ObservationStore";
+export type ChartAnnotation = Datum;
+export interface AnnotationActivationEvent {
+    annotation: ChartAnnotation;
+    annotationId?: string;
+    chartId?: string;
+    inputType: ObservationInputType;
+}
+export type OnAnnotationActivateCallback = (event: AnnotationActivationEvent) => void;
+export interface AnnotationActivationOptions {
+    onAnnotationActivate?: OnAnnotationActivateCallback;
+    onObservation?: OnObservationCallback;
+    chartId?: string;
+    chartType?: string;
+}
+/** Route annotation activation to both a direct callback and the observation store. */
+export declare function useAnnotationActivationOptions(options: AnnotationActivationOptions): AnnotationActivationOptions;
+/**
+ * Resolve a durable annotation identity without ever falling back to array
+ * position. Provenance stable IDs are accepted for agent-authored notes.
+ */
+export declare function annotationStableId(annotation: ChartAnnotation): string | undefined;
+/**
+ * Event props for a widget's existing HTML boundary. Capture phase observes
+ * arbitrary descendant controls without replacing their behavior or adding a
+ * nested interactive element.
+ */
+export declare function annotationActivationProps(annotation: ChartAnnotation, options?: AnnotationActivationOptions): React.HTMLAttributes<HTMLDivElement> & {
+    "data-semiotic-annotation-id"?: string;
+    "data-semiotic-annotation-widget": "";
+};
+/** True when a bubbled frame click originated inside a widget annotation. */
+export declare function isAnnotationActivationTarget(target: EventTarget | null): boolean;

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

@@ -0,0 +1,5 @@
+export declare const TOP_LABEL_BASELINE = 16;
+/** Keep a horizontal-threshold label inside the plot when its rule is near the top. */
+export declare function thresholdLabelY(y: number, height: number): number;
+/** Place a horizontal-band label just inside its visible top edge. */
+export declare function bandLabelY(y0: number, y1: number): number;

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

@@ -1,6 +1,7 @@
 import * as React from "react";
 import type { AnnotationContext } from "../../realtime/types";
 import type { Datum } from "./datumTypes";
+import { type AnnotationActivationOptions } from "./annotationActivation";
 export { applyAnnotationEmphasis, type AnnotationRenderPair } from "./annotationHierarchy";
 type AnnotationRule = (annotation: Datum, index: number, context: AnnotationContext) => React.ReactNode | null;
 /**
@@ -17,4 +18,4 @@ type AnnotationRule = (annotation: Datum, index: number, context: AnnotationCont
  * through to the default rule, preserving the existing override contract.
  */
 export declare function renderAnnotationPass(annotations: ReadonlyArray<Datum>, defaultRule: AnnotationRule, userRule: AnnotationRule | undefined, context: AnnotationContext): React.ReactNode[];
-export declare function createDefaultAnnotationRules(_frameType: "xy" | "ordinal" | "network"): (annotation: Datum, index: number, context: AnnotationContext) => React.ReactNode | null;
+export declare function createDefaultAnnotationRules(_frameType: "xy" | "ordinal" | "network", activation?: AnnotationActivationOptions): (annotation: Datum, index: number, context: AnnotationContext) => React.ReactNode | null;

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

@@ -0,0 +1,4 @@
+import type { Datum } from "./datumTypes";
+export declare function resolveHoverXPosition(interactionDatum: Datum, datum: Datum | null | undefined, xField: string): number | null;
+export declare function observationDatum(interactionDatum: Datum): Datum;
+export declare function hasOwnEnumerableKey(value: object | undefined | null): boolean;

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

@@ -6,9 +6,9 @@
  *   - `src/components/charts/shared/validationMap.ts`     (runtime prop validation)
  *   - `ai/componentMetadata.cjs`                          (category buckets)
  *
- * Today, `validationMap.ts` is derived directly from this registry, and
- * `ai/schema.json` is generated from it — run `npm run docs:chart-specs:schema`
- * to refresh the schema after editing a spec. `componentMetadata.cjs` is still
+ * Today, `validationMap.generated.ts` and `ai/schema.json` are generated from
+ * this registry — run `npm run docs:chart-specs:schema` to refresh both after
+ * editing a spec. `componentMetadata.cjs` is still
  * hand-edited but gated for parity by the registry: `check:chart-specs` (run
  * via `npm run check:chart-specs`) regenerates each chart's schema/
  * validation/metadata entries with the pure functions in

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

@@ -18,3 +18,5 @@
  * reason" referenced by the lint policy for `@typescript-eslint/no-explicit-any`.
  */
 export type Datum = Record<string, any>;
+/** Values that can be returned by a chart accessor or stored in a datum field. */
+export type DatumValue = string | number | boolean | Date | Datum | Datum[] | null | undefined;

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

@@ -1,4 +1,6 @@
 import type { Datum } from "./datumTypes";
 import type { Diagnosis } from "./diagnoseTypes";
+/** Interactive widgets need durable identity for replay and normalized events. */
+export declare function checkInteractiveAnnotationIds(_component: string, props: Datum, out: Diagnosis[]): void;
 export declare function checkAnnotationConnectors(_component: string, props: Datum, out: Diagnosis[]): void;
 export declare function checkAnnotationDensity(_component: string, props: Datum, out: Diagnosis[]): void;

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

@@ -58,7 +58,7 @@ export declare function formatAxis(type?: "number" | "date" | "percent" | "curre
  * )
  * ```
  */
-export declare function createTooltip(fields: string[], formatters?: Record<string, (v: any) => string>, labels?: Record<string, string>): (d: Datum) => React.JSX.Element;
+export declare function createTooltip(fields: string[], formatters?: Record<string, (value: string | number | Date) => string>, labels?: Record<string, string>): (d: Datum) => React.JSX.Element;
 /**
  * Formats large numbers with K/M/B suffixes
  *
@@ -85,7 +85,7 @@ export declare function formatLargeNumber(value: number, decimals?: number): str
  *
  * Used as the default axis tickFormat when no explicit format is provided.
  */
-export declare function smartTickFormat(value: any): string;
+export declare function smartTickFormat(value: string | number | Date | null | undefined): string;
 type TimeGranularity = "seconds" | "minutes" | "hours" | "days" | "months" | "years";
 /**
  * Creates a hierarchical time axis formatter.
@@ -112,7 +112,7 @@ type TimeGranularity = "seconds" | "minutes" | "hours" | "days" | "months" | "ye
  * <LineChart data={ts} xFormat={adaptiveTimeTicks("minutes")} />
  * ```
  */
-export declare function adaptiveTimeTicks(granularity?: TimeGranularity): (value: any, index?: number, allTicks?: number[]) => string;
+export declare function adaptiveTimeTicks(granularity?: TimeGranularity): (value: string | number | Date, index?: number, allTicks?: number[]) => string;
 /**
  * Truncates text to specified length with ellipsis
  *

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

@@ -0,0 +1,87 @@
+/**
+ * Declarative hatch-fill descriptor — a single value that renders as a
+ * diagonal-line pattern on BOTH rendering backends.
+ *
+ * The library historically had two disjoint hatch primitives: a canvas
+ * `createHatchPattern` (→ `CanvasPattern`) and an SVG `<pattern>` builder
+ * (`hatchFill` recipe / `createSVGHatchPattern`). A caller had to know
+ * which medium they were painting into and hand-produce the right thing —
+ * which is why a `CanvasPattern` returned from a `pieceStyle` silently
+ * collapses to a solid color in SSR (`svgFill` drops non-string fills).
+ *
+ * `HatchFill` closes that gap: it is a plain, serializable descriptor that
+ * can be set directly as `style.fill`. The canvas renderer resolves it to a
+ * `CanvasPattern` (`resolveHatchCanvasPattern`); the SVG serializer resolves
+ * it to a `<pattern>` def + `url(#id)` (`hatchPatternDef` / `hatchFillId`).
+ * One declaration, both mediums — so a bar hatched via a style rule looks
+ * identical whether it is drawn to canvas in the browser or serialized to
+ * SVG on the server.
+ *
+ * @example
+ * ```tsx
+ * <BarChart
+ *   styleRules={[
+ *     { when: { gt: 10 }, style: { fill: { type: "hatch", background: "#ffd166", stroke: "#e0a92a" } } },
+ *   ]}
+ * />
+ * ```
+ */
+import * as React from "react";
+/**
+ * A declarative diagonal-hatch fill. Assign it anywhere a `style.fill`
+ * is accepted (`pieceStyle`, `styleRules`, annotation region `fill`).
+ * Backend-agnostic: resolved to a `CanvasPattern` for canvas and an SVG
+ * `<pattern>` for SSR / the SVG overlay.
+ */
+export interface HatchFill {
+    /** Discriminator — marks this fill as a hatch descriptor. */
+    type: "hatch";
+    /** Tile background color painted under the lines. @default "transparent" */
+    background?: string;
+    /** Color of the diagonal lines. @default "#000" */
+    stroke?: string;
+    /** Width of the diagonal lines in px. @default 1.5 */
+    lineWidth?: number;
+    /** Spacing between lines in px. @default 6 */
+    spacing?: number;
+    /** Angle of the lines in degrees (0 = horizontal, 45 = diagonal). @default 45 */
+    angle?: number;
+    /** Opacity applied to the hatch lines (SVG `<line>` stroke opacity). @default 1 */
+    lineOpacity?: number;
+}
+/** Type guard — is a resolved `style.fill` a `HatchFill` descriptor? */
+export declare function isHatchFill(fill: unknown): fill is HatchFill;
+/**
+ * Stable, content-derived key for a hatch descriptor. Used to cache canvas
+ * patterns and to mint deterministic SVG `<pattern>` ids so identical
+ * descriptors dedupe rather than proliferate.
+ */
+export declare function hatchFillKey(h: HatchFill): string;
+/** Deterministic, SVG-id-safe identifier for a hatch descriptor. */
+export declare function hatchFillId(prefix: string, h: HatchFill): string;
+/**
+ * Resolve a `HatchFill` descriptor to a `CanvasPattern` for the given
+ * context. Cached by descriptor content + DPR. Returns `null` only when
+ * the environment can't create a pattern (SSR/test) — callers fall back
+ * to the descriptor's `background` color.
+ */
+export declare function resolveHatchCanvasPattern(h: HatchFill, ctx: CanvasRenderingContext2D): CanvasPattern | null;
+/**
+ * Render a `HatchFill` descriptor as an SVG `<pattern>` element.
+ * Place the returned element inside `<defs>` (or anywhere valid) and set
+ * `fill="url(#id)"` on the target shape. Mirrors the canvas tile exactly:
+ * parallel lines rotated by `angle` so the two backends read identically.
+ */
+export declare function hatchPatternDef(h: HatchFill, id: string): React.ReactElement;
+/**
+ * Resolve a `style.fill` for an SVG shape. Returns the paint string to use
+ * plus, when the fill is a `HatchFill`, the `<pattern>` def to inject.
+ *
+ * @param fill    the raw `style.fill` (string color, `HatchFill`, or `CanvasPattern`)
+ * @param idBase  prefix for the generated pattern id (should be node-unique-ish)
+ * @param fallback solid color used when `fill` is null/undefined or a raw CanvasPattern
+ */
+export declare function resolveSvgFill(fill: string | HatchFill | CanvasPattern | null | undefined, idBase: string, fallback?: string): {
+    fill: string;
+    def?: React.ReactElement;
+};

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

@@ -7,6 +7,7 @@ import type { TransitionConfig } from "../../stream/types";
 import type { Datum } from "./datumTypes";
 import type { MobileVisualizationContract } from "./auditMobileVisualization";
 import type { ResponsiveRule } from "./responsiveRules";
+import type { SemanticClickBehavior, SemanticHoverBehavior } from "./semanticInteractions";
 /**
  * Default fill color used when no colorBy is specified
  */
@@ -46,13 +47,13 @@ export declare function resolveDefaultFill(color: string | undefined, themeCateg
  * Resolve an accessor (string key or function) into a function.
  * Used across chart components to normalize `valueAccessor`, `categoryAccessor`, etc.
  */
-export declare function resolveAccessor<T = any>(accessor: string | ((d: Datum, i?: number) => T)): (d: Datum) => T;
+export declare function resolveAccessor<T = string | number | boolean | Date | Datum | null | undefined>(accessor: string | ((d: Datum, i?: number) => T)): (d: Datum) => T;
 /**
  * Hook to create a color scale from data and colorBy configuration.
  * Returns undefined when colorBy is absent or data is empty (push API mode).
  * Supports both string and function accessors for colorBy.
  */
-export declare function useColorScale(data: Array<Datum>, colorBy: string | ((d: any, i?: number) => any) | undefined, colorScheme?: string | string[] | Record<string, string>): ((v: string) => string) | undefined;
+export declare function useColorScale(data: Array<Datum>, colorBy: string | ((d: Datum, i?: number) => string | number) | undefined, colorScheme?: string | string[] | Record<string, string>): ((v: string) => string) | undefined;
 /**
  * Hook to sort data by a value accessor.
  * Used by BarChart and DotPlot.
@@ -83,7 +84,7 @@ export declare function useChartSelection({ selection, linkedHover, fallbackFiel
     onObservation?: OnObservationCallback;
     chartType?: string;
     chartId?: string;
-    onClick?: (datum: any, event: {
+    onClick?: (datum: Datum, event: {
         x: number;
         y: number;
     }) => void;
@@ -93,8 +94,8 @@ export declare function useChartSelection({ selection, linkedHover, fallbackFiel
 }): {
     activeSelectionHook: SelectionHookResult | null;
     hoverSelectionHook: SelectionHookResult | null;
-    customHoverBehavior: (d: Datum | null) => void;
-    customClickBehavior: (d: Datum | null) => void;
+    customHoverBehavior: SemanticHoverBehavior;
+    customClickBehavior: SemanticClickBehavior;
     /** Stable ID for this chart instance, used to suppress linked crosshair on source chart */
     crosshairSourceId: string;
 };
@@ -172,7 +173,7 @@ interface ChartModeInput {
     categoryLabel?: string;
     valueLabel?: string;
     /** When truthy, enableHover is forced true regardless of mode (LinkedCharts needs hover) */
-    linkedHover?: any;
+    linkedHover?: LinkedHoverProp;
     /** Optional mobile interaction policy surfaced through useChartMode for custom wrappers. */
     mobileInteraction?: MobileInteractionProp;
     /** Optional mobile semantic contract surfaced through useChartMode for custom wrappers. */

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

@@ -0,0 +1,9 @@
+/**
+ * AUTO-GENERATED from chartSpecs.ts by scripts/regenerate-schema.ts.
+ * Do not edit by hand; run `npm run docs:chart-specs:schema`.
+ *
+ * This compact registry is intentionally separate from validation metadata:
+ * config serialization only needs chart-name membership.
+ */
+export declare const KNOWN_CHART_COMPONENTS: readonly ["BarChart", "StackedBarChart", "GroupedBarChart", "SwarmPlot", "BoxPlot", "Histogram", "ViolinPlot", "RidgelinePlot", "DotPlot", "PieChart", "DonutChart", "GaugeChart", "FunnelChart", "SwimlaneChart", "LikertChart", "LineChart", "AreaChart", "DifferenceChart", "StackedAreaChart", "Scatterplot", "BubbleChart", "Heatmap", "QuadrantChart", "MultiAxisLineChart", "CandlestickChart", "ConnectedScatterplot", "ScatterplotMatrix", "MinimapChart", "ForceDirectedGraph", "SankeyDiagram", "ProcessSankey", "ChordDiagram", "TreeDiagram", "Treemap", "CirclePack", "OrbitDiagram", "ChoroplethMap", "ProportionalSymbolMap", "FlowMap", "DistanceCartogram", "RealtimeLineChart", "RealtimeHistogram", "TemporalHistogram", "RealtimeSwarmChart", "RealtimeWaterfallChart", "RealtimeHeatmap", "GaltonBoardChart", "EventDropChart", "PhysicsPileChart", "CollisionSwarmChart", "GauntletChart", "ProcessFlowChart", "PhysicalFlowChart", "BigNumber"];
+export declare function isKnownChartComponent(componentName: string): boolean;

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

@@ -0,0 +1,16 @@
+export type RegressionPoint = [number, number];
+export interface LeastSquaresResult {
+    points: RegressionPoint[];
+    /**
+     * Linear: `[slope, intercept]`. Polynomial: highest power first, matching
+     * the historical `regression` package result consumed by annotations.
+     */
+    equation: number[];
+}
+/** Fit a two-parameter least-squares line with two-decimal output rounding. */
+export declare function linearRegression(data: ReadonlyArray<readonly [number, number | null]>): LeastSquaresResult;
+/**
+ * Fit an order-N polynomial using normal equations. Coefficients and predicted
+ * points use the former dependency's two-decimal rounding and equation order.
+ */
+export declare function polynomialRegression(data: ReadonlyArray<readonly [number, number | null]>, order?: number): LeastSquaresResult;

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

@@ -27,7 +27,8 @@ export interface PrimitiveStyleOverrides {
     strokeWidth?: number;
     opacity?: number;
 }
-type StyleFnArg = (...args: any[]) => Datum;
+type StyleArgument = Datum | string | number | boolean | Date | null | undefined;
+type StyleFn<TArgs extends StyleArgument[]> = (...args: TArgs) => Datum;
 /** Returns true when at least one override key has a non-undefined value. */
 export declare function hasPrimitiveOverrides(overrides: PrimitiveStyleOverrides): boolean;
 /**
@@ -39,5 +40,5 @@ export declare function hasPrimitiveOverrides(overrides: PrimitiveStyleOverrides
  * keeps the memoization-stable identity path hot for the common case
  * where a designer has set nothing.
  */
-export declare function mergeShapeStyle<F extends StyleFnArg>(styleFn: F | undefined, overrides: PrimitiveStyleOverrides): F;
+export declare function mergeShapeStyle<TArgs extends StyleArgument[] = []>(styleFn: StyleFn<TArgs> | undefined, overrides: PrimitiveStyleOverrides): StyleFn<TArgs>;
 export {};

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

@@ -0,0 +1,42 @@
+import type { Datum } from "./datumTypes";
+import type { KeyboardEvent as ReactKeyboardEvent } from "react";
+import type { OnObservationCallback, ObservationInputType } from "../../store/ObservationStore";
+/** Extra context supplied by Stream Frames to their existing behavior hooks. */
+export interface SemanticInteractionContext {
+    type: "focus" | "activate";
+    inputType: ObservationInputType;
+}
+export type SemanticHoverBehavior<T = Datum> = (datum: T | null, context?: SemanticInteractionContext) => void;
+export type SemanticClickBehavior<T = Datum> = (datum: T | null, context?: SemanticInteractionContext) => void;
+export declare function observationInputType(pointerType?: string): "pointer" | "touch";
+/**
+ * Stream Frame keyboard navigation lives on a focusable chart wrapper. Let
+ * native controls rendered inside that wrapper (notably widget annotations)
+ * handle their own keys before the chart consumes Enter, Space, or arrows.
+ */
+export declare function isInteractiveKeyboardTarget(event: Pick<ReactKeyboardEvent, "target" | "currentTarget">): boolean;
+/**
+ * Emit the legacy hover event and its semantic focus companion when present.
+ * Keeping both makes the semantic vocabulary additive for existing consumers.
+ */
+export declare function emitHoverObservations(options: {
+    onObservation?: OnObservationCallback;
+    datum: Datum | null;
+    x?: number;
+    y?: number;
+    chartType: string;
+    chartId?: string;
+    context?: SemanticInteractionContext;
+    timestamp?: number;
+}): void;
+/** Emit the legacy click event and its semantic activation companion. */
+export declare function emitClickObservations(options: {
+    onObservation?: OnObservationCallback;
+    datum: Datum | null;
+    x?: number;
+    y?: number;
+    chartType: string;
+    chartId?: string;
+    context?: SemanticInteractionContext;
+    timestamp?: number;
+}): void;

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

@@ -24,4 +24,4 @@
  * mutation throws in strict mode rather than corrupting later reads.
  */
 export declare const EMPTY_ARRAY: readonly unknown[];
-export declare function filterSparseArray<T>(input: readonly T[] | undefined | null): T[];
+export declare function filterSparseArray<T extends object>(input: readonly (T | null | undefined)[] | undefined | null): T[];

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 {};