@fusion.dev/helix-headless 0.166.0 → 0.167.0

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

@@ -11,6 +11,13 @@ import { holdControls, releaseControls } from '../controls.js';
 import { fillHoles, keyOf, textsOf } from '../fill.js';
 import { skipDisabled, stepIndex } from '../keys.js';
 import { drawPlan, itemsOf, stopAfter } from '../plan.js';
+import { entryOf, headOf, itemsIn, sectionAt, sectionsOf } from '../sections.js';
+let sectionCount = 0;
+const nextSectionId = () => {
+    sectionCount += 1;
+    return `virtual-list-${sectionCount}`;
+};
+const ROWS = ':scope > [data-index], :scope > [data-section] > [data-index]';
 let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixElement {
     constructor() {
         super(...arguments);
@@ -26,6 +33,8 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
         this.loadingLabel = 'Loading more';
         this.measured = false;
         this.minColumnWidth = 0;
+        this.orientation = 'vertical';
+        this.sectionField = '';
         this.selectionBehavior = 'toggle';
         this.textField = '';
         this.value = '';
@@ -41,9 +50,12 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
         });
         this.virtualize = new VirtualizeController(this, {
             container: () => this.partNamed('viewport'),
-            count: () => Math.ceil(this.data.length / this.across),
+            count: () => this.sections
+                ? this.data.length + this.sections.starts.length
+                : Math.ceil(this.data.length / this.across),
             estimate: () => this.estimate,
             gap: () => this.space,
+            horizontal: () => this.horizontal,
             measured: () => this.measured,
             rows: () => this.lines(),
         });
@@ -94,13 +106,23 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
             }
             const count = this.data.length;
             const { first, last } = this.virtualize.visible();
-            const stepped = stepIndex(event.key, at, count, last - first - 1, {
+            const forward = isRtl(this) ? 'ArrowLeft' : 'ArrowRight';
+            const key = !this.horizontal
+                ? event.key
+                : event.key === forward
+                    ? 'ArrowDown'
+                    : event.key === 'ArrowLeft' || event.key === 'ArrowRight'
+                        ? 'ArrowUp'
+                        : event.key === 'ArrowDown' || event.key === 'ArrowUp'
+                            ? ''
+                            : event.key;
+            const stepped = stepIndex(key, at, count, last - first - 1, {
                 across: this.across,
-                forward: isRtl(this) ? 'ArrowLeft' : 'ArrowRight',
+                forward,
             });
             const next = stepped === undefined
                 ? undefined
-                : skipDisabled(event.key, at, stepped, count, (one) => this.isDisabled(one), this.across);
+                : skipDisabled(key, at, stepped, count, (one) => this.isDisabled(one), this.across);
             if (next === undefined) {
                 if (stepped !== undefined) {
                     event.preventDefault();
@@ -122,7 +144,7 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
                 return;
             }
             const path = event.composedPath();
-            const row = path.find((node) => node instanceof HTMLElement && node.parentElement === this);
+            const row = path.find((node) => this.isRow(node));
             const at = this.indexOf(row ?? null);
             if (at === undefined) {
                 return;
@@ -143,7 +165,7 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
         };
         this.handleFocusIn = (event) => {
             let node = event.target;
-            while (node && node.parentNode !== this) {
+            while (node && node !== this && !this.isRow(node)) {
                 node = node.parentNode;
             }
             const index = this.indexOf(node);
@@ -152,6 +174,7 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
             }
             this.requestUpdate();
         };
+        this.sectionId = nextSectionId();
     }
     static { this.words = 'helix-virtual-list'; }
     get range() {
@@ -186,7 +209,32 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
         this.widthWatch.observe(viewport);
     }
     itemsOn(lines) {
-        return itemsOf(lines, this.across, this.data.length);
+        const sections = this.sections;
+        return sections
+            ? itemsIn(sections, lines, this.data.length)
+            : itemsOf(lines, this.across, this.data.length);
+    }
+    lineOf(at) {
+        const sections = this.sections;
+        return sections ? entryOf(sections, at) : Math.floor(at / this.across);
+    }
+    get horizontal() {
+        return this.orientation === 'horizontal' && this.across === 1;
+    }
+    get sections() {
+        const data = this.data;
+        if (this.sectionField === '' || data.length === 0 || this.across !== 1) {
+            return undefined;
+        }
+        const read = this.sectionsRead;
+        if (read?.data !== data || read.field !== this.sectionField) {
+            this.sectionsRead = {
+                data,
+                field: this.sectionField,
+                sections: sectionsOf(data, this.sectionField),
+            };
+        }
+        return this.sectionsRead?.sections;
     }
     scrollToIndex(index, options = {}) {
         const count = this.data.length;
@@ -194,14 +242,14 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
             return;
         }
         const at = Math.max(0, Math.min(Math.trunc(index), count - 1));
-        this.virtualize.reveal(Math.floor(at / this.across), 0, options);
+        this.virtualize.reveal(this.lineOf(at), 0, options);
         this.virtualize.measure();
     }
     get data() {
         return this.items ?? this.rows;
     }
     drawn() {
-        return [...this.querySelectorAll(':scope > [data-index]')].map((element) => ({
+        return [...this.querySelectorAll(ROWS)].map((element) => ({
             element,
             index: Number(element.dataset.index),
         }));
@@ -209,6 +257,13 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
     lines() {
         const across = this.across;
         const drawn = this.drawn();
+        const sections = this.sections;
+        if (sections) {
+            return [
+                ...drawn.map(({ element, index }) => ({ element, index: entryOf(sections, index) })),
+                ...[...this.querySelectorAll(':scope > [data-section] > [data-entry]')].map((element) => ({ element, index: Number(element.dataset.entry) })),
+            ];
+        }
         return across === 1
             ? drawn
             : drawn
@@ -226,6 +281,9 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
             this.measuredAcross = across;
             this.virtualize.forget();
         }
+        if (this.hasUpdated && (changed.has('orientation') || changed.has('sectionField'))) {
+            this.virtualize.forget();
+        }
         if (this.hasUpdated) {
             if (changed.has('items')) {
                 this.keepPlace(changed.get('items'));
@@ -245,10 +303,13 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
         if (!same(by, 0) || !same(now.length - 1, was.length - 1)) {
             return;
         }
-        if (by % this.across === 0) {
+        if (this.sections) {
+            this.virtualize.shift(this.lineOf(by) - 1);
+        }
+        else if (by % this.across === 0) {
             this.virtualize.shift(by / this.across);
         }
-        for (const row of this.querySelectorAll(':scope > [data-index]')) {
+        for (const row of this.querySelectorAll(ROWS)) {
             row.dataset.index = String(Number(row.dataset.index) + by);
         }
         this.active += by;
@@ -324,6 +385,7 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
         super.updated?.(changed);
         this.toggleState('empty', this.readFor !== undefined && this.data.length === 0);
         this.toggleState('loading', this.loading);
+        this.toggleState('horizontal', this.horizontal);
         this.watchWidth();
         const was = this.virtualize.window;
         this.virtualize.measure();
@@ -376,14 +438,18 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
         return this.disabledKeys !== '' && this.disabled.has(this.keyAt(at));
     }
     indexOf(node) {
-        if (!(node instanceof HTMLElement) || node.parentElement !== this) {
+        if (!this.isRow(node)) {
             return undefined;
         }
         const index = node.dataset.index;
         return index === undefined ? undefined : Number(index);
     }
+    isRow(node) {
+        const parent = node instanceof HTMLElement ? node.parentElement : null;
+        return (parent === this || (parent?.parentElement === this && parent.hasAttribute('data-section')));
+    }
     rowFor(index) {
-        return this.querySelector(`:scope > [data-index="${index}"]`);
+        return ([...this.querySelectorAll(ROWS)].find((row) => row.dataset.index === String(index)) ?? null);
     }
     keyAt(at) {
         return keyOf(this.data[at], at, this.keyField);
@@ -437,7 +503,7 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
     async focusIndex(index) {
         this.active = index;
         this.focusing = index;
-        this.virtualize.reveal(Math.floor(index / this.across));
+        this.virtualize.reveal(this.lineOf(index));
         this.virtualize.measure();
         this.requestUpdate();
         try {
@@ -451,7 +517,7 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
     focusedIndex() {
         const root = this.getRootNode();
         let node = root.activeElement;
-        while (node && node.parentElement !== this) {
+        while (node && node !== this && !this.isRow(node)) {
             node = node.parentElement;
         }
         const index = node instanceof HTMLElement ? node.dataset.index : undefined;
@@ -518,10 +584,20 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
         const onScreen = this.range.first;
         if (this.hasUpdated) {
             const spacers = this.spacerSizes();
-            this.partNamed('before')?.style.setProperty('block-size', `${spacers.before}px`);
-            this.partNamed('after')?.style.setProperty('block-size', `${spacers.after}px`);
-        }
-        const children = [...this.children].filter((child) => child !== template && child instanceof HTMLElement && !child.hasAttribute('slot'));
+            const size = this.horizontal ? 'inline-size' : 'block-size';
+            this.partNamed('before')?.style.setProperty(size, `${spacers.before}px`);
+            this.partNamed('after')?.style.setProperty(size, `${spacers.after}px`);
+        }
+        const sections = this.sections;
+        const regroup = sections !== this.placedSections;
+        this.placedSections = sections;
+        const children = [
+            ...[...this.children].filter((child) => child !== template &&
+                child instanceof HTMLElement &&
+                !child.hasAttribute('slot') &&
+                !child.hasAttribute('data-section')),
+            ...this.querySelectorAll(':scope > [data-section] > [data-index]'),
+        ];
         const plan = drawPlan({
             across: this.across,
             count,
@@ -529,7 +605,7 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
             first,
             kept: this.keptIndex(),
             last,
-            redraw: (this.filledBy === undefined) !== (this.renderItem === undefined),
+            redraw: regroup || (this.filledBy === undefined) !== (this.renderItem === undefined),
         });
         const drawn = new Map();
         for (const child of children) {
@@ -541,26 +617,34 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
             }
             drawn.set(index, [...(drawn.get(index) ?? []), child]);
         }
-        const refill = this.filledFrom !== this.data || this.filledBy !== this.renderItem;
+        const refill = this.filledFrom !== this.data ||
+            this.filledBy !== this.renderItem ||
+            this.headedBy !== this.renderSection;
         this.filledFrom = this.data;
         this.filledBy = this.renderItem;
+        this.headedBy = this.renderSection;
+        const groups = this.groups(sections, plan.wanted, regroup, refill);
         const fresh = new Set();
-        let anchor = drawn.values().next().value?.[0] ?? null;
+        const anchors = new Map();
         for (const at of plan.wanted) {
+            const parent = (sections && groups.get(sectionAt(sections, at))) || this;
+            if (!anchors.has(parent)) {
+                anchors.set(parent, parent.querySelector(':scope > [data-index]'));
+            }
             const group = drawn.get(at);
             if (group) {
                 if (refill) {
                     this.fill(group, at);
                     fresh.add(at);
                 }
-                anchor = group.at(-1).nextElementSibling;
+                anchors.set(parent, group.at(-1).nextElementSibling);
                 continue;
             }
             const fragment = this.draw(template, at);
             drawn.set(at, [...fragment.children]);
             this.watchSize([...fragment.children]);
             fresh.add(at);
-            this.insertBefore(fragment, anchor);
+            parent.insertBefore(fragment, anchors.get(parent) ?? null);
         }
         this.active = stopAfter(this.active, plan.wanted, {
             count,
@@ -594,13 +678,100 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
             }, 0);
         }
     }
+    groups(sections, wanted, regroup, refill) {
+        const keep = new Set(sections ? wanted.map((at) => sectionAt(sections, at)) : []);
+        const groups = new Map();
+        for (const group of this.querySelectorAll(':scope > [data-section]')) {
+            const at = Number(group.dataset.section);
+            if (regroup || !keep.has(at)) {
+                this.sizes?.unobserve(group.firstElementChild);
+                group.remove();
+            }
+            else {
+                groups.set(at, group);
+            }
+        }
+        if (!sections) {
+            return groups;
+        }
+        for (const at of [...keep].sort((a, b) => a - b)) {
+            let group = groups.get(at);
+            const fresh = group === undefined;
+            if (!group) {
+                group = document.createElement('div');
+                const header = document.createElement('div');
+                header.id = `${this.sectionId}-${at}`;
+                header.dataset.entry = String(headOf(sections, at));
+                header.setAttribute('data-header', '');
+                group.dataset.section = String(at);
+                group.setAttribute('role', 'group');
+                group.setAttribute('aria-labelledby', header.id);
+                group.append(header);
+                const after = [...groups].find(([other]) => other > at)?.[1] ?? null;
+                this.insertBefore(group, after);
+                groups.set(at, group);
+                this.watchSize([header]);
+            }
+            const header = group.firstElementChild;
+            if (fresh || refill) {
+                const name = sections.names[at] ?? '';
+                if (this.renderSection) {
+                    render(this.renderSection(name, at), header);
+                }
+                else {
+                    header.textContent = name;
+                }
+            }
+            if (this.selectionMode) {
+                header.setAttribute('role', 'presentation');
+            }
+            else {
+                header.removeAttribute('role');
+            }
+            const gap = this.space;
+            group.style.cssText = this.horizontal
+                ? `display: flex; column-gap: ${gap}px`
+                : gap === 0
+                    ? ''
+                    : `display: flex; flex-direction: column; row-gap: ${gap}px`;
+        }
+        return groups;
+    }
     spacerSizes() {
         const kept = this.hasUpdated ? this.keptIndex() : undefined;
-        return this.virtualize.spacers(kept === undefined ? undefined : Math.floor(kept / this.across));
+        const room = this.virtualize.spacers(kept === undefined ? undefined : this.lineOf(kept));
+        const sections = this.sections;
+        if (!sections || !this.hasUpdated) {
+            return room;
+        }
+        const { first, last } = this.virtualize.window;
+        const items = this.itemsOn(this.virtualize.window);
+        const drawnIn = new Set();
+        if (items.last > items.first) {
+            drawnIn.add(sectionAt(sections, items.first));
+        }
+        if (kept !== undefined) {
+            drawnIn.add(sectionAt(sections, kept));
+        }
+        let { after, before } = room;
+        for (const section of drawnIn) {
+            const head = headOf(sections, section);
+            if (head < first) {
+                before = Math.max(0, before - this.virtualize.sizeOf(head));
+            }
+            else if (head >= last) {
+                after = Math.max(0, after - this.virtualize.sizeOf(head));
+            }
+        }
+        return { after, before };
     }
     render() {
         const { after, before } = this.spacerSizes();
         const across = this.across;
+        const horizontal = this.horizontal;
+        const size = horizontal ? 'inline-size' : 'block-size';
+        const flex = horizontal ? '; flex: none' : '';
+        const gap = this.space;
         const empty = this.readFor !== undefined &&
             !this.loading &&
             this.data.length === 0 &&
@@ -612,20 +783,24 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
       aria-multiselectable=${this.selectionMode === 'multiple' ? 'true' : nothing}
       aria-busy=${this.loading ? 'true' : nothing}
       aria-label=${this.label}
+      aria-orientation=${this.selectionMode && horizontal ? 'horizontal' : nothing}
+      style=${horizontal ? 'display: flex' : nothing}
       @scroll=${() => {
             this.virtualize.measure();
             this.report();
         }}
     >
-      <div part="before" style="block-size: ${before}px"></div>
+      <div part="before" style="${size}: ${before}px${flex}"></div>
       <slot
-        style=${across === 1
-            ? this.space === 0
-                ? nothing
-                : `display: flex; flex-direction: column; row-gap: ${this.space}px; padding-block-end: ${this.space}px`
-            : `display: grid; grid-template-columns: repeat(${across}, minmax(0, 1fr))${this.space === 0 ? '' : `; gap: ${this.space}px; padding-block-end: ${this.space}px`}`}
+        style=${horizontal
+            ? `display: flex; flex: none${gap === 0 ? '' : `; column-gap: ${gap}px; padding-inline-end: ${gap}px`}`
+            : across === 1
+                ? gap === 0
+                    ? nothing
+                    : `display: flex; flex-direction: column; row-gap: ${gap}px; padding-block-end: ${gap}px`
+                : `display: grid; grid-template-columns: repeat(${across}, minmax(0, 1fr))${gap === 0 ? '' : `; gap: ${gap}px; padding-block-end: ${gap}px`}`}
       ></slot>
-      <div part="after" style="block-size: ${after}px"></div>
+      <div part="after" style="${size}: ${after}px${flex}"></div>
       ${this.loading
             ? html `<div part="loading" role=${this.selectionMode ? 'option' : 'listitem'}>
               <slot name="loading">${this.loadingLabel}</slot>
@@ -679,9 +854,18 @@ __decorate([
 __decorate([
     property({ attribute: 'min-column-width', type: Number })
 ], HelixHeadlessVirtualList.prototype, "minColumnWidth", void 0);
+__decorate([
+    property()
+], HelixHeadlessVirtualList.prototype, "orientation", void 0);
 __decorate([
     property({ attribute: false })
 ], HelixHeadlessVirtualList.prototype, "renderItem", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessVirtualList.prototype, "renderSection", void 0);
+__decorate([
+    property({ attribute: 'section-field' })
+], HelixHeadlessVirtualList.prototype, "sectionField", void 0);
 __decorate([
     property({ attribute: 'selection-behavior' })
 ], HelixHeadlessVirtualList.prototype, "selectionBehavior", void 0);

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

@@ -0,0 +1,27 @@
+/** Where each section starts in the items, and what it is called. */
+export interface Sections {
+    /** The section names, in order. */
+    names: string[];
+    /** The index of each section's first item, in order. */
+    starts: number[];
+}
+/** The sections `field` divides the items into. */
+export declare const sectionsOf: (items: readonly unknown[], field: string) => Sections;
+/** The section item `item` is in. */
+export declare const sectionAt: ({ starts }: Sections, item: number) => number;
+/** The entry item `item` is. */
+export declare const entryOf: (sections: Sections, item: number) => number;
+/** The entry of section `section`'s header. */
+export declare const headOf: ({ starts }: Sections, section: number) => number;
+/**
+ * The items a span of entries holds: what a window of entries draws, or what
+ * a reader sees. A header at either end holds no item, so the span starts at
+ * its section's first item.
+ */
+export declare const itemsIn: (sections: Sections, entries: {
+    first: number;
+    last: number;
+}, count: number) => {
+    first: number;
+    last: number;
+};

package/dist/virtual-list/sections.js

@@ -0,0 +1,43 @@
+import { valueAt } from '@fusion.dev/helix-core';
+import { textOf } from './fill.js';
+export const sectionsOf = (items, field) => {
+    const names = [];
+    const starts = [];
+    let last;
+    for (const [at, item] of items.entries()) {
+        const name = textOf(valueAt(item, field));
+        if (at === 0 || name !== last) {
+            names.push(name);
+            starts.push(at);
+            last = name;
+        }
+    }
+    return { names, starts };
+};
+const lastUpTo = (length, at, target) => {
+    let low = 0;
+    let high = length - 1;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if (at(middle) <= target) {
+            low = middle;
+        }
+        else {
+            high = middle - 1;
+        }
+    }
+    return low;
+};
+export const sectionAt = ({ starts }, item) => lastUpTo(starts.length, (index) => starts[index] ?? 0, item);
+export const entryOf = (sections, item) => item + sectionAt(sections, item) + 1;
+export const headOf = ({ starts }, section) => (starts[section] ?? 0) + section;
+export const itemsIn = (sections, entries, count) => {
+    const item = (entry) => {
+        if (entry >= count + sections.starts.length) {
+            return count;
+        }
+        const section = lastUpTo(sections.starts.length, (index) => headOf(sections, index), entry);
+        return Math.max(sections.starts[section] ?? 0, entry - section - 1);
+    };
+    return { first: item(entries.first), last: Math.max(item(entries.first), item(entries.last)) };
+};