semiotic 3.5.3 → 3.6.0

package/dist/components/server/staticLegend.d.ts

@@ -7,6 +7,21 @@
 import * as React from "react";
 import type { SemioticTheme } from "../store/ThemeStore";
 import type { Datum } from "../charts/shared/datumTypes";
+import type { GradientLegendConfig, LegendGroup, LegendLayout } from "../types/legendTypes";
+interface LegendItemLayout {
+    category: string;
+    width: number;
+    x: number;
+    y: number;
+}
+interface StaticLegendMetrics {
+    items: LegendItemLayout[];
+    width: number;
+    height: number;
+    swatchSize: number;
+    labelOffset: number;
+    swatchRadius: number;
+}
 export interface StaticLegendConfig {
     /** Category labels to show in legend */
     categories: string[];
@@ -28,13 +43,33 @@ export interface StaticLegendConfig {
     };
     /** Title presence (affects top-position offset) */
     hasTitle?: boolean;
+    /** SSR legend layout controls */
+    legendLayout?: LegendLayout;
+    /** Optional id namespace used for generated SVG ids */
+    idPrefix?: string;
+}
+export interface StaticLegendGroupsConfig extends Omit<StaticLegendConfig, "categories" | "colorScheme"> {
+    legendGroups: LegendGroup[];
+}
+export interface StaticGradientLegendConfig extends Omit<StaticLegendConfig, "categories" | "colorScheme"> {
+    gradient: GradientLegendConfig;
 }
+export declare function measureStaticLegend(config: StaticLegendConfig): Omit<StaticLegendMetrics, "items" | "labelOffset" | "swatchRadius">;
+export declare function measureStaticLegendGroups(config: StaticLegendGroupsConfig): Omit<StaticLegendMetrics, "items" | "labelOffset" | "swatchRadius">;
+export declare function measureStaticGradientLegend(config: StaticGradientLegendConfig): {
+    width: number;
+    height: number;
+    swatchSize: number;
+};
 /**
  * Render a static legend as SVG elements.
  * Returns null if no categories to show.
  */
 export declare function renderStaticLegend(config: StaticLegendConfig): React.ReactNode;
+export declare function renderStaticLegendGroups(config: StaticLegendGroupsConfig): React.ReactNode;
+export declare function renderStaticGradientLegend(config: StaticGradientLegendConfig): React.ReactNode;
 /**
  * Extract unique categories from data using an accessor.
  */
 export declare function extractCategories(data: any[], accessor: string | ((d: Datum) => string) | undefined): string[];
+export {};

package/dist/components/store/ThemeStore.d.ts

@@ -34,6 +34,8 @@ export interface SemioticTheme {
         textSecondary: string;
         grid: string;
         border: string;
+        /** Separator/border color for cell-like marks such as treemap tiles and heatmap cells. Falls back to `border`. */
+        cellBorder?: string;
         focus?: string;
         /** Linked hover/selection highlight color */
         selection?: string;

package/dist/components/store/useChartFocus.d.ts

@@ -0,0 +1,43 @@
+import type { ChartObservation } from "./ObservationStore";
+import type { InterrogationFocus } from "./useChartInterrogation";
+export interface UseChartFocusOptions {
+    /** Limit attention to a specific chart instance. Required when the page has more than one. */
+    chartId?: string;
+    /**
+     * Which observation types count as "focused." Default is hover + click +
+     * selection — anything that signals user attention. Set to ["click"] for
+     * sticky-focus UIs where hover doesn't change the AI's reference point.
+     */
+    types?: ChartObservation["type"][];
+}
+/**
+ * Convenience hook: returns the latest `InterrogationFocus` for use with
+ * `useChartInterrogation`'s `focus` option. Internally subscribes to the
+ * observation store and converts the latest matching observation into the
+ * focus shape.
+ *
+ * Pair with `<Chart onObservation={…} chartId="myChart" />` and an
+ * `<ObservationProvider>` ancestor.
+ *
+ * Returns `null` when no qualifying observation has fired yet.
+ *
+ * @example
+ * function ChartWithChat({ data }) {
+ *   const focus = useChartFocus({ chartId: "sales" })
+ *   const { ask, history, annotations } = useChartInterrogation({
+ *     data,
+ *     focus,                    // ← latest hovered/clicked datum threads in
+ *     onQuery: async (q, ctx) => {
+ *       // ctx.focus is the same `focus` value passed above
+ *       return askLLM({ question: q, focus: ctx.focus, summary: ctx.summary })
+ *     },
+ *   })
+ *   return (
+ *     <>
+ *       <LineChart data={data} chartId="sales" annotations={annotations} />
+ *       <YourChatUI history={history} onAsk={ask} />
+ *     </>
+ *   )
+ * }
+ */
+export declare function useChartFocus(options?: UseChartFocusOptions): InterrogationFocus | null;

package/dist/components/store/useChartInterrogation.d.ts

@@ -0,0 +1,141 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import { type DataSummary } from "../data/DataSummarizer";
+import type { ChartDataProfile, Suggestion } from "../ai/chartCapabilityTypes";
+import type { IntentId } from "../ai/intents";
+/**
+ * Identifies a single point of interest on the chart — typically the datum
+ * the user is currently hovering, clicked, or otherwise focused on. When
+ * provided, the LLM gets the explicit signal that the user is asking
+ * "about *this specific point*" rather than the chart at large.
+ */
+export interface InterrogationFocus {
+    /** The row the user is focused on. */
+    datum: Datum;
+    /** Pixel x coordinate, when known. Useful for anchoring response annotations. */
+    x?: number;
+    /** Pixel y coordinate, when known. */
+    y?: number;
+    /** Optional source label — "hover" / "click" / "selection". Surfaces in the LLM prompt. */
+    source?: "hover" | "click" | "selection" | "manual";
+}
+export interface InterrogationContext {
+    /** The data extracted from the chart (or whatever caller passed in). */
+    data: ReadonlyArray<Datum>;
+    /** Statistical summary, ready to send to an LLM. */
+    summary: DataSummary;
+    /** Shape profile — present when `includeProfile` or `includeSuggestions` is enabled. */
+    profile?: ChartDataProfile;
+    /** Heuristic chart suggestions — present when `includeSuggestions` is enabled. */
+    suggestions?: ReadonlyArray<Suggestion>;
+    /** Optional caller-supplied chart component name (e.g. "LineChart"). */
+    componentName?: string;
+    /** Optional caller-supplied chart props (accessor names, scales, etc.). */
+    props?: Record<string, unknown>;
+    /**
+     * The current focused datum — what the user is interactively pointing at.
+     * Lets the LLM tailor responses to a specific point ("why is *this* one
+     * higher than the rest?") and to anchor visual responses (callouts,
+     * comments) back at the same coordinates.
+     */
+    focus?: InterrogationFocus;
+}
+export interface InterrogationResult {
+    /** Natural-language answer to display to the user. */
+    answer: string;
+    /** Optional Semiotic annotations to overlay on the chart. */
+    annotations?: ReadonlyArray<Datum>;
+}
+export type InterrogationQuery = (query: string, context: InterrogationContext) => Promise<InterrogationResult>;
+export interface InterrogationMessage {
+    role: "user" | "assistant";
+    text: string;
+}
+export interface UseChartInterrogationOptions {
+    /** Data backing the chart. Use whatever shape the chart consumes (rows, nodes, etc.). */
+    data: ReadonlyArray<Datum> | null | undefined;
+    /** Async handler — typically calls your LLM with the query + summary. */
+    onQuery: InterrogationQuery;
+    /** Annotations to seed the merged set (e.g. existing chart annotations). */
+    initialAnnotations?: ReadonlyArray<Datum>;
+    /** Optional context passed through to onQuery for richer prompts. */
+    componentName?: string;
+    /** Optional context passed through to onQuery. */
+    props?: Record<string, unknown>;
+    /**
+     * Include the shape `profile` in the interrogation context. Required to let an LLM
+     * reason about candidate axes, distinct counts, hierarchy/network/geo detection, etc.
+     */
+    includeProfile?: boolean;
+    /**
+     * Include heuristic chart `suggestions` in the interrogation context. Implies `includeProfile`.
+     * Lets an LLM answer "would another chart show this better?" without re-deriving rules.
+     */
+    includeSuggestions?: boolean;
+    /** When `includeSuggestions` is true, rank by this intent. */
+    suggestionsIntent?: IntentId | IntentId[];
+    /** When `includeSuggestions` is true, cap the suggestion list. Default 5. */
+    suggestionsMax?: number;
+    /**
+     * The point on the chart the user is currently focused on. Forwarded to
+     * onQuery so an LLM can answer "about this specific datum" rather than
+     * "about the chart in general." Typically wired from a chart's
+     * `onObservation` callback or the convenience `useChartFocus` hook.
+     */
+    focus?: InterrogationFocus | null;
+}
+export interface UseChartInterrogationResult {
+    /** Ask a question. Updates history, annotations, loading, and error. */
+    ask: (query: string) => Promise<void>;
+    /**
+     * Append an AI-initiated message to the transcript without a user query.
+     *
+     * Use for proactive narration — a streaming watcher that detected an
+     * anomaly, a background analysis that surfaced an insight, an LLM that
+     * decided to volunteer information mid-session. Synchronous; no `onQuery`
+     * call. Annotations merge into the chart's `annotations` array like
+     * any other AI response.
+     *
+     * @example
+     * announce({
+     *   text: "Spike detected at 14:32 — 3.2σ above rolling mean.",
+     *   annotations: [{ type: "callout", ts: now, value: 850, note: "Slow query?" }],
+     * })
+     */
+    announce: (message: {
+        text: string;
+        annotations?: ReadonlyArray<Datum>;
+    }) => void;
+    /** Conversation history, oldest first. */
+    history: ReadonlyArray<InterrogationMessage>;
+    /** Statistical summary of the data — memoized, safe to pass to a prompt. */
+    summary: DataSummary;
+    /** Merged annotations: initial + latest AI response. Pass to the chart's `annotations` prop. */
+    annotations: ReadonlyArray<Datum>;
+    /** True while onQuery is in flight. */
+    loading: boolean;
+    /** Last error from onQuery, if any. */
+    error: Error | null;
+    /** Clear history, AI annotations, and error. */
+    reset: () => void;
+}
+/**
+ * Headless interrogation hook — a sibling to `useChartObserver`.
+ *
+ * Generates an LLM-friendly statistical summary of your chart's data, runs queries through
+ * a caller-supplied `onQuery`, and merges any annotations the response returns so the chart
+ * can highlight what the model is talking about.
+ *
+ * The hook owns no UI. Render whatever input/transcript surface fits your product.
+ *
+ * @example
+ * const { ask, history, annotations, loading } = useChartInterrogation({
+ *   data,
+ *   onQuery: async (q, ctx) => {
+ *     const res = await fetch("/api/chat", { method: "POST", body: JSON.stringify({ q, summary: ctx.summary }) })
+ *     return res.json()
+ *   },
+ * })
+ *
+ * <LineChart data={data} annotations={annotations} ... />
+ */
+export declare function useChartInterrogation(options: UseChartInterrogationOptions): UseChartInterrogationResult;

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

@@ -1,7 +1,7 @@
 import type { Datum } from "../charts/shared/datumTypes";
 import type { ReactNode } from "react";
 import type { NetworkLabel } from "./networkTypes";
-import type { LegendGroup, GradientLegendConfig } from "../types/legendTypes";
+import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../types/legendTypes";
 type AnnotationAnchorNode = {
     type: string;
     datum: Datum | null;
@@ -43,6 +43,7 @@ export interface NetworkSVGOverlayProps {
     legendHighlightedCategory?: string | null;
     legendIsolatedCategories?: Set<string>;
     legendPosition?: "right" | "left" | "top" | "bottom";
+    legendLayout?: LegendLayout;
     /** User-provided SVG elements on top */
     foregroundGraphics?: ReactNode;
     /** Scene nodes for annotation positioning */

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

@@ -3,7 +3,7 @@ import * as React from "react";
 import type { OrdinalScales } from "./ordinalTypes";
 import type { AnnotationContext } from "../realtime/types";
 import type { ReactNode } from "react";
-import type { LegendGroup, GradientLegendConfig } from "../types/legendTypes";
+import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../types/legendTypes";
 import { type AxisExtentMode } from "../charts/shared/axisExtent";
 interface OrdinalSVGOverlayProps {
     width: number;
@@ -49,6 +49,7 @@ interface OrdinalSVGOverlayProps {
     legendHighlightedCategory?: string | null;
     legendIsolatedCategories?: Set<string>;
     legendPosition?: "right" | "left" | "top" | "bottom";
+    legendLayout?: LegendLayout;
     foregroundGraphics?: ReactNode;
     annotations?: Datum[];
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;

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

@@ -2,7 +2,7 @@ import type { Datum } from "../charts/shared/datumTypes";
 import type { StreamScales, MarginalGraphicsConfig, XYFrameAxisConfig } from "./types";
 import type { AnnotationContext } from "../realtime/types";
 import type { ReactNode } from "react";
-import type { LegendGroup, GradientLegendConfig } from "../types/legendTypes";
+import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../types/legendTypes";
 export type AxisConfig = XYFrameAxisConfig;
 interface SVGOverlayProps {
     width: number;
@@ -51,6 +51,7 @@ interface SVGOverlayProps {
     legendIsolatedCategories?: Set<string>;
     /** Legend position relative to chart area */
     legendPosition?: "right" | "left" | "top" | "bottom";
+    legendLayout?: LegendLayout;
     foregroundGraphics?: ReactNode;
     marginalGraphics?: MarginalGraphicsConfig;
     xValues?: number[];

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

@@ -13,7 +13,7 @@ export declare function xySceneNodeToSVG(node: SceneNode, i: number, idPrefix?:
 export declare function networkSceneNodeToSVG(node: NetworkSceneNode, i: number): React.ReactNode;
 export declare function networkSceneEdgeToSVG(edge: NetworkSceneEdge, i: number): React.ReactNode;
 export declare function networkLabelToSVG(label: NetworkLabel, i: number): React.ReactNode;
-export declare function ordinalSceneNodeToSVG(node: OrdinalSceneNode, i: number): React.ReactNode;
+export declare function ordinalSceneNodeToSVG(node: OrdinalSceneNode, i: number, idPrefix?: string): React.ReactNode;
 export declare function geoSceneNodeToSVG(node: GeoSceneNode, i: number): React.ReactNode;
 /**
  * Returns true when running in a true server/Node.js context where

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

@@ -1,6 +1,6 @@
 import type { ReactNode } from "react";
 import type { GeoProjection, GeoPath, GeoPermissibleObjects } from "d3-geo";
-import type { GradientLegendConfig, LegendGroup } from "../types/legendTypes";
+import type { GradientLegendConfig, LegendGroup, LegendLayout } from "../types/legendTypes";
 import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, SceneDatum, PointSceneNode, ThemeSemanticColors } from "./types";
 import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { HoverAnnotationConfig, HoverData } from "../realtime/types";
@@ -191,6 +191,7 @@ export interface StreamGeoFrameProps<T = Datum> {
         gradient: GradientLegendConfig;
     };
     legendPosition?: "right" | "left" | "top" | "bottom";
+    legendLayout?: LegendLayout;
     legendHoverBehavior?: (item: {
         label: string;
     } | null) => void;

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

@@ -19,6 +19,7 @@ export interface HoverPointerCoords {
     clientX: number;
     clientY: number;
 }
+export declare function normalizeHoverDatum(rawDatum: any): any;
 /**
  * Build a HoverData object from a raw datum and pixel coordinates.
  * The raw datum is preserved as `hover.data` for tooltip / callback

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

@@ -1,5 +1,5 @@
 import type { ReactNode } from "react";
-import type { LegendGroup, GradientLegendConfig } from "../types/legendTypes";
+import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../types/legendTypes";
 export interface LegendRenderConfig {
     legend: ReactNode | {
         legendGroups: LegendGroup[];
@@ -15,6 +15,7 @@ export interface LegendRenderConfig {
         left: number;
     };
     legendPosition?: "right" | "left" | "top" | "bottom";
+    legendLayout?: LegendLayout;
     title?: string | ReactNode;
     legendHoverBehavior?: (item: {
         label: string;

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

@@ -1,7 +1,7 @@
 import type { ReactNode } from "react";
 import type { OnObservationCallback } from "../store/ObservationStore";
 import type { HoverData, AnnotationContext } from "../realtime/types";
-import type { LegendGroup } from "../types/legendTypes";
+import type { LegendGroup, LegendLayout } from "../types/legendTypes";
 import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors, SceneDatum } from "./types";
 import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { Datum } from "../charts/shared/datumTypes";
@@ -523,6 +523,7 @@ export interface StreamNetworkFrameProps<T = Datum> {
         legendGroups: LegendGroup[];
     };
     legendPosition?: "right" | "left" | "top" | "bottom";
+    legendLayout?: LegendLayout;
     legendHoverBehavior?: (item: {
         label: string;
     } | null) => void;

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

@@ -3,7 +3,7 @@ import type { ScaleLinear, ScaleBand } from "d3-scale";
 import type { WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext } from "../realtime/types";
 import type { Style, SceneDatum, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors } from "./types";
 import type { AnimateProp } from "./pipelineTransitionUtils";
-import type { LegendGroup } from "../types/legendTypes";
+import type { GradientLegendConfig, LegendGroup, LegendLayout } from "../types/legendTypes";
 import type { Datum } from "../charts/shared/datumTypes";
 export type OrdinalChartType = "bar" | "clusterbar" | "point" | "swarm" | "pie" | "donut" | "boxplot" | "violin" | "histogram" | "ridgeline" | "timeline" | "funnel" | "bar-funnel" | "swimlane" | "custom";
 export interface OrdinalScales {
@@ -37,6 +37,19 @@ export interface WedgeSceneNode {
         start?: boolean;
         end?: boolean;
     };
+    /** Render the wedge's interior as N equal angular slices, each filled
+     *  with the corresponding color from `colors`. The wedge's own shape
+     *  (incl. `cornerRadius` + `roundedEnds`) is used as a clip mask so
+     *  only the slice geometry shows through the rounded outline. Used by
+     *  GaugeChart's gradient-fill mode: the band reads as one continuous
+     *  rounded arc with a gradient sampled along its length, without any
+     *  individual slice (which would be far too narrow to host its own
+     *  rounded corners) needing to round. Slices are an internal
+     *  rendering detail — they do not appear as separate scene nodes,
+     *  participate in hit testing, or transition independently. */
+    _gradientBand?: {
+        colors: string[];
+    };
     style: Style;
     datum: SceneDatum;
     category?: string;
@@ -373,7 +386,7 @@ export interface StreamOrdinalFrameProps<T = Datum> {
     legend?: ReactNode | {
         legendGroups: LegendGroup[];
     } | {
-        gradient: import("../types/legendTypes").GradientLegendConfig;
+        gradient: GradientLegendConfig;
     };
     legendHoverBehavior?: (item: {
         label: string;
@@ -384,6 +397,7 @@ export interface StreamOrdinalFrameProps<T = Datum> {
     legendHighlightedCategory?: string | null;
     legendIsolatedCategories?: Set<string>;
     legendPosition?: "right" | "left" | "top" | "bottom";
+    legendLayout?: LegendLayout;
     /** Accessor used to report the current legend category domain in push mode. */
     legendCategoryAccessor?: string | ((d: T) => string);
     /** Fires when the current legend category domain changes after scene rebuilds. */

package/dist/components/stream/renderers/wedgePathBuilder.d.ts

@@ -54,3 +54,34 @@ export interface AnnularPathOptions {
  *     unrounded so the path stays well-formed.
  */
 export declare function annularSectorPath(opts: AnnularPathOptions): string;
+/**
+ * Build the clip outline + slice paths for a gauge gradient band.
+ *
+ * The band is rendered as one rounded annular sector used as a clip
+ * mask, with N unrounded slice sectors painted inside. Each slice
+ * extends from its own start angle out to the band's full end angle,
+ * so adjacent colors overpaint each other's trailing edge — eliminates
+ * subpixel AA gaps between slices without an explicit overlap epsilon
+ * and means the staircase reveals one color per `sliceAngle` of arc.
+ *
+ * Canvas and SVG renderers both consume this: canvas builds Path2D
+ * objects from the strings, SVG drops them straight into `<path d="…"/>`.
+ */
+export interface GaugeGradientGeometryOptions {
+    innerRadius: number;
+    outerRadius: number;
+    startAngle: number;
+    endAngle: number;
+    cornerRadius?: number;
+    roundStart?: boolean;
+    roundEnd?: boolean;
+    colors: string[];
+}
+export interface GaugeGradientGeometry {
+    clipPath: string;
+    slices: {
+        d: string;
+        color: string;
+    }[];
+}
+export declare function buildGaugeGradientGeometry(opts: GaugeGradientGeometryOptions): GaugeGradientGeometry;

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

@@ -1,7 +1,7 @@
 import type { ReactNode } from "react";
 import type { ScaleLinear } from "d3-scale";
 import type { AnimateProp } from "./pipelineTransitionUtils";
-import type { LegendGroup, GradientLegendConfig } from "../types/legendTypes";
+import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../types/legendTypes";
 import type { ArrowOfTime, WindowMode, LineStyle, BarStyle, WaterfallStyle, SwarmStyle, HoverAnnotationConfig, HoverData, AnnotationContext, AnnotationAnchorMode } from "../realtime/types";
 import type { Datum } from "../charts/shared/datumTypes";
 import type { CoercibleNumber } from "./accessorUtils";
@@ -651,6 +651,7 @@ export interface StreamXYFrameProps<T = Datum> {
     legendHighlightedCategory?: string | null;
     legendIsolatedCategories?: Set<string>;
     legendPosition?: "right" | "left" | "top" | "bottom";
+    legendLayout?: LegendLayout;
     /** Accessor used to report the current legend category domain in push mode. */
     legendCategoryAccessor?: string | ((d: T) => string);
     /** Fires when the current legend category domain changes after scene rebuilds. */

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

@@ -31,6 +31,20 @@ export declare function isLegendConfig(value: unknown): value is {
 export declare function isGradientLegendConfig(value: unknown): value is {
     gradient: GradientLegendConfig;
 };
+export interface LegendLayout {
+    /** Horizontal alignment for top/bottom legends within the plot width */
+    align?: "start" | "center" | "end" | "left" | "right";
+    /** Width/height of categorical swatches in pixels */
+    swatchSize?: number;
+    /** Gap between a swatch and its label in pixels */
+    labelGap?: number;
+    /** Gap between horizontal legend items in pixels */
+    itemGap?: number;
+    /** Vertical row height for stacked legend items in pixels */
+    rowHeight?: number;
+    /** Override the alignment width used for top/bottom legends */
+    maxWidth?: number;
+}
 export interface LegendProps {
     legendGroups?: LegendGroup[];
     customClickBehavior?: (item: LegendItem) => void;
@@ -46,4 +60,5 @@ export interface LegendProps {
     height?: number;
     orientation?: string;
     position?: "left" | "right";
+    legendLayout?: LegendLayout;
 }

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

@@ -8,8 +8,22 @@ export interface MarginType {
     left: number;
     right: number;
 }
+/** Public margin side value. Numbers pin a side to an exact pixel value.
+ *  `"auto"` and `null` explicitly leave that side to chart defaults plus
+ *  auto-reservation such as legends. */
+export type MarginSide = number | "auto" | null | undefined;
 /** Public-API margin shape. Users can pass any subset of sides (`{ left: 120 }`
  *  for wide y-axis labels is a common pattern) or a single number as shorthand
- *  for "same on all sides". The frame fills missing sides from the chart-mode
- *  defaults before handing a fully-resolved `MarginType` to the layout code. */
-export type PartialMargin = number | Partial<MarginType>;
+ *  for "same on all sides". Pass a side as `"auto"` or `null` to explicitly
+ *  opt back into chart auto-reservation for that side, e.g.
+ *  `{ right: "auto" }` with a right-side legend. The frame fills missing/auto
+ *  sides from chart-mode defaults before handing a fully-resolved
+ *  `MarginType` to the layout code. */
+export type PartialMargin = number | {
+    top?: MarginSide;
+    right?: MarginSide;
+    bottom?: MarginSide;
+    left?: MarginSide;
+};
+export declare function resolveMarginSide(value: MarginSide, fallback: number): number;
+export declare function normalizePartialMargin(m: PartialMargin | undefined): Partial<MarginType> | undefined;