@fusion.dev/helix-headless 0.146.0 → 0.147.0

package/dist/virtual-list/root/virtual-list-root.d.ts

@@ -46,13 +46,20 @@ export interface VirtualListRange {
  *
  * Rows are your markup in the light DOM, so your stylesheet styles them.
  *
+ * **A grid.** `columns` lays the items out that many to a line, as a grid of
+ * equal columns, and windows the set a line at a time, as React Aria's grid
+ * layout does. Each item draws one element, a cell of the grid, and
+ * `estimate` is the height of a line. Space the items with padding inside
+ * each one, which the list measures with the line.
+ *
  * **Keyboard.** The list is one tab stop.
  *
  * | Key | What it does |
  * |---|---|
- * | Down, Up | Moves to the next or the previous item. |
+ * | Down, Up | Moves to the next or the previous item, or in a grid to the item in the same column on the next or the previous line. |
+ * | Right, Left | In a grid, moves to the next or the previous item along the line, the other way round on a right-to-left page. |
  * | Home, End | Moves to the first or the last item. |
- * | Page Down, Page Up | Moves by the number of items on screen. |
+ * | Page Down, Page Up | Moves by the number of items, or of lines in a grid, on screen. |
  * | A letter or a word | Moves to the next item whose text starts with what you typed. |
  * | Tab | Moves into the focused row's own links and buttons, then out of the list. |
  *
@@ -68,7 +75,7 @@ export interface VirtualListRange {
  *
  * **Selecting.** `selection-mode` makes the list a list box a reader chooses
  * from: `single` selects one item and `multiple` any number. Space or a press
- * selects an item, Shift with Space, Up, Down, Home, End or a press takes in
+ * selects an item, Shift with Space, an arrow, Home, End or a press takes in
  * the items from the last one chosen, and Control or Command with A selects
  * them all, in `multiple`. `value` holds the chosen items' keys, separated by
  * commas, in the order of the set: `key-field` names each item's key, and a
@@ -116,6 +123,12 @@ export interface VirtualListRange {
  * @csspart viewport - The scrolling box. On this tier, it needs only a block size.
  */
 export declare class HelixHeadlessVirtualList extends HelixElement {
+    /**
+     * How many items a line holds. One, the default, is a list; more lays the
+     * items out as a grid of that many equal columns, windowed a line at a
+     * time, with Left and Right moving along a line.
+     */
+    columns: number;
     /**
      * The height of one row, in pixels, used to find the row at a scroll offset.
      *
@@ -247,6 +260,10 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * box to measure.
      */
     get range(): VirtualListRange;
+    /** How many items a line holds: `columns`, at least one. */
+    private get across();
+    /** The items a span of lines holds. */
+    private itemsOn;
     /**
      * Scrolls the list to show the item at `index`.
      *
@@ -267,6 +284,11 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * window moved.
      */
     private drawn;
+    /**
+     * The drawn lines, for the controller to measure: each row in a list, and
+     * the first item of each line in a grid, whose cell is as tall as its line.
+     */
+    private lines;
     /**
      * Reads the source named by `for`, before the render that draws it.
      *

package/dist/virtual-list/root/virtual-list-root.js

@@ -4,16 +4,17 @@ 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 { AriaForwardController, commaList, customElement, elementById, HelixBeforeChangeEvent, HelixElement, HelixLoadMoreEvent, HelixRangeChangeEvent, rangeAdd, requestChange, searchableById, Typeahead, toggleValue, typesCharacter, VirtualizeController, valueAt, } from '@fusion.dev/helix-core';
+import { AriaForwardController, commaList, customElement, elementById, HelixBeforeChangeEvent, HelixElement, HelixLoadMoreEvent, HelixRangeChangeEvent, isRtl, rangeAdd, requestChange, searchableById, selectsAll, Typeahead, toggleValue, typesCharacter, VirtualizeController, } from '@fusion.dev/helix-core';
 import { html, nothing, render } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { holdControls, releaseControls } from '../controls.js';
-import { fillHoles, textOf } from '../fill.js';
+import { fillHoles, keyOf, textsOf } from '../fill.js';
 import { stepIndex } from '../keys.js';
-import { drawPlan, stopAfter } from '../plan.js';
+import { drawPlan, itemsOf, stopAfter } from '../plan.js';
 let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixElement {
     constructor() {
         super(...arguments);
+        this.columns = 1;
         this.estimate = 32;
         this.for = '';
         this.keyField = '';
@@ -34,10 +35,10 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
         });
         this.virtualize = new VirtualizeController(this, {
             container: () => this.partNamed('viewport'),
-            count: () => this.data.length,
+            count: () => Math.ceil(this.data.length / this.across),
             estimate: () => this.estimate,
             measured: () => this.measured,
-            rows: () => this.drawn(),
+            rows: () => this.lines(),
         });
         this.handleKeydown = (event) => {
             if (event.defaultPrevented) {
@@ -57,7 +58,7 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
             }
             const toggle = event.ctrlKey || event.metaKey;
             if (this.selectionMode && !event.altKey) {
-                if (toggle && event.key.toLowerCase() === 'a' && this.selectionMode === 'multiple') {
+                if (selectsAll(event) && this.selectionMode === 'multiple') {
                     event.preventDefault();
                     this.choose(this.keys().join(','));
                     return;
@@ -73,7 +74,10 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
                 return;
             }
             const { first, last } = this.virtualize.visible();
-            const next = stepIndex(event.key, at, this.data.length, last - first - 1);
+            const next = stepIndex(event.key, at, this.data.length, last - first - 1, {
+                across: this.across,
+                forward: isRtl(this) ? 'ArrowLeft' : 'ArrowRight',
+            });
             if (next === undefined) {
                 return;
             }
@@ -117,14 +121,21 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
         };
     }
     get range() {
-        return this.virtualize.visible();
+        return this.itemsOn(this.virtualize.visible());
+    }
+    get across() {
+        return Math.max(1, Math.trunc(this.columns) || 1);
+    }
+    itemsOn(lines) {
+        return itemsOf(lines, this.across, this.data.length);
     }
     scrollToIndex(index, options = {}) {
         const count = this.data.length;
         if (count === 0 || !Number.isFinite(index)) {
             return;
         }
-        this.virtualize.reveal(Math.max(0, Math.min(Math.trunc(index), count - 1)), 0, options);
+        const at = Math.max(0, Math.min(Math.trunc(index), count - 1));
+        this.virtualize.reveal(Math.floor(at / this.across), 0, options);
         this.virtualize.measure();
     }
     get data() {
@@ -136,6 +147,15 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
             index: Number(element.dataset.index),
         }));
     }
+    lines() {
+        const across = this.across;
+        const drawn = this.drawn();
+        return across === 1
+            ? drawn
+            : drawn
+                .filter(({ index }) => index % across === 0)
+                .map(({ element, index }) => ({ element, index: index / across }));
+    }
     willUpdate(changed) {
         super.willUpdate(changed);
         if (this.readFor !== this.for && searchableById(this) && !this.hydrating) {
@@ -205,7 +225,7 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
         }
     }
     report() {
-        const { first, last } = this.virtualize.visible();
+        const { first, last } = this.range;
         if (first !== this.said.first || last !== this.said.last) {
             this.said = { first, last };
             this.dispatchEvent(new HelixRangeChangeEvent({ first, last }));
@@ -220,9 +240,7 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
                 ?.content.querySelector('[data-field]')
                 ?.getAttribute('data-field') ||
             '';
-        return this.data.map((item) => field === '' || item === null || typeof item !== 'object'
-            ? textOf(item)
-            : textOf(valueAt(item, field)));
+        return textsOf(this.data, field);
     }
     indexOf(node) {
         if (!(node instanceof HTMLElement) || node.parentElement !== this) {
@@ -235,11 +253,7 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
         return this.querySelector(`:scope > [data-index="${index}"]`);
     }
     keyAt(at) {
-        const item = this.data[at];
-        if (this.keyField !== '' && item !== null && typeof item === 'object') {
-            return textOf(valueAt(item, this.keyField));
-        }
-        return typeof item === 'string' || typeof item === 'number' ? String(item) : String(at);
+        return keyOf(this.data[at], at, this.keyField);
     }
     keys() {
         return this.data.map((_, at) => this.keyAt(at));
@@ -293,7 +307,7 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
     async focusIndex(index) {
         this.active = index;
         this.focusing = index;
-        this.virtualize.reveal(index);
+        this.virtualize.reveal(Math.floor(index / this.across));
         this.virtualize.measure();
         this.requestUpdate();
         try {
@@ -315,7 +329,7 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
     }
     keptIndex() {
         const index = this.focusing ?? this.focusedIndex();
-        const { first, last } = this.virtualize.window;
+        const { first, last } = this.itemsOn(this.virtualize.window);
         return index !== undefined && index < this.data.length && (index < first || index >= last)
             ? index
             : undefined;
@@ -363,9 +377,10 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
             return;
         }
         const count = this.data.length;
-        const { first, last } = this.virtualize.window;
+        const { first, last } = this.itemsOn(this.virtualize.window);
         const children = [...this.children].filter((child) => child !== template && child instanceof HTMLElement && !child.hasAttribute('slot'));
         const plan = drawPlan({
+            across: this.across,
             count,
             drawn: children.map((child) => Number(child.dataset.index)),
             first,
@@ -406,7 +421,7 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
             count,
             first,
             last,
-            onScreen: this.virtualize.visible().first,
+            onScreen: this.range.first,
         });
         const chosen = this.chosen;
         for (const [at, group] of drawn) {
@@ -425,7 +440,9 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
         this.released = this.active;
     }
     render() {
-        const { after, before } = this.virtualize.spacers(this.hasUpdated ? this.keptIndex() : undefined);
+        const kept = this.hasUpdated ? this.keptIndex() : undefined;
+        const { after, before } = this.virtualize.spacers(kept === undefined ? undefined : Math.floor(kept / this.across));
+        const across = this.across;
         return html `<div
       data-scroller
       part="viewport"
@@ -439,7 +456,11 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
         }}
     >
       <div part="before" style="block-size: ${before}px"></div>
-      <slot></slot>
+      <slot
+        style=${across === 1
+            ? nothing
+            : `display: grid; grid-template-columns: repeat(${across}, minmax(0, 1fr))`}
+      ></slot>
       <div part="after" style="block-size: ${after}px"></div>
       ${this.loading
             ? html `<div part="loading" role=${this.selectionMode ? 'option' : 'listitem'}>
@@ -449,6 +470,9 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
     </div>`;
     }
 };
+__decorate([
+    property({ type: Number })
+], HelixHeadlessVirtualList.prototype, "columns", void 0);
 __decorate([
     property({ type: Number })
 ], HelixHeadlessVirtualList.prototype, "estimate", void 0);