@fusion.dev/helix-headless 0.177.2 → 0.179.0

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

@@ -256,6 +256,18 @@ export declare class HelixHeadlessButton extends HelixFormElement {
      */
     protected announcePress(click: Event): void;
     private readonly handleClick;
+    /**
+     * Presses the button, as `click()` presses a native one: the command is sent,
+     * the form submits or resets, and `helix-press` says `virtual`.
+     *
+     * **Passed to the inner control, because a click on the host reaches nothing
+     * that acts.** The control in the shadow root is what answers a click, so
+     * `click()` from a script, an automation or a test, dispatched on the host,
+     * submitted nothing and sent no `helix-press`. The control's own click reaches
+     * the host's listeners once, retargeted, as one from a native button does. A
+     * disabled button does nothing, and a pending one refuses the press.
+     */
+    click(): void;
     /** What a press does: sends the command, and submits or resets the form. */
     private act;
     /**

package/dist/button/root/button-root.js

@@ -89,6 +89,15 @@ let HelixHeadlessButton = class HelixHeadlessButton extends HelixFormElement {
         this.recent = {};
         this.dispatchEvent(new HelixPressEvent({ pointerType }));
     }
+    click() {
+        const control = this.partNamed('button');
+        if (control) {
+            control.click();
+        }
+        else {
+            super.click();
+        }
+    }
     act() {
         this.linkCommand();
         this.sendCommand();

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

@@ -207,6 +207,12 @@ export declare class HelixHeadlessDrilldownItem extends HelixElement {
      * an icon of your own replaces it by being slotted.
      */
     protected renderMark(): TemplateResult;
+    /**
+     * Presses the row, as `click()` presses a native button: passed to the
+     * control inside, which is what answers a click, so a script's `click()`
+     * chooses the row, or follows its link, once.
+     */
+    click(): void;
     protected render(): TemplateResult | typeof nothing;
 }
 declare global {

package/dist/drilldown/item/drilldown-item.js

@@ -104,6 +104,15 @@ let HelixHeadlessDrilldownItem = class HelixHeadlessDrilldownItem extends HelixE
       </svg></slot
     >`;
     }
+    click() {
+        const control = this.partNamed('item');
+        if (control) {
+            control.click();
+        }
+        else {
+            super.click();
+        }
+    }
     render() {
         if (this.showingPage || this.onPath) {
             return html `<slot name="page" @slotchange=${this.readPage}></slot>`;

package/dist/element-events.generated.js

@@ -137,7 +137,13 @@ registerElementEvents({
         'helix-graph-signal',
         'helix-graph-zoom',
     ],
-    'helix-headless-heatmap': ['change', 'helix-before-change', 'helix-resize'],
+    'helix-headless-heatmap': [
+        'change',
+        'helix-before-change',
+        'helix-reading-change',
+        'helix-reading-press',
+        'helix-resize',
+    ],
     'helix-headless-icon': ['error', 'load'],
     'helix-headless-icon-button': ['helix-press'],
     'helix-headless-image': ['error', 'load'],

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

@@ -3,3 +3,4 @@ export * from './field/filter-field.js';
 export * from './grammar.js';
 export * from './operator/filter-operator.js';
 export * from './root/filter-input-root.js';
+export type { FilterSource, FilterSourceRequest, FilterSuggestion } from './suggest.js';

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

@@ -1,6 +1,7 @@
 import { AriaForwardController, HelixFormElement, PopoverController } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 import { HelixHeadlessFilterField } from '../field/filter-field.js';
+import { type FilterSource } from '../suggest.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 text field for filters, with the active filters shown in it as tokens.
@@ -67,9 +68,15 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  *
  * **The picker has an entry of its own.** `FilterMenu` draws its pages with
  * `Menu`, which a field without a picker does not need, so this family's entry
- * leaves it out. A page that writes one imports
- * `@fusion.dev/helix/filter-input/menu` as well, and a picker written without it
- * is reported once the page has loaded, with the entry to add.
+ * leaves it out. A page that writes a `FilterMenu` imports both entries:
+ *
+ * ```js
+ * import '@fusion.dev/helix/filter-input'
+ * import '@fusion.dev/helix/filter-input/menu'
+ * ```
+ *
+ * A picker written without the second is reported once the page has loaded,
+ * with the entry to add.
  *
  * **Suggestions.** Slot options into `suggestions` and the field shows them,
  * moves through them with the arrow keys, and presses one on Enter. The option
@@ -85,6 +92,24 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  * completion back and put the caret after it, or the next parse reads the wrong
  * term.
  *
+ * **Suggestions from a source.** Set `source` to a function, and the field asks
+ * it for suggestions as the text changes and draws them as options in the
+ * panel. It is given the term at the caret, the field the term is a value of,
+ * the whole text, and an `AbortSignal`, and returns the suggestions or a
+ * promise of them. `filter-delay` waits for typing to rest before asking, and
+ * a later keystroke aborts a request still out. While a promise is pending, the
+ * panel shows `loading-text` and a screen reader hears it, then the count.
+ * Choosing a suggestion writes its value over the term at the caret, and a
+ * finished `field:value` is read into a chip as Enter would. Cancel its
+ * `helix-select` to write it yourself.
+ *
+ * ```js
+ * filter.source = async ({ field, term, signal }) => {
+ *   const response = await fetch(`/values?field=${field}&q=${term}`, { signal })
+ *   return response.json()
+ * }
+ * ```
+ *
  * **State.** Three things have three different owners:
  *
  * - `value` is the text. The user types, the element applies it, and `input`
@@ -126,7 +151,7 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  * @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 {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 an option you slotted, and you decide what it does. A suggestion from `source` is written over the term at the caret unless you cancel it.
  * @event {Event} input - Fired when the text changes.
  * @event {ToggleEvent} toggle - Fired when the suggestions panel opens or closes, with `newState` and `oldState`.
  *
@@ -139,13 +164,13 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  * @csspart label - The label above the field.
  * @csspart lead - The box before the text that holds the `start` slot.
  * @csspart live - The live region that says how many suggestions the open panel offers. It is rendered from the first time the panel opens with suggestions.
- * @csspart loading - Shown in the panel while the suggestions load.
+ * @csspart loading - Shown in the panel while the suggestions load: while `loading` is set, or a request to `source` is out.
  * @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 - The field has an error to show, from the browser's validation or from your `feedback`.
- * @cssstate loading - While `loading` is set.
+ * @cssstate loading - While `loading` is set, or a request to `source` is out.
  * @cssstate no-results - `filter-suggestions` hid every suggestion, and `no-results-text` or the `no-results` slot says so.
  * @cssstate open - The suggestions are open.
  */
@@ -186,6 +211,12 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
      * an icon.
      */
     clearLabel: string;
+    /**
+     * How long typing rests before `source` is asked, in milliseconds. A delay
+     * sends one request for a word in place of one for each letter. The arrow
+     * keys and Enter ask at once. `0` asks on every keystroke.
+     */
+    filterDelay: number;
     /**
      * Whether the panel narrows itself to the suggestions that hold the term
      * being typed, as React Aria's Autocomplete filters. Off, the panel shows
@@ -219,6 +250,15 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
      * Not a label: it goes when typing starts.
      */
     placeholder: string;
+    /**
+     * Where the suggestions come from: a function given the term at the caret,
+     * the field it is a value of, the whole text, and an `AbortSignal`, which
+     * returns the suggestions or a promise of them. Each is a string, or a
+     * `value` with a `label` and `disabled`. The field draws them as options in
+     * the panel, beside any you slot. A property only, there being no way to
+     * write a function in markup. See the class description.
+     */
+    source?: FilterSource | undefined;
     /**
      * What a reader hears for one suggestion, where `suggestions-label` should
      * not say it. `{count}` is the count.
@@ -465,6 +505,52 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
      * would only be a copy of that one going stale.
      */
     private settleOpen;
+    /** Whether a request to `source` is out, which the panel shows as loading. */
+    private fetching;
+    /** Whether the suggestions are loading: `loading`, or a request to `source` out. */
+    private get busy();
+    /** The request to `source` still out, which a later one aborts. */
+    private request;
+    /** The text `source` was last asked about, so focus alone does not ask again. */
+    private asked;
+    /** The source the suggestions drawn now came from. */
+    private used;
+    /** The options this element drew from what `source` gave, which the next answer replaces. */
+    private sourced;
+    /** The request waiting out `filterDelay`, if any. */
+    private readonly asking;
+    /**
+     * A new source, or none: what the old one gave goes, and the new one is
+     * asked where the reader is in the field.
+     */
+    private resetSource;
+    /** Asks `source` once typing rests for `filterDelay`, or at once without one. */
+    private askSoon;
+    /**
+     * Asks `source` for suggestions for the term at the caret, and draws what
+     * it gives.
+     *
+     * **A later request aborts this one, and an answer that arrives late is
+     * dropped**, whether or not the source heeds the signal: the panel shows
+     * what the text says now.
+     */
+    private ask;
+    /**
+     * Draws what `source` gave as options in the `suggestions` slot, in place of
+     * the ones it gave before, and leaves the ones you slotted alone. The
+     * options are this tier's `Option`, which a page on the headless tier
+     * imports; one not registered is reported.
+     */
+    private drawSourced;
+    /**
+     * A suggestion `source` gave, chosen: its value written over the term at the
+     * caret, and a finished `field:value` read into a chip, as Enter reads it.
+     *
+     * **After every listener has had its turn**, as a chip under `chips` is
+     * drawn, so a `preventDefault()` on the `helix-select` is read and leaves the
+     * text to you.
+     */
+    private readonly handleSourcedSelect;
     /** Moves the highlight, wrapping, and opens the panel if it was closed. */
     private move;
     private readonly handleKeydown;

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

@@ -4,13 +4,13 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { AriaForwardController, countLabel, customElement, drawIcon, drawStatus, formatWords, HelixFacetEvent, HelixFormElement, holdCaret, MixinControllerOpen, MixinControllerValue, MixinField, MixinTokens, PopoverController, reportRuntime, restoreValue, StatusController, scrollItemIntoView, words, wordsLocale, } from '@fusion.dev/helix-core';
+import { AriaForwardController, countLabel, customElement, DelayController, drawIcon, drawStatus, formatWords, HelixFacetEvent, HelixFormElement, holdCaret, MixinControllerOpen, MixinControllerValue, MixinField, MixinTokens, PopoverController, reportRuntime, restoreValue, StatusController, scrollItemIntoView, words, wordsLocale, } from '@fusion.dev/helix-core';
 import { x } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { HelixHeadlessFilterField } from '../field/filter-field.js';
 import { readFilterText } from '../grammar.js';
-import { currentTerm, suggests, tokenEntry } from '../suggest.js';
+import { completeTerm, currentField, currentTerm, suggests, tokenEntry, } from '../suggest.js';
 const picks = (element) => typeof element.apply === 'function' &&
     Array.isArray(element.fields);
 const asksToGo = (node) => typeof node?.dismiss === 'function';
@@ -25,6 +25,7 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
         this.chips = false;
         this.clearable = false;
         this.clearLabel = 'Clear';
+        this.filterDelay = 0;
         this.filterSuggestions = false;
         this.loading = false;
         this.loadingText = 'Loading';
@@ -59,6 +60,7 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
             restoreValue(control, this.value);
             this.dismissed = false;
             this.settleOpen();
+            this.askSoon();
             if (event.inputType === 'insertFromPaste') {
                 this.readFilters();
             }
@@ -84,13 +86,27 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
                 return;
             }
             const field = chip.getAttribute('name') ?? '';
-            const menu = field === '' ? null : this.menuFor(field);
-            if (!menu) {
+            const declared = field === '' ? undefined : this.fields.find((one) => (one.name ?? '') === field);
+            if (!declared) {
                 return;
             }
             event.preventDefault();
             event.stopPropagation();
-            menu.apply(field, []);
+            const menu = this.menuFor(field);
+            if (menu) {
+                menu.apply(field, []);
+                return;
+            }
+            const { label, operators } = declared.vocabulary;
+            const usual = operators.find((operator) => operator.default) ?? operators[0];
+            this.announceFacet({
+                arity: usual?.arity ?? 'many',
+                field,
+                label,
+                operator: usual?.name ?? '',
+                operatorLabel: '',
+                values: [],
+            });
         };
         this.handleClear = () => {
             if (this.value !== '' && this.requestValue('')) {
@@ -102,6 +118,36 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
                 control.focus();
             }
         };
+        this.fetching = false;
+        this.sourced = [];
+        this.asking = new DelayController(this, { renders: false });
+        this.handleSourcedSelect = (event) => {
+            const option = event.composedPath()[0];
+            if (!this.sourced.includes(option)) {
+                return;
+            }
+            queueMicrotask(() => {
+                if (event.defaultPrevented || !this.sourced.includes(option)) {
+                    return;
+                }
+                const value = option.value;
+                const written = completeTerm(this.value, this.control?.selectionStart ?? this.value.length, value);
+                if (!this.requestValue(written.text)) {
+                    return;
+                }
+                const control = this.control;
+                if (control) {
+                    restoreValue(control, this.value);
+                    control.setSelectionRange(written.caret, written.caret);
+                }
+                this.activeAt = -1;
+                this.dismissed = false;
+                if (currentField(written.text, written.caret - 1) !== '') {
+                    this.readFilters();
+                }
+                this.ask();
+            });
+        };
         this.handleKeydown = (event) => {
             if (event.isComposing) {
                 return;
@@ -109,6 +155,9 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
             if (this.tokenKeydown(event, this.value)) {
                 return;
             }
+            if (['ArrowDown', 'ArrowUp', 'Enter'].includes(event.key)) {
+                this.asking.flush();
+            }
             if (event.key === 'Enter' && !(this.open && this.suggestions[this.activeAt])) {
                 if (this.readFilters() > 0) {
                     event.preventDefault();
@@ -172,6 +221,9 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
         };
         this.handleFocusIn = () => {
             this.settleOpen();
+            if (this.source && this.asked !== this.value) {
+                this.ask();
+            }
         };
         this.handleFocusOut = (event) => {
             const next = event.relatedTarget;
@@ -220,7 +272,7 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
         }
     }
     sayCount() {
-        const count = this.open && this.suggesting ? (this.loading ? -2 : this.suggestions.length) : -1;
+        const count = this.open && this.suggesting ? (this.busy ? -2 : this.suggestions.length) : -1;
         if (count === this.saidCount) {
             return;
         }
@@ -360,6 +412,109 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
         const focused = this.matches(':focus-within') || this.contains(document.activeElement);
         this.requestOpen(this.suggesting && !this.dismissed && !this.isDisabled && focused);
     }
+    get busy() {
+        return this.loading || this.fetching;
+    }
+    resetSource() {
+        if (this.source === this.used) {
+            return;
+        }
+        this.used = this.source;
+        this.request?.abort();
+        this.request = undefined;
+        this.fetching = false;
+        this.asked = undefined;
+        if (this.sourced.length > 0) {
+            this.drawSourced([]);
+        }
+        if (this.source && (this.matches(':focus-within') || this.contains(document.activeElement))) {
+            this.ask();
+        }
+    }
+    askSoon() {
+        if (!this.source) {
+            return;
+        }
+        this.asking.cancel();
+        if (this.filterDelay > 0) {
+            this.asking.start(this.filterDelay, () => this.ask());
+        }
+        else {
+            this.ask();
+        }
+    }
+    ask() {
+        this.asking.cancel();
+        const source = this.source;
+        if (!source) {
+            return;
+        }
+        this.used = source;
+        this.request?.abort();
+        const request = new AbortController();
+        this.request = request;
+        const text = this.value;
+        const caret = this.control?.selectionStart ?? text.length;
+        this.asked = text;
+        const take = (suggestions) => {
+            if (this.request !== request) {
+                return;
+            }
+            this.request = undefined;
+            this.fetching = false;
+            this.drawSourced(Array.isArray(suggestions) ? suggestions : []);
+        };
+        let answer;
+        try {
+            answer = source({
+                field: currentField(text, caret),
+                signal: request.signal,
+                term: currentTerm(text, caret),
+                text,
+            });
+        }
+        catch {
+            take([]);
+            return;
+        }
+        if (typeof answer?.then !== 'function') {
+            take(answer);
+            return;
+        }
+        this.fetching = true;
+        answer.then(take, () => take([]));
+    }
+    drawSourced(suggestions) {
+        for (const option of this.sourced) {
+            option.remove();
+        }
+        const tag = `${this.constructor.tier}option`;
+        if (suggestions.length > 0 && !customElements.get(tag)) {
+            const entry = tag.startsWith('helix-headless-')
+                ? '@fusion.dev/helix-headless'
+                : '@fusion.dev/helix';
+            reportRuntime({
+                kind: 'unregistered-part',
+                message: `<${tag}> is not registered, so the suggestions \`source\` gave cannot be chosen. Import '${entry}/option'.`,
+                tag: this.localName,
+            });
+        }
+        this.sourced = suggestions.map((suggestion) => {
+            const { disabled, label, value } = typeof suggestion === 'string'
+                ? { disabled: false, label: undefined, value: suggestion }
+                : suggestion;
+            const option = document.createElement(tag);
+            option.slot = 'suggestions';
+            option.setAttribute('value', value);
+            option.textContent = label ?? value;
+            if (disabled) {
+                option.setAttribute('disabled', '');
+            }
+            return option;
+        });
+        this.append(...this.sourced);
+        this.handleSuggestions();
+    }
     move(by) {
         const options = this.suggestions;
         if (options.length === 0) {
@@ -376,12 +531,12 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
     refreshSuggesting() {
         this.narrow();
         const options = this.suggestions;
-        this.suggesting = options.length > 0 || this.loading || this.unmatched;
+        this.suggesting = options.length > 0 || this.busy || this.unmatched;
         this.activeAt = this.activeAt < options.length ? this.activeAt : -1;
     }
     get unmatched() {
         const said = this.noResultsText !== '' || this.knownChildren.some((child) => child.slot === 'no-results');
-        return said && !this.loading && this.options.length > 0 && this.suggestions.length === 0;
+        return said && !this.busy && this.options.length > 0 && this.suggestions.length === 0;
     }
     tokenElements() {
         return (this.tokens?.assignedElements({ flatten: true }) ?? []);
@@ -399,11 +554,16 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
         super.connectedCallback();
         this.addEventListener('helix-dismiss', this.handleDismiss, { capture: true });
         this.addEventListener(HelixFacetEvent.eventName, this.handleFacet);
+        this.addEventListener('helix-select', this.handleSourcedSelect);
     }
     disconnectedCallback() {
         super.disconnectedCallback();
         this.removeEventListener('helix-dismiss', this.handleDismiss, { capture: true });
         this.removeEventListener(HelixFacetEvent.eventName, this.handleFacet);
+        this.removeEventListener('helix-select', this.handleSourcedSelect);
+        this.request?.abort();
+        this.request = undefined;
+        this.fetching = false;
     }
     willUpdate(changed) {
         super.willUpdate(changed);
@@ -420,7 +580,7 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
         }
         this.handleTokens();
         this.refreshSuggesting();
-        this.toggleState('loading', this.loading);
+        this.toggleState('loading', this.busy);
         this.toggleState('no-results', this.unmatched);
     }
     firstUpdated(changed) {
@@ -455,6 +615,9 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
     }
     updated(changed) {
         super.updated(changed);
+        if (changed.has('source')) {
+            queueMicrotask(() => this.resetSource());
+        }
         this.releaseCaret?.();
         this.releaseCaret = undefined;
         this.internals.setFormValue(this.formValue(), this.value);
@@ -543,7 +706,7 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
       <slot name="suggestions" @slotchange=${this.handleSuggestions}></slot>
       <!-- Hidden from the tree, which a listbox keeps for its options: the
            live region says these. -->
-      <div part="loading" aria-hidden="true" ?hidden=${!this.loading}>
+      <div part="loading" aria-hidden="true" ?hidden=${!this.busy}>
         <slot name="loading">${this.loadingText}</slot>
       </div>
       <div part="empty" aria-hidden="true" ?hidden=${!this.unmatched}>
@@ -564,6 +727,9 @@ __decorate([
     words,
     property({ attribute: 'clear-label' })
 ], HelixHeadlessFilterInput.prototype, "clearLabel", void 0);
+__decorate([
+    property({ attribute: 'filter-delay', type: Number })
+], HelixHeadlessFilterInput.prototype, "filterDelay", void 0);
 __decorate([
     property({ attribute: 'filter-suggestions', type: Boolean })
 ], HelixHeadlessFilterInput.prototype, "filterSuggestions", void 0);
@@ -580,6 +746,9 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessFilterInput.prototype, "placeholder", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessFilterInput.prototype, "source", void 0);
 __decorate([
     property({ attribute: 'suggestion-label' })
 ], HelixHeadlessFilterInput.prototype, "suggestionLabel", void 0);
@@ -599,6 +768,9 @@ __decorate([
 __decorate([
     state()
 ], HelixHeadlessFilterInput.prototype, "leading", void 0);
+__decorate([
+    state()
+], HelixHeadlessFilterInput.prototype, "fetching", void 0);
 HelixHeadlessFilterInput = __decorate([
     customElement('helix-headless-filter-input')
 ], HelixHeadlessFilterInput);

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

@@ -7,6 +7,53 @@
  * and after its colon where it has one, so `status:ope` narrows by `ope`.
  */
 export declare const currentTerm: (text: string, caret?: number) => string;
+/**
+ * The field the term at the caret is a value of: the word before its colon,
+ * without a leading `-`, so `-status:ope` is a value of `status`. Empty where
+ * the term has no colon, which is a key being typed.
+ */
+export declare const currentField: (text: string, caret?: number) => string;
+/**
+ * The text with a suggestion written over the term at the caret, and where
+ * the caret goes after it.
+ *
+ * The word's field and its colon stay, and a leading `-`, so a value chosen
+ * for `-status:op` gives `-status:open`. A space follows, ready for the next
+ * term, unless the suggestion ends with a colon, which is a key whose value
+ * comes next.
+ */
+export declare const completeTerm: (text: string, caret: number, value: string) => {
+    caret: number;
+    text: string;
+};
+/** One suggestion a `source` gives: its words, or its value with the words a reader sees. */
+export type FilterSuggestion = string | {
+    /** Shown, and skipped by the arrow keys. */
+    disabled?: boolean | undefined;
+    /** What a reader sees. The value where unset. */
+    label?: string | undefined;
+    /** What is written over the term when the suggestion is chosen. */
+    value: string;
+};
+/** What a `source` is asked for. */
+export interface FilterSourceRequest {
+    /**
+     * The field the term is a value of, where the caret is after `field:`, as
+     * `currentField` reads it. Empty while a key is being typed.
+     */
+    field: string;
+    /** Aborted once a later keystroke asks again, or the field leaves the page. */
+    signal: AbortSignal;
+    /** The term at the caret, after its colon, as `currentTerm` reads it. */
+    term: string;
+    /** The whole text. */
+    text: string;
+}
+/**
+ * Where the suggestions come from: given the term at the caret, the
+ * suggestions for it, or a promise of them.
+ */
+export type FilterSource = (request: FilterSourceRequest) => readonly FilterSuggestion[] | PromiseLike<readonly FilterSuggestion[]>;
 /** Whether a suggestion's words hold the term, ignoring case and accents. */
 export declare const suggests: (words: string, term: string) => boolean;
 /** What a token says about the filter it shows, as `tokenEntry` reads it. */

package/dist/filter-input/suggest.js

@@ -4,6 +4,23 @@ export const currentTerm = (text, caret = text.length) => {
     const colon = word.indexOf(':');
     return (colon === -1 ? word : word.slice(colon + 1)).replace(/^-/u, '');
 };
+export const currentField = (text, caret = text.length) => {
+    const before = text.slice(0, caret);
+    const word = before.slice(before.search(/\S*$/u));
+    const colon = word.indexOf(':');
+    return colon === -1 ? '' : word.slice(0, colon).replace(/^-/u, '');
+};
+export const completeTerm = (text, caret, value) => {
+    const before = text.slice(0, caret);
+    const start = before.search(/\S*$/u);
+    const word = before.slice(start);
+    const colon = word.indexOf(':');
+    const kept = colon === -1 ? (word.startsWith('-') ? '-' : '') : word.slice(0, colon + 1);
+    const after = text.slice(caret).replace(/^\S*/u, '');
+    const space = value.endsWith(':') ? '' : ' ';
+    const written = `${text.slice(0, start)}${kept}${value}${space}`;
+    return { caret: written.length, text: `${written}${space ? after.replace(/^\s+/u, '') : after}` };
+};
 export const suggests = (words, term) => {
     const plain = (text) => text.normalize('NFD').replace(/\p{M}/gu, '').toLowerCase();
     return term === '' || plain(words).includes(plain(term));