@fusion.dev/helix-headless 0.12.3 → 0.13.1

package/types/jsx.d.ts

@@ -55,6 +55,7 @@ import type {
   HelixHeadlessDrilldownItem,
   HelixHeadlessEmpty,
   HelixHeadlessFileInput,
+  HelixHeadlessFilterInput,
   HelixHeadlessFormatDate,
   HelixHeadlessHeatmap,
   HelixHeadlessIcon,
@@ -2985,6 +2986,9 @@ export type HelixHeadlessComboboxHelixBeforeOpenElementEvent =
 /** `helix-create` event type */
 export type HelixHeadlessComboboxHelixCreateElementEvent =
   HelixHeadlessComboboxElementEvent<HelixCreateEvent>;
+/** `helix-filter` event type */
+export type HelixHeadlessComboboxHelixFilterElementEvent =
+  HelixHeadlessComboboxElementEvent<HelixFilterEvent>;
 
 export type HelixHeadlessComboboxProps = {
   /** What the browser may autofill in the text field, as a platform token.
@@ -3134,6 +3138,8 @@ differently: they are one chooser to a consumer. */
   ) => void) | undefined;
   /** Fired when the reader asks for something the list does not hold, and cancelable. */
   "onhelix-create"?: ((e: HelixHeadlessComboboxHelixCreateElementEvent) => void) | undefined;
+  /** Fired as the reader types, carrying the text the list is being narrowed to. Cancelable: refusing it leaves the list whole, and is how a consumer takes the filtering for themselves. */
+  "onhelix-filter"?: ((e: HelixHeadlessComboboxHelixFilterElementEvent) => void) | undefined;
   /** Announced once the value has moved. */
   oninput?: ((e: HelixHeadlessComboboxElementEvent) => void) | undefined;
   /** Says the state moved, carrying `newState` and `oldState`. */
@@ -3287,6 +3293,8 @@ differently: they are one chooser to a consumer. */
   ) => void) | undefined;
   /** Fired when the reader asks for something the list does not hold, and cancelable. */
   "on:helix-create"?: ((e: HelixHeadlessComboboxHelixCreateElementEvent) => void) | undefined;
+  /** Fired as the reader types, carrying the text the list is being narrowed to. Cancelable: refusing it leaves the list whole, and is how a consumer takes the filtering for themselves. */
+  "on:helix-filter"?: ((e: HelixHeadlessComboboxHelixFilterElementEvent) => void) | undefined;
   /** Announced once the value has moved. */
   "on:input"?: ((e: HelixHeadlessComboboxElementEvent) => void) | undefined;
   /** Says the state moved, carrying `newState` and `oldState`. */
@@ -5764,6 +5772,171 @@ Here rather than on each control. */
   textContent?: (string | number) | undefined;
 };
 
+/** `HelixHeadlessFilterInput` component event */
+export type HelixHeadlessFilterInputElementEvent<E = Event> = TypedEvent<
+  HelixHeadlessFilterInput,
+  E
+>;
+/** `helix-before-change` event type */
+export type HelixHeadlessFilterInputHelixBeforeChangeElementEvent =
+  HelixHeadlessFilterInputElementEvent<HelixBeforeChangeEvent>;
+
+export type HelixHeadlessFilterInputProps = {
+  /** Whether the field offers a button that empties it.
+
+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
+`hideOverflow` marks the ones over the cap `hidden` rather than removing
+them. */
+  clearable?: (HelixHeadlessFilterInput["clearable"]) | undefined;
+  /** What the clear button is called, since an icon has no name of its own. */
+  "clear-label"?: (HelixHeadlessFilterInput["clearLabel"]) | undefined;
+  /** What the clear button is called, since an icon has no name of its own. */
+  clearLabel?: (HelixHeadlessFilterInput["clearLabel"]) | undefined;
+  /** Shown while the field is empty.
+
+Not a label: it goes when typing starts. */
+  placeholder?: (HelixHeadlessFilterInput["placeholder"]) | undefined;
+  /** How many tokens to show before the rest become a count. */
+  "max-tags"?: (HelixHeadlessFilterInput["maxTags"]) | undefined;
+  /** How many tokens to show before the rest become a count. */
+  maxTags?: (HelixHeadlessFilterInput["maxTags"]) | undefined;
+  /** The value the markup declared, which is where a reset returns to. */
+  "default-value"?: (HelixHeadlessFilterInput["defaultValue"]) | undefined;
+  /** The value the markup declared, which is where a reset returns to. */
+  defaultValue?: (HelixHeadlessFilterInput["defaultValue"]) | undefined;
+  /** What the control holds now, and what its form submits.
+
+One property, not two, so `input.value` answers the question anyone
+asking it meant. Writing always applies; `<helix-input value="x">` is the
+same statement in markup, and `default-value` is how markup seeds a value
+a reset should return to. */
+  value?: (HelixHeadlessFilterInput["value"]) | undefined;
+  /** What is wrong, in the reader's words rather than the browser's. */
+  feedback?: (HelixHeadlessFilterInput["feedback"]) | undefined;
+  /** Help under the control, shown while there is nothing wrong. */
+  hint?: (HelixHeadlessFilterInput["hint"]) | undefined;
+  /** The accessible name, and the fallback for the `label` slot. */
+  label?: (HelixHeadlessFilterInput["label"]) | undefined;
+  /** Whether the form refuses to submit without it. */
+  required?: (HelixHeadlessFilterInput["required"]) | undefined;
+  /** Whether the control is non-interactive.
+
+Reflected, because the styled tier selects on it, and mirrored to
+`aria-disabled` rather than removing the element from the accessibility
+tree, so a screen reader can still announce that the control exists.
+
+The mirror itself is in `willUpdate` below, here rather than in each
+control, because here is where `disabled` is. */
+  disabled?: (HelixHeadlessFilterInput["disabled"]) | undefined;
+  /** Name submitted with the form.
+
+**Reflected, and it is the exception to "reflect only what CSS selects
+on".** The platform builds a form's entry list from the `name` *content
+attribute*, not from the property, so a control named through the property
+submitted under no name at all and was silently dropped. Measured: two
+inputs in one form, one named by attribute and one by property, and the
+form carried a single entry.
+
+Safe for a React consumer, which is what the rule is protecting: React
+renders a custom element's props as attributes on the server, so the name
+is already in the markup being hydrated and reflecting it writes what is
+there. It is only a change to the markup when a consumer assigns it
+imperatively later, and nothing is hydrating by then.
+
+Here rather than on each control. */
+  name?: (HelixHeadlessFilterInput["name"]) | undefined;
+
+  /** Relayed from the input once the reader has finished. */
+  onchange?: ((e: HelixHeadlessFilterInputElementEvent) => void) | undefined;
+  /** Fired as the text changes, and cancelable. */
+  "onhelix-before-change"?: ((
+    e: HelixHeadlessFilterInputHelixBeforeChangeElementEvent,
+  ) => void) | undefined;
+  /** Announced once the text has moved. */
+  oninput?: ((e: HelixHeadlessFilterInputElementEvent) => void) | undefined;
+};
+
+export type HelixHeadlessFilterInputSolidJsProps = {
+  /** Whether the field offers a button that empties it.
+
+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
+`hideOverflow` marks the ones over the cap `hidden` rather than removing
+them. */
+  "prop:clearable"?: (HelixHeadlessFilterInput["clearable"]) | undefined;
+  /** What the clear button is called, since an icon has no name of its own. */
+  "attr:clear-label"?: (HelixHeadlessFilterInput["clearLabel"]) | undefined;
+  /** What the clear button is called, since an icon has no name of its own. */
+  "prop:clearLabel"?: (HelixHeadlessFilterInput["clearLabel"]) | undefined;
+  /** Shown while the field is empty.
+
+Not a label: it goes when typing starts. */
+  "prop:placeholder"?: (HelixHeadlessFilterInput["placeholder"]) | undefined;
+  /** How many tokens to show before the rest become a count. */
+  "attr:max-tags"?: (HelixHeadlessFilterInput["maxTags"]) | undefined;
+  /** How many tokens to show before the rest become a count. */
+  "prop:maxTags"?: (HelixHeadlessFilterInput["maxTags"]) | undefined;
+  /** The value the markup declared, which is where a reset returns to. */
+  "attr:default-value"?: (HelixHeadlessFilterInput["defaultValue"]) | undefined;
+  /** The value the markup declared, which is where a reset returns to. */
+  "prop:defaultValue"?: (HelixHeadlessFilterInput["defaultValue"]) | undefined;
+  /** What the control holds now, and what its form submits.
+
+One property, not two, so `input.value` answers the question anyone
+asking it meant. Writing always applies; `<helix-input value="x">` is the
+same statement in markup, and `default-value` is how markup seeds a value
+a reset should return to. */
+  "prop:value"?: (HelixHeadlessFilterInput["value"]) | undefined;
+  /** What is wrong, in the reader's words rather than the browser's. */
+  "prop:feedback"?: (HelixHeadlessFilterInput["feedback"]) | undefined;
+  /** Help under the control, shown while there is nothing wrong. */
+  "prop:hint"?: (HelixHeadlessFilterInput["hint"]) | undefined;
+  /** The accessible name, and the fallback for the `label` slot. */
+  "prop:label"?: (HelixHeadlessFilterInput["label"]) | undefined;
+  /** Whether the form refuses to submit without it. */
+  "prop:required"?: (HelixHeadlessFilterInput["required"]) | undefined;
+  /** Whether the control is non-interactive.
+
+Reflected, because the styled tier selects on it, and mirrored to
+`aria-disabled` rather than removing the element from the accessibility
+tree, so a screen reader can still announce that the control exists.
+
+The mirror itself is in `willUpdate` below, here rather than in each
+control, because here is where `disabled` is. */
+  "prop:disabled"?: (HelixHeadlessFilterInput["disabled"]) | undefined;
+  /** Name submitted with the form.
+
+**Reflected, and it is the exception to "reflect only what CSS selects
+on".** The platform builds a form's entry list from the `name` *content
+attribute*, not from the property, so a control named through the property
+submitted under no name at all and was silently dropped. Measured: two
+inputs in one form, one named by attribute and one by property, and the
+form carried a single entry.
+
+Safe for a React consumer, which is what the rule is protecting: React
+renders a custom element's props as attributes on the server, so the name
+is already in the markup being hydrated and reflecting it writes what is
+there. It is only a change to the markup when a consumer assigns it
+imperatively later, and nothing is hydrating by then.
+
+Here rather than on each control. */
+  "prop:name"?: (HelixHeadlessFilterInput["name"]) | undefined;
+  /** Relayed from the input once the reader has finished. */
+  "on:change"?: ((e: HelixHeadlessFilterInputElementEvent) => void) | undefined;
+  /** Fired as the text changes, and cancelable. */
+  "on:helix-before-change"?: ((
+    e: HelixHeadlessFilterInputHelixBeforeChangeElementEvent,
+  ) => void) | undefined;
+  /** Announced once the text has moved. */
+  "on:input"?: ((e: HelixHeadlessFilterInputElementEvent) => void) | undefined;
+
+  /** Set the innerHTML of the element */
+  innerHTML?: (string) | undefined;
+  /** Set the textContent of the element */
+  textContent?: (string | number) | undefined;
+};
+
 export type HelixHeadlessFormatDateProps = {
   /** The timestamp, as anything `Date` parses.
 
@@ -18274,6 +18447,7 @@ export type CustomElements = {
    * - `helix-before-close`: Fired before it closes. Cancelable: refusing it takes the decision and nothing moves.
    * - `helix-before-open`: Fired before the panel opens. Cancelable: refusing it takes the decision and nothing moves.
    * - `helix-create`: Fired when the reader asks for something the list does not hold, and cancelable.
+   * - `helix-filter`: Fired as the reader types, carrying the text the list is being narrowed to. Cancelable: refusing it leaves the list whole, and is how a consumer takes the filtering for themselves.
    * - `input`: Announced once the value has moved.
    * - `toggle`: Says the state moved, carrying `newState` and `oldState`.
    *
@@ -20332,6 +20506,186 @@ export type CustomElements = {
     HelixHeadlessFileInputProps & BaseProps<HelixHeadlessFileInput> & BaseEvents<HelixHeadlessFileInput>
   >;
 
+  /**
+   * **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.
+   *
+   * **`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.
+   *
+   * 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.
+   *
+   * ## Attributes & Properties
+   *
+   * Component attributes and properties that can be applied to the element or by using JavaScript.
+   *
+   * - `clearable`: Whether the field offers a button that empties it.
+   *
+   * 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
+   * `hideOverflow` marks the ones over the cap `hidden` rather than removing
+   * them.
+   * - `clear-label`/`clearLabel`: What the clear button is called, since an icon has no name of its own.
+   * - `placeholder`: Shown while the field is empty.
+   *
+   * Not a label: it goes when typing starts.
+   * - `max-tags`/`maxTags`: How many tokens to show before the rest become a count.
+   * - `default-value`/`defaultValue`: The value the markup declared, which is where a reset returns to.
+   * - `value`: What the control holds now, and what its form submits.
+   *
+   * One property, not two, so `input.value` answers the question anyone
+   * asking it meant. Writing always applies; `<helix-input value="x">` is the
+   * same statement in markup, and `default-value` is how markup seeds a value
+   * a reset should return to.
+   * - `feedback`: What is wrong, in the reader's words rather than the browser's.
+   * - `hint`: Help under the control, shown while there is nothing wrong.
+   * - `label`: The accessible name, and the fallback for the `label` slot.
+   * - `required`: Whether the form refuses to submit without it.
+   * - `disabled`: Whether the control is non-interactive.
+   *
+   * Reflected, because the styled tier selects on it, and mirrored to
+   * `aria-disabled` rather than removing the element from the accessibility
+   * tree, so a screen reader can still announce that the control exists.
+   *
+   * The mirror itself is in `willUpdate` below, here rather than in each
+   * control, because here is where `disabled` is.
+   * - `name`: Name submitted with the form.
+   *
+   * **Reflected, and it is the exception to "reflect only what CSS selects
+   * on".** The platform builds a form's entry list from the `name` *content
+   * attribute*, not from the property, so a control named through the property
+   * submitted under no name at all and was silently dropped. Measured: two
+   * inputs in one form, one named by attribute and one by property, and the
+   * form carried a single entry.
+   *
+   * Safe for a React consumer, which is what the rule is protecting: React
+   * renders a custom element's props as attributes on the server, so the name
+   * is already in the markup being hydrated and reflecting it writes what is
+   * there. It is only a change to the markup when a consumer assigns it
+   * imperatively later, and nothing is hydrating by then.
+   *
+   * Here rather than on each control.
+   * - `form`: The form this control belongs to, if any. (property only) (readonly)
+   * - `labels`: Labels associated with this control. (property only) (readonly)
+   * - `whenSettled`: Resolves a frame after the first update, when transitions are switched on.
+   *
+   * **Named `whenSettled` because `settled` is taken four times over**, by
+   * Image, Splitter and both color controls, none of them about transitions. A
+   * base class takes the name every subclass then cannot use.
+   *
+   * **The state it reports cannot be watched, which is why this exists.** A
+   * custom state is deliberately not in the DOM, so there is no
+   * `MutationObserver` equivalent for `ElementInternals.states`. Await this
+   * instead.
+   *
+   * Separate from `updateComplete`, which resolves in the microtask checkpoint
+   * the suppression is still active in. That is the distinction `readyToMove`
+   * in `@fusion.dev/helix-testing` is written around.
+   *
+   * It never resolves where `requestAnimationFrame` never fires, which is a
+   * server, a hidden tab, and happy-dom. Callers that must not hang race it
+   * against a timeout; `readyToMove` does exactly that. (property only) (readonly)
+   *
+   * ## Events
+   *
+   * Events that will be emitted by the component.
+   *
+   * - `change`: Relayed from the input once the reader has finished.
+   * - `helix-before-change`: Fired as the text changes, and cancelable.
+   * - `input`: Announced once the text has moved.
+   *
+   * ## Slots
+   *
+   * Areas where markup can be added to the component.
+   *
+   * - `end`: After the text, for a count or a control.
+   * - `start`: Before the text, for a search icon.
+   * - `tags`: What is already narrowing the results, as `Tag`s.
+   *
+   * ## Methods
+   *
+   * Methods that can be called to access component functionality.
+   *
+   * - `focus(options?: FocusOptions) => void`: Puts the caret in the field, the way a label pointing at one would.
+   * - `requestValue(next: string) => boolean`: Requests a new value, and reports whether the request stood.
+   *
+   * Announces before it acts, so `preventDefault()` on the `helix-before-change` is
+   * a refusal and nothing moves. Nobody refusing means the control updates
+   * itself, whether or not a consumer declared `value`: a declared property
+   * is a seed and a correction, the way `<input value>` is, and a consumer
+   * who wants the change for themselves refuses it and assigns their own.
+   * - `formResetCallback() => void`: Returns the control to the value its markup declared.
+   *
+   * Both halves are dropped, the consumer's and the control's, because a
+   * reset means the form is as it was served. Clearing only the internal one
+   * would leave a control that had been written to stuck at that value.
+   * - `formStateRestoreCallback(state: string | null) => void`: Restores the value when the browser brings a form back.
+   *
+   * Falling back to `defaultValue` rather than to empty, because a restore
+   * with no state is a form the browser has nothing recorded for, which is
+   * the same situation as a fresh one.
+   * - `formDisabledCallback(disabled: boolean) => void`: The platform's notice that an ancestor fieldset changed.
+   *
+   * **The argument is the effective state, and taking it whole is what latched
+   * every control in the library.** The platform calls this for the element's
+   * own `disabled` as well as for a fieldset, and our own arrives here at the
+   * worst possible moment: reflecting `disabled` to the attribute happens
+   * inside Lit's `update()`, the UA fires this synchronously from that write,
+   * and a reactive write during an update is a change-in-update Lit does not
+   * re-render for. So `formDisabled` ran exactly one update behind forever.
+   *
+   * Measured on Slider, logging what `render` saw:
+   *
+   * ```
+   * set true    disabled true   formDisabled false  isDisabled true
+   * set false   disabled false  formDisabled true   isDisabled true   <- stale
+   * (no third render)
+   * ```
+   *
+   * The host came out right every time, `disabled` false, `:disabled` not
+   * matching, and the inner control kept the attribute, so a control disabled
+   * once could never be re-enabled. It only shows when something re-enables,
+   * which is the same shape of bug `inheritDisabled` was written for.
+   *
+   * Our own half is already in `this.disabled` and `isDisabled` is an or, so
+   * this records only what the fieldset adds. That also removes the write
+   * entirely on the own-disabled path rather than moving it.
+   *
+   * The one case this cannot see is a control that is disabled itself *and*
+   * inside a disabled fieldset, whose own `disabled` is then removed: the
+   * effective state does not change, so the platform does not call again, and
+   * the fieldset's hold is not recorded. There is no callback to learn it from
+   * and reading `:disabled` here would answer about the attribute we are in the
+   * middle of removing.
+   *
+   * ## CSS Parts
+   *
+   * Custom selectors for styling elements within the component.
+   *
+   * - `clear`: The button that empties the field.
+   * - `control`: The input itself.
+   * - `feedback`: What is wrong with it.
+   * - `field`: The box holding everything.
+   * - `hint`: Help under the field, while nothing is wrong.
+   * - `label`: The question, over the field.
+   * - `rest`: How many tokens did not fit.
+   * - `tags`: The row the tokens sit in.
+   */
+  "helix-headless-filter-input": Partial<
+    HelixHeadlessFilterInputProps &
+      BaseProps<HelixHeadlessFilterInput> &
+      BaseEvents<HelixHeadlessFilterInput>
+  >;
+
   /**
    * 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
@@ -32493,6 +32847,7 @@ export type CustomElementsSolidJs = {
    * - `helix-before-close`: Fired before it closes. Cancelable: refusing it takes the decision and nothing moves.
    * - `helix-before-open`: Fired before the panel opens. Cancelable: refusing it takes the decision and nothing moves.
    * - `helix-create`: Fired when the reader asks for something the list does not hold, and cancelable.
+   * - `helix-filter`: Fired as the reader types, carrying the text the list is being narrowed to. Cancelable: refusing it leaves the list whole, and is how a consumer takes the filtering for themselves.
    * - `input`: Announced once the value has moved.
    * - `toggle`: Says the state moved, carrying `newState` and `oldState`.
    *
@@ -34585,6 +34940,187 @@ export type CustomElementsSolidJs = {
       BaseEvents<HelixHeadlessFileInput>
   >;
 
+  /**
+   * **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.
+   *
+   * **`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.
+   *
+   * 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.
+   *
+   * ## Attributes & Properties
+   *
+   * Component attributes and properties that can be applied to the element or by using JavaScript.
+   *
+   * - `clearable`: Whether the field offers a button that empties it.
+   *
+   * 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
+   * `hideOverflow` marks the ones over the cap `hidden` rather than removing
+   * them.
+   * - `clear-label`/`clearLabel`: What the clear button is called, since an icon has no name of its own.
+   * - `placeholder`: Shown while the field is empty.
+   *
+   * Not a label: it goes when typing starts.
+   * - `max-tags`/`maxTags`: How many tokens to show before the rest become a count.
+   * - `default-value`/`defaultValue`: The value the markup declared, which is where a reset returns to.
+   * - `value`: What the control holds now, and what its form submits.
+   *
+   * One property, not two, so `input.value` answers the question anyone
+   * asking it meant. Writing always applies; `<helix-input value="x">` is the
+   * same statement in markup, and `default-value` is how markup seeds a value
+   * a reset should return to.
+   * - `feedback`: What is wrong, in the reader's words rather than the browser's.
+   * - `hint`: Help under the control, shown while there is nothing wrong.
+   * - `label`: The accessible name, and the fallback for the `label` slot.
+   * - `required`: Whether the form refuses to submit without it.
+   * - `disabled`: Whether the control is non-interactive.
+   *
+   * Reflected, because the styled tier selects on it, and mirrored to
+   * `aria-disabled` rather than removing the element from the accessibility
+   * tree, so a screen reader can still announce that the control exists.
+   *
+   * The mirror itself is in `willUpdate` below, here rather than in each
+   * control, because here is where `disabled` is.
+   * - `name`: Name submitted with the form.
+   *
+   * **Reflected, and it is the exception to "reflect only what CSS selects
+   * on".** The platform builds a form's entry list from the `name` *content
+   * attribute*, not from the property, so a control named through the property
+   * submitted under no name at all and was silently dropped. Measured: two
+   * inputs in one form, one named by attribute and one by property, and the
+   * form carried a single entry.
+   *
+   * Safe for a React consumer, which is what the rule is protecting: React
+   * renders a custom element's props as attributes on the server, so the name
+   * is already in the markup being hydrated and reflecting it writes what is
+   * there. It is only a change to the markup when a consumer assigns it
+   * imperatively later, and nothing is hydrating by then.
+   *
+   * Here rather than on each control.
+   * - `form`: The form this control belongs to, if any. (property only) (readonly)
+   * - `labels`: Labels associated with this control. (property only) (readonly)
+   * - `whenSettled`: Resolves a frame after the first update, when transitions are switched on.
+   *
+   * **Named `whenSettled` because `settled` is taken four times over**, by
+   * Image, Splitter and both color controls, none of them about transitions. A
+   * base class takes the name every subclass then cannot use.
+   *
+   * **The state it reports cannot be watched, which is why this exists.** A
+   * custom state is deliberately not in the DOM, so there is no
+   * `MutationObserver` equivalent for `ElementInternals.states`. Await this
+   * instead.
+   *
+   * Separate from `updateComplete`, which resolves in the microtask checkpoint
+   * the suppression is still active in. That is the distinction `readyToMove`
+   * in `@fusion.dev/helix-testing` is written around.
+   *
+   * It never resolves where `requestAnimationFrame` never fires, which is a
+   * server, a hidden tab, and happy-dom. Callers that must not hang race it
+   * against a timeout; `readyToMove` does exactly that. (property only) (readonly)
+   *
+   * ## Events
+   *
+   * Events that will be emitted by the component.
+   *
+   * - `change`: Relayed from the input once the reader has finished.
+   * - `helix-before-change`: Fired as the text changes, and cancelable.
+   * - `input`: Announced once the text has moved.
+   *
+   * ## Slots
+   *
+   * Areas where markup can be added to the component.
+   *
+   * - `end`: After the text, for a count or a control.
+   * - `start`: Before the text, for a search icon.
+   * - `tags`: What is already narrowing the results, as `Tag`s.
+   *
+   * ## Methods
+   *
+   * Methods that can be called to access component functionality.
+   *
+   * - `focus(options?: FocusOptions) => void`: Puts the caret in the field, the way a label pointing at one would.
+   * - `requestValue(next: string) => boolean`: Requests a new value, and reports whether the request stood.
+   *
+   * Announces before it acts, so `preventDefault()` on the `helix-before-change` is
+   * a refusal and nothing moves. Nobody refusing means the control updates
+   * itself, whether or not a consumer declared `value`: a declared property
+   * is a seed and a correction, the way `<input value>` is, and a consumer
+   * who wants the change for themselves refuses it and assigns their own.
+   * - `formResetCallback() => void`: Returns the control to the value its markup declared.
+   *
+   * Both halves are dropped, the consumer's and the control's, because a
+   * reset means the form is as it was served. Clearing only the internal one
+   * would leave a control that had been written to stuck at that value.
+   * - `formStateRestoreCallback(state: string | null) => void`: Restores the value when the browser brings a form back.
+   *
+   * Falling back to `defaultValue` rather than to empty, because a restore
+   * with no state is a form the browser has nothing recorded for, which is
+   * the same situation as a fresh one.
+   * - `formDisabledCallback(disabled: boolean) => void`: The platform's notice that an ancestor fieldset changed.
+   *
+   * **The argument is the effective state, and taking it whole is what latched
+   * every control in the library.** The platform calls this for the element's
+   * own `disabled` as well as for a fieldset, and our own arrives here at the
+   * worst possible moment: reflecting `disabled` to the attribute happens
+   * inside Lit's `update()`, the UA fires this synchronously from that write,
+   * and a reactive write during an update is a change-in-update Lit does not
+   * re-render for. So `formDisabled` ran exactly one update behind forever.
+   *
+   * Measured on Slider, logging what `render` saw:
+   *
+   * ```
+   * set true    disabled true   formDisabled false  isDisabled true
+   * set false   disabled false  formDisabled true   isDisabled true   <- stale
+   * (no third render)
+   * ```
+   *
+   * The host came out right every time, `disabled` false, `:disabled` not
+   * matching, and the inner control kept the attribute, so a control disabled
+   * once could never be re-enabled. It only shows when something re-enables,
+   * which is the same shape of bug `inheritDisabled` was written for.
+   *
+   * Our own half is already in `this.disabled` and `isDisabled` is an or, so
+   * this records only what the fieldset adds. That also removes the write
+   * entirely on the own-disabled path rather than moving it.
+   *
+   * The one case this cannot see is a control that is disabled itself *and*
+   * inside a disabled fieldset, whose own `disabled` is then removed: the
+   * effective state does not change, so the platform does not call again, and
+   * the fieldset's hold is not recorded. There is no callback to learn it from
+   * and reading `:disabled` here would answer about the attribute we are in the
+   * middle of removing.
+   *
+   * ## CSS Parts
+   *
+   * Custom selectors for styling elements within the component.
+   *
+   * - `clear`: The button that empties the field.
+   * - `control`: The input itself.
+   * - `feedback`: What is wrong with it.
+   * - `field`: The box holding everything.
+   * - `hint`: Help under the field, while nothing is wrong.
+   * - `label`: The question, over the field.
+   * - `rest`: How many tokens did not fit.
+   * - `tags`: The row the tokens sit in.
+   */
+  "helix-headless-filter-input": Partial<
+    HelixHeadlessFilterInputProps &
+      HelixHeadlessFilterInputSolidJsProps &
+      BaseProps<HelixHeadlessFilterInput> &
+      BaseEvents<HelixHeadlessFilterInput>
+  >;
+
   /**
    * 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

package/types/svelte.d.ts

@@ -46,6 +46,7 @@ declare module 'svelte/elements' {
     'helix-headless-drilldown': CustomElements['helix-headless-drilldown']
     'helix-headless-empty': CustomElements['helix-headless-empty']
     'helix-headless-file-input': CustomElements['helix-headless-file-input']
+    'helix-headless-filter-input': CustomElements['helix-headless-filter-input']
     'helix-headless-format-date': CustomElements['helix-headless-format-date']
     'helix-headless-heatmap': CustomElements['helix-headless-heatmap']
     'helix-headless-icon-button': CustomElements['helix-headless-icon-button']