semiotic 3.7.4 → 3.8.0

package/dist/components/MobileStandardControls.d.ts

@@ -0,0 +1,68 @@
+import * as React from "react";
+import type { MobileStandardControlKind, MobileStandardControlsMode } from "./charts/shared/types";
+export type { MobileStandardControlKind, MobileStandardControlsMode };
+export type MobileStandardControlRequest = MobileStandardControlsMode;
+export interface MobileStandardControlLegendItem {
+    id: string;
+    label?: React.ReactNode;
+    color?: string;
+    active?: boolean;
+    disabled?: boolean;
+}
+export interface MobileStandardBrushControls {
+    label?: React.ReactNode;
+    value?: [number, number];
+    domain?: [number, number];
+    step?: number;
+    disabled?: boolean;
+    formatValue?: (value: number) => React.ReactNode;
+    onChange?: (value: [number, number]) => void;
+    onClear?: () => void;
+}
+export interface MobileStandardZoomControls {
+    label?: React.ReactNode;
+    disabled?: boolean;
+    onZoomIn?: () => void;
+    onZoomOut?: () => void;
+    onReset?: () => void;
+}
+export interface MobileStandardLegendControls {
+    label?: React.ReactNode;
+    items?: MobileStandardControlLegendItem[];
+    disabled?: boolean;
+    onToggle?: (id: string, active: boolean) => void;
+    onShowAll?: () => void;
+    onHideAll?: () => void;
+}
+export interface MobileStandardControlsProps {
+    controls?: MobileStandardControlRequest;
+    targetSize?: number;
+    compact?: boolean;
+    className?: string;
+    style?: React.CSSProperties;
+    ariaLabel?: string;
+    brush?: MobileStandardBrushControls;
+    zoom?: MobileStandardZoomControls;
+    legend?: MobileStandardLegendControls;
+}
+export interface UseMobileRangeControlsOptions {
+    domain: [number, number];
+    initialValue?: [number, number];
+    step?: number;
+    minSpan?: number;
+    label?: React.ReactNode;
+    formatValue?: (value: number) => React.ReactNode;
+    onChange?: (value: [number, number]) => void;
+}
+export interface UseMobileRangeControlsResult {
+    value: [number, number];
+    setValue: (value: [number, number]) => void;
+    xExtent: [number, number];
+    brush: MobileStandardBrushControls;
+    zoom: MobileStandardZoomControls;
+}
+export declare function clampMobileRange(value: [number, number], domain: [number, number], minSpan?: number): [number, number];
+export declare function zoomMobileRange(value: [number, number], domain: [number, number], direction: "in" | "out", step?: number, minSpan?: number): [number, number];
+export declare function useMobileRangeControls(options: UseMobileRangeControlsOptions): UseMobileRangeControlsResult;
+export declare function MobileStandardControls({ controls, targetSize, compact, className, style, ariaLabel, brush, zoom, legend, }: MobileStandardControlsProps): React.JSX.Element | null;
+export default MobileStandardControls;

package/dist/components/SmallMultipleChart.d.ts

@@ -0,0 +1,84 @@
+import * as React from "react";
+import type { ChartMode, LinkedHoverProp, MobileInteractionProp, SelectionConfig } from "./charts/shared/types";
+import type { MobileVisualizationContract } from "./charts/shared/auditMobileVisualization";
+import { type LinkedChartsProps } from "./LinkedCharts";
+export type SmallMultipleExtent = [number, number];
+export interface SmallMultipleItem<TDatum = unknown> {
+    id: string;
+    title?: React.ReactNode;
+    subtitle?: React.ReactNode;
+    summary?: React.ReactNode;
+    data?: readonly TDatum[];
+    extent?: SmallMultipleExtent;
+}
+export interface SmallMultipleSharedExtent {
+    xExtent?: SmallMultipleExtent;
+    yExtent?: SmallMultipleExtent;
+    valueExtent?: SmallMultipleExtent;
+}
+export interface SmallMultipleRenderContext<TItem> {
+    item: TItem;
+    index: number;
+    count: number;
+    chartProps: Record<string, unknown>;
+    sharedExtent: SmallMultipleSharedExtent;
+}
+export interface SmallMultipleChartProps<TItem extends SmallMultipleItem = SmallMultipleItem> {
+    items?: readonly TItem[];
+    children: React.ReactNode | ((item: TItem, context: SmallMultipleRenderContext<TItem>) => React.ReactNode);
+    /** Columns above the tablet breakpoint. Default 3. */
+    columns?: number;
+    /** Columns between mobile and tablet breakpoints. Default 2. */
+    tabletColumns?: number;
+    /** Columns at the mobile breakpoint. Default 1. */
+    mobileColumns?: number;
+    /** Mobile breakpoint used by the generated CSS. Default 480. */
+    mobileBreakpoint?: number;
+    /** Tablet breakpoint used by the generated CSS. Default 860. */
+    tabletBreakpoint?: number;
+    /** Gap between panels. Default 12. */
+    gap?: number;
+    /** Default child chart mode. Default "mobile". */
+    mode?: ChartMode;
+    /** Default child chart height. Default 220. */
+    chartHeight?: number;
+    /** Share y/value extents across panels. Pass an object for explicit extents. Default true. */
+    sharedExtent?: boolean | SmallMultipleSharedExtent;
+    /** Field or function used to compute the shared y/value extent when sharedExtent is true. */
+    valueAccessor?: string | ((datum: unknown) => unknown);
+    /** Field or function used to read each item's data array. Default "data". */
+    dataAccessor?: string | ((item: TItem) => readonly unknown[] | undefined);
+    /** Extent prop names injected into child charts. Default ["yExtent", "valueExtent"]. */
+    extentProps?: string[];
+    /** Linked hover emitted by each panel. */
+    linkedHover?: LinkedHoverProp;
+    /** Selection consumed by each panel. */
+    selection?: SelectionConfig;
+    /** Convenience config for linked hover + selection using the same name/fields. */
+    linkedBy?: string[] | {
+        name?: string;
+        fields?: string[];
+    };
+    /** Whether to provide a LinkedCharts wrapper for linked panels. Default "auto". */
+    linkProvider?: boolean | "auto";
+    /** LinkedCharts selection seed config when SmallMultipleChart provides the wrapper. */
+    selections?: LinkedChartsProps["selections"];
+    /** Unified legend setting passed to LinkedCharts when SmallMultipleChart provides the wrapper. Default false. */
+    showLegend?: LinkedChartsProps["showLegend"];
+    legendPosition?: LinkedChartsProps["legendPosition"];
+    legendInteraction?: LinkedChartsProps["legendInteraction"];
+    legendSelectionName?: LinkedChartsProps["legendSelectionName"];
+    legendField?: LinkedChartsProps["legendField"];
+    /** Touch-first mobile interaction policy injected into child charts. Default true. */
+    mobileInteraction?: MobileInteractionProp;
+    /** Semantic mobile contract injected into child charts. */
+    mobileSemantics?: MobileVisualizationContract;
+    /** Consistent labeling posture. Panel labels are outside the plot by default. */
+    labelMode?: "panel" | "direct" | "legend";
+    /** Additional defaults injected into each child chart when the child has not already declared them. */
+    chartDefaults?: Record<string, unknown>;
+    className?: string;
+    style?: React.CSSProperties;
+}
+export declare function SmallMultipleChart<TItem extends SmallMultipleItem = SmallMultipleItem>({ items, children, columns, tabletColumns, mobileColumns, mobileBreakpoint, tabletBreakpoint, gap, mode, chartHeight, sharedExtent, valueAccessor, dataAccessor, extentProps, linkedHover, selection, linkedBy, linkProvider, selections, showLegend, legendPosition, legendInteraction, legendSelectionName, legendField, mobileInteraction, mobileSemantics, labelMode, chartDefaults, className, style, }: SmallMultipleChartProps<TItem>): React.JSX.Element;
+export default SmallMultipleChart;

package/dist/components/Tooltip/FlippingTooltip.d.ts

@@ -22,6 +22,27 @@ interface FlippingTooltipProps {
     /** z-index (default 1) */
     zIndex?: number;
 }
+/**
+ * True when the tooltip content's root element looks like the
+ * consumer is handling chrome themselves. Signals (any one is enough):
+ *
+ *   1. Component-type `ownsChrome: true` (for components that paint
+ *      chrome internally — avoids double-wrap).
+ *   2. An inline `background` / `backgroundColor` on `style`.
+ *   3. `data-semiotic-tooltip-chrome` for CSS-class-only chrome
+ *      where the background is defined outside the React element.
+ *
+ * **`.semiotic-tooltip` class alone is NOT ownership.** Charts and
+ * examples repeatedly return `<div className="semiotic-tooltip">…</div>`
+ * without a background (expecting a global CSS rule or theme var that
+ * is missing or transparent). Treating the class as ownership was the
+ * transparent-tooltip regression. Shared helpers that truly own chrome
+ * pass `defaultTooltipStyle` (inline background) or `ownsChrome`.
+ *
+ * When none of these fire, `FlippingTooltip` paints `defaultTooltipStyle`
+ * on its wrapper so the tooltip can never come out chrome-less.
+ */
+export declare function hasOwnChrome(node: React.ReactNode): boolean;
 /**
  * Viewport-aware tooltip wrapper that flips horizontally and vertically
  * when the tooltip would overflow the chart container.

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

@@ -0,0 +1,16 @@
+import * as React from "react";
+import type { Datum } from "../charts/shared/datumTypes";
+import type { ChartRecipe as ChartRecipeDefinition } from "./chartRecipes";
+export type ChartRecipe = ChartRecipeDefinition;
+export interface ChartRecipeProps extends Datum {
+    recipeId?: string;
+    recipe?: ChartRecipeDefinition;
+    layoutConfig?: Record<string, unknown>;
+    chartId?: string;
+    className?: string;
+}
+/**
+ * Render a registered recipe config. Portable recipes resolve their layout by
+ * registered id; local recipes may carry the function in their manifest.
+ */
+export declare function ChartRecipe(props: ChartRecipeProps): React.ReactElement;

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

@@ -0,0 +1,15 @@
+import * as React from "react";
+import type { IntentManifest } from "./intentManifest";
+export interface IntentMarkProps {
+    manifest: IntentManifest;
+    label?: string;
+    className?: string;
+    /** Show the human summary above the JSON contract. Default true. */
+    showSummary?: boolean;
+}
+/**
+ * Visible, inspectable IDID contract for docs and review surfaces. Native
+ * `<details>` keeps the first version keyboard- and screen-reader-operable
+ * without introducing a popover dependency.
+ */
+export declare function IntentMark({ manifest, label, className, showSummary, }: IntentMarkProps): React.JSX.Element;

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

@@ -38,6 +38,13 @@ 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";
+import { GaltonBoardChartCapability } from "../charts/physics/GaltonBoardChart.capability";
+import { EventDropChartCapability } from "../charts/physics/EventDropChart.capability";
+import { PhysicsPileChartCapability } from "../charts/physics/PhysicsPileChart.capability";
+import { CollisionSwarmChartCapability } from "../charts/physics/CollisionSwarmChart.capability";
+import { PhysicalFlowChartCapability } from "../charts/physics/PhysicalFlowChart.capability";
+import { ProcessFlowChartCapability } from "../charts/physics/ProcessFlowChart.capability";
+import { GauntletChartCapability } from "../charts/physics/GauntletChart.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.
@@ -52,4 +59,4 @@ export declare function unregisterChartCapability(component: string): void;
 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, };
+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, GaltonBoardChartCapability, EventDropChartCapability, PhysicsPileChartCapability, CollisionSwarmChartCapability, PhysicalFlowChartCapability, ProcessFlowChartCapability, GauntletChartCapability, };

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

@@ -1,6 +1,7 @@
 import type { Datum } from "../charts/shared/datumTypes";
 import type { DataSummary } from "../data/DataSummarizer";
 import type { IntentId } from "./intents";
+import type { ChartRecipe, ChartRecipeFrameFamily, MobileDesignDefinition } from "./chartRecipes";
 import type { ScaleFitFn, QualityFitFn, ScaleBand, CardinalityBand, EffectiveScale } from "./dataScaleProfile";
 /**
  * Chart family — high-level taxonomy used for filtering and intent matching.
@@ -9,7 +10,13 @@ export type ChartFamily = "time-series" | "categorical" | "distribution" | "rela
 /**
  * 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";
+export type ChartImportPath = "semiotic/xy" | "semiotic/ordinal" | "semiotic/network" | "semiotic/geo" | "semiotic/realtime" | "semiotic/physics" | "semiotic/value" | "semiotic/ai" | "semiotic";
+export type ChartCandidateKind = "built-in" | "recipe";
+export interface WhyCustomExplanation {
+    defaultAlternative?: string;
+    reason: string;
+    tradeoff?: string;
+}
 /**
  * Familiarity/accuracy/precision rubric (1-5 each).
  * Familiarity = how well-known the chart is to a general audience.
@@ -73,6 +80,22 @@ export interface ChartDataProfile extends DataSummary {
     hasRepeatedX: boolean;
     /** True when the primary x candidate is monotonic. */
     monotonicX: boolean;
+    /**
+     * How amenable the (x × series) grid is to stacking. Only populated when both
+     * a primary x and series field exist. A stacked area/bar reads as bands only
+     * when series share x columns; when most columns hold a single series, the
+     * renderer zero-fills the gaps and every layer collapses into an isolated
+     * triangular spike instead of a continuous band. Capabilities gate on this to
+     * decline stacking on near-unique x (flat record lists, scatter-shaped data).
+     */
+    stackability?: {
+        /** Mean distinct series present per x value. ~1 → spiky; ~seriesCount → dense. */
+        seriesPerX: number;
+        /** Fraction of x columns where 2+ series coexist (where stacking is visible). */
+        multiSeriesFraction: number;
+        /** Number of distinct x columns considered. */
+        xColumns: number;
+    };
     /** True when there is at least one date-typed candidate. */
     hasTimeAxis: boolean;
     /**
@@ -145,7 +168,13 @@ export type FitResult = null | string;
  */
 export interface ChartCapability {
     component: string;
+    /** Human-facing name. `component` remains the stable lookup id. */
+    displayName?: string;
+    /** Omitted descriptors are treated as built-ins for backward compatibility. */
+    candidateKind?: ChartCandidateKind;
     family: ChartFamily;
+    /** The frame/runtime substrate behind a registered recipe. */
+    renderingFamily?: ChartRecipeFrameFamily;
     importPath: ChartImportPath;
     /** Base rubric, before variant/profile adjustments. */
     rubric: ChartRubric;
@@ -189,6 +218,14 @@ export interface ChartCapability {
      * low completeness on the primary y field.
      */
     qualityFit?: QualityFitFn;
+    /** Mobile design contract for custom recipes and advanced built-ins. */
+    mobile?: MobileDesignDefinition;
+    /** Present only on recipe-derived capabilities. */
+    recipe?: ChartRecipe;
+    /** Positive reception/design rationale appended to suggestion explanations. */
+    positiveRationale?: ReadonlyArray<string>;
+    /** Why this candidate justifies leaving the built-in catalog. */
+    whyCustom?: WhyCustomExplanation;
 }
 /**
  * Effective scale range tag on a suggestion. Lets callers group suggestions
@@ -211,6 +248,9 @@ export interface SuggestionScaleRange {
  */
 export interface Suggestion {
     component: string;
+    displayName: string;
+    candidateKind: ChartCandidateKind;
+    recipeId?: string;
     family: ChartFamily;
     importPath: ChartImportPath;
     variant?: ChartVariant;
@@ -226,6 +266,7 @@ export interface Suggestion {
     caveats: ReadonlyArray<string>;
     /** Ready-to-spread props. */
     props: Record<string, unknown>;
+    whyCustom?: WhyCustomExplanation;
     /**
      * Scale tag — present when scale/quality information is available, either
      * through declared `DataScaleProfile` or through the measured profile.

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

@@ -0,0 +1,91 @@
+/**
+ * Read-only Chart Clinic inspection contract.
+ *
+ * This is intentionally an inspection surface, not an authoring or repair
+ * loop. It composes the existing validation, diagnostic, serializable-config,
+ * render-evidence, and revision contracts into one deterministic report that
+ * a docs page, CLI, MCP tool, or application can present without mutating the
+ * caller's chart props or store.
+ */
+import type { Datum } from "../charts/shared/datumTypes";
+import type { ChartCategory } from "../charts/shared/chartSpecs";
+import type { Diagnosis } from "../charts/shared/diagnoseConfig";
+import type { ValidationResult } from "../charts/shared/validateProps";
+import type { ChartConfig } from "../export/chartConfig";
+import type { RenderEvidence } from "../server/renderEvidence";
+import type { RevisionSet } from "../stream/pipelineUpdateContract";
+import { type RenderFn } from "./generativeChart";
+/**
+ * Inspection is a reproducible projection, not an authored export. The
+ * timestamp in a ChartConfig is meaningful when a user saves a config but is
+ * volatile noise in an identical read-only Clinic report.
+ */
+export type ChartClinicConfig = Omit<ChartConfig, "createdAt">;
+export interface ChartClinicRevisionInput {
+    /** Latest revision snapshot reported by a retained chart/store host. */
+    readonly revisions: RevisionSet;
+    /** Optional snapshot that a host says it has already consumed. */
+    readonly consumed?: Partial<RevisionSet>;
+}
+export interface ChartClinicInput {
+    readonly component: string;
+    readonly props?: Datum;
+    /** Omit this for a static configuration with no retained runtime host. */
+    readonly revision?: ChartClinicRevisionInput;
+}
+export interface ChartClinicOptions {
+    /**
+     * Optional static renderer. Supplying it attaches SVG-derived evidence; it
+     * never changes the inspected configuration and render failures are exposed
+     * as a stable code rather than rethrowing arbitrary error text.
+     */
+    readonly render?: RenderFn;
+}
+export interface ChartClinicSceneSummary {
+    readonly status: RenderEvidence["status"];
+    readonly frameType: RenderEvidence["frameType"];
+    readonly markCount: number;
+    readonly markCountByType: Readonly<Record<string, number>>;
+    readonly xDomain?: readonly [number, number];
+    readonly yDomain?: readonly [number, number];
+    readonly categories?: readonly string[];
+    readonly nodeCount?: number;
+    readonly edgeCount?: number;
+}
+export interface ChartClinicRevisionStatus {
+    readonly state: "not-observed" | "fully-consumed" | "pending-consumption";
+    readonly revisions?: RevisionSet;
+    readonly consumed?: Partial<RevisionSet>;
+    /** Revision counters newer than the supplied consumption snapshot. */
+    readonly pending: readonly (keyof RevisionSet)[];
+}
+export interface ChartClinicBundleGuidance {
+    readonly category?: ChartCategory;
+    /** Prefer the pilot's explicit module when available, otherwise a family facade. */
+    readonly recommendedImport?: string;
+    readonly serverImport?: "semiotic/server";
+    readonly docsRoute?: string;
+    readonly note: string;
+}
+export interface ChartClinicReport {
+    readonly mode: "read-only";
+    readonly component: string;
+    /** A serializable configuration projected from the inspected props. */
+    readonly normalizedConfig?: ChartClinicConfig;
+    readonly validation: ValidationResult;
+    readonly diagnostics: readonly Diagnosis[];
+    readonly evidence?: RenderEvidence;
+    readonly scene?: ChartClinicSceneSummary;
+    readonly revisions: ChartClinicRevisionStatus;
+    readonly bundle: ChartClinicBundleGuidance;
+    /** Stable reasons; arbitrary renderer exception messages are never copied here. */
+    readonly reasons: readonly string[];
+    readonly ok: boolean;
+}
+/**
+ * Inspect a chart proposal without changing it. Automatic repair is explicitly
+ * disabled even when data is present; the beta reports diagnostics and bundle
+ * guidance only. Pass a renderer when the caller can safely obtain static SVG
+ * evidence in its own runtime.
+ */
+export declare function inspectChart(input: ChartClinicInput, options?: ChartClinicOptions): ChartClinicReport;

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

@@ -0,0 +1,14 @@
+import type { ChartCapability } from "./chartCapabilityTypes";
+import type { ChartRecipe, CustomLayoutFunction } from "./chartRecipes";
+/** Register or replace a named recipe and its capability adapter. */
+export declare function registerChartRecipe(recipe: ChartRecipe): void;
+export declare function unregisterChartRecipe(recipeId: string): void;
+export declare function getChartRecipe(recipeId: string): ChartRecipe | undefined;
+export declare function listChartRecipes(): ChartRecipe[];
+export declare function getRegisteredRecipeCapabilities(): ReadonlyArray<ChartCapability>;
+export declare function hasRegisteredRecipeCapabilities(): boolean;
+/** Register a known runtime implementation used by portable recipe manifests. */
+export declare function registerRecipeLayout(layoutId: string, layout: CustomLayoutFunction): void;
+export declare function unregisterRecipeLayout(layoutId: string): void;
+export declare function getRecipeLayout(layoutId: string): CustomLayoutFunction | undefined;
+export declare function resolveChartRecipe(value: unknown): ChartRecipe | undefined;