@sophistry/charts 0.0.0-stage → 0.0.1

package/dist/band.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"band.d.ts","sourceRoot":"","sources":["../src/band.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAE1E;;;;;;GAMG;AACH,wBAAgB,UAAU,CACzB,IAAI,EAAE,SAAS,GAAG,SAAS,EAC3B,KAAK,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CAMpB;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CACvB,IAAI,EAAE,SAAS,GAAG,SAAS,EAC3B,KAAK,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,GAC/B,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAI9B;AAED,kHAAkH;AAClH,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,GAAG,OAAO,CAE7D"}

package/dist/bars/bar-chart.d.ts

@@ -0,0 +1,144 @@
+/**
+ * `barChart`: a one-series categorical bar chart with names underneath, as
+ * its own plot: a `chart` whose children are a `bars` layer, the names (an
+ * internal `BarNames` layer of label nodes) and the user's children.
+ */
+import type { AxisOptions, CoordinateSystem, SceneNode } from "@sophistry/core";
+import type { ColorInput } from "@sophistry/core/color";
+import type { Bounds, Point, Range } from "@sophistry/core/geometry";
+import type { Channel, ColorChannel } from "../data/channels";
+import type { TransitionProps } from "../props";
+/**
+ * What {@link barChartHandle} hands back: bar boxes in scene units, and the chart's coordinate system.
+ *
+ * @category Charts
+ */
+export interface BarChartHandle {
+    /** How many bars there are — `data.length`. */
+    count(): number;
+    /**
+     * One bar's box in scene units, or null if the index is out of range. Feed it to `nextTo` or
+     * `surroundingRectangle` to annotate a bar.
+     */
+    barBounds(index: number): Bounds | null;
+    /** The chart's coordinate system: x is the slot index, y the value. */
+    coords: CoordinateSystem;
+}
+/**
+ * Props of {@link barChart}: `value` is required unless `data` is `number[]`.
+ *
+ * @category Charts
+ */
+export interface BarChartProps<T = unknown> extends TransitionProps<T> {
+    /** One bar per datum. */
+    data: readonly T[];
+    /**
+     * The bar's value, in data units. Defaults to the datum when `data` is `number[]`; required
+     * otherwise. Negative values hang below the baseline; non-finite values leave an empty slot.
+     */
+    value?: Channel<T, number>;
+    /** The name drawn under each bar. Omitted, no names are drawn. */
+    label?: Channel<T, string>;
+    /** `[min, max, step?]` in data units. Omitted, fitted to the data (including 0). */
+    yRange?: Range;
+    /** Width of the plotting area. */
+    width: number;
+    /** Height of the plotting area. */
+    height: number;
+    /** Centre of the plotting area. Defaults to the origin. */
+    center?: Point;
+    /**
+     * Bar width as a fraction of the slot pitch.
+     * @default 0.6
+     */
+    barWidth?: number;
+    /** One colour for every bar, or `(d, i) => colour`. Wins over `colors`. */
+    color?: ColorChannel<T>;
+    /** Colours cycled across the bars by index. Defaults to the theme's categorical colours. */
+    colors?: readonly ColorInput[];
+    /**
+     * Fill opacity, 0..1.
+     * @default 0.75
+     */
+    fillOpacity?: number;
+    /** Outline width of every bar. */
+    barStrokeWidth?: number;
+    /**
+     * The value axis: `false` hides it; an object styles it and sets its ticks.
+     * @default true
+     */
+    yAxis?: boolean | AxisOptions;
+    /**
+     * Whether to draw the line the bars stand on.
+     * @default true
+     */
+    baseline?: boolean;
+    /**
+     * Font size of the bar labels.
+     * @default 0.28
+     */
+    labelFontSize?: number;
+    /**
+     * Gap between the baseline (or a negative bar's bottom) and its label.
+     * @default 0.16
+     */
+    labelGap?: number;
+    /**
+     * Reveal, 0..1: the axis, baseline and labels first, then each bar grows out of the baseline.
+     * @default 1
+     * @see https://sophistry.dev/guides/chart-animation/#reveals
+     */
+    progress?: number;
+    /**
+     * The data to transition to, bars matched by `label` (else index): they slide to their new slot
+     * and value; new ones grow in, removed ones shrink away. A sort is a transition to the same
+     * data reordered. See {@link TransitionProps}.
+     * @see https://sophistry.dev/guides/chart-animation/#data-transitions
+     */
+    to?: readonly T[];
+    /**
+     * Fraction of a transition's enter stage spent staggering entering bars (and their labels). See
+     * {@link TransitionProps}.
+     * @default 0
+     */
+    enterStagger?: number;
+    /** Paint order; higher draws later. */
+    zIndex?: number;
+    visible?: boolean;
+    /** Placed inside the chart's coordinate context. */
+    children?: readonly SceneNode[];
+}
+/**
+ * A `barChart` node's handle, as of its last
+ * update.
+ *
+ * @param node - A node made by {@link barChart}.
+ * @returns The handle, or null for a node that is not a `barChart`.
+ * @category Charts
+ */
+export declare function barChartHandle(node: SceneNode): BarChartHandle | null;
+/**
+ * A one-series categorical bar chart with names underneath, as its own plot
+ * sized by `width`/`height` (not inside an `axes` or `chart`). Children
+ * share its coordinates: slot `i` is centred at `i + 0.5`. For horizontal,
+ * stacked or multi-layer bars use a `chart` with {@link bars}, which this is
+ * built from.
+ *
+ * @example
+ * ```ts
+ * import { createScene } from "@sophistry/core";
+ * import { barChart } from "@sophistry/charts";
+ *
+ * const scene = createScene({ host: document.querySelector("#figure")!, units: 10 });
+ * const sales = [
+ * 	{ quarter: "Q1", units: 120 },
+ * 	{ quarter: "Q2", units: 90 },
+ * ];
+ * scene.add(barChart.create({ data: sales, value: "units", label: "quarter", width: 8, height: 4 }));
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#bars
+ * @category Charts
+ */
+export declare const barChart: import("@sophistry/core").Definition<BarChartProps<any>, import("@sophistry/core/internal").CompositeNode<BarChartProps<any>>, keyof BarChartProps<any>>;
+//# sourceMappingURL=bar-chart.d.ts.map

package/dist/bars/bar-chart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bar-chart.d.ts","sourceRoot":"","sources":["../../src/bars/bar-chart.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACX,WAAW,EAEX,gBAAgB,EAEhB,SAAS,EACT,MAAM,iBAAiB,CAAC;AASzB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAW,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAI9E,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAQ9D,OAAO,KAAK,EAAY,eAAe,EAAE,MAAM,UAAU,CAAC;AAQ1D;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,+CAA+C;IAC/C,KAAK,IAAI,MAAM,CAAC;IAChB;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACxC,uEAAuE;IACvE,MAAM,EAAE,gBAAgB,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,eAAe,CAAC,CAAC,CAAC;IACrE,yBAAyB;IACzB,IAAI,EAAE,SAAS,CAAC,EAAE,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAC3B,kEAAkE;IAClE,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAC3B,oFAAoF;IACpF,MAAM,CAAC,EAAE,KAAK,CAAC;IACf,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,MAAM,CAAC,EAAE,KAAK,CAAC;IACf;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IACxB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAC/B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,GAAG,WAAW,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,EAAE,CAAC,EAAE,SAAS,CAAC,EAAE,CAAC;IAClB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;CAChC;AAmBD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,GAAG,cAAc,GAAG,IAAI,CAYrE;AA+FD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,QAAQ,0JAsDnB,CAAC"}

package/dist/bars/bar-labels.d.ts

@@ -0,0 +1,117 @@
+/**
+ * `bars` `labels`: what each bar's value label and its stack's total write,
+ * where they sit (past the bar's growing end, or inside it when it fits),
+ * and the label props that draw them. Pure: `bars` builds one entry per
+ * label on each update and keeps the label nodes in a keyed list.
+ */
+import type { CoordinateSystem, LabelProps } from "@sophistry/core";
+import type { ColorInput } from "@sophistry/core/color";
+import type { Bounds, TickFormatterSpec } from "@sophistry/core/geometry";
+import type { Theme } from "@sophistry/core/themes";
+import type { Channel, ChannelFn } from "../data/channels";
+/**
+ * Where `bars` `labels` are written and how.
+ *
+ * @category Charts
+ */
+export interface BarLabelOptions<T> {
+    /**
+     * Where each bar's label goes: `"inside"` centred in the bar (or its stacked segment), `"edge"`
+     * just past its end, `"none"` for no per-bar labels (e.g. only `total`).
+     * @default "inside"
+     */
+    position?: "inside" | "edge" | "none";
+    /** Your own text, a key of `T` or `(d, i) => string`, instead of the number. */
+    text?: Channel<T, string>;
+    /**
+     * How the number is written: a format string (`",.0f"`, `".1%"`), a built-in name (`"percent"`,
+     * `"si"`) or a function. Applies to totals too; under `offset="normalize"` segments show their
+     * share as a percent.
+     */
+    format?: TickFormatterSpec;
+    /**
+     * With `layout="stack"`, write each stack's total just past its end.
+     * @default false
+     */
+    total?: boolean;
+    /**
+     * Whether an inside label that doesn't fit its bar is hidden or drawn anyway.
+     * @default "hide"
+     */
+    overflow?: "hide" | "show";
+    /**
+     * Text colour. Defaults to the theme foreground outside the bar, and to whichever of foreground or
+     * background reads better on the fill inside it.
+     */
+    color?: ColorInput;
+    /**
+     * Gap in scene units between an edge label and the bar's end (inside: the room kept from each
+     * edge). Defaults to 0.08 (0.04 inside).
+     */
+    offset?: number;
+}
+/** The label settings every bar of a `bars` shares, for one update. */
+export interface BarLabels<T> {
+    /** `labels` as options: undefined for `true` and a channel (the edge labels). */
+    options: BarLabelOptions<T> | undefined;
+    /** The custom text channel, if any. */
+    custom: ChannelFn<T, string> | undefined;
+    vertical: boolean;
+    /** Where each bar's own label goes. */
+    position: "inside" | "edge" | "none";
+    fontSize: number;
+    fontFamily: string;
+    /** A number as labels write it: the `format`, else a normalized share as a percent, else with `rest`'s decimal places. */
+    writeNumber(shown: number, rest: number, share: boolean): string;
+}
+/** Reads `bars`' label props into the settings every bar shares. */
+export declare function barLabelSettings<T>(spec: {
+    labels: boolean | Channel<T, string> | BarLabelOptions<T> | undefined;
+    labelFontSize: number | undefined;
+    vertical: boolean;
+    coords: CoordinateSystem;
+    theme: Theme;
+    /** Whether the bars are a normalized stack (shares, written as percents). */
+    normalized: boolean;
+}): BarLabels<T>;
+/** What one bar's labels read from it on one frame. */
+export interface BarLabelState<T> {
+    key: unknown;
+    datum: T;
+    index: number;
+    /** The value `labels={true}` writes. */
+    value: number;
+    /** The number option labels write: `value`, or a normalized segment's share. */
+    share: number;
+    /** Its stack's total when it carries it, else undefined. */
+    total: number | undefined;
+    /** 0..1: how present the bar is while entering or leaving. */
+    presence: number;
+    /** The bar as drawn, and at full length on this frame. */
+    grown: Bounds;
+    rest: Bounds | null;
+    /** The bar's fade (1 when opaque). */
+    opacity: number;
+    /** The bar's reveal, 0..1. */
+    t: number;
+    /** A number counted up with the bar's reveal. */
+    counted(value: number): number;
+    color: string;
+    /** True when the bar runs down (or left) from its foot. */
+    backward: boolean;
+    fillOpacity: number;
+}
+/** One label to draw: its key in the list and its props. */
+export interface BarLabelEntry {
+    key: string;
+    props: LabelProps;
+}
+/**
+ * One bar's edge label, inside label and stack total, as label props placed
+ * on its box. Appends to `out`.
+ */
+export declare function barLabelEntries<T>(labels: BarLabels<T>, own: BarLabelState<T>, theme: Theme, layer: {
+    zIndex: number | undefined;
+    visible: boolean | undefined;
+}, out: BarLabelEntry[]): void;
+//# sourceMappingURL=bar-labels.d.ts.map

package/dist/bars/bar-labels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bar-labels.d.ts","sourceRoot":"","sources":["../../src/bars/bar-labels.ts"],"names":[],"mappings":"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"}

package/dist/bars/bars.d.ts

@@ -0,0 +1,224 @@
+/**
+ * `bars`: bars on a categorical axis, one per datum, drawn as one instances
+ * node of `rect`s; their value labels are label nodes in a keyed list.
+ *
+ * Follows the per-datum mark steps of `points/scatter.ts`, with the bar's
+ * own pieces:
+ *
+ * - each dataset becomes a {@link BarSide} (categories, values, bases,
+ *   sub-bands, stacks, totals), cached by its inputs, so a frame of a
+ *   reveal or a blend reuses it;
+ * - the keyed join (`createKeyedData`) pairs bars across `data` and `to`;
+ *   a bar in both slides to its new band and value, a bar only in `to`
+ *   grows out of its foot, one only in `data` shrinks into it (or fades
+ *   when it can't shrink); mid axis-kind swap each end draws through its
+ *   own plot and the boxes blend in scene units;
+ * - the reveal scales each box off its foot (`"grow"`), about zero
+ *   (`"stack"`), or fades it (`"fade"`, or on an axis without zero). It
+ *   is geometry and per-item opacity, so it batches; a bar not started is
+ *   left out of the batch.
+ */
+import type { SceneNode } from "@sophistry/core";
+import type { ColorInput } from "@sophistry/core/color";
+import type { BandKey, Bounds } from "@sophistry/core/geometry";
+import type { MarkTransition } from "../batch";
+import type { Channel, ColorChannel } from "../data/channels";
+import type { StackOffset } from "../math/stack";
+import type { BarReveal, KeyedTransitionProps, RevealProps, StaggerOrder } from "../props";
+import type { TooltipSpec } from "../tooltip";
+import type { BarLabelOptions } from "./bar-labels";
+import type { StackOptions } from "./transforms";
+/**
+ * What {@link barsHandle} hands back.
+ *
+ * @category Charts
+ */
+export interface BarsHandle {
+    /** How many bars there are — `data.length`. */
+    count(): number;
+    /**
+     * One bar's full-height box in scene units, or null if the index is out of range, its value is not
+     * finite, or its category is not on the axis.
+     */
+    barBounds(index: number): Bounds | null;
+}
+/**
+ * Props of {@link bars}: `value` is required unless `data` is `number[]`.
+ *
+ * @category Charts
+ */
+export interface BarsProps<T = unknown> extends KeyedTransitionProps<T>, RevealProps {
+    /** One bar per datum. */
+    data: readonly T[];
+    /** The bar's category: which band it stands in. Defaults to the datum's index. */
+    category?: Channel<T, BandKey>;
+    /**
+     * The bar's value, in data units. Defaults to the datum itself when `data` is `number[]`; required
+     * otherwise. Non-finite values leave the band empty.
+     */
+    value?: Channel<T, number>;
+    /**
+     * `"vertical"` stands bars on a categorical x axis; `"horizontal"` lays them along a categorical y
+     * axis.
+     * @default "vertical"
+     */
+    orientation?: "vertical" | "horizontal";
+    /**
+     * The series each bar belongs to: colours the bars through the chart's shared colour scale and
+     * legend, and is what `layout` stacks or dodges.
+     */
+    series?: Channel<T, BandKey>;
+    /**
+     * Each bar's identity across data changes and transitions. See {@link KeyedTransitionProps}.
+     * Defaults to the datum's place within its `series`, else its index.
+     */
+    key?: Channel<T, BandKey>;
+    /**
+     * How bars sharing a category are arranged: `"overlay"` each fills its band (or `subband`) from
+     * its `base`; `"stack"` end to end by series (negative values stack down; replaces `base`);
+     * `"dodge"` side by side, one sub-band per series (replaces `subband`). Without a `series`, bars
+     * are told apart by their order.
+     * @default "overlay"
+     */
+    layout?: "overlay" | "stack" | "dodge";
+    /**
+     * With `layout="stack"`: `"zero"` or `"normalize"` (shares of the total). See {@link StackOffset}.
+     * @default "zero"
+     */
+    offset?: StackOffset;
+    /**
+     * With `layout="stack"`: which series sits at the bottom: `"appearance"`, `"reverse"`, `"sum"`,
+     * `"insideOut"`, or the series keys bottom to top.
+     * @default "appearance"
+     */
+    order?: StackOptions<T>["order"];
+    /** One colour for every bar, or `(d, i) => colour`. Wins over `colors` and `series`. */
+    color?: ColorChannel<T>;
+    /**
+     * Colours cycled across the bars by index. Wins over `series`. Defaults to the theme's
+     * categorical colours.
+     */
+    colors?: readonly ColorInput[];
+    /**
+     * Fill opacity, 0..1.
+     * @default 0.75
+     */
+    fillOpacity?: number;
+    /** Outline width. */
+    strokeWidth?: number;
+    /**
+     * Where each bar starts, in data units, for floating bars (Gantt spans, waterfall steps). Omitted,
+     * bars start at the baseline and the chart keeps zero in view.
+     */
+    base?: Channel<T, number>;
+    /**
+     * The part `[from, to]` of the category's band the bar fills, as fractions (what {@link dodge}
+     * writes). Omitted, the bar fills its band.
+     */
+    subband?: Channel<T, readonly [number, number]>;
+    /**
+     * How `progress` reveals the bars: `"grow"` out of their foot, `"stack"` the whole stack scaled
+     * about zero together, `"fade"` in at full length. With no zero on the value axis (log or
+     * truncated), bars fade. Defaults to `"grow"` (`"stack"` under `layout="stack"`).
+     * @see https://sophistry.dev/guides/chart-animation/#reveals
+     */
+    reveal?: BarReveal;
+    /**
+     * Value labels: `true` writes each bar's number past its end, a channel writes your own text, and
+     * {@link BarLabelOptions} places and formats them.
+     * @default false
+     */
+    labels?: boolean | Channel<T, string> | BarLabelOptions<T>;
+    /**
+     * Font size of `labels`.
+     * @default 0.24
+     */
+    labelFontSize?: number;
+    /**
+     * Reveal, 0..1: every bar grows out of its baseline (or `base`).
+     * @default 1
+     * @see https://sophistry.dev/guides/chart-animation/#reveals
+     */
+    progress?: number;
+    /**
+     * Fraction of the reveal spent staggering bar after bar, in category order, 0..0.95.
+     * @default 0
+     */
+    stagger?: number;
+    /**
+     * The order `stagger` reveals bars in. See {@link StaggerOrder}.
+     * @default "position"
+     */
+    staggerOrder?: StaggerOrder;
+    /**
+     * Fraction of a transition's enter stage spent staggering entering bars, in `staggerOrder`. See
+     * {@link TransitionProps}.
+     * @default 0
+     */
+    enterStagger?: number;
+    /**
+     * The data to transition to, matched to `data` by `key`: bars slide to their new band and value;
+     * new ones grow from their foot, removed ones shrink into it. See {@link KeyedTransitionProps}.
+     * @see https://sophistry.dev/guides/chart-animation/#data-transitions
+     */
+    to?: readonly T[];
+    /**
+     * Hover tooltip: `true` for a row per channel (`category`, `series`, `value`), or a template,
+     * function or options. See {@link TooltipSpec}.
+     */
+    tooltip?: TooltipSpec<T>;
+    /**
+     * How bars move when `data` changes (outside a `to` blend): a tween or a
+     * spring in the node's tween bank; new bars grow out of their foot,
+     * removed ones shrink into it. Omitted, data changes are instant.
+     */
+    transition?: MarkTransition;
+    /**
+     * Paint order; higher draws later. The bars paint at `zIndex + UNDER_AXES_Z_INDEX` (above the
+     * grid, under the axis they stand on), their labels at `zIndex`.
+     * @default 0
+     */
+    zIndex?: number;
+    visible?: boolean;
+}
+/**
+ * A `bars` node's handle: the bar count and each
+ * bar's full-height box as of its last update.
+ *
+ * @param node - A node made by {@link bars}.
+ * @returns The handle, or null for a node that is not a `bars`.
+ * @category Charts
+ */
+export declare function barsHandle(node: SceneNode): BarsHandle | null;
+/**
+ * Bars on a categorical axis, inside a `chart`: the one bar mark behind
+ * grouped, stacked, normalized, diverging and floating bar charts. Give it
+ * a `series` and a `layout` (or feed it {@link stack} / {@link dodge}
+ * output) for multi-series bars. Drawn as one instances node of rects:
+ * hover and tooltips resolve per bar (`event.key` is the bar's key), and
+ * `transition` tweens or springs bars to new data. `to` + `blend` is the
+ * seekable keyed transition.
+ *
+ * @example
+ * ```ts
+ * import { bars, chart } from "@sophistry/charts";
+ *
+ * const sales = [
+ * 	{ quarter: "Q1", region: "north", units: 3 },
+ * 	{ quarter: "Q1", region: "south", units: 5 },
+ * 	{ quarter: "Q2", region: "north", units: 4 },
+ * 	{ quarter: "Q2", region: "south", units: 2 },
+ * ];
+ * chart.create({
+ * 	width: 6,
+ * 	height: 4,
+ * 	legendTitle: "Region",
+ * 	children: [bars.create({ data: sales, category: "quarter", value: "units", series: "region", layout: "stack" })],
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#bars
+ * @category Charts
+ */
+export declare const bars: import("@sophistry/core").Definition<BarsProps<any>, import("@sophistry/core/internal").CompositeNode<BarsProps<any>>, keyof BarsProps<any>>;
+//# sourceMappingURL=bars.d.ts.map

package/dist/bars/bars.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bars.d.ts","sourceRoot":"","sources":["../../src/bars/bars.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAIX,SAAS,EACT,MAAM,iBAAiB,CAAC;AAQzB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAa,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAE3E,OAAO,KAAK,EAAa,cAAc,EAAE,MAAM,UAAU,CAAC;AAI1D,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAY,MAAM,kBAAkB,CAAC;AAoBxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,KAAK,EAEX,SAAS,EACT,oBAAoB,EACpB,WAAW,EACX,YAAY,EACZ,MAAM,UAAU,CAAC;AAIlB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C,OAAO,KAAK,EAAiB,eAAe,EAAE,MAAM,cAAc,CAAC;AAGnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAKjD;;;;GAIG;AACH,MAAM,WAAW,UAAU;IAC1B,+CAA+C;IAC/C,KAAK,IAAI,MAAM,CAAC;IAChB;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CACxC;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,OAAO,CACrC,SAAQ,oBAAoB,CAAC,CAAC,CAAC,EAC9B,WAAW;IACZ,yBAAyB;IACzB,IAAI,EAAE,SAAS,CAAC,EAAE,CAAC;IACnB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAC/B;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAC3B;;;;OAIG;IACH,WAAW,CAAC,EAAE,UAAU,GAAG,YAAY,CAAC;IACxC;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAC7B;;;OAGG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAC1B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;IACvC;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IACjC,wFAAwF;IACxF,KAAK,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAC/B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qBAAqB;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC;IAC3D;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,EAAE,CAAC,EAAE,SAAS,CAAC,EAAE,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IACzB;;;;OAIG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AA+FD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,IAAI,CAE7D;AAulBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,IAAI,8IAyEf,CAAC"}

package/dist/bars/bullet.d.ts

@@ -0,0 +1,158 @@
+/**
+ * `bullet`: one measure against a target and qualitative ranges per row,
+ * drawn in scene units (no `chart`). The qualitative bands, the measure bars
+ * and the target markers are three instances nodes of `rect`s (they paint
+ * at three depths); titles and tick numbers are label nodes.
+ *
+ * The tooltip overlay is the chart frame's; until a shared one exists,
+ * `bullet` keeps its own tooltip state (the bars' handlers show and hide
+ * it) and draws no panel.
+ */
+import type { SceneNode } from "@sophistry/core";
+import type { ColorInput } from "@sophistry/core/color";
+import type { Point } from "@sophistry/core/geometry";
+import type { Channel, ColorChannel, Quantity } from "../data/channels";
+import type { TooltipSpec, TooltipState } from "../tooltip";
+/**
+ * Props of {@link bullet}: `value` is required unless `data` is `number[]`.
+ *
+ * @category Charts
+ */
+export interface BulletProps<T = unknown> {
+    /** One bullet per datum, stacked top-down in data order. */
+    data: readonly T[];
+    /**
+     * The featured measure. Defaults to the datum when `data` is `number[]`; required otherwise. A
+     * non-finite value draws no bar.
+     */
+    value?: Channel<T, number>;
+    /** The comparative measure, drawn as a short perpendicular line. Omitted, no marker. */
+    target?: Channel<T, number>;
+    /**
+     * Qualitative thresholds, ascending, each where a band ends: `[150, 225, 300]` reads poor /
+     * satisfactory / good. The last band runs to the end of the scale.
+     */
+    ranges?: Channel<T, readonly number[]>;
+    /** The row's title, right-aligned to the left of its scale. */
+    label?: Channel<T, string>;
+    /**
+     * Where a row's scale starts, in data units: a number or a channel. Defaults to 0 (or below the
+     * smallest value when one is negative).
+     */
+    min?: Quantity<T>;
+    /**
+     * Where a row's scale ends, in data units: a number or a channel. Defaults to the largest of
+     * the row's value, target and thresholds.
+     */
+    max?: Quantity<T>;
+    /**
+     * Give every row the same scale instead of its own (use when rows measure the same thing).
+     * @default false
+     */
+    sharedScale?: boolean;
+    /**
+     * Round default scale ends out to tick values.
+     * @default true
+     */
+    nice?: boolean;
+    /** Width of the chart, titles included. */
+    width: number;
+    /** Height of the chart; each row gets an equal slot. */
+    height: number;
+    /** Centre of the chart. Defaults to the origin. */
+    center?: Point;
+    /**
+     * Width kept for the titles. Defaults to the widest title plus a gap, at most 45% of `width`.
+     */
+    labelWidth?: number;
+    /**
+     * Colour of the measure bar, constant or `(d, i) => colour`. Defaults to the theme's first
+     * series colour.
+     */
+    color?: ColorChannel<T>;
+    /**
+     * One colour per band, worst first. Defaults to graded greys from background toward foreground,
+     * the worst band strongest.
+     */
+    rangeColors?: readonly ColorInput[];
+    /** Colour of the target marker. Defaults to the theme's foreground. */
+    targetColor?: ColorInput;
+    /**
+     * Thickness of the measure bar, as a fraction of the band's.
+     * @default 1/3
+     */
+    barSize?: number;
+    /**
+     * Gap between rows, as a fraction of a row's slot.
+     * @default 0.35
+     */
+    padding?: number;
+    /**
+     * Write tick numbers under each row's scale.
+     * @default true
+     */
+    ticks?: boolean;
+    /**
+     * Title font size.
+     * @default 0.24
+     */
+    labelFontSize?: number;
+    /**
+     * Tick-number font size.
+     * @default 0.16
+     */
+    tickFontSize?: number;
+    /**
+     * Reveal, 0..1: bands, titles and ticks fade in first; then each row's bar grows from zero and
+     * its target draws in, rows staggered top-down.
+     * @default 1
+     * @see https://sophistry.dev/guides/chart-animation/#reveals
+     */
+    progress?: number;
+    /**
+     * Fraction of the data reveal spent staggering row after row, 0..0.95.
+     * @default 0.3
+     */
+    stagger?: number;
+    /** Hover tooltip on the bar: `true` for "label: value (target T)", or `(d, i) => string`. */
+    tooltip?: TooltipSpec<T>;
+    /** Paint order; higher draws later. */
+    zIndex?: number;
+    visible?: boolean;
+}
+/**
+ * A bullet chart: one measure against a target and qualitative ranges per
+ * row, a compact dashboard KPI that stacks into a table. Each row gets its
+ * own scale unless `sharedScale`. Draws in scene units; needs no `chart`.
+ *
+ * @example
+ * ```ts
+ * import { createScene } from "@sophistry/core";
+ * import { bullet } from "@sophistry/charts";
+ *
+ * const scene = createScene({ host: document.querySelector("#figure")!, units: 10 });
+ * scene.add(
+ * 	bullet.create({
+ * 		data: [{ name: "Revenue", value: 270, target: 250, ranges: [150, 225, 300] }],
+ * 		value: "value",
+ * 		target: "target",
+ * 		ranges: "ranges",
+ * 		label: "name",
+ * 		width: 8,
+ * 		height: 1.5,
+ * 	}),
+ * );
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#gauges-bullets-waffles-mosaics-and-radial-bars
+ * @category Charts
+ */
+export declare const bullet: import("@sophistry/core").Definition<BulletProps<any>, import("@sophistry/core/internal").CompositeNode<BulletProps<any>>, keyof BulletProps<any>>;
+/**
+ * A `bullet` node's tooltip state (what its bars show on hover), for an
+ * overlay to bind to; null for a node that is not a `bullet`.
+ *
+ * @category Charts
+ */
+export declare function bulletTooltip(node: SceneNode): TooltipState | null;
+//# sourceMappingURL=bullet.d.ts.map

package/dist/bars/bullet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bullet.d.ts","sourceRoot":"","sources":["../../src/bars/bullet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAIX,SAAS,EACT,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAWtD,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAaxE,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAyB5D;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACvC,4DAA4D;IAC5D,IAAI,EAAE,SAAS,CAAC,EAAE,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAC3B,wFAAwF;IACxF,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAC5B;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;IACvC,+DAA+D;IAC/D,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAC3B;;;OAGG;IACH,GAAG,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IAClB;;;OAGG;IACH,GAAG,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,MAAM,CAAC,EAAE,KAAK,CAAC;IACf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IACxB;;;OAGG;IACH,WAAW,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACpC,uEAAuE;IACvE,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6FAA6F;IAC7F,OAAO,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IACzB,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAwVD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,MAAM,oJAwCjB,CAAC;AAEH;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,YAAY,GAAG,IAAI,CAElE"}