@fusion.dev/helix-headless 0.13.2 → 0.15.0

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

@@ -71,7 +71,7 @@ declare const HelixHeadlessCombobox_base: (new (...args: any[]) => import("@fusi
  * @csspart listbox-loading - Shown while the options are still on their way.
  * @csspart listbox-search - The region holding the field that narrows the list.
  * @csspart listbox-search-field - The field itself.
- * @csspart rest - The count of choices held beyond `max-tags`.
+ * @csspart rest - The count of choices held beyond `max-tags`. A `<button>` with `expandable`, a `<span>` without it.
  * @csspart surface - The floating panel.
  * @csspart tag - One chosen option.
  * @csspart tag-dismiss - The remove button, when `dismissible`.

package/dist/combobox/root/combobox-root.js

@@ -177,7 +177,8 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
     }
     get shown() {
         const held = this.chosen;
-        return this.maxTags > 0 ? held.slice(0, this.maxTags) : held;
+        const limit = this.shownLimit;
+        return limit > 0 ? held.slice(0, limit) : held;
     }
     get restCount() {
         return Math.max(0, this.chosen.length - this.shown.length);

package/dist/element-events.generated.js

@@ -53,7 +53,14 @@ registerElementEvents({
     'helix-headless-drilldown': ['helix-select'],
     'helix-headless-drilldown-item': ['helix-select'],
     'helix-headless-file-input': ['change', 'helix-before-change', 'input'],
-    'helix-headless-filter-input': ['change', 'helix-before-change', 'input'],
+    'helix-headless-filter-input': [
+        'change',
+        'helix-before-change',
+        'helix-before-close',
+        'helix-before-open',
+        'input',
+        'toggle',
+    ],
     'helix-headless-heatmap': ['helix-resize'],
     'helix-headless-image': ['error', 'load'],
     'helix-headless-input': ['change', 'helix-before-change', 'input'],

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

@@ -1,6 +1,6 @@
-import { AriaForwardController, HelixFormElement } from '@fusion.dev/helix-core';
+import { AriaForwardController, HelixFormElement, PopoverController } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
-declare const HelixHeadlessFilterInput_base: (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;
+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.
  *
@@ -22,6 +22,20 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  * `helix-dismiss` its own remove control fires, so a consumer who handled the
  * pointer has already handled the keyboard.
  *
+ * **It can suggest what to type next, and it never learns the grammar.** Slot
+ * `helix-option` elements 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. Deciding
+ * *what* to suggest is theirs too: keys before a colon and values after it are
+ * the same panel with different contents, which is all a two-level filter is,
+ * and the parse that tells them apart belongs where the domain does.
+ *
+ * **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.
+ *
  * @since 0.1.0
  * @status experimental
  * @category forms
@@ -30,11 +44,15 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  *
  * @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 `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 {Event} input - Announced once the text has moved.
+ * @event {Event} toggle - Says the panel moved, carrying `newState` and `oldState`.
  *
  * @csspart clear - The button that empties the field.
  * @csspart control - The input itself.
@@ -42,7 +60,8 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  * @csspart field - The box holding everything.
  * @csspart hint - Help under the field, while nothing is wrong.
  * @csspart label - The question, over the field.
- * @csspart rest - How many tokens did not fit.
+ * @csspart rest - How many tokens did not fit. A `<button>` with `expandable`, a `<span>` without it.
+ * @csspart surface - The floating panel the suggestions sit in.
  * @csspart tags - The row the tokens sit in.
  */
 export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_base {
@@ -70,6 +89,34 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
     placeholder: string;
     /** How many tokens did not fit, which is what the row's count renders. */
     private over;
+    /**
+     * Which suggestion the keyboard is on, or `-1` for none.
+     *
+     * An index rather than a value, unlike Listbox's: these are the consumer's
+     * own list and two of them may legitimately carry the same value, a `label`
+     * and an `assignee` both called `ada`. Position is what a reader is moving
+     * through and it is what stays right when they do.
+     */
+    private activeAt;
+    /**
+     * Whether anything is offering itself to be suggested.
+     *
+     * **The ARIA follows this rather than being declared once.** A text field
+     * carrying `role="combobox"` promises a popup; a filter field that no consumer
+     * ever gives options to has none, and saying otherwise sends a screen reader
+     * looking for a list that does not exist. So the role, `aria-expanded` and
+     * `aria-controls` all arrive with the first option and leave with the last.
+     */
+    private suggesting;
+    /**
+     * Whether Escape has closed the panel over text that still has suggestions.
+     *
+     * Without it the panel is open whenever there is something to show, so Escape
+     * would close it and the next render would put it straight back. Cleared by
+     * the next keystroke, because that is the reader saying something new.
+     */
+    private dismissed;
+    protected readonly panel: PopoverController;
     /**
      * The caret, held across a value the consumer wrote rather than the reader.
      *
@@ -83,6 +130,40 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
     private get tokens();
     /** Whether there is a clear button on screen right now. */
     private get showsClear();
+    /**
+     * The suggestions, in the order a reader moves through them.
+     *
+     * **Groups are opened out rather than walked into.** A slot assigns the group
+     * element, not the options inside it, so a panel that read only what was
+     * assigned would offer nothing at all the moment a consumer reached for
+     * `option-group` to say what a run of values belongs to.
+     *
+     * A disabled option keeps its place on screen and is skipped here, which is
+     * the difference between a list that explains why something cannot be chosen
+     * and one that pretends it was never there.
+     */
+    private get suggestions();
+    /**
+     * The caret and the selection, under the platform's own names.
+     *
+     * **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
+     * way to ask where the caret is: `querySelector` does not cross the boundary.
+     * A grammar that completes what is being typed cannot work without it, because
+     * "what is being typed" is the term the caret is in, and after writing a
+     * completion back the caret has to be put after it or the next parse reads the
+     * wrong term.
+     *
+     * Zero before there is a control, which is where an empty field's caret would
+     * be anyway.
+     */
+    get selectionDirection(): 'backward' | 'forward' | 'none';
+    /** Where the selection ends, which is the caret when nothing is selected. */
+    get selectionEnd(): number;
+    /** Where the selection starts, which is the caret when nothing is selected. */
+    get selectionStart(): number;
+    /** Moves the caret, or selects a run of the text. */
+    setSelectionRange(start: number, end: number, direction?: 'backward' | 'forward' | 'none'): void;
     /**
      * Every keystroke, cancelable, and put back where it is refused.
      *
@@ -100,7 +181,52 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
      * disappear, which would otherwise land on the body.
      */
     private readonly handleClear;
+    /**
+     * Opens the panel when there is something in it, and closes it when there is
+     * not.
+     *
+     * **Derived rather than commanded, which is the whole of how two levels
+     * work.** A reader who picks `disposition` wants its values next, and the
+     * consumer answers by rendering those values; if picking closed the panel it
+     * would shut and reopen between two renders, which a reader sees as a flicker
+     * and a screen reader hears as a list going away. Nothing here closes on a
+     * choice: the panel goes when the consumer stops offering, which is exactly
+     * when a value has been completed and there is nothing left to say.
+     *
+     * Through `requestOpen` for both directions, so `helix-before-open` and
+     * `helix-before-close` still gate it and a consumer who refuses is obeyed.
+     * **No guard of its own**, because that method already returns early when the
+     * answer has not moved: this runs after every render, and a second guard here
+     * would only be a copy of that one going stale.
+     */
+    private settleOpen;
+    /** Moves the highlight, wrapping, and opens the panel if it was closed. */
+    private move;
     private readonly handleKeydown;
+    /**
+     * What is on offer, settled before the render that draws it.
+     *
+     * **Not left to `slotchange`, for the reason the token row is not.** That
+     * event reports the assignment moving and nothing else, and it does not fire
+     * at all under the harness these are tested in, so a panel that learned only
+     * from it would be a panel that never opened. Reading the slot every update is
+     * what makes the answer true whenever anyone asks.
+     *
+     * State only. Opening is an announcement and belongs after the render, which
+     * is why `settleOpen` is not called from here.
+     */
+    private refreshSuggesting;
+    /** The panel again, whenever what is in it changes. */
+    private readonly handleSuggestions;
+    /** Focus arriving in the field is a reader asking what they can type. */
+    private readonly handleFocusIn;
+    /**
+     * Focus leaving the element closes it.
+     *
+     * `relatedTarget` and not a timer: a press inside the panel moves focus within
+     * this element and must not close what is being pressed.
+     */
+    private readonly handleFocusOut;
     /** The row again, whenever what is in it changes. */
     private readonly handleTokens;
     /**
@@ -117,6 +243,23 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
     protected willUpdate(changed: PropertyValues): void;
     protected firstUpdated(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
+    /**
+     * Marks the highlighted suggestion, and tells the control which one it is.
+     *
+     * **Two halves, and neither does the other's job.** `active` is the option's
+     * own published flag and is what a stylesheet draws from. The control carries
+     * `aria-activedescendant`, because focus never leaves the text: a screen
+     * reader is told what is highlighted by the field the caret is in, not by the
+     * list.
+     *
+     * Through `ariaActiveDescendantElement` rather than an id, which is what
+     * `Listbox` reaches for and for the same two reasons: it crosses a shadow
+     * boundary, where an `aria-activedescendant` naming an id cannot, and it needs
+     * no ids invented for the consumer's own elements. Feature-tested, because
+     * where it is missing the assignment is a silent no-op rather than an error,
+     * and the highlight is still drawn.
+     */
+    private markActive;
     /** Puts the caret in the field, the way a label pointing at one would. */
     focus(options?: FocusOptions): void;
     protected render(): TemplateResult;

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

@@ -4,12 +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, customElement, drawIcon, HelixFormElement, holdCaret, MixinControllerValue, MixinField, MixinTokens, restoreValue, } from '@fusion.dev/helix-core';
+import { AriaForwardController, customElement, drawIcon, HelixFormElement, holdCaret, MixinControllerOpen, MixinControllerValue, MixinField, MixinTokens, PopoverController, restoreValue, } from '@fusion.dev/helix-core';
 import { x } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 const asksToGo = (node) => typeof node?.dismiss === 'function';
-let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinTokens(MixinControllerValue(MixinField(HelixFormElement))) {
+const isOption = (node) => 'active' in node && 'value' in node;
+let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinControllerOpen(MixinTokens(MixinControllerValue(MixinField(HelixFormElement)))) {
     constructor() {
         super(...arguments);
         this.aria = new AriaForwardController(this, {
@@ -20,11 +21,27 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinToken
         this.clearLabel = 'Clear';
         this.placeholder = '';
         this.over = 0;
+        this.activeAt = -1;
+        this.suggesting = false;
+        this.dismissed = false;
+        this.panel = new PopoverController(this, {
+            anchor: () => this.renderRoot?.querySelector('[part="field"]'),
+            boundary: () => [
+                this.renderRoot?.querySelector('[part="surface"]'),
+                this.renderRoot?.querySelector('[part="field"]'),
+            ],
+            offset: () => 4,
+            onDismiss: () => this.requestOpen(false),
+            placement: 'bottom-start',
+            surface: () => this.renderRoot?.querySelector('[part="surface"]'),
+        });
         this.handleInput = (event) => {
             event.stopPropagation();
             const control = event.target;
             this.requestValue(control.value);
             restoreValue(control, this.value);
+            this.dismissed = false;
+            this.settleOpen();
         };
         this.handleChange = (event) => {
             event.stopPropagation();
@@ -39,7 +56,68 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinToken
             }
         };
         this.handleKeydown = (event) => {
-            this.tokenKeydown(event, this.value);
+            if (this.tokenKeydown(event, this.value)) {
+                return;
+            }
+            if (!this.suggesting) {
+                return;
+            }
+            switch (event.key) {
+                case 'ArrowDown':
+                    event.preventDefault();
+                    this.move(1);
+                    return;
+                case 'ArrowUp':
+                    event.preventDefault();
+                    this.move(-1);
+                    return;
+                case 'Home':
+                    if (this.open) {
+                        event.preventDefault();
+                        this.activeAt = 0;
+                    }
+                    return;
+                case 'End':
+                    if (this.open) {
+                        event.preventDefault();
+                        this.activeAt = this.suggestions.length - 1;
+                    }
+                    return;
+                case 'Escape':
+                    if (this.open) {
+                        event.preventDefault();
+                        event.stopPropagation();
+                        this.dismissed = true;
+                        this.activeAt = -1;
+                        this.requestOpen(false);
+                    }
+                    return;
+                case 'Enter': {
+                    const active = this.suggestions[this.activeAt];
+                    if (!this.open || !active) {
+                        return;
+                    }
+                    event.preventDefault();
+                    active.select();
+                    return;
+                }
+                default:
+            }
+        };
+        this.handleSuggestions = () => {
+            this.refreshSuggesting();
+            this.settleOpen();
+        };
+        this.handleFocusIn = () => {
+            this.settleOpen();
+        };
+        this.handleFocusOut = (event) => {
+            const next = event.relatedTarget;
+            if (next instanceof Node && this.contains(next)) {
+                return;
+            }
+            this.activeAt = -1;
+            this.requestOpen(false);
         };
         this.handleTokens = () => {
             this.over = this.hideOverflow(this.tokens);
@@ -58,6 +136,56 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinToken
     get showsClear() {
         return this.clearable && this.value !== '' && !this.isDisabled;
     }
+    get suggestions() {
+        const slot = this.renderRoot?.querySelector('slot[name="suggestions"]');
+        const found = [];
+        for (const node of slot?.assignedElements({ flatten: true }) ?? []) {
+            if (isOption(node)) {
+                found.push(node);
+                continue;
+            }
+            for (const child of node.children) {
+                if (isOption(child)) {
+                    found.push(child);
+                }
+            }
+        }
+        return found.filter((option) => !option.disabled);
+    }
+    get selectionDirection() {
+        return this.control?.selectionDirection ?? 'none';
+    }
+    get selectionEnd() {
+        return this.control?.selectionEnd ?? 0;
+    }
+    get selectionStart() {
+        return this.control?.selectionStart ?? 0;
+    }
+    setSelectionRange(start, end, direction) {
+        this.control?.setSelectionRange(start, end, direction);
+    }
+    settleOpen() {
+        const focused = this.matches(':focus-within') || this.contains(document.activeElement);
+        this.requestOpen(this.suggesting && !this.dismissed && !this.isDisabled && focused);
+    }
+    move(by) {
+        const options = this.suggestions;
+        if (options.length === 0) {
+            return;
+        }
+        if (!this.open) {
+            this.dismissed = false;
+            this.settleOpen();
+        }
+        const from = this.activeAt;
+        this.activeAt =
+            from < 0 ? (by > 0 ? 0 : options.length - 1) : (from + by + options.length) % options.length;
+    }
+    refreshSuggesting() {
+        const options = this.suggestions;
+        this.suggesting = options.length > 0;
+        this.activeAt = this.activeAt < options.length ? this.activeAt : -1;
+    }
     removeLastToken() {
         const last = this.tokens?.assignedElements({ flatten: true }).at(-1);
         if (asksToGo(last)) {
@@ -74,23 +202,46 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinToken
             this.releaseCaret = holdCaret(control);
         }
         this.handleTokens();
+        this.refreshSuggesting();
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
         this.handleTokens();
+        this.refreshSuggesting();
     }
     updated(changed) {
         super.updated(changed);
         this.releaseCaret?.();
         this.releaseCaret = undefined;
         this.internals.setFormValue(this.value);
+        this.markActive();
+        if (this.open) {
+            this.panel.show();
+        }
+        else {
+            this.panel.hide();
+        }
+        this.settleOpen();
+    }
+    markActive() {
+        const options = this.suggestions;
+        const active = this.open ? options[this.activeAt] : undefined;
+        for (const [at, option] of options.entries()) {
+            option.active = this.open && at === this.activeAt;
+        }
+        const control = this.control;
+        if (control && 'ariaActiveDescendantElement' in control) {
+            ;
+            control.ariaActiveDescendantElement = active ?? null;
+        }
+        active?.scrollIntoView({ block: 'nearest' });
     }
     focus(options) {
         this.control?.focus(options);
     }
     render() {
         return html `${this.renderLabel()}
-    <div part="field">
+    <div part="field" @focusin=${this.handleFocusIn} @focusout=${this.handleFocusOut}>
       <slot name="start"></slot>
       ${this.renderTokenRow(html `<slot name="tags" @slotchange=${this.handleTokens}></slot>`, this.over)}
       <input
@@ -101,6 +252,10 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinToken
         name=${this.name || nothing}
         placeholder=${this.placeholder || nothing}
         aria-describedby=${this.describedBy ?? nothing}
+        role=${this.suggesting ? 'combobox' : nothing}
+        aria-autocomplete=${this.suggesting ? 'list' : nothing}
+        aria-controls=${this.suggesting ? 'suggestions' : nothing}
+        aria-expanded=${this.suggesting ? (this.open ? 'true' : 'false') : nothing}
         ?disabled=${this.isDisabled}
         ?required=${this.required}
         @input=${this.handleInput}
@@ -119,6 +274,14 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinToken
             </button>`
             : nothing}
     </div>
+    <!-- **Always rendered, and hidden rather than absent**, for the reason the
+         token row is: a slot that is not in the tree assigns nothing, so a panel
+         built only once there were options could never learn that there are
+         any. A manual popover puts it in the top layer, so it is not clipped by
+         a scrolling table or an overflow on an ancestor. -->
+    <div part="surface" id="suggestions" role="listbox" popover="manual" ?hidden=${!this.open}>
+      <slot name="suggestions" @slotchange=${this.handleSuggestions}></slot>
+    </div>
     ${this.renderHint()}${this.renderFeedback()}`;
     }
 };
@@ -134,6 +297,12 @@ __decorate([
 __decorate([
     state()
 ], HelixHeadlessFilterInput.prototype, "over", void 0);
+__decorate([
+    state()
+], HelixHeadlessFilterInput.prototype, "activeAt", void 0);
+__decorate([
+    state()
+], HelixHeadlessFilterInput.prototype, "suggesting", void 0);
 HelixHeadlessFilterInput = __decorate([
     customElement('helix-headless-filter-input')
 ], HelixHeadlessFilterInput);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-headless",
   "description": "Headless component tier. Structure, accessibility, state, and form participation. No styling.",
-  "version": "0.13.2",
+  "version": "0.15.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -45,14 +45,14 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.13.2",
-    "@fusion.dev/helix-icons": "0.13.2",
+    "@fusion.dev/helix-core": "0.15.0",
+    "@fusion.dev/helix-icons": "0.15.0",
     "uqr": "^0.1.3"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",
-    "@fusion.dev/helix-cem": "0.13.2",
-    "@fusion.dev/helix-testing": "0.13.2",
+    "@fusion.dev/helix-cem": "0.15.0",
+    "@fusion.dev/helix-testing": "0.15.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.0.0",
     "@lit-labs/ssr": "^3.3.0",