@fusion.dev/helix-headless 0.105.0 → 0.107.0

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

@@ -3,29 +3,28 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 import '../../tooltip/index.js';
 declare const HelixHeadlessHeatmap_base: typeof HelixElement & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinChartSourceInterface);
 /**
- * @summary A strip of cells colored by how each one went: uptime, contributions, activity.
+ * @summary A strip of cells, each colored by its reading, for uptime, contributions, or activity.
  *
  * @description
- * **One family covers both readings.** `rows="1"` is a status strip, `rows="7"`
- * is a contribution graph, and a cell that takes a tone covers both: GitHub's
- * contribution graph is five discrete levels rather than a gradient.
+ * A grid of cells, each colored by a tone. `rows="1"` makes a status strip, and
+ * `rows="7"` makes a contribution graph. GitHub's contribution graph uses five
+ * discrete levels, which a set of tones covers.
  *
- * **What it cannot be is a bar chart with flat values**, and the data model is
- * what closes that: chart color is per *series* everywhere else here, so ninety
- * differently colored cells would be ninety series.
+ * Color in a heatmap is per cell. In every other Helix chart, color is per
+ * series, so ninety differently colored cells would need ninety series.
  *
- * **The data is a real `<table>` named by `for`**, the convention every chart
- * in this library uses, and it is the accessible representation. Hide it with
- * `data-hidden-visually` and the reading is still there.
+ * **The data is a real `<table>` named by `for`**, as in every Helix chart, and
+ * the table is the accessible representation. Hide it with
+ * `data-hidden-visually`, and screen readers still read it.
  *
  * A cell takes its tone from its own `data-tone`, or from `thresholds` and
- * `tones` bucketing its value. The cell's own wins, so a page that already
- * knows a day was degraded does not encode that as a number to be decoded.
+ * `tones` applied to its value. `data-tone` wins, so when you already know a
+ * day was degraded, you can set the tone directly.
  *
- * **A tone is a name this tier never resolves.** `tone="success"` writes
- * `--heatmap-tone: var(--heatmap-tone-success)` and stops, so what a name is
- * worth is the answering tier's to say. Reaching for `var(--helix-color-*)`
- * here is the dependency the tiers exist to prevent.
+ * **The headless tier does not resolve tone names.** A tone named `success`
+ * writes `--heatmap-tone: var(--heatmap-tone-success)`, and the styled tier or
+ * your own stylesheet defines that property. The headless tier does not use
+ * `var(--helix-color-*)`.
  *
  * @since 0.1.0
  * @status stable
@@ -35,12 +34,12 @@ declare const HelixHeadlessHeatmap_base: typeof HelixElement & (new (...args: an
  *
  * @slot end - Below the strip, at the trailing edge: usually the newest date.
  * @slot start - Below the strip, at the leading edge: usually the oldest date.
- * @slot summary - Below the strip, in the middle: the reading over the range drawn.
+ * @slot summary - Below the strip, in the middle: a summary of the range shown.
  *
- * @event {HelixResizeEvent} helix-resize - Fired when the number of cells drawn changes, carrying that number.
+ * @event {HelixResizeEvent} helix-resize - Fired when the number of cells drawn changes, with the new number.
  *
  * @csspart cell - One reading.
- * @csspart empty - Shown when the table has no readings in it, and not before the table can be read at all: on a server, and while hydrating what one sent, there is no document to resolve `for` in and nothing is known yet.
+ * @csspart empty - Shown when the table has no readings. It stays hidden until the table can be read: on the server and during hydration, there is no document to resolve `for` in.
  * @csspart end - The trailing slot's box.
  * @csspart footer - The three-slot row under the strip.
  * @csspart mark - The invisible point the tooltip is anchored to.
@@ -50,33 +49,33 @@ declare const HelixHeadlessHeatmap_base: typeof HelixElement & (new (...args: an
  * @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 reading'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.
  *
- * @cssproperty --heatmap-rows - How many rows the strip lays out. Written by the component from the data, read by the tier that draws it.
- * @cssproperty --heatmap-tone - The tone of the cell this is set on. Written by the component, read by the sheet that paints.
- * @cssproperty --heatmap-tone-1 - The quietest step of the magnitude ramp, reached by `tones="1 …"`.
+ * @cssproperty --heatmap-rows - How many rows the strip lays out. The component writes it from the data, and the stylesheet that draws the strip reads it.
+ * @cssproperty --heatmap-tone - The tone of the cell it is set on. The component writes it, and the stylesheet that paints the cell reads it.
+ * @cssproperty --heatmap-tone-1 - The weakest step of the magnitude ramp, used by `tones="1 …"`.
  * @cssproperty --heatmap-tone-2 - The second step of the magnitude ramp.
  * @cssproperty --heatmap-tone-3 - The third step of the magnitude ramp.
  * @cssproperty --heatmap-tone-4 - The fourth step of the magnitude ramp.
- * @cssproperty --heatmap-tone-5 - The loudest step of the magnitude ramp.
- * @cssproperty --heatmap-tone-accent - What `accent` is worth.
- * @cssproperty --heatmap-tone-danger - What `danger` is worth.
- * @cssproperty --heatmap-tone-info - What `info` is worth.
- * @cssproperty --heatmap-tone-muted - What `muted` is worth: the quiet ground, for a bucket that means nothing happened.
- * @cssproperty --heatmap-tone-primary - What `primary` is worth.
- * @cssproperty --heatmap-tone-success - What `success` is worth, as a name or a `data-tone`.
- * @cssproperty --heatmap-tone-warning - What `warning` is worth.
+ * @cssproperty --heatmap-tone-5 - The strongest step of the magnitude ramp.
+ * @cssproperty --heatmap-tone-accent - The color of the `accent` tone.
+ * @cssproperty --heatmap-tone-danger - The color of the `danger` tone.
+ * @cssproperty --heatmap-tone-info - The color of the `info` tone.
+ * @cssproperty --heatmap-tone-muted - The color of the `muted` tone: a quiet background, for a bucket that means nothing happened.
+ * @cssproperty --heatmap-tone-primary - The color of the `primary` tone.
+ * @cssproperty --heatmap-tone-success - The color of the `success` tone, named in `tones` or in `data-tone`.
+ * @cssproperty --heatmap-tone-warning - The color of the `warning` tone.
  */
 export declare class HelixHeadlessHeatmap extends HelixHeadlessHeatmap_base {
     /**
@@ -87,8 +86,8 @@ export declare class HelixHeadlessHeatmap extends HelixHeadlessHeatmap_base {
      */
     emptyText: string;
     /**
-     * Space between cells, in CSS pixels, for the same reason `min-cell` is a
-     * number.
+     * Space between cells, in CSS pixels. It is a number for the same reason
+     * `min-cell` is.
      */
     gap: number;
     /**
@@ -132,7 +131,7 @@ export declare class HelixHeadlessHeatmap extends HelixHeadlessHeatmap_base {
      */
     thresholds: string;
     /**
-     * Tone per bucket, in the same order as `thresholds`.
+     * The tone for each bucket, in the same order as `thresholds`.
      *
      * A name, resolved as `--heatmap-tone-<name>` by whichever tier answers.
      * **`"1"` through `"5"` are a ramp and everything else is a category**, which

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

@@ -2,31 +2,27 @@ import { HelixElement } from '@fusion.dev/helix-core';
 import { type HelixIcon } from '@fusion.dev/helix-icons';
 import { nothing, type TemplateResult } from 'lit';
 /**
- * @summary Renders a named icon from the Helix set.
+ * @summary A named icon from the Helix set.
  *
  * @description
- * The set is Phosphor, drawn on a 256 box at stroke-width 16, and each glyph is
- * rendered as its own inner markup rather than as a single path. Most icons are
- * several elements at once, each with its own stroke and fill, so a one-path
- * model would draw a fraction of the set and quietly drop the rest.
+ * The icons are Phosphor, drawn on a 256 box at stroke-width 16. Each glyph
+ * renders its full inner markup, because most icons are several elements, each
+ * with its own stroke and fill.
  *
- * **The markup is trusted by construction.** It is generated at build time from
- * SVG files in this repository, never from anything a user supplies, which is
- * what makes `unsafeSVG` the right tool rather than a risk.
+ * The markup is generated at build time from SVG files in this repository and
+ * never comes from user input, so rendering it with `unsafeSVG` is safe.
  *
- * The `<svg>` carries `fill="currentColor"` because the generator keeps only
- * the inner markup and discards the source's own root tag, and that tag is
- * where Phosphor puts its fill. Without it, every solid glyph in the set, 65 of
- * them, falls back to the SVG default of black and disappears on a dark page.
- * Shapes that set their own `fill` or `stroke` are unaffected, which is why the
- * outline icons looked fine and hid this.
+ * The `<svg>` carries `fill="currentColor"`. The generator keeps only the inner
+ * markup, and Phosphor sets its fill on the root tag that the generator
+ * discards. Without it, the 65 solid glyphs fall back to black and disappear on
+ * a dark background. Shapes that set their own `fill` or `stroke` are
+ * unaffected.
  *
- * A name with no match renders nothing at all instead of an empty box, so a
- * typo cannot leave a hole in a layout that looks deliberate.
+ * A name with no match renders nothing.
  *
- * An icon is decorative by default and hidden from assistive technology. Give
- * it a `label` only when the icon is the sole carrier of meaning, such as
- * inside a button with no text.
+ * An icon is decorative by default and hidden from assistive technology. Set
+ * `label` only when the icon is the only carrier of meaning, such as in a
+ * button with no text.
  *
  * @since 0.1.0
  * @status stable
@@ -38,7 +34,7 @@ import { nothing, type TemplateResult } from 'lit';
  */
 export declare class HelixHeadlessIcon extends HelixElement {
     /**
-     * The icon itself, for a consumer who imported one.
+     * The icon to draw, as an object you import.
      *
      * **The scalable door, and the one this library uses internally.** An icon is
      * data, `{ content, name, viewBox }`, so a value imported by name ships one
@@ -53,11 +49,13 @@ export declare class HelixHeadlessIcon extends HelixElement {
      */
     icon?: HelixIcon;
     /**
-     * Accessible name, for an icon that is not decorative.
+     * The icon's name, read by screen readers. Set it for an icon that is not
+     * decorative.
      */
     label: string;
     /**
-     * Turns the glyph round on a right-to-left page, for an arrow meaning forward or back.
+     * Flips the glyph on a right-to-left page. Use it for an arrow that means
+     * forward or back.
      *
      * Asked for rather than inferred from the name. The names are physical, and
      * `arrow-left` drawn pointing right on an Arabic page would be the icon
@@ -65,7 +63,7 @@ export declare class HelixHeadlessIcon extends HelixElement {
      */
     mirror: boolean;
     /**
-     * Name of the icon in the Helix set.
+     * The name of the icon in the Helix set.
      *
      * **A lookup, and the reason both this and `icon` exist.** A name is a string,
      * so it is what markup can carry, and resolving one means an index of the

package/dist/icon-button/root/icon-button-root.d.ts

@@ -1,23 +1,21 @@
 import { HelixHeadlessButton } from '../../button/root/button-root.js';
 /**
- * @summary A button whose content is an icon, and which must be named.
+ * @summary A button whose content is an icon, named by its `label`.
  *
  * @description
- * Everything a button does, with one thing added and it is the reason this is
- * an element rather than a note on `Button`: **an icon-only control has no
- * accessible name unless it is given one.** A button whose content is a glyph
- * announces as "button" and nothing else, which is the single most common way a
- * toolbar becomes unusable without sight. `label` is not optional in practice,
- * and having a component that says so is what makes it reviewable.
+ * A button with an icon for its content. Always set `label`: an icon-only
+ * control has no accessible name unless you give it one, and a button whose
+ * content is a glyph is announced as "button" and nothing else. A separate
+ * component with a `label` makes the name something a review can check.
  *
- * **Registered, so it can be rendered and not only subclassed.** Anything in
- * this tier needing an icon button, such as an announcement's dismiss control,
- * renders `helix-headless-icon-button` rather than reaching into the styled tier
- * for a tag that would never upgrade.
+ * The element is registered, so other headless components can render
+ * `helix-headless-icon-button`, for example as an announcement's dismiss
+ * control. They do not depend on a styled tag, which would never upgrade in
+ * this tier.
  *
- * Top-level rather than `Button.Icon`, because a namespace means composition
- * and an icon-only button is not part of a button. It is a button with
- * different content and a different shape, which makes it its own component.
+ * Icon Button is a top-level component. A namespace such as `Button.Icon` would
+ * mean a part of a button, and an icon-only button is a complete button with
+ * different content and a different shape.
  *
  * @since 0.1.0
  * @status stable

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

@@ -1,18 +1,16 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
- * @summary A picture that says whether it arrived.
+ * @summary An image that shows a placeholder while it loads and a fallback if it fails.
  *
  * @description
- * **An element rather than a recipe, because of the part CSS cannot do.**
- * Reserving the box is `aspect-ratio` and needs nothing from anybody. What
- * cannot be written as a rule is *when the picture arrived*: a stylesheet has
- * no way to know, and no way to hear that it never will. So this owns three
- * states and the two events that move between them, and leaves the box to the
- * stylesheet.
+ * Image handles the part CSS cannot: when the picture has loaded, or that it
+ * failed. `aspect-ratio` in your stylesheet reserves the box. The element
+ * tracks three states and relays the two events that move between them, and
+ * leaves the box to the stylesheet.
  *
- * **The placeholder is a slot with nothing in it by default.** A default of
- * `Skeleton` would make this tier depend on a component it does not ship.
+ * The `placeholder` slot is empty by default, so the headless tier does not
+ * depend on `Skeleton`, which it does not ship.
  *
  * @since 0.1.0
  * @status stable
@@ -20,31 +18,31 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @aliases Picture, Img, Figure
  * @documentation https://fusion.dev/helix/components/image
  *
- * @slot fallback - Shown instead of it, if it never does.
- * @slot placeholder - Shown until the picture arrives.
+ * @slot fallback - Shown in place of the image if it fails to load.
+ * @slot placeholder - Shown until the image loads.
  *
- * @event {Event} error - Relayed for the same reason.
- * @event {Event} load - Relayed, because the platform's own does not escape.
+ * @event {Event} error - The image failed to load. Relayed from the inner image, whose own event stays inside the shadow root.
+ * @event {Event} load - The image loaded. Relayed from the inner image, whose own event stays inside the shadow root.
  *
- * @csspart fallback - What stands in when it fails.
- * @csspart image - The picture itself.
- * @csspart placeholder - What stands in until it arrives.
+ * @csspart fallback - The fallback, shown when the image fails to load.
+ * @csspart image - The image itself.
+ * @csspart placeholder - The placeholder, shown until the image loads.
  */
 export declare class HelixHeadlessImage extends HelixElement {
     /**
-     * What it shows, for a reader who cannot see it.
+     * A text description of the image, read by screen readers.
      *
      * Empty is a real answer and means decoration. Omitting the attribute is not
      * the same thing: a reader with nothing to read announces the file name.
      */
     alt: string;
     /**
-     * How the picture is fetched across origins, which decides whether a canvas
-     * can read it.
+     * How the image is fetched across origins. It decides whether a canvas can
+     * read the image.
      */
     crossOrigin: 'anonymous' | 'use-credentials' | null;
     /**
-     * Whether the browser may decode off the main thread.
+     * Whether the browser may decode the image off the main thread.
      *
      * `async` is the resting value and right for a picture in a page. `sync` is
      * what a consumer reaches for when the picture is about to be composited with
@@ -52,7 +50,8 @@ export declare class HelixHeadlessImage extends HelixElement {
      */
     decoding: 'async' | 'auto' | 'sync';
     /**
-     * How urgently to fetch it, for the one picture that is the page.
+     * How urgently the browser fetches the image. Set `high` on the main image
+     * of a page.
      *
      * The hero of a page is usually its largest contentful paint, and the fix is
      * two attributes rather than one: `loading="eager"` stops it waiting for the
@@ -62,7 +61,8 @@ export declare class HelixHeadlessImage extends HelixElement {
      */
     fetchPriority: 'auto' | 'high' | 'low';
     /**
-     * Whether to wait until it is nearly on screen.
+     * Whether the image waits to load until it is nearly on screen. Defaults to
+     * `lazy`.
      *
      * `lazy` by default, which is the opposite of the platform's, because a
      * picture worth putting in a component is usually below the fold and the one
@@ -74,19 +74,19 @@ export declare class HelixHeadlessImage extends HelixElement {
      */
     referrerPolicy: string;
     /**
-     * How much of the line it will take, passed through to the picture.
+     * The width the image takes in the layout, passed through to the inner image.
      */
     sizes: string;
     /**
-     * Where the picture is.
+     * The URL of the image.
      */
     src: string;
     /**
-     * The candidate widths, passed through to the picture.
+     * The candidate files and their widths, passed through to the inner image.
      */
     srcset: string;
     /**
-     * Whether the picture is on its way, here, or never coming.
+     * The loading state: `loading`, `loaded`, or `error`.
      *
      * Read-only to a consumer: it is a report rather than a setting.
      *
@@ -185,13 +185,13 @@ export declare class HelixHeadlessImage extends HelixElement {
      * nowhere else on the page.
      */
     private get image();
-    /** Whether the picture has finished arriving, however it went. */
+    /** Whether the image has finished loading, successfully or not. */
     get complete(): boolean;
-    /** Which candidate the browser actually chose out of `srcset`. */
+    /** The candidate the browser chose from `srcset`. */
     get currentSrc(): string;
-    /** The picture's own height in pixels, and zero until it has arrived. */
+    /** The image's intrinsic height in pixels. Zero until the image loads. */
     get naturalHeight(): number;
-    /** The picture's own width in pixels, and zero until it has arrived. */
+    /** The image's intrinsic width in pixels. Zero until the image loads. */
     get naturalWidth(): number;
     protected render(): TemplateResult;
 }

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

@@ -4,25 +4,23 @@ import { type PropertyValues, type TemplateResult } from 'lit';
 export type InputType = 'email' | 'number' | 'password' | 'search' | 'tel' | 'text' | 'url';
 declare const HelixHeadlessInput_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
 /**
- * @summary A single line of text a reader types into.
+ * @summary A field for a single line of text.
  *
  * @description
- * Renders a real `<input>`, so the caret, selection, autofill, spellcheck, the
- * password manager and the on-screen keyboard a phone chooses are all the
- * platform's. It serializes into the server's markup, so the field is usable
- * before any script loads.
+ * Renders a real `<input>`, so the caret, selection, autofill, spellcheck,
+ * password managers, and a phone's on-screen keyboard all work natively. The
+ * field is in the server markup, so it works before any script loads.
  *
- * **The input inside a shadow root submits nothing**, the form being on the
- * other side of the boundary. The host is form-associated instead and reports
- * its own value through `ElementInternals`, which also carries validity and
- * answers a form reset.
+ * An input inside a shadow root does not submit with a form outside it, so the
+ * host is form-associated and reports its value through `ElementInternals`.
+ * That also carries validity and handles a form reset.
  *
- * `value` and `defaultValue` are separate the way `checked` and
- * `defaultChecked` are: `value` is what is in the field now, `defaultValue` is
- * what the markup asked for and where a reset returns to.
+ * `value` and `defaultValue` work like `checked` and `defaultChecked`. `value`
+ * is what is in the field now, and `defaultValue` is the value from the markup,
+ * which a reset restores.
  *
- * **Validity is the platform's.** `type` and `required` are set on the real
- * input and its `validity` is copied onto the host.
+ * Validity comes from the browser. `type` and `required` are set on the real
+ * input, and its `validity` is copied to the host.
  *
  * @since 0.1.0
  * @status stable
@@ -33,34 +31,35 @@ declare const HelixHeadlessInput_base: (new (...args: any[]) => import("@fusion.
  * @slot end - After the text, for an icon or a unit.
  * @slot start - Before the text, for an icon or a prefix.
  *
- * @event {Event} change - Relayed from the input once the reader has finished.
- * @event {HelixBeforeChangeEvent} helix-before-change - Fired as the text changes, and cancelable.
- * @event {Event} input - Announced once the value has moved.
+ * @event {Event} change - Sent when the user finishes changing the value. Relayed from the native input.
+ * @event {HelixBeforeChangeEvent} helix-before-change - The text is about to change. Cancelable: cancel it to keep the current text.
+ * @event {Event} input - Fired as the value changes.
  *
  * @csspart clear - The button that empties the field.
- * @csspart control - The input itself.
- * @csspart feedback - What is wrong with it.
- * @csspart field - The box holding everything.
- * @csspart hint - Help under the field, while nothing is wrong.
- * @csspart label - The question, over the field.
+ * @csspart control - The native input.
+ * @csspart feedback - The message that says what is wrong with the value.
+ * @csspart field - The box around the input, its slots, and its buttons.
+ * @csspart hint - Help text under the field, shown while there is no feedback.
+ * @csspart label - The label above the field.
  * @csspart reveal - The button that shows and hides a password.
- * @csspart reveal-pressed - The reveal button while the password shows, beside `reveal`.
+ * @csspart reveal-pressed - The reveal button while the password is shown, added beside `reveal`.
  *
- * @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 HelixHeadlessInput extends HelixHeadlessInput_base {
     protected readonly aria: AriaForwardController;
     /** Typed or dragged, so every edit is announced. See `announcesInput`. */
     protected readonly announcesInput = true;
     /**
-     * What the browser may autofill here, as one of the platform's own tokens.
+     * What the browser may autofill in the field, as an HTML `autocomplete`
+     * token.
      *
      * Empty leaves the attribute off, which is the browser's default. Set it to
      * a token like `email` or `bday` to ask for autofill, or to `off` to refuse.
      */
     autocomplete: string;
     /**
-     * Whether the field offers a button that empties it.
+     * Whether the field shows a button that empties it.
      *
      * Shown only while there is something to clear, because a control that does
      * nothing is worse than no control: a reader who presses it and sees no
@@ -69,7 +68,7 @@ export declare class HelixHeadlessInput extends HelixHeadlessInput_base {
      */
     clearable: boolean;
     /**
-     * What the clear button is called, since an icon has no name of its own.
+     * The accessible name of the clear button, which shows only an icon.
      */
     clearLabel: string;
     /**
@@ -89,13 +88,14 @@ export declare class HelixHeadlessInput extends HelixHeadlessInput_base {
      */
     pattern: string;
     /**
-     * Shown while the field is empty.
+     * The text shown while the field is empty.
      *
      * Not a label: it goes when typing starts.
      */
     placeholder: string;
     /**
-     * Whether the field refuses input while still submitting its value.
+     * Whether the field blocks editing. A read-only field still submits its
+     * value.
      *
      * **The attribute is `readonly`, which is the platform's spelling.** A
      * camelCase property needs an explicit `attribute`, and dash-casing a word
@@ -128,7 +128,7 @@ export declare class HelixHeadlessInput extends HelixHeadlessInput_base {
     /** Focus is delegated to the input, so the host is never the focus target. */
     static shadowRootOptions: ShadowRootInit;
     /**
-     * The caret and the selection, under the platform's own names.
+     * The direction of the selection, as the native input names it.
      *
      * The `<input>` is inside this shadow root, so a consumer had no way to ask
      * where the selection is, let alone move it: `querySelector` does not cross
@@ -149,8 +149,8 @@ export declare class HelixHeadlessInput extends HelixHeadlessInput_base {
     get selectionStart(): number;
     set selectionStart(at: number);
     /**
-     * Selects a range, which is the one operation the three accessors above
-     * cannot express between them.
+     * Selects the range from `start` to `end` in one call, which setting
+     * `selectionStart` and `selectionEnd` one at a time cannot always do.
      *
      * Setting `selectionStart` past the current `selectionEnd` drags the end
      * along, so the two writes a consumer would make in sequence do not compose
@@ -185,7 +185,7 @@ export declare class HelixHeadlessInput extends HelixHeadlessInput_base {
     private readonly handleChange;
     /** Reports the value and the validity the host stands behind. */
     private sync;
-    /** Puts the caret in the field, the way a label pointing at one would. */
+    /** Puts the caret in the field, as clicking its label does. */
     focus(options?: FocusOptions): void;
     /** Selects everything in the field. */
     select(): void;
@@ -208,13 +208,14 @@ export declare class HelixHeadlessInput extends HelixHeadlessInput_base {
      */
     reveal: boolean;
     /**
-     * What the reveal toggle is called.
+     * The accessible name of the reveal toggle.
      *
      * The state is `aria-pressed`, not this.
      */
     revealLabel: string;
     /**
-     * What the field accepts, which decides the keyboard and the validation.
+     * The kind of text the field accepts. It sets the on-screen keyboard and the
+     * validation.
      *
      * **Not reflected.** Reflection exists so a selector can reach a value, and
      * no stylesheet in this repository selects on `type`. Reflecting it writes

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

@@ -4,21 +4,18 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @summary A keyboard key or chord, set inline with text.
  *
  * @description
- * Renders a real `<kbd>`, so the passage still means "press this" to anything
- * reading the markup.
+ * Renders a `<kbd>` element.
  *
- * **One key per element, with `keys` as the stated exception.** A sequence is
- * several of these with the separator written between them as ordinary text,
- * because that separator is prose: "then" in a sequence, "plus" in a chord, and
- * a component inserting one would have to guess which.
+ * Each element holds one key, except when you use `keys`. For a sequence or a
+ * chord, write one element per key and put the separator between them as text,
+ * such as "then" or "plus".
  *
- * **`keys` exists because the glyphs were being typed by hand and were wrong.**
- * A literal `⌘K` in a template tells a reader on Windows to press a key their
- * keyboard does not have, and nothing catches it. Given `mod` this renders
- * `⌘K` on Apple and `Ctrl+K` everywhere else.
+ * `keys` renders the right glyphs for the platform. Given `mod`, it renders
+ * `⌘K` on Apple devices and `Ctrl+K` everywhere else. A `⌘K` typed into a
+ * template is wrong for anyone on Windows.
  *
- * **`within` is what binds it, and it is absent by default**, so this draws a
- * key and listens for nothing unless asked.
+ * The element binds the shortcut only when `within` is set. By default it draws
+ * the key and listens for nothing.
  *
  * @since 0.1.0
  * @status stable
@@ -28,13 +25,13 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  *
  * @slot - The key's label, where `keys` is not set.
  *
- * @event {HelixShortcutEvent} helix-shortcut - Fired when the chord is pressed, and cancelable.
+ * @event {HelixShortcutEvent} helix-shortcut - The chord was pressed. Cancelable: cancel it to let the key press keep its usual effect.
  *
  * @csspart kbd - The key.
  */
 export declare class HelixHeadlessKbd extends HelixElement {
     /**
-     * The chord, written plainly: `mod+k`, `shift+?`, `/`.
+     * The key or chord to show, such as `mod+k`, `shift+?`, or `/`.
      *
      * `mod` is the platform's own command modifier, which is the reason to write
      * a chord here rather than a glyph: it is the one token whose right answer
@@ -42,7 +39,8 @@ export declare class HelixHeadlessKbd extends HelixElement {
      */
     keys: string;
     /**
-     * Where the chord is listened for, and whether it is listened for at all.
+     * Where the chord is listened for. `control` listens inside the control the
+     * key sits in, and `document` listens on the whole page.
      *
      * Unset draws a key and binds nothing.
      *