semiotic 3.0.0-beta.3 → 3.0.0-beta.4

package/dist/charts/shared/hooks.d.ts

@@ -1,4 +1,8 @@
-import type { Accessor } from "./types";
+import { createLegend } from "./legendUtils";
+import type { SelectionHookResult } from "./selectionUtils";
+import type { OnObservationCallback } from "../../store/ObservationStore";
+import type { Accessor, SelectionConfig, LinkedHoverProp, ChartMode } from "./types";
+import type { MarginType } from "../../types/generalTypes";
 /**
  * Default fill color used when no colorBy is specified
  */
@@ -18,3 +22,94 @@ export declare function useColorScale(data: Array<Record<string, any>>, colorBy:
  * Used by BarChart and DotPlot.
  */
 export declare function useSortedData(data: Array<Record<string, any>>, sort: boolean | "asc" | "desc" | ((a: Record<string, any>, b: Record<string, any>) => number), valueAccessor: Accessor<number>): Array<Record<string, any>>;
+/**
+ * Hook to set up selection and linked hover for a chart component.
+ * Consolidates normalizeLinkedHover, useSelection, useLinkedHover,
+ * and the customHoverBehavior callback that every HOC chart repeats.
+ *
+ * @param unwrapData - Deprecated / no-op. Hover data is always unwrapped
+ *   (stream frames wrap the raw datum in { data, time, value, x, y }).
+ */
+export declare function useChartSelection({ selection, linkedHover, fallbackFields, unwrapData, onObservation, chartType, chartId, }: {
+    selection?: SelectionConfig;
+    linkedHover?: LinkedHoverProp;
+    fallbackFields?: string[];
+    unwrapData?: boolean;
+    onObservation?: OnObservationCallback;
+    chartType?: string;
+    chartId?: string;
+}): {
+    activeSelectionHook: SelectionHookResult | null;
+    customHoverBehavior: (d: Record<string, any> | null) => void;
+    customClickBehavior: (d: Record<string, any> | null) => void;
+};
+/**
+ * Hook to create a legend and compute margins with legend-aware adjustment.
+ * Consolidates the shouldShowLegend / createLegend / margin merge / right-margin
+ * expansion pattern that every chart with color encoding repeats.
+ */
+export declare function useChartLegendAndMargin({ data, colorBy, colorScale, showLegend, userMargin, defaults, }: {
+    data: Array<Record<string, any>>;
+    colorBy: Accessor<string> | undefined;
+    colorScale: ((v: string) => string) | undefined;
+    showLegend: boolean | undefined;
+    userMargin: MarginType | undefined;
+    defaults?: {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    };
+}): {
+    legend: ReturnType<typeof createLegend> | undefined;
+    margin: {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    };
+};
+interface ChartModeInput {
+    width?: number;
+    height?: number;
+    showGrid?: boolean;
+    enableHover?: boolean;
+    showLegend?: boolean;
+    showLabels?: boolean;
+    title?: string;
+    xLabel?: string;
+    yLabel?: string;
+    categoryLabel?: string;
+    valueLabel?: string;
+    /** When truthy, enableHover is forced true regardless of mode (LinkedCharts needs hover) */
+    linkedHover?: any;
+}
+interface ChartModeResult {
+    width: number;
+    height: number;
+    showAxes: boolean;
+    showGrid: boolean;
+    enableHover: boolean;
+    showLegend: boolean | undefined;
+    showLabels: boolean | undefined;
+    title: string | undefined;
+    xLabel: string | undefined;
+    yLabel: string | undefined;
+    categoryLabel: string | undefined;
+    valueLabel: string | undefined;
+    marginDefaults: {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    };
+}
+/**
+ * Resolve chart display mode into concrete prop defaults.
+ * User-provided values always override mode defaults.
+ */
+export declare function useChartMode(mode: ChartMode | undefined, userProps: ChartModeInput, primaryDefaults?: {
+    width?: number;
+    height?: number;
+}): ChartModeResult;
+export {};

package/dist/charts/shared/loess.d.ts

@@ -0,0 +1,13 @@
+/**
+ * LOESS (Locally Weighted Scatterplot Smoothing) regression.
+ *
+ * For each x-point, fits a local weighted linear regression using tricube
+ * weights, producing a smooth curve that follows the data more closely
+ * than global polynomial regression.
+ *
+ * @param points - Array of [x, y] pairs (need not be sorted)
+ * @param bandwidth - Smoothing parameter 0-1. Lower = more local detail,
+ *                    higher = smoother. Default 0.3.
+ * @returns Array of [x, y_smoothed] pairs sorted by x
+ */
+export declare function loess(points: [number, number][], bandwidth?: number): [number, number][];

package/dist/charts/shared/networkUtils.d.ts

@@ -0,0 +1,31 @@
+import type { Accessor } from "./types";
+/**
+ * Flatten a hierarchical data structure into an array of all nodes
+ * by recursively traversing children.
+ */
+export declare function flattenHierarchy(data: Record<string, any> | null, childrenAccessor: string | ((d: any) => any[])): Array<Record<string, any>>;
+/**
+ * Infer nodes from edges when a nodes array is not provided.
+ * Extracts unique source/target IDs and returns `{ id }` objects.
+ * Returns the provided nodes array if it's non-empty.
+ */
+export declare function inferNodesFromEdges(nodes: any[] | undefined, edges: any[], sourceAccessor: string | ((d: any) => string), targetAccessor: string | ((d: any) => string)): Array<{
+    id: string;
+}>;
+/**
+ * Convert a valueAccessor prop into a hierarchy sum function.
+ * Used by TreeDiagram, Treemap, and CirclePack for d3-hierarchy's `.sum()`.
+ */
+export declare function resolveHierarchySum(valueAccessor: string | ((d: any) => number)): (d: Record<string, any>) => number;
+/**
+ * Create an edge style function for Sankey/Chord edge coloring.
+ * Handles edgeColorBy = "source" | "target" | "gradient" | function.
+ */
+export declare function createEdgeStyleFn({ edgeColorBy, colorBy, colorScale, nodeStyleFn, edgeOpacity, baseStyle, }: {
+    edgeColorBy: "source" | "target" | "gradient" | ((d: any) => string);
+    colorBy: Accessor<string> | undefined;
+    colorScale: ((v: string) => string) | undefined;
+    nodeStyleFn: (d: any, index?: number) => Record<string, any>;
+    edgeOpacity: number;
+    baseStyle?: Record<string, string | number>;
+}): (d: Record<string, any>) => Record<string, any>;

package/dist/charts/shared/tooltipUtils.d.ts

@@ -10,9 +10,25 @@ export interface TooltipFieldConfig {
  * Strings return themselves; functions return "value".
  */
 export declare function accessorName(acc: string | Function): string;
+export declare function formatVal(v: unknown): string;
+export declare function resolveValue(d: Record<string, any>, acc: string | ((d: Record<string, any>) => any)): unknown;
 /**
  * Build a default tooltipContent function for StreamXYFrame HOCs.
  * Receives HoverData ({ data, time, value, x, y }) and renders
  * labeled fields derived from the HOC's props.
  */
 export declare function buildDefaultTooltip(fields: TooltipFieldConfig[]): (hover: HoverData) => React.ReactNode;
+/**
+ * Build a default tooltip for ordinal charts (BarChart, DotPlot, SwarmPlot, etc.).
+ * Shows a bold category header, formatted value, and optional group field.
+ *
+ * @param pieData - If true, extracts datum via `d.data?.[0] || d.data || d`
+ *   (PieChart/DonutChart wrap data in arrays). Default: `d.data || d`.
+ */
+export declare function buildOrdinalTooltip({ categoryAccessor, valueAccessor, groupAccessor, groupLabel, pieData, }: {
+    categoryAccessor: string | ((d: any) => any);
+    valueAccessor: string | ((d: any) => any);
+    groupAccessor?: string | ((d: any) => any);
+    groupLabel?: string;
+    pieData?: boolean;
+}): (d: Record<string, any>) => React.ReactNode;

package/dist/charts/shared/types.d.ts

@@ -1,4 +1,5 @@
 import type { MarginType } from "../../types/generalTypes";
+import type { OnObservationCallback } from "../../store/ObservationStore";
 /**
  * Selection consumption config — makes this chart react to a named selection
  */
@@ -32,10 +33,17 @@ export type LinkedBrushProp = string | {
     xField?: string;
     yField?: string;
 };
+/**
+ * Chart display mode — controls default chrome, size, and interaction.
+ * User-provided props always override mode defaults.
+ */
+export type ChartMode = "primary" | "context" | "sparkline";
 /**
  * Base props shared across all chart components
  */
 export interface BaseChartProps {
+    /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
+    mode?: ChartMode;
     /** Chart width in pixels. Default: 600 */
     width?: number;
     /** Chart height in pixels. Default: 400 */
@@ -52,6 +60,11 @@ export interface BaseChartProps {
     linkedHover?: LinkedHoverProp;
     /** Produce brush-based selections for cross-filtering */
     linkedBrush?: LinkedBrushProp;
+    /** Callback emitting structured observation events on user interaction.
+     * Used by AI agent systems to observe user behavior for insight generation. */
+    onObservation?: OnObservationCallback;
+    /** Identifier for this chart instance, included in observation events */
+    chartId?: string;
 }
 /**
  * Axis configuration props
@@ -72,9 +85,11 @@ export interface AxisConfig {
  */
 export type Accessor<T = any> = string | ((d: any, i?: number) => T);
 /**
- * Generic accessor type that provides autocomplete when TDatum is specified
+ * Generic accessor type that provides autocomplete when TDatum is specified.
+ * Uses Record<string, any> in the function param so HOC charts can pass
+ * accessors to Stream Frames without contravariance errors under strict mode.
  */
-export type ChartAccessor<TDatum, T> = (keyof TDatum & string) | ((d: TDatum, i?: number) => T);
+export type ChartAccessor<TDatum, T> = (keyof TDatum & string) | ((d: Record<string, any>, i?: number) => T);
 /**
  * Color configuration
  */

package/dist/charts/shared/validateChartData.d.ts

@@ -2,9 +2,8 @@
  * Validates chart data and accessors at render time.
  * Returns null if data is valid, or an error message string if not.
  *
- * Validation is intentionally lightweight — it checks the first data point
- * to catch common mistakes (wrong field names, missing data) without
- * iterating the entire dataset.
+ * Samples first, last, and a middle element to catch common mistakes
+ * (wrong field names, missing data) without iterating the entire dataset.
  */
 type AccessorLike = string | ((...args: any[]) => any);
 interface ArrayDataValidation {

package/dist/charts/shared/validateProps.d.ts

@@ -9,6 +9,23 @@ export interface ValidationResult {
     valid: boolean;
     errors: string[];
 }
+export type PropType = "string" | "number" | "boolean" | "array" | "object" | "function";
+export interface PropDef {
+    type: PropType | PropType[];
+    enum?: readonly string[];
+}
+type DataShape = "array" | "object" | "network" | "realtime";
+export interface ComponentSpec {
+    /** Props that must be present */
+    required: string[];
+    /** Data shape — drives which validateChartData helper to call */
+    dataShape: DataShape;
+    /** Accessor props to validate against data (key = prop name) */
+    dataAccessors: string[];
+    /** Per-prop type / enum constraints */
+    props: Record<string, PropDef>;
+}
+export declare const VALIDATION_MAP: Record<string, ComponentSpec>;
 /**
  * Validate props for a Semiotic HOC chart component.
  *
@@ -16,3 +33,4 @@ export interface ValidationResult {
  * unknown prop names (typo detection), and data shape + accessor validity.
  */
 export declare function validateProps(componentName: string, props: Record<string, any>): ValidationResult;
+export {};

package/dist/charts/xy/AreaChart.d.ts

@@ -93,6 +93,10 @@ export interface AreaChartProps<TDatum extends Record<string, any> = Record<stri
      * Tooltip configuration
      */
     tooltip?: TooltipProp;
+    /**
+     * Annotation objects to render on the chart
+     */
+    annotations?: Record<string, any>[];
     /**
      * Additional StreamXYFrame props for advanced customization
      * For full control, consider using StreamXYFrame directly

package/dist/charts/xy/BubbleChart.d.ts

@@ -90,6 +90,12 @@ export interface BubbleChartProps<TDatum extends Record<string, any> = Record<st
      * Marginal distribution plots in axis margins
      */
     marginalGraphics?: MarginalGraphicsConfig;
+    /** Accessor for unique point IDs, used by point-anchored annotations */
+    pointIdAccessor?: ChartAccessor<TDatum, string>;
+    /**
+     * Annotation objects to render on the chart
+     */
+    annotations?: Record<string, any>[];
     /**
      * Additional StreamXYFrame props for advanced customization
      * For full control, consider using StreamXYFrame directly

package/dist/charts/xy/Heatmap.d.ts

@@ -86,6 +86,10 @@ export interface HeatmapProps<TDatum extends Record<string, any> = Record<string
      * Tooltip configuration
      */
     tooltip?: TooltipProp;
+    /**
+     * Annotation objects to render on the chart
+     */
+    annotations?: Record<string, any>[];
     /**
      * Additional StreamXYFrame props for advanced customization
      * For full control, consider using StreamXYFrame directly

package/dist/charts/xy/LineChart.d.ts

@@ -109,6 +109,12 @@ export interface LineChartProps<TDatum extends Record<string, any> = Record<stri
      * Tooltip configuration
      */
     tooltip?: TooltipProp;
+    /** Accessor for unique point IDs, used by point-anchored annotations (when showPoints is true) */
+    pointIdAccessor?: ChartAccessor<TDatum, string>;
+    /**
+     * Annotation objects to render on the chart
+     */
+    annotations?: Record<string, any>[];
     /**
      * Additional StreamXYFrame props for advanced customization
      * For full control, consider using StreamXYFrame directly

package/dist/charts/xy/Scatterplot.d.ts

@@ -34,6 +34,10 @@ export interface ScatterplotProps<TDatum extends Record<string, any> = Record<st
     tooltip?: TooltipProp;
     /** Marginal distribution plots in axis margins */
     marginalGraphics?: MarginalGraphicsConfig;
+    /** Accessor for unique point IDs, used by point-anchored annotations */
+    pointIdAccessor?: ChartAccessor<TDatum, string>;
+    /** Annotation objects to render on the chart */
+    annotations?: Record<string, any>[];
     /** Additional StreamXYFrame props for advanced customization */
     frameProps?: Partial<Omit<StreamXYFrameProps, "chartType" | "data" | "size">>;
 }

package/dist/charts/xy/StackedAreaChart.d.ts

@@ -97,6 +97,10 @@ export interface StackedAreaChartProps<TDatum extends Record<string, any> = Reco
      * Tooltip configuration
      */
     tooltip?: TooltipProp;
+    /**
+     * Annotation objects to render on the chart
+     */
+    annotations?: Record<string, any>[];
     /**
      * Additional StreamXYFrame props for advanced customization
      * For full control, consider using StreamXYFrame directly

package/dist/data/fromVegaLite.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Vega-Lite to Semiotic translator.
+ * Converts a Vega-Lite spec into a Semiotic ChartConfig.
+ *
+ * Scope: core marks (bar, line, point, area, rect, arc, circle, square, tick)
+ * with basic encodings. No layers, facets, selections, or complex transforms.
+ */
+import type { ChartConfig } from "../export/chartConfig";
+export interface VegaLiteEncoding {
+    field?: string;
+    type?: "quantitative" | "nominal" | "ordinal" | "temporal";
+    aggregate?: string;
+    scale?: {
+        scheme?: string;
+        range?: any;
+        domain?: any;
+    };
+    axis?: {
+        title?: string;
+        labelAngle?: number;
+    };
+    value?: any;
+    bin?: boolean | {
+        maxbins?: number;
+    };
+    stack?: boolean | string | null;
+}
+export interface VegaLiteSpec {
+    mark: string | {
+        type: string;
+        [key: string]: any;
+    };
+    data?: {
+        values?: any[];
+        url?: string;
+    };
+    encoding?: Record<string, VegaLiteEncoding>;
+    width?: number;
+    height?: number;
+    title?: string | {
+        text: string;
+    };
+    transform?: any[];
+    [key: string]: any;
+}
+export declare function fromVegaLite(spec: VegaLiteSpec): ChartConfig & {
+    warnings?: string[];
+};

package/dist/export/chartConfig.d.ts

@@ -0,0 +1,29 @@
+import type { SerializedSelections } from "./selectionSerializer";
+export interface ChartConfig {
+    /** Component name, e.g. "LineChart", "SankeyDiagram" */
+    component: string;
+    /** Serializable props only — functions and React elements stripped */
+    props: Record<string, any>;
+    /** Config schema version */
+    version: string;
+    /** ISO 8601 timestamp */
+    createdAt: string;
+    /** Optional serialized selection/brush state */
+    selections?: SerializedSelections;
+}
+export interface ToConfigOptions {
+    /** Include data arrays in the config. Default: true */
+    includeData?: boolean;
+    /** Serialized selection state to embed */
+    selections?: SerializedSelections;
+}
+export type CopyFormat = "json" | "jsx";
+export declare function toConfig(componentName: string, props: Record<string, any>, options?: ToConfigOptions): ChartConfig;
+export declare function fromConfig(config: ChartConfig): {
+    componentName: string;
+    props: Record<string, any>;
+};
+export declare function toURL(config: ChartConfig): string;
+export declare function fromURL(urlString: string): ChartConfig;
+export declare function copyConfig(config: ChartConfig, format?: CopyFormat): Promise<void>;
+export declare function configToJSX(config: ChartConfig): string;

package/dist/export/selectionSerializer.d.ts

@@ -0,0 +1,20 @@
+import type { Selection } from "../store/SelectionStore";
+export type SerializedFieldSelection = {
+    type: "point";
+    values: any[];
+} | {
+    type: "interval";
+    range: [number, number];
+};
+export interface SerializedSelection {
+    name: string;
+    resolution: "union" | "intersect" | "crossfilter";
+    clauses: Array<{
+        clientId: string;
+        type: "point" | "interval";
+        fields: Record<string, SerializedFieldSelection>;
+    }>;
+}
+export type SerializedSelections = Record<string, SerializedSelection>;
+export declare function serializeSelections(selections: Map<string, Selection>): SerializedSelections;
+export declare function deserializeSelections(serialized: SerializedSelections): Map<string, Selection>;

package/dist/geometry/sankeyLinks.d.ts

@@ -1,2 +1,2 @@
 export declare const areaLink: (d: any) => string;
-export declare function circularAreaLink(link: any): any;
+export declare function circularAreaLink(link: any): string | null;