semiotic 3.4.2 → 3.5.1

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

@@ -74,7 +74,7 @@ export interface MarginalGraphicsConfig {
     left?: MarginalConfig | MarginalType;
     right?: MarginalConfig | MarginalType;
 }
-export type StreamChartType = "line" | "area" | "stackedarea" | "mixed" | "scatter" | "bubble" | "heatmap" | "bar" | "swarm" | "waterfall" | "candlestick";
+export type StreamChartType = "line" | "area" | "stackedarea" | "mixed" | "scatter" | "bubble" | "heatmap" | "bar" | "swarm" | "waterfall" | "candlestick" | "custom";
 export type RuntimeMode = "bounded" | "streaming";
 export interface Style {
     stroke?: string;
@@ -137,6 +137,14 @@ export interface AreaSceneNode {
     style: Style;
     datum: SeriesDatum;
     group?: string;
+    /** Clip the area to this rect (in plot-relative pixels). Used by horizon
+     *  charts to band a single series into N slices. */
+    clipRect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
     /** Gradient fill: opacity-based (topOpacity/bottomOpacity) or multi-color (colorStops) */
     fillGradient?: {
         topOpacity: number;
@@ -364,6 +372,27 @@ export interface StreamXYFrameProps<T = Datum> {
     lineDataAccessor?: string;
     curve?: CurveType;
     normalize?: boolean;
+    /**
+     * Stacked area baseline. Only consulted by stackedarea chartType.
+     * - "zero" (default): standard stack from y=0
+     * - "wiggle": Byron–Wattenberg streamgraph offset (minimizes wiggle)
+     * - "silhouette": center the stack symmetrically around y=0
+     *
+     * Mutually exclusive with `normalize`: when `normalize` is `true`, the
+     * stack is forced to a `"zero"` baseline (any other value is ignored)
+     * because normalization assumes a fixed `[0, 1]` y-domain.
+     */
+    baseline?: "zero" | "wiggle" | "silhouette";
+    /**
+     * Stack order — controls which series sits at the top, middle, or bottom.
+     * - "key" (default): alphabetical by group key
+     * - "insideOut": largest-total series in the middle, smaller alternating
+     *   above/below. Combined with `baseline: "wiggle"` or `"silhouette"`,
+     *   produces the canonical streamgraph look where a "central anchor"
+     *   layer sits across y=0 and other layers stack outward.
+     * - "asc" / "desc": by total ascending / descending
+     */
+    stackOrder?: "key" | "insideOut" | "asc" | "desc";
     /**
      * Accessor returning a symmetric uncertainty offset per datum.
      * When set, an uncertainty band is drawn ± this offset from the line.
@@ -506,6 +535,10 @@ export interface StreamXYFrameProps<T = Datum> {
     legendHighlightedCategory?: string | null;
     legendIsolatedCategories?: Set<string>;
     legendPosition?: "right" | "left" | "top" | "bottom";
+    /** Accessor used to report the current legend category domain in push mode. */
+    legendCategoryAccessor?: string | ((d: T) => string);
+    /** Fires when the current legend category domain changes after scene rebuilds. */
+    onCategoriesChange?: (categories: string[]) => void;
     /** SVG elements rendered behind the canvas (in pixel space) */
     backgroundGraphics?: ReactNode;
     /** SVG elements rendered on top of everything (in SVG overlay) */
@@ -550,6 +583,16 @@ export interface StreamXYFrameProps<T = Datum> {
     linkedCrosshairName?: string;
     /** Source chart ID — crosshair is suppressed on the source chart to avoid double rendering */
     linkedCrosshairSourceId?: string;
+    /** Replaces chart-type scene dispatch with a user-supplied layout function.
+     *  Receives a LayoutContext (scales, dimensions, theme, resolveColor) and
+     *  returns SceneNode[] + optional overlays. See `semiotic/recipes` for
+     *  reference layouts (waffle, calendar, horizon). */
+    customLayout?: import("./customLayout").CustomLayout;
+    /** User-supplied config blob threaded through to LayoutContext.config.
+     *  Typed as `object` so caller-defined interfaces (without an index
+     *  signature) flow through without casts; layouts narrow via their
+     *  own `CustomLayout<TConfig>` parameterization. */
+    layoutConfig?: object;
 }
 export interface StreamXYFrameHandle<T = Datum> {
     push(datum: T): void;

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

@@ -0,0 +1,89 @@
+import type { MutableRefObject, RefObject } from "react";
+/**
+ * Returns `false` on the server (no effect fires there) and during the
+ * first client render after hydration; `true` from the first
+ * post-commit re-render onward.
+ */
+export declare function useHydration(): boolean;
+/**
+ * Returns `true` when this component instance was mounted via SSR
+ * hydration (i.e. there was server-rendered HTML to hydrate from), and
+ * `false` when it was mounted via pure client-side rendering (no SSR).
+ *
+ * The trick: `useSyncExternalStore`'s `getServerSnapshot` callback is
+ * called *only* during hydration of server-rendered content — never
+ * during a fresh CSR mount. Returning different values from the two
+ * snapshots lets us read the hydration mode on the very first render,
+ * then we capture it into a ref so it survives later renders.
+ *
+ * Stream Frames use this to decide whether to skip the intro animation
+ * on the canvas's first paint: when SSR has already shown the chart in
+ * its final state, re-animating from blank when the canvas takes over
+ * looks like a regression. CSR mounts keep their intro animation
+ * because the SVG branch's output never actually paints (it's
+ * overwritten by the canvas branch within the same paint frame, before
+ * the browser commits a frame).
+ */
+export declare function useWasHydratingFromSSR(): boolean;
+/**
+ * Shared post-hydration lifecycle for every Stream Frame.
+ *
+ * Three things happen on every commit-after-hydration:
+ *
+ * 1. If we just rehydrated from SSR, cancel the intro animation that
+ *    the SVG-branch's `computeScene` installed (the server already
+ *    painted the chart in its final state — re-animating from blank
+ *    on the canvas takeover is a visual regression).
+ * 2. Mark the scene dirty so the canvas-paint pipeline rebuilds.
+ * 3. **Paint the canvas synchronously** via `renderFnRef.current()`.
+ *
+ * Step 3 is the timing-critical bit. The hook fires inside an
+ * isomorphic layout effect — `useLayoutEffect` on the client (runs
+ * synchronously after commit but before the browser paints),
+ * `useEffect` on the server (no-op, since SSR doesn't paint). If we
+ * deferred the paint to a `requestAnimationFrame` (the standard
+ * `scheduleRender()` route), the rAF callback wouldn't fire until
+ * the *next* frame — meaning the browser would paint *frame N* with
+ * the canvas in DOM but blank, then *frame N+1* with the canvas
+ * actually drawn. Synchronous paint inside the layout effect makes
+ * frame N's paint already include the canvas content; no flash.
+ *
+ * Each frame supplies its own `cleanup` for unmount work that's
+ * frame-specific (XY/Ordinal clear the streaming adapter; Geo clears
+ * its tile cache; Network has no extra cleanup).
+ */
+export interface HydrationLifecycleOptions {
+    hydrated: boolean;
+    wasHydratingFromSSR: boolean;
+    /**
+     * Ref to the frame's pipeline store. The store optionally implements
+     * `cancelIntroAnimation()`; the hook calls it when the SVG → canvas
+     * swap fires after SSR rehydration. (Currently every shipped store
+     * implements the method, but the optional shape lets a custom store
+     * opt out.)
+     */
+    storeRef: RefObject<{
+        cancelIntroAnimation?: () => void;
+    } | null>;
+    /**
+     * Mutable dirty flag the renderer reads on its next paint. The hook
+     * sets it to true on every commit so the post-hydration paint
+     * rebuilds the scene from scratch.
+     */
+    dirtyRef: MutableRefObject<boolean>;
+    /**
+     * Ref to the frame's render closure (assigned by `useFrame` /
+     * the frame body). The hook calls this synchronously to paint
+     * within the same frame as the SVG → canvas swap commit, avoiding
+     * the one-frame blank-canvas flicker that an rAF-deferred paint
+     * would produce.
+     */
+    renderFnRef: MutableRefObject<() => void>;
+    /**
+     * Optional unmount cleanup. Frame-specific work the hook can't
+     * generalize — e.g. clearing the streaming `DataSourceAdapter`
+     * (XY/Ordinal) or the geo tile cache.
+     */
+    cleanup?: () => void;
+}
+export declare function useHydrationLifecycle(opts: HydrationLifecycleOptions): void;

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

@@ -0,0 +1 @@
+export declare function useStableShallow<T>(value: T): T;

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

@@ -46,6 +46,10 @@ export interface XYSceneConfig {
     curve?: CurveType;
     colorScheme?: string | string[];
     normalize?: boolean;
+    /** Stacked area baseline. "zero" (default), "wiggle" (streamgraph), "silhouette" (centered). */
+    baseline?: "zero" | "wiggle" | "silhouette";
+    /** Stack order — see PipelineConfig.stackOrder. */
+    stackOrder?: "key" | "insideOut" | "asc" | "desc";
     gradientFill?: boolean | {
         topOpacity?: number;
         bottomOpacity?: number;