@fusion.dev/helix-headless 0.0.0-dev

package/dist/dialog/index.d.ts

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

package/dist/dialog/index.js

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

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

@@ -0,0 +1,185 @@
+import { CommandController, HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+declare const HelixHeadlessDialog_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
+/**
+ * @summary A modal window, on the platform's own dialog.
+ *
+ * @description
+ * A real `<dialog>` opened with `showModal()`, not a div with a role and a
+ * hand-built trap. The platform gives four things that are each a day's work to
+ * reimplement and easy to get subtly wrong: the top layer, so the dialog is
+ * above everything regardless of what `z-index` anyone else wrote; a real
+ * backdrop; Escape; and inert-behind, so the page underneath is not reachable
+ * by pointer, keyboard, or a screen reader's virtual cursor.
+ *
+ * **`open` drives `showModal()`, and every way it can close comes back through
+ * `requestOpen`.** A native dialog can close from three directions: the
+ * property, Escape, and a `<form method="dialog">` submit inside it. Left
+ * alone, two of those would shut the dialog while the consumer's state still
+ * said open, which is the bug that makes a modal impossible to reopen. Escape
+ * is intercepted and routed through the request, so `preventDefault()` on the
+ * `helix-before-close` refuses it; a close that happens anyway is reflected back.
+ *
+ * **Nothing here traps focus.** `showModal()` does it, and better: `inert` on
+ * the rest of the document is something no JavaScript trap can achieve.
+ * `FocusTrapController` stays for the surfaces that are not modal.
+ *
+ * The regions are bare slots rather than wrappers, for the reason the card's
+ * are: an unassigned `<slot>` is `display: contents` and generates no box, so a
+ * dialog with no footer has no empty band where one would be.
+ *
+ * Opened declaratively with the platform's invoker attributes:
+ *
+ * ```html
+ * <helix-button commandfor="confirm" command="--show">Delete…</helix-button>
+ * <helix-dialog id="confirm">…</helix-dialog>
+ * ```
+ *
+ * `--show`, `--close` and `--toggle`. Custom commands rather than the built-in
+ * `show-modal`, because those are defined against native elements and do
+ * nothing when pointed at a custom one.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category overlays
+ * @aliases Modal, Lightbox, Sheet
+ * @documentation https://helix.fusion.dev/components/dialog
+ *
+ * @slot - The dialog's content.
+ * @slot footer - The actions.
+ * @slot header - The title, and anything beside it.
+ * @slot icon - A single mark above the title, for a dialog that warns.
+ *
+ * @event {Event} close - Relayed, because the platform's own does not escape.
+ * @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 dialog - The native dialog element.
+ */
+export declare class HelixHeadlessDialog extends HelixHeadlessDialog_base {
+    /**
+     * Accessible name for the dialog.
+     */
+    label: string;
+    /**
+     * Whether Escape can close it.
+     *
+     * Off for a dialog that must be answered. It does not disable the close
+     * control a consumer slots in: refusing to be dismissed is not the same as
+     * refusing to be closed, and a dialog with no way out at all is a trap.
+     *
+     * Escape *and* a press on the backdrop, which it now genuinely means. The
+     * sentence said both for a long time while nothing listened for a backdrop
+     * press, so it promised a behavior a consumer would have written their
+     * markup around; the fix then was to narrow the sentence, and the fix now is
+     * to build the half that was missing.
+     *
+     * A persistent dialog does not ignore that press. It answers it: see
+     * `refuse`, which is the only way a dialog that will not be dismissed can say
+     * so at the moment a reader asks.
+     */
+    persistent: boolean;
+    protected readonly commands: CommandController;
+    /**
+     * Which close requests the browser answers on its own.
+     *
+     * `<dialog closedby>`, forwarded, and safe to forward because every path it
+     * opens still comes back through this element: a close request fires `cancel`
+     * first, `handleCancel` prevents it, and `requestOpen` decides. So
+     * `closedby="any"` gains light dismiss without giving up the refusal, which is
+     * the property this component exists to keep.
+     *
+     * Absent by default, which is the platform's `auto` and this library's rule
+     * that a resting value is an attribute's absence.
+     */
+    closedBy?: 'any' | 'closerequest' | 'none';
+    /**
+     * What the dialog closed with, the way `<dialog>` reports it.
+     *
+     * **The whole point of a `<dialog>` returning a value is lost behind a shadow
+     * boundary**, which is where this one is: the platform's contract is
+     * `close(value)` then read `returnValue`, and a consumer could do neither
+     * because `querySelector` does not reach the element. A confirmation asking
+     * which button was pressed is the ordinary case and had no answer.
+     *
+     * Held here as well as on the element, so a value set before the first render
+     * survives to it and a consumer reading one back gets what they wrote.
+     */
+    get returnValue(): string;
+    set returnValue(value: string);
+    /** What a value set before the element existed is kept in. */
+    private returned;
+    /** The native dialog, or nothing where there is no DOM to hold one. */
+    private get dialog();
+    /** Moves focus into the dialog and makes the rest of the page inert. */
+    show(): void;
+    /**
+     * Asks to close, which a consumer may refuse.
+     *
+     * Takes what the dialog closed with, the way `<dialog>.close(value)` does, so
+     * the button that dismissed it can say which one it was. Set before the
+     * request rather than after, because a `close` listener reads `returnValue`
+     * and would otherwise read the previous one.
+     *
+     * Not set where the request is refused, since nothing closed and a value
+     * saying it did would outlive the refusal.
+     */
+    close(returnValue?: string): void;
+    /**
+     * Escape, intercepted so it is a request rather than an act.
+     *
+     * The native `cancel` event fires before the dialog closes, so preventing it
+     * leaves the dialog open and lets `requestOpen` decide. Without this a reader
+     * pressing Escape would close a dialog its consumer had said was open, and
+     * the two would disagree until something else moved.
+     */
+    private readonly handleCancel;
+    /**
+     * A close that happened anyway, reflected back.
+     *
+     * `<form method="dialog">` closes the dialog directly and there is no event
+     * to prevent. Rather than fight it, the state follows: the dialog is shut, so
+     * saying otherwise would be a lie the next `showModal()` would trip over.
+     */
+    private readonly handleClose;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    /** Opens once anything slotted has had its first render. See `updated`. */
+    private openWhenSlotted;
+    /**
+     * A press on the backdrop, which lands on the dialog element itself.
+     *
+     * **The target alone is not enough here, where it is for `Drawer`.** A modal
+     * `<dialog>` attributes backdrop clicks to itself, which is the usual trick,
+     * and this panel also carries `--dialog-padding` of padding: a press in that
+     * padding has the same target as a press on the backdrop, so the trick alone
+     * closes a dialog when a reader clicks just inside its own edge. The drawer
+     * escapes that because its panel is flush against the window and its content
+     * fills it. So the point is compared against the panel's box.
+     */
+    private readonly handleBackdrop;
+    /**
+     * Says no to a dismissal, by moving.
+     *
+     * A persistent dialog that ignores a press on the backdrop is
+     * indistinguishable from one that did not notice, and a reader's next move is
+     * to press again harder. A short swell and settle is the smallest thing that
+     * reads as "I heard you, and no": it is the same gesture a native alert makes
+     * on macOS and the one every reader has already been taught.
+     *
+     * An attribute for the length of the animation rather than a class, cleared
+     * on `animationend`, so the styled tier decides what refusing looks like and
+     * this decides only when it happens. Removed first so a second press
+     * restarts it: without that, pressing twice does nothing the second time,
+     * which is the impression the whole thing exists to avoid.
+     */
+    private refuse;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-dialog': HelixHeadlessDialog;
+    }
+}
+export {};

package/dist/dialog/root/dialog-root.js

@@ -0,0 +1,319 @@
+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 { CommandController, customElement, HelixElement, hostAria, MixinControllerOpen, } from '@fusion.dev/helix-core';
+import { html, nothing } from 'lit';
+import { property } from 'lit/decorators.js';
+/**
+ * @summary A modal window, on the platform's own dialog.
+ *
+ * @description
+ * A real `<dialog>` opened with `showModal()`, not a div with a role and a
+ * hand-built trap. The platform gives four things that are each a day's work to
+ * reimplement and easy to get subtly wrong: the top layer, so the dialog is
+ * above everything regardless of what `z-index` anyone else wrote; a real
+ * backdrop; Escape; and inert-behind, so the page underneath is not reachable
+ * by pointer, keyboard, or a screen reader's virtual cursor.
+ *
+ * **`open` drives `showModal()`, and every way it can close comes back through
+ * `requestOpen`.** A native dialog can close from three directions: the
+ * property, Escape, and a `<form method="dialog">` submit inside it. Left
+ * alone, two of those would shut the dialog while the consumer's state still
+ * said open, which is the bug that makes a modal impossible to reopen. Escape
+ * is intercepted and routed through the request, so `preventDefault()` on the
+ * `helix-before-close` refuses it; a close that happens anyway is reflected back.
+ *
+ * **Nothing here traps focus.** `showModal()` does it, and better: `inert` on
+ * the rest of the document is something no JavaScript trap can achieve.
+ * `FocusTrapController` stays for the surfaces that are not modal.
+ *
+ * The regions are bare slots rather than wrappers, for the reason the card's
+ * are: an unassigned `<slot>` is `display: contents` and generates no box, so a
+ * dialog with no footer has no empty band where one would be.
+ *
+ * Opened declaratively with the platform's invoker attributes:
+ *
+ * ```html
+ * <helix-button commandfor="confirm" command="--show">Delete…</helix-button>
+ * <helix-dialog id="confirm">…</helix-dialog>
+ * ```
+ *
+ * `--show`, `--close` and `--toggle`. Custom commands rather than the built-in
+ * `show-modal`, because those are defined against native elements and do
+ * nothing when pointed at a custom one.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category overlays
+ * @aliases Modal, Lightbox, Sheet
+ * @documentation https://helix.fusion.dev/components/dialog
+ *
+ * @slot - The dialog's content.
+ * @slot footer - The actions.
+ * @slot header - The title, and anything beside it.
+ * @slot icon - A single mark above the title, for a dialog that warns.
+ *
+ * @event {Event} close - Relayed, because the platform's own does not escape.
+ * @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 dialog - The native dialog element.
+ */
+let HelixHeadlessDialog = class HelixHeadlessDialog extends MixinControllerOpen(HelixElement) {
+    constructor() {
+        super(...arguments);
+        /**
+         * Accessible name for the dialog.
+         */
+        this.label = '';
+        /**
+         * Whether Escape can close it.
+         *
+         * Off for a dialog that must be answered. It does not disable the close
+         * control a consumer slots in: refusing to be dismissed is not the same as
+         * refusing to be closed, and a dialog with no way out at all is a trap.
+         *
+         * Escape *and* a press on the backdrop, which it now genuinely means. The
+         * sentence said both for a long time while nothing listened for a backdrop
+         * press, so it promised a behavior a consumer would have written their
+         * markup around; the fix then was to narrow the sentence, and the fix now is
+         * to build the half that was missing.
+         *
+         * A persistent dialog does not ignore that press. It answers it: see
+         * `refuse`, which is the only way a dialog that will not be dismissed can say
+         * so at the moment a reader asks.
+         */
+        this.persistent = false;
+        /* Opened and closed from anywhere on the page, without a line of script:
+           `<helix-button commandfor="…" command="--show">`. See `CommandController`
+           for why this is the platform's invoker rather than a `data-` recipe. */
+        this.commands = new CommandController(this, {
+            commands: {
+                '--close': () => this.close(),
+                '--show': () => this.show(),
+                '--toggle': () => this.toggleOpen(),
+            },
+        });
+        /** What a value set before the element existed is kept in. */
+        this.returned = '';
+        /**
+         * Escape, intercepted so it is a request rather than an act.
+         *
+         * The native `cancel` event fires before the dialog closes, so preventing it
+         * leaves the dialog open and lets `requestOpen` decide. Without this a reader
+         * pressing Escape would close a dialog its consumer had said was open, and
+         * the two would disagree until something else moved.
+         */
+        this.handleCancel = (event) => {
+            event.preventDefault();
+            if (this.persistent) {
+                return;
+            }
+            this.requestOpen(false);
+        };
+        /**
+         * A close that happened anyway, reflected back.
+         *
+         * `<form method="dialog">` closes the dialog directly and there is no event
+         * to prevent. Rather than fight it, the state follows: the dialog is shut, so
+         * saying otherwise would be a lie the next `showModal()` would trip over.
+         */
+        this.handleClose = (event) => {
+            if (this.open) {
+                this.requestOpen(false);
+            }
+            /* And under the platform's own name, from the host. `close` on a `<dialog>`
+               neither bubbles nor is composed, so the one the browser just fired reaches
+               nobody outside this shadow root, which is the same reason `Avatar` relays
+               `load`. Announced after the state has moved, so a consumer binding
+               `onClose` reads a dialog that is already shut.
+        
+               `cancel` is deliberately not relayed. `handleCancel` prevents it so that
+               Escape is a request rather than an act, so the native one never completes:
+               relaying it would announce a dismissal that was refused. See 296. */
+            this.relayNativeEvent(event);
+        };
+        /**
+         * A press on the backdrop, which lands on the dialog element itself.
+         *
+         * **The target alone is not enough here, where it is for `Drawer`.** A modal
+         * `<dialog>` attributes backdrop clicks to itself, which is the usual trick,
+         * and this panel also carries `--dialog-padding` of padding: a press in that
+         * padding has the same target as a press on the backdrop, so the trick alone
+         * closes a dialog when a reader clicks just inside its own edge. The drawer
+         * escapes that because its panel is flush against the window and its content
+         * fills it. So the point is compared against the panel's box.
+         */
+        this.handleBackdrop = (event) => {
+            const panel = this.dialog;
+            if (!panel || event.target !== panel) {
+                return;
+            }
+            const box = panel.getBoundingClientRect();
+            if (event.clientX >= box.left &&
+                event.clientX <= box.right &&
+                event.clientY >= box.top &&
+                event.clientY <= box.bottom) {
+                return;
+            }
+            if (this.persistent) {
+                this.refuse();
+                return;
+            }
+            this.requestOpen(false);
+        };
+    }
+    /**
+     * What the dialog closed with, the way `<dialog>` reports it.
+     *
+     * **The whole point of a `<dialog>` returning a value is lost behind a shadow
+     * boundary**, which is where this one is: the platform's contract is
+     * `close(value)` then read `returnValue`, and a consumer could do neither
+     * because `querySelector` does not reach the element. A confirmation asking
+     * which button was pressed is the ordinary case and had no answer.
+     *
+     * Held here as well as on the element, so a value set before the first render
+     * survives to it and a consumer reading one back gets what they wrote.
+     */
+    get returnValue() {
+        return this.dialog?.returnValue ?? this.returned;
+    }
+    set returnValue(value) {
+        this.returned = value;
+        const dialog = this.dialog;
+        if (dialog) {
+            dialog.returnValue = value;
+        }
+    }
+    /** The native dialog, or nothing where there is no DOM to hold one. */
+    get dialog() {
+        return this.renderRoot?.querySelector('dialog') ?? null;
+    }
+    /** Moves focus into the dialog and makes the rest of the page inert. */
+    show() {
+        this.requestOpen(true);
+    }
+    /**
+     * Asks to close, which a consumer may refuse.
+     *
+     * Takes what the dialog closed with, the way `<dialog>.close(value)` does, so
+     * the button that dismissed it can say which one it was. Set before the
+     * request rather than after, because a `close` listener reads `returnValue`
+     * and would otherwise read the previous one.
+     *
+     * Not set where the request is refused, since nothing closed and a value
+     * saying it did would outlive the refusal.
+     */
+    close(returnValue) {
+        const previous = this.returnValue;
+        if (returnValue !== undefined) {
+            this.returnValue = returnValue;
+        }
+        if (!this.requestOpen(false) && returnValue !== undefined) {
+            this.returnValue = previous;
+        }
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        hostAria(this.internals, { label: this.label });
+    }
+    updated(changed) {
+        super.updated(changed);
+        /* After render, because the element has to exist to be opened, and only on
+           a difference: `showModal()` on an open dialog throws, and `close()` on a
+           shut one fires a second `close` event. */
+        const dialog = this.dialog;
+        if (!dialog) {
+            return;
+        }
+        if (this.open && !dialog.open) {
+            /* **After the slotted elements have rendered, or the modal focuses
+               itself.** `showModal()` moves focus to the first focusable descendant,
+               and a custom element that has not rendered its shadow yet has none: the
+               browser falls back to the dialog. Markup never showed this, the parser
+               having upgraded everything before this element's first update, and
+               React does: it creates and connects the dialog before the chat inside
+               it has rendered, so a `default-open` dialog opened with focus on the
+               dialog rather than on the field, measured against the markup twin.
+      
+               Awaited only for children that are Lit elements and only on the way
+               open; a dialog with no such children resolves on the same microtask and
+               is unchanged. */
+            void this.openWhenSlotted(dialog);
+        }
+        else if (!this.open && dialog.open) {
+            dialog.close();
+        }
+    }
+    /** Opens once anything slotted has had its first render. See `updated`. */
+    async openWhenSlotted(dialog) {
+        await Promise.all([...this.children]
+            .map((one) => one.updateComplete)
+            .filter((one) => one instanceof Promise));
+        /* Re-checked, because both facts can have moved while that resolved. */
+        if (this.open && !dialog.open && this.isConnected) {
+            dialog.showModal();
+        }
+    }
+    /**
+     * Says no to a dismissal, by moving.
+     *
+     * A persistent dialog that ignores a press on the backdrop is
+     * indistinguishable from one that did not notice, and a reader's next move is
+     * to press again harder. A short swell and settle is the smallest thing that
+     * reads as "I heard you, and no": it is the same gesture a native alert makes
+     * on macOS and the one every reader has already been taught.
+     *
+     * An attribute for the length of the animation rather than a class, cleared
+     * on `animationend`, so the styled tier decides what refusing looks like and
+     * this decides only when it happens. Removed first so a second press
+     * restarts it: without that, pressing twice does nothing the second time,
+     * which is the impression the whole thing exists to avoid.
+     */
+    refuse() {
+        const panel = this.dialog;
+        if (!panel) {
+            return;
+        }
+        panel.removeAttribute('data-refused');
+        // Read forces the removal to land before the attribute goes back on, or the
+        // two happen in one frame and the animation never restarts.
+        void panel.offsetWidth;
+        panel.setAttribute('data-refused', '');
+        panel.addEventListener('animationend', () => panel.removeAttribute('data-refused'), {
+            once: true,
+        });
+    }
+    render() {
+        return html `<dialog
+      part="dialog"
+      closedby=${this.closedBy ?? nothing}
+      aria-label=${this.label || 'Dialog'}
+      @cancel=${this.handleCancel}
+      @click=${this.handleBackdrop}
+      @close=${this.handleClose}
+    >
+      <slot name="icon"></slot>
+      <slot name="header"></slot>
+      <slot></slot>
+      <slot name="footer"></slot>
+    </dialog>`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessDialog.prototype, "label", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessDialog.prototype, "persistent", void 0);
+__decorate([
+    property({ attribute: 'closedby', reflect: true })
+], HelixHeadlessDialog.prototype, "closedBy", void 0);
+HelixHeadlessDialog = __decorate([
+    customElement('helix-headless-dialog')
+], HelixHeadlessDialog);
+export { HelixHeadlessDialog };

package/dist/divider/index.d.ts

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

package/dist/divider/index.js

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

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

@@ -0,0 +1,68 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @summary Separates content into groups with a rule.
+ *
+ * @description
+ * The separator role lives on the rule inside the shadow root rather than on
+ * the host. A role does not need to cross the shadow boundary the way an IDREF
+ * does, and putting it on the rendered element means the semantics are in the
+ * server's markup with no attribute written during a lifecycle the server never
+ * runs.
+ *
+ * Use `orientation="vertical"` between items on one line, such as inside a
+ * toolbar. A vertical divider stretches to its flex parent rather than setting
+ * a height of its own.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category layout
+ * @aliases Separator, Rule
+ * @documentation https://helix.fusion.dev/components/divider
+ *
+ * @slot - Content set into the rule, such as the word between two sections.
+ *
+ * @csspart content - What is set into it.
+ * @csspart line - The rule itself, or each half of it where something is set in.
+ */
+export declare class HelixHeadlessDivider extends HelixElement {
+    /**
+     * Which way the rule runs.
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Whether the rule is announced as a separator.
+     *
+     * Off by default, and out of the accessibility tree. Most rules on a page
+     * separate nothing: they underline a heading or close a section that space
+     * had already closed, and announcing every one as a separator is noise a
+     * screen-reader user has to walk past.
+     *
+     * An opt-in, not a `decorative` opt-out, because a boolean attribute cannot
+     * be turned off: `decorative="false"` parses as `true`, which would put the
+     * quiet default out of reach from HTML and leave it settable only as a
+     * property. An opt-in is absent by default, which every reflected property
+     * here has to be.
+     */
+    announced: boolean;
+    /**
+     * Marks the middle region when nothing has been set into it.
+     *
+     * A divider with no content has to be one continuous line, and the space
+     * either side of the content is what would break it. `:empty` cannot answer
+     * this and neither can `:host(:has(...))`, which is invalid CSS dropped at
+     * parse time: `check:selectors` caught exactly that rule here, written in
+     * this file, by an author who had already read the note saying so.
+     *
+     * On the region inside the shadow root rather than on the host, because an
+     * attribute written onto the host is a change to markup the consumer rendered.
+     */
+    private markEmpty;
+    protected updated(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-divider': HelixHeadlessDivider;
+    }
+}