semiotic 3.8.0 → 3.8.1

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

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. */
@@ -65,6 +66,13 @@ export interface AreaChartProps<TDatum extends Datum = Datum> extends BaseChartP
      * @default "category10"
      */
     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
@@ -56,6 +57,14 @@ export interface BubbleChartProps<TDatum extends Datum = Datum> extends BaseChar
      * @default "category10"
      */
     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