semiotic 3.3.1 → 3.4.1

package/dist/components/stream/useFrame.d.ts

@@ -0,0 +1,122 @@
+import * as React from "react";
+import type { ReactNode } from "react";
+import type { SemioticTheme } from "../store/ThemeStore";
+import { useResponsiveSize } from "./useResponsiveSize";
+import { resolveAnimateConfig } from "./pipelineTransitionUtils";
+import type { AnimateProp } from "./pipelineTransitionUtils";
+import type { TransitionConfig } from "./types";
+import type { HoverPointerCoords } from "./hoverUtils";
+/**
+ * Frame-supplied margin defaults. Each Stream Frame has its own — XY's
+ * differs from Ordinal's, Network has both a default and a CENTERED variant
+ * for radial chart types. The hook accepts the resolved default and
+ * shallow-merges user margin on top.
+ */
+export interface FrameMargin {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/**
+ * Foreground/background graphics can be a ReactNode (rendered as-is) or a
+ * function that receives the current `{ size, margin }` and returns one.
+ * The function form lets users place chrome relative to the chart area.
+ */
+export type FrameGraphicsProp = ReactNode | ((ctx: {
+    size: number[];
+    margin: FrameMargin;
+}) => ReactNode);
+export interface UseFrameInput {
+    /** Resolved size `[width, height]`. Each frame defaults its `size` prop
+     *  before calling, so this is never undefined. */
+    sizeProp: [number, number];
+    /** Frame's `responsiveWidth` prop. */
+    responsiveWidth: boolean | undefined;
+    /** Frame's `responsiveHeight` prop. */
+    responsiveHeight: boolean | undefined;
+    /** Frame's user-supplied margin (always partial — each side optional).
+     *  Matches the `margin?:` prop type on every Stream Frame. */
+    userMargin: Partial<FrameMargin> | undefined;
+    /** Frame's family-default margin. Shallow-merged with `userMargin`. */
+    marginDefault: FrameMargin;
+    /** Frame's `foregroundGraphics` prop. */
+    foregroundGraphics?: FrameGraphicsProp;
+    /** Frame's `backgroundGraphics` prop. */
+    backgroundGraphics?: FrameGraphicsProp;
+    /** Frame's `animate` prop. */
+    animate?: AnimateProp;
+    /** Frame's `transition` prop (legacy / explicit form). */
+    transitionProp?: TransitionConfig;
+    /**
+     * Frame's `dirtyRef` (the flag that forces a full canvas redraw on the
+     * next paint). When provided, useFrame installs a theme-change effect
+     * that bumps it to `true`, clears the CSS-var cache, and queues a
+     * render — the pattern that all four frames duplicated.
+     *
+     * Optional because this is a Tier B add-on; before the migration the
+     * frames installed this themselves. The hook keeps the input optional
+     * so a frame can opt in independently, but in practice all four pass
+     * it.
+     *
+     * `dirtyRef` is owned by the frame (not the hook) because its initial
+     * value differs — only `StreamXYFrame` inits to `false`; Ordinal,
+     * Network, and Geo all init to `true` (load-bearing for first-paint
+     * timing on those three).
+     */
+    themeDirtyRef?: React.MutableRefObject<boolean>;
+}
+export interface UseFrameResult {
+    /** Reduced-motion preference at last render (for re-render gating). */
+    reducedMotion: boolean;
+    /** Reduced-motion ref-mirror so render closures see the latest value
+     *  without depending on it. */
+    reducedMotionRef: React.MutableRefObject<boolean>;
+    /** Ref to attach to the responsive container. */
+    responsiveRef: ReturnType<typeof useResponsiveSize>[0];
+    /** Resolved size `[width, height]` accounting for `responsiveWidth/Height`. */
+    size: [number, number];
+    /** Effective margin (`marginDefault` ⊕ `userMargin`). */
+    margin: FrameMargin;
+    /** `size[0] - margin.left - margin.right`. */
+    adjustedWidth: number;
+    /** `size[1] - margin.top - margin.bottom`. */
+    adjustedHeight: number;
+    /** Resolved foreground (function-or-node, evaluated). */
+    resolvedForeground: ReactNode;
+    /** Resolved background (function-or-node, evaluated). */
+    resolvedBackground: ReactNode;
+    /** Current theme from the ThemeStore — re-renders on theme change. */
+    currentTheme: SemioticTheme;
+    /** Resolved transition config from `animate`/`transition` props. */
+    transition: ReturnType<typeof resolveAnimateConfig>["transition"];
+    /** Whether the intro animation should run on first render. */
+    introEnabled: boolean;
+    /** Stable id for the AccessibleDataTable region (hash-suffixed). */
+    tableId: string;
+    /** Token of the pending rAF, or 0 if none. */
+    rafRef: React.MutableRefObject<number>;
+    /** Frame assigns its render closure here. */
+    renderFnRef: React.MutableRefObject<() => void>;
+    /** Queue a render on the next animation frame. Coalesces. */
+    scheduleRender: () => void;
+    /** Frame assigns its hover handler closure here. */
+    hoverHandlerRef: React.MutableRefObject<(coords: HoverPointerCoords) => void>;
+    /** Frame assigns its pointer-leave closure here. */
+    hoverLeaveRef: React.MutableRefObject<() => void>;
+    /** Stable callback to attach to canvas's onPointerMove (or onMouseMove).
+     *  Captures the coords and queues a single rAF to drain into hoverHandlerRef. */
+    onPointerMove: (e: {
+        clientX: number;
+        clientY: number;
+    }) => void;
+    /** Stable callback to attach to canvas's onPointerLeave (or onMouseLeave).
+     *  Cancels any pending hover rAF and invokes hoverLeaveRef. */
+    onPointerLeave: () => void;
+}
+/**
+ * Bundles the universally-shared setup boilerplate that opens every
+ * Stream Frame. See `FRAME_COMPOSITION_LOG.md` for which concerns are
+ * inside this hook vs. left frame-specific.
+ */
+export declare function useFrame(input: UseFrameInput): UseFrameResult;

package/dist/components/stream/xySceneBuilders/areaScene.d.ts

@@ -1,3 +1,4 @@
+import type { Datum } from "../../charts/shared/datumTypes";
 /**
  * Area and stacked area scene builders.
  *
@@ -9,5 +10,5 @@
  */
 import type { SceneNode } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildAreaScene(ctx: XYSceneContext, data: Record<string, any>[]): SceneNode[];
-export declare function buildStackedAreaScene(ctx: XYSceneContext, data: Record<string, any>[]): SceneNode[];
+export declare function buildAreaScene(ctx: XYSceneContext, data: Datum[]): SceneNode[];
+export declare function buildStackedAreaScene(ctx: XYSceneContext, data: Datum[]): SceneNode[];

package/dist/components/stream/xySceneBuilders/barScene.d.ts

@@ -1,3 +1,4 @@
+import type { Datum } from "../../charts/shared/datumTypes";
 /**
  * Realtime histogram bar scene builder.
  *
@@ -15,4 +16,4 @@ export interface BarSceneResult {
     /** Sorted bin boundary values (edges of all bins) for data-driven brush snapping */
     binBoundaries: number[];
 }
-export declare function buildBarScene(ctx: XYSceneContext, data: Record<string, any>[]): BarSceneResult;
+export declare function buildBarScene(ctx: XYSceneContext, data: Datum[]): BarSceneResult;

package/dist/components/stream/xySceneBuilders/boundsScene.d.ts

@@ -1,3 +1,4 @@
+import type { Datum } from "../../charts/shared/datumTypes";
 /**
  * Bounds scene builder — produces an AreaSceneNode for confidence bands/envelopes.
  *
@@ -5,4 +6,4 @@
  */
 import type { AreaSceneNode } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildBoundsForGroup(ctx: XYSceneContext, data: Record<string, any>[], group: string): AreaSceneNode | null;
+export declare function buildBoundsForGroup(ctx: XYSceneContext, data: Datum[], group: string): AreaSceneNode | null;

package/dist/components/stream/xySceneBuilders/candlestickScene.d.ts

@@ -1,3 +1,4 @@
+import type { Datum } from "../../charts/shared/datumTypes";
 /**
  * Candlestick (OHLC) scene builder.
  *
@@ -7,4 +8,4 @@
  */
 import type { SceneNode, StreamLayout } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildCandlestickScene(ctx: XYSceneContext, data: Record<string, any>[], layout: StreamLayout): SceneNode[];
+export declare function buildCandlestickScene(ctx: XYSceneContext, data: Datum[], _layout: StreamLayout): SceneNode[];

package/dist/components/stream/xySceneBuilders/emitPointNodes.d.ts

@@ -1,3 +1,4 @@
+import type { Datum } from "../../charts/shared/datumTypes";
 /**
  * Shared helper for emitting PointSceneNodes from grouped data.
  *
@@ -9,5 +10,5 @@ import type { SceneNode } from "../types";
 import type { XYSceneContext } from "./types";
 export declare function emitPointNodes(ctx: XYSceneContext, groups: {
     key: string;
-    data: Record<string, any>[];
-}[], nodes: SceneNode[], yGetOverride?: (d: Record<string, any>) => number): void;
+    data: Datum[];
+}[], nodes: SceneNode[], yGetOverride?: (d: Datum) => number): void;

package/dist/components/stream/xySceneBuilders/heatmapScene.d.ts

@@ -1,3 +1,4 @@
+import type { Datum } from "../../charts/shared/datumTypes";
 import type { SceneNode, StreamLayout } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildHeatmapScene(ctx: XYSceneContext, data: Record<string, any>[], layout: StreamLayout): SceneNode[];
+export declare function buildHeatmapScene(ctx: XYSceneContext, data: Datum[], layout: StreamLayout): SceneNode[];

package/dist/components/stream/xySceneBuilders/lineScene.d.ts

@@ -1,3 +1,4 @@
+import type { Datum } from "../../charts/shared/datumTypes";
 /**
  * Line scene builder — produces LineSceneNode[] from grouped data.
  *
@@ -9,4 +10,4 @@
  */
 import type { SceneNode } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildLineScene(ctx: XYSceneContext, data: Record<string, any>[]): SceneNode[];
+export declare function buildLineScene(ctx: XYSceneContext, data: Datum[]): SceneNode[];

package/dist/components/stream/xySceneBuilders/mixedScene.d.ts

@@ -1,3 +1,4 @@
+import type { Datum } from "../../charts/shared/datumTypes";
 /**
  * Mixed scene builder — renders some series as areas and others as lines.
  *
@@ -9,4 +10,4 @@
  */
 import type { SceneNode } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildMixedScene(ctx: XYSceneContext, data: Record<string, any>[]): SceneNode[];
+export declare function buildMixedScene(ctx: XYSceneContext, data: Datum[]): SceneNode[];

package/dist/components/stream/xySceneBuilders/pointScene.d.ts

@@ -1,3 +1,4 @@
+import type { Datum } from "../../charts/shared/datumTypes";
 /**
  * Point/scatter/bubble scene builder.
  *
@@ -9,4 +10,4 @@
  */
 import type { SceneNode } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildPointScene(ctx: XYSceneContext, data: Record<string, any>[]): SceneNode[];
+export declare function buildPointScene(ctx: XYSceneContext, data: Datum[]): SceneNode[];

package/dist/components/stream/xySceneBuilders/swarmScene.d.ts

@@ -1,3 +1,4 @@
+import type { Datum } from "../../charts/shared/datumTypes";
 /**
  * Realtime swarm chart scene builder.
  *
@@ -7,4 +8,4 @@
  */
 import type { SceneNode } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildSwarmScene(ctx: XYSceneContext, data: Record<string, any>[]): SceneNode[];
+export declare function buildSwarmScene(ctx: XYSceneContext, data: Datum[]): SceneNode[];

package/dist/components/stream/xySceneBuilders/types.d.ts

@@ -1,3 +1,4 @@
+import type { Datum } from "../../charts/shared/datumTypes";
 /**
  * XYSceneContext — shared context passed to all XY scene builder functions.
  *
@@ -5,33 +6,33 @@
  * Scene builders are pure functions that receive this context instead of
  * accessing PipelineStore instance fields directly.
  */
-import type { StreamScales, Style, CurveType } from "../types";
+import type { StreamScales, Style, CurveType, BarStyle, ThemeSemanticColors } from "../types";
 export interface XYSceneContext {
     scales: StreamScales;
     config: XYSceneConfig;
-    getX: (d: any) => number;
-    getY: (d: any) => number;
-    getY0?: (d: any) => number | null;
-    getSize?: (d: any) => number;
-    getColor?: (d: any) => string;
-    getGroup?: (d: any) => string;
-    getCategory?: (d: any) => string;
-    getPointId?: (d: any) => string;
-    getBounds?: (d: any) => number | null;
-    getOpen?: (d: any) => number;
-    getHigh?: (d: any) => number;
-    getLow?: (d: any) => number;
-    getClose?: (d: any) => number;
+    getX: (d: Datum) => number;
+    getY: (d: Datum) => number;
+    getY0?: (d: Datum) => number | null;
+    getSize?: (d: Datum) => number;
+    getColor?: (d: Datum) => string;
+    getGroup?: (d: Datum) => string;
+    getCategory?: (d: Datum) => string;
+    getPointId?: (d: Datum) => string;
+    getBounds?: (d: Datum) => number | null;
+    getOpen?: (d: Datum) => number;
+    getHigh?: (d: Datum) => number;
+    getLow?: (d: Datum) => number;
+    getClose?: (d: Datum) => number;
     /** Style resolvers — delegate to PipelineStore's cached color management */
-    resolveLineStyle: (group: string, sampleDatum?: Record<string, any>) => Style;
-    resolveAreaStyle: (group: string, sampleDatum?: Record<string, any>) => Style;
-    resolveBoundsStyle: (group: string, sampleDatum?: Record<string, any>) => Style;
-    resolveColorMap: (data: Record<string, any>[]) => Map<string, string>;
+    resolveLineStyle: (group: string, sampleDatum?: Datum) => Style;
+    resolveAreaStyle: (group: string, sampleDatum?: Datum) => Style;
+    resolveBoundsStyle: (group: string, sampleDatum?: Datum) => Style;
+    resolveColorMap: (data: Datum[]) => Map<string, string>;
     resolveGroupColor: (group: string) => string | null;
     /** Group data by lineBy/colorBy accessor */
-    groupData: (data: Record<string, any>[]) => {
+    groupData: (data: Datum[]) => {
         key: string;
-        data: Record<string, any>[];
+        data: Datum[];
     }[];
     /** Instance-scoped mutable cache for bar category ordering (prevents cross-instance leaks) */
     barCategoryCache?: {
@@ -61,14 +62,14 @@ export interface XYSceneConfig {
             color: string;
         }>;
     };
-    annotations?: Record<string, any>[];
-    pointStyle?: (d: any) => Style & {
+    annotations?: Datum[];
+    pointStyle?: (d: Datum) => Style & {
         r?: number;
     };
     sizeRange?: [number, number];
-    xAccessor?: string | ((d: any) => any);
-    yAccessor?: string | ((d: any) => any);
-    valueAccessor?: string | ((d: any) => any);
+    xAccessor?: string | ((d: Datum) => any);
+    yAccessor?: string | ((d: Datum) => any);
+    valueAccessor?: string | ((d: Datum) => any);
     heatmapAggregation?: "count" | "sum" | "mean";
     heatmapXBins?: number;
     heatmapYBins?: number;
@@ -76,6 +77,13 @@ export interface XYSceneConfig {
     heatmapValueFormat?: (v: number) => string;
     binSize?: number;
     barColors?: Record<string, string>;
+    /** Bar fill/stroke/strokeWidth/gap. Threaded through from RealtimeHistogram. */
+    barStyle?: BarStyle;
+    themeSemantic?: ThemeSemanticColors;
+    /** Theme sequential scheme name — fallback when colorScheme is not set (heatmap). */
+    themeSequential?: string;
+    /** Theme diverging scheme name — fallback when colorScheme is not set. */
+    themeDiverging?: string;
     swarmStyle?: {
         radius?: number;
         fill?: string;
@@ -89,6 +97,7 @@ export interface XYSceneConfig {
         gap?: number;
         stroke?: string;
         strokeWidth?: number;
+        opacity?: number;
         connectorStroke?: string;
         connectorWidth?: number;
     };
@@ -104,5 +113,5 @@ export interface XYSceneConfig {
     candlestickRangeMode?: boolean;
     boundsStyle?: Style | ((d: any, group: string) => Style);
     lineStyle?: Style | ((d: any, group: string) => Style);
-    areaStyle?: (d: any) => Style;
+    areaStyle?: (d: Datum) => Style;
 }

package/dist/components/stream/xySceneBuilders/waterfallScene.d.ts

@@ -7,6 +7,7 @@
  * Dependencies: SceneGraph (buildRectNode)
  * Consumed by: PipelineStore.buildSceneNodes (chartType "waterfall")
  */
+import type { Datum } from "../../charts/shared/datumTypes";
 import type { SceneNode, StreamLayout } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildWaterfallScene(ctx: XYSceneContext, data: Record<string, any>[], layout: StreamLayout): SceneNode[];
+export declare function buildWaterfallScene(ctx: XYSceneContext, data: Datum[], layout: StreamLayout): SceneNode[];

package/dist/components/types/marginType.d.ts

@@ -0,0 +1,15 @@
+/** Resolved chart margin in pixels — every side populated. This is the
+ *  internal shape after the frame merges the user-supplied margin with
+ *  chart-mode defaults, so downstream layout math can read all four fields
+ *  without null-checking. */
+export interface MarginType {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+}
+/** Public-API margin shape. Users can pass any subset of sides (`{ left: 120 }`
+ *  for wide y-axis labels is a common pattern) or a single number as shorthand
+ *  for "same on all sides". The frame fills missing sides from the chart-mode
+ *  defaults before handing a fully-resolved `MarginType` to the layout code. */
+export type PartialMargin = number | Partial<MarginType>;