semiotic 3.5.4 → 3.6.0

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

@@ -0,0 +1,76 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import { type ProfileDataOptions } from "./profileData";
+import type { ChartCapability, ChartDataProfile, Suggestion } from "./chartCapabilityTypes";
+import type { IntentId } from "./intents";
+import { type AudienceProfile } from "./audienceProfile";
+export interface SuggestChartsOptions extends ProfileDataOptions {
+    /** Ranking intent(s). When omitted, suggestions are ranked by mean intent score. */
+    intent?: IntentId | IntentId[];
+    /** Restrict to these component names. */
+    allow?: ReadonlyArray<string>;
+    /** Exclude these component names. */
+    deny?: ReadonlyArray<string>;
+    /** Maximum suggestions to return (default 10). */
+    maxResults?: number;
+    /** Include variant-level suggestions (default true). */
+    includeVariants?: boolean;
+    /** Filter out suggestions with a composite score below this (default 0 — keep all). */
+    minScore?: number;
+    /** Provide a pre-built profile instead of re-deriving from data. */
+    profile?: ChartDataProfile;
+    /** Override the registry. Defaults to the global capability registry. */
+    capabilities?: ReadonlyArray<ChartCapability>;
+    /**
+     * Audience profile — overrides chart familiarity and applies adoption-target
+     * bias to the ranking. See `audienceProfile.ts`.
+     */
+    audience?: AudienceProfile;
+}
+/**
+ * Suggest charts for a dataset, ranked by intent suitability.
+ *
+ * Heuristic-only — does not call an LLM. Designed to be cheap enough to run on every
+ * keystroke in a UI, and to feed structured context to an LLM when one is available.
+ */
+export declare function suggestCharts(data: ReadonlyArray<Datum> | null | undefined, options?: SuggestChartsOptions): Suggestion[];
+/**
+ * One rejected capability: a chart whose `fits()` returned a reason.
+ * Surfaced by `explainCapabilityFit` for diagnostic panels and `--doctor` auto-fix.
+ */
+export interface RejectedCapability {
+    component: string;
+    family: ChartCapability["family"];
+    importPath: ChartCapability["importPath"];
+    /** Human-readable reason this chart can't render this profile. */
+    reason: string;
+}
+export interface ExplainCapabilityFitResult {
+    /** Capabilities that fit the profile — full ranked suggestion list. */
+    fitting: Suggestion[];
+    /** Capabilities that did not fit, with their rejection reasons. */
+    rejected: RejectedCapability[];
+    /** The profile that was evaluated against (provided or computed). */
+    profile: ChartDataProfile;
+}
+/**
+ * Like `suggestCharts`, but also returns the capabilities that *didn't* fit
+ * along with their rejection reasons. The single best primitive for:
+ *   • "Why isn't there a pie chart option?" UI surfaces (vizmart V.4)
+ *   • `--doctor` auto-fix loops that need to enumerate alternatives
+ *   • Descriptor authoring — quickly see whose `fits()` is too strict
+ *
+ * Mirrors `suggestCharts` for the fitting side. Rejection enumeration walks
+ * every registered capability whether it fits or not.
+ */
+export declare function explainCapabilityFit(data: ReadonlyArray<Datum> | null | undefined, options?: SuggestChartsOptions): ExplainCapabilityFitResult;
+/**
+ * Score a specific (component, variant) pair against a dataset and (optionally) an intent.
+ * Useful for evaluating a chart a user already chose: "is this a good fit for what they want?"
+ */
+export declare function scoreChart(component: string, data: ReadonlyArray<Datum> | null | undefined, options?: {
+    intent?: IntentId | IntentId[];
+    variantKey?: string;
+    profile?: ChartDataProfile;
+}): Suggestion | {
+    reason: string;
+};

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

@@ -0,0 +1,92 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import { type StretchSuggestion } from "./suggestStretchCharts";
+import type { ChartDataProfile, Suggestion } from "./chartCapabilityTypes";
+import type { IntentId } from "./intents";
+import type { AudienceProfile } from "./audienceProfile";
+/**
+ * One panel in a generated dashboard. Pairs a chart suggestion with the
+ * intent that motivated it — consumers render the suggestion and label it
+ * with the intent so readers know *why* that panel exists.
+ */
+export interface DashboardPanel {
+    /** The intent this panel covers. */
+    intent: IntentId;
+    /** The chart picked for that intent. */
+    suggestion: Suggestion;
+}
+export interface DashboardSuggestion {
+    /** Ordered panels, each covering a distinct intent. */
+    panels: DashboardPanel[];
+    /** Intents the engine actually filled. */
+    intentsCovered: IntentId[];
+    /** Intents the engine couldn't fill from this data. */
+    intentsMissing: IntentId[];
+    /**
+     * Stretch panels — unfamiliar-but-fitting charts the audience could grow
+     * into. Empty when no `audience` is provided or `exposureLevel` is 0.
+     * Render alongside the main panels in a distinct surface so users see
+     * them as opt-in literacy growth, not silent defaults.
+     */
+    stretchPanels: StretchSuggestion[];
+    /** The shape profile (computed once, reused for every panel). */
+    profile: ChartDataProfile;
+}
+export interface SuggestDashboardOptions {
+    /**
+     * Intents to attempt. When omitted, the engine picks a sensible default set
+     * based on the data shape (e.g. if `hasTimeAxis`, include "trend"; if
+     * `categoryCount`, include "rank" and "part-to-whole").
+     */
+    intents?: ReadonlyArray<IntentId>;
+    /** Maximum number of panels. Default 6. */
+    maxPanels?: number;
+    /**
+     * When true (default), prefer not to repeat the same chart family across
+     * panels — produces a more varied dashboard. Set false to allow duplicates.
+     */
+    diversifyByFamily?: boolean;
+    /** Allow only these component names. */
+    allow?: ReadonlyArray<string>;
+    /** Exclude these component names. */
+    deny?: ReadonlyArray<string>;
+    /** Optional pre-built profile (avoids recomputation). */
+    profile?: ChartDataProfile;
+    /** Non-tabular payload — forwarded to profileData. */
+    rawInput?: unknown;
+    /**
+     * Audience profile — applies familiarity overrides and adoption-target bias
+     * to every panel's ranking. When set with `exposureLevel >= 1`, the dashboard
+     * additionally returns `stretchPanels` showing unfamiliar-but-fitting charts.
+     */
+    audience?: AudienceProfile;
+    /** Max stretch panels (default min(maxPanels, 3)). */
+    maxStretchPanels?: number;
+}
+/**
+ * Generate a dashboard: a set of complementary chart panels, each
+ * answering a distinct analytical intent on the same dataset.
+ *
+ * The contract: every panel has a stated `intent` and a suggestion that
+ * fits that intent. The engine diversifies by chart family by default to
+ * avoid "every panel is a bar chart" outcomes. Intents that can't be
+ * filled from the data (e.g. "geo" on row data with no lat/lon) are
+ * reported in `intentsMissing` so consumers can show "no fit for geo
+ * here" rather than silently dropping them.
+ *
+ * Heuristic only — no LLM call. The result is suitable for direct
+ * rendering (each panel's `suggestion.props` is spreadable into the
+ * matching chart) or for piping to an LLM as composition context.
+ *
+ * @example
+ * const { panels } = suggestDashboard(data)
+ * return (
+ *   <Grid>
+ *     {panels.map(({ intent, suggestion }) => (
+ *       <Panel key={intent} title={intent}>
+ *         <DynamicChart component={suggestion.component} props={suggestion.props} />
+ *       </Panel>
+ *     ))}
+ *   </Grid>
+ * )
+ */
+export declare function suggestDashboard(data: ReadonlyArray<Datum> | null | undefined, options?: SuggestDashboardOptions): DashboardSuggestion;

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

@@ -0,0 +1,34 @@
+import type { StreamChartCapability, StreamSchema, StreamSuggestion } from "./streamingTypes";
+import type { IntentId } from "./intents";
+export declare function registerStreamChartCapability(capability: StreamChartCapability): void;
+export declare function unregisterStreamChartCapability(component: string): void;
+export declare function getStreamCapabilities(): ReadonlyArray<StreamChartCapability>;
+export interface SuggestStreamChartsOptions {
+    intent?: IntentId | IntentId[];
+    allow?: ReadonlyArray<string>;
+    deny?: ReadonlyArray<string>;
+    maxResults?: number;
+    minScore?: number;
+    capabilities?: ReadonlyArray<StreamChartCapability>;
+}
+/**
+ * Suggest realtime charts for a schema, ranked by intent.
+ *
+ * Parallel to `suggestCharts` but operates on a `StreamSchema` (fields +
+ * throughput/retention hints) rather than row data. Use for live dashboards,
+ * monitoring views, anywhere events arrive over time rather than as a bounded
+ * table.
+ *
+ * @example
+ * const suggestions = suggestStreamCharts({
+ *   fields: [
+ *     { name: "ts", kind: "date" },
+ *     { name: "latency_ms", kind: "numeric" },
+ *     { name: "endpoint", kind: "categorical" },
+ *   ],
+ *   throughput: "high",
+ *   retention: "windowed",
+ * }, { intent: "trend" })
+ * // → [{ component: "RealtimeHeatmap", ... }, { component: "RealtimeWaterfallChart", ... }]
+ */
+export declare function suggestStreamCharts(schema: StreamSchema, options?: SuggestStreamChartsOptions): StreamSuggestion[];

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

@@ -0,0 +1,60 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { ChartDataProfile, Suggestion } from "./chartCapabilityTypes";
+import type { IntentId } from "./intents";
+import { type AudienceProfile } from "./audienceProfile";
+/**
+ * A "stretch pick" — an unfamiliar-but-fitting chart paired with the
+ * familiar chart it could substitute for. Pairing makes the literacy
+ * suggestion concrete: "instead of BarChart, try BoxPlot here, because…"
+ */
+export interface StretchSuggestion {
+    /** The unfamiliar chart we're suggesting as growth. */
+    suggestion: Suggestion;
+    /**
+     * The familiar chart this stretch could replace for the same intent.
+     * Undefined when the stretch is recommended on its own merits (e.g. a
+     * direct "increase" target with no obvious familiar counterpart).
+     */
+    replacing?: string;
+    /** Human-readable rationale, suitable for verbatim display. */
+    rationale: string;
+    /** Audience familiarity for this chart — the number that made it qualify as a stretch. */
+    familiarity: number;
+}
+export interface SuggestStretchChartsOptions {
+    /** Intent(s) to rank by. When omitted, charts are picked by data fit alone. */
+    intent?: IntentId | IntentId[];
+    /** Required — without an audience profile, the concept of "stretch" doesn't apply. */
+    audience?: AudienceProfile;
+    /** Restrict to these component names. */
+    allow?: ReadonlyArray<string>;
+    /** Exclude these component names. */
+    deny?: ReadonlyArray<string>;
+    /** Max stretch picks to return (default 5). */
+    maxResults?: number;
+    /** Pre-built profile. */
+    profile?: ChartDataProfile;
+    /** Non-tabular payload — forwarded to profileData. */
+    rawInput?: unknown;
+    /**
+     * Only return stretches within this score distance of the top familiar pick
+     * (default 1.5). Tighter values keep the suggestions plausible; wider values
+     * expose more variety.
+     */
+    scoreTolerance?: number;
+}
+/**
+ * Find pairs (familiar, stretch) where the stretch chart fits the data,
+ * has audience familiarity at or below the stretch ceiling, and either:
+ *   • is an `increase` target for this audience, OR
+ *   • scores within `scoreTolerance` of a familiar alternative for the
+ *     same intent.
+ *
+ * Each pair is returned as a StretchSuggestion with `replacing` (the
+ * familiar chart it could substitute for) and a rationale string.
+ *
+ * Heuristic only. Use `audience` with care — without target signals, every
+ * audience-unfamiliar chart becomes a candidate, which can drown the
+ * surface in dubious recommendations.
+ */
+export declare function suggestStretchCharts(data: ReadonlyArray<Datum> | null | undefined, options?: SuggestStretchChartsOptions): StretchSuggestion[];

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

@@ -0,0 +1,22 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import { type ProfileDataOptions } from "./profileData";
+import { type SuggestChartsOptions } from "./suggestCharts";
+import type { ChartDataProfile, Suggestion } from "./chartCapabilityTypes";
+export interface UseChartSuggestionsOptions extends SuggestChartsOptions, ProfileDataOptions {
+}
+export interface UseChartSuggestionsResult {
+    suggestions: ReadonlyArray<Suggestion>;
+    profile: ChartDataProfile;
+}
+/**
+ * Memoized chart suggestion hook.
+ *
+ * Heuristic-only: this hook never calls an LLM. Pair with `useChartInterrogation`
+ * to let an LLM re-rank or narrate the heuristic suggestions.
+ *
+ * @example
+ * const { suggestions } = useChartSuggestions(data, { intent: "trend" })
+ * const top = suggestions[0]
+ * return <DynamicChart component={top.component} props={top.props} />
+ */
+export declare function useChartSuggestions(data: ReadonlyArray<Datum> | null | undefined, options?: UseChartSuggestionsOptions): UseChartSuggestionsResult;

package/dist/components/charts/geo/ChoroplethMap.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const ChoroplethMapCapability: ChartCapability;

package/dist/components/charts/geo/DistanceCartogram.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const DistanceCartogramCapability: ChartCapability;

package/dist/components/charts/geo/FlowMap.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const FlowMapCapability: ChartCapability;

package/dist/components/charts/geo/ProportionalSymbolMap.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const ProportionalSymbolMapCapability: ChartCapability;

package/dist/components/charts/index.d.ts

@@ -27,7 +27,7 @@ export type { ScatterplotMatrixProps } from "./xy/ScatterplotMatrix";
 export { MinimapChart } from "./xy/MinimapChart";
 export type { MinimapChartProps, MinimapConfig } from "./xy/MinimapChart";
 export { QuadrantChart } from "./xy/QuadrantChart";
-export type { QuadrantChartProps, QuadrantsConfig, QuadrantConfig, CenterlineStyle } from "./xy/QuadrantChart";
+export type { QuadrantChartProps, QuadrantsConfig, QuadrantsConfigOverride, QuadrantConfig, CenterlineStyle } from "./xy/QuadrantChart";
 export { MultiAxisLineChart } from "./xy/MultiAxisLineChart";
 export type { MultiAxisLineChartProps, MultiAxisSeriesConfig } from "./xy/MultiAxisLineChart";
 export { CandlestickChart } from "./xy/CandlestickChart";

package/dist/components/charts/network/ChordDiagram.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const ChordDiagramCapability: ChartCapability;

package/dist/components/charts/network/CirclePack.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const CirclePackCapability: ChartCapability;

package/dist/components/charts/network/ForceDirectedGraph.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const ForceDirectedGraphCapability: ChartCapability;

package/dist/components/charts/network/OrbitDiagram.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const OrbitDiagramCapability: ChartCapability;

package/dist/components/charts/network/ProcessSankey.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const ProcessSankeyCapability: ChartCapability;

package/dist/components/charts/network/SankeyDiagram.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const SankeyDiagramCapability: ChartCapability;

package/dist/components/charts/network/TreeDiagram.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const TreeDiagramCapability: ChartCapability;

package/dist/components/charts/network/Treemap.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const TreemapCapability: ChartCapability;

package/dist/components/charts/ordinal/BarChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const BarChartCapability: ChartCapability;

package/dist/components/charts/ordinal/BoxPlot.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const BoxPlotCapability: ChartCapability;

package/dist/components/charts/ordinal/DonutChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const DonutChartCapability: ChartCapability;

package/dist/components/charts/ordinal/DotPlot.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const DotPlotCapability: ChartCapability;

package/dist/components/charts/ordinal/FunnelChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const FunnelChartCapability: ChartCapability;

package/dist/components/charts/ordinal/GaugeChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const GaugeChartCapability: ChartCapability;

package/dist/components/charts/ordinal/GroupedBarChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const GroupedBarChartCapability: ChartCapability;

package/dist/components/charts/ordinal/Histogram.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const HistogramCapability: ChartCapability;

package/dist/components/charts/ordinal/Histogram.d.ts

@@ -23,8 +23,10 @@ export interface HistogramProps<TDatum extends Datum = Datum> extends BaseChartP
     data?: TDatum[];
     /**
      * Field name or function returning the bin label (used when data is
-     * already binned). Ignored when binning raw values.
-     * @default "category"
+     * already binned). For raw-observation data with no category dimension,
+     * the default treats all rows as a single "All" bucket — no need to set
+     * this explicitly.
+     * @default (d) => d.category ?? "All"
      */
     categoryAccessor?: ChartAccessor<TDatum, string>;
     /**

package/dist/components/charts/ordinal/LikertChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const LikertChartCapability: ChartCapability;

package/dist/components/charts/ordinal/LikertChart.d.ts

@@ -62,7 +62,7 @@ export interface LikertChartProps<TDatum extends Datum = Datum> extends BaseChar
      *
      * Odd count → center level is neutral. Even count → clean negative/positive split.
      */
-    levels: string[];
+    levels?: string[];
     /**
      * "horizontal" (default): diverging bar chart centered at 0%.
      * "vertical": stacked 100% bar chart.

package/dist/components/charts/ordinal/LikertChart.defaults.d.ts

@@ -0,0 +1 @@
+export declare const DEFAULT_LIKERT_LEVELS: string[];

package/dist/components/charts/ordinal/PieChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const PieChartCapability: ChartCapability;

package/dist/components/charts/ordinal/RidgelinePlot.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const RidgelinePlotCapability: ChartCapability;

package/dist/components/charts/ordinal/StackedBarChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const StackedBarChartCapability: ChartCapability;

package/dist/components/charts/ordinal/SwarmPlot.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const SwarmPlotCapability: ChartCapability;

package/dist/components/charts/ordinal/SwimlaneChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const SwimlaneChartCapability: ChartCapability;

package/dist/components/charts/ordinal/ViolinPlot.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const ViolinPlotCapability: ChartCapability;

package/dist/components/charts/realtime/RealtimeHeatmap.capability.d.ts

@@ -0,0 +1,2 @@
+import type { StreamChartCapability } from "../../ai/streamingTypes";
+export declare const RealtimeHeatmapCapability: StreamChartCapability;

package/dist/components/charts/realtime/RealtimeHistogram.capability.d.ts

@@ -0,0 +1,2 @@
+import type { StreamChartCapability } from "../../ai/streamingTypes";
+export declare const RealtimeHistogramCapability: StreamChartCapability;

package/dist/components/charts/realtime/RealtimeLineChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { StreamChartCapability } from "../../ai/streamingTypes";
+export declare const RealtimeLineChartCapability: StreamChartCapability;

package/dist/components/charts/realtime/RealtimeSwarmChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { StreamChartCapability } from "../../ai/streamingTypes";
+export declare const RealtimeSwarmChartCapability: StreamChartCapability;

package/dist/components/charts/realtime/RealtimeWaterfallChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { StreamChartCapability } from "../../ai/streamingTypes";
+export declare const RealtimeWaterfallChartCapability: StreamChartCapability;

package/dist/components/charts/realtime/TemporalHistogram.capability.d.ts

@@ -0,0 +1,7 @@
+import type { StreamChartCapability } from "../../ai/streamingTypes";
+/**
+ * TemporalHistogram is the bounded sibling of RealtimeHistogram — same chart
+ * but for static data with a fixed window. For stream selection it competes
+ * with RealtimeHistogram; the choice depends on retention.
+ */
+export declare const TemporalHistogramCapability: StreamChartCapability;

package/dist/components/charts/shared/chartSpecs.d.ts

@@ -1,37 +1,3 @@
-/**
- * Single source of truth for per-chart prop specifications.
- *
- * Three downstream consumers used to maintain their own per-chart entries:
- *   - `ai/schema.json`                                    (LLM tool definitions)
- *   - `src/components/charts/shared/validationMap.ts`     (runtime prop validation)
- *   - `ai/componentMetadata.cjs`                          (category buckets)
- *
- * Today, `ai/schema.json` is generated from this registry — run
- * `npm run docs:chart-specs:schema` to refresh it after editing a spec.
- * `validationMap.ts` and `ai/componentMetadata.cjs` are still hand-edited
- * but are gated for parity by the registry: `check:chart-specs` (run via
- * `npm run check:chart-specs`) regenerates each chart's schema/
- * validation/metadata entries with the pure functions in
- * `scripts/lib/chart-specs-generators.mjs` and fails the build on any
- * drift, including unexpected adds or removes that bypass the registry.
- *
- * Design notes:
- *   - Shared prop bags (common, xyAxis, ordinalAxis) live in `PROP_BAGS` and
- *     are referenced by name in each spec so common surface stays in one place.
- *   - The runtime PropType set ("string" | "number" | "boolean" | "array" |
- *     "object" | "function") is broader than JSON Schema's, but the schema
- *     generator emits whatever types this registry declares — including
- *     "function" inside type unions (canonical entries like
- *     `RidgelinePlot.tooltip: ["function", "object"]` and
- *     `SwimlaneChart.onBrush: "function"` already use this convention; LLMs
- *     read the union and pick a non-function alternative when they can't
- *     supply a function value). For props that are purely callbacks or
- *     escape hatches an LLM cannot meaningfully populate, tag the spec
- *     with `omitFromSchema: true` to keep it in validationMap but out of
- *     schema.json. `description` and `default` annotations surface in
- *     schema.json (and MCP responses) but are dropped from validationMap
- *     (which only reads `type` and `enum`).
- */
 export type PropType = "string" | "number" | "boolean" | "array" | "object" | "function";
 export type DataShape = "array" | "object" | "network" | "realtime" | "none";
 export type ChartCategory = "xy" | "ordinal" | "network" | "geo" | "realtime";

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

@@ -0,0 +1,10 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+/**
+ * AreaChart is treated as a strictly single-series chart. Multi-series areas
+ * are an occlusion nightmare — when the data has 2+ series we subselect the
+ * leading series (largest cumulative y) and surface a caveat so the reader
+ * knows they're looking at one slice, not the whole dataset. For full multi-
+ * series comparison the engine routes callers to LineChart; for two-series
+ * comparison, to DifferenceChart.
+ */
+export declare const AreaChartCapability: ChartCapability;

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

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const BubbleChartCapability: ChartCapability;

package/dist/components/charts/xy/CandlestickChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const CandlestickChartCapability: ChartCapability;

package/dist/components/charts/xy/ConnectedScatterplot.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const ConnectedScatterplotCapability: ChartCapability;

package/dist/components/charts/xy/DifferenceChart.capability.d.ts

@@ -0,0 +1,8 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+/**
+ * DifferenceChart's native shape is two series. When the input has 2+ series
+ * we subselect the top two by total y and pivot them into the wide form the
+ * chart expects — same "narrow the dataset to make the chart honest" pattern
+ * AreaChart uses for its single-series fallback.
+ */
+export declare const DifferenceChartCapability: ChartCapability;

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

@@ -0,0 +1,9 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+/**
+ * Heatmap is a matrix: categorical × categorical (or temporal × categorical),
+ * with a numeric encoded as color. Without two genuine discrete dimensions
+ * for the axes, a heatmap of raw rows is sparse and unreadable. Tuned in
+ * Phase 2.1 after the scorecard surfaced Heatmap winning unsuitable
+ * compare-categories rankings.
+ */
+export declare const HeatmapCapability: ChartCapability;

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

@@ -0,0 +1,9 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+/**
+ * LineChart capability — declares what data shapes LineChart serves well,
+ * what intents it answers, and what variants change those answers.
+ *
+ * Read alongside `LineChart.tsx`; this file is what makes the chart
+ * "self-aware" for suggestion and interrogation flows.
+ */
+export declare const LineChartCapability: ChartCapability;

package/dist/components/charts/xy/MinimapChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const MinimapChartCapability: ChartCapability;

package/dist/components/charts/xy/MultiAxisLineChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const MultiAxisLineChartCapability: ChartCapability;

package/dist/components/charts/xy/QuadrantChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const QuadrantChartCapability: ChartCapability;

package/dist/components/charts/xy/QuadrantChart.d.ts

@@ -30,6 +30,9 @@ export interface QuadrantsConfig {
     bottomRight: QuadrantConfig;
     bottomLeft: QuadrantConfig;
 }
+export type QuadrantsConfigOverride = {
+    [TQuadrant in keyof QuadrantsConfig]?: Partial<QuadrantsConfig[TQuadrant]>;
+};
 /**
  * Centerline style configuration
  */
@@ -55,8 +58,8 @@ export interface QuadrantChartProps<TDatum extends Datum = Datum> extends BaseCh
     xCenter?: number;
     /** Y-coordinate of the horizontal center line. Defaults to midpoint of y domain. */
     yCenter?: number;
-    /** Quadrant configuration: labels and colors for each of the four quadrants */
-    quadrants: QuadrantsConfig;
+    /** Optional quadrant overrides. Omitted quadrants and quadrant fields fall back to built-in defaults. */
+    quadrants?: QuadrantsConfigOverride;
     /** Style for the center lines */
     centerlineStyle?: CenterlineStyle;
     /** Show quadrant labels @default true */

package/dist/components/charts/xy/QuadrantChart.defaults.d.ts

@@ -0,0 +1,2 @@
+import type { QuadrantsConfig } from "./QuadrantChart";
+export declare const DEFAULT_QUADRANTS: QuadrantsConfig;

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

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const ScatterplotCapability: ChartCapability;

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

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const StackedAreaChartCapability: ChartCapability;