@fusion.dev/helix-headless 0.12.3 → 0.13.1

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

@@ -49,6 +49,7 @@ declare const HelixHeadlessCombobox_base: (new (...args: any[]) => import("@fusi
  * @event {HelixBeforeCloseEvent} helix-before-close - Fired before it closes. Cancelable: refusing it takes the decision and nothing moves.
  * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the panel opens. Cancelable: refusing it takes the decision and nothing moves.
  * @event {HelixCreateEvent} helix-create - Fired when the reader asks for something the list does not hold, and cancelable.
+ * @event {HelixFilterEvent} 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.
  * @event {Event} input - Announced once the value has moved.
  * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
  *

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

@@ -4,7 +4,7 @@ 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, HelixCreateEvent, HelixFormElement, MixinControllerOpen, MixinControllerValue, MixinField, MixinTokens, PopoverController, } from '@fusion.dev/helix-core';
+import { AriaForwardController, customElement, HelixCreateEvent, HelixFilterEvent, HelixFormElement, MixinControllerOpen, MixinControllerValue, MixinField, MixinTokens, PopoverController, } from '@fusion.dev/helix-core';
 import { caretDown } from '@fusion.dev/helix-icons';
 import { nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -47,7 +47,10 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
             event.stopPropagation();
             const typed = event.target.value;
             this.typed = typed;
-            this.listbox?.requestFilter(typed);
+            const narrowing = new HelixFilterEvent({ value: typed });
+            if (this.dispatchEvent(narrowing)) {
+                this.listbox?.requestFilter(typed);
+            }
             this.suggestion = this.suggest && isInsertion(event) ? this.completionFor(typed) : '';
             if (!this.open) {
                 this.requestOpen(true);
@@ -251,6 +254,7 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
       .value=${this.value}
       @helix-before-change=${this.handleChange}
       @change=${this.stopInner}
+      @helix-filter=${this.stopInner}
       @input=${this.stopInner}
     >
       <!-- The field's words are read off the options, and on the first

package/dist/element-events.generated.js

@@ -32,6 +32,7 @@ registerElementEvents({
         'helix-before-close',
         'helix-before-open',
         'helix-create',
+        'helix-filter',
         'input',
         'toggle',
     ],
@@ -52,6 +53,7 @@ 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-heatmap': ['helix-resize'],
     'helix-headless-image': ['error', 'load'],
     'helix-headless-input': ['change', 'helix-before-change', 'input'],

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

@@ -0,0 +1 @@
+export * from './root/filter-input-root.js';

package/dist/filter-input/index.js

@@ -0,0 +1 @@
+export * from './root/filter-input-root.js';

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

@@ -0,0 +1,129 @@
+import { AriaForwardController, HelixFormElement } 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;
+/**
+ * @summary A field that narrows something else, beside what is already narrowing it.
+ *
+ * @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.
+ *
+ * **`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.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category forms
+ * @aliases SearchField, FacetInput, TokenInput
+ * @documentation https://helix.fusion.dev/components/filter-input
+ *
+ * @slot end - After the text, for a count or a control.
+ * @slot start - Before the text, for a search icon.
+ * @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 {Event} input - Announced once the text has moved.
+ *
+ * @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 rest - How many tokens did not fit.
+ * @csspart tags - The row the tokens sit in.
+ */
+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.
+     *
+     * 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: boolean;
+    /**
+     * What the clear button is called, since an icon has no name of its own.
+     */
+    clearLabel: string;
+    /**
+     * Shown while the field is empty.
+     *
+     * Not a label: it goes when typing starts.
+     */
+    placeholder: string;
+    /** How many tokens did not fit, which is what the row's count renders. */
+    private over;
+    /**
+     * The caret, held across a value the consumer wrote rather than the reader.
+     *
+     * Set in `willUpdate` and spent in `updated`, because Lit's `.value` binding
+     * lands between the two and takes the selection with it. See `holdCaret`.
+     */
+    private releaseCaret;
+    /** Focus is delegated to the input, so the host is never the focus target. */
+    static shadowRootOptions: ShadowRootInit;
+    private get control();
+    private get tokens();
+    /** Whether there is a clear button on screen right now. */
+    private get showsClear();
+    /**
+     * Every keystroke, cancelable, and put back where it is refused.
+     *
+     * Stopped for the reason `Input` gives: `input` is composed, so the inner
+     * control's own would arrive beside the one the mixin announces and a consumer
+     * would hear one keystroke twice, once carrying the value from before it.
+     */
+    private readonly handleInput;
+    /** Relayed, because `change` does not cross a shadow boundary on its own. */
+    private readonly handleChange;
+    /**
+     * Empties the text and gives the caret back.
+     *
+     * Focus returns to the input rather than staying on a button that is about to
+     * disappear, which would otherwise land on the body.
+     */
+    private readonly handleClear;
+    private readonly handleKeydown;
+    /** The row again, whenever what is in it changes. */
+    private readonly handleTokens;
+    /**
+     * Asks the last token to go, rather than taking it.
+     *
+     * `dismiss()` is the tag's own, so this is the code path its remove control
+     * already runs on a press: the consumer hears one `helix-dismiss`, cancels it
+     * or removes the element, and never learns which of the two asked. A slotted
+     * node that is not a `Tag` has no such method and is left alone, because
+     * hiding a consumer's element on Backspace would be this element deciding
+     * something it was never given.
+     */
+    protected removeLastToken(): void;
+    protected willUpdate(changed: PropertyValues): void;
+    protected firstUpdated(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    /** Puts the caret in the field, the way a label pointing at one would. */
+    focus(options?: FocusOptions): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-filter-input': HelixHeadlessFilterInput;
+    }
+}
+export {};

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

@@ -0,0 +1,140 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    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 { 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))) {
+    constructor() {
+        super(...arguments);
+        this.aria = new AriaForwardController(this, {
+            target: () => this.renderRoot?.querySelector('[part="control"]') ?? null,
+        });
+        this.announcesInput = true;
+        this.clearable = false;
+        this.clearLabel = 'Clear';
+        this.placeholder = '';
+        this.over = 0;
+        this.handleInput = (event) => {
+            event.stopPropagation();
+            const control = event.target;
+            this.requestValue(control.value);
+            restoreValue(control, this.value);
+        };
+        this.handleChange = (event) => {
+            event.stopPropagation();
+            this.dispatchEvent(new Event('change', { bubbles: true, composed: false }));
+        };
+        this.handleClear = () => {
+            this.requestValue('');
+            const control = this.control;
+            if (control) {
+                restoreValue(control, this.value);
+                control.focus();
+            }
+        };
+        this.handleKeydown = (event) => {
+            this.tokenKeydown(event, this.value);
+        };
+        this.handleTokens = () => {
+            this.over = this.hideOverflow(this.tokens);
+        };
+    }
+    static { this.shadowRootOptions = {
+        ...HelixFormElement.shadowRootOptions,
+        delegatesFocus: true,
+    }; }
+    get control() {
+        return this.renderRoot.querySelector('[part="control"]');
+    }
+    get tokens() {
+        return this.renderRoot?.querySelector('slot[name="tags"]') ?? null;
+    }
+    get showsClear() {
+        return this.clearable && this.value !== '' && !this.isDisabled;
+    }
+    removeLastToken() {
+        const last = this.tokens?.assignedElements({ flatten: true }).at(-1);
+        if (asksToGo(last)) {
+            last.dismiss();
+        }
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        if (!this.hasUpdated) {
+            return;
+        }
+        const control = this.control;
+        if (changed.has('value') && control && this.shadowRoot?.activeElement === control) {
+            this.releaseCaret = holdCaret(control);
+        }
+        this.handleTokens();
+    }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        this.handleTokens();
+    }
+    updated(changed) {
+        super.updated(changed);
+        this.releaseCaret?.();
+        this.releaseCaret = undefined;
+        this.internals.setFormValue(this.value);
+    }
+    focus(options) {
+        this.control?.focus(options);
+    }
+    render() {
+        return html `${this.renderLabel()}
+    <div part="field">
+      <slot name="start"></slot>
+      ${this.renderTokenRow(html `<slot name="tags" @slotchange=${this.handleTokens}></slot>`, this.over)}
+      <input
+        part="control"
+        id="control"
+        type="text"
+        .value=${this.value}
+        name=${this.name || nothing}
+        placeholder=${this.placeholder || nothing}
+        aria-describedby=${this.describedBy ?? nothing}
+        ?disabled=${this.isDisabled}
+        ?required=${this.required}
+        @input=${this.handleInput}
+        @change=${this.handleChange}
+        @keydown=${this.handleKeydown}
+      />
+      <slot name="end"></slot>
+      ${this.showsClear
+            ? html `<button
+              part="clear"
+              type="button"
+              aria-label=${this.clearLabel}
+              @click=${this.handleClear}
+            >
+              ${drawIcon(x)}
+            </button>`
+            : nothing}
+    </div>
+    ${this.renderHint()}${this.renderFeedback()}`;
+    }
+};
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessFilterInput.prototype, "clearable", void 0);
+__decorate([
+    property({ attribute: 'clear-label' })
+], HelixHeadlessFilterInput.prototype, "clearLabel", void 0);
+__decorate([
+    property()
+], HelixHeadlessFilterInput.prototype, "placeholder", void 0);
+__decorate([
+    state()
+], HelixHeadlessFilterInput.prototype, "over", void 0);
+HelixHeadlessFilterInput = __decorate([
+    customElement('helix-headless-filter-input')
+], HelixHeadlessFilterInput);
+export { HelixHeadlessFilterInput };

package/dist/index.d.ts

@@ -42,6 +42,7 @@ export * from './drawer/index.js';
 export * from './drilldown/index.js';
 export * from './empty/index.js';
 export * from './file-input/index.js';
+export * from './filter-input/index.js';
 export * from './format-date/index.js';
 export * from './heatmap/index.js';
 export * from './icon/index.js';

package/dist/index.js

@@ -33,6 +33,7 @@ export * from './drawer/index.js';
 export * from './drilldown/index.js';
 export * from './empty/index.js';
 export * from './file-input/index.js';
+export * from './filter-input/index.js';
 export * from './format-date/index.js';
 export * from './heatmap/index.js';
 export * from './icon/index.js';

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.12.3",
+  "version": "0.13.1",
   "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.12.3",
-    "@fusion.dev/helix-icons": "0.12.3",
+    "@fusion.dev/helix-core": "0.13.1",
+    "@fusion.dev/helix-icons": "0.13.1",
     "uqr": "^0.1.3"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",
-    "@fusion.dev/helix-cem": "0.12.3",
-    "@fusion.dev/helix-testing": "0.12.3",
+    "@fusion.dev/helix-cem": "0.13.1",
+    "@fusion.dev/helix-testing": "0.13.1",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.0.0",
     "@lit-labs/ssr": "^3.3.0",