@fundar/data-chart-telling 1.15.0 → 1.17.0

package/dist/types/plots/part-of-a-whole/treemap/props.js

@@ -0,0 +1 @@
+export {};

package/dist/types/plots/part-of-a-whole/treemap/state.d.ts

@@ -0,0 +1,6 @@
+import type { BarSegmentStyle } from '../../segments/common';
+import type { AxisPlotState, AxisPlotCtx } from '../../../phases';
+/** TreemapPlot's pipeline state: the shared axis-based state, over a unit square its tiles are laid out in. */
+export type TreemapPlotState<TData extends Record<string, unknown>> = AxisPlotState<TData, BarSegmentStyle>;
+/** The environment every TreemapPlot phase reads from, alongside the growing state. */
+export type TreemapPlotCtx = AxisPlotCtx;

package/dist/types/plots/part-of-a-whole/treemap/state.js

@@ -0,0 +1 @@
+export {};

package/dist/types/plots/props.d.ts

@@ -1,6 +1,6 @@
 import type { Pipeline } from '../../phases/Pipeline';
 import type { Snippet } from 'svelte';
-import type { TooltipOptions, TooltipProp } from '../layout/tooltip';
+import type { TooltipContext, TooltipOptions, TooltipProp } from '../layout/tooltip';
 import type { HoverPoint, HoverStrategy } from '../layout/hover';
 import type { LegendExtension, LegendSection } from '../layout/legend';
 import type { FacetConfig, FacetScoped } from '../layout/facet';
@@ -188,9 +188,12 @@ export type FigureBoxProps = GridPlacement & {
     width?: number;
     height?: number;
 };
-/** A plot component's public props: its core props, chrome, `timeline`, `facet` and an author-facing `tooltip`. */
-export type BasePlotProps<TDataContract, TRow extends Record<string, unknown>, TStyles extends object, TSegmentStyle extends object, TMarker, TScales extends ScalesConfig<TRow>, TCoordinates = undefined> = TDataContract & Omit<PlotCommonProps<TStyles, TSegmentStyle, TMarker, TScales, TCoordinates>, 'width' | 'height'> & FigureBoxProps & PlotChromeProps & {
-    tooltip?: TooltipProp<TRow>;
+/**
+ * A plot component's public props: its core props, chrome, `timeline`, `facet` and an author-facing `tooltip`,
+ * whose `format` gets the kind's `TTooltipContext`.
+ */
+export type BasePlotProps<TDataContract, TRow extends Record<string, unknown>, TStyles extends object, TSegmentStyle extends object, TMarker, TScales extends ScalesConfig<TRow>, TCoordinates = undefined, TTooltipContext extends TooltipContext = TooltipContext> = TDataContract & Omit<PlotCommonProps<TStyles, TSegmentStyle, TMarker, TScales, TCoordinates>, 'width' | 'height'> & FigureBoxProps & PlotChromeProps & {
+    tooltip?: TooltipProp<TRow, TTooltipContext>;
     timeline?: TimelineConfig<TRow>;
     facet?: FacetConfig<TRow>;
 };

package/dist/types/plots/ranking/bar/props.d.ts

@@ -1,10 +1,10 @@
 import type { BasePlotProps, PlotCoreProps } from '../../props';
 import type { AxisBasedScalesConfig } from '../../../layout/scales';
 import type { AxisBasedMarkersConfig } from '../../../markers/common';
-import type { SeriesProps, DataProps } from '../../data/common';
+import type { SeriesProps, DualAxisDataProps } from '../../data/common';
 import type { GapsAwarePlotStylesConfig } from '../../../layout/styles';
 import type { BarSegmentStyle } from '../../segments/common';
 /** `BarPlot`'s public props. */
-export type BarPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DataProps<TData>, TData, GapsAwarePlotStylesConfig<BarSegmentStyle>, BarSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+export type BarPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, GapsAwarePlotStylesConfig<BarSegmentStyle>, BarSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
 /** What `BarPlot`'s core draws from. */
-export type BarPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DataProps<TData>, TData, GapsAwarePlotStylesConfig<BarSegmentStyle>, BarSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+export type BarPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, GapsAwarePlotStylesConfig<BarSegmentStyle>, BarSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;

package/dist/types/plots/ranking/cleveland/props.d.ts

@@ -1,10 +1,10 @@
 import type { BasePlotProps, PlotCoreProps } from '../../props';
 import type { AxisBasedScalesConfig } from '../../../layout/scales';
 import type { AxisBasedMarkersConfig } from '../../../markers/common';
-import type { SeriesProps, DataProps } from '../../data/common';
+import type { SeriesProps, DualAxisDataProps } from '../../data/common';
 import type { ConnectorBasedStylesConfig } from '../../../layout/styles';
 import type { LineSegmentStyle } from '../../segments/common';
 /** `ClevelandPlot`'s public props. */
-export type ClevelandPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DataProps<TData>, TData, ConnectorBasedStylesConfig, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+export type ClevelandPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, ConnectorBasedStylesConfig, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
 /** What `ClevelandPlot`'s core draws from. */
-export type ClevelandPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DataProps<TData>, TData, ConnectorBasedStylesConfig, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+export type ClevelandPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, ConnectorBasedStylesConfig, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;

package/dist/types/plots/ranking/dumbbell/props.d.ts

@@ -1,10 +1,10 @@
 import type { BasePlotProps, PlotCoreProps } from '../../props';
 import type { AxisBasedScalesConfig } from '../../../layout/scales';
 import type { AxisBasedMarkersConfig } from '../../../markers/common';
-import type { SeriesProps, DataProps } from '../../data/common';
+import type { SeriesProps, DualAxisDataProps } from '../../data/common';
 import type { ConnectorBasedStylesConfig } from '../../../layout/styles';
 import type { LineSegmentStyle } from '../../segments/common';
 /** `DumbbellPlot`'s public props. */
-export type DumbbellPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DataProps<TData>, TData, ConnectorBasedStylesConfig, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+export type DumbbellPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, ConnectorBasedStylesConfig, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
 /** What `DumbbellPlot`'s core draws from. */
-export type DumbbellPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DataProps<TData>, TData, ConnectorBasedStylesConfig, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+export type DumbbellPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, ConnectorBasedStylesConfig, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;

package/dist/types/plots/ranking/forest/props.d.ts

@@ -1,7 +1,7 @@
 import type { BasePlotProps, PlotCoreProps } from '../../props';
 import type { AxisBasedScalesConfig } from '../../../layout/scales';
 import type { AxisBasedMarkersConfig } from '../../../markers/common';
-import type { SeriesProps, DataProps, Accessor } from '../../data/common';
+import type { SeriesProps, DualAxisDataProps, Accessor } from '../../data/common';
 import type { ConnectorBasedStylesConfig } from '../../../layout/styles';
 import type { LineSegmentStyle } from '../../segments/common';
 /**
@@ -18,6 +18,6 @@ export type ForestIntervalProps<TData extends Record<string, unknown>> = {
     error?: Accessor<TData, number>;
 };
 /** `ForestPlot`'s public props. */
-export type ForestPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DataProps<TData>, TData, ConnectorBasedStylesConfig, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>> & ForestIntervalProps<TData>;
+export type ForestPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, ConnectorBasedStylesConfig, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>> & ForestIntervalProps<TData>;
 /** What `ForestPlot`'s core draws from. */
-export type ForestPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DataProps<TData>, TData, ConnectorBasedStylesConfig, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>> & ForestIntervalProps<TData>;
+export type ForestPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, ConnectorBasedStylesConfig, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>> & ForestIntervalProps<TData>;

package/dist/types/plots/ranking/lollipop/props.d.ts

@@ -1,10 +1,10 @@
 import type { BasePlotProps, PlotCoreProps } from '../../props';
 import type { AxisBasedScalesConfig } from '../../../layout/scales';
 import type { AxisBasedMarkersConfig } from '../../../markers/common';
-import type { SeriesProps, DataProps } from '../../data/common';
+import type { SeriesProps, DualAxisDataProps } from '../../data/common';
 import type { ConnectorBasedStylesConfig } from '../../../layout/styles';
 import type { LineSegmentStyle } from '../../segments/common';
 /** `LollipopPlot`'s public props. */
-export type LollipopPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DataProps<TData>, TData, ConnectorBasedStylesConfig, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+export type LollipopPlotProps<TData extends Record<string, unknown>> = BasePlotProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, ConnectorBasedStylesConfig, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
 /** What `LollipopPlot`'s core draws from. */
-export type LollipopPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DataProps<TData>, TData, ConnectorBasedStylesConfig, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+export type LollipopPlotCoreProps<TData extends Record<string, unknown>> = PlotCoreProps<SeriesProps<TData> | DualAxisDataProps<TData>, TData, ConnectorBasedStylesConfig, LineSegmentStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;

package/dist/types/plots/styling.d.ts

@@ -53,3 +53,27 @@ export type AreaStyle = {
     strokeDasharray?: string | LineStyle;
     borderRadius?: number;
 };
+/** How far a shape is pulled in from its edges, in pixels (a bar's, as a fraction of its band): `inset` on all sides, or each side's own. */
+export type InsetStyle = {
+    inset?: number;
+    insetTop?: number;
+    insetRight?: number;
+    insetBottom?: number;
+    insetLeft?: number;
+};
+/** How far a shape with a direction (an arrow) is pulled in from its ends, in pixels: `inset` at both, or `insetStart` and `insetEnd` each. */
+export type DirectedInsetStyle = {
+    inset?: number;
+    insetStart?: number;
+    insetEnd?: number;
+};
+/**
+ * A style as a value, or as a function of the row a shape draws - a different value for each one.
+ * A number can also be the name of a field of the rows; so can a color, when the rows have a field
+ * of that name.
+ */
+export type RowValue<T> = T | (T extends number ? string : never) | ((row: any) => T);
+/** A style whose every field can be a function of the row ({@link RowValue}). */
+export type PerRow<TStyle> = {
+    [K in keyof TStyle]?: RowValue<NonNullable<TStyle[K]>>;
+};

package/dist/types/transforms/index.d.ts

@@ -12,6 +12,7 @@ import type { SortTransform, ShuffleTransform, ReverseTransform } from './sort';
 import type { FilterTransform } from './filter';
 import type { SelectTransform, SelectShorthandTransform } from './select';
 import type { GroupXTransform, GroupYTransform, GroupZTransform, Group2DTransform } from './group';
+import type { TreemapTransform } from './treemap';
 export type { TransformChannel, TransformReducer, PositionChannels } from './common';
 export type { StackXTransform, StackYTransform, StackMosaicXTransform, StackMosaicYTransform } from './stack';
 export type { BinXTransform, BinYTransform, Bin2DTransform } from './bin';
@@ -27,10 +28,11 @@ export type { SortBy, SortTransform, ShuffleTransform, ReverseTransform } from '
 export type { FilterTransform } from './filter';
 export type { SelectBy, SelectTransform, SelectShorthandTransform } from './select';
 export type { GroupXTransform, GroupYTransform, GroupZTransform, Group2DTransform } from './group';
+export type { TreemapTile, TreemapTransform } from './treemap';
 /**
  * Every svelteplot transform a marker (via `CommonMarkerConfig.transforms`) or
  * a plot (via its `transforms` prop) can run on its rows before they're drawn.
  * Each one is a flat object: `type` picks the transform, and the rest are its
  * own channels and options, by svelteplot's own names.
  */
-export type MarkerTransform = StackYTransform | StackXTransform | StackMosaicXTransform | StackMosaicYTransform | BinXTransform | BinYTransform | Bin2DTransform | DensityXTransform | DensityYTransform | WindowXTransform | WindowYTransform | BollingerXTransform | BollingerYTransform | NormalizeXTransform | NormalizeYTransform | NormalizeParallelXTransform | NormalizeParallelYTransform | MapXTransform | MapYTransform | IntervalXTransform | IntervalYTransform | JitterXTransform | JitterYTransform | ShiftXTransform | ShiftYTransform | SortTransform | ShuffleTransform | ReverseTransform | FilterTransform | SelectTransform | SelectShorthandTransform | GroupXTransform | GroupYTransform | GroupZTransform | Group2DTransform;
+export type MarkerTransform = StackYTransform | StackXTransform | StackMosaicXTransform | StackMosaicYTransform | BinXTransform | BinYTransform | Bin2DTransform | DensityXTransform | DensityYTransform | WindowXTransform | WindowYTransform | BollingerXTransform | BollingerYTransform | NormalizeXTransform | NormalizeYTransform | NormalizeParallelXTransform | NormalizeParallelYTransform | MapXTransform | MapYTransform | IntervalXTransform | IntervalYTransform | JitterXTransform | JitterYTransform | ShiftXTransform | ShiftYTransform | SortTransform | ShuffleTransform | ReverseTransform | FilterTransform | SelectTransform | SelectShorthandTransform | GroupXTransform | GroupYTransform | GroupZTransform | Group2DTransform | TreemapTransform;

package/dist/types/transforms/treemap.d.ts

@@ -0,0 +1,32 @@
+import type { TransformChannel } from './common';
+/** How a treemap splits a rectangle among its children. */
+export type TreemapTile = 'squarify' | 'binary' | 'slice' | 'dice' | 'sliceDice';
+/** Channels the treemap reads: the rows, and each one's `value` - what its tile's area is. */
+export type TreemapChannels = {
+    data?: Record<string, unknown>[];
+    value?: TransformChannel;
+};
+/** The keys of {@link TreemapChannels}, at runtime. */
+export declare const TREEMAP_CHANNEL_KEYS: Record<keyof TreemapChannels, true>;
+/** Options the treemap takes, flat next to the channels. */
+type TreemapOptions = {
+    /**
+     * What the tiles nest by: one reader per level, outermost first. Rows with the same value at every
+     * level are one tile, whose area is their values' sum, and the last level names it. Without levels,
+     * every row is part of a single tile.
+     */
+    levels?: TransformChannel[];
+    /** How a rectangle is split among its tiles. Defaults to `'squarify'`, which keeps them close to squares. */
+    tile?: TreemapTile;
+    /** The width over the height of the box the tiles fill, which squarified tiles aim to be square in. Defaults to `1`. */
+    aspect?: number;
+};
+/**
+ * `treemap` as a marker transform: a tile per distinct path of `levels`, laid out in the unit square with
+ * d3-hierarchy, its area its summed `value`. Produces `x1`/`x2`/`y1`/`y2` for a `rect` marker, and `x`/`y`
+ * at each tile's centre; each row also carries its tile's name, path, value and share (see `TREEMAP_ROW`).
+ */
+export type TreemapTransform = {
+    type: 'treemap';
+} & TreemapChannels & TreemapOptions;
+export {};

package/dist/types/transforms/treemap.js

@@ -0,0 +1,5 @@
+/** The keys of {@link TreemapChannels}, at runtime. */
+export const TREEMAP_CHANNEL_KEYS = {
+    data: true,
+    value: true
+};

package/dist/utils/color/ColorTones.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Tones of a color, and the colors of a hierarchy made of them: each outermost value keeps its categorical
+ * color, and the values under it take tones of it, so the parts of one group read as one family. For any plot
+ * whose rows nest (a treemap, an icicle, a sunburst, a map of the votes of several parties).
+ */
+export declare class ColorTones {
+    /** How far the lightest tone goes from the color toward white. */
+    static readonly LIGHTEST = 0.6;
+    /** `count` tones of `color`: the color itself first, then lighter ones; a single one is the color itself. */
+    static of(color: string, count: number): string[];
+    /**
+     * The color of every path of a hierarchy, its levels outermost first, colored down to level `depth`: the
+     * outermost value takes the color `colorOf` gives it, and each distinct path down to `depth` under it a
+     * tone of that color - the first of them the color itself - siblings next to each other in the order they
+     * first appear. `depth` 1 is the
+     * outermost color alone; a path shorter than `depth` is colored by all of it.
+     */
+    static hierarchy(paths: readonly (readonly string[])[], depth: number, colorOf: (outermost: string) => string): (path: readonly string[]) => string;
+}

package/dist/utils/color/ColorTones.js

@@ -0,0 +1,64 @@
+import { interpolateLab, interpolateRgb } from 'd3-interpolate';
+import { CssColor } from './CssColor';
+/**
+ * Tones of a color, and the colors of a hierarchy made of them: each outermost value keeps its categorical
+ * color, and the values under it take tones of it, so the parts of one group read as one family. For any plot
+ * whose rows nest (a treemap, an icicle, a sunburst, a map of the votes of several parties).
+ */
+export class ColorTones {
+    /** How far the lightest tone goes from the color toward white. */
+    static LIGHTEST = 0.6;
+    /** `count` tones of `color`: the color itself first, then lighter ones; a single one is the color itself. */
+    static of(color, count) {
+        const base = CssColor.resolve(color);
+        if (count <= 1)
+            return count === 1 ? [base] : [];
+        const ramp = interpolateLab(base, interpolateRgb(base, '#fff')(ColorTones.LIGHTEST));
+        return Array.from({ length: count }, (_, i) => (i === 0 ? base : ramp(i / (count - 1))));
+    }
+    /**
+     * The color of every path of a hierarchy, its levels outermost first, colored down to level `depth`: the
+     * outermost value takes the color `colorOf` gives it, and each distinct path down to `depth` under it a
+     * tone of that color - the first of them the color itself - siblings next to each other in the order they
+     * first appear. `depth` 1 is the
+     * outermost color alone; a path shorter than `depth` is colored by all of it.
+     */
+    static hierarchy(paths, depth, colorOf) {
+        const keyOf = (path) => JSON.stringify(path.slice(0, Math.max(1, Math.floor(depth))));
+        if (depth <= 1)
+            return (path) => colorOf(path[0]);
+        // Where each partial path first appears, so siblings sort together and in the data's own order.
+        const first = new Map();
+        const prefixes = new Map();
+        for (const path of paths) {
+            const own = JSON.parse(keyOf(path));
+            own.forEach((_, i) => {
+                const partial = JSON.stringify(own.slice(0, i + 1));
+                if (!first.has(partial))
+                    first.set(partial, first.size);
+            });
+            prefixes.set(keyOf(path), own);
+        }
+        const rank = (path) => path.map((_, i) => first.get(JSON.stringify(path.slice(0, i + 1))) ?? 0);
+        const byOutermost = new Map();
+        for (const prefix of prefixes.values()) {
+            const group = byOutermost.get(prefix[0]) ?? [];
+            group.push(prefix);
+            byOutermost.set(prefix[0], group);
+        }
+        const colors = new Map();
+        for (const [outermost, group] of byOutermost) {
+            group.sort((a, b) => {
+                const [ra, rb] = [rank(a), rank(b)];
+                for (let i = 0; i < Math.max(ra.length, rb.length); i++) {
+                    if ((ra[i] ?? -1) !== (rb[i] ?? -1))
+                        return (ra[i] ?? -1) - (rb[i] ?? -1);
+                }
+                return 0;
+            });
+            const tones = ColorTones.of(colorOf(outermost), group.length);
+            group.forEach((prefix, i) => colors.set(JSON.stringify(prefix), tones[i]));
+        }
+        return (path) => colors.get(keyOf(path)) ?? colorOf(path[0]);
+    }
+}

package/dist/utils/color/CssColor.d.ts

@@ -8,12 +8,21 @@ export declare class CssColor {
     static parse(color: string): Rgb | null;
     /** WCAG contrast ratio between two colors, from 1 (no contrast) to 21 (black on white). */
     static contrastRatio(colorA: string, colorB: string): number;
+    /** The WCAG 2 AA contrast ratio for normal text. */
+    static readonly AA = 4.5;
     /**
-     * The `candidates` entry with the highest WCAG contrast ratio against
-     * `background`. Defaults to plain white/black; pass a grayscale or other
-     * palette to widen the choice. Falls back to the first candidate when
-     * `background` can't be parsed.
+     * The `candidates` entry with the highest WCAG contrast ratio against an opaque `background`. Defaults to plain
+     * white/black; pass a grayscale or other palette to widen the choice. When none reaches `minRatio` (WCAG AA for
+     * normal text by default), white or black is taken instead, whichever reads better - one of them always reaches
+     * 4.5 on an opaque color. Falls back to the first candidate when `background` can't be parsed.
      */
-    static contrastText(background: string, candidates?: string[]): string;
+    static contrastText(background: string, candidates?: string[], minRatio?: number): string;
+    /** The opacity of a CSS color, from 0 to 1: its alpha (`rgba()`, `#rrggbbaa`...), 0 for `transparent`, else 1. */
+    static alpha(color: string): number;
+    /**
+     * The opaque color `color` is seen as, drawn at `opacity` (times its own alpha) over `backdrop`, as a browser
+     * blends it. A backdrop that is not opaque counts as white, the page under it. `color` as it is when unreadable.
+     */
+    static composite(color: string, opacity?: number, backdrop?: string): string;
 }
 export {};

package/dist/utils/color/CssColor.js

@@ -13,17 +13,9 @@ export class CssColor {
     }
     /** Parses any CSS color syntax (hex, rgb(), oklch(), named colors, hsl(), ...) into an `[r, g, b]` (0-255) triple, or `null` if it can't be resolved. */
     static parse(color) {
-        const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(color.trim());
-        if (hex) {
-            const digits = hex[1].length === 3
-                ? hex[1]
-                    .split('')
-                    .map((c) => c + c)
-                    .join('')
-                : hex[1];
-            const num = parseInt(digits, 16);
-            return [(num >> 16) & 255, (num >> 8) & 255, num & 255];
-        }
+        const hex = CssColor.#hex(color);
+        if (hex)
+            return [hex[0], hex[1], hex[2]];
         const rgb = /^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)/i.exec(color);
         if (rgb)
             return [Number(rgb[1]), Number(rgb[2]), Number(rgb[3])];
@@ -53,30 +45,80 @@ export class CssColor {
         const lB = CssColor.#luminance(b);
         return (Math.max(lA, lB) + 0.05) / (Math.min(lA, lB) + 0.05);
     }
+    /** The WCAG 2 AA contrast ratio for normal text. */
+    static AA = 4.5;
     /**
-     * The `candidates` entry with the highest WCAG contrast ratio against
-     * `background`. Defaults to plain white/black; pass a grayscale or other
-     * palette to widen the choice. Falls back to the first candidate when
-     * `background` can't be parsed.
+     * The `candidates` entry with the highest WCAG contrast ratio against an opaque `background`. Defaults to plain
+     * white/black; pass a grayscale or other palette to widen the choice. When none reaches `minRatio` (WCAG AA for
+     * normal text by default), white or black is taken instead, whichever reads better - one of them always reaches
+     * 4.5 on an opaque color. Falls back to the first candidate when `background` can't be parsed.
      */
-    static contrastText(background, candidates = ['#ffffff', '#000000']) {
+    static contrastText(background, candidates = ['#ffffff', '#000000'], minRatio = CssColor.AA) {
+        const best = (colors) => colors.reduce((top, color) => {
+            const ratio = CssColor.contrastRatio(background, color);
+            return ratio > top.ratio ? { color, ratio } : top;
+        }, { color: colors[0], ratio: -Infinity });
         if (candidates.length === 0)
             return '#000000';
-        let best = candidates[0];
-        let bestRatio = -Infinity;
-        for (const candidate of candidates) {
-            const ratio = CssColor.contrastRatio(background, candidate);
-            if (ratio > bestRatio) {
-                bestRatio = ratio;
-                best = candidate;
-            }
-        }
-        return best;
+        const own = best(candidates);
+        if (own.ratio >= minRatio)
+            return own.color;
+        const plain = best(['#ffffff', '#000000']);
+        return plain.ratio > own.ratio ? plain.color : own.color;
+    }
+    /** The opacity of a CSS color, from 0 to 1: its alpha (`rgba()`, `#rrggbbaa`...), 0 for `transparent`, else 1. */
+    static alpha(color) {
+        const trimmed = CssColor.resolve(color).trim();
+        if (trimmed === 'transparent')
+            return 0;
+        const hex = CssColor.#hex(trimmed);
+        if (hex)
+            return hex[3];
+        const own = /^(?:rgba?|hsla?|oklch|oklab|lab|lch)\(([^)]*)\)$/i.exec(trimmed);
+        if (!own)
+            return 1;
+        const parts = own[1].split(/[\s,/]+/).filter(Boolean);
+        const slashed = own[1].includes('/');
+        const value = slashed || parts.length === 4 ? parts.at(-1) : undefined;
+        if (value === undefined)
+            return 1;
+        const alpha = value.endsWith('%') ? Number(value.slice(0, -1)) / 100 : Number(value);
+        return Number.isFinite(alpha) ? Math.max(0, Math.min(1, alpha)) : 1;
+    }
+    /**
+     * The opaque color `color` is seen as, drawn at `opacity` (times its own alpha) over `backdrop`, as a browser
+     * blends it. A backdrop that is not opaque counts as white, the page under it. `color` as it is when unreadable.
+     */
+    static composite(color, opacity = 1, backdrop = '#ffffff') {
+        const own = CssColor.parse(CssColor.resolve(color));
+        if (!own)
+            return color;
+        const alpha = Math.max(0, Math.min(1, CssColor.alpha(color) * opacity));
+        if (alpha >= 1)
+            return `rgb(${own.join(', ')})`;
+        const under = CssColor.alpha(backdrop) >= 1 ? CssColor.parse(CssColor.resolve(backdrop)) : undefined;
+        const base = under ?? [255, 255, 255];
+        const mixed = own.map((c, i) => Math.round(c * alpha + base[i] * (1 - alpha)));
+        return `rgb(${mixed.join(', ')})`;
+    }
+    /** A hex color's `[r, g, b]` (0-255) and alpha (0-1), in its 3, 4, 6 or 8 digit form. */
+    static #hex(color) {
+        const match = /^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.exec(color.trim());
+        if (!match)
+            return null;
+        const digits = match[1].length <= 4
+            ? match[1]
+                .split('')
+                .map((c) => c + c)
+                .join('')
+            : match[1];
+        const byte = (i) => parseInt(digits.slice(i, i + 2), 16);
+        return [byte(0), byte(2), byte(4), digits.length === 8 ? byte(6) / 255 : 1];
     }
     static #luminance([r, g, b]) {
         const [rs, gs, bs] = [r, g, b].map((c) => {
             const s = c / 255;
-            return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+            return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
         });
         return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
     }

package/dist/utils/color/index.d.ts

@@ -1,7 +1,9 @@
 export { CssColor } from './CssColor';
 export { ColorRamp } from './ColorRamp';
 export { Palette } from './Palette';
+export { ColorTones } from './ColorTones';
 import { ColorRamp } from './ColorRamp';
+import { ColorTones } from './ColorTones';
 export declare const resolveCssColor: (color: string) => string;
 export declare const contrastRatio: (colorA: string, colorB: string) => number;
 export declare const contrastTextColor: (background: string, candidates?: string[]) => string;
@@ -9,3 +11,5 @@ export declare const normalize: (v: number, min: number, max: number) => number;
 export declare const makeColorScale: (min: number, max: number, colorMin: string, colorMax: string) => (v: number) => string;
 export declare const resolveColorScale: typeof ColorRamp.resolve;
 export declare const paletteColor: (index: number, palette: string[]) => string;
+export declare const colorTones: (color: string, count: number) => string[];
+export declare const hierarchicalColors: typeof ColorTones.hierarchy;

package/dist/utils/color/index.js

@@ -1,9 +1,11 @@
 export { CssColor } from './CssColor';
 export { ColorRamp } from './ColorRamp';
 export { Palette } from './Palette';
+export { ColorTones } from './ColorTones';
 import { CssColor } from './CssColor';
 import { ColorRamp } from './ColorRamp';
 import { Palette } from './Palette';
+import { ColorTones } from './ColorTones';
 // The package's public function names, over the classes above.
 export const resolveCssColor = (color) => CssColor.resolve(color);
 export const contrastRatio = (colorA, colorB) => CssColor.contrastRatio(colorA, colorB);
@@ -12,3 +14,5 @@ export const normalize = (v, min, max) => ColorRamp.normalize(v, min, max);
 export const makeColorScale = (min, max, colorMin, colorMax) => ColorRamp.between(min, max, colorMin, colorMax);
 export const resolveColorScale = ColorRamp.resolve;
 export const paletteColor = (index, palette) => Palette.at(index, palette);
+export const colorTones = (color, count) => ColorTones.of(color, count);
+export const hierarchicalColors = ColorTones.hierarchy;

package/dist/utils/grouping.d.ts

@@ -1,5 +1,22 @@
-import type { AxisValue } from '../types/layout/mapping';
+import type { AxisValue, GroupingAccessor } from '../types/layout/mapping';
 import type { Series, Accessor } from '../types/plots/data/common';
+/**
+ * A plot's `grouping`, read into its levels. A dotted name is a field of the rows when they have one by that
+ * name, and the fields of its levels otherwise. Rows grouped by several levels make one key of them, dotted
+ * too (`'Tertiary.Finance'`), which is how `segments` names them.
+ */
+export declare class Grouping {
+    /** The separator between the levels of a grouping, and of the key they make together. */
+    static readonly SEPARATOR = ".";
+    /** The levels `grouping` names, outermost first: none when it is unset. */
+    static levels<TRow extends Record<string, unknown>>(grouping: GroupingAccessor<TRow> | undefined, rows?: readonly TRow[]): Accessor<TRow, unknown>[];
+    /**
+     * The key rows split into series by: a single level as it is - a field stays its name - and several as
+     * the key their values make together. `nested` takes the outermost level alone, for a plot that draws
+     * the inner ones itself (a treemap).
+     */
+    static key<TRow extends Record<string, unknown>>(grouping: GroupingAccessor<TRow> | undefined, rows?: readonly TRow[], nested?: boolean): Accessor<TRow, unknown> | undefined;
+}
 /**
  * Splits rows into ordered groups keyed by the stringified accessor value.
  * Insertion order of first appearance is preserved, which keeps colours stable

package/dist/utils/grouping.js

@@ -1,4 +1,35 @@
 import { resolveAccessor } from './accessors';
+/**
+ * A plot's `grouping`, read into its levels. A dotted name is a field of the rows when they have one by that
+ * name, and the fields of its levels otherwise. Rows grouped by several levels make one key of them, dotted
+ * too (`'Tertiary.Finance'`), which is how `segments` names them.
+ */
+export class Grouping {
+    /** The separator between the levels of a grouping, and of the key they make together. */
+    static SEPARATOR = '.';
+    /** The levels `grouping` names, outermost first: none when it is unset. */
+    static levels(grouping, rows = []) {
+        if (grouping === undefined)
+            return [];
+        if (typeof grouping !== 'string' || !grouping.includes(Grouping.SEPARATOR))
+            return [grouping];
+        if (rows.some((row) => grouping in row))
+            return [grouping];
+        return grouping.split(Grouping.SEPARATOR);
+    }
+    /**
+     * The key rows split into series by: a single level as it is - a field stays its name - and several as
+     * the key their values make together. `nested` takes the outermost level alone, for a plot that draws
+     * the inner ones itself (a treemap).
+     */
+    static key(grouping, rows = [], nested = false) {
+        const levels = Grouping.levels(grouping, rows);
+        if (levels.length <= 1 || nested)
+            return levels[0];
+        const reads = levels.map((level) => resolveAccessor(level));
+        return (row) => reads.map((read) => String(read(row))).join(Grouping.SEPARATOR);
+    }
+}
 /**
  * Splits rows into ordered groups keyed by the stringified accessor value.
  * Insertion order of first appearance is preserved, which keeps colours stable

package/docs/concepts.md

@@ -39,13 +39,14 @@ A **channel** maps a field of each row to a visual property. Each channel takes
 | ---------- | ----------------------------------------------------------- | ---------------------- |
 | `x`, `y`   | Position on the horizontal and vertical axis                | `scales.x`, `scales.y` |
 | `color`    | A color: categorical (one per value) or continuous (a ramp) | `scales.color`         |
-| `grouping` | Which series the row belongs to                             | `scales.grouping`      |
+| `grouping` | Which series the row belongs to (`'a.b'`: several levels)   | `scales.grouping`      |
 | `opacity`  | A fill or stroke opacity                                    | `scales.opacity`       |
 | `symbol`   | A marker shape (categorical)                                | `scales.symbol`        |
 | `r`        | A dot radius, scaled so that area follows the value         | `scales.r`             |
 | `length`   | A vector or spike length                                    | `scales.length`        |
+| `value`    | What a row amounts to as a part of a whole (a treemap tile) | -                      |
 
-`grouping` splits `data` into series. When it is unset, `color` groups too, so one accessor both separates and colors the series - the usual case. Pass both to group by one field and color by another:
+`grouping` splits `data` into series. Fields joined by dots are one grouping of several levels, outermost first: a plot that nests its rows ([TreemapPlot](plots/part-of-a-whole/treemap.md)) nests them by those levels, and any other splits them by the combination of the levels (`'region.sex'` is one series per region and sex, named `'CABA.F'`, which is how `segments` keys it). A dotted name is a field when the rows have one by that name; a function is a single level. When it is unset, `color` groups too, so one accessor both separates and colors the series - the usual case. Pass both to group by one field and color by another:
 
 ```svelte
 <ScatterPlot data={rows} x="gdp" y="life" grouping="country" color="temperature" {width} {height} />

package/docs/legend.md

@@ -71,11 +71,14 @@ Items become clickable with `interactive` on the series section. `disabled` says
 
 ![Legend items as toggles](images/legend-toggle.png)
 
-| `disabled.mode`   | A hidden series...                                                                    |
-| ----------------- | ------------------------------------------------------------------------------------- |
-| `'dim'` (default) | stays, faded (`style` sets how: opacity, fill, ...; default `legend.disabledOpacity`) |
-| `'hide'`          | becomes transparent, the axes keep its range                                          |
-| `'omit'`          | is removed and the axes refit to the rest                                             |
+| `disabled.mode`   | A hidden series...                                                                     |
+| ----------------- | -------------------------------------------------------------------------------------- |
+| `'dim'` (default) | stays, faded (`style` sets how: opacity, fill, ...; default `legend.disabledOpacity`)  |
+| `'hide'`          | becomes transparent, the axes keep its range                                           |
+| `'omit'`          | is removed and the axes refit to the rest; a part of a whole keeps its share and place |
+| `'rescale'`       | is removed, and the parts left make the whole again (see below)                        |
+
+A plot uses one mode for all its series. `'omit'` and `'rescale'` differ on a plot of parts of a whole. With `'omit'` the other parts keep their values: a stack closes over the hidden series and its top drops, and a [treemap](plots/part-of-a-whole/treemap.md)'s tiles keep their place and their share of the whole economy, leaving the room empty. With `'rescale'` the parts left are the new 100%: each category of a stack (`stackY`/`stackX`) is scaled back up to the total it had, and a treemap's tiles fill the plot again, each share of what is left. On any other plot, `'rescale'` is an `'omit'`.
 
 `interactive.legendStyle` is `'badge'` (default: pills filled with the series color and an eye toggle) or `'basic'` (swatches). `showIcon` toggles the symbol in a badge.