@fusion.dev/helix-headless 0.104.1 → 0.106.0

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

@@ -2,26 +2,24 @@ import { AriaForwardController, HelixFormElement } from '@fusion.dev/helix-core'
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessCheckbox_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerCheckedInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
 /**
- * @summary A box that is ticked, or not, or neither.
+ * @summary A box that is checked, unchecked, or indeterminate.
  *
  * @description
- * Renders a real `<input type="checkbox">`, so the space key, the focus ring,
- * and the indeterminate glyph come from the platform. `delegatesFocus` puts
- * focus on it, and it serializes into the server's markup, so the control is
- * reachable before any script loads.
+ * Renders a native `<input type="checkbox">`, so the Space key, the focus ring,
+ * and the indeterminate glyph come from the platform. `delegatesFocus` sends
+ * focus to the input, and the input is in the server-rendered markup, so the
+ * control works before any script loads.
  *
- * **The input inside a shadow root submits nothing**, because the form is on
- * the other side of the boundary. The host is form-associated instead and
- * reports its own value through `ElementInternals`, which is also what carries
- * validity and what answers a form reset.
+ * An input inside a shadow root does not submit with a form. The host is
+ * form-associated and uses `ElementInternals` for its value, its validity, and
+ * form reset.
  *
- * A checked box submits its `value`, and an unchecked one submits nothing at
- * all. That is what a native checkbox does, and a form built around one reads
- * the absence rather than a `false`.
+ * A checked box submits its `value`, and an unchecked one submits nothing, as a
+ * native checkbox does.
  *
- * `indeterminate` is presentation and nothing else. It is neither checked nor
- * unchecked to a reader, it never submits, and the first click resolves it: a
- * third state that survives interaction is a control nobody can finish.
+ * `indeterminate` changes only the presentation. Assistive technology reports
+ * it as neither checked nor unchecked, it never submits, and the first click
+ * resolves it.
  *
  * @since 0.1.0
  * @status stable
@@ -31,34 +29,34 @@ declare const HelixHeadlessCheckbox_base: (new (...args: any[]) => import("@fusi
  *
  * @slot - The label.
  *
- * @event {Event} change - Relayed from the input once the state has changed.
- * @event {HelixBeforeToggleEvent} helix-before-toggle - Fired before the state changes, and cancelable.
- * @event {Event} input - Announced once the state has moved.
+ * @event {Event} change - The box was checked or unchecked. Relayed from the native input.
+ * @event {HelixBeforeToggleEvent} helix-before-toggle - The box is about to be checked or unchecked. Cancelable: cancel it to keep its state.
+ * @event {Event} input - The box was checked or unchecked.
  *
- * @csspart box - The frame the input is painted as, and the mark sits over.
- * @csspart control - The input.
- * @csspart feedback - What is wrong with it.
- * @csspart field - The row the box and its label share, and the surface the card appearance draws.
- * @csspart hint - Help under the control, while nothing is wrong.
- * @csspart label - The label beside it.
- * @csspart mark - The tick, or the dash when the box is indeterminate.
- * @csspart mark-checked - The mark while the box is checked, beside `mark`.
- * @csspart mark-indeterminate - The mark while the box is indeterminate, beside `mark`.
+ * @csspart box - The box drawn for the input, under the mark.
+ * @csspart control - The native input.
+ * @csspart feedback - The message that says what is wrong.
+ * @csspart field - The row that holds the box and its label. It is the card when `separation` is set.
+ * @csspart hint - Help text under the control, shown while there is no feedback.
+ * @csspart label - The label next to the box.
+ * @csspart mark - The check mark, or the dash when the box is indeterminate.
+ * @csspart mark-checked - Added to `mark` while the box is checked.
+ * @csspart mark-indeterminate - Added to `mark` while the box is indeterminate.
  *
  * @cssstate checked - While the box is checked.
- * @cssstate has-label - While the label slot holds something to read, which is what draws a label at all.
- * @cssstate invalid - While there is feedback to show: the platform's verdict, or the consumer's `feedback`.
+ * @cssstate has-label - The label slot has content, so the label is drawn.
+ * @cssstate invalid - The control has an error to show, from the browser's validation or from your `feedback`.
  */
 export declare class HelixHeadlessCheckbox extends HelixHeadlessCheckbox_base {
     protected readonly aria: AriaForwardController;
     /**
-     * Whether the box shows as neither checked nor unchecked.
+     * Shows the box as neither checked nor unchecked.
      *
      * Presentation only. It never submits, and the first change resolves it.
      */
     indeterminate: boolean;
     /**
-     * Value submitted when the box is checked.
+     * The value submitted when the box is checked.
      */
     value: string;
     /** Focus is delegated to the input, so the host is never the focus target. */
@@ -66,7 +64,7 @@ export declare class HelixHeadlessCheckbox extends HelixHeadlessCheckbox_base {
     private readonly handleChange;
     /** Reports the value and the validity the host stands behind. */
     private sync;
-    /** Returns the box to the state its markup declared. */
+    /** Resets the box to the state set in its markup. */
     formResetCallback(): void;
     protected willUpdate(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;

package/dist/checkbox-group/root/checkbox-group-root.d.ts

@@ -3,25 +3,25 @@ import { type PropertyValues, type TemplateResult } from 'lit';
 import { HelixHeadlessCheckbox } from '../../checkbox/root/checkbox-root.js';
 declare const HelixHeadlessCheckboxGroup_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
 /**
- * @summary Groups related checkboxes, and reports them as one set.
+ * @summary A group of related checkboxes under one label, with one value for the set.
  *
  * @description
- * The host is the group, so `role="group"` sits on it through internals and
- * `label` names it. A run of checkboxes with no name is announced as separate
- * controls, which is what the grouping exists to say it is not.
+ * The host is the group. It has `role="group"` through internals, and `label`
+ * names it. Without a name, screen readers announce the checkboxes as separate
+ * controls.
  *
- * **Each checkbox still submits itself.** They are form-associated already and
- * a native group is several inputs sharing a name, so this adds no form value
- * of its own: it would submit the same answers twice. What it adds is the
- * grouping, a shared `name` so it is written once, and one place to read and
- * write the whole set.
+ * **Each checkbox submits its own value.** Checkboxes are already
+ * form-associated, and a native group is several inputs that share a name, so
+ * the group adds no form value of its own. It adds the grouping, a shared
+ * `name` that you write once, and one place to read and write the whole set.
  *
- * `value` is the checked values, comma separated, in the order the boxes are
- * written. Setting it ticks exactly those and unticks the rest.
+ * `value` is the checked values, separated by commas, in the order the
+ * checkboxes are written. Setting it checks exactly those values and unchecks
+ * the rest.
  *
- * **Its message is always given, never derived.** The group is form-associated
- * for validity alone and never calls `setFormValue`, so `feedback` is what shows
- * here: the browser has nothing to say about a set it does not submit.
+ * **The group shows the message you set in `feedback`.** It is form-associated
+ * only for validity and never calls `setFormValue`, so the browser does not
+ * generate a message for it.
  *
  * @since 0.1.0
  * @status stable
@@ -30,19 +30,19 @@ declare const HelixHeadlessCheckboxGroup_base: (new (...args: any[]) => import("
  * @documentation https://fusion.dev/helix/components/checkbox-group
  *
  * @slot - The checkboxes.
- * @slot hint - Richer than a string.
- * @slot label - Richer than a string, where the label is more than one.
+ * @slot hint - Help under the checkboxes, for help that needs more than plain text.
+ * @slot label - The group's label, for a label that needs more than plain text.
  *
- * @event {Event} change - Announced once the value has moved.
- * @event {HelixBeforeChangeEvent} helix-before-change - Fired before any box changes, with the whole set. Cancelable: refusing it takes the decision and nothing moves.
- * @event {Event} input - Announced once the value has moved.
+ * @event {Event} change - The set of checked boxes changed.
+ * @event {HelixBeforeChangeEvent} helix-before-change - A box is about to change. Carries the whole set that would result. Cancelable: canceling it leaves every box as it was.
+ * @event {Event} input - The set of checked boxes changed.
  *
- * @csspart feedback - What is wrong with it.
- * @csspart hint - Help under the set.
- * @csspart items - The list itself, which is what `orientation` lays out.
- * @csspart label - The group's name, over the set.
+ * @csspart feedback - The message that says what is wrong with the set.
+ * @csspart hint - The help under the checkboxes.
+ * @csspart items - The element that holds the checkboxes, laid out by `orientation`.
+ * @csspart label - The group's label, above the checkboxes.
  *
- * @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 HelixHeadlessCheckboxGroup extends HelixHeadlessCheckboxGroup_base {
     /**
@@ -50,7 +50,7 @@ export declare class HelixHeadlessCheckboxGroup extends HelixHeadlessCheckboxGro
      */
     value: string;
     protected readonly cascade: DisabledCascadeController;
-    /** The boxes, in light-DOM order. Client only: the server has no tree. */
+    /** The checkboxes in the group, in the order they are written. Browser only. */
     get boxes(): HelixHeadlessCheckbox[];
     /**
      * Pushes the group's name and value onto the boxes.

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

@@ -4,17 +4,13 @@ import { type TemplateResult } from 'lit';
  * @summary A fragment of code inside a line of prose.
  *
  * @description
- * **A real `<code>`, because the element is the meaning.** A styled span reads
- * as code and is not: a screen reader announces nothing about it, a translation
- * tool will happily translate it, and a search that understands documents
- * cannot tell it from emphasis. The tag is the whole point, which is also why
- * this component is so small.
+ * Renders a real `<code>` element, which marks the text as code for translation
+ * tools and document search. A styled span carries no such meaning, and a
+ * screen reader announces nothing about it.
  *
- * **Inline, and only inline.** A block of code is `CodeBlock`, a separate
- * family rather than a variant here. The two differ in more than presentation:
- * one flows with a sentence and must never scroll, the other is a figure with
- * its own box, its own overflow and something to copy. Namespacing them
- * together would say `CodeBlock` is part of `Code`, and it is not.
+ * `Code` is inline only and never scrolls. For a block of code with its own
+ * box, its own overflow, and copying, use `CodeBlock`, which is a separate
+ * family.
  *
  * @since 0.1.0
  * @status stable

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

@@ -2,44 +2,31 @@ import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 import '../../copy-button/index.js';
 /**
- * @summary A block of code, with somewhere to put its name and a way to take it.
+ * @summary A block of code with an optional name and a copy button.
  *
  * @description
- * **`<pre><code>` and nothing cleverer.** The pair is what the platform means
- * by a block of code: `pre` keeps the whitespace, `code` says what the
- * whitespace is for, and losing either one loses something no styling puts
- * back. Indentation in a `div` is a paragraph with odd spacing.
+ * Renders a `<pre><code>` pair: `pre` keeps the whitespace, and `code` marks it
+ * as code. Long lines scroll inside the block and do not wrap, because a line
+ * break can be significant in code.
  *
- * **It scrolls rather than wraps.** A wrapped line of code is a lie about where
- * the line ends, and in a language where a line break can be significant it is
- * a lie that costs someone an afternoon. The box takes its own scrollbar.
+ * A copy button is on by default. Set `no-copy` to remove it. The button copies
+ * the slotted text, so there is no second copy of the code to keep in sync.
  *
- * **The copy button is here because the alternative is selecting it by hand.**
- * Every consumer would otherwise put one there, slightly differently, and the
- * one that forgot would be the one with the longest snippet. It is on unless
- * `no-copy` says otherwise, and takes its text from the slot rather than from a
- * property, so there is no second copy of the code to keep in step.
+ * For a fragment of code inside a sentence, use `Code`.
  *
- * A `Code` for a fragment inside a sentence. Separate families, because one
- * flows with prose and the other is a figure.
+ * Set `diff` to show a change. Put a unified diff, the output of `git diff` or
+ * `diff -u`, in the same slot, and the block draws the lines it added and
+ * removed. The block never computes a diff itself. Line numbers come from the
+ * hunk headers and are hidden from the accessibility tree. Changed lines are
+ * `<ins>` and `<del>` with the `+` and `-` kept as text, so the change does not
+ * depend on color. Each file in the patch is its own block under its own name,
+ * and its copy button copies the new version of the file. `variant="split"`
+ * shows the old version beside the new, each removal opposite its replacement.
  *
- * **`diff` reads the code as a change.** The content is then a unified diff,
- * what `git diff` and `diff -u` write, in the same slot ordinary code goes in,
- * and it is drawn as the lines it added and removed. The block reads a diff and
- * never computes one, so the algorithm stays wherever the two versions are.
- * Numbers come from the hunk headers, which makes them the file's; changed lines
- * are `<ins>` and `<del>` with the `+` and `-` kept as text, so the change is not
- * carried by color; the numbers are hidden from the accessibility tree. Each
- * file in the patch is a block of its own under its own name, and its copy
- * button takes the file as it now reads. `variant="split"` sets the old version
- * beside the new, each removal opposite its replacement.
- *
- * **Before the script runs, a diff is its own text.** A server has no children
- * to read, so it renders the slot as ordinary code, which for a diff is the
- * patch in a `<pre>`: a legible diff, and the first render the client makes
- * too, which is what keeps hydration clean. The drawn diff replaces it once the
- * content can be read. Diff mode is experimental while the rest of the family
- * is stable.
+ * On the server, the slot renders as ordinary code, so a diff first appears as
+ * the patch text in a `<pre>`. The client makes the same first render, which
+ * keeps hydration clean, and draws the diff once it can read the content. Diff
+ * mode is experimental. The rest of the family is stable.
  *
  * @since 0.1.0
  * @status stable
@@ -53,26 +40,26 @@ import '../../copy-button/index.js';
  * @csspart block - The scrolling `<pre>`.
  * @csspart code - The `<code>` inside it.
  * @csspart context - In a diff, a line both versions share.
- * @csspart copy - The copy button: in the header where there is one, and otherwise beside the code.
+ * @csspart copy - The copy button. It sits in the header when there is one, and beside the code otherwise.
  * @csspart copy-button - The inner button.
- * @csspart copy-mark - The clipboard glyph, and the confirmation that replaces it.
- * @csspart copy-tooltip - The bubble, forwarded from the tooltip inside.
- * @csspart copy-tooltip-arrow - The point, resting against the trigger.
- * @csspart copy-tooltip-arrow-bottom - The point while the bubble is below the copy button, so on its top edge, beside `copy-tooltip-arrow`.
- * @csspart copy-tooltip-arrow-left - The point while the bubble is left of the copy button, so on its right edge, beside `copy-tooltip-arrow`.
- * @csspart copy-tooltip-arrow-right - The point while the bubble is right of the copy button, so on its left edge, beside `copy-tooltip-arrow`.
- * @csspart copy-tooltip-arrow-top - The point while the bubble is above the copy button, so on its bottom edge, beside `copy-tooltip-arrow`.
- * @csspart copy-tooltip-bottom - The bubble while it is below the copy button, beside `copy-tooltip`.
- * @csspart copy-tooltip-left - The bubble while it is left of the copy button, beside `copy-tooltip`.
- * @csspart copy-tooltip-right - The bubble while it is right of the copy button, beside `copy-tooltip`.
- * @csspart copy-tooltip-top - The bubble while it is above the copy button, beside `copy-tooltip`.
+ * @csspart copy-mark - The clipboard icon, and the check mark that replaces it after a copy.
+ * @csspart copy-tooltip - The copy button's tooltip.
+ * @csspart copy-tooltip-arrow - The tooltip's arrow, which points at the copy button.
+ * @csspart copy-tooltip-arrow-bottom - The arrow while the tooltip is below the copy button, on the tooltip's top edge. Applied with `copy-tooltip-arrow`.
+ * @csspart copy-tooltip-arrow-left - The arrow while the tooltip is left of the copy button, on the tooltip's right edge. Applied with `copy-tooltip-arrow`.
+ * @csspart copy-tooltip-arrow-right - The arrow while the tooltip is right of the copy button, on the tooltip's left edge. Applied with `copy-tooltip-arrow`.
+ * @csspart copy-tooltip-arrow-top - The arrow while the tooltip is above the copy button, on the tooltip's bottom edge. Applied with `copy-tooltip-arrow`.
+ * @csspart copy-tooltip-bottom - The tooltip while it is below the copy button. Applied with `copy-tooltip`.
+ * @csspart copy-tooltip-left - The tooltip while it is left of the copy button. Applied with `copy-tooltip`.
+ * @csspart copy-tooltip-right - The tooltip while it is right of the copy button. Applied with `copy-tooltip`.
+ * @csspart copy-tooltip-top - The tooltip while it is above the copy button. Applied with `copy-tooltip`.
  * @csspart file - In a diff, one file's header and block.
  * @csspart filler - In a split diff, the empty row opposite a line the other side does not have.
  * @csspart frame - The code, and the copy button beside it where there is no header.
- * @csspart header - The bar carrying the name and the copy button, where there is a name.
+ * @csspart header - The bar that holds the name and the copy button, shown when there is a name.
  * @csspart hunk - In a diff, a `@@` line saying where the lines under it are.
  * @csspart label - The file name or language, where one is given.
- * @csspart marker - In a diff, the `+`, `-` or space that opens a line.
+ * @csspart marker - In a diff, the `+`, `-`, or space that starts a line.
  * @csspart new - In a split diff, the new version's `<pre>`.
  * @csspart number - In a diff, a line number.
  * @csspart old - In a split diff, the old version's `<pre>`.
@@ -89,7 +76,7 @@ export declare class HelixHeadlessCodeBlock extends HelixElement {
      */
     diff: boolean;
     /**
-     * What to call this block, usually a file name or a language.
+     * The block's name, usually a file name or a language.
      *
      * In a diff, each file is named from the patch, and this names a patch that
      * carries no name of its own.
@@ -118,7 +105,7 @@ export declare class HelixHeadlessCodeBlock extends HelixElement {
      */
     noCopy: boolean;
     /**
-     * How a diff's two versions are arranged; nothing without `diff`.
+     * How a diff's two versions are arranged. It has no effect without `diff`.
      *
      * Absent is unified, each removal above its replacement, which fits any
      * width. `split` sets the old version beside the new one. Optional rather

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

@@ -3,33 +3,29 @@ import { type PropertyValues, type TemplateResult } from 'lit';
 import '../../color-picker/index.js';
 declare const HelixHeadlessColorInput_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinPickerFieldInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
 /**
- * @summary A color, typed in any syntax or picked from a panel.
+ * @summary A field for a color, typed in any syntax or picked from a panel.
  *
  * @description
- * **The picker is `ColorPicker`, not a second one written here.** It owns the
- * square, the ramps, the eyedropper and the syntax toggle, and it is worth
- * having on its own: a settings pane wants a picker flat on the page with
- * nothing to open. This element is the field, the overlay, and the form.
- * Exactly the arrangement Date Input has with `DatePicker`.
+ * A text field with a button that opens `ColorPicker` in an overlay.
+ * `ColorPicker` provides the square, the ramps, the eyedropper, and the syntax
+ * toggle, and you can also use it on its own, flat on the page. Color Input
+ * adds the field, the overlay, and the form value, the same arrangement Date
+ * Input has with `DatePicker`.
  *
- * **Typed as well as picked, and the typing is the reason this is not
- * `<input type="color">`.** The native control gives a free picker and takes
- * nearly all styling with it, which is a fair trade until a product needs the
- * panel to match everything around it. What is kept from the native one is the
- * part worth keeping: a real text field, so a reader who has the hex pastes it
- * and never opens anything.
+ * You can type or paste a color into the field without opening the picker.
+ * Color Input is a custom control, unlike `<input type="color">`, so you can
+ * style the panel to match your interface.
  *
- * **Every syntax is read; the one `format` names is written.** `#f00`,
- * `#ff0000`, `rgb(255 0 0)`, `rgba(255,0,0,.5)`, `rgb(255 0 0 / 50%)` and
- * `hsl(0 100% 50%)` are all colors, and a field that refuses one because it
- * prefers another is arguing with the person using it. What the field *shows* is
- * the value itself, for the reason Date Input gives about its dates: half-typed
- * input does not survive a round trip through a formatter.
+ * The field reads every color syntax, including `#f00`, `#ff0000`,
+ * `rgb(255 0 0)`, `rgba(255,0,0,.5)`, `rgb(255 0 0 / 50%)`, and
+ * `hsl(0 100% 50%)`. It writes colors in the syntax that `format` names. The
+ * field shows the value without reformatting it, because half-typed input does
+ * not survive a round trip through a formatter. Date Input does the same with
+ * dates.
  *
- * The custom property below is written by this component and never set by a
- * consumer: it carries a value this element resolved and CSS cannot, which is
- * what lets a stylesheet on this tier paint the swatch without parsing anything
- * itself.
+ * The component sets `--color-input-swatch`, so do not set it yourself. It
+ * holds the resolved color, so the styled tier can paint the swatch without
+ * parsing the value.
  *
  * @since 0.1.0
  * @status stable
@@ -38,58 +34,58 @@ declare const HelixHeadlessColorInput_base: (new (...args: any[]) => import("@fu
  * @documentation https://fusion.dev/helix/components/color-input
  *
  * @slot end - Content at the trailing end, before the trigger.
- * @slot feedback - What is wrong with it.
- * @slot hint - Help under the field.
+ * @slot feedback - The message that says what is wrong with the value.
+ * @slot hint - Help text under the field.
  * @slot start - Content at the leading end of the field, inside its border.
- * @slot trigger - The mark on the field saying a panel opens.
+ * @slot trigger - The icon on the trigger, which shows that the field opens a panel.
  *
- * @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 {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 {Event} input - Announced once the value has moved.
- * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
+ * @event {Event} change - Sent when the user finishes changing the value.
+ * @event {HelixBeforeChangeEvent} helix-before-change - The color is about to change. Cancelable: cancel it to keep the current color.
+ * @event {HelixBeforeCloseEvent} helix-before-close - The panel is about to close. Cancelable: cancel it to keep it open.
+ * @event {HelixBeforeOpenEvent} helix-before-open - The panel is about to open. Cancelable: cancel it to keep it closed.
+ * @event {Event} input - Fired as the value changes.
+ * @event {Event} toggle - The panel opened or closed. The event carries `newState` and `oldState`.
  *
- * @csspart control - The text input carrying the value. Absent in `swatch`.
- * @csspart feedback - What is wrong with it.
+ * @csspart control - The text input that holds the value. Absent in the `swatch` variant.
+ * @csspart feedback - The message that says what is wrong with the value.
  * @csspart field - The box holding the text and the trigger.
- * @csspart hint - Help under the field, while nothing is wrong.
- * @csspart label - The question, over the field.
- * @csspart picker - The color picker inside it.
+ * @csspart hint - Help text under the field, shown while there is no feedback.
+ * @csspart label - The label above the field.
+ * @csspart picker - The color picker inside the panel.
  * @csspart picker-actions - The group holding the eyedropper and the syntax toggle.
- * @csspart picker-channel - One ramp.
- * @csspart picker-channel-control - The range input.
- * @csspart picker-channel-feedback - What is wrong with it.
- * @csspart picker-channel-field - The row: the control and its readout.
- * @csspart picker-channel-hint - Help under the track, while nothing is wrong.
- * @csspart picker-channel-label - The question, over the track.
- * @csspart picker-channel-marker - One mark.
+ * @csspart picker-channel - One channel slider.
+ * @csspart picker-channel-control - The range input of a channel slider.
+ * @csspart picker-channel-feedback - The error message for a channel slider.
+ * @csspart picker-channel-field - The row that holds a channel slider's control and its readout.
+ * @csspart picker-channel-hint - The help text under the track, shown while there is no error.
+ * @csspart picker-channel-label - The label above the track.
+ * @csspart picker-channel-marker - One mark on the track.
  * @csspart picker-channel-marker-label - The value a mark stands at, when `marker-labels` is set.
  * @csspart picker-channel-markers - The row of marks along the track.
- * @csspart picker-channel-output - The current value, shown beside it.
- * @csspart picker-channels - The ramps beside it.
+ * @csspart picker-channel-output - The current value, shown beside the track.
+ * @csspart picker-channels - The channel sliders beside the sample.
  * @csspart picker-controls - The row under the square.
  * @csspart picker-eyedropper - The control that samples a color from the screen.
- * @csspart picker-eyedropper-button - The inner control.
+ * @csspart picker-eyedropper-button - The button inside `picker-eyedropper`.
  * @csspart picker-footer - The row holding the value and the tools.
  * @csspart picker-format - The control that changes the syntax the value is written in.
- * @csspart picker-format-button - The inner control.
+ * @csspart picker-format-button - The button inside `picker-format`.
  * @csspart picker-grid - The saturation and brightness square.
- * @csspart picker-grid-brightness - The range input for its vertical axis.
+ * @csspart picker-grid-brightness - The range input for the square's vertical axis.
  * @csspart picker-grid-handle - The mark showing where in the square the color sits.
  * @csspart picker-grid-saturation - The range input for the square's horizontal axis.
- * @csspart picker-icon - A glyph this component draws.
- * @csspart picker-sample - The chip of the current color, which copies it when pressed.
+ * @csspart picker-icon - An icon drawn by the picker.
+ * @csspart picker-sample - A chip of the current color. Pressing it copies the value.
  * @csspart picker-swatch - One preset.
  * @csspart picker-swatches - The row of presets.
- * @csspart picker-value - The color as text, which can be typed or pasted.
+ * @csspart picker-value - The text field that holds the color. It accepts a typed or pasted color.
  * @csspart preview - The chip showing the color, inside the trigger.
  * @csspart surface - The floating panel.
  * @csspart trigger - The control that opens the panel.
  *
- * @cssproperty --color-input-swatch - The chosen color, to paint over the transparency check.
+ * @cssproperty --color-input-swatch - The chosen color, painted over the checkerboard that shows transparency.
  *
- * @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 picker is open.
  */
 export declare class HelixHeadlessColorInput extends HelixHeadlessColorInput_base {
@@ -108,7 +104,7 @@ export declare class HelixHeadlessColorInput extends HelixHeadlessColorInput_bas
      */
     autocomplete: string;
     /**
-     * The syntax the value is written in: `hex`, `rgb` or `hsl`.
+     * The syntax the value is written in: `hex`, `rgb`, or `hsl`.
      *
      * **Undefaulted, because it reflects.** The two together stamp an attribute
      * onto every host anybody renders, including the ones nobody configured: the
@@ -120,11 +116,11 @@ export declare class HelixHeadlessColorInput extends HelixHeadlessColorInput_bas
      */
     format?: ColorFormat;
     /**
-     * Whether the reader may change the format from the panel.
+     * Hides the button in the panel that changes the format.
      */
     noFormat: boolean;
     /**
-     * What the field says before a color is in it.
+     * The text the field shows before a color is entered.
      */
     placeholder: string;
     /**
@@ -184,6 +180,16 @@ export declare class HelixHeadlessColorInput extends HelixHeadlessColorInput_bas
     private get painted();
     /** Relayed under this element's name, so a consumer hears one control. */
     private readonly handleInput;
+    /**
+     * The picker's request, taken as this element's own.
+     *
+     * **Only the picker's.** A request from anything inside it arrives here
+     * retargeted to the picker, and a slider's carried its number: a hue of 120
+     * became this field's value and every page listening heard it. The picker
+     * keeps its sliders' requests now, and this checks where the event started
+     * as well, so a picker a tier above renders cannot say for it what it did
+     * not mean.
+     */
     private readonly handlePickerChange;
     /**
      * The picker is about to take the pointer over, so the panel gets out of the

package/dist/color-input/root/color-input-root.js

@@ -29,6 +29,9 @@ let HelixHeadlessColorInput = class HelixHeadlessColorInput extends MixinPickerF
         };
         this.handlePickerChange = (event) => {
             event.stopPropagation();
+            if (event.composedPath()[0] !== event.currentTarget) {
+                return;
+            }
             this.requestValue(event.detail.value);
             this.restore();
         };