@fusion.dev/helix-headless 0.104.1 → 0.106.0

package/dist/pagination/size/pagination-size.d.ts

@@ -3,68 +3,62 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 import '../../option/index.js';
 import '../../select/index.js';
 /**
- * @summary Chooses how many items a page holds.
+ * @summary A control for choosing how many items each page shows.
  *
  * @description
- * Its own element beside `Pagination` rather than a slot inside it, for the
- * reason `Pagination.Summary` is: a footer's direction and order are the
- * consumer's, and a control that can only sit at one end of one row has taken
- * that decision for them.
+ * A separate element that you place beside `Pagination`, like
+ * `Pagination.Summary`, so you choose the direction and order of your footer.
  *
- * **`Select`, not a native `<select>`.** Two dropdowns identical closed and
- * different open meet each other in the same footer as a table's filters. The
- * caret is `Select`'s rather than a color literal baked into a data URI,
- * because a background image cannot read `currentColor`, and the label is a
- * real `<label for>` against the trigger's own id.
+ * It uses `Select`, so it matches a table's filter dropdowns in the same
+ * footer, both open and closed. The caret is `Select`'s, so it follows
+ * `currentColor`, and the label is a real `<label for>` pointing at the
+ * trigger's id.
  *
- * **The label sits on the row, not above it.** `Select`'s host is a column, and
- * an outer-tree rule beats a `:host` rule, so turning it into a row needs no
- * property on `Select` and nothing written into the consumer's markup.
+ * The label sits on the same row as the select. `Select`'s host is a column,
+ * and an outer-tree rule overrides a `:host` rule, so the row layout needs no
+ * property on `Select` and nothing added to your markup.
  *
- * **An empty `sizes` renders nothing**, rather than falling back to the
- * built-in list, which would be a component overruling a consumer who said
- * "none". Same rule as `Pagination` over a single page, and reported the same
- * way, through `ElementInternals.states` rather than an attribute the server
- * never wrote.
+ * An empty `sizes` renders nothing and does not fall back to the built-in list.
+ * `Pagination` does the same with a single page, and both report it through
+ * `ElementInternals.states`.
  *
- * `value` is the size the control holds and `default-value` is what the markup
- * declared.
- * Changing it announces `helix-before-change`; re-querying and moving back to
- * page one is the consumer's, because only they know whether the reader's
- * position should survive it.
+ * `value` is the current size, and `default-value` is the size from the markup.
+ * Changing it dispatches `helix-before-change`. Re-querying and returning to
+ * page one is up to you, because only you know whether the current position
+ * should be kept.
  *
  * @since 0.1.0
  * @status stable
  * @aliases Page size, Rows per page
  * @documentation https://fusion.dev/helix/components/pagination
  *
- * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the size changes, and cancelable. The only way to refuse one.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the size changes, and cancelable. Canceling it is the only way to stop a size change.
  *
  * @csspart control - The select.
- * @csspart control-feedback - What is wrong with it.
+ * @csspart control-feedback - The message that says what is wrong with the value.
  * @csspart control-hint - Help under the trigger.
- * @csspart control-indicator - The caret saying the control opens.
- * @csspart control-label - The words beside the number.
- * @csspart control-listbox - The list inside it.
- * @csspart control-listbox-empty - Shown when a filter has hidden everything.
- * @csspart control-listbox-feedback - What is wrong with the list.
- * @csspart control-listbox-filter-icon - The mark beside the filter field.
- * @csspart control-listbox-filter-mark - The glyph beside the filter field, where none is slotted.
+ * @csspart control-indicator - The caret that shows the control opens.
+ * @csspart control-label - The label beside the number.
+ * @csspart control-listbox - The list inside the panel.
+ * @csspart control-listbox-empty - The text shown when the filter hides every option.
+ * @csspart control-listbox-feedback - The inner list's message that says what is wrong with the value.
+ * @csspart control-listbox-filter-icon - The icon beside the filter field.
+ * @csspart control-listbox-filter-mark - The default icon beside the filter field, shown when none is slotted.
  * @csspart control-listbox-hint - Help under the list.
- * @csspart control-listbox-items - The list itself.
- * @csspart control-listbox-label - The question, over the list.
- * @csspart control-listbox-live - The inner listbox's `live`, the region a screen reader hears its empty and loading lines from.
- * @csspart control-listbox-loading - Shown while the options are still on their way.
- * @csspart control-listbox-search - The region holding the field that narrows the list.
- * @csspart control-listbox-search-field - The field itself.
+ * @csspart control-listbox-items - The list of options.
+ * @csspart control-listbox-label - The label above the list.
+ * @csspart control-listbox-live - The inner list's `live` part, the region screen readers announce its empty and loading text from.
+ * @csspart control-listbox-loading - The text shown while the options load.
+ * @csspart control-listbox-search - The region that holds the filter field.
+ * @csspart control-listbox-search-field - The filter field.
  * @csspart control-surface - The floating panel.
- * @csspart control-trigger - The closed control, which says what size is chosen.
+ * @csspart control-trigger - The closed control, which shows the chosen size.
  * @csspart control-value - The chosen size inside the trigger.
  * @csspart option - One size on offer.
  * @csspart option-description - The caption under the number, when there is one.
  * @csspart option-item - The row.
  * @csspart option-item-active - The row the keyboard is on.
- * @csspart option-item-selected - The row of the size chosen.
+ * @csspart option-item-selected - The row of the chosen size.
  * @csspart option-label - The number.
  * @csspart option-text - The number and the caption, as one column.
  *
@@ -72,11 +66,11 @@ import '../../select/index.js';
  */
 export declare class HelixHeadlessPaginationSize extends HelixElement {
     /**
-     * Size to start on, where nothing declared one.
+     * The size to start on when `value` is not set.
      */
     defaultValue: number;
     /**
-     * The words beside the control.
+     * The label beside the control.
      */
     label: string;
     /**
@@ -94,7 +88,7 @@ export declare class HelixHeadlessPaginationSize extends HelixElement {
      */
     sizes: string;
     /**
-     * The size in force.
+     * The current page size.
      *
      * Reading gives the real one; writing declares it the consumer's, and
      * `default-value` seeds one this element owns. Same accessor pair as

package/dist/pagination/summary/pagination-summary.d.ts

@@ -1,22 +1,19 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type TemplateResult } from 'lit';
 /**
- * @summary Reads out which items of how many are on show.
+ * @summary Text that shows which items are on the current page, out of the total.
  *
  * @description
- * Its own element rather than a part of `Pagination`, so a consumer decides
- * where it goes: above, below, in a table's caption, or on the other side of
- * the page. Inside the run it could only ever be at one end of one row.
+ * A separate element from `Pagination`, so you decide where the count goes:
+ * above, below, in a table caption, or elsewhere on the page.
  *
- * **It repeats `page`, `page-size` and `total`, and the cost of that is skew.**
- * Those three come from the consumer's own query, so writing them on two
- * elements is one variable used twice; what it risks is the two disagreeing.
+ * You set `page`, `page-size`, and `total` on both this element and
+ * `Pagination`. They come from your own query, so use the same values for both
+ * and the two elements agree.
  *
- * **Nothing removes that at this level, and it was measured.** A coordinating
- * root can only reach light-DOM children by writing attributes onto them, which
- * a framework reports as a hydration error, or through context, which is dead
- * on a server: `@lit/context` subscribes from `connectedCallback`, and Lit SSR
- * does not call it.
+ * A shared parent cannot pass the values down. Writing attributes onto light
+ * DOM children causes hydration errors in frameworks, and `@lit/context`
+ * subscribes in `connectedCallback`, which Lit SSR does not call.
  *
  * @since 0.1.0
  * @status stable
@@ -25,7 +22,8 @@ import { type TemplateResult } from 'lit';
  */
 export declare class HelixHeadlessPaginationSummary extends HelixElement {
     /**
-     * The reading, with `{from}`, `{to}` and `{total}` filled in.
+     * The text shown. `{from}`, `{to}`, and `{total}` are replaced with the first
+     * item, the last item, and the item count.
      *
      * A template rather than a prefix and a suffix, because word order is not
      * universal: `format="{total} 件中 {from}-{to} 件"` is one attribute here and
@@ -47,7 +45,7 @@ export declare class HelixHeadlessPaginationSummary extends HelixElement {
      */
     locale: string;
     /**
-     * The page on show, one-based.
+     * The current page, counting from one.
      */
     page: number;
     /**

package/dist/pin-input/root/pin-input-root.d.ts

@@ -4,34 +4,28 @@ import { type PropertyValues, type TemplateResult } from 'lit';
 export type PinType = 'alphanumeric' | 'numeric' | 'text';
 declare const HelixHeadlessPinInput_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
 /**
- * @summary A short code, one character to a box.
+ * @summary A field for a short code, with one box for each character.
  *
  * @description
- * **One `<input>` per cell, rather than one input drawn as cells.** A single
- * field autofills perfectly and needs a drawn caret nobody can style well;
- * separate fields give every box a real focus ring, a real caret and a real tab
- * stop for free. Autofill's gap is closed below rather than lived with.
+ * Each cell is its own `<input>`, so every box has a real focus ring, caret,
+ * and tab stop.
  *
- * **Anything longer than one character is treated as a paste, wherever it
- * lands.** That covers the obvious case and two that are not: a browser
- * autofilling an SMS code drops the whole thing into whichever box is focused,
- * and a password manager does the same. So a six-character arrival in cell three
- * fills from cell three rather than being truncated to its first character,
- * which is what a per-cell `maxlength` would have done silently.
+ * Input longer than one character is treated as a paste, in any cell. This
+ * covers pasting, a browser autofilling an SMS code, and a password manager,
+ * which all put the whole code into the focused box. A six-character code that
+ * arrives in cell three fills from cell three.
  *
- * **The code is one value to a form.** The cells are inside a shadow root and
- * submit nothing on their own; the host is form-associated and reports the
- * joined string, which is also what carries validity and answers a reset.
+ * The code is one value to a form. The cells are in a shadow root and submit
+ * nothing. The host is form-associated and submits the joined string, which
+ * also carries validity and responds to a form reset.
  *
- * `autocomplete="one-time-code"` is on the first cell only. It is a hint about
- * the field as a whole, and repeating it on six boxes offers a browser six
- * places to put one code.
+ * Only the first cell has `autocomplete="one-time-code"`, because the hint
+ * applies to the whole field.
  *
- * **Left to right on every page.** A code is read the way a phone number is,
- * one character after another from the left, in Arabic and Hebrew as in
- * English, so the row carries `dir="ltr"`: the first box is the leftmost, a
- * paste fills rightward and the right arrow moves on. The label, the hint and
- * the feedback are words and keep the page's direction.
+ * The row of cells always runs left to right, with `dir="ltr"`, including in
+ * Arabic and Hebrew. The first box is the leftmost, a paste fills to the right,
+ * and the right arrow moves to the next box. The label, hint, and feedback
+ * follow the page's direction.
  *
  * @since 0.1.0
  * @status stable
@@ -39,25 +33,25 @@ declare const HelixHeadlessPinInput_base: (new (...args: any[]) => import("@fusi
  * @aliases PinField, OTP, One-time code, Verification code, InputPin
  * @documentation https://fusion.dev/helix/components/pin-input
  *
- * @event {Event} change - Announced with a filled code, and when an edited one loses focus.
- * @event {HelixBeforeChangeEvent} helix-before-change - Fired as the code changes, and cancelable.
- * @event {HelixCompleteEvent} helix-complete - Fired when the last box is filled.
- * @event {Event} input - Announced once the value has moved.
+ * @event {Event} change - The code was filled, or an edited code lost focus.
+ * @event {HelixBeforeChangeEvent} helix-before-change - The code is about to change. Cancelable.
+ * @event {HelixCompleteEvent} helix-complete - The last box was filled.
+ * @event {Event} input - The code changed.
  *
  * @csspart cell - One box.
- * @csspart feedback - What is wrong with it.
- * @csspart field - The row of boxes, left to right on every page.
- * @csspart hint - Help under the boxes, while nothing is wrong.
- * @csspart label - The question, over the boxes.
+ * @csspart feedback - The message that says what is wrong with the code.
+ * @csspart field - The row of boxes, ordered left to right in every language.
+ * @csspart hint - The help under the boxes, shown while there is no feedback.
+ * @csspart label - The label above the boxes.
  *
- * @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 HelixHeadlessPinInput extends HelixHeadlessPinInput_base {
     protected readonly aria: AriaForwardController;
     /** Typed or dragged, so every edit is announced. See `announcesInput`. */
     protected readonly announcesInput = true;
     /**
-     * What the browser may autofill, reaching the first cell only.
+     * The autofill hint for the browser, set on the first box only.
      *
      * `one-time-code` is why this defaults to anything at all: it is the token
      * that lets a phone offer the code out of a message. Later cells stay `off`
@@ -90,16 +84,16 @@ export declare class HelixHeadlessPinInput extends HelixHeadlessPinInput_base {
      */
     placeholder: string;
     /**
-     * Whether the boxes refuse input while still submitting their value.
+     * Whether the boxes block input. A read-only code still submits its value.
      */
     readOnly: boolean;
     /**
-     * What a reader is told when the code is started and not finished, with
-     * `{length}` filled in. Absent is the control's own sentence, in English.
+     * The message shown when the code is started and not finished, with
+     * `{length}` filled in. When it is unset, an English default is shown.
      */
     tooShortMessage?: string;
     /**
-     * What a box accepts, which decides the keyboard a phone offers.
+     * The characters a box accepts, which also sets the keyboard a phone shows.
      *
      * `numeric` and `alphanumeric` also refuse anything else on the way in,
      * because a code that is digits is digits: letting a letter into a box a
@@ -272,9 +266,9 @@ export declare class HelixHeadlessPinInput extends HelixHeadlessPinInput_base {
      * reported every case valid because nothing had set that flag.
      */
     private sync;
-    /** Puts the caret in the first empty box, which is where a reader resumes. */
+    /** Puts the caret in the first empty box. */
     focus(options?: FocusOptions): void;
-    /** Empties every box and returns to the first. */
+    /** Empties every box and moves focus to the first. */
     clear(): void;
     protected firstUpdated(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;

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

@@ -2,29 +2,24 @@ import { CommandController, HelixElement, type Placement } from '@fusion.dev/hel
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessPopover_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
 /**
- * @summary A panel that opens against a trigger and holds anything.
+ * @summary A panel that opens next to its trigger and holds any content.
  *
  * @description
- * The general case the specific overlays are versions of. `Menu` holds
- * commands, `Select` holds options, `Tooltip` holds a description; this holds
- * whatever the consumer puts in it, which is why it has no keyboard of its own
- * and no opinion about what is inside.
+ * Popover is the general overlay that the specific ones build on. `Menu` holds
+ * commands, `Select` holds options, and `Tooltip` holds a description. Popover
+ * holds any content you put in it, so it has no keyboard handling of its own.
  *
- * **The trigger is slotted and stays the consumer's own element.** Nothing is
- * written onto it: no `aria-expanded`, no `id`, no `tabindex`. A component that
- * decorates a consumer's markup after upgrading is a component whose output a
- * React consumer's hydration disagrees with, and the attribute they would care
- * about most is the one that changes on every open.
+ * The trigger is slotted and stays your own element. The popover writes nothing
+ * onto it, including `aria-expanded`, `id`, and `tabindex`, because changing
+ * your markup after upgrade causes a React hydration mismatch.
  *
- * **The panel is in the top layer**, through the popover API, so it clears any
- * ancestor with `overflow: hidden` without a `z-index` fight. `position: fixed`
- * does not do that: it is still clipped by `overflow`, and re-anchored entirely
- * by an ancestor carrying `transform`, `filter` or `contain`.
+ * The panel is in the top layer through the popover API, so it needs no
+ * `z-index`, and an ancestor with `overflow: hidden`, `transform`, `filter`, or
+ * `contain` does not clip or move it.
  *
- * **It opens on click, and from a command.** `command="--show"` and its
- * siblings work here the way they do on `Dialog` and `Drawer`, so a trigger
- * elsewhere on the page can open it without a line of script and without being
- * slotted into it.
+ * It opens on click and from a command. `command="--show"` and the related
+ * commands work as they do on `Dialog` and `Drawer`, so a button anywhere on
+ * the page can open the popover with no script.
  *
  * @since 0.1.0
  * @status stable
@@ -33,11 +28,11 @@ declare const HelixHeadlessPopover_base: (new (...args: any[]) => import("@fusio
  * @documentation https://fusion.dev/helix/components/popover
  *
  * @slot - The contents of the panel.
- * @slot trigger - What opens it.
+ * @slot trigger - The element that opens the panel.
  *
  * @event {HelixBeforeCloseEvent} helix-before-close - Fired before it closes, and cancelable.
  * @event {HelixBeforeOpenEvent} helix-before-open - Fired before it opens, and cancelable.
- * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
+ * @event {Event} toggle - Fired after the panel opens or closes, with `newState` and `oldState`.
  *
  * @csspart content - The scrolling region inside the panel.
  * @csspart popover - The panel.
@@ -46,7 +41,7 @@ declare const HelixHeadlessPopover_base: (new (...args: any[]) => import("@fusio
  */
 export declare class HelixHeadlessPopover extends HelixHeadlessPopover_base {
     /**
-     * Accessible name for the panel.
+     * The panel's name, read by screen readers.
      */
     label: string;
     /**

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

@@ -1,19 +1,19 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
- * @summary Shows how far along a task is, when that is known.
+ * @summary A bar or ring that shows how far along a task is.
  *
  * @description
- * Determinate by default, and `indeterminate` for a task whose total is not
- * known yet. `Loader` is still right where the wait is short or has no place of
- * its own on the page.
+ * Determinate by default. Set `indeterminate` for a task whose total is not
+ * known yet. Use `Loader` for a short wait or one with no place of its own on
+ * the page.
  *
- * A bar that fills at a made-up rate would be a bar that lies, so the
- * indeterminate one does not fill: it runs a segment across the track, which
- * says work is happening and claims no proportion. `aria-valuenow` is omitted
- * with it, which is the platform's own signal for the same thing.
+ * The indeterminate bar runs a segment across the track and does not fill, so
+ * it shows that work is happening without claiming a proportion.
+ * `aria-valuenow` is omitted in that state, which is the platform's signal for
+ * the same thing.
  *
- * **The fill is a fraction of the track, written as a custom property.**
+ * The fill is a fraction of the track, written as a custom property.
  *
  * @since 0.1.0
  * @status stable
@@ -21,16 +21,17 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @aliases Progress bar, Loading bar
  * @documentation https://fusion.dev/helix/components/progress
  *
- * @csspart groove - The unfilled circle, under the ring's own sweep.
- * @csspart indicator - The part of it that is done.
+ * @csspart groove - The unfilled circle under the ring's filled arc.
+ * @csspart indicator - The filled part that shows the work done.
  * @csspart track - The full length the work is measured against.
- * @csspart value - The reading beside the bar, under `show-value`.
+ * @csspart value - The value shown beside the bar when `show-value` is set.
  *
  * @cssproperty --progress-fraction - The value as a fraction of the range, 0 to 1. Pinned to 1 while indeterminate.
  */
 export declare class HelixHeadlessProgress extends HelixElement {
     /**
-     * Whether the work has a knowable end.
+     * Whether the length of the task is unknown. The bar then shows activity
+     * without a value.
      *
      * On the headless tier rather than as a treatment, because it is
      * semantics before it is a picture: a progressbar with no `aria-valuenow` is
@@ -86,7 +87,8 @@ export declare class HelixHeadlessProgress extends HelixElement {
      */
     value: number;
     /**
-     * A reading for the value, where the number alone does not say enough.
+     * Text that describes the value when the number alone is not enough, such as
+     * "3 of 8 files".
      *
      * "3 of 8 files" rather than "37". Announced instead of the percentage, and
      * never instead of the value itself: `aria-valuenow` still carries the

package/dist/qr-code/root/qr-code-root.d.ts

@@ -5,30 +5,26 @@ export type QrCorrection = 'H' | 'L' | 'M' | 'Q';
 /** How the modules are drawn. */
 export type QrStyle = 'dots' | 'rounded' | 'square';
 /**
- * @summary Encodes a short piece of text as a scannable square.
+ * @summary A scannable QR code for a short piece of text.
  *
  * @description
- * **The picture is one `<path>`, not a grid of squares.** A code of any useful
- * length is a thousand modules, and drawing each as its own rect is a thousand
- * nodes for one image. Runs of adjacent dark modules are joined, so a row of
- * eight is one horizontal move rather than eight squares.
+ * The code is drawn as one `<path>`. Runs of adjacent dark modules are joined,
+ * so a row of eight is one horizontal move. A code of useful length has about a
+ * thousand modules, and an element for each would be a thousand nodes for one
+ * image.
  *
- * **It is an image and says so.** `role="img"` with a name, because what a
- * reader with a screen reader needs is what the code is *for*, and no amount of
- * describing the pattern gives them that. Where nothing is passed the value
- * itself is the name, which is right far more often than it looks: most codes
- * hold a URL, and a URL read aloud is the destination.
+ * The element has `role="img"` and an accessible name. Set the name to what the
+ * code is for. When you pass no name, the value is the name. Most codes hold a
+ * URL, and a URL read aloud gives the destination.
  *
- * **The quiet zone is part of the code.** Four modules of margin are required
- * by the specification, not a design choice, and a scanner will refuse a code
- * that is cropped to its edge. It is drawn inside the `viewBox` so it survives
- * any size the component is given, including one set in CSS.
+ * The quiet zone of four modules is required by the specification, and a
+ * scanner rejects a code cropped to its edge. It is drawn inside the `viewBox`,
+ * so it stays at any size, including a size set in CSS.
  *
- * `correction` is what buys the middle slot. A code at `H` can lose thirty
- * percent of itself and still read, which is what makes covering the center
- * with a mark safe; at `L` the same mark makes the code unscannable. That is
- * why the slot exists on the same element as the property, and why the default
- * moves when the slot is filled.
+ * `correction` sets how much of the code can be lost. At `H` a code can lose
+ * thirty percent and still scan, so a mark in the center slot is safe. At `L`
+ * the same mark makes the code unscannable. The default is `M`, and `H` when the
+ * `logo` slot is filled.
  *
  * @since 0.1.0
  * @status stable
@@ -36,16 +32,17 @@ export type QrStyle = 'dots' | 'rounded' | 'square';
  * @aliases QR, Barcode, Scan code
  * @documentation https://fusion.dev/helix/components/qr-code
  *
- * @slot logo - A mark for the center, which only reads at a high correction.
+ * @slot logo - A logo for the center. A code with a logo scans only at a high correction level.
  *
- * @csspart code - The square itself.
+ * @csspart code - The square code image.
  * @csspart finders - The three corner squares, which can take their own color.
- * @csspart logo - The box holding the center mark.
- * @csspart modules - Everything but the three corner squares.
+ * @csspart logo - The box that holds the center logo.
+ * @csspart modules - Every module except the three corner squares.
  */
 export declare class HelixHeadlessQrCode extends HelixElement {
     /**
-     * How much of the code can be lost and still read.
+     * The error correction level, which sets how much of the code can be lost
+     * and still scan.
      *
      * `M` by default, which is the level almost every code in the world uses and
      * costs about fifteen percent redundancy. `H` where a mark covers the center,
@@ -55,7 +52,7 @@ export declare class HelixHeadlessQrCode extends HelixElement {
      */
     correction?: QrCorrection;
     /**
-     * What the image is called.
+     * The image's accessible name.
      *
      * Falling back to the value is deliberate: a code almost always holds a URL,
      * and a URL is a better name than "QR code" for a reader who cannot see it.

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

@@ -4,13 +4,12 @@ import { type TemplateResult } from 'lit';
  * @summary A short quotation, set inline with the text around it.
  *
  * @description
- * Renders a real `<q>`, which is what supplies the quotation marks: the browser
- * inserts the right ones for the document's language, and nests them correctly
- * when one quotation sits inside another. Typing the marks into the content
- * instead gets both of those wrong in every language but one.
+ * Renders a real `<q>`, so the browser supplies the quotation marks. It inserts
+ * the correct marks for the document's language and nests them correctly when
+ * one quotation sits inside another. Do not type quotation marks into the
+ * content.
  *
- * A passage set off from the prose rather than run inside it is a blockquote,
- * which is a different element for a different job.
+ * For a passage set off from the surrounding text, use a blockquote.
  *
  * @since 0.1.0
  * @status stable

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

@@ -3,27 +3,25 @@ import { type PropertyValues, type TemplateResult } from 'lit';
 import { HelixHeadlessRadio } from '../root/radio-root.js';
 declare const HelixHeadlessRadioGroup_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
 /**
- * @summary A set of choices where exactly one is the answer.
+ * @summary A set of radios where exactly one can be chosen.
  *
  * @description
- * **The group is the control, and the radios are its options.** This is the
- * asymmetry with checkboxes and it comes from what a form submits: a set of
- * checkboxes is several answers and each box submits its own, while a set of
- * radios is one answer, so the group owns the `name`, the `value` and the
- * validity, and a lone radio outside a group is not a control at all.
+ * The group is the form control, and the radios are its options. A set of
+ * radios submits one answer, so the group owns the `name`, the `value`, and the
+ * validity. A radio outside a group is not a control. Checkboxes work the other
+ * way: each checkbox submits its own answer.
  *
- * Which is also why `MixinField` lands here and not on `Radio`: the label, the
- * hint and the message are about the question, and the question is the set.
+ * `MixinField` applies to the group for the same reason. The label, the hint,
+ * and the message describe the question, and the question belongs to the set.
  *
- * Selection travels up and state travels down. An item announces that it was
- * chosen, the group decides whether that stands, and the group writes
- * `selected` onto every item. Nothing sets itself, so there is one answer to
- * "which one is on" rather than one per item.
+ * Selection moves up and state moves down. A radio dispatches an event when it
+ * is chosen, the group determines whether the choice stands, and the group
+ * writes `selected` onto every radio. The group is the one source of which
+ * radio is on.
  *
- * `value` and `defaultValue` are separate for the reason `checked` and
- * `defaultChecked` are: `value` is the answer now, `defaultValue` is what the
- * markup asked for, which is where a reset returns and is gone the moment
- * anything is chosen.
+ * `value` is the current answer. `defaultValue` is what the markup declared:
+ * the value until something is chosen, and where a reset returns. The two work
+ * like `checked` and `defaultChecked`.
  *
  * @since 0.1.0
  * @status stable
@@ -31,24 +29,24 @@ declare const HelixHeadlessRadioGroup_base: (new (...args: any[]) => import("@fu
  * @documentation https://fusion.dev/helix/components/radio
  *
  * @slot - The radios.
- * @slot hint - Richer than a string.
- * @slot label - Richer than a string, where the question is more than one.
+ * @slot hint - The help text under the group, for content richer than a string.
+ * @slot label - The group's label, for a question that needs more than a string.
  *
- * @event {Event} change - Announced once the value has moved.
- * @event {HelixBeforeChangeEvent} helix-before-change - Fired when the answer changes, and cancelable.
- * @event {HelixSelectEvent} helix-select - Fired when an answer is chosen. Dispatched by the radio and listened for here, because the group is what a consumer holds. Cancelable: refusing it takes the decision and nothing moves.
- * @event {Event} input - Announced once the value has moved.
+ * @event {Event} change - Fired after the value changes.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired when the choice changes. Cancelable: call `preventDefault()` to keep the current choice.
+ * @event {HelixSelectEvent} helix-select - Fired when a radio is chosen. The radio sends it, and you listen for it on the group. Cancelable: call `preventDefault()` to keep the current choice.
+ * @event {Event} input - Fired after the value changes.
  *
- * @csspart feedback - What is wrong with it.
- * @csspart hint - Help under the set.
- * @csspart items - The choices, which is what `orientation` lays out.
- * @csspart label - The question, over the set.
+ * @csspart feedback - The error message under the group.
+ * @csspart hint - The help text under the group.
+ * @csspart items - The container of the choices, laid out by `orientation`.
+ * @csspart label - The label above the group.
  *
- * @cssstate invalid - While there is feedback to show: the platform's verdict, or the consumer's `feedback`.
+ * @cssstate invalid - The group has an error to show, from the browser's validation or from your `feedback`.
  */
 export declare class HelixHeadlessRadioGroup extends HelixHeadlessRadioGroup_base {
     /**
-     * Which way the choices run. A column reads one line per answer.
+     * The direction the choices run. `vertical` puts one choice on each line.
      *
      * **Optional rather than defaulted, which is not a style preference.** A
      * reflecting property with a default writes its attribute onto every host the