@fusion.dev/helix-headless 0.12.2 → 0.13.0

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

@@ -2,7 +2,7 @@ import { AriaForwardController, HelixFormElement, PopoverController } from '@fus
 import { type PropertyValues, type TemplateResult } from 'lit';
 import '../../listbox/index.js';
 import '../../tag/index.js';
-declare const HelixHeadlessCombobox_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
+declare const HelixHeadlessCombobox_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 filters a list as it is typed into.
  *
@@ -121,21 +121,6 @@ export declare class HelixHeadlessCombobox extends HelixHeadlessCombobox_base {
      * What the list says while they are on their way.
      */
     loadingText: string;
-    /**
-     * How many tags to draw before the rest become a count. `multiple` only.
-     *
-     * `0` is all of them, and is the default: a cap that guesses is worse than no
-     * cap, because the number that fits depends on the width of the field and the
-     * length of what is in it, neither of which this element knows. What a cap is
-     * genuinely for is a field in a row or a table cell, where a set of twelve
-     * choices would push everything below it down a line at a time.
-     *
-     * The remainder is counted rather than hidden. `+3` is a fact a reader can act
-     * on, where a row that silently stops is a field that appears to have lost
-     * what was put in it. Date Input and Time Input carry the same property and
-     * the same reasoning.
-     */
-    maxTags: number;
     /**
      * Whether more than one option can be chosen.
      *
@@ -295,6 +280,14 @@ export declare class HelixHeadlessCombobox extends HelixHeadlessCombobox_base {
      * when you clicked into the middle of your own typing would be unusable.
      */
     private readonly handleFieldClick;
+    /**
+     * The last chosen one goes, which is what Backspace on an empty field means.
+     *
+     * `MixinTokens` owns when this is asked for and this owns what it does: a
+     * token here is a chosen option, so it leaves by the same door a dismissed
+     * tag does.
+     */
+    protected removeLastToken(): void;
     /** One tag asking to be taken out of the set. */
     private readonly handleDismiss;
     /**

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, PopoverController, } from '@fusion.dev/helix-core';
+import { AriaForwardController, customElement, HelixCreateEvent, 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';
@@ -13,7 +13,7 @@ import { html } from 'lit/static-html.js';
 import '../../listbox/index.js';
 import '../../tag/index.js';
 const isInsertion = (event) => !event.inputType?.startsWith('delete');
-let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerOpen(MixinControllerValue(MixinField(HelixFormElement))) {
+let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerOpen(MixinTokens(MixinControllerValue(MixinField(HelixFormElement)))) {
     constructor() {
         super(...arguments);
         this.aria = new AriaForwardController(this, {
@@ -26,7 +26,6 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
         this.listLabel = 'Options';
         this.loading = false;
         this.loadingText = 'Loading';
-        this.maxTags = 0;
         this.multiple = false;
         this.placeholder = '';
         this.removeLabel = 'Remove';
@@ -71,12 +70,7 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
                 }
                 return;
             }
-            if (event.key === 'Backspace' && this.multiple && this.typed === '') {
-                const last = this.values.at(-1);
-                if (last !== undefined) {
-                    event.preventDefault();
-                    this.drop(last);
-                }
+            if (this.multiple && this.tokenKeydown(event, this.typed)) {
                 return;
             }
             if (event.key === 'Enter' && this.creation !== '' && !this.showing) {
@@ -206,6 +200,12 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
         const match = (this.listbox?.options ?? []).find((option) => !option.hidden && !option.disabled && option.text.toLowerCase().startsWith(needle));
         return match && match.text.length > typed.length ? match.text : '';
     }
+    removeLastToken() {
+        const last = this.values.at(-1);
+        if (last !== undefined) {
+            this.drop(last);
+        }
+    }
     sync() {
         this.internals.setFormValue(this.value === '' ? null : this.value);
         this.reportRequired(this.value === '', 'Choose one to continue.', 'control');
@@ -284,12 +284,7 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
       <div part="field" @click=${this.handleFieldClick}>
         <slot name="start"></slot>
         ${this.multiple && this.chosen.length > 0
-            ? html `<span part="tags">
-                ${this.shown.map((option) => this.renderTag(option))}
-                ${this.restCount > 0
-                ? html `<span part="rest">${`+${this.restCount}`}</span>`
-                : nothing}
-              </span>`
+            ? this.renderTokenRow(this.shown.map((option) => this.renderTag(option)), this.restCount)
             : nothing}
         <input
           part="control"
@@ -344,9 +339,6 @@ __decorate([
 __decorate([
     property({ attribute: 'loading-text' })
 ], HelixHeadlessCombobox.prototype, "loadingText", void 0);
-__decorate([
-    property({ attribute: 'max-tags', type: Number })
-], HelixHeadlessCombobox.prototype, "maxTags", void 0);
 __decorate([
     property({ type: Boolean })
 ], HelixHeadlessCombobox.prototype, "multiple", void 0);

package/dist/element-events.generated.js

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