semiotic 3.5.4 → 3.7.0

package/dist/components/ai/audiences.d.ts

@@ -0,0 +1,31 @@
+import type { AudienceProfile } from "./audienceProfile";
+/**
+ * Three example AudienceProfile shapes. Not authoritative — these are
+ * sketches based on rough industry stereotypes, useful for documentation,
+ * demos, and as starting points consumers can fork.
+ *
+ * To use one in production, copy it and tune to your audience's actual
+ * survey/telemetry data. Do not assume these defaults represent your team.
+ */
+/**
+ * Executive audience — high familiarity with bar/line/pie/gauge,
+ * limited tolerance for unfamiliar chart shapes. Most likely to encounter
+ * dashboards built by analysts; not building their own.
+ */
+export declare const executivePersona: AudienceProfile;
+/**
+ * Analyst audience — broader chart vocabulary, comfortable with
+ * distribution-shape and matrix-shape charts. Building dashboards for
+ * others; can read most things on first encounter.
+ */
+export declare const analystPersona: AudienceProfile;
+/**
+ * Data scientist audience — comfortable with the full distribution-chart
+ * family, regression overlays, and density encodings. Will accept most
+ * exotic shapes if they're more honest about the data.
+ */
+export declare const dataScientistPersona: AudienceProfile;
+/**
+ * Convenience map for consumers loading audience by name (e.g. from a config string).
+ */
+export declare const BUILT_IN_AUDIENCES: Record<string, AudienceProfile>;

package/dist/components/ai/chartCapabilities.d.ts

@@ -0,0 +1,55 @@
+import type { ChartCapability } from "./chartCapabilityTypes";
+import { LineChartCapability } from "../charts/xy/LineChart.capability";
+import { AreaChartCapability } from "../charts/xy/AreaChart.capability";
+import { StackedAreaChartCapability } from "../charts/xy/StackedAreaChart.capability";
+import { ScatterplotCapability } from "../charts/xy/Scatterplot.capability";
+import { ConnectedScatterplotCapability } from "../charts/xy/ConnectedScatterplot.capability";
+import { BubbleChartCapability } from "../charts/xy/BubbleChart.capability";
+import { QuadrantChartCapability } from "../charts/xy/QuadrantChart.capability";
+import { MultiAxisLineChartCapability } from "../charts/xy/MultiAxisLineChart.capability";
+import { MinimapChartCapability } from "../charts/xy/MinimapChart.capability";
+import { DifferenceChartCapability } from "../charts/xy/DifferenceChart.capability";
+import { CandlestickChartCapability } from "../charts/xy/CandlestickChart.capability";
+import { HeatmapCapability } from "../charts/xy/Heatmap.capability";
+import { BarChartCapability } from "../charts/ordinal/BarChart.capability";
+import { GroupedBarChartCapability } from "../charts/ordinal/GroupedBarChart.capability";
+import { StackedBarChartCapability } from "../charts/ordinal/StackedBarChart.capability";
+import { DotPlotCapability } from "../charts/ordinal/DotPlot.capability";
+import { PieChartCapability } from "../charts/ordinal/PieChart.capability";
+import { DonutChartCapability } from "../charts/ordinal/DonutChart.capability";
+import { FunnelChartCapability } from "../charts/ordinal/FunnelChart.capability";
+import { GaugeChartCapability } from "../charts/ordinal/GaugeChart.capability";
+import { LikertChartCapability } from "../charts/ordinal/LikertChart.capability";
+import { SwimlaneChartCapability } from "../charts/ordinal/SwimlaneChart.capability";
+import { HistogramCapability } from "../charts/ordinal/Histogram.capability";
+import { BoxPlotCapability } from "../charts/ordinal/BoxPlot.capability";
+import { SwarmPlotCapability } from "../charts/ordinal/SwarmPlot.capability";
+import { ViolinPlotCapability } from "../charts/ordinal/ViolinPlot.capability";
+import { RidgelinePlotCapability } from "../charts/ordinal/RidgelinePlot.capability";
+import { ForceDirectedGraphCapability } from "../charts/network/ForceDirectedGraph.capability";
+import { SankeyDiagramCapability } from "../charts/network/SankeyDiagram.capability";
+import { ChordDiagramCapability } from "../charts/network/ChordDiagram.capability";
+import { ProcessSankeyCapability } from "../charts/network/ProcessSankey.capability";
+import { TreeDiagramCapability } from "../charts/network/TreeDiagram.capability";
+import { TreemapCapability } from "../charts/network/Treemap.capability";
+import { CirclePackCapability } from "../charts/network/CirclePack.capability";
+import { OrbitDiagramCapability } from "../charts/network/OrbitDiagram.capability";
+import { ChoroplethMapCapability } from "../charts/geo/ChoroplethMap.capability";
+import { ProportionalSymbolMapCapability } from "../charts/geo/ProportionalSymbolMap.capability";
+import { FlowMapCapability } from "../charts/geo/FlowMap.capability";
+import { DistanceCartogramCapability } from "../charts/geo/DistanceCartogram.capability";
+/**
+ * Register a capability for a chart (built-in or third-party). Re-registering by
+ * component name replaces the previous descriptor — useful for overriding defaults.
+ */
+export declare function registerChartCapability(capability: ChartCapability): void;
+/** Remove a previously-registered capability. Does not affect built-ins. */
+export declare function unregisterChartCapability(component: string): void;
+/**
+ * Current capability list — built-ins, then user-registered, with user-registered
+ * overriding built-ins by component name.
+ */
+export declare function getCapabilities(): ReadonlyArray<ChartCapability>;
+/** Look up a capability by component name. */
+export declare function getCapability(component: string): ChartCapability | undefined;
+export { LineChartCapability, AreaChartCapability, StackedAreaChartCapability, ScatterplotCapability, ConnectedScatterplotCapability, BubbleChartCapability, QuadrantChartCapability, MultiAxisLineChartCapability, MinimapChartCapability, DifferenceChartCapability, CandlestickChartCapability, HeatmapCapability, BarChartCapability, GroupedBarChartCapability, StackedBarChartCapability, DotPlotCapability, PieChartCapability, DonutChartCapability, FunnelChartCapability, GaugeChartCapability, LikertChartCapability, SwimlaneChartCapability, HistogramCapability, BoxPlotCapability, SwarmPlotCapability, ViolinPlotCapability, RidgelinePlotCapability, ForceDirectedGraphCapability, SankeyDiagramCapability, ChordDiagramCapability, ProcessSankeyCapability, TreeDiagramCapability, TreemapCapability, CirclePackCapability, OrbitDiagramCapability, ChoroplethMapCapability, ProportionalSymbolMapCapability, FlowMapCapability, DistanceCartogramCapability, };

package/dist/components/ai/chartCapabilityTypes.d.ts

@@ -0,0 +1,254 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { DataSummary } from "../data/DataSummarizer";
+import type { IntentId } from "./intents";
+import type { ScaleFitFn, QualityFitFn, ScaleBand, CardinalityBand, EffectiveScale } from "./dataScaleProfile";
+/**
+ * Chart family — high-level taxonomy used for filtering and intent matching.
+ */
+export type ChartFamily = "time-series" | "categorical" | "distribution" | "relationship" | "flow" | "network" | "hierarchy" | "geo" | "realtime" | "value" | "custom";
+/**
+ * Where a chart is imported from. Used by generators to emit correct import paths.
+ */
+export type ChartImportPath = "semiotic/xy" | "semiotic/ordinal" | "semiotic/network" | "semiotic/geo" | "semiotic/realtime" | "semiotic/value" | "semiotic/ai" | "semiotic";
+/**
+ * Familiarity/accuracy/precision rubric (1-5 each).
+ * Familiarity = how well-known the chart is to a general audience.
+ * Accuracy    = how faithfully it represents the underlying data.
+ * Precision   = how readable individual values are.
+ */
+export interface ChartRubric {
+    familiarity: number;
+    accuracy: number;
+    precision: number;
+}
+/**
+ * The kind of value a field holds, used for axis fitness.
+ */
+export type FieldKind = "numeric" | "categorical" | "date" | "boolean" | "unknown";
+/**
+ * A candidate field for a given role (x, y, series, etc.), with a quality score.
+ */
+export interface FieldCandidate {
+    field: string;
+    kind: FieldKind;
+    /** 0..1 — how good this field is for the role being considered. */
+    quality: number;
+    /** Field-level stats for downstream scorers. */
+    distinctCount?: number;
+    /** True if the field's values are strictly increasing in row order. */
+    monotonic?: boolean;
+}
+/**
+ * Profile of a dataset for chart-fitness scoring. Extends DataSummary with
+ * shape inference (axis candidates, structure detection, primary roles).
+ */
+export interface ChartDataProfile extends DataSummary {
+    /** Original rows (read-only); used by capabilities to compute their own stats. */
+    data: ReadonlyArray<Datum>;
+    /** Candidate fields per role, sorted best-first. */
+    candidates: {
+        x: FieldCandidate[];
+        y: FieldCandidate[];
+        size: FieldCandidate[];
+        category: FieldCandidate[];
+        series: FieldCandidate[];
+        time: FieldCandidate[];
+    };
+    /** Best-guess primary assignment per role (the top candidate, if any). */
+    primary: {
+        x?: string;
+        y?: string;
+        size?: string;
+        category?: string;
+        series?: string;
+        time?: string;
+    };
+    /** Distinct count of the primary category field, if any. */
+    categoryCount?: number;
+    /** Distinct count of the primary series field, if any. */
+    seriesCount?: number;
+    /** Distinct count of the primary x field, if any. */
+    uniqueXCount?: number;
+    /** True when some x value appears in more than one row (suggests aggregation). */
+    hasRepeatedX: boolean;
+    /** True when the primary x candidate is monotonic. */
+    monotonicX: boolean;
+    /** True when there is at least one date-typed candidate. */
+    hasTimeAxis: boolean;
+    /**
+     * How the primary x role was inferred. Capabilities can use this to detect
+     * the "scatter fallback" case (x picked only because there were 2+ numerics,
+     * not because the field is genuinely an x-axis) and decline to recommend
+     * themselves for trend-shaped intents.
+     *
+     * • "time"   — explicit date/time field
+     * • "named"  — numeric whose name matches an x-pattern (month, year, index, …)
+     * • "scatter"— filled in via the two-numeric scatter fallback; weak signal
+     * • "none"   — no x role inferred
+     */
+    xProvenance: "time" | "named" | "scatter" | "none";
+    /** Source dataset looks like a hierarchy (had a `children` array at root). */
+    hasHierarchy: boolean;
+    /** Source dataset looks like a node/edge graph. */
+    hasNetwork: boolean;
+    /** Source dataset looks like GeoJSON (FeatureCollection). */
+    hasGeo: boolean;
+    /** Extracted network payload when hasNetwork is true. */
+    network?: {
+        nodes: ReadonlyArray<Datum>;
+        edges: ReadonlyArray<Datum>;
+    };
+    /** Extracted hierarchy root when hasHierarchy is true. */
+    hierarchy?: Datum;
+    /** Extracted GeoJSON FeatureCollection when hasGeo is true. */
+    geo?: {
+        features: ReadonlyArray<Datum>;
+        points?: ReadonlyArray<Datum>;
+        flows?: ReadonlyArray<Datum>;
+    };
+}
+/**
+ * An intent scorer is either a static 0..5 score or a function evaluated against the profile.
+ */
+export type IntentScorer = number | ((profile: ChartDataProfile) => number);
+/**
+ * Variant — a configuration of the chart that meaningfully changes what it's good for.
+ *
+ * Variants compose into suggestions. The `intentDeltas` are additive against the
+ * base capability's intent scores (clamped to 0..5 by the engine).
+ */
+export interface ChartVariant {
+    key: string;
+    label: string;
+    description?: string;
+    /** Props to merge into the base chart props. */
+    props: Record<string, unknown>;
+    /** Style/role tags (used by consumers like vizmart for filtering). */
+    tags?: ReadonlyArray<string>;
+    /** Per-intent additive score deltas (e.g. {"trend": +1, "outlier-detection": -2}). */
+    intentDeltas?: Partial<Record<IntentId, number>>;
+    /** Rubric deltas — usually small, e.g. smoothing trades precision for familiarity. */
+    rubricDeltas?: Partial<ChartRubric>;
+    /** Caveats specific to this variant — surfaced in suggestion.caveats. */
+    caveats?: ReadonlyArray<string>;
+}
+/**
+ * Result of a capability's `fits()` gate. `null` means the chart fits. A string
+ * is the human-readable reason it doesn't, used for diagnostics and reasoning.
+ */
+export type FitResult = null | string;
+/**
+ * The capability descriptor each chart ships alongside itself.
+ *
+ * Charts that declare a capability participate in `suggestCharts`, `useChartSuggestions`,
+ * and the `interrogateChart` MCP tool's recommendation surface.
+ */
+export interface ChartCapability {
+    component: string;
+    family: ChartFamily;
+    importPath: ChartImportPath;
+    /** Base rubric, before variant/profile adjustments. */
+    rubric: ChartRubric;
+    /**
+     * Hard requirements gate. Return null if the chart can render this profile,
+     * or a human-readable string explaining why not (e.g. "no numeric y candidate").
+     */
+    fits: (profile: ChartDataProfile) => FitResult;
+    /**
+     * Per-intent suitability score (0..5). Missing intents default to 0.
+     * Values may be functions for profile-aware scoring.
+     */
+    intentScores: Partial<Record<IntentId, IntentScorer>>;
+    /**
+     * Variants — different settings that change what the chart is useful for.
+     * Suggestion engine emits one suggestion per (capability × variant) pair.
+     * If empty, the engine still emits a base suggestion.
+     */
+    variants?: ReadonlyArray<ChartVariant>;
+    /** Caveats independent of variants (e.g. "log scale skipped for negative values"). */
+    caveats?: (profile: ChartDataProfile) => ReadonlyArray<string>;
+    /**
+     * Build the props you'd pass to this chart for this dataset. Should produce
+     * a runnable config (accessor names, etc.) so consumers can `<Component {...props}>`.
+     */
+    buildProps: (profile: ChartDataProfile, variant?: ChartVariant) => Record<string, unknown>;
+    /**
+     * Optional declaration of this chart's sweet spot under scale. Receives the
+     * effective scale (declared `DataScaleProfile` merged with measured profile)
+     * and returns a score delta plus optional caveats. Use `scaleHints(...)` from
+     * `dataScaleProfile.ts` for the common declarative shape.
+     *
+     * When omitted, the engine assumes the chart is scale-agnostic and applies
+     * no scale bias beyond what `intentScores` already encodes in `profile`.
+     */
+    scaleFit?: ScaleFitFn;
+    /**
+     * Optional declaration of this chart's response to data quality (missingness,
+     * outliers, type heterogeneity). Returns a score delta plus caveats. When
+     * omitted, the engine applies a default heuristic that adds caveats for
+     * low completeness on the primary y field.
+     */
+    qualityFit?: QualityFitFn;
+}
+/**
+ * Effective scale range tag on a suggestion. Lets callers group suggestions
+ * by their scale sweet spot, detect threshold crossings as data grows, and
+ * narrate why a recommendation changed.
+ */
+export interface SuggestionScaleRange {
+    /** Band classification of the row count this suggestion was evaluated against. */
+    band: ScaleBand;
+    /** Cardinality band, if known. */
+    cardinalityBand?: CardinalityBand;
+    /** Effective row count the engine reasoned over (declared or measured). */
+    rows: number;
+    /** Whether the row count came from a user-declared profile or the measured data. */
+    rowsSource: "declared" | "measured";
+}
+/**
+ * One suggestion produced by `suggestCharts`. Consumers render this as a card,
+ * pass it to an LLM for re-ranking, or hand the props straight to the chart.
+ */
+export interface Suggestion {
+    component: string;
+    family: ChartFamily;
+    importPath: ChartImportPath;
+    variant?: ChartVariant;
+    /** Composite score for the ranking intent(s), 0..5. */
+    score: number;
+    /** Per-intent scores after variant deltas. */
+    intentScores: Partial<Record<IntentId, number>>;
+    /** Rubric after variant/profile adjustments. */
+    rubric: ChartRubric;
+    /** Narrative reasons this chart fits — suitable for tooltips or LLM context. */
+    reasons: ReadonlyArray<string>;
+    /** Gotchas / things to be careful about. */
+    caveats: ReadonlyArray<string>;
+    /** Ready-to-spread props. */
+    props: Record<string, unknown>;
+    /**
+     * Scale tag — present when scale/quality information is available, either
+     * through declared `DataScaleProfile` or through the measured profile.
+     * Surfaces what band this chart was scored at so consumers can group by
+     * scale, detect threshold crossings, or narrate "the chart for now → at 10×."
+     */
+    scaleRange?: SuggestionScaleRange;
+}
+/**
+ * Multi-tier grouping of suggestions by scale band. Returned by
+ * `suggestChartsGrouped()`.
+ *
+ * Each tier is a ranked list of suggestions whose `scaleRange.band` falls in
+ * that tier. A single chart can appear in multiple tiers when its sweet-spot
+ * range spans them — that's the "graduation of views" surface: the same data
+ * gets a different chart depending on which scale you're optimizing for.
+ */
+export interface ScaledSuggestionGroups {
+    tiny: Suggestion[];
+    small: Suggestion[];
+    medium: Suggestion[];
+    large: Suggestion[];
+    huge: Suggestion[];
+    /** The effective scale view the engine reasoned over. */
+    effective: EffectiveScale;
+}

package/dist/components/ai/chartRoles.d.ts

@@ -0,0 +1,27 @@
+import type { Datum } from "../charts/shared/datumTypes";
+/**
+ * Shared chart-family classification + measure/dimension role resolution.
+ *
+ * `describeChart` (prose) and `buildNavigationTree` (structure) both need to
+ * know which family a component belongs to and which props carry its measure
+ * (quantitative) and dimension (categorical/ordered) accessors. This is the
+ * single source of truth so the two surfaces can't drift apart.
+ *
+ * Pure, dependency-light (types only).
+ */
+export declare const XY_FAMILY: Set<string>;
+export declare const BAR_FAMILY: Set<string>;
+export declare const PART_TO_WHOLE: Set<string>;
+export declare const DISTRIBUTION: Set<string>;
+export interface ChartRoles {
+    measure?: string;
+    measureFallback: string;
+    dimension?: string;
+    dimensionFallback: string;
+}
+/** The measure (quantitative) and dimension (categorical/ordered) accessors, by family. */
+export declare function roles(component: string, props: Datum): ChartRoles;
+/** First string-valued series-splitting accessor among the known channels, if any. */
+export declare function seriesField(props: Datum): string | undefined;
+/** Format a dimension value (the label at an extremum) — dates as ISO day, numbers compactly. */
+export declare function fmtDim(v: unknown, fmtNum: (n: number) => string): string;