@fusion.dev/helix-headless 0.146.0 → 0.147.0

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

@@ -26,7 +26,13 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * `caps` draws a chord as a key per key: each is a `key` part and the `+`
  * between two a `separator` part, so a sheet can draw a cap for each.
  * `key-labels` renames any key, on every platform, such as
- * `key-labels='{"mod":"Command"}'`.
+ * `key-labels='{"mod":"Command"}'`. On an Apple keyboard a word joins the
+ * next key with a hyphen, as in `Command-K`.
+ *
+ * **`activate` makes the shortcut work the control `for` names**, with no
+ * script: `activate="focus"` moves focus to it, as `/` does to a search
+ * field, and `activate="click"` presses it. It acts once `helix-shortcut` has
+ * gone out and no listener canceled it, and only where `within` listens.
  *
  * @since 0.1.0
  * @status stable
@@ -40,9 +46,18 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  *
  * @csspart kbd - The key, or the chord under `keys`.
  * @csspart key - One key of a chord under `keys` and `caps`, such as `Ctrl` in `Ctrl+K`.
- * @csspart separator - The `+` between two keys of a chord under `keys` and `caps`, drawn where the platform writes one: on Windows and Linux. An Apple keyboard writes none.
+ * @csspart separator - The `+` between two keys of a chord under `keys` and `caps`, drawn where the platform writes one: on Windows and Linux. An Apple keyboard writes none between glyphs, and a hyphen between words from `key-labels`.
  */
 export declare class HelixHeadlessKbd extends HelixElement {
+    /**
+     * What the chord does to the control `for` names once it is pressed:
+     * `focus` moves focus to the control and `click` presses it.
+     *
+     * Unset, the chord sends `helix-shortcut` and does nothing else, for a page
+     * that acts on the event itself. It acts only where `within` listens, after
+     * `helix-shortcut`, and not when a listener cancels that event.
+     */
+    activate?: 'click' | 'focus';
     /**
      * Draws a chord under `keys` as one key per key, each a `key` part with a
      * `separator` part between two where the platform writes a `+`, as GitHub
@@ -72,7 +87,7 @@ export declare class HelixHeadlessKbd extends HelixElement {
      * changes: the chord written onto `aria-keyshortcuts` keeps the names a
      * screen reader knows.
      */
-    keyLabels?: Record<string, string>;
+    keyLabels: Record<string, string>;
     /**
      * The key or chord to show, such as `mod+k`, `?`, or `/`.
      *
@@ -119,6 +134,8 @@ export declare class HelixHeadlessKbd extends HelixElement {
     private listen;
     private deafen;
     private readonly handleKeydown;
+    /** Focuses or presses the control `for` names, as `activate` says. */
+    private act;
     protected firstUpdated(changed: PropertyValues): void;
     protected render(): TemplateResult;
     /**

package/dist/kbd/root/kbd-root.js

@@ -4,9 +4,10 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     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 { ariaChord, chordParts, customElement, elementById, HelixElement, HelixShortcutEvent, matchesChord, onApple, printableChord, } from '@fusion.dev/helix-core';
+import { ariaChord, chordParts, customElement, elementById, HelixElement, HelixShortcutEvent, matchesChord, onApple, printableChord, wordsConverter, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
+import { keyNames } from '../keys.js';
 import { claimShortcut, releaseShortcut } from '../shortcut.js';
 const typing = (node) => {
     if (node instanceof HTMLTextAreaElement) {
@@ -29,49 +30,12 @@ const UNTYPED = new Set([
     'reset',
     'submit',
 ]);
-const APPLE = {
-    alt: '⌥',
-    backspace: '⌫',
-    cmd: '⌘',
-    ctrl: '⌃',
-    del: '⌦',
-    down: '↓',
-    enter: '↵',
-    esc: 'Esc',
-    left: '←',
-    meta: '⌘',
-    mod: '⌘',
-    opt: '⌥',
-    right: '→',
-    shift: '⇧',
-    space: 'Space',
-    tab: '⇥',
-    up: '↑',
-};
-const ELSEWHERE = {
-    alt: 'Alt',
-    backspace: 'Backspace',
-    cmd: 'Win',
-    ctrl: 'Ctrl',
-    del: 'Del',
-    down: '↓',
-    enter: 'Enter',
-    esc: 'Esc',
-    left: '←',
-    meta: 'Win',
-    mod: 'Ctrl',
-    opt: 'Alt',
-    right: '→',
-    shift: 'Shift',
-    space: 'Space',
-    tab: 'Tab',
-    up: '↑',
-};
 let HelixHeadlessKbd = class HelixHeadlessKbd extends HelixElement {
     constructor() {
         super(...arguments);
         this.caps = false;
         this.for = '';
+        this.keyLabels = {};
         this.keys = '';
         this.handleKeydown = (event) => {
             const press = event;
@@ -88,9 +52,11 @@ let HelixHeadlessKbd = class HelixHeadlessKbd extends HelixElement {
             }
             const shortcut = new HelixShortcutEvent({ keys: this.keys });
             this.dispatchEvent(shortcut);
-            if (!shortcut.defaultPrevented) {
-                press.preventDefault();
+            if (shortcut.defaultPrevented) {
+                return;
             }
+            press.preventDefault();
+            this.act();
         };
     }
     connectedCallback() {
@@ -133,14 +99,7 @@ let HelixHeadlessKbd = class HelixHeadlessKbd extends HelixElement {
         }
     }
     get label() {
-        const apple = !this.hydrating && onApple();
-        const names = apple ? APPLE : ELSEWHERE;
-        const own = this.keyLabels ?? {};
-        const keys = chordParts(this.keys).map((part) => {
-            const name = part.toLowerCase();
-            return own[name] ?? names[name] ?? (part.length === 1 ? part.toUpperCase() : part);
-        });
-        return { keys, separator: apple ? '' : '+' };
+        return keyNames(chordParts(this.keys), !this.hydrating && onApple(), this.keyLabels ?? {});
     }
     listen() {
         if (!this.within || this.keys === '') {
@@ -157,6 +116,18 @@ let HelixHeadlessKbd = class HelixHeadlessKbd extends HelixElement {
         this.listening?.removeEventListener('keydown', this.handleKeydown);
         this.listening = undefined;
     }
+    act() {
+        const control = this.activate && this.for !== '' ? elementById(this, this.for) : null;
+        if (!(control instanceof HTMLElement)) {
+            return;
+        }
+        if (this.activate === 'click') {
+            control.click();
+        }
+        else {
+            control.focus();
+        }
+    }
     firstUpdated(changed) {
         super.firstUpdated(changed);
         this.finishHydration();
@@ -173,6 +144,9 @@ let HelixHeadlessKbd = class HelixHeadlessKbd extends HelixElement {
         return html `${keys.map((key, index) => html `${index > 0 && separator !== '' ? html `<span part="separator">${separator}</span>` : nothing}<span part="key">${key}</span>`)}`;
     }
 };
+__decorate([
+    property()
+], HelixHeadlessKbd.prototype, "activate", void 0);
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessKbd.prototype, "caps", void 0);
@@ -180,7 +154,7 @@ __decorate([
     property()
 ], HelixHeadlessKbd.prototype, "for", void 0);
 __decorate([
-    property({ attribute: 'key-labels', type: Object })
+    property({ attribute: 'key-labels', converter: wordsConverter })
 ], HelixHeadlessKbd.prototype, "keyLabels", void 0);
 __decorate([
     property()

package/dist/legend/hidden-series.d.ts

@@ -1,8 +1,16 @@
+/** A list as it may be given: names separated by commas, or an array of names. */
+export type NameList = string | readonly string[];
+/**
+ * The names in a list, written either way: split on commas from a string,
+ * trimmed and without blanks from an array, which is what a framework hands
+ * over for `hiddenSeries={['Direct']}`.
+ */
+export declare const namesIn: (list: NameList) => string[];
 /** Whether a name is in the list, matched without regard to case, as a heading is. */
-export declare const isHidden: (list: string, name: string) => boolean;
+export declare const isHidden: (list: NameList, name: string) => boolean;
 /**
  * The list a press on this name leaves: without it where it was hidden, and
  * with it at the end where it was shown. Written back with a comma and a
  * space, as a person writes a list.
  */
-export declare const toggledNames: (list: string, name: string) => string;
+export declare const toggledNames: (list: NameList, name: string) => string;

package/dist/legend/hidden-series.js

@@ -1,11 +1,14 @@
 import { commaList, seriesKey } from '@fusion.dev/helix-core';
+export const namesIn = (list) => typeof list === 'string'
+    ? commaList(list)
+    : list.map((name) => String(name).trim()).filter((name) => name !== '');
 export const isHidden = (list, name) => {
     const key = seriesKey(name);
-    return commaList(list).some((one) => seriesKey(one) === key);
+    return namesIn(list).some((one) => seriesKey(one) === key);
 };
 export const toggledNames = (list, name) => {
     const key = seriesKey(name);
-    const now = commaList(list);
+    const now = namesIn(list);
     const next = isHidden(list, name)
         ? now.filter((one) => seriesKey(one) !== key)
         : [...now, name.trim()];

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

@@ -1,5 +1,5 @@
 import { HelixElement, KeyboardNavigationController, SourceController } from '@fusion.dev/helix-core';
-import { type PropertyValues, type TemplateResult } from 'lit';
+import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 /**
  * @summary A list of the series in a chart, each name beside the color it is drawn in.
  *
@@ -21,9 +21,10 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * **`toggles` makes each entry a button that hides its series.** Every chart
  * reading the same table draws without a hidden series and fits its scale to
  * the rest, and the series keeps its color. The button says whether its
- * series is shown with `aria-pressed`. The buttons are one tab stop: the
- * arrow keys move between them, Home and End go to the first and the last,
- * and a typed letter goes to the next name starting with it.
+ * series is shown with `aria-pressed`. The buttons are a `toolbar`, named
+ * as the list is, and one tab stop: the arrow keys move between them, Home
+ * and End go to the first and the last, and a typed letter goes to the next
+ * name starting with it.
  * `hidden-series` holds the hidden names,
  * so a page can start with some hidden or read which are. Two legends on one
  * table show the same hidden series: the list written last wins, and the
@@ -42,7 +43,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * `::part(entry)::before` in your stylesheet. The entry holds its series color
  * as `--chart-series`, and this tier ships no CSS.
  * @csspart entry-hidden - An entry whose series is hidden. Set alongside `entry`.
- * @csspart list - The list of entries.
+ * @csspart list - The list of entries, a `toolbar` under `toggles`.
  * @csspart name - One series name.
  * @csspart toggle - The button around a name under `toggles`, which hides or shows its series.
  */
@@ -84,9 +85,11 @@ export declare class HelixHeadlessLegend extends HelixElement {
      *
      * Set it to start with series hidden. Every chart reading the same table
      * draws without them. Commas only, because a column's heading may hold a
-     * space. For a ring the names are the rows.
+     * space. For a ring the names are the rows. An array of names set on the
+     * property works too, as React sets `hiddenSeries={['Direct']}`; a toggle
+     * writes the list back as a string.
      */
-    hiddenSeries: string;
+    hiddenSeries: string | readonly string[];
     /**
      * The name of the list, which a screen reader announces before its entries.
      *
@@ -176,6 +179,21 @@ export declare class HelixHeadlessLegend extends HelixElement {
      */
     protected names(): string[];
     protected render(): TemplateResult;
+    /**
+     * What an entry shows before its name, behind a seam a tier can fill.
+     *
+     * Nothing on this tier, which ships no CSS: the styled tier and a page draw
+     * the swatch with `::part(entry)::before`, from the entry's `--chart-series`.
+     * A tier that draws its swatch as an element, or a mark per series, returns
+     * it here, and `index` says which palette slot the series takes.
+     */
+    protected renderSwatch(_name: string, _index: number): TemplateResult | typeof nothing;
+    /**
+     * An entry's name, behind a seam a tier can move: a value beside the name,
+     * or the name in other words. `index` is the series' place among the
+     * entries. A toggle holds the same name inside its button.
+     */
+    protected renderName(name: string, _index: number): TemplateResult;
     /**
      * The button around a name under `toggles`, behind a seam a tier can move.
      *

package/dist/legend/root/legend-root.js

@@ -4,10 +4,10 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     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 { commaList, customElement, HelixBeforeChangeEvent, HelixElement, KeyboardNavigationController, requestChange, SourceController, seriesIndex, seriesKey, typeaheadBy, } from '@fusion.dev/helix-core';
+import { customElement, HelixBeforeChangeEvent, HelixElement, KeyboardNavigationController, requestChange, SourceController, seriesIndex, seriesKey, typeaheadBy, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
-import { isHidden, toggledNames } from '../hidden-series.js';
+import { isHidden, namesIn, toggledNames } from '../hidden-series.js';
 let HelixHeadlessLegend = class HelixHeadlessLegend extends HelixElement {
     constructor() {
         super(...arguments);
@@ -41,15 +41,16 @@ let HelixHeadlessLegend = class HelixHeadlessLegend extends HelixElement {
         }
         const table = this.source.element;
         const asked = changed.has('hiddenSeries') &&
-            !(changed.get('hiddenSeries') === undefined && this.hiddenSeries === '');
-        this.writes = asked || (table !== null && table !== this.wroteTo && this.hiddenSeries !== '');
+            !(changed.get('hiddenSeries') === undefined && namesIn(this.hiddenSeries).length === 0);
+        this.writes =
+            asked || (table !== null && table !== this.wroteTo && namesIn(this.hiddenSeries).length > 0);
         if (!this.writes && table !== null) {
             this.follow();
         }
     }
     follow() {
         const hidden = this.source.hidden;
-        const now = commaList(this.hiddenSeries);
+        const now = namesIn(this.hiddenSeries);
         const next = this.names().filter((name) => hidden.has(seriesKey(name)));
         const same = next.length === now.length &&
             next.every((name) => now.some((one) => seriesKey(one) === seriesKey(name)));
@@ -61,7 +62,7 @@ let HelixHeadlessLegend = class HelixHeadlessLegend extends HelixElement {
         super.updated(changed);
         if (this.writes) {
             this.writes = false;
-            this.wroteTo = this.source.hide(commaList(this.hiddenSeries), this.names()) ?? this.wroteTo;
+            this.wroteTo = this.source.hide(namesIn(this.hiddenSeries), this.names()) ?? this.wroteTo;
         }
     }
     disconnectedCallback() {
@@ -93,20 +94,31 @@ let HelixHeadlessLegend = class HelixHeadlessLegend extends HelixElement {
         const named = this.label || this.source.element?.querySelector('caption')?.textContent?.trim();
         const names = this.names();
         const stop = Math.min(this.stop, names.length - 1);
-        return html `<ul aria-label=${named || nothing} part="list" role="list">
+        const toolbar = this.toggles;
+        return html `<ul
+      aria-label=${named || nothing}
+      part="list"
+      role=${toolbar ? 'toolbar' : 'list'}
+    >
       ${names.map((name, index) => {
             const off = isHidden(this.hiddenSeries, name);
             return html `<li
           data-series=${seriesIndex(index)}
           part="entry${off ? ' entry-hidden' : ''}"
           style="--chart-series: var(--chart-series-${seriesIndex(index)})"
-          role="listitem"
+          role=${toolbar ? 'none' : 'listitem'}
         >
-          ${this.toggles ? this.renderToggle(name, off, index, index === stop) : html `<span part="name">${name}</span>`}
+          ${this.renderSwatch(name, index)}${toolbar ? this.renderToggle(name, off, index, index === stop) : this.renderName(name, index)}
         </li>`;
         })}
     </ul>`;
     }
+    renderSwatch(_name, _index) {
+        return nothing;
+    }
+    renderName(name, _index) {
+        return html `<span part="name">${name}</span>`;
+    }
     renderToggle(name, off, index = 0, holds = true) {
         return html `<button
       aria-pressed=${off ? 'false' : 'true'}
@@ -118,7 +130,7 @@ let HelixHeadlessLegend = class HelixHeadlessLegend extends HelixElement {
             this.stop = index;
         }}
     >
-      <span part="name">${name}</span>
+      ${this.renderName(name, index)}
     </button>`;
     }
 };

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

@@ -30,7 +30,11 @@ declare const HelixHeadlessLightbox_base: (new (...args: any[]) => import("@fusi
  * about. `+` and `-` zoom in and out from the keyboard, and `0` puts it back.
  * The scale and the offset are on the `viewport` part as `--lightbox-zoom`,
  * `--lightbox-pan-x` and `--lightbox-pan-y`, written only while zoomed, and a
- * swipe moves to the next item only while the item is at its own size.
+ * swipe moves to the next item only while the item is at its own size. With
+ * `controls`, the viewer also draws zoom-out and zoom-in controls, for a
+ * pointer with no wheel and no second finger. Once a reader stops zooming, the
+ * live region says the new scale in the words of `zoom-status-label`, such as
+ * "Zoomed to 150%".
  *
  * Each item is a slide: a `group` with the role description in
  * `slide-role-label`, named by its `label` or by `slide-label`. A touch or a pen
@@ -55,6 +59,8 @@ declare const HelixHeadlessLightbox_base: (new (...args: any[]) => import("@fusi
  * @slot header - Content above the item, such as a title and a close button.
  * @slot next-icon - Replaces the glyph inside the next control.
  * @slot previous-icon - Replaces the glyph inside the previous control.
+ * @slot zoom-in-icon - Replaces the glyph inside the zoom-in control.
+ * @slot zoom-out-icon - Replaces the glyph inside the zoom-out control.
  *
  * @event {Event} close - Fired when the viewer closes. The component dispatches it again from the host, because the dialog's own event does not leave the shadow root.
  * @event {HelixActivateEvent} helix-activate - Fired after the shown item changes, when the element already holds the new item.
@@ -67,12 +73,18 @@ declare const HelixHeadlessLightbox_base: (new (...args: any[]) => import("@fusi
  * @csspart dialog - The native dialog element.
  * @csspart dismiss - The close control, drawn with `controls`.
  * @csspart dismiss-mark - The glyph on the close control, where none is slotted.
- * @csspart live - The live region that announces which item is shown.
+ * @csspart footer - The slot the footer is in. It draws no box until you give it one.
+ * @csspart header - The slot the header is in. It draws no box until you give it one.
+ * @csspart live - The live region that announces which item is shown, and the scale once a reader has zoomed.
  * @csspart next - The control that shows the next item, drawn with `controls`.
  * @csspart next-mark - The glyph on the next control, where none is slotted.
  * @csspart previous - The control that shows the previous item, drawn with `controls`.
  * @csspart previous-mark - The glyph on the previous control, where none is slotted.
  * @csspart viewport - The box the current item is shown in.
+ * @csspart zoom-in - The control that zooms in by half again, drawn with `controls` where `max-zoom` allows zooming.
+ * @csspart zoom-in-mark - The glyph on the zoom-in control, where none is slotted.
+ * @csspart zoom-out - The control that zooms back out, drawn with `controls` where `max-zoom` allows zooming.
+ * @csspart zoom-out-mark - The glyph on the zoom-out control, where none is slotted.
  *
  * @cssproperty --lightbox-pan-x - How far the zoomed item is moved across from the middle of the viewport, in pixels, toward the right. Written only while zoomed.
  * @cssproperty --lightbox-pan-y - How far the zoomed item is moved down from the middle of the viewport, in pixels. Written only while zoomed.
@@ -86,12 +98,14 @@ declare const HelixHeadlessLightbox_base: (new (...args: any[]) => import("@fusi
  */
 export declare class HelixHeadlessLightbox extends HelixHeadlessLightbox_base {
     /**
-     * Draws the viewer's own previous, next and close controls over the picture.
+     * Draws the viewer's own previous, next and close controls over the picture,
+     * and zoom-out and zoom-in controls where `max-zoom` allows zooming.
      *
      * Off by default, for a viewer whose chrome you compose in the `header` and
      * `footer` slots. The controls hide with the rest of the chrome while the
-     * reader is idle, and the previous and next ones say they are unavailable at
-     * either end of a set that does not `loop`.
+     * reader is idle, the previous and next ones say they are unavailable at
+     * either end of a set that does not `loop`, and the zoom ones at either end
+     * of the scale.
      */
     controls: boolean;
     /**
@@ -156,16 +170,36 @@ export declare class HelixHeadlessLightbox extends HelixHeadlessLightbox_base {
      * counter in the chrome can empty this and say it themselves.
      */
     statusLabel: string;
+    /**
+     * The zoom-in control's accessible name.
+     */
+    zoomInLabel: string;
+    /**
+     * The zoom-out control's accessible name.
+     */
+    zoomOutLabel: string;
+    /**
+     * What the live region says once a reader has stopped zooming, with the
+     * scale as a whole `{percent}` filled in. Empty it to say nothing.
+     */
+    zoomStatusLabel: 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;
+    /** The scale the shown item is drawn at, which the zoom controls read. */
+    private zoomScale;
+    private readonly zoomSaid;
+    /** Whether the zoom is being put back because the item changed, which says nothing. */
+    private quietZoom;
     protected readonly swipes: SwipeController;
     private readonly zoomer;
     /** Writes the zoom on the viewport, and nothing at the item's own size. */
     private drawZoom;
+    /** Says the new scale in the live region, a moment after the last change. */
+    private sayZoom;
     /**
      * Zooms the shown item to `scale`, held between `1` and `max-zoom`, about
      * the middle of the viewport.
@@ -243,6 +277,10 @@ export declare class HelixHeadlessLightbox extends HelixHeadlessLightbox_base {
     private readonly handleKeydown;
     /** `+` and `-` zoom in and out by half again, and `0` puts the item back. Returns whether it was one. */
     private zoomKey;
+    /** Zooms in by half again, as `+` and the zoom-in control do. */
+    private zoomIn;
+    /** Zooms out by as much, as `-` and the zoom-out control do. */
+    private zoomOut;
     /** Home and End, which are an index rather than a step. */
     private toEnd;
     /** The item on screen: the one `active` names, or the first where it names none. */
@@ -288,6 +326,13 @@ export declare class HelixHeadlessLightbox extends HelixHeadlessLightbox_base {
      * control that has just shown the last picture keeps focus.
      */
     protected renderControls(): TemplateResult;
+    /**
+     * Zoom out and zoom in, for a pointer with no wheel and no second finger.
+     *
+     * Out before in, so they read as a scale runs. `aria-disabled` at either
+     * limit, as the previous and next controls are at the ends.
+     */
+    protected renderZoomControls(): TemplateResult;
 }
 declare global {
     interface HTMLElementTagNameMap {