@cehlers88/chart 1.1.1 → 1.2.1

package/README.md

@@ -60,13 +60,104 @@ Attributes:
 
 | Attribute   | Description                                                        | Default |
 |-------------|----------------------------------------------------------------------|---------|
-| `width`     | Canvas width in pixels                                                | `300`   |
+| `width`     | Canvas width in pixels; `100%`/`auto` makes the diagram responsive (it takes the width of its container and is redrawn sharply whenever that changes) | `300`   |
 | `height`    | Canvas height in pixels                                               | `150`   |
 | `value`     | JSON string with the data groups (see data format below)             | `[]`    |
 | `autostart` | Starts the chart automatically once mounted (`"true"`/`"false"`)     | `true`  |
 
 Additional plugins can be registered on the element before it starts via `getPlugin()`/`addPlugin()`.
 
+## Changing data at runtime
+
+The data of a chart is not frozen after the page was loaded – it can be read,
+replaced and manipulated at any time, either through the `<canvas-diagram>`
+element or through the `ChartEngine`. A running chart picks the changes up with
+the next frame, no restart needed.
+
+```html
+<canvas-diagram id="sales" width="600" height="300"
+                value='{"Revenue":[1,5,3,8,2]}'></canvas-diagram>
+
+<script type="module">
+  import { DataGroupFactory, diagramRegistry } from "@cehlers88/chart";
+
+  const diagram = document.getElementById("sales");
+  // ... or, without a dom reference:
+  // const diagram = diagramRegistry.getDiagram("sales");
+
+  diagram.addValue(6, "Revenue");                 // append a value
+  diagram.setValue("Revenue", 0, 4);              // replace a single value
+  diagram.removeValue("Revenue", 1);              // remove a single value
+  diagram.addDataGroup(                           // add a whole group
+      DataGroupFactory.createDataGroup([2, 3, 1], "Costs", "#e84949")
+  );
+  diagram.removeDataGroup("Costs");               // remove a whole group
+  diagram.setData({ Revenue: [1, 2, 3] });        // replace everything
+  diagram.clearData();                            // remove everything
+
+  console.log(diagram.getDataGroups());           // read the current data
+</script>
+```
+
+Setting the `value` attribute again works as well and replaces the complete data:
+
+```javascript
+document.getElementById("sales").setAttribute("value", '{"Revenue":[3,4,5]}');
+```
+
+Methods of `<canvas-diagram>`:
+
+| Method                                  | Description                                                            |
+|-----------------------------------------|--------------------------------------------------------------------------|
+| `setData(definition)`                   | Replaces all data. Accepts a JSON string, an array or an object          |
+| `setDataGroups(dataGroups)`             | Replaces all data with ready-made `TDataGroup`s                          |
+| `getDataGroups()`                       | Returns the current data groups                                          |
+| `getDataGroup(labelOrIndex)`            | Returns a single data group                                              |
+| `addDataGroup(dataGroup)`               | Adds a data group                                                        |
+| `removeDataGroup(labelOrIndex)`         | Removes a data group                                                     |
+| `addValue(value, groupName?)`           | Appends a value; creates the group if it does not exist yet              |
+| `setValue(labelOrIndex, index, value)`  | Replaces a single value; missing values in between are filled up empty   |
+| `removeValue(labelOrIndex, index)`      | Removes a single value                                                   |
+| `clearData()`                           | Removes all data groups                                                  |
+| `addPlugin(plugin)` / `getPlugin(name)` | Registers / returns a plugin – also while the chart is already running   |
+| `start()` / `stop()`                    | Starts / stops the render loop                                           |
+| `getEngine()`                           | Returns the underlying `ChartEngine`                                     |
+
+The same data methods exist on `ChartEngine`, so the programmatic usage works
+identically:
+
+```typescript
+const engine = new ChartEngine(canvas, { plugins: [new plugins.BarsPlugin()] });
+
+engine.setData({ Revenue: [1, 5, 3] });
+engine.start();
+
+setInterval(() => engine.addValue(Math.random() * 10, "Revenue"), 1000);
+```
+
+Data methods may be called before the element is mounted as well; those calls
+are applied as soon as the element is connected (and take precedence over the
+`value` attribute).
+
+### Live data
+
+For values that arrive after the page was loaded (ajax, Mercure, websockets, …) give the
+group a `maxLength` and append the new values with their timestamp. The oldest values are
+pushed out, so the chart keeps its time window, and the new value is labelled like the
+initial ones:
+
+```html
+<canvas-diagram id="co2" width="100%" height="110"
+    value='{"CO2":{"data":[450,470],"timestamps":[1790000000,1790000600],"unit":"ppm","maxLength":2}}'></canvas-diagram>
+
+<script type="module">
+  import { diagramRegistry } from "@cehlers88/chart";
+
+  // without a group name the value goes to the only group of the chart
+  diagramRegistry.getDiagram("co2").addValue({ value: 480, timestamp: 1790001200 });
+</script>
+```
+
 ## Data format
 
 `DataGroupFactory` accepts several notations for the values within a group:
@@ -91,13 +182,58 @@ As a JSON string (e.g. for the custom element's `value` attribute), groups are g
 }
 ```
 
+The object notation takes a few optional keys more:
+
+| Key          | Description                                                                                   |
+|--------------|-----------------------------------------------------------------------------------------------|
+| `unit`       | Unit of the values, shown in the tooltip and on the value axis (`"°C"`, `"ppm"`)             |
+| `labels`     | One label per value (e.g. the time of a measurement), shown in the tooltip and on the x axis |
+| `timestamps` | One unix timestamp per value (seconds or milliseconds), turned into time labels; `0`/`null` means "no label". Values below 1e11 are read as seconds (up to the year 5138), larger ones as milliseconds (from 1973 on). Single values take theirs as `{ "value": 1, "timestamp": 1790000000 }` |
+| `maxLength`  | Maximum number of values; values appended later push the oldest ones out                     |
+
+`null` values are gaps: the line is interrupted there instead of dropping to 0, and they
+do not count for the value range.
+
+```json
+{ "CO2": { "data": [null, 450, 470], "timestamps": [0, 1790000000, 1790000600], "unit": "ppm" } }
+```
+
+## Look & theming
+
+`DiagramLinePlugin` draws a smooth (monotone, never overshooting) line with a gradient
+fill, a value axis with "nice" steps on the right and - if the values carry labels - a
+label axis at the bottom. Hovering (or tapping) shows a crosshair and a tooltip with the
+values next to the pointer. Options: `smooth`, `fill`, `lineWidth`, `showGrid`,
+`showYLabels`, `showXLabels`, `showTooltip`, `showBulletPoints`, `showZeroLine`,
+`maxYTicks`, `decimals`.
+
+Colours are read from CSS custom properties of the canvas, so the host page adapts the
+charts to its theme:
+
+```css
+canvas-diagram {
+    --chart-text-color: #8a93a6;
+    --chart-grid-color: rgba(255, 255, 255, .07);
+    --chart-tooltip-background: rgba(12, 12, 12, .94);
+    --chart-tooltip-border: rgba(255, 255, 255, .12);
+    --chart-tooltip-text-color: #e4e4e4;
+    --chart-font: 11px system-ui, sans-serif;
+    --chart-background: transparent;   /* background of the canvas */
+    --chart-border-radius: 0;
+}
+```
+
+A plugin property of the same name (`textColor`, `gridColor`, `tooltipBackground`,
+`tooltipBorder`, `tooltipTextColor`, `font`) wins over the CSS property. Numbers and
+times are formatted in the language of the page (`<html lang>`).
+
 ## Available plugins
 
 | Plugin                   | Purpose                                                            |
 |--------------------------|---------------------------------------------------------------------|
 | `BarsPlugin`             | Renders data groups as bars                                        |
-| `DiagramLinePlugin`      | Renders data groups as lines, including helper lines                |
-| `LegendsPlugin`          | Displays a legend for the data groups                              |
+| `DiagramLinePlugin`      | Renders data groups as lines with value axis, crosshair and tooltip |
+| `LegendsPlugin`          | Displays a legend for the data groups (only for two or more groups unless `showSingleGroup`; steps aside while a tooltip covers it) |
 | `TooltipPlugin`          | Shows tooltips on hover over data points                           |
 | `CameraMovePlugin`       | Enables scrolling/panning the view via mouse/wheel                 |
 | `PaginationPlugin`       | Splits large data sets into pages                                   |
@@ -115,6 +251,12 @@ npm run watch     # build in watch mode
 npm test          # run tests with Jest
 ```
 
+## Release / Deployment
+
+Pushes/merges to `main` trigger the `.github/workflows/publish.yml` GitHub Actions workflow, which installs dependencies, runs the tests and the build, and publishes the package to npm if `package.json`'s `version` differs from the version currently published on npm. To cut a release, bump `version` in `package.json` before merging to `main`.
+
+This requires an `NPM_TOKEN` repository secret (an npm automation token with publish rights for `@cehlers88/chart`).
+
 ## License
 
 ISC © Christoph Ehlers

package/dist/ChartEngine.d.ts

@@ -14,21 +14,93 @@ export default class ChartEngine implements IChartEngine {
     private _entityRegistry;
     private _ctx;
     private _dataGroups;
+    private _dataGroupsSignature;
+    private _processedDataGroups;
     private _plugins;
     private _pluginProperties;
+    private _created;
+    private _runStackEntry;
     constructor(canvasElement: HTMLCanvasElement, properties?: {
         plugins?: IChartPlugin[];
     });
     addPlugin(plugin: IChartPlugin): ChartEngine;
+    /**
+     * Changes the size of the canvas (in canvas pixels). The plugins rebuild
+     * their buffers, so the chart is drawn sharp in the new size instead of
+     * being stretched by css.
+     */
+    resize(width: number, height: number): ChartEngine;
+    /**
+     * Converts a pointer position (css pixels) into canvas pixels - both differ
+     * as soon as the canvas is scaled by css, e.g. by `width: 100%`.
+     */
+    private toCanvasPosition;
     getDrawAreaRect(): TRect;
     getPlugin(pluginName: string): IChartPlugin | undefined;
     getPlugins(): IChartPlugin[];
     setPluginProperty(propertyName: string, value: any): ChartEngine;
     create(): ChartEngine;
     addDataGroup(dataGroup: TDataGroup): IChartEngine;
+    /**
+     * Returns the data groups currently held by the engine.
+     * The returned groups are the live objects; changes made to them are
+     * picked up with the next update cycle.
+     */
+    getDataGroups(): TDataGroup[];
+    /**
+     * Returns a single data group, addressed either by its label or by its index.
+     */
+    getDataGroup(group: string | number): TDataGroup | undefined;
+    /**
+     * Replaces all data groups at once.
+     */
+    setDataGroups(dataGroups: TDataGroup[]): IChartEngine;
+    /**
+     * Replaces the complete data of the chart. Accepts everything
+     * `DataGroupFactory.parseDataGroupsDefinition` understands: a JSON string,
+     * a plain array of values or an object keyed by group name.
+     */
+    setData(dataDefinition: string | any[] | object): IChartEngine;
+    /**
+     * Removes a data group, addressed either by its label or by its index.
+     */
+    removeDataGroup(group: string | number): IChartEngine;
+    /**
+     * Removes all data groups.
+     */
+    clearData(): IChartEngine;
+    /**
+     * Appends a value - e.g. a new measurement that arrived after the page was
+     * loaded - to a data group. The value may be given as `{value, timestamp}`
+     * or `{value, label}`. A group with a `maxLength` drops its oldest values,
+     * so a live chart keeps its window. Without a group name the value goes to
+     * the only group of the chart; an unknown group is created.
+     */
     addValue(value: any, groupName?: string): IChartEngine;
+    /**
+     * Replaces a single value within a data group.
+     */
+    setValue(group: string | number, dataIndex: number, value: any): IChartEngine;
+    /**
+     * Removes a single value from a data group.
+     */
+    removeValue(group: string | number, dataIndex: number): IChartEngine;
     draw(): ChartEngine;
     update(): ChartEngine;
+    /**
+     * Returns the data groups handed to the plugins. They are a detached copy
+     * of the data owned by the engine and are renewed whenever that data
+     * changed. Without that separation the plugins would hold references to
+     * the very objects manipulated from outside, so neither they nor the
+     * engine could tell a manipulation from the state of the last frame.
+     */
+    private getPipelineDataGroups;
     start(): void;
+    /**
+     * Stops the render loop of this engine. The data stays untouched, so the
+     * chart can be started again later on.
+     */
+    stop(): ChartEngine;
+    isRunning(): boolean;
     private getEngineCallbacks;
 }

package/dist/Factory/DataGroupFactory.d.ts

@@ -1,10 +1,43 @@
 import { TDataGroup } from "../type/TDataGroup";
+import { TData } from "../type/TData";
 export default class DataGroupFactory {
     static buildCounter: number;
     private static _colors;
     private static _lastColorIndex;
+    /**
+     * Normalizes a single value definition into a TData object.
+     * Accepts plain numbers, ranges ([start, end]), null (empty value) and
+     * objects like {value, valueStart, label}.
+     */
+    static createDataValue(valueDef: any): TData;
+    /**
+     * Unix timestamps in seconds or milliseconds (see `toMilliseconds`),
+     * stored as milliseconds; everything else means "no timestamp".
+     */
+    static normalizeTimestamp(timestamp: any): number | undefined;
     static createDataGroup(values: any[], groupLabel?: string, color?: string): TDataGroup;
-    static parseDataGroupsDefinition(value: string): TDataGroup[];
+    /**
+     * Parses a data group definition. Beside the JSON notation used by the
+     * `value` attribute of `<canvas-diagram>` an already parsed object/array
+     * may be passed, so data can be handed over programmatically at runtime.
+     */
+    static parseDataGroupsDefinition(value: string | any[] | object): TDataGroup[];
+    /**
+     * Applies the optional parts of an object definition to a data group:
+     * `unit` (shown in tooltips and axis labels), `labels` (one label per value),
+     * `timestamps` (one unix timestamp per value, in seconds or milliseconds -
+     * shown as time labels) and `maxLength` (values added later push the oldest
+     * ones out, so a live chart keeps its time window). Labels and timestamps of
+     * single values given as `{value, label, timestamp}` win.
+     */
+    static applyGroupOptions(dataGroup: TDataGroup, definition: {
+        unit?: string;
+        labels?: any[];
+        maxLength?: number;
+        timestamps?: any[];
+        [key: string]: any;
+    }): TDataGroup;
+    static getNextColor(): string;
     static setColor(color: string, index: number): void;
     static setColors(colors: string[]): void;
 }

package/dist/Registry/DiagramRegistry.d.ts

@@ -8,9 +8,17 @@ import CanvasDiagram from "../customElement/CanvasDiagram";
 import { ICanvasDiagram } from "../interface/ICanvasDiagram";
 declare class DiagramRegistry {
     private static _identPrefix;
+    private static _identCounter;
     private createUniqueIdentifier;
     getDiagram(identifier: string): ICanvasDiagram;
+    hasDiagram(identifier: string): boolean;
+    getDiagrams(): ICanvasDiagram[];
     register(diagram: CanvasDiagram, identifier?: string): DiagramRegistry;
+    /**
+     * Removes a diagram from the registry, either by its identifier or by the
+     * element itself, so removed diagrams are not kept alive by the registry.
+     */
+    unregister(diagram: CanvasDiagram | string): DiagramRegistry;
 }
 export default DiagramRegistry;
 export declare const diagramRegistry: DiagramRegistry;

package/dist/Utils/ChartStyle.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Library ChartStyle
+ * Created 29.09.26
+ *
+ * Shared helpers for the look of the charts: theme colours, colour alpha,
+ * number formatting and "nice" axis ticks.
+ *
+ * @author Christoph Ehlers
+ */
+export type TChartTheme = {
+    textColor: string;
+    gridColor: string;
+    tooltipBackground: string;
+    tooltipBorder: string;
+    tooltipTextColor: string;
+    font: string;
+};
+/**
+ * The defaults are mid-tone colours, so a chart stays readable on a dark as
+ * well as on a light background when the host page defines nothing.
+ */
+export declare const DEFAULT_THEME: TChartTheme;
+/**
+ * Reads the theme from the CSS custom properties `--chart-*` of the given
+ * element, so the host page can adapt the charts to its own theme without
+ * touching any plugin options.
+ */
+export declare function readTheme(element: any): TChartTheme;
+/**
+ * Returns the given colour with the given opacity. Hex colours (#rgb, #rrggbb,
+ * #rrggbbaa) and rgb()/rgba() are supported; any other notation is returned
+ * unchanged, which only costs the transparency.
+ */
+export declare function withAlpha(color: string, alpha: number): string;
+/**
+ * The language of the page (`<html lang>`), so numbers and times are written
+ * the way the rest of the page writes them.
+ */
+export declare function pageLocale(): string | undefined;
+/**
+ * Formats a value for axis labels and tooltips: at most `maxDecimals`
+ * decimals, grouped by the locale of the page.
+ */
+export declare function formatValue(value: any, maxDecimals?: number, locale?: string | undefined): string;
+/**
+ * Calculates evenly spaced, human friendly axis ticks (1, 2, 2.5, 5 × 10^n)
+ * which enclose the given range.
+ */
+export declare function niceTicks(min: number, max: number, maxTicks?: number): {
+    min: number;
+    max: number;
+    step: number;
+    ticks: number[];
+};
+/**
+ * Returns the number of decimals needed to show the given step exactly.
+ */
+export declare function decimalsOf(step: number): number;
+/**
+ * Normalizes a unix timestamp in seconds or milliseconds (see
+ * SECONDS_MILLISECONDS_BOUNDARY) to milliseconds. 0, negative values, null
+ * and anything unparsable mean "no timestamp".
+ */
+export declare function toMilliseconds(timestamp: any): number | undefined;
+/**
+ * Turns unix timestamps (seconds or milliseconds) into short labels. The date
+ * is only part of the label when the timestamps span more than one day.
+ */
+export declare function formatTimestamps(timestamps: any[], locale?: string | undefined): (string | undefined)[];

package/dist/customElement/CanvasDiagram.d.ts

@@ -7,14 +7,58 @@
 import '../style/CanvasDiagram.css';
 import { IChartPlugin } from "../interface/IChartPlugin";
 import { ICanvasDiagram } from "../interface/ICanvasDiagram";
+import { TDataGroup } from "../type/TDataGroup";
+import { IChartEngine } from "../interface/IChartEngine";
 declare class CanvasDiagram extends HTMLElement implements ICanvasDiagram {
     private _cleanDom;
     private _engine;
+    private _ignoreValueAttribute;
+    private _pendingActions;
+    private _resizeObserver;
+    private _responsive;
+    private _runningBeforeDisconnect;
+    static get observedAttributes(): string[];
     connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     addPlugin(plugin: IChartPlugin): ICanvasDiagram;
     getPlugin(pluginName: string): IChartPlugin | undefined;
+    /**
+     * Changes the size of the diagram (in pixels) and redraws it sharply in
+     * the new size.
+     */
+    resize(width: number, height: number): ICanvasDiagram;
+    getEngine(): IChartEngine | undefined;
+    addDataGroup(dataGroup: TDataGroup): ICanvasDiagram;
+    addValue(value: any, groupName?: string): ICanvasDiagram;
+    clearData(): ICanvasDiagram;
+    getDataGroup(group: string | number): TDataGroup | undefined;
+    getDataGroups(): TDataGroup[];
+    removeDataGroup(group: string | number): ICanvasDiagram;
+    removeValue(group: string | number, dataIndex: number): ICanvasDiagram;
+    /**
+     * Replaces the complete data of the diagram, at any time - also long after
+     * the page was loaded.
+     */
+    setData(dataDefinition: string | any[] | object): ICanvasDiagram;
+    setDataGroups(dataGroups: TDataGroup[]): ICanvasDiagram;
+    setValue(group: string | number, dataIndex: number, value: any): ICanvasDiagram;
     start(): ICanvasDiagram;
+    stop(): ICanvasDiagram;
+    /**
+     * Runs the given action against the engine. If the element is not mounted
+     * yet, the action is queued and executed as soon as the engine exists,
+     * so data can be set before as well as after the element was connected.
+     */
+    private withEngine;
+    private flushPendingActions;
+    /**
+     * A width given in percent (`width="100%"`) or as `auto` makes the diagram
+     * responsive: it takes the width of its container and is redrawn in the
+     * new size whenever that changes.
+     */
     private createCanvas;
+    private observeSize;
     private evalArguments;
 }
 export default CanvasDiagram;

package/dist/index.d.ts

@@ -9,7 +9,6 @@ import BarsPluginClass from "./plugin/BarsPlugin";
 import ChartEngineClass from './ChartEngine';
 import DataGroupFactoryClass from "./Factory/DataGroupFactory";
 import DiagramLine from "./plugin/DiagramLine";
-import DiagramRegistry from "./Registry/DiagramRegistry";
 import CameraMove from "./plugin/CameraMove";
 import EnrichGroupInfosPlugin from "./plugin/EnrichGroupInfosPlugin";
 import TimelinePlugin from "./plugin/TimelinePlugin";
@@ -18,7 +17,7 @@ import PaginationPlugin from "./plugin/PaginationPlugin";
 export declare const CanvasDiagram: typeof CanvasDiagramClass;
 export declare const ChartEngine: typeof ChartEngineClass;
 export declare const DataGroupFactory: typeof DataGroupFactoryClass;
-export declare const diagramRegistry: DiagramRegistry;
+export declare const diagramRegistry: import("./Registry/DiagramRegistry").default;
 export declare const plugins: {
     BarsPlugin: typeof BarsPluginClass;
     CameraMovePlugin: typeof CameraMove;
@@ -32,7 +31,7 @@ declare const _default: {
     CanvasDiagram: typeof CanvasDiagramClass;
     ChartEngine: typeof ChartEngineClass;
     DataGroupFactory: typeof DataGroupFactoryClass;
-    diagramRegistry: DiagramRegistry;
+    diagramRegistry: import("./Registry/DiagramRegistry").default;
     plugins: {
         BarsPlugin: typeof BarsPluginClass;
         CameraMovePlugin: typeof CameraMove;