@fusion.dev/helix-core 0.52.1 → 0.53.0

package/custom-elements.json

@@ -5235,6 +5235,22 @@
             "module": "./mixins/mixin-chart-source/mixin-chart-source.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "PLOT_HEIGHT",
+          "declaration": {
+            "name": "PLOT_HEIGHT",
+            "module": "./mixins/mixin-chart-source/mixin-chart-source.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "PLOT_WIDTH",
+          "declaration": {
+            "name": "PLOT_WIDTH",
+            "module": "./mixins/mixin-chart-source/mixin-chart-source.js"
+          }
+        },
         {
           "kind": "js",
           "name": "seriesIndex",
@@ -5395,6 +5411,22 @@
             "module": "./mixins/mixin-picker-field/mixin-picker-field.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "MixinSelectableItem",
+          "declaration": {
+            "name": "MixinSelectableItem",
+            "module": "./mixins/mixin-selectable-item/mixin-selectable-item.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "MixinSelectableItemInterface",
+          "declaration": {
+            "name": "MixinSelectableItemInterface",
+            "module": "./mixins/mixin-selectable-item/mixin-selectable-item.js"
+          }
+        },
         {
           "kind": "js",
           "name": "MixinTokens",
@@ -5611,6 +5643,22 @@
             "module": "./utils/line-path/line-path.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "markRegion",
+          "declaration": {
+            "name": "markRegion",
+            "module": "./utils/mark-region/mark-region.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "RegionOptions",
+          "declaration": {
+            "name": "RegionOptions",
+            "module": "./utils/mark-region/mark-region.js"
+          }
+        },
         {
           "kind": "js",
           "name": "onUnlessFalse",
@@ -5882,6 +5930,14 @@
             "name": "valueAsTime",
             "module": "./utils/value-as/value-as.js"
           }
+        },
+        {
+          "kind": "js",
+          "name": "writtenList",
+          "declaration": {
+            "name": "writtenList",
+            "module": "./utils/written-list/written-list.js"
+          }
         }
       ]
     },
@@ -5916,6 +5972,24 @@
           ],
           "description": "The palette slot for the nth series, counting from one and wrapping."
         },
+        {
+          "kind": "variable",
+          "name": "PLOT_WIDTH",
+          "type": {
+            "text": "number"
+          },
+          "default": "100",
+          "description": "The drawing's own coordinates, which a `viewBox` maps onto whatever box CSS\ngives it.\n\nHere for the reason `PALETTE` is here, one paragraph up: six families drew\ninto the same square and declared it six times under three names, and one of\nthem wrote the same number as a literal on one axis and as its own constant\non the other, in one attribute. A round hundred so a `d` attribute is\nreadable in the inspector.\n\n**Two names for one number, because the axes are two facts.** `x2=${PLOT_WIDTH}`\nand `y2=${PLOT_HEIGHT}` say which edge they reach; one name used twice says\nnothing, and the day a chart is not square the call sites are already right.\n`Sparkline` is that day already: it is a strip rather than a plot, so it takes\nthis width and states its own height beside it."
+        },
+        {
+          "kind": "variable",
+          "name": "PLOT_HEIGHT",
+          "type": {
+            "text": "number"
+          },
+          "default": "100",
+          "description": "The drawing's own coordinates. See `PLOT_WIDTH`."
+        },
         {
           "kind": "function",
           "name": "seriesNames",
@@ -5932,7 +6006,7 @@
               }
             }
           ],
-          "description": "A list of series names, as the attributes that take one are written.\n\n**Here because five properties across two tiers read the same list and two of\nthem read it differently.** `BarChart.lines` and `secondary` split on\nwhitespace; `outlined`, `subtle` and `glass` on the styled tier split on\nwhitespace or a comma, under a sentence saying the first three are matched\n\"the way `lines` and `secondary` are\". So `lines=\"Gateway, Billing\"` looked\nexactly like `outlined=\"Gateway, Billing\"` and matched nothing, because\n`gateway,` is not a column heading: no column drawn as a line, no error, and\nnothing to read off the page that says why. That is the undebuggable case\n`gridlines` names in its own docblock, arrived at from the other direction.\n\nA comma is accepted rather than refused because a reader writing a list of\nwords puts commas between them, and the widest of the spellings already\nshipped. Lowercased and trimmed, since the headings are matched\ncase-insensitively."
+          "description": "A list of series names, as the attributes that take one are written.\n\n**Here because five properties across two tiers read the same list and two of\nthem read it differently.** `BarChart.lines` and `secondary` split on\nwhitespace; `outlined`, `subtle` and `glass` on the styled tier split on\nwhitespace or a comma, under a sentence saying the first three are matched\n\"the way `lines` and `secondary` are\". So `lines=\"Gateway, Billing\"` looked\nexactly like `outlined=\"Gateway, Billing\"` and matched nothing, because\n`gateway,` is not a column heading: no column drawn as a line, no error, and\nnothing to read off the page that says why.\n\n`writtenList` is the split, and carries the argument for accepting a comma.\nWhat this adds is the lowercase, the headings being matched\ncase-insensitively."
         },
         {
           "kind": "class",
@@ -6282,6 +6356,22 @@
             "module": "src/mixins/mixin-chart-source/mixin-chart-source.ts"
           }
         },
+        {
+          "kind": "js",
+          "name": "PLOT_WIDTH",
+          "declaration": {
+            "name": "PLOT_WIDTH",
+            "module": "src/mixins/mixin-chart-source/mixin-chart-source.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "PLOT_HEIGHT",
+          "declaration": {
+            "name": "PLOT_HEIGHT",
+            "module": "src/mixins/mixin-chart-source/mixin-chart-source.ts"
+          }
+        },
         {
           "kind": "js",
           "name": "seriesNames",
@@ -7574,6 +7664,15 @@
           "description": "The public surface `MixinField` adds.\n\nDeclared separately because TypeScript cannot emit declarations for an\nanonymous class that has private members (TS4094). Casting the mixin's return\nto this interface keeps the internals private and the build working.",
           "name": "MixinFieldInterface",
           "members": [
+            {
+              "kind": "field",
+              "name": "controlId",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "protected",
+              "description": "Id the field's label points at, written by the control this wraps.\n\nThe third fixed id and the only one this mixin does not render, the\ncontrol being the family's. See the note on the class member."
+            },
             {
               "kind": "field",
               "name": "hint",
@@ -7729,6 +7828,16 @@
           "description": "Grafts a label, help text, and a validation message onto a control.\n\n**Over `HelixElement` rather than `HelixFormElement`, because not every\ncontrol that wants a label is form-associated.** A checkbox group is the\ncase: each box in it submits itself already, so the group deliberately\nreports no value of its own, and every form-related member of\n`ElementInternals` throws `NotSupportedError` on an element that is not\nform-associated. Measured, and the ARIA members are fine on the same\nelement, which is why the naming and describing work there and only the\nvalidity has to ask first.\n\nEvery form control wants the same three things around it and wants them in a\ndifferent arrangement: a label above an input, beside a checkbox, and over a\ngroup. So this owns the properties, the parts, and the wiring, and each\ncontrol places the nodes where its own geometry needs them. Same part names\neither way, so one stylesheet in the styled tier dresses all of them.\n\n**Not a wrapping `Field` component, and that is not a style preference.** A\nwrapper cannot name what it wraps. Its label would live in its own shadow\nroot and the control in another, and measured in Chrome 148: an\n`aria-labelledby` IDREF cannot see across, and\n`control.ariaLabelledByElements = [labelInTheWrapper]` reads back as zero\nelements, the reference dropped. The same assignment with a label in the\ncontrol's own tree is kept. That pattern works in React libraries because\nthey have no shadow boundary; bringing it here brings the ergonomics and none\nof the conditions that made it work.\n\n**A control whose label is its content renders its own.** A checkbox is named\nby the words beside it, inside the `<label>` that forwards the press, so it\nuses its default slot and nesting `renderLabel`'s `<label>` in there would be\ninvalid markup. `label` is that slot's fallback either way.\n\nWorth knowing, because it costs a label and gives no warning: **a\nwhitespace-only text node is assigned to the default slot and defeats its\nfallback.** Measured in Chrome 148, and a newline between the tags is enough,\nso `<helix-checkbox label=\"Accept\">` closed on the next line renders no label\nat all. A named slot does not have this problem, because `slot=\"label\"` is an\nattribute and a text node has none. It is the platform's behavior rather\nthan ours, and the same is already true of every slot fallback here.\n\n**The ids are fixed rather than generated.** IDREFs resolve within the tree\nthat holds them, so two controls on a page each carrying `helix-hint` in\ntheir own shadow root do not collide. That also removes the usual hydration\nhazard, since there is no generated value for a server and a client to\ndisagree about.\n\n**A group has to say it differently.** A control's `<input>` and its hint\nare both in the shadow root, so a plain `aria-describedby` resolves. A\ngroup's host is in the light DOM and its hint is not, so the IDREF cannot\nreach and `element.ariaDescribedByElements` drops the reference. Only\n`internals.ariaDescribedByElements` keeps it, which is what `describeHost`\nuses. Measured the same way, and the failure is silent either way: the\ndescription simply never reaches the accessibility tree.\n\n**The label, the hint and the feedback are documented on each component that\napplies this, rather than here.** Declaring them once on this mixin is the\nobvious fix and does not work: the analyzer reads `@csspart` off a custom\nelement class, so a class-level tag here reaches the manifest as nothing at\nall, on this JSDoc and on the inner class alike. Measured both ways, and the\ninner-class version is the dangerous one, since it satisfies the rule while\nevery API page stays exactly as wrong as before. Members are different and\ndo inherit, which is what the note about the inner class in the area rules\nis about. `:state(invalid)` is listed the same way, as a `@cssstate` on each\ncomponent, for the same reason.",
           "name": "MixinField",
           "members": [
+            {
+              "kind": "field",
+              "name": "controlId",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "protected",
+              "default": "'control'",
+              "description": "Id the field's label points at, written by the control this wraps.\n\n`renderLabel` emits the `for` and the family renders the `id`, so the\ntwo ends of one IDREF sat in two packages as a pair of literals with\nnothing holding them together: eleven templates wrote `id=\"control\"`,\ntwo wrote a second `for=\"control\"` of their own, and a family that\nspelled either differently got a `<label for>` resolving to nothing.\nThat failure is silent in the way the area rules describe for a\n`[part=]` naming a part nobody renders: no error, no warning, and a\nlabel that has stopped focusing its field.\n\nA member rather than a module constant, which is what the anchor\nargument for `reportRequired` already settled one level down: the name\nbelongs to the control the family renders, so the family has to be able\nto read it, and `HINT_ID` and `FEEDBACK_ID` stay private because this\nmixin renders both of those itself."
+            },
             {
               "kind": "field",
               "name": "feedback",
@@ -8456,6 +8565,196 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/mixins/mixin-selectable-item/mixin-selectable-item.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "The public surface `MixinSelectableItem` adds.\n\nDeclared separately because TypeScript cannot emit declarations for an\nanonymous class that has private members (TS4094). Casting the mixin's return\nto this interface keeps the internals private and the build working.",
+          "name": "MixinSelectableItemInterface",
+          "members": [
+            {
+              "kind": "field",
+              "name": "disabled",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Whether this one can be chosen."
+            },
+            {
+              "kind": "method",
+              "name": "focusItem",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Moves focus to the control this renders, for the set's arrow keys."
+            },
+            {
+              "kind": "field",
+              "name": "itemPart",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "protected",
+              "description": "The part `focusItem` focuses, which each family names for itself.\n\nParameterised for the reason `MixinField`'s `reportRequired` takes its\nanchor as an argument: the control is the family's to render, so a literal\nhere would be a lookup for a part this file does not write."
+            },
+            {
+              "kind": "method",
+              "name": "select",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "description": "Chooses this one and announces it, and reports whether the request stood.\n\n`MixinDismissible.dismiss` next door has the same shape and for the same\nreason: a mixin has no family, so the answer to a cancelable event it\ndispatches is read at the dispatch or nowhere. The set acting on the choice\noffers the second refusal on its own root."
+            },
+            {
+              "kind": "field",
+              "name": "selected",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Whether this is the current one. Written by the set."
+            },
+            {
+              "kind": "field",
+              "name": "value",
+              "type": {
+                "text": "string"
+              },
+              "description": "Identifies this one to the set, and is what a form submits."
+            }
+          ],
+          "helix": {}
+        },
+        {
+          "kind": "mixin",
+          "description": "The item half of a set: what is chosen, and what the arrow keys move over.\n\n**This is `KeyboardNavigationController.NavigableItem`, implemented.** That\ninterface has declared the contract since the controller was written and\nnothing implemented it, so every family that took the controller wrote the\nsame five members out again: Radio and Toggle were byte-identical down to the\nfourteen-line note on `willUpdate`, and Tab differed in one part name. A\ncontract with no implementation is a contract each caller reinvents, and the\nreinventions drift: the mirror is the half that must not, because a stylesheet\nselects on it.\n\n**The render stays with the family and only the part name comes here.** These\nelements are a radio, a switch and a tab, and what goes inside the control is\nthe whole of what makes them different. `itemPart` is the one thing the mixin\nhas to know, because focusing is the one thing it does to the render.\n\n**What is deliberately not here.** `defaultSelected` belongs to the families\nwhose selection a consumer declares in markup, and `focusable` to the ones\nwhose set has a tab stop to park while nothing is chosen. Neither is true of\nevery item in the library, and a mixin that granted them would publish a\nproperty on a reference page for a fact the family has no answer to. The\nitems whose current one is wherever focus happens to be (`Menu.Item`,\n`Drilldown.Item`, `SpeedDial.Item`) are the other kind again: their `selected`\nis a getter over `activeElement` rather than a property a parent writes, so\nthey satisfy the same interface by a different route and take nothing from\nhere.",
+          "name": "MixinSelectableItem",
+          "members": [
+            {
+              "kind": "field",
+              "name": "disabled",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether this one can be chosen.",
+              "attribute": "disabled",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "selected",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether this is the current one.\n\nWritten by the set rather than by a consumer, which is why it takes no\ndefault from an attribute here: a family whose selection a consumer\ndeclares in markup carries `defaultSelected` of its own to say so.",
+              "attribute": "selected"
+            },
+            {
+              "kind": "field",
+              "name": "value",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "Identifies this one to the set, and is what a form submits.",
+              "attribute": "value"
+            },
+            {
+              "kind": "field",
+              "name": "itemPart",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "protected",
+              "default": "'item'",
+              "description": "The part `focusItem` focuses. See the interface note."
+            },
+            {
+              "kind": "method",
+              "name": "focusItem",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Moves focus to the control this renders, for the set's arrow keys.\n\nThe set drives the keys and cannot reach the control itself, which is\ninside this shadow root, so the intent is a method and the internals stay\nthe item's."
+            },
+            {
+              "kind": "method",
+              "name": "select",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "description": "Chooses this one and announces it, and reports whether it stood."
+            }
+          ],
+          "attributes": [
+            {
+              "name": "disabled",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether this one can be chosen.",
+              "fieldName": "disabled"
+            },
+            {
+              "name": "selected",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether this is the current one.\n\nWritten by the set rather than by a consumer, which is why it takes no\ndefault from an attribute here: a family whose selection a consumer\ndeclares in markup carries `defaultSelected` of its own to say so.",
+              "fieldName": "selected"
+            },
+            {
+              "name": "value",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "Identifies this one to the set, and is what a form submits.",
+              "fieldName": "value"
+            }
+          ],
+          "parameters": [
+            {
+              "name": "Base",
+              "type": {
+                "text": "T"
+              }
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "MixinSelectableItemInterface",
+          "declaration": {
+            "name": "MixinSelectableItemInterface",
+            "module": "src/mixins/mixin-selectable-item/mixin-selectable-item.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "MixinSelectableItem",
+          "declaration": {
+            "name": "MixinSelectableItem",
+            "module": "src/mixins/mixin-selectable-item/mixin-selectable-item.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/mixins/mixin-tokens/mixin-tokens.ts",
@@ -9505,6 +9804,59 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/utils/mark-region/mark-region.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "markRegion",
+          "return": {
+            "type": {
+              "text": "void"
+            }
+          },
+          "parameters": [
+            {
+              "name": "root",
+              "type": {
+                "text": "ParentNode | null | undefined"
+              }
+            },
+            {
+              "name": "part",
+              "type": {
+                "text": "string"
+              }
+            },
+            {
+              "name": "slots",
+              "type": {
+                "text": "readonly string[]"
+              }
+            },
+            {
+              "name": "options",
+              "default": "{}",
+              "type": {
+                "text": "RegionOptions"
+              }
+            }
+          ],
+          "description": "Says on a rendered region whether anything is in it.\n\nNine families ask one question of a slot and write the same two attributes on\nthe box around it, and three of them carried this method byte for byte. What\ndiffers between them is the region's name, which slots count toward it, and\nwhether the component draws into the region itself, so those are the\narguments and nothing else is. `slotFilled` beside this is the half that\nanswers whether there is anything there, and carries the reason no selector\ncan.\n\n**The empty string names the default slot**, and it resolves to\n`slot:not([name])` rather than to a bare `slot`, which matches whichever slot\ncomes first in the shadow root and is the right answer only while a component\nhas one.\n\nOn the region inside the shadow root rather than on the host: an attribute\nwritten onto the host is a change to markup the consumer rendered, which\nReact reports on hydration and does not patch up."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "markRegion",
+          "declaration": {
+            "name": "markRegion",
+            "module": "src/utils/mark-region/mark-region.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/utils/on-unless-false/on-unless-false.ts",
@@ -10260,6 +10612,40 @@
           }
         }
       ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/utils/written-list/written-list.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "writtenList",
+          "return": {
+            "type": {
+              "text": "string[]"
+            }
+          },
+          "parameters": [
+            {
+              "name": "source",
+              "type": {
+                "text": "string | undefined"
+              }
+            }
+          ],
+          "description": "A list a consumer wrote into an attribute, split the way they write one.\n\n**Whitespace or commas, because a reader listing words puts commas between\nthem.** A split on whitespace alone turns `extra-controls=\"speed, pip\"` into\n`speed,` and `pip`, and `speed,` is not a control name: the control is\ndropped, nothing is logged, and the docblock on the property says\nunrecognized values are skipped, so the behavior looks like the documented\none. That is the undebuggable case `gridlines` names in its own docblock,\narrived at from the other direction, and it is why the widest spelling is the\none every consumer-written list takes.\n\n**Not for a value.** A payload is comma separated and nothing else, because a\nvalue may hold a space: splitting `value=\"New York,Paris\"` on whitespace\nwould submit a city that does not exist. Select, Listbox, Combobox and\nCheckbox Group each split their own value on a comma and trim, which is the\nother rule and not a lesser version of this one.\n\n**Nor for an IDREF list**, which is the platform's own format: `aria-*` and\n`for` take whitespace and only whitespace, and accepting a comma there would\nresolve an id nobody can write."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "writtenList",
+          "declaration": {
+            "name": "writtenList",
+            "module": "src/utils/written-list/written-list.ts"
+          }
+        }
+      ]
     }
   ]
 }

package/dist/index.d.ts

@@ -17,7 +17,7 @@ export { eventsForTag, registerElementEvents } from './events/element-events.js'
 export { type CaretDetail, type ChangeDetail, type CompleteDetail, type ConsoleDetail, type CopyDetail, type CreateDetail, type DismissDetail, type FacetDetail, type FilterDetail, HelixActivateEvent, HelixBeforeActivateEvent, HelixBeforeChangeEvent, HelixBeforeCloseEvent, HelixBeforeCollapseEvent, HelixBeforeEditEvent, HelixBeforeOpenEvent, HelixBeforePanelResizeEvent, HelixBeforePinEvent, HelixBeforeResizeEvent, HelixBeforeSplitEvent, HelixBeforeToggleEvent, HelixCaretEvent, HelixCompleteEvent, HelixConsoleEvent, HelixCopyEvent, HelixCreateEvent, HelixDismissEvent, HelixFacetEvent, HelixFilterEvent, HelixHistoryEvent, HelixNavigateEvent, HelixNextEvent, HelixPreviousEvent, HelixReadEvent, HelixReorderEvent, HelixResizeEvent, HelixSampleEndEvent, HelixSampleStartEvent, HelixScrolledEvent, HelixSelectEvent, HelixSendEvent, HelixShortcutEvent, HelixSortEvent, HelixTourAskEvent, type NavigateDetail, type OpenDetail, type ReadDetail, type ResizeDetail, type ScrolledDetail, type SelectDetail, type SendDetail, type ShortcutDetail, type SkipDetail, type SortDetail, type ToggleDetail, } from './events/events.js';
 export { HelixElement, whenHydrated } from './helix-element/helix-element.js';
 export { HelixFormElement } from './helix-form-element/helix-form-element.js';
-export { MixinChartSource, type MixinChartSourceInterface, PALETTE, seriesIndex, seriesNames, } from './mixins/mixin-chart-source/mixin-chart-source.js';
+export { MixinChartSource, type MixinChartSourceInterface, PALETTE, PLOT_HEIGHT, PLOT_WIDTH, seriesIndex, seriesNames, } from './mixins/mixin-chart-source/mixin-chart-source.js';
 export { type CollectionElement, MixinCollection, } from './mixins/mixin-collection/mixin-collection.js';
 export { MixinControllerActive, type MixinControllerActiveInterface, } from './mixins/mixin-controller-active/mixin-controller-active.js';
 export { MixinControllerChecked, type MixinControllerCheckedInterface, } from './mixins/mixin-controller-checked/mixin-controller-checked.js';
@@ -27,6 +27,7 @@ export { type DismissibleElement, MixinDismissible, } from './mixins/mixin-dismi
 export { MixinField, type MixinFieldInterface } from './mixins/mixin-field/mixin-field.js';
 export { MixinPickerEditing, type MixinPickerEditingInterface, } from './mixins/mixin-picker-editing/mixin-picker-editing.js';
 export { MixinPickerField, type MixinPickerFieldInterface, } from './mixins/mixin-picker-field/mixin-picker-field.js';
+export { MixinSelectableItem, type MixinSelectableItemInterface, } from './mixins/mixin-selectable-item/mixin-selectable-item.js';
 export { MixinTokens, type MixinTokensInterface } from './mixins/mixin-tokens/mixin-tokens.js';
 export { anchorElement } from './utils/anchor-element/anchor-element.js';
 export { capturePointer } from './utils/capture-pointer/capture-pointer.js';
@@ -42,6 +43,7 @@ export { type HostAria, hostAria } from './utils/host-aria/host-aria.js';
 export { type DisableableItem, forgetDisabled, inheritDisabled, } from './utils/inherit-disabled/inherit-disabled.js';
 export { inlineStep } from './utils/inline-step/inline-step.js';
 export { type Curve, linePath, type Point } from './utils/line-path/line-path.js';
+export { markRegion, type RegionOptions } from './utils/mark-region/mark-region.js';
 export { onUnlessFalse } from './utils/on-unless-false/on-unless-false.js';
 export { type Row, type RowCell, readRows, readSeries, type Series, type SeriesPoint, } from './utils/read-series/read-series.js';
 export { type Relative, relativeTime, } from './utils/relative-time/relative-time.js';
@@ -56,3 +58,4 @@ export { tellDisclosure } from './utils/tell-disclosure/tell-disclosure.js';
 export { subscribe } from './utils/ticker/ticker.js';
 export { type HelixStatusTone, TONE_MARKS, type ToneMark, toneMark, } from './utils/tone-marks/tone-marks.js';
 export { dateAsValue, numberAsValue, timeAsValue, valueAsDate, valueAsNumber, valueAsTime, } from './utils/value-as/value-as.js';
+export { writtenList } from './utils/written-list/written-list.js';

package/dist/index.js

@@ -17,7 +17,7 @@ export { eventsForTag, registerElementEvents } from './events/element-events.js'
 export { HelixActivateEvent, HelixBeforeActivateEvent, HelixBeforeChangeEvent, HelixBeforeCloseEvent, HelixBeforeCollapseEvent, HelixBeforeEditEvent, HelixBeforeOpenEvent, HelixBeforePanelResizeEvent, HelixBeforePinEvent, HelixBeforeResizeEvent, HelixBeforeSplitEvent, HelixBeforeToggleEvent, HelixCaretEvent, HelixCompleteEvent, HelixConsoleEvent, HelixCopyEvent, HelixCreateEvent, HelixDismissEvent, HelixFacetEvent, HelixFilterEvent, HelixHistoryEvent, HelixNavigateEvent, HelixNextEvent, HelixPreviousEvent, HelixReadEvent, HelixReorderEvent, HelixResizeEvent, HelixSampleEndEvent, HelixSampleStartEvent, HelixScrolledEvent, HelixSelectEvent, HelixSendEvent, HelixShortcutEvent, HelixSortEvent, HelixTourAskEvent, } from './events/events.js';
 export { HelixElement, whenHydrated } from './helix-element/helix-element.js';
 export { HelixFormElement } from './helix-form-element/helix-form-element.js';
-export { MixinChartSource, PALETTE, seriesIndex, seriesNames, } from './mixins/mixin-chart-source/mixin-chart-source.js';
+export { MixinChartSource, PALETTE, PLOT_HEIGHT, PLOT_WIDTH, seriesIndex, seriesNames, } from './mixins/mixin-chart-source/mixin-chart-source.js';
 export { MixinCollection, } from './mixins/mixin-collection/mixin-collection.js';
 export { MixinControllerActive, } from './mixins/mixin-controller-active/mixin-controller-active.js';
 export { MixinControllerChecked, } from './mixins/mixin-controller-checked/mixin-controller-checked.js';
@@ -27,6 +27,7 @@ export { MixinDismissible, } from './mixins/mixin-dismissible/mixin-dismissible.
 export { MixinField } from './mixins/mixin-field/mixin-field.js';
 export { MixinPickerEditing, } from './mixins/mixin-picker-editing/mixin-picker-editing.js';
 export { MixinPickerField, } from './mixins/mixin-picker-field/mixin-picker-field.js';
+export { MixinSelectableItem, } from './mixins/mixin-selectable-item/mixin-selectable-item.js';
 export { MixinTokens } from './mixins/mixin-tokens/mixin-tokens.js';
 export { anchorElement } from './utils/anchor-element/anchor-element.js';
 export { capturePointer } from './utils/capture-pointer/capture-pointer.js';
@@ -42,6 +43,7 @@ export { hostAria } from './utils/host-aria/host-aria.js';
 export { forgetDisabled, inheritDisabled, } from './utils/inherit-disabled/inherit-disabled.js';
 export { inlineStep } from './utils/inline-step/inline-step.js';
 export { linePath } from './utils/line-path/line-path.js';
+export { markRegion } from './utils/mark-region/mark-region.js';
 export { onUnlessFalse } from './utils/on-unless-false/on-unless-false.js';
 export { readRows, readSeries, } from './utils/read-series/read-series.js';
 export { relativeTime, } from './utils/relative-time/relative-time.js';
@@ -56,3 +58,4 @@ export { tellDisclosure } from './utils/tell-disclosure/tell-disclosure.js';
 export { subscribe } from './utils/ticker/ticker.js';
 export { TONE_MARKS, toneMark, } from './utils/tone-marks/tone-marks.js';
 export { dateAsValue, numberAsValue, timeAsValue, valueAsDate, valueAsNumber, valueAsTime, } from './utils/value-as/value-as.js';
+export { writtenList } from './utils/written-list/written-list.js';

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

@@ -13,6 +13,25 @@ type Constructor<T> = new (...args: any[]) => T;
 export declare const PALETTE = 24;
 /** The palette slot for the nth series, counting from one and wrapping. */
 export declare const seriesIndex: (depth: number) => number;
+/**
+ * The drawing's own coordinates, which a `viewBox` maps onto whatever box CSS
+ * gives it.
+ *
+ * Here for the reason `PALETTE` is here, one paragraph up: six families drew
+ * into the same square and declared it six times under three names, and one of
+ * them wrote the same number as a literal on one axis and as its own constant
+ * on the other, in one attribute. A round hundred so a `d` attribute is
+ * readable in the inspector.
+ *
+ * **Two names for one number, because the axes are two facts.** `x2=${PLOT_WIDTH}`
+ * and `y2=${PLOT_HEIGHT}` say which edge they reach; one name used twice says
+ * nothing, and the day a chart is not square the call sites are already right.
+ * `Sparkline` is that day already: it is a strip rather than a plot, so it takes
+ * this width and states its own height beside it.
+ */
+export declare const PLOT_WIDTH = 100;
+/** The drawing's own coordinates. See `PLOT_WIDTH`. */
+export declare const PLOT_HEIGHT = 100;
 /**
  * A list of series names, as the attributes that take one are written.
  *
@@ -23,12 +42,10 @@ export declare const seriesIndex: (depth: number) => number;
  * "the way `lines` and `secondary` are". So `lines="Gateway, Billing"` looked
  * exactly like `outlined="Gateway, Billing"` and matched nothing, because
  * `gateway,` is not a column heading: no column drawn as a line, no error, and
- * nothing to read off the page that says why. That is the undebuggable case
- * `gridlines` names in its own docblock, arrived at from the other direction.
+ * nothing to read off the page that says why.
  *
- * A comma is accepted rather than refused because a reader writing a list of
- * words puts commas between them, and the widest of the spellings already
- * shipped. Lowercased and trimmed, since the headings are matched
+ * `writtenList` is the split, and carries the argument for accepting a comma.
+ * What this adds is the lowercase, the headings being matched
  * case-insensitively.
  */
 export declare const seriesNames: (list: string | undefined) => string[];

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

@@ -7,12 +7,12 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 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';
+import { writtenList } from '../../utils/written-list/written-list.js';
 export const PALETTE = 24;
 export const seriesIndex = (depth) => (depth % PALETTE) + 1;
-export const seriesNames = (list) => (list ?? '')
-    .split(/[\s,]+/)
-    .map((name) => name.trim().toLowerCase())
-    .filter(Boolean);
+export const PLOT_WIDTH = 100;
+export const PLOT_HEIGHT = 100;
+export const seriesNames = (list) => writtenList(list).map((name) => name.toLowerCase());
 export const MixinChartSource = (Base) => {
     class ChartSourceElement extends Base {
         constructor() {

package/dist/mixins/mixin-collection/mixin-collection.js

@@ -28,7 +28,7 @@ export const MixinCollection = (Base) => {
         }
         willUpdate(changed) {
             super.willUpdate(changed);
-            if (this.children === undefined || this.hydrating) {
+            if (!this.childrenKnown) {
                 return;
             }
             const rows = this.slotted.length;

package/dist/mixins/mixin-field/mixin-field.d.ts

@@ -9,6 +9,13 @@ type Constructor<T> = new (...args: any[]) => T;
  * to this interface keeps the internals private and the build working.
  */
 export declare class MixinFieldInterface {
+    /**
+     * Id the field's label points at, written by the control this wraps.
+     *
+     * The third fixed id and the only one this mixin does not render, the
+     * control being the family's. See the note on the class member.
+     */
+    protected controlId: string;
     /**
      * Help under the control, shown while there is nothing wrong.
      *

package/dist/mixins/mixin-field/mixin-field.js

@@ -13,6 +13,7 @@ export const MixinField = (Base) => {
     class FieldElement extends Base {
         constructor() {
             super(...arguments);
+            this.controlId = 'control';
             this.feedback = '';
             this.hint = '';
             this.label = '';
@@ -52,7 +53,7 @@ export const MixinField = (Base) => {
             if (this.label === '' && !hidden) {
                 return nothing;
             }
-            return html `<label part="label" for="control" ?data-hidden=${hidden !== null}
+            return html `<label part="label" for=${this.controlId} ?data-hidden=${hidden !== null}
         ><slot name="label">${this.label || hidden}</slot></label
       >`;
         }

package/dist/mixins/mixin-selectable-item/mixin-selectable-item.d.ts

@@ -0,0 +1,66 @@
+import type { HelixElement } from '../../helix-element/helix-element.js';
+type Constructor<T> = new (...args: any[]) => T;
+/**
+ * The public surface `MixinSelectableItem` adds.
+ *
+ * Declared separately because TypeScript cannot emit declarations for an
+ * anonymous class that has private members (TS4094). Casting the mixin's return
+ * to this interface keeps the internals private and the build working.
+ */
+export declare class MixinSelectableItemInterface {
+    /** Whether this one can be chosen. */
+    disabled: boolean;
+    /** Moves focus to the control this renders, for the set's arrow keys. */
+    focusItem(): void;
+    /**
+     * The part `focusItem` focuses, which each family names for itself.
+     *
+     * Parameterised for the reason `MixinField`'s `reportRequired` takes its
+     * anchor as an argument: the control is the family's to render, so a literal
+     * here would be a lookup for a part this file does not write.
+     */
+    protected itemPart: string;
+    /**
+     * Chooses this one and announces it, and reports whether the request stood.
+     *
+     * `MixinDismissible.dismiss` next door has the same shape and for the same
+     * reason: a mixin has no family, so the answer to a cancelable event it
+     * dispatches is read at the dispatch or nowhere. The set acting on the choice
+     * offers the second refusal on its own root.
+     */
+    select(): boolean;
+    /** Whether this is the current one. Written by the set. */
+    selected: boolean;
+    /** Identifies this one to the set, and is what a form submits. */
+    value: string;
+}
+/**
+ * The item half of a set: what is chosen, and what the arrow keys move over.
+ *
+ * **This is `KeyboardNavigationController.NavigableItem`, implemented.** That
+ * interface has declared the contract since the controller was written and
+ * nothing implemented it, so every family that took the controller wrote the
+ * same five members out again: Radio and Toggle were byte-identical down to the
+ * fourteen-line note on `willUpdate`, and Tab differed in one part name. A
+ * contract with no implementation is a contract each caller reinvents, and the
+ * reinventions drift: the mirror is the half that must not, because a stylesheet
+ * selects on it.
+ *
+ * **The render stays with the family and only the part name comes here.** These
+ * elements are a radio, a switch and a tab, and what goes inside the control is
+ * the whole of what makes them different. `itemPart` is the one thing the mixin
+ * has to know, because focusing is the one thing it does to the render.
+ *
+ * **What is deliberately not here.** `defaultSelected` belongs to the families
+ * whose selection a consumer declares in markup, and `focusable` to the ones
+ * whose set has a tab stop to park while nothing is chosen. Neither is true of
+ * every item in the library, and a mixin that granted them would publish a
+ * property on a reference page for a fact the family has no answer to. The
+ * items whose current one is wherever focus happens to be (`Menu.Item`,
+ * `Drilldown.Item`, `SpeedDial.Item`) are the other kind again: their `selected`
+ * is a getter over `activeElement` rather than a property a parent writes, so
+ * they satisfy the same interface by a different route and take nothing from
+ * here.
+ */
+export declare const MixinSelectableItem: <T extends Constructor<HelixElement>>(Base: T) => Constructor<MixinSelectableItemInterface> & T;
+export {};

package/dist/mixins/mixin-selectable-item/mixin-selectable-item.js

@@ -0,0 +1,44 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { property } from 'lit/decorators.js';
+import { HelixSelectEvent } from '../../events/events.js';
+export const MixinSelectableItem = (Base) => {
+    class SelectableItem extends Base {
+        constructor() {
+            super(...arguments);
+            this.disabled = false;
+            this.selected = false;
+            this.value = '';
+            this.itemPart = 'item';
+        }
+        focusItem() {
+            this.partNamed(this.itemPart)?.focus();
+        }
+        select() {
+            if (this.disabled) {
+                return false;
+            }
+            const event = new HelixSelectEvent({ value: this.value });
+            this.dispatchEvent(event);
+            return !event.defaultPrevented;
+        }
+        willUpdate(changed) {
+            super.willUpdate(changed);
+            this.toggleState('selected', this.selected);
+        }
+    }
+    __decorate([
+        property({ reflect: true, type: Boolean })
+    ], SelectableItem.prototype, "disabled", void 0);
+    __decorate([
+        property({ type: Boolean })
+    ], SelectableItem.prototype, "selected", void 0);
+    __decorate([
+        property()
+    ], SelectableItem.prototype, "value", void 0);
+    return SelectableItem;
+};

package/dist/utils/mark-region/mark-region.d.ts

@@ -0,0 +1,43 @@
+/** What a region may hold besides what a consumer slotted. */
+export interface RegionOptions {
+    /**
+     * Whether an empty region leaves the box tree as well as being marked.
+     *
+     * True everywhere but one place, and that exception is why this is an option
+     * rather than the behavior. A region a component paints into while it is
+     * empty has to keep its box: `Chat.Message` draws its typing indicator into a
+     * content region whose emptiness is exactly what says to draw it, so hiding
+     * the region would take the indicator with it.
+     */
+    hide?: boolean;
+    /**
+     * A selector for something the component itself renders into the region.
+     *
+     * A region holding only what the component drew is not empty. Data Table's
+     * footer holds its own pagination and Notifications' header its own mark-all
+     * control, and both would otherwise be hidden out from under the thing they
+     * were rendered to carry.
+     */
+    occupied?: string;
+}
+/**
+ * Says on a rendered region whether anything is in it.
+ *
+ * Nine families ask one question of a slot and write the same two attributes on
+ * the box around it, and three of them carried this method byte for byte. What
+ * differs between them is the region's name, which slots count toward it, and
+ * whether the component draws into the region itself, so those are the
+ * arguments and nothing else is. `slotFilled` beside this is the half that
+ * answers whether there is anything there, and carries the reason no selector
+ * can.
+ *
+ * **The empty string names the default slot**, and it resolves to
+ * `slot:not([name])` rather than to a bare `slot`, which matches whichever slot
+ * comes first in the shadow root and is the right answer only while a component
+ * has one.
+ *
+ * On the region inside the shadow root rather than on the host: an attribute
+ * written onto the host is a change to markup the consumer rendered, which
+ * React reports on hydration and does not patch up.
+ */
+export declare const markRegion: (root: ParentNode | null | undefined, part: string, slots: readonly string[], options?: RegionOptions) => void;

package/dist/utils/mark-region/mark-region.js

@@ -0,0 +1,9 @@
+import { slotFilled } from '../slot-filled/slot-filled.js';
+export const markRegion = (root, part, slots, options = {}) => {
+    const region = root?.querySelector(`[part="${part}"]`);
+    const filled = slots.some((name) => slotFilled(root?.querySelector(name === '' ? 'slot:not([name])' : `slot[name="${name}"]`))) || Boolean(options.occupied && root?.querySelector(options.occupied));
+    region?.toggleAttribute('data-empty', !filled);
+    if (options.hide !== false) {
+        region?.toggleAttribute('hidden', !filled);
+    }
+};

package/dist/utils/written-list/written-list.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A list a consumer wrote into an attribute, split the way they write one.
+ *
+ * **Whitespace or commas, because a reader listing words puts commas between
+ * them.** A split on whitespace alone turns `extra-controls="speed, pip"` into
+ * `speed,` and `pip`, and `speed,` is not a control name: the control is
+ * dropped, nothing is logged, and the docblock on the property says
+ * unrecognized values are skipped, so the behavior looks like the documented
+ * one. That is the undebuggable case `gridlines` names in its own docblock,
+ * arrived at from the other direction, and it is why the widest spelling is the
+ * one every consumer-written list takes.
+ *
+ * **Not for a value.** A payload is comma separated and nothing else, because a
+ * value may hold a space: splitting `value="New York,Paris"` on whitespace
+ * would submit a city that does not exist. Select, Listbox, Combobox and
+ * Checkbox Group each split their own value on a comma and trim, which is the
+ * other rule and not a lesser version of this one.
+ *
+ * **Nor for an IDREF list**, which is the platform's own format: `aria-*` and
+ * `for` take whitespace and only whitespace, and accepting a comma there would
+ * resolve an id nobody can write.
+ */
+export declare const writtenList: (source: string | undefined) => string[];

package/dist/utils/written-list/written-list.js

@@ -0,0 +1 @@
+export const writtenList = (source) => (source ?? '').split(/[\s,]+/).filter((one) => one !== '');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.52.1",
+  "version": "0.53.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -34,12 +34,12 @@
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",
-    "@fusion.dev/helix-icons": "0.52.1"
+    "@fusion.dev/helix-icons": "0.53.0"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",
-    "@fusion.dev/helix-cem": "0.52.1",
-    "@fusion.dev/helix-testing": "0.52.1",
+    "@fusion.dev/helix-cem": "0.53.0",
+    "@fusion.dev/helix-testing": "0.53.0",
     "lit": "^3.2.1"
   },
   "homepage": "https://fusion.dev",