@fusion.dev/helix-core 0.103.2 → 0.104.0

package/dist/mixins/mixin-viewport/mixin-viewport.js

@@ -0,0 +1,215 @@
+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 { html, nothing } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { FullscreenController } from '../../controllers/fullscreen-controller/fullscreen-controller.js';
+import { IdleController } from '../../controllers/idle-controller/idle-controller.js';
+import { inlineStep } from '../../utils/inline-step/inline-step.js';
+import { isRtl } from '../../utils/is-rtl/is-rtl.js';
+export const MixinViewport = (Base) => {
+    class Viewport extends Base {
+        constructor() {
+            super(...arguments);
+            this.fullscreenLabel = 'Fill the screen';
+            this.idleDelay = 0;
+            this.panDownLabel = 'Pan down';
+            this.panLeftLabel = 'Pan left';
+            this.panRightLabel = 'Pan right';
+            this.panStep = 0.25;
+            this.panUpLabel = 'Pan up';
+            this.zoomInLabel = 'Zoom in';
+            this.resting = false;
+            this.filled = false;
+            this.fullscreen = new FullscreenController(this, (full) => {
+                this.filled = full;
+            });
+            this.idle = new IdleController(this, () => this.idleDelay, (resting) => {
+                this.resting = resting;
+            });
+            this.zoomOutLabel = 'Zoom out';
+            this.handleKeydown = (event) => {
+                const target = event.target;
+                const own = target?.closest('[part="region"], [part~="controls"]');
+                if (!own || !this.renderRoot.contains(own)) {
+                    return;
+                }
+                if (target !== own && !own.matches('[part~="controls"]')) {
+                    return;
+                }
+                const along = inlineStep(this, event.key);
+                if (along === 1) {
+                    event.preventDefault();
+                    this.pan('end');
+                }
+                else if (along === -1) {
+                    event.preventDefault();
+                    this.pan('start');
+                }
+                else if (event.key === 'ArrowUp') {
+                    event.preventDefault();
+                    this.pan('up');
+                }
+                else if (event.key === 'ArrowDown') {
+                    event.preventDefault();
+                    this.pan('down');
+                }
+                else if (event.key === '+' || event.key === '=') {
+                    event.preventDefault();
+                    this.zoom(1);
+                }
+                else if (event.key === '-' || event.key === '_') {
+                    event.preventDefault();
+                    this.zoom(-1);
+                }
+            };
+        }
+        get restingControlsLabel() {
+            return 'View controls';
+        }
+        panEvent(_detail) {
+            throw new Error(`<${this.localName}> composes MixinViewport and must implement panEvent(), the surface naming no event of its own.`);
+        }
+        zoomEvent(_detail) {
+            throw new Error(`<${this.localName}> composes MixinViewport and must implement zoomEvent(), the surface naming no event of its own.`);
+        }
+        pan(to) {
+            this.dispatchEvent(this.panEvent({ by: this.panStep, to }));
+        }
+        zoom(by) {
+            this.dispatchEvent(this.zoomEvent({ by }));
+        }
+        toggleFullscreen() {
+            void this.fullscreen.toggle();
+        }
+        get restingControls() {
+            return 'pan zoom fullscreen';
+        }
+        draws(group) {
+            return (this.controls ?? this.restingControls).split(/\s+/).includes(group);
+        }
+        sideOf(way) {
+            if (way !== 'start' && way !== 'end') {
+                return way;
+            }
+            return (way === 'start') !== this.rightToLeft ? 'left' : 'right';
+        }
+        get rightToLeft() {
+            const element = this;
+            return !element.hydrating && isRtl(this);
+        }
+        named(way) {
+            const side = this.sideOf(way);
+            return side === 'up'
+                ? this.panUpLabel
+                : side === 'down'
+                    ? this.panDownLabel
+                    : side === 'left'
+                        ? this.panLeftLabel
+                        : this.panRightLabel;
+        }
+        glyph(way) {
+            return { down: '↓', left: '←', right: '→', up: '↑' }[this.sideOf(way)] ?? '';
+        }
+        firstUpdated(changed) {
+            super.firstUpdated(changed);
+            this.idle.stir();
+            const element = this;
+            if (element.serverRendered && isRtl(this)) {
+                this.requestUpdate();
+            }
+        }
+        get controlsElement() {
+            return this.renderRoot?.querySelector('[part="controls"]') ?? null;
+        }
+        renderControls() {
+            const pan = this.draws('pan');
+            const zoom = this.draws('zoom');
+            const fullscreen = this.draws('fullscreen');
+            if (!pan && !zoom && !fullscreen) {
+                return nothing;
+            }
+            return html `<div part="controls" role="group" aria-label=${this.controlsLabel ?? this.restingControlsLabel}>
+        ${pan
+                ? html `<button part="pan-up" aria-label=${this.named('up')} type="button" @click=${() => this.pan('up')}>
+                  ${this.glyph('up')}
+                </button>
+                <button part="pan-start" aria-label=${this.named('start')} type="button" @click=${() => this.pan('start')}>
+                  ${this.glyph('start')}
+                </button>
+                <button part="pan-end" aria-label=${this.named('end')} type="button" @click=${() => this.pan('end')}>
+                  ${this.glyph('end')}
+                </button>
+                <button part="pan-down" aria-label=${this.named('down')} type="button" @click=${() => this.pan('down')}>
+                  ${this.glyph('down')}
+                </button>`
+                : nothing}
+        ${zoom
+                ? html `<button part="zoom-in" aria-label=${this.zoomInLabel} type="button" @click=${() => this.zoom(1)}>
+                  +
+                </button>
+                <button part="zoom-out" aria-label=${this.zoomOutLabel} type="button" @click=${() => this.zoom(-1)}>
+                  −
+                </button>`
+                : nothing}
+        ${fullscreen
+                ? html `<button
+                part="fullscreen"
+                aria-label=${this.fullscreenLabel}
+                aria-pressed=${this.filled ? 'true' : 'false'}
+                type="button"
+                @click=${this.toggleFullscreen}
+              >
+                ⤢
+              </button>`
+                : nothing}
+      </div>`;
+        }
+    }
+    __decorate([
+        property({ reflect: true })
+    ], Viewport.prototype, "controls", void 0);
+    __decorate([
+        property({ attribute: 'controls-label' })
+    ], Viewport.prototype, "controlsLabel", void 0);
+    __decorate([
+        property({ attribute: 'controls-placement', reflect: true })
+    ], Viewport.prototype, "controlsPlacement", void 0);
+    __decorate([
+        property({ attribute: 'fullscreen-label' })
+    ], Viewport.prototype, "fullscreenLabel", void 0);
+    __decorate([
+        property({ attribute: 'idle-delay', type: Number })
+    ], Viewport.prototype, "idleDelay", void 0);
+    __decorate([
+        property({ attribute: 'pan-down-label' })
+    ], Viewport.prototype, "panDownLabel", void 0);
+    __decorate([
+        property({ attribute: 'pan-left-label' })
+    ], Viewport.prototype, "panLeftLabel", void 0);
+    __decorate([
+        property({ attribute: 'pan-right-label' })
+    ], Viewport.prototype, "panRightLabel", void 0);
+    __decorate([
+        property({ attribute: 'pan-step', type: Number })
+    ], Viewport.prototype, "panStep", void 0);
+    __decorate([
+        property({ attribute: 'pan-up-label' })
+    ], Viewport.prototype, "panUpLabel", void 0);
+    __decorate([
+        property({ attribute: 'zoom-in-label' })
+    ], Viewport.prototype, "zoomInLabel", void 0);
+    __decorate([
+        state()
+    ], Viewport.prototype, "resting", void 0);
+    __decorate([
+        state()
+    ], Viewport.prototype, "filled", void 0);
+    __decorate([
+        property({ attribute: 'zoom-out-label' })
+    ], Viewport.prototype, "zoomOutLabel", void 0);
+    return Viewport;
+};

package/dist/utils/fill-template/fill-template.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A label with its `{placeholders}` filled in.
+ *
+ * **The one way every translatable sentence here is written**: a property holds
+ * the whole sentence, and the numbers and names go in where it says. A
+ * sentence built from pieces in code puts the pieces in English order, and
+ * another language may want them the other way round.
+ *
+ * Every occurrence is filled, so a sentence can name the same thing twice. A
+ * placeholder with no value is left as written rather than emptied, which
+ * shows up on the page as the mistake it is.
+ */
+export declare const fillTemplate: (template: string, values: Record<string, string | number>) => string;

package/dist/utils/fill-template/fill-template.js

@@ -0,0 +1 @@
+export const fillTemplate = (template, values) => Object.entries(values).reduce((out, [key, value]) => out.replaceAll(`{${key}}`, () => String(value)), template);

package/dist/utils/key-claimed/key-claimed.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Whether a press was already the business of whatever it landed on.
+ *
+ * **For a container that binds keys over content it did not write**: a toolbar,
+ * a viewer, a drilldown. Some of what they hold uses the same keys for itself,
+ * and moving the container regardless makes an input inside it uneditable:
+ * ArrowRight moves somewhere else, and `preventDefault` means the caret never
+ * moves at all.
+ *
+ * `composedPath()[0]` rather than `event.target`, which is retargeted to the
+ * control's host at the shadow boundary and cannot tell a text field inside a
+ * component from the component itself.
+ *
+ * `defaultPrevented` first, because a control that has already answered the
+ * press has said so in the way the platform provides, and a foreign control
+ * this package has never heard of has no other way to say it.
+ */
+export declare const keyClaimed: (event: KeyboardEvent) => boolean;

package/dist/utils/key-claimed/key-claimed.js

@@ -0,0 +1,14 @@
+const CARETLESS = new Set(['button', 'checkbox', 'color', 'file', 'image', 'reset', 'submit']);
+export const keyClaimed = (event) => {
+    if (event.defaultPrevented) {
+        return true;
+    }
+    const inner = event.composedPath()[0];
+    if (!(inner instanceof HTMLElement)) {
+        return false;
+    }
+    if (inner.isContentEditable || inner.localName === 'textarea' || inner.localName === 'select') {
+        return true;
+    }
+    return inner.localName === 'input' && !CARETLESS.has(inner.type);
+};

package/dist/utils/report-values/report-values.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Reports a control's answer to its form: one entry for each value, the way a
+ * native `<select multiple>` and a row of checkboxes send theirs.
+ *
+ * **Several answers are several entries, not one joined string.** A server
+ * reading `tags=a,b` has to know to split it on a convention this library
+ * chose, and one reading `tags=a&tags=b` reads it the way it reads every
+ * other multi-valued control on the platform. Listbox, Select and Combobox
+ * sent the first and Date Picker the second, so what a server received for the
+ * same answer depended on which control asked for it.
+ *
+ * **The joined string is the state**, which is what the browser hands back to
+ * `formStateRestoreCallback` and what `value` holds, so a restored control
+ * reads the shape it wrote.
+ *
+ * **Nothing without a `name`.** A plain string is skipped by the form when its
+ * control has no name, but `FormData` carries its own names and its entries
+ * are appended whatever the element is called, so an unnamed control would
+ * submit empty-named values.
+ */
+export declare const reportValues: (internals: ElementInternals, name: string, values: readonly string[]) => void;

package/dist/utils/report-values/report-values.js

@@ -0,0 +1,11 @@
+export const reportValues = (internals, name, values) => {
+    if (name === '' || values.length === 0) {
+        internals.setFormValue(null);
+        return;
+    }
+    const data = new FormData();
+    for (const value of values) {
+        data.append(name, value);
+    }
+    internals.setFormValue(data, values.join(','));
+};

package/dist/utils/slotted-words/slotted-words.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The words a host's children say in the named slots, `''` being the default
+ * one, in the order they are written.
+ *
+ * For a component that says what the page put in it, which is the page's own
+ * text and not anything this library wrote: an empty state's heading and
+ * message, a banner's message. Text nodes count toward the default slot, as
+ * they are assigned to it. Nothing on a server, whose element has no children
+ * to read.
+ */
+export declare const slottedWords: (host: Element, slots: readonly string[]) => string;

package/dist/utils/slotted-words/slotted-words.js

@@ -0,0 +1,5 @@
+export const slottedWords = (host, slots) => [...(host.childNodes ?? [])]
+    .filter((node) => (node instanceof Element ? slots.includes(node.slot) : slots.includes('')))
+    .map((node) => node.textContent?.replace(/\s+/g, ' ').trim() ?? '')
+    .filter(Boolean)
+    .join(' ');

package/dist/utils/tell-disclosure/tell-disclosure.d.ts

@@ -43,6 +43,8 @@
  * `<button slot="trigger">` has no shadow root to keep the state out of the
  * markup and no property to take it, and a consumer cannot mirror it themselves
  * because the open state belongs to the component. Saying so once is the same
- * answer `Tooltip` gives about the link it will not write for them.
+ * answer `Tooltip` gives about the link it will not write for them, and not at
+ * all to a trigger that already carries `aria-expanded`, which is a consumer
+ * mirroring the state from the component's `toggle` event.
  */
 export declare const tellDisclosure: (trigger: Element | null | undefined, open: boolean) => void;

package/dist/utils/tell-disclosure/tell-disclosure.js

@@ -8,7 +8,7 @@ export const tellDisclosure = (trigger, open) => {
         trigger.expanded = open;
         return;
     }
-    if (warned.has(trigger)) {
+    if (warned.has(trigger) || trigger.hasAttribute('aria-expanded')) {
         return;
     }
     warned.add(trigger);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.103.2",
+  "version": "0.104.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -34,11 +34,11 @@
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",
-    "@fusion.dev/helix-icons": "0.103.2"
+    "@fusion.dev/helix-icons": "0.104.0"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.103.2",
-    "@fusion.dev/helix-testing": "0.103.2",
+    "@fusion.dev/helix-cem": "0.104.0",
+    "@fusion.dev/helix-testing": "0.104.0",
     "@lit-labs/ssr": "^4.1.0",
     "lit": "^3.2.1"
   },