@martinomagnifico/tablechart 1.0.2 → 1.0.3

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [1.0.3] - 2026-10-11
+
+### Added
+
+- Changes to handling of JSON data sources. A header row written in the figure table markup, if missing from the data source, is then used.
+- Values below zero on column, bar, line, area and waterfall charts, also in stacks.
+
+### Changed
+
+- A waterfall builds one step at a time: a column grows, then its connector draws, then the next column.
+
+### Removed
+
+- The `closing` option and `data-chart-closing`. The last total of a waterfall always grows from the last connector to the baseline.
+
+### Fixed
+
+- A chart's hidden table no longer adds empty pages in print.
+
+
 ## [1.0.2] - 2026-10-10
 
 ### Added

package/README.md

@@ -1,13 +1,30 @@
 # Tablechart
 
-Simple charts from an HTML or Markdown table: column, bar, line, area,
-waterfall and donut, with annotations. A chart builds when it scrolls into
-view. Charts are SVG and use the colours of the page, which you can change with
-CSS variables.
+[![Version](https://img.shields.io/npm/v/@martinomagnifico/tablechart)](https://www.npmjs.com/package/@martinomagnifico/tablechart)
 
-> Work in progress. The documentation site is in `docs/`.
+[<img src="screenshot.png" width="100%" alt="Tablechart: a column chart, a donut and a waterfall">](https://martinomagnifico.github.io/tablechart/)
 
-## Install
+----
+
+## What is it?
+
+Tablechart makes simple charts from a table: an HTML table, a Markdown table or a JSON file. You write the table, Tablechart shows it as a chart.
+
+* **Chart types:** column, bar, line, area, waterfall and donut
+* **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
+* **Step by step:** show the rows one at a time, with Previous and Next buttons
+* **Animation:** a chart builds when it scrolls into view
+
+----
+
+**Documentation:** every chart type, option and CSS variable, with live examples, is at <https://martinomagnifico.github.io/tablechart/>. This README is a quick start.
+
+----
+
+## Installation
 
 ```sh
 npm install @martinomagnifico/tablechart
@@ -26,46 +43,48 @@ Or with a script tag:
 <link rel="stylesheet" href="tablechart.css">
 <script src="tablechart.js"></script>
 <script>
-    Tablechart.init();
+	Tablechart.init();
 </script>
 ```
 
-## Markup
+## A chart
 
-A chart is an element with `data-chart` and a table in it. The first cell of a
-row is the label, the second the value.
+A chart is a `figure` with `data-chart` and a table in it. The first cell of a row is its name, the other cells are its values. The `figcaption` is the title; text after a `br` is the subtitle.
 
 ```html
 <figure data-chart="column">
-    <figcaption><b>Apples picked</b><br><span>thousands</span></figcaption>
-    <table>
-        <tbody>
-            <tr><th>Spring</th><td>58</td></tr>
-            <tr><th>Summer</th><td>72</td></tr>
-            <tr><th>Autumn</th><td>70</td></tr>
-        </tbody>
-    </table>
+	<figcaption><b>Apples picked</b><br><span>thousands</span></figcaption>
+	<table>
+		<tbody>
+			<tr><th>Spring</th><td>58</td></tr>
+			<tr><th>Summer</th><td>72</td></tr>
+			<tr><th>Autumn</th><td>70</td></tr>
+		</tbody>
+	</table>
 </figure>
 ```
 
+Use `bar`, `line`, `area`, `waterfall` or `donut` for the other types. With more than one value column, each column is a line, or a bar in each group. Add `data-chart-stack` to stack them.
+
 ## Options
 
 ```js
 init({
-    selector: "[data-chart]", // The elements to make charts of
-    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
-    animate: true,            // Animate the chart when it builds
-    langattribute: "data-i18n", // The attribute for translation keys, or false for none
-    debug: false
+	animate: true,      // Animate a chart when it builds: true, false, "across" or "up"
+	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
+	locale: undefined,  // Locale for numbers; the language of the page if not set
 });
 ```
 
-`init` returns `{ charts, refresh, destroy }`. `refresh()` lays out every chart
-again. `destroy()` stops watching scroll, size and language changes.
+Most options can also be set on one chart with a `data-chart-*` attribute. All options are in the [options reference](https://martinomagnifico.github.io/tablechart/reference/options.html).
 
-To make a chart of one element, use `create`. Each chart is also on its element,
-as `element.tablechart`:
+## API
+
+`init()` returns `{ charts, refresh, destroy }`. `refresh()` lays out every chart again. `destroy()` stops watching scroll, size and language changes.
+
+To make a chart of one element, use `create()`. Each chart is also on its element, as `element.tablechart`.
 
 ```js
 import { create } from "@martinomagnifico/tablechart";
@@ -74,19 +93,27 @@ const chart = await create(document.querySelector("#sales"));
 chart.refresh();
 ```
 
-## Bar width
+For a script that decides itself when a chart builds, `@martinomagnifico/tablechart/core` has the separate steps. See the [API reference](https://martinomagnifico.github.io/tablechart/reference/api.html).
+
+## Styling
+
+Tablechart uses the colours of the page. To change them, set CSS variables on a chart or on a parent:
+
+```css
+.sales {
+	--tablechart-bar-color: teal;
+	--tablechart-value-size: 1.2em;
+}
+```
+
+All variables are in the [CSS variables reference](https://martinomagnifico.github.io/tablechart/reference/variables.html).
 
-A column, a waterfall step or a bar is never wider than `--tablechart-bar-max`,
-60px by default. Use any of `px`, `%` (of the chart's width), `em` or `rem`. In a
-narrow chart, bars are 58% of their space. Set `--tablechart-bar-max: none` for
-no maximum.
+## Reveal.js
 
-## Height
+For charts in a Reveal.js presentation, with fragments that step a chart, use [reveal.js-tablechart](https://github.com/Martinomagnifico/reveal.js-tablechart).
 
-The height of a chart is a share of its width: `data-chart-aspect`, 0.38 by
-default. On a narrow screen it is never less than `--tablechart-min-height`,
-200px by default. Use `px`, `em` or `rem`, or `none` for no minimum.
+Tablechart is free and open source. If it saves you time, consider [sponsoring my work](https://ko-fi.com/martinomagnifico).
 
-## Licence
+## License
 
-MIT
+MIT © [Martinomagnifico](https://github.com/martinomagnifico)

package/dist/tablechart-core.d.ts

@@ -69,6 +69,8 @@ declare interface ChartType {
     /** 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";
@@ -118,8 +120,6 @@ export declare interface Config {
     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";
-    /** How the closing total of a waterfall grows: `down` from the step before it to the baseline, or `up` from the baseline. A figure overrides it with `data-chart-closing`. */
-    closing: "down" | "up";
     /** 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"`. */
@@ -175,7 +175,6 @@ declare interface Geometry {
     /** Where a bar chart is cut across, in viewBox units; set by its drawing. */
     breakX?: number;
     labels: "outside" | "inside";
-    closing: "down" | "up";
     /** Where a number inside its bar goes, from `--tablechart-inside-align`; null for the chart's own default. */
     insideAlign: "start" | "center" | "end" | null;
     stacked: boolean;
@@ -211,7 +210,7 @@ declare interface HeadroomInput {
 /** Pass 3. Needs layout; makes no text, only places it. */
 export declare const layout: (state: ChartState, config: Config) => boolean;
 
-/** `data-chart-src` replaces any table in the figure with one made from a JSON file; a file that fails is reported. */
+/** `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>;
 
 export declare const PLACED_CLASS = "is-placed";