@fusion.dev/helix-headless 0.100.0 → 0.101.0

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

@@ -20,7 +20,7 @@ declare const HelixHeadlessDialog_base: (new (...args: any[]) => import("@fusion
  * @since 0.1.0
  * @status stable
  * @category overlays
- * @aliases Modal, Lightbox, Sheet
+ * @aliases Modal, Sheet
  * @documentation https://fusion.dev/helix/components/dialog
  *
  * @slot - The dialog's content.

package/dist/element-events.generated.js

@@ -76,6 +76,14 @@ registerElementEvents({
     'helix-headless-image': ['error', 'load'],
     'helix-headless-input': ['change', 'helix-before-change', 'input'],
     'helix-headless-kbd': ['helix-shortcut'],
+    'helix-headless-lightbox': [
+        'close',
+        'helix-activate',
+        'helix-before-activate',
+        'helix-before-close',
+        'helix-before-open',
+        'toggle',
+    ],
     'helix-headless-listbox': ['change', 'helix-before-change', 'helix-filter', 'input'],
     'helix-headless-megamenu': ['helix-before-close', 'helix-before-open', 'toggle'],
     'helix-headless-menu': ['helix-before-close', 'helix-before-open', 'helix-select', 'toggle'],

package/dist/index.d.ts

@@ -53,6 +53,7 @@ export * from './image/index.js';
 export * from './input/index.js';
 export * from './kbd/index.js';
 export * from './legend/index.js';
+export * from './lightbox/index.js';
 export * from './line-chart/index.js';
 export * from './list/index.js';
 export * from './listbox/index.js';

package/dist/index.js

@@ -44,6 +44,7 @@ export * from './image/index.js';
 export * from './input/index.js';
 export * from './kbd/index.js';
 export * from './legend/index.js';
+export * from './lightbox/index.js';
 export * from './line-chart/index.js';
 export * from './list/index.js';
 export * from './listbox/index.js';

package/dist/lightbox/index.d.ts

@@ -0,0 +1,2 @@
+export { HelixHeadlessLightboxItem } from './item/lightbox-item.js';
+export { HelixHeadlessLightbox } from './root/lightbox-root.js';

package/dist/lightbox/index.js

@@ -0,0 +1,2 @@
+export { HelixHeadlessLightboxItem } from './item/lightbox-item.js';
+export { HelixHeadlessLightbox } from './root/lightbox-root.js';

package/dist/lightbox/item/lightbox-item.d.ts

@@ -0,0 +1,60 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @summary One thing a lightbox can show.
+ *
+ * @description
+ * A wrapper around whatever the consumer opened, which is the whole of what it
+ * is: a picture, a frame of video, a chart. The family shows one at a time and
+ * this is how it says which, so the content stays the consumer's and the
+ * arithmetic stays the root's.
+ *
+ * Hidden rather than unmounted while another item is current, for the reason
+ * `TabPanel` gives: what is in the markup is what a crawler reads and what a
+ * server sent, and an `<img>` that has already decoded does not decode again
+ * when the reader walks back to it.
+ *
+ * @since 0.100.0
+ * @status stable
+ * @category media
+ * @aliases LightboxSlide, GalleryItem
+ * @documentation https://fusion.dev/helix/components/lightbox
+ *
+ * @slot - What is being shown.
+ * @slot description - A line under it saying what it is.
+ *
+ * @csspart item - The box the content is shown in.
+ *
+ * @cssstate current - While this is the item the lightbox is showing.
+ */
+export declare class HelixHeadlessLightboxItem extends HelixElement {
+    /**
+     * Whether this is the one being shown.
+     *
+     * Written by the root, which is the only thing that sees the set.
+     */
+    current: boolean;
+    /**
+     * What this item is called, for the reading that says where the reader is.
+     */
+    label: string;
+    /**
+     * What names this item, and what `active` on the root is compared against.
+     */
+    value: string;
+    /**
+     * Mirrors the shown state where a stylesheet can select on it.
+     *
+     * A custom state and never a reflected attribute, for the reason `TabPanel`
+     * writes out at length: the parent writes this, so reflecting it would put
+     * the element's own bookkeeping into markup a consumer never sent, which is a
+     * hydration mismatch in React and a choice nobody made in a serialized tree.
+     */
+    protected willUpdate(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-lightbox-item': HelixHeadlessLightboxItem;
+    }
+}

package/dist/lightbox/item/lightbox-item.js

@@ -0,0 +1,45 @@
+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';
+let HelixHeadlessLightboxItem = class HelixHeadlessLightboxItem extends HelixElement {
+    constructor() {
+        super(...arguments);
+        this.current = false;
+        this.label = '';
+        this.value = '';
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        this.toggleState('current', this.current);
+    }
+    render() {
+        return html `<div
+      part="item"
+      role="group"
+      aria-label=${this.label || nothing}
+      ?hidden=${!this.current}
+    >
+      <slot></slot>
+      <slot name="description"></slot>
+    </div>`;
+    }
+};
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessLightboxItem.prototype, "current", void 0);
+__decorate([
+    property()
+], HelixHeadlessLightboxItem.prototype, "label", void 0);
+__decorate([
+    property()
+], HelixHeadlessLightboxItem.prototype, "value", void 0);
+HelixHeadlessLightboxItem = __decorate([
+    customElement('helix-headless-lightbox-item')
+], HelixHeadlessLightboxItem);
+export { HelixHeadlessLightboxItem };

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

@@ -0,0 +1,176 @@
+import { CommandController, HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+declare const HelixHeadlessLightbox_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerActiveInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
+/**
+ * @summary A viewer that opens one thing over the page.
+ *
+ * @description
+ * **A lightbox is chrome around a picture rather than a picture.** It draws
+ * nothing of its own: what it shows is whatever the consumer opened, so this
+ * earns its place on the frame, the keyboard and the reading that says where in
+ * the set the reader is.
+ *
+ * **The modal half is the platform's.** A real `<dialog>` opened with
+ * `showModal()` brings the top layer, a backdrop, Escape and `inert` behind it,
+ * and this repository has already removed one hand-written focus trap for being
+ * worse than that: `inert` on the rest of the document is something no
+ * JavaScript trap can achieve. Every way it can close comes back through
+ * `requestOpen`, which is what `Dialog` and `Drawer` both do and for the reason
+ * they both give.
+ *
+ * **The set is this component's own and not `Carousel`'s.** A carousel is a
+ * track: a scroller with snap points, per-view arithmetic and stops it can rest
+ * between. A lightbox shows one thing at a time and has no track, so what it
+ * needs is which item is current, which is `active` and the same pair `Tabs`
+ * uses. The arrow keys move the picture under a reader whose focus stays in the
+ * dialog, which is also why `KeyboardNavigationController` is not the right
+ * tool: that one moves focus between focusable items, and these are pictures.
+ *
+ * **Chrome hides while the reader is still**, on `IdleController`, and comes
+ * back on a pointer move or a focus. `fullscreen` is `FullscreenController`, the
+ * same pair `Video` holds and the only two it shares.
+ *
+ * @since 0.100.0
+ * @status stable
+ * @category media
+ * @aliases Photo viewer, Image viewer, Gallery overlay
+ * @documentation https://fusion.dev/helix/components/lightbox
+ *
+ * @slot - The items, which are `<helix-headless-lightbox-item>` elements.
+ * @slot footer - Chrome below the item, such as a counter or a thumbnail strip.
+ * @slot header - Chrome above the item, such as a title and a close button.
+ *
+ * @event {Event} close - Relayed, because the platform's own does not escape.
+ * @event {HelixActivateEvent} helix-activate - Fired once the shown item has moved, so the element already holds it.
+ * @event {HelixBeforeActivateEvent} helix-before-activate - Fired before the shown item changes, and cancelable. The only way to refuse one.
+ * @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.
+ * @csspart live - The region that says which item is shown.
+ * @csspart viewport - The box the current item is shown in.
+ *
+ * @cssstate fullscreen - While the viewer fills the screen.
+ * @cssstate idle - While the reader has been still long enough to hide the chrome.
+ * @cssstate open - While the viewer is open.
+ */
+export declare class HelixHeadlessLightbox extends HelixHeadlessLightbox_base {
+    /**
+     * How long the reader may be still before the chrome hides, in milliseconds.
+     *
+     * Zero keeps it up, which is what a viewer with a caption worth reading
+     * wants. The wait is only ever about idling: whether anything else should
+     * keep the chrome up is the consumer's to decide with this.
+     */
+    idleDelay: number;
+    /**
+     * Accessible name for the viewer.
+     */
+    label: string;
+    /**
+     * Whether walking past the end comes back to the beginning.
+     */
+    loop: boolean;
+    /**
+     * The reading that says where in the set the reader is, with `{index}` and
+     * `{count}` filled in.
+     *
+     * Announced rather than only drawn, because the picture changing under a
+     * reader who cannot see it is otherwise silent. A consumer who has their own
+     * counter in the chrome can empty this and say it themselves.
+     */
+    statusLabel: string;
+    /** Whether the reader has been still long enough to hide the chrome. */
+    private resting;
+    /** Whether the viewer is filling the screen. */
+    private filled;
+    /** What the live region is currently saying. */
+    private announcement;
+    private readonly fullscreen;
+    private readonly idle;
+    protected readonly commands: CommandController;
+    /** The items, read from the host so the server has them too. */
+    private get items();
+    /** The native dialog, or nothing where there is no DOM to hold one. */
+    private get dialog();
+    /** Opens the viewer, which makes the rest of the page inert. */
+    show(): void;
+    /** Asks to close, which a consumer may refuse. */
+    close(): void;
+    /** Shows the next item, or the first where it is past the end and looping. */
+    next(): void;
+    /** Shows the previous item, or the last where it is past the start and looping. */
+    previous(): void;
+    /** Fills the screen with the viewer, or comes back. */
+    toggleFullscreen(): void;
+    /**
+     * Moves the shown item, through `requestActive` so a consumer can refuse.
+     *
+     * Clamped rather than wrapped by default: a viewer that silently returns to
+     * the first picture tells a reader they have seen everything only if they
+     * were counting, and `loop` is how a consumer asks for the other reading.
+     */
+    private step;
+    /**
+     * Escape, intercepted so it is a request rather than an act.
+     *
+     * The native `cancel` fires before the dialog closes, so preventing it leaves
+     * the viewer open and lets `requestOpen` decide. Without this a reader
+     * pressing Escape would close a viewer 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 and relayed.
+     *
+     * `close` on a `<dialog>` neither bubbles nor is composed, so the one the
+     * browser fires reaches nobody outside this shadow root.
+     */
+    private readonly handleClose;
+    /**
+     * The arrow keys, which move the picture rather than the focus.
+     *
+     * `inlineStep` rather than a comparison against `ArrowLeft`, so the reader on
+     * a right-to-left page gets the next picture from the key that points the way
+     * their set runs. Up and down are bound as well, the set having one axis and
+     * a reader having no way to know which one this component thinks it is.
+     */
+    private readonly handleKeydown;
+    /** Home and End, which are an index rather than a step. */
+    private toEnd;
+    /**
+     * A press on the backdrop, which lands on the dialog element itself.
+     *
+     * The point is compared against the panel's box rather than trusting the
+     * target alone, for the reason `Dialog` gives: a modal `<dialog>` attributes
+     * backdrop presses to itself, so any padding the styled tier gives the panel
+     * is a strip where a press on the panel looks like a press outside it.
+     */
+    private readonly handleBackdrop;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    /**
+     * Tells each item whether it is the one being shown.
+     *
+     * `resolveActiveItem` rather than a comparison, so a set whose `active` names
+     * nothing still shows something: every set before its consumer has chosen, and
+     * every set whose current item has just been removed.
+     */
+    private mark;
+    /**
+     * Says where the reader is, once the reader has moved.
+     *
+     * Empty until then, because a live region populated as it enters the document
+     * announces itself on arrival, which for a component that upgrades on load is
+     * every page load.
+     */
+    private say;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-lightbox': HelixHeadlessLightbox;
+    }
+}
+export {};

package/dist/lightbox/root/lightbox-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 { CommandController, customElement, FullscreenController, HelixElement, hostAria, IdleController, inlineStep, MixinControllerActive, MixinControllerOpen, resolveActiveItem, } from '@fusion.dev/helix-core';
+import { html, nothing } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { HelixHeadlessLightboxItem } from '../item/lightbox-item.js';
+const fill = (template, index, count) => template.replaceAll('{index}', String(index)).replaceAll('{count}', String(count));
+let HelixHeadlessLightbox = class HelixHeadlessLightbox extends MixinControllerActive(MixinControllerOpen(HelixElement)) {
+    constructor() {
+        super(...arguments);
+        this.idleDelay = 0;
+        this.label = '';
+        this.loop = false;
+        this.statusLabel = '{index} of {count}';
+        this.resting = false;
+        this.filled = false;
+        this.announcement = '';
+        this.fullscreen = new FullscreenController(this, (full) => {
+            this.filled = full;
+        });
+        this.idle = new IdleController(this, () => this.idleDelay, (resting) => {
+            this.resting = resting;
+        });
+        this.commands = new CommandController(this, {
+            commands: {
+                '--close': () => this.close(),
+                '--fullscreen': () => this.toggleFullscreen(),
+                '--next': () => this.next(),
+                '--previous': () => this.previous(),
+                '--show': () => this.show(),
+                '--toggle': () => this.toggleOpen(),
+            },
+        });
+        this.handleCancel = (event) => {
+            event.preventDefault();
+            this.requestOpen(false);
+        };
+        this.handleClose = (event) => {
+            if (this.open) {
+                this.requestOpen(false);
+            }
+            this.relayNativeEvent(event);
+        };
+        this.handleKeydown = (event) => {
+            const along = inlineStep(this, event.key);
+            if (along === 1 || event.key === 'ArrowDown') {
+                event.preventDefault();
+                this.next();
+            }
+            else if (along === -1 || event.key === 'ArrowUp') {
+                event.preventDefault();
+                this.previous();
+            }
+            else if (event.key === 'Home') {
+                event.preventDefault();
+                this.toEnd(0);
+            }
+            else if (event.key === 'End') {
+                event.preventDefault();
+                this.toEnd(this.items.length - 1);
+            }
+        };
+        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;
+            }
+            this.requestOpen(false);
+        };
+    }
+    get items() {
+        return [...this.children].filter((child) => child instanceof HelixHeadlessLightboxItem);
+    }
+    get dialog() {
+        return this.renderRoot?.querySelector('dialog') ?? null;
+    }
+    show() {
+        this.requestOpen(true);
+    }
+    close() {
+        this.requestOpen(false);
+    }
+    next() {
+        this.step(1);
+    }
+    previous() {
+        this.step(-1);
+    }
+    toggleFullscreen() {
+        void this.fullscreen.toggle();
+    }
+    step(by) {
+        const items = this.items;
+        if (items.length === 0) {
+            return;
+        }
+        const current = items.findIndex((item) => item.value === this.active);
+        const from = current === -1 ? 0 : current;
+        const last = items.length - 1;
+        const next = this.loop
+            ? (from + by + items.length) % items.length
+            : Math.min(Math.max(from + by, 0), last);
+        const target = items[next];
+        if (target && target.value !== this.active) {
+            this.requestActive(target.value);
+        }
+    }
+    toEnd(at) {
+        const target = this.items[at];
+        if (target && target.value !== this.active) {
+            this.requestActive(target.value);
+        }
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        hostAria(this.internals, { label: this.label });
+        this.toggleState('fullscreen', this.filled);
+        this.toggleState('idle', this.resting);
+        this.say(changed);
+    }
+    updated(changed) {
+        super.updated(changed);
+        this.mark();
+        const dialog = this.dialog;
+        if (!dialog) {
+            return;
+        }
+        if (this.open && !dialog.open) {
+            dialog.showModal();
+            this.idle.stir();
+        }
+        else if (!this.open && dialog.open) {
+            dialog.close();
+        }
+    }
+    mark() {
+        const items = this.items;
+        const current = resolveActiveItem(this.active, items);
+        for (const item of items) {
+            item.current = item === current;
+        }
+    }
+    say(changed) {
+        if (!changed.has('active') && !changed.has('open')) {
+            return;
+        }
+        if (!this.open || this.statusLabel === '') {
+            this.announcement = '';
+            return;
+        }
+        const items = this.items;
+        const current = resolveActiveItem(this.active, items);
+        const at = current ? items.indexOf(current) : -1;
+        this.announcement = at === -1 ? '' : fill(this.statusLabel, at + 1, items.length);
+    }
+    render() {
+        return html `<dialog
+      part="dialog"
+      aria-label=${this.label || 'Lightbox'}
+      @cancel=${this.handleCancel}
+      @click=${this.handleBackdrop}
+      @close=${this.handleClose}
+      @focusin=${this.idle.stir}
+      @keydown=${this.handleKeydown}
+      @pointerleave=${this.idle.leave}
+      @pointermove=${this.idle.stir}
+    >
+      <slot name="header"></slot>
+      <div part="viewport">
+        <slot></slot>
+      </div>
+      <slot name="footer"></slot>
+      <span part="live" role="status" aria-live="polite">${this.announcement || nothing}</span>
+    </dialog>`;
+    }
+};
+__decorate([
+    property({ attribute: 'idle-delay', type: Number })
+], HelixHeadlessLightbox.prototype, "idleDelay", void 0);
+__decorate([
+    property()
+], HelixHeadlessLightbox.prototype, "label", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessLightbox.prototype, "loop", void 0);
+__decorate([
+    property({ attribute: 'status-label' })
+], HelixHeadlessLightbox.prototype, "statusLabel", void 0);
+__decorate([
+    state()
+], HelixHeadlessLightbox.prototype, "resting", void 0);
+__decorate([
+    state()
+], HelixHeadlessLightbox.prototype, "filled", void 0);
+__decorate([
+    state()
+], HelixHeadlessLightbox.prototype, "announcement", void 0);
+HelixHeadlessLightbox = __decorate([
+    customElement('helix-headless-lightbox')
+], HelixHeadlessLightbox);
+export { HelixHeadlessLightbox };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-headless",
   "description": "Headless component tier. Structure, accessibility, state, and form participation. No styling.",
-  "version": "0.100.0",
+  "version": "0.101.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -46,13 +46,13 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.100.0",
-    "@fusion.dev/helix-icons": "0.100.0",
+    "@fusion.dev/helix-core": "0.101.0",
+    "@fusion.dev/helix-icons": "0.101.0",
     "uqr": "^0.1.3"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.100.0",
-    "@fusion.dev/helix-testing": "0.100.0",
+    "@fusion.dev/helix-cem": "0.101.0",
+    "@fusion.dev/helix-testing": "0.101.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.0.0",
     "@lit-labs/ssr": "^4.1.0",