enarratio-emdash 0.0.0-stage → 0.4.1

package/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+All notable changes to enarratio-emdash 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 or
+the saved block's fields; every such change is listed here.
+
+## [Unreleased]
+
+## [0.4.1] - 2026-11-03
+
+### Changed
+
+- Draws with enarratio-astro 0.4.1 (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
+
+- Built on enarratio-astro 0.4.0 (Enarratio 0.7.0). No block field changes.
+
+### Release
+
+- Staging works: the release job's setup-node moves from v4 to v7 (see enarratio-astro 0.4.0).
+
+- Each release's `npm pack` tarball gets a GitHub artifact attestation beside npm's provenance:
+  `gh attestation verify enarratio-emdash-<version>.tgz --repo DrDustinEdwards/astro` checks a download.
+
+## [0.3.0] - 2026-10-31
+
+### Changed
+
+- Built on enarratio-astro 0.3.0 (Enarratio 0.5.0). No block field changes.
+- First release on npm since 0.1.0: 0.2.0 and 0.2.1 never reached npm, because trusted publishing was not yet
+  set up.
+- The Data field's placeholder example and the README's theme example use neutral names.
+
+## [0.2.1] - 2026-10-31
+
+### Changed
+
+- Built on enarratio-astro 0.2.1 (Enarratio 0.4.1).
+
+## [0.2.0] - 2026-10-31
+
+### Changed
+
+- Draws with enarratio-astro 0.2.0 (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
+  caption field is now labeled for method or caveats; the source has its own field.
+
+### Added
+
+- Fields `subtitle`, `notes`, `source`, `sourceHref`, `byline`, `xUnit` and `yUnit`. Blocks saved by
+  0.1.0 draw as before.
+
+## [0.1.0] - 2026-10-24
+
+### Added
+
+- The Chart block for EmDash's Portable Text editor: bar, line, stacked area, scatter and heatmap
+  charts drawn on the server by enarratio-astro 0.1.0 (Enarratio 0.3.1) from pasted CSV or
+  spreadsheet data, with a required description, a data table, and light and dark themes.
+- Optional interactivity per chart, from Enarratio's enhancement script, added only to pages with
+  an interactive chart.
+- `enarratioPlugin({ 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

@@ -0,0 +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.

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+# enarratio-emdash
 
-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.
+**Accessible charts for [EmDash](https://github.com/emdash-cms/emdash) sites, drawn on the server by
+[Enarratio](https://github.com/DrDustinEdwards/enarratio).**
+
+The plugin adds a **Chart** block to EmDash's Portable Text editor. An editor types `/chart`, pastes
+data from a spreadsheet (or types CSV), writes one sentence saying what the chart shows, and names
+the columns to plot. The published page gets the chart 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, and
+click-to-filter, from Enarratio's small enhancement script, which is added only to pages that have
+an interactive chart.
+
+Supports EmDash 1.0 or later and 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-emdash/CHANGELOG.md).
+
+## Install
+
+```sh
+npm install enarratio-emdash
+```
+
+Register it in `astro.config.mjs`, then build and deploy the site:
+
+```js
+import emdash from "emdash/astro";
+import { enarratioPlugin } from "enarratio-emdash";
+
+export default defineConfig({
+  integrations: [
+    emdash({
+      // ...your database and storage
+      plugins: [enarratioPlugin()],
+    }),
+  ],
+});
+```
+
+Nothing else is needed: EmDash adds the plugin's renderer to its `<PortableText>` component.
+
+## Why a native plugin
+
+EmDash runs registry plugins in a sandbox, and sandboxed plugins cannot render on public pages. A
+block that draws on the page needs an Astro component loaded when the site builds, which only a
+native plugin (an npm package listed in `astro.config.mjs`) can provide. Native plugins run with the
+site's authority. This one declares no capabilities, makes no network requests and stores nothing:
+it only reads the block an editor saved and draws it.
+
+## The Chart block
+
+| Field | Used by | Notes |
+|---|---|---|
+| Chart | all | Bar, Line, Area (stacked), Scatter or Heatmap. |
+| Title, subtitle | all | Shown above the chart. Optional. |
+| Description | all | **Required.** What the chart shows and finds, in a sentence. It names the chart for screen readers. |
+| Data | all | CSV, semicolon-separated, or pasted from a spreadsheet (tab-separated). The first row names the columns. Numbers such as `1,234` (quoted in CSV) are read as numbers; an empty cell is a gap. Up to 5000 rows and 50 columns. |
+| Column along the x axis | all | Column names match without regard to case. Line and area charts read ISO dates (`2026-03-01`) as a time axis. |
+| Column of values (y) | all | Bar charts count rows when it is blank. For a heatmap, the row column. |
+| Series column | bar, line, area, scatter | Splits rows into series, told apart by color and by legend, labels or symbols. |
+| Heatmap: column of cell values | heatmap | |
+| Axis labels and units | all | Optional. A unit shows after its axis label. |
+| Caption, notes | all | Optional. The caption is for method or caveats; notes are for definitions. |
+| Source, source link, byline | all | Optional. The source line, linked when a link is given, sits beside a CSV download of the data. |
+| Bar: several series, direction | bar | Stacked or side by side; vertical or horizontal. |
+| y scale | line, scatter | Linear or logarithmic. |
+| Regression | scatter | Least-squares line with its 95% confidence band. |
+| Data table | all | Behind a "Data table" toggle (default) or hidden for screen readers only. Every chart has one. |
+| Interactive | all | Adds Enarratio's enhancement script to the page. Off by default, so pages stay script-free. |
+
+A block that cannot be drawn (a column that is not in the data, text in a number column, a missing
+description) is replaced on the page by a short note saying why, and the reason is logged, so one
+mistake never breaks the page. Text in every field is escaped.
+
+## Styles
+
+The plugin writes the chart CSS once per page that has a chart. `enarratioPlugin({ styles })` picks
+what it writes:
+
+- `"theme"` (default): Enarratio's default theme, in light and dark. Charts follow the page's
+  `color-scheme`, so a site with `<meta name="color-scheme" content="light dark">` gets dark charts
+  in dark mode.
+- `"base"`: Enarratio's 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.
+- `"none"`: nothing; the site includes Enarratio's stylesheet itself.
+
+To use your own Enarratio theme, or a theme that switches with an attribute instead of
+`color-scheme`, wrap the renderer and pass it to `<PortableText>`, which takes precedence over the
+plugin's:
+
+```astro
+---
+// src/components/SiteChart.astro
+import { Chart } from "enarratio-emdash/astro";
+import { siteTheme } from "../site-theme";
+---
+<Chart node={Astro.props.node} theme={siteTheme} stylesheetOptions={{ colorScheme: { dark: '[data-theme="dark"]' } }} />
+```
+
+```astro
+<PortableText value={post.data.content} components={{ type: { enarratioChart: SiteChart } }} />
+```
+
+Enarratio's [README](https://github.com/DrDustinEdwards/enarratio#themes) covers themes and the
+custom properties.
+
+## How it draws
+
+The block is rendered by [enarratio-astro](https://github.com/DrDustinEdwards/astro/tree/main/packages/enarratio-astro#readme)'s `Chart` component, so a chart
+saved in EmDash looks the same as one in an Astro page or a Markdown file. 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 on a page that has one.
+
+Development, the demo site and releases: the [repository README](https://github.com/DrDustinEdwards/astro#readme).
+
+## License
+
+[MIT](LICENSE). Copyright (c) 2026 Dustin Edwards.

package/dist/block.d.ts

@@ -0,0 +1,38 @@
+import type { PortableTextBlockConfig } from "emdash";
+/** The Portable Text `_type` of a chart block, and the key of its renderer. */
+export declare const BLOCK_TYPE = "enarratioChart";
+/** A saved Chart block: the editor form's values, every one optional until the chart is drawn. */
+export interface ChartNode {
+    readonly _type: string;
+    readonly _key?: string;
+    readonly chart?: string;
+    readonly title?: string;
+    readonly subtitle?: string;
+    readonly alt?: string;
+    readonly caption?: string;
+    readonly notes?: string;
+    readonly source?: string;
+    readonly sourceHref?: string;
+    readonly byline?: string;
+    readonly data?: string;
+    readonly x?: string;
+    readonly y?: string;
+    readonly series?: string;
+    readonly value?: string;
+    readonly xLabel?: string;
+    readonly yLabel?: string;
+    readonly xUnit?: string;
+    readonly yUnit?: string;
+    readonly layout?: string;
+    readonly orientation?: string;
+    readonly scale?: string;
+    readonly regression?: boolean;
+    readonly dataTable?: string;
+    readonly interactive?: boolean;
+}
+/**
+ * The chart block as the editor shows it: one form, whose `action_id`s become the saved block's
+ * properties. Every field but the chart kind, description, data and x column is optional, and
+ * the labels say which chart kinds read it.
+ */
+export declare const chartBlock: PortableTextBlockConfig;

package/dist/block.js

@@ -0,0 +1,120 @@
+/** The Portable Text `_type` of a chart block, and the key of its renderer. */
+export const BLOCK_TYPE = "enarratioChart";
+/**
+ * The chart block as the editor shows it: one form, whose `action_id`s become the saved block's
+ * properties. Every field but the chart kind, description, data and x column is optional, and
+ * the labels say which chart kinds read it.
+ */
+export const chartBlock = {
+    type: BLOCK_TYPE,
+    label: "Chart",
+    description: "An accessible chart drawn from data you paste",
+    category: "Media",
+    fields: [
+        {
+            type: "select",
+            action_id: "chart",
+            label: "Chart",
+            options: [
+                { label: "Bar", value: "bar" },
+                { label: "Line", value: "line" },
+                { label: "Area (stacked)", value: "area" },
+                { label: "Scatter", value: "scatter" },
+                { label: "Heatmap", value: "heatmap" },
+            ],
+            initial_value: "bar",
+        },
+        { type: "text_input", action_id: "title", label: "Title" },
+        {
+            type: "text_input",
+            action_id: "subtitle",
+            label: "Subtitle: how to read the chart (optional)",
+        },
+        {
+            type: "text_input",
+            action_id: "alt",
+            label: "Description (required)",
+            placeholder: "What the chart shows and what it finds, in a sentence. Screen readers read it.",
+            multiline: true,
+        },
+        {
+            type: "text_input",
+            action_id: "data",
+            label: "Data",
+            placeholder: "Paste from a spreadsheet or type CSV. The first row names the columns.\nyear,type,count\n2024,Guides,3",
+            multiline: true,
+        },
+        { type: "text_input", action_id: "x", label: "Column along the x axis" },
+        {
+            type: "text_input",
+            action_id: "y",
+            label: "Column of values (y)",
+            placeholder: "Bar charts count rows when this is blank. Heatmaps: the row column.",
+        },
+        {
+            type: "text_input",
+            action_id: "series",
+            label: "Column that splits rows into series (optional)",
+        },
+        { type: "text_input", action_id: "value", label: "Heatmap: column of cell values" },
+        { type: "text_input", action_id: "xLabel", label: "x axis label (optional)" },
+        { type: "text_input", action_id: "yLabel", label: "y axis label (optional)" },
+        { type: "text_input", action_id: "xUnit", label: "x axis unit, such as kg (optional)" },
+        { type: "text_input", action_id: "yUnit", label: "y axis unit (optional)" },
+        {
+            type: "text_input",
+            action_id: "caption",
+            label: "Caption: method or caveats (optional)",
+        },
+        { type: "text_input", action_id: "notes", label: "Notes: what a measure means (optional)" },
+        { type: "text_input", action_id: "source", label: "Source of the data (optional)" },
+        { type: "text_input", action_id: "sourceHref", label: "Link to the source, https (optional)" },
+        { type: "text_input", action_id: "byline", label: "Made by (optional)" },
+        {
+            type: "select",
+            action_id: "layout",
+            label: "Bar: several series",
+            options: [
+                { label: "Stacked", value: "stacked" },
+                { label: "Side by side", value: "grouped" },
+            ],
+            initial_value: "stacked",
+        },
+        {
+            type: "select",
+            action_id: "orientation",
+            label: "Bar: direction",
+            options: [
+                { label: "Vertical", value: "vertical" },
+                { label: "Horizontal", value: "horizontal" },
+            ],
+            initial_value: "vertical",
+        },
+        {
+            type: "select",
+            action_id: "scale",
+            label: "Line and scatter: y scale",
+            options: [
+                { label: "Linear", value: "linear" },
+                { label: "Logarithmic", value: "log" },
+            ],
+            initial_value: "linear",
+        },
+        { type: "toggle", action_id: "regression", label: "Scatter: regression line with 95% band" },
+        {
+            type: "select",
+            action_id: "dataTable",
+            label: "Data table",
+            options: [
+                { label: "Behind a Data table toggle", value: "details" },
+                { label: "Hidden, for screen readers only", value: "visually-hidden" },
+            ],
+            initial_value: "details",
+        },
+        {
+            type: "toggle",
+            action_id: "interactive",
+            label: "Interactive: hover details, keyboard navigation and filtering (adds a small script)",
+        },
+    ],
+};

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Enarratio charts for EmDash: a Chart block for the Portable Text editor, drawn on the server
+ * by Enarratio as accessible HTML and SVG.
+ *
+ * @example
+ * // astro.config.mjs
+ * import { enarratioPlugin } from "enarratio-emdash";
+ * emdash({ plugins: [enarratioPlugin()] });
+ */
+import type { PluginDescriptor, ResolvedPlugin } from "emdash";
+export { BLOCK_TYPE, type ChartNode, chartBlock } from "./block.js";
+/** Kept equal to package.json's version, which a test checks. */
+export declare const VERSION = "0.4.1";
+/** Options for {@link enarratioPlugin}. */
+export interface EnarratioPluginOptions {
+    /**
+     * The CSS the plugin writes, once per page with a chart:
+     * - `"theme"` (default): Enarratio's default theme, colors and rules, light and dark.
+     * - `"base"`: the rules without colors or fonts, for a site whose own tokens define the
+     *   `--enarratio-*` properties (Capsomer's tokens do).
+     * - `"none"`: nothing; the site includes Enarratio's stylesheet itself.
+     */
+    readonly styles?: "theme" | "base" | "none";
+}
+/** The descriptor a site lists in `astro.config.mjs`. */
+export declare function enarratioPlugin(options?: EnarratioPluginOptions): PluginDescriptor;
+/** The plugin EmDash loads at run time: the Chart block, and no capabilities, since it only draws. */
+export declare function createPlugin(): ResolvedPlugin;
+export default createPlugin;

package/dist/index.js

@@ -0,0 +1,33 @@
+import { definePlugin } from "emdash";
+import { chartBlock } from "./block.js";
+export { BLOCK_TYPE, chartBlock } from "./block.js";
+/** Kept equal to package.json's version, which a test checks. */
+export const VERSION = "0.4.1";
+const ID = "enarratio";
+const COMPONENTS = {
+    theme: "enarratio-emdash/astro",
+    base: "enarratio-emdash/astro/base",
+    none: "enarratio-emdash/astro/none",
+};
+/** The descriptor a site lists in `astro.config.mjs`. */
+export function enarratioPlugin(options = {}) {
+    return {
+        id: ID,
+        version: VERSION,
+        format: "native",
+        entrypoint: "enarratio-emdash",
+        // Astro imports the renderer while it builds the site, before any plugin option reaches it,
+        // so each styles option is its own entry.
+        componentsEntry: COMPONENTS[options.styles ?? "theme"],
+    };
+}
+/** The plugin EmDash loads at run time: the Chart block, and no capabilities, since it only draws. */
+export function createPlugin() {
+    return definePlugin({
+        id: ID,
+        version: VERSION,
+        capabilities: [],
+        admin: { portableTextBlocks: [chartBlock] },
+    });
+}
+export default createPlugin;

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "enarratio-emdash",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.1",
+  "description": "EmDash plugin: a Chart block for the Portable Text editor, drawn on the server by Enarratio as accessible HTML and SVG",
+  "keywords": [
+    "emdash",
+    "emdash-plugin",
+    "astro",
+    "charts",
+    "accessibility",
+    "enarratio"
+  ],
+  "license": "MIT",
+  "author": "Dustin Edwards (https://dustinedwards.info)",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./astro": "./src/astro/index.ts",
+    "./astro/base": "./src/astro/base.ts",
+    "./astro/none": "./src/astro/none.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.22"
+  },
+  "peerDependencies": {
+    "astro": "7.4.4",
+    "emdash": "1.4.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "homepage": "https://github.com/DrDustinEdwards/astro/tree/main/packages/enarratio-emdash#readme",
+  "bugs": {
+    "url": "https://github.com/DrDustinEdwards/astro/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DrDustinEdwards/astro.git",
+    "directory": "packages/enarratio-emdash"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "enarratio-astro": "0.4.1"
+  }
+}

package/src/astro/Chart.astro

@@ -0,0 +1,46 @@
+---
+/**
+ * Renders a saved Chart block with enarratio-astro's Chart. EmDash passes the block as `node`;
+ * the plugin's `styles` option picks the entry (astro, astro/base, astro/none) and so the `styles`
+ * prop. A site can also wrap this component to pass its own Enarratio theme, and register the
+ * wrapper through `<PortableText components={{ type: { enarratioChart: MyChart } }}>`.
+ */
+import type { StyleOptions } from "enarratio-astro";
+import Chart from "enarratio-astro/Chart.astro";
+import type { ChartNode } from "../block.ts";
+
+interface Props extends StyleOptions {
+  node: ChartNode;
+}
+
+const { node, ...style } = Astro.props;
+---
+
+<Chart
+  type={node.chart}
+  data={node.data ?? ""}
+  alt={node.alt}
+  title={node.title}
+  subtitle={node.subtitle}
+  caption={node.caption}
+  notes={node.notes}
+  source={node.source}
+  sourceHref={node.sourceHref}
+  byline={node.byline}
+  x={node.x}
+  y={node.y}
+  series={node.series}
+  value={node.value}
+  xLabel={node.xLabel}
+  yLabel={node.yLabel}
+  xUnit={node.xUnit}
+  yUnit={node.yUnit}
+  layout={node.layout}
+  orientation={node.orientation}
+  scale={node.scale}
+  regression={node.regression}
+  dataTable={node.dataTable}
+  id={node._key ? `chart-${node._key}` : undefined}
+  interactive={node.interactive === true}
+  {...style}
+/>

package/src/astro/ChartBase.astro

@@ -0,0 +1,6 @@
+---
+/** The Chart block with Enarratio's rules but no colors: the site's tokens define them. */
+import Chart from "./Chart.astro";
+---
+
+<Chart node={Astro.props.node} styles="base" />

package/src/astro/ChartUnstyled.astro

@@ -0,0 +1,6 @@
+---
+/** The Chart block with no CSS of its own: the site includes Enarratio's stylesheet itself. */
+import Chart from "./Chart.astro";
+---
+
+<Chart node={Astro.props.node} styles="none" />

package/src/astro/base.ts

@@ -0,0 +1,4 @@
+/** The renderer for `enarratioPlugin({ styles: "base" })`: Enarratio's rules, the site's colors. */
+import ChartBase from "./ChartBase.astro";
+
+export const blockComponents = { enarratioChart: ChartBase };

package/src/astro/env.d.ts

@@ -0,0 +1,7 @@
+// The type checker does not read .astro files; Astro's own compiler checks them when a site builds.
+declare module "*.astro" {
+  import type { AstroComponentFactory } from "astro/runtime/server/index.js";
+
+  const component: AstroComponentFactory;
+  export default component;
+}

package/src/astro/index.ts

@@ -0,0 +1,9 @@
+/**
+ * The site-side renderer EmDash merges into `<PortableText>`, writing the default theme's CSS.
+ * The key must equal the block's `_type` (BLOCK_TYPE). `./base` and `./none` are the same
+ * renderer for the plugin's other `styles` options.
+ */
+import Chart from "./Chart.astro";
+
+export const blockComponents = { enarratioChart: Chart };
+export { Chart };

package/src/astro/none.ts

@@ -0,0 +1,4 @@
+/** The renderer for `enarratioPlugin({ styles: "none" })`: no CSS from the plugin. */
+import ChartUnstyled from "./ChartUnstyled.astro";
+
+export const blockComponents = { enarratioChart: ChartUnstyled };

package/src/block.ts

@@ -0,0 +1,154 @@
+import type { PortableTextBlockConfig } from "emdash";
+
+/** The Portable Text `_type` of a chart block, and the key of its renderer. */
+export const BLOCK_TYPE = "enarratioChart";
+
+/** A saved Chart block: the editor form's values, every one optional until the chart is drawn. */
+export interface ChartNode {
+  readonly _type: string;
+  readonly _key?: string;
+  readonly chart?: string;
+  readonly title?: string;
+  readonly subtitle?: string;
+  readonly alt?: string;
+  readonly caption?: string;
+  readonly notes?: string;
+  readonly source?: string;
+  readonly sourceHref?: string;
+  readonly byline?: string;
+  readonly data?: string;
+  readonly x?: string;
+  readonly y?: string;
+  readonly series?: string;
+  readonly value?: string;
+  readonly xLabel?: string;
+  readonly yLabel?: string;
+  readonly xUnit?: string;
+  readonly yUnit?: string;
+  readonly layout?: string;
+  readonly orientation?: string;
+  readonly scale?: string;
+  readonly regression?: boolean;
+  readonly dataTable?: string;
+  readonly interactive?: boolean;
+}
+
+/**
+ * The chart block as the editor shows it: one form, whose `action_id`s become the saved block's
+ * properties. Every field but the chart kind, description, data and x column is optional, and
+ * the labels say which chart kinds read it.
+ */
+export const chartBlock: PortableTextBlockConfig = {
+  type: BLOCK_TYPE,
+  label: "Chart",
+  description: "An accessible chart drawn from data you paste",
+  category: "Media",
+  fields: [
+    {
+      type: "select",
+      action_id: "chart",
+      label: "Chart",
+      options: [
+        { label: "Bar", value: "bar" },
+        { label: "Line", value: "line" },
+        { label: "Area (stacked)", value: "area" },
+        { label: "Scatter", value: "scatter" },
+        { label: "Heatmap", value: "heatmap" },
+      ],
+      initial_value: "bar",
+    },
+    { type: "text_input", action_id: "title", label: "Title" },
+    {
+      type: "text_input",
+      action_id: "subtitle",
+      label: "Subtitle: how to read the chart (optional)",
+    },
+    {
+      type: "text_input",
+      action_id: "alt",
+      label: "Description (required)",
+      placeholder: "What the chart shows and what it finds, in a sentence. Screen readers read it.",
+      multiline: true,
+    },
+    {
+      type: "text_input",
+      action_id: "data",
+      label: "Data",
+      placeholder:
+        "Paste from a spreadsheet or type CSV. The first row names the columns.\nyear,type,count\n2024,Guides,3",
+      multiline: true,
+    },
+    { type: "text_input", action_id: "x", label: "Column along the x axis" },
+    {
+      type: "text_input",
+      action_id: "y",
+      label: "Column of values (y)",
+      placeholder: "Bar charts count rows when this is blank. Heatmaps: the row column.",
+    },
+    {
+      type: "text_input",
+      action_id: "series",
+      label: "Column that splits rows into series (optional)",
+    },
+    { type: "text_input", action_id: "value", label: "Heatmap: column of cell values" },
+    { type: "text_input", action_id: "xLabel", label: "x axis label (optional)" },
+    { type: "text_input", action_id: "yLabel", label: "y axis label (optional)" },
+    { type: "text_input", action_id: "xUnit", label: "x axis unit, such as kg (optional)" },
+    { type: "text_input", action_id: "yUnit", label: "y axis unit (optional)" },
+    {
+      type: "text_input",
+      action_id: "caption",
+      label: "Caption: method or caveats (optional)",
+    },
+    { type: "text_input", action_id: "notes", label: "Notes: what a measure means (optional)" },
+    { type: "text_input", action_id: "source", label: "Source of the data (optional)" },
+    { type: "text_input", action_id: "sourceHref", label: "Link to the source, https (optional)" },
+    { type: "text_input", action_id: "byline", label: "Made by (optional)" },
+    {
+      type: "select",
+      action_id: "layout",
+      label: "Bar: several series",
+      options: [
+        { label: "Stacked", value: "stacked" },
+        { label: "Side by side", value: "grouped" },
+      ],
+      initial_value: "stacked",
+    },
+    {
+      type: "select",
+      action_id: "orientation",
+      label: "Bar: direction",
+      options: [
+        { label: "Vertical", value: "vertical" },
+        { label: "Horizontal", value: "horizontal" },
+      ],
+      initial_value: "vertical",
+    },
+    {
+      type: "select",
+      action_id: "scale",
+      label: "Line and scatter: y scale",
+      options: [
+        { label: "Linear", value: "linear" },
+        { label: "Logarithmic", value: "log" },
+      ],
+      initial_value: "linear",
+    },
+    { type: "toggle", action_id: "regression", label: "Scatter: regression line with 95% band" },
+    {
+      type: "select",
+      action_id: "dataTable",
+      label: "Data table",
+      options: [
+        { label: "Behind a Data table toggle", value: "details" },
+        { label: "Hidden, for screen readers only", value: "visually-hidden" },
+      ],
+      initial_value: "details",
+    },
+    {
+      type: "toggle",
+      action_id: "interactive",
+      label: "Interactive: hover details, keyboard navigation and filtering (adds a small script)",
+    },
+  ],
+};

package/src/index.ts

@@ -0,0 +1,61 @@
+/**
+ * Enarratio charts for EmDash: a Chart block for the Portable Text editor, drawn on the server
+ * by Enarratio as accessible HTML and SVG.
+ *
+ * @example
+ * // astro.config.mjs
+ * import { enarratioPlugin } from "enarratio-emdash";
+ * emdash({ plugins: [enarratioPlugin()] });
+ */
+import type { PluginDescriptor, ResolvedPlugin } from "emdash";
+import { definePlugin } from "emdash";
+import { chartBlock } from "./block.js";
+
+export { BLOCK_TYPE, type ChartNode, chartBlock } from "./block.js";
+
+/** Kept equal to package.json's version, which a test checks. */
+export const VERSION = "0.4.1";
+const ID = "enarratio";
+
+/** Options for {@link enarratioPlugin}. */
+export interface EnarratioPluginOptions {
+  /**
+   * The CSS the plugin writes, once per page with a chart:
+   * - `"theme"` (default): Enarratio's default theme, colors and rules, light and dark.
+   * - `"base"`: the rules without colors or fonts, for a site whose own tokens define the
+   *   `--enarratio-*` properties (Capsomer's tokens do).
+   * - `"none"`: nothing; the site includes Enarratio's stylesheet itself.
+   */
+  readonly styles?: "theme" | "base" | "none";
+}
+
+const COMPONENTS = {
+  theme: "enarratio-emdash/astro",
+  base: "enarratio-emdash/astro/base",
+  none: "enarratio-emdash/astro/none",
+} as const;
+
+/** The descriptor a site lists in `astro.config.mjs`. */
+export function enarratioPlugin(options: EnarratioPluginOptions = {}): PluginDescriptor {
+  return {
+    id: ID,
+    version: VERSION,
+    format: "native",
+    entrypoint: "enarratio-emdash",
+    // Astro imports the renderer while it builds the site, before any plugin option reaches it,
+    // so each styles option is its own entry.
+    componentsEntry: COMPONENTS[options.styles ?? "theme"],
+  };
+}
+
+/** The plugin EmDash loads at run time: the Chart block, and no capabilities, since it only draws. */
+export function createPlugin(): ResolvedPlugin {
+  return definePlugin({
+    id: ID,
+    version: VERSION,
+    capabilities: [],
+    admin: { portableTextBlocks: [chartBlock] },
+  });
+}
+
+export default createPlugin;