semiotic 3.5.2 → 3.5.4

package/dist/components/ThemeProvider.d.ts

@@ -1,10 +1,10 @@
 import * as React from "react";
 import { LIGHT_THEME, DARK_THEME, HIGH_CONTRAST_THEME } from "./store/ThemeStore";
-import type { SemioticTheme } from "./store/ThemeStore";
+import type { SemioticTheme, SemioticThemeUpdate } from "./store/ThemeStore";
 import type { ThemePresetName } from "./semiotic-themes";
 interface ThemeProviderProps {
     /** Theme preset name (e.g. "tufte", "pastels-dark", "bi-tool") or a partial SemioticTheme object. */
-    theme?: ThemePresetName | Partial<SemioticTheme>;
+    theme?: ThemePresetName | SemioticThemeUpdate;
     children: React.ReactNode;
 }
 declare function ThemeProviderWrapper({ theme, children }: ThemeProviderProps): import("react/jsx-runtime").JSX.Element;

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

@@ -13,7 +13,7 @@ export type { ConnectedScatterplotProps } from "./xy/ConnectedScatterplot";
 export { LineChart } from "./xy/LineChart";
 export type { LineChartProps } from "./xy/LineChart";
 export { AreaChart } from "./xy/AreaChart";
-export type { AreaChartProps } from "./xy/AreaChart";
+export type { AreaChartProps, SemanticGradientStop } from "./xy/AreaChart";
 export { DifferenceChart } from "./xy/DifferenceChart";
 export type { DifferenceChartProps } from "./xy/DifferenceChart";
 export { StackedAreaChart } from "./xy/StackedAreaChart";
@@ -88,8 +88,8 @@ export { OrbitDiagram } from "./network/OrbitDiagram";
 export type { OrbitDiagramProps, OrbitNode } from "./network/OrbitDiagram";
 export { RealtimeLineChart } from "./realtime/RealtimeLineChart";
 export type { RealtimeLineChartProps } from "./realtime/RealtimeLineChart";
-export { RealtimeTemporalHistogram, RealtimeHistogram } from "./realtime/RealtimeHistogram";
-export type { RealtimeTemporalHistogramProps, RealtimeHistogramProps } from "./realtime/RealtimeHistogram";
+export { RealtimeTemporalHistogram, RealtimeHistogram, TemporalHistogram } from "./realtime/RealtimeHistogram";
+export type { RealtimeTemporalHistogramProps, RealtimeHistogramProps, TemporalHistogramProps } from "./realtime/RealtimeHistogram";
 export { RealtimeSwarmChart } from "./realtime/RealtimeSwarmChart";
 export type { RealtimeSwarmChartProps } from "./realtime/RealtimeSwarmChart";
 export { RealtimeWaterfallChart } from "./realtime/RealtimeWaterfallChart";

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

@@ -22,6 +22,24 @@ export interface ProcessSankeyProps<TNode extends Datum = Datum, TEdge extends D
     valueAccessor?: ChartAccessor<TEdge, number>;
     startTimeAccessor?: ChartAccessor<TEdge, TimeLike>;
     endTimeAccessor?: ChartAccessor<TEdge, TimeLike>;
+    /**
+     * Optional accessor for the per-edge "system in" time — when
+     * `value` is added to the SOURCE node's mass. Use when the
+     * source node has an intake event distinct from when this edge
+     * departs (e.g. a patient is admitted to the ER at 7pm and
+     * transferred out at 9pm — the ER node carries the patient's
+     * weight between 7pm and 9pm). Without this, the source node's
+     * mass is synthesized as a flat baseline and the band reads as
+     * "always there." Set it and the node band climbs / falls as
+     * units arrive and depart — a true staircase profile.
+     */
+    systemInTimeAccessor?: ChartAccessor<TEdge, TimeLike>;
+    /**
+     * Optional accessor for the per-edge "system out" time — when
+     * `value` is removed from the TARGET node's mass. Mirror of
+     * `systemInTimeAccessor` for the inbound side.
+     */
+    systemOutTimeAccessor?: ChartAccessor<TEdge, TimeLike>;
     /**
      * Accessor for a node's explicit lifetime extent — a `[start, end]`
      * tuple of time-likes. Lane spans
@@ -50,6 +68,10 @@ export interface ProcessSankeyProps<TNode extends Datum = Datum, TEdge extends D
     lifetimeMode?: "full" | "half";
     showLaneRails?: boolean;
     showQualityReadout?: boolean;
+    /** Render the per-band node id label at the band's left edge.
+     *  Default `true`. Set `false` for dense layouts where labels
+     *  would overlap, or when the legend already names every band. */
+    showLabels?: boolean;
     edgeOpacity?: number;
     /** Tooltip content. `false` disables, `true` uses the default,
      *  or pass a `Tooltip(...)` / custom function for full control. */

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

@@ -4,7 +4,7 @@ import type { StreamNetworkFrameProps } from "../../stream/networkTypes";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
-import type { LegendInteractionMode } from "../shared/hooks";
+import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 /**
  * SankeyDiagram component props
  */
@@ -25,6 +25,10 @@ export interface SankeyDiagramProps<TNode extends Datum = Datum, TEdge extends D
     nodeLabel?: ChartAccessor<TNode, string>;
     showLabels?: boolean;
     enableHover?: boolean;
+    /** Show a swatch + label legend. Defaults to `true` when `colorBy` is set. */
+    showLegend?: boolean;
+    /** Legend position. Default `"right"`. */
+    legendPosition?: LegendPosition;
     legendInteraction?: LegendInteractionMode;
     edgeOpacity?: number;
     edgeSort?: (a: any, b: any) => number;

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

@@ -19,6 +19,14 @@ export interface TreemapProps<TNode extends Datum = Datum> extends BaseChartProp
     nodeLabel?: ChartAccessor<TNode, string>;
     padding?: number;
     paddingTop?: number;
+    /**
+     * Per-node style overlay. The returned style is merged on top of
+     * Treemap's built-in colorBy/colorByDepth/default fill, then primitive
+     * props and selection state are applied. Use this for root hiding,
+     * custom borders, or per-depth opacity without re-implementing color
+     * encoding.
+     */
+    nodeStyle?: (d: Datum) => Datum;
     enableHover?: boolean;
     legendInteraction?: LegendInteractionMode;
     tooltip?: TooltipProp;

package/dist/components/charts/network/processSankey/algorithm.d.ts

@@ -11,6 +11,25 @@ export interface ProcessSankeyEdge {
     value: number;
     startTime: number;
     endTime: number;
+    /** Optional: time at which this unit of mass actually "arrived" at
+     *  the SOURCE node (e.g., the hospital admit time for an ER patient
+     *  whose transfer to ICU happens later at `startTime`). Purely a
+     *  rendering hint — the layout/mass profile is unchanged. The
+     *  renderer cuts a rectangular slot out of the source node's band
+     *  from the node's left edge up to the scaled `systemInTime`, with
+     *  height equal to this edge's ribbon thickness. Edges without
+     *  `systemInTime` are drawn as-is. Result: a staircase profile on
+     *  the source side as units enter the system one by one.
+     *  Default: undefined. */
+    systemInTime?: number;
+    /** Optional: time at which this unit of mass leaves the TARGET node
+     *  (e.g., the discharge time for a patient who arrived at the ward
+     *  at `endTime`). Symmetric to `systemInTime`: the renderer cuts a
+     *  rectangular slot out of the target node's band from the scaled
+     *  `systemOutTime` to the node's right edge, with height equal to
+     *  this edge's ribbon thickness. Layout/mass profile unchanged.
+     *  Default: undefined. */
+    systemOutTime?: number;
 }
 export interface ProcessSankeyIssue {
     kind: string;
@@ -98,6 +117,44 @@ export declare function clampTime(t: number, domain: Domain): number;
 export declare function clampSamples(samples: ProcessSankeySample[], domain: Domain): ProcessSankeySample[];
 export declare function attachmentYRange(att: ProcessSankeyAttachment, cl: number, S: number): [number, number];
 export declare function buildBandPath(samples: ProcessSankeySample[], cl: number, S: number, xScale: (t: number) => number, domain: Domain): string | null;
+/**
+ * One 20-px gradient stub at an attachment with `systemInTime` /
+ * `systemOutTime`. Rendered as its own bezier scene-edge with a
+ * horizontal gradient, painted underneath the band. The band
+ * paints with `fill: none` whenever any stubs are present, so the
+ * stub gradients are the only colored regions inside the band's
+ * outline.
+ */
+export interface BandGradientStub {
+    /** Rect path (M-L-L-L-Z). */
+    pathD: string;
+    /** Gradient extent in screen pixels. */
+    x0: number;
+    x1: number;
+    /** Color stops — 0 = transparent end, 1 = band-color end. */
+    from: 0 | 1;
+    to: 0 | 1;
+}
+/**
+ * Build the per-edge 20-px gradient stubs that visualize
+ * `systemInTime` / `systemOutTime` on a node band. Each stub is
+ * a rect on the edge's attachment slot, painted with a horizontal
+ * gradient that fades the band color in (or out) over 20 screen
+ * pixels and saturates through the rest of the rect.
+ *
+ * The rect is clipped to the band's outline bounds (so cutouts don't
+ * spill outside the node shape), but the gradient extent stays at
+ * its natural `[xSysIn - FADE_PX, xSysIn]` / `[xSysOut, xSysOut + FADE_PX]`
+ * range. The canvas renderer uses pad-mode clamping for color stops
+ * outside the rect, so a stub whose fade region falls past the band's
+ * edge still paints solid band-color where it's visible — instead of
+ * collapsing to a degenerate gradient that the renderer would clamp
+ * to transparent.
+ *
+ * Pure rendering hint — layout/mass-profile unchanged. Returns an
+ * empty array when the node has no qualifying edges.
+ */
+export declare function buildBandCutoutsForNode(nodeId: string, edges: ProcessSankeyEdge[], layout: ProcessSankeyLayout, xScale: (t: number) => number, domain: Domain): BandGradientStub[];
 type SlotByNode = Record<string, number>;
 export declare function countCrossings(slotByNode: SlotByNode, edges: ProcessSankeyEdge[]): number;
 export declare function totalEdgeLength(slotByNode: SlotByNode, edges: ProcessSankeyEdge[]): number;

package/dist/components/charts/network/processSankey/buildScenes.d.ts

@@ -14,6 +14,12 @@ export interface ProcessSankeyNormalizedEdge {
     value: number;
     startTime: number;
     endTime: number;
+    /** Optional render-only hint: when this unit of mass actually
+     *  entered the source node. Triggers a cutout in the source band. */
+    systemInTime?: number;
+    /** Optional render-only hint: when this unit of mass left the
+     *  target node. Triggers a cutout in the target band. */
+    systemOutTime?: number;
     __raw?: Datum;
 }
 export interface BuildScenesInput {

package/dist/components/charts/network/processSankey/streamingLayout.d.ts

@@ -3,10 +3,16 @@ import type { BezierCache } from "../../../stream/networkTypes";
 import type { Datum } from "../../shared/datumTypes";
 export interface ProcessSankeyBandSpec {
     id: string;
+    /** Outer band perimeter — same path used for fill and stroke. */
     pathD: string;
     fill: string;
     stroke?: string;
     strokeWidth?: number;
+    /** Per-edge 20-px gradient stubs (band-color fade-in for
+     *  systemInTime, fade-out for systemOutTime). When at least one
+     *  stub is present, the band paints outline-only and the stubs
+     *  are the only colored regions inside the perimeter. */
+    gradientStubs?: BandGradientStub[];
     /** The user's raw node datum, surfaced as `data` in HoverData. */
     rawDatum: Datum;
     /** Pre-computed label x/y for the node band. */
@@ -14,6 +20,13 @@ export interface ProcessSankeyBandSpec {
     labelY: number;
     labelText: string;
 }
+export interface BandGradientStub {
+    pathD: string;
+    x0: number;
+    x1: number;
+    from: 0 | 1;
+    to: 0 | 1;
+}
 export interface ProcessSankeyRibbonSpec {
     id: string;
     pathD: string;

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

@@ -4,6 +4,7 @@ import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
 import type { BaseChartProps } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { RealtimeFrameHandle } from "../../realtime/types";
+import { type GaugeGradientFill } from "../shared/gaugeGradient";
 export interface GaugeThreshold {
     /** Upper bound of this zone (value, not percentage) */
     value: number;
@@ -21,6 +22,15 @@ export interface GaugeChartProps extends BaseChartProps {
     max?: number;
     /** Threshold zones — ordered list of { value, color, label? }. Last threshold's value should equal max. */
     thresholds?: GaugeThreshold[];
+    /**
+     * Arc-length gradient for the gauge band.
+     *
+     * The gradient is sampled along the visible filled arc from sweep start
+     * toward the current value. If `fillZones` is false, the entire arc uses
+     * the gradient. If `fillZones` is true, the unfilled remainder stays on
+     * `backgroundColor`.
+     */
+    gradientFill?: GaugeGradientFill;
     /** Color of the value arc when no thresholds defined (default: theme primary) */
     color?: string;
     /** Background arc color (default: var(--semiotic-grid, #e0e0e0)) */

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

@@ -87,6 +87,8 @@ export interface RealtimeHeatmapProps<TDatum extends Datum = Datum> {
     selection?: SelectionConfig;
     /** Show a loading skeleton placeholder */
     loading?: boolean;
+    /** Custom content rendered in place of the default skeleton while `loading` is true. */
+    loadingContent?: React.ReactNode | false;
     /** Custom content to render when data is empty. Set to `false` to disable empty state. */
     emptyContent?: ReactNode | false;
     /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */

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

@@ -6,6 +6,7 @@ import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Datum } from "../shared/datumTypes";
+export type RealtimeHistogramDirection = "up" | "down";
 export interface RealtimeHistogramProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
@@ -44,6 +45,14 @@ export interface RealtimeHistogramProps<TDatum extends Datum = Datum> {
     timeExtent?: [number, number];
     /** Fixed value domain */
     valueExtent?: [number, number];
+    /**
+     * Direction bars grow from the baseline.
+     * "up" uses the normal y-domain. "down" flips the resolved value
+     * domain so bars grow downward from the top, useful for mirrored
+     * histogram layouts. Explicit valueExtent is reversed.
+     * @default "up"
+     */
+    direction?: RealtimeHistogramDirection;
     /** Extent padding factor */
     extentPadding?: number;
     /**
@@ -103,6 +112,8 @@ export interface RealtimeHistogramProps<TDatum extends Datum = Datum> {
     transition?: TransitionConfig;
     /** Show a loading skeleton placeholder */
     loading?: boolean;
+    /** Custom content rendered in place of the default skeleton while `loading` is true. */
+    loadingContent?: React.ReactNode | false;
     /** Custom content to render when data is empty. Set to `false` to disable empty state. */
     emptyContent?: ReactNode | false;
     /** Brush configuration. `true` defaults to `{ dimension: "x", snap: "bin" }`. */
@@ -173,6 +184,19 @@ export declare const RealtimeHistogram: {
     <TDatum extends Datum = Datum>(props: RealtimeHistogramProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
     displayName?: string;
 };
+export interface TemporalHistogramProps<TDatum extends Datum = Datum> extends Omit<RealtimeHistogramProps<TDatum>, "data" | "windowSize" | "windowMode"> {
+    /** Static data array for a bounded temporal histogram. */
+    data: TDatum[];
+}
+/**
+ * Static-data sibling for temporal histograms. Use this when the data is a
+ * bounded array rather than a ref-driven stream; the realtime push API is not
+ * part of this public surface.
+ */
+export declare function TemporalHistogram<TDatum extends Datum = Datum>(props: TemporalHistogramProps<TDatum>): import("react/jsx-runtime").JSX.Element;
+export declare namespace TemporalHistogram {
+    var displayName: string;
+}
 /** @deprecated Use `RealtimeHistogram` (the canonical public name) instead. The
  *  `RealtimeTemporalHistogram` alias is preserved for back-compat with code
  *  written before the rename and will be removed in a future major version. */

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

@@ -89,6 +89,8 @@ export interface RealtimeLineChartProps<TDatum extends Datum = Datum> {
     selection?: SelectionConfig;
     /** Show a loading skeleton placeholder */
     loading?: boolean;
+    /** Custom content rendered in place of the default skeleton while `loading` is true. */
+    loadingContent?: React.ReactNode | false;
     /** Custom content to render when data is empty. Set to `false` to disable empty state. */
     emptyContent?: ReactNode | false;
     /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */

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

@@ -87,6 +87,8 @@ export interface RealtimeSwarmChartProps<TDatum extends Datum = Datum> {
     selection?: SelectionConfig;
     /** Show a loading skeleton placeholder */
     loading?: boolean;
+    /** Custom content rendered in place of the default skeleton while `loading` is true. */
+    loadingContent?: React.ReactNode | false;
     /** Custom content to render when data is empty. Set to `false` to disable empty state. */
     emptyContent?: ReactNode | false;
     /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */

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

@@ -89,6 +89,8 @@ export interface RealtimeWaterfallChartProps<TDatum extends Datum = Datum> {
     selection?: SelectionConfig;
     /** Show a loading skeleton placeholder */
     loading?: boolean;
+    /** Custom content rendered in place of the default skeleton while `loading` is true. */
+    loadingContent?: React.ReactNode | false;
     /** Custom content to render when data is empty. Set to `false` to disable empty state. */
     emptyContent?: ReactNode | false;
     /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */

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

@@ -0,0 +1,62 @@
+import type { Datum } from "./datumTypes";
+export interface GaugeThresholdLike {
+    value: number;
+    color: string;
+    label?: string;
+}
+export interface GaugeGradientStop {
+    offset: number;
+    color: string;
+}
+export interface GaugeGradientFill {
+    colorStops: GaugeGradientStop[];
+}
+export interface GaugeArcDatum extends Datum {
+    category: string;
+    value: number;
+    _zone?: string;
+    _isFill: boolean;
+    _pctStart?: number;
+    _pct?: number;
+    _roundedEnds?: {
+        start?: boolean;
+        end?: boolean;
+    };
+    _nonInteractive?: boolean;
+    /** Pre-computed gradient colors for the rendered band. Each entry is
+     *  the color for one equal-angle slice across the band's full angular
+     *  span. The wedge renderer reads this and paints the slices itself
+     *  inside a clip-mask shaped like the wedge's rounded outline. */
+    _gradientBand?: {
+        colors: string[];
+    };
+}
+export interface GaugeArcModel {
+    gaugeData: GaugeArcDatum[];
+    pieceStyle: (d: Datum, category?: string) => {
+        fill: string;
+        opacity?: number;
+    };
+    gaugeAnnotations: Datum[];
+}
+interface BuildGaugeArcModelOptions {
+    min: number;
+    max: number;
+    value: number;
+    thresholds?: GaugeThresholdLike[];
+    fillColor?: string;
+    backgroundColor: string;
+    fillZones: boolean;
+    showScaleLabels: boolean;
+    gradientFill?: GaugeGradientFill;
+    gradientSteps?: number;
+}
+/**
+ * Build the synthetic wedge data model used by GaugeChart.
+ *
+ * When `gradientFill` is provided, the visible fill is split into many thin
+ * slices and sampled against the supplied color stops so color changes along
+ * the arc length rather than by threshold zone.
+ */
+export declare function buildGaugeArcModel(options: BuildGaugeArcModelOptions): GaugeArcModel;
+export {};

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

@@ -1,7 +1,7 @@
 import { createLegend } from "./legendUtils";
 import type { SelectionHookResult } from "./selectionUtils";
 import type { OnObservationCallback } from "../../store/ObservationStore";
-import type { Accessor, SelectionConfig, LinkedHoverProp, ChartMode } from "./types";
+import type { Accessor, SelectionConfig, LinkedHoverProp, ChartMode, HoverHighlightMode } from "./types";
 import type { MarginType, PartialMargin } from "../../types/marginType";
 import type { TransitionConfig } from "../../stream/types";
 import type { Datum } from "./datumTypes";
@@ -76,7 +76,7 @@ export declare function useChartSelection({ selection, linkedHover, fallbackFiel
         x: number;
         y: number;
     }) => void;
-    hoverHighlight?: boolean;
+    hoverHighlight?: HoverHighlightMode;
     colorByField?: string;
 }): {
     activeSelectionHook: SelectionHookResult | null;

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

@@ -2,7 +2,7 @@ import type { ReactNode } from "react";
 import type { Datum } from "./datumTypes";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { HoverData } from "../../realtime/types";
-import type { LinkedHoverProp, SelectionConfig } from "./types";
+import type { HoverHighlightMode, LinkedHoverProp, SelectionConfig } from "./types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { AnimateProp } from "../../stream/pipelineTransitionUtils";
 /**
@@ -74,7 +74,7 @@ export declare function buildCustomBehaviorProps(input: {
         x: number;
         y: number;
     }) => void) | undefined;
-    hoverHighlight?: boolean;
+    hoverHighlight?: HoverHighlightMode;
     customHoverBehavior: (d: Datum | null) => void;
     customClickBehavior: (d: Datum | null) => void;
     /**

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

@@ -21,6 +21,17 @@ export interface TooltipFieldConfig {
 export declare function accessorName(acc: string | ((...args: any[]) => any)): string;
 export declare function formatVal(v: unknown): string;
 export declare function resolveValue(d: Datum, acc: string | ((d: Datum) => any)): unknown;
+/**
+ * Build TooltipFieldConfig rows for a `band` prop config so the default
+ * tooltip surfaces envelope values automatically. Reads from the
+ * `bands` array the hover handler synthesizes onto the datum — one
+ * row pair per configured band (low + high). String accessors are
+ * used verbatim as labels; function accessors fall back to "low"/"high".
+ *
+ * Returns an empty array when band is not configured, so the spread at
+ * the call site is a no-op for the common case.
+ */
+export declare function bandTooltipFields(band: unknown, valueFormat?: (v: any, ...rest: any[]) => React.ReactNode): TooltipFieldConfig[];
 /**
  * Build a default tooltipContent function for StreamXYFrame HOCs.
  * Receives HoverData ({ data, time, value, x, y }) and renders

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

@@ -43,6 +43,13 @@ export type LinkedBrushProp = string | {
  * User-provided props always override mode defaults.
  */
 export type ChartMode = "primary" | "context" | "sparkline";
+/**
+ * Hover highlighting mode.
+ * `true` and `"series"` both dim non-hovered series/categories; the string
+ * form is accepted for compatibility with wrapper libraries that expose a
+ * more explicit per-series mode.
+ */
+export type HoverHighlightMode = boolean | "series";
 /**
  * Base props shared across all chart components
  */
@@ -55,7 +62,9 @@ export interface BaseChartProps {
     height?: number;
     /** Margin around the chart. Accepts a number (same on all sides) or an object
      *  with any subset of `top`/`bottom`/`left`/`right`. Missing sides fall back
-     *  to the chart-mode defaults. */
+     *  to the chart-mode defaults. Use `"auto"` or `null` for a side to explicitly
+     *  allow chart auto-reservation, e.g. `margin={{ right: "auto" }}` with a
+     *  right-side legend. */
     margin?: PartialMargin;
     /** Auto-match width to parent container. Default: false */
     responsiveWidth?: boolean;
@@ -78,6 +87,12 @@ export interface BaseChartProps {
     chartId?: string;
     /** Show a loading skeleton placeholder */
     loading?: boolean;
+    /** Custom content to render in place of the default skeleton when `loading` is `true`.
+     *  Sibling to `emptyContent` — use for branded loading states or progress UI.
+     *  When omitted, the built-in shimmer-bar skeleton renders.
+     *  Pass `false` to suppress the loading UI entirely (an outer wrapper's
+     *  loading state takes over). */
+    loadingContent?: React.ReactNode | false;
     /** Custom content to render when data is empty. Set to `false` to disable empty state. */
     emptyContent?: React.ReactNode | false;
     /** Uniform fill color for all data marks. Overrides colorScheme and theme categorical.
@@ -104,7 +119,7 @@ export interface BaseChartProps {
         y: number;
     }) => void;
     /** Dim non-hovered series when hovering a data mark. Requires `colorBy`. */
-    hoverHighlight?: boolean;
+    hoverHighlight?: HoverHighlightMode;
     /** Max pixel distance for hover/click hit testing. Default 30. Increase for sparse charts, decrease for dense ones. */
     hoverRadius?: number;
     /** ID accessor for remove()/update() on XY charts. Extracts a unique identifier from each datum. */

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

@@ -41,7 +41,7 @@ export interface AreaSeriesSetupOptions<TDatum extends Datum = Datum> {
     showPoints: boolean;
     /** Point radius when `showPoints`. @default 3 */
     pointRadius: number;
-    xAccessor: ChartAccessor<TDatum, number>;
+    xAccessor: ChartAccessor<TDatum, number | Date | string>;
     yAccessor: ChartAccessor<TDatum, number>;
     xLabel?: string;
     yLabel?: string;
@@ -52,6 +52,9 @@ export interface AreaSeriesSetupOptions<TDatum extends Datum = Datum> {
     /** Field used to label the series row in the default tooltip.
      *  Typically `areaBy ?? colorBy`. */
     groupField?: Accessor<string> | ChartAccessor<TDatum, string>;
+    /** Optional band prop — when set, the default tooltip surfaces a
+     *  pair of rows per band (low + high). Threaded through verbatim. */
+    band?: unknown;
 }
 export interface AreaSeriesSetupResult<TDatum extends Datum = Datum> {
     /** Flat data array ready for `<StreamXYFrame data={…} />`. Empty

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

@@ -1,7 +1,7 @@
 import type { Datum } from "./datumTypes";
 import { useChartLegendAndMargin, useLegendInteraction, DEFAULT_COLOR } from "./hooks";
 import type { LegendInteractionMode, LegendPosition } from "./hooks";
-import type { Accessor, SelectionConfig, LinkedHoverProp } from "./types";
+import type { Accessor, SelectionConfig, LinkedHoverProp, HoverHighlightMode } from "./types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { PartialMargin } from "../../types/marginType";
 import type { SelectionHookResult } from "./selectionUtils";
@@ -57,9 +57,11 @@ export interface ChartSetupInput {
         y: number;
     }) => void;
     /** Dim non-hovered series on data mark hover */
-    hoverHighlight?: boolean;
+    hoverHighlight?: HoverHighlightMode;
     /** Loading state */
     loading: boolean | undefined;
+    /** Custom content rendered in place of the default skeleton while `loading` is true. */
+    loadingContent?: ReactNode | false;
     /** Empty content override */
     emptyContent?: ReactNode;
     /** Resolved width from useChartMode */

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

@@ -3,7 +3,7 @@ import { useChartMode } from "./hooks";
 import { type ChartSetupResult } from "./useChartSetup";
 import type { ChartMode, SelectionConfig, LinkedHoverProp } from "./types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
-import type { PartialMargin, MarginType } from "../../types/marginType";
+import { type PartialMargin, type MarginType } from "../../types/marginType";
 import type { Datum } from "./datumTypes";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 /**
@@ -64,6 +64,7 @@ interface DataSetupOptions extends ScaffoldOptions {
     }) => void;
     chartId?: string;
     loading?: boolean;
+    loadingContent?: ReactNode | false;
     emptyContent?: ReactNode;
 }
 interface DataSetupResult<TFrameHandle> extends ScaffoldResult<TFrameHandle> {

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

@@ -45,6 +45,8 @@ export interface NetworkChartSetupInput<TNode extends Datum = Datum, TEdge exten
     width: number;
     height: number;
     loading?: boolean;
+    /** Custom content rendered in place of the default skeleton while `loading` is true. */
+    loadingContent?: ReactNode | false;
     emptyContent?: ReactNode | false;
     /**
      * Which array drives the empty-state check. `"edges"` (default)

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

@@ -27,10 +27,17 @@ export declare function SafeRender({ componentName, width, height, children }: S
  */
 export declare function renderEmptyState(data: any[] | undefined | null, width: number, height: number, emptyContent?: React.ReactNode | false): React.ReactElement | null;
 /**
- * Renders a shimmer/skeleton loading placeholder.
- * Returns null when loading is false.
+ * Renders a loading placeholder while `loading` is true.
+ *
+ * When `loadingContent` is provided, it replaces the default shimmer
+ * skeleton — wrapped in the same sized container so the chart still
+ * occupies the slot it would when rendered. Pass `false` to suppress
+ * the skeleton entirely (the early-return becomes null and the chart's
+ * own loading UI takes over).
+ *
+ * Returns null when `loading` is falsy.
  */
-export declare function renderLoadingState(loading: boolean | undefined, width: number, height: number): React.ReactElement | null;
+export declare function renderLoadingState(loading: boolean | undefined, width: number, height: number, loadingContent?: React.ReactNode | false): React.ReactElement | null;
 /** Warn if a string accessor isn't found in the first data element */
 export declare function warnMissingField(componentName: string, data: any[] | undefined, accessorName: string, accessorValue: any): void;
 /** Warn if data looks like the wrong shape for this chart type */