@fusion.dev/helix-core 0.143.0 → 0.145.0

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

@@ -63,6 +63,16 @@ export interface Window {
     /** Index one past the last item rendered. */
     last: number;
 }
+/** Where `reveal` puts an item, and how it gets there. */
+export interface RevealOptions {
+    /**
+     * Where the item lands: the least distance that shows it whole (`nearest`,
+     * the default), or at the box's `start`, `center` or `end`.
+     */
+    align?: 'center' | 'end' | 'nearest' | 'start';
+    /** The platform's scroll behavior. Instant when left out. */
+    behavior?: ScrollBehavior;
+}
 /**
  * Works out which slice of a long set is worth rendering.
  *
@@ -86,35 +96,14 @@ export interface Window {
  * track, so the room the absent rows would have taken is left as padding before
  * and after. A reader dragging that thumb is dragging against the real length.
  *
- * **What it does not do, and the reason is narrower than it first looks.** True
- * virtualization means never creating the rows that are not on screen, and that
- * needs the set as *data*. Two channels are shut: a consumer's items arrive as
- * light-DOM children, which exist by the time this could decide not to create
- * them, and an `items` property cannot survive React hydration, which skips
- * every property it would have to apply imperatively (see `bindReactHandler`,
- * and the note in the rules that objects and functions have that bug and are
- * not fixed).
- *
- * **A third channel is open.** Data as *text*
- * in the markup, a `<script type="application/json">` child or an attribute, is
- * neither a property nor a node per row: React's hydration bug cannot touch text
- * it renders as a child, a server emits it, and the node count is one. The
- * charts already read data out of the document this way, `for="<id>"` at a real
- * `<table>`, so the pattern is in the library rather than being invented for
- * this.
- *
- * So the thing actually blocked is the *row template*. Turning an item into
- * markup wants either a render function, which is a function property and dies
- * on the same bug, or a `<template>` with named holes, which survives because it
- * is markup and which no component here asks anyone to write. That is a decision
- * about what this library is willing to look like, not a platform limit, and it
- * is open at #71.
- *
- * So what this buys is the expensive half rather than all of it: the rows
- * outside the window are not laid out and not painted, which is where the time
- * goes in a long list, and the node count stays. That is worth having and it is
- * not worth calling something it is not. An element that windows children it
- * was handed is not a virtual list, whatever it is named.
+ * **The set arrives as data**, which is what lets a host create only the rows
+ * in the window. A host takes it through a property (an `items` array, which
+ * `applyReactProperties` carries across React hydration with every other object
+ * property) or as text in the markup (a `<script type="application/json">`
+ * named by `for`, which a server emits and which is one node whatever the
+ * row count). A host that is handed its rows as light-DOM children still gets
+ * the expensive half from this: the rows outside the window are not laid out
+ * and not painted, and the node count stays.
  *
  * **One estimate, not per-row measurement.** Measuring every row to place it is
  * how a virtual list ends up reading the layout it is trying to avoid, and it
@@ -166,6 +155,39 @@ export declare class VirtualizeController implements ReactiveController {
      * on screen plus the overscan, whatever the set's length.
      */
     private placed;
+    /**
+     * The items on screen, with no overscan: `first` is the item at the top of
+     * the box and `last` is one past the item at its bottom, so
+     * `items.slice(first, last)` is what a reader sees.
+     *
+     * For a host that reports what is visible, where `window` is what is drawn.
+     * An empty span (`first === last`) while the box has no height or the set
+     * no items.
+     */
+    visible(): {
+        first: number;
+        last: number;
+    };
+    /**
+     * How much of the set lies below the bottom of the box, in pixels.
+     *
+     * For a host that asks for more items as a reader nears the end. Read from
+     * the arithmetic and not from `scrollHeight`, which also counts whatever the
+     * host draws around the rows.
+     */
+    remaining(): number;
+    /**
+     * The two spacers' heights for the window, with item `kept` drawn too.
+     *
+     * For a host that keeps an item outside the window drawn, the row holding
+     * focus say. The item takes its own room out of the spacer on its side, so
+     * the scrollbar still measures the set. Every host that keeps a focused row
+     * asks this, so the arithmetic is written once.
+     */
+    spacers(kept?: number): {
+        after: number;
+        before: number;
+    };
     /**
      * Measures what was just drawn, and holds the reader still if it moved.
      *
@@ -206,14 +228,25 @@ export declare class VirtualizeController implements ReactiveController {
      */
     sizeOf(index: number): number;
     /**
-     * Scrolls the box the least distance that shows item `index` whole.
+     * Scrolls the box to show item `index`.
+     *
+     * By default the least distance that shows it whole, for a host moving focus
+     * to an item outside the window, whose own element cannot be scrolled to
+     * because it is not drawn where it belongs. `inset` is how far into the box
+     * the items start, for a heading that sticks at its top and covers that much
+     * of every item scrolled under it.
      *
-     * For a host moving focus to an item outside the window, whose own element
-     * cannot be scrolled to because it is not drawn where it belongs. `inset` is
-     * how far into the box the items start, for a heading that sticks at its
-     * top and covers that much of every item scrolled under it.
+     * `align` puts the item at the box's `start`, `center` or `end` instead, and
+     * `behavior` is the platform's, for a host whose consumer asked to be taken
+     * to an item. A smooth scroll moves the window through the box's own
+     * `scroll` events, the same as a reader scrolling.
+     */
+    reveal(index: number, inset?: number, { align, behavior }?: RevealOptions): void;
+    /**
+     * Where item `index` starts along the scroll axis, in pixels from the top of
+     * the set: what was measured above it, or the estimate.
      */
-    reveal(index: number, inset?: number): void;
+    offsetOf(index: number): number;
     /**
      * Drops every measurement, for a host that swapped its data.
      *

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

@@ -39,6 +39,7 @@ export class VirtualizeController {
         }
         this.observer.observe(box);
         box.addEventListener('scroll', this.handleScroll, { passive: true });
+        box.setAttribute('data-virtual', '');
         this.watching = true;
     }
     measure() {
@@ -97,6 +98,48 @@ export class VirtualizeController {
             last,
         };
     }
+    visible() {
+        const box = this.options.container();
+        const total = Math.max(0, this.options.count());
+        if (!box || total === 0) {
+            return { first: 0, last: 0 };
+        }
+        const top = Math.max(0, box.scrollTop);
+        const bottom = top + box.clientHeight;
+        if (!this.measuring()) {
+            const size = Math.max(1, this.options.estimate());
+            const first = Math.min(Math.floor(top / size), total);
+            return { first, last: Math.max(first, Math.min(total, Math.ceil(bottom / size))) };
+        }
+        const first = this.heights.indexAt(top, total);
+        let last = first;
+        while (last < total && this.heights.before(last, total) < bottom) {
+            last += 1;
+        }
+        return { first, last };
+    }
+    remaining() {
+        const box = this.options.container();
+        const total = Math.max(0, this.options.count());
+        if (!box) {
+            return 0;
+        }
+        const length = this.measuring()
+            ? this.heights.total(total)
+            : total * Math.max(1, this.options.estimate());
+        return Math.max(0, length - Math.max(0, box.scrollTop) - box.clientHeight);
+    }
+    spacers(kept) {
+        const { after, before, first, last } = this.window;
+        if (kept === undefined || (kept >= first && kept < last)) {
+            return { after, before };
+        }
+        const room = this.sizeOf(kept);
+        return {
+            after: kept >= last ? Math.max(0, after - room) : after,
+            before: kept < first ? Math.max(0, before - room) : before,
+        };
+    }
     hostUpdated() {
         if (this.owed !== 0) {
             const box = this.options.container();
@@ -149,22 +192,46 @@ export class VirtualizeController {
     sizeOf(index) {
         return this.measuring() ? this.heights.at(index) : Math.max(1, this.options.estimate());
     }
-    reveal(index, inset = 0) {
+    reveal(index, inset = 0, { align = 'nearest', behavior } = {}) {
         const box = this.options.container();
         if (!box) {
             return;
         }
-        const total = Math.max(0, this.options.count());
-        const top = this.measuring()
-            ? this.heights.before(index, total)
-            : index * Math.max(1, this.options.estimate());
-        const bottom = top + this.sizeOf(index) + inset;
-        if (top < box.scrollTop) {
-            box.scrollTop = top;
+        const top = this.offsetOf(index);
+        const size = this.sizeOf(index);
+        const room = box.clientHeight - inset;
+        let to;
+        if (align === 'start') {
+            to = top;
+        }
+        else if (align === 'center') {
+            to = top - inset - (room - size) / 2;
+        }
+        else if (align === 'end') {
+            to = top + size + inset - box.clientHeight;
+        }
+        else if (top < box.scrollTop) {
+            to = top;
         }
-        else if (bottom > box.scrollTop + box.clientHeight) {
-            box.scrollTop = bottom - box.clientHeight;
+        else if (top + size + inset > box.scrollTop + box.clientHeight) {
+            to = top + size + inset - box.clientHeight;
         }
+        else {
+            return;
+        }
+        const next = Math.max(0, to);
+        if (behavior && typeof box.scrollTo === 'function') {
+            box.scrollTo({ behavior, top: next });
+        }
+        else {
+            box.scrollTop = next;
+        }
+    }
+    offsetOf(index) {
+        const total = Math.max(0, this.options.count());
+        return this.measuring()
+            ? this.heights.before(index, total)
+            : Math.max(0, Math.min(index, total)) * Math.max(1, this.options.estimate());
     }
     forget() {
         this.heights.forget();

package/dist/events/events.d.ts

@@ -261,6 +261,34 @@ export declare class HelixCanvasEditEvent extends CustomEvent<{
         name: string;
     });
 }
+/** Why a file field did not take a file. */
+export type Refusal = 'count' | 'invalid' | 'size' | 'type';
+/** One file a file field did not take, and why. */
+export interface RefusedFile {
+    /** The file. */
+    readonly file: File;
+    /** What the field's `validate` said about it, where it was the one refusing. */
+    readonly message?: string;
+    /** Why it was not taken. */
+    readonly reason: Refusal;
+}
+/** The files a file field refused. */
+export interface RejectDetail {
+    /** Each refused file with its reason, in the order they arrived. */
+    files: RefusedFile[];
+}
+/**
+ * Files arrived at a file field and some were refused: by `accept`, by
+ * `max-file-size`, by `max-files`, or by the field's own `validate`.
+ *
+ * A notification and not a request, because the files are already left out;
+ * the event is how a page tells the reader why. Bubbles and is composed, so a
+ * form around the field hears it.
+ */
+export declare class HelixRejectEvent extends CustomEvent<RejectDetail> {
+    static readonly eventName = "helix-reject";
+    constructor(detail: RejectDetail);
+}
 /** What a reader asked to take off the board. */
 export interface RemoveDetail {
     /** The cards, by name. */
@@ -799,6 +827,17 @@ export declare class HelixBeforeSplitEvent extends CustomEvent<ChangeDetail> {
     static readonly eventName = "helix-before-split";
     constructor(detail: ChangeDetail);
 }
+/**
+ * The divider between a sandbox's panes settled somewhere new.
+ *
+ * The notification half of `helix-before-split`, sent once `split` has moved,
+ * with the lead pane's new share. Not cancelable: the decision was the
+ * request's.
+ */
+export declare class HelixSplitEvent extends CustomEvent<ChangeDetail> {
+    static readonly eventName = "helix-split";
+    constructor(detail: ChangeDetail);
+}
 /**
  * A sandbox's panel is about to change height, and can be refused.
  *
@@ -811,6 +850,17 @@ export declare class HelixBeforePanelResizeEvent extends CustomEvent<ChangeDetai
     static readonly eventName = "helix-before-panel-resize";
     constructor(detail: ChangeDetail);
 }
+/**
+ * A sandbox's panel settled at a new height.
+ *
+ * The notification half of `helix-before-panel-resize`, sent once `panelSize`
+ * has moved, with the height in pixels. Not cancelable: the decision was the
+ * request's.
+ */
+export declare class HelixPanelResizeEvent extends CustomEvent<ChangeDetail> {
+    static readonly eventName = "helix-panel-resize";
+    constructor(detail: ChangeDetail);
+}
 /** A pane is about to collapse or reopen, and can be refused. */
 export declare class HelixBeforeCollapseEvent extends CustomEvent<ChangeDetail> {
     static readonly eventName = "helix-before-collapse";
@@ -832,6 +882,17 @@ export declare class HelixBeforeEditEvent extends CustomEvent<ChangeDetail> {
     static readonly eventName = "helix-before-edit";
     constructor(detail: ChangeDetail);
 }
+/**
+ * Source was edited.
+ *
+ * The notification half of `helix-before-edit`, sent once the pane holds the
+ * new source, with that source. Not cancelable: the decision was the
+ * request's.
+ */
+export declare class HelixEditEvent extends CustomEvent<ChangeDetail> {
+    static readonly eventName = "helix-edit";
+    constructor(detail: ChangeDetail);
+}
 /**
  * A value is about to change, and the change can be refused.
  *
@@ -914,6 +975,145 @@ export declare class HelixCreateEvent extends CustomEvent<CreateDetail> {
     static readonly eventName = "helix-create";
     constructor(detail: CreateDetail);
 }
+/** Detail carried by `helix-aura-fallback`. */
+export interface AuraFallbackDetail {
+    /**
+     * Why the gradient shows: `software` for a renderer that draws on the CPU,
+     * `unavailable` for no WebGL or a shader the browser refused, and `lost` for
+     * a context the browser took back, on a GPU reset or past its limit of about
+     * sixteen.
+     */
+    reason: 'lost' | 'software' | 'unavailable';
+}
+/**
+ * An aura stopped drawing its shader and shows its gradient, and says why.
+ *
+ * Sent each time it falls back, from the aura, which then matches
+ * `:state(fallback)` until it draws again. Not cancelable: there is nothing
+ * left to refuse.
+ */
+export declare class HelixAuraFallbackEvent extends CustomEvent<AuraFallbackDetail> {
+    static readonly eventName = "helix-aura-fallback";
+    constructor(detail: AuraFallbackDetail);
+}
+/**
+ * A reader cleared the value: an input's clear button emptied the field, or a
+ * clearable rating went back to unrated.
+ *
+ * Sent after the value is cleared, and after the `input` and `change` the
+ * clear sends. Carries nothing, because the value is the cleared one.
+ */
+export declare class HelixClearEvent extends Event {
+    static readonly eventName = "helix-clear";
+    constructor();
+}
+/**
+ * A press put nothing on the clipboard: the browser did not allow the write,
+ * such as on a page without the clipboard permission, or there was nothing to
+ * copy.
+ */
+export declare class HelixCopyErrorEvent extends Event {
+    static readonly eventName = "helix-copy-error";
+    constructor();
+}
+/**
+ * A reader asked for more items: a feed's or a table's `load-more` button, or
+ * a list scrolled near its end. Append them, and set `loading` while they are
+ * on their way.
+ *
+ * Carries nothing, because what comes next is the consumer's to know. Not
+ * cancelable: nothing is loaded until the consumer loads it.
+ */
+export declare class HelixLoadMoreEvent extends Event {
+    static readonly eventName = "helix-load-more";
+    constructor();
+}
+/**
+ * A lazy branch opened and asks for its children: a tree item with `lazy`.
+ * Sent from the item, so `target` is the branch to fill.
+ *
+ * Carries nothing, because the children are the consumer's to fetch. Not
+ * cancelable: the branch is already open, and says it is busy until children
+ * arrive.
+ */
+export declare class HelixLoadEvent extends Event {
+    static readonly eventName = "helix-load";
+    constructor();
+}
+/** Detail carried by `helix-range-change`. */
+export interface RangeDetail {
+    /** The index of the first item on screen. */
+    first: number;
+    /** One past the index of the last item on screen. */
+    last: number;
+}
+/**
+ * The items on screen changed: a virtual list was scrolled or resized, or its
+ * items changed. Carries the new range, which the list's `range` also holds.
+ * Not cancelable: the list has already moved.
+ */
+export declare class HelixRangeChangeEvent extends CustomEvent<RangeDetail> {
+    static readonly eventName = "helix-range-change";
+    constructor(detail: RangeDetail);
+}
+/**
+ * Rows opened or closed in place: a data table's tree of rows. Carries every
+ * open row's key, separated by commas, which the table's `expanded` also
+ * holds. Not cancelable: the rows have already moved.
+ */
+export declare class HelixExpandEvent extends CustomEvent<ChangeDetail> {
+    static readonly eventName = "helix-expand";
+    constructor(detail: ChangeDetail);
+}
+/**
+ * A sequence played to its last entry and stopped there: a video playlist
+ * with no `repeat`. Carries nothing, because the playlist still holds the last
+ * entry. Not cancelable: playback has already ended.
+ */
+export declare class HelixEndEvent extends Event {
+    static readonly eventName = "helix-end";
+    constructor();
+}
+/** Detail carried by `helix-typing`. */
+export interface TypingDetail {
+    /** Whether the user is writing now, as a boolean and not a word that reads like one. */
+    typing: boolean;
+}
+/**
+ * The user started or stopped writing: a chat composer, for a typing
+ * indicator on the other side. Carries which, as the composer's `typing` does.
+ * Not cancelable: it reports what the user did.
+ */
+export declare class HelixTypingEvent extends CustomEvent<TypingDetail> {
+    static readonly eventName = "helix-typing";
+    constructor(detail: TypingDetail);
+}
+/**
+ * A reader acted on a row: Enter on a list row, or a press in a list that
+ * selects nothing. Sent from the row, so `target` is the row acted on.
+ *
+ * Carries nothing, because the row is the whole of the answer. Not cancelable:
+ * a row with a link follows it and sends nothing, so there is no default left
+ * to refuse.
+ */
+export declare class HelixActionEvent extends Event {
+    static readonly eventName = "helix-action";
+    constructor();
+}
+/**
+ * A checked state changed after `helix-before-toggle` let it: a map layer
+ * shown or hidden from the layers menu. Sent from what changed, with the state
+ * it now holds.
+ *
+ * **Not the native `toggle`.** That one is a `ToggleEvent` saying a popover or
+ * a `<details>` opened or closed, with `newState` of `open` or `closed`, and a
+ * layer shown on a map is neither: it is the request's own verb without
+ * `before`, carrying the same `checked` the request did.
+ */
+export declare class HelixToggleEvent extends CustomEvent<ToggleDetail> {
+    static readonly eventName = "helix-toggle";
+    constructor(detail: ToggleDetail);
+}
 /** Detail carried by `helix-copy`. */
 export interface CopyDetail {
     /** What was put on the clipboard. */
@@ -1037,6 +1237,12 @@ export interface SelectDetail {
      * A flag says it outright.
      */
     alternate?: boolean;
+    /**
+     * The link of a row that is a link, which the browser follows once the event
+     * is done unless it is canceled. A client-side router cancels it and follows
+     * the link itself.
+     */
+    href?: string;
     /** Value of the item the reader chose. */
     value: string;
 }
@@ -1285,7 +1491,9 @@ export declare class HelixHistoryEvent extends CustomEvent<Record<string, never>
  * forgotten.
  */
 declare const registry: {
+    readonly HelixActionEvent: typeof HelixActionEvent;
     readonly HelixActivateEvent: typeof HelixActivateEvent;
+    readonly HelixAuraFallbackEvent: typeof HelixAuraFallbackEvent;
     readonly HelixBeforeActivateEvent: typeof HelixBeforeActivateEvent;
     readonly HelixBeforeChangeEvent: typeof HelixBeforeChangeEvent;
     readonly HelixBeforeCloseEvent: typeof HelixBeforeCloseEvent;
@@ -1305,13 +1513,18 @@ declare const registry: {
     readonly HelixCanvasViewEvent: typeof HelixCanvasViewEvent;
     readonly HelixCanvasZoomEvent: typeof HelixCanvasZoomEvent;
     readonly HelixCaretEvent: typeof HelixCaretEvent;
+    readonly HelixClearEvent: typeof HelixClearEvent;
     readonly HelixCollapseEvent: typeof HelixCollapseEvent;
     readonly HelixCompleteEvent: typeof HelixCompleteEvent;
     readonly HelixConnectEvent: typeof HelixConnectEvent;
     readonly HelixConsoleEvent: typeof HelixConsoleEvent;
+    readonly HelixCopyErrorEvent: typeof HelixCopyErrorEvent;
     readonly HelixCopyEvent: typeof HelixCopyEvent;
     readonly HelixCreateEvent: typeof HelixCreateEvent;
     readonly HelixDismissEvent: typeof HelixDismissEvent;
+    readonly HelixEditEvent: typeof HelixEditEvent;
+    readonly HelixEndEvent: typeof HelixEndEvent;
+    readonly HelixExpandEvent: typeof HelixExpandEvent;
     readonly HelixFacetEvent: typeof HelixFacetEvent;
     readonly HelixFilterEvent: typeof HelixFilterEvent;
     readonly HelixFilteredEvent: typeof HelixFilteredEvent;
@@ -1323,6 +1536,8 @@ declare const registry: {
     readonly HelixGraphSignalEvent: typeof HelixGraphSignalEvent;
     readonly HelixGraphZoomEvent: typeof HelixGraphZoomEvent;
     readonly HelixHistoryEvent: typeof HelixHistoryEvent;
+    readonly HelixLoadEvent: typeof HelixLoadEvent;
+    readonly HelixLoadMoreEvent: typeof HelixLoadMoreEvent;
     readonly HelixMapClusterEvent: typeof HelixMapClusterEvent;
     readonly HelixMapPanEvent: typeof HelixMapPanEvent;
     readonly HelixMapPartChangeEvent: typeof HelixMapPartChangeEvent;
@@ -1333,10 +1548,13 @@ declare const registry: {
     readonly HelixMoveEvent: typeof HelixMoveEvent;
     readonly HelixNavigateEvent: typeof HelixNavigateEvent;
     readonly HelixNextEvent: typeof HelixNextEvent;
+    readonly HelixPanelResizeEvent: typeof HelixPanelResizeEvent;
     readonly HelixPinEvent: typeof HelixPinEvent;
     readonly HelixPreviousEvent: typeof HelixPreviousEvent;
+    readonly HelixRangeChangeEvent: typeof HelixRangeChangeEvent;
     readonly HelixReadEvent: typeof HelixReadEvent;
     readonly HelixReconnectEvent: typeof HelixReconnectEvent;
+    readonly HelixRejectEvent: typeof HelixRejectEvent;
     readonly HelixRelabelEvent: typeof HelixRelabelEvent;
     readonly HelixRemoveEvent: typeof HelixRemoveEvent;
     readonly HelixReorderEvent: typeof HelixReorderEvent;
@@ -1352,7 +1570,10 @@ declare const registry: {
     readonly HelixShortcutEvent: typeof HelixShortcutEvent;
     readonly HelixSortEvent: typeof HelixSortEvent;
     readonly HelixSortedEvent: typeof HelixSortedEvent;
+    readonly HelixSplitEvent: typeof HelixSplitEvent;
+    readonly HelixToggleEvent: typeof HelixToggleEvent;
     readonly HelixTourAskEvent: typeof HelixTourAskEvent;
+    readonly HelixTypingEvent: typeof HelixTypingEvent;
 };
 /**
  * Every name this library dispatches.