@fusion.dev/helix-headless 0.0.0-dev

package/dist/popover/root/popover-root.js

@@ -0,0 +1,231 @@
+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 { anchorElement, CommandController, customElement, deepActiveElement, HelixElement, MixinControllerOpen, PopoverController, tellDisclosure, } from '@fusion.dev/helix-core';
+import { html } from 'lit';
+import { property } from 'lit/decorators.js';
+/**
+ * @summary A panel that opens against a trigger and holds anything.
+ *
+ * @description
+ * The general case the specific overlays are versions of. `Menu` holds
+ * commands, `Select` holds options, `Tooltip` holds a description; this holds
+ * whatever the consumer puts in it, which is why it has no keyboard of its own
+ * and no opinion about what is inside.
+ *
+ * **The trigger is slotted and stays the consumer's own element.** Nothing is
+ * written onto it: no `aria-expanded`, no `id`, no `tabindex`. A component that
+ * decorates a consumer's markup after upgrading is a component whose output a
+ * React consumer's hydration disagrees with, and the attribute they would care
+ * about most is the one that changes on every open.
+ *
+ * **The panel is in the top layer**, through the popover API, so it clears any
+ * ancestor with `overflow: hidden` without a `z-index` fight. `position: fixed`
+ * does not do that: it is still clipped by `overflow`, and re-anchored entirely
+ * by an ancestor carrying `transform`, `filter` or `contain`.
+ *
+ * **It opens on click, and from a command.** `command="--show"` and its
+ * siblings work here the way they do on `Dialog` and `Drawer`, so a trigger
+ * elsewhere on the page can open it without a line of script and without being
+ * slotted into it.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category overlays
+ * @aliases Popper, Flyout, Overlay
+ * @documentation https://helix.fusion.dev/components/popover
+ *
+ * @slot - The contents of the panel.
+ * @slot trigger - What opens it.
+ *
+ * @event {HelixBeforeCloseEvent} helix-before-close - Fired before it closes, and cancelable.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before it opens, and cancelable.
+ * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
+ *
+ * @csspart content - The scrolling region inside the panel.
+ * @csspart popover - The panel.
+ */
+let HelixHeadlessPopover = class HelixHeadlessPopover extends MixinControllerOpen(HelixElement) {
+    constructor() {
+        super(...arguments);
+        /**
+         * Accessible name for the panel.
+         */
+        this.label = 'Popover';
+        /**
+         * Space between the trigger and the panel, in pixels.
+         */
+        this.offset = 4;
+        /**
+         * Preferred side.
+         *
+         * It moves if that side does not fit.
+         */
+        this.placement = 'bottom-start';
+        /* The panel, plus everything that has to happen around it: one controller
+           rather than the three this took at every call site, which is what let
+           `Select` quietly never reach the top layer at all.
+         *
+         * Called `panel` rather than `popover`, because `HTMLElement.popover` is the
+         * popover API's own IDL attribute and a field of that name shadows it with
+         * something of a different type. TypeScript objects; what it would have done
+         * at runtime is break the API this is built on. */
+        this.panel = new PopoverController(this, {
+            anchor: () => this.trigger,
+            /* The host, not the panel. `display: contents` leaves it without a box, so
+               a press on the trigger is inside the host and outside the panel, and a
+               boundary of the panel alone would close on the very press that opened
+               it. */
+            /* The host *and* whatever invoked it. An outside press is measured against
+               this, and a `--toggle` button outside the host is part of the control by
+               any reading a reader would give it: pressing it while the panel is open
+               should close it once, not close it on `pointerdown` and reopen it on the
+               `click` that follows. */
+            boundary: () => [this, this.invoker],
+            offset: () => this.offset,
+            onDismiss: () => this.hide(),
+            placement: () => this.placement,
+            surface: () => this.renderRoot?.querySelector('[part="popover"]'),
+        });
+        this.commands = new CommandController(this, {
+            commands: {
+                '--close': () => this.hide(),
+                '--show': (source) => {
+                    this.invoker = source instanceof HTMLElement ? source : undefined;
+                    this.show();
+                },
+                '--toggle': (source) => {
+                    this.invoker = source instanceof HTMLElement ? source : undefined;
+                    if (this.open) {
+                        this.hide();
+                    }
+                    else {
+                        this.show();
+                    }
+                },
+            },
+        });
+        this.handleTriggerClick = () => {
+            if (this.open) {
+                this.hide();
+            }
+            else {
+                this.show();
+            }
+        };
+    }
+    /** The element the panel opens against. */
+    get trigger() {
+        /* The invoker first, where there is one: a command names the element the
+           reader actually pressed, and it is a better anchor than a slotted trigger
+           the consumer may not have provided at all. */
+        return (this.invoker ??
+            anchorElement(this.renderRoot?.querySelector('slot[name="trigger"]'), this));
+    }
+    /** Opens the panel. */
+    show() {
+        if (this.open || !this.requestOpen(true)) {
+            return;
+        }
+        // The raising happens in `updated()`, which `requestOpen` has just
+        // scheduled: one path for both the imperative and the declarative case.
+    }
+    /** Closes the panel and puts focus back on the trigger. */
+    hide() {
+        if (!this.open || !this.requestOpen(false)) {
+            return;
+        }
+        this.panel.hide();
+        /* Only when focus is inside the panel that is going away. A popover
+           dismissed by a press somewhere else has not taken focus with it, and
+           pulling focus back to the trigger would move a reader who was already
+           somewhere else on purpose. */
+        /* `deepActiveElement`, which walks into shadow roots. `document.activeElement`
+           stops at the outermost host, so a popover living inside another
+           component's shadow root never saw its own focus and never gave it back to
+           the trigger. The util exists for this. */
+        if (this.contains(deepActiveElement())) {
+            this.trigger.focus();
+        }
+    }
+    /** Tells a slotted trigger the disclosure state, by property. See `tellDisclosure`. */
+    tellTrigger() {
+        const slot = this.renderRoot?.querySelector('slot[name="trigger"]');
+        tellDisclosure(slot?.assignedElements({ flatten: false })[0], this.open);
+    }
+    /**
+     * Puts the panel where `open` says it should be, however it got there.
+     *
+     * `show()` and `hide()` raised and lowered it, and nothing else did, so a
+     * panel opened by *declaring* `open` (or `default-open`, or a consumer
+     * assigning the property) rendered visible and was never in the top layer and
+     * never anchored. Every imperative path worked and every declarative one was
+     * quietly half-open: clipped by the first ancestor with `overflow`, and
+     * positioned wherever normal flow left it.
+     *
+     * Driving the controller from the resolved state rather than from the two
+     * methods is what makes the two paths the same path. The controller ignores a
+     * `show()` on something already raised, so this costs nothing when the
+     * methods did the work.
+     */
+    updated(changed) {
+        super.updated(changed);
+        /* Every update, not only the ones that move `open`: a trigger slotted after
+           the first render has to be told too, and a slot change is not a property
+           change. Idempotent, so saying it twice costs an assignment Lit compares
+           and discards. */
+        this.tellTrigger();
+        if (!changed.has('open')) {
+            return;
+        }
+        /* Raised here rather than a microtask later, and `updated()` is what makes
+           that safe: the render has already been written, so the panel is no longer
+           `display: none` and `showPopover` will not throw on it. The old
+           `show()` deferred to `updateComplete` precisely because it ran *before*
+           the render; from here there is nothing left to wait for. */
+        if (this.open) {
+            this.panel.show();
+        }
+        else {
+            this.panel.hide();
+        }
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        /* The name is the panel's, not the host's.
+         *
+         * `label` is documented as the panel's accessible name and was written to
+         * the host's internals, and the host carries no role at all: the name
+         * landed on a generic element while the panel it names rendered with none.
+         * A `dialog` role goes with it, because a name needs something to be the
+         * name of, and that is what a popover is. */
+    }
+    render() {
+        return html `<slot name="trigger" @click=${this.handleTriggerClick}></slot>
+      <div
+        part="popover"
+        popover="manual"
+        role="dialog"
+        aria-label=${this.label}
+        ?hidden=${!this.open}
+      >
+        <div part="content"><slot></slot></div>
+      </div>`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessPopover.prototype, "label", void 0);
+__decorate([
+    property({ type: Number })
+], HelixHeadlessPopover.prototype, "offset", void 0);
+__decorate([
+    property()
+], HelixHeadlessPopover.prototype, "placement", void 0);
+HelixHeadlessPopover = __decorate([
+    customElement('helix-headless-popover')
+], HelixHeadlessPopover);
+export { HelixHeadlessPopover };

package/dist/progress/index.d.ts

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

package/dist/progress/index.js

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

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

@@ -0,0 +1,125 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @summary Shows how far along a task is, when that is known.
+ *
+ * @description
+ * Determinate by default, and `indeterminate` for a task whose total is not
+ * known yet. `Loader` is still the right answer where the wait is short or has
+ * no place of its own on the page; a bar earns its width where the work is the
+ * subject of the region it sits in.
+ *
+ * A bar that fills at a made-up rate would be a bar that lies, so the
+ * indeterminate one does not fill: it runs a segment across the track, which
+ * says work is happening and claims no proportion at all. `aria-valuenow` is
+ * omitted with it, which is the platform's own signal for the same thing.
+ *
+ * **The fill is a percentage of the track, written as a custom property.** It
+ * is derived from `value` and `max` rather than measured, so it renders on a
+ * server with no layout and needs nothing after upgrade. That is what keeps it
+ * out of the class of geometry this library writes only on the client.
+ *
+ * **`value` is clamped, and out-of-range input is not an error.** A count that
+ * runs past its own total is ordinary in real applications, and a bar that
+ * overflows its track or reports `aria-valuenow` above `aria-valuemax` is worse
+ * than one that reads as finished.
+ *
+ * Semantics are on the host through `ElementInternals`, the same as everywhere
+ * else: a `role` in the shadow root announces correctly and leaves the host
+ * anonymous to anything walking the light DOM, and a `role` written onto the
+ * host as an attribute is one a server's markup never had.
+ *
+ * The properties below are written by this component and read by whoever draws
+ * it. A consumer sets none of them: they carry a number this element computed
+ * and CSS cannot, which is what lets a stylesheet on this tier draw the thing
+ * without measuring anything itself.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category feedback
+ * @aliases Progress bar, Loading bar
+ * @documentation https://helix.fusion.dev/components/progress
+ *
+ * @csspart groove - The unfilled circle, under the ring's own sweep.
+ * @csspart indicator - The part of it that is done.
+ * @csspart track - The full length the work is measured against.
+ * @csspart value - The reading beside the bar, under `show-value`.
+ *
+ * @cssproperty --progress-fraction - The value as a fraction of the range, 0 to 1. Absent while indeterminate.
+ */
+export declare class HelixHeadlessProgress extends HelixElement {
+    /**
+     * Accessible name for what is in progress.
+     */
+    label: string;
+    /**
+     * Whether the work has a knowable end.
+     *
+     * On the headless tier rather than as a treatment, because it is
+     * semantics before it is a picture: a progressbar with no `aria-valuenow` is
+     * how the platform says "running, and nobody knows how far", and a reader on
+     * a screen reader is told that rather than being read a number that means
+     * nothing. `value` and `max` are ignored while it is set.
+     *
+     * Not `Loader`, which is the other thing this could be. A loader says the
+     * page is busy; a bar says a named piece of work is running, and keeps its
+     * place in the layout when the answer arrives and it becomes determinate.
+     */
+    indeterminate: boolean;
+    /**
+     * The total the work is measured against.
+     */
+    max: number;
+    /**
+     * Whether the value is drawn as a bar or as a ring.
+     *
+     * **On this tier because it changes the markup**, which is the headless tier's to
+     * own. A bar is two boxes and a ring is an SVG with two circles in it, and no
+     * stylesheet turns one into the other: the styled tier tried, with a conic
+     * gradient and a mask, and the thing it could not do was the round end the
+     * loader has, because a gradient has hard radial edges and no notion of a
+     * cap. `Skeleton.shape` is the same word for the same kind of decision.
+     *
+     * The value, the ARIA and the form participation are untouched by it. What
+     * changes is only which shape carries the fraction.
+     */
+    shape?: 'ring';
+    /**
+     * Whether the reading is shown beside the bar.
+     *
+     * The same name and shape `Slider` uses, because it is the same question:
+     * a control that holds a number can either show it or leave it to whatever is
+     * around it. Off by default, since most bars sit under a label that already
+     * says what is happening and a second number is noise.
+     *
+     * Nothing under `indeterminate`, where there is no reading to show: a percent
+     * that does not move is worse than none, and `valueText` is the property for
+     * saying "uploading" while the bar runs.
+     */
+    showValue: boolean;
+    /**
+     * What has been done so far, in the same units as `max`.
+     *
+     * Clamped between zero and `max` for both the fill and the announcement, so
+     * the two can never disagree about what is on screen.
+     */
+    value: number;
+    /**
+     * A reading for the value, where the number alone does not say enough.
+     *
+     * "3 of 8 files" rather than "37". Announced instead of the percentage, and
+     * never instead of the value itself: `aria-valuenow` still carries the
+     * number, because assistive technology that ignores the text still has to
+     * report progress.
+     */
+    valueText: string;
+    /** What is done, as a fraction of the whole, between 0 and 1. */
+    get fraction(): number;
+    protected willUpdate(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-progress': HelixHeadlessProgress;
+    }
+}

package/dist/progress/root/progress-root.js

@@ -0,0 +1,212 @@
+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, hostAria } from '@fusion.dev/helix-core';
+import { html } from 'lit';
+import { property } from 'lit/decorators.js';
+/**
+ * @summary Shows how far along a task is, when that is known.
+ *
+ * @description
+ * Determinate by default, and `indeterminate` for a task whose total is not
+ * known yet. `Loader` is still the right answer where the wait is short or has
+ * no place of its own on the page; a bar earns its width where the work is the
+ * subject of the region it sits in.
+ *
+ * A bar that fills at a made-up rate would be a bar that lies, so the
+ * indeterminate one does not fill: it runs a segment across the track, which
+ * says work is happening and claims no proportion at all. `aria-valuenow` is
+ * omitted with it, which is the platform's own signal for the same thing.
+ *
+ * **The fill is a percentage of the track, written as a custom property.** It
+ * is derived from `value` and `max` rather than measured, so it renders on a
+ * server with no layout and needs nothing after upgrade. That is what keeps it
+ * out of the class of geometry this library writes only on the client.
+ *
+ * **`value` is clamped, and out-of-range input is not an error.** A count that
+ * runs past its own total is ordinary in real applications, and a bar that
+ * overflows its track or reports `aria-valuenow` above `aria-valuemax` is worse
+ * than one that reads as finished.
+ *
+ * Semantics are on the host through `ElementInternals`, the same as everywhere
+ * else: a `role` in the shadow root announces correctly and leaves the host
+ * anonymous to anything walking the light DOM, and a `role` written onto the
+ * host as an attribute is one a server's markup never had.
+ *
+ * The properties below are written by this component and read by whoever draws
+ * it. A consumer sets none of them: they carry a number this element computed
+ * and CSS cannot, which is what lets a stylesheet on this tier draw the thing
+ * without measuring anything itself.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category feedback
+ * @aliases Progress bar, Loading bar
+ * @documentation https://helix.fusion.dev/components/progress
+ *
+ * @csspart groove - The unfilled circle, under the ring's own sweep.
+ * @csspart indicator - The part of it that is done.
+ * @csspart track - The full length the work is measured against.
+ * @csspart value - The reading beside the bar, under `show-value`.
+ *
+ * @cssproperty --progress-fraction - The value as a fraction of the range, 0 to 1. Absent while indeterminate.
+ */
+let HelixHeadlessProgress = class HelixHeadlessProgress extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * Accessible name for what is in progress.
+         */
+        this.label = 'Progress';
+        /**
+         * Whether the work has a knowable end.
+         *
+         * On the headless tier rather than as a treatment, because it is
+         * semantics before it is a picture: a progressbar with no `aria-valuenow` is
+         * how the platform says "running, and nobody knows how far", and a reader on
+         * a screen reader is told that rather than being read a number that means
+         * nothing. `value` and `max` are ignored while it is set.
+         *
+         * Not `Loader`, which is the other thing this could be. A loader says the
+         * page is busy; a bar says a named piece of work is running, and keeps its
+         * place in the layout when the answer arrives and it becomes determinate.
+         */
+        this.indeterminate = false;
+        /**
+         * The total the work is measured against.
+         */
+        this.max = 100;
+        /**
+         * Whether the reading is shown beside the bar.
+         *
+         * The same name and shape `Slider` uses, because it is the same question:
+         * a control that holds a number can either show it or leave it to whatever is
+         * around it. Off by default, since most bars sit under a label that already
+         * says what is happening and a second number is noise.
+         *
+         * Nothing under `indeterminate`, where there is no reading to show: a percent
+         * that does not move is worse than none, and `valueText` is the property for
+         * saying "uploading" while the bar runs.
+         */
+        this.showValue = false;
+        /**
+         * What has been done so far, in the same units as `max`.
+         *
+         * Clamped between zero and `max` for both the fill and the announcement, so
+         * the two can never disagree about what is on screen.
+         */
+        this.value = 0;
+        /**
+         * A reading for the value, where the number alone does not say enough.
+         *
+         * "3 of 8 files" rather than "37". Announced instead of the percentage, and
+         * never instead of the value itself: `aria-valuenow` still carries the
+         * number, because assistive technology that ignores the text still has to
+         * report progress.
+         */
+        this.valueText = '';
+    }
+    /** What is done, as a fraction of the whole, between 0 and 1. */
+    get fraction() {
+        const max = this.max > 0 ? this.max : 100;
+        /* `|| 0` catches the value that is not a number.
+         *
+         * `undefined / 100` is `NaN`, `Math.min(Math.max(NaN, 0), 1)` is `NaN`, and
+         * `NaN` reached CSS as `scale: NaN`, which is an invalid value the
+         * declaration is dropped for: the bar fell back to its unscaled width and
+         * painted COMPLETE for a value nobody had given. `aria-valuenow` announced
+         * the string "NaN" beside it. Empty means nothing done, which is the only
+         * reading that is not a claim. */
+        return Math.min(Math.max(this.value / max, 0), 1) || 0;
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        hostAria(this.internals, { label: this.label, role: 'progressbar' });
+        /* The clamped value, not the given one, so what is announced is what is
+           drawn. Written as strings because that is what `ElementInternals` takes;
+           a number assigned here is stringified anyway and reads as though the
+           type were checked. */
+        this.internals.ariaValueMin = '0';
+        this.internals.ariaValueMax = String(this.max > 0 ? this.max : 100);
+        /* Absent, not zero. An omitted `aria-valuenow` is the platform's own signal
+           for indeterminate, and it is the only one: `aria-busy` says the element
+           is being updated, which is a different claim. Reporting 0 would announce
+           "0 percent" for work that is running, which is worse than saying nothing
+           because it is wrong rather than unknown. */
+        /* The clamped value itself, not the fraction multiplied back up.
+         *
+         * Dividing by `max` and then multiplying by it is a round trip through a
+         * float, and for roughly one integer pair in sixteen it does not come back:
+         * `1/3*3` is `0.9999999999999998`, which is what the accessibility tree
+         * carried and what a screen reader read out. Clamping the value directly
+         * says the same thing without the detour. */
+        const ceiling = this.max > 0 ? this.max : 100;
+        this.internals.ariaValueNow = this.indeterminate
+            ? null
+            : String(Math.min(Math.max(this.value || 0, 0), ceiling));
+        this.internals.ariaValueText = this.valueText || null;
+    }
+    render() {
+        /* A custom property rather than a width, so the styled tier decides what
+           the number means: a bar fills along it, and a ring would sweep. */
+        const fraction = this.indeterminate ? 1 : this.fraction;
+        /* Two circles and `pathLength`, which is what makes the arithmetic go away.
+         *
+         * Declaring the path 100 units long lets `stroke-dasharray` be written as
+         * the percentage itself, so nothing here or in the stylesheet needs the
+         * circumference, the radius or pi. The geometry is CSS as well: `r` and the
+         * stroke both read the ring's own custom properties, so a consumer changing
+         * the thickness moves the circle that carries it without the component
+         * recalculating anything.
+         *
+         * `aria-hidden`, because the host is the `progressbar` and carries the
+         * value. The drawing is a picture of what it already says. */
+        const ring = html `<svg part="track" aria-hidden="true">
+      <circle part="groove" />
+      <circle part="indicator" pathLength="100" style="--progress-fraction: ${fraction}" />
+    </svg>`;
+        return html `${this.shape === 'ring'
+            ? ring
+            : html `<div part="track">
+            <div part="indicator" style="--progress-fraction: ${fraction}"></div>
+          </div>`}
+      ${
+        /* `aria-hidden`, because the bar already reports this. The host carries
+           `role="progressbar"` with `aria-valuenow` and `aria-valuetext`, so a
+           readable copy of the same number is a second announcement of one
+           fact. It is here to be looked at, not to be read out. */
+        this.showValue && !this.indeterminate
+            ? html `<span part="value" aria-hidden="true"
+              >${this.valueText || `${Math.round(this.fraction * 100)}%`}</span
+            >`
+            : ''}`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessProgress.prototype, "label", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessProgress.prototype, "indeterminate", void 0);
+__decorate([
+    property({ type: Number })
+], HelixHeadlessProgress.prototype, "max", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessProgress.prototype, "shape", void 0);
+__decorate([
+    property({ attribute: 'show-value', reflect: true, type: Boolean })
+], HelixHeadlessProgress.prototype, "showValue", void 0);
+__decorate([
+    property({ type: Number })
+], HelixHeadlessProgress.prototype, "value", void 0);
+__decorate([
+    property({ attribute: 'value-text' })
+], HelixHeadlessProgress.prototype, "valueText", void 0);
+HelixHeadlessProgress = __decorate([
+    customElement('helix-headless-progress')
+], HelixHeadlessProgress);
+export { HelixHeadlessProgress };

package/dist/qr-code/index.d.ts

@@ -0,0 +1 @@
+export { HelixHeadlessQrCode, type QrCorrection } from './root/qr-code-root.js';

package/dist/qr-code/index.js

@@ -0,0 +1 @@
+export { HelixHeadlessQrCode } from './root/qr-code-root.js';

package/dist/qr-code/root/qr-code-root.d.ts

@@ -0,0 +1,93 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type TemplateResult } from 'lit';
+/** How much of the code can be lost and still read. */
+export type QrCorrection = 'H' | 'L' | 'M' | 'Q';
+/** How the modules are drawn. */
+export type QrStyle = 'dots' | 'rounded' | 'square';
+/**
+ * @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.
+ */
+export declare class HelixHeadlessQrCode extends HelixElement {
+    /**
+     * What the code encodes, which is usually a URL.
+     */
+    value: string;
+    /**
+     * 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.
+     */
+    label: string;
+    /**
+     * 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.
+     */
+    shape: QrStyle;
+    /**
+     * How much of the code can be lost and still read.
+     *
+     * `M` by default, which is the level almost every code in the world uses and
+     * costs about fifteen percent redundancy. `H` where a mark covers the center,
+     * chosen automatically when the slot is filled: it is the level that makes
+     * covering safe, and a consumer who fills the slot has said what they want
+     * without having to know that.
+     */
+    correction?: QrCorrection;
+    /** Whether anything is slotted into the middle. */
+    private logo;
+    /** The level actually used, which the slot can raise. */
+    private get level();
+    private renderCode;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-qr-code': HelixHeadlessQrCode;
+    }
+}