enarratio-astro 0.1.0 → 0.4.1

package/CHANGELOG.md

@@ -1,22 +1,74 @@
-# Changelog
-
-All notable changes to enarratio-astro are recorded here. The format follows
-[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
-[Semantic Versioning](https://semver.org/). Before 1.0.0, a minor version may change the options;
-every such change is listed here.
-
-## [Unreleased]
-
-## [0.1.0] - 2026-10-24
-
-### Added
-
-- `<Chart>`: bar, line, stacked area, scatter and heatmap charts drawn on the server by Enarratio
-  0.3.1, from rows or from CSV, semicolon- or tab-separated text, with a required description, a
-  data table, and light and dark themes. The chart CSS is written once per page.
-- Charts in Markdown: `chart` code blocks, with `satteriCharts()` for Sätteri and `remarkCharts`
-  for remark.
-- `<Enhance />` and the `interactive` option: Enarratio's enhancement script, only on pages that
-  ask for it.
-- `styles`: `"theme"` (default), `"base"` for sites whose tokens define the colors, or `"none"`.
-- A note in place of a chart that cannot be drawn, saying why.
+# Changelog
+
+All notable changes to enarratio-astro are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/). Before 1.0.0, a minor version may change the options;
+every such change is listed here.
+
+## [Unreleased]
+
+## [0.4.1] - 2026-11-03
+
+### Changed
+
+- Draws with Enarratio 0.7.2: timeline text never renders under 12 px.
+- Requires Node.js 22.22 or later (was 22.16), the floor Astro 7.4 sets.
+
+## [0.4.0] - 2026-11-01
+
+### Changed
+
+- Draws with Enarratio 0.7.0 (0.6.0's phone drawings and Play as sound, and 0.7.0's tactile SVG download and
+  forced-colors legend swatches).
+
+### Release
+
+- Staging works: the release job's setup-node moves from v4 to v7, whose v4 placeholder `NODE_AUTH_TOKEN` was sent
+  in place of the trusted-publishing token (E401 on 0.2.0, 0.2.1 and 0.3.0, so 0.1.0 is the newest on npm).
+
+- Each release's `npm pack` tarball gets a GitHub artifact attestation beside npm's provenance:
+  `gh attestation verify enarratio-astro-<version>.tgz --repo DrDustinEdwards/astro` checks a download.
+
+## [0.3.0] - 2026-10-31
+
+### Changed
+
+- Draws with Enarratio 0.5.0: axis titles clear of the ticks, ticks thinned to fit, the y range rounded to the
+  drawn ticks, proportional tick figures, text-safe series ink in the Capsomer theme, and Download SVG and PNG
+  through `enarratio/enhance`.
+- First release on npm since 0.1.0: 0.2.0 and 0.2.1 were tagged but never reached npm, because trusted
+  publishing was not yet set up.
+
+## [0.2.1] - 2026-10-31
+
+### Changed
+
+- Draws with Enarratio 0.4.1: capitalized summaries, ranges said with their unit, day ticks for
+  whole-day data, and linked bars whose links sit in the data table.
+
+## [0.2.0] - 2026-10-31
+
+### Changed
+
+- Draws with Enarratio 0.4.0: a head with the title and the finding, a summary under the chart, a
+  CSV download, and wide charts that scroll sideways on a phone. The base styles now set system
+  colors under forced colors.
+
+### Added
+
+- `subtitle`, `notes`, `source`, `sourceHref`, `byline`, `xUnit` and `yUnit`, as props and as
+  Markdown keys.
+
+## [0.1.0] - 2026-10-24
+
+### Added
+
+- `<Chart>`: bar, line, stacked area, scatter and heatmap charts drawn on the server by Enarratio
+  0.3.1, from rows or from CSV, semicolon- or tab-separated text, with a required description, a
+  data table, and light and dark themes. The chart CSS is written once per page.
+- Charts in Markdown: `chart` code blocks, with `satteriCharts()` for Sätteri and `remarkCharts`
+  for remark.
+- `<Enhance />` and the `interactive` option: Enarratio's enhancement script, only on pages that
+  ask for it.
+- `styles`: `"theme"` (default), `"base"` for sites whose tokens define the colors, or `"none"`.
+- A note in place of a chart that cannot be drawn, saying why.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Dustin Edwards
-
-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.
+MIT License
+
+Copyright (c) 2026 Dustin Edwards
+
+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,151 +1,155 @@
-# enarratio-astro
-
-**Accessible charts for [Astro](https://astro.build): a `<Chart>` component and charts in Markdown,
-drawn on the server by [Enarratio](https://github.com/DrDustinEdwards/enarratio).**
-
-A chart arrives in the page as HTML and SVG: complete before any script runs, readable by screen
-readers and search engines, with a data table, and in light and dark. It draws bar (stacked, side
-by side, vertical or horizontal; counting rows when no value column is given), line, stacked area,
-scatter (with an optional regression line and 95% band) and heatmap charts. A chart can be made
-interactive (hover and focus details, keyboard navigation, click-to-filter) with Enarratio's small
-enhancement script, which is added only to pages that ask for it.
-
-Supports Astro 6 or later. Status: 0.x, so options may change before 1.0; every change is in the
-[changelog](https://github.com/DrDustinEdwards/astro/blob/main/packages/enarratio-astro/CHANGELOG.md). For EmDash sites,
-[enarratio-emdash](https://github.com/DrDustinEdwards/astro/tree/main/packages/enarratio-emdash#readme) adds the same charts as a block
-in the editor.
-
-## Install
-
-```sh
-npm install enarratio-astro
-```
-
-## In a page
-
-```astro
----
-import Chart from "enarratio-astro/Chart.astro";
-
-const downloads = [
-  { year: 2024, package: "Core", downloads: 4100 },
-  { year: 2025, package: "Core", downloads: 5300 },
-  { year: 2026, package: "Core", downloads: 6100 },
-  { year: 2024, package: "Plugin", downloads: 1200 },
-  { year: 2025, package: "Plugin", downloads: 1900 },
-  { year: 2026, package: "Plugin", downloads: 2800 },
-];
----
-<Chart
-  type="line"
-  data={downloads}
-  x="year"
-  y="downloads"
-  series="package"
-  title="Downloads per year"
-  alt="Downloads per year, 2024 to 2026: the core grows from 4,100 to 6,100, the plugin from 1,200 to 2,800."
-  interactive
-/>
-```
-
-`data` is rows as objects (from code, JSON or a content collection; dates become ISO dates) or
-text: CSV, semicolon-separated, or pasted from a spreadsheet (tab-separated), first row naming the
-columns. The chart CSS is written once per page, however many charts it has.
-
-## In Markdown
-
-A code block whose language is `chart` becomes a chart: options, a line of three dashes, then the
-data.
-
-~~~md
-```chart
-type: bar
-x: team
-y: tickets
-series: status
-layout: grouped
-alt: Support has the most open tickets; Platform has closed the most.
----
-team,status,tickets
-Support,Open,14
-Support,Closed,22
-Platform,Open,5
-Platform,Closed,31
-```
-~~~
-
-Register the plugin for Astro's Markdown processor. Astro 7's default, Sätteri:
-
-```js
-// astro.config.mjs
-import { satteri } from "@astrojs/markdown-satteri";
-import { satteriCharts } from "enarratio-astro/markdown";
-
-export default defineConfig({
-  markdown: { processor: satteri({ mdastPlugins: [satteriCharts()] }) },
-});
-```
-
-With remark (Astro 6, or Astro 7's unified processor):
-
-```js
-import { remarkCharts } from "enarratio-astro/markdown";
-
-export default defineConfig({ markdown: { remarkPlugins: [remarkCharts] } });
-```
-
-A Markdown chart with `interactive: true` is marked for the enhancement script; include it once in
-the page's layout with `<Enhance />` from `enarratio-astro/Enhance.astro`. It finds every
-interactive chart on the page and works with view transitions.
-
-## Options
-
-The component's props and a Markdown block's keys are the same:
-
-| Option | Used by | Notes |
-|---|---|---|
-| `type` | all | `bar` (default), `line`, `area` (stacked), `scatter` or `heatmap`. |
-| `data` | all | The data (component only; in Markdown it follows the dashes). Up to 5000 rows and 50 columns. |
-| `alt` | all | **Required.** What the chart shows and finds, in a sentence. It names the chart for screen readers. |
-| `title`, `caption` | all | Optional. The caption is for source, method or caveats. |
-| `x` | all | The column along the x axis. Column names match without regard to case. ISO dates make a time axis in line and area charts. |
-| `y` | all | The value column. Bar charts count rows when it is missing. For a heatmap, the row column. |
-| `series` | bar, line, area, scatter | Splits rows into series, told apart by color and by legend, labels or symbols. |
-| `value` | heatmap | The cell value column. |
-| `xLabel`, `yLabel` | all | Axis labels. |
-| `layout` | bar | `stacked` (default) or `grouped`. |
-| `orientation` | bar | `vertical` (default) or `horizontal`. |
-| `scale` | line, scatter | `linear` (default) or `log`. |
-| `regression` | scatter | A least-squares line with its 95% band. |
-| `dataTable` | all | `details` (default; behind a "Data table" toggle) or `visually-hidden` (screen readers only). |
-| `id` | all | The figure's id. |
-| `interactive` | all | Adds the enhancement script. Off by default, so pages stay script-free. |
-
-A chart that cannot be drawn (a column that is not in the data, text in a number column, a missing
-`alt`) is replaced by a short note saying why, and the reason is logged, so one mistake never
-breaks the page. All text is escaped.
-
-## Styles
-
-The component takes `styles`, `theme` and `stylesheetOptions`; the Markdown plugins take the same
-as options (`satteriCharts({ styles: "base" })`).
-
-- `styles: "theme"` (default): an Enarratio theme (`theme`, default Enarratio's own), in light and
-  dark. Charts follow the page's `color-scheme`; for a site that switches with an attribute, pass
-  `stylesheetOptions={{ colorScheme: { dark: '[data-theme="dark"]' } }}`.
-- `styles: "base"`: layout rules without colors or fonts, for a site whose own design tokens define
-  the `--enarratio-*` properties. [Capsomer](https://github.com/DrDustinEdwards/capsomer)'s tokens do.
-- `styles: "none"`: nothing; the site includes Enarratio's stylesheet itself.
-
-Enarratio's [README](https://github.com/DrDustinEdwards/enarratio#themes) covers themes and the
-custom properties.
-
-## Rendering cost
-
-Bar, line and area charts are drawn by `enarratio/lite`, which builds the SVG as a string with no
-DOM, the cheapest render on Cloudflare Workers. Scatter plots and heatmaps load `enarratio/plot`
-(Observable Plot and linkedom) only when a page has one.
-
-## License
-
-[MIT](LICENSE). Copyright (c) 2026 Dustin Edwards.
+# enarratio-astro
+
+**Accessible charts for [Astro](https://astro.build): a `<Chart>` component and charts in Markdown,
+drawn on the server by [Enarratio](https://github.com/DrDustinEdwards/enarratio).**
+
+A chart arrives in the page as HTML and SVG: complete before any script runs, readable by screen
+readers and search engines, with a data table, and in light and dark. It draws bar (stacked, side
+by side, vertical or horizontal; counting rows when no value column is given), line, stacked area,
+scatter (with an optional regression line and 95% band) and heatmap charts. A chart can be made
+interactive (hover and focus details, keyboard navigation, click-to-filter) with Enarratio's small
+enhancement script, which is added only to pages that ask for it.
+
+Supports Astro 6 or later. Status: 0.x, so options may change before 1.0; every change is in the
+[changelog](https://github.com/DrDustinEdwards/astro/blob/main/packages/enarratio-astro/CHANGELOG.md). For EmDash sites,
+[enarratio-emdash](https://github.com/DrDustinEdwards/astro/tree/main/packages/enarratio-emdash#readme) adds the same charts as a block
+in the editor.
+
+## Install
+
+```sh
+npm install enarratio-astro
+```
+
+## In a page
+
+```astro
+---
+import Chart from "enarratio-astro/Chart.astro";
+
+const downloads = [
+  { year: 2024, package: "Core", downloads: 4100 },
+  { year: 2025, package: "Core", downloads: 5300 },
+  { year: 2026, package: "Core", downloads: 6100 },
+  { year: 2024, package: "Plugin", downloads: 1200 },
+  { year: 2025, package: "Plugin", downloads: 1900 },
+  { year: 2026, package: "Plugin", downloads: 2800 },
+];
+---
+<Chart
+  type="line"
+  data={downloads}
+  x="year"
+  y="downloads"
+  series="package"
+  title="Downloads per year"
+  alt="Downloads per year, 2024 to 2026: the core grows from 4,100 to 6,100, the plugin from 1,200 to 2,800."
+  interactive
+/>
+```
+
+`data` is rows as objects (from code, JSON or a content collection; dates become ISO dates) or
+text: CSV, semicolon-separated, or pasted from a spreadsheet (tab-separated), first row naming the
+columns. The chart CSS is written once per page, however many charts it has.
+
+## In Markdown
+
+A code block whose language is `chart` becomes a chart: options, a line of three dashes, then the
+data.
+
+~~~md
+```chart
+type: bar
+x: team
+y: tickets
+series: status
+layout: grouped
+alt: Support has the most open tickets; Platform has closed the most.
+---
+team,status,tickets
+Support,Open,14
+Support,Closed,22
+Platform,Open,5
+Platform,Closed,31
+```
+~~~
+
+Register the plugin for Astro's Markdown processor. Astro 7's default, Sätteri:
+
+```js
+// astro.config.mjs
+import { satteri } from "@astrojs/markdown-satteri";
+import { satteriCharts } from "enarratio-astro/markdown";
+
+export default defineConfig({
+  markdown: { processor: satteri({ mdastPlugins: [satteriCharts()] }) },
+});
+```
+
+With remark (Astro 6, or Astro 7's unified processor):
+
+```js
+import { remarkCharts } from "enarratio-astro/markdown";
+
+export default defineConfig({ markdown: { remarkPlugins: [remarkCharts] } });
+```
+
+A Markdown chart with `interactive: true` is marked for the enhancement script; include it once in
+the page's layout with `<Enhance />` from `enarratio-astro/Enhance.astro`. It finds every
+interactive chart on the page and works with view transitions.
+
+## Options
+
+The component's props and a Markdown block's keys are the same:
+
+| Option | Used by | Notes |
+|---|---|---|
+| `type` | all | `bar` (default), `line`, `area` (stacked), `scatter` or `heatmap`. |
+| `data` | all | The data (component only; in Markdown it follows the dashes). Up to 5000 rows and 50 columns. |
+| `alt` | all | **Required.** What the chart shows and finds, in a sentence. It names the chart for screen readers. |
+| `title`, `subtitle` | all | Optional. Shown above the chart. |
+| `caption`, `notes` | all | Optional. The caption, under the chart, is for method or caveats; notes are a smaller line for definitions. |
+| `source`, `sourceHref` | all | Optional. Where the data came from, linked when `sourceHref` is set, beside a CSV download of the data. |
+| `byline` | all | Optional. Who made the chart. |
+| `x` | all | The column along the x axis. Column names match without regard to case. ISO dates make a time axis in line and area charts. |
+| `y` | all | The value column. Bar charts count rows when it is missing. For a heatmap, the row column. |
+| `series` | bar, line, area, scatter | Splits rows into series, told apart by color and by legend, labels or symbols. |
+| `value` | heatmap | The cell value column. |
+| `xLabel`, `yLabel` | all | Axis labels. |
+| `xUnit`, `yUnit` | all | Optional. The unit, shown after the axis label (`Sales (units)`) and in the table and summary. |
+| `layout` | bar | `stacked` (default) or `grouped`. |
+| `orientation` | bar | `vertical` (default) or `horizontal`. |
+| `scale` | line, scatter | `linear` (default) or `log`. |
+| `regression` | scatter | A least-squares line with its 95% band. |
+| `dataTable` | all | `details` (default; behind a "Data table" toggle) or `visually-hidden` (screen readers only). |
+| `id` | all | The figure's id. |
+| `interactive` | all | Adds the enhancement script. Off by default, so pages stay script-free. |
+
+A chart that cannot be drawn (a column that is not in the data, text in a number column, a missing
+`alt`) is replaced by a short note saying why, and the reason is logged, so one mistake never
+breaks the page. All text is escaped.
+
+## Styles
+
+The component takes `styles`, `theme` and `stylesheetOptions`; the Markdown plugins take the same
+as options (`satteriCharts({ styles: "base" })`).
+
+- `styles: "theme"` (default): an Enarratio theme (`theme`, default Enarratio's own), in light and
+  dark. Charts follow the page's `color-scheme`; for a site that switches with an attribute, pass
+  `stylesheetOptions={{ colorScheme: { dark: '[data-theme="dark"]' } }}`.
+- `styles: "base"`: layout rules without colors or fonts, for a site whose own design tokens define
+  the `--enarratio-*` properties. [Capsomer](https://github.com/DrDustinEdwards/capsomer)'s tokens do.
+- `styles: "none"`: nothing; the site includes Enarratio's stylesheet itself.
+
+Enarratio's [README](https://github.com/DrDustinEdwards/enarratio#themes) covers themes and the
+custom properties.
+
+## Rendering cost
+
+Bar, line and area charts are drawn by `enarratio/lite`, which builds the SVG as a string with no
+DOM, the cheapest render on Cloudflare Workers. Scatter plots and heatmaps load `enarratio/plot`
+(Observable Plot and linkedom) only when a page has one.
+
+## License
+
+[MIT](LICENSE). Copyright (c) 2026 Dustin Edwards.

package/dist/chart.d.ts

@@ -17,8 +17,18 @@ export interface ChartSpec {
     /** Required: what the chart shows and finds, in a sentence. Names the chart for screen readers. */
     readonly alt?: string | undefined;
     readonly title?: string | undefined;
-    /** Source, method or caveats, below the chart. */
+    /** A line under the title saying what the chart shows or how to read it. */
+    readonly subtitle?: string | undefined;
+    /** Method or caveats, below the chart. */
     readonly caption?: string | undefined;
+    /** Notes under the chart: what a measure means, what was left out. */
+    readonly notes?: string | undefined;
+    /** Where the data come from, in the source line beside the CSV download. */
+    readonly source?: string | undefined;
+    /** A link for the source (https). */
+    readonly sourceHref?: string | undefined;
+    /** Who made the chart, in the source line. */
+    readonly byline?: string | undefined;
     /** The column along the x axis. Column names match without regard to case. */
     readonly x?: string | undefined;
     /** The value column. Bar charts count rows without one; for a heatmap, the row column. */
@@ -29,6 +39,9 @@ export interface ChartSpec {
     readonly value?: string | undefined;
     readonly xLabel?: string | undefined;
     readonly yLabel?: string | undefined;
+    /** Units added to the axis labels and table headers: "Weight (kg)". */
+    readonly xUnit?: string | undefined;
+    readonly yUnit?: string | undefined;
     /** Bar: series stacked (default) or side by side ("grouped"). */
     readonly layout?: string | undefined;
     /** Bar: "vertical" (default) or "horizontal". */

package/dist/chart.js

@@ -28,16 +28,19 @@ function figure(spec) {
     if (!alt)
         throw new Error("Add a description (alt): one sentence on what the chart shows.");
     const title = text(spec.title);
-    const caption = text(spec.caption);
-    const xLabel = text(spec.xLabel);
-    const yLabel = text(spec.yLabel);
+    const source = text(spec.source);
+    const sourceHref = text(spec.sourceHref);
+    if (sourceHref && !source)
+        throw new Error("Name the source (source) that the link (sourceHref) goes to.");
     const id = text(spec.id)?.replace(/[^A-Za-z0-9_-]/g, "");
+    const optional = Object.fromEntries(["subtitle", "caption", "notes", "byline", "xLabel", "yLabel", "xUnit", "yUnit"]
+        .map((key) => [key, text(spec[key])])
+        .filter(([, value]) => value !== undefined));
     return {
         alt,
         ...(title ? { title } : {}),
-        ...(caption ? { caption } : {}),
-        ...(xLabel ? { xLabel } : {}),
-        ...(yLabel ? { yLabel } : {}),
+        ...optional,
+        ...(source ? { source: sourceHref ? { name: source, href: sourceHref } : source } : {}),
         ...(id ? { id } : {}),
         dataTable: spec.dataTable === "visually-hidden" ? "visually-hidden" : "details",
     };

package/dist/markdown.js

@@ -6,13 +6,20 @@ const KEYS = new Set([
     "type",
     "alt",
     "title",
+    "subtitle",
     "caption",
+    "notes",
+    "source",
+    "sourceHref",
+    "byline",
     "x",
     "y",
     "series",
     "value",
     "xLabel",
     "yLabel",
+    "xUnit",
+    "yUnit",
     "layout",
     "orientation",
     "scale",