@bro-code/charts 0.0.0-stage → 2026.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bro Code Technologies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,142 @@
-# Temporary Holding Version
+# @bro-code/charts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@bro-code/charts.svg)](https://www.npmjs.com/package/@bro-code/charts)
+[![license](https://img.shields.io/npm/l/@bro-code/charts.svg)](./LICENSE)
+
+Chart geometry for SVG: scales, area paths, pie slices and grouped bars, computed as plain data with no framework or DOM, so any app can draw its own charts.
+
+The package computes numbers and SVG path data and nothing else. The app draws the `<svg>` in whatever it renders with, and owns the colours, tooltips and any animation, so a change to how a chart looks never needs a new version of this package. It has no runtime dependencies and does nothing when imported.
+
+## Installation
+
+```bash
+npm install @bro-code/charts
+```
+
+## Usage
+
+An area chart of six monthly lows, as an `<svg>` string:
+
+```ts
+import { areaPath, extent, linearScale, nearestIndex } from '@bro-code/charts';
+
+const lows = [120, 80, -40, 15, 60, 95];
+const width = 300;
+const height = 120;
+
+const x = linearScale([0, lows.length - 1], [0, width]);
+const y = linearScale(extent(lows, { includeZero: true }), [height, 0]);
+const points = lows.map((low, i) => ({ x: x.map(i), y: y.map(low) }));
+const { line, area } = areaPath(points, { baseline: y.map(0) });
+
+const svg = `<svg viewBox="0 0 ${width} ${height}" width="${width}" height="${height}">
+  <path d="${area}" fill="rgb(76 175 80 / 0.25)" />
+  <path d="${line}" fill="none" stroke="rgb(76 175 80)" stroke-width="2" />
+</svg>`;
+
+// The month under the pointer, for a tooltip:
+const pointerX = 130; // from a pointer event, in the chart's coordinates
+const month = nearestIndex(points.map((p) => p.x), pointerX); // 2
+```
+
+### CommonJS
+
+```js
+const { areaPath, extent, linearScale } = require('@bro-code/charts');
+```
+
+## API
+
+Every position is in drawing coordinates: x grows to the right and y grows downward, as in SVG. Path data is written with at most two decimals.
+
+### `linearScale(domain, range)`
+
+Maps `domain` (data values) linearly onto `range` (drawing positions). Both are `[start, end]` pairs and either may run backwards; a value axis is usually `linearScale([min, max], [height, 0])`. Returns a `LinearScale`:
+
+| Member | |
+|---|---|
+| `map(value)` | The position of a domain value. Values outside the domain extrapolate past the ends of the range. |
+| `invert(position)` | The domain value at a position, extrapolating the same way. |
+
+A domain whose ends are equal (every value the same) maps every value to the middle of the range, and a range whose ends are equal (a chart with no width yet) inverts every position to the middle of the domain, instead of dividing by zero.
+
+### `extent(values, options?)`
+
+The smallest and largest of `values`, as `[min, max]`; `[0, 0]` when there are none. The values are not changed.
+
+| Option | Default | |
+|---|---|---|
+| `includeZero` | `false` | Stretch the extent to take in zero, so bars and areas have a zero line to stand on. An extent that already spans zero is unchanged. |
+
+### `areaPath(points, options)`
+
+Path data for an area chart through `points` (`{ x, y }`, in drawing order), joined with straight segments. Returns `{ line, area }`: `line` runs through every point, for the stroke, and `area` is that line closed to the baseline, for the fill.
+
+| Option | |
+|---|---|
+| `baseline` | The y the area closes to: the zero line (`y.map(0)`) or the bottom of the chart. Above the points, the area closes upward. |
+
+No points give empty strings. One point gives a zero-length line, which a round `stroke-linecap` shows as a dot, and an area with no width.
+
+### `pieSlices(values, options)`
+
+One `PieSlice` per value, in the order given, going clockwise. Angles are in degrees, clockwise from 12 o'clock.
+
+| Option | Default | |
+|---|---|---|
+| `cx`, `cy` | | The centre. |
+| `radius` | | The outer radius. |
+| `innerRadius` | `0` | The radius of the hole, for a donut. |
+| `startAngle` | `0` | Where the first slice starts; `180` (or `-180`) starts at the bottom. |
+| `padAngle` | `0` | Degrees of gap between neighbouring slices, taken half from each end of each slice. |
+
+| Slice field | |
+|---|---|
+| `index`, `value` | The value's place in `values`, and the value. |
+| `fraction` | Its share of the total, from 0 to 1; 0 for every slice when all the values are 0. |
+| `startAngle`, `endAngle` | Its angles before padding, so the slices tile the full turn. |
+| `path` | Path data for the slice; empty when it draws nothing. |
+| `centroid` | `{ x, y }` at the middle of its angle, halfway between the inner and outer radius: a place for a tooltip or label. |
+
+A value that is the whole total is drawn as a full circle (a ring for a donut), with no padding. A zero value, every value when all are zero, and a slice no wider than `padAngle` draw nothing. A negative value throws a `RangeError` naming its index.
+
+### `groupedBars(series, options)`
+
+Grouped bars for `series`, one number array per series (charges and deposits, say), all the same length: group `i` holds value `i` of each series. Returns `{ bars, baseline }`: `baseline` is the y of the zero line, and `bars` run left to right, group by group, each group's bars in series order. Each `Bar` is `{ series, index, value, x, y, width, height }`, `index` being its group.
+
+| Option | Default | |
+|---|---|---|
+| `width`, `height` | | The size of the chart. |
+| `groupPadding` | `0.1` | Share of each group's band left empty, half on each side of the group. |
+| `barPadding` | `0` | Share of each group's width left empty between its bars. |
+
+The groups split `width` into equal bands with no outer padding, so equal grid columns under the chart (month labels, say) line up with them. The value domain spans zero and every value, so a negative value hangs below the zero line; with no values or only zeros, the zero line is the bottom. Series of different lengths throw a `RangeError`.
+
+### `nearestIndex(positions, x)`
+
+The index of the position closest to `x`, the first of a tie; -1 when there are none. For an area chart's tooltip, pass the points' x positions and the pointer's x.
+
+### `bandIndex(x, count, width)`
+
+Which of `count` equal bands across `width` holds `x`, clamped to the first and last band; -1 when `count` is 0. For a bar chart's tooltip, `bandIndex(x, groupCount, width)` gives the group under the pointer, and `bandIndex` again across that group's bars (from its first bar's `x` to its last bar's `x + width`) gives the bar.
+
+### Types
+
+The package exports `LinearScale`, `ExtentOptions`, `Interval` (a `readonly [number, number]` pair), `Point`, `AreaOptions`, `AreaPath`, `PieOptions`, `PieSlice`, `GroupedBarsOptions`, `GroupedBars` and `Bar` as types.
+
+## License
+
+MIT - see [LICENSE](./LICENSE).
+
+## Changelog
+
+### [2026.0.0] - 2026-10-29
+
+#### Added
+- Initial release.
+- `linearScale(domain, range)`, with `map` and `invert`, reversed domains and ranges, and equal-ended domains and ranges mapped to their middle.
+- `extent(values, { includeZero })`.
+- `areaPath(points, { baseline })`: the line and the filled area, with straight segments.
+- `pieSlices(values, options)`: pie and donut slices with a start angle and padding, full-circle and empty slices, and a centroid for each.
+- `groupedBars(series, options)`: bars in equal bands with group and bar padding, and negative values below the zero line.
+- `nearestIndex(positions, x)` and `bandIndex(x, count, width)`, for finding what is under the pointer.

package/dist/cjs/area.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.areaPath = areaPath;
+const path_js_1 = require("./internal/path.js");
+/**
+ * SVG path data for an area chart through `points`, which are in drawing
+ * coordinates and drawing order, joined with straight segments. No points give
+ * empty strings. One point gives a zero-length line, which a round
+ * `stroke-linecap` shows as a dot, and an area with no width.
+ */
+function areaPath(points, options) {
+    if (points.length === 0)
+        return { line: '', area: '' };
+    const first = points[0];
+    const last = points[points.length - 1];
+    const lineTo = (rest) => rest.map((point) => `L${(0, path_js_1.pt)(point)}`).join('');
+    const baseline = (0, path_js_1.num)(options.baseline);
+    return {
+        line: `M${(0, path_js_1.pt)(first)}${lineTo(points.length === 1 ? points : points.slice(1))}`,
+        area: `M${(0, path_js_1.num)(first.x)},${baseline}${lineTo(points)}L${(0, path_js_1.num)(last.x)},${baseline}Z`,
+    };
+}

package/dist/cjs/bars.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.groupedBars = groupedBars;
+const scale_js_1 = require("./scale.js");
+/**
+ * Grouped bars for `series`, one number array per series, all the same length:
+ * group `i` holds value `i` of each series. The groups split `width` into equal
+ * bands with no outer padding, so equal grid columns under the chart line up
+ * with them. The value domain spans zero and every value, so a negative value
+ * hangs below the zero line; with no values or only zeros, the zero line is the
+ * bottom. Throws a `RangeError` when the series differ in length.
+ */
+function groupedBars(series, options) {
+    const count = series.length > 0 ? series[0].length : 0;
+    series.forEach((values, index) => {
+        if (values.length !== count) {
+            throw new RangeError(`groupedBars: series ${index} has ${values.length} values, series 0 has ${count}`);
+        }
+    });
+    const { width, height, groupPadding = 0.1, barPadding = 0 } = options;
+    const [min, max] = (0, scale_js_1.extent)(series.flat(), { includeZero: true });
+    const y = (0, scale_js_1.linearScale)(min === max ? [0, 1] : [min, max], [height, 0]);
+    const baseline = y.map(0);
+    const band = count > 0 ? width / count : 0;
+    const groupWidth = band * (1 - groupPadding);
+    const gaps = series.length - 1;
+    const gap = gaps > 0 ? (groupWidth * barPadding) / gaps : 0;
+    const barWidth = series.length > 0 ? (groupWidth - gap * gaps) / series.length : 0;
+    const bars = [];
+    for (let index = 0; index < count; index++) {
+        const left = index * band + (band - groupWidth) / 2;
+        series.forEach((values, s) => {
+            const value = values[index];
+            const top = y.map(value);
+            bars.push({
+                series: s,
+                index,
+                value,
+                x: left + s * (barWidth + gap),
+                y: Math.min(top, baseline),
+                width: barWidth,
+                height: Math.abs(top - baseline),
+            });
+        });
+    }
+    return { bars, baseline };
+}

package/dist/cjs/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.linearScale = exports.extent = exports.nearestIndex = exports.bandIndex = exports.pieSlices = exports.groupedBars = exports.areaPath = void 0;
+var area_js_1 = require("./area.js");
+Object.defineProperty(exports, "areaPath", { enumerable: true, get: function () { return area_js_1.areaPath; } });
+var bars_js_1 = require("./bars.js");
+Object.defineProperty(exports, "groupedBars", { enumerable: true, get: function () { return bars_js_1.groupedBars; } });
+var pie_js_1 = require("./pie.js");
+Object.defineProperty(exports, "pieSlices", { enumerable: true, get: function () { return pie_js_1.pieSlices; } });
+var pointer_js_1 = require("./pointer.js");
+Object.defineProperty(exports, "bandIndex", { enumerable: true, get: function () { return pointer_js_1.bandIndex; } });
+Object.defineProperty(exports, "nearestIndex", { enumerable: true, get: function () { return pointer_js_1.nearestIndex; } });
+var scale_js_1 = require("./scale.js");
+Object.defineProperty(exports, "extent", { enumerable: true, get: function () { return scale_js_1.extent; } });
+Object.defineProperty(exports, "linearScale", { enumerable: true, get: function () { return scale_js_1.linearScale; } });

package/dist/cjs/internal/path.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.num = num;
+exports.pt = pt;
+/** A coordinate for SVG path data: at most two decimals, no trailing zeros and no `-0`. */
+function num(value) {
+    const rounded = Math.round(value * 100) / 100;
+    return String(rounded === 0 ? 0 : rounded);
+}
+function pt(point) {
+    return `${num(point.x)},${num(point.y)}`;
+}

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/cjs/pie.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pieSlices = pieSlices;
+const path_js_1 = require("./internal/path.js");
+function polar(ring, radius, degrees) {
+    const radians = (degrees * Math.PI) / 180;
+    return { x: ring.cx + radius * Math.sin(radians), y: ring.cy - radius * Math.cos(radians) };
+}
+function arc(radius, large, clockwise, to) {
+    return `A${(0, path_js_1.num)(radius)},${(0, path_js_1.num)(radius)} 0 ${large ? 1 : 0} ${clockwise ? 1 : 0} ${(0, path_js_1.pt)(to)}`;
+}
+// One SVG arc can't close a circle, so a whole one is two half circles. A
+// donut's hole runs the other way round, so the nonzero fill rule leaves it empty.
+function circlePath(ring, from) {
+    const { radius, innerRadius } = ring;
+    const start = polar(ring, radius, from);
+    let path = `M${(0, path_js_1.pt)(start)}${arc(radius, true, true, polar(ring, radius, from + 180))}${arc(radius, true, true, start)}Z`;
+    if (innerRadius > 0) {
+        const inner = polar(ring, innerRadius, from);
+        path += `M${(0, path_js_1.pt)(inner)}${arc(innerRadius, true, false, polar(ring, innerRadius, from + 180))}`;
+        path += `${arc(innerRadius, true, false, inner)}Z`;
+    }
+    return path;
+}
+function slicePath(ring, from, to) {
+    const { radius, innerRadius } = ring;
+    const large = to - from > 180;
+    const outer = `${(0, path_js_1.pt)(polar(ring, radius, from))}${arc(radius, large, true, polar(ring, radius, to))}`;
+    if (innerRadius <= 0)
+        return `M${(0, path_js_1.num)(ring.cx)},${(0, path_js_1.num)(ring.cy)}L${outer}Z`;
+    const inner = arc(innerRadius, large, false, polar(ring, innerRadius, from));
+    return `M${outer}L${(0, path_js_1.pt)(polar(ring, innerRadius, to))}${inner}Z`;
+}
+/**
+ * One slice per value, in the order given. A value that is the whole total is
+ * drawn as a full circle (or ring), with no padding. A zero value draws nothing.
+ * `padAngle` is taken from each slice's own angle, half at each end, and a slice
+ * no wider than it draws nothing. Throws a `RangeError` for a negative value.
+ */
+function pieSlices(values, options) {
+    values.forEach((value, index) => {
+        if (value < 0)
+            throw new RangeError(`pieSlices: value ${index} is negative (${value})`);
+    });
+    const { cx, cy, radius, innerRadius = 0, startAngle = 0, padAngle = 0 } = options;
+    const ring = { cx, cy, radius, innerRadius };
+    const total = values.reduce((sum, value) => sum + value, 0);
+    const drawn = values.filter((value) => value > 0).length;
+    const pad = drawn > 1 ? padAngle : 0;
+    let sum = 0;
+    return values.map((value, index) => {
+        const from = total > 0 ? startAngle + (sum / total) * 360 : startAngle;
+        sum += value;
+        const to = total > 0 ? startAngle + (sum / total) * 360 : startAngle;
+        let path = '';
+        if (drawn === 1 && value > 0)
+            path = circlePath(ring, from);
+        else if (value > 0 && to - from > pad)
+            path = slicePath(ring, from + pad / 2, to - pad / 2);
+        return {
+            index,
+            value,
+            fraction: total > 0 ? value / total : 0,
+            startAngle: from,
+            endAngle: to,
+            path,
+            centroid: polar(ring, (radius + innerRadius) / 2, (from + to) / 2),
+        };
+    });
+}

package/dist/cjs/pointer.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nearestIndex = nearestIndex;
+exports.bandIndex = bandIndex;
+/** The index of the position closest to `x`, the first of a tie; -1 when there are none. */
+function nearestIndex(positions, x) {
+    let nearest = -1;
+    let nearestDistance = Infinity;
+    positions.forEach((position, index) => {
+        const distance = Math.abs(position - x);
+        if (distance < nearestDistance) {
+            nearest = index;
+            nearestDistance = distance;
+        }
+    });
+    return nearest;
+}
+/**
+ * Which of `count` equal bands across `width` holds `x`, clamped to the first
+ * and last band; -1 when there are no bands.
+ */
+function bandIndex(x, count, width) {
+    if (count <= 0)
+        return -1;
+    return Math.min(count - 1, Math.max(0, Math.floor((x / width) * count)));
+}

package/dist/cjs/scale.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.linearScale = linearScale;
+exports.extent = extent;
+/**
+ * Maps a domain linearly onto a range. Either may run backwards: SVG's y grows
+ * downward, so a value axis is usually `linearScale([min, max], [height, 0])`.
+ * A domain whose ends are equal maps every value to the middle of the range,
+ * and a range whose ends are equal inverts every position to the middle of
+ * the domain, instead of dividing by zero.
+ */
+function linearScale(domain, range) {
+    const [d0, d1] = domain;
+    const [r0, r1] = range;
+    const domainSpan = d1 - d0;
+    const rangeSpan = r1 - r0;
+    return {
+        map: (value) => (domainSpan === 0 ? (r0 + r1) / 2 : r0 + ((value - d0) / domainSpan) * rangeSpan),
+        invert: (position) => (rangeSpan === 0 ? (d0 + d1) / 2 : d0 + ((position - r0) / rangeSpan) * domainSpan),
+    };
+}
+/** The smallest and largest of `values`, or `[0, 0]` when there are none. */
+function extent(values, options = {}) {
+    if (values.length === 0)
+        return [0, 0];
+    let min = values[0];
+    let max = values[0];
+    for (const value of values) {
+        if (value < min)
+            min = value;
+        if (value > max)
+            max = value;
+    }
+    if (options.includeZero) {
+        min = Math.min(min, 0);
+        max = Math.max(max, 0);
+    }
+    return [min, max];
+}

package/dist/cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/esm/area.js

@@ -0,0 +1,19 @@
+import { num, pt } from './internal/path.js';
+/**
+ * SVG path data for an area chart through `points`, which are in drawing
+ * coordinates and drawing order, joined with straight segments. No points give
+ * empty strings. One point gives a zero-length line, which a round
+ * `stroke-linecap` shows as a dot, and an area with no width.
+ */
+export function areaPath(points, options) {
+    if (points.length === 0)
+        return { line: '', area: '' };
+    const first = points[0];
+    const last = points[points.length - 1];
+    const lineTo = (rest) => rest.map((point) => `L${pt(point)}`).join('');
+    const baseline = num(options.baseline);
+    return {
+        line: `M${pt(first)}${lineTo(points.length === 1 ? points : points.slice(1))}`,
+        area: `M${num(first.x)},${baseline}${lineTo(points)}L${num(last.x)},${baseline}Z`,
+    };
+}

package/dist/esm/bars.js

@@ -0,0 +1,44 @@
+import { extent, linearScale } from './scale.js';
+/**
+ * Grouped bars for `series`, one number array per series, all the same length:
+ * group `i` holds value `i` of each series. The groups split `width` into equal
+ * bands with no outer padding, so equal grid columns under the chart line up
+ * with them. The value domain spans zero and every value, so a negative value
+ * hangs below the zero line; with no values or only zeros, the zero line is the
+ * bottom. Throws a `RangeError` when the series differ in length.
+ */
+export function groupedBars(series, options) {
+    const count = series.length > 0 ? series[0].length : 0;
+    series.forEach((values, index) => {
+        if (values.length !== count) {
+            throw new RangeError(`groupedBars: series ${index} has ${values.length} values, series 0 has ${count}`);
+        }
+    });
+    const { width, height, groupPadding = 0.1, barPadding = 0 } = options;
+    const [min, max] = extent(series.flat(), { includeZero: true });
+    const y = linearScale(min === max ? [0, 1] : [min, max], [height, 0]);
+    const baseline = y.map(0);
+    const band = count > 0 ? width / count : 0;
+    const groupWidth = band * (1 - groupPadding);
+    const gaps = series.length - 1;
+    const gap = gaps > 0 ? (groupWidth * barPadding) / gaps : 0;
+    const barWidth = series.length > 0 ? (groupWidth - gap * gaps) / series.length : 0;
+    const bars = [];
+    for (let index = 0; index < count; index++) {
+        const left = index * band + (band - groupWidth) / 2;
+        series.forEach((values, s) => {
+            const value = values[index];
+            const top = y.map(value);
+            bars.push({
+                series: s,
+                index,
+                value,
+                x: left + s * (barWidth + gap),
+                y: Math.min(top, baseline),
+                width: barWidth,
+                height: Math.abs(top - baseline),
+            });
+        });
+    }
+    return { bars, baseline };
+}

package/dist/esm/index.js

@@ -0,0 +1,5 @@
+export { areaPath } from './area.js';
+export { groupedBars } from './bars.js';
+export { pieSlices } from './pie.js';
+export { bandIndex, nearestIndex } from './pointer.js';
+export { extent, linearScale } from './scale.js';

package/dist/esm/internal/path.js

@@ -0,0 +1,8 @@
+/** A coordinate for SVG path data: at most two decimals, no trailing zeros and no `-0`. */
+export function num(value) {
+    const rounded = Math.round(value * 100) / 100;
+    return String(rounded === 0 ? 0 : rounded);
+}
+export function pt(point) {
+    return `${num(point.x)},${num(point.y)}`;
+}

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/esm/pie.js

@@ -0,0 +1,67 @@
+import { num, pt } from './internal/path.js';
+function polar(ring, radius, degrees) {
+    const radians = (degrees * Math.PI) / 180;
+    return { x: ring.cx + radius * Math.sin(radians), y: ring.cy - radius * Math.cos(radians) };
+}
+function arc(radius, large, clockwise, to) {
+    return `A${num(radius)},${num(radius)} 0 ${large ? 1 : 0} ${clockwise ? 1 : 0} ${pt(to)}`;
+}
+// One SVG arc can't close a circle, so a whole one is two half circles. A
+// donut's hole runs the other way round, so the nonzero fill rule leaves it empty.
+function circlePath(ring, from) {
+    const { radius, innerRadius } = ring;
+    const start = polar(ring, radius, from);
+    let path = `M${pt(start)}${arc(radius, true, true, polar(ring, radius, from + 180))}${arc(radius, true, true, start)}Z`;
+    if (innerRadius > 0) {
+        const inner = polar(ring, innerRadius, from);
+        path += `M${pt(inner)}${arc(innerRadius, true, false, polar(ring, innerRadius, from + 180))}`;
+        path += `${arc(innerRadius, true, false, inner)}Z`;
+    }
+    return path;
+}
+function slicePath(ring, from, to) {
+    const { radius, innerRadius } = ring;
+    const large = to - from > 180;
+    const outer = `${pt(polar(ring, radius, from))}${arc(radius, large, true, polar(ring, radius, to))}`;
+    if (innerRadius <= 0)
+        return `M${num(ring.cx)},${num(ring.cy)}L${outer}Z`;
+    const inner = arc(innerRadius, large, false, polar(ring, innerRadius, from));
+    return `M${outer}L${pt(polar(ring, innerRadius, to))}${inner}Z`;
+}
+/**
+ * One slice per value, in the order given. A value that is the whole total is
+ * drawn as a full circle (or ring), with no padding. A zero value draws nothing.
+ * `padAngle` is taken from each slice's own angle, half at each end, and a slice
+ * no wider than it draws nothing. Throws a `RangeError` for a negative value.
+ */
+export function pieSlices(values, options) {
+    values.forEach((value, index) => {
+        if (value < 0)
+            throw new RangeError(`pieSlices: value ${index} is negative (${value})`);
+    });
+    const { cx, cy, radius, innerRadius = 0, startAngle = 0, padAngle = 0 } = options;
+    const ring = { cx, cy, radius, innerRadius };
+    const total = values.reduce((sum, value) => sum + value, 0);
+    const drawn = values.filter((value) => value > 0).length;
+    const pad = drawn > 1 ? padAngle : 0;
+    let sum = 0;
+    return values.map((value, index) => {
+        const from = total > 0 ? startAngle + (sum / total) * 360 : startAngle;
+        sum += value;
+        const to = total > 0 ? startAngle + (sum / total) * 360 : startAngle;
+        let path = '';
+        if (drawn === 1 && value > 0)
+            path = circlePath(ring, from);
+        else if (value > 0 && to - from > pad)
+            path = slicePath(ring, from + pad / 2, to - pad / 2);
+        return {
+            index,
+            value,
+            fraction: total > 0 ? value / total : 0,
+            startAngle: from,
+            endAngle: to,
+            path,
+            centroid: polar(ring, (radius + innerRadius) / 2, (from + to) / 2),
+        };
+    });
+}

package/dist/esm/pointer.js

@@ -0,0 +1,22 @@
+/** The index of the position closest to `x`, the first of a tie; -1 when there are none. */
+export function nearestIndex(positions, x) {
+    let nearest = -1;
+    let nearestDistance = Infinity;
+    positions.forEach((position, index) => {
+        const distance = Math.abs(position - x);
+        if (distance < nearestDistance) {
+            nearest = index;
+            nearestDistance = distance;
+        }
+    });
+    return nearest;
+}
+/**
+ * Which of `count` equal bands across `width` holds `x`, clamped to the first
+ * and last band; -1 when there are no bands.
+ */
+export function bandIndex(x, count, width) {
+    if (count <= 0)
+        return -1;
+    return Math.min(count - 1, Math.max(0, Math.floor((x / width) * count)));
+}

package/dist/esm/scale.js

@@ -0,0 +1,35 @@
+/**
+ * Maps a domain linearly onto a range. Either may run backwards: SVG's y grows
+ * downward, so a value axis is usually `linearScale([min, max], [height, 0])`.
+ * A domain whose ends are equal maps every value to the middle of the range,
+ * and a range whose ends are equal inverts every position to the middle of
+ * the domain, instead of dividing by zero.
+ */
+export function linearScale(domain, range) {
+    const [d0, d1] = domain;
+    const [r0, r1] = range;
+    const domainSpan = d1 - d0;
+    const rangeSpan = r1 - r0;
+    return {
+        map: (value) => (domainSpan === 0 ? (r0 + r1) / 2 : r0 + ((value - d0) / domainSpan) * rangeSpan),
+        invert: (position) => (rangeSpan === 0 ? (d0 + d1) / 2 : d0 + ((position - r0) / rangeSpan) * domainSpan),
+    };
+}
+/** The smallest and largest of `values`, or `[0, 0]` when there are none. */
+export function extent(values, options = {}) {
+    if (values.length === 0)
+        return [0, 0];
+    let min = values[0];
+    let max = values[0];
+    for (const value of values) {
+        if (value < min)
+            min = value;
+        if (value > max)
+            max = value;
+    }
+    if (options.includeZero) {
+        min = Math.min(min, 0);
+        max = Math.max(max, 0);
+    }
+    return [min, max];
+}

package/dist/esm/types.js

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

package/dist/types/area.d.ts

@@ -0,0 +1,18 @@
+import type { Point } from './types.js';
+export interface AreaOptions {
+    /** The y the area closes to: usually the zero line or the bottom of the chart. */
+    baseline: number;
+}
+export interface AreaPath {
+    /** Path data through every point, for the stroke. */
+    line: string;
+    /** The line closed to the baseline, for the fill. */
+    area: string;
+}
+/**
+ * SVG path data for an area chart through `points`, which are in drawing
+ * coordinates and drawing order, joined with straight segments. No points give
+ * empty strings. One point gives a zero-length line, which a round
+ * `stroke-linecap` shows as a dot, and an area with no width.
+ */
+export declare function areaPath(points: readonly Point[], options: AreaOptions): AreaPath;

package/dist/types/bars.d.ts

@@ -0,0 +1,34 @@
+export interface GroupedBarsOptions {
+    width: number;
+    height: number;
+    /** Share of each group's band left empty, half on each side of the group. Default 0.1. */
+    groupPadding?: number;
+    /** Share of each group's width left empty between its bars. Default 0. */
+    barPadding?: number;
+}
+export interface Bar {
+    /** Which series the bar belongs to. */
+    series: number;
+    /** Which group (month, say) the bar belongs to. */
+    index: number;
+    value: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface GroupedBars {
+    /** Left to right: group by group, and each group's bars in series order. */
+    bars: Bar[];
+    /** The y of the zero line. */
+    baseline: number;
+}
+/**
+ * Grouped bars for `series`, one number array per series, all the same length:
+ * group `i` holds value `i` of each series. The groups split `width` into equal
+ * bands with no outer padding, so equal grid columns under the chart line up
+ * with them. The value domain spans zero and every value, so a negative value
+ * hangs below the zero line; with no values or only zeros, the zero line is the
+ * bottom. Throws a `RangeError` when the series differ in length.
+ */
+export declare function groupedBars(series: readonly (readonly number[])[], options: GroupedBarsOptions): GroupedBars;

package/dist/types/index.d.ts

@@ -0,0 +1,10 @@
+export { areaPath } from './area.js';
+export { groupedBars } from './bars.js';
+export { pieSlices } from './pie.js';
+export { bandIndex, nearestIndex } from './pointer.js';
+export { extent, linearScale } from './scale.js';
+export type { AreaOptions, AreaPath } from './area.js';
+export type { Bar, GroupedBars, GroupedBarsOptions } from './bars.js';
+export type { PieOptions, PieSlice } from './pie.js';
+export type { ExtentOptions, Interval, LinearScale } from './scale.js';
+export type { Point } from './types.js';

package/dist/types/internal/path.d.ts

@@ -0,0 +1,4 @@
+import type { Point } from '../types.js';
+/** A coordinate for SVG path data: at most two decimals, no trailing zeros and no `-0`. */
+export declare function num(value: number): string;
+export declare function pt(point: Point): string;

package/dist/types/pie.d.ts

@@ -0,0 +1,32 @@
+import type { Point } from './types.js';
+export interface PieOptions {
+    cx: number;
+    cy: number;
+    radius: number;
+    /** Radius of the hole, for a donut. Default 0. */
+    innerRadius?: number;
+    /** Where the first slice starts, in degrees clockwise from 12 o'clock. Default 0. */
+    startAngle?: number;
+    /** Degrees of gap between neighbouring slices. Default 0. */
+    padAngle?: number;
+}
+export interface PieSlice {
+    index: number;
+    value: number;
+    /** The slice's share of the total, from 0 to 1; 0 when every value is 0. */
+    fraction: number;
+    /** Degrees clockwise from 12 o'clock, before padding. */
+    startAngle: number;
+    endAngle: number;
+    /** SVG path data; empty when the slice draws nothing. */
+    path: string;
+    /** The middle of the slice's angle, halfway between the inner and outer radius. */
+    centroid: Point;
+}
+/**
+ * One slice per value, in the order given. A value that is the whole total is
+ * drawn as a full circle (or ring), with no padding. A zero value draws nothing.
+ * `padAngle` is taken from each slice's own angle, half at each end, and a slice
+ * no wider than it draws nothing. Throws a `RangeError` for a negative value.
+ */
+export declare function pieSlices(values: readonly number[], options: PieOptions): PieSlice[];

package/dist/types/pointer.d.ts

@@ -0,0 +1,7 @@
+/** The index of the position closest to `x`, the first of a tie; -1 when there are none. */
+export declare function nearestIndex(positions: readonly number[], x: number): number;
+/**
+ * Which of `count` equal bands across `width` holds `x`, clamped to the first
+ * and last band; -1 when there are no bands.
+ */
+export declare function bandIndex(x: number, count: number, width: number): number;

package/dist/types/scale.d.ts

@@ -0,0 +1,22 @@
+/** Two ends of a domain or range, in either order. */
+export type Interval = readonly [number, number];
+export interface LinearScale {
+    /** The position of a domain value. Values outside the domain extrapolate. */
+    map(value: number): number;
+    /** The domain value at a position. */
+    invert(position: number): number;
+}
+export interface ExtentOptions {
+    /** Stretch the extent to take in zero. */
+    includeZero?: boolean;
+}
+/**
+ * Maps a domain linearly onto a range. Either may run backwards: SVG's y grows
+ * downward, so a value axis is usually `linearScale([min, max], [height, 0])`.
+ * A domain whose ends are equal maps every value to the middle of the range,
+ * and a range whose ends are equal inverts every position to the middle of
+ * the domain, instead of dividing by zero.
+ */
+export declare function linearScale(domain: Interval, range: Interval): LinearScale;
+/** The smallest and largest of `values`, or `[0, 0]` when there are none. */
+export declare function extent(values: readonly number[], options?: ExtentOptions): [number, number];

package/dist/types/types.d.ts

@@ -0,0 +1,5 @@
+/** A point in drawing coordinates. */
+export interface Point {
+    x: number;
+    y: number;
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@bro-code/charts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2026.0.0",
+  "type": "module",
+  "description": "Chart geometry for SVG: scales, area paths, pie slices and grouped bars, computed as plain data with no framework or DOM, so any app can draw its own charts.",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npm run build:esm && npm run build:cjs && npm run build:types && npm run build:fixup",
+    "build:esm": "tsc --project tsconfig.esm.json",
+    "build:cjs": "tsc --project tsconfig.cjs.json",
+    "build:types": "tsc --project tsconfig.types.json",
+    "build:fixup": "node scripts/fixup.cjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "prepublishOnly": "npm run lint && npm run test && npm run build",
+    "preversion": "npm run lint && npm run test",
+    "version": "git add -A"
+  },
+  "keywords": [
+    "charts",
+    "svg",
+    "geometry",
+    "scale",
+    "pie",
+    "bar-chart",
+    "area-chart",
+    "bro-code"
+  ],
+  "author": "Bro Code Technologies",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Bro-Code-Technologies/bro-code-package-maker.git",
+    "directory": "packages/charts"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@eslint/js": "~10.0.1",
+    "@types/node": "~25.9.9",
+    "eslint": "~10.13.0",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "~8.72.1",
+    "vitest": "~4.1.12"
+  }
+}