@fusion.dev/helix-core 0.176.1 → 0.177.1

package/custom-elements.json

@@ -12298,13 +12298,13 @@
             {
               "kind": "method",
               "name": "runPendingUpdate",
-              "privacy": "private",
+              "privacy": "protected",
               "return": {
                 "type": {
                   "text": "void"
                 }
               },
-              "description": "Runs an update that is on its way, so the verdict read next is the one\nfor what the control holds now.\n\n**A control reports its verdict as it updates, and an update waits for a\nmicrotask**, so a script that wrote `value` and asked at once was answered\nabout the value before: measured on Time Input, `value = '18:00'` past a\n`max` of 17:00 and `checkValidity()` returned true until `updateComplete`.\nA native control answers about the value it was just given, so the\nquestions a script can ask run the pending update first. Lit's\n`performUpdate` is the documented way to run one synchronously."
+              "description": "Runs an update that is on its way, so the verdict read next is the one\nfor what the control holds now.\n\n**A control reports its verdict as it updates, and an update waits for a\nmicrotask**, so a script that wrote `value` and asked at once was answered\nabout the value before: measured on Time Input, `value = '18:00'` past a\n`max` of 17:00 and `checkValidity()` returned true until `updateComplete`.\nA native control answers about the value it was just given, so the\nquestions a script can ask run the pending update first. Lit's\n`performUpdate` is the documented way to run one synchronously.\n\nProtected for a control that submits on its own, which has to hand the\nform the verdict for what it holds now: Pin Input's `autosubmit`."
             },
             {
               "kind": "field",
@@ -12415,6 +12415,24 @@
               "privacy": "private",
               "description": "Stops listening for the labels in this control's tree."
             },
+            {
+              "kind": "method",
+              "name": "formAssociatedCallback",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "form",
+                  "type": {
+                    "text": "HTMLFormElement | null"
+                  }
+                }
+              ],
+              "description": "Called by the browser when the control's form changes: watches the new\nform's `checkValidity()`, as connecting does for the form it starts in."
+            },
             {
               "kind": "field",
               "name": "form",
@@ -12842,6 +12860,14 @@
             "package": "#audit-name"
           }
         },
+        {
+          "kind": "js",
+          "name": "auditNesting",
+          "declaration": {
+            "name": "auditNesting",
+            "package": "#audit-nesting"
+          }
+        },
         {
           "kind": "js",
           "name": "auditServed",
@@ -18135,6 +18161,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 +18208,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 +18260,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 +18278,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 +18367,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 +18538,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 +18615,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": [
@@ -21057,6 +21062,17 @@
               "privacy": "protected",
               "readonly": true,
               "description": "A press that focuses the field opens the picker.\n\nA reader who presses into this control is choosing, and making them find\nthe trigger afterwards is a second action for something they have already\nasked for. Typing still works with it up, because the picker follows the\nfield rather than the other way round. Focus by Tab or by `focus()` opens\nnothing: see the mixin's note.\n\n**Only where focus arrived from outside this element**, which is the whole\nof the difficulty: picking shuts the panel and puts the caret back in the\nfield, so an unguarded version reopens the picker the reader just\nanswered. `relatedTarget` is where focus came from, so a hand-off from the\npicker or the trigger is left alone and only a genuine arrival opens\nanything. `returning` covers the hand-off `relatedTarget` cannot see, and\n`MixinPickerField` says why.\n\nOn the input rather than on the field, too. Focus does not bubble, so a\nlistener there covers the text and not the trigger, which is what keeps\npressing the trigger from opening the panel on focus and then shutting it\nagain on the click."
+            },
+            {
+              "kind": "method",
+              "name": "selectOnArrival",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Selects the text a reader tabbed into, once the field shows it for\nediting, as Tab into a native `<input>` holding text selects all of it,\nfrom either side. Not when this element hands the caret back itself.\n\n**After the update**, because focus is what turns editing on, and the\ntext the field then writes put the caret at its end. Measured in\nChromium before this: Tab into a Time Input holding `14:30` left the\nselection at 5 to 5, and typing `9am` gave `14:309am`. A press keeps\nits caret where the pointer put it."
             }
           ],
           "attributes": [
@@ -24659,6 +24675,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 +24826,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 +24844,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 +24882,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 +24910,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 +30035,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 +30099,14 @@
         }
       ],
       "exports": [
+        {
+          "kind": "js",
+          "name": "isChartData",
+          "declaration": {
+            "name": "isChartData",
+            "module": "src/utils/read-data/read-data.ts"
+          }
+        },
         {
           "kind": "js",
           "name": "seriesFromData",
@@ -33810,7 +33958,7 @@
           "type": {
             "text": "string"
           },
-          "default": "'0.176.1'",
+          "default": "'0.177.1'",
           "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."
         }
       ],
@@ -34446,6 +34594,6 @@
   ],
   "helix": {
     "package": "@fusion.dev/helix-core",
-    "version": "0.176.1"
+    "version": "0.177.1"
   }
 }

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/helix-form-element/helix-form-element.d.ts

@@ -228,8 +228,11 @@ export declare class HelixFormElement extends HelixElement {
      * A native control answers about the value it was just given, so the
      * questions a script can ask run the pending update first. Lit's
      * `performUpdate` is the documented way to run one synchronously.
+     *
+     * Protected for a control that submits on its own, which has to hand the
+     * form the verdict for what it holds now: Pin Input's `autosubmit`.
      */
-    private runPendingUpdate;
+    protected runPendingUpdate(): void;
     /** Whether the control is checked when its form is submitted. */
     get willValidate(): boolean;
     /**
@@ -246,8 +249,10 @@ export declare class HelixFormElement extends HelixElement {
      * required `<input>` checked from a script fires `invalid` and does not match
      * `:user-invalid`, measured in Chromium. Every layer that takes `invalid` as
      * a reader's attempt asks this first, so a script that checks an untouched
-     * field does not mark it wrong. A submission, `reportValidity()`, and the
-     * reader's own edits still do.
+     * field does not mark it wrong. The same holds for `form.checkValidity()`,
+     * which fires `invalid` on every control in the form and marks no native
+     * one. A submission, `reportValidity()`, and the reader's own edits still
+     * mark it.
      */
     protected get checkingValidity(): boolean;
     /**
@@ -290,6 +295,11 @@ export declare class HelixFormElement extends HelixElement {
     private unwatchLabels;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /**
+     * Called by the browser when the control's form changes: watches the new
+     * form's `checkValidity()`, as connecting does for the form it starts in.
+     */
+    formAssociatedCallback(form: HTMLFormElement | null): void;
     /**
      * @internal Whether this control is a field that counts against implicit
      * submission: a single line of text, as `<input type="text">` is. Read by

package/dist/helix-form-element/helix-form-element.js

@@ -41,6 +41,24 @@ const firstTabStop = (node) => {
     }
     return null;
 };
+let formChecks = 0;
+const watchedForms = new WeakSet();
+const watchFormChecks = (form) => {
+    if (!form || watchedForms.has(form)) {
+        return;
+    }
+    watchedForms.add(form);
+    const check = form.checkValidity;
+    form.checkValidity = function checkValidity() {
+        formChecks += 1;
+        try {
+            return check.call(this);
+        }
+        finally {
+            formChecks -= 1;
+        }
+    };
+};
 export class HelixFormElement extends HelixElement {
     static { this.formAssociated = true; }
     get isDisabled() {
@@ -172,7 +190,7 @@ export class HelixFormElement extends HelixElement {
         }
     }
     get checkingValidity() {
-        return this.checkInProgress;
+        return this.checkInProgress || formChecks > 0;
     }
     reportValidity() {
         this.runPendingUpdate();
@@ -198,6 +216,7 @@ export class HelixFormElement extends HelixElement {
     }
     connectedCallback() {
         super.connectedCallback();
+        watchFormChecks(this.internals.form);
         this.addEventListener('click', this.focusFromLabel);
         this.addEventListener('invalid', this.refreshAnchor);
         this.unwatchLabels = watchLabels(this, () => this.requestUpdate());
@@ -209,6 +228,9 @@ export class HelixFormElement extends HelixElement {
         this.unwatchLabels?.();
         this.unwatchLabels = undefined;
     }
+    formAssociatedCallback(form) {
+        watchFormChecks(form);
+    }
     get blocksImplicitSubmission() {
         return false;
     }

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/mixins/mixin-picker-editing/mixin-picker-editing.js

@@ -55,10 +55,11 @@ export const MixinPickerEditing = (Base) => {
                 const pressed = this.pressing;
                 this.pressing = false;
                 const from = event.relatedTarget;
-                if (!pressed || this.open || this.isDisabled || this.returning) {
-                    return;
+                const inside = from instanceof Node && Boolean(this.renderRoot?.contains?.(from));
+                if (!pressed && !this.returning) {
+                    this.selectOnArrival();
                 }
-                if (from instanceof Node && this.renderRoot?.contains?.(from)) {
+                if (!pressed || this.open || this.isDisabled || this.returning || inside) {
                     return;
                 }
                 this.requestOpen(true);
@@ -90,6 +91,15 @@ export const MixinPickerEditing = (Base) => {
             this.removeEventListener('click', this.handlePress);
             this.removeEventListener('keydown', this.handleEditKey);
         }
+        selectOnArrival() {
+            void this.updateComplete.then(() => {
+                const control = this.control;
+                const root = this.renderRoot;
+                if (control && root?.activeElement === control) {
+                    control.select();
+                }
+            });
+        }
     }
     __decorate([
         property({ attribute: 'readonly', reflect: true, type: Boolean })

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/number-format/number-format.js

@@ -32,8 +32,9 @@ export const parseNumber = (text, locale = '', options) => {
     const parts = format.formatToParts(-12345.6);
     const one = format.formatToParts(1);
     const of = (type, from = parts) => from.filter((part) => part.type === type).map((part) => part.value);
-    const group = of('group')[0] ?? ',';
-    const decimal = of('decimal')[0] ?? '.';
+    const plain = formatter(locale, undefined).formatToParts(-12345.6);
+    const group = of('group')[0] ?? of('group', plain)[0] ?? ',';
+    const decimal = of('decimal')[0] ?? of('decimal', plain)[0] ?? '.';
     const named = (from) => [
         ...of('currency', from),
         ...of('percentSign', from),

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

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.176.1';
+export const VERSION = '0.177.1';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.176.1",
+  "version": "0.177.1",
   "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.1"
+    "@fusion.dev/helix-icons": "0.177.1"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.176.1",
-    "@fusion.dev/helix-testing": "0.176.1",
+    "@fusion.dev/helix-cem": "0.177.1",
+    "@fusion.dev/helix-testing": "0.177.1",
     "@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",