@fusion.dev/helix-headless 0.145.0 → 0.146.0

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

@@ -30,10 +30,20 @@ declare const EDGES: readonly ['block-start', 'block-end', 'inline-start', 'inli
  * and draws the thumb from the two custom properties written on each
  * scrollbar. An axis whose `overflow` is `hidden` gets no scrollbar.
  *
+ * **`orientation` keeps the content to one axis.** `vertical` scrolls up and
+ * down only, and `horizontal` sideways only, so the other axis has no
+ * scrollbar, the browser's or the component's, and clips what is past it.
+ * Leave it unset to scroll both ways.
+ *
  * The viewport's `scroll` and `scrollend` are sent again from the host, which
- * is the element you hold. In React, bind them with `onScroll` and
+ * is the element you hold. A thumb dragged across the content sends one
+ * `scrollend`, once it is let go. In React, bind them with `onScroll` and
  * `onScrollEnd`.
  *
+ * **Keyboard.** The viewport is the tab stop while the content overflows, and
+ * the browser's scrolling keys move it: the arrow keys, Page Up and Page Down,
+ * Home and End, and Space. The scrollbars take no focus.
+ *
  * @since 0.1.0
  * @status stable
  * @category layout
@@ -43,7 +53,7 @@ declare const EDGES: readonly ['block-start', 'block-end', 'inline-start', 'inli
  * @slot - The content that scrolls.
  *
  * @event {Event} scroll - The content scrolled. Sent from the host, because the viewport's own does not leave the shadow root. Does not bubble.
- * @event {Event} scrollend - The content stopped scrolling. Sent from the host, as `scroll` is. Does not bubble.
+ * @event {Event} scrollend - The content stopped scrolling. Sent from the host, as `scroll` is, and once for a thumb dragged across the content. Does not bubble.
  *
  * @csspart corner - The square where the two scrollbars meet, under `scrollbars`. Hidden unless both are drawn.
  * @csspart edges - The layer that draws the cues on the inline start and end edges.
@@ -80,6 +90,11 @@ export declare class HelixHeadlessScrollArea extends HelixElement {
      * Without one there is no region: see the note on the class.
      */
     label: string;
+    /**
+     * The one axis the content scrolls along: `vertical` or `horizontal`. The
+     * other axis clips what is past it and has no scrollbar. Unset scrolls both.
+     */
+    orientation?: 'horizontal' | 'vertical';
     /**
      * Draws scrollbars of the component's own in place of the browser's, and
      * says when they show.
@@ -93,18 +108,8 @@ export declare class HelixHeadlessScrollArea extends HelixElement {
      * Absent keeps the browser's scrollbars.
      */
     scrollbars?: 'always' | 'auto' | 'hover' | 'scroll';
-    /** What each scrollbar shows, measured, and `undefined` until it has been. */
-    private bars;
-    /** Whether the content moved, or the pointer left, within the hide delay. */
-    private active;
-    /** Whether the pointer is over the scroll area. */
-    private hovered;
-    /** Whether the pointer is over a scrollbar. */
-    private over;
-    /** The thumb being dragged, if one is. */
-    private drag;
-    /** Puts the scrollbars away once nothing has moved for the hide delay. */
-    private readonly hide;
+    /** The scrollbars drawn under `scrollbars`: what they show, when, and the drag. */
+    private readonly bars;
     /**
      * Which edges have content past them, measured rather than guessed.
      */
@@ -137,45 +142,9 @@ export declare class HelixHeadlessScrollArea extends HelixElement {
      * costs.
      */
     private measure;
-    /** One axis of the box, counted from its start whichever way the line runs. */
-    private extent;
-    /**
-     * 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.
-     *
-     * Written only on a change, so a scroll that moves no thumb renders nothing.
-     */
-    private readBars;
-    /**
-     * Shows the scrollbars and starts the wait that puts them away again, under
-     * `scroll` and `hover`.
-     */
-    private wake;
-    /** 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;
-    private readonly handleVerticalDown;
-    private readonly handleHorizontalDown;
-    /** Moves the content with a dragged thumb. Nothing while no thumb is held. */
-    private readonly handleDragMove;
-    private readonly handleDragEnd;
-    private readonly handleBarEnter;
-    private readonly handleBarLeave;
-    private readonly handleEnter;
-    private readonly handleLeave;
     /** Measures, shows the scrollbars, and sends the event on from the host. */
     private readonly handleScroll;
+    /** Sends the event on from the host, except the ones a thumb drag holds back. */
     private readonly handleScrollEnd;
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -184,6 +153,8 @@ export declare class HelixHeadlessScrollArea extends HelixElement {
     private watchContent;
     protected updated(changed: PropertyValues): void;
     private readonly handleSlotChange;
+    /** The axis `orientation` takes away, clipped where the content would overflow it. */
+    private get clipped();
     protected render(): TemplateResult;
     /**
      * The scrollbars, the thumbs in them and the corner.

package/dist/scroll-area/root/scroll-area-root.js

@@ -4,20 +4,22 @@ 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 { capturePointer, customElement, DelayController, HelixElement, isRtl, } from '@fusion.dev/helix-core';
+import { customElement, HelixElement } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
-import { hasScrollbar, offsetAt, scrollFraction, scrollPerPixel, showsScrollbar, thumbFraction, } from '../scrollbar.js';
+import { ScrollbarController } from '../scrollbar-controller.js';
 const EDGES = ['block-start', 'block-end', 'inline-start', 'inline-end'];
 let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement {
     constructor() {
         super(...arguments);
         this.hideDelay = 600;
         this.label = '';
-        this.active = false;
-        this.hovered = false;
-        this.over = false;
-        this.hide = new DelayController(this, { renders: false });
+        this.bars = new ScrollbarController(this, {
+            box: () => this.scroller,
+            hideDelay: () => this.hideDelay,
+            mode: () => this.scrollbars,
+            scrollEnd: () => this.dispatchEvent(new Event('scrollend')),
+        });
         this.more = [];
         this.scrolls = false;
         this.measure = () => {
@@ -26,72 +28,39 @@ let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement
                 return;
             }
             const slack = 1;
+            const block = this.orientation !== 'horizontal';
+            const inline = this.orientation !== 'vertical';
             const found = [];
-            if (box.scrollTop > slack) {
+            if (block && box.scrollTop > slack) {
                 found.push('block-start');
             }
-            if (box.scrollTop + box.clientHeight < box.scrollHeight - slack) {
+            if (block && box.scrollTop + box.clientHeight < box.scrollHeight - slack) {
                 found.push('block-end');
             }
             const along = Math.abs(box.scrollLeft);
-            if (along > slack) {
+            if (inline && along > slack) {
                 found.push('inline-start');
             }
-            if (along + box.clientWidth < box.scrollWidth - slack) {
+            if (inline && along + box.clientWidth < box.scrollWidth - slack) {
                 found.push('inline-end');
             }
             this.more = found;
-            this.scrolls = box.scrollHeight > box.clientHeight || box.scrollWidth > box.clientWidth;
+            this.scrolls =
+                (block && box.scrollHeight > box.clientHeight) ||
+                    (inline && box.scrollWidth > box.clientWidth);
             if (this.scrollbars) {
-                this.readBars(box);
-            }
-        };
-        this.handleVerticalDown = (event) => {
-            this.grab(event, 'vertical');
-        };
-        this.handleHorizontalDown = (event) => {
-            this.grab(event, 'horizontal');
-        };
-        this.handleDragMove = (event) => {
-            const drag = this.drag;
-            const box = this.scroller;
-            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;
-            this.wake();
-            this.requestUpdate();
-        };
-        this.handleBarEnter = () => {
-            this.over = true;
-        };
-        this.handleBarLeave = () => {
-            this.over = false;
-            this.wake();
-        };
-        this.handleEnter = () => {
-            this.hovered = true;
-        };
-        this.handleLeave = () => {
-            this.hovered = false;
-            if (this.scrollbars === 'hover') {
-                this.wake();
+                this.bars.read(box);
             }
         };
         this.handleScroll = (event) => {
             this.measure();
-            this.wake();
+            this.bars.wake();
             this.relayNativeEvent(event);
         };
         this.handleScrollEnd = (event) => {
-            this.relayNativeEvent(event);
+            if (!this.bars.holdsScrollEnd()) {
+                this.relayNativeEvent(event);
+            }
         };
         this.handleSlotChange = (event) => {
             const slot = event.target;
@@ -104,84 +73,8 @@ let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement
     get scroller() {
         return this.partNamed('viewport');
     }
-    extent(box, axis) {
-        return axis === 'vertical'
-            ? { client: box.clientHeight, offset: box.scrollTop, scroll: box.scrollHeight }
-            : { client: box.clientWidth, offset: Math.abs(box.scrollLeft), scroll: box.scrollWidth };
-    }
-    readBars(box) {
-        const mode = this.scrollbars ?? 'auto';
-        const style = getComputedStyle(box);
-        const bar = (axis, overflow) => {
-            const extent = this.extent(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;
-        }
-    }
-    wake() {
-        if (this.scrollbars !== 'scroll' && this.scrollbars !== 'hover') {
-            return;
-        }
-        this.active = true;
-        this.hide.start(this.hideDelay, () => {
-            this.active = false;
-        });
-    }
-    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.scroller;
-        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 = this.extent(box, axis);
-        const pointer = vertical ? event.clientY : event.clientX;
-        let from = extent.offset;
-        if (!thumb.contains(event.target)) {
-            const along = vertical
-                ? pointer - track.top
-                : rtl
-                    ? track.right - pointer
-                    : pointer - track.left;
-            from = offsetAt(extent, along, 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.requestUpdate();
-    }
     connectedCallback() {
         super.connectedCallback();
-        this.addEventListener('pointerenter', this.handleEnter);
-        this.addEventListener('pointerleave', this.handleLeave);
         this.watcher = new ResizeObserver(this.measure);
         if (this.hasUpdated) {
             this.watchContent();
@@ -189,14 +82,8 @@ let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement
     }
     disconnectedCallback() {
         super.disconnectedCallback();
-        this.removeEventListener('pointerenter', this.handleEnter);
-        this.removeEventListener('pointerleave', this.handleLeave);
         this.watcher?.disconnect();
         this.watcher = undefined;
-        this.drag = undefined;
-        this.active = false;
-        this.hovered = false;
-        this.over = false;
     }
     firstUpdated(changed) {
         super.firstUpdated?.(changed);
@@ -217,10 +104,13 @@ let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement
     }
     updated(changed) {
         super.updated?.(changed);
-        if (changed.has('scrollbars') && this.hasUpdated && this.scrollbars) {
+        if (changed.has('orientation') && this.hasUpdated) {
+            this.measure();
+        }
+        else if (changed.has('scrollbars') && this.scrollbars) {
             const box = this.scroller;
             if (box) {
-                this.readBars(box);
+                this.bars.read(box);
             }
         }
         this.toggleState('scrolls', this.scrolls);
@@ -228,14 +118,21 @@ let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement
         this.toggleState('more-block-end', this.more.includes('block-end'));
         this.toggleState('more-inline-start', this.more.includes('inline-start'));
         this.toggleState('more-inline-end', this.more.includes('inline-end'));
-        const drawn = this.scrollbars ? this.bars : undefined;
+        const drawn = this.scrollbars ? this.bars.bars : undefined;
         this.toggleState('scrollbar-horizontal', drawn?.horizontal.drawn === true);
         this.toggleState('scrollbar-vertical', drawn?.vertical.drawn === true);
     }
+    get clipped() {
+        if (this.orientation === 'vertical') {
+            return 'overflow-x: hidden';
+        }
+        return this.orientation === 'horizontal' ? 'overflow-y: hidden' : nothing;
+    }
     render() {
         return html `<div
       data-scroller
       part="viewport"
+      style=${this.clipped}
       role=${this.label ? 'region' : nothing}
       aria-label=${this.label || nothing}
       tabindex=${this.scrolls ? '0' : nothing}
@@ -252,16 +149,12 @@ let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement
     <div
       part="edges"
       aria-hidden="true"
-    ></div>${this.scrollbars ? this.renderScrollbars(this.scrollbars) : nothing}`;
+    ></div>${this.scrollbars ? this.renderScrollbars() : nothing}`;
     }
-    renderScrollbars(mode) {
-        const bars = this.bars;
-        const moment = {
-            active: this.active,
-            held: this.over || this.drag !== undefined,
-            hovered: this.hovered,
-        };
-        const shown = showsScrollbar(mode, moment);
+    renderScrollbars() {
+        const controller = this.bars;
+        const bars = controller.bars;
+        const shown = controller.shown;
         const facts = (bar) => bar
             ? `--scroll-area-thumb-fraction: ${bar.thumb}; --scroll-area-scroll-fraction: ${bar.along}`
             : nothing;
@@ -272,13 +165,13 @@ let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement
         aria-hidden="true"
         ?hidden=${!vertical}
         style=${facts(bars?.vertical)}
-        @pointerdown=${this.handleVerticalDown}
-        @pointermove=${this.handleDragMove}
-        @pointerup=${this.handleDragEnd}
-        @pointercancel=${this.handleDragEnd}
-        @lostpointercapture=${this.handleDragEnd}
-        @pointerenter=${this.handleBarEnter}
-        @pointerleave=${this.handleBarLeave}
+        @pointerdown=${controller.handleVerticalDown}
+        @pointermove=${controller.handleDragMove}
+        @pointerup=${controller.handleDragEnd}
+        @pointercancel=${controller.handleDragEnd}
+        @lostpointercapture=${controller.handleDragEnd}
+        @pointerenter=${controller.handleBarEnter}
+        @pointerleave=${controller.handleBarLeave}
       >
         <div part="thumb thumb-vertical"></div>
       </div>
@@ -287,13 +180,13 @@ let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement
         aria-hidden="true"
         ?hidden=${!horizontal}
         style=${facts(bars?.horizontal)}
-        @pointerdown=${this.handleHorizontalDown}
-        @pointermove=${this.handleDragMove}
-        @pointerup=${this.handleDragEnd}
-        @pointercancel=${this.handleDragEnd}
-        @lostpointercapture=${this.handleDragEnd}
-        @pointerenter=${this.handleBarEnter}
-        @pointerleave=${this.handleBarLeave}
+        @pointerdown=${controller.handleHorizontalDown}
+        @pointermove=${controller.handleDragMove}
+        @pointerup=${controller.handleDragEnd}
+        @pointercancel=${controller.handleDragEnd}
+        @lostpointercapture=${controller.handleDragEnd}
+        @pointerenter=${controller.handleBarEnter}
+        @pointerleave=${controller.handleBarLeave}
       >
         <div part="thumb thumb-horizontal"></div>
       </div>
@@ -310,21 +203,12 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessScrollArea.prototype, "label", void 0);
+__decorate([
+    property()
+], HelixHeadlessScrollArea.prototype, "orientation", void 0);
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessScrollArea.prototype, "scrollbars", void 0);
-__decorate([
-    state()
-], HelixHeadlessScrollArea.prototype, "bars", void 0);
-__decorate([
-    state()
-], HelixHeadlessScrollArea.prototype, "active", void 0);
-__decorate([
-    state()
-], HelixHeadlessScrollArea.prototype, "hovered", void 0);
-__decorate([
-    state()
-], HelixHeadlessScrollArea.prototype, "over", void 0);
 __decorate([
     state()
 ], HelixHeadlessScrollArea.prototype, "more", void 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;
+}