@fusion.dev/helix-headless 0.104.1 → 0.106.0

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

@@ -5,23 +5,24 @@ declare const HelixHeadlessDrawer_base: (new (...args: any[]) => import("@fusion
  * @summary A panel that slides in from an edge.
  *
  * @description
- * Takes `MixinControllerOpen`, so `open`, `defaultOpen` and the
- * `helix-before-open` and `helix-before-close` requests behave exactly as they
- * do on an accordion item, and a consumer already knows the API.
+ * Uses `MixinControllerOpen`, so `open`, `defaultOpen`, and the
+ * `helix-before-open` and `helix-before-close` events work the same way as on
+ * an accordion item.
  *
- * Modal by default, which is three things together and not one: focus is
- * trapped inside, Escape and an outside press close it, and the page behind is
- * covered. A panel with the look of a modal and none of its behavior is worse
- * than an inline one, because it invites the reader to treat it as blocking.
+ * The drawer is modal by default, which means three things:
  *
- * Content stays mounted when closed, so it is in the server's markup and can
- * animate. A closed `<dialog>` is already out of the tab order and out of the
- * accessibility tree, so nothing here writes `inert`. The `role`, the
- * `aria-modal` and the scrim come from the element too, and
- * `drawer-root.ssr.spec.ts` asserts the panel carries no hand-written `inert`
- * and no hand-written `role`.
+ * - focus is trapped inside
+ * - Escape and a press outside close it
+ * - the page behind is covered
  *
- * Opened declaratively with the platform's invoker attributes:
+ * Content stays mounted when the drawer is closed, so it is in the server
+ * markup and can animate. A closed `<dialog>` is already out of the tab order
+ * and the accessibility tree, so the drawer does not write `inert`. The `role`,
+ * `aria-modal`, and the scrim also come from the `<dialog>` element.
+ * `drawer-root.ssr.spec.ts` checks that the panel has no hand-written `inert`
+ * or `role`.
+ *
+ * Open the drawer declaratively with the platform's invoker attributes:
  *
  * ```html
  * <helix-headless-button commandfor="nav" command="--toggle">Menu</helix-headless-button>
@@ -37,10 +38,10 @@ declare const HelixHeadlessDrawer_base: (new (...args: any[]) => import("@fusion
  * @slot - The drawer's content.
  * @slot header - Content pinned above the scrolling area.
  *
- * @event {Event} close - Relayed, because the platform's own does not escape.
+ * @event {Event} close - Sent from the host after the drawer closes, because the native `close` event does not leave the shadow root.
  * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the panel closes, and cancelable.
- * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the panel opens. Cancelable: refusing it takes the decision and nothing moves.
- * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the panel opens, and cancelable. Canceling it keeps the panel closed.
+ * @event {Event} toggle - Sent when the drawer opens or closes, with `newState` and `oldState`.
  *
  * @csspart content - The scrolling content region.
  * @csspart header - The header region.
@@ -51,7 +52,7 @@ declare const HelixHeadlessDrawer_base: (new (...args: any[]) => import("@fusion
 export declare class HelixHeadlessDrawer extends HelixHeadlessDrawer_base {
     protected readonly commands: CommandController;
     /**
-     * Which close requests the browser answers on its own.
+     * Which close requests the browser handles on its own.
      *
      * `<dialog closedby>`, forwarded, and safe to forward because every path it
      * opens still comes back through this element: a close request fires `cancel`

package/dist/drilldown/item/drilldown-item.d.ts

@@ -1,43 +1,43 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 /**
- * @summary One row of a drill-down, which may hold a page of its own.
+ * @summary One row of a drill-down, which can open a page of its own.
  *
  * @description
- * A row that opens a page *contains* that page: its rows are this row's own
- * children, assigned to the `page` slot. The tree is the structure, so there
- * are no ids to wire and a consumer who moves a row has moved its page with it.
+ * A row that opens a page contains that page: the page's rows are this row's
+ * own children, assigned to the `page` slot. There are no ids to wire, and
+ * moving a row moves its page with it.
  *
- * **It renders one of three things**, and which one is the stack's business
- * rather than its own. On the page showing, it is a row. Showing its own page,
- * it contributes that page's rows and nothing else, because its row belongs to
- * the page above. On neither, it renders nothing at all: the rows are in the
- * light DOM and come back untouched, so there is no state to keep and nothing
- * to hide with an attribute this element would have to write onto itself.
+ * What the item renders depends on the stack:
  *
- * Choosing is announced, never applied. The row dispatches and the stack
- * decides whether that means drilling in or choosing a command.
+ * - On the page that is showing, it renders its row.
+ * - When its own page is showing, it renders only that page's rows. Its row
+ *   belongs to the page above.
+ * - Otherwise it renders nothing. The rows stay in the light DOM untouched, so
+ *   there is no state to keep.
  *
- * **A row that opens a page says so**, with a caret after its words and
- * `aria-haspopup`, the way `Menu` marks a row with a submenu: a row that goes
- * somewhere and a row that does something otherwise look the same until one is
- * pressed. Not on the server, which cannot see the children and so cannot know.
+ * Choosing a row dispatches an event, and the stack decides whether that drills
+ * in or runs a command.
+ *
+ * A row that opens a page shows a caret after its text and sets
+ * `aria-haspopup`, the same way `Menu` marks a row with a submenu. The server
+ * render leaves both out, because the server cannot see the children.
  *
  * @since 0.1.0
  * @status stable
  * @aliases Panel item, Drill row
  * @documentation https://fusion.dev/helix/components/drilldown
  *
- * @slot - The words naming this row.
- * @slot end - After the words, usually a mark or a count.
- * @slot page - The rows of the page this one opens.
- * @slot start - Before the words, usually an icon.
+ * @slot - The row's label.
+ * @slot end - Content after the label, usually an icon or a count.
+ * @slot page - The rows of the page this row opens.
+ * @slot start - Content before the label, usually an icon.
  *
- * @event {HelixSelectEvent} helix-select - Fired when the row is chosen. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixSelectEvent} helix-select - Fired when the row is chosen. Cancelable: canceling it stops the change and leaves the decision to you.
  *
  * @csspart item - The row itself.
- * @csspart label - The words.
- * @csspart mark - The caret at the end of a row that opens a page, after the `end` slot. A caret points, so a sheet mirrors it in a right-to-left document.
+ * @csspart label - The row's label.
+ * @csspart mark - The caret at the end of a row that opens a page, after the `end` slot. The caret points, so a stylesheet mirrors it in a right-to-left document.
  */
 export declare class HelixHeadlessDrilldownItem extends HelixElement {
     /**
@@ -45,7 +45,7 @@ export declare class HelixHeadlessDrilldownItem extends HelixElement {
      */
     disabled: boolean;
     /**
-     * Whether this row holds the region's tab stop. Written by the stack.
+     * Whether this row holds the region's tab stop. Set by the drill-down.
      *
      * A drill-down keeps one stop and moves within it on the arrows, so every
      * other row is at `-1`. Leave it off every row, including the first, and
@@ -77,7 +77,7 @@ export declare class HelixHeadlessDrilldownItem extends HelixElement {
      */
     showingPage: boolean;
     /**
-     * Identifies the row to whatever is listening.
+     * Identifies the row to your event listeners.
      */
     value: string;
     /**
@@ -112,8 +112,8 @@ export declare class HelixHeadlessDrilldownItem extends HelixElement {
     /** Moves focus onto the row itself. */
     focusItem(): void;
     /**
-     * Whether this is the row the set is on, which in a drill-down is where focus
-     * is.
+     * Whether this is the current row, which in a drill-down is the row with
+     * focus.
      *
      * A radio group's selection is an answer it holds; a page of rows has no
      * answer, only the row a reader has walked to, so focus is the whole of what
@@ -129,7 +129,7 @@ export declare class HelixHeadlessDrilldownItem extends HelixElement {
      * dereferences what it ran out of.
      */
     get selected(): boolean;
-    /** Announces that this row was chosen. */
+    /** Fires `helix-select` for this row. */
     select(): void;
     protected render(): TemplateResult | typeof nothing;
 }

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

@@ -2,29 +2,23 @@ import { HelixElement, KeyboardNavigationController } from '@fusion.dev/helix-co
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessDrilldown_base: (new (...args: any[]) => import("@fusion.dev/helix-core").CollectionElement) & typeof HelixElement;
 /**
- * @summary A stack of pages, one showing at a time, with a way back.
+ * @summary A stack of pages that shows one at a time, with a back button.
  *
  * @description
- * One panel that changes rather than panels opening beside each other. That is
- * the right shape wherever there is no room for a second column: a phone has
- * none, and a touch screen has no hover to open one with.
+ * One panel whose content changes as you move between pages. Use it where there
+ * is no room for a second column, such as on a phone, or on a touch screen with
+ * no hover to open one.
  *
- * **Not a `Menu`, and the difference is what it is for rather than how it
- * looks.** A menu is a thing that opens from a trigger and closes when it is
- * done; this is a region that sits where it is put, inside a drawer or a
- * sidebar or a settings panel. `Menu` drills too, through the same controller,
- * because a menu deep enough to need pages wants exactly this behavior without
- * being this component.
+ * It is a region that stays where you put it, such as inside a drawer, a
+ * sidebar, or a settings panel. A `Menu` opens from a trigger and closes when
+ * you are done. `Menu` can drill into pages too, through the same controller.
  *
- * **Navigation, never a value.** Rows are places to go and commands to run, so
- * nothing here is form-associated and nothing is submitted. A drill-down that
- * reported a value would be a `Listbox` whose options happen to nest, and that
- * is the component to reach for instead.
+ * Rows are places to go and commands to run. Nothing here is form-associated
+ * and nothing is submitted. To choose a value, use a `Listbox`.
  *
- * **The tree is the state.** A row that opens a page contains that page, so the
- * stack holds one reference and reads the rest from the DOM. See
- * `DrilldownController`, which is where this behavior lives and which `Menu`
- * shares.
+ * A row that opens a page contains that page, so the stack holds one reference
+ * and reads the rest from the DOM. The behavior lives in `DrilldownController`,
+ * which `Menu` shares.
  *
  * @since 0.1.0
  * @status stable
@@ -34,26 +28,26 @@ declare const HelixHeadlessDrilldown_base: (new (...args: any[]) => import("@fus
  *
  * @slot - The rows of the top page.
  *
- * @event {HelixSelectEvent} helix-select - Fired when a row with no page is chosen. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixSelectEvent} helix-select - Fired when a row with no page is chosen. Cancelable: canceling it stops the change and leaves the decision to you.
  *
- * @csspart back - The control that returns one page.
- * @csspart back-mark - The glyph on the back control.
+ * @csspart back - The button that goes back one page.
+ * @csspart back-mark - The icon on the back button.
  * @csspart empty - Shown when there are no entries to show.
- * @csspart header - The bar above a page, holding the way back and its name.
- * @csspart live - The empty and loading lines again, in a region a screen reader hears when they change. Visually hidden in the styled tier.
- * @csspart loading - Shown while the entries are still on their way.
+ * @csspart header - The bar above a page, which holds the back button and the page's name.
+ * @csspart live - A copy of the empty and loading text, in a region that screen readers announce when it changes. Visually hidden in the styled tier.
+ * @csspart loading - Shown while the entries load.
  * @csspart page - The region the rows are in.
  * @csspart title - The name of the page showing.
  *
- * @cssstate drilled - While a row's page is showing rather than the top one, so a frame around this can answer the depth it is at.
+ * @cssstate drilled - A row's page is showing, so a frame around the drilldown can style itself for that depth.
  */
 export declare class HelixHeadlessDrilldown extends HelixHeadlessDrilldown_base {
     /**
-     * Accessible name for the region.
+     * The region's name, read by screen readers.
      */
     label: string;
     /**
-     * What the control returning from a page reads.
+     * The text of the back button.
      */
     backLabel: string;
     /**
@@ -108,7 +102,7 @@ export declare class HelixHeadlessDrilldown extends HelixHeadlessDrilldown_base
     /** Shows a row's page, and puts focus on the first row of it. */
     private enter;
     /**
-     * Returns one page, and reports whether there was one to return to.
+     * Goes back one page, and returns whether there was a page to go back to.
      *
      * Focus lands on the row that opened the page being left, which is why the
      * row is read before going back rather than after: a reader who drills in and

package/dist/element-events.generated.js

@@ -100,7 +100,25 @@ registerElementEvents({
         'toggle',
     ],
     'helix-headless-listbox': ['change', 'helix-before-change', 'helix-filter', 'input'],
-    'helix-headless-map': ['helix-map-pan', 'helix-map-zoom'],
+    'helix-headless-map': [
+        'helix-activate',
+        'helix-map-cluster',
+        'helix-map-pan',
+        'helix-map-part-change',
+        'helix-map-rotate',
+        'helix-map-tilt',
+        'helix-map-zoom',
+    ],
+    'helix-headless-map-area': ['helix-map-part-change'],
+    'helix-headless-map-buildings': ['helix-map-part-change'],
+    'helix-headless-map-contours': ['helix-map-part-change'],
+    'helix-headless-map-landcover': ['helix-map-part-change'],
+    'helix-headless-map-marker': ['helix-map-cluster', 'helix-map-part-change'],
+    'helix-headless-map-points': ['helix-activate', 'helix-map-cluster', 'helix-map-part-change'],
+    'helix-headless-map-position': ['helix-map-part-change'],
+    'helix-headless-map-raster': ['helix-map-part-change'],
+    'helix-headless-map-route': ['helix-map-part-change'],
+    'helix-headless-map-terrain': ['helix-map-part-change'],
     'helix-headless-megamenu': ['helix-before-close', 'helix-before-open', 'toggle'],
     'helix-headless-menu': ['helix-before-close', 'helix-before-open', 'helix-select', 'toggle'],
     'helix-headless-menu-item': ['helix-select'],

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

@@ -1,24 +1,21 @@
 import { ArrivalController, HelixElement } from '@fusion.dev/helix-core';
 import { type TemplateResult } from 'lit';
 /**
- * @summary Says that a region has nothing in it, and what to do about it.
+ * @summary A message that a region has nothing in it, and the next step to take.
  *
  * @description
- * An empty region with no explanation is indistinguishable from one that failed
- * to load, so this exists to tell the difference: what would be here, and the
- * one action that would put something here.
+ * Shows what would be in a region and the one action that would fill it, so an
+ * empty region does not look like one that failed to load.
  *
- * Announced, because an empty view usually arrives in place of content that was
- * being fetched: saying so is the only way a screen-reader user learns the
- * search returned nothing, rather than being left waiting. **From a region of
- * its own that is there before its words are**, filled a frame after the view
- * appears. The host was the region, and a page inserts an empty state with its
- * message already in it, which is a region arriving with its words: read
- * inconsistently at best.
+ * The message is announced, because an empty view often replaces content that
+ * was loading, and the announcement tells a screen reader user that the search
+ * returned nothing. It is announced from a status region of its own, which is
+ * rendered empty and filled a frame after the view appears. Screen readers read
+ * a region that arrives with its text already in it inconsistently.
  *
- * Every region is a bare slot. The reference ships an `empty-state-heading` and
- * an `empty-state-actions` whose only job is to assign themselves a slot on
- * connect, which is a component for something the consumer can write.
+ * Every region is a bare slot. There is no `empty-state-heading` or
+ * `empty-state-actions` element: assign your own heading and actions to the
+ * slots.
  *
  * @since 0.1.0
  * @status stable
@@ -26,12 +23,12 @@ import { type TemplateResult } from 'lit';
  * @aliases Placeholder, NoResults, Blank
  * @documentation https://fusion.dev/helix/components/empty
  *
- * @slot - Why, and what to do about it.
- * @slot actions - The way out.
- * @slot heading - What is missing.
- * @slot icon - A mark above the heading.
+ * @slot - The message: why the region is empty, and what to do about it.
+ * @slot actions - The action that would put something in the region.
+ * @slot heading - The heading, which names what is missing.
+ * @slot icon - An icon above the heading.
  *
- * @csspart live - The heading and the message again, in a region a screen reader hears when the view appears. Visually hidden in the styled tier.
+ * @csspart live - A copy of the heading and the message, in a live region that screen readers announce when the view appears. Visually hidden in the styled tier.
  */
 export declare class HelixHeadlessEmpty extends HelixElement {
     /**

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

@@ -3,19 +3,18 @@ import { type PropertyValues, type TemplateResult } from 'lit';
 import '../../tag/index.js';
 declare const HelixHeadlessFileInput_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
 /**
- * @summary A control for choosing files, by pointer or by dropping them on it.
+ * @summary A field for choosing files from a picker or by dropping them on it.
  *
  * @description
- * **A real `<input type="file">`, kept and made invisible rather than
- * replaced.** It is the only way to open a file picker: the dialog is a
- * privileged action a script cannot start on its own, and it opens for a click
- * on the input or on a `<label>` pointing at it. A component that draws its own
- * button calls `.click()` on a hidden input anyway, and then has two things a
- * screen reader can find where there is one control.
+ * File Input keeps a real `<input type="file">` and makes it invisible. Only a
+ * file input opens the file picker: the browser opens it for a click on the
+ * input or on a `<label>` that points at it, and a script cannot open it on its
+ * own. A custom button would still call `.click()` on a hidden input, and a
+ * screen reader would find two controls.
  *
- * So the input stays, holding the label, the name, the validity and the focus,
- * and the visible trigger is a `<label for>`. A label is not focusable and does
- * not need to be: the input is, and Enter and Space on it open the picker.
+ * The input holds the label, the name, the validity, and the focus, and the
+ * visible trigger is a `<label for>`. The label is not focusable. The input is,
+ * and Enter and Space on it open the picker.
  *
  * @since 0.1.0
  * @status stable
@@ -23,36 +22,36 @@ declare const HelixHeadlessFileInput_base: (new (...args: any[]) => import("@fus
  * @aliases FileUpload, FilePicker, Dropzone, InputFile
  * @documentation https://fusion.dev/helix/components/file-input
  *
- * @slot feedback - What is wrong with it.
+ * @slot feedback - The message that says what is wrong with the chosen files.
  * @slot hint - Help under the field.
- * @slot trigger - What the reader presses to open the picker.
+ * @slot trigger - The content that opens the picker when pressed.
  *
- * @event {Event} change - Announced once the value has moved.
- * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the chosen files change, with their names. Cancelable: refusing it takes the decision and the field keeps the files it had, a pick the browser has already written included.
- * @event {Event} input - Announced once the value has moved.
+ * @event {Event} change - Fired after the value changes.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the chosen files change, with their names, and cancelable. Canceling it keeps the files the field had, even when the browser has already written a new pick.
+ * @event {Event} input - Fired after the value changes.
  *
  * @csspart control - The file input itself, which carries the label and validity.
- * @csspart detail - Its name and its reading, stacked.
- * @csspart feedback - What is wrong with it.
- * @csspart field - The box that is pressed and dropped on.
+ * @csspart detail - A file's name, with its size and type below it.
+ * @csspart feedback - The message that says what is wrong.
+ * @csspart field - The box you press or drop files on.
  * @csspart file - One chosen file.
  * @csspart hint - Help under the field, while nothing is wrong.
- * @csspart kind - What kind of file it is.
+ * @csspart kind - A file's type.
  * @csspart kind-dismiss - The remove button, when `dismissible`.
  * @csspart kind-dismiss-mark - The glyph on the dismiss control, where none is slotted.
  * @csspart kind-start - The category before the label.
- * @csspart label - The question, over the field.
+ * @csspart label - The label above the field.
  * @csspart list - The chosen files.
- * @csspart meta - The row holding its size and kind.
- * @csspart name - Its name.
- * @csspart remove - The control that takes it back out.
- * @csspart size - How big it is.
+ * @csspart meta - The row that holds a file's size and type.
+ * @csspart name - A file's name.
+ * @csspart remove - The control that removes a file.
+ * @csspart size - A file's size.
  * @csspart size-dismiss - The remove button, when `dismissible`.
  * @csspart size-dismiss-mark - The glyph on the dismiss control, where none is slotted.
  * @csspart size-start - The category before the label.
  * @csspart trigger - The label that opens the picker.
  *
- * @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 HelixHeadlessFileInput extends HelixHeadlessFileInput_base {
     protected readonly aria: AriaForwardController;
@@ -75,7 +74,8 @@ export declare class HelixHeadlessFileInput extends HelixHeadlessFileInput_base
      */
     multiple: boolean;
     /**
-     * What the control removing one file is called, with `{name}` filled in.
+     * The accessible name of the control that removes a file. `{name}` is
+     * replaced with the file's name.
      *
      * **The name goes in**, so a row of them is heard as which one each
      * removes rather than as "Remove" said once per file. A label with no
@@ -83,7 +83,7 @@ export declare class HelixHeadlessFileInput extends HelixHeadlessFileInput_base
      */
     removeLabel: string;
     /**
-     * What the trigger reads, where nothing is slotted into it.
+     * The trigger's text when nothing is slotted into it.
      */
     triggerLabel: string;
     /**
@@ -96,7 +96,7 @@ export declare class HelixHeadlessFileInput extends HelixHeadlessFileInput_base
      */
     private dropping;
     /**
-     * The files chosen, which is the element's own and never assigned.
+     * The chosen files. It is read-only.
      *
      * Read from the input rather than mirrored into a field. The input is what
      * the picker filled and what a form submits, so a copy here could only ever
@@ -114,7 +114,7 @@ export declare class HelixHeadlessFileInput extends HelixHeadlessFileInput_base
      */
     private get control();
     /**
-     * Takes every file back out.
+     * Removes every chosen file.
      *
      * The one change a consumer can ask for. Setting a `FileList` is refused by
      * every browser for a reason worth keeping, but emptying one is not: nothing
@@ -122,7 +122,7 @@ export declare class HelixHeadlessFileInput extends HelixHeadlessFileInput_base
      */
     clear(): void;
     /**
-     * Drops one file, by index.
+     * Removes one file, by its index.
      *
      * `removeAt` rather than `remove`, which is `Element`'s own and takes no
      * arguments: shadowing it would break every caller who meant the node.
@@ -185,10 +185,10 @@ export declare class HelixHeadlessFileInput extends HelixHeadlessFileInput_base
     private readonly handleDrop;
     private readonly handleRemove;
     protected firstUpdated(changed: PropertyValues): void;
-    /** Puts focus on the input, the way a label pointing at one would. */
+    /** Moves focus to the native file input, as a label pointing at it would. */
     focus(options?: FocusOptions): void;
     /**
-     * Empties it, which is what a form reset means for a file input.
+     * Clears the chosen files when the form resets.
      *
      * Not through `commit`, and that is the point of the split: a reset is the
      * form's decision and there is nothing here for a listener to refuse. What it

package/dist/filter-input/chip/filter-chip.d.ts

@@ -2,39 +2,35 @@ import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessFilterChip_base: (new (...args: any[]) => import("@fusion.dev/helix-core").DismissibleElement) & typeof HelixElement;
 /**
- * @summary One filter in force: a field, how it is compared, and to what.
+ * @summary One active filter: a field, a comparison, and the values it is compared to.
  *
  * @description
- * A chip is the readable form of the thing `FilterField` declares. It carries
- * the three parts a filter has and a control that asks for it to go.
+ * Shows one filter declared by a `FilterField`: the field, the operator, and
+ * the values, with a control to remove the filter.
  *
- * **The operator is drawn only when it is worth drawing**, which is the whole
- * reason the common case reads as plainly as it does:
+ * The operator is shown only when it is not the field's default:
  *
  * ```
- * Disposition   refunded, chargeback         the field's usual comparison, unwritten
- * Disposition   is not   refunded            a comparison somebody chose, so it shows
- * Created       after    1 Aug               a scalar, which has no usual comparison
+ * Disposition   refunded, chargeback         default operator, hidden
+ * Disposition   is not   refunded            chosen operator, shown
+ * Created       after    1 Aug               a scalar field has no default
  * ```
  *
- * A reader ticking two values in a menu gets the first, with no jargon on it. A
- * reader who reaches for a comparison gets the third, which explains itself the
- * first time they see one. The rule is one line: **omit `operator-label` for the
- * field's default operator and pass it for every other.** Whoever builds the
- * chip holds the field, and the field knows which its default is.
+ * Omit `operator-label` for the field's default operator and pass it for every
+ * other operator. The code that builds the chip has the field, and the field
+ * defines its default.
  *
- * **It shows a filter and never applies one.** Dismissing is a request, the way
- * it is on `Tag` and `Announcement`: the chip is the consumer's element in a
- * consumer's list, and taking it out from under them would put their model and
- * the document out of step. `preventDefault()` on the `helix-dismiss` is a
- * refusal, and that is also how a consumer takes control of the interaction for
- * one press: `requestChange` documents the whole pattern, and its first line is
- * that control is an action rather than a mode.
+ * The chip shows a filter and does not apply it. Dismissing fires
+ * `helix-dismiss` as a request, as on `Tag` and `Announcement`. The chip is
+ * your element in your list, so you remove it, which keeps your model and the
+ * document in step. Call `preventDefault()` on `helix-dismiss` to cancel the
+ * dismissal, which is also how you take control of the interaction for one
+ * press. `requestChange` documents the pattern.
  *
- * **Changing the comparison belongs to whatever is slotted into `operator`.** A
- * menu trigger there makes the segment a control; the text fallback makes it a
- * label. This element does not learn either, for the reason `FilterOperator`
- * gives: what the words mean is the domain's.
+ * To let the user change the operator, slot a menu trigger into `operator`.
+ * With the text fallback, the operator is a label. The chip does not interpret
+ * operators: their meaning belongs to your domain, as `FilterOperator`
+ * explains.
  *
  * @since 0.23.0
  * @status stable
@@ -42,32 +38,32 @@ declare const HelixHeadlessFilterChip_base: (new (...args: any[]) => import("@fu
  * @aliases FilterToken, FacetChip
  * @documentation https://fusion.dev/helix/components/filter-input
  *
- * @slot - What the field is compared to, which is usually text and may be
- * anything a consumer wants read there.
- * @slot field - Replaces the field's name, for a chip that wants a mark beside
- * it or a shortened form.
- * @slot operator - Replaces the comparison, and is where a control that changes
- * it goes.
+ * @slot - The values the field is compared to, usually as text. It takes any
+ * content you want shown there.
+ * @slot field - Replaces the field's name. Use it to put an icon beside the name
+ * or to shorten it.
+ * @slot operator - Replaces the comparison. Put a control that changes the
+ * comparison here.
  *
- * @event {HelixDismissEvent} helix-dismiss - Fired when the reader asks to remove the filter. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixDismissEvent} helix-dismiss - Fired when the user asks to remove the filter. Cancelable: call `preventDefault()` to keep the chip.
  *
- * @csspart dismiss - The control that asks to remove the filter.
- * @csspart dismiss-mark - The glyph on the dismiss control, where none is slotted.
+ * @csspart dismiss - The button that removes the filter.
+ * @csspart dismiss-mark - The icon on the remove button, shown when no icon is slotted.
  * @csspart field - The name of what is being filtered.
- * @csspart operator - How it is compared, drawn only where there is one to draw.
- * @csspart values - What it is compared to.
+ * @csspart operator - The comparison, drawn only when there is one to show.
+ * @csspart values - The values the field is compared to.
  */
 export declare class HelixHeadlessFilterChip extends HelixHeadlessFilterChip_base {
     dismissLabel: string;
     /**
-     * The field this filter is on, as a reader sees it.
+     * The name of the field the filter is on, as shown on the chip.
      *
      * The slot's fallback rather than the slot's replacement: a consumer who wants
      * a mark beside the name slots `field` and this goes unused.
      */
     label: string;
     /**
-     * The field this filter is on, as the consumer's model calls it.
+     * The name of the field the filter is on, in your data model.
      *
      * Never shown. Reflected, because a consumer removing one filter from a list
      * of them selects on this, and so undefaulted for the reason `operator` gives.
@@ -83,7 +79,7 @@ export declare class HelixHeadlessFilterChip extends HelixHeadlessFilterChip_bas
      */
     name?: string;
     /**
-     * What the consumer's own model calls the comparison in force.
+     * The name of the active comparison in your data model.
      *
      * Never shown, and it is what a consumer matches on when the chip comes back
      * to them. `label` translates; this does not.
@@ -94,7 +90,8 @@ export declare class HelixHeadlessFilterChip extends HelixHeadlessFilterChip_bas
      */
     operator?: string;
     /**
-     * The comparison, as a reader sees it, and empty for the field's usual one.
+     * The comparison as shown on the chip. Leave it empty for the field's usual
+     * comparison.
      *
      * **Empty is the whole design and not an oversight.** A chip drawn for the
      * comparison a field is normally filtered by says the field and the values and