@fusion.dev/helix-headless 0.105.0 → 0.106.0

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;
 }

package/dist/format-date/root/format-date-root.d.ts

@@ -1,33 +1,24 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 /**
- * @summary A timestamp, written the way the reader's locale writes one.
+ * @summary A timestamp, formatted for the user's locale.
  *
  * @description
- * A date in a page is almost never wanted as an ISO string, and formatting one
- * in the consumer's own code means every consumer ships a copy of the same
- * `Intl` call and a different set of options. This is that call, as an element,
- * so a date is written where it is shown.
+ * Formats a date with `Intl` where it is shown, so you do not write the same
+ * `Intl` call and options in your own code.
  *
- * **`elapsed` is the mode a feed wants, and it stops being relative on
- * purpose.** "42m", "3h", "1d" is what a row of activity reads as, and past a
- * week the compact form is a lie: `Intl.NumberFormat` narrow renders both
- * `minute` and `month` as `m` in en-US, so "3m" is three minutes at the top of a
- * feed and three months further down it. Past six days this shows a date, which
- * is shorter to read and impossible to misread. `elapsedTime` in `helix/core`
- * carries the measurement.
+ * **`elapsed` shows compact relative time for a feed**, such as "42m", "3h", or
+ * "1d". After six days it shows a date. In en-US, `Intl.NumberFormat` narrow
+ * renders both `minute` and `month` as `m`, so a compact "3m" could mean three
+ * minutes or three months. `elapsedTime` in `helix/core` does the measurement.
  *
- * **The reading refreshes itself, from one timer the page shares.** A relative
- * timestamp is correct for as long as its unit lasts and wrong afterwards, and a
- * page left open is exactly where that shows. Each element asks to be woken when
- * its own reading expires rather than polling, and an element showing a date
- * asks for nothing at all: fifty rows and fifty intervals is fifty wakeups a
- * second where one will do, and a feed of last month's notifications should cost
- * nothing to leave open.
+ * **The text refreshes on one timer shared by the page.** Each element
+ * schedules an update for when its current reading expires, and an element
+ * showing a date schedules none, so a long feed left open costs almost nothing.
  *
- * **`<time datetime>` whatever the text says**, so a screen reader, a copy and
- * paste, and anything parsing the page all get the real instant rather than
- * "yesterday".
+ * **The output is always `<time datetime>`**, so screen readers, copy and
+ * paste, and scripts parsing the page get the exact instant, whatever the
+ * visible text says.
  *
  * @since 0.1.0
  * @status stable
@@ -35,11 +26,11 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * @aliases RelativeTime, Timestamp, TimeAgo
  * @documentation https://fusion.dev/helix/components/format-date
  *
- * @csspart time - The `<time>` element carrying the reading.
+ * @csspart time - The `<time>` element that holds the formatted text.
  */
 export declare class HelixHeadlessFormatDate extends HelixElement {
     /**
-     * The timestamp, as anything `Date` parses.
+     * The timestamp, in any format `Date` can parse.
      *
      * An ISO string is what an API sends and what `<time datetime>` takes, so it
      * is the shape that needs no translation at either end. Left unset this
@@ -61,7 +52,8 @@ export declare class HelixHeadlessFormatDate extends HelixElement {
      */
     day?: 'numeric' | '2-digit';
     /**
-     * Show how long ago it was, compactly, instead of the date.
+     * Shows how long ago the timestamp was, in a compact form such as "3h", in
+     * place of the date.
      *
      * Reflected, because it is the one property that decides which of two readings
      * this is and a stylesheet has a reason to know: a compact reading is a fixed
@@ -73,7 +65,7 @@ export declare class HelixHeadlessFormatDate extends HelixElement {
      */
     hour?: 'numeric' | '2-digit';
     /**
-     * Locale for the reading.
+     * The locale to format the timestamp in.
      *
      * Empty is the runtime's own.
      */
@@ -97,7 +89,7 @@ export declare class HelixHeadlessFormatDate extends HelixElement {
      */
     timeZone?: string;
     /**
-     * Whether to name the time zone, and how.
+     * Shows the name of the time zone, in its `long` or `short` form.
      */
     timeZoneName?: 'long' | 'short';
     /**