inkplot 0.0.0-stage → 1.0.0-beta.1

package/dist/web-components.js

@@ -0,0 +1,264 @@
+/**
+ * The Web Components adapter: chart elements as custom HTML elements, so that a chart can be written, or pre-rendered, as markup.
+ *
+ *     import * as inkplot from 'inkplot';
+ *     import { defineElements } from 'inkplot/web-components';
+ *     defineElements({ Chart: inkplot.Chart, CartesianPlane: inkplot.CartesianPlane, Axis: inkplot.Axis, … }, { prefix: 'ch' });
+ *
+ *     <ch-chart style="display:block; height:300px" meta-title="Sales">
+ *       <ch-cartesian-plane>
+ *         <ch-axis orientation="bottom" meta-title="Month"><ch-linear-scale></ch-linear-scale></ch-axis>
+ *         <ch-domain-series name="2024"><ch-flat-data-source data="[1,3,2]" regulardomain-step="1"></ch-flat-data-source> …
+ *
+ * Only the classes you give are defined, so nothing else is bundled. The tag is the prefix and the key, kebab-cased
+ * (`ch-cartesian-plane`).
+ *
+ * How it follows the DOM:
+ * - The element tree is the DOM tree: a wrapper finds its parent wrapper among its ancestors and joins it in document order
+ *   when connected, and leaves when disconnected. Moving a node moves the chart element. The outermost wrapper (one with
+ *   `attach`, a Chart) draws into a shadow root, so the wrapper elements inside it are never rendered, and the page's CSS does not reach the chart.
+ *   Give that element a size; it is `display: block`.
+ * - Attributes are the element's attributes. HTML lowercases names, so `regulardomain-step` finds `regularDomain.step` (the
+ *   class' `attrTypes` and `STYLE_NAMES` say how the names are spelled). Hyphens nest, as in attrs.ts: `meta-title`, `style-ticklabel-size`.
+ *   Text becomes a value by the class' `attrTypes`: `STRING` stays text; otherwise `true`/`false`, numbers, and `[…]`/`{…}` (JSON)
+ *   convert, and a present attribute with no value is true. Changing an attribute later updates the element (on the next microtask).
+ * - Values HTML cannot carry are set as JavaScript: `element.props = { format: fn, data: new Float64Array(…) }` on the wrapper,
+ *   and they win over attributes. `wrapper.element` is the chart element itself, for calling its methods.
+ * - Callbacks (`onClick`, `onHover`, `onDrag`, `onFlush`: attributes that are functions) are events: once the page listens, with
+ *   `addEventListener('click', …)` or `onclick=""`, the wrapper dispatches a bubbling `CustomEvent` named like the DOM's (`click`,
+ *   `hover`, `drag`, `flush`) with the callback's argument as `detail`. (Until then no callback is set, so the chart stays serializable.)
+ *   `on…` attributes are the DOM's own and are not read as chart attributes.
+ * - `style`, `class` and the other attributes every HTML element has are the page's, not the chart's: set the chart's `style` blocks with `style-…` names.
+ */
+import { AUTO, BOOLEAN, NUMBER, STRING } from './attrs.js';
+import { attributesOf, difference } from './adapt.js';
+import { DOMPlatform } from './dom-platform.js';
+import { STYLE_NAMES } from './style-names.js';
+const lowerCache = new WeakMap();
+/** The names a spec lists, by lowercase (HTML's spelling). Two names that differ only in case are an error. */
+function lowerNames(spec, where = 'attribute types') {
+    let map = lowerCache.get(spec);
+    if (!map) {
+        map = new Map();
+        for (const n of Object.keys(spec)) {
+            const lower = n.toLowerCase();
+            if (map.has(lower) && map.get(lower) !== n)
+                throw new Error(`${where}: '${n}' and '${map.get(lower)}' differ only in case`);
+            map.set(lower, n);
+        }
+        lowerCache.set(spec, map);
+    }
+    return map;
+}
+/** The nested spec for an attribute inside the objects named by `path` (real names), or undefined where none is listed. */
+function specAt(types, path) {
+    let spec = types;
+    for (const p of path) {
+        const next = spec?.[p];
+        spec = typeof next === 'object' ? next : undefined;
+    }
+    return spec;
+}
+/** The attributes every HTML element has, or has for the page; none is a chart attribute. */
+const PAGE_ATTRIBUTES = new Set(['class', 'style', 'slot', 'part', 'is', 'hidden', 'lang', 'dir', 'tabindex', 'contenteditable', 'draggable', 'translate', 'inert', 'nonce']);
+const NUMERIC = /^[+-]?(\d+\.?\d*|\.\d+)(e[+-]?\d+)?$/i;
+/** A value from attribute text. `kind` says how; AUTO guesses, and is safe because every attribute that is only text is STRING. */
+function convert(text, kind, name) {
+    switch (kind) {
+        case STRING: return text;
+        case NUMBER: {
+            const n = Number(text);
+            if (text.trim() === '' || Number.isNaN(n))
+                throw new TypeError(`attribute '${name}': '${text}' is not a number`);
+            return n;
+        }
+        case BOOLEAN: return text !== 'false';
+        default: {
+            if (text === '' || text === 'true')
+                return true;
+            if (text === 'false')
+                return false;
+            if (NUMERIC.test(text.trim()))
+                return Number(text);
+            if (/^\s*[[{]/.test(text)) {
+                try {
+                    return JSON.parse(text);
+                }
+                catch (cause) {
+                    throw new TypeError(`attribute '${name}': '${text}' is not valid JSON`, { cause });
+                }
+            }
+            return text;
+        }
+    }
+}
+const kebab = (key) => key.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+/** The base class of every wrapper, made when `defineElements` first runs because `HTMLElement` may not exist before. */
+let Base = null;
+function makeBase() {
+    const observer = new MutationObserver((records) => {
+        for (const target of new Set(records.map((r) => r.target)))
+            target.sync();
+    });
+    return class Wrapper extends HTMLElement {
+        // Set by defineElements on each defined subclass.
+        static cls;
+        static types;
+        static styleNames;
+        #element = null;
+        #applied = {};
+        #props = {};
+        #handlers = new Map();
+        #listening = new Set();
+        #parent = null;
+        #platform = null;
+        platformOptions;
+        addEventListener(type, listener, options) {
+            super.addEventListener(type, listener, options);
+            if (!this.#listening.has(type)) {
+                this.#listening.add(type);
+                this.sync();
+            }
+        }
+        get element() { return this.#element; }
+        get props() { return this.#props; }
+        set props(value) { this.#props = { ...value }; this.sync(); }
+        /** Read the attributes (and props) and write what differs to the element, making it the first time. */
+        sync() {
+            if (!this.isConnected)
+                return this.#element;
+            const ctor = this.constructor;
+            const flat = {};
+            for (const a of Array.from(this.attributes)) {
+                const lower = a.name;
+                if (PAGE_ATTRIBUTES.has(lower) || lower.startsWith('on'))
+                    continue;
+                flat[lower] = a.value;
+            }
+            const attrs = attributesOf(flat, {
+                name: (part, parents) => {
+                    const spec = specAt(ctor.types, parents);
+                    return (spec ? lowerNames(spec).get(part) : parents.length ? ctor.styleNames.get(part) : undefined) ?? part;
+                },
+                value: (path, text) => {
+                    // oxlint-disable-next-line typescript/no-non-null-assertion -- in range: the index comes from a loop bound or a length checked in the same function
+                    const kind = specAt(ctor.types, path.slice(0, -1))?.[path[path.length - 1]];
+                    return convert(text, typeof kind === 'number' ? kind : AUTO, path.join('-'));
+                },
+            });
+            // A callback that dispatches its event, once the page listens for it (`addEventListener`, or an inline `onclick=""`).
+            for (const name of Object.keys(ctor.types)) {
+                if (!/^on[A-Z]/.test(name))
+                    continue;
+                const type = name.slice(2).toLowerCase();
+                if (!this.#listening.has(type) && !this.hasAttribute('on' + type))
+                    continue;
+                let handler = this.#handlers.get(name);
+                if (!handler)
+                    this.#handlers.set(name, handler = (detail) => { this.dispatchEvent(new CustomEvent(type, { detail, bubbles: true, composed: true })); });
+                attrs[name] = handler;
+            }
+            for (const k of Object.keys(this.#props))
+                if (this.#props[k] === undefined)
+                    delete attrs[k];
+                else
+                    attrs[k] = this.#props[k];
+            if (!this.#element) {
+                this.#element = new ctor.cls(attrs);
+                this.#applied = attrs;
+                return this.#element;
+            }
+            const patch = difference(this.#applied, attrs);
+            if (patch)
+                this.#element.setAttributes(patch);
+            this.#applied = attrs;
+            return this.#element;
+        }
+        connectedCallback() {
+            const element = this.sync();
+            if (!element)
+                return; // only when disconnected, and this is the callback for connecting
+            let ancestor = this.parentElement;
+            while (ancestor && !(ancestor instanceof Wrapper))
+                ancestor = ancestor.parentElement;
+            this.#parent = ancestor;
+            if (this.#parent) {
+                const host = this.#parent.element;
+                if (!host)
+                    return;
+                // Before the first later sibling tag that is already in the same parent element, else last.
+                let before = null;
+                for (let s = this.nextElementSibling; s; s = s.nextElementSibling) {
+                    const other = s instanceof Wrapper ? s.element : null;
+                    if (other && other.parent === host) {
+                        before = other;
+                        break;
+                    }
+                }
+                host.insertBefore(element, before);
+                observer.observe(this, { attributes: true });
+            }
+            else if (typeof element.attach === 'function') {
+                const root = this.shadowRoot ?? this.attachShadow({ mode: 'open' });
+                root.replaceChildren();
+                const style = this.ownerDocument.createElement('style');
+                style.textContent = ':host{display:block}div{width:100%;height:100%}';
+                const container = this.ownerDocument.createElement('div');
+                root.append(style, container);
+                this.#platform = new DOMPlatform(container, this.platformOptions);
+                element.attach(this.#platform);
+                observer.observe(this, { attributes: true });
+            }
+        }
+        disconnectedCallback() {
+            const element = this.#element;
+            if (!element)
+                return;
+            if (this.#platform) {
+                element.detach();
+                this.#platform.dispose();
+                this.#platform = null;
+            }
+            const host = this.#parent?.element;
+            if (host && element.parent === host)
+                host.remove(element);
+            this.#parent = null;
+        }
+    };
+}
+/**
+ * Define a custom element for each class. `classes` maps a name to a class, and the name gives the tag. Returns the tags by name.
+ * Does nothing at import, so a module that imports this can be loaded where there is no DOM.
+ */
+export function defineElements(classes, options) {
+    const registry = options.registry ?? customElements;
+    const base = (Base ??= makeBase());
+    const styleNames = new Map();
+    for (const n of [...STYLE_NAMES, ...options.names ?? []])
+        styleNames.set(n.toLowerCase(), n);
+    const tags = {};
+    for (const [key, cls] of Object.entries(classes)) {
+        const tag = `${options.prefix}-${kebab(key)}`;
+        tags[key] = tag;
+        const types = cls.attrTypes ?? {};
+        // The lowercase-name maps are made now, so a clash is an error here and not on first use.
+        const check = (spec, where) => {
+            lowerNames(spec, where);
+            for (const [n, v] of Object.entries(spec))
+                if (typeof v === 'object')
+                    check(v, `${where}.${n}`);
+        };
+        check(types, key);
+        const wrapper = class extends base {
+        };
+        Object.assign(wrapper, { cls, types, styleNames });
+        const have = registry.get(tag);
+        if (have) {
+            if (have.cls === cls)
+                continue;
+            throw new Error(`<${tag}> is already defined for something else`);
+        }
+        registry.define(tag, wrapper);
+    }
+    return tags;
+}

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "inkplot",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-beta.1",
+  "description": "A small, tree-shakeable chart library for the web and servers: a tree of elements you keep, drawn as SVG.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neofox-solutions/inkplot.git"
+  },
+  "homepage": "https://github.com/neofox-solutions/inkplot#readme",
+  "bugs": {
+    "url": "https://github.com/neofox-solutions/inkplot/issues"
+  },
+  "keywords": [
+    "chart",
+    "charts",
+    "svg",
+    "visualization",
+    "plot",
+    "tree-shakeable",
+    "ssr"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./jsx-runtime": {
+      "types": "./dist/jsx-runtime.d.ts",
+      "default": "./dist/jsx-runtime.js"
+    },
+    "./jsx-dev-runtime": {
+      "types": "./dist/jsx-dev-runtime.d.ts",
+      "default": "./dist/jsx-dev-runtime.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    },
+    "./web-components": {
+      "types": "./dist/web-components.d.ts",
+      "default": "./dist/web-components.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  }
 }