@fusion.dev/helix-headless 0.2.0 → 0.3.0

package/dist/stat/group/stat-group.js

@@ -7,27 +7,9 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, hostAria } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary A row of related measurements.
- *
- * @description
- * A group rather than a list, because the figures are read together and their
- * order carries no meaning: a list would announce "1 of 4" for a set where the
- * position is not information.
- *
- * @since 0.1.0
- * @status stable
- * @aliases Metrics, KPIs, Figures
- * @documentation https://helix.fusion.dev/components/stat
- *
- * @slot - The stats.
- */
 let HelixHeadlessStatGroup = class HelixHeadlessStatGroup extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Accessible name for the set.
-         */
         this.label = '';
     }
     willUpdate(changed) {

package/dist/stat/root/stat-root.js

@@ -7,29 +7,6 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary One measurement, with the word for what it measures.
- *
- * @description
- * Label first in the markup and the value after it, which is the reading order
- * a screen reader takes and the order a caption sits above a figure. The eye
- * lands on the number either way, because the number is the loud thing; a
- * reader hearing it needs to know what it counts before hearing how many.
- *
- * Both are bare slots. An element whose only job is to assign itself a slot on
- * connect gives its own host an attribute after upgrade, which a React
- * consumer's server markup never had.
- *
- * @since 0.1.0
- * @status stable
- * @category data
- * @aliases Metric, KPI, Figure
- * @documentation https://helix.fusion.dev/components/stat
- *
- * @slot - The value.
- * @slot label - What the value measures.
- * @slot unit - The unit, set beside the value.
- */
 let HelixHeadlessStat = class HelixHeadlessStat extends HelixElement {
     render() {
         return html `<slot name="label"></slot>

package/dist/steps/root/steps-root.js

@@ -7,59 +7,9 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, hostAria, MixinControllerActive, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary A sequence of stages, and where the reader is in it.
- *
- * @description
- * **`active` names where the reader is. `complete` stays on each step.** They
- * are two different facts and only one of them is positional. Deriving both
- * from a position is the obvious design and it is wrong the first time anybody
- * steps back: return to stage one of three and stages one and two are still
- * finished, while "everything before the active one" says only the first is.
- * So this element drives `current` and never touches `complete`.
- *
- * **`active` is optional, and a sequence without it still renders.** Left
- * unset, each step's own `current` stands and nothing here overwrites it, which
- * is what lets the whole sequence be right in the server's markup: this element
- * would have to count its slotted children to know which one is third, and the
- * server has no children to count. Set it, and it wins, because it is a
- * statement about the sequence where the attribute on a step is a statement
- * about one step.
- *
- * That is also why the numbering is not JavaScript. It is a CSS counter in the
- * tier above, which the browser resolves at layout with no script at all, so
- * the third step reads "3" in the server's own markup.
- *
- * **The connector belongs to the step, not to the list.** Each one draws the
- * line that arrives at it and hides it when it is first, the same arrangement
- * Breadcrumbs uses for its separator and for the same reason: a line drawn
- * between items needs either an index or a parent that counts, and drawing it
- * on the item needs neither.
- *
- * `role="list"` on the host rather than an `<ol>` in the shadow root. The steps
- * are the consumer's elements in the light DOM, so an `<ol>` here would be a
- * list whose items are somewhere else.
- *
- * @since 0.1.0
- * @status experimental
- * @category navigation
- * @aliases Stepper, Wizard, Progress steps
- * @documentation https://helix.fusion.dev/components/steps
- *
- * @slot - The steps, which are `helix-step` elements.
- *
- * @event {HelixActivateEvent} helix-activate - Fired once the current one has moved, so the element already holds it.
- * @event {HelixBeforeActivateEvent} helix-before-activate - Fired before the active step changes. Cancelable: refusing it takes the decision and nothing moves.
- */
 let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(HelixElement) {
     constructor() {
         super(...arguments);
-        /**
-         * Accessible name for the sequence.
-         *
-         * A list of stages is a landmark a reader arrives at out of order, so it
-         * needs a name of its own rather than borrowing the heading above it.
-         */
         this.label = 'Steps';
         this.handleSelection = (event) => {
             this.requestActive(event.detail.value);
@@ -68,21 +18,9 @@ let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(
             this.sync();
         };
     }
-    /** The steps, in the order the consumer wrote them. */
     get steps() {
         return [...this.querySelectorAll(':scope > *')].filter((one) => 'current' in one);
     }
-    /**
-     * Puts `active` on whichever step owns it.
-     *
-     * Returns without touching anything where nothing has set `active`, which is
-     * the case a server renders: the steps' own `current` is the state then, and
-     * overwriting it on hydration is exactly the flash this design exists to
-     * avoid.
-     *
-     * `current` only. `complete` is the consumer's on each step, because a reader
-     * who steps back has finished more stages than they are standing in front of.
-     */
     sync() {
         if (this.active === '') {
             return;

package/dist/steps/step/step.js

@@ -9,131 +9,21 @@ import { check, circle, record } from '@fusion.dev/helix-icons';
 import { property } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 import { html } from 'lit/static-html.js';
-/* Side-effect import, because this renders a button and a custom element
-   registers on import. The path is relative, so this registers the base button
-   and the styled file's identical import registers the styled one; `tier` picks
-   which name the template asks for. */
 import '../../button/index.js';
-/**
- * @summary One stage in a sequence.
- *
- * @description
- * **The name is a button, and only the name.** A stepper is something a reader
- * goes back through, and the thing they reach for is the name of the stage. The
- * marker is `aria-hidden` decoration, so wrapping it in the button would add
- * hit area and no meaning: the accessible name would be the text either way,
- * and what is pressable would stop being the same shape as what is readable.
- *
- * It is `helix-button`, not a `<button>` this element resets and dresses: the
- * hover wash, the focus ring and the disabled treatment are decisions the
- * button already carries. `ghost` is the quiet shape, transparent until it is
- * pointed at.
- *
- * It says nothing about where a reader may go. Every step is pressable and
- * announces itself with `helix-select`; refusing the ones ahead is `disabled`,
- * which the consumer sets because only the consumer knows whether a form can be
- * skipped. A component that guessed would be wrong on the first wizard that
- * lets you jump to the end.
- *
- * **The marker is a slot whose fallback is the state.** A finished stage shows
- * a check, the current one a target, and one not yet reached an empty ring:
- * three marks that say what a reader wants to know without a legend. A consumer
- * who wants their own fills the slot instead.
- *
- * The step renders exactly one of the three, chosen from its own two booleans.
- * Rendering all three and hiding two in CSS would work and is worse: the
- * accessibility tree would carry marks that are not there, and the markup would
- * say three things about a stage that is one.
- *
- * Numbering belongs to the tier above. `numeric` hides the mark and shows a CSS
- * counter, which the browser resolves at layout, so the digit costs no script
- * and is right in the server's markup however the steps are ordered. Nothing
- * here knows which appearance is in use.
- *
- * **`complete` and `current` are separate, and both can be false.** A stage
- * that is neither is one the reader has not reached, which is the majority of
- * any sequence and therefore the state that needs no attribute. They can also
- * both be true: a reader who steps back into a finished stage is in it and has
- * finished it, and a stepper that forgets the second is one that loses its
- * checks the moment somebody reviews their answers.
- *
- * **The `content` slot opens on the current step, and only down a column.** A
- * row has no room under a step to put a form in, and stretching one to fit
- * would set every step's height by the tallest. `current` is what opens it, so
- * the state that says where the reader is is also the state that shows them the
- * stage: one attribute, no second flag to keep in step with it, and it renders
- * open on the server rather than after hydration.
- *
- * @since 0.1.0
- * @status experimental
- * @aliases Stage
- * @documentation https://helix.fusion.dev/components/steps
- *
- * @slot - The step's name.
- * @slot content - What the stage holds, shown while it is the current one.
- * @slot description - A line under the name, for what the stage is for.
- * @slot marker - Replaces the number, or the check a complete step shows.
- *
- * @event {HelixSelectEvent} helix-select - Fired when the step is pressed. Cancelable: refusing it takes the decision and nothing moves.
- *
- * @csspart body - The name and its description.
- * @csspart content - What the stage holds, while it is open.
- * @csspart description - The line under it.
- * @csspart label - The step's name, which is a `helix-button`.
- * @csspart label-button - The inner control.
- * @csspart lead - The half line arriving from the step before.
- * @csspart mark - The glyph inside the marker: a tick, a dot, or an empty ring.
- * @csspart marker - The shape carrying the number or the check.
- * @csspart trail - The half line running on to the next.
- */
 let HelixHeadlessStep = class HelixHeadlessStep extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Whether the reader has finished this stage.
-         */
         this.complete = false;
-        /**
-         * Whether this is the stage the reader is in.
-         */
         this.current = false;
-        /**
-         * Whether the reader may go to this stage.
-         */
         this.disabled = false;
-        /**
-         * What this stage is called when it announces itself.
-         */
         this.value = '';
     }
-    /** Announces the step, unless it is refusing. */
     select() {
         if (this.disabled) {
             return;
         }
         this.dispatchEvent(new HelixSelectEvent({ value: this.value }));
     }
-    /**
-     * The mark this stage's state calls for.
-     *
-     * `complete` first, so a stage a reader has stepped back into keeps its check
-     * rather than losing it to the target: they did finish it, and the name and
-     * the rule below still say which one is open.
-     *
-     * **Three shapes, and the reader can tell them apart with the color off.**
-     * An outline circle for a stage nobody has reached, the same circle with a
-     * center for the one they are standing on, a bare check for one that is done.
-     * The first two are one shape filling in, which is the progression, and the
-     * check is the only mark that leaves the family because finishing is the only
-     * state that is not a position in the sequence. A coin around the check would
-     * put two of the three inside the same container and leave hue doing the work
-     * of telling them apart.
-     *
-     * The bare check matches `Timeline`, deliberately: the two components report
-     * the same kind of thing, a sequence with marks down it, and a check on a
-     * hairline in one beside a check inside a coin in the other is two answers to
-     * one question.
-     */
     renderMarker() {
         const icon = this.complete ? check : this.current ? record : circle;
         return html `<slot name="marker"
@@ -147,15 +37,6 @@ let HelixHeadlessStep = class HelixHeadlessStep extends HelixElement {
         hostAria(this.internals, { role: 'listitem' });
         this.internals.ariaCurrent = this.current ? 'step' : null;
     }
-    /**
-     * The step's own label, which is a control because a step can be gone to, behind a seam the styled tier can move.
-     *
-     * A method rather than a fragment inline, so a tier above can render its own,
-     * wrap this one, or leave it out, without reimplementing the whole template.
-     * The tag is interpolated rather than written, so `tier` resolves it: this
-     * renders the headless element, and a styled subclass that sets `tier`
-     * renders the styled one from the same template.
-     */
     renderLabel() {
         return html `<${this.tag('button')}
       part="label"
@@ -168,18 +49,6 @@ let HelixHeadlessStep = class HelixHeadlessStep extends HelixElement {
     </${this.tag('button')}>`;
     }
     render() {
-        /* Two half lines, one either side of the mark, rather than one line running
-           the whole way to the next step.
-           A single line drawn to the next marker has to know how far away that is,
-           which is the next step's size, and a step knows only its own; drawn
-           across the gap alone it is a stub. Two halves need neither: each reaches
-           from the mark to its own step's edge and half the gap beyond, so it meets
-           the one coming the other way in the middle of the gap and the rule reads
-           as continuous however wide the steps are or how differently they are
-           filled.
-           The first has nothing on its leading side and the last nothing on its
-           trailing one, which `:host(:first-child)` and `:host(:last-child)` say
-           with no index and no parent counting its children. */
         return html `<span part="lead" aria-hidden="true"></span>
       <span part="trail" aria-hidden="true"></span>
       <span part="marker" aria-hidden="true">

package/dist/switch/root/switch-root.js

@@ -7,74 +7,17 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { AriaForwardController, customElement, HelixFormElement, MixinControllerChecked, MixinField, slotFilled, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary A control that turns something on or off.
- *
- * @description
- * **A switch is not a checkbox with a different shape.** A checkbox is an
- * answer to a question the form asks when it is submitted; a switch is a thing
- * happening now. That is why `role="switch"` exists and why a switch belongs
- * outside a form as often as in one: it says "on" and "off" rather than
- * "ticked" and "unticked", and a reader expects the effect immediately rather
- * than on Save.
- *
- * Rendered as a real `<input type="checkbox">` carrying `role="switch"`, which
- * is the pairing ARIA describes: the input is what a form submits and what a
- * label forwards a press to, and the role is what a screen reader announces.
- * Neither half can be got from the other.
- *
- * The label sits beside it, inside the `<label>` that forwards the press, the
- * way a checkbox's does. The hint and the message go under the row, because
- * there is no above: the switch and the words naming it are one line.
- *
- * @since 0.1.0
- * @status stable
- * @category forms
- * @aliases Toggle switch, On/off
- * @documentation https://helix.fusion.dev/components/switch
- *
- * @slot - The words naming what this turns on.
- *
- * @event {Event} change - Relayed from the input once the state has changed.
- * @event {HelixBeforeToggleEvent} helix-before-toggle - Fired before the state changes, and cancelable.
- * @event {Event} input - Announced once the state has moved.
- *
- * @csspart control - The input.
- * @csspart feedback - What is wrong with it.
- * @csspart field - The row: the track and its label.
- * @csspart hint - Help under the control, while nothing is wrong.
- * @csspart label - The words beside it.
- * @csspart thumb - The part that moves.
- * @csspart track - The groove the thumb travels in.
- */
 let HelixHeadlessSwitch = class HelixHeadlessSwitch extends MixinControllerChecked(MixinField(HelixFormElement)) {
     constructor() {
         super(...arguments);
-        /* A consumer's `aria-describedby` names ids in their own tree and the control
-           is in this shadow root, so the reference has to be carried down as an
-           element rather than copied as an id. See `AriaForwardController`: measured
-           in Chrome's own tree, the host held the description and the control the
-           reader is actually on was exposed without it. */
         this.aria = new AriaForwardController(this, {
             target: () => this.renderRoot?.querySelector('[part="control"]') ?? null,
         });
-        /**
-         * Value submitted when the switch is on.
-         */
         this.value = 'on';
         this.handleChange = (event) => {
             event.stopPropagation();
             const control = event.target;
             const taken = this.requestChecked(control.checked);
-            /* The input follows the element, always, not only where the change was
-               refused.
-             *
-             * A controlled switch takes the request and applies nothing: it has
-               announced where it would go and is waiting to be told. The input had
-               already flipped itself, so until the consumer answered, the switch showed
-               one state and held the other, and a consumer who never answers showed the
-               wrong one for good. Putting it back costs nothing where the change was
-               taken, since `this.checked` is then the new value anyway. */
             control.checked = this.checked;
             if (!taken) {
                 return;
@@ -82,17 +25,11 @@ let HelixHeadlessSwitch = class HelixHeadlessSwitch extends MixinControllerCheck
             this.dispatchEvent(new Event('change', { bubbles: true, composed: false }));
         };
     }
-    /** Reports what the form would submit, and the verdict on it. */
     sync() {
-        // `null` rather than the value when it is off, which is how a checkbox
-        // behaves: an unticked box submits nothing rather than a blank.
         this.internals.setFormValue(this.checked ? this.value : null);
         this.reportRequired(!this.checked, 'Turn this on to continue.', 'control');
     }
-    /** Returns the switch to the state its markup declared. */
     formResetCallback() {
-        // `resetChecked` drops both halves, the consumer's and the element's, so
-        // there is nothing to clear before it.
         this.resetChecked();
     }
     updated(changed) {
@@ -100,30 +37,13 @@ let HelixHeadlessSwitch = class HelixHeadlessSwitch extends MixinControllerCheck
         this.markEmpty();
         this.sync();
     }
-    /**
-     * Says on the `label` region whether anything is in it.
-     *
-     * An empty region is not free: it is still a flex item, so it still takes the
-     * container's gap. There is no selector that can ask, `slot:empty` being
-     * about a slot's fallback rather than its assigned nodes, so the component
-     * asks and says so, on the region inside this 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.
-     */
     markEmpty() {
         const region = this.renderRoot?.querySelector('[part="label"]');
         const empty = !slotFilled(this.renderRoot?.querySelector('[part="label"] slot'));
         region?.toggleAttribute('data-empty', empty);
-        /* `hidden` beside the mirror, because `data-empty` is a hook the styled
-           sheet reads and this tier has no sheet: an empty region left in the box
-           tree is a gap a consumer cannot close without knowing to look for it. The
-           styled rule stays, because that sheet sets `display` on this part and so
-           outranks the UA one. */
         region?.toggleAttribute('hidden', empty);
     }
     render() {
-        /* A real `<label>` around both, so pressing the words works with no click
-           handler: the browser does the forwarding. */
         return html `<label part="field">
       <span part="track">
         <input

package/dist/table/cell/table-cell.js

@@ -7,36 +7,13 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, hostAria } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary One cell of a table.
- *
- * @description
- * Carries its own role, because a grid of divs is not a table to anything
- * reading it. `header` makes the cell a `columnheader`, which is what lets a
- * screen reader announce "Attribute, appearance" rather than just the value.
- *
- * The role goes on the host rather than inside the shadow root, because the
- * cell has to be a child of its row in the flat tree for the table's structure
- * to hold together.
- *
- * @since 0.1.0
- * @status experimental
- * @aliases Cell, TableCell
- * @documentation https://helix.fusion.dev/components/table
- *
- * @slot - The cell's content.
- */
 let HelixHeadlessTableCell = class HelixHeadlessTableCell extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Whether the cell heads its column.
-         */
         this.header = false;
     }
     willUpdate(changed) {
         super.willUpdate(changed);
-        // In `willUpdate`, which the server does call, unlike `connectedCallback`.
         hostAria(this.internals, { role: this.header ? 'columnheader' : 'cell' });
     }
     render() {

package/dist/table/column/table-column.js

@@ -7,15 +7,6 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, hostAria } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property, state } from 'lit/decorators.js';
-/**
- * A dot path resolved against a row.
- *
- * Written here rather than taken from a library, because the whole of what is
- * needed is "walk the keys and stop at the first thing that is not an object".
- * Returns `undefined` for a path that does not resolve, which the table renders
- * as an empty cell: a missing key is a hole in the data and drawing `undefined`
- * into a table tells a reader the software is broken rather than the row is.
- */
 const at = (row, path) => {
     if (path === '') {
         return undefined;
@@ -32,189 +23,40 @@ const at = (row, path) => {
     }
     return cursor;
 };
-/**
- * @summary One column of a table: its heading, how wide it is, and what it reads.
- *
- * @description
- * **The column is the source of both its heading and its track.** Add one and
- * the table has another track; remove one and it does not. Declaring the widths
- * separately, as a CSS track list on the table, leaves nothing tying the two
- * together: a table with three headings and a two-track list renders without
- * complaint, and a track list that is accidentally the headings is invalid CSS
- * the grid silently ignores, collapsing the whole table into one column.
- *
- * **It is also where every per-column fact goes**, which is the reason
- * `helix-data-table` needs no column config object. `field` names the key the
- * cell reads, `sortable` says a reader may reorder by it, `align` says which
- * edge the values line up against, and `cell` takes a function for anything the
- * field alone cannot express. The schema is markup and the data is a property:
- * a schema is small, declarative, and something a reader should be able to see
- * in the HTML, and data is large and windowed.
- *
- * **The same element serves both tables**, the markup one and the data one. It
- * is identified by a flag rather than by `instanceof`, so a `helix-table-column`
- * works inside either without the two roots sharing anything else.
- *
- * **It generates no box of its own**, the same as a row: the heading is a grid
- * item of the table, so it lines up with the cells under it rather than sitting
- * in a wrapper that has to be kept the same width.
- *
- * @since 0.1.0
- * @status experimental
- * @aliases Column header, Th
- * @documentation https://helix.fusion.dev/components/table
- *
- * @slot - The heading.
- *
- * @csspart column - The heading cell.
- */
 let HelixHeadlessTableColumn = class HelixHeadlessTableColumn extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Which edge the values line up against.
-         *
-         * `end` is what a column of numbers wants, so digits of the same magnitude sit
-         * above each other. Left unset the cell inherits the table's own alignment,
-         * which is `start` for text in either writing direction.
-         */
         this.align = '';
-        /**
-         * How to read the cell, where the field alone will not do.
-         *
-         * A property and not an attribute, because it is a function. Set it from a Lit
-         * template with `.cell=${...}`, or assign it in script. A column with neither
-         * this nor a `field` renders an empty cell rather than the whole row stringified,
-         * which is the failure mode of guessing.
-         */
         this.cell = undefined;
-        /**
-         * How to read the value that gets sorted and filtered, where it is not the cell.
-         *
-         * **The one that is easy to leave out and expensive to add later.** A cell
-         * showing `2.4 MB` sorts as a string unless something says the underlying value
-         * is a number, so `12 kB` sorts above `2.4 MB` and the column looks broken
-         * while every value in it is right. Left unset this is the field, which is the
-         * correct default: the raw value is what an API sorted by.
-         */
         this.compare = undefined;
-        /**
-         * The key this column reads out of a row.
-         *
-         * Dot paths resolve, so `field="owner.name"` reads a nested value: a result
-         * from an API arrives shaped the way the API shaped it, and requiring a flat
-         * row would push a mapping pass onto every consumer.
-         *
-         * **It is also the sort and filter identity**, which is why sorting is by
-         * field and not by column index: a reordered or hidden column would otherwise
-         * change what `sort="2:asc"` means, and a sort that means something different
-         * after a column moves is a sort a consumer cannot store in a URL.
-         *
-         * Empty on a column that is purely presentational, an actions column say, and
-         * such a column is never sortable however it is marked.
-         */
         this.field = '';
-        /**
-         * Whether a reader may reorder the set by this column.
-         *
-         * Ignored without a `field`, and silently: a column with nothing to sort by
-         * has no order to offer, and refusing loudly would mean an actions column
-         * carrying `sortable` breaks a table rather than doing nothing.
-         */
         this.sortable = false;
-        /**
-         * The track this column takes, as CSS.
-         *
-         * A single track value, so anything valid in `grid-template-columns` works:
-         * `16rem`, `auto`, `minmax(0, 2fr)`. Left unset the column shares what is
-         * left over equally, as `minmax(max-content, 1fr)`.
-         *
-         * **The floor is `max-content`, never `0` and never `min-content`.** A zero
-         * floor lets a track shrink under its own content: at 375 the columns squeeze
-         * to 75px and `eu-central-1` wraps across lines, which reads as corrupt data
-         * rather than as a table that ran out of room. A `min-content` floor still
-         * breaks it, a hyphen being a wrap opportunity.
-         *
-         * The overflow has somewhere to go: `@fusion.dev/helix` scrolls the table's
-         * own box, so a long value pushes past the container and the table scrolls
-         * instead of the value being destroyed. Measured at 375: tracks of 192, 89 and
-         * 102 against a 343 box, so the table scrolls 384 and the page does not move.
-         *
-         * The cost is that a column of prose asks for its longest paragraph on one
-         * line, so a column holding sentences rather than values wants
-         * `width="minmax(0, 1fr)"` to opt back into wrapping. A headless consumer owns
-         * the overflow either way, that being paint, and gets the honest track list.
-         */
         this.width = '';
-        /**
-         * @internal Read by a parent to identify its children across the light DOM,
-         * which is cheaper than `instanceof` and is why this is public rather than
-         * protected. Not a consumer's to read or set.
-         */
         this.isTableColumn = true;
-        /**
-         * @internal Which way this column is currently ordered, written by the table
-         * that owns the sort. Not a consumer's to set: the sort lives on the table,
-         * and a column that disagreed with it would announce an order the rows are
-         * not in.
-         */
         this.sorted = undefined;
     }
-    /** The track this column contributes, resolved. */
     get track() {
         return this.width || 'minmax(max-content, 1fr)';
     }
-    /** Whether a reader can actually reorder by this column. */
     get canSort() {
         return this.sortable && this.field !== '';
     }
-    /**
-     * The value this column shows for a row.
-     *
-     * `cell` first, then the field. An explicit reader that returns `undefined` is
-     * treated as declining rather than as an answer, so a formatter can hand the
-     * default back for the rows it has nothing to say about.
-     */
     read(row) {
         const rendered = this.cell?.(row);
         return rendered === undefined ? at(row, this.field) : rendered;
     }
-    /** The value this column sorts and filters by, which is not always what it shows. */
     order(row) {
         const compared = this.compare?.(row);
         return compared === undefined ? at(row, this.field) : compared;
     }
     willUpdate(changed) {
         super.willUpdate(changed);
-        /* **`aria-sort` is not decoration.** A `columnheader` a reader can reorder
-           by has to say which way it is ordered and which headers are orderable at
-           all, or the whole affordance exists only for a reader who can see the rows
-           move. `none` on the sortable ones that are not currently the sort is the
-           part that carries the second half: it is what tells a screen reader this
-           column can be sorted, where an absent attribute says nothing.
-    
-           Off the internals rather than the attribute, for the same reason the role
-           is: it is this element's own semantics rather than markup a consumer
-           wrote, and an attribute here is one more thing hydration can disagree
-           about. */
         hostAria(this.internals, { role: 'columnheader' });
-        /* Set here rather than through `hostAria`, which carries the four semantics
-           every family needs and not this one. */
         this.internals.ariaSort = this.canSort ? (this.sorted ?? 'none') : null;
-        /* And the same fact as a custom state, because ARIA is not a style hook.
-           Whoever draws this column draws the caret, and had nothing to draw it
-           from: no state and no part told the sorted column from the rest, so the
-           only way to it was listening for `helix-sort` and reading the order back a
-           microtask later, which is a lot of machinery for one glyph. */
         for (const [name, on] of [
             ['sorted-ascending', this.sorted === 'ascending'],
             ['sorted-descending', this.sorted === 'descending'],
         ]) {
-            /* Through `toggleState`, which carries the feature test, the way
-               `pagination-root.ts` does in this same hook. Safari below 17.4 and
-               Firefox below 126 have no `CustomStateSet`, and there
-               `internals.states.delete` is a `TypeError` thrown from `willUpdate`:
-               the column would fail to render rather than render without a caret. */
             this.toggleState(name, on);
         }
     }