@fusion.dev/helix-headless 0.105.0 → 0.107.0

package/dist/color-picker/root/color-picker-root.d.ts

@@ -5,23 +5,21 @@ import '../../button-group/index.js';
 import '../../slider/index.js';
 declare const HelixHeadlessColorPicker_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & typeof HelixFormElement;
 /**
- * @summary Picks a color, from a square and two ramps.
+ * @summary A color picker made of a square and two ramps.
  *
  * @description
- * **The picker itself, with no field around it.** Color Input is this element
- * in a panel behind a text field; a settings pane or a toolbar wants the picker
- * flat on the page with nothing to open.
+ * The picker on its own, with no field around it, for a settings pane or a
+ * toolbar. Color Input shows this element in a panel behind a text field.
  *
- * **The square is two real range inputs.** Saturation and brightness are each
- * an `<input type="range">`, laid over the square and made invisible, and the
- * handle is drawn from their values. The keyboard, the announcements and the
- * touch targets are the platform's, and there is no `role="application"`.
+ * The saturation and brightness square is two `<input type="range">` elements,
+ * laid over the square and made invisible, and the handle is drawn from their
+ * values. The keyboard behavior, the announcements, and the touch targets come
+ * from the platform, and there is no `role="application"`.
  *
- * **The working model is HSB, and the value is derived from it.** The reverse
- * loses colors: black is `brightness: 0`, whose hue and saturation are both
- * undefined, so dragging to the bottom of the square and back would give gray
- * where there had been red. A value arriving from outside is read into the
- * model once.
+ * The picker works in HSB and derives the value from it. A value set from
+ * outside is read into the model once. Black is `brightness: 0`, which has no
+ * hue or saturation, so a model read back from the value would turn red into
+ * gray after you drag to the bottom of the square and back.
  *
  * @since 0.1.0
  * @status stable
@@ -29,49 +27,48 @@ declare const HelixHeadlessColorPicker_base: (new (...args: any[]) => import("@f
  * @aliases Color, ColorArea, Swatch picker
  * @documentation https://fusion.dev/helix/components/color-picker
  *
- * @slot eyedropper-icon - The glyph on the screen-sampling control, usually a dropper.
+ * @slot eyedropper-icon - The icon on the eyedropper button, usually a dropper.
  *
- * @event {Event} change - Announced once the value has moved.
- * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the color changes. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {Event} change - Fired after the value changes.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the color changes. Cancelable: call `preventDefault()` to keep the current color.
  * @event {HelixCopyEvent} helix-copy - Fired when the color is put on the clipboard.
- * @event {HelixSampleEndEvent} helix-sample-end - The eyedropper has closed, whether or not a color was taken.
- * @event {HelixSampleStartEvent} helix-sample-start - The eyedropper is opening, so anything covering the page should get out of the way.
- * @event {Event} input - Announced once the value has moved.
+ * @event {HelixSampleEndEvent} helix-sample-end - Fired when the eyedropper closes, whether or not a color was taken.
+ * @event {HelixSampleStartEvent} helix-sample-start - Fired as the eyedropper opens. Hide anything that covers the page.
+ * @event {Event} input - Fired after the value changes.
  *
  * @csspart actions - The group holding the eyedropper and the syntax toggle.
  * @csspart channel - One ramp.
  * @csspart channel-control - The range input.
- * @csspart channel-feedback - What is wrong with it.
- * @csspart channel-field - The row: the control and its readout.
- * @csspart channel-hint - Help under the track, while nothing is wrong.
- * @csspart channel-label - The question, over the track.
- * @csspart channel-marker - One mark.
+ * @csspart channel-feedback - The error message for a ramp.
+ * @csspart channel-field - The row that holds a ramp's control and its readout.
+ * @csspart channel-hint - The help text under the track, shown while there is no error.
+ * @csspart channel-label - The label above the track.
+ * @csspart channel-marker - One mark on the track.
  * @csspart channel-marker-label - The value a mark stands at, when `marker-labels` is set.
  * @csspart channel-markers - The row of marks along the track.
- * @csspart channel-output - The current value, shown beside it.
- * @csspart channels - The ramps beside it.
+ * @csspart channel-output - The current value, shown beside the track.
+ * @csspart channels - The ramps beside the sample.
  * @csspart controls - The row under the square.
  * @csspart eyedropper - The control that samples a color from the screen.
- * @csspart eyedropper-button - The inner control.
+ * @csspart eyedropper-button - The button inside `eyedropper`.
  * @csspart footer - The row holding the value and the tools.
  * @csspart format - The control that changes the syntax the value is written in.
- * @csspart format-button - The inner control.
- * @csspart grid - The saturation and brightness square. The mark showing where
- * in the square the color sits is drawn on the square itself, which is
- * `::part(grid)::after` from a consumer's sheet: the two channels are already
- * on the square as `--color-picker-saturation` and `--color-picker-brightness`,
- * so a box would have carried nothing, and this tier ships no CSS.
- * @csspart grid-brightness - The range input for its vertical axis.
+ * @csspart format-button - The button inside `format`.
+ * @csspart grid - The saturation and brightness square. Draw the mark that shows
+ * where the color sits with `::part(grid)::after` in your stylesheet. The
+ * square carries the two channels as `--color-picker-saturation` and
+ * `--color-picker-brightness`, and this tier ships no CSS.
+ * @csspart grid-brightness - The range input for the square's vertical axis.
  * @csspart grid-saturation - The range input for the square's horizontal axis.
- * @csspart sample - The chip of the current color, which copies it when pressed.
+ * @csspart sample - A chip of the current color. Pressing it copies the value.
  * @csspart swatch - One preset.
  * @csspart swatches - The row of presets.
- * @csspart value - The color as text, which can be typed or pasted.
+ * @csspart value - The text field that holds the color. It accepts a typed or pasted color.
  *
  * @cssproperty --color-picker-brightness - The chosen brightness, 0 to 100, as a percentage.
  * @cssproperty --color-picker-hue - The chosen hue, 0 to 360, unitless.
  * @cssproperty --color-picker-saturation - The chosen saturation, 0 to 100, as a percentage.
- * @cssproperty --color-picker-swatch - A color to paint: the current one on the sample, a preset's on each preset.
+ * @cssproperty --color-picker-swatch - The color a chip shows: the current color on the sample, and the preset's color on each preset.
  */
 export declare class HelixHeadlessColorPicker extends HelixHeadlessColorPicker_base {
     /**
@@ -98,11 +95,12 @@ export declare class HelixHeadlessColorPicker extends HelixHeadlessColorPicker_b
      */
     brightnessLabel: string;
     /**
-     * What the sample says for a moment after it copied the value.
+     * The text the sample shows for a moment after it copies the value.
      */
     copiedLabel: string;
     /**
-     * What the sample is called, which copies the value, with `{value}` filled in.
+     * The name of the sample, which copies the value. `{value}` is replaced with
+     * the color.
      */
     copyLabel: string;
     /**
@@ -110,7 +108,7 @@ export declare class HelixHeadlessColorPicker extends HelixHeadlessColorPicker_b
      */
     eyedropperLabel: string;
     /**
-     * The syntax the value is written in: `hex`, `rgb` or `hsl`.
+     * The syntax the value is written in: `hex`, `rgb`, or `hsl`.
      *
      * Only what is written. Everything is read whatever this says, so a picker on
      * `hex` still takes an `rgb()` handed to it and stores the hex for it.
@@ -135,15 +133,17 @@ export declare class HelixHeadlessColorPicker extends HelixHeadlessColorPicker_b
      */
     invalid: boolean;
     /**
-     * Whether the eyedropper is offered where the browser has one.
+     * Hides the eyedropper. Without it, the eyedropper appears in browsers that
+     * support one.
      */
     noEyedropper: boolean;
     /**
-     * Whether the reader may change the format.
+     * Hides the syntax toggle, so the format cannot be changed.
      */
     noFormat: boolean;
     /**
-     * Whether to leave the value out, for a picker whose value is stated elsewhere.
+     * Hides the text field that holds the value. Use it when the value is shown
+     * elsewhere.
      *
      * The row reads the color as text and lets it be typed or pasted, which is
      * what makes this element complete standing on a page: a square and two ramps
@@ -166,7 +166,7 @@ export declare class HelixHeadlessColorPicker extends HelixHeadlessColorPicker_b
      */
     presetsLabel: string;
     /**
-     * Whether the control refuses changes while still submitting its value.
+     * Makes the color read-only. The value is still submitted with the form.
      *
      * **Enforced by refusing every request in one place**, which is the seam this
      * component already has: `requestValue` is what every path here comes through,
@@ -193,7 +193,7 @@ export declare class HelixHeadlessColorPicker extends HelixHeadlessColorPicker_b
      */
     readOnly: boolean;
     /**
-     * Whether the form refuses to submit while no color is chosen.
+     * Requires a color before the form can submit.
      *
      * **A color is exactly as requirable as a date**, which is the comparison
      * that settles it: this element extends `HelixFormElement`, carries `name`
@@ -234,7 +234,7 @@ export declare class HelixHeadlessColorPicker extends HelixHeadlessColorPicker_b
      */
     valueLabel: string;
     /**
-     * What a reader is told when a color is required and none is chosen.
+     * The message shown when a color is required and none is chosen.
      *
      * **Every sentence a control raises in the browser's bubble is a property**,
      * named for the validity flag it reports, so a form in another language
@@ -266,7 +266,7 @@ export declare class HelixHeadlessColorPicker extends HelixHeadlessColorPicker_b
      * which reads back as hue 0 and saturation 0, and the next drag starts gray.
      */
     private owned;
-    /** Where the picker stands: what was moved, or what the value says, or the start. */
+    /** The current color: the last one moved to, the value, or the start color. */
     get color(): Color;
     /**
      * Whether the tools row holds anything at all.
@@ -298,7 +298,7 @@ export declare class HelixHeadlessColorPicker extends HelixHeadlessColorPicker_b
     private settled;
     /** Takes what was typed, and lets the square follow only a whole color. */
     private readonly handleValueInput;
-    /** Refuses every change while read-only. See `readOnly`. */
+    /** Blocks every change while `readOnly` is set. */
     requestValue(next: string): boolean;
     /** Moves part of the model and announces the value that follows from it. */
     private readonly move;
@@ -373,7 +373,7 @@ export declare class HelixHeadlessColorPicker extends HelixHeadlessColorPicker_b
      */
     private reportRequired;
     protected updated(changed: import('lit').PropertyValues): void;
-    /** Puts the keyboard on the square, which is the control a reader wants. */
+    /** Moves focus to the square. */
     focus(options?: FocusOptions): void;
     /**
      * One of the ramps under the square.

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

@@ -4,34 +4,29 @@ import '../../listbox/index.js';
 import '../../tag/index.js';
 declare const HelixHeadlessCombobox_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinTokensInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
 /**
- * @summary A field that filters a list as it is typed into.
+ * @summary A text field that filters a list of options as you type.
  *
  * @description
- * **The list is `Listbox`, and the filtering is its own.** It owns narrowing,
- * the empty state, the highlight, `aria-activedescendant` and scrolling an
- * option into view. What is left for this element is the field, the panel and
- * the traffic between them.
+ * The list is a `Listbox`, which handles filtering, the empty state, the
+ * highlight, `aria-activedescendant`, and scrolling an option into view. This
+ * element handles the field, the panel, and the communication between them.
  *
- * **The text and the value are two things.** What a reader types is a filter:
- * it narrows the list and is thrown away. The value is whichever option they
- * then choose, and the field is rewritten to that option's words once they
- * have. The filter is cleared on close, so a reopened control does not start
- * from the last visit's leftovers.
+ * The typed text and the value are separate. The text is a filter: it narrows
+ * the list and is then discarded. The value is the option you choose, and the
+ * field then shows that option's text. The filter clears on close, so a
+ * reopened combobox starts from the whole list.
  *
- * **Focus stays in the field, which is the whole of what a combobox is.** The
- * arrows move the list without leaving the text, through the listbox's public
- * `navigate`. `role="combobox"` is on the input rather than on a wrapper,
- * because the thing the pattern describes is the text field.
+ * Focus stays in the text field. The arrow keys move through the list with the
+ * listbox's public `navigate` method. `role="combobox"` is on the input itself.
  *
- * **With `multiple`, the chosen options are tags in the field**, one object per
- * answer, each with its own remove control. The panel stays open while more
- * than one can be chosen and the filter clears on each choice, so the next pick
- * starts from the whole list.
+ * With `multiple`, each chosen option is a tag in the field with its own remove
+ * control. The panel stays open and the filter clears after each choice, so the
+ * next choice starts from the whole list.
  *
- * **`creatable` announces, and does not write.** The options are the consumer's
- * light DOM and nothing here puts an element into it: a component that grew the
- * consumer's markup would be one their framework re-renders over. It offers the
- * row and fires the event; adding the option is the consumer's.
+ * With `creatable`, the combobox offers a create row and fires `helix-create`.
+ * It does not add the option. The options are your light DOM, and your
+ * framework would re-render over an element the combobox inserted, so add the
+ * option in your event handler.
  *
  * @since 0.1.0
  * @status stable
@@ -40,38 +35,38 @@ declare const HelixHeadlessCombobox_base: (new (...args: any[]) => import("@fusi
  * @documentation https://fusion.dev/helix/components/combobox
  *
  * @slot - The options.
- * @slot end - After it, for a unit or a clear button.
- * @slot indicator - Replaces the caret saying the field opens.
+ * @slot end - After the text, for a unit or a clear button.
+ * @slot indicator - Replaces the caret that shows the field opens a list.
  * @slot start - Before the text, for an icon.
  *
- * @event {Event} change - Announced once the value has moved.
- * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the chosen option 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 panel opens. Cancelable: refusing it takes the decision and nothing moves.
- * @event {HelixCreateEvent} helix-create - Fired when the reader asks for something the list does not hold, and cancelable.
- * @event {HelixFilterEvent} helix-filter - Fired as the reader types, carrying the text the list is being narrowed to. Cancelable: refusing it leaves the list whole, and is how a consumer takes the filtering for themselves.
- * @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 - Fired before the chosen option changes. Cancelable: cancel it to keep the current option.
+ * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the panel closes. Cancelable: cancel it to keep the panel open.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the panel opens. Cancelable: cancel it to keep the panel closed.
+ * @event {HelixCreateEvent} helix-create - Fired when the user adds a value that is not in the list. Cancelable.
+ * @event {HelixFilterEvent} helix-filter - Fired as the user types, with the text the list is filtered by. Cancelable: cancel it to leave the list unfiltered and do the filtering yourself.
+ * @event {Event} input - Fired after the value changes.
+ * @event {Event} toggle - Fired when the panel opens or closes, with `newState` and `oldState`.
  *
  * @csspart control - The text field itself.
  * @csspart create - The row offering to add what was typed.
- * @csspart feedback - What is wrong with it.
+ * @csspart feedback - The message that explains what is wrong with the value.
  * @csspart field - The box around the text and its marks.
- * @csspart hint - Help under the field, while nothing is wrong.
+ * @csspart hint - Help text under the field, shown while there is no error.
  * @csspart indicator - The caret.
- * @csspart label - The question, over the field.
- * @csspart listbox - The list inside it.
+ * @csspart label - The label above the field.
+ * @csspart listbox - The list inside the panel.
  * @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-feedback - The inner list's error message.
+ * @csspart listbox-filter-icon - The icon beside the list's filter field.
  * @csspart listbox-filter-mark - The glyph beside the filter field, where 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-items - The element that holds the 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 messages from.
+ * @csspart listbox-loading - Shown while the options are loading.
  * @csspart listbox-search - The region holding the field that narrows the list.
- * @csspart listbox-search-field - The field itself.
+ * @csspart listbox-search-field - The filter field inside that region.
  * @csspart rest - The count of choices held beyond `max-tags`. A `<button>` with `expandable`, a `<span>` without it.
  * @csspart surface - The floating panel.
  * @csspart tag - One chosen option.
@@ -80,7 +75,7 @@ declare const HelixHeadlessCombobox_base: (new (...args: any[]) => import("@fusi
  * @csspart tag-start - The category before the label.
  * @csspart tags - The row of chosen options, when `multiple` is set.
  *
- * @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 HelixHeadlessCombobox extends HelixHeadlessCombobox_base {
@@ -95,7 +90,7 @@ export declare class HelixHeadlessCombobox extends HelixHeadlessCombobox_base {
      */
     autocomplete: string;
     /**
-     * Whether the reader may answer with something the list does not hold.
+     * Whether the user can add a value that is not in the list.
      *
      * The row appears while what is typed matches no option's words exactly, so
      * it is offered next to near misses too: a reader typing "Ruby on Rails" with
@@ -104,26 +99,26 @@ export declare class HelixHeadlessCombobox extends HelixHeadlessCombobox_base {
      */
     creatable: boolean;
     /**
-     * What the create row says, before the words it would add.
+     * The text of the create row, shown before the typed words it adds.
      */
     createLabel: string;
     /**
-     * Words shown where the filter has hidden everything.
+     * Text shown when the filter hides every option.
      */
     emptyText: string;
     /**
-     * Accessible name for the list, which has no visible one of its own.
+     * The list's name, read by screen readers. The list has no visible name.
      */
     listLabel: string;
     /**
-     * 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.
      */
     loading: boolean;
     /**
-     * What the list says while they are on their way.
+     * Text the list shows while the options load.
      */
     loadingText: string;
     /**
@@ -151,14 +146,15 @@ export declare class HelixHeadlessCombobox extends HelixHeadlessCombobox_base {
      */
     placeholder: string;
     /**
-     * What the control removing one chosen option is called, with `{name}` filled in.
+     * The name of the control that removes one chosen option, with `{name}`
+     * filled in.
      *
      * **The name goes in**, so a row of them is heard as which one each
      * removes rather than as "Remove" said once per chosen option.
      */
     removeLabel: string;
     /**
-     * Whether the field finishes the word as it is typed.
+     * Whether the field completes the word as the user types.
      *
      * `suggest` rather than `autocomplete`, which is a real HTML attribute this
      * element already sets on the input it renders, and two things of one name
@@ -193,7 +189,10 @@ export declare class HelixHeadlessCombobox extends HelixHeadlessCombobox_base {
      */
     get selectedIndex(): number;
     set selectedIndex(at: number);
-    /** Which kind of chooser this is, in the platform's two words. */
+    /**
+     * The control type, `select-one` or `select-multiple`, as on a native
+     * `<select>`.
+     */
     get type(): string;
     private get listbox();
     protected readonly panel: PopoverController;

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

@@ -4,30 +4,25 @@ import '../../dialog/index.js';
 import '../../listbox/index.js';
 declare const HelixHeadlessCommand_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
 /**
- * @summary A list of commands, opened from anywhere and filtered by typing.
+ * @summary A command palette: a list of commands that opens from anywhere on the page and filters as you type.
  *
  * @description
- * **The list is `Listbox`, filtering and all.** Listbox already owns narrowing,
- * the empty state, the highlight over what matched, `aria-activedescendant`,
- * scrolling an option into view and the keyboard that moves between them. Its
- * own note says a command palette is that list again with something different
- * opening it, and this is that something: a dialog, and a key that summons it.
+ * The list is a `Listbox`, which handles filtering, the empty state, the match
+ * highlight, `aria-activedescendant`, scrolling an option into view, and moving
+ * between options with the keyboard. The palette adds a dialog and a hotkey
+ * that opens it.
  *
- * **The value is not kept.** A palette runs a command and forgets it: nothing
- * here is a form control and nothing is submitted, so what it reports is that
- * an option was chosen, once, with `helix-select`. A consumer that wants the
- * last command remembered is a consumer with somewhere better to keep it.
+ * The palette keeps no value. It is not a form control and submits nothing.
+ * Choosing an option dispatches `helix-select` once. To remember the last
+ * command, store it yourself.
  *
- * **The hotkey is global and the element does not have to be open to hear it.**
- * The listener is on the document, because the point of a palette is that it
- * answers from wherever the reader is, including from inside another control's
- * text field. `mod` is Command on a Mac and Control elsewhere, resolved here so
- * a consumer writes one thing.
+ * The hotkey listener is on the document, so the hotkey works from anywhere on
+ * the page, including inside another control's text field, whether or not the
+ * palette is open. `mod` means Command on a Mac and Control elsewhere, so you
+ * write one binding.
  *
- * The filter is emptied as the palette closes, for the reason Combobox and
- * Select both record: a control reopened still narrowed by the last visit's
- * search is one whose second use starts from the first one's leftovers, and a
- * palette is used far more often than either.
+ * The filter is cleared when the palette closes, so each opening starts from
+ * the full list. Combobox and Select do the same.
  *
  * @since 0.1.0
  * @status stable
@@ -36,37 +31,37 @@ declare const HelixHeadlessCommand_base: (new (...args: any[]) => import("@fusio
  * @documentation https://fusion.dev/helix/components/command
  *
  * @slot - The commands, and any groups of them.
- * @slot footer - Under the list, for the keys a reader can press.
+ * @slot footer - Content under the list, such as the keys that work in the palette.
  *
- * @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 palette opens. Cancelable: refusing it takes the decision and nothing moves.
- * @event {HelixSelectEvent} helix-select - Fired when a command is chosen. Cancelable: refusing it takes the decision and nothing moves.
- * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
+ * @event {HelixBeforeCloseEvent} helix-before-close - The palette is about to close. Cancelable: cancel it to keep it open.
+ * @event {HelixBeforeOpenEvent} helix-before-open - The palette is about to open. Cancelable: cancel it to keep it closed.
+ * @event {HelixSelectEvent} helix-select - A command was chosen. Cancelable: cancel it to keep the palette open.
+ * @event {Event} toggle - The palette opened or closed. The event carries `newState` and `oldState`.
  *
- * @csspart dialog - The overlay's own box, forwarded from the dialog.
+ * @csspart dialog - The box of the dialog the palette opens in, forwarded from `Dialog`.
  * @csspart footer - The row under the list.
- * @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 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 - The listbox inside the palette.
+ * @csspart listbox-empty - The text shown when the filter matches no commands.
+ * @csspart listbox-feedback - The listbox's error message.
+ * @csspart listbox-filter-icon - The icon beside the filter field.
+ * @csspart listbox-filter-mark - The default icon beside the filter field, drawn when no icon is slotted.
+ * @csspart listbox-hint - Help text under the list.
+ * @csspart listbox-items - The list of commands.
+ * @csspart listbox-label - The label above the list.
+ * @csspart listbox-live - The listbox's `live` part, a live region that holds the empty and loading text for screen readers.
+ * @csspart listbox-loading - The text shown while the commands are loading.
+ * @csspart listbox-search - The region that holds the filter field.
+ * @csspart listbox-search-field - The filter field.
  *
  * @cssstate open - While the palette is open.
  */
 export declare class HelixHeadlessCommand extends HelixHeadlessCommand_base {
     /**
-     * Words shown where the filter has matched nothing.
+     * The text shown when the filter matches no commands.
      */
     emptyText: string;
     /**
-     * The key that opens it, as `mod+k` or `shift+p` or plain `k`.
+     * The key that opens the palette, written as `mod+k`, `shift+p`, or `k`.
      *
      * Empty turns it off, for a consumer who opens the palette from a button or
      * from their own shortcut handler. There is no list of defaults to fight
@@ -78,7 +73,7 @@ export declare class HelixHeadlessCommand extends HelixHeadlessCommand_base {
      */
     label: string;
     /**
-     * Shown in the field before anything is typed.
+     * The text shown in the filter field before anything is typed.
      */
     placeholder: string;
     /**

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

@@ -2,19 +2,17 @@ import { type TemplateResult } from 'lit';
 import { HelixHeadlessIconButton } from '../../icon-button/root/icon-button-root.js';
 import '../../tooltip/index.js';
 /**
- * @summary A button that puts a string on the clipboard and says it did.
+ * @summary A button that copies a string to the clipboard and confirms the copy.
  *
  * @description
- * **The confirmation is the component.** Writing to the clipboard is three
- * lines; what makes this worth an element is that the platform gives a reader
- * no feedback at all, so a press that copies looks identical to one that
- * failed.
+ * Copies text to the clipboard and confirms the copy. The platform gives no
+ * feedback for a clipboard write, so without a confirmation a press that copies
+ * looks the same as one that fails.
  *
- * **Announced after the write, never before.** A clipboard write is a
- * permission the browser may refuse, for real reasons: an insecure origin, a
- * document that is not focused, a gesture that did not qualify. The
- * confirmation and the event both wait for the promise, and a refusal leaves
- * the button exactly as it was.
+ * The confirmation and the event wait for the write to finish. The browser can
+ * refuse a clipboard write, for example on an insecure origin, in a document
+ * that is not focused, or after a gesture that does not qualify. A refused
+ * write leaves the button unchanged.
  *
  * @since 0.1.0
  * @status stable
@@ -22,34 +20,34 @@ import '../../tooltip/index.js';
  * @aliases Copy, Copy to clipboard
  * @documentation https://fusion.dev/helix/components/copy-button
  *
- * @slot - The resting icon. Falls back to a clipboard.
- * @slot copied - What replaces it once the write succeeds. Falls back to a check.
+ * @slot - The icon shown before a copy. Defaults to a clipboard.
+ * @slot copied - The icon shown after a successful copy. Defaults to a check mark.
  *
  * @event {HelixCopyEvent} helix-copy - Fired after the clipboard write succeeds.
  *
  * @csspart button - The inner button.
- * @csspart mark - The clipboard glyph, and the confirmation that replaces it.
- * @csspart tooltip - The bubble, forwarded from the tooltip inside.
- * @csspart tooltip-arrow - The point, resting against the trigger.
- * @csspart tooltip-arrow-bottom - The point while the bubble is below the button, so on its top edge, beside `tooltip-arrow`.
- * @csspart tooltip-arrow-left - The point while the bubble is left of the button, so on its right edge, beside `tooltip-arrow`.
- * @csspart tooltip-arrow-right - The point while the bubble is right of the button, so on its left edge, beside `tooltip-arrow`.
- * @csspart tooltip-arrow-top - The point while the bubble is above the button, so on its bottom edge, beside `tooltip-arrow`.
- * @csspart tooltip-bottom - The bubble while it is below the button, beside `tooltip`.
- * @csspart tooltip-left - The bubble while it is left of the button, beside `tooltip`.
- * @csspart tooltip-right - The bubble while it is right of the button, beside `tooltip`.
- * @csspart tooltip-top - The bubble while it is above the button, beside `tooltip`.
+ * @csspart mark - The clipboard icon, and the confirmation icon that replaces it.
+ * @csspart tooltip - The tooltip bubble, forwarded from the tooltip inside the button.
+ * @csspart tooltip-arrow - The tooltip's arrow, which points at the button.
+ * @csspart tooltip-arrow-bottom - The arrow while the bubble is below the button, on the bubble's top edge. Set together with `tooltip-arrow`.
+ * @csspart tooltip-arrow-left - The arrow while the bubble is left of the button, on the bubble's right edge. Set together with `tooltip-arrow`.
+ * @csspart tooltip-arrow-right - The arrow while the bubble is right of the button, on the bubble's left edge. Set together with `tooltip-arrow`.
+ * @csspart tooltip-arrow-top - The arrow while the bubble is above the button, on the bubble's bottom edge. Set together with `tooltip-arrow`.
+ * @csspart tooltip-bottom - The bubble while it is below the button. Set together with `tooltip`.
+ * @csspart tooltip-left - The bubble while it is left of the button. Set together with `tooltip`.
+ * @csspart tooltip-right - The bubble while it is right of the button. Set together with `tooltip`.
+ * @csspart tooltip-top - The bubble while it is above the button. Set together with `tooltip`.
  */
 export declare class HelixHeadlessCopyButton extends HelixHeadlessIconButton {
     /**
-     * What it is called, and says, after one.
+     * The button's name and tooltip text after a copy.
      *
      * `attribute` written out, because Lit lowercases a property name rather than
      * dash-casing it, and `copiedlabel` is not what anyone would type.
      */
     copiedLabel: string;
     /**
-     * What it is called, and says, before a press.
+     * The button's name and tooltip text before a copy.
      *
      * Defaulted rather than left empty. An icon-only control must be named, and
      * the name of this one is not a judgment call: every copy button in the
@@ -57,7 +55,7 @@ export declare class HelixHeadlessCopyButton extends HelixHeadlessIconButton {
      */
     label: string;
     /**
-     * What goes on the clipboard.
+     * The text copied to the clipboard.
      *
      * **Narrows `Button.value`, which is the submit value, and the two agree.**
      * A copy button is `type="button"` and never submits, so the inherited