semiotic 3.7.3 → 3.7.5

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

@@ -6,6 +6,7 @@ import type { ArrowOfTime, WindowMode, LineStyle, BarStyle, WaterfallStyle, Swar
 import type { Datum } from "../charts/shared/datumTypes";
 import type { CoercibleNumber } from "./accessorUtils";
 import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
+import type { SymbolName } from "./symbolPath";
 export type SceneDatum = Datum | null;
 export type SeriesDatum = Datum[] | null;
 export type AxisTickFormat = ((d: number, index?: number, allTicks?: number[]) => string) | ((d: string, index?: number, allTicks?: number[]) => string) | ((d: Date, index?: number, allTicks?: number[]) => string);
@@ -47,14 +48,34 @@ export interface TransitionConfig {
     easing?: "ease-out" | "linear";
 }
 export interface StalenessConfig {
-    /** ms without data before "stale" (default: 5000) */
+    /**
+     * ms without data before "stale" (default: 5000). In graded mode this
+     * is the base TTL the lifecycle bands are measured against — `aging`
+     * begins here, `stale` at 1.5×, `expired` at 3× (overridable).
+     */
     threshold?: number;
-    /** Canvas alpha when stale (default: 0.5) */
+    /** Canvas alpha when stale, binary mode (default: 0.5) */
     dimOpacity?: number;
     /** Render LIVE/STALE badge (default: false) */
     showBadge?: boolean;
     /** Badge position (default: "top-right") */
     badgePosition?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
+    /**
+     * Opt into graded (banded) staleness. Instead of a single live→stale
+     * flip at `threshold`, frames that support graded staleness dim
+     * progressively through fresh → aging → stale → expired as idle time
+     * crosses multiples of `threshold`, sharing one schedule with per-datum
+     * decay and annotation freshness. (Currently honored by `StreamXYFrame`,
+     * which backs the realtime XY charts; other frames treat it as binary.)
+     * `true` uses the default per-band opacities; pass an object to override
+     * the band thresholds or opacities.
+     */
+    graded?: boolean | {
+        /** Multiples of `threshold` marking each band edge (see LifecycleBandThresholds). */
+        thresholds?: import("../realtime/lifecycleBands").LifecycleBandThresholds;
+        /** Per-band canvas alpha override. Missing bands use the defaults. */
+        opacities?: Partial<Record<import("../realtime/lifecycleBands").LifecycleBand, number>>;
+    };
 }
 export type MarginalType = "histogram" | "violin" | "ridgeline" | "boxplot";
 export interface MarginalConfig {
@@ -96,7 +117,7 @@ export interface Style {
     /** Internal geo line flag: fade line ends at projection clipping edges. */
     _edgeFade?: boolean;
 }
-export type SceneNode = LineSceneNode | AreaSceneNode | PointSceneNode | RectSceneNode | HeatcellSceneNode | CandlestickSceneNode;
+export type SceneNode = LineSceneNode | AreaSceneNode | PointSceneNode | SymbolSceneNode | RectSceneNode | HeatcellSceneNode | CandlestickSceneNode;
 export interface LineColorThreshold {
     value: number;
     color: string;
@@ -219,6 +240,46 @@ export interface PointSceneNode {
     /** Stable identity key for transition tracking */
     _transitionKey?: string;
 }
+/**
+ * Symbol node — the per-datum **shape channel**, shared with the network and
+ * ordinal pipelines. A glyph drawn from a `d3-shape` symbol path (or a custom
+ * `path`), painted on canvas and in SVG/SSR via the shared `symbolPath` helpers,
+ * and hit-tested + keyboard-navigated as a unit. Emitted by custom XY layouts
+ * and by Scatterplot's `symbolBy` encoding. Uses `x`/`y` like its sibling
+ * `PointSceneNode` (the network variant uses `cx`/`cy`).
+ */
+export interface SymbolSceneNode {
+    type: "symbol";
+    x: number;
+    y: number;
+    /** d3-symbol area in px² — drives the glyph's drawn size. */
+    size: number;
+    /** Named shape. Ignored when `path` is set. @default "circle" */
+    symbolType?: SymbolName;
+    /** Pre-built SVG path string, origin-centered — overrides `symbolType`. */
+    path?: string;
+    /** Rotation in radians about (x, y). */
+    rotation?: number;
+    style: Style;
+    datum: SceneDatum;
+    /** Optional unique identifier for point-anchored annotations. */
+    pointId?: string;
+    /** Pulse glow intensity 0–1 (set by PipelineStore when pulse is active). */
+    _pulseIntensity?: number;
+    /** Pulse glow color. */
+    _pulseColor?: string;
+    /** Pulse glow radius in px. */
+    _pulseGlowRadius?: number;
+    /** Animation target fields (set during transitions). */
+    _targetX?: number;
+    _targetY?: number;
+    _targetR?: number;
+    _targetOpacity?: number;
+    /** Per-datum decay opacity (set by PipelineStore.applyDecay). */
+    _decayOpacity?: number;
+    /** Stable identity key for transition tracking. */
+    _transitionKey?: string;
+}
 export interface RectSceneNode {
     type: "rect";
     x: number;
@@ -467,6 +528,10 @@ export interface StreamXYFrameProps<T = Datum> {
     yAccessor?: string | ((d: T) => CoercibleNumber);
     colorAccessor?: string | ((d: T) => string);
     sizeAccessor?: string | ((d: T) => CoercibleNumber);
+    /** Categorical accessor → glyph shape (scatter/bubble). */
+    symbolAccessor?: string | ((d: T) => string);
+    /** Explicit `{category → shape}` map for `symbolAccessor`; unmapped auto-assign. */
+    symbolMap?: Record<string, SymbolName>;
     groupAccessor?: string | ((d: T) => string);
     lineDataAccessor?: string;
     curve?: CurveType;
@@ -712,6 +777,10 @@ export interface StreamXYFrameProps<T = Datum> {
      *  signature) flow through without casts; layouts narrow via their
      *  own `CustomLayout<TConfig>` parameterization. */
     layoutConfig?: object;
+    /** Resolved shared selection projected into `LayoutContext.selection`. Kept off
+     *  the rebuild path — a change restyles (if the layout returned `restyle`) or
+     *  rebuilds, never re-ingests. */
+    layoutSelection?: import("./customLayoutSelection").CustomLayoutSelection | null;
 }
 export interface StreamXYFrameHandle<T = Datum> {
     push(datum: T): void;

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

@@ -4,10 +4,15 @@ interface StoreWithIngestTime {
 }
 /**
  * Shared hook that polls a store's `lastIngestTime` on a 1-second interval
- * and manages staleness state. When staleness changes it sets
+ * and manages staleness state. When the resolved staleness changes it sets
  * `dirtyRef.current = true` and calls `scheduleRender()` so the canvas
  * repaints with the appropriate dimming.
  *
+ * Handles both binary staleness (a single live→stale flip) and graded
+ * staleness (progressive dimming through fresh → aging → stale → expired):
+ * a repaint is scheduled whenever the resolved *band* changes, so the
+ * graded ramp advances even though `isStale` may already be true.
+ *
  * Call this hook after `storeRef`, `dirtyRef`, and `scheduleRender` are
  * declared. The `isStale` / `setIsStale` state must live in the caller
  * so that the `useState` call order stays unchanged.

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

@@ -8,6 +8,6 @@ import type { Datum } from "../../charts/shared/datumTypes";
  * Dependencies: SceneGraph (buildPointNode)
  * Consumed by: PipelineStore.buildSceneNodes (chartTypes "scatter", "bubble")
  */
-import type { PointSceneNode } from "../types";
+import type { PointSceneNode, SymbolSceneNode } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildPointScene(ctx: XYSceneContext, data: Datum[]): PointSceneNode[];
+export declare function buildPointScene(ctx: XYSceneContext, data: Datum[]): (PointSceneNode | SymbolSceneNode)[];

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

@@ -8,6 +8,7 @@ import type { AreaGradientConfig } from "./areaGradient";
  * accessing PipelineStore instance fields directly.
  */
 import type { StreamScales, Style, CurveType, BarStyle, ThemeSemanticColors } from "../types";
+import type { SymbolName } from "../symbolPath";
 import type { ResolvedRibbon } from "./ribbonScene";
 export interface XYSceneContext {
     scales: StreamScales;
@@ -17,6 +18,8 @@ export interface XYSceneContext {
     getY0?: (d: Datum) => number | null;
     getSize?: (d: Datum) => number;
     getColor?: (d: Datum) => string;
+    /** Categorical accessor → glyph shape (scatter/bubble symbolBy). */
+    getSymbol?: (d: Datum) => string;
     getGroup?: (d: Datum) => string;
     getCategory?: (d: Datum) => string;
     getPointId?: (d: Datum) => string;
@@ -68,6 +71,8 @@ export interface XYSceneConfig {
         r?: number;
     };
     sizeRange?: [number, number];
+    /** Explicit `{category → shape}` map for symbolBy; unmapped auto-assign. */
+    symbolMap?: Record<string, SymbolName>;
     xAccessor?: string | ((d: Datum) => any);
     yAccessor?: string | ((d: Datum) => any);
     valueAccessor?: string | ((d: Datum) => any);