@martinomagnifico/tablechart 1.0.3 → 1.0.4

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [1.0.4] - 2026-10-14
+
+### Added
+
+- `--tablechart-animation-element-duration`, `--tablechart-animation-stagger` and `--tablechart-animation-max`: the time of one element, when the next one starts, and a ceiling for a whole chart, which is 4x the standard element duration, so 2s by default.
+- `data-chart-animate="sweep"` on a donut draws the ring in one sweep, and on a waterfall builds it at one speed.
+
+### Changed
+
+- A large chart builds within 2s: the starts of its elements move closer together.
+- A waterfall grows column by column, one after the other: its stagger is 0.6 by default. Under the maximum its columns get shorter.
+- CSS variables that set the same part of a chart now start there variable name in the same way, such as `--tablechart-animation-` and `--tablechart-name-`. See the list of old and new names on the CSS variables page.
+- `--tablechart-name-size` now sets all names, also those under the bars.
+- The callout of an annotation is now called the badge in the docs, like its variables.
+- `data-chart-animate` and the `animate` option take `grow` and `sweep`, the same on every chart type. `up` and `across` are the old names.
+- The types are now `tablechart.d.mts` and `tablechart-core.d.mts`, next to the ES modules, and share `tablechart-shared.d.mts` like the modules share their code. They are made with rolldown-plugin-dts instead of API Extractor.
+
+### Fixed
+
+- With steps, the closing total of a waterfall grows from the baseline if the column before it is not there yet.
+- Importing `@martinomagnifico/tablechart/core` in TypeScript no longer fails with "Cannot find name 'TablechartChart'".
+
+### Deprecated
+
+- The old variable names and the animate values `up` and `across`, removed in the next minor version. The console lists the ones a page still uses.
+
+
 ## [1.0.3] - 2026-10-11
 
 ### Added

package/README.md

@@ -14,7 +14,7 @@ Tablechart makes simple charts from a table: an HTML table, a Markdown table or
 * **The table stays:** it is hidden from sight, but screen readers, search engines and translation scripts still read it. Without JavaScript, the table is all there is.
 * **Real text:** names and numbers are HTML, so they use the font of the page and do not scale with the drawing.
 * **CSS for the looks:** colours, sizes and animation are CSS variables. Light and dark mode follow the page.
-* **Annotations:** callouts, brackets, trend arrows and a break in the scale
+* **Annotations:** badges, brackets, trend arrows and a break in the scale
 * **Step by step:** show the rows one at a time, with Previous and Next buttons
 * **Animation:** a chart builds when it scrolls into view
 
@@ -70,7 +70,7 @@ Use `bar`, `line`, `area`, `waterfall` or `donut` for the other types. With more
 
 ```js
 init({
-	animate: true,      // Animate a chart when it builds: true, false, "across" or "up"
+	animate: true,      // Animate a chart when it builds: true, false, "grow" or "sweep"
 	threshold: 0.5,     // How much of a chart must be in view before it builds
 	replay: false,      // Build again each time a chart scrolls back into view
 	controls: true,     // Previous and Next buttons on a chart that steps

package/dist/tablechart-core.d.mts

@@ -0,0 +1,26 @@
+import { _ as stepTo, c as PLACED_CLASS, d as SHOWN_CLASS, f as defaultConfig, g as StepPlan, h as Series, i as entranceOf, l as PLOT_CLASS, m as Row, o as prepare, p as ChartState, s as Config, u as QUEUED_CLASS } from "./tablechart-shared.mjs";
+//#region src/js/core.d.ts
+/** Pass 2: everything a reader will read, before a translation script looks. */
+export declare const build: (figure: HTMLElement, config: Config, asKind?: string | null) => ChartState | null;
+/** Pass 3. Needs layout; makes no text, only places it. */
+export declare const layout: (state: ChartState, config: Config) => boolean;
+/** Numbers are reformatted in place, so a language change costs no redraw. */
+export declare const relabel: (state: ChartState, config: Config) => void;
+/** Removes what `build` added, so the chart can be built again. */
+export declare const unbuild: (state: ChartState) => void;
+/** One class, `is-shown`, starts the whole build. */
+export declare const setShown: (state: ChartState, shown: boolean) => void;
+//#endregion
+//#region src/js/functions/sources.d.ts
+/** A Markdown table, or a caption with chart attributes, is wrapped in a div with the caption and annotations beside it. */
+export declare const adoptTables: (figures: HTMLElement[]) => HTMLElement[];
+/** `data-chart-src` fills the figure's table with the rows of a JSON file, keeping a header row the author wrote; a file that fails is reported. */
+export declare const loadSources: (figures: HTMLElement[]) => Promise<void>;
+/** In a Markdown table, a bold label makes the row a total, and a bold header puts that series in focus. */
+export declare const readMarkdownRows: (figures: HTMLElement[]) => void;
+//#endregion
+//#region src/js/functions/read-table.d.ts
+/** Writes translation keys such as `harvest-row1` onto a figure with `data-chart-keys`; a duplicate prefix gets a number. */
+export declare const assignKeys: (figures: HTMLElement[], langattribute: string | false) => void;
+//#endregion
+export { type ChartState, type Config, PLACED_CLASS, PLOT_CLASS, QUEUED_CLASS, type Row, SHOWN_CLASS, type Series, type StepPlan, defaultConfig, entranceOf, prepare, stepTo };

package/dist/tablechart-core.mjs

@@ -1,2 +1 @@
-import { _ as e, a as t, c as n, d as r, f as i, g as a, h as o, i as s, l as c, m as l, n as u, o as d, p as f, s as p, u as m, v as h, y as g } from "./tablechart-shared.mjs";
-export { o as PLACED_CLASS, a as PLOT_CLASS, e as QUEUED_CLASS, h as SHOWN_CLASS, t as adoptTables, l as assignKeys, n as build, g as defaultConfig, u as entranceOf, c as layout, d as loadSources, s as prepare, p as readMarkdownRows, m as relabel, r as setShown, f as stepTo, i as unbuild };
+export { h as PLACED_CLASS, g as PLOT_CLASS, _ as QUEUED_CLASS, v as SHOWN_CLASS, a as adoptTables, m as assignKeys, c as build, y as defaultConfig, n as entranceOf, l as layout, o as loadSources, i as prepare, s as readMarkdownRows, u as relabel, d as setShown, p as stepTo, f as unbuild } from "./tablechart-shared.mjs";

package/dist/tablechart-shared.d.mts

@@ -0,0 +1,302 @@
+//#region src/js/functions/scale.d.ts
+/** A break in the scale: values from `lo` to `hi` get `share` of the length, and the cut is at `gap`. */
+interface Squeeze {
+  lo: number;
+  hi: number;
+  gap: number;
+  share: number;
+}
+//#endregion
+//#region src/js/steps.d.ts
+/** The steps of one chart: which step shows each row, column and annotation, and how many steps there are. */
+interface StepPlan {
+  rows: {
+    step: number | null;
+    slot: number;
+  }[];
+  series: {
+    step: number | null;
+  }[];
+  /** A cell on a step of its own, by row and then by column. */
+  cells: {
+    step: number | null;
+    slot: number;
+  }[][];
+  notes: {
+    step: number | null;
+    after: number;
+  }[];
+  count: number;
+  /** The `data-fragment-index` of each step, if it asked for one, so a presentation can make a fragment for each. */
+  indexes: (string | null)[];
+}
+/**
+ * Shows the chart up to step `step`, from 0 (only what has no step) to the number of steps (all of it).
+ * Says so with a `tablechart:step` event on the figure, unless `quietly`.
+ */
+declare const stepTo: (state: ChartState, step: number, quietly?: boolean) => void;
+//#endregion
+//#region src/js/types.d.ts
+/** How a line or an area runs from one point to the next. */
+type Shape = "straight" | "step" | "smooth";
+/** How a chart builds: each element grows from zero, or the chart is revealed in one movement. */
+type Motion = "grow" | "sweep";
+interface Cell {
+  raw: string;
+  /** As written, so its decimal places survive. Empty when the cell holds no number. */
+  number: string;
+  /** Text around the number, such as `%` or a footnote `*`, kept either side of the formatted number. */
+  prefix: string;
+  suffix: string;
+  /** No number, such as "n/a": no mark, and the label says what the cell says. Counts as zero. */
+  missing: boolean;
+  value: number;
+}
+interface Row extends Cell {
+  label: string;
+  key: string | null;
+  cells: Cell[];
+  /** Copied to everything drawn for the row, so one class styles all of it. */
+  classes: string[];
+  isTotal: boolean;
+  /** The stagger counts from here. */
+  slot: number;
+}
+interface Series {
+  name: string;
+  key: string | null;
+  /** `data-kind="focus"`, or bold in Markdown: the others are shown fainter. */
+  focus: boolean;
+  /** `data-marker` on the header, such as `square` or `diamond open`. */
+  marker: string | null;
+  line: "dashed" | "dotted" | null;
+}
+interface Segment extends Row {
+  from: number;
+  to: number;
+  kind: "bar" | "up" | "down" | "total";
+}
+/** Scales only, no pixel positions, so an annotation follows the data. */
+interface Geometry {
+  rows: Row[];
+  segments: Segment[];
+  cx: (index: number) => number;
+  y: (value: number) => number;
+  barWidth: number;
+  barMax: number;
+  height: number;
+  /** viewBox units per screen pixel. */
+  unit: number;
+  labelHeight: number;
+  badgeHeight: number;
+  /** How many stagger steps the data takes, so commentary can land after it. */
+  after: number;
+  /** An annotation's number in the figure, from 1, set as `data-note` on its marks. Zero for the chart. */
+  note: number;
+  /** Where the break's mark goes, as a value. Null when the scale runs straight through. */
+  breakAt: number | null;
+  /** The break itself, for a chart that makes a scale of its own, such as a bar chart. */
+  squeeze: Squeeze | null;
+  /** The empty space where the scale jumps, in viewBox units. */
+  breakGap: number;
+  /** Where a bar chart is cut across, in viewBox units; set by its drawing. */
+  breakX?: number;
+  labels: "outside" | "inside";
+  /** Where a number inside its bar goes, from `--tablechart-value-align`; null for the chart's own default. */
+  insideAlign: "start" | "center" | "end" | null;
+  stacked: boolean;
+  shape: Shape;
+  /** Empty when the chart is not stacked or its kind shows no totals. */
+  totals: HTMLElement[];
+  svg: SVGSVGElement;
+  plot: HTMLElement;
+  /** Made by `build`; a chart only places them. */
+  values: HTMLElement[];
+  series: Series[];
+  seriesValues: HTMLElement[][];
+  /** Empty with one series. */
+  names: HTMLElement[];
+  /** A chart with its names beside the marks places these; one with them under the plot does not. */
+  categories: HTMLElement[];
+  centre: HTMLElement | null;
+  config: Config;
+  /** Numbers an annotation worked out, against the ones the author wrote. */
+  checks: Check[];
+}
+interface Check {
+  label: string;
+  computed: number;
+  stated: number;
+  agrees: boolean;
+}
+interface ChartType {
+  aspect?: number;
+  /** A row marked as a total goes in the middle rather than among the marks. */
+  centre?: boolean;
+  /** A break in the scale works here; a waterfall keeps its floating steps clear of it. */
+  breakable?: boolean;
+  stackable?: boolean;
+  /** A stack is a running sum, so each line follows the one under it; otherwise values below zero stack down from zero. */
+  running?: boolean;
+  totals?: boolean;
+  /** The sample in front of a legend name when it is not a line; the legend shows only when asked. */
+  swatch?: "box";
+  categories?: "under" | "beside";
+  series?: boolean;
+  /** With several series, always a legend, with a sample of this shape. */
+  legend?: "box";
+  headroom?: (geo: HeadroomInput) => number;
+  minHeight?: (input: {
+    labelHeight: number;
+    nameHeight: number;
+    unit: number;
+    rows: number;
+    series: number;
+    stacked: boolean;
+  }) => number;
+  /** Room under the baseline for numbers that hang below a mark near it. */
+  footroom?: (geo: HeadroomInput) => number;
+  /** Default: one bar per row from the baseline. */
+  segments?: (rows: Row[]) => Segment[];
+  draw: (geo: Geometry) => void;
+}
+interface HeadroomInput {
+  labelHeight: number;
+  badgeHeight: number;
+  hasAnnotations: boolean;
+  unit: number;
+  series: number;
+  focused: boolean;
+  stacked: boolean;
+}
+/** `create` runs before layout, so a translation script finds its text; `draw` only places it. */
+interface AnnotationType {
+  create: (spec: HTMLElement, plot: HTMLElement) => HTMLElement | null;
+  draw: (spec: HTMLElement, badge: HTMLElement | null, geo: Geometry) => void;
+}
+interface ChartState {
+  figure: HTMLElement;
+  plot: HTMLElement;
+  svg: SVGSVGElement;
+  rows: Row[];
+  decimals: number;
+  type: ChartType;
+  values: HTMLElement[];
+  series: Series[];
+  seriesValues: HTMLElement[][];
+  names: HTMLElement[];
+  categories: HTMLElement[];
+  centre: HTMLElement | null;
+  stacked: boolean;
+  totals: HTMLElement[];
+  totalCell: HTMLElement | null;
+  /** In screen pixels from the plot's corner. Null for a chart whose rows are not side by side. */
+  rowAt: ((x: number, y: number) => number | null) | null;
+  /** As percentages: left, top, width and height. */
+  rowBox: ((index: number) => [number, number, number, number]) | null;
+  annotations: {
+    spec: HTMLElement;
+    type: AnnotationType;
+    badge: HTMLElement | null;
+    /** From 0; `data-series` counts from 1. */
+    series: number;
+    after: number;
+  }[];
+  /** The steps of a chart that steps (`data-fragment`); null for one that does not. */
+  plan: StepPlan | null;
+  /** How many steps are shown. */
+  step: number;
+  /** The Previous and Next buttons, if Tablechart made them. */
+  controls: HTMLElement | null;
+  checks: Check[];
+}
+//#endregion
+//#region src/js/config.d.ts
+declare const PLOT_CLASS = "tablechart-plot";
+declare const PLACED_CLASS = "is-placed";
+declare const SHOWN_CLASS = "is-shown";
+declare const QUEUED_CLASS = "tablechart-queued";
+interface Config {
+  /** Which elements Tablechart turns into charts. */
+  selector: string;
+  /** Height of the plot as a share of its width. */
+  aspect: number;
+  /** Share of a band that a bar fills. */
+  barfill: number;
+  /** Share of a donut's radius that the ring itself takes. */
+  ringfill: number;
+  /** Locale for numbers. Unset, the document's language is used and followed when it changes. */
+  locale?: string;
+  /** Animate a chart when it builds. `"grow"` grows each element from zero, `"sweep"` reveals the chart in one movement; a figure overrides it with `data-chart-animate`. `"up"` and `"across"` are their old names. */
+  animate: boolean | Motion | "across" | "up";
+  /** How far an animated parent is in before its chart builds: 0 when it starts moving, 1 when it is in. A figure overrides it with `data-chart-entrance`. */
+  entrance: number;
+  /** Where a column's number goes: on the bar, or inside it. A figure overrides it with `data-chart-labels`. */
+  labels: "outside" | "inside";
+  /** How a line or area runs between points: `straight`, `step` or `smooth`. A figure overrides it with `data-chart-shape`. */
+  shape: "straight" | "step" | "smooth";
+  /** Names of several lines in a legend instead of at the end of each line. A figure overrides it with `data-chart-legend`. */
+  legend: boolean;
+  /** Pointing at a row shows numbers that were left out for lack of room. A figure turns it off with `data-chart-hover="false"`. */
+  hover: boolean;
+  /** The name of the total that a donut without a total row works out, for screen readers. */
+  totallabel: string;
+  /** Previous and Next buttons under a chart that steps (`data-fragment`). `false` leaves them out, for buttons of your own. */
+  controls: boolean;
+  /** The text of the Previous button. */
+  previouslabel: string;
+  /** The text of the Next button. */
+  nextlabel: string;
+  /** Read by screen readers after the text of each button, so they know it only changes the chart. */
+  stephint: string;
+  /** How much of a chart must be in view before it builds, from 0 to 1. */
+  threshold: number;
+  /** Build again each time a chart scrolls back into view, not only the first time. */
+  replay: boolean;
+  /** The attribute for translation keys, for a translation script. `false` turns keys off. */
+  langattribute: string | false;
+  /** Show messages in the console for whoever is working on the page. */
+  debug?: boolean;
+}
+declare const defaultConfig: Config;
+//#endregion
+//#region src/js/init.d.ts
+interface TablechartChart {
+  figure: HTMLElement;
+  /** Lays the chart out again, for example after a script has changed its text. */
+  refresh(): void;
+  /** Stops watching scroll, size and language. The chart stays as it is. */
+  destroy(): void;
+  /** On a chart that steps (`data-fragment`): shows one step more. */
+  next(): void;
+  /** On a chart that steps: shows one step less. */
+  previous(): void;
+  /** On a chart that steps: shows the chart up to `step`, from 0 to `steps`. */
+  stepTo(step: number): void;
+  /** How many steps are shown. */
+  readonly step: number;
+  /** How many steps the chart has; 0 for a chart that does not step. */
+  readonly steps: number;
+}
+interface TablechartInstance {
+  charts: TablechartChart[];
+  /** Lays out every chart again, for example after a script has changed its text. */
+  refresh(): void;
+  /** Stops watching scroll, size and language. The charts stay as they are. */
+  destroy(): void;
+}
+declare global {
+  interface HTMLElement {
+    tablechart?: TablechartChart;
+  }
+}
+/** How far an animated parent is in before the chart builds: the figure's `data-chart-entrance`, or else the option. */
+declare const entranceOf: (figure: HTMLElement, config: Config) => number;
+/** Turns elements into figures with a table and translation keys, all at once, so duplicate keys are found. */
+declare const prepare: (found: HTMLElement[], config: Config) => Promise<HTMLElement[]>;
+/** Makes a chart of one element; returns the existing chart if there is one, or null without data. */
+declare const create: (element: HTMLElement, options?: Partial<Config>) => Promise<TablechartChart | null>;
+/** Makes a chart of every element in `root` that matches the selector, skipping existing charts. */
+declare const init: (options?: Partial<Config>, root?: ParentNode) => Promise<TablechartInstance>;
+//#endregion
+export { stepTo as _, init as a, PLACED_CLASS as c, SHOWN_CLASS as d, defaultConfig as f, StepPlan as g, Series as h, entranceOf as i, PLOT_CLASS as l, Row as m, TablechartInstance as n, prepare as o, ChartState as p, create as r, Config as s, TablechartChart as t, QUEUED_CLASS as u };