@fusion.dev/helix-headless 0.145.0 → 0.147.0

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, SourceController } from '@fusion.dev/helix-core';
-import { type PropertyValues, type TemplateResult } from 'lit';
+import { HelixElement, KeyboardNavigationController, SourceController } from '@fusion.dev/helix-core';
+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,8 +21,14 @@ 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`. `hidden-series` holds the hidden names,
- * so a page can start with some hidden or read which are.
+ * 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
+ * other legend takes it for its own entries.
  *
  * @since 0.1.0
  * @status stable
@@ -37,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.
  */
@@ -79,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.
      *
@@ -99,16 +107,56 @@ export declare class HelixHeadlessLegend extends HelixElement {
      */
     toggles: boolean;
     protected readonly source: SourceController;
-    /** Whether this legend has written the table's hidden series, so leaving undoes it. */
-    private wrote;
+    /**
+     * The toggle that holds the one tab stop, by place: the one a reader was
+     * last on, or the first.
+     */
+    private stop;
+    /**
+     * The arrow keys, Home, End and typed letters among the toggles, so a
+     * legend of twelve series is one tab stop, as a toolbar of
+     * toggle buttons is. Nothing without `toggles`, where there is nothing to
+     * press.
+     */
+    protected readonly keys: KeyboardNavigationController;
+    /** The table this legend last wrote its `hidden-series` to, so leaving undoes it. */
+    private wroteTo;
+    /** Whether this update writes `hidden-series` to the table, decided before the render. */
+    private writes;
+    /**
+     * Decides who holds the hidden series for this update: this legend, or the
+     * table.
+     *
+     * **This legend, where its own `hidden-series` moved**, by a press, by the
+     * page, or by its first value, and where it has a list the table it now
+     * reads has not had from it yet. **The table otherwise**, which is a second
+     * legend on the same table having hidden something: this one takes the
+     * table's list for its own entries and writes nothing back.
+     *
+     * Writing back on every update is what hung a page with two legends whose
+     * lists differed: each write asks every reader of the table to update,
+     * which included the other legend, which wrote its own list back. Now the
+     * last list written wins and the other legend shows it, as two switches on
+     * one lamp do.
+     */
     protected willUpdate(changed: PropertyValues<this>): void;
+    /**
+     * Takes the table's hidden series as this legend's own, for its entries.
+     *
+     * A name hidden on the table that is not one of this legend's entries stays
+     * out of its list: a legend of the rows and one of the columns share a
+     * table, and each keeps a list of its own.
+     */
+    private follow;
     /**
      * Hands `hidden-series` to the table, where every chart reading it finds
      * it.
      *
      * After the update rather than before, because a server has no table and a
      * hydrating render must draw what the server drew: the charts follow a frame
-     * after the legend, which is when they draw at all.
+     * after the legend, which is when they draw at all. Only this legend's own
+     * entries are written, so a series another legend hid among other names
+     * stays hidden.
      */
     protected updated(changed: PropertyValues<this>): void;
     disconnectedCallback(): void;
@@ -131,13 +179,30 @@ 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.
      *
      * Pressed while its series is shown, which is the state a reader changes by
-     * pressing it: a toggle button says whether its thing is on.
+     * pressing it: a toggle button says whether its thing is on. `holds` says
+     * whether it is the one tab stop, which is the last toggle a reader was on,
+     * the toggle at `index`.
      */
-    protected renderToggle(name: string, off: boolean): TemplateResult;
+    protected renderToggle(name: string, off: boolean, index?: number, holds?: boolean): TemplateResult;
 }
 declare global {
     interface HTMLElementTagNameMap {

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, requestChange, SourceController, seriesIndex, } 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 } from 'lit/decorators.js';
-import { isHidden, toggledNames } from '../hidden-series.js';
+import { property, state } from 'lit/decorators.js';
+import { isHidden, namesIn, toggledNames } from '../hidden-series.js';
 let HelixHeadlessLegend = class HelixHeadlessLegend extends HelixElement {
     constructor() {
         super(...arguments);
@@ -16,25 +16,59 @@ let HelixHeadlessLegend = class HelixHeadlessLegend extends HelixElement {
         this.label = '';
         this.toggles = false;
         this.source = new SourceController(this);
-        this.wrote = false;
+        this.stop = 0;
+        this.keys = new KeyboardNavigationController(this, {
+            items: () => this.toggles
+                ? [...this.renderRoot.querySelectorAll('[part="toggle"]')].map((button) => ({
+                    contains: (node) => button.contains(node),
+                    disabled: false,
+                    focusItem: () => button.focus(),
+                    select: () => { },
+                    selected: false,
+                    words: button.textContent?.trim() ?? '',
+                }))
+                : [],
+            origin: 'focus',
+            selects: () => false,
+            typeahead: typeaheadBy((item) => item.words ?? ''),
+        });
+        this.wroteTo = null;
+        this.writes = false;
     }
     willUpdate(changed) {
         if (changed.has('for')) {
             this.source.watch();
         }
+        const table = this.source.element;
+        const asked = changed.has('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 = 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)));
+        if (!same) {
+            this.hiddenSeries = next.join(', ');
+        }
     }
     updated(changed) {
         super.updated(changed);
-        const names = commaList(this.hiddenSeries);
-        if (names.length > 0 || this.wrote) {
-            this.source.hide(names);
-            this.wrote = names.length > 0;
+        if (this.writes) {
+            this.writes = false;
+            this.wroteTo = this.source.hide(namesIn(this.hiddenSeries), this.names()) ?? this.wroteTo;
         }
     }
     disconnectedCallback() {
-        if (this.wrote) {
-            this.source.hide([]);
-            this.wrote = false;
+        if (this.wroteTo !== null) {
+            this.source.hide([], this.names());
+            this.wroteTo = null;
         }
         super.disconnectedCallback();
     }
@@ -58,28 +92,45 @@ let HelixHeadlessLegend = class HelixHeadlessLegend extends HelixElement {
     }
     render() {
         const named = this.label || this.source.element?.querySelector('caption')?.textContent?.trim();
-        return html `<ul aria-label=${named || nothing} part="list" role="list">
-      ${this.names().map((name, index) => {
+        const names = this.names();
+        const stop = Math.min(this.stop, names.length - 1);
+        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) : html `<span part="name">${name}</span>`}
+          ${this.renderSwatch(name, index)}${toolbar ? this.renderToggle(name, off, index, index === stop) : this.renderName(name, index)}
         </li>`;
         })}
     </ul>`;
     }
-    renderToggle(name, off) {
+    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'}
       part="toggle"
+      tabindex=${holds ? '0' : '-1'}
       type="button"
       @click=${() => this.toggle(name)}
+      @focus=${() => {
+            this.stop = index;
+        }}
     >
-      <span part="name">${name}</span>
+      ${this.renderName(name, index)}
     </button>`;
     }
 };
@@ -98,6 +149,9 @@ __decorate([
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessLegend.prototype, "toggles", void 0);
+__decorate([
+    state()
+], HelixHeadlessLegend.prototype, "stop", void 0);
 HelixHeadlessLegend = __decorate([
     customElement('helix-headless-legend')
 ], HelixHeadlessLegend);

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

@@ -19,9 +19,22 @@ declare const HelixHeadlessLightbox_base: (new (...args: any[]) => import("@fusi
  * focus stays in the dialog.
  *
  * Set `controls` for the viewer's own previous, next and close controls, named
- * by `previous-label`, `next-label` and `dismiss-label`. Without it, compose the
- * chrome yourself in the `header` and `footer` slots, with buttons that send
- * `--previous`, `--next` and `--close`.
+ * by `previous-label`, `next-label` and `dismiss-label`, whose glyphs you can
+ * replace in the `previous-icon`, `next-icon` and `dismiss-icon` slots. Without
+ * it, compose the chrome yourself in the `header` and `footer` slots, with
+ * buttons that send `--previous`, `--next` and `--close`.
+ *
+ * **Set `max-zoom` to let a reader zoom into the shown item**, such as `3`.
+ * Two fingers pinch it, a double click or a double tap zooms all the way in
+ * about the point pressed and back out, and once zoomed one pointer drags it
+ * 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. 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
@@ -41,8 +54,13 @@ declare const HelixHeadlessLightbox_base: (new (...args: any[]) => import("@fusi
  * @documentation https://fusion.dev/helix/components/lightbox
  *
  * @slot - The items, which are `<helix-headless-lightbox-item>` elements.
+ * @slot dismiss-icon - Replaces the glyph inside the close control.
  * @slot footer - Content below the item, such as a counter or a thumbnail strip.
  * @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.
@@ -51,30 +69,52 @@ declare const HelixHeadlessLightbox_base: (new (...args: any[]) => import("@fusi
  * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the viewer opens. Cancelable.
  * @event {ToggleEvent} toggle - Fired when the viewer opens or closes, with `newState` and `oldState`.
  *
+ * @csspart counter - The place of the shown item in the set, drawn with `counter`.
  * @csspart dialog - The native dialog element.
  * @csspart dismiss - The close control, drawn with `controls`.
- * @csspart dismiss-mark - The glyph on the close control.
- * @csspart live - The live region that announces which item is shown.
+ * @csspart dismiss-mark - The glyph on the close control, where none is slotted.
+ * @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.
+ * @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.
+ * @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.
+ * @cssproperty --lightbox-zoom - The scale the shown item is zoomed to, such as `2`. Written only while zoomed.
  *
  * @cssstate fullscreen - While the viewer fills the screen.
  * @cssstate idle - The user has been still long enough for the controls to hide.
  * @cssstate open - While the viewer is open.
+ * @cssstate zoomable - While `max-zoom` lets a reader zoom.
+ * @cssstate zoomed - While the shown item is zoomed past its own size.
  */
 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;
+    /**
+     * Draws the place of the shown item in the set over the picture, in the
+     * words of `status-label`, such as "2 of 5". It hides with the controls while
+     * the reader is idle. Screen readers hear the place from the live region, so
+     * the drawn copy is hidden from them.
+     */
+    counter: boolean;
     /**
      * The close control's accessible name. Translate it with the rest of your
      * interface.
@@ -97,6 +137,11 @@ export declare class HelixHeadlessLightbox extends HelixHeadlessLightbox_base {
      * Whether moving past the last item returns to the first.
      */
     loop: boolean;
+    /**
+     * How far a reader can zoom into the shown item, as a scale, such as `3`.
+     * `1`, the default, turns zooming off.
+     */
+    maxZoom: number;
     /**
      * The next control's accessible name.
      */
@@ -125,13 +170,41 @@ 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.
+     */
+    zoomTo(scale: number): void;
     private readonly fullscreen;
     private readonly idle;
     /**
@@ -202,6 +275,12 @@ export declare class HelixHeadlessLightbox extends HelixHeadlessLightbox_base {
      * a reader having no way to know which one this component thinks it is.
      */
     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. */
@@ -236,6 +315,8 @@ export declare class HelixHeadlessLightbox extends HelixHeadlessLightbox_base {
      * every page load.
      */
     private say;
+    /** The shown item's place in the set, in the words of `status-label`. */
+    private place;
     protected render(): TemplateResult;
     /**
      * The viewer's own controls, behind a seam a tier above can move.
@@ -245,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 {