semiotic 3.3.1 → 3.4.0

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

@@ -1,5 +1,6 @@
 import type { ReactNode } from "react";
 import type { ScaleLinear } from "d3-scale";
+import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { ArrowOfTime, WindowMode, LineStyle, BarStyle, WaterfallStyle, SwarmStyle, HoverAnnotationConfig, HoverData, AnnotationContext, AnnotationAnchorMode } from "../realtime/types";
 export interface DecayConfig {
     type: "linear" | "exponential" | "step";
@@ -107,6 +108,8 @@ export interface LineSceneNode {
     _prevPath?: [number, number][];
     /** Target path coordinates for interpolation during transitions */
     _targetPath?: [number, number][];
+    /** Intro clip fraction (0→1): reveals line from left to right via canvas clip */
+    _introClipFraction?: number;
 }
 export interface AreaSceneNode {
     type: "area";
@@ -156,6 +159,8 @@ export interface AreaSceneNode {
     _prevBottomPath?: [number, number][];
     /** Target bottom path coordinates for interpolation during transitions */
     _targetBottomPath?: [number, number][];
+    /** Intro clip fraction (0→1): reveals area from left to right via canvas clip */
+    _introClipFraction?: number;
 }
 export interface PointSceneNode {
     type: "point";
@@ -278,6 +283,15 @@ export interface Changeset<T = Record<string, any>> {
     bounded: boolean;
     /** Hint: total dataset size when progressively chunking bounded data */
     totalSize?: number;
+    /** When true on a bounded changeset, the store replaces the buffer
+     *  contents but does NOT clear its category insertion-order memory
+     *  and marks itself as having received streaming-sourced data. Used
+     *  by aggregator HOCs (LikertChart, future density/bin charts) that
+     *  re-derive their full dataset from streaming input on every push —
+     *  the user perceives it as a stream even though the transport is
+     *  a wholesale replacement. Without this, re-aggregation would wipe
+     *  the category order and categories would shuffle on every tick. */
+    preserveCategoryOrder?: boolean;
 }
 /**
  * Note: when xScaleType="time", the x scale is a d3.scaleTime at runtime
@@ -467,6 +481,10 @@ export interface StreamXYFrameProps<T = Record<string, any>> {
     pulse?: PulseConfig;
     /** Smooth position transitions on data change */
     transition?: TransitionConfig;
+    /** Declarative animation: `true` for defaults (300ms ease-out), or config object.
+     *  When enabled, charts animate on first render (intro) and on data change.
+     *  Set `{ intro: false }` to disable the intro animation. */
+    animate?: AnimateProp;
     /** Frame-level data liveness indicator */
     staleness?: StalenessConfig;
     /** Marginal distribution plots in axis margins (histogram, violin, ridgeline, boxplot) */

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;