nuxt-charts 2.2.1 → 3.0.0-beta.0

package/dist/runtime/types/shared.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Shared config types, preserved from `nuxt-charts` v2.
+ *
+ * Kept structurally identical to the v2 (`vue-chrts`) types so existing
+ * templates keep type-checking after the engine swap to `vccs`. Types that
+ * were Unovis-specific and have no `vccs` analog are retained as inert
+ * shapes and marked `@deprecated` — passing them is a no-op, not an error.
+ */
+/**
+ * Describes one category / series in a chart's legend: its label, colour, and
+ * visibility. Keyed by the data property it represents in a `categories` record.
+ */
+export interface BulletLegendItemInterface {
+    name: string | number;
+    /** Series colour. An array is accepted for v2 compatibility; the first entry is used. */
+    color?: string | Array<string>;
+    className?: string;
+    inactive?: boolean;
+    hidden?: boolean;
+    pointer?: boolean;
+    /**
+     * Id of the y-axis this series is plotted against. Series sharing an id share
+     * a scale. Defaults to the primary axis, so charts that omit it are unchanged.
+     */
+    yAxis?: AxisId;
+}
+/** Identifies one y-axis. Series and axis configs are matched by this value. */
+export type AxisId = string | number;
+/**
+ * Configuration for one y-axis in a multi-axis chart, keyed by {@link AxisId}
+ * in the `yAxes` prop.
+ */
+export interface YAxisConfig extends AxisConfig {
+    /** Which side of the plot area the axis is drawn on. Default `left`. */
+    orientation?: "left" | "right";
+    /** Axis label. */
+    label?: string;
+    /** Fixed domain as `[min, max]`. */
+    domain?: [number | undefined, number | undefined];
+    /** Desired number of ticks. */
+    numTicks?: number;
+    /** Formats this axis' ticks. */
+    formatter?: axisFormatter;
+    /** Hide the axis while still plotting its series. */
+    hide?: boolean;
+}
+/**
+ * Formats an axis tick value into a display string.
+ * Mapped onto the `vccs` axis `tickFormatter(value, index)`.
+ */
+export type axisFormatter = ((tick: number, i?: number, ticks?: number[]) => string) | ((tick: Date, i?: number, ticks?: Date[]) => string);
+/**
+ * Fine-grained axis appearance options.
+ *
+ * Only the fields with a `vccs` equivalent are applied (`tickFormatter`,
+ * `tickLine`). The remaining text-layout fields are retained for v2
+ * template compatibility and currently have no effect.
+ */
+export interface AxisConfig {
+    tickLine?: boolean;
+    tickFormat?: axisFormatter;
+    /** Tick label font size, applied as the tick `<text>` `font-size`. */
+    tickTextFontSize?: string;
+    /** Tick label colour, applied as the tick `<text>` `fill`. */
+    tickTextColor?: string;
+    /** Tick label horizontal anchor (`left`→`start`, `right`→`end`, `center`→`middle`). */
+    tickTextAlign?: "left" | "right" | "center";
+    /** @deprecated No `vccs` equivalent; retained for v2 compatibility. */
+    tickTextAngle?: number;
+    /** @deprecated No `vccs` equivalent; retained for v2 compatibility. */
+    tickTextWidth?: number;
+    /** @deprecated No `vccs` equivalent; retained for v2 compatibility. */
+    tickTextFitMode?: "wrap" | "trim";
+    /** @deprecated No `vccs` equivalent; retained for v2 compatibility. */
+    tickTextTrimType?: "start" | "middle" | "end";
+    /** @deprecated No `vccs` equivalent; retained for v2 compatibility. */
+    tickTextForceWordBreak?: boolean;
+    /** @deprecated No `vccs` equivalent; retained for v2 compatibility. */
+    tickTextSeparator?: string | readonly string[];
+    minMaxTicksOnly?: boolean;
+    /** @deprecated No `vccs` equivalent; retained for v2 compatibility. */
+    minMaxTicksOnlyShowGridLines?: boolean;
+    tickValues?: readonly number[] | readonly Date[];
+}
+/**
+ * Tooltip behaviour options. Mapped onto `vccs` `<Tooltip>`.
+ */
+export interface TooltipConfig {
+    /** Hide delay in milliseconds. */
+    hideDelay?: number;
+    /** Show delay in milliseconds. */
+    showDelay?: number;
+    /** If `true`, the tooltip follows the cursor. */
+    followCursor?: boolean;
+}
+/**
+ * @deprecated Unovis-only. `vccs` has no crosshair primitive; retained as an
+ * inert type so v2 templates keep type-checking. Has no effect.
+ */
+export interface CrosshairConfig<T> {
+    color?: string | ((d: T, i: number) => string | undefined);
+    strokeColor?: string;
+    strokeWidth?: number;
+    template?: (d: T) => string;
+}
+/**
+ * @deprecated Unovis-only. `vccs` has no custom marker primitive; retained as
+ * an inert type so v2 templates keep type-checking. Has no effect.
+ */
+/** Per-series marker (dot) options. */
+export type MarkerSeriesConfig = {
+    type?: "circle" | "square" | "triangle" | "diamond";
+    size?: number;
+    strokeWidth?: number;
+    color?: string;
+    strokeColor?: string;
+};
+/**
+ * Marker configuration keyed by series (category) key, matching the v2 docs
+ * usage: `:marker-config="{ desktop: { type: 'circle', size: 6 } }"`.
+ *
+ * The legacy `{ id, config }` wrapper shape is still accepted for back-compat;
+ * the adapter reads `config` when present, else treats the value as the flat map.
+ */
+export type MarkerConfig = Record<string, MarkerSeriesConfig> | {
+    id?: string;
+    config: Record<string, MarkerSeriesConfig>;
+};
+/** Per-side chart padding in pixels. */
+export interface ChartPadding {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/**
+ * Per-chart appearance overrides. Every field maps onto a `--vc-*` CSS token
+ * (`runtime/assets/theme.css` for SVG + tokens, `runtime/assets/components.css`
+ * for HTML chrome) written inline on the chart root. Set `theme.legend.size` to
+ * scale legend, axis ticks, axis titles, and radar labels together.
+ */
+export interface ChartTheme {
+    /** Grid + axis (domain) lines. */
+    grid?: {
+        /** Line colour. Token: `--vc-grid-color`. */
+        color?: string;
+        /** SVG dash pattern, e.g. `"3 3"` (solid: `"0"`). Token: `--vc-grid-dash`. */
+        dash?: string;
+        /** Line width in pixels. Token: `--vc-grid-width`. */
+        width?: number;
+    };
+    /** Axis ticks + labels. */
+    axis?: {
+        /** Tick label colour. Token: `--vc-tick-color`. */
+        tickColor?: string;
+        /** Tick label size. Defaults to `--vc-legend-size`. Token: `--vc-tick-size`. */
+        tickSize?: string;
+        /** Tick label weight. Token: `--vc-tick-weight`. */
+        tickWeight?: number | string;
+        /** Axis title colour. Token: `--vc-axis-label-color`. */
+        labelColor?: string;
+        /** Axis title size. Defaults to `--vc-legend-size`. Token: `--vc-axis-label-size`. */
+        labelSize?: string;
+        /** Domain (axis) line colour. Token: `--vc-axis-line-color`. */
+        lineColor?: string;
+    };
+    /** Legend text + spacing. */
+    legend?: {
+        /** Text colour. Token: `--vc-legend-color`. */
+        color?: string;
+        /** Font size for legend and all chart labels. Token: `--vc-legend-size`. */
+        size?: string;
+        /** Font weight. Token: `--vc-legend-weight`. */
+        weight?: number | string;
+        /** Gap between items, e.g. `"0.75rem"`. Token: `--vc-legend-gap`. */
+        gap?: string;
+        /** Gap between plot and legend, e.g. `"0.75rem"`. Token: `--vc-legend-inset`. */
+        inset?: string;
+    };
+    /** Hover cursor (the band/rect behind the hovered point). */
+    hover?: {
+        /** Fill colour. Token: `--vc-hover-fill`. */
+        fill?: string;
+        /** Stroke colour. Token: `--vc-hover-stroke`. */
+        stroke?: string;
+        /** Corner radius in pixels. Token: `--vc-hover-radius`. */
+        radius?: number;
+        /** Set `false` to hide the hover cursor entirely (tooltip still shows). */
+        visible?: boolean;
+    };
+    /** Tooltip container. */
+    tooltip?: {
+        /** Background colour. Token: `--vc-tooltip-bg`. */
+        bg?: string;
+        /** Text colour. Token: `--vc-tooltip-fg`. */
+        fg?: string;
+        /** Border colour. Token: `--vc-tooltip-border`. */
+        border?: string;
+        /** Corner radius, e.g. `"0.5rem"`. Token: `--vc-tooltip-radius`. */
+        radius?: string;
+    };
+}

package/dist/runtime/types.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Public type surface for `nuxt-charts`.
+ *
+ * Re-exported via the module's `addImportsSources` so these auto-import in
+ * consumer code (`from "nuxt-charts/types"`).
+ */
+export type * from "./types/shared";
+export type * from "./types/charts";

package/dist/runtime/utils/axis.d.ts

@@ -0,0 +1,132 @@
+import type { AxisConfig, AxisId, axisFormatter, YAxisConfig } from "../types/shared.js";
+import { type SeriesDescriptor } from "./categories.js";
+/** `vccs` axis `tickFormatter` signature. */
+export type VccsTickFormatter = (value: unknown, index: number) => string;
+/** A `vccs` axis tick value (numbers for value axes, strings for category axes). */
+export type VccsAxisTick = number | string;
+/** `vccs` axis `interval` values we use. */
+export type VccsAxisInterval = number | "preserveStartEnd";
+/**
+ * Axis slot sizing tuned for gallery / dashboard charts. vccs defaults (Y width
+ * 60, X height 30, tickMargin 2) leave the value Y-axis too far from the plot
+ * and X tick labels hugging the bottom edge.
+ */
+export declare const AXIS_SLOT: {
+    readonly numericYWidth: 40;
+    readonly categoryYWidth: 72;
+    readonly titledYWidth: 72;
+    readonly defaultXHeight: 38;
+    readonly titledXHeight: 52;
+};
+export declare function resolveYAxisWidth(options: {
+    hasTitle: boolean;
+    isCategoryAxis: boolean;
+}): number;
+export declare function resolveXAxisHeight(options: {
+    hasTitle: boolean;
+}): number;
+/**
+ * Gap (in px) between an axis line and its tick labels, passed to the native
+ * `vccs` `tickMargin` prop. vccs positions labels in SVG space from this value
+ * (X labels hang below the axis, Y labels are right-aligned toward the plot and
+ * vertically centred on each gridline), so we let it own positioning instead of
+ * nudging with CSS transforms. vccs's own default (2) leaves labels cramped.
+ */
+export declare const AXIS_TICK_MARGIN: {
+    /** Between the x-axis line and the tick label below it. */
+    readonly x: 8;
+    /** Between the plot edge and the right-aligned y tick label. */
+    readonly y: 8;
+};
+/**
+ * The native `vccs` `tick` prop value for an axis. vccs accepts `true` (default
+ * SVG presentation, with per-orientation `textAnchor` / `verticalAnchor`) or an
+ * object of SVG attrs that override those defaults. We only ever override the
+ * horizontal anchor (from `AxisConfig.tickTextAlign`); colour / size / weight
+ * are themed via CSS variables on `.v-charts-cartesian-axis-tick-value`.
+ */
+export declare function toTickProp(tick: Record<string, unknown> | undefined): true | {
+    textAnchor: string;
+};
+/**
+ * Resolved subset of `vccs` axis props derived from the v2 config API. Centralises
+ * the mapping for the props that *do* have a `vccs` equivalent (explicit ticks,
+ * min/max-only) so both axes in {@link CartesianFrame} stay consistent.
+ */
+export interface ResolvedAxisProps {
+    /** Explicit tick values (`xExplicitTicks` / `tickValues`). */
+    ticks: VccsAxisTick[] | undefined;
+    /** Tick thinning. `preserveStartEnd` approximates v2 `minMaxTicksOnly`. */
+    interval: VccsAxisInterval | undefined;
+    /** Per-tick SVG presentation attributes (colour / font-size) from `AxisConfig`. */
+    tick: Record<string, unknown> | undefined;
+}
+/**
+ * Build `vccs` axis presentation props from the v2 explicit-tick props and
+ * {@link AxisConfig}. `explicitTicks` is the standalone `xExplicitTicks` /
+ * `yExplicitTicks` prop; `AxisConfig.tickValues` is the equivalent nested form
+ * and takes precedence when both are set.
+ *
+ * `minMaxTicksOnly` (top-level or in `AxisConfig`) maps onto
+ * `interval="preserveStartEnd"`, the closest `vccs` analog of "first & last only".
+ */
+export declare function resolveAxisProps(explicitTicks: ReadonlyArray<number | string | Date> | undefined, config: AxisConfig | undefined, minMaxTicksOnly: boolean | undefined): ResolvedAxisProps;
+/** One resolved y-axis, ready to render as a `vccs` `<YAxis>`. */
+export interface ResolvedYAxis extends ResolvedAxisProps {
+    id: AxisId;
+    orientation: "left" | "right";
+    label: string | undefined;
+    domain: readonly [number, number] | undefined;
+    tickCount: number | undefined;
+    tickFormatter: VccsTickFormatter | undefined;
+    tickLine: boolean;
+    hide: boolean;
+}
+/**
+ * Build the list of y-axes to render.
+ *
+ * The primary axis (id {@link PRIMARY_Y_AXIS_ID}) is always present and driven
+ * by the top-level `yLabel` / `yDomain` / `yAxisConfig` props, so single-axis
+ * charts are unaffected. Each additional id referenced by a series' `yAxis` — or
+ * declared in `yAxes` — becomes its own axis, falling back to the primary axis'
+ * settings for anything its {@link YAxisConfig} leaves unset.
+ *
+ * Axes are emitted in `yAxes` declaration order (primary first) so the render
+ * order is stable and predictable when several share a side.
+ */
+export declare function resolveYAxes(options: {
+    series: readonly SeriesDescriptor[];
+    yAxes: Record<AxisId, YAxisConfig> | undefined;
+    primary: Omit<ResolvedYAxis, "id" | "orientation">;
+    minMaxTicksOnly: boolean | undefined;
+}): ResolvedYAxis[];
+/**
+ * Adapt a v2 {@link axisFormatter} to the `vccs` `tickFormatter(value, index)`
+ * signature. Returns `undefined` when no formatter is supplied so the axis
+ * falls back to `vccs`'s default rendering.
+ *
+ * The v2 union accepts either a number- or Date-typed tick; both are forwarded
+ * as-is, matching how Unovis called them.
+ */
+export declare function toTickFormatter(formatter: axisFormatter | undefined): VccsTickFormatter | undefined;
+/** `vccs` axis title config (string labels default to the axis centre and overlap ticks). */
+export type VccsAxisLabel = {
+    value: string;
+    position: "insideBottom" | "insideLeft" | "insideRight";
+    offset: number;
+    angle?: number;
+    textAnchor?: "start" | "middle" | "end";
+    fill: string;
+    fontSize: string;
+    fontWeight: string | number;
+};
+/**
+ * Build a positioned axis title for `vccs` cartesian axes.
+ *
+ * Plain strings land at the axis midpoint; `insideBottom` / `insideLeft` keep
+ * titles clear of tick values and inside the reserved axis slot.
+ */
+export declare function toAxisLabel(text: string | undefined, position: "insideBottom" | "insideLeft" | "insideRight", options?: {
+    angle?: number;
+    offset?: number;
+}): VccsAxisLabel | undefined;

package/dist/runtime/utils/axis.js

@@ -0,0 +1,93 @@
+import { PRIMARY_Y_AXIS_ID, normalizeAxisId } from "./categories.js";
+import { toAxisDomain } from "./style.js";
+export const AXIS_SLOT = {
+  numericYWidth: 40,
+  categoryYWidth: 72,
+  titledYWidth: 72,
+  defaultXHeight: 38,
+  titledXHeight: 52
+};
+export function resolveYAxisWidth(options) {
+  if (options.hasTitle) return AXIS_SLOT.titledYWidth;
+  if (options.isCategoryAxis) return AXIS_SLOT.categoryYWidth;
+  return AXIS_SLOT.numericYWidth;
+}
+export function resolveXAxisHeight(options) {
+  return options.hasTitle ? AXIS_SLOT.titledXHeight : AXIS_SLOT.defaultXHeight;
+}
+export const AXIS_TICK_MARGIN = {
+  /** Between the x-axis line and the tick label below it. */
+  x: 8,
+  /** Between the plot edge and the right-aligned y tick label. */
+  y: 8
+};
+export function toTickProp(tick) {
+  if (tick && typeof tick.textAnchor === "string") return { textAnchor: tick.textAnchor };
+  return true;
+}
+function toAxisTicks(values) {
+  if (!values || values.length === 0) return void 0;
+  return values.map((v) => v instanceof Date ? v.getTime() : v);
+}
+export function resolveAxisProps(explicitTicks, config, minMaxTicksOnly) {
+  const ticks = toAxisTicks(config?.tickValues ?? explicitTicks);
+  const minMax = minMaxTicksOnly ?? config?.minMaxTicksOnly ?? false;
+  const tickAttrs = {};
+  if (config?.tickTextColor) tickAttrs.fill = config.tickTextColor;
+  if (config?.tickTextFontSize) tickAttrs.fontSize = config.tickTextFontSize;
+  if (config?.tickTextAlign) {
+    tickAttrs.textAnchor = config.tickTextAlign === "left" ? "start" : config.tickTextAlign === "right" ? "end" : "middle";
+  }
+  return {
+    ticks,
+    interval: minMax ? "preserveStartEnd" : void 0,
+    tick: Object.keys(tickAttrs).length ? tickAttrs : void 0
+  };
+}
+export function resolveYAxes(options) {
+  const { series, yAxes, primary, minMaxTicksOnly } = options;
+  const ids = [PRIMARY_Y_AXIS_ID];
+  const seen = /* @__PURE__ */ new Set([PRIMARY_Y_AXIS_ID]);
+  for (const raw of [...Object.keys(yAxes ?? {}), ...series.map((s) => s.yAxisId)]) {
+    const id = normalizeAxisId(raw);
+    if (seen.has(id)) continue;
+    seen.add(id);
+    ids.push(id);
+  }
+  const DEFAULT_ORIENTATION = "left";
+  return ids.map((id) => {
+    const config = yAxes?.[id] ?? yAxes?.[String(id)];
+    if (!config) return { ...primary, id, orientation: DEFAULT_ORIENTATION };
+    const resolved = resolveAxisProps(void 0, config, config.minMaxTicksOnly ?? minMaxTicksOnly);
+    return {
+      ...primary,
+      ...resolved,
+      id,
+      orientation: config.orientation ?? DEFAULT_ORIENTATION,
+      label: config.label ?? (id === PRIMARY_Y_AXIS_ID ? primary.label : void 0),
+      domain: toAxisDomain(config.domain) ?? primary.domain,
+      tickCount: config.numTicks ?? primary.tickCount,
+      tickFormatter: toTickFormatter(config.formatter ?? config.tickFormat) ?? primary.tickFormatter,
+      tickLine: config.tickLine ?? primary.tickLine,
+      hide: config.hide ?? false
+    };
+  });
+}
+export function toTickFormatter(formatter) {
+  if (!formatter) return void 0;
+  return (value, index) => formatter(value, index);
+}
+export function toAxisLabel(text, position, options) {
+  if (!text) return void 0;
+  const isVertical = position === "insideLeft" || position === "insideRight";
+  return {
+    value: text,
+    position,
+    offset: options?.offset ?? (isVertical ? 8 : 4),
+    ...options?.angle !== void 0 ? { angle: options.angle } : {},
+    ...isVertical && options?.angle !== void 0 ? { textAnchor: "middle" } : {},
+    fill: "var(--vc-axis-label-color)",
+    fontSize: "var(--vc-axis-label-size)",
+    fontWeight: "var(--vc-axis-label-weight)"
+  };
+}

package/dist/runtime/utils/categories.d.ts

@@ -0,0 +1,36 @@
+import type { AxisId, BulletLegendItemInterface } from "../types/shared.js";
+/** Id of the implicit primary y-axis, matching the `vccs` default. */
+export declare const PRIMARY_Y_AXIS_ID = 0;
+/**
+ * Canonicalise an axis id to the form `vccs` will match on.
+ *
+ * `vccs` binds a series to its axis with strict equality (`item.yAxisId === axisId`),
+ * so `"1"` and `1` are two different axes as far as the engine is concerned. Object
+ * keys are always strings, which means a numeric id declared in `yAxes` would never
+ * match the same id written as a number on a category. Ids that look like integers
+ * are normalised to numbers so both spellings — including `yAxis: "0"` for the
+ * primary axis — land on one axis.
+ */
+export declare function normalizeAxisId(id: AxisId): AxisId;
+/**
+ * A single resolved series, derived from one entry in a `categories` record.
+ * Drives one `<Area>` / `<Bar>` / `<Line>` / `<Scatter>` child in the adapters.
+ */
+export interface SeriesDescriptor {
+    /** The data property this series plots (the `categories` record key). */
+    dataKey: string;
+    /** Display name shown in legend / tooltip. */
+    name: string;
+    /** Resolved colour. Falls back to `var(--chart-color-N)` for CSS-var theming. */
+    color: string;
+    /** Whether the series is hidden. */
+    hidden: boolean;
+    /** Id of the y-axis this series is plotted against. */
+    yAxisId: AxisId;
+}
+/**
+ * Convert a `categories` record into an ordered list of {@link SeriesDescriptor}s.
+ * Hidden categories are kept (so the legend can still show them) — callers that
+ * want only visible series can filter on `hidden`.
+ */
+export declare function categoriesToSeries(categories: Record<string, BulletLegendItemInterface>): SeriesDescriptor[];

package/dist/runtime/utils/categories.js

@@ -0,0 +1,18 @@
+export const PRIMARY_Y_AXIS_ID = 0;
+export function normalizeAxisId(id) {
+  if (typeof id === "number") return id;
+  return /^-?\d+$/.test(id) ? Number(id) : id;
+}
+function resolveColor(color, index) {
+  if (Array.isArray(color)) return color[0] ?? `var(--chart-color-${index})`;
+  return color ?? `var(--chart-color-${index})`;
+}
+export function categoriesToSeries(categories) {
+  return Object.entries(categories).map(([dataKey, item], index) => ({
+    dataKey,
+    name: String(item.name ?? dataKey),
+    color: resolveColor(item.color, index),
+    hidden: item.hidden ?? false,
+    yAxisId: item.yAxis == null ? PRIMARY_Y_AXIS_ID : normalizeAxisId(item.yAxis)
+  }));
+}

package/dist/runtime/utils/cubes.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Cube-grid bar geometry.
+ *
+ * Turns a column band + value segment into a vertical stack of square cells
+ * (GitHub-contribution / Lego style). Pure functions — no Vue — so layout can
+ * be unit-tested and shared across single, grouped, and stacked series.
+ */
+/** One square in a cube column. */
+export interface CubeRect {
+    x: number;
+    y: number;
+    size: number;
+    radius: number;
+    /** 0–1 fill opacity. Tapers with size when `minSize` is set. */
+    opacity: number;
+    /** True when this cell represents the data value. */
+    filled: boolean;
+}
+/** Full-column band from the plot top to the baseline (`vccs` bar `background`). */
+export interface CubeColumnBand {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface LayoutCubeColumnInput {
+    column: CubeColumnBand;
+    /** Already-scaled segment height in px. */
+    valueHeight: number;
+    /**
+     * SVG y of the segment top. When omitted, the segment sits on the baseline
+     * (`valueHeight` tall). Stacked series pass the real bar `y` here so each
+     * layer owns a contiguous cube range.
+     */
+    segmentY?: number;
+    /**
+     * Draw ghost cubes for unfilled rows. For stacked bars only the first series
+     * should do this; later series paint fills only. Default `true`.
+     */
+    includeEmpty?: boolean;
+    /** Gap between cubes in px. Default 2. */
+    gap?: number;
+    /** Corner radius per cube. Default 2. */
+    radius?: number;
+    /**
+     * Preferred cube edge length. Clamped to the band width so each column stays
+     * a straight, centered stack. Default 10.
+     */
+    preferredSize?: number;
+    /**
+     * When set below `preferredSize`, cube edge length tapers from preferred at
+     * the top of the plot down to this size at the baseline. Size is based on
+     * absolute row position so every horizontal line shares one cube size.
+     * Grid stride stays based on preferred size; each square is centered in its cell.
+     * Opacity also tapers top → bottom (see `minOpacity`).
+     */
+    minSize?: number;
+    /**
+     * Floor opacity when size-tapering (top stays 1). Default 0.05 — nearly
+     * invisible at the baseline. Ignored unless `minSize` enables taper.
+     */
+    minOpacity?: number;
+}
+export declare const DEFAULT_CUBE_GAP = 2;
+export declare const DEFAULT_CUBE_RADIUS = 2;
+export declare const DEFAULT_CUBE_SIZE = 10;
+export declare const DEFAULT_CUBE_EMPTY_COLOR = "rgba(128, 128, 128, 0.14)";
+/** Baseline opacity when size-tapering — almost invisible at the bottom. */
+export declare const DEFAULT_CUBE_MIN_OPACITY = 0.05;
+/**
+ * Map a value height onto an integer cube count.
+ * `valueHeight / columnHeight` mirrors the y-scale without needing yMax.
+ */
+export declare function valueToCubeCount(valueHeight: number, columnHeight: number, rows: number): number;
+/** Resolve cube size + row count for a column band. */
+export declare function resolveCubeGrid(column: CubeColumnBand, gap?: number, preferredSize?: number): {
+    size: number;
+    rows: number;
+    stride: number;
+    originX: number;
+    originY: number;
+} | null;
+/**
+ * Edge length for a row when tapering from `maxSize` (top) to `minSize` (bottom).
+ * `rowFromTop` is 0 at the top of the column.
+ */
+export declare function cubeSizeAtRow(rowFromTop: number, rows: number, maxSize: number, minSize: number): number;
+/**
+ * Fill opacity for a row when tapering from 1 (top) to `minOpacity` (bottom).
+ * Uses a ease-in curve so the washout accelerates toward the baseline.
+ */
+export declare function cubeOpacityAtRow(rowFromTop: number, rows: number, minOpacity?: number): number;
+/**
+ * Lay out cubes for one series segment within a category column.
+ *
+ * - Single / grouped: omit `segmentY`, `includeEmpty: true` (default).
+ * - Stacked: pass each layer's bar `y` as `segmentY`; only the first series
+ *   should set `includeEmpty: true` so the ghost tower is drawn once.
+ */
+export declare function layoutCubeColumn(input: LayoutCubeColumnInput): CubeRect[];

package/dist/runtime/utils/cubes.js

@@ -0,0 +1,73 @@
+export const DEFAULT_CUBE_GAP = 2;
+export const DEFAULT_CUBE_RADIUS = 2;
+export const DEFAULT_CUBE_SIZE = 10;
+export const DEFAULT_CUBE_EMPTY_COLOR = "rgba(128, 128, 128, 0.14)";
+export const DEFAULT_CUBE_MIN_OPACITY = 0.05;
+export function valueToCubeCount(valueHeight, columnHeight, rows) {
+  if (rows <= 0 || columnHeight <= 0 || valueHeight <= 0) return 0;
+  return Math.min(rows, Math.max(0, Math.round(valueHeight / columnHeight * rows)));
+}
+export function resolveCubeGrid(column, gap = DEFAULT_CUBE_GAP, preferredSize = DEFAULT_CUBE_SIZE) {
+  const { x, y, width, height } = column;
+  if (!(width > 0) || !(height > 0)) return null;
+  const size = Math.max(1, Math.min(width, preferredSize));
+  const stride = size + gap;
+  const rows = Math.max(1, Math.floor((height + gap) / stride));
+  const stackHeight = rows * size + (rows - 1) * gap;
+  return {
+    size,
+    rows,
+    stride,
+    originX: x + (width - size) / 2,
+    originY: y + height - stackHeight
+  };
+}
+export function cubeSizeAtRow(rowFromTop, rows, maxSize, minSize) {
+  if (rows <= 1 || minSize >= maxSize) return maxSize;
+  const t = rowFromTop / (rows - 1);
+  return maxSize + (minSize - maxSize) * t;
+}
+export function cubeOpacityAtRow(rowFromTop, rows, minOpacity = DEFAULT_CUBE_MIN_OPACITY) {
+  if (rows <= 1) return 1;
+  const t = rowFromTop / (rows - 1);
+  const eased = t * t;
+  return 1 + (Math.min(1, Math.max(0, minOpacity)) - 1) * eased;
+}
+export function layoutCubeColumn(input) {
+  const gap = input.gap ?? DEFAULT_CUBE_GAP;
+  const radius = input.radius ?? DEFAULT_CUBE_RADIUS;
+  const preferred = input.preferredSize ?? DEFAULT_CUBE_SIZE;
+  const includeEmpty = input.includeEmpty !== false;
+  const { column } = input;
+  const grid = resolveCubeGrid(column, gap, preferred);
+  if (!grid) return [];
+  const { size, rows, stride, originX, originY } = grid;
+  const rawMin = input.minSize;
+  const taper = typeof rawMin === "number" && Number.isFinite(rawMin) && rawMin > 0 && rawMin < size;
+  const minSize = taper ? Math.max(1, rawMin) : size;
+  const minOpacity = typeof input.minOpacity === "number" && Number.isFinite(input.minOpacity) ? Math.min(1, Math.max(0, input.minOpacity)) : DEFAULT_CUBE_MIN_OPACITY;
+  const baseline = column.y + column.height;
+  const segH = Math.max(0, input.valueHeight);
+  const segTop = input.segmentY ?? baseline - segH;
+  const segBottom = segTop + segH;
+  const startIdx = valueToCubeCount(Math.max(0, baseline - segBottom), column.height, rows);
+  const endIdx = valueToCubeCount(Math.max(0, baseline - segTop), column.height, rows);
+  const rects = [];
+  for (let i = 0; i < rows; i++) {
+    const filled = i >= startIdx && i < endIdx;
+    if (!filled && !includeEmpty) continue;
+    const rowFromTop = rows - 1 - i;
+    const cubeSize = taper ? cubeSizeAtRow(rowFromTop, rows, size, minSize) : size;
+    const opacity = taper ? cubeOpacityAtRow(rowFromTop, rows, minOpacity) : 1;
+    const inset = (size - cubeSize) / 2;
+    rects.push({
+      x: originX + inset,
+      y: originY + rowFromTop * stride + inset,
+      size: cubeSize,
+      radius: Math.min(radius, cubeSize / 2),
+      opacity,
+      filled
+    });
+  }
+  return rects;
+}