@galaxy-io/dls 1.6.0 → 2.0.0

package/dist/charts/constants.js

@@ -1,285 +1,115 @@
-import { ChartPalette } from "./types.js";
+import { RADIUS, SPACE } from "../theme/tokens/scales.js";
 //#region src/charts/constants.ts
 /**
-* Layout and motion tokens for the chart components.
-*
-* This module is evaluated by Linaria at build time — its constants are
-* interpolated statically into styled templates — so it must stay free of
-* component imports. Pulling React, framer-motion or Phosphor in here would
-* drag them into build-time evaluation.
-*/
-var DEFAULT_CHART_MARGIN = {
-	top: 12,
-	right: 16,
-	bottom: 36,
-	left: 52
-};
-/**
-* Gap between a value-axis tick label and the plot edge.
-*
-* The label box is `margin.left - VALUE_AXIS_TICK_GAP` wide, so the axis
-* geometry follows the margin instead of hardcoding an offset.
-*/
-var VALUE_AXIS_TICK_GAP = 12;
-/** Height of a value-axis tick label box in px. */
+* @internal Geometry and interaction constants for the chart family.
+*
+* wyw evaluates this module at build time (its values are interpolated into templates), so it
+* imports nothing but the token scales: no React, no d3, no component. Values equal to a scale
+* step are derived from `SPACE` / `RADIUS`; the rest are literals with a one-line reason.
+*/
+var px = (value) => Number.parseFloat(value);
+/** @internal Height of one caption line (`caption` type step): every axis label and title. */
+var CAPTION_LINE = px(SPACE[12]);
+/** @internal Clear space between an axis label (or title) and the plot, its grid, or the next label row. */
+var AXIS_LABEL_GAP = px(SPACE[8]);
+/** @internal Grid lines extend this far past both plot edges: a short lead-in, clear of the labels. */
+var GRID_LINE_BLEED = px(SPACE[4]);
+/** @internal Space above the plot: half a value label box (its text clears the top) plus air for a dot. */
+var PLOT_INSET_TOP = px(SPACE[8]);
+/** @internal Space right of the plot: the grid bleed plus air for a line's end dot and cap. */
+var PLOT_INSET_RIGHT = px(SPACE[8]);
+/** @internal Gap between a value tick label and the plot edge: the grid bleed plus the label gap. */
+var VALUE_AXIS_TICK_GAP = GRID_LINE_BLEED + AXIS_LABEL_GAP;
+/** @internal Height of a value tick label box: taller than the caption line so it centers on its tick. */
 var VALUE_AXIS_LABEL_HEIGHT = 20;
-/** Height of the category-axis label box in px. */
-var CATEGORY_AXIS_LABEL_HEIGHT = 24;
-/** Gap between the plot's bottom edge and the category labels, in px. */
-var CATEGORY_AXIS_LABEL_GAP = 8;
-/** Band reserved for an axis title, in px. Sized for one CAPTION line. */
-var AXIS_TITLE_BAND = 18;
-/**
-* Clear space between an axis title and its tick labels, in px.
-*
-* The category axis gets this for free: its labels sit in a 24px box and its
-* title in an 18px band, and centring a CAPTION line in each leaves roughly this
-* much air between the two. The value axis has no such slack — its title band
-* abuts the label box exactly — so without reserving it here a wide tick number
-* runs straight into the rotated title, and the two axes visibly disagree.
-*/
-var AXIS_TITLE_GAP = 8;
-/** Default approximate tick count on the value axis. */
+/** @internal Gap between the plot's bottom edge and the category labels. */
+var CATEGORY_AXIS_LABEL_GAP = AXIS_LABEL_GAP;
+/** @internal Height of the category label box: one caption line, so the label gap is the visible gap. */
+var CATEGORY_AXIS_LABEL_HEIGHT = CAPTION_LINE;
+/** @internal Space below the plot: label gap + label line. */
+var PLOT_INSET_BOTTOM = CATEGORY_AXIS_LABEL_GAP + CATEGORY_AXIS_LABEL_HEIGHT;
+/** @internal Band reserved for an axis title: a caption line with 2px of air each side, so a rotated title stays inside the chart. */
+var AXIS_TITLE_BAND = px(SPACE[16]);
+/** @internal Clear space between an axis title and its tick labels. */
+var AXIS_TITLE_GAP = AXIS_LABEL_GAP;
+/** @internal Minimum distance between value ticks (a caption line plus the label gap): closer ticks are thinned so labels never crowd. */
+var MIN_VALUE_TICK_SPACING = CAPTION_LINE + AXIS_LABEL_GAP;
+/** @internal Default approximate tick count on the value axis. */
 var DEFAULT_VALUE_TICK_COUNT = 5;
-/** Corner radius applied to the outer end of a wide bar, in px. */
-var BAR_RADIUS = 4;
-/** Corner radius for bars narrower than {@link NARROW_BAR_WIDTH}, in px. */
-var BAR_RADIUS_NARROW = 2;
-/** Bars below this width use the smaller radius so the curve doesn't dominate. */
-var NARROW_BAR_WIDTH = 40;
-/**
-* Px shaved off a stacked segment's covered edge to separate it from its
-* neighbour.
-*
-* Keep this a whole number. The geometry snaps every stack boundary to a whole
-* pixel first, so an integer gap renders at exactly the same size at every seam;
-* a fractional one would land differently against the device pixel grid from one
-* boundary to the next and read as uneven.
-*
-* Applied to every segment except the one sitting on the baseline, so each seam
-* gets a gap and the bar still meets the axis flush.
-*/
-var STACK_SEGMENT_GAP = 2;
-/** Minimum rendered height for a non-zero bar, in px. */
-var MIN_BAR_LENGTH = 2;
-/**
-* Target gaps in px between groups, and between bars within a group.
-*
-* The within-group gap must stay clearly smaller than the between-group gap —
-* that ratio is the only thing making a group read as a group. When the two are
-* close, the eye has nothing to bind a group's bars together and the chart reads
-* as one long row of unrelated bars.
-*/
-var GROUP_GAP_COMFORTABLE = 24;
-var BAR_GAP_COMFORTABLE = 6;
-var GROUP_GAP_MEDIUM = 16;
-var BAR_GAP_MEDIUM = 4;
-var GROUP_GAP_TIGHT = 12;
-var BAR_GAP_TIGHT = 3;
-/**
-* Fraction of its available slot a bar actually fills.
-*
-* Bars sized to consume every last pixel of their group read as heavy, and the
-* chart becomes a wall of colour rather than a set of measurements. Holding them
-* back leaves air on both sides of each group without touching the gap between
-* neighbouring bars.
-*/
-var BAR_WIDTH_RATIO = .8;
-/**
-* Ceiling on a single bar's thickness, in px.
-*
-* Without it a two- or three-category chart divides the whole plot between a
-* handful of bars and produces slabs — the width stops carrying information the
-* moment it exceeds what the eye needs to compare heights.
-*/
-var MAX_BAR_WIDTH = 44;
-/** Below this many bars the chart always uses comfortable spacing. */
-var MIN_BARS_FOR_TIGHT_SPACING = 13;
-/**
-* Ceiling on a gap, as a share of the space it divides.
-*
-* The gaps above are absolute pixel values chosen from chart-wide density, which
-* says nothing about how much room a *single* category actually got. Forty
-* categories in a 650px plot leave a 16px step, and a 24px gap subtracted from
-* that goes negative — the width lands on its 1px floor and every bar renders as
-* a hairline. Capping the gap proportionally keeps it honest at any density: it
-* stays exactly as specified whenever there is room, and degrades smoothly when
-* there is not.
-*/
-var MAX_GAP_SHARE = .3;
-/** Plot widths above this stay comfortable; below the tight threshold go tight. */
-var WIDTH_FOR_MEDIUM_SPACING = 650;
-var WIDTH_FOR_TIGHT_SPACING = 500;
-/** Grid lines extend this far past both plot edges, in px. */
-var GRID_LINE_BLEED = 12;
-var DEFAULT_LINE_STROKE_WIDTH = 1.5;
-/** Radius of the dot marking a point on a hovered category, in px. */
+/** @internal Width of one caption character, for arithmetic label sizing (SSR-safe, no DOM). */
+var CAPTION_CHAR_WIDTH_PX = 6.2;
+/** @internal Floor of the auto-sized left gutter. */
+var MIN_AUTO_INSET_LEFT = px(SPACE[32]);
+/** @internal Ceiling of the auto-sized left gutter, so a wide formatter cannot eat the plot (no step). */
+var MAX_AUTO_INSET_LEFT = 96;
+/** @internal The left gutter grows in steps of this, so plots stay aligned across charts. */
+var AUTO_INSET_LEFT_STEP = px(SPACE[8]);
+/** @internal Minimum space between category labels before the axis thins them (rows: one caption line apart). */
+var MIN_CATEGORY_LABEL_GAP = px(SPACE[8]);
+/** @internal Insets around a radial plot, which draws no axes. */
+var RADIAL_PLOT_INSET = px(SPACE[8]);
+/** @internal Every line's stroke width (no stroke token; the 1.x weight). */
+var LINE_STROKE_WIDTH = 1.5;
+/** @internal Radius of a point dot (the 1.x dot; no step). */
 var LINE_POINT_RADIUS = 3.5;
-/** Opacity of the area fill under a line. */
-var LINE_AREA_OPACITY = .12;
-/** Gap between slices, in radians. */
-var PIE_PAD_ANGLE = .012;
-/** Slice corner radius in px. */
-var PIE_CORNER_RADIUS = 2;
-/** Inner radius as a fraction of the outer radius, for donut mode. */
-var PIE_DONUT_INNER_RATIO = .62;
-/**
-* Share of the narrowest slice that its two inner pad insets may consume.
-*
-* d3 turns {@link PIE_PAD_ANGLE} into a *constant linear* gap, and holding that
-* width at radius `r` costs an angular inset of `asin(gap / 2r)` — unbounded as
-* `r` approaches zero. When the two insets no longer fit inside a slice's own
-* span, d3 collapses that slice's inner edge rather than sweeping backwards. The
-* collapse is what makes a hole-less pie look wrong: the gap edge stops being
-* radial, so gaps sit at visibly different widths and lean at slight angles, and
-* it bites hardest between the *narrowest* slices, where the span runs out
-* first.
-*
-* So the inner radius is solved for rather than guessed: pick the radius that
-* keeps both insets inside the narrowest slice, with this much of it spent. At
-* 0.7 the measured gap spread is 1.01× (against 1.46× when the inner edge is
-* left to collapse), and the remaining 30% is what absorbs the corner radius.
-*/
-var PIE_MAX_INSET_SHARE = .7;
-/**
-* Ceiling on the auto-derived inner radius, as a share of the outer radius.
-*
-* The radius needed grows without bound as the narrowest slice shrinks, so a
-* single sliver would otherwise turn a pie into a donut. Past this point the
-* hole is doing more visual damage than the uneven gap it fixes, so the gap is
-* allowed to degrade instead — never worse than it renders today.
-*/
-var PIE_MAX_AUTO_INNER_RATIO = .06;
-/** How far outside the arc the tooltip anchors, in px. */
-var PIE_TOOLTIP_ANCHOR_INSET = 8;
-/**
-* Default share below which a slice is folded into an "Other" bucket.
-*
-* Slivers this thin are unreadable and effectively unhoverable, so grouping
-* them communicates more than rendering each faithfully.
-*/
-var PIE_MIN_SLICE_SHARE = .02;
-/** React key used for the bucket that absorbs slices below the fold threshold. */
-var AGGREGATED_SLICE_KEY = "__other__";
-/** Margin around a pie, which needs no axis gutters. */
-var PIE_CHART_MARGIN = {
-	top: 8,
-	right: 8,
-	bottom: 8,
-	left: 8
-};
-/**
-* Duration in ms for the tooltip's fade and glide.
-*
-* Sits inside the 75–150ms band the DLS uses everywhere else. Only the tooltip
-* transitions — mark and legend emphasis snaps, because emphasis is feedback
-* and feedback that eases in reads as lag.
-*/
-var CHART_TRANSITION_MS = 100;
-/**
-* Opacity ramp for the mark states.
-*
-* The grammar is inherited from the reference charts and is the opposite of the
-* obvious one: hovering does not brighten the hovered mark, it *softens*
-* everything else. `MUTED` applies to marks outside the hovered category or
-* series.
-*
-* The step down from ACTIVE is deliberately steep. These are large filled areas
-* — bars and arcs — and a filled shape still reads as present at an opacity
-* where a hairline would have vanished, so a timid step barely registers as a
-* highlight at all.
-*/
+/** @internal Dash and gap of a dashed line. */
+var LINE_DASH = px(SPACE[4]);
+/** @internal Opacity of an area fill (1.x `LINE_AREA_OPACITY`). */
+var AREA_FILL_OPACITY = .12;
+/** @internal Opacity of a stacked area band: bands never overlap, so they carry a firmer fill (AreaChart). */
+var AREA_STACKED_FILL_OPACITY = .24;
+/** @internal Opacity of `ChartMarkState.ACTIVE`. */
 var CHART_MARK_OPACITY_ACTIVE = 1;
+/** @internal Opacity of `ChartMarkState.MUTED`: steep, so a filled mark visibly recedes. */
 var CHART_MARK_OPACITY_MUTED = .1;
-/**
-* The whisper tier, for `ChartMarkState.DIMMED`.
-*
-* Deliberately far gentler than MUTED: it is used where another affordance —
-* BarChart's cursor band — already marks the hovered category, so the
-* off-category marks only need to step back, not disappear.
-*/
+/** @internal Opacity of `ChartMarkState.DIMMED`: a whisper, where a cursor band already highlights. */
 var CHART_MARK_OPACITY_DIMMED = .4;
-/** Distance in px between the tooltip and its anchor. */
-var CHART_TOOLTIP_OFFSET = 10;
-/** Minimum width of the tooltip, in px. */
-var CHART_TOOLTIP_MIN_WIDTH = 200;
-/** Maximum width of the tooltip, in px. */
-var CHART_TOOLTIP_MAX_WIDTH = 320;
-/** Gap in px between the plot box and a side-placed legend. */
-var CHART_LEGEND_SIDE_GAP = 16;
-/**
-* Spacing in px between entries in a horizontal legend.
-*
-* Applied as each entry's *trailing padding*, not a flex gap on the row: a gap
-* is dead space between hover targets, and sweeping across it drops the series
-* isolation between every pair of entries. Because the padding lives inside
-* the entries, measured entry sizes already include the spacing and the fit
-* computation needs no separate gap term.
-*/
-var CHART_LEGEND_COLUMN_GAP = 16;
-/** Spacing in px between entries in a vertical legend. Same contract as
-* {@link CHART_LEGEND_COLUMN_GAP}: trailing padding on the entry, no flex gap. */
-var CHART_LEGEND_VERTICAL_GAP = 8;
-/**
-* Ceiling on the collapsed-legend popover's height, in px.
-*
-* Roughly eight entries. Past that the list scrolls rather than growing into a
-* popover taller than the chart it annotates — the cap on *visible* entries is
-* the caller's `legendMaxItems`; this one only bounds the overflow list itself.
-*/
+/** @internal Corner radius on the outer end of a wide bar. */
+var BAR_RADIUS = px(RADIUS.md);
+/** @internal Corner radius of a bar narrower than `NARROW_BAR_WIDTH`. */
+var BAR_RADIUS_NARROW = px(RADIUS.sm);
+/** @internal Bars below this width use the smaller radius (1.x). */
+var NARROW_BAR_WIDTH = 40;
+/** @internal Seam between stacked segments; whole pixels so every seam renders alike. */
+var STACK_SEGMENT_GAP = px(SPACE[2]);
+/** @internal Minimum drawn length of a non-zero bar. */
+var MIN_BAR_LENGTH = px(SPACE[2]);
+/**
+* @internal The gap between categories as a share of the category band. Gaps are proportional so
+* a narrow chart keeps its bars; this share and the in-group one below reproduce the 1.x look at
+* 480px and up, where the bars also hit their 44px ceiling or the gaps hit theirs.
+*/
+var CATEGORY_GAP_RATIO = .35;
+/** @internal Floor of the category gap, so neighbouring categories never touch. */
+var MIN_CATEGORY_GAP = px(SPACE[2]);
+/**
+* @internal Ceiling of the category gap. 1.x drew 24px plus 20% of each bar slot as air, so a wide
+* grouped chart showed ~40px between groups; this ceiling keeps that look.
+*/
+var MAX_CATEGORY_GAP = px(SPACE[48]);
+/** @internal The gap between bars in a group as a share of one bar's slot (the group gap binds a group). */
+var BAR_GAP_RATIO = .2;
+/** @internal Floor of the in-group gap: one hairline of air (no step). */
+var MIN_BAR_GAP = 1;
+/** @internal Ceiling of the in-group gap (the 1.x gap). */
+var MAX_BAR_GAP = px(SPACE[4]);
+/** @internal Gap between heatmap cells as a share of a cell's step: proportional, like the bar gaps. */
+var HEATMAP_CELL_GAP_RATIO = .1;
+/** @internal Floor of the heatmap cell gap: one hairline of air (no step). */
+var MIN_HEATMAP_CELL_GAP = 1;
+/** @internal Ceiling of the heatmap cell gap (the 1.x gap). */
+var MAX_HEATMAP_CELL_GAP = px(SPACE[2]);
+/** @internal Width of the seam between pie slices, constant in pixels at any radius (the stack seam). */
+var PIE_SLICE_GAP = STACK_SEGMENT_GAP;
+/** @internal Distance between the tooltip and its anchor. */
+var CHART_TOOLTIP_OFFSET = px(SPACE[8]);
+/** @internal Rows the built-in tooltip body shows before "+N more". */
+var CHART_TOOLTIP_MAX_ROWS = 8;
+/** @internal Gap between the plot box and a side-placed legend. */
+var CHART_LEGEND_SIDE_GAP = px(SPACE[16]);
+/** @internal Height cap of the "+N more" legend list (about eight entries) before it scrolls. */
 var CHART_LEGEND_OVERFLOW_MAX_HEIGHT = 208;
-/**
-* Floor on the collapsed-legend popover's width, in px, measured as the full
-* popover box — the list inside subtracts the Tooltip's 8px inset per side.
-* Without one, a couple of short labels shrink-wrap into a scrunched box.
-*/
-var CHART_LEGEND_OVERFLOW_MIN_WIDTH = 160;
-/**
-* Approximate width of one CAPTION-size character.
-*
-* Axis sizing estimates label widths arithmetically rather than measuring the
-* DOM, so it stays correct during build-time evaluation and server rendering.
-*/
-var CAPTION_CHAR_WIDTH_PX = 6.2;
-/** Ceiling for an auto-sized left margin, so a wide formatter can't eat the plot. */
-var MAX_AUTO_MARGIN_LEFT = 96;
-/**
-* Floor for an auto-sized left margin.
-*
-* Enough for a two- or three-character tick plus {@link VALUE_AXIS_TICK_GAP}, so
-* an axis labelled `0`–`5` still has its numbers clear of the container edge
-* rather than jammed against it.
-*/
-var MIN_AUTO_MARGIN_LEFT = 32;
-/**
-* Quantum for an auto-sized left margin, in px.
-*
-* Sizing the gutter to the widest tick means the plot origin moves whenever that
-* label's width changes — live data crossing 999 → 1000 gains a digit and would
-* shift every mark sideways. Rounding up to a step absorbs that: the margin only
-* moves when a label crosses a real threshold, and two charts with similar ticks
-* land on the *same* value, so stacked charts in a dashboard keep their plots
-* aligned instead of each choosing its own origin.
-*/
-var AUTO_MARGIN_LEFT_STEP = 8;
-/** Minimum px between category labels before AUTO mode starts skipping them. */
-var MIN_CATEGORY_LABEL_GAP = 8;
-/**
-* Default assignment order for series colors.
-*
-* Purple leads to match the Galaxy brand. Galaxy blue is deliberately absent —
-* it is structural only, reserved for primary actions and selection.
-*/
-var CHART_PALETTE_ORDER = [
-	ChartPalette.PURPLE,
-	ChartPalette.PINK,
-	ChartPalette.BLUE,
-	ChartPalette.TEAL,
-	ChartPalette.LIME,
-	ChartPalette.ORANGE,
-	ChartPalette.YELLOW,
-	ChartPalette.GREEN,
-	ChartPalette.RED
-];
+/** @internal 2:1, the aspect-ratio fallback of cartesian charts and PieChart. */
+var CHART_DEFAULT_ASPECT_RATIO = 2;
 //#endregion
-export { AGGREGATED_SLICE_KEY, AUTO_MARGIN_LEFT_STEP, AXIS_TITLE_BAND, AXIS_TITLE_GAP, BAR_GAP_COMFORTABLE, BAR_GAP_MEDIUM, BAR_GAP_TIGHT, BAR_RADIUS, BAR_RADIUS_NARROW, BAR_WIDTH_RATIO, CAPTION_CHAR_WIDTH_PX, CATEGORY_AXIS_LABEL_GAP, CATEGORY_AXIS_LABEL_HEIGHT, CHART_LEGEND_COLUMN_GAP, CHART_LEGEND_OVERFLOW_MAX_HEIGHT, CHART_LEGEND_OVERFLOW_MIN_WIDTH, CHART_LEGEND_SIDE_GAP, CHART_LEGEND_VERTICAL_GAP, CHART_MARK_OPACITY_ACTIVE, CHART_MARK_OPACITY_DIMMED, CHART_MARK_OPACITY_MUTED, CHART_PALETTE_ORDER, CHART_TOOLTIP_MAX_WIDTH, CHART_TOOLTIP_MIN_WIDTH, CHART_TOOLTIP_OFFSET, CHART_TRANSITION_MS, DEFAULT_CHART_MARGIN, DEFAULT_LINE_STROKE_WIDTH, DEFAULT_VALUE_TICK_COUNT, GRID_LINE_BLEED, GROUP_GAP_COMFORTABLE, GROUP_GAP_MEDIUM, GROUP_GAP_TIGHT, LINE_AREA_OPACITY, LINE_POINT_RADIUS, MAX_AUTO_MARGIN_LEFT, MAX_BAR_WIDTH, MAX_GAP_SHARE, MIN_AUTO_MARGIN_LEFT, MIN_BARS_FOR_TIGHT_SPACING, MIN_BAR_LENGTH, MIN_CATEGORY_LABEL_GAP, NARROW_BAR_WIDTH, PIE_CHART_MARGIN, PIE_CORNER_RADIUS, PIE_DONUT_INNER_RATIO, PIE_MAX_AUTO_INNER_RATIO, PIE_MAX_INSET_SHARE, PIE_MIN_SLICE_SHARE, PIE_PAD_ANGLE, PIE_TOOLTIP_ANCHOR_INSET, STACK_SEGMENT_GAP, VALUE_AXIS_LABEL_HEIGHT, VALUE_AXIS_TICK_GAP, WIDTH_FOR_MEDIUM_SPACING, WIDTH_FOR_TIGHT_SPACING };
+export { AREA_FILL_OPACITY, AREA_STACKED_FILL_OPACITY, AUTO_INSET_LEFT_STEP, AXIS_LABEL_GAP, AXIS_TITLE_BAND, AXIS_TITLE_GAP, BAR_GAP_RATIO, BAR_RADIUS, BAR_RADIUS_NARROW, CAPTION_CHAR_WIDTH_PX, CAPTION_LINE, CATEGORY_AXIS_LABEL_GAP, CATEGORY_AXIS_LABEL_HEIGHT, CATEGORY_GAP_RATIO, CHART_DEFAULT_ASPECT_RATIO, CHART_LEGEND_OVERFLOW_MAX_HEIGHT, CHART_LEGEND_SIDE_GAP, CHART_MARK_OPACITY_ACTIVE, CHART_MARK_OPACITY_DIMMED, CHART_MARK_OPACITY_MUTED, CHART_TOOLTIP_MAX_ROWS, CHART_TOOLTIP_OFFSET, DEFAULT_VALUE_TICK_COUNT, GRID_LINE_BLEED, HEATMAP_CELL_GAP_RATIO, LINE_DASH, LINE_POINT_RADIUS, LINE_STROKE_WIDTH, MAX_AUTO_INSET_LEFT, MAX_BAR_GAP, MAX_CATEGORY_GAP, MAX_HEATMAP_CELL_GAP, MIN_AUTO_INSET_LEFT, MIN_BAR_GAP, MIN_BAR_LENGTH, MIN_CATEGORY_GAP, MIN_CATEGORY_LABEL_GAP, MIN_HEATMAP_CELL_GAP, MIN_VALUE_TICK_SPACING, NARROW_BAR_WIDTH, PIE_SLICE_GAP, PLOT_INSET_BOTTOM, PLOT_INSET_RIGHT, PLOT_INSET_TOP, RADIAL_PLOT_INSET, STACK_SEGMENT_GAP, VALUE_AXIS_LABEL_HEIGHT, VALUE_AXIS_TICK_GAP };

package/dist/charts/heatmapGeometry.d.ts

@@ -0,0 +1,95 @@
+import { ChartPalette } from "./types.js";
+/** @internal Cell corner radius: `radius.sm`. */
+export declare const HEATMAP_CELL_RADIUS: number;
+/** @internal Number of ramp steps. */
+export declare const HEATMAP_STEP_COUNT = 5;
+/** @internal The aspect-ratio fallback is clamped to these, so cells stay near-square. */
+export declare const HEATMAP_MIN_ASPECT_RATIO = 1;
+/** @internal Upper bound of the aspect-ratio fallback. */
+export declare const HEATMAP_MAX_ASPECT_RATIO = 4;
+/** @internal Five ramp steps, lowest first. */
+export type HeatmapRamp = readonly [string, string, string, string, string];
+/** @internal Palette slot → its five-step ramp (`PRIMARY` / `SECONDARY` / `TERTIARY` → hues, never gray). */
+export declare const HEATMAP_STEP_TO_TOKEN_MAP: Record<ChartPalette, HeatmapRamp>;
+/** @internal The data a cell needs (Heatmap's `HeatmapCellDatum`, structurally). */
+export interface HeatmapGeometryCell {
+    /** Column label. */
+    column: string;
+    /** Row label. */
+    row: string;
+    /** Reading, or `null` for none. */
+    value: number | null;
+}
+/** @internal Labels in first-seen order, unless given. */
+export declare function getHeatmapLabels(cells: HeatmapGeometryCell[], explicitColumns?: string[], explicitRows?: string[]): {
+    columns: string[];
+    rows: string[];
+};
+/** @internal `[min, max]` of the ramp: the non-null extent, overridden by `valueDomain`. */
+export declare function getHeatmapDomain(cells: HeatmapGeometryCell[], override?: {
+    min?: number | undefined;
+    max?: number | undefined;
+}): [number, number];
+/**
+ * @internal The ramp step of a value: equal intervals over `[min, max]`, clamped to 0–4; every
+ * value is step 2 when the domain has no width.
+ */
+export declare function getHeatmapStep(value: number, [min, max]: [number, number]): number;
+/**
+ * @internal Left gutter that fits the widest row label (the value gutter's rule, plus one
+ * character: row labels are words, whose capitals run wider than the digit estimate).
+ */
+export declare function estimateRowLabelInset(labels: string[]): number;
+/** @internal One cell, resolved to pixels. Flat index = `rowIndex * columns + columnIndex`. */
+export interface HeatmapCell {
+    /** React key. */
+    id: string;
+    /** Column index. */
+    columnIndex: number;
+    /** Row index. */
+    rowIndex: number;
+    /** Column label. */
+    column: string;
+    /** Row label. */
+    row: string;
+    /** Reading, or `null` (no entry, or `value: null`). */
+    value: number | null;
+    /** Ramp step 0–4 (`null` for an empty cell). */
+    step: number | null;
+    /** Left edge. */
+    x: number;
+    /** Top edge. */
+    y: number;
+    /** Width. */
+    width: number;
+    /** Height. */
+    height: number;
+}
+/** @internal The finished geometry. */
+export interface HeatmapGeometry {
+    /** Every cell, row-major. */
+    cells: HeatmapCell[];
+    /** Column step (cell width + gap). */
+    columnStep: number;
+    /** Row step (cell height + gap). */
+    rowStep: number;
+    /** Leading edge of each column's slot (cell x − half a gap), for the axis. */
+    columnPositions: number[];
+    /** Leading edge of each row's slot, for the axis. */
+    rowPositions: number[];
+    /** Gap between neighbouring columns, px (whole). */
+    gapX: number;
+    /** Gap between neighbouring rows, px (whole). */
+    gapY: number;
+    /** Any cell without a reading. */
+    hasEmptyCells: boolean;
+}
+/** @internal Builds a heatmap's cells. */
+export declare function buildHeatmapGeometry({ cells, columns, rows, domain, plotWidth, plotHeight, }: {
+    cells: HeatmapGeometryCell[];
+    columns: string[];
+    rows: string[];
+    domain: [number, number];
+    plotWidth: number;
+    plotHeight: number;
+}): HeatmapGeometry;

package/dist/charts/heatmapGeometry.js

@@ -0,0 +1,155 @@
+import { RADIUS } from "../theme/tokens/scales.js";
+import { t } from "../theme/tokens/t.js";
+import { ChartPalette } from "./types.js";
+import { AUTO_INSET_LEFT_STEP, CAPTION_CHAR_WIDTH_PX, HEATMAP_CELL_GAP_RATIO, MAX_HEATMAP_CELL_GAP, MIN_AUTO_INSET_LEFT, VALUE_AXIS_TICK_GAP } from "./constants.js";
+import { clamp, sanitizeValue } from "./chartScales.js";
+import { CHART_PALETTE_TO_HUE_MAP } from "./chartPalette.js";
+//#region src/charts/heatmapGeometry.ts
+/**
+* @internal Heatmap geometry and color ramp (Heatmap). Cells sit on whole pixels with a
+* proportional gap (about 10% of a cell's step, 1–2px); each filled cell takes one of five token steps of its hue's ramp, quantized at
+* equal intervals over the value domain. Pure: no React. The ramp is `t.*` strings
+* (`var(--gx-…)`, one `color-mix` of two), so it follows the theme.
+*/
+/** @internal Cell corner radius: `radius.sm`. */
+var HEATMAP_CELL_RADIUS = Number.parseFloat(RADIUS.sm);
+/** @internal Number of ramp steps. */
+var HEATMAP_STEP_COUNT = 5;
+/** @internal The aspect-ratio fallback is clamped to these, so cells stay near-square. */
+var HEATMAP_MIN_ASPECT_RATIO = 1;
+/** @internal Upper bound of the aspect-ratio fallback. */
+var HEATMAP_MAX_ASPECT_RATIO = 4;
+/**
+* The five token steps of one ramp, monotonic away from the canvas in both themes: the soft
+* tint, halfway to the border, the border, the solid fill, and the solid fill a quarter of the way
+* to `text.primary` (away from the canvas: lighter in dark, darker in light). Not the solid's
+* `hovered`, which moves away from its own text color and so toward the canvas for some hues.
+*/
+function rampOf(hue) {
+	return [
+		t.color.background[hue],
+		`color-mix(in srgb, ${t.color.background[hue]}, ${t.color.border[hue]})`,
+		t.color.border[hue],
+		t.color.solid[hue].background,
+		`color-mix(in oklch, ${t.color.solid[hue].background}, ${t.color.text.primary} 25%)`
+	];
+}
+/** @internal Palette slot → its five-step ramp (`PRIMARY` / `SECONDARY` / `TERTIARY` → hues, never gray). */
+var HEATMAP_STEP_TO_TOKEN_MAP = Object.fromEntries(Object.values(ChartPalette).map((palette) => [palette, rampOf(CHART_PALETTE_TO_HUE_MAP[palette])]));
+/** @internal Labels in first-seen order, unless given. */
+function getHeatmapLabels(cells, explicitColumns, explicitRows) {
+	const firstSeen = (pick) => {
+		const seen = /* @__PURE__ */ new Set();
+		for (const cell of cells) seen.add(pick(cell));
+		return [...seen];
+	};
+	return {
+		columns: explicitColumns ?? firstSeen((cell) => cell.column),
+		rows: explicitRows ?? firstSeen((cell) => cell.row)
+	};
+}
+/** @internal `[min, max]` of the ramp: the non-null extent, overridden by `valueDomain`. */
+function getHeatmapDomain(cells, override) {
+	let min = Number.POSITIVE_INFINITY;
+	let max = Number.NEGATIVE_INFINITY;
+	for (const cell of cells) {
+		if (cell.value === null || !Number.isFinite(cell.value)) continue;
+		min = Math.min(min, cell.value);
+		max = Math.max(max, cell.value);
+	}
+	if (min > max) {
+		min = 0;
+		max = 0;
+	}
+	return [override?.min ?? min, override?.max ?? max];
+}
+/**
+* @internal The ramp step of a value: equal intervals over `[min, max]`, clamped to 0–4; every
+* value is step 2 when the domain has no width.
+*/
+function getHeatmapStep(value, [min, max]) {
+	if (max === min) return 2;
+	return clamp(Math.floor((value - min) / (max - min) * 5), 0, 4);
+}
+/**
+* @internal Left gutter that fits the widest row label (the value gutter's rule, plus one
+* character: row labels are words, whose capitals run wider than the digit estimate).
+*/
+function estimateRowLabelInset(labels) {
+	let widest = 0;
+	for (const label of labels) widest = Math.max(widest, (label.length + 1) * CAPTION_CHAR_WIDTH_PX);
+	const needed = Math.ceil(widest) + VALUE_AXIS_TICK_GAP;
+	return clamp(Math.ceil(needed / AUTO_INSET_LEFT_STEP) * AUTO_INSET_LEFT_STEP, MIN_AUTO_INSET_LEFT, 96);
+}
+/**
+* `count` cells across `length` px: the gap is `HEATMAP_CELL_GAP_RATIO` of the step, rounded and
+* clamped to 1–2px (0 when a cell would drop under 1px); every edge snaps to a whole pixel and the
+* gaps stay equal, so the grid reads as even rules.
+*/
+function layoutCellTrack(count, length) {
+	const step = length / count;
+	let gap = count > 1 ? clamp(Math.round(step * HEATMAP_CELL_GAP_RATIO), 1, MAX_HEATMAP_CELL_GAP) : 0;
+	if (step - gap < 1) gap = 0;
+	const pitch = (length + gap) / count;
+	const starts = [];
+	const sizes = [];
+	for (let index = 0; index < count; index += 1) {
+		const start = Math.round(index * pitch);
+		const end = Math.round((index + 1) * pitch) - gap;
+		starts.push(start);
+		sizes.push(Math.max(1, end - start));
+	}
+	return {
+		starts,
+		sizes,
+		step: pitch,
+		gap
+	};
+}
+/** @internal Builds a heatmap's cells. */
+function buildHeatmapGeometry({ cells, columns, rows, domain, plotWidth, plotHeight }) {
+	const values = /* @__PURE__ */ new Map();
+	for (const cell of cells) values.set(`${cell.column}\u0000${cell.row}`, cell.value === null ? null : sanitizeValue(cell.value));
+	let hasEmptyCells = false;
+	for (const row of rows) for (const column of columns) if ((values.get(`${column}\u0000${row}`) ?? null) === null) hasEmptyCells = true;
+	const geometry = {
+		cells: [],
+		columnStep: 0,
+		rowStep: 0,
+		columnPositions: [],
+		rowPositions: [],
+		gapX: 0,
+		gapY: 0,
+		hasEmptyCells
+	};
+	if (columns.length === 0 || rows.length === 0 || plotWidth <= 0 || plotHeight <= 0) return geometry;
+	const x = layoutCellTrack(columns.length, plotWidth);
+	const y = layoutCellTrack(rows.length, plotHeight);
+	geometry.columnStep = x.step;
+	geometry.rowStep = y.step;
+	geometry.gapX = x.gap;
+	geometry.gapY = y.gap;
+	geometry.columnPositions = x.starts.map((start) => start - x.gap / 2);
+	geometry.rowPositions = y.starts.map((start) => start - y.gap / 2);
+	rows.forEach((row, rowIndex) => {
+		columns.forEach((column, columnIndex) => {
+			const value = values.get(`${column}\u0000${row}`) ?? null;
+			geometry.cells.push({
+				id: `${rowIndex}:${columnIndex}`,
+				columnIndex,
+				rowIndex,
+				column,
+				row,
+				value,
+				step: value === null ? null : getHeatmapStep(value, domain),
+				x: x.starts[columnIndex] ?? 0,
+				y: y.starts[rowIndex] ?? 0,
+				width: x.sizes[columnIndex] ?? 0,
+				height: y.sizes[rowIndex] ?? 0
+			});
+		});
+	});
+	return geometry;
+}
+//#endregion
+export { HEATMAP_CELL_RADIUS, HEATMAP_MAX_ASPECT_RATIO, HEATMAP_MIN_ASPECT_RATIO, HEATMAP_STEP_COUNT, HEATMAP_STEP_TO_TOKEN_MAP, buildHeatmapGeometry, estimateRowLabelInset, getHeatmapDomain, getHeatmapLabels, getHeatmapStep };