@fusion.dev/helix-headless 0.104.1 → 0.106.0

package/dist/radio/root/radio-root.d.ts

@@ -5,20 +5,18 @@ declare const HelixHeadlessRadio_base: (new (...args: any[]) => import("@fusion.
  * @summary One choice in a radio group.
  *
  * @description
- * Renders a `<button role="radio">`, not an `<input type="radio">`, and the
- * reason is the shadow boundary rather than preference: native radios group by
- * sharing a `name` within a form, and a radio inside a shadow root cannot join
- * a group on the other side of it. The group is the form control here, so the
- * option only has to say what it is and announce when it is chosen.
+ * Renders a `<button role="radio">`. Native radios group by sharing a `name`
+ * within a form, and a radio inside a shadow root cannot join a group outside
+ * it. The group is the form control, so each radio only exposes its role and
+ * dispatches an event when it is chosen.
  *
- * **It carries no label of its own.** A radio is named by the words beside it,
- * which is its own content, and the label, hint and message of the *set* belong
- * to the group. This is the one control in the family that takes nothing from
- * `MixinField`, because a lone radio is not a control: it is an answer to one.
+ * The radio has no label of its own. Its content names it, and the label, the
+ * hint, and the message of the set belong to the group. It is the only control
+ * in the family that takes nothing from `MixinField`.
  *
- * Selection is announced rather than applied. The item dispatches, the group
- * decides, and the group writes `selected` back. An item that set itself would
- * be a second source of truth for which one is on.
+ * When a radio is chosen, it dispatches an event, the group determines whether
+ * the choice stands, and the group writes `selected` back. The group is the one
+ * source of which radio is on.
  *
  * @since 0.1.0
  * @status stable
@@ -26,27 +24,25 @@ declare const HelixHeadlessRadio_base: (new (...args: any[]) => import("@fusion.
  * @aliases Option, Choice
  * @documentation https://fusion.dev/helix/components/radio
  *
- * @slot - The words naming this choice.
- * @slot icon - A mark shown beside them, or instead of them under
- * `variant="chip"`, where the words become the accessible name and the mark
- * is what a reader picks between. Separate from the default slot because the
- * chip has to hide one and show the other, and they are both in the same place
- * otherwise.
+ * @slot - The radio's label.
+ * @slot icon - An icon shown beside the label. With `variant="chip"`, the icon
+ * replaces the visible label, and the label becomes the name read by screen
+ * readers. The icon has its own slot so the chip can hide the label and show
+ * the icon.
  *
- * @event {HelixSelectEvent} helix-select - Fired when this choice is made. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixSelectEvent} helix-select - Fired when the radio is chosen. Cancelable: call `preventDefault()` to keep the current choice.
  *
- * @csspart box - The circle. The dot inside it is drawn on the box itself,
- * which is `::part(box)::after` from a consumer's sheet: this tier ships no CSS,
- * so a box it renders for one to paint is an empty child costing whatever the
- * consumer's own layout charges for a child. `ListItem` measured that.
- * @csspart item - The button, which is the whole row.
- * @csspart label - The words beside it.
+ * @csspart box - The circle. Draw the dot inside it with `::part(box)::after` in
+ * your stylesheet. This tier ships no CSS, so it renders no separate element for
+ * the dot, which would add an empty child to your layout.
+ * @csspart item - The button, which covers the whole row.
+ * @csspart label - The label beside the circle.
  *
- * @cssstate selected - While it is the one chosen.
+ * @cssstate selected - The radio is chosen.
  */
 export declare class HelixHeadlessRadio extends HelixHeadlessRadio_base {
     /**
-     * Whether the markup declared this one chosen, which is what a reset returns to.
+     * Whether the markup declares the radio chosen. A form reset returns to it.
      *
      * `<option selected>` reflects to `defaultSelected` and `option.selected` is
      * live state that does not reflect, and those are two different facts. This
@@ -75,7 +71,7 @@ export declare class HelixHeadlessRadio extends HelixHeadlessRadio_base {
     get defaultSelected(): boolean;
     set defaultSelected(next: boolean);
     /**
-     * Whether this choice holds the group's tab stop while nothing is chosen.
+     * Whether the radio holds the group's tab stop while nothing is chosen.
      *
      * The stop rides on the selection, and an unanswered group has no selection,
      * so without this every choice is `tabindex="-1"` and the keyboard cannot

package/dist/rating/root/rating-root.d.ts

@@ -2,21 +2,18 @@ import { HelixFormElement, KeyboardNavigationController } from '@fusion.dev/heli
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessRating_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
 /**
- * @summary A score out of a few marks, given or shown.
+ * @summary A row of marks, such as stars, for giving or showing a score.
  *
  * @description
- * **Half marks decide the shape.** Supporting them means the value is not an
- * integer and the targets are not the marks: five stars at a half step is ten
- * places to press. The pointer handling and `step` are built around that
- * rather than added over it.
+ * Supports half marks, so the value is not always an integer and the press
+ * targets are not the marks: five stars at a half step give ten places to
+ * press. The pointer handling and `step` are built around half marks.
  *
- * **A partial mark is the whole mark, clipped**, not a second glyph filled to
- * the middle: the fill is the same marks over the same marks, cut off partway,
- * so any mark works and any fraction does.
+ * A partial mark is the full mark, clipped. The filled marks are drawn over the
+ * empty marks and cut off partway, so any mark and any fraction work.
  *
- * **Read-only is not this control grayed out.** The commoner use is showing a
- * score nobody is being asked for, which is a reading rather than a disabled
- * input, and it is announced as one.
+ * A read-only rating displays a score, which is the most common use. It is
+ * announced as a displayed value and does not look disabled.
  *
  * @since 0.1.0
  * @status stable
@@ -24,27 +21,27 @@ declare const HelixHeadlessRating_base: (new (...args: any[]) => import("@fusion
  * @aliases Stars, Score, Review score
  * @documentation https://fusion.dev/helix/components/rating
  *
- * @event {Event} change - Announced with it, the choice being the commit.
- * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the score changes, and cancelable.
- * @event {Event} input - Announced once the value has moved.
+ * @event {Event} change - The score was chosen. Sent together with `input`, because each choice commits the score.
+ * @event {HelixBeforeChangeEvent} helix-before-change - The score is about to change. Cancelable: cancel it to keep the current score.
+ * @event {Event} input - The score changed.
  *
- * @csspart feedback - What is wrong with it.
- * @csspart field - The row: the marks, and the score beside them.
+ * @csspart feedback - The message that says what is wrong.
+ * @csspart field - The row that holds the marks and the score next to them.
  * @csspart fill - The filled marks, clipped to the score.
- * @csspart hint - Help under the marks, while nothing is wrong.
- * @csspart label - The question, over the marks.
- * @csspart mark - One mark, in either layer.
+ * @csspart hint - Help text under the marks, shown while there is no feedback.
+ * @csspart label - The label above the marks.
+ * @csspart mark - One mark, in the fill or the track.
  * @csspart marks - The row of marks.
- * @csspart option - One place a reader can press, which is one step.
+ * @csspart option - One target you can press, for one step.
  * @csspart track - The unfilled marks.
- * @csspart value - The score written out, under `show-value`.
+ * @csspart value - The score as a number, shown with `show-value`.
  *
- * @cssproperty --rating-full - How many marks are wholly filled.
- * @cssproperty --rating-part - How much of the next mark is filled, 0 to 1.
- * @cssproperty --rating-step - Which step along the row a target is, counting from one, whatever `min` leaves open.
- * @cssproperty --rating-steps - How many steps the whole row holds, which is `max` over `step`.
+ * @cssproperty --rating-full - The number of marks that are fully filled.
+ * @cssproperty --rating-part - How much of the next mark is filled, from 0 to 1.
+ * @cssproperty --rating-step - The target's position among all the steps in the row, counting from one. Steps below `min` still count.
+ * @cssproperty --rating-steps - The number of steps in the whole row: `max` divided by `step`.
  *
- * @cssstate invalid - While there is feedback to show: the platform's verdict, or the consumer's `feedback`.
+ * @cssstate invalid - The control has an error to show, from the browser's validation or from your `feedback`.
  */
 export declare class HelixHeadlessRating extends HelixHeadlessRating_base {
     protected readonly announcesInput = false;
@@ -53,7 +50,7 @@ export declare class HelixHeadlessRating extends HelixHeadlessRating_base {
      */
     max: number;
     /**
-     * The lowest score a reader can give, which is what clearing returns to.
+     * The lowest score that can be given. A cleared rating shows this score.
      *
      * Zero rather than one, because "no rating" and "the worst rating" are
      * different answers and a control that cannot express the first has to
@@ -96,14 +93,14 @@ export declare class HelixHeadlessRating extends HelixHeadlessRating_base {
      */
     min: number;
     /**
-     * Whether this shows a score rather than asks for one.
+     * Shows the score without letting users change it.
      *
      * A readout is not a control that has been switched off. It takes no focus,
      * answers no keys, and reads as one thing: see the note on the class.
      */
     readOnly: boolean;
     /**
-     * Whether the score is written out beside the marks.
+     * Shows the score as a number next to the marks.
      *
      * Marks say roughly, and a number says exactly. Four and a bit stars is not a
      * reading anyone can repeat, which is why a product's average is nearly always
@@ -123,7 +120,7 @@ export declare class HelixHeadlessRating extends HelixHeadlessRating_base {
      */
     step: number;
     /**
-     * How the score is read out, where "3.5 out of 5" is not what it should say.
+     * The text screen readers read for the score, in place of "3.5 out of 5".
      *
      * A rating out of five is one of the few places a screen reader gets a worse
      * answer from the value than from a sentence: "3.5" alone is a number without

package/dist/scatter-chart/root/scatter-chart-root.d.ts

@@ -20,42 +20,30 @@ export interface ScatterField {
 }
 declare const HelixHeadlessScatterChart_base: typeof HelixElement & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinChartSourceInterface);
 /**
- * @summary Whether two measures move together, one point per row.
+ * @summary A chart that shows whether two measures move together, with one point per row.
  *
  * @description
- * The chart for a relation rather than a series. The table's first numeric
- * column is measured across and every other numeric column is measured up, one
- * point per row, so a table of countries with a column of income and a column
- * of life expectancy draws one dot for each country. More numeric columns are
- * more series against the same across, each in its own color.
+ * A scatter chart shows how two measures relate. The table's first numeric
+ * column is measured across, every other numeric column is measured up, and
+ * each row is one point. A table of countries with an income column and a life
+ * expectancy column draws one point for each country. Each additional numeric
+ * column is another series, in its own color.
  *
- * **Both axes are measured, so both are labeled.** A line chart's readings are
- * named along the bottom and its values are read from the tooltip; here the
- * horizontal position is itself a value, and a point with no scale under it says
- * nothing about how far along it is. The ticks sit at round numbers and the
- * range is widened to them, so the plot's edges are numbers a reader can name.
+ * Both axes are labeled, because both positions are values. The ticks sit at
+ * round numbers, and the range extends to them.
  *
- * **What a reader without the picture is told is how strongly the two relate**,
- * because that is the question a scatter is drawn to answer and the one a table
- * of the same numbers makes hardest to see. The summary gives each series'
- * correlation coefficient and how many points it rests on; the table has every
- * number, and the drawing is `aria-hidden`.
+ * The summary gives each series' correlation coefficient and its number of
+ * points. The table has every number, and the drawing is `aria-hidden`.
  *
- * **The points are elements, not shapes in the drawing.** The drawing stretches
- * to its box, and a circle in a stretched space is an ellipse, so each point is
- * a `<span>` placed by percentage over it, which is how `LineChart` draws its
- * termini and for the same reason.
+ * Each point is a `<span>` placed by percentage over the drawing, as
+ * `LineChart` places its end points, so points stay round when the drawing
+ * stretches.
  *
- * **Left to right on every page, the one chart here that is.** A bar or a line
- * chart's across is the order its readings are named in, which follows the
- * line of text and turns with it. Here it is a measure, and a measure has a
- * direction of its own: more is to the right in every script, as a number line
- * is. So the plot, its axes and the names at their ends sit in a `plane` part
- * that carries `dir="ltr"`, which holds the y axis on the left and the points,
- * rules, ticks, pointer and tooltip mark where a left-to-right page puts them,
- * with no stylesheet asked to know. The names carry `dir="auto"`, so one written
- * in Arabic or Hebrew still reads its own way; the summary is outside the plane
- * and the bubble is told the page's direction, both being words.
+ * The plot runs left to right in every text direction, as a number line does.
+ * The plot, its axes, and the axis names sit in a `plane` part with
+ * `dir="ltr"`. The axis names carry `dir="auto"`, so a name in Arabic or Hebrew
+ * reads in its own direction. The summary and the tooltip bubble follow the
+ * page's direction.
  *
  * @since 0.1.0
  * @status stable
@@ -63,47 +51,47 @@ declare const HelixHeadlessScatterChart_base: typeof HelixElement & (new (...arg
  * @aliases Scatter Plot, XY Chart, Correlation Chart, Dot Plot
  * @documentation https://fusion.dev/helix/components/scatter-chart
  *
- * @csspart gridline - One rule across the plot, under `gridlines`.
+ * @csspart gridline - One line across the plot, drawn when `gridlines` is set.
  * @csspart mark - The invisible point the tooltip is anchored to.
- * @csspart plane - The plot, both axes and their names, left to right on every page. The grid they are laid out in.
+ * @csspart plane - The grid that holds the plot, both axes, and their names. It runs left to right on every page.
  * @csspart plot - The drawing.
  * @csspart point - One row, as a point.
- * @csspart point-active - A point of the row a pointer is asking about, beside `point`.
- * @csspart summary - How strongly the measures relate, for a reader who cannot see the points.
- * @csspart svg - The drawing surface the rules sit on.
+ * @csspart point-active - A point in the row under the pointer. Set alongside `point`.
+ * @csspart summary - The text that says how strongly the measures relate, for people who cannot see the points.
+ * @csspart svg - The drawing surface the gridlines sit on.
  * @csspart tooltip - The bubble, forwarded from `Tooltip`.
  * @csspart tooltip-anchor - The `Tooltip` element itself.
  * @csspart tooltip-arrow - The bubble's point, forwarded from `Tooltip`.
- * @csspart tooltip-arrow-bottom - The point while the bubble is below the reading, so on its top edge, beside `tooltip-arrow`.
- * @csspart tooltip-arrow-left - The point while the bubble is left of the reading, so on its right edge, beside `tooltip-arrow`.
- * @csspart tooltip-arrow-right - The point while the bubble is right of the reading, so on its left edge, beside `tooltip-arrow`.
- * @csspart tooltip-arrow-top - The point while the bubble is above the reading, so on its bottom edge, beside `tooltip-arrow`.
- * @csspart tooltip-bottom - The bubble while it is below the reading, beside `tooltip`.
+ * @csspart tooltip-arrow-bottom - The point while the bubble is below the reading, on its top edge. Set alongside `tooltip-arrow`.
+ * @csspart tooltip-arrow-left - The point while the bubble is left of the reading, on its right edge. Set alongside `tooltip-arrow`.
+ * @csspart tooltip-arrow-right - The point while the bubble is right of the reading, on its left edge. Set alongside `tooltip-arrow`.
+ * @csspart tooltip-arrow-top - The point while the bubble is above the reading, on its bottom edge. Set alongside `tooltip-arrow`.
+ * @csspart tooltip-bottom - The bubble while it is below the reading. Set alongside `tooltip`.
  * @csspart tooltip-cell - One column's name and value inside the tooltip.
  * @csspart tooltip-label - The row's own name inside the tooltip.
- * @csspart tooltip-left - The bubble while it is left of the reading, beside `tooltip`.
+ * @csspart tooltip-left - The bubble while it is left of the reading. Set alongside `tooltip`.
  * @csspart tooltip-name - A column's name inside the tooltip.
- * @csspart tooltip-right - The bubble while it is right of the reading, beside `tooltip`.
- * @csspart tooltip-top - The bubble while it is above the reading, beside `tooltip`.
+ * @csspart tooltip-right - The bubble while it is right of the reading. Set alongside `tooltip`.
+ * @csspart tooltip-top - The bubble while it is above the reading. Set alongside `tooltip`.
  * @csspart tooltip-value - A column's value inside the tooltip.
- * @csspart x-axis - The levels measured across, under the plot.
- * @csspart x-name - What is measured across.
- * @csspart x-tick - One labeled level across. A part of its own rather than a shared `tick`, because `::part()` cannot tell which axis a tick is on.
- * @csspart y-axis - The levels measured up, beside the plot.
- * @csspart y-name - What is measured up.
- * @csspart y-tick - One labeled level up.
+ * @csspart x-axis - The values along the horizontal axis, under the plot.
+ * @csspart x-name - The name of the horizontal measure.
+ * @csspart x-tick - One labeled value on the horizontal axis. Each axis has its own tick part, because `::part()` cannot tell which axis a tick is on.
+ * @csspart y-axis - The values along the vertical axis, beside the plot.
+ * @csspart y-name - The name of the vertical measure.
+ * @csspart y-tick - One labeled value on the vertical axis.
  *
- * @cssproperty --chart-point-x - Where a point sits across, as a percentage. Written by the component.
- * @cssproperty --chart-point-y - Where a point sits up, as a percentage from the top. Written by the component.
- * @cssproperty --chart-tick - Where a tick sits along its axis, as a percentage. Written by the component.
+ * @cssproperty --chart-point-x - A point's horizontal position, as a percentage. The component writes it.
+ * @cssproperty --chart-point-y - A point's vertical position, as a percentage from the top. The component writes it.
+ * @cssproperty --chart-tick - A tick's position along its axis, as a percentage. The component writes it.
  */
 export declare class HelixHeadlessScatterChart extends HelixHeadlessScatterChart_base {
     /**
-     * What to call the strength of the relation in the summary.
+     * The word the summary uses for the strength of the relation.
      */
     correlationLabel: string;
     /**
-     * Which rules are drawn across the plot, if any.
+     * Which gridlines are drawn across the plot, if any.
      *
      * Both axes are measured, so the values name an axis rather than a role:
      * `x` rules the levels across, `y` the levels up. A bare `gridlines`, or
@@ -112,7 +100,7 @@ export declare class HelixHeadlessScatterChart extends HelixHeadlessScatterChart
      */
     gridlines?: 'both' | 'x' | 'y';
     /**
-     * What to call a row in the summary, which counts them.
+     * The word the summary uses for a row when it counts them.
      */
     pointsLabel: string;
     /** The points as last drawn, which the pointer searches. */

package/dist/scroll-area/root/scroll-area-root.d.ts

@@ -3,28 +3,22 @@ import { type PropertyValues, type TemplateResult } from 'lit';
 /** Which edges have something past them, as a set of tokens. */
 declare const EDGES: readonly ['block-start', 'block-end', 'inline-start', 'inline-end'];
 /**
- * @summary A scrolling box that says there is more.
+ * @summary A scrolling box that shows which edges have more content past them.
  *
  * @description
- * **The whole component is one fact a stylesheet cannot work out for itself:
- * which edges have content past them.** A fade at the bottom of a list is easy
- * to draw and impossible to decide, because CSS has no reading of scroll
- * position. So this measures and says, in a custom state per edge, and the
- * styled tier draws whatever it likes on the edges named.
+ * Measures which edges have content past them and sets one custom state per
+ * edge. CSS cannot read scroll position, so a stylesheet cannot work this out
+ * on its own. The styled tier draws a fade on each edge that has a state.
  *
- * **States rather than attributes**, so an element that upgrades after a
- * framework rendered its markup does not hand that framework markup it did not
- * write. A stylesheet asks `:host(:state(more-block-end))`.
+ * Custom states keep an element that upgrades after a framework rendered it
+ * from adding markup the framework did not write. Select them with
+ * `:host(:state(more-block-end))`.
  *
- * **A scrolling region takes the keyboard when it scrolls, and not before.**
- * A box a reader can only reach with a pointer is a box some readers cannot
- * read at all, which is what `tabindex` answers here. Only while it overflows:
- * a tab stop on a box with nothing to scroll is a stop that does nothing, and a
- * form full of them is worse than the problem.
+ * While the content overflows, the region gets a `tabindex`, so keyboard users
+ * can scroll it. When nothing overflows, it is not a tab stop.
  *
- * `role="region"` only with a `label`, because an unnamed region is an
- * announcement with no content: a screen reader says "region" and the reader
- * has learned nothing they did not already know.
+ * It has `role="region"` only when you set a `label`, because a screen reader
+ * announces an unnamed region as only "region".
  *
  * @since 0.1.0
  * @status stable
@@ -32,9 +26,9 @@ declare const EDGES: readonly ['block-start', 'block-end', 'inline-start', 'inli
  * @aliases Scroller, Overflow, Scroll container
  * @documentation https://fusion.dev/helix/components/scroll-area
  *
- * @slot - What scrolls.
+ * @slot - The content that scrolls.
  *
- * @csspart edges - Where the sideways edge cues are drawn.
+ * @csspart edges - The layer that draws the cues on the inline start and end edges.
  * @csspart viewport - The scrolling box.
  *
  * @cssstate more-block-end - While there is more to scroll to past the block end.
@@ -45,7 +39,7 @@ declare const EDGES: readonly ['block-start', 'block-end', 'inline-start', 'inli
  */
 export declare class HelixHeadlessScrollArea extends HelixElement {
     /**
-     * Names the region, for a reader arriving at it out of context.
+     * The region's name, read by screen readers.
      *
      * Without one there is no region: see the note on the class.
      */
@@ -60,7 +54,7 @@ export declare class HelixHeadlessScrollArea extends HelixElement {
     private scrolls;
     private watcher;
     /**
-     * The box that actually scrolls, for anything that needs to move it.
+     * The element that scrolls. Use it to scroll the content from your code.
      *
      * **Public because the alternative is silence.** The scrolling box is inside
      * this shadow root: a consumer holding a reference to this element holds the

package/dist/select/root/select-root.d.ts

@@ -3,22 +3,19 @@ import { type PropertyValues, type TemplateResult } from 'lit';
 import '../../listbox/index.js';
 declare const HelixHeadlessSelect_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
 /**
- * @summary A closed list that opens to be chosen from.
+ * @summary A control that opens a list of options to choose from.
  *
  * @description
- * **A trigger and a `Listbox`, not a listbox reimplemented behind a button.**
- * The list this opens is the same element a consumer can use on its own, with
- * the same keyboard, the same filtering and the same multi-select rules. What
- * Select adds is the closing: a trigger that says what is chosen, a surface
- * that floats, and somewhere for focus to go back to.
+ * A trigger that opens a `Listbox`. The list is the same element you can use on
+ * its own, with the same keyboard behavior, filtering, and multi-select rules.
+ * Select adds a trigger that shows what is chosen, a floating surface, and a
+ * place for focus to return to when the list closes.
  *
- * The options are the consumer's, in the consumer's light DOM, slotted through
- * into the listbox. That is why the listbox walks through slots to find them:
- * from its point of view the options belong to something else.
+ * Your options stay in your light DOM and are slotted through into the listbox,
+ * so the listbox looks through slots to find them.
  *
- * **What it does not do is duplicate the value.** `Select` owns it, hands it
- * down, and takes changes back; the listbox is the thing being operated and not
- * a second place the answer lives.
+ * `Select` owns the value, passes it down to the listbox, and takes changes
+ * back, so the value lives in one place.
  *
  * @since 0.1.0
  * @status stable
@@ -27,46 +24,46 @@ declare const HelixHeadlessSelect_base: (new (...args: any[]) => import("@fusion
  * @documentation https://fusion.dev/helix/components/select
  *
  * @slot - The options, and any groups of them.
- * @slot end - After it, for a count, a unit, or a clear button.
- * @slot hint - Richer than a string.
- * @slot indicator - The mark on the trigger saying this opens, usually a caret.
- * @slot label - Richer than a string.
- * @slot start - Before the chosen value, for an icon or a prefix.
+ * @slot end - Content after the chosen value, such as a count, a unit, or a clear button.
+ * @slot hint - The hint, for content richer than plain text.
+ * @slot indicator - The icon on the trigger that shows it opens, usually a caret.
+ * @slot label - The label, for content richer than plain text.
+ * @slot start - Content before the chosen value, such as an icon or a prefix.
  *
- * @event {Event} change - Announced once the value has moved.
- * @event {HelixBeforeChangeEvent} helix-before-change - Relayed from the listbox when the answer changes. Cancelable: refusing it takes the decision and nothing moves.
- * @event {HelixBeforeCloseEvent} helix-before-close - Fired before it closes. Cancelable: refusing it takes the decision and nothing moves.
- * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the list opens. Cancelable: refusing it takes the decision and nothing moves.
- * @event {Event} input - Announced once the value has moved.
- * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
+ * @event {Event} change - Fired after the value changes.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Relayed from the listbox when the value is about to change. Cancelable: canceling it stops the change and leaves the decision to you.
+ * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the list closes. Cancelable: canceling it keeps the list open and leaves the decision to you.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the list opens. Cancelable: canceling it keeps the list closed and leaves the decision to you.
+ * @event {Event} input - Fired after the value changes.
+ * @event {Event} toggle - Fired after the list opens or closes, with `newState` and `oldState`.
  *
- * @csspart feedback - What is wrong with it.
+ * @csspart feedback - The message that says what is wrong with the value.
  * @csspart hint - Help under the trigger.
- * @csspart indicator - The caret saying the control opens. Replaced by slotting one.
- * @csspart label - The question, over the trigger.
- * @csspart listbox - The list inside it.
- * @csspart listbox-empty - Shown when a filter has hidden everything.
- * @csspart listbox-feedback - What is wrong with it.
- * @csspart listbox-filter-icon - The mark beside that field.
- * @csspart listbox-filter-mark - The glyph beside the filter field, where none is slotted.
+ * @csspart indicator - The caret that shows the control opens. Replaced by content in the `indicator` slot.
+ * @csspart label - The label above the trigger.
+ * @csspart listbox - The list inside the panel.
+ * @csspart listbox-empty - The text shown when the filter hides every option.
+ * @csspart listbox-feedback - The inner list's message that says what is wrong with the value.
+ * @csspart listbox-filter-icon - The icon beside the filter field.
+ * @csspart listbox-filter-mark - The default icon beside the filter field, shown when none is slotted.
  * @csspart listbox-hint - Help under the list.
- * @csspart listbox-items - The list itself.
- * @csspart listbox-label - The question, over the list.
- * @csspart listbox-live - The inner list's `live`, the region a screen reader hears its empty and loading lines from.
- * @csspart listbox-loading - Shown while the options are still on their way.
- * @csspart listbox-search - The region holding the field that narrows the list.
- * @csspart listbox-search-field - The field itself.
+ * @csspart listbox-items - The list of options.
+ * @csspart listbox-label - The label above the list.
+ * @csspart listbox-live - The inner list's `live` part, the region screen readers announce its empty and loading text from.
+ * @csspart listbox-loading - The text shown while the options load.
+ * @csspart listbox-search - The region that holds the filter field.
+ * @csspart listbox-search-field - The filter field.
  * @csspart surface - The floating panel.
- * @csspart trigger - The closed control, which says what is chosen.
+ * @csspart trigger - The closed control, which shows the chosen value.
  * @csspart value - The chosen option's text inside the trigger.
  *
- * @cssstate invalid - While there is feedback to show: the platform's verdict, or the consumer's `feedback`.
+ * @cssstate invalid - The control has an error to show, from the browser's validation or from your `feedback`.
  * @cssstate open - While the list is open.
  */
 export declare class HelixHeadlessSelect extends HelixHeadlessSelect_base {
     protected readonly aria: AriaForwardController;
     /**
-     * What it says where there are none.
+     * The text shown when no options match the filter.
      */
     emptyText: string;
     /**
@@ -77,7 +74,7 @@ export declare class HelixHeadlessSelect extends HelixHeadlessSelect_base {
      */
     filterable: boolean;
     /**
-     * Whether the options are still on their way.
+     * Whether the options are still loading.
      *
      * Passed straight to the list, which is where the rows are and so where the
      * message belongs. Two components saying "Loading" about one request is a
@@ -85,11 +82,11 @@ export declare class HelixHeadlessSelect extends HelixHeadlessSelect_base {
      */
     loading: boolean;
     /**
-     * What the list says while they are on their way.
+     * The text shown while the options load.
      */
     loadingText: string;
     /**
-     * Whether more than one option can be the answer.
+     * Whether more than one option can be chosen.
      */
     multiple: boolean;
     /**
@@ -106,7 +103,7 @@ export declare class HelixHeadlessSelect extends HelixHeadlessSelect_base {
      */
     get selectedIndex(): number;
     set selectedIndex(at: number);
-    /** Which kind of chooser this is, in the platform's two words. */
+    /** The kind of select, as the platform names it: `select-one` or `select-multiple`. */
     get type(): string;
     /**
      * The list inside the surface, or nothing where there is no DOM to hold one.

package/dist/skeleton/root/skeleton-root.d.ts

@@ -1,16 +1,15 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
- * @summary Stands in for content that has not arrived.
+ * @summary A placeholder shown in place of content that is still loading.
  *
  * @description
- * Carries `aria-busy` and a polite live region, so a reader using a screen
- * reader is told the region is filling rather than told nothing and left to
- * wonder. Both go through `ElementInternals`, which writes no attribute.
+ * Sets `aria-busy` and a polite live region, so a screen reader announces that
+ * the region is loading. Both are set through `ElementInternals`, which writes
+ * no attributes.
  *
- * Holds no `shape`. Whether a placeholder is a line, a block or a circle is
- * presentation, and putting it here would give the headless tier an appearance
- * property, which is the one thing that tier is for not having.
+ * There is no `shape` property. Whether a placeholder is a line, a block, or a
+ * circle is presentation, which belongs to the styled tier.
  *
  * @since 0.1.0
  * @status stable
@@ -18,7 +17,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @aliases Placeholder, Shimmer, Ghost
  * @documentation https://fusion.dev/helix/components/skeleton
  *
- * @csspart skeleton - The placeholder surface.
+ * @csspart skeleton - The placeholder shape.
  */
 export declare class HelixHeadlessSkeleton extends HelixElement {
     protected willUpdate(changed: PropertyValues): void;