@fusion.dev/helix-core 0.152.0 → 0.154.0

package/custom-elements.json

@@ -4920,6 +4920,35 @@
               "description": "The element `for` names, or null where there is nothing to name it in.\n\nNull on the server as well, since resolving an id wants a document. Every\nchart inherits that: the table is served whole and the drawing arrives on\nhydration.\n\n**And null while hydrating what a server sent**, which drew nothing, because\nthe render that hydrates has to be the server's: a drawing that differs is\na template Lit throws on. The update after it, which this asks for, draws.",
               "readonly": true
             },
+            {
+              "kind": "field",
+              "name": "hydrating",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "description": "Whether the host is hydrating what a server sent.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "data",
+              "type": {
+                "text": "ChartData | undefined"
+              },
+              "privacy": "private",
+              "description": "The host's `data`, where it is read: on the client, after hydration, and\nwhere `for` names no table.\n\n**Never on the server**, so a chart given data serves the frame, as one\nreading a table does, and the drawing arrives on hydration. A server's\nelement shim has no `closest`, which is how one is told apart, Lit's\n`isServer` being true in any test runner that resolves its `node` build.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "known",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Whether what the chart reads has been looked at: a table resolved or\nlooked for, or data read. False on the server and while hydrating, where\nneither is, so a chart there says nothing about its readings.",
+              "readonly": true
+            },
             {
               "kind": "method",
               "name": "resolve",
@@ -4968,11 +4997,11 @@
                 {
                   "name": "read",
                   "type": {
-                    "text": "(table: Element | null) => T"
+                    "text": "(table: Element | null, data: ChartData | undefined) => T"
                   }
                 }
               ],
-              "description": "A held parse where it still describes the table, or a fresh one."
+              "description": "A held parse where it still describes the table or the data, or a fresh\none. `data` is held by identity, so a new object is read again and an\nobject changed in place is not, as a Lit property is."
             },
             {
               "kind": "field",
@@ -14212,6 +14241,22 @@
             "module": "./mixins/mixin-chart-source/mixin-chart-source.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "MixinChartStatus",
+          "declaration": {
+            "name": "MixinChartStatus",
+            "module": "./mixins/mixin-chart-status/mixin-chart-status.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "MixinChartStatusInterface",
+          "declaration": {
+            "name": "MixinChartStatusInterface",
+            "module": "./mixins/mixin-chart-status/mixin-chart-status.js"
+          }
+        },
         {
           "kind": "js",
           "name": "CollectionElement",
@@ -15732,6 +15777,38 @@
             "module": "./utils/read-color/read-color.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "ChartData",
+          "declaration": {
+            "name": "ChartData",
+            "module": "./utils/read-data/read-data.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ChartDatum",
+          "declaration": {
+            "name": "ChartDatum",
+            "module": "./utils/read-data/read-data.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "rowsFromData",
+          "declaration": {
+            "name": "rowsFromData",
+            "module": "./utils/read-data/read-data.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "seriesFromData",
+          "declaration": {
+            "name": "seriesFromData",
+            "module": "./utils/read-data/read-data.js"
+          }
+        },
         {
           "kind": "js",
           "name": "byRow",
@@ -17180,6 +17257,14 @@
             }
           ],
           "members": [
+            {
+              "kind": "field",
+              "name": "data",
+              "type": {
+                "text": "ChartData | undefined"
+              },
+              "description": "The readings as data, in the shape of a table, where the page has no\ntable to point `for` at. `for` wins where both are set."
+            },
             {
               "kind": "field",
               "name": "for",
@@ -17212,6 +17297,15 @@
               },
               "description": "Where a reading the keys moved to stands among the readings, said after\nit. `{position}` and `{count}` are replaced with the numbers, written in\n`locale`.\n\nSet it to the words of the page's language, such as `{position} von\n{count}`, or to nothing to say no position."
             },
+            {
+              "kind": "field",
+              "name": "readingsKnown",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Whether the readings have been looked for: false on the server and while\nhydrating, where no table is resolved and no data is read.",
+              "readonly": true
+            },
             {
               "kind": "field",
               "name": "series",
@@ -17379,6 +17473,15 @@
               "default": "new ChartPointerController(this)",
               "description": "Finds the reading nearest the pointer, so the tooltip can sit on it.\n\nPublic for the same reason `series` and `named` are: a protected member\ncannot be cast onto across unrelated classes, so it would be invisible to\nevery chart that needs it. Reading where a pointer is resting is a fair\nthing to ask a chart anyway."
             },
+            {
+              "kind": "field",
+              "name": "data",
+              "type": {
+                "text": "ChartData | undefined"
+              },
+              "default": "undefined",
+              "description": "The readings as data, in the shape of a table, where the page has no\ntable to point `for` at. `for` wins where both are set.\n\n```js\nchart.data = {\n  caption: 'Sessions by channel',\n  columns: ['Month', 'Direct', 'Referral'],\n  rows: [['Jan', 10, 4], ['Feb', 20, 8]],\n}\n```\n\nThe first column holds each row's label and every column after it a\nseries, as in a table. A cell is a number, words, `null` for a blank,\nor `{ value, text }` for a number shown as words, such as `$128k`. A\nnumber is shown in `locale`.\n\n**A table is still the better source where the page can show one**:\nit reads with no script and before hydration, and a reader can sort and\ncopy it. Data is drawn on the client only, so a server serves the\nframe, and the summary, the keys and the readout are then the whole of\nwhat a screen reader is given. Set a new object to redraw: the chart\ndoes not look inside the one it has."
+            },
             {
               "kind": "field",
               "name": "for",
@@ -17480,6 +17583,15 @@
               "description": "The chart's name: an `aria-label` written on the chart, then `label`,\nthen the table's caption.\n\nThe fallback is the reason this is shared rather than copied: a caption is\nalready written, already the right words, and already the thing a reader\nof the table sees. A chart that made the consumer say it twice would be\nasking for the second one to drift.\n\n**An `aria-label` on the chart comes first**, because it is how a page\nnames an element, and the chart is a generic around its plot: written\non the host, the name reached nobody. The plot takes it, as Heatmap's\nstrip always did.",
               "readonly": true
             },
+            {
+              "kind": "field",
+              "name": "readingsKnown",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Whether the readings have been looked for: false on the server and\nwhile hydrating, where no table is resolved and no data is read. A\nchart says it has no readings only once this is true.",
+              "readonly": true
+            },
             {
               "kind": "field",
               "name": "sourceRows",
@@ -17695,6 +17807,175 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/mixins/mixin-chart-status/mixin-chart-status.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "The public surface `MixinChartStatus` adds.\n\nDeclared apart from the class for the reason `MixinChartSourceInterface`\ngives: TypeScript cannot emit declarations for an anonymous class with\nprotected members.",
+          "name": "MixinChartStatusInterface",
+          "members": [
+            {
+              "kind": "field",
+              "name": "emptyText",
+              "type": {
+                "text": "string"
+              },
+              "description": "The words shown in place of the drawing when the table has no readings,\nand the fallback of the `empty` slot."
+            },
+            {
+              "kind": "field",
+              "name": "loading",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Whether the readings are still on their way. The chart shows\n`loading-text` in place of an empty drawing until it has readings."
+            },
+            {
+              "kind": "field",
+              "name": "loadingText",
+              "type": {
+                "text": "string"
+              },
+              "description": "The words shown in place of the drawing while `loading` is set and there\nare no readings yet, and the fallback of the `loading` slot."
+            },
+            {
+              "kind": "method",
+              "name": "renderStatus",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "TemplateResult | typeof nothing"
+                }
+              },
+              "description": "What stands in the plot while there is nothing to draw: the `loading`\nline, the `empty` line, or nothing while the table cannot be read yet."
+            }
+          ],
+          "helix": {}
+        },
+        {
+          "kind": "mixin",
+          "description": "What a chart shows in place of its drawing when it has no readings: words\nwhile they load, and words when the table it reads has none.\n\n**A blank box said neither.** A chart pointed at an empty table drew its\nplot at full height with nothing in it, which reads as a chart that failed,\nand one waiting for a request drew the same. `Table` and `Data Table` take\nthe same pair, `empty-text` and `loading-text` with `empty` and `loading`\nslots for markup, such as a link to add the first reading.\n\n**Nothing at all while the readings cannot be looked for**, which is a\nserver render and the hydrating one after it: there is no document to\nresolve `for` in and `data` is drawn on the client only, so \"No readings\"\nthere would be a claim about readings nobody has looked at. `Heatmap` keeps\nthe same rule for its own `empty-text`.\n\nApplied by the four charts that draw on axes. The slots and parts are\ndocumented on each of them, a class-level tag on a mixin reaching no\nmanifest.",
+          "name": "MixinChartStatus",
+          "members": [
+            {
+              "kind": "field",
+              "name": "words",
+              "type": {
+                "text": "string"
+              },
+              "static": true,
+              "default": "''",
+              "description": "The key the empty and loading words are registered under: the host's\nown, which each chart names with its styled tag, `static words =\n'helix-line-chart'`. A host with none reads its tag name."
+            },
+            {
+              "kind": "field",
+              "name": "emptyText",
+              "type": {
+                "text": "string"
+              },
+              "default": "'No readings'",
+              "description": "The words shown in place of the drawing when the table has no readings,\nand the fallback of the `empty` slot.",
+              "attribute": "empty-text",
+              "helix": {
+                "words": true
+              }
+            },
+            {
+              "kind": "field",
+              "name": "loading",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether the readings are still on their way. The chart shows\n`loading-text` in place of an empty drawing until it has readings.\n\nReflected, so a stylesheet can treat the chart while it waits. A chart\nthat already has readings keeps drawing them, so a refresh does not\nblank it.",
+              "attribute": "loading",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "loadingText",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Loading readings'",
+              "description": "The words shown in place of the drawing while `loading` is set and\nthere are no readings yet, and the fallback of the `loading` slot.",
+              "attribute": "loading-text",
+              "helix": {
+                "words": true
+              }
+            },
+            {
+              "kind": "method",
+              "name": "renderStatus",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "TemplateResult | typeof nothing"
+                }
+              },
+              "description": "What stands in the plot while there is nothing to draw: the `loading`\nline, the `empty` line, or nothing while the table cannot be read yet.\n\n`dir=\"auto\"`, so words in a right-to-left script read their own way in\na plot that holds itself left to right, as Scatter Chart's does."
+            }
+          ],
+          "attributes": [
+            {
+              "name": "empty-text",
+              "type": {
+                "text": "string"
+              },
+              "default": "'No readings'",
+              "description": "The words shown in place of the drawing when the table has no readings,\nand the fallback of the `empty` slot.",
+              "fieldName": "emptyText"
+            },
+            {
+              "name": "loading",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether the readings are still on their way. The chart shows\n`loading-text` in place of an empty drawing until it has readings.\n\nReflected, so a stylesheet can treat the chart while it waits. A chart\nthat already has readings keeps drawing them, so a refresh does not\nblank it.",
+              "fieldName": "loading"
+            },
+            {
+              "name": "loading-text",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Loading readings'",
+              "description": "The words shown in place of the drawing while `loading` is set and\nthere are no readings yet, and the fallback of the `loading` slot.",
+              "fieldName": "loadingText"
+            }
+          ],
+          "parameters": [
+            {
+              "name": "Base",
+              "type": {
+                "text": "T"
+              }
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "MixinChartStatusInterface",
+          "declaration": {
+            "name": "MixinChartStatusInterface",
+            "module": "src/mixins/mixin-chart-status/mixin-chart-status.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "MixinChartStatus",
+          "declaration": {
+            "name": "MixinChartStatus",
+            "module": "src/mixins/mixin-chart-status/mixin-chart-status.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/mixins/mixin-collection/mixin-collection.ts",
@@ -27545,7 +27826,7 @@
               "name": "options",
               "optional": true,
               "type": {
-                "text": "Intl.NumberFormatOptions"
+                "text": "Intl.NumberFormatOptions | null"
               }
             }
           ],
@@ -28086,6 +28367,74 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/utils/read-data/read-data.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "seriesFromData",
+          "return": {
+            "type": {
+              "text": "Series[]"
+            }
+          },
+          "parameters": [
+            {
+              "name": "data",
+              "type": {
+                "text": "ChartData"
+              }
+            },
+            {
+              "name": "locale",
+              "default": "''"
+            }
+          ],
+          "description": "Reads `data` as series, one per column after the first, as `readSeries`\nreads a table: a column with no numbers in it is not a series, and a blank\nkeeps its row's place."
+        },
+        {
+          "kind": "function",
+          "name": "rowsFromData",
+          "return": {
+            "type": {
+              "text": "Row[]"
+            }
+          },
+          "parameters": [
+            {
+              "name": "data",
+              "type": {
+                "text": "ChartData"
+              }
+            },
+            {
+              "name": "locale",
+              "default": "''"
+            }
+          ],
+          "description": "Reads `data` as rows, as `readRows` reads a table: every cell with its\nwords and its number, including the columns nothing plots."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "seriesFromData",
+          "declaration": {
+            "name": "seriesFromData",
+            "module": "src/utils/read-data/read-data.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "rowsFromData",
+          "declaration": {
+            "name": "rowsFromData",
+            "module": "src/utils/read-data/read-data.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/utils/read-series/read-series.ts",
@@ -28106,7 +28455,7 @@
               }
             }
           ],
-          "description": "Reads a table as series, one per data column.\n\n**The table is the chart's accessible representation, not a fallback for\none.** Every chart here takes its numbers from real markup rather than from a\nproperty, so the page is readable with no script at all, sortable by anything\nthat sorts tables, and correct in a screen reader without a parallel\ndescription that has to be kept in step by hand. A `values` array would be\neasier to pass and would make the accessible version the thing nobody\nmaintains.\n\nThe shape is the ordinary one: a header row naming the series, a first column\nof row headers, and numbers in the rest. A single-column table has one series\nand takes its name from the caption, since a header row of one is usually\nabsent.\n\n`data-value` wins over the cell's text, because `$1.2k` is what a reader\nshould see and is not a number. `Number()` rather than `parseFloat`, because\nthe second reads `12abc` as 12: a value that is nearly a number is a mistake\nworth dropping rather than rounding off, and a dropped point is visible where\na silently truncated one is not.\n\n**A dropped point keeps its place.** Each point carries `at`, the row it was\nread from, and a chart draws it at that row's category. Counted by position\nin `points`, a blank in March slid April's reading under March's label, and a\nblank in the first column took a category off the axis for every series.\n`byRow` lays a series out one slot per row with the blanks left empty."
+          "description": "Reads a table as series, one per data column.\n\n**The table is the chart's accessible representation, not a fallback for\none.** Every chart here takes its numbers from real markup by preference, so\nthe page is readable with no script at all, sortable by anything that sorts\ntables, and correct in a screen reader without a parallel description that\nhas to be kept in step by hand. A chart's `data` takes the same shape for a\npage that has no table to show, and is read by `seriesFromData`; the docs\nsteer every page that can show a table to the table.\n\nThe shape is the ordinary one: a header row naming the series, a first column\nof row headers, and numbers in the rest. A single-column table has one series\nand takes its name from the caption, since a header row of one is usually\nabsent.\n\n`data-value` wins over the cell's text, because `$1.2k` is what a reader\nshould see and is not a number. `Number()` rather than `parseFloat`, because\nthe second reads `12abc` as 12: a value that is nearly a number is a mistake\nworth dropping rather than rounding off, and a dropped point is visible where\na silently truncated one is not.\n\n**A dropped point keeps its place.** Each point carries `at`, the row it was\nread from, and a chart draws it at that row's category. Counted by position\nin `points`, a blank in March slid April's reading under March's label, and a\nblank in the first column took a category off the axis for every series.\n`byRow` lays a series out one slot per row with the blanks left empty."
         },
         {
           "kind": "function",
@@ -31881,7 +32230,7 @@
           "type": {
             "text": "string"
           },
-          "default": "'0.152.0'",
+          "default": "'0.154.0'",
           "description": "The version of the package this file ships in.\n\n**Written by `fusion/scripts/version.mjs`** wherever it writes the package's\n`package.json`, and stamped back into the repository beside it after a\nrelease, so the two never disagree; a spec beside this holds them to it.\nNothing else in the running code knows which release it is."
         }
       ],
@@ -32441,6 +32790,6 @@
   ],
   "helix": {
     "package": "@fusion.dev/helix-core",
-    "version": "0.152.0"
+    "version": "0.154.0"
   }
 }

package/dist/controllers/source-controller/source-controller.d.ts

@@ -1,4 +1,5 @@
 import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import { type ChartData } from '../../utils/read-data/read-data.js';
 import { type Row, type Series } from '../../utils/read-series/read-series.js';
 /** A host that names the element it reads from. */
 export interface SourceHost extends ReactiveControllerHost, HTMLElement {
@@ -6,6 +7,14 @@ export interface SourceHost extends ReactiveControllerHost, HTMLElement {
      * The id of the table or grid to read.
      */
     for: string;
+    /**
+     * Readings given as data, read where `for` names nothing.
+     */
+    data?: ChartData | undefined;
+    /**
+     * The locale numbers in `data` are written in.
+     */
+    locale?: string;
 }
 /**
  * Resolves the element a chart reads from, and follows it.
@@ -69,6 +78,24 @@ export declare class SourceController implements ReactiveController {
      * a template Lit throws on. The update after it, which this asks for, draws.
      */
     get element(): Element | null;
+    /** Whether the host is hydrating what a server sent. */
+    private get hydrating();
+    /**
+     * The host's `data`, where it is read: on the client, after hydration, and
+     * where `for` names no table.
+     *
+     * **Never on the server**, so a chart given data serves the frame, as one
+     * reading a table does, and the drawing arrives on hydration. A server's
+     * element shim has no `closest`, which is how one is told apart, Lit's
+     * `isServer` being true in any test runner that resolves its `node` build.
+     */
+    private get data();
+    /**
+     * Whether what the chart reads has been looked at: a table resolved or
+     * looked for, or data read. False on the server and while hydrating, where
+     * neither is, so a chart there says nothing about its readings.
+     */
+    get known(): boolean;
     /**
      * The element `for` names, whatever the host is rendering.
      *
@@ -98,7 +125,11 @@ export declare class SourceController implements ReactiveController {
     get series(): Series[];
     /** Every row it holds, text and number alike, or none. Held the way `series` is. */
     get rows(): Row[];
-    /** A held parse where it still describes the table, or a fresh one. */
+    /**
+     * A held parse where it still describes the table or the data, or a fresh
+     * one. `data` is held by identity, so a new object is read again and an
+     * object changed in place is not, as a Lit property is.
+     */
     private parsed;
     /**
      * The series hidden on the table, by lowercased name. Empty where there is

package/dist/controllers/source-controller/source-controller.js

@@ -1,6 +1,8 @@
 import { auditSource } from '@fusion.dev/helix-core/audits/source';
-import { elementById } from '../../utils/element-by-id/element-by-id.js';
+import { elementById, searchableById } from '../../utils/element-by-id/element-by-id.js';
+import { rowsFromData, seriesFromData } from '../../utils/read-data/read-data.js';
 import { readRows, readSeries, seriesKey, } from '../../utils/read-series/read-series.js';
+import { wordsLocale } from '../../words/words-locale.js';
 const HIDDEN = new WeakMap();
 const READERS = new WeakMap();
 const NONE = new Set();
@@ -13,12 +15,32 @@ export class SourceController {
         host.addController(this);
     }
     get element() {
-        if (this.host.hydrating === true) {
-            this.deferred = this.host.for !== '';
+        if (this.hydrating) {
+            this.deferred = this.host.for !== '' || this.host.data !== undefined;
             return null;
         }
         return this.resolve();
     }
+    get hydrating() {
+        return this.host.hydrating === true;
+    }
+    get data() {
+        const host = this.host;
+        if (host.data === undefined || typeof host.closest !== 'function' || this.hydrating) {
+            return undefined;
+        }
+        return host.data;
+    }
+    get known() {
+        const host = this.host;
+        if (host.for === '' && host.data === undefined) {
+            return true;
+        }
+        if (typeof host.closest !== 'function' || this.hydrating) {
+            return false;
+        }
+        return host.for === '' || searchableById(host);
+    }
     resolve() {
         const host = this.host;
         if (host.for === '') {
@@ -37,19 +59,20 @@ export class SourceController {
             : null;
     }
     get series() {
-        this.heldSeries = this.parsed(this.heldSeries, (table) => (table ? readSeries(table) : []));
+        this.heldSeries = this.parsed(this.heldSeries, (table, data) => table ? readSeries(table) : data ? seriesFromData(data, wordsLocale(this.host)) : []);
         return this.heldSeries.value;
     }
     get rows() {
-        this.heldRows = this.parsed(this.heldRows, (table) => (table ? readRows(table) : []));
+        this.heldRows = this.parsed(this.heldRows, (table, data) => table ? readRows(table) : data ? rowsFromData(data, wordsLocale(this.host)) : []);
         return this.heldRows.value;
     }
     parsed(held, read) {
         const element = this.element;
-        if (held && held.element === element && held.version === this.version) {
+        const data = element ? undefined : this.data;
+        if (held && held.element === element && held.data === data && held.version === this.version) {
             return held;
         }
-        return { element, value: read(element), version: this.version };
+        return { data, element, value: read(element, data), version: this.version };
     }
     get hidden() {
         const element = this.element;

package/dist/index.d.ts

@@ -37,6 +37,7 @@ export { type ActivateDetail, type AuraFallbackDetail, type BandDetail, type Can
 export { HelixElement, whenHydrated } from './helix-element/helix-element.js';
 export { HelixFormElement } from './helix-form-element/helix-form-element.js';
 export { MixinChartSource, type MixinChartSourceInterface, PALETTE, PLOT_HEIGHT, PLOT_WIDTH, POSITION_LABEL, seriesIndex, seriesNames, } from './mixins/mixin-chart-source/mixin-chart-source.js';
+export { MixinChartStatus, type MixinChartStatusInterface, } from './mixins/mixin-chart-status/mixin-chart-status.js';
 export { type CollectionElement, MixinCollection, } from './mixins/mixin-collection/mixin-collection.js';
 export { MixinControllerActive, type MixinControllerActiveInterface, } from './mixins/mixin-controller-active/mixin-controller-active.js';
 export { MixinControllerChecked, type MixinControllerCheckedInterface, } from './mixins/mixin-controller-checked/mixin-controller-checked.js';
@@ -109,6 +110,7 @@ export { appleTouch, onAndroid, onApple, type Platform } from './utils/platform/
 export { pressType, type RecentPress } from './utils/press-type/press-type.js';
 export { rangeAdd } from './utils/range-add/range-add.js';
 export { type ColorBytes, type ColorBytesAlpha, readColor, readColorAlpha, rgbOf, } from './utils/read-color/read-color.js';
+export { type ChartData, type ChartDatum, rowsFromData, seriesFromData, } from './utils/read-data/read-data.js';
 export { byRow, type Extremes, extremesOf, type Row, type RowCell, readRows, readSeries, type Series, type SeriesPoint, seriesKey, unbroken, } from './utils/read-series/read-series.js';
 export { type ElementsProperty, linkDescription, reflectElements, unlinkDescription, } from './utils/reflect-elements/reflect-elements.js';
 export { type Relative, type RelativeOptions, relativeTime, } from './utils/relative-time/relative-time.js';

package/dist/index.js

@@ -37,6 +37,7 @@ export { HelixActionEvent, HelixActivateEvent, HelixAuraFallbackEvent, HelixBand
 export { HelixElement, whenHydrated } from './helix-element/helix-element.js';
 export { HelixFormElement } from './helix-form-element/helix-form-element.js';
 export { MixinChartSource, PALETTE, PLOT_HEIGHT, PLOT_WIDTH, POSITION_LABEL, seriesIndex, seriesNames, } from './mixins/mixin-chart-source/mixin-chart-source.js';
+export { MixinChartStatus, } from './mixins/mixin-chart-status/mixin-chart-status.js';
 export { MixinCollection, } from './mixins/mixin-collection/mixin-collection.js';
 export { MixinControllerActive, } from './mixins/mixin-controller-active/mixin-controller-active.js';
 export { MixinControllerChecked, } from './mixins/mixin-controller-checked/mixin-controller-checked.js';
@@ -109,6 +110,7 @@ export { appleTouch, onAndroid, onApple } from './utils/platform/platform.js';
 export { pressType } from './utils/press-type/press-type.js';
 export { rangeAdd } from './utils/range-add/range-add.js';
 export { readColor, readColorAlpha, rgbOf, } from './utils/read-color/read-color.js';
+export { rowsFromData, seriesFromData, } from './utils/read-data/read-data.js';
 export { byRow, extremesOf, readRows, readSeries, seriesKey, unbroken, } from './utils/read-series/read-series.js';
 export { linkDescription, reflectElements, unlinkDescription, } from './utils/reflect-elements/reflect-elements.js';
 export { relativeTime, } from './utils/relative-time/relative-time.js';

package/dist/mixins/mixin-chart-source/mixin-chart-source.d.ts

@@ -1,5 +1,6 @@
 import { ChartPointerController } from '../../controllers/chart-pointer-controller/chart-pointer-controller.js';
 import type { HelixElement } from '../../helix-element/helix-element.js';
+import type { ChartData } from '../../utils/read-data/read-data.js';
 import { type Row, type Series } from '../../utils/read-series/read-series.js';
 type Constructor<T> = new (...args: any[]) => T;
 /**
@@ -110,6 +111,11 @@ export declare const seriesNames: (list: string | undefined) => string[];
  * @cssproperty --chart-series-24 - The color of series 24. The styled tier points it at a palette token.
  */
 export declare class MixinChartSourceInterface {
+    /**
+     * The readings as data, in the shape of a table, where the page has no
+     * table to point `for` at. `for` wins where both are set.
+     */
+    data: ChartData | undefined;
     /**
      * The id of the table to read.
      *
@@ -145,6 +151,11 @@ export declare class MixinChartSourceInterface {
      * {count}`, or to nothing to say no position.
      */
     positionLabel: string;
+    /**
+     * Whether the readings have been looked for: false on the server and while
+     * hydrating, where no table is resolved and no data is read.
+     */
+    get readingsKnown(): boolean;
     /**
      * The table's columns, one series each. Empty when there is no table.
      */

package/dist/mixins/mixin-chart-source/mixin-chart-source.js

@@ -22,6 +22,7 @@ export const MixinChartSource = (Base) => {
             super(...arguments);
             this.source = new SourceController(this);
             this.pointer = new ChartPointerController(this);
+            this.data = undefined;
             this.for = '';
             this.label = '';
             this.locale = '';
@@ -48,11 +49,16 @@ export const MixinChartSource = (Base) => {
             return this.source.series;
         }
         get named() {
+            const table = this.source.element;
             return (this.getAttribute?.('aria-label') ||
                 this.label ||
-                this.source.element?.querySelector('caption')?.textContent?.trim() ||
+                table?.querySelector('caption')?.textContent?.trim() ||
+                (table ? '' : this.data?.caption) ||
                 '');
         }
+        get readingsKnown() {
+            return this.source.known;
+        }
         get sourceRows() {
             return this.source.rows;
         }
@@ -79,6 +85,9 @@ export const MixinChartSource = (Base) => {
             return this.sourceRows.length;
         }
     }
+    __decorate([
+        property({ attribute: false })
+    ], ChartSourceElement.prototype, "data", void 0);
     __decorate([
         property()
     ], ChartSourceElement.prototype, "for", void 0);

package/dist/mixins/mixin-chart-status/mixin-chart-status.d.ts

@@ -0,0 +1,59 @@
+import { nothing, type TemplateResult } from 'lit';
+import type { HelixElement } from '../../helix-element/helix-element.js';
+type Constructor<T> = new (...args: any[]) => T;
+/** A chart that reads a table or data, and knows whether it has looked yet. */
+interface ChartHost extends HelixElement {
+    /** Whether the readings have been looked for, which a server never does. */
+    readonly readingsKnown: boolean;
+}
+/**
+ * The public surface `MixinChartStatus` adds.
+ *
+ * Declared apart from the class for the reason `MixinChartSourceInterface`
+ * gives: TypeScript cannot emit declarations for an anonymous class with
+ * protected members.
+ */
+export declare class MixinChartStatusInterface {
+    /**
+     * The words shown in place of the drawing when the table has no readings,
+     * and the fallback of the `empty` slot.
+     */
+    emptyText: string;
+    /**
+     * Whether the readings are still on their way. The chart shows
+     * `loading-text` in place of an empty drawing until it has readings.
+     */
+    loading: boolean;
+    /**
+     * The words shown in place of the drawing while `loading` is set and there
+     * are no readings yet, and the fallback of the `loading` slot.
+     */
+    loadingText: string;
+    /**
+     * What stands in the plot while there is nothing to draw: the `loading`
+     * line, the `empty` line, or nothing while the table cannot be read yet.
+     */
+    protected renderStatus(): TemplateResult | typeof nothing;
+}
+/**
+ * What a chart shows in place of its drawing when it has no readings: words
+ * while they load, and words when the table it reads has none.
+ *
+ * **A blank box said neither.** A chart pointed at an empty table drew its
+ * plot at full height with nothing in it, which reads as a chart that failed,
+ * and one waiting for a request drew the same. `Table` and `Data Table` take
+ * the same pair, `empty-text` and `loading-text` with `empty` and `loading`
+ * slots for markup, such as a link to add the first reading.
+ *
+ * **Nothing at all while the readings cannot be looked for**, which is a
+ * server render and the hydrating one after it: there is no document to
+ * resolve `for` in and `data` is drawn on the client only, so "No readings"
+ * there would be a claim about readings nobody has looked at. `Heatmap` keeps
+ * the same rule for its own `empty-text`.
+ *
+ * Applied by the four charts that draw on axes. The slots and parts are
+ * documented on each of them, a class-level tag on a mixin reaching no
+ * manifest.
+ */
+export declare const MixinChartStatus: <T extends Constructor<ChartHost>>(Base: T) => T & Constructor<MixinChartStatusInterface>;
+export {};

package/dist/mixins/mixin-chart-status/mixin-chart-status.js

@@ -0,0 +1,40 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { html, nothing } from 'lit';
+import { property } from 'lit/decorators.js';
+import { words } from '../../words/words.js';
+export const MixinChartStatus = (Base) => {
+    class ChartStatusElement extends Base {
+        constructor() {
+            super(...arguments);
+            this.emptyText = 'No readings';
+            this.loading = false;
+            this.loadingText = 'Loading readings';
+        }
+        static { this.words = ''; }
+        renderStatus() {
+            if (this.loading) {
+                return html `<p dir="auto" part="loading"><slot name="loading">${this.loadingText}</slot></p>`;
+            }
+            return this.readingsKnown
+                ? html `<p dir="auto" part="empty"><slot name="empty">${this.emptyText}</slot></p>`
+                : nothing;
+        }
+    }
+    __decorate([
+        words,
+        property({ attribute: 'empty-text' })
+    ], ChartStatusElement.prototype, "emptyText", void 0);
+    __decorate([
+        property({ reflect: true, type: Boolean })
+    ], ChartStatusElement.prototype, "loading", void 0);
+    __decorate([
+        words,
+        property({ attribute: 'loading-text' })
+    ], ChartStatusElement.prototype, "loadingText", void 0);
+    return ChartStatusElement;
+};

package/dist/utils/number-format/number-format.d.ts

@@ -8,7 +8,7 @@
  * build and cheap to call, and a control formats on every update.
  */
 /** Writes a number in a locale with `Intl.NumberFormat` options. */
-export declare const formatNumber: (value: number, locale?: string, options?: Intl.NumberFormatOptions) => string;
+export declare const formatNumber: (value: number, locale?: string, options?: Intl.NumberFormatOptions | null) => string;
 /**
  * A share, from 0 to 1, as a locale writes a whole percentage: `40%`, or
  * `40 %` in French. For `aria-valuetext`, since a bare `aria-valuenow` is read

package/dist/utils/number-format/number-format.js

@@ -3,7 +3,7 @@ const formatter = (locale, options) => {
     const key = `${locale}|${JSON.stringify(options ?? {})}`;
     let found = held.get(key);
     if (!found) {
-        found = new Intl.NumberFormat(locale || undefined, options);
+        found = new Intl.NumberFormat(locale || undefined, options ?? undefined);
         held.set(key, found);
     }
     return found;

package/dist/utils/read-data/read-data.d.ts

@@ -0,0 +1,50 @@
+import type { Row, Series } from '../read-series/read-series.js';
+/**
+ * One cell of a chart's `data`: a number, words, a blank, or a number with
+ * the words it is shown as, such as `{ value: 128000, text: '$128k' }`.
+ */
+export type ChartDatum = number | string | null | undefined | {
+    text: string;
+    value: number;
+};
+/**
+ * A chart's readings given as data, in the shape a table has.
+ *
+ * ```js
+ * chart.data = {
+ *   caption: 'Sessions by channel',
+ *   columns: ['Month', 'Direct', 'Referral'],
+ *   rows: [
+ *     ['Jan', 10, 4],
+ *     ['Feb', 20, 8],
+ *   ],
+ * }
+ * ```
+ */
+export interface ChartData {
+    /**
+     * The chart's name where it has no `label`, as a table's caption is, and
+     * the series' name where there is one column and no heading for it.
+     */
+    caption?: string;
+    /**
+     * The column headings. The first heads the row labels, and each after it
+     * names a series.
+     */
+    columns: string[];
+    /**
+     * One row per reading: its label first, then a cell per column.
+     */
+    rows: ReadonlyArray<readonly [label: string, ...cells: ChartDatum[]]>;
+}
+/**
+ * Reads `data` as series, one per column after the first, as `readSeries`
+ * reads a table: a column with no numbers in it is not a series, and a blank
+ * keeps its row's place.
+ */
+export declare const seriesFromData: (data: ChartData, locale?: string) => Series[];
+/**
+ * Reads `data` as rows, as `readRows` reads a table: every cell with its
+ * words and its number, including the columns nothing plots.
+ */
+export declare const rowsFromData: (data: ChartData, locale?: string) => Row[];

package/dist/utils/read-data/read-data.js

@@ -0,0 +1,35 @@
+const cellOf = (datum, locale) => {
+    if (datum === null || datum === undefined) {
+        return { text: '' };
+    }
+    if (typeof datum === 'object') {
+        return Number.isFinite(datum.value)
+            ? { text: datum.text, value: datum.value }
+            : { text: datum.text };
+    }
+    if (typeof datum === 'number') {
+        return Number.isFinite(datum)
+            ? { text: new Intl.NumberFormat(locale || undefined).format(datum), value: datum }
+            : { text: '' };
+    }
+    const value = Number(datum.trim());
+    return Number.isFinite(value) && datum.trim() !== '' ? { text: datum, value } : { text: datum };
+};
+export const seriesFromData = (data, locale = '') => {
+    const names = data.columns.slice(1);
+    const count = Math.max(0, ...data.rows.map((row) => row.length - 1));
+    return Array.from({ length: count }, (_, column) => ({
+        name: names[column] ?? data.caption ?? '',
+        points: data.rows.flatMap((row, at) => {
+            const value = cellOf(row[column + 1], locale).value;
+            return value === undefined ? [] : [{ at, label: String(row[0] ?? ''), value }];
+        }),
+    })).filter((one) => one.points.length > 0);
+};
+export const rowsFromData = (data, locale = '') => data.rows.map((row) => ({
+    cells: row.slice(1).map((datum, column) => ({
+        name: data.columns[column + 1] ?? '',
+        ...cellOf(datum, locale),
+    })),
+    label: String(row[0] ?? ''),
+}));

package/dist/utils/read-series/read-series.d.ts

@@ -38,12 +38,12 @@ export interface Series {
  * Reads a table as series, one per data column.
  *
  * **The table is the chart's accessible representation, not a fallback for
- * one.** Every chart here takes its numbers from real markup rather than from a
- * property, so the page is readable with no script at all, sortable by anything
- * that sorts tables, and correct in a screen reader without a parallel
- * description that has to be kept in step by hand. A `values` array would be
- * easier to pass and would make the accessible version the thing nobody
- * maintains.
+ * one.** Every chart here takes its numbers from real markup by preference, so
+ * the page is readable with no script at all, sortable by anything that sorts
+ * tables, and correct in a screen reader without a parallel description that
+ * has to be kept in step by hand. A chart's `data` takes the same shape for a
+ * page that has no table to show, and is read by `seriesFromData`; the docs
+ * steer every page that can show a table to the table.
  *
  * The shape is the ordinary one: a header row naming the series, a first column
  * of row headers, and numbers in the rest. A single-column table has one series

package/dist/version.d.ts

@@ -6,4 +6,4 @@
  * release, so the two never disagree; a spec beside this holds them to it.
  * Nothing else in the running code knows which release it is.
  */
-export declare const VERSION = "0.152.0";
+export declare const VERSION = "0.154.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.152.0';
+export const VERSION = '0.154.0';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.152.0",
+  "version": "0.154.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -56,11 +56,11 @@
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",
-    "@fusion.dev/helix-icons": "0.152.0"
+    "@fusion.dev/helix-icons": "0.154.0"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.152.0",
-    "@fusion.dev/helix-testing": "0.152.0",
+    "@fusion.dev/helix-cem": "0.154.0",
+    "@fusion.dev/helix-testing": "0.154.0",
     "@lit-labs/ssr": "^4.1.0",
     "lit": "^3.2.1"
   },