@fusion.dev/helix-headless 0.0.0-dev

package/dist/qr-code/root/qr-code-root.js

@@ -0,0 +1,233 @@
+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 { html, nothing, svg } from 'lit';
+import { property } from 'lit/decorators.js';
+import { encode } from 'uqr';
+/** Whether a module is one of the three finder squares, or their separators. */
+const isFinder = (x, y, size) => {
+    const near = (a, b) => a < 8 && b < 8;
+    return near(x, y) || near(size - 1 - x, y) || near(x, size - 1 - y);
+};
+/**
+ * The dark modules of a matrix, as one path.
+ *
+ * One `<path>` rather than a rect per module. A modest code is 33 by 33, so a
+ * rect apiece is a thousand elements the browser lays out and the accessibility
+ * tree walks, and every one of them is a one-unit square.
+ *
+ * **`square` joins runs and the other styles cannot.** A row of eight square
+ * modules is one `h8`, which is what keeps the node count down; a row of eight
+ * *rounded* ones is eight shapes, because the corners are what is being drawn
+ * and a joined run has no corners in the middle of it. So the cost of the other
+ * styles is real and is paid only by the codes that ask for them.
+ *
+ * `only` splits the drawing in two without walking the matrix twice: the finder
+ * squares are structural, at three known corners, so a caller can ask for them
+ * alone and get a second path to paint differently.
+ */
+const pathFor = (matrix, style, only = 'all') => {
+    const size = matrix.length;
+    const wanted = (x, y) => {
+        if (!matrix[y]?.[x]) {
+            return false;
+        }
+        if (only === 'all') {
+            return true;
+        }
+        return only === 'finders' ? isFinder(x, y, size) : !isFinder(x, y, size);
+    };
+    const parts = [];
+    if (style === 'square') {
+        for (let y = 0; y < size; y += 1) {
+            let run = 0;
+            for (let x = 0; x <= size; x += 1) {
+                if (wanted(x, y)) {
+                    run += 1;
+                    continue;
+                }
+                if (run > 0) {
+                    parts.push(`M${x - run} ${y}h${run}v1h-${run}z`);
+                    run = 0;
+                }
+            }
+        }
+        return parts.join('');
+    }
+    /* A circle for `dots` and a squircle for `rounded`, both drawn as arcs on a
+       one-unit square. The radius is a little under half so neighbouring dots do
+       not touch, which is what makes a dotted code read as dots rather than as a
+       square one with soft edges. */
+    const r = style === 'dots' ? 0.45 : 0.28;
+    for (let y = 0; y < size; y += 1) {
+        for (let x = 0; x < size; x += 1) {
+            if (!wanted(x, y)) {
+                continue;
+            }
+            if (style === 'dots') {
+                parts.push(`M${x + 0.5 - r} ${y + 0.5}a${r} ${r} 0 1 0 ${r * 2} 0a${r} ${r} 0 1 0 ${-r * 2} 0z`);
+            }
+            else {
+                parts.push(`M${x + r} ${y}h${1 - r * 2}a${r} ${r} 0 0 1 ${r} ${r}` +
+                    `v${1 - r * 2}a${r} ${r} 0 0 1 ${-r} ${r}` +
+                    `h${-(1 - r * 2)}a${r} ${r} 0 0 1 ${-r} ${-r}` +
+                    `v${-(1 - r * 2)}a${r} ${r} 0 0 1 ${r} ${-r}z`);
+            }
+        }
+    }
+    return parts.join('');
+};
+/**
+ * @summary Encodes a short piece of text as a scannable square.
+ *
+ * @description
+ * **The picture is one `<path>`, not a grid of squares.** A code of any useful
+ * length is a thousand modules, and drawing each as its own rect is a thousand
+ * nodes for one image. Runs of adjacent dark modules are joined, so a row of
+ * eight is one horizontal move rather than eight squares.
+ *
+ * **It is an image and says so.** `role="img"` with a name, because what a
+ * reader with a screen reader needs is what the code is *for*, and no amount of
+ * describing the pattern gives them that. Where nothing is passed the value
+ * itself is the name, which is right far more often than it looks: most codes
+ * hold a URL, and a URL read aloud is the destination.
+ *
+ * **The quiet zone is part of the code.** Four modules of margin are required
+ * by the specification, not a design choice, and a scanner will refuse a code
+ * that is cropped to its edge. It is drawn inside the `viewBox` so it survives
+ * any size the component is given, including one set in CSS.
+ *
+ * `correction` is what buys the middle slot. A code at `H` can lose thirty
+ * percent of itself and still read, which is what makes covering the center
+ * with a mark safe; at `L` the same mark makes the code unscannable. That is
+ * why the slot exists on the same element as the property, and why the default
+ * moves when the slot is filled.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category media
+ * @aliases QR, Barcode, Scan code
+ * @documentation https://helix.fusion.dev/components/qr-code
+ *
+ * @slot logo - A mark for the center, which only reads at a high correction.
+ *
+ * @csspart code - The square itself.
+ * @csspart finders - The three corner squares, which can take their own color.
+ * @csspart logo - The box holding the center mark.
+ * @csspart modules - Everything but the three corner squares.
+ */
+let HelixHeadlessQrCode = class HelixHeadlessQrCode extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * What the code encodes, which is usually a URL.
+         */
+        this.value = '';
+        /**
+         * What the image is called.
+         *
+         * Falling back to the value is deliberate: a code almost always holds a URL,
+         * and a URL is a better name than "QR code" for a reader who cannot see it.
+         */
+        this.label = '';
+        /**
+         * How the modules are drawn.
+         *
+         * `square` is the default and the only one that joins runs of adjacent
+         * modules into a single subpath, which is what keeps a thousand modules to a
+         * handful of nodes. `rounded` and `dots` draw each module on its own, because
+         * the corners are the thing being drawn and a joined run has none in the
+         * middle. That cost is paid only by a code that asks for them.
+         *
+         * A scanner reads contrast between cells, not their shape, so all three
+         * scan. `dots` sits a little under half a module so neighbours do not touch,
+         * which is what makes it read as dots rather than as a softened square code.
+         */
+        this.shape = 'square';
+        /** Whether anything is slotted into the middle. */
+        this.logo = false;
+    }
+    /** The level actually used, which the slot can raise. */
+    get level() {
+        return this.correction ?? (this.logo ? 'H' : 'M');
+    }
+    renderCode() {
+        if (this.value === '') {
+            return nothing;
+        }
+        /* Regenerated on every render rather than cached. It is a pure function of
+           two properties, Lit only renders when one of them moved, and a cache here
+           would be a second place for them to disagree. */
+        const result = encode(this.value, { border: 0, ecc: this.level });
+        const size = result.size;
+        /* The quiet zone, in the `viewBox` rather than in a wrapper's padding. Four
+           modules is what the specification requires and what a scanner looks for,
+           so it has to scale with the code and not with whatever box the component
+           was given. */
+        const quiet = 4;
+        const box = size + quiet * 2;
+        /* The three corner squares as their own path, so they can take their own
+           color. Their positions are structural rather than guessed: seven by
+           seven at each of three corners, plus the separator ring, which is what
+           `isFinder` describes. Drawn square whatever the body's style is, because
+           they are what a scanner locks onto first and rounding them costs
+           reliability for decoration. */
+        const finders = pathFor(result.data, 'square', 'finders');
+        return svg `<svg
+      part="code"
+      viewBox="0 0 ${box} ${box}"
+      xmlns="http://www.w3.org/2000/svg"
+      role="img"
+      aria-label=${this.label || this.value}
+      shape-rendering="crispEdges"
+    >
+      <path
+        part="modules"
+        d=${pathFor(result.data, this.shape, 'body')}
+        transform="translate(${quiet} ${quiet})"
+        fill="currentColor"
+      />
+      <path
+        part="finders"
+        d=${finders}
+        transform="translate(${quiet} ${quiet})"
+        fill="currentColor"
+      />
+    </svg>`;
+    }
+    render() {
+        return html `${this.renderCode()}
+    <span ?hidden=${!this.logo} part="logo">
+      <slot
+        name="logo"
+        @slotchange=${(event) => {
+            const next = event.target.assignedNodes().length > 0;
+            if (next !== this.logo) {
+                this.logo = next;
+                this.requestUpdate();
+            }
+        }}
+      ></slot>
+    </span>`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessQrCode.prototype, "value", void 0);
+__decorate([
+    property()
+], HelixHeadlessQrCode.prototype, "label", void 0);
+__decorate([
+    property()
+], HelixHeadlessQrCode.prototype, "shape", void 0);
+__decorate([
+    property({ attribute: 'correction' })
+], HelixHeadlessQrCode.prototype, "correction", void 0);
+HelixHeadlessQrCode = __decorate([
+    customElement('helix-headless-qr-code')
+], HelixHeadlessQrCode);
+export { HelixHeadlessQrCode };

package/dist/quote/index.d.ts

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

package/dist/quote/index.js

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

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

@@ -0,0 +1,36 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type TemplateResult } from 'lit';
+/**
+ * @summary A short quotation, set inline with the text around it.
+ *
+ * @description
+ * Renders a real `<q>`, which is what supplies the quotation marks: the browser
+ * inserts the right ones for the document's language, and nests them correctly
+ * when one quotation sits inside another. Typing the marks into the content
+ * instead gets both of those wrong in every language but one.
+ *
+ * A passage set off from the prose rather than run inside it is a blockquote,
+ * which is a different element for a different job.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category typography
+ * @aliases Q, InlineQuote
+ * @documentation https://helix.fusion.dev/components/quote
+ *
+ * @slot - The quoted text.
+ *
+ * @csspart quote - The quotation.
+ */
+export declare class HelixHeadlessQuote extends HelixElement {
+    /**
+     * URL identifying where the quotation came from.
+     */
+    cite: string;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-quote': HelixHeadlessQuote;
+    }
+}

package/dist/quote/root/quote-root.js

@@ -0,0 +1,50 @@
+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 { html, nothing } from 'lit';
+import { property } from 'lit/decorators.js';
+/**
+ * @summary A short quotation, set inline with the text around it.
+ *
+ * @description
+ * Renders a real `<q>`, which is what supplies the quotation marks: the browser
+ * inserts the right ones for the document's language, and nests them correctly
+ * when one quotation sits inside another. Typing the marks into the content
+ * instead gets both of those wrong in every language but one.
+ *
+ * A passage set off from the prose rather than run inside it is a blockquote,
+ * which is a different element for a different job.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category typography
+ * @aliases Q, InlineQuote
+ * @documentation https://helix.fusion.dev/components/quote
+ *
+ * @slot - The quoted text.
+ *
+ * @csspart quote - The quotation.
+ */
+let HelixHeadlessQuote = class HelixHeadlessQuote extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * URL identifying where the quotation came from.
+         */
+        this.cite = '';
+    }
+    render() {
+        return html `<q part="quote" cite=${this.cite || nothing}><slot></slot></q>`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessQuote.prototype, "cite", void 0);
+HelixHeadlessQuote = __decorate([
+    customElement('helix-headless-quote')
+], HelixHeadlessQuote);
+export { HelixHeadlessQuote };

package/dist/radio/group/radio-group.d.ts

@@ -0,0 +1,84 @@
+import { DisabledCascadeController, HelixFormElement, KeyboardNavigationController } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+import { HelixHeadlessRadio } from '../root/radio-root.js';
+declare const HelixHeadlessRadioGroup_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
+/**
+ * @summary A set of choices where exactly one is the answer.
+ *
+ * @description
+ * **The group is the control, and the radios are its options.** This is the
+ * asymmetry with checkboxes and it comes from what a form submits: a set of
+ * checkboxes is several answers and each box submits its own, while a set of
+ * radios is one answer, so the group owns the `name`, the `value` and the
+ * validity, and a lone radio outside a group is not a control at all.
+ *
+ * Which is also why `MixinField` lands here and not on `Radio`: the label, the
+ * hint and the message are about the question, and the question is the set.
+ *
+ * Selection travels up and state travels down. An item announces that it was
+ * chosen, the group decides whether that stands, and the group writes
+ * `selected` onto every item. Nothing sets itself, so there is one answer to
+ * "which one is on" rather than one per item.
+ *
+ * `value` and `defaultValue` are separate for the reason `checked` and
+ * `defaultChecked` are: `value` is the answer now, `defaultValue` is what the
+ * markup asked for, which is where a reset returns and is gone the moment
+ * anything is chosen.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @aliases RadioButtons, Choice group
+ * @documentation https://helix.fusion.dev/components/radio-group
+ *
+ * @slot - The radios.
+ * @slot hint - Richer than a string.
+ * @slot label - Richer than a string, where the question is more than one.
+ *
+ * @event {Event} change - Announced once the value has moved.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired when the answer changes, and cancelable.
+ * @event {Event} input - Announced once the value has moved.
+ *
+ * @csspart feedback - What is wrong with it.
+ * @csspart hint - Help under the set.
+ * @csspart items - The choices, which is what `orientation` lays out.
+ * @csspart label - The question, over the set.
+ */
+export declare class HelixHeadlessRadioGroup extends HelixHeadlessRadioGroup_base {
+    /**
+     * Which way the choices run. A column reads one line per answer.
+     *
+     * **Optional rather than defaulted, which is not a style preference.** A
+     * reflecting property with a default writes its attribute onto every host the
+     * moment the element upgrades, including the ones a consumer rendered and did
+     * not touch, and React reads that as a hydration mismatch. The absent
+     * attribute *is* the column, which the stylesheet reads as the base rule, so
+     * only `horizontal` has to be named.
+     */
+    orientation?: 'horizontal' | 'vertical';
+    protected readonly keys: KeyboardNavigationController;
+    protected readonly cascade: DisabledCascadeController;
+    /** The radios, in light-DOM order. Client only: the server has no tree. */
+    get items(): HelixHeadlessRadio[];
+    /**
+     * Announces before it applies, so a listener can refuse the change.
+     *
+     * The item has not moved by the time this runs, unlike a native input, so
+     * refusing is simply not writing the value: there is nothing to put back.
+     */
+    private readonly handleSelection;
+    /** Writes the answer onto the items, and nothing onto the host. */
+    private place;
+    /** Reports the answer and the verdict on it. */
+    private sync;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-radio-group': HelixHeadlessRadioGroup;
+    }
+}
+export {};

package/dist/radio/group/radio-group.js

@@ -0,0 +1,170 @@
+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, DisabledCascadeController, HelixFormElement, hostAria, KeyboardNavigationController, MixinControllerValue, MixinField, } from '@fusion.dev/helix-core';
+import { html } from 'lit';
+import { property } from 'lit/decorators.js';
+import { HelixHeadlessRadio } from '../root/radio-root.js';
+/**
+ * @summary A set of choices where exactly one is the answer.
+ *
+ * @description
+ * **The group is the control, and the radios are its options.** This is the
+ * asymmetry with checkboxes and it comes from what a form submits: a set of
+ * checkboxes is several answers and each box submits its own, while a set of
+ * radios is one answer, so the group owns the `name`, the `value` and the
+ * validity, and a lone radio outside a group is not a control at all.
+ *
+ * Which is also why `MixinField` lands here and not on `Radio`: the label, the
+ * hint and the message are about the question, and the question is the set.
+ *
+ * Selection travels up and state travels down. An item announces that it was
+ * chosen, the group decides whether that stands, and the group writes
+ * `selected` onto every item. Nothing sets itself, so there is one answer to
+ * "which one is on" rather than one per item.
+ *
+ * `value` and `defaultValue` are separate for the reason `checked` and
+ * `defaultChecked` are: `value` is the answer now, `defaultValue` is what the
+ * markup asked for, which is where a reset returns and is gone the moment
+ * anything is chosen.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @aliases RadioButtons, Choice group
+ * @documentation https://helix.fusion.dev/components/radio-group
+ *
+ * @slot - The radios.
+ * @slot hint - Richer than a string.
+ * @slot label - Richer than a string, where the question is more than one.
+ *
+ * @event {Event} change - Announced once the value has moved.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired when the answer changes, and cancelable.
+ * @event {Event} input - Announced once the value has moved.
+ *
+ * @csspart feedback - What is wrong with it.
+ * @csspart hint - Help under the set.
+ * @csspart items - The choices, which is what `orientation` lays out.
+ * @csspart label - The question, over the set.
+ */
+let HelixHeadlessRadioGroup = class HelixHeadlessRadioGroup extends MixinControllerValue(MixinField(HelixFormElement)) {
+    constructor() {
+        super(...arguments);
+        /* Moving and choosing are one act, which is the radio group pattern and is
+           what this controller exists to stop being written per component. */
+        /* Registered rather than held. A controller adds itself to the host, so there
+           is no reference to keep: nothing here talks to it after construction, which
+           is why it is `protected` and not `private`. A private field nothing reads
+           is an unused one, and the honest reading is that the subclass tier is where
+           a consumer would reach for it. */
+        this.keys = new KeyboardNavigationController(this, { items: () => this.items });
+        /* Stated once, and the group never thinks about it again. See the
+           controller: the cascade was four hand calls from four different
+           methods, so which paths reached it differed by component and a fifth
+           group would have got none at all. */
+        this.cascade = new DisabledCascadeController(this, {
+            items: () => this.items,
+        });
+        /**
+         * Announces before it applies, so a listener can refuse the change.
+         *
+         * The item has not moved by the time this runs, unlike a native input, so
+         * refusing is simply not writing the value: there is nothing to put back.
+         */
+        this.handleSelection = (event) => {
+            event.stopPropagation();
+            const next = event.detail.value;
+            if (next === this.value) {
+                return;
+            }
+            this.requestValue(next);
+        };
+    }
+    /** The radios, in light-DOM order. Client only: the server has no tree. */
+    get items() {
+        return [...this.children].filter((child) => child instanceof HelixHeadlessRadio);
+    }
+    /** Writes the answer onto the items, and nothing onto the host. */
+    place() {
+        const items = this.items;
+        for (const item of items) {
+            item.selected = item.value === this.value;
+        }
+        /* Nothing chosen yet, so the first item is the tab stop. A group where
+           every item is `tabindex="-1"` is a group the keyboard cannot enter.
+         *
+         * Taken back the moment there is an answer, which it was not: the attribute
+         * was written on the first item and never removed, so an answered group
+         * carried two tab stops, the entry one and the selected item's own. Tabbing
+         * through a form stopped twice on one question, and the first stop was on an
+         * item that is not the answer.
+         *
+         * `entered` rather than a bare toggle, because this also runs when the
+         * group is answered and the attribute has to go whether or not this call is
+         * the one that put it there. */
+        const entered = this.value === '' && items.length > 0 ? items[0] : undefined;
+        for (const item of items) {
+            if (item === entered) {
+                item.setAttribute('tabindex', '0');
+            }
+            else {
+                item.removeAttribute('tabindex');
+            }
+        }
+    }
+    /** Reports the answer and the verdict on it. */
+    sync() {
+        this.internals.setFormValue(this.value === '' ? null : this.value);
+        this.reportRequired(this.value === '', 'Choose one to continue.', 'items');
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.addEventListener('helix-select', this.handleSelection);
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.removeEventListener('helix-select', this.handleSelection);
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        // Through internals, so nothing lands on the host as an attribute a React
+        // consumer's server markup never had.
+        /* The string half, which is what a server can write. `linkHost` adds the
+           element references on the client, and those win where a consumer slotted
+           a label richer than a string. */
+        hostAria(this.internals, { label: this.label, role: 'radiogroup' });
+        /* Announced as required, which it never was.
+         *
+         * `required` reflects, sets validity and paints the asterisk the field sheet
+         * draws, and told the accessibility tree nothing: a reader met a group with
+         * a mark beside its label they could not see and no announcement of why the
+         * form would refuse it. The stylesheet drawing that asterisk depends on the
+         * control saying so. */
+        this.internals.ariaRequired = this.required ? 'true' : null;
+    }
+    updated(changed) {
+        super.updated(changed);
+        this.place();
+        this.sync();
+        this.linkHost();
+    }
+    render() {
+        /* The choices sit in an element of their own, because `orientation` lays
+           out whatever is in the flex container and on the host that would be the
+           label and the hint as well. */
+        return html `${this.renderGroupLabel()}
+      <div part="items">
+        <slot @slotchange=${() => this.place()}></slot>
+      </div>
+      ${this.renderHint()}${this.renderFeedback()}`;
+    }
+};
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessRadioGroup.prototype, "orientation", void 0);
+HelixHeadlessRadioGroup = __decorate([
+    customElement('helix-headless-radio-group')
+], HelixHeadlessRadioGroup);
+export { HelixHeadlessRadioGroup };

package/dist/radio/index.d.ts

@@ -0,0 +1,2 @@
+export * from './group/radio-group.js';
+export * from './root/radio-root.js';

package/dist/radio/index.js

@@ -0,0 +1,2 @@
+export * from './group/radio-group.js';
+export * from './root/radio-root.js';