@galaxy-io/dls 1.6.0 → 2.0.0

package/dist/charts/types.js

@@ -1,178 +1,89 @@
 //#region src/charts/types.ts
 /**
-* Shared types for the chart components (`BarChart`, `LineChart`, `PieChart`).
-*
-* Every data type is generic over its key unions, and the inference is
-* deliberately one-directional: `TMetric` comes from the keys of the `series`
-* record and from nowhere else, with {@link NoInfer} applied to every
-* data-shaped prop.
-*
-* That asymmetry is what makes the guarantees real. Were `TMetric` also
-* inferred from the data, an inline `{ metric: "revenue" }` would widen to
-* `string`, TypeScript would pick the supertype, and every check below would
-* quietly become a no-op — type safety that looks present but is not.
-*
-* ```ts
-* <BarChart
-*   series={{
-*     revenue: { label: "Revenue" },
-*     cost: { label: "Cost" },
-*   }}
-*   groups={[
-*     { label: "Q1", bars: [{ metric: "revenu", components: [] }] },
-*     //                              ^ Type '"revenu"' is not assignable to
-*     //                                type '"revenue" | "cost"'.
-*   ]}
-* />
-* ```
-*
-* The same union then makes aggregates exhaustive, spell-checks legend and
-* ordering props, and narrows callback parameters for `ts-pattern`.
-*/
-/**
-* Semantic color slot for a series, resolved against the active theme at render
-* time by `resolveChartPaletteColor` in `chartTheme.ts`.
-*
-* Deliberately an enum of slots rather than a hex string: consumer data should
-* never carry raw color, and every rendered color has to come from
-* `theme.color.*` so both themes stay correct.
+* Series color slot. Members are canonical color-set names (Constitution
+* III.4). The first eight are the automatic order (purple leads); the rest are for explicit,
+* meaningful assignment only.
 */
 var ChartPalette = /* @__PURE__ */ function(ChartPalette) {
+	/** `text.purple`. First in the automatic order. */
 	ChartPalette["PURPLE"] = "PURPLE";
+	/** `text.pink`. */
 	ChartPalette["PINK"] = "PINK";
+	/** `text.blue`. */
 	ChartPalette["BLUE"] = "BLUE";
+	/** `text.teal`. */
 	ChartPalette["TEAL"] = "TEAL";
+	/** `text.lime`. */
 	ChartPalette["LIME"] = "LIME";
+	/** `text.orange`. */
 	ChartPalette["ORANGE"] = "ORANGE";
+	/** `text.yellow`. */
 	ChartPalette["YELLOW"] = "YELLOW";
+	/** `text.green`. Last in the automatic order. */
 	ChartPalette["GREEN"] = "GREEN";
-	ChartPalette["RED"] = "RED";
+	/** `text.success`. Explicit assignment only. */
+	ChartPalette["SUCCESS"] = "SUCCESS";
+	/** `text.warning`. Explicit assignment only. */
+	ChartPalette["WARNING"] = "WARNING";
+	/** `text.error` (1.x `RED`). Explicit assignment only. */
+	ChartPalette["ERROR"] = "ERROR";
+	/** `text.indigo` (no gray in charts). Explicit assignment only. */
 	ChartPalette["PRIMARY"] = "PRIMARY";
+	/** `text.sky` (no gray in charts). Explicit assignment only. */
 	ChartPalette["SECONDARY"] = "SECONDARY";
+	/** `text.violet` (no gray in charts). Explicit assignment only. */
 	ChartPalette["TERTIARY"] = "TERTIARY";
-	ChartPalette["WARNING"] = "WARNING";
 	return ChartPalette;
 }({});
-/**
-* Built-in value formats. Supplies an `Intl`-based default for axis ticks,
-* value labels and tooltip rows so callers don't have to write the same
-* formatter three times.
-*
-* A `valueFormatter` prop always wins over this when both are given.
-*/
-var ChartValueUnit = /* @__PURE__ */ function(ChartValueUnit) {
-	/** Locale-grouped integer, e.g. `1,250`. */
-	ChartValueUnit["PLAIN"] = "PLAIN";
-	/** Locale currency with no decimals, e.g. `$1,250`. */
-	ChartValueUnit["CURRENCY"] = "CURRENCY";
-	/** Percentage of a 0–100 value, e.g. `42%`. */
-	ChartValueUnit["PERCENT"] = "PERCENT";
-	/** Abbreviated magnitude, e.g. `1.3K`, `4.2M`. */
-	ChartValueUnit["COMPACT"] = "COMPACT";
-	return ChartValueUnit;
+/** How segments between points are drawn (LineChart, AreaChart, Sparkline). 1.x `LineChartCurve`. */
+var ChartCurve = /* @__PURE__ */ function(ChartCurve) {
+	/** Straight segments. */
+	ChartCurve["LINEAR"] = "LINEAR";
+	/** Monotone cubic: smooth without overshooting the data. */
+	ChartCurve["SMOOTH"] = "SMOOTH";
+	/** Right-angled steps (step-after). */
+	ChartCurve["STEP"] = "STEP";
+	return ChartCurve;
 }({});
-/**
-* Which chart is being rendered.
-*
-* Exists so the frame can phrase a default accessible name — a pie has slices
-* where the cartesian charts have categories. Deliberately not a styling hook:
-* nothing else branches on it.
-*/
+/** @internal Emphasis of a rendered mark, applied as a `css` class (`CHART_MARK_STATE_TO_CSS_MAP`). */
+var ChartMarkState = /* @__PURE__ */ function(ChartMarkState) {
+	/** Full strength: the default, and the engaged category or series. */
+	ChartMarkState["ACTIVE"] = "ACTIVE";
+	/** Softened: outside the engaged series, the selection, or while loading. */
+	ChartMarkState["MUTED"] = "MUTED";
+	/** Barely softened: off-category marks where a cursor band already carries the emphasis. */
+	ChartMarkState["DIMMED"] = "DIMMED";
+	return ChartMarkState;
+}({});
+/** @internal Which chart is rendering; phrases the default accessible name only. */
 var ChartKind = /* @__PURE__ */ function(ChartKind) {
-	ChartKind["BAR"] = "BAR";
+	/** `LineChart`. */
 	ChartKind["LINE"] = "LINE";
+	/** `AreaChart`. */
+	ChartKind["AREA"] = "AREA";
+	/** `BarChart`. */
+	ChartKind["BAR"] = "BAR";
+	/** `PieChart`. */
 	ChartKind["PIE"] = "PIE";
+	/** `Heatmap`. */
+	ChartKind["HEATMAP"] = "HEATMAP";
 	return ChartKind;
 }({});
-/**
-* Where the legend sits relative to the plot.
-*
-* Its own enum rather than a branch on {@link ChartKind}, which promises to be
-* nothing but a label for the accessible name.
-*/
+/** @internal Where the legend sits relative to the plot. */
 var ChartLegendPlacement = /* @__PURE__ */ function(ChartLegendPlacement) {
-	/** Beneath the plot, wrapping — the cartesian layout. */
+	/** Beneath the plot, one line (cartesian charts, Heatmap). */
 	ChartLegendPlacement["BOTTOM"] = "BOTTOM";
-	/** Beside the plot, stacked, vertically centred on it — the pie layout. */
+	/** Beside the plot, one column, vertically centered (PieChart). */
 	ChartLegendPlacement["RIGHT"] = "RIGHT";
 	return ChartLegendPlacement;
 }({});
-/** How the category axis copes when labels outgrow their slots. */
-var ChartCategoryLabelMode = /* @__PURE__ */ function(ChartCategoryLabelMode) {
-	/** Render every label that fits; otherwise show every nth. The default. */
-	ChartCategoryLabelMode["AUTO"] = "AUTO";
-	/** Render every label, ellipsizing any that overflow its slot. */
-	ChartCategoryLabelMode["TRUNCATE"] = "TRUNCATE";
-	/** Render every label unconditionally, overlap included. */
-	ChartCategoryLabelMode["ALL"] = "ALL";
-	return ChartCategoryLabelMode;
-}({});
-/**
-* Emphasis level of a rendered mark.
-*
-* Travels to the DOM as a `data-state` attribute rather than a styled-component
-* prop: `@linaria/react` skips prop filtering entirely for SVG tags (its
-* `allTagsSet` is built with a missing spread, so `has('rect')` is false and
-* `propsAsIs` turns on), which would forward a `$`-prefixed prop straight to the
-* DOM and trigger a React warning.
-*/
-var ChartMarkState = /* @__PURE__ */ function(ChartMarkState) {
-	/** Full strength — the default, and the hovered category. */
-	ChartMarkState["ACTIVE"] = "active";
-	/** Softened, for marks outside the engaged series or category. */
-	ChartMarkState["MUTED"] = "muted";
-	/**
-	* Barely softened — a whisper of {@link MUTED}.
-	*
-	* Used where another affordance already carries the emphasis and strong
-	* muting would be a second, louder voice: BarChart's category axis dims
-	* like this because the cursor band is the highlight.
-	*/
-	ChartMarkState["DIMMED"] = "dimmed";
-	return ChartMarkState;
-}({});
-/** Which pair of a rectangle's corners carries the radius. */
-var BarCorners = /* @__PURE__ */ function(BarCorners) {
-	/** Cap for a bar growing up from the baseline. */
-	BarCorners["TOP"] = "TOP";
-	/** Cap for a bar growing down from the baseline. */
-	BarCorners["BOTTOM"] = "BOTTOM";
-	/** Interior stack segment — square on both ends. */
-	BarCorners["NONE"] = "NONE";
-	return BarCorners;
-}({});
-/**
-* How bar values are scaled before rendering.
-*
-* Note there is no grouped-vs-stacked mode: with the group → bar → component
-* hierarchy, several `bars` in a group render side by side and several
-* `components` in a bar render on top of each other, so a chart can be grouped
-* and stacked at the same time.
-*/
-var BarChartNormalization = /* @__PURE__ */ function(BarChartNormalization) {
-	/** Plot raw values. */
-	BarChartNormalization["NONE"] = "NONE";
-	/** Scale each bar's components to fill the axis — a 100% stacked chart. */
-	BarChartNormalization["PERCENT"] = "PERCENT";
-	return BarChartNormalization;
-}({});
-/** How the segments between points are interpolated. */
-var LineChartCurve = /* @__PURE__ */ function(LineChartCurve) {
-	/** Straight segments. */
-	LineChartCurve["LINEAR"] = "LINEAR";
-	/** Monotone cubic — smooth without overshooting the data. */
-	LineChartCurve["SMOOTH"] = "SMOOTH";
-	/** Right-angled steps. */
-	LineChartCurve["STEP"] = "STEP";
-	return LineChartCurve;
-}({});
-/** Which shape a category's hit target is drawn as. */
+/** @internal Shape of a hit target. */
 var ChartTargetShape = /* @__PURE__ */ function(ChartTargetShape) {
-	/** Cartesian charts: a full-height band over the category. */
+	/** A rectangle: a category band or a bar. */
 	ChartTargetShape["RECT"] = "RECT";
-	/** Radial charts: the arc's own outline, redrawn transparent. */
+	/** A path: an arc outline, redrawn transparent. */
 	ChartTargetShape["PATH"] = "PATH";
 	return ChartTargetShape;
 }({});
 //#endregion
-export { BarChartNormalization, BarCorners, ChartCategoryLabelMode, ChartKind, ChartLegendPlacement, ChartMarkState, ChartPalette, ChartTargetShape, ChartValueUnit, LineChartCurve };
+export { ChartCurve, ChartKind, ChartLegendPlacement, ChartMarkState, ChartPalette, ChartTargetShape };

package/dist/charts/useCartesianChartLayout.d.ts

@@ -1,70 +1,39 @@
-import type { ChartLabelFormatter, ChartMargin, ChartValueDomain, ChartValueFormatter, ChartValueUnit } from "./types";
-import type { ChartDimensions } from "./useChartDimensions";
 /**
- * Everything a cartesian chart resolves *before* it can be measured.
- *
- * There is a hard ordering inside bar and line alike:
- *
- * ```
- * domain → ticks → left margin → dimensions → plot size → geometry
- * ```
- *
- * The gutter has to fit the tick labels, the ticks come from the domain, and
- * the domain comes from the data — none of which needs the plot. Everything
- * after `geometry` does need it, which is why this hook stops there rather than
- * trying to own the whole chart: the geometry builders are generic over the
- * chart's own key types, and threading those through here would buy nothing.
- *
- * Deliberately **not generic**. `getBarValueDomain` and `getLineValueDomain`
- * have already erased the key types by the time they return an extent, so
- * nothing in this phase needs them.
+ * @internal Everything a cartesian chart resolves before its geometry, in the one order that
+ * works: measured box → plot height (the top and bottom insets do not depend on the ticks) →
+ * domain and ticks thinned to that height → left gutter (fits the tick labels) → plot → geometry.
+ * Not generic: the value extent has already erased the series keys.
  */
-interface UseCartesianChartLayoutOptions {
-    containerRef: React.RefObject<HTMLDivElement | null>;
-    /**
-     * The data's own extent, before any override or nicing.
-     *
-     * Free to be a fresh array each render — the memo below keys on the two
-     * numbers, not the array's identity.
-     */
+import { type RefObject } from "react";
+import type { ChartAxisLabels, ChartLabelFormatter, ChartValueDomain, ChartValueFormatter } from "./types.js";
+import { type ChartDimensions } from "./useChartDimensions.js";
+/** @internal Inputs of `useCartesianChartLayout`. */
+export interface UseCartesianChartLayoutOptions {
+    /** The plot box to measure. */
+    plotRef: RefObject<HTMLDivElement>;
+    /** The data's own extent, before any override or nicing. */
     rawDomain: [number, number];
-    valueDomain?: Partial<ChartValueDomain>;
-    width?: number;
-    height?: number;
-    fillWidth?: boolean;
-    fillHeight?: boolean;
-    aspectRatio?: number;
-    margin?: Partial<ChartMargin>;
-    valueUnit?: ChartValueUnit;
-    valueFormatter?: ChartValueFormatter;
-    labelFormatter?: ChartLabelFormatter;
-    /**
-     * Rewrites the resolved value formatter for the axis alone.
-     *
-     * Takes the resolved formatter rather than replacing it, because the only
-     * caller — a percent-normalized bar chart — falls back to it whenever the
-     * consumer asked for something specific. Applies to the tick labels *and* the
-     * gutter estimate, which is the point: sizing the gutter with a different
-     * formatter than the one that renders into it is how a gutter ends up too
-     * narrow for its own labels.
-     *
-     * Must be stable; memoize it at the call site.
-     */
-    deriveAxisFormatter?: (formatValue: ChartValueFormatter) => ChartValueFormatter;
-    valueAxisTitle?: string;
-    categoryAxisTitle?: string;
+    /** The `valueDomain` prop. */
+    valueDomain?: Partial<ChartValueDomain> | undefined;
+    /** The `valueFormatter` prop. */
+    valueFormatter?: ChartValueFormatter | undefined;
+    /** The `labelFormatter` prop. */
+    labelFormatter?: ChartLabelFormatter | undefined;
+    /** The `axisLabels` prop. */
+    axisLabels?: ChartAxisLabels | undefined;
 }
+/** @internal The resolved layout. */
 export interface CartesianChartLayout {
+    /** Measured plot box, insets and plot size. */
     dimensions: ChartDimensions;
-    /** Override applied, zero included, degenerate widened, `nice()` applied. */
+    /** Override applied, zero included, degenerate widened, `nice()`d. */
     domain: [number, number];
+    /** Value tick values. */
     valueTicks: number[];
-    /** Tooltip rows and value labels. */
+    /** Values: ticks, tooltip rows, announcements. */
     formatValue: ChartValueFormatter;
-    /** Category names — the axis and the tooltip heading. */
+    /** Category names: the axis and the tooltip heading. */
     formatLabel: ChartLabelFormatter;
-    /** Axis ticks. Identical to `formatValue` unless `deriveAxisFormatter` said otherwise. */
-    formatAxisValue: ChartValueFormatter;
 }
-export declare function useCartesianChartLayout({ containerRef, rawDomain, valueDomain, width, height, fillWidth, fillHeight, aspectRatio, margin, valueUnit, valueFormatter, labelFormatter, deriveAxisFormatter, valueAxisTitle, categoryAxisTitle, }: UseCartesianChartLayoutOptions): CartesianChartLayout;
-export {};
+/** @internal Resolves a cartesian chart's domain, ticks, insets, dimensions and formatters. */
+export declare function useCartesianChartLayout({ plotRef, rawDomain, valueDomain, valueFormatter, labelFormatter, axisLabels, }: UseCartesianChartLayoutOptions): CartesianChartLayout;

package/dist/charts/useCartesianChartLayout.js

@@ -1,55 +1,70 @@
-import { addAxisTitleSpace, estimateValueAxisMargin, getValueTicks, resolveValueDomain } from "./chartScales.js";
+import { estimateValueAxisInset, getCartesianInsets, resolveValueAxis } from "./chartScales.js";
+import { useElementClientSize } from "../hooks/useElementClientSize.js";
+import { toChartDimensions } from "./useChartDimensions.js";
 import { useChartFormatters } from "./useChartFormatters.js";
-import { useChartDimensions } from "./useChartDimensions.js";
 import { useMemo } from "react";
 //#region src/charts/useCartesianChartLayout.ts
-function useCartesianChartLayout({ containerRef, rawDomain, valueDomain, width, height, fillWidth, fillHeight, aspectRatio, margin, valueUnit, valueFormatter, labelFormatter, deriveAxisFormatter, valueAxisTitle, categoryAxisTitle }) {
-	const { formatValue, formatLabel } = useChartFormatters({
-		valueFormatter,
-		valueUnit,
-		labelFormatter
+/**
+* @internal Everything a cartesian chart resolves before its geometry, in the one order that
+* works: measured box → plot height (the top and bottom insets do not depend on the ticks) →
+* domain and ticks thinned to that height → left gutter (fits the tick labels) → plot → geometry.
+* Not generic: the value extent has already erased the series keys.
+*/
+/** @internal Resolves a cartesian chart's domain, ticks, insets, dimensions and formatters. */
+function useCartesianChartLayout({ plotRef, rawDomain, valueDomain, valueFormatter, labelFormatter, axisLabels }) {
+	const { formatValue, formatLabel } = useChartFormatters(valueFormatter, labelFormatter);
+	const { width: measuredWidth, height: measuredHeight } = useElementClientSize(plotRef);
+	const width = measuredWidth ?? 0;
+	const height = measuredHeight ?? 0;
+	const hasValueTitle = Boolean(axisLabels?.value);
+	const hasCategoryTitle = Boolean(axisLabels?.category);
+	const { top, bottom } = getCartesianInsets(0, {
+		hasValueTitle,
+		hasCategoryTitle
 	});
-	const formatAxisValue = useMemo(() => deriveAxisFormatter?.(formatValue) ?? formatValue, [deriveAxisFormatter, formatValue]);
+	const plotHeight = height > 0 ? Math.max(0, height - top - bottom) : 0;
 	const [rawMin, rawMax] = rawDomain;
-	const domain = useMemo(() => resolveValueDomain([rawMin, rawMax], valueDomain), [
+	const domainMin = valueDomain?.min;
+	const domainMax = valueDomain?.max;
+	const tickCount = valueDomain?.tickCount;
+	const { domain, ticks: valueTicks } = useMemo(() => resolveValueAxis([rawMin, rawMax], {
+		...domainMin !== void 0 && { min: domainMin },
+		...domainMax !== void 0 && { max: domainMax },
+		...tickCount !== void 0 && { tickCount }
+	}, plotHeight), [
 		rawMin,
 		rawMax,
-		valueDomain
+		domainMin,
+		domainMax,
+		tickCount,
+		plotHeight
 	]);
-	const valueTicks = useMemo(() => getValueTicks(domain, valueDomain), [domain, valueDomain]);
-	const dimensions = useChartDimensions({
-		containerRef,
+	const tickInset = useMemo(() => estimateValueAxisInset(valueTicks, formatValue), [valueTicks, formatValue]);
+	const insets = useMemo(() => getCartesianInsets(tickInset, {
+		hasValueTitle,
+		hasCategoryTitle
+	}), [
+		tickInset,
+		hasValueTitle,
+		hasCategoryTitle
+	]);
+	const dimensions = useMemo(() => toChartDimensions(width, height, insets), [
 		width,
 		height,
-		fillWidth,
-		fillHeight,
-		aspectRatio,
-		margin: addAxisTitleSpace(useMemo(() => ({
-			...margin,
-			left: margin?.left ?? estimateValueAxisMargin(valueTicks, formatAxisValue)
-		}), [
-			margin,
-			valueTicks,
-			formatAxisValue
-		]), {
-			hasValueTitle: Boolean(valueAxisTitle),
-			hasCategoryTitle: Boolean(categoryAxisTitle)
-		})
-	});
+		insets
+	]);
 	return useMemo(() => ({
 		dimensions,
 		domain,
 		valueTicks,
 		formatValue,
-		formatLabel,
-		formatAxisValue
+		formatLabel
 	}), [
 		dimensions,
 		domain,
 		valueTicks,
 		formatValue,
-		formatLabel,
-		formatAxisValue
+		formatLabel
 	]);
 }
 //#endregion

package/dist/charts/useChartDimensions.d.ts

@@ -1,47 +1,26 @@
-import type { ChartMargin } from "./types";
-interface UseChartDimensionsOptions {
-    /**
-     * The element to measure.
-     *
-     * Owned by the caller rather than returned from here: a hook that hands back
-     * a ref inside its result object reads as a ref access during render, both to
-     * the `react-hooks/refs` lint rule and to anyone reviewing the call site.
-     */
-    containerRef: React.RefObject<HTMLElement | null>;
-    width?: number;
-    height?: number;
-    fillWidth?: boolean;
-    /**
-     * Take the height from the measured box rather than a prop.
-     *
-     * Requires an ancestor with a definite height — see {@link ChartSize}. The
-     * measured element is the *plot box*, not the chart root, so the legend is
-     * already excluded by flexbox and nothing here has to subtract it.
-     */
-    fillHeight?: boolean;
-    aspectRatio?: number;
-    margin?: Partial<ChartMargin>;
-    /**
-     * Fallback for whichever fields `margin` leaves out.
-     *
-     * Radial charts pass their own, since the cartesian default reserves gutters
-     * for axes they do not draw. Merged per field, so a caller's partial margin
-     * lands on top of *this* rather than reverting the chart to the cartesian
-     * defaults.
-     */
-    defaultMargin?: ChartMargin;
-}
+/**
+ * @internal Measures a chart's plot box. The chart fills its parent (or takes its 2:1
+ * aspect-ratio fallback through CSS), so the box already has its size before measurement lands
+ * and nothing shifts. SSR-safe: `useElementClientSize` measures in an effect.
+ */
+import { type RefObject } from "react";
+import type { ChartInsets } from "./chartScales.js";
+/** @internal The measured plot box and the plot inside it. */
 export interface ChartDimensions {
+    /** Plot box width (client pixels). */
     width: number;
+    /** Plot box height (client pixels). */
     height: number;
+    /** Plot width: the box less the left and right insets, never negative. */
     plotWidth: number;
+    /** Plot height: the box less the top and bottom insets, never negative. */
     plotHeight: number;
-    margin: ChartMargin;
-    /** False until the box has usable dimensions; guard mark rendering on it. */
+    /** Space between the box edge and the plot. */
+    insets: ChartInsets;
+    /** `false` until the first measurement with a usable size; marks render only after it. */
     isMeasured: boolean;
-    /** Handed to the plot box so it reserves space before measurement lands. */
-    reservedHeight?: number;
-    reservedAspectRatio?: number;
 }
-export declare function useChartDimensions({ containerRef, width, height, fillWidth, fillHeight, aspectRatio, margin: marginOverride, defaultMargin, }: UseChartDimensionsOptions): ChartDimensions;
-export {};
+/** @internal The plot inside a measured `width` × `height` box (pure: the hook below, without measuring). */
+export declare function toChartDimensions(width: number, height: number, insets: ChartInsets): ChartDimensions;
+/** @internal Measures `plotRef` (the plot box, not the root: the legend is a sibling). */
+export declare function useChartDimensions(plotRef: RefObject<HTMLElement | null>, insets: ChartInsets): ChartDimensions;

package/dist/charts/useChartDimensions.js

@@ -1,63 +1,47 @@
 import { useElementClientSize } from "../hooks/useElementClientSize.js";
-import { DEFAULT_CHART_MARGIN } from "./constants.js";
-import { getPlotDimensions, resolveMargin } from "./chartScales.js";
-import { useEffect, useMemo } from "react";
+import { useMemo } from "react";
 //#region src/charts/useChartDimensions.ts
-function useChartDimensions({ containerRef, width, height, fillWidth = false, fillHeight = false, aspectRatio, margin: marginOverride, defaultMargin }) {
-	const { width: measuredWidth, height: measuredHeight } = useElementClientSize(containerRef);
-	const resolvedWidth = fillWidth ? measuredWidth ?? 0 : width ?? 0;
-	const resolvedHeight = fillHeight ? measuredHeight ?? 0 : aspectRatio ? resolvedWidth / aspectRatio : height ?? 0;
-	const { top: marginTop, right: marginRight, bottom: marginBottom, left: marginLeft } = marginOverride ?? {};
-	const { top: defaultTop, right: defaultRight, bottom: defaultBottom, left: defaultLeft } = defaultMargin ?? DEFAULT_CHART_MARGIN;
-	const margin = useMemo(() => resolveMargin({
-		top: marginTop,
-		right: marginRight,
-		bottom: marginBottom,
-		left: marginLeft
-	}, {
-		top: defaultTop,
-		right: defaultRight,
-		bottom: defaultBottom,
-		left: defaultLeft
-	}), [
-		marginTop,
-		marginRight,
-		marginBottom,
-		marginLeft,
-		defaultTop,
-		defaultRight,
-		defaultBottom,
-		defaultLeft
-	]);
-	const { plotWidth, plotHeight } = useMemo(() => getPlotDimensions(resolvedWidth, resolvedHeight, margin), [
-		resolvedWidth,
-		resolvedHeight,
-		margin
-	]);
-	useEffect(() => {
-		if (typeof process !== "undefined" && process.env.NODE_ENV === "production") return;
-		if (!fillHeight || measuredHeight === void 0 || measuredHeight > 0) return;
-		console.warn("[@galaxy-io/dls] A chart with `fillHeight` measured 0px tall and will not render. `fillHeight` takes its height from the container, so an ancestor needs a definite height — an explicit height, a flex or grid track, or absolute positioning. Use `height` or `aspectRatio` instead if the container is sized by its content.");
-	}, [fillHeight, measuredHeight]);
-	return useMemo(() => ({
-		width: resolvedWidth,
-		height: resolvedHeight,
-		plotWidth,
-		plotHeight,
-		margin,
-		isMeasured: resolvedWidth > 0 && resolvedHeight > 0,
-		reservedHeight: fillHeight || aspectRatio ? void 0 : height,
-		reservedAspectRatio: fillHeight ? void 0 : aspectRatio
+/**
+* @internal Measures a chart's plot box. The chart fills its parent (or takes its 2:1
+* aspect-ratio fallback through CSS), so the box already has its size before measurement lands
+* and nothing shifts. SSR-safe: `useElementClientSize` measures in an effect.
+*/
+/** @internal The plot inside a measured `width` × `height` box (pure: the hook below, without measuring). */
+function toChartDimensions(width, height, insets) {
+	const { top, right, bottom, left } = insets;
+	return {
+		width,
+		height,
+		plotWidth: Math.max(0, width - left - right),
+		plotHeight: Math.max(0, height - top - bottom),
+		insets: {
+			top,
+			right,
+			bottom,
+			left
+		},
+		isMeasured: width > 0 && height > 0
+	};
+}
+/** @internal Measures `plotRef` (the plot box, not the root: the legend is a sibling). */
+function useChartDimensions(plotRef, insets) {
+	const { width: measuredWidth, height: measuredHeight } = useElementClientSize(plotRef);
+	const width = measuredWidth ?? 0;
+	const height = measuredHeight ?? 0;
+	const { top, right, bottom, left } = insets;
+	return useMemo(() => toChartDimensions(width, height, {
+		top,
+		right,
+		bottom,
+		left
 	}), [
-		resolvedWidth,
-		resolvedHeight,
-		plotWidth,
-		plotHeight,
-		margin,
-		aspectRatio,
+		width,
 		height,
-		fillHeight
+		top,
+		right,
+		bottom,
+		left
 	]);
 }
 //#endregion
-export { useChartDimensions };
+export { toChartDimensions, useChartDimensions };

package/dist/charts/useChartFormatters.d.ts

@@ -1,19 +1,10 @@
-import type { ChartLabelFormatter, ChartValueFormatter, ChartValueUnit } from "./types";
-interface UseChartFormattersOptions {
-    valueFormatter?: ChartValueFormatter;
-    valueUnit?: ChartValueUnit;
-    labelFormatter?: ChartLabelFormatter;
-}
+import type { ChartLabelFormatter, ChartValueFormatter } from "./types.js";
+/** @internal The resolved formatters. */
 export interface ChartFormatters {
+    /** Values: axis ticks, tooltip rows, announcements. */
     formatValue: ChartValueFormatter;
+    /** Category names: the axis and the tooltip heading. */
     formatLabel: ChartLabelFormatter;
 }
-/**
- * Resolves the value and label formatters once per chart.
- *
- * Doing this centrally is what keeps axis ticks, value labels and tooltip rows
- * from drifting apart — the recurring failure when each call site formats for
- * itself.
- */
-export declare function useChartFormatters({ valueFormatter, valueUnit, labelFormatter, }: UseChartFormattersOptions): ChartFormatters;
-export {};
+/** @internal Resolves `valueFormatter` (default `formatNumber(v, { precision: 2 })`) and `labelFormatter` (identity). */
+export declare function useChartFormatters(valueFormatter?: ChartValueFormatter, labelFormatter?: ChartLabelFormatter): ChartFormatters;