semiotic 3.6.0 → 3.7.1

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

@@ -13,6 +13,14 @@ export declare function computeCanvasAriaLabel(scene: AnySceneNode[] | null | un
  * Compute an aria-label for network charts from scene nodes and edges.
  */
 export declare function computeNetworkAriaLabel(nodeCount: number, edgeCount: number, chartType: string): string;
+interface DataRow {
+    label: string;
+    values: Record<string, string | number>;
+}
+/** Extract a flat list of typed rows from scene nodes, surfacing the raw datum
+ *  fields (not pixel coordinates). Defensively handles missing/malformed data —
+ *  never throws. Exported for direct testing. */
+export declare function extractAllRows(scene: AnySceneNode[]): DataRow[];
 interface AccessibleDataTableProps {
     scene: AnySceneNode[];
     chartType: string;
@@ -24,9 +32,10 @@ interface AccessibleDataTableProps {
 /**
  * JIT accessible data summary. Renders a lightweight sr-only button by default.
  * On activation (or when ChartContainer's dataSummary action is toggled),
- * computes a statistical summary (.describe()-style) and shows 5 sample rows.
+ * computes a statistical summary (.describe()-style) and shows a sample of rows
+ * (5 to start), pageable to the full dataset via "Show more".
  */
-export declare function AccessibleDataTable({ scene, chartType, tableId, chartTitle }: AccessibleDataTableProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function AccessibleDataTable({ scene, chartType, tableId, chartTitle }: AccessibleDataTableProps): React.JSX.Element | null;
 interface NetworkAccessibleDataTableProps {
     nodes: Array<{
         datum?: any;
@@ -48,25 +57,25 @@ interface NetworkAccessibleDataTableProps {
 /**
  * JIT accessible data summary for network charts.
  */
-export declare function NetworkAccessibleDataTable({ nodes, edges, chartType, tableId, chartTitle }: NetworkAccessibleDataTableProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function NetworkAccessibleDataTable({ nodes, edges, chartType, tableId, chartTitle }: NetworkAccessibleDataTableProps): React.JSX.Element | null;
 /**
  * Screen-reader-only summary note for the chart.
  * Rendered as role="note" so assistive technology can discover it.
  */
 export declare function ScreenReaderSummary({ summary }: {
     summary?: string;
-}): import("react/jsx-runtime").JSX.Element | null;
+}): React.JSX.Element | null;
 /**
  * Screen-reader-only skip link to jump past chart canvas to the data table.
  * Only rendered when accessibleTable is enabled.
  */
 export declare function SkipToTableLink({ tableId }: {
     tableId: string;
-}): import("react/jsx-runtime").JSX.Element;
+}): React.JSX.Element;
 /**
  * Visually-hidden aria-live region that mirrors tooltip text for screen readers.
  */
 export declare function AriaLiveTooltip({ hoverPoint }: {
     hoverPoint: any;
-}): import("react/jsx-runtime").JSX.Element;
+}): React.JSX.Element;
 export { SR_ONLY_STYLE };

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

@@ -1,3 +1,4 @@
+import * as React from "react";
 /**
  * Shape-appropriate keyboard focus indicator for canvas-based charts.
  *
@@ -29,4 +30,4 @@ export interface FocusRingProps {
     /** Height of rect-shaped focus target */
     height?: number;
 }
-export declare function FocusRing({ active, hoverPoint, margin, size, shape, width, height }: FocusRingProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function FocusRing({ active, hoverPoint, margin, size, shape, width, height }: FocusRingProps): React.JSX.Element | null;

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

@@ -1,3 +1,4 @@
+import * as React from "react";
 import type { ScaleLinear } from "d3-scale";
 import type { MarginalConfig, MarginalType } from "./types";
 export type MarginalOrient = "top" | "bottom" | "left" | "right";
@@ -15,4 +16,4 @@ export interface MarginalGraphicsProps {
 }
 /** Resolve a string shorthand or full config into a MarginalConfig */
 export declare function normalizeMarginalConfig(input: MarginalConfig | MarginalType): MarginalConfig;
-export declare function MarginalGraphics({ orient, config: rawConfig, values, scale, size, length }: MarginalGraphicsProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function MarginalGraphics({ orient, config: rawConfig, values, scale, size, length }: MarginalGraphicsProps): React.JSX.Element | null;

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

@@ -1,7 +1,10 @@
 import type { Datum } from "../charts/shared/datumTypes";
+import * as React from "react";
 import type { ReactNode } from "react";
 import type { NetworkLabel } from "./networkTypes";
 import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../types/legendTypes";
+import { type AutoPlaceAnnotations } from "../recipes/annotationLayout";
+import type { AnnotationContext } from "../realtime/types";
 type AnnotationAnchorNode = {
     type: string;
     datum: Datum | null;
@@ -12,6 +15,13 @@ type AnnotationAnchorNode = {
     cy?: number;
     w?: number;
     h?: number;
+    /** Circle nodes (NetworkCircleNode, force/tree/orbit marks) carry an explicit radius. */
+    r?: number;
+    /** Arc nodes (chord, radial) carry an outer radius. */
+    outerR?: number;
+};
+type NetworkAnnotationContext = AnnotationContext & {
+    sceneNodes?: AnnotationAnchorNode[];
 };
 export interface NetworkSVGOverlayProps {
     width: number;
@@ -50,11 +60,8 @@ export interface NetworkSVGOverlayProps {
     sceneNodes?: AnnotationAnchorNode[];
     /** Annotations */
     annotations?: Datum[];
-    svgAnnotationRules?: (annotation: Datum, index: number, context: {
-        width: number;
-        height: number;
-        sceneNodes?: AnnotationAnchorNode[];
-    }) => ReactNode;
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
+    svgAnnotationRules?: (annotation: Datum, index: number, context: NetworkAnnotationContext) => ReactNode;
     annotationFrame?: number;
 }
 /**
@@ -63,7 +70,7 @@ export interface NetworkSVGOverlayProps {
  * Unlike XY/ordinal overlays, network charts don't have axes or grid lines.
  * The overlay is positioned absolutely over the canvas.
  */
-export declare function NetworkSVGOverlay(props: NetworkSVGOverlayProps): import("react/jsx-runtime").JSX.Element;
+export declare function NetworkSVGOverlay(props: NetworkSVGOverlayProps): React.JSX.Element;
 export declare namespace NetworkSVGOverlay {
     var displayName: string;
 }

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

@@ -1,3 +1,21 @@
+/**
+ * OrdinalBrushOverlay — d3-brush SVG overlay for ordinal frames.
+ *
+ * Renders a transparent SVG positioned above the canvas. Brushes along the
+ * r-axis (value axis) only: horizontal projection → brushX, vertical → brushY.
+ *
+ * Key design decisions:
+ *   - Outer SVG has pointerEvents:"none", inner brush-g has "all", so
+ *     axes/legends rendered underneath remain clickable.
+ *   - d3-brush lifecycle (useEffect) depends on [width, height, isHorizontal]
+ *     only — NOT scales. Scales are read from a ref to avoid brush teardown
+ *     mid-drag (scales change every render due to new object identity).
+ *   - A separate useEffect repositions the brush when scales change (streaming).
+ *
+ * Consumed by: StreamOrdinalFrame (rendered when brush prop is set).
+ * Wired by: useOrdinalBrush hook in HOC charts.
+ */
+import * as React from "react";
 import type { OrdinalScales } from "./ordinalTypes";
 interface OrdinalBrushOverlayProps {
     width: number;
@@ -21,5 +39,5 @@ interface OrdinalBrushOverlayProps {
  * In horizontal projection, r maps to x-pixels → uses brushX.
  * In vertical projection, r maps to y-pixels → uses brushY.
  */
-export declare function OrdinalBrushOverlay({ width, height, totalWidth, totalHeight, margin, scales, onBrush }: OrdinalBrushOverlayProps): import("react/jsx-runtime").JSX.Element;
+export declare function OrdinalBrushOverlay({ width, height, totalWidth, totalHeight, margin, scales, onBrush }: OrdinalBrushOverlayProps): React.JSX.Element;
 export {};

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

@@ -4,6 +4,7 @@ import type { OrdinalScales } from "./ordinalTypes";
 import type { AnnotationContext } from "../realtime/types";
 import type { ReactNode } from "react";
 import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../types/legendTypes";
+import { type AutoPlaceAnnotations } from "../recipes/annotationLayout";
 import { type AxisExtentMode } from "../charts/shared/axisExtent";
 interface OrdinalSVGOverlayProps {
     width: number;
@@ -52,6 +53,7 @@ interface OrdinalSVGOverlayProps {
     legendLayout?: LegendLayout;
     foregroundGraphics?: ReactNode;
     annotations?: Datum[];
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     annotationFrame?: number;
     xAccessor?: string;
@@ -79,6 +81,6 @@ interface OrdinalSVGUnderlayProps {
     rTickValues?: number[];
     axisExtent?: AxisExtentMode;
 }
-export declare function OrdinalSVGUnderlay(props: OrdinalSVGUnderlayProps): import("react/jsx-runtime").JSX.Element | null;
-export declare function OrdinalSVGOverlay(props: OrdinalSVGOverlayProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function OrdinalSVGUnderlay(props: OrdinalSVGUnderlayProps): React.JSX.Element | null;
+export declare function OrdinalSVGOverlay(props: OrdinalSVGOverlayProps): React.JSX.Element | null;
 export {};

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

@@ -1,8 +1,10 @@
 import type { Datum } from "../charts/shared/datumTypes";
+import * as React from "react";
 import type { StreamScales, MarginalGraphicsConfig, XYFrameAxisConfig } from "./types";
 import type { AnnotationContext } from "../realtime/types";
 import type { ReactNode } from "react";
 import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../types/legendTypes";
+import { type AutoPlaceAnnotations } from "../recipes/annotationLayout";
 export type AxisConfig = XYFrameAxisConfig;
 interface SVGOverlayProps {
     width: number;
@@ -57,6 +59,7 @@ interface SVGOverlayProps {
     xValues?: number[];
     yValues?: number[];
     annotations?: Datum[];
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     annotationFrame?: number;
     xAccessor?: string;
@@ -109,6 +112,6 @@ interface SVGUnderlayProps {
     yFormat?: (d: number | Date | string) => string | ReactNode;
     axisExtent?: import("../charts/shared/axisExtent").AxisExtentMode;
 }
-export declare function SVGUnderlay(props: SVGUnderlayProps): import("react/jsx-runtime").JSX.Element | null;
-export declare function SVGOverlay(props: SVGOverlayProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function SVGUnderlay(props: SVGUnderlayProps): React.JSX.Element | null;
+export declare function SVGOverlay(props: SVGOverlayProps): React.JSX.Element | null;
 export {};

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

@@ -1,3 +1,23 @@
+/**
+ * XYBrushOverlay — d3-brush SVG overlay for XY frames.
+ *
+ * Renders a transparent SVG positioned above the canvas. Supports x, y, and
+ * xy brush dimensions, bin snapping, and streaming brush tracking (shrinks/
+ * clears the brush as data scrolls past the selected range).
+ *
+ * Key design decisions:
+ *   - d3-brush lifecycle depends on [width, height, dimension, snap, binSize, snapDuring]
+ *     only — scales and binBoundaries are read from refs to avoid teardown mid-drag.
+ *   - Data-driven snapping (binBoundaries) uses binary search to snap to actual bin
+ *     edges. Falls back to uniform grid math (binSize) when no boundaries are provided.
+ *   - Bin snapping applies on "end" events by default. Set snapDuring=true to also
+ *     snap during drag (the "brush" event).
+ *   - Streaming tracking guards against y-only dimension (no x-domain to track).
+ *   - isProgrammaticMoveRef prevents re-entrant brush events from .move() calls.
+ *
+ * Consumed by: StreamXYFrame (rendered when brush prop is set).
+ */
+import * as React from "react";
 import type { StreamScales } from "./types";
 export interface XYBrushOverlayProps {
     width: number;
@@ -24,4 +44,4 @@ export interface XYBrushOverlayProps {
     snapDuring?: boolean;
     streaming?: boolean;
 }
-export declare function XYBrushOverlay({ width, height, totalWidth, totalHeight, margin, dimension, scales, onBrush, binSize, snap, binBoundaries, snapDuring, streaming }: XYBrushOverlayProps): import("react/jsx-runtime").JSX.Element;
+export declare function XYBrushOverlay({ width, height, totalWidth, totalHeight, margin, dimension, scales, onBrush, binSize, snap, binBoundaries, snapDuring, streaming }: XYBrushOverlayProps): React.JSX.Element;

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

@@ -6,6 +6,7 @@ import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { HoverAnnotationConfig, HoverData } from "../realtime/types";
 import type { GeoParticleStyle } from "./GeoParticlePool";
 import type { Datum } from "../charts/shared/datumTypes";
+import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
 export type ProjectionProp = GeoProjection | ProjectionName | ProjectionConfig;
 export type ProjectionName = "mercator" | "equalEarth" | "albersUsa" | "orthographic" | "naturalEarth" | "equirectangular";
 export interface ProjectionConfig {
@@ -94,6 +95,7 @@ export interface GeoPipelineConfig {
     /** Whether to animate elements on first render */
     introAnimation?: boolean;
     annotations?: Datum[];
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
     pointIdAccessor?: string | ((d: Datum) => string);
     /** ID accessor on line data — required for `removeLine` by id. */
     lineIdAccessor?: string | ((d: Datum) => string);
@@ -174,6 +176,7 @@ export interface StreamGeoFrameProps<T = Datum> {
     customClickBehavior?: (d: HoverData | null) => void;
     customHoverBehavior?: (d: HoverData | null) => void;
     annotations?: Datum[];
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
     decay?: DecayConfig;
     pulse?: PulseConfig;
     transition?: TransitionConfig;

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

@@ -5,6 +5,7 @@ import type { LegendGroup, LegendLayout } from "../types/legendTypes";
 import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors, SceneDatum } from "./types";
 import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { Datum } from "../charts/shared/datumTypes";
+import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
 export interface TensionConfig {
     weightChange: number;
     newEdge: number;
@@ -518,6 +519,7 @@ export interface StreamNetworkFrameProps<T = Datum> {
     chartId?: string;
     onTopologyChange?: (nodes: RealtimeNode[], edges: RealtimeEdge[]) => void;
     annotations?: Datum[];
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     legend?: ReactNode | {
         legendGroups: LegendGroup[];

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

@@ -1,6 +1,7 @@
 import type { ReactNode } from "react";
 import type { ScaleLinear, ScaleBand } from "d3-scale";
 import type { WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext } from "../realtime/types";
+import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
 import type { Style, SceneDatum, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors } from "./types";
 import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { GradientLegendConfig, LegendGroup, LegendLayout } from "../types/legendTypes";
@@ -381,6 +382,7 @@ export interface StreamOrdinalFrameProps<T = Datum> {
     tooltipContent?: (d: HoverData) => ReactNode;
     customHoverBehavior?: (d: HoverData | null) => void;
     annotations?: Datum[];
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     showGrid?: boolean;
     legend?: ReactNode | {

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

@@ -5,6 +5,7 @@ import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../types/l
 import type { ArrowOfTime, WindowMode, LineStyle, BarStyle, WaterfallStyle, SwarmStyle, HoverAnnotationConfig, HoverData, AnnotationContext, AnnotationAnchorMode } from "../realtime/types";
 import type { Datum } from "../charts/shared/datumTypes";
 import type { CoercibleNumber } from "./accessorUtils";
+import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
 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);
@@ -635,6 +636,7 @@ export interface StreamXYFrameProps<T = Datum> {
     /** Accessor for unique point IDs used by point-anchored annotations */
     pointIdAccessor?: string | ((d: T) => string);
     annotations?: Datum[];
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     showGrid?: boolean;
     legend?: ReactNode | {