@fusion.dev/helix-core 0.176.0 → 0.177.0

package/custom-elements.json

@@ -12842,6 +12842,14 @@
             "package": "#audit-name"
           }
         },
+        {
+          "kind": "js",
+          "name": "auditNesting",
+          "declaration": {
+            "name": "auditNesting",
+            "package": "#audit-nesting"
+          }
+        },
         {
           "kind": "js",
           "name": "auditServed",
@@ -18135,6 +18143,17 @@
                 "text": "ChartPointerController"
               },
               "description": "Finds the reading nearest the pointer, so the tooltip can sit on it."
+            },
+            {
+              "kind": "method",
+              "name": "renderTable",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "TemplateResult | typeof nothing"
+                }
+              },
+              "description": "The readings as a table, for a screen reader, where they were drawn from\n`data`: there is then no table on the page to read. Nothing otherwise."
             }
           ],
           "helix": {}
@@ -18171,13 +18190,6 @@
               "default": "new SourceController(this)",
               "description": "Resolves `for` and re-renders when the table behind it changes."
             },
-            {
-              "kind": "field",
-              "name": "pointer",
-              "readonly": true,
-              "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",
@@ -18230,46 +18242,6 @@
                 "words": true
               }
             },
-            {
-              "kind": "field",
-              "name": "observedAttributes",
-              "type": {
-                "text": "string[]"
-              },
-              "static": true,
-              "description": "Hears an `aria-label` written on the chart, which no property mirrors,\nso a page that names the chart that way names its plot.\n\nLit observes the attributes of its own properties only, and `ariaLabel`\nbelongs to the platform.\n\nRead through `Reflect.get` with this class as the receiver, which is\nwhat `super.observedAttributes` means: Lit's getter finalizes whichever\nclass it is asked on, and asked on the base it would finalize the base\nand leave a subclass without its styles. A mixin's base has no static\nside TypeScript can see, so `super` cannot be written here.",
-              "readonly": true
-            },
-            {
-              "kind": "method",
-              "name": "attributeChangedCallback",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              },
-              "parameters": [
-                {
-                  "name": "name",
-                  "type": {
-                    "text": "string"
-                  }
-                },
-                {
-                  "name": "old",
-                  "type": {
-                    "text": "string | null"
-                  }
-                },
-                {
-                  "name": "value",
-                  "type": {
-                    "text": "string | null"
-                  }
-                }
-              ],
-              "description": "Called by the browser when an observed attribute changes. A new\n`aria-label` asks for an update, because it names the plot."
-            },
             {
               "kind": "field",
               "name": "series",
@@ -18288,24 +18260,6 @@
               "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",
-              "type": {
-                "text": "Row[]"
-              },
-              "description": "Every row of the table, with each cell's text and number.\n\nThis is where a tooltip's content comes from, and it is deliberately not\n`series`. A chart draws numbers; a reader resting a pointer on one wants\nwhat the table says, which is `$128k` and not `128000`, and often wants\nthe column beside it that nothing plotted at all.\n\n**Not `rows`.** It is the source table's rows, and `rows` on a chart is a\nname a chart wants for itself: `helix-heatmap` takes `rows=\"7\"` to mean a\ncalendar week, and declaring that against a base class whose `rows` is a\n`Row[]` getter is a type error at best. Name the member for what it holds\nrather than for the shortest word available.",
-              "readonly": true
-            },
             {
               "kind": "field",
               "name": "plottedColumns",
@@ -18395,6 +18349,17 @@
               },
               "description": "The number of readings, which the pointer position maps onto.",
               "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "renderTable",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "TemplateResult | typeof nothing"
+                }
+              },
+              "description": "The readings as a table, for a screen reader, where they were drawn from\n`data`: there is then no table on the page to read, and a chart's\nsummary gives only what the readings come to. Nothing where a table on\nthe page was read, which is already the readable version.\n\nThe `table` part, named by the chart, its cells as `data` writes them."
             }
           ],
           "attributes": [
@@ -18555,13 +18520,24 @@
                 }
               },
               "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."
+            },
+            {
+              "kind": "method",
+              "name": "renderEmpty",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "TemplateResult"
+                }
+              },
+              "description": "The plot while there is nothing to draw: a group named as the chart is,\nholding `renderStatus`."
             }
           ],
           "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.",
+          "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\n**The plot keeps the chart's name while it has nothing to draw**, as a\ngroup around the words, so the chart is still found by its name.\n\n**Three custom states follow:** `active` while a reading is shown, under the\npointer or the keys, with its tooltip open; `empty` while the empty words\nstand in the plot; and `loading` while the loading words do.\n\nApplied by the four charts that draw on axes and by Donut Chart. The slots,\nparts and states are documented on each of them, a class-level tag on a\nmixin reaching no manifest.",
           "name": "MixinChartStatus",
           "members": [
             {
@@ -18621,6 +18597,17 @@
                 }
               },
               "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."
+            },
+            {
+              "kind": "method",
+              "name": "renderEmpty",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "TemplateResult"
+                }
+              },
+              "description": "The plot while there is nothing to draw: a group named as the chart is,\nholding `renderStatus`. Not focusable, there being no reading to walk."
             }
           ],
           "attributes": [
@@ -24659,6 +24646,70 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/utils/audit-nesting/audit-nesting-off.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "auditNesting",
+          "description": "The unslotted-item warning in a production build: nothing.\n\n`#audit-nesting` resolves here unless the bundler or runtime asks for the\n`development` condition, so a production build carries none of the audit's\ncode. The signature is the audit's, so a call site reads the same in both\nbuilds. See `audit-nesting.ts`.",
+          "type": {
+            "text": "typeof audit"
+          }
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "auditNesting",
+          "declaration": {
+            "name": "auditNesting",
+            "module": "src/utils/audit-nesting/audit-nesting-off.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/utils/audit-nesting/audit-nesting.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "auditNesting",
+          "return": {
+            "type": {
+              "text": "void"
+            }
+          },
+          "parameters": [
+            {
+              "name": "host",
+              "type": {
+                "text": "HTMLElement"
+              }
+            },
+            {
+              "name": "slot",
+              "type": {
+                "text": "string"
+              }
+            }
+          ],
+          "description": "Reports an item nested in another item of its own tag without the slot that\nnests it, the one mistake that leaves a tree drawing the child as words.\n\n`<helix-tree-item>src<helix-tree-item>app.ts</helix-tree-item></helix-tree-item>`\nputs the inner item in the outer one's default slot, which is its label: the\nrow reads \"src app.ts\" and is drawn as a leaf. The item has to carry\n`slot=\"children\"`. **Nothing moves it there**, because writing `slot` onto\nan element the page rendered is a change to markup a server sent and a\nframework owns.\n\n**In a development build only**, as `missing-name` is: every item would pay\nfor a sentence meant for the person writing the page. Core imports it as\n`#audit-nesting`, which `package.json` resolves here under the `development`\ncondition and to `audit-nesting-off.ts`, which does nothing, everywhere else.\n\n`slot` is the name of the slot that nests an item."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "auditNesting",
+          "declaration": {
+            "name": "auditNesting",
+            "module": "src/utils/audit-nesting/audit-nesting.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/utils/audit-served/audit-served-off.ts",
@@ -24746,6 +24797,14 @@
           "type": {
             "text": "typeof audit"
           }
+        },
+        {
+          "kind": "function",
+          "name": "auditData",
+          "description": "The malformed-data warning in a production build: nothing.",
+          "type": {
+            "text": "typeof auditShape"
+          }
         }
       ],
       "exports": [
@@ -24756,6 +24815,14 @@
             "name": "auditSource",
             "module": "src/utils/audit-source/audit-source-off.ts"
           }
+        },
+        {
+          "kind": "js",
+          "name": "auditData",
+          "declaration": {
+            "name": "auditData",
+            "module": "src/utils/audit-source/audit-source-off.ts"
+          }
         }
       ]
     },
@@ -24786,6 +24853,24 @@
             }
           ],
           "description": "Reports a chart, a legend or a sparkline whose `for` names no table once the\npage has loaded, the one mistake that leaves it drawing nothing and saying\nnothing.\n\n**Read a task after `load`**, so a table later in the markup, or one a\nscript writes as the page starts, counts. A table a framework renders later\nthan that is reported, and the chart still draws it when it arrives.\n\n**In a development build only**, as `missing-name` is: every chart would pay\nfor a sentence meant for the person writing the page. Core imports it as\n`#audit-source`, which `package.json` resolves here under the `development`\ncondition and to `audit-source-off.ts`, which does nothing, everywhere else.\n\n`table` answers what `for` resolves to now: the table, or null."
+        },
+        {
+          "kind": "function",
+          "name": "auditData",
+          "return": {
+            "type": {
+              "text": "void"
+            }
+          },
+          "parameters": [
+            {
+              "name": "host",
+              "type": {
+                "text": "HTMLElement"
+              }
+            }
+          ],
+          "description": "Reports a chart whose `data` is not `{ columns, rows }`, such as an array of\nrows, once for each chart. The chart draws its empty state. In a development\nbuild only, as the missing-table warning is."
         }
       ],
       "exports": [
@@ -24796,6 +24881,14 @@
             "name": "auditSource",
             "module": "src/utils/audit-source/audit-source.ts"
           }
+        },
+        {
+          "kind": "js",
+          "name": "auditData",
+          "declaration": {
+            "name": "auditData",
+            "module": "src/utils/audit-source/audit-source.ts"
+          }
         }
       ]
     },
@@ -29913,6 +30006,24 @@
       "kind": "javascript-module",
       "path": "src/utils/read-data/read-data.ts",
       "declarations": [
+        {
+          "kind": "function",
+          "name": "isChartData",
+          "return": {
+            "type": {
+              "text": "data is ChartData"
+            }
+          },
+          "parameters": [
+            {
+              "name": "data",
+              "type": {
+                "text": "unknown"
+              }
+            }
+          ],
+          "description": "Whether `data` has the shape a chart reads: an object with an array of\n`columns` and an array of `rows`, each row an array. Any other value draws\nthe empty state, where it would throw from the render."
+        },
         {
           "kind": "function",
           "name": "seriesFromData",
@@ -29959,6 +30070,14 @@
         }
       ],
       "exports": [
+        {
+          "kind": "js",
+          "name": "isChartData",
+          "declaration": {
+            "name": "isChartData",
+            "module": "src/utils/read-data/read-data.ts"
+          }
+        },
         {
           "kind": "js",
           "name": "seriesFromData",
@@ -33810,7 +33929,7 @@
           "type": {
             "text": "string"
           },
-          "default": "'0.176.0'",
+          "default": "'0.177.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."
         }
       ],
@@ -33825,6 +33944,110 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/words/held.ts",
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "held",
+          "type": {
+            "text": "Held"
+          },
+          "description": "The page's words, held on `globalThis`.\n\n**One registry for a page that carries two copies of this module**, one per\nbundle that imports it: words registered through one have to reach elements\ndefined through the other, as the icon registry's glyphs do.\n\n**What every element reads, and nothing more.** An element with a word\nproperty reads its English until a page registers words, so the lookup and\nthe locale chain arrive with `registerWords`, which puts its lookup in\n`find`, and the locale with `wordsLocale`, which puts itself in `locale`. A\npage that registers no words and formats no numbers ships neither: measured\non Button, 474 bytes of its 13,437 compressed."
+        },
+        {
+          "kind": "function",
+          "name": "changed",
+          "return": {
+            "type": {
+              "text": "void"
+            }
+          },
+          "description": "Asks every element that reads words to look again, once per task."
+        },
+        {
+          "kind": "function",
+          "name": "wordsRegistered",
+          "return": {
+            "type": {
+              "text": "boolean"
+            }
+          },
+          "description": "Whether any words are registered, for a read that can skip the lookup."
+        },
+        {
+          "kind": "function",
+          "name": "watchLang",
+          "return": {
+            "type": {
+              "text": "void"
+            }
+          },
+          "description": "Starts watching the document's `lang`, once for the page, in a browser.\nCalled by what a `lang` change reaches: registered words, and a locale read."
+        },
+        {
+          "kind": "function",
+          "name": "watchWords",
+          "return": {
+            "type": {
+              "text": "(() => void)"
+            }
+          },
+          "parameters": [
+            {
+              "name": "watcher",
+              "type": {
+                "text": "() => void"
+              }
+            }
+          ],
+          "description": "Calls `watcher` once in the microtask after words are registered or\ncleared, or the document's `lang` changes. Returns the function that stops\nit."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "held",
+          "declaration": {
+            "name": "held",
+            "module": "src/words/held.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "changed",
+          "declaration": {
+            "name": "changed",
+            "module": "src/words/held.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "wordsRegistered",
+          "declaration": {
+            "name": "wordsRegistered",
+            "module": "src/words/held.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "watchLang",
+          "declaration": {
+            "name": "watchLang",
+            "module": "src/words/held.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "watchWords",
+          "declaration": {
+            "name": "watchWords",
+            "module": "src/words/held.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/words/index.ts",
@@ -34094,16 +34317,6 @@
           ],
           "description": "The locales a word is looked for in, most specific first, ending in `en`.\n\n**The script comes before the bare language**, so Hong Kong (`zh-HK`)\nreaches a Traditional Chinese pack (`zh-Hant`) before a `zh` pack, which is\nusually Simplified. Unicode extensions are dropped, and a tag `Intl` refuses\nfalls straight to `en`.\n\n`de-CH` tries `de-ch`, `de-latn-ch`, `de-latn`, `de`, then `en`."
         },
-        {
-          "kind": "function",
-          "name": "wordsRegistered",
-          "return": {
-            "type": {
-              "text": "boolean"
-            }
-          },
-          "description": "Whether any words are registered, for a read that can skip the lookup."
-        },
         {
           "kind": "function",
           "name": "lookupWord",
@@ -34133,27 +34346,25 @@
             }
           ],
           "description": "A registered word for a tag's property in a locale, with the locale it was\nfound in, or `undefined`.\n\n**Per key, along the chain.** A `de-CH` pack that holds only the Swiss\nspellings falls through to `de` for every other word. A word table merges\nalong the chain, the more specific entry winning."
-        },
-        {
-          "kind": "function",
-          "name": "watchWords",
-          "return": {
-            "type": {
-              "text": "(() => void)"
-            }
-          },
-          "parameters": [
-            {
-              "name": "watcher",
-              "type": {
-                "text": "() => void"
-              }
-            }
-          ],
-          "description": "Calls `watcher` once in the microtask after words are registered or\ncleared, or the document's `lang` changes. Returns the function that stops\nit.\n\nThe first watcher in a browser starts watching the document's `lang`, once\nfor the page."
         }
       ],
       "exports": [
+        {
+          "kind": "js",
+          "name": "watchWords",
+          "declaration": {
+            "name": "watchWords",
+            "module": "./held.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "wordsRegistered",
+          "declaration": {
+            "name": "wordsRegistered",
+            "module": "./held.js"
+          }
+        },
         {
           "kind": "js",
           "name": "registerWords",
@@ -34202,14 +34413,6 @@
             "module": "src/words/registry.ts"
           }
         },
-        {
-          "kind": "js",
-          "name": "wordsRegistered",
-          "declaration": {
-            "name": "wordsRegistered",
-            "module": "src/words/registry.ts"
-          }
-        },
         {
           "kind": "js",
           "name": "lookupWord",
@@ -34217,14 +34420,6 @@
             "name": "lookupWord",
             "module": "src/words/registry.ts"
           }
-        },
-        {
-          "kind": "js",
-          "name": "watchWords",
-          "declaration": {
-            "name": "watchWords",
-            "module": "src/words/registry.ts"
-          }
         }
       ]
     },
@@ -34370,6 +34565,6 @@
   ],
   "helix": {
     "package": "@fusion.dev/helix-core",
-    "version": "0.176.0"
+    "version": "0.177.0"
   }
 }

package/dist/controllers/chart-pointer-controller/chart-pointer-controller.d.ts

@@ -50,6 +50,12 @@ export interface ChartPointerHost extends ReactiveControllerHost, HTMLElement {
      * The keys pass over a hidden reading, as they pass over a hidden series.
      */
     showsReading?(at: number): boolean;
+    /**
+     * The readings in the order the keys walk them, by place, for a chart whose
+     * drawing does not follow the table: a scatter's points from left to right.
+     * Absent, the keys walk the table's order.
+     */
+    readingOrder?(): number[];
     /**
      * Where PageUp or PageDown goes from the reading at `at`, by place among the
      * readings, for a chart whose page is no fixed count: a calendar's month.

package/dist/controllers/chart-pointer-controller/chart-pointer-controller.js

@@ -58,6 +58,7 @@ export class ChartPointerController {
                 if (this.at >= 0) {
                     event.preventDefault();
                     this.clear();
+                    this.by = 'keyboard';
                 }
                 return;
             }
@@ -206,7 +207,7 @@ export class ChartPointerController {
     }
     shown() {
         const host = this.host;
-        const all = Array.from({ length: host.readings }, (_, at) => at);
+        const all = host.readingOrder?.() ?? Array.from({ length: host.readings }, (_, at) => at);
         return host.showsReading === undefined
             ? all
             : all.filter((at) => host.showsReading?.(at) !== false);

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

@@ -1,6 +1,6 @@
-import { auditSource } from '@fusion.dev/helix-core/audits/source';
+import { auditData, auditSource } from '@fusion.dev/helix-core/audits/source';
 import { elementById, searchableById } from '../../utils/element-by-id/element-by-id.js';
-import { rowsFromData, seriesFromData } from '../../utils/read-data/read-data.js';
+import { isChartData, 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();
@@ -29,6 +29,10 @@ export class SourceController {
         if (host.data === undefined || typeof host.closest !== 'function' || this.hydrating) {
             return undefined;
         }
+        if (!isChartData(host.data)) {
+            auditData(host);
+            return undefined;
+        }
         return host.data;
     }
     get known() {

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { auditName } from '@fusion.dev/helix-core/audits/name';
+export { auditNesting } from '@fusion.dev/helix-core/audits/nesting';
 export { auditServed } from '@fusion.dev/helix-core/audits/served';
 export { AriaForwardController, type AriaForwardOptions, } from './controllers/aria-forward-controller/aria-forward-controller.js';
 export { ArrivalController, type ArrivalOptions, } from './controllers/arrival-controller/arrival-controller.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { auditName } from '@fusion.dev/helix-core/audits/name';
+export { auditNesting } from '@fusion.dev/helix-core/audits/nesting';
 export { auditServed } from '@fusion.dev/helix-core/audits/served';
 export { AriaForwardController, } from './controllers/aria-forward-controller/aria-forward-controller.js';
 export { ArrivalController, } from './controllers/arrival-controller/arrival-controller.js';

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

@@ -1,3 +1,4 @@
+import { nothing, type TemplateResult } from 'lit';
 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';
@@ -202,6 +203,11 @@ export declare class MixinChartSourceInterface {
      * Finds the reading nearest the pointer, so the tooltip can sit on it.
      */
     pointer: ChartPointerController;
+    /**
+     * The readings as a table, for a screen reader, where they were drawn from
+     * `data`: there is then no table on the page to read. Nothing otherwise.
+     */
+    protected renderTable(): TemplateResult | typeof nothing;
 }
 /**
  * The words a chart says a reading's place in by default, such as "2 of 12":

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

@@ -4,6 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     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 { ChartPointerController } from '../../controllers/chart-pointer-controller/chart-pointer-controller.js';
 import { SourceController } from '../../controllers/source-controller/source-controller.js';
@@ -84,6 +85,19 @@ export const MixinChartSource = (Base) => {
         get readings() {
             return this.sourceRows.length;
         }
+        renderTable() {
+            const rows = this.sourceRows;
+            if (this.source.element || rows.length === 0) {
+                return nothing;
+            }
+            const width = Math.max(...rows.map((row) => row.cells.length));
+            const columns = Array.from({ length: width }, (_, cell) => this.columnName(cell));
+            return html `<table part="table">
+        ${this.named ? html `<caption>${this.named}</caption>` : nothing}
+        <thead><tr><th scope="col">${this.data?.columns[0] ?? ''}</th>${columns.map((name) => html `<th scope="col">${name}</th>`)}</tr></thead>
+        <tbody>${rows.map((row) => html `<tr><th scope="row">${row.label}</th>${columns.map((_, cell) => html `<td>${row.cells[cell]?.text ?? ''}</td>`)}</tr>`)}</tbody>
+      </table>`;
+        }
     }
     __decorate([
         property({ attribute: false })

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

@@ -5,6 +5,12 @@ type Constructor<T> = new (...args: any[]) => T;
 interface ChartHost extends HelixElement {
     /** Whether the readings have been looked for, which a server never does. */
     readonly readingsKnown: boolean;
+    /** The chart's name, which the plot keeps while it has nothing to draw. */
+    readonly named: string;
+    /** The reading shown, by its place, or -1 for none. */
+    readonly pointer: {
+        readonly at: number;
+    };
 }
 /**
  * The public surface `MixinChartStatus` adds.
@@ -34,6 +40,11 @@ export declare class MixinChartStatusInterface {
      * line, the `empty` line, or nothing while the table cannot be read yet.
      */
     protected renderStatus(): TemplateResult | typeof nothing;
+    /**
+     * The plot while there is nothing to draw: a group named as the chart is,
+     * holding `renderStatus`.
+     */
+    protected renderEmpty(): TemplateResult;
 }
 /**
  * What a chart shows in place of its drawing when it has no readings: words
@@ -51,9 +62,16 @@ export declare class MixinChartStatusInterface {
  * 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.
+ * **The plot keeps the chart's name while it has nothing to draw**, as a
+ * group around the words, so the chart is still found by its name.
+ *
+ * **Three custom states follow:** `active` while a reading is shown, under the
+ * pointer or the keys, with its tooltip open; `empty` while the empty words
+ * stand in the plot; and `loading` while the loading words do.
+ *
+ * Applied by the four charts that draw on axes and by Donut Chart. The slots,
+ * parts and states 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

@@ -6,6 +6,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
+import { CHART_PLOT } from '../../controllers/chart-pointer-controller/chart-pointer-controller.js';
 import { words } from '../../words/words.js';
 export const MixinChartStatus = (Base) => {
     class ChartStatusElement extends Base {
@@ -24,6 +25,22 @@ export const MixinChartStatus = (Base) => {
                 ? html `<p dir="auto" part="empty"><slot name="empty">${this.emptyText}</slot></p>`
                 : nothing;
         }
+        renderEmpty() {
+            const named = this.named;
+            return html `<div
+        aria-label=${named || nothing}
+        id=${CHART_PLOT}
+        part="plot"
+        role=${named ? 'group' : nothing}
+      >${this.renderStatus()}</div>`;
+        }
+        updated(changed) {
+            super.updated(changed);
+            const root = this.renderRoot;
+            this.toggleState('active', this.pointer.at >= 0);
+            this.toggleState('empty', root.querySelector('[part="empty"]') !== null);
+            this.toggleState('loading', root.querySelector('[part="loading"]') !== null);
+        }
     }
     __decorate([
         words,

package/dist/utils/audit-nesting/audit-nesting-off.d.ts

@@ -0,0 +1,10 @@
+import type { auditNesting as audit } from './audit-nesting.js';
+/**
+ * The unslotted-item warning in a production build: nothing.
+ *
+ * `#audit-nesting` resolves here unless the bundler or runtime asks for the
+ * `development` condition, so a production build carries none of the audit's
+ * code. The signature is the audit's, so a call site reads the same in both
+ * builds. See `audit-nesting.ts`.
+ */
+export declare const auditNesting: typeof audit;

package/dist/utils/audit-nesting/audit-nesting-off.js

@@ -0,0 +1 @@
+export const auditNesting = () => { };

package/dist/utils/audit-nesting/audit-nesting.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Reports an item nested in another item of its own tag without the slot that
+ * nests it, the one mistake that leaves a tree drawing the child as words.
+ *
+ * `<helix-tree-item>src<helix-tree-item>app.ts</helix-tree-item></helix-tree-item>`
+ * puts the inner item in the outer one's default slot, which is its label: the
+ * row reads "src app.ts" and is drawn as a leaf. The item has to carry
+ * `slot="children"`. **Nothing moves it there**, because writing `slot` onto
+ * an element the page rendered is a change to markup a server sent and a
+ * framework owns.
+ *
+ * **In a development build only**, as `missing-name` is: every item would pay
+ * for a sentence meant for the person writing the page. Core imports it as
+ * `#audit-nesting`, which `package.json` resolves here under the `development`
+ * condition and to `audit-nesting-off.ts`, which does nothing, everywhere else.
+ *
+ * `slot` is the name of the slot that nests an item.
+ */
+export declare const auditNesting: (host: HTMLElement, slot: string) => void;

package/dist/utils/audit-nesting/audit-nesting.js

@@ -0,0 +1,19 @@
+import { reportRuntime } from '../report-runtime/report-runtime.js';
+const audited = new WeakSet();
+export const auditNesting = (host, slot) => {
+    if (audited.has(host)) {
+        return;
+    }
+    const stray = [...host.children].find((child) => child.localName === host.localName && !child.hasAttribute('slot'));
+    if (!stray) {
+        return;
+    }
+    audited.add(host);
+    reportRuntime({
+        kind: 'unslotted-item',
+        message: `<${host.localName}> holds a <${stray.localName}> in its default slot, which is its ` +
+            `label, so the inner item is read as words in the row and drawn as no branch. Add ` +
+            `slot="${slot}" to each nested <${stray.localName}>.`,
+        tag: host.localName,
+    });
+};

package/dist/utils/audit-source/audit-source-off.d.ts

@@ -1,4 +1,4 @@
-import type { auditSource as audit } from './audit-source.js';
+import type { auditSource as audit, auditData as auditShape } from './audit-source.js';
 /**
  * The missing-table warning in a production build: nothing.
  *
@@ -8,3 +8,5 @@ import type { auditSource as audit } from './audit-source.js';
  * builds. See `audit-source.ts`.
  */
 export declare const auditSource: typeof audit;
+/** The malformed-data warning in a production build: nothing. */
+export declare const auditData: typeof auditShape;

package/dist/utils/audit-source/audit-source-off.js

@@ -1 +1,2 @@
 export const auditSource = () => { };
+export const auditData = () => { };

package/dist/utils/audit-source/audit-source.d.ts

@@ -17,3 +17,9 @@
 export declare const auditSource: (host: HTMLElement & {
     for: string;
 }, table: () => Element | null) => void;
+/**
+ * Reports a chart whose `data` is not `{ columns, rows }`, such as an array of
+ * rows, once for each chart. The chart draws its empty state. In a development
+ * build only, as the missing-table warning is.
+ */
+export declare const auditData: (host: HTMLElement) => void;

package/dist/utils/audit-source/audit-source.js

@@ -1,5 +1,6 @@
 import { reportRuntime } from '../report-runtime/report-runtime.js';
 const audited = new WeakSet();
+const misshapen = new WeakSet();
 export const auditSource = (host, table) => {
     if (host.for === '' || audited.has(host) || typeof document === 'undefined') {
         return;
@@ -25,3 +26,16 @@ export const auditSource = (host, table) => {
         window.addEventListener('load', read, { once: true });
     }
 };
+export const auditData = (host) => {
+    if (misshapen.has(host)) {
+        return;
+    }
+    misshapen.add(host);
+    reportRuntime({
+        kind: 'malformed-data',
+        message: `<${host.localName}> was given \`data\` that is not { columns, rows }, so it draws nothing. ` +
+            "Pass an object such as { columns: ['Month', 'Sales'], rows: [['Jan', 10]] }, each row " +
+            'an array.',
+        tag: host.localName,
+    });
+};

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

@@ -37,6 +37,12 @@ export interface ChartData {
      */
     rows: ReadonlyArray<readonly [label: string, ...cells: ChartDatum[]]>;
 }
+/**
+ * Whether `data` has the shape a chart reads: an object with an array of
+ * `columns` and an array of `rows`, each row an array. Any other value draws
+ * the empty state, where it would throw from the render.
+ */
+export declare const isChartData: (data: unknown) => data is ChartData;
 /**
  * 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

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

@@ -1,3 +1,11 @@
+export const isChartData = (data) => {
+    const shape = data;
+    return (typeof shape === 'object' &&
+        shape !== null &&
+        Array.isArray(shape.columns) &&
+        Array.isArray(shape.rows) &&
+        shape.rows.every((row) => Array.isArray(row)));
+};
 const cellOf = (datum, locale) => {
     if (datum === null || datum === undefined) {
         return { text: '' };

package/dist/utils/report-runtime/report-runtime.d.ts

@@ -30,6 +30,8 @@ export type RuntimeKind =
  | 'fullscreen-refused'
 /** A rating's `min` is no score between 0 and its `max`. */
  | 'min-out-of-range'
+/** A chart's `data` is not `{ columns, rows }`, so it draws its empty state. Development builds only. */
+ | 'malformed-data'
 /** A Stat was given one of Trend's directions, `up`, `down` or `neutral`, which lay nothing out. */
  | 'misread-direction'
 /** A React handler prop names an event the element never dispatches itself. Development builds only. */
@@ -99,6 +101,11 @@ export type RuntimeKind =
  | 'unscannable-logo'
 /** A virtualized list's box has no height of its own, so its window never settles. */
  | 'unsettled-window'
+/**
+ * An item is nested in another of its tag without the slot that nests it, so it is read as
+ * the label. Development builds only.
+ */
+ | 'unslotted-item'
 /** A native button in a Button Group with `selection-mode`, which cannot be told it is pressed. */
  | 'untold-toggle'
 /** A slotted trigger is a plain element, which cannot be told it opens something. */

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.176.0";
+export declare const VERSION = "0.177.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.176.0';
+export const VERSION = '0.177.0';

package/dist/words/held.d.ts

@@ -0,0 +1,55 @@
+import type { Message, MessageTable } from './message.js';
+/** One locale's words, by tag, then by property. */
+export type Pack = Record<string, Record<string, Message | MessageTable>>;
+/** An element that reads words, perhaps with a `locale`. */
+export type Speaker = Element & {
+    locale?: string | undefined;
+};
+/** What the page has registered, kept on `globalThis`. */
+interface Held {
+    /** Each locale's words, under its lowercase tag. */
+    packs: Map<string, Pack>;
+    /** The locale a server render and a hydrating render speak. */
+    fallback: string;
+    /** What updates the elements that read words. */
+    watchers: Set<() => void>;
+    /** Whether an update is already queued for this task. */
+    queued?: boolean;
+    /** Whether the document's `lang` is watched. */
+    observed?: boolean;
+    /** Finds a registered word for an element, set by the first `registerWords`. */
+    find?: (host: Speaker, tag: string, name: string) => [Message | MessageTable, string] | undefined;
+    /** Reads the locale an element speaks, set where `wordsLocale` is loaded. */
+    locale?: (host: Speaker) => string;
+}
+/**
+ * The page's words, held on `globalThis`.
+ *
+ * **One registry for a page that carries two copies of this module**, one per
+ * bundle that imports it: words registered through one have to reach elements
+ * defined through the other, as the icon registry's glyphs do.
+ *
+ * **What every element reads, and nothing more.** An element with a word
+ * property reads its English until a page registers words, so the lookup and
+ * the locale chain arrive with `registerWords`, which puts its lookup in
+ * `find`, and the locale with `wordsLocale`, which puts itself in `locale`. A
+ * page that registers no words and formats no numbers ships neither: measured
+ * on Button, 474 bytes of its 13,437 compressed.
+ */
+export declare const held: Held;
+/** Asks every element that reads words to look again, once per task. */
+export declare const changed: () => void;
+/** Whether any words are registered, for a read that can skip the lookup. */
+export declare const wordsRegistered: () => boolean;
+/**
+ * Starts watching the document's `lang`, once for the page, in a browser.
+ * Called by what a `lang` change reaches: registered words, and a locale read.
+ */
+export declare const watchLang: () => void;
+/**
+ * Calls `watcher` once in the microtask after words are registered or
+ * cleared, or the document's `lang` changes. Returns the function that stops
+ * it.
+ */
+export declare const watchWords: (watcher: () => void) => (() => void);
+export {};

package/dist/words/held.js

@@ -0,0 +1,29 @@
+export const held = (globalThis[Symbol.for('helix.words')] ??= {
+    fallback: 'en',
+    packs: new Map(),
+    watchers: new Set(),
+});
+export const changed = () => {
+    if (!held.queued) {
+        held.queued = true;
+        queueMicrotask(() => {
+            held.queued = false;
+            for (const watcher of held.watchers) {
+                watcher();
+            }
+        });
+    }
+};
+export const wordsRegistered = () => held.packs.size > 0;
+export const watchLang = () => {
+    if (!held.observed && typeof MutationObserver === 'function' && globalThis.document) {
+        held.observed = true;
+        new MutationObserver(changed).observe(document.documentElement, {
+            attributeFilter: ['lang'],
+        });
+    }
+};
+export const watchWords = (watcher) => {
+    held.watchers.add(watcher);
+    return () => held.watchers.delete(watcher);
+};

package/dist/words/registry.d.ts

@@ -1,4 +1,5 @@
 import type { Message, MessageTable } from './message.js';
+export { watchWords, wordsRegistered } from './held.js';
 /**
  * The words of every family, keyed by the family's styled tag, each with its
  * word properties.
@@ -67,8 +68,6 @@ export declare const refreshWords: () => void;
  * `de-CH` tries `de-ch`, `de-latn-ch`, `de-latn`, `de`, then `en`.
  */
 export declare const localeChain: (locale: string) => string[];
-/** Whether any words are registered, for a read that can skip the lookup. */
-export declare const wordsRegistered: () => boolean;
 /**
  * A registered word for a tag's property in a locale, with the locale it was
  * found in, or `undefined`.
@@ -78,12 +77,3 @@ export declare const wordsRegistered: () => boolean;
  * along the chain, the more specific entry winning.
  */
 export declare const lookupWord: (locale: string, tag: string, name: string) => [Message | MessageTable, string] | undefined;
-/**
- * Calls `watcher` once in the microtask after words are registered or
- * cleared, or the document's `lang` changes. Returns the function that stops
- * it.
- *
- * The first watcher in a browser starts watching the document's `lang`, once
- * for the page.
- */
-export declare const watchWords: (watcher: () => void) => (() => void);

package/dist/words/registry.js

@@ -1,20 +1,9 @@
-const held = (globalThis[Symbol.for('helix.words')] ??= {
-    fallback: 'en',
-    packs: new Map(),
-    watchers: new Set(),
-});
-const changed = () => {
-    if (!held.queued) {
-        held.queued = true;
-        queueMicrotask(() => {
-            held.queued = false;
-            for (const watcher of held.watchers) {
-                watcher();
-            }
-        });
-    }
-};
+import { changed, held, watchLang } from './held.js';
+import { wordsLocale } from './words-locale.js';
+export { watchWords, wordsRegistered } from './held.js';
 export const registerWords = (locale, ...words) => {
+    held.find ??= (host, tag, name) => lookupWord(wordsLocale(host), tag, name);
+    watchLang();
     const key = locale.toLowerCase();
     const pack = held.packs.get(key) ?? {};
     held.packs.set(key, pack);
@@ -74,7 +63,6 @@ export const localeChain = (locale) => {
     chains.set(locale, found);
     return found;
 };
-export const wordsRegistered = () => held.packs.size > 0;
 export const lookupWord = (locale, tag, name) => {
     let found;
     for (const one of localeChain(locale)) {
@@ -89,13 +77,3 @@ export const lookupWord = (locale, tag, name) => {
     }
     return found;
 };
-export const watchWords = (watcher) => {
-    held.watchers.add(watcher);
-    if (!held.observed && typeof MutationObserver === 'function' && globalThis.document) {
-        held.observed = true;
-        new MutationObserver(changed).observe(document.documentElement, {
-            attributeFilter: ['lang'],
-        });
-    }
-    return () => held.watchers.delete(watcher);
-};

package/dist/words/words-locale.js

@@ -1,5 +1,5 @@
 import { localeOf, runtimeLocale } from '../utils/locale-of/locale-of.js';
-import { defaultWordsLocale } from './registry.js';
+import { held, watchLang } from './held.js';
 const checked = new Map();
 const tagOf = (written) => {
     let found = checked.get(written);
@@ -15,15 +15,17 @@ const tagOf = (written) => {
     return found;
 };
 export const wordsLocale = (element) => {
+    watchLang();
     const own = tagOf(element.locale || '');
     if (own) {
         return own;
     }
     if (typeof element.closest !== 'function' || element.hydrating) {
-        return tagOf(element.getAttribute?.('lang') ?? '') || defaultWordsLocale();
+        return tagOf(element.getAttribute?.('lang') ?? '') || held.fallback;
     }
     return localeOf(element) || runtimeLocale();
 };
+held.locale = wordsLocale;
 export const handedLocale = (element) => {
     const own = typeof element.locale === 'string' ? element.locale : '';
     return element.hydrating ? own : localeOf(element, own);

package/dist/words/words.js

@@ -1,5 +1,5 @@
+import { held, watchWords, wordsRegistered } from './held.js';
 import { formatMessage } from './message.js';
-import { lookupWord, watchWords, wordsRegistered } from './registry.js';
 import { wordsLocale } from './words-locale.js';
 const HELD = Symbol();
 const heldBy = (host) => host[HELD] ?? {};
@@ -21,7 +21,7 @@ const resolve = (host, name) => {
     let found = [own, ''];
     if (own == null || table) {
         const registered = wordsRegistered()
-            ? lookupWord(wordsLocale(host), host.constructor.words || host.localName, name)
+            ? held.find?.(host, host.constructor.words || host.localName, name)
             : undefined;
         found = table
             ? [{ ...table, ...registered?.[0], ...own }, '']
@@ -44,10 +44,10 @@ const watcher = (host) => {
     let locale = '';
     return {
         hostConnected: () => {
-            locale = wordsLocale(host);
+            locale = held.locale?.(host) ?? '';
             stop = watchWords(() => {
                 recheck(host);
-                const now = wordsLocale(host);
+                const now = held.locale?.(host) ?? '';
                 if (now !== locale) {
                     locale = now;
                     host.requestUpdate();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.176.0",
+  "version": "0.177.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -23,6 +23,12 @@
       "helix-development": "./dist/utils/audit-name/audit-name.js",
       "default": "./dist/utils/audit-name/audit-name-off.js"
     },
+    "./audits/nesting": {
+      "types": "./dist/utils/audit-nesting/audit-nesting.d.ts",
+      "development": "./dist/utils/audit-nesting/audit-nesting.js",
+      "helix-development": "./dist/utils/audit-nesting/audit-nesting.js",
+      "default": "./dist/utils/audit-nesting/audit-nesting-off.js"
+    },
     "./audits/react": {
       "types": "./dist/helix-element/react-audit.d.ts",
       "development": "./dist/helix-element/react-audit.js",
@@ -62,11 +68,11 @@
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",
-    "@fusion.dev/helix-icons": "0.176.0"
+    "@fusion.dev/helix-icons": "0.177.0"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.176.0",
-    "@fusion.dev/helix-testing": "0.176.0",
+    "@fusion.dev/helix-cem": "0.177.0",
+    "@fusion.dev/helix-testing": "0.177.0",
     "@lit-labs/ssr": "^4.1.0",
     "lit": "^3.2.1"
   },
@@ -77,6 +83,11 @@
       "helix-development": "./src/utils/audit-name/audit-name.ts",
       "default": "./src/utils/audit-name/audit-name-off.ts"
     },
+    "#audit-nesting": {
+      "development": "./src/utils/audit-nesting/audit-nesting.ts",
+      "helix-development": "./src/utils/audit-nesting/audit-nesting.ts",
+      "default": "./src/utils/audit-nesting/audit-nesting-off.ts"
+    },
     "#audit-served": {
       "development": "./src/utils/audit-served/audit-served.ts",
       "helix-development": "./src/utils/audit-served/audit-served.ts",