@fusion.dev/helix-headless 0.145.0 → 0.147.0

package/dist/scroll-area/scrollbar-controller.d.ts

@@ -0,0 +1,111 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import { type Axis, type Scrollbars } from './scrollbar.js';
+/** What one drawn scrollbar shows: whether it is there, and its thumb's facts. */
+export interface Bar {
+    /** Whether the axis has a scrollbar at all. See `hasScrollbar`. */
+    drawn: boolean;
+    /** How far along the axis is scrolled, from 0 to 1. */
+    along: number;
+    /** The share of the track the thumb covers, from 0 to 1. */
+    thumb: number;
+}
+/** What the controller needs of the scroll area it serves. */
+export interface ScrollbarOptions {
+    /** The box that scrolls, or null before it renders. */
+    box: () => HTMLElement | null;
+    /** The host's `hide-delay`, in milliseconds. */
+    hideDelay: () => number;
+    /** The host's `scrollbars`, or undefined for the browser's own. */
+    mode: () => Scrollbars | undefined;
+    /** Sends a `scrollend` from the host, for the one a drag held back. */
+    scrollEnd: () => void;
+}
+/**
+ * The scrollbars a scroll area draws under `scrollbars`: what each shows, when
+ * they show, and the thumb a pointer drags.
+ *
+ * **A controller, so the element only draws.** It holds the drag, whether the
+ * pointer is over the area or a scrollbar, and the wait that puts the
+ * scrollbars away, and asks the host to render when any of them changes.
+ *
+ * **A drag sends one `scrollend`.** The thumb moves the content by
+ * `scrollTo`, and the browser ends each of those steps with a `scrollend` of
+ * its own, so a drag sent a burst of them. While a thumb is held they are held
+ * back, and once it is let go one is sent: the browser's own for the last
+ * step, or the held one where none comes.
+ */
+export declare class ScrollbarController implements ReactiveController {
+    /** What each scrollbar shows, measured, and `undefined` until it has been. */
+    bars: Record<Axis, Bar> | undefined;
+    /** Whether the content moved, or the pointer left, within the hide delay. */
+    active: boolean;
+    /** Whether the pointer is over the scroll area. */
+    hovered: boolean;
+    /** Whether the pointer is over a scrollbar. */
+    over: boolean;
+    /** The thumb being dragged, if one is. */
+    private drag;
+    /** Whether a `scrollend` was held back by a drag and not sent yet. */
+    private heldEnd;
+    private readonly host;
+    private readonly options;
+    /** Puts the scrollbars away once nothing has moved for the hide delay. */
+    private readonly hide;
+    /** Waits after a drag for the browser's last `scrollend`. */
+    private readonly settle;
+    constructor(host: ReactiveControllerHost & HTMLElement, options: ScrollbarOptions);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /** Whether a thumb is held. */
+    get dragging(): boolean;
+    /** Whether the scrollbars that are drawn are showing at this moment. */
+    get shown(): boolean;
+    /**
+     * Reads what each scrollbar shows off the box.
+     *
+     * An axis scrolls unless its `overflow` says it cannot. An empty reading is a
+     * harness with no layout, where the mark `core` puts on the viewport is
+     * `overflow: auto` on both axes, so it counts as one that scrolls.
+     *
+     * Asks for a render only on a change, so a scroll that moves no thumb
+     * renders nothing.
+     */
+    read(box: HTMLElement): void;
+    /**
+     * Shows the scrollbars and starts the wait that puts them away again, under
+     * `scroll` and `hover`.
+     */
+    wake(): void;
+    /**
+     * Whether to hold back a `scrollend` the viewport sent: true while a thumb is
+     * held. One arriving after the drag ends is the browser's last, and stands
+     * for the one held back.
+     */
+    holdsScrollEnd(): boolean;
+    /** Writes one of the moment's facts, and renders where it changed. */
+    private set;
+    /** Sends the content to `offset` along an axis, counted from its start. */
+    private scrollAlong;
+    /**
+     * Takes hold of a thumb, or presses the track.
+     *
+     * A press on the track sends the thumb's middle to the press first, and the
+     * drag carries on from there, so a press and a drag are one gesture as they
+     * are on the browser's own scrollbar. `preventDefault` keeps the press from
+     * starting a text selection, and from moving focus off the viewport.
+     */
+    private grab;
+    readonly handleVerticalDown: (event: PointerEvent) => void;
+    readonly handleHorizontalDown: (event: PointerEvent) => void;
+    /** Moves the content with a dragged thumb. Nothing while no thumb is held. */
+    readonly handleDragMove: (event: PointerEvent) => void;
+    /**
+     * Lets go of the thumb. A `scrollend` the drag held back goes out once the
+     * browser's last one has had a frame or two to arrive and has not.
+     */
+    readonly handleDragEnd: () => void;
+    readonly handleBarEnter: () => void;
+    readonly handleBarLeave: () => void;
+    private readonly handleEnter;
+    private readonly handleLeave;
+}

package/dist/scroll-area/scrollbar-controller.js

@@ -0,0 +1,172 @@
+import { capturePointer, DelayController, isRtl } from '@fusion.dev/helix-core';
+import { alongTrack, extentOf, hasScrollbar, offsetAt, scrollFraction, scrollPerPixel, showsScrollbar, thumbFraction, } from './scrollbar.js';
+const SETTLE = 100;
+export class ScrollbarController {
+    constructor(host, options) {
+        this.active = false;
+        this.hovered = false;
+        this.over = false;
+        this.heldEnd = false;
+        this.handleVerticalDown = (event) => {
+            this.grab(event, 'vertical');
+        };
+        this.handleHorizontalDown = (event) => {
+            this.grab(event, 'horizontal');
+        };
+        this.handleDragMove = (event) => {
+            const drag = this.drag;
+            const box = this.options.box();
+            if (!drag || !box) {
+                return;
+            }
+            const pointer = drag.axis === 'vertical' ? event.clientY : event.clientX;
+            this.scrollAlong(box, drag.axis, drag.from + (pointer - drag.pointer) * drag.sign * drag.perPixel);
+        };
+        this.handleDragEnd = () => {
+            if (!this.drag) {
+                return;
+            }
+            this.drag = undefined;
+            if (this.heldEnd) {
+                this.settle.start(SETTLE, () => {
+                    if (this.heldEnd) {
+                        this.heldEnd = false;
+                        this.options.scrollEnd();
+                    }
+                });
+            }
+            this.wake();
+            this.host.requestUpdate();
+        };
+        this.handleBarEnter = () => {
+            this.set('over', true);
+        };
+        this.handleBarLeave = () => {
+            this.set('over', false);
+            this.wake();
+        };
+        this.handleEnter = () => {
+            this.set('hovered', true);
+        };
+        this.handleLeave = () => {
+            this.set('hovered', false);
+            if (this.options.mode() === 'hover') {
+                this.wake();
+            }
+        };
+        this.host = host;
+        this.options = options;
+        this.hide = new DelayController(host, { renders: false });
+        this.settle = new DelayController(host, { renders: false });
+        host.addController(this);
+    }
+    hostConnected() {
+        this.host.addEventListener('pointerenter', this.handleEnter);
+        this.host.addEventListener('pointerleave', this.handleLeave);
+    }
+    hostDisconnected() {
+        this.host.removeEventListener('pointerenter', this.handleEnter);
+        this.host.removeEventListener('pointerleave', this.handleLeave);
+        this.drag = undefined;
+        this.heldEnd = false;
+        this.active = false;
+        this.hovered = false;
+        this.over = false;
+    }
+    get dragging() {
+        return this.drag !== undefined;
+    }
+    get shown() {
+        const mode = this.options.mode();
+        return mode
+            ? showsScrollbar(mode, {
+                active: this.active,
+                held: this.over || this.drag !== undefined,
+                hovered: this.hovered,
+            })
+            : false;
+    }
+    read(box) {
+        const mode = this.options.mode() ?? 'auto';
+        const style = getComputedStyle(box);
+        const bar = (axis, overflow) => {
+            const extent = extentOf(box, axis);
+            return {
+                along: scrollFraction(extent),
+                drawn: hasScrollbar(mode, !['clip', 'hidden', 'visible'].includes(overflow), extent.offset > 1 || extent.client < extent.scroll - 1),
+                thumb: thumbFraction(extent),
+            };
+        };
+        const next = {
+            horizontal: bar('horizontal', style.overflowX),
+            vertical: bar('vertical', style.overflowY),
+        };
+        if (JSON.stringify(next) !== JSON.stringify(this.bars)) {
+            this.bars = next;
+            this.host.requestUpdate();
+        }
+    }
+    wake() {
+        const mode = this.options.mode();
+        if (mode !== 'scroll' && mode !== 'hover') {
+            return;
+        }
+        this.set('active', true);
+        this.hide.start(this.options.hideDelay(), () => {
+            this.set('active', false);
+        });
+    }
+    holdsScrollEnd() {
+        if (this.drag) {
+            this.heldEnd = true;
+            return true;
+        }
+        if (this.heldEnd) {
+            this.heldEnd = false;
+            this.settle.cancel();
+        }
+        return false;
+    }
+    set(key, value) {
+        if (this[key] !== value) {
+            this[key] = value;
+            this.host.requestUpdate();
+        }
+    }
+    scrollAlong(box, axis, offset) {
+        box.scrollTo(axis === 'vertical'
+            ? { behavior: 'instant', top: offset }
+            : { behavior: 'instant', left: isRtl(box) ? -offset : offset });
+    }
+    grab(event, axis) {
+        const box = this.options.box();
+        const bar = event.currentTarget;
+        const thumb = bar.querySelector('[part~="thumb"]');
+        if (event.button !== 0 || !box || !thumb) {
+            return;
+        }
+        event.preventDefault();
+        const vertical = axis === 'vertical';
+        const rtl = !vertical && isRtl(box);
+        const track = bar.getBoundingClientRect();
+        const held = thumb.getBoundingClientRect();
+        const length = vertical ? track.height : track.width;
+        const size = vertical ? held.height : held.width;
+        const extent = extentOf(box, axis);
+        const pointer = vertical ? event.clientY : event.clientX;
+        let from = extent.offset;
+        if (!thumb.contains(event.target)) {
+            from = offsetAt(extent, alongTrack(pointer, track, axis, rtl), length, size);
+            this.scrollAlong(box, axis, from);
+        }
+        this.drag = {
+            axis,
+            from,
+            perPixel: scrollPerPixel(extent, length, size),
+            pointer,
+            sign: rtl ? -1 : 1,
+        };
+        capturePointer(bar, event.pointerId);
+        this.host.requestUpdate();
+    }
+}

package/dist/scroll-area/scrollbar.d.ts

@@ -1,13 +1,16 @@
-/**
- * The arithmetic behind the scrollbars a scroll area draws under `scrollbars`.
- *
- * Every length here is along one axis and counted from that axis' start, which
- * is the right-hand edge on a right-to-left page for the horizontal one. The
- * component turns a pointer and a `scrollLeft` into those counts, so nothing
- * below has to know which way the line runs.
- */
 /** Which scrollbars are drawn, and when. Absent keeps the browser's own. */
 export type Scrollbars = 'always' | 'auto' | 'hover' | 'scroll';
+/** The two axes a scrollbar runs along. */
+export type Axis = 'horizontal' | 'vertical';
+/** The box a scrollbar reads, as the numbers it reads off it. */
+export interface Box {
+    clientHeight: number;
+    clientWidth: number;
+    scrollHeight: number;
+    scrollLeft: number;
+    scrollTop: number;
+    scrollWidth: number;
+}
 /** One axis of the viewport, read off the box. */
 export interface Extent {
     /** How much of the content the viewport shows, `clientHeight` or `clientWidth`. */
@@ -63,3 +66,19 @@ export declare const showsScrollbar: (mode: Scrollbars, moment: {
     held: boolean;
     hovered: boolean;
 }) => boolean;
+/**
+ * One axis of a box, counted from its start whichever way the line runs: a
+ * right-to-left box counts `scrollLeft` down from zero, so its offset is the
+ * distance from zero.
+ */
+export declare const extentOf: (box: Box, axis: Axis) => Extent;
+/**
+ * Where a pointer is along a track, counted from the track's start: its top,
+ * or its left edge, or its right edge on a right-to-left page.
+ */
+export declare const alongTrack: (pointer: number, track: {
+    bottom: number;
+    left: number;
+    right: number;
+    top: number;
+}, axis: Axis, rtl: boolean) => number;

package/dist/scroll-area/scrollbar.js

@@ -1,4 +1,4 @@
-const clamp = (value, low, high) => Math.min(Math.max(value, low), high);
+import { clamp } from '@fusion.dev/helix-core';
 export const thumbFraction = ({ client, scroll }) => scroll <= 0 ? 1 : clamp(client / scroll, 0, 1);
 export const scrollFraction = ({ client, offset, scroll }) => {
     const room = scroll - client;
@@ -22,3 +22,12 @@ export const showsScrollbar = (mode, moment) => {
     }
     return moment.active || moment.held || (mode === 'hover' && moment.hovered);
 };
+export const extentOf = (box, axis) => axis === 'vertical'
+    ? { client: box.clientHeight, offset: box.scrollTop, scroll: box.scrollHeight }
+    : { client: box.clientWidth, offset: Math.abs(box.scrollLeft), scroll: box.scrollWidth };
+export const alongTrack = (pointer, track, axis, rtl) => {
+    if (axis === 'vertical') {
+        return pointer - track.top;
+    }
+    return rtl ? track.right - pointer : pointer - track.left;
+};

package/dist/select/align.d.ts

@@ -0,0 +1,47 @@
+/** A box on the screen, in viewport pixels. */
+export interface Box {
+    height: number;
+    left: number;
+    top: number;
+    width: number;
+}
+/** What places a list over its trigger. */
+export interface Over {
+    /** How far inside the screen's edges the list stays, in pixels. */
+    margin: number;
+    /** The option to sit on the trigger: its top within the list, and its height. */
+    option: {
+        height: number;
+        top: number;
+    };
+    /** The list's own size. */
+    panel: {
+        height: number;
+        width: number;
+    };
+    /** Whether the line of text runs right to left, which aligns the end edges. */
+    rtl: boolean;
+    /** The trigger. */
+    trigger: Box;
+    /** The screen. */
+    viewport: {
+        height: number;
+        width: number;
+    };
+}
+/**
+ * Where a list opened over its trigger goes, so the option it opens on sits
+ * where the trigger is: the native select's place on macOS, and Radix's
+ * `item-aligned`.
+ *
+ * The option's middle on the trigger's middle, then kept on the screen: a
+ * list that would run off the bottom moves up, and one that would run off the
+ * top moves down, so near an edge the option is beside the trigger rather than
+ * on it. A list taller than the screen starts at its top edge. The start edges
+ * line up, the left in English and the right in Arabic, kept on the screen the
+ * same way.
+ */
+export declare const over: ({ margin, option, panel, rtl, trigger, viewport, }: Over) => {
+    left: number;
+    top: number;
+};

package/dist/select/align.js

@@ -0,0 +1,7 @@
+export const over = ({ margin, option, panel, rtl, trigger, viewport, }) => {
+    const centered = trigger.top + trigger.height / 2 - (option.top + option.height / 2);
+    const top = Math.max(margin, Math.min(centered, viewport.height - margin - panel.height));
+    const start = rtl ? trigger.left + trigger.width - panel.width : trigger.left;
+    const left = Math.max(margin, Math.min(start, viewport.width - margin - panel.width));
+    return { left: Math.round(left), top: Math.round(top) };
+};

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

@@ -48,6 +48,7 @@ declare const HelixHeadlessSelect_base: (new (...args: any[]) => import("@fusion
  * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the list closes. Cancelable: canceling it keeps the list open and leaves the decision to you.
  * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the list opens. Cancelable: canceling it keeps the list closed and leaves the decision to you.
  * @event {HelixFilterEvent} helix-filter - Fired as the user types in the filter field of a `filterable` select, with the text the list is filtered by. Cancelable: cancel it to leave the list unfiltered and filter the options yourself.
+ * @event {HelixLoadMoreEvent} helix-load-more - Fired once the list is scrolled within a screen of its end, once for each number of options, and not while `loading` is set. Add the next page and set `loading` while you fetch it.
  * @event {Event} input - Fired after the value changes.
  * @event {ToggleEvent} toggle - Fired after the list opens or closes, with `newState` and `oldState`.
  *
@@ -57,6 +58,7 @@ declare const HelixHeadlessSelect_base: (new (...args: any[]) => import("@fusion
  * @csspart label - The label above the trigger.
  * @csspart listbox - The list inside the panel.
  * @csspart listbox-empty - The text shown when the filter hides every option.
+ * @csspart listbox-error - The inner list's `error` part, shown while its `load-error` is set.
  * @csspart listbox-feedback - The inner list's message that says what is wrong with the value.
  * @csspart listbox-filter-icon - The icon beside the filter field.
  * @csspart listbox-filter-mark - The default icon beside the filter field, shown when none is slotted.
@@ -71,6 +73,9 @@ declare const HelixHeadlessSelect_base: (new (...args: any[]) => import("@fusion
  * @csspart trigger - The closed control, which shows the chosen value.
  * @csspart value - The chosen option's text inside the trigger.
  *
+ * @cssproperty --floating-anchor-inline-size - The trigger's width, written on the panel while it is open, as in `min-inline-size: var(--floating-anchor-inline-size)`. Read it; a value set here is written over.
+ * @cssproperty --floating-available-block-size - The room between the panel and the edge of the screen it opens toward, written on the panel while it is open. Read it; a value set here is written over.
+ *
  * @cssstate invalid - The control has an error to show, from the browser's validation or from your `feedback`.
  * @cssstate open - While the list is open.
  */
@@ -87,6 +92,29 @@ export declare class HelixHeadlessSelect extends HelixHeadlessSelect_base {
      * the filtering, the empty state and the keyboard.
      */
     filterable: boolean;
+    /**
+     * Whether the trigger holds its group's tab stop.
+     *
+     * A toolbar keeps one tab stop across its controls, and writing `tabindex`
+     * onto this element would change markup the consumer rendered, which a React
+     * consumer's hydration reports. A toolbar sets this property instead, and
+     * the stop moves on the trigger inside the shadow root, as Button's does.
+     *
+     * No attribute, because it is coordination between elements rather than
+     * anything a consumer sets.
+     */
+    focusable: boolean;
+    /**
+     * The open list's name where nothing names the Select, read by screen
+     * readers. The list has no visible name.
+     *
+     * A Select named by `label`, `aria-label`, `aria-labelledby` or a `<label>`
+     * gives its list that name, and this is not used. Unnamed, the Select is
+     * reported once by the missing-name warning, and its list is not reported a
+     * second time for a name the page never wrote: the list is this element's,
+     * and so is the fallback. Combobox calls its list the same.
+     */
+    listLabel: string;
     /**
      * Whether the options are still loading.
      *
@@ -107,6 +135,18 @@ export declare class HelixHeadlessSelect extends HelixHeadlessSelect_base {
      * Shown on the trigger while nothing is chosen.
      */
     placeholder: string;
+    /**
+     * Where the list opens: `floating`, under the trigger and above it where
+     * there is no room, or `item-aligned`, over the trigger with the chosen
+     * option where the trigger is, as a native select does on macOS and Radix
+     * Select does by default.
+     *
+     * Over the trigger, a reader's eye stays on the answer as the list opens
+     * round it, and a short move reaches the options either side. Near an edge
+     * of the screen the list moves to stay on it, so the option may sit beside
+     * the trigger rather than on it. It follows the page as it scrolls.
+     */
+    position: 'floating' | 'item-aligned';
     /**
      * What the trigger shows for the chosen options: a function given them, in
      * the order they appear, that returns text, an element or a Lit template.
@@ -213,8 +253,26 @@ export declare class HelixHeadlessSelect extends HelixHeadlessSelect_base {
     private readonly handleLinkFollowed;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /**
+     * Puts the open list over the trigger, with the option it opened on where
+     * the trigger is, for `position="item-aligned"`.
+     *
+     * Measured once the list has drawn and scrolled to that option, and again as
+     * the page scrolls or the window changes size. The offset of the option in
+     * the list is read from the boxes on screen and divided by the list's scale,
+     * since a styled list opens from a little under full size. Written as the
+     * floating controller writes a position, so the same entrance runs and the
+     * controller takes it back on close.
+     */
+    private readonly alignOver;
+    /** The option the open list was put over the trigger by. */
+    private alignedTo;
+    /** Stops following the page, once the list over the trigger closes. */
+    private stopAligning;
     /** Opens the list with the highlight where the opening key says. */
     private openAt;
+    /** Puts focus on the trigger, which is what a toolbar moving its stop here asks. */
+    focus(options?: FocusOptions): void;
     /** Closes the list and puts focus back where it came from. */
     private close;
     private readonly handleChange;
@@ -276,6 +334,19 @@ export declare class HelixHeadlessSelect extends HelixHeadlessSelect_base {
      * cannot change.
      */
     protected renderIndicator(): TemplateResult;
+    /**
+     * What names the list once it opens, read through core's `hostWords` in
+     * the order a browser names the host: its `aria-labelledby`, its
+     * `aria-label`, the `label`, then a `<label>` for it.
+     *
+     * **Words rather than a reference**, because the list is inside another
+     * element's shadow root and neither an IDREF nor the host's labels reach it.
+     * Read as the list renders, which opening it makes happen, so a label
+     * changed while the list is closed is read when it next opens. Without the
+     * last two routes a Select named by a `<label for>` opened onto a listbox
+     * with no name, which the missing-name warning reported.
+     */
+    private get listName();
     /**
      * What names the trigger: the label, then the choice.
      *