@fusion.dev/helix-headless 0.104.1 → 0.106.0

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

@@ -4,13 +4,12 @@ import type { HelixHeadlessOption } from '../../option/index.js';
 import { type FilterGrammarField } from '../grammar.js';
 import type { HelixHeadlessFilterOperator } from '../operator/filter-operator.js';
 /**
- * @summary One thing a set can be filtered by, and how.
+ * @summary A field that a filter can apply to, with its comparisons and values.
  *
  * @description
- * **A declaration, not a control.** It renders nothing and is never seen. A
- * consumer writes one per field, with the comparisons that field supports and
- * the values it supports them on, and the filter input reads them to build its
- * menu:
+ * Declares a filter field. It renders nothing. Write one per field, with the
+ * operators that field supports and its values, and the filter input reads them
+ * to build its menu:
  *
  * ```html
  * <helix-headless-filter-field name="disposition" label="Disposition">
@@ -22,25 +21,19 @@ import type { HelixHeadlessFilterOperator } from '../operator/filter-operator.js
  * </helix-headless-filter-field>
  * ```
  *
- * **Operators are per field and never global.** `is after` belongs to a date and
- * `has all of` to a set, and a field that supports one comparison shows no
- * chooser at all. A global list would offer every field every word and leave the
- * component deciding which of them made sense, which is the domain question it
- * declines to answer.
+ * Operators are declared per field. `is after` fits a date and `has all of`
+ * fits a set. A field with one operator shows no operator chooser.
  *
- * **A field that declares none gets two, and they are the ones the punctuation
- * can say.** `is any of` and `is none of` are what `field:a,b` and `-field:a,b`
- * mean, so declaring them was ceremony for the case every product has; the
- * example above is what a consumer writes when the words matter, not the price
- * of admission. Declaring one comparison replaces both rather than joining
- * them: see `vocabulary`, which is where that is decided once for the menu and
- * the grammar together.
+ * A field that declares no operators gets two: `is any of` and `is none of`,
+ * which match the typed forms `field:a,b` and `-field:a,b`. Declare operators,
+ * as in the example above, when you want to set the words. Declaring any
+ * operator replaces both defaults. `vocabulary` defines this once for both the
+ * menu and the grammar.
  *
- * **Values are `Option`s, which is the element a consumer already has.** They
- * carry a value, a label and a disabled state, and a picker built on `Menu` or
- * `Listbox` can render them without this element inventing a second way to say
- * the same thing. A field whose values cannot be enumerated declares none, and
- * what fills a chip then is whatever the consumer types.
+ * Values are `Option` elements, with a value, a label, and a disabled state, so
+ * a picker built on `Menu` or `Listbox` can render them directly. A field whose
+ * values cannot be listed declares none, and a chip for it holds whatever you
+ * type.
  *
  * @since 0.23.0
  * @status stable
@@ -48,16 +41,17 @@ import type { HelixHeadlessFilterOperator } from '../operator/filter-operator.js
  * @aliases Facet, Dimension
  * @documentation https://fusion.dev/helix/components/filter-input
  *
- * @slot - The comparisons this field supports, as `FilterOperator`s, and the
- * values it supports them on, as `Option`s. Neither is rendered: they are read.
+ * @slot - The field's comparisons, as `FilterOperator`s, and its values, as
+ * `Option`s. The filter input reads them and does not render them.
  */
 export declare class HelixHeadlessFilterField extends HelixElement {
     /**
-     * What a reader is shown, in the menu and on every chip built from this field.
+     * The field's name as shown in the menu and on every chip built from the
+     * field.
      */
     label: string;
     /**
-     * What the consumer's own model calls this field.
+     * The field's name in your data model.
      *
      * Never shown, and what arrives in the filter this helps build.
      *
@@ -66,7 +60,7 @@ export declare class HelixHeadlessFilterField extends HelixElement {
      */
     name?: string;
     /**
-     * The comparisons declared under this field, in the order they were written.
+     * The comparisons declared in the field, in source order.
      *
      * Read from the light DOM rather than from a slot, because there is no slot:
      * this element renders nothing, so nothing is ever assigned. Order is the
@@ -78,8 +72,8 @@ export declare class HelixHeadlessFilterField extends HelixElement {
      */
     get operators(): HelixHeadlessFilterOperator[];
     /**
-     * The comparison a chip leaves unwritten, or nothing where the consumer named
-     * none.
+     * The comparison a chip does not show, or `null` when no operator is marked
+     * `default`.
      *
      * **The first one marked, and a second is reported rather than resolved.** Two
      * defaults on one field is a consumer saying two different things, and picking
@@ -90,7 +84,7 @@ export declare class HelixHeadlessFilterField extends HelixElement {
      */
     get defaultOperator(): HelixHeadlessFilterOperator | null;
     /**
-     * The values declared under this field, in the order they were written.
+     * The values declared in the field, in source order.
      *
      * Empty is meaningful rather than missing: a field whose values cannot be
      * listed, a free text search or an open ended number, declares none and the
@@ -98,7 +92,7 @@ export declare class HelixHeadlessFilterField extends HelixElement {
      */
     get values(): HelixHeadlessOption[];
     /**
-     * This field flattened into what the menu renders and the grammar reads.
+     * The field as flat data, for the menu to render and the grammar to read.
      *
      * **The one place the defaults are applied.** A field that declares no
      * comparisons supports `is any of` and `is none of`, which is what the typed

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

@@ -5,13 +5,12 @@ import type { FilterGrammarOperator } from '../grammar.js';
 import '../../divider/index.js';
 import '../../menu/index.js';
 /**
- * @summary The control that builds a filter: pick a field, tick its values.
+ * @summary A menu for building a filter by picking a field and checking its values.
  *
  * @description
- * **It reads the declarations and renders a menu.** A consumer writes their
- * fields as `FilterField`s inside this, and what comes out is a two level menu:
- * the fields, and under each one its comparisons and its values. Nothing here
- * knows what a field means, which is the line `FilterField` already draws.
+ * Reads the `FilterField` declarations inside it and renders a two-level menu:
+ * the fields, and under each field its operators and values. The menu does not
+ * interpret what a field means.
  *
  * ```html
  * <helix-headless-filter-menu label="Filter">
@@ -21,33 +20,36 @@ import '../../menu/index.js';
  * </helix-headless-filter-menu>
  * ```
  *
- * That field declares no comparisons and so is offered `is any of` and `is none
- * of`, which are the two the typed grammar can say. The menu and the text end up
- * offering the same filters because both read `FilterField.vocabulary`, and a
- * consumer whose field needs other words declares them there.
+ * That field declares no operators, so it offers `is any of` and `is none of`,
+ * the two the typed grammar supports. The menu and the typed text offer the
+ * same filters because both read `FilterField.vocabulary`. Declare other
+ * operators on the field when you need them.
  *
- * **A tick is a filter, immediately.** There is no Apply: ticking a value
- * announces the field's whole set as it now stands, so a queue narrows as the
- * reader works rather than after they have finished. Unticking the last value
- * announces an empty set, which is a consumer's cue to drop the chip.
+ * Ticking a value applies the filter immediately. There is no Apply button.
+ * Each tick fires `helix-facet` with the field's whole set of values, so
+ * results narrow as the user works. Unticking the last value fires an empty
+ * set, which is your cue to remove the chip.
  *
- * **The operator is chosen here and written nowhere else.** `helix-facet` carries
- * `operatorLabel` empty when the comparison is the field's default, which is
- * exactly what a chip's `operator-label` wants: the segment appears only where
- * somebody picked something worth noticing. Deciding it here is the point, since
- * this is the only thing that has read both the field and its operators.
+ * The operator is chosen in the menu. `helix-facet` carries an empty
+ * `operatorLabel` when the operator is the field's default, which is the value
+ * a chip's `operator-label` expects, so the operator segment appears only for a
+ * non-default choice. The menu decides this because it is the only element that
+ * reads both the field and its operators.
  *
- * **How many values a comparison takes decides what is under it.** A field
- * whose comparison is `arity="none"`, `is empty` or `is set`, is offered no
- * values at all and gives back any that were ticked: the comparison is the whole
- * filter. One at `arity="one"` offers its values as a single choice, so pressing
- * another replaces it and pressing the one already on clears it. Both announce
- * `arity` in the facet, which is what lets a consumer tell an empty filter from
- * no filter at all.
+ * An operator's `arity` sets what appears under it:
  *
- * **It applies nothing.** The chips are the consumer's markup and the rows are
- * their data, so this announces and stops, the way `Notification` reports a read
- * rather than inventing one. Refusing `helix-facet` refuses the change.
+ * - `arity="none"`, such as `is empty` or `is set`, offers no values and clears
+ *   any that were ticked. The operator is the whole filter.
+ * - `arity="one"` offers the values as a single choice. Pressing another value
+ *   replaces the choice, and pressing the chosen value clears it.
+ *
+ * `helix-facet` includes `arity`, so you can tell an empty filter from no
+ * filter.
+ *
+ * The menu applies nothing. The chips are your markup and the rows are your
+ * data, so the menu fires the event and leaves the change to you, as
+ * `Notification` does for a read. Call `preventDefault()` on `helix-facet` to
+ * cancel the change.
  *
  * @since 0.25.0
  * @status stable
@@ -55,31 +57,31 @@ import '../../menu/index.js';
  * @aliases FacetPicker, FilterBuilder
  * @documentation https://fusion.dev/helix/components/filter-input
  *
- * @slot - The fields this can filter by, as `FilterField`s. Read rather than rendered.
- * @slot trigger - The control that opens the menu. A `Button` is the usual one.
+ * @slot - The fields the menu can filter by, as `FilterField`s. The menu reads them and does not render them.
+ * @slot trigger - The control that opens the menu, usually a `Button`.
  *
- * @event {HelixFacetEvent} helix-facet - Fired when a field's values change. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixFacetEvent} helix-facet - Fired when a field's values change. Cancelable: call `preventDefault()` to keep the previous values.
  *
- * @csspart divider - The rule between a field's comparisons and its values.
- * @csspart divider-content - What is set into the rule.
- * @csspart divider-line - The rule itself.
- * @csspart entry - One row: a field, its comparison, an operator or a value.
+ * @csspart divider - The line between a field's comparisons and its values.
+ * @csspart divider-content - The content set into the line.
+ * @csspart divider-line - The line itself.
+ * @csspart entry - One row: a field, its comparison, an operator, or a value.
  * @csspart entry-item - The row itself.
- * @csspart entry-mark - The trailing mark: a tick on a chosen value, a caret on a field.
+ * @csspart entry-mark - The mark at the end of a row: a check mark on a chosen value, and a caret on a field.
  * @csspart entry-start - The leading column.
  * @csspart menu - The menu the fields are offered in.
- * @csspart menu-back - The control that returns from a field's page.
- * @csspart menu-back-mark - The glyph on the back control.
+ * @csspart menu-back - The button that goes back from a field's page.
+ * @csspart menu-back-mark - The icon on the back button.
  * @csspart menu-empty - Shown when there are no fields to offer.
- * @csspart menu-header - The bar above a field's page, holding the way back and its name.
- * @csspart menu-live - The inner menu's `live`, the region a screen reader hears its empty and loading lines from.
- * @csspart menu-loading - Shown while the fields are still on their way.
+ * @csspart menu-header - The bar above a field's page, with the back button and the field's name.
+ * @csspart menu-live - The inner menu's `live` part: the region that screen readers announce the empty and loading messages from.
+ * @csspart menu-loading - Shown while the fields are loading.
  * @csspart menu-surface - The floating panel the menu is drawn on.
  * @csspart menu-title - The name of the field whose page is showing.
  */
 export declare class HelixHeadlessFilterMenu extends HelixElement {
     /**
-     * Accessible name for the menu.
+     * The menu's name, read by screen readers.
      */
     label: string;
     /**
@@ -94,7 +96,7 @@ export declare class HelixHeadlessFilterMenu extends HelixElement {
     /** Which comparison each field is using, where the reader chose one. */
     private readonly comparisons;
     /**
-     * The fields declared inside this, in the order they were written.
+     * The fields declared inside the menu, in source order.
      *
      * What a render may know of them: none on a server, whose shim has no tree
      * and threw here, and none while hydrating what one sent.
@@ -107,11 +109,11 @@ export declare class HelixHeadlessFilterMenu extends HelixElement {
      */
     get fields(): HelixHeadlessFilterField[];
     protected firstUpdated(changed: PropertyValues): void;
-    /** What is ticked for one field, as the consumer's own values. */
+    /** The values checked for one field. */
     valuesFor(field: string): readonly string[];
     /**
-     * Which comparison a field is using: the reader's choice, then the one the
-     * field marked, then the first one it supports.
+     * The comparison a field uses: the one the user chose, or the field's
+     * `default`, or the first one the field supports, in that order.
      *
      * **The last of those is not a fallback for nothing, it is the scalar case.**
      * A date supports `after` and nothing else and marks no default, because there
@@ -135,7 +137,8 @@ export declare class HelixHeadlessFilterMenu extends HelixElement {
      */
     private announce;
     /**
-     * Filters a field by these values, announcing it the way a tick does.
+     * Filters a field by the given values and sends `helix-facet`, as checking a
+     * value does.
      *
      * **The one way this element's state changes**, whether the move came from a
      * row here, from a filter typed into the field around it, or from a chip

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

@@ -4,23 +4,18 @@ import { nothing, type PropertyValues } from 'lit';
  * @summary One way a filter can compare a field to its values.
  *
  * @description
- * **A declaration, not a control.** It renders nothing and is never seen: it is
- * how a consumer says which comparisons their field supports, in markup, beside
- * the values it supports them on. `Field` reads them; the chip shows the one in
- * force; the menu offers the rest.
+ * Declares one operator a field supports. It renders nothing. Write operators
+ * in markup beside the field's values. `FilterField` reads them, the chip shows the
+ * one in use, and the menu offers the rest.
  *
- * **The vocabulary is the consumer's and this element never learns it.** What
- * `is none of` means against a queue of refunds is a question about refunds, so
- * nothing here compares anything or knows what `name` will be handed to. Helix
- * owns the shape a filter has, which is a field, an operator and some values,
- * and owns the interaction that builds one. What the words mean is the domain's,
- * which is the same line `FilterInput` already draws when it declines to learn a
- * grammar.
+ * Helix defines the shape of a filter, which is a field, an operator, and
+ * values, and the interaction that builds one. The meaning of each operator
+ * belongs to your domain: the element compares nothing and does not interpret
+ * `name`.
  *
- * **`default` is what makes a chip readable.** The operator a field is usually
- * filtered by is the one nobody needs told, so a chip drawn with it says only
- * the field and the values. Naming a second operator `default` on one field is a
- * consumer bug and the field reports it rather than guessing.
+ * Mark the field's usual operator `default`. A chip with the default operator
+ * shows only the field and the values. Marking a second operator `default` on
+ * one field is an error, and the field reports it.
  *
  * @since 0.23.0
  * @status stable
@@ -30,7 +25,7 @@ import { nothing, type PropertyValues } from 'lit';
  */
 export declare class HelixHeadlessFilterOperator extends HelixElement {
     /**
-     * How many values this comparison takes.
+     * How many values the comparison takes.
      *
      * `none` is a comparison that is complete on its own, which is what `is empty`
      * and `is set` are: a chip drawn for one shows no values because there are
@@ -60,8 +55,8 @@ export declare class HelixHeadlessFilterOperator extends HelixElement {
      */
     arity?: 'many' | 'none' | 'one';
     /**
-     * Whether this is the comparison the field is filtered by unless asked
-     * otherwise.
+     * Marks the comparison as the field's usual one, used unless the user picks
+     * another.
      *
      * The chip leaves a default operator unwritten, so the common filter reads as
      * a field and its values and nothing else, and the word only appears once
@@ -69,7 +64,7 @@ export declare class HelixHeadlessFilterOperator extends HelixElement {
      */
     default: boolean;
     /**
-     * What a reader is shown, in the chip and in the menu that changes it.
+     * The comparison's text, shown on the chip and in the menu that changes it.
      *
      * Words rather than symbols, and the reason is that a set has more than one
      * negation: `!=` cannot tell "is none of" from "is not all of", and both are
@@ -78,7 +73,7 @@ export declare class HelixHeadlessFilterOperator extends HelixElement {
      */
     label: string;
     /**
-     * What the consumer's own model calls this comparison.
+     * The comparison's name in your data model.
      *
      * Never shown. It is what arrives in the filter this element helps build, so
      * a consumer matches on it rather than on the words a reader sees, and

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

@@ -3,83 +3,64 @@ import { type PropertyValues, type TemplateResult } from 'lit';
 import type { HelixHeadlessFilterField } from '../field/filter-field.js';
 declare const HelixHeadlessFilterInput_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 narrows something else, beside what is already narrowing it.
+ * @summary A text field for filters, with the active filters shown in it as tokens.
  *
  * @description
- * **The tokens are the consumer's own elements, slotted.** What a filter narrows
- * by belongs to the consumer's model rather than to this element: a facet with a
- * prefix, a saved query, a range. So they are slotted rather than rendered from
- * a list of strings, and removing one is a request this element makes rather
- * than a change it applies. Combobox is the other way round, and that is the
- * difference between the two: its tokens are a view of a selection it owns,
- * drawn from options it was handed.
+ * Tokens are your own elements, slotted in. A filter can be a facet with a
+ * prefix, a saved query, or a range, and these belong to your model, so the
+ * element does not render tokens from a list of strings. Removing a token is a
+ * request the element fires, and you apply it. Combobox works the other way:
+ * its tokens show a selection it owns, drawn from the options it was given.
  *
- * **`value` is the text being typed, not the tokens**, which is what makes this
- * a field a consumer can listen to. Every keystroke announces `input` with the
- * text on the element, so a table narrows as the reader types. The tokens need
- * no reporting back, being markup the consumer already holds.
+ * `value` is the typed text. Every keystroke fires `input` with the text on the
+ * element, so a table can narrow as the user types. Tokens are not reported,
+ * because they are markup you already hold. Backspace in an empty field fires
+ * `helix-dismiss` on the last token, the same event its remove control fires,
+ * so one handler covers the pointer and the keyboard.
  *
- * Backspace on an empty field asks the last token to go, through the same
- * `helix-dismiss` its own remove control fires, so a consumer who handled the
- * pointer has already handled the keyboard.
+ * **Typed filters.** The field parses only the fields you declare. Write
+ * `FilterField` elements, usually inside the `FilterMenu` slotted into `start`,
+ * so the picker and the text share one set. On Enter, the field reads the text
+ * against them. `disposition:refunded,settled` and `-disposition:refunded` fire
+ * `helix-facet` exactly as ticking those values in the picker would, and the
+ * parsed text is removed. Everything else stays, so `refund tuesday
+ * disposition:settled` is a filter and a search at once. Helix defines the
+ * punctuation and you define every word. `grammar.ts` has the full rule, so
+ * read it before you rely on it. A field with no `FilterField` in it parses
+ * nothing.
  *
- * **It reads what was declared, and nothing that was not.** Write
- * `FilterField`s (usually inside the `FilterMenu` slotted into `start`, so the
- * picker and the text work off one set), and Enter reads the box against them:
- * `disposition:refunded,settled` and `-disposition:refunded` announce
- * `helix-facet`, exactly as ticking those values in the picker would, and the
- * text they were read from goes. Everything else stays where it was typed, so
- * `refund tuesday disposition:settled` is a filter and a search at once.
- * `grammar.ts` carries the whole rule and is worth reading before relying on it;
- * the short version is that Helix owns the punctuation and the consumer owns
- * every word in it. A field with no `FilterField` in it parses nothing, which is
- * the behavior this had before it could.
+ * A field whose values cannot be listed, such as `assignee:ada`, goes directly
+ * inside this element, outside the menu. It is not assigned to a slot, so
+ * nothing draws it and the menu has no page for it, and the grammar still reads
+ * it.
  *
- * **A field whose values cannot be listed belongs here rather than in the
- * picker.** `assignee:ada` is a filter and nobody wants to enumerate every name
- * in the company, but a menu page for it would have nothing on it to press.
- * Written directly inside this element it is read by the grammar and never
- * offered as a page: unslotted, so nothing draws it, which is the same trick
- * `FilterField` already plays on its own children.
+ * **Suggestions.** Slot options into `suggestions` and the field shows them,
+ * moves through them with the arrow keys, and presses one on Enter. The option
+ * fires its own `helix-select`, and you decide what choosing it means. Keys
+ * before a colon and values after it use the same panel with different
+ * contents. `readFilterText` is exported so you can narrow the panel against
+ * partly typed text. The panel opens when it has options and closes when it has
+ * none, and a choice does not close it, so after picking a key you see its
+ * values next. Use `selectionStart` and `setSelectionRange` to write a
+ * completion back and put the caret after it, or the next parse reads the wrong
+ * term.
  *
- * **It can suggest what to type next, and deciding what to suggest is still the
- * consumer's.** Slot options into `suggestions` and the field shows them, moves
- * through them with the arrows, and lets Enter press one; the option fires its
- * own `helix-select` and the consumer decides what choosing meant. Keys before
- * a colon and values after it are the same panel with different contents, and
- * `readFilterText` is exported for a consumer narrowing that panel against what
- * a reader has half typed.
+ * **State.** Three things have three different owners:
  *
- * **The panel opens when there is something in it and closes when there is
- * not**, rather than on a choice. A reader who picks a key wants its values
- * next, and closing on the choice would shut the panel between two renders. Use
- * `selectionStart` and `setSelectionRange` to write a completion back and put
- * the caret after it, or the next parse reads the wrong term.
- *
- * **Three things here have three different owners.**
- *
- * `value` is the text: the reader types, the element applies it, and `input`
- * says so. **Writing `value` does not take that over.** It is a seed and a
- * correction, so a consumer who sets it and then expects the field to hold
- * still will watch the next keystroke overwrite them.
- * Ownership is taken by refusing `helix-before-change` and writing the value
- * you want, which is the same shape every field in this library uses and is
- * worth saying out loud here because the property looks like React's.
- * `default-value` seeds the field without claiming anything.
- *
- * `open` is the suggestions panel, and it is the ordinary pair: refuse
- * `helix-before-open` or `helix-before-close` to take the decision, and
- * `default-open` to seed it.
- *
- * The tokens are neither, because they are not state. They are the consumer's
- * own elements in a slot, so there is nothing for this to own and nothing to
- * report back: a token goes when the consumer removes it from their markup,
- * having been asked by `helix-dismiss`. **A `FilterChip` naming a declared field
- * is asked differently**, and it has to be: the picker holds what is ticked, so
- * a chip that removed itself without telling it left the value ticked in a list
- * nobody could see was wrong. That dismissal is answered as the field being
- * filtered by nothing, so it arrives as `helix-facet` like every other change
- * and the chip goes because the filter went.
+ * - `value` is the text. The user types, the element applies it, and `input`
+ *   reports it. Setting `value` seeds or corrects the text, and the next
+ *   keystroke overwrites it, even in React. To control the value, cancel
+ *   `helix-before-change` and write the value you want, as with every field in
+ *   this library. `default-value` seeds the field.
+ * - `open` is the suggestions panel. Cancel `helix-before-open` or
+ *   `helix-before-close` to control it, and use `default-open` to seed it.
+ * - Tokens are your elements in a slot and hold no state. A token goes when you
+ *   remove it from your markup after `helix-dismiss`. A `FilterChip` naming a
+ *   declared field works differently, because the picker holds what is ticked
+ *   and removing the chip alone would leave its value ticked in the hidden
+ *   menu. Its dismissal is treated as the field being filtered by nothing, so
+ *   it fires `helix-facet` like every other change, and the chip goes when the
+ *   filter goes.
  *
  * @since 0.1.0
  * @status stable
@@ -87,41 +68,41 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  * @aliases SearchField, FacetInput, TokenInput
  * @documentation https://fusion.dev/helix/components/filter-input
  *
- * @slot end - After the text, for a count or a control.
- * @slot start - Before the text, for a search icon.
- * @slot suggestions - What could be typed next, as `Option`s, and `Option.Group`s of them.
- * @slot tags - What is already narrowing the results, as `FilterChip`s or `Tag`s.
+ * @slot end - Content after the text, such as a count or a control.
+ * @slot start - Content before the text, such as a search icon.
+ * @slot suggestions - Suggestions for what to type next, as `Option`s and `Option.Group`s.
+ * @slot tags - The active filters, as `FilterChip`s or `Tag`s.
  *
- * @event {Event} change - Relayed from the input once the reader has finished.
- * @event {HelixBeforeChangeEvent} helix-before-change - Fired as the text changes, and cancelable.
- * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the suggestions go, and cancelable.
- * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the suggestions show, and cancelable.
- * @event {HelixDismissEvent} helix-dismiss - A token asking to go, from its close control or from Backspace on an empty field. A `FilterChip` naming a declared field is answered as `helix-facet` instead. Cancelable: refusing it takes the decision and the token stays.
- * @event {HelixFacetEvent} helix-facet - Fired when a filter changes, whether read out of the text, picked, or dismissed. Cancelable: refusing it leaves the text and the chip where they were.
- * @event {HelixSelectEvent} helix-select - A suggestion was chosen: the option's own, heard here because it bubbles out of `suggestions`. Cancelable: refusing it takes the decision from any other listener, and this field never acts on a choice itself, since what it means is the page's.
- * @event {Event} input - Announced once the text has moved.
- * @event {Event} toggle - Says the panel moved, carrying `newState` and `oldState`.
+ * @event {Event} change - Fired from the input when the user finishes editing the text.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired as the text changes. Cancelable: call `preventDefault()` to keep the current text.
+ * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the suggestions close. Cancelable: call `preventDefault()` to keep them open.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the suggestions open. Cancelable: call `preventDefault()` to keep them closed.
+ * @event {HelixDismissEvent} helix-dismiss - Fired when the user removes a token with its remove button or with Backspace in an empty field. A `FilterChip` that names a declared field sends `helix-facet` instead. Cancelable: call `preventDefault()` to keep the token.
+ * @event {HelixFacetEvent} helix-facet - Fired when a filter changes, whether it was typed, picked, or removed. Cancelable: call `preventDefault()` to leave the text and the chip as they were.
+ * @event {HelixSelectEvent} helix-select - Fired by an option in `suggestions` when it is chosen, and bubbles out of the field. Cancelable: call `preventDefault()` to stop other listeners acting on it. The field takes no action on a choice; you decide what it does.
+ * @event {Event} input - Fired when the text changes.
+ * @event {Event} toggle - Fired when the suggestions panel opens or closes, with `newState` and `oldState`.
  *
  * @csspart clear - The button that empties the field.
  * @csspart control - The input itself.
- * @csspart feedback - What is wrong with it.
- * @csspart field - The box holding everything.
- * @csspart hint - Help under the field, while nothing is wrong.
- * @csspart label - The question, over the field.
- * @csspart lead - The box before the text, holding whatever is slotted into `start`.
- * @csspart rest - How many tokens did not fit. A `<button>` with `expandable`, a `<span>` without it.
+ * @csspart feedback - The error message under the field.
+ * @csspart field - The box that holds everything.
+ * @csspart hint - The help text under the field, shown while there is no error.
+ * @csspart label - The label above the field.
+ * @csspart lead - The box before the text that holds the `start` slot.
+ * @csspart rest - The count of tokens that did not fit. It is a `<button>` with `expandable` and a `<span>` without it.
  * @csspart surface - The floating panel the suggestions sit in.
  * @csspart tags - The row the tokens sit in.
  *
- * @cssstate invalid - While there is feedback to show: the platform's verdict, or the consumer's `feedback`.
- * @cssstate open - While the suggestions are open.
+ * @cssstate invalid - The field has an error to show, from the browser's validation or from your `feedback`.
+ * @cssstate open - The suggestions are open.
  */
 export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_base {
     protected readonly aria: AriaForwardController;
     /** Typed, so every keystroke is announced. See `announcesInput`. */
     protected readonly announcesInput = true;
     /**
-     * Whether the field offers a button that empties it.
+     * Shows a button that empties the field.
      *
      * The text only. The tokens are the consumer's markup and this element is not
      * entitled to take them out of the document, which is the same reason
@@ -130,11 +111,12 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
      */
     clearable: boolean;
     /**
-     * What the clear button is called, since an icon has no name of its own.
+     * The name of the clear button, read by screen readers. The button shows only
+     * an icon.
      */
     clearLabel: string;
     /**
-     * Shown while the field is empty.
+     * The text shown while the field is empty.
      *
      * Not a label: it goes when typing starts.
      */
@@ -214,7 +196,7 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
      */
     private get suggestions();
     /**
-     * The caret and the selection, under the platform's own names.
+     * The direction of the selection, named as on `<input>`.
      *
      * **Published for the reason `Input` publishes them, and this element needs
      * them more.** The `<input>` is inside this shadow root, so a consumer has no
@@ -228,9 +210,9 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
      * be anyway.
      */
     get selectionDirection(): 'backward' | 'forward' | 'none';
-    /** Where the selection ends, which is the caret when nothing is selected. */
+    /** Where the selection ends. With nothing selected, it is the caret position. */
     get selectionEnd(): number;
-    /** Where the selection starts, which is the caret when nothing is selected. */
+    /** Where the selection starts. With nothing selected, it is the caret position. */
     get selectionStart(): number;
     /** Moves the caret, or selects a run of the text. */
     setSelectionRange(start: number, end: number, direction?: 'backward' | 'forward' | 'none'): void;
@@ -245,7 +227,7 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
     /** Relayed, because `change` does not cross a shadow boundary on its own. */
     private readonly handleChange;
     /**
-     * The fields this can be filtered by, wherever they were written.
+     * The fields the input can filter by, declared anywhere inside it.
      *
      * Descendants rather than children, because the usual place to write them is
      * inside the `FilterMenu` slotted into `start`: the picker and the text are
@@ -392,7 +374,7 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
      * and the highlight is still drawn.
      */
     private markActive;
-    /** Puts the caret in the field, the way a label pointing at one would. */
+    /** Puts the caret in the text field. */
     focus(options?: FocusOptions): void;
     protected render(): TemplateResult;
 }