@fusion.dev/helix-core 0.147.0 → 0.149.0

package/dist/controllers/option-window-controller/option-window-controller.d.ts

@@ -0,0 +1,96 @@
+import { type ReactiveController, type ReactiveControllerHost, type TemplateResult } from 'lit';
+import { type DataOption, type DataOptionItem } from '../../utils/data-options/data-options.js';
+/** What the controller needs of a list whose options can come as data. */
+export interface OptionWindowOptions {
+    /** The value of the option the keyboard is on, which is kept drawn. */
+    current: () => string;
+    /** The options as data, or nothing for a list of child elements. */
+    items: () => readonly DataOptionItem[] | undefined;
+}
+/**
+ * Draws the options of a list handed over as data, a window of them at a
+ * time, for a list too long to draw whole.
+ *
+ * **The list keeps its logic and this keeps the drawing.** `records` are the
+ * options as the list reads them, built once per `items` array: the keyboard,
+ * the typeahead, the filter and the value work over all of them, and the list
+ * writes `hidden`, `selected` and `active` onto them as it would onto its
+ * option elements. This draws the ones in the window as option elements of
+ * the host's tier, between two spacers that hold the room of the rest, through
+ * `VirtualizeController`.
+ *
+ * **The option the keyboard is on is always drawn**, wherever the window is,
+ * because `aria-activedescendant` points at an element. `follow` brings it into
+ * view when it moves, in two steps where it is far: the arithmetic scrolls the
+ * window to it, and the host scrolls the drawn element into view on the next
+ * update, as it does for a list of children.
+ *
+ * **The scrolling box is the element `render` was drawn into**, so the host
+ * says nothing about it: it puts the template inside its box. A host's
+ * `isDisabled`, or else its `disabled`, holds every drawn option down.
+ *
+ * Listbox uses it, and so every list that holds a Listbox can.
+ */
+export declare class OptionWindowController implements ReactiveController {
+    private readonly host;
+    private readonly options;
+    /** The option elements drawn on the last update, in order. */
+    drawn: HTMLElement[];
+    /** The `items` array the records were built from. */
+    private source;
+    private built;
+    /** Which slice is drawn, made the first time there are records. */
+    private virtualize;
+    /** Where in the shown records the highlight is: `-1` for nowhere. */
+    private kept;
+    /** Whether the highlight is still being brought into view. */
+    private following;
+    /**
+     * The window as it was last drawn, which `follow` reads: the controller's
+     * own may have moved since, measured after the draw, and an option is in
+     * its place only in the window that drew it.
+     */
+    private span;
+    constructor(host: ReactiveControllerHost & HTMLElement & {
+        disabled?: boolean;
+        isDisabled?: boolean;
+    }, options: OptionWindowOptions);
+    /**
+     * The options as the list reads them, or undefined for a list of children.
+     *
+     * Built when `items` is a new array, so a page that changes the set hands
+     * over a new one, as a property of any framework is set. The windowing is
+     * made then too, and only then: a list of children observes no size and
+     * listens to no scroll it does not need. Its estimate of 32 pixels is
+     * corrected by the rows it draws, on first sight.
+     */
+    get records(): DataOption[] | undefined;
+    /** The box the window is drawn into, inside the scrolling one. */
+    private box;
+    /** The records a filter has left showing. */
+    private get shown();
+    /**
+     * The spacers and the box the window is drawn in, for the host's scrolling
+     * box, or undefined for a list of children, which draws its slot instead.
+     *
+     * A spacer never shrinks: in a column of rows that flexes, it shrank to
+     * nothing, and the list scrolled for a screenful.
+     */
+    render(): TemplateResult | undefined;
+    /**
+     * Draws the window once the render has put its box in place, then measures
+     * it again. Before `VirtualizeController`'s own pass, which reads the rows.
+     */
+    hostUpdated(): void;
+    /**
+     * Brings the highlight into view where `moved` says it moved, and answers
+     * whether its drawn element is in place for the host to scroll to now.
+     *
+     * Only when it moved, or the filter did: the window moves on every scroll,
+     * and following then would pull a reader scrolling with a wheel back to the
+     * highlight.
+     */
+    follow(moved: boolean): boolean;
+    /** Scrolls the box to put the option of `value` in its middle. */
+    center(value: string): void;
+}

package/dist/controllers/option-window-controller/option-window-controller.js

@@ -0,0 +1,81 @@
+import { html, } from 'lit';
+import { dataOptions, drawOptions, windowOf, } from '../../utils/data-options/data-options.js';
+import { VirtualizeController } from '../virtualize-controller/virtualize-controller.js';
+export class OptionWindowController {
+    constructor(host, options) {
+        this.drawn = [];
+        this.kept = -1;
+        this.following = false;
+        this.span = { first: 0, last: 0 };
+        this.host = host;
+        this.options = options;
+        host.addController(this);
+    }
+    get records() {
+        const items = this.options.items();
+        if (items !== this.source) {
+            this.source = items;
+            this.built = items && dataOptions(items);
+            if (items) {
+                this.virtualize ??= new VirtualizeController(this.host, {
+                    container: () => this.box()?.parentElement,
+                    count: () => this.shown.length,
+                    estimate: () => 32,
+                    measured: () => false,
+                    rows: () => this.drawn.map((element) => ({
+                        element,
+                        index: Number(element.getAttribute('aria-posinset')) - 1,
+                    })),
+                });
+            }
+        }
+        return this.built;
+    }
+    box() {
+        return this.host.shadowRoot?.querySelector('[data-rows]');
+    }
+    get shown() {
+        return this.records?.filter((record) => !record.hidden) ?? [];
+    }
+    render() {
+        if (!this.records || !this.virtualize) {
+            return undefined;
+        }
+        const current = this.options.current();
+        this.kept = this.shown.findIndex((record) => record.value === current);
+        const { after, before } = this.virtualize.spacers(this.kept < 0 ? undefined : this.kept);
+        return html `<div style="flex: none; block-size: ${before}px"></div>
+      <div data-rows></div>
+      <div style="flex: none; block-size: ${after}px"></div>`;
+    }
+    hostUpdated() {
+        const box = this.box();
+        if (!this.records || !this.virtualize || !box) {
+            return;
+        }
+        const { first, last } = this.virtualize.window;
+        const shown = this.shown;
+        this.span = { first, last };
+        this.drawn = drawOptions(box, `${this.host.constructor.tier}option`, shown, windowOf(first, last, shown.length, this.kept), Boolean(this.host.isDisabled ?? this.host.disabled));
+        this.virtualize.measure();
+    }
+    follow(moved) {
+        this.following ||= moved;
+        if (!this.virtualize || !this.following || this.kept < 0) {
+            return false;
+        }
+        const { first, last } = this.span;
+        if (this.kept < first || this.kept >= last) {
+            this.virtualize.reveal(this.kept);
+            return false;
+        }
+        this.following = false;
+        return true;
+    }
+    center(value) {
+        const at = this.shown.findIndex((record) => record.value === value);
+        if (at >= 0) {
+            this.virtualize?.reveal(at, 0, { align: 'center' });
+        }
+    }
+}

package/dist/controllers/popover-controller/popover-controller.js

@@ -44,7 +44,7 @@ export class PopoverController {
     }
     show() {
         const surface = this.options.surface();
-        if (this.shown || !surface) {
+        if (this.shown || !surface?.isConnected) {
             return;
         }
         this.shown = true;

package/dist/controllers/reorder-controller/reorder-controller.d.ts

@@ -0,0 +1,285 @@
+import type { nothing, ReactiveController, ReactiveControllerHost, TemplateResult } from 'lit';
+import type { ReorderDetail } from '../../events/details.js';
+import { type ReorderAxis, type ReorderHold } from '../../utils/reorder/reorder.js';
+/**
+ * What a screen reader hears as an item moves. `{name}` is the item's name,
+ * and `{position}` and `{count}` say where it would go.
+ */
+export interface ReorderWords {
+    /** Said when a key or a click puts the item back where it was. */
+    canceled: string;
+    /** Said when the item is let go. */
+    dropped: string;
+    /** Said each time a key moves the held item. */
+    moved: string;
+    /** Said when a key or a click takes hold of the item. */
+    pickedUp: string;
+}
+/** A move a drop asks for, counted from 0 in the order the items are drawn. */
+export interface ReorderMove {
+    from: number;
+    key: string;
+    to: number;
+}
+export interface ReorderOptions {
+    /**
+     * Every key the item with that key moves among, the ones a filter hides
+     * included, for a drop the controller asks for itself. `keys` where this is
+     * not given.
+     */
+    all?: (key: string) => readonly string[];
+    /** Which way the items run: rows down the block axis, or columns along the inline one. */
+    axis: ReorderAxis;
+    /** The box an item is drawn in, or nothing for one a window did not draw. */
+    box: (key: string) => DOMRect | undefined;
+    /**
+     * Called when an item is let go at a new place. Returns whether the move
+     * stood: `false` where a listener refused it.
+     *
+     * Where this is not given, the controller asks the page itself, from the
+     * host: `helix-before-reorder`, then `helix-reorder`, with `kind` and
+     * every key of `all` in the new order, joined by commas in `value`. A key a
+     * filter hides keeps its place, as `placeKey` says.
+     */
+    drop?: (move: ReorderMove) => boolean;
+    /**
+     * The key of the item a key pressed in the host stands for: the one with
+     * focus, or the one `aria-activedescendant` names. Alt with Up or Down then
+     * moves that item a place at once, and Alt with Home or End to either end,
+     * as the rearrangeable listbox of the APG does, with no grip and nothing
+     * held. Alt with an arrow moves nothing where this is not given.
+     */
+    current?: (event: KeyboardEvent) => string | undefined;
+    /**
+     * Whether an item may be moved now. Where this is not given, the host's own
+     * `reorderable` says, and every item may on a host without one.
+     */
+    enabled?: () => boolean;
+    /**
+     * The grip an event passed through, and the key of the item it moves, or
+     * nothing for an event that passed through none.
+     */
+    grip: (event: Event) => {
+        element: HTMLElement;
+        key: string;
+    } | undefined;
+    /**
+     * Whether a key or a click holds the item for the arrow keys. `true` where
+     * this is not given. Data Table's columns move a place for each arrow on the
+     * grip and say `false`, so they are only dragged. A listbox's options say
+     * `false` too: the whole option is what a pointer drags, and a click on it
+     * still chooses it.
+     */
+    holds?: boolean;
+    /**
+     * The key of the item an event passed through, anywhere in it. A click there
+     * drops a held item at that place, which is the move a single pointer makes
+     * without a drag.
+     */
+    item?: (event: Event) => string | undefined;
+    /** What a drop the controller asks for itself moves: `item`, the default, or `row`. */
+    kind?: ReorderDetail['kind'];
+    /**
+     * The keys of the items the item with that key moves among, in the order
+     * they are drawn: every item of a list, or the item's siblings in a tree.
+     */
+    keys: (key: string) => readonly string[];
+    /** An item's name, for the words. */
+    name?: (key: string) => string;
+    /**
+     * The element a pointer drag copies for the drag preview: a copy of what it
+     * draws follows the pointer, raised over the page, until the item is let go
+     * or Escape puts it back. A move made with the keys draws none. No preview
+     * is drawn where this is not given.
+     *
+     * The copy is drawn in the host's `drag-preview` part, which the host's
+     * template draws with `drawDragPreview`: a manual popover in its shadow
+     * root, hidden from assistive technology, shown in the top layer so no
+     * scrolling box clips it. The host's stylesheet gives it its look. No
+     * preview is drawn where the host draws no such part.
+     */
+    preview?: (key: string) => Element | null | undefined;
+    /**
+     * Gives focus back to the item with that key, called after a move made from
+     * the keyboard stood, once the page has moved the item and focus went to the
+     * body with it. Focus the page put anywhere else is left there. Focus is left
+     * alone where this is not given.
+     */
+    refocus?: (key: string) => void;
+    /**
+     * Speaks words in the host's live region. Where this is not given, the
+     * words go to the host's `announced`, the region a collection draws, where
+     * it has one, and nowhere otherwise.
+     */
+    say?: (words: string) => void;
+    /**
+     * The box to scroll while a dragged item nears one of its edges, or `null`
+     * for the window. Where this is not given, rows down the block axis scroll
+     * the nearest box around the host's first child that scrolls that way and
+     * has more to show, or the window, and items along the inline axis scroll
+     * nothing.
+     */
+    scroller?: () => HTMLElement | null;
+    /**
+     * The words a screen reader hears. Where this is not given, they are the
+     * host's own `canceledLabel`, `droppedLabel`, `movedLabel`, and
+     * `pickedUpLabel`, which is what a family declares them as.
+     */
+    words?: () => ReorderWords;
+}
+/**
+ * Asks to move a row or an item and reports whether the move stood:
+ * `helix-before-reorder`, which can refuse it, and then `helix-reorder`, which
+ * is when you move your data.
+ */
+export declare const requestReorder: (host: HTMLElement, detail: ReorderDetail) => boolean;
+/**
+ * Moves one item of a collection to a new place, by pointer, by keyboard, and
+ * by a screen reader, and says each step in words.
+ *
+ * - **A pointer** drags an item by its grip. The page under it scrolls near an
+ *   edge, and `mark` says where a drop indicator goes.
+ * - **A key or a click** on a grip holds the item. The arrows move it, Home
+ *   and End move it to either end, Enter, Space, or a second click drops it,
+ *   and Escape puts it back. A click on another item drops it there, so one
+ *   pointer can move an item without dragging, as WCAG 2.5.7 asks.
+ * - **Alt with an arrow** moves the item focus is on a place at once, where
+ *   the host says which item that is with `current`. A collection whose own
+ *   keys are the arrows, Enter, and Space, such as a listbox or a tree, moves
+ *   its items this way.
+ *
+ * **It moves nothing.** A drop calls `drop`, and the host asks its page,
+ * which owns the items, to move them. The host reads `held` and `mark` when
+ * it renders, and this asks it for an update at each change of state.
+ *
+ * Each change of state is worked out by `reorderStep`, a pure function, and
+ * what it calls for runs here: the words, the scrolling, and the drop.
+ */
+export declare class ReorderController implements ReactiveController {
+    private readonly host;
+    private readonly options;
+    /** The state of the move. */
+    private state;
+    /** The grip a key or a click took hold of, which has to keep focus. */
+    private holder;
+    /** Where the pointer was last, for the scrolling to place the item by. */
+    private pointer;
+    /** The frame the next scroll waits for. */
+    private frame;
+    /** The copy of the dragged item that follows the pointer, while one is drawn. */
+    private shown;
+    /** Where the pointer went down on the item the preview copies. */
+    private anchor;
+    constructor(host: ReactiveControllerHost & HTMLElement, options: ReorderOptions);
+    /** The item held and where it would go, or nothing while none is. */
+    get held(): {
+        by: ReorderHold;
+        from: number;
+        key: string;
+        to: number;
+    } | undefined;
+    /**
+     * Where the drop indicator goes: before or after the item with that key, or
+     * nothing while no item is held away from its place.
+     */
+    get mark(): {
+        edge: 'after' | 'before';
+        key: string;
+    } | undefined;
+    /**
+     * Where the item with that key stands in a move, for the host to mark it:
+     * the item held, the item the drop indicator is before or after, or nothing.
+     */
+    moveOf(key: string): 'dragging' | 'drop-after' | 'drop-before' | undefined;
+    /**
+     * The `drag-preview` part, for the host's template: an empty manual popover
+     * while items may be moved, which a pointer drag fills and shows.
+     */
+    drawDragPreview(): TemplateResult | typeof nothing;
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /** Puts a held item back where it was, as Escape does. */
+    cancel(): void;
+    /** Moves the state on, and runs what the change calls for. */
+    private send;
+    /** What a change of state calls for. */
+    private enter;
+    /** Asks for a move: through `drop`, or of the page where the host gives none. */
+    private drop;
+    /** Says one of the words, with the item's name and place filled in. */
+    private speak;
+    /** The place among the others that the pointer is over, for the item with that key. */
+    private placeAt;
+    private enabled;
+    /** The page's own watch for the move it was asked for, while one is awaited. */
+    private awaiting;
+    /**
+     * Gives focus back to a moved item once the page has moved it, where moving
+     * it sent focus to the body. A page that moves the item as it hears
+     * `helix-reorder` has done so already; one that renders later changes the
+     * host's children first.
+     */
+    private follow;
+    private readonly handleDown;
+    private readonly handleMove;
+    /**
+     * Draws the drag preview: a copy of the item, where it is, in the host's
+     * `drag-preview` part, shown in the top layer. Measured before the host
+     * draws the item as dragged, so the copy is the item as it was.
+     */
+    private lift;
+    /** Moves the drag preview with the pointer. */
+    private glide;
+    /** Takes the drag preview away: hides the part and empties it. */
+    private lower;
+    /** Places the dragged item under the pointer's last reading. */
+    private drag;
+    private readonly handleUp;
+    private readonly handleCancel;
+    /**
+     * Escape while a pointer drags puts the item back. Heard on the window,
+     * since focus may be anywhere while a pointer drags, and kept from the page,
+     * so a dialog the list is in stays open.
+     */
+    private readonly handleEscape;
+    /** Starts or stops hearing the pointer on the window, and the scrolling with it. */
+    private listen;
+    /** Scrolls the box while the dragged item is near one of its edges, a frame at a time. */
+    private scroll;
+    /**
+     * A click on a grip takes hold of its item, and a second one drops it. While
+     * one is held, a click on another item drops it there. Heard in the capture
+     * phase, so the click that drops an item does not also select a row.
+     */
+    private readonly handleClick;
+    /** Takes hold of an item from its grip, which keeps focus while it is held. */
+    private take;
+    /**
+     * The keys while an item is held: the arrows, Home and End move it, Enter and
+     * Space drop it, and Escape puts it back. Heard in the capture phase and kept
+     * from everything else, so an arrow moves the item and not focus.
+     *
+     * A grip that is a native button answers Enter and Space with a click, which
+     * `handleClick` hears. Any other grip, such as a cell of a grid, is answered
+     * here.
+     */
+    private readonly handleKey;
+    /**
+     * Alt with an arrow, Home, or End: moves the item the key stands for at
+     * once, with nothing held, and says where it went. A move the page refuses
+     * is said as canceled. At an end the key is kept and nothing moves.
+     */
+    private nudge;
+    /**
+     * A pointer went down while a key or a click holds an item. Its click may
+     * drop the item on another one, so the focus it moves does not put the item
+     * back until that click has been heard.
+     */
+    private press;
+    /** Whether a pointer is down while an item is held, for `press`. */
+    private pressing;
+    /** Focus leaving the grip that holds an item puts the item back. */
+    private readonly handleFocusOut;
+    /** Puts a held item back where focus has left its grip. */
+    private keepOrCancel;
+}