@fusion.dev/helix-headless 0.23.0 → 0.24.0

package/dist/filter-input/grammar.js

@@ -0,0 +1,133 @@
+export const DEFAULT_FILTER_OPERATORS = [
+    { arity: 'many', default: true, label: 'is any of', name: 'any' },
+    { arity: 'many', default: false, label: 'is none of', name: 'none' },
+];
+const NEGATION = 'none';
+const same = (written, declared) => declared !== '' && written.toLowerCase() === declared.trim().toLowerCase();
+const unquote = (piece) => piece.length > 1 && piece.startsWith('"') && piece.endsWith('"') ? piece.slice(1, -1) : piece;
+function split(text, separator) {
+    const parts = [];
+    let current = '';
+    let quoted = false;
+    for (const char of text) {
+        if (char === '"') {
+            quoted = !quoted;
+            current += char;
+            continue;
+        }
+        if (!quoted && (separator === ' ' ? /\s/.test(char) : char === separator)) {
+            if (current !== '') {
+                parts.push(current);
+            }
+            current = '';
+            continue;
+        }
+        current += char;
+    }
+    if (current !== '') {
+        parts.push(current);
+    }
+    return parts;
+}
+function atColon(term) {
+    let quoted = false;
+    for (let at = 0; at < term.length; at += 1) {
+        const char = term[at];
+        if (char === '"') {
+            quoted = !quoted;
+            continue;
+        }
+        if (!quoted && char === ':') {
+            return [term.slice(0, at), term.slice(at + 1)];
+        }
+    }
+    return null;
+}
+function readPiece(written, fields) {
+    const negated = written.startsWith('-');
+    const parts = atColon(negated ? written.slice(1) : written);
+    if (!parts) {
+        return null;
+    }
+    const key = unquote(parts[0]);
+    const field = fields.find((one) => same(key, one.name) || same(key, one.label));
+    if (!field) {
+        return null;
+    }
+    const operator = negated
+        ? field.operators.find((one) => one.name === NEGATION)
+        : (field.operators.find((one) => one.default) ?? field.operators[0]);
+    if (!operator || operator.arity === 'none') {
+        return null;
+    }
+    const values = [];
+    for (const raw of split(parts[1], ',').map(unquote)) {
+        if (raw === '') {
+            continue;
+        }
+        if (field.values.length === 0) {
+            values.push(raw);
+            continue;
+        }
+        const found = field.values.find((one) => same(raw, one.value) || same(raw, one.label));
+        if (!found) {
+            return null;
+        }
+        values.push(found.value);
+    }
+    if (values.length === 0) {
+        return null;
+    }
+    if (operator.arity === 'one' && values.length > 1) {
+        return null;
+    }
+    return { field, operator, values };
+}
+export function readFilterText(text, fields) {
+    const order = [];
+    const held = new Map();
+    const spare = [];
+    for (const written of split(text, ' ')) {
+        const read = readPiece(written, fields);
+        if (!read) {
+            spare.push(written);
+            continue;
+        }
+        const standing = held.get(read.field.name);
+        if (standing && standing.operator.name !== read.operator.name) {
+            spare.push(written);
+            continue;
+        }
+        if (standing) {
+            for (const value of read.values) {
+                if (!standing.values.includes(value)) {
+                    standing.values.push(value);
+                }
+            }
+            standing.written.push(written);
+            continue;
+        }
+        const term = {
+            field: read.field,
+            operator: read.operator,
+            values: [...new Set(read.values)],
+            written: [written],
+        };
+        order.push(term);
+        held.set(read.field.name, term);
+    }
+    return {
+        terms: order.map((term) => ({
+            facet: {
+                arity: term.operator.arity,
+                field: term.field.name,
+                label: term.field.label,
+                operator: term.operator.name,
+                operatorLabel: term.operator.default ? '' : term.operator.label,
+                values: term.values,
+            },
+            written: term.written,
+        })),
+        text: spare.join(' '),
+    };
+}

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

@@ -1 +1,6 @@
+export * from './chip/filter-chip.js';
+export * from './field/filter-field.js';
+export * from './grammar.js';
+export * from './menu/filter-menu.js';
+export * from './operator/filter-operator.js';
 export * from './root/filter-input-root.js';

package/dist/filter-input/index.js

@@ -1 +1,6 @@
+export * from './chip/filter-chip.js';
+export * from './field/filter-field.js';
+export * from './grammar.js';
+export * from './menu/filter-menu.js';
+export * from './operator/filter-operator.js';
 export * from './root/filter-input-root.js';

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

@@ -0,0 +1,153 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+import type { HelixHeadlessFilterField } from '../field/filter-field.js';
+import type { FilterGrammarOperator } from '../grammar.js';
+import '../../divider/index.js';
+import '../../menu/index.js';
+/**
+ * @summary The control that builds a filter: pick a field, tick its values.
+ *
+ * @description
+ * **It reads the declarations and renders a menu.** A consumer writes their
+ * fields as `FilterField`s inside this, and what comes out is a two level menu:
+ * the fields, and under each one its comparisons and its values. Nothing here
+ * knows what a field means, which is the line `FilterField` already draws.
+ *
+ * ```html
+ * <helix-headless-filter-menu label="Filter">
+ *   <helix-headless-filter-field name="disposition" label="Disposition">
+ *     <helix-headless-option value="refunded">Refunded</helix-headless-option>
+ *   </helix-headless-filter-field>
+ * </helix-headless-filter-menu>
+ * ```
+ *
+ * That field declares no comparisons and so is offered `is any of` and `is none
+ * of`, which are the two the typed grammar can say. The menu and the text end up
+ * offering the same filters because both read `FilterField.vocabulary`, and a
+ * consumer whose field needs other words declares them there.
+ *
+ * **A tick is a filter, immediately.** There is no Apply: ticking a value
+ * announces the field's whole set as it now stands, so a queue narrows as the
+ * reader works rather than after they have finished. Unticking the last value
+ * announces an empty set, which is a consumer's cue to drop the chip.
+ *
+ * **The operator is chosen here and written nowhere else.** `helix-facet` carries
+ * `operatorLabel` empty when the comparison is the field's default, which is
+ * exactly what a chip's `operator-label` wants: the segment appears only where
+ * somebody picked something worth noticing. Deciding it here is the point, since
+ * this is the only thing that has read both the field and its operators.
+ *
+ * **How many values a comparison takes decides what is under it.** A field
+ * whose comparison is `arity="none"`, `is empty` or `is set`, is offered no
+ * values at all and gives back any that were ticked: the comparison is the whole
+ * filter. One at `arity="one"` offers its values as a single choice, so pressing
+ * another replaces it and pressing the one already on clears it. Both announce
+ * `arity` in the facet, which is what lets a consumer tell an empty filter from
+ * no filter at all.
+ *
+ * **It applies nothing.** The chips are the consumer's markup and the rows are
+ * their data, so this announces and stops, the way `Notification` reports a read
+ * rather than inventing one. Refusing `helix-facet` refuses the change.
+ *
+ * @since 0.25.0
+ * @status experimental
+ * @category forms
+ * @aliases FacetPicker, FilterBuilder
+ * @documentation https://helix.fusion.dev/components/filter-input
+ *
+ * @slot - The fields this can filter by, as `FilterField`s. Read rather than rendered.
+ * @slot trigger - The control that opens the menu. A `Button` is the usual one.
+ *
+ * @event {HelixFacetEvent} helix-facet - Fired when a field's values change. Cancelable: refusing it takes the decision and nothing moves.
+ */
+export declare class HelixHeadlessFilterMenu extends HelixElement {
+    /**
+     * Accessible name for the menu.
+     */
+    label: string;
+    /**
+     * What is ticked, per field.
+     *
+     * **Held here rather than read back off the menu**, because the menu's rows
+     * are rebuilt every time a page changes and a tick read from a row that has
+     * been re-rendered is a tick nobody made. This is the answer; the rows are a
+     * view of it.
+     */
+    private readonly picked;
+    /** Which comparison each field is using, where the reader chose one. */
+    private readonly comparisons;
+    /**
+     * The fields declared inside this, in the order they were written.
+     *
+     * What a render may know of them: none on a server, whose shim has no tree
+     * and threw here, and none while hydrating what one sent.
+     */
+    get fields(): HelixHeadlessFilterField[];
+    protected firstUpdated(changed: PropertyValues): void;
+    /** What is ticked for one field, as the consumer's own values. */
+    valuesFor(field: string): readonly string[];
+    /**
+     * Which comparison a field is using: the reader's choice, then the one the
+     * field marked, then the first one it supports.
+     *
+     * **The last of those is not a fallback for nothing, it is the scalar case.**
+     * A date supports `after` and nothing else and marks no default, because there
+     * is nothing for a default to distinguish it from. Answering `null` there left
+     * a chip built from it with no comparison at all: `Created` and a date, with
+     * the word that made it mean anything missing. It is not marked `default`, so
+     * it is not the unwritten one and the chip says it, which is right.
+     *
+     * Read off `vocabulary` rather than off the operator elements, so a field that
+     * declared none is offered the defaults here and parses them in the text, from
+     * one answer rather than two that can drift.
+     */
+    operatorFor(field: HelixHeadlessFilterField): FilterGrammarOperator | null;
+    /**
+     * Announces a field's set as it now stands, and reports whether it stood.
+     *
+     * The whole set rather than the one value that moved, because a filter is the
+     * set: a consumer redrawing a chip from a single tick would have to keep their
+     * own copy of everything else, which is the second source of truth this exists
+     * to avoid.
+     */
+    private announce;
+    /**
+     * Filters a field by these values, announcing it the way a tick does.
+     *
+     * **The one way this element's state changes**, whether the move came from a
+     * row here, from a filter typed into the field around it, or from a chip
+     * somebody dismissed. Before this existed the ticks were only ever written by
+     * a press, so a chip removed anywhere else left the menu still showing it
+     * ticked, and the reader's next press on that value read as *unticking* it:
+     * they pressed `Refunded`, an empty set was announced, and nothing appeared.
+     *
+     * Refusing the `helix-facet` puts everything back, so a consumer who declines
+     * a filter is never left looking at a menu that says it took.
+     */
+    apply(field: string, values: readonly string[], operator?: string): boolean;
+    /**
+     * A row was chosen: a value to tick, or a comparison to use.
+     *
+     * **Read off the row rather than encoded into its `value`.** Packing the three
+     * facts into one string and splitting them apart again was the first idea, and
+     * it does not survive the template: a nested template literal inside a
+     * `static-html` template comes back carrying Lit's own binding marker where
+     * the separator was, so `field disposition` arrived with a null byte in the
+     * middle of it and every split produced nonsense. Three data attributes cost
+     * nothing and there is nothing to parse.
+     *
+     * Stopped here rather than let past, because a consumer listening for
+     * `helix-select` on their own page should not receive one for a row inside a
+     * control they did not write. Only the two rows that choose something need it:
+     * a row that opens a page is stopped by `Menu` itself, in a capture-phase
+     * handler, on the ground that looking into a submenu is not a choice. Measured
+     * both ways, and widening this to every `data-facet` row changed nothing.
+     */
+    private readonly handleSelect;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-filter-menu': HelixHeadlessFilterMenu;
+    }
+}

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

@@ -0,0 +1,164 @@
+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 { customElement, HelixElement, HelixFacetEvent } from '@fusion.dev/helix-core';
+import { nothing } from 'lit';
+import { property } from 'lit/decorators.js';
+import { html } from 'lit/static-html.js';
+import '../../divider/index.js';
+import '../../menu/index.js';
+let HelixHeadlessFilterMenu = class HelixHeadlessFilterMenu extends HelixElement {
+    constructor() {
+        super(...arguments);
+        this.label = 'Filter';
+        this.picked = new Map();
+        this.comparisons = new Map();
+        this.handleSelect = (event) => {
+            const row = event.composedPath()[0];
+            if (!(row instanceof HTMLElement)) {
+                return;
+            }
+            const kind = row.dataset.facet;
+            if (kind !== 'value' && kind !== 'operator') {
+                return;
+            }
+            event.stopPropagation();
+            const field = row.dataset.field ?? '';
+            const value = row.dataset.value ?? '';
+            if (kind === 'operator') {
+                this.apply(field, this.valuesFor(field), value);
+                return;
+            }
+            const declared = this.fields.find((one) => (one.name ?? '') === field);
+            const held = this.picked.get(field) ?? new Set();
+            if (declared && this.operatorFor(declared)?.arity === 'one') {
+                this.apply(field, held.has(value) && held.size === 1 ? [] : [value]);
+                return;
+            }
+            const ticked = new Set(held);
+            if (ticked.has(value)) {
+                ticked.delete(value);
+            }
+            else {
+                ticked.add(value);
+            }
+            this.apply(field, [...ticked]);
+        };
+    }
+    get fields() {
+        return this.knownChildren.filter((child) => ['helix-headless-filter-field', 'helix-filter-field'].includes(child.localName));
+    }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        this.finishHydration();
+    }
+    valuesFor(field) {
+        return [...(this.picked.get(field) ?? [])];
+    }
+    operatorFor(field) {
+        const { operators } = field.vocabulary;
+        const chosen = this.comparisons.get(field.name ?? '');
+        const declared = operators.find((operator) => operator.default) ?? operators[0] ?? null;
+        if (chosen === undefined) {
+            return declared;
+        }
+        return operators.find((operator) => operator.name === chosen) ?? declared;
+    }
+    announce(field) {
+        const operator = this.operatorFor(field);
+        return this.dispatchEvent(new HelixFacetEvent({
+            arity: operator?.arity ?? 'many',
+            field: field.name ?? '',
+            label: field.label,
+            operator: operator?.name ?? '',
+            operatorLabel: operator?.default ? '' : (operator?.label ?? ''),
+            values: this.valuesFor(field.name ?? ''),
+        }));
+    }
+    apply(field, values, operator) {
+        const declared = this.fields.find((one) => (one.name ?? '') === field);
+        if (!declared) {
+            return false;
+        }
+        const heldValues = this.picked.get(field);
+        const heldOperator = this.comparisons.get(field);
+        if (operator !== undefined) {
+            this.comparisons.set(field, operator);
+        }
+        else if (values.length === 0) {
+            this.comparisons.delete(field);
+        }
+        const arity = this.operatorFor(declared)?.arity ?? 'many';
+        this.picked.set(field, new Set(arity === 'none' ? [] : values));
+        const stood = this.announce(declared);
+        if (!stood) {
+            if (heldValues === undefined) {
+                this.picked.delete(field);
+            }
+            else {
+                this.picked.set(field, heldValues);
+            }
+            if (heldOperator === undefined) {
+                this.comparisons.delete(field);
+            }
+            else {
+                this.comparisons.set(field, heldOperator);
+            }
+        }
+        this.requestUpdate();
+        return stood;
+    }
+    render() {
+        const divider = this.tag('divider');
+        const menu = this.tag('menu');
+        const item = this.tag('menu-item');
+        return html `<${menu} label=${this.label} @helix-select=${this.handleSelect}>
+      <slot name="trigger" slot="trigger"></slot>
+      ${this.fields.map((field) => {
+            const { label, name, operators, values } = field.vocabulary;
+            const ticked = this.picked.get(name) ?? new Set();
+            const using = this.operatorFor(field);
+            const offered = using?.arity === 'none' ? [] : values;
+            return html `<${item} data-facet="field" data-field=${name}>
+          ${label}
+          ${operators.length > 1
+                ? html `<${item} slot="submenu" data-facet="comparison" data-field=${name}>
+                  ${using?.label ?? ''}
+                  ${operators.map((operator) => html `<${item}
+                      slot="submenu"
+                      checkable
+                      exclusive
+                      ?checked=${operator.name === using?.name}
+                      data-facet="operator"
+                      data-field=${name}
+                      data-value=${operator.name}
+                    >${operator.label}</${item}>`)}
+                </${item}>`
+                : nothing}
+          ${operators.length > 1 && offered.length > 0
+                ? html `<${divider} slot="submenu" announced></${divider}>`
+                : nothing}
+          ${offered.map((option) => html `<${item}
+              slot="submenu"
+              checkable
+              ?exclusive=${using?.arity === 'one'}
+              ?checked=${ticked.has(option.value)}
+              data-facet="value"
+              data-field=${name}
+              data-value=${option.value}
+            >${option.label}</${item}>`)}
+        </${item}>`;
+        })}
+    </${menu}>`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessFilterMenu.prototype, "label", void 0);
+HelixHeadlessFilterMenu = __decorate([
+    customElement('helix-headless-filter-menu')
+], HelixHeadlessFilterMenu);
+export { HelixHeadlessFilterMenu };

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

@@ -0,0 +1,105 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { nothing, type PropertyValues } from 'lit';
+/**
+ * @summary One way a filter can compare a field to its values.
+ *
+ * @description
+ * **A declaration, not a control.** It renders nothing and is never seen: it is
+ * how a consumer says which comparisons their field supports, in markup, beside
+ * the values it supports them on. `Field` reads them; the chip shows the one in
+ * force; the menu offers the rest.
+ *
+ * **The vocabulary is the consumer's and this element never learns it.** What
+ * `is none of` means against a queue of refunds is a question about refunds, so
+ * nothing here compares anything or knows what `name` will be handed to. Helix
+ * owns the shape a filter has, which is a field, an operator and some values,
+ * and owns the interaction that builds one. What the words mean is the domain's,
+ * which is the same line `FilterInput` already draws when it declines to learn a
+ * grammar.
+ *
+ * **`default` is what makes a chip readable.** The operator a field is usually
+ * filtered by is the one nobody needs told, so a chip drawn with it says only
+ * the field and the values. Naming a second operator `default` on one field is a
+ * consumer bug and the field reports it rather than guessing.
+ *
+ * @since 0.23.0
+ * @status experimental
+ * @category forms
+ * @aliases Comparator, Predicate
+ * @documentation https://helix.fusion.dev/components/filter-input
+ */
+export declare class HelixHeadlessFilterOperator extends HelixElement {
+    /**
+     * How many values this comparison takes.
+     *
+     * `none` is a comparison that is complete on its own, which is what `is empty`
+     * and `is set` are: a chip drawn for one shows no values because there are
+     * none to show, and the menu that builds it offers nothing to pick.
+     *
+     * `one` takes a single value, which is every scalar comparison: `is after` a
+     * date, `is above` a number. `many` takes a set, which is what `is any of` and
+     * `is none of` are, and is the only arity a multi-select panel makes sense
+     * for.
+     *
+     * Read rather than enforced. This element applies nothing, so the arity is a
+     * fact the picker uses to decide what to offer, not a rule it polices. What
+     * the picker does with it: `none` offers no values at all and takes back any
+     * that were ticked, since the comparison is the whole filter; `one` replaces
+     * rather than adds, and its rows announce as one of a set. The typed grammar
+     * reads it too, refusing a list where a scalar was declared and never writing
+     * a comparison that takes nothing.
+     *
+     * The arity reaches a consumer in `helix-facet`, which is what tells an empty
+     * filter from no filter: `values` empty means the field is no longer narrowing
+     * anything, unless the comparison is one that never had values to give.
+     *
+     * **Undefined reads as `many`, and takes no default**, which is the rule every
+     * reflected property here answers to: a default writes an attribute on upgrade
+     * that the server never wrote, and the two markups differ before a reader has
+     * touched anything.
+     */
+    arity?: 'many' | 'none' | 'one';
+    /**
+     * Whether this is the comparison the field is filtered by unless asked
+     * otherwise.
+     *
+     * The chip leaves a default operator unwritten, so the common filter reads as
+     * a field and its values and nothing else, and the word only appears once
+     * somebody has chosen a comparison worth noticing.
+     */
+    default: boolean;
+    /**
+     * What a reader is shown, in the chip and in the menu that changes it.
+     *
+     * Words rather than symbols, and the reason is that a set has more than one
+     * negation: `!=` cannot tell "is none of" from "is not all of", and both are
+     * filters somebody wants. A chip is read, so it takes the reading. The text
+     * grammar a consumer types is theirs and may use whatever symbols it likes.
+     */
+    label: string;
+    /**
+     * What the consumer's own model calls this comparison.
+     *
+     * Never shown. It is what arrives in the filter this element helps build, so
+     * a consumer matches on it rather than on the words a reader sees, and
+     * translating the label breaks nothing.
+     *
+     * Reflected and so undefaulted, for the reason `arity` gives above.
+     */
+    name?: string;
+    protected willUpdate(changed: PropertyValues): void;
+    /**
+     * Nothing, which is what makes this a declaration.
+     *
+     * **No `<slot>`, deliberately.** An element that renders no slot renders none
+     * of its children, so the words a consumer writes inside one are held for
+     * whoever reads them and never painted. That is the whole mechanism, and it
+     * costs no `display: none` in a tier that has no stylesheet to put one in.
+     */
+    protected render(): typeof nothing;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-filter-operator': HelixHeadlessFilterOperator;
+    }
+}

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

@@ -0,0 +1,39 @@
+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 { customElement, HelixElement } from '@fusion.dev/helix-core';
+import { nothing } from 'lit';
+import { property } from 'lit/decorators.js';
+let HelixHeadlessFilterOperator = class HelixHeadlessFilterOperator extends HelixElement {
+    constructor() {
+        super(...arguments);
+        this.default = false;
+        this.label = '';
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        this.internals.role = 'none';
+    }
+    render() {
+        return nothing;
+    }
+};
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessFilterOperator.prototype, "arity", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessFilterOperator.prototype, "default", void 0);
+__decorate([
+    property()
+], HelixHeadlessFilterOperator.prototype, "label", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessFilterOperator.prototype, "name", void 0);
+HelixHeadlessFilterOperator = __decorate([
+    customElement('helix-headless-filter-operator')
+], HelixHeadlessFilterOperator);
+export { HelixHeadlessFilterOperator };