@ixfx/components 0.11.6 → 0.11.8

package/bundle/index.js

@@ -5,10 +5,10 @@ import { styleMap } from "lit/directives/style-map.js";
 import { unsafeHTML } from "lit/directives/unsafe-html.js";
 import { Fzf } from "fzf";
 import { createCommandRegistry } from "@clinth/ui-commands";
+import { repeat } from "lit/directives/repeat.js";
 import { Colour } from "@ixfx/visual";
 import { Trees } from "@ixfx/collections";
 import { clamp, clamper, rangeStream, round, scaler } from "@ixfx/numbers";
-import { repeat } from "lit/directives/repeat.js";
 import { classMap } from "lit/directives/class-map.js";
 import { createRef, ref } from "lit/directives/ref.js";
 import { Easings } from "@ixfx/modulation";
@@ -5549,6 +5549,56 @@ __decorate([state()], RadioGroup.prototype, "_icons", void 0);
 __decorate([query(`slot`)], RadioGroup.prototype, "_slot", void 0);
 RadioGroup = __decorate([safeCustomElement(`ixfx-radio-group`)], RadioGroup);
 //#endregion
+//#region src/interaction/grouping.ts
+/** Label shown for the empty group key. */
+const EMPTY_GROUP_LABEL = `(none)`;
+/** Default header label: the key, or `(none)` for the empty key. */
+function defaultGroupLabel(key) {
+	return key === `` ? EMPTY_GROUP_LABEL : key;
+}
+/** Coerce a raw group value to a key, as data-grid does. */
+function toGroupKey(value) {
+	return String(value ?? ``);
+}
+/**
+* Group key for `item`. A string `groupBy` is resolved through `readNamed`
+* (property or `data-*` lookup, supplied by the host); a function is called.
+*/
+function resolveGroupKey(groupBy, item, index, readNamed) {
+	if (typeof groupBy === `string`) return toGroupKey(readNamed(item, groupBy));
+	return toGroupKey(groupBy(item, index));
+}
+/**
+* Split `items` into groups in first-encounter order. Single pass, O(n).
+* Item order within a group is preserved.
+*/
+function partitionByGroup(items, keyOf, labelOf) {
+	const byKey = /* @__PURE__ */ new Map();
+	for (let i = 0; i < items.length; i++) {
+		const key = keyOf(items[i], i);
+		const existing = byKey.get(key);
+		if (existing) existing.items.push(items[i]);
+		else byKey.set(key, {
+			key,
+			items: [items[i]],
+			firstIndex: i
+		});
+	}
+	return [...byKey.values()].map((g) => ({
+		key: g.key,
+		items: g.items,
+		firstIndex: g.firstIndex,
+		label: labelOf ? labelOf(g.key, g.items) : defaultGroupLabel(g.key)
+	}));
+}
+/** Immutable toggle of `key` in `set`. */
+function toggleInSet(set, key) {
+	const next = new Set(set);
+	if (next.has(key)) next.delete(key);
+	else next.add(key);
+	return next;
+}
+//#endregion
 //#region src/interaction/list-drag-preview-default.ts
 const CARD_DEFAULT = 72;
 const CARD_MIN = 48;
@@ -6670,6 +6720,10 @@ var ListSelectionController = class {
 		if (next.has(item)) next.delete(item);
 		else {
 			if (!this.canSelectMultiple()) next.clear();
+			if (this.#clamped()) {
+				const g = this.#groupOf(item);
+				for (const other of [...next]) if (this.#groupOf(other) !== g) next.delete(other);
+			}
 			next.add(item);
 		}
 		this.#apply(next);
@@ -6688,6 +6742,22 @@ var ListSelectionController = class {
 			this.replace(item);
 			return;
 		}
+		if (this.#clamped()) {
+			const group = this.#groupOf(this.#anchor);
+			if (group !== this.#groupOf(item)) {
+				this.replace(item);
+				return;
+			}
+			const inGroup = ordered.filter((t) => this.#groupOf(t) === group);
+			const a = inGroup.indexOf(this.#anchor);
+			const b = inGroup.indexOf(item);
+			if (a === -1 || b === -1) {
+				this.replace(item);
+				return;
+			}
+			this.#apply(new Set(inGroup.slice(Math.min(a, b), Math.max(a, b) + 1).filter((t) => this.#config.isSelectable(t))));
+			return;
+		}
 		const start = Math.min(anchorIdx, targetIdx);
 		const end = Math.max(anchorIdx, targetIdx);
 		this.#apply(new Set(ordered.slice(start, end + 1).filter((t) => this.#config.isSelectable(t))));
@@ -6699,8 +6769,12 @@ var ListSelectionController = class {
 	}
 	/** Select every ordered item that passes `isSelectable`. */
 	selectAll() {
-		const ordered = this.#config.getOrderedItems();
+		let ordered = this.#config.getOrderedItems();
 		if (ordered.length === 0) return;
+		if (this.#clamped()) {
+			const group = (this.#anchor === void 0 ? null : this.#groupOf(this.#anchor)) ?? this.#config.getFallbackGroupKey?.() ?? null;
+			if (group !== null) ordered = ordered.filter((t) => this.#groupOf(t) === group);
+		}
 		const next = new Set(ordered.filter((t) => this.#config.isSelectable(t)));
 		if (next.size === 0) return;
 		this.#apply(next);
@@ -6712,7 +6786,7 @@ var ListSelectionController = class {
 	selectMany(items) {
 		const { selectionMode } = this.#config.getModes();
 		if (selectionMode !== `multiple`) throw new Error(`selectMany requires selectionMode="multiple" (current: "${selectionMode}")`);
-		const next = new Set([...items].filter((t) => this.#config.isSelectable(t)));
+		const next = this.#clampToFirstGroup(new Set([...items].filter((t) => this.#config.isSelectable(t))));
 		if (next.size === 0) return;
 		this.#anchor = [...next].at(-1);
 		this.#apply(next);
@@ -6737,7 +6811,7 @@ var ListSelectionController = class {
 	*/
 	applyDragSelection(items) {
 		if (!this.canDragSelect()) return;
-		const next = new Set([...items].filter((t) => this.#config.isSelectable(t)));
+		const next = this.#clampToFirstGroup(new Set([...items].filter((t) => this.#config.isSelectable(t))));
 		if (next.size === 0 && this.#selected.size === 0) return;
 		this.#anchor = [...next].at(-1);
 		this.#apply(next);
@@ -6866,6 +6940,20 @@ var ListSelectionController = class {
 		this.#selected = new Set(items);
 		this.#anchor = anchor;
 	}
+	/** Whether gestures must stay inside one group. */
+	#clamped() {
+		return this.#config.getGroupKey !== void 0 && !(this.#config.crossGroupSelection?.() ?? false);
+	}
+	#groupOf(item) {
+		return this.#config.getGroupKey?.(item) ?? null;
+	}
+	/** Keep only items in the group of the first item (in display order) when clamped. */
+	#clampToFirstGroup(items) {
+		if (!this.#clamped() || items.size === 0) return new Set(items);
+		const first = this.#config.getOrderedItems().find((t) => items.has(t)) ?? [...items][0];
+		const group = this.#groupOf(first);
+		return new Set([...items].filter((t) => this.#groupOf(t) === group));
+	}
 	#apply(next) {
 		const previous = this.#selected;
 		this.#selected = next;
@@ -8238,6 +8326,7 @@ SplitButton = __decorate([safeCustomElement(`ixfx-split-button`)], SplitButton);
 * Properties
 *   checked   – checkbox state (default: false)
 *   disabled  – disabled state (default: false)
+*   readonly  – display-only: no pointer/keyboard interaction, full opacity (default: false)
 *   label     – label text
 *   name      – form field name
 *   value     – form field value
@@ -8269,12 +8358,14 @@ let Checkbox = class Checkbox extends LitElement {
 		this.checked = false;
 		this.disabled = false;
 		this.indeterminate = false;
+		this.readonly = false;
 		this.label = ``;
 		this.name = ``;
 		this.value = ``;
 		this.#handleChange = (e) => {
 			const target = e.target;
 			this.checked = target.checked;
+			this.indeterminate = false;
 			this.dispatchEvent(new CustomEvent(`change`, {
 				detail: { checked: this.checked },
 				bubbles: true,
@@ -8337,6 +8428,16 @@ let Checkbox = class Checkbox extends LitElement {
       opacity: var(--box-opacity-checked);
     }
 
+    /* Display-only: inert, keeps full opacity, no hover reveal */
+    :host([readonly]) {
+      pointer-events: none;
+    }
+    :host([readonly]) label,
+    :host([readonly]) label:hover {
+      cursor: default;
+      opacity: var(--box-opacity-checked);
+    }
+
     input {
       position: absolute;
       opacity: 0;
@@ -8448,6 +8549,10 @@ let Checkbox = class Checkbox extends LitElement {
   `
 		];
 	}
+	/** Focus the inner input, so the host can be focused like a native checkbox. */
+	focus(options) {
+		this.renderRoot.querySelector(`input`)?.focus(options);
+	}
 	#handleChange;
 	render() {
 		return html`
@@ -8457,6 +8562,8 @@ let Checkbox = class Checkbox extends LitElement {
           type="checkbox"
           .checked=${this.checked}
           .disabled=${this.disabled}
+          tabindex=${this.readonly ? `-1` : nothing}
+          aria-hidden=${this.readonly ? `true` : nothing}
           .indeterminate=${this.indeterminate}
           .name=${this.name}
           .value=${this.value}
@@ -8471,10 +8578,605 @@ let Checkbox = class Checkbox extends LitElement {
 __decorate([property({ type: Boolean })], Checkbox.prototype, "checked", void 0);
 __decorate([property({ type: Boolean })], Checkbox.prototype, "disabled", void 0);
 __decorate([property({ type: Boolean })], Checkbox.prototype, "indeterminate", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+})], Checkbox.prototype, "readonly", void 0);
 __decorate([property({ type: String })], Checkbox.prototype, "label", void 0);
 __decorate([property({ type: String })], Checkbox.prototype, "name", void 0);
 __decorate([property({ type: String })], Checkbox.prototype, "value", void 0);
 Checkbox = __decorate([safeCustomElement(`ixfx-checkbox`)], Checkbox);
+//#endregion
+//#region src/checked-select/logic.ts
+function byLabel(a, b) {
+	return a.label.localeCompare(b.label, void 0, { sensitivity: `base` });
+}
+/** Checked/indeterminate items first, then the rest; each group sorted by label. */
+function sortForOpen(items) {
+	const on = items.filter((i) => i.checked !== `false`).toSorted(byLabel);
+	const off = items.filter((i) => i.checked === `false`).toSorted(byLabel);
+	return [...on, ...off];
+}
+/** User toggle: indeterminate and unchecked become checked, checked becomes unchecked. */
+function toggleState(state) {
+	return state === `true` ? `false` : `true`;
+}
+/** Items shown in the resting state, alphabetically. */
+function visibleAtRest(items) {
+	return items.filter((i) => i.checked !== `false`).toSorted(byLabel);
+}
+const VARIES_LABEL = `(varies)`;
+/** Resting text entries: checked labels, then a single `(varies)` if any are indeterminate. */
+function restTextParts(items) {
+	const on = items.filter((i) => i.checked === `true`).toSorted(byLabel).map((i) => i.label);
+	const varies = items.some((i) => i.checked === `indeterminate`) ? [VARIES_LABEL] : [];
+	return [...on, ...varies];
+}
+/** Plain-text resting summary, comma separated. */
+function restText(items) {
+	return restTextParts(items).join(`, `);
+}
+/** Returns a new list with the item matching `value` toggled. */
+function applyToggle(items, value) {
+	return items.map((i) => i.value === value ? {
+		...i,
+		checked: toggleState(i.checked)
+	} : i);
+}
+/**
+* Index of the next label after `current` beginning with `char` (case-insensitive),
+* wrapping around. Returns -1 if nothing matches.
+*/
+function nextMatchIndex(labels, current, char) {
+	const c = char.toLocaleLowerCase();
+	const count = labels.length;
+	for (let step = 1; step <= count; step++) {
+		const index = (current + step + count) % count;
+		if (labels[index].toLocaleLowerCase().startsWith(c)) return index;
+	}
+	return -1;
+}
+/** Items in `draft` whose state differs from `original`. */
+function diffItems(original, draft) {
+	const before = new Map(original.map((i) => [i.value, i.checked]));
+	return draft.filter((i) => before.get(i.value) !== i.checked);
+}
+function clampSize(size, min, max) {
+	return {
+		width: Math.min(Math.max(size.width, min.width), Math.max(max.width, min.width)),
+		height: Math.min(Math.max(size.height, min.height), Math.max(max.height, min.height))
+	};
+}
+//#endregion
+//#region src/checked-select/checked-select.ts
+let instanceCounter = 0;
+let CheckedSelect = class CheckedSelect extends LitElement {
+	constructor(..._args) {
+		super(..._args);
+		this.items = [];
+		this.multiline = false;
+		this.itemsInert = false;
+		this.itemDisplay = `checkbox`;
+		this.orientation = `horizontal`;
+		this.placeholder = ``;
+		this.disabled = false;
+		this._open = false;
+		this._draft = [];
+		this._order = [];
+		this.#anchorName = `--checked-select-anchor-${instanceCounter++}`;
+		this.#tickled = new TickledController(this, { getItems: () => this._order.map((_, i) => ({ id: i })) });
+		this.#onRestCheckboxChange = (e, value) => {
+			e.stopPropagation();
+			if (this._open) return;
+			const next = applyToggle(this.items, value);
+			this.#emitChange(next, diffItems(this.items, next));
+			this.#focusRestCheckbox(value);
+		};
+		this.#onDocumentPointerDown = (e) => {
+			const path = e.composedPath();
+			const popup = this.#popup;
+			const trigger = this.#trigger;
+			if (popup && path.includes(popup) || trigger && path.includes(trigger)) return;
+			this.cancel();
+		};
+		this.#onTriggerClick = (e) => {
+			if (e.target.closest?.(`ixfx-checkbox`)) return;
+			const scroller = e.composedPath()[0];
+			if (scroller.classList?.contains(`rest-items`) && e instanceof MouseEvent && (e.offsetX > scroller.clientWidth || e.offsetY > scroller.clientHeight)) return;
+			if (this._open) this.commit();
+			else this.open();
+		};
+		this.#onTriggerKeyDown = (e) => {
+			if (this._open || e.target !== e.currentTarget) return;
+			if (e.key === `Enter` || e.key === ` ` || e.key === `ArrowDown`) {
+				e.preventDefault();
+				this.open();
+			}
+		};
+		this.#onListKeyDown = (e) => {
+			const rows = this.#rows();
+			switch (e.key) {
+				case `ArrowDown`:
+					e.preventDefault();
+					this.#tickled.handleKeyboardNavigation(`next`);
+					this.#scrollToCursor();
+					return;
+				case `ArrowUp`:
+					e.preventDefault();
+					this.#tickled.handleKeyboardNavigation(`previous`);
+					this.#scrollToCursor();
+					return;
+				case `Home`:
+					e.preventDefault();
+					this.#tickled.handleKeyboardNavigation(`first`);
+					this.#scrollToCursor();
+					return;
+				case `End`:
+					e.preventDefault();
+					this.#tickled.handleKeyboardNavigation(`last`);
+					this.#scrollToCursor();
+					return;
+				case ` `: {
+					e.preventDefault();
+					const row = rows[this.#tickled.tickledId ?? -1];
+					if (row) this.#toggleRow(row.value);
+					return;
+				}
+				case `Enter`:
+					e.preventDefault();
+					this.commit();
+					return;
+				case `Escape`:
+					e.preventDefault();
+					this.cancel();
+					return;
+				case `Tab`:
+					this.cancel();
+					return;
+			}
+			if (e.key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) {
+				const next = nextMatchIndex(rows.map((r) => r.label), this.#tickled.tickledId ?? -1, e.key);
+				if (next >= 0) {
+					this.#tickled.handleKeyboardNavigation(next);
+					this.#scrollToCursor();
+				}
+			}
+		};
+		this.#onResizeDown = (e) => {
+			const frame = this.shadowRoot?.querySelector(`.frame`);
+			const zone = e.currentTarget;
+			if (!frame) return;
+			e.preventDefault();
+			const start = frame.getBoundingClientRect();
+			const originX = e.clientX;
+			const originY = e.clientY;
+			const style = getComputedStyle(this);
+			const min = {
+				width: Number.parseFloat(style.getPropertyValue(`--checked-select-min-width`)) || 128,
+				height: Number.parseFloat(style.getPropertyValue(`--checked-select-min-height`)) || 80
+			};
+			const max = {
+				width: window.innerWidth - start.left - 8,
+				height: window.innerHeight - start.top - 8
+			};
+			zone.setPointerCapture?.(e.pointerId);
+			zone.setAttribute(`data-active`, ``);
+			const onMove = (m) => {
+				this._size = clampSize({
+					width: start.width + m.clientX - originX,
+					height: start.height + m.clientY - originY
+				}, min, max);
+			};
+			const onEnd = () => {
+				zone.removeAttribute(`data-active`);
+				zone.removeEventListener(`pointermove`, onMove);
+				zone.removeEventListener(`pointerup`, onEnd);
+				zone.removeEventListener(`pointercancel`, onEnd);
+				this.#listbox?.focus();
+			};
+			zone.addEventListener(`pointermove`, onMove);
+			zone.addEventListener(`pointerup`, onEnd);
+			zone.addEventListener(`pointercancel`, onEnd);
+		};
+	}
+	static {
+		this.styles = [
+			themeFallbacks,
+			handleStyles,
+			tickledStyles,
+			tickledItemStyles,
+			css`
+    :host {
+      --checked-select-gap: var(--space-m);
+      --checked-select-padding: var(--space-s) var(--space-m);
+      --checked-select-caret-width: 2rem;
+      --checked-select-rest-max-height: 8rem;
+      --checked-select-max-height: 16rem;
+      --checked-select-min-width: 8rem;
+      --checked-select-min-height: 5rem;
+
+      display: block;
+      position: relative;
+    }
+
+    :host([disabled]) {
+      opacity: var(--prominence-disabled-opacity, 0.4);
+      pointer-events: none;
+    }
+
+    .rest {
+      position: relative;
+      box-sizing: border-box;
+      cursor: pointer;
+      background: var(--surface-4);
+      color: var(--surface-4-text);
+      border: var(--border);
+      border-radius: var(--radius-m);
+      user-select: none;
+    }
+
+    .rest-items {
+      display: flex;
+      flex-wrap: nowrap;
+      align-items: center;
+      gap: var(--checked-select-gap);
+      padding: var(--checked-select-padding);
+      /* Room to scroll the last item clear of the caret */
+      padding-inline-end: var(--checked-select-caret-width);
+      min-height: 1.5em;
+      box-sizing: border-box;
+      overflow-x: auto;
+      overflow-y: hidden;
+      scrollbar-width: thin;
+    }
+    :host([multiline]) .rest-items {
+      flex-wrap: wrap;
+      overflow-x: hidden;
+      overflow-y: auto;
+      max-height: var(--checked-select-rest-max-height);
+      /* Wrapping never runs under the caret, so keep its column clear (and the scrollbar beside it) */
+      padding-inline-end: var(--space-m);
+      margin-inline-end: var(--checked-select-caret-width);
+    }
+
+    /* Vertical: one item per row, scrolling vertically beside the caret. Must follow the multiline rule. */
+    :host([orientation="vertical"]) .rest-items {
+      flex-direction: column;
+      flex-wrap: nowrap;
+      align-items: flex-start;
+      overflow-x: hidden;
+      overflow-y: auto;
+      max-height: var(--checked-select-rest-max-height);
+      padding-inline-end: var(--space-m);
+      margin-inline-end: var(--checked-select-caret-width);
+    }
+
+    /* Always-visible caret; items scroll underneath it */
+    .caret {
+      position: absolute;
+      inset-block: 0;
+      inset-inline-end: 0;
+      width: var(--checked-select-caret-width);
+      display: grid;
+      place-items: center;
+      background: inherit;
+      border-radius: inherit;
+      pointer-events: auto;
+    }
+    .caret svg {
+      width: 1.1em;
+      height: 1.1em;
+      fill: none;
+      stroke: currentColor;
+      stroke-width: 2;
+      stroke-linecap: round;
+      stroke-linejoin: round;
+      transition: rotate var(--transition, 0.1s ease-out);
+    }
+    .rest[aria-expanded="true"] .caret svg {
+      rotate: 180deg;
+    }
+    /* While the popup is open its draft is authoritative */
+    .rest[aria-expanded="true"] ixfx-checkbox {
+      pointer-events: none;
+    }
+    .rest:hover {
+      background: var(--surface-5);
+    }
+    .rest:focus-visible {
+      outline: 2px solid var(--accent);
+      outline-offset: 2px;
+    }
+    .rest ixfx-checkbox {
+      flex-shrink: 0;
+    }
+    .rest-text {
+      white-space: nowrap;
+    }
+    :host([multiline]) .rest-text {
+      white-space: normal;
+    }
+    .placeholder {
+      opacity: 0.6;
+    }
+
+    .popup {
+      /* Reset popover UA styles */
+      inset: unset;
+      margin: 0;
+      padding: 0;
+      border: none;
+      background: transparent;
+      overflow: visible;
+
+      /* CSS anchor positioning — position-anchor set inline */
+      position: fixed;
+      left: anchor(left);
+      top: anchor(bottom);
+      /* anchor-size() only works on the anchored element itself, so the width lives here */
+      width: anchor-size(width);
+      min-width: var(--checked-select-min-width);
+      position-try-fallbacks: flip-block;
+      margin-block: 4px;
+      z-index: 100;
+    }
+
+    .frame {
+      position: relative;
+      box-sizing: border-box;
+      display: flex;
+      flex-direction: column;
+      width: 100%;
+      max-height: var(--checked-select-max-height);
+      background: var(--surface-3);
+      color: var(--surface-3-text);
+      border: var(--border);
+      border-radius: var(--radius-m);
+    }
+
+    .listbox {
+      flex: 1;
+      min-height: 0;
+      overflow-y: auto;
+      padding: var(--space-s);
+      outline: none;
+    }
+    .listbox:focus-visible {
+      outline: 2px solid var(--accent);
+      outline-offset: -2px;
+    }
+
+    .item {
+      display: flex;
+      width: 100%;
+      box-sizing: border-box;
+    }
+
+    /* Key-repeat outpaces the fade, smearing the cursor across rows. Snap while
+       the keyboard drives the cursor; hover (mouse mode) keeps the transition. */
+    .listbox[data-input-mode="keyboard"] .item {
+      transition: none;
+    }
+
+    .resize-zone {
+      position: absolute;
+      inset-block-end: 0;
+      inset-inline-end: 0;
+      width: 16px;
+      height: 16px;
+      display: grid;
+      place-items: center;
+      cursor: nwse-resize;
+      touch-action: none;
+    }
+    .resize-zone .ixfx-handle {
+      --ixfx-handle-spot-size: 10px;
+    }
+  `
+		];
+	}
+	#anchorName;
+	#tickled;
+	get isOpen() {
+		return this._open;
+	}
+	get #trigger() {
+		return this.shadowRoot?.querySelector(`.rest`) ?? null;
+	}
+	get #popup() {
+		return this.shadowRoot?.querySelector(`.popup`) ?? null;
+	}
+	get #listbox() {
+		return this.shadowRoot?.querySelector(`.listbox`) ?? null;
+	}
+	/** Draft items in their frozen open-time order. */
+	#rows() {
+		const byValue = new Map(this._draft.map((i) => [i.value, i]));
+		return this._order.flatMap((v) => byValue.get(v) ?? []);
+	}
+	disconnectedCallback() {
+		super.disconnectedCallback();
+		document.removeEventListener(`pointerdown`, this.#onDocumentPointerDown, true);
+	}
+	willUpdate(changed) {
+		super.willUpdate(changed);
+		if (changed.has(`disabled`) && this.disabled && this._open) this.cancel();
+	}
+	async open() {
+		if (this._open || this.disabled) return;
+		this._draft = this.items;
+		this._order = sortForOpen(this.items).map((i) => i.value);
+		this._size = void 0;
+		this._open = true;
+		if (this._order.length > 0) this.#tickled.handleKeyboardNavigation(`first`);
+		document.addEventListener(`pointerdown`, this.#onDocumentPointerDown, true);
+		await this.updateComplete;
+		this.#popup?.showPopover?.();
+		this.#listbox?.focus();
+	}
+	commit() {
+		if (!this._open) return;
+		const changed = diffItems(this.items, this._draft);
+		const next = this._draft;
+		this.#close();
+		if (changed.length === 0) return;
+		this.#emitChange(next, changed);
+	}
+	#emitChange(next, changed) {
+		this.items = next;
+		this.dispatchEvent(new CustomEvent(`change`, {
+			detail: {
+				items: next,
+				changed
+			},
+			bubbles: true,
+			composed: true
+		}));
+	}
+	/** A resting checkbox was used directly: toggle and commit immediately. */
+	#onRestCheckboxChange;
+	async #focusRestCheckbox(value) {
+		await this.updateComplete;
+		(this.shadowRoot?.querySelector(`.rest ixfx-checkbox[data-value="${CSS.escape(value)}"]`) ?? this.#trigger)?.focus();
+	}
+	cancel() {
+		if (!this._open) return;
+		this.#close();
+	}
+	#close() {
+		document.removeEventListener(`pointerdown`, this.#onDocumentPointerDown, true);
+		this.#popup?.hidePopover?.();
+		this._open = false;
+		this._draft = [];
+		this.#tickled.clearTickled();
+		this.#trigger?.focus();
+	}
+	#onDocumentPointerDown;
+	#onTriggerClick;
+	#onTriggerKeyDown;
+	#toggleRow(value) {
+		this._draft = applyToggle(this._draft, value);
+	}
+	#onRowClick(value, index) {
+		this.#tickled.setTickled(index);
+		this.#toggleRow(value);
+	}
+	#onListKeyDown;
+	async #scrollToCursor() {
+		await this.updateComplete;
+		const index = this.#tickled.tickledId;
+		this.shadowRoot?.querySelector(`[data-index="${index}"]`)?.scrollIntoView?.({ block: `nearest` });
+	}
+	#onResizeDown;
+	#renderRest() {
+		const shown = visibleAtRest(this.items);
+		if (shown.length === 0) return html`<span class="placeholder">${this.placeholder}</span>`;
+		if (this.itemDisplay === `text`) {
+			if (this.orientation === `vertical`) return restTextParts(this.items).map((part) => html`<span class="rest-text">${part}</span>`);
+			return html`<span class="rest-text">${restText(this.items)}</span>`;
+		}
+		return repeat(shown, (i) => i.value, (i) => html`
+      <ixfx-checkbox
+        ?readonly=${this.itemsInert}
+        data-value=${i.value}
+        label=${i.label}
+        .checked=${i.checked === `true`}
+        .indeterminate=${i.checked === `indeterminate`}
+        @change=${(e) => this.#onRestCheckboxChange(e, i.value)}
+      ></ixfx-checkbox>`);
+	}
+	#renderRow(row, index) {
+		return html`
+      <div
+        class="item ${this.#tickled.isTickled(index) ? `tickled` : ``}"
+        role="option"
+        id="opt-${index}"
+        data-index=${index}
+        aria-checked=${row.checked === `indeterminate` ? `mixed` : row.checked}
+        @pointerenter=${() => this.#tickled.handlePointerEnter(index)}
+        @click=${() => this.#onRowClick(row.value, index)}
+      >
+        <ixfx-checkbox
+          readonly
+          label=${row.label}
+          .checked=${row.checked === `true`}
+          .indeterminate=${row.checked === `indeterminate`}
+        ></ixfx-checkbox>
+      </div>`;
+	}
+	render() {
+		const rows = this._open ? this.#rows() : [];
+		const cursor = this.#tickled.tickledId;
+		const popupSize = this._size ? `width: ${this._size.width}px;` : ``;
+		const frameStyle = this._size ? `height: ${this._size.height}px; max-height: none;` : ``;
+		const summary = visibleAtRest(this.items).map((i) => i.label).join(`, `);
+		return html`
+      <div
+        class="rest"
+        role="combobox"
+        tabindex=${this.disabled ? `-1` : `0`}
+        aria-haspopup="listbox"
+        aria-expanded=${this._open ? `true` : `false`}
+        aria-disabled=${this.disabled ? `true` : nothing}
+        title=${summary || nothing}
+        style="anchor-name: ${this.#anchorName}"
+        @click=${this.#onTriggerClick}
+        @keydown=${this.#onTriggerKeyDown}
+      >
+        <div class="rest-items">${this.#renderRest()}</div>
+        <div class="caret" aria-hidden="true">
+          <svg viewBox="0 0 24 24"><path d="m6 9 6 6 6-6" /></svg>
+        </div>
+      </div>
+      <div class="popup" popover="manual" style="position-anchor: ${this.#anchorName}; ${popupSize}">
+        <div class="frame" style=${frameStyle}>
+          <div
+            class="listbox"
+            role="listbox"
+            aria-multiselectable="true"
+            tabindex="-1"
+            aria-activedescendant=${cursor === void 0 ? nothing : `opt-${cursor}`}
+            data-input-mode=${this.#tickled.inputMode}
+            @pointerleave=${(e) => this.#tickled.handlePointerLeave(e)}
+            @keydown=${this.#onListKeyDown}
+          >${rows.map((r, i) => this.#renderRow(r, i))}</div>
+          <div class="resize-zone" @pointerdown=${this.#onResizeDown}>
+            <span class="ixfx-handle" data-handle="dotted" data-shape="spot" part="handle"></span>
+          </div>
+        </div>
+      </div>
+    `;
+	}
+};
+__decorate([property({ type: Array })], CheckedSelect.prototype, "items", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+})], CheckedSelect.prototype, "multiline", void 0);
+__decorate([property({
+	type: Boolean,
+	attribute: `items-inert`,
+	reflect: true
+})], CheckedSelect.prototype, "itemsInert", void 0);
+__decorate([property({
+	type: String,
+	attribute: `item-display`,
+	reflect: true
+})], CheckedSelect.prototype, "itemDisplay", void 0);
+__decorate([property({
+	type: String,
+	reflect: true
+})], CheckedSelect.prototype, "orientation", void 0);
+__decorate([property({ type: String })], CheckedSelect.prototype, "placeholder", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+})], CheckedSelect.prototype, "disabled", void 0);
+__decorate([state()], CheckedSelect.prototype, "_open", void 0);
+__decorate([state()], CheckedSelect.prototype, "_draft", void 0);
+__decorate([state()], CheckedSelect.prototype, "_order", void 0);
+__decorate([state()], CheckedSelect.prototype, "_size", void 0);
+CheckedSelect = __decorate([safeCustomElement(`ixfx-checked-select`)], CheckedSelect);
 const RANGE_LIMITS = {
 	l: [0, 1],
 	c: [0, .4],
@@ -16559,9 +17261,134 @@ __decorate([state()], DataTableElement.prototype, "_detailIndex", void 0);
 __decorate([state()], DataTableElement.prototype, "_stacked", void 0);
 DataTableElement = __decorate([safeCustomElement(`ixfx-data-table`)], DataTableElement);
 //#endregion
+//#region src/list-group-header/list-group-header.ts
+let ListGroupHeaderElement = class ListGroupHeaderElement extends LitElement {
+	constructor(..._args) {
+		super(..._args);
+		this.label = ``;
+		this.count = 0;
+		this.collapsed = false;
+		this.orientation = `horizontal`;
+	}
+	static {
+		this.styles = css`
+    :host {
+      --_height: var(--list-group-header-height, 28px);
+      --_border: var(--list-group-header-border, var(--border));
+
+      display: flex;
+      align-items: center;
+      gap: var(--space-s);
+      box-sizing: border-box;
+      min-height: var(--_height);
+      padding: 0 var(--space-s);
+      background: transparent;
+      color: var(--list-group-header-text, var(--surface-3-text));
+      border-bottom: 1px solid var(--_border);
+      font-weight: 600;
+      cursor: pointer;
+      user-select: none;
+    }
+
+    .caret {
+      display: inline-flex;
+      transition: transform 0.15s;
+    }
+
+    :host([collapsed]) .caret {
+      transform: rotate(-90deg);
+    }
+
+    .count {
+      opacity: 0.6;
+      font-weight: 400;
+      font-size: 0.9em;
+    }
+
+    .label {
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+      min-width: 0;
+    }
+
+    .divider {
+      flex: 1;
+      height: 1px;
+      background: var(--_border);
+      margin-left: var(--space-s);
+    }
+
+    /* Single-row (grid-list \`row\` orientation) layout: a narrow column cell. */
+    :host([orientation="vertical"]) {
+      flex-direction: column;
+      justify-content: flex-start;
+      padding: var(--space-s) 0;
+      border-bottom: 0;
+      border-right: 1px solid var(--_border);
+      min-height: 0;
+    }
+
+    :host([orientation="vertical"]) .divider {
+      width: 1px;
+      height: auto;
+      margin-left: 0;
+      margin-top: var(--space-s);
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+      .caret { transition: none; }
+    }
+  `;
+	}
+	connectedCallback() {
+		super.connectedCallback();
+		this.setAttribute(`role`, `button`);
+	}
+	willUpdate() {
+		this.setAttribute(`aria-expanded`, this.collapsed ? `false` : `true`);
+		this.setAttribute(`aria-label`, `${this.label}, ${this.count} ${this.count === 1 ? `item` : `items`}`);
+	}
+	render() {
+		return html`
+      <span class="caret"><ixfx-icon name="chevron-down" size="12"></ixfx-icon></span>
+      <span class="label" part="label">${this.label}</span>
+      <span class="count" part="count">(${this.count})</span>
+      <span class="divider" part="divider"></span>
+    `;
+	}
+};
+__decorate([property({
+	type: String,
+	reflect: true
+})], ListGroupHeaderElement.prototype, "label", void 0);
+__decorate([property({
+	type: Number,
+	reflect: true
+})], ListGroupHeaderElement.prototype, "count", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+})], ListGroupHeaderElement.prototype, "collapsed", void 0);
+__decorate([property({
+	type: String,
+	reflect: true
+})], ListGroupHeaderElement.prototype, "orientation", void 0);
+ListGroupHeaderElement = __decorate([safeCustomElement(`ixfx-list-group-header`)], ListGroupHeaderElement);
+//#endregion
 //#region src/detail-list/detail-list.ts
 const ITEM_SELECTOR$3 = `:scope > li`;
+const GROUP_HEADER_ATTR = `data-ixfx-group-header`;
+const GROUP_COLLAPSED_ATTR = `data-group-collapsed`;
 const SEARCH_HIGHLIGHT_KEY = `detail-list-search`;
+const NAV_KEYS = /* @__PURE__ */ new Set([
+	`ArrowDown`,
+	`ArrowUp`,
+	`ArrowLeft`,
+	`ArrowRight`,
+	`Home`,
+	`End`
+]);
 const LABEL_SPAN_CSS = `overflow:hidden;text-overflow:ellipsis;white-space:nowrap;min-width:0`;
 /**
 * Layout for the per-item badge wrapper `#ensureBadge` adds. Applied as inline
@@ -16610,14 +17437,26 @@ let DetailListElement = class DetailListElement extends LitElement {
 		this.keyProperty = ``;
 		this.itemWrap = `stop`;
 		this.itemsDraggable = false;
+		this.groupBy = null;
+		this.crossGroupSelection = false;
+		this._collapsedGroups = /* @__PURE__ */ new Set();
 		this.#itemData = /* @__PURE__ */ new WeakMap();
 		this.#grid = [];
 		this.#positions = /* @__PURE__ */ new Map();
+		this.#tops = /* @__PURE__ */ new Map();
 		this.#geometryScheduled = false;
 		this.#sortRaf = 0;
 		this.#viewportScrollRaf = 0;
 		this.#animatedItems = /* @__PURE__ */ new WeakSet();
 		this.#builtFromProvider = [];
+		this.#groupIndex = /* @__PURE__ */ new Map();
+		this.#groupList = [];
+		this.#headerEls = /* @__PURE__ */ new Map();
+		this.#seq = /* @__PURE__ */ new WeakMap();
+		this.#seqNext = 0;
+		this.#wasGrouped = false;
+		this.#groupsScheduled = false;
+		this.#groupByChanged = false;
 		this.#providerBuilt = 0;
 		this.#data = new DataController(this);
 		this.selection = new ListSelectionController({
@@ -16628,6 +17467,12 @@ let DetailListElement = class DetailListElement extends LitElement {
 				interactionMode: this.interactionMode
 			}),
 			getKey: keyForElement,
+			getGroupKey: (el) => this.#groupIndex.get(el) ?? null,
+			crossGroupSelection: () => this.crossGroupSelection,
+			getFallbackGroupKey: () => {
+				const t = this.tickled.tickledId;
+				return t ? this.#groupIndex.get(t) ?? null : null;
+			},
 			onChange: (selected, previous) => {
 				this._syncItemStates();
 				this._dispatch(`list-select`, {
@@ -16709,6 +17554,7 @@ let DetailListElement = class DetailListElement extends LitElement {
 				if (this._listEl) this._listEl.scrollLeft += dx;
 			},
 			shouldStart: (event) => {
+				if (this.#findGroupHeader(event.composedPath())) return false;
 				this.#blankItemPressPending = this.itemsDraggable && this.#isBlankItemPress(event);
 				return !this.itemsDraggable || this.#blankItemPressPending;
 			}
@@ -16732,6 +17578,9 @@ let DetailListElement = class DetailListElement extends LitElement {
 		this._onPointerLeave = (e) => {
 			this.tickled.handlePointerLeave(e);
 		};
+		this._endKeyboardNav = () => {
+			this.removeAttribute(`data-keyboard-nav`);
+		};
 		this._onKeyDown = (e) => {
 			if (this.search.isOpen) return;
 			if ((e.ctrlKey || e.metaKey) && e.key === `a`) {
@@ -16741,6 +17590,7 @@ let DetailListElement = class DetailListElement extends LitElement {
 				}
 				return;
 			}
+			if (NAV_KEYS.has(e.key)) this.setAttribute(`data-keyboard-nav`, ``);
 			switch (e.key) {
 				case `ArrowDown`:
 					e.preventDefault();
@@ -16796,7 +17646,13 @@ let DetailListElement = class DetailListElement extends LitElement {
 		};
 		this._onClick = (e) => {
 			if (this.#dragSelect.isDragging || this.#nativeDrag.isDragging || this.#postDragSuppressTimer !== 0) return;
-			const item = this._findListItem(e.composedPath());
+			const path = e.composedPath();
+			const header = this.#findGroupHeader(path);
+			if (header) {
+				this.toggleGroup(header.dataset.groupKey ?? ``);
+				return;
+			}
+			const item = this._findListItem(path);
 			if (!item) return;
 			this.focus();
 			this._dispatch(`list-item-click`, { item });
@@ -16815,6 +17671,8 @@ let DetailListElement = class DetailListElement extends LitElement {
 	#itemData;
 	#grid;
 	#positions;
+	/** Viewport-relative `top` per item at the last geometry pass — lines rows up across columns. */
+	#tops;
 	#geometryScheduled;
 	#sortRaf;
 	#viewportScrollRaf;
@@ -16826,6 +17684,17 @@ let DetailListElement = class DetailListElement extends LitElement {
 	/** Items that have already played (or been skipped for) their enter animation. */
 	#animatedItems;
 	#builtFromProvider;
+	/** Element → group key, for the selection controller. Empty while ungrouped. */
+	#groupIndex;
+	#groupList;
+	#headerEls;
+	/** Insertion sequence per item, so regrouping starts from the original order. */
+	#seq;
+	#seqNext;
+	#wasGrouped;
+	#groupsScheduled;
+	#groupByChanged;
+	#groupObserver;
 	#providerBuilt;
 	#data;
 	#nativeDragging;
@@ -16929,6 +17798,8 @@ let DetailListElement = class DetailListElement extends LitElement {
 		this.addEventListener(`pointerover`, this._onPointerOver);
 		this.addEventListener(`pointerleave`, this._onPointerLeave);
 		this.addEventListener(`keydown`, this._onKeyDown);
+		this.addEventListener(`pointermove`, this._endKeyboardNav);
+		this.addEventListener(`pointerdown`, this._endKeyboardNav);
 		this.addEventListener(`click`, this._onClick);
 		this.addEventListener(`dblclick`, this._onDblClick);
 		this.addEventListener(`wheel`, this._onWheel);
@@ -16940,6 +17811,7 @@ let DetailListElement = class DetailListElement extends LitElement {
 			this.#processChildren();
 			this.#animateChildMutations(records);
 			this.#scheduleGeometry();
+			this.#scheduleGroups();
 		});
 		this.#mutationObserver.observe(this, {
 			childList: true,
@@ -16949,6 +17821,7 @@ let DetailListElement = class DetailListElement extends LitElement {
 		for (const el of this.querySelectorAll(ITEM_SELECTOR$3)) this.#animatedItems.add(el);
 		this.#searchRegistry ??= createCommandRegistry();
 		this.#syncSearchCommands();
+		this.#scheduleGroups();
 	}
 	/**
 	* Collapse-in items appended to the light DOM (however they got there). A bulk
@@ -16975,6 +17848,8 @@ let DetailListElement = class DetailListElement extends LitElement {
 		this.removeEventListener(`pointerover`, this._onPointerOver);
 		this.removeEventListener(`pointerleave`, this._onPointerLeave);
 		this.removeEventListener(`keydown`, this._onKeyDown);
+		this.removeEventListener(`pointermove`, this._endKeyboardNav);
+		this.removeEventListener(`pointerdown`, this._endKeyboardNav);
 		this.removeEventListener(`click`, this._onClick);
 		this.removeEventListener(`dblclick`, this._onDblClick);
 		this.removeEventListener(`wheel`, this._onWheel);
@@ -16988,6 +17863,8 @@ let DetailListElement = class DetailListElement extends LitElement {
 		this.#resizeObserver = void 0;
 		this.#mutationObserver?.disconnect();
 		this.#mutationObserver = void 0;
+		this.#groupObserver?.disconnect();
+		this.#groupObserver = void 0;
 		this.#unregisterSearchCommands?.();
 		this.#unregisterSearchCommands = void 0;
 		this.#searchRegistry = void 0;
@@ -17002,8 +17879,22 @@ let DetailListElement = class DetailListElement extends LitElement {
 		this.#recomputeGeometry();
 		this._syncNativeDraggable();
 	}
+	willUpdate(changed) {
+		super.willUpdate(changed);
+		if (changed.has(`groupBy`) && this.hasUpdated) {
+			if (this._collapsedGroups.size > 0) this._collapsedGroups = /* @__PURE__ */ new Set();
+			this.#groupByChanged = true;
+		}
+	}
 	updated(changed) {
 		super.updated(changed);
+		if (changed.has(`groupBy`) || changed.has(`groupLabel`) || changed.has(`_collapsedGroups`)) {
+			this.#scheduleGroups();
+			if (this.#groupByChanged) {
+				this.#groupByChanged = false;
+				this._dispatch(`list-group-change`, { groupBy: this.groupBy });
+			}
+		}
 		if (changed.has(`searchModes`)) this.#syncSearchCommands();
 		if (changed.has(`provider`)) {
 			this.#builtFromProvider = [];
@@ -17020,6 +17911,7 @@ let DetailListElement = class DetailListElement extends LitElement {
 		if (changed.has(`filterPredicate`)) {
 			this.#applyFilterPredicate();
 			this.#scheduleGeometry();
+			this.#scheduleGroups();
 		}
 		if (changed.has(`interactionMode`)) {
 			this.selection.clearAnchor();
@@ -17059,6 +17951,7 @@ let DetailListElement = class DetailListElement extends LitElement {
 		this.#ensureIcon(el);
 		if (this.sort !== `none`) this.#applySort();
 		if (this.interactionMode === `checked`) this._syncCheckboxes();
+		this.#scheduleGroups();
 	}
 	/**
 	* Collapse + fade `item` out, then detach it; the rows after it slide up to
@@ -17068,6 +17961,7 @@ let DetailListElement = class DetailListElement extends LitElement {
 		this.selection.deselect(item);
 		return animateListItemOut(item).then(() => {
 			item.remove();
+			this.#scheduleGroups();
 			if (this.interactionMode === `checked`) this._syncCheckboxes();
 			this.#recomputeGeometry();
 		});
@@ -17078,6 +17972,8 @@ let DetailListElement = class DetailListElement extends LitElement {
 	}
 	clearItems() {
 		this.replaceChildren();
+		this.#headerEls.clear();
+		this.#scheduleGroups();
 		this.selection.reset();
 		this.#builtFromProvider = [];
 		this.#providerBuilt = 0;
@@ -17095,6 +17991,7 @@ let DetailListElement = class DetailListElement extends LitElement {
 		}
 		if (this.sort !== `none`) this.#applySort();
 		if (this.interactionMode === `checked`) this._syncCheckboxes();
+		this.#scheduleGroups();
 	}
 	/**
 	* Get the source object behind an `<li>` built from an `items` array or
@@ -17214,6 +18111,7 @@ let DetailListElement = class DetailListElement extends LitElement {
 		if (this.interactionMode === `checked`) this._syncCheckboxes();
 		this._syncItemStates();
 		this.#scheduleGeometry();
+		this.#scheduleGroups();
 	}
 	#createItemEl(item, index) {
 		const li = document.createElement(`li`);
@@ -17265,6 +18163,7 @@ let DetailListElement = class DetailListElement extends LitElement {
 			if (this.interactionMode === `checked`) this._syncCheckboxes();
 			this._syncItemStates();
 			this.#scheduleGeometry();
+			this.#scheduleGroups();
 		} else {
 			this.#providerBuilt = 0;
 			this.#rebuildFromObjects(items);
@@ -17283,6 +18182,16 @@ let DetailListElement = class DetailListElement extends LitElement {
 		if (this.sort === `none`) return;
 		const rows = [...this.querySelectorAll(ITEM_SELECTOR$3)];
 		if (rows.length < 2) return;
+		if (this.#groupingActive()) {
+			this.#scheduleGroups();
+			return;
+		}
+		for (const el of this.#sortRows(rows)) this.appendChild(el);
+		this.#scheduleGeometry();
+		this.#scheduleGroups();
+	}
+	/** Stable sort of `rows` by the current `sort` / `sortBy` / `sortComparator`. */
+	#sortRows(rows) {
 		const dir = this.sort === `descending` ? -1 : 1;
 		const meta = (el) => ({
 			element: el,
@@ -17312,9 +18221,147 @@ let DetailListElement = class DetailListElement extends LitElement {
 			i
 		}));
 		indexed.sort((a, b) => cmp(a.el, b.el) * dir || a.i - b.i);
-		for (const { el } of indexed) this.appendChild(el);
+		return indexed.map(({ el }) => el);
+	}
+	#groupingActive() {
+		return this.groupBy !== null && this.groupBy !== void 0 && this.groupBy !== ``;
+	}
+	/** Coalesce regrouping to one pass per microtask (streaming batches, search keystrokes). */
+	#scheduleGroups() {
+		if (this.#groupsScheduled || !this.#groupingActive() && !this.#wasGrouped) return;
+		this.#groupsScheduled = true;
+		queueMicrotask(() => {
+			this.#groupsScheduled = false;
+			this.#syncGroups();
+		});
+	}
+	#groupValue(el, name) {
+		return this.#propertyValue(this.getItemData(el), name) ?? el.getAttribute(`data-${name}`);
+	}
+	#groupKeyOf(el) {
+		const by = this.groupBy;
+		if (typeof by === `string`) return toGroupKey(this.#groupValue(el, by));
+		return toGroupKey(by(this.getItemData(el), el));
+	}
+	#isItemVisible(el) {
+		return !el.hidden && (!this.filterPredicate || this.filterPredicate(el));
+	}
+	#headerFor(key) {
+		let header = this.#headerEls.get(key);
+		if (!header) {
+			header = document.createElement(`ixfx-list-group-header`);
+			header.setAttribute(GROUP_HEADER_ATTR, ``);
+			header.dataset.groupKey = key;
+			this.#headerEls.set(key, header);
+		}
+		return header;
+	}
+	/**
+	* Bring the light DOM into grouped order: original order → sort → partition
+	* into contiguous groups, each preceded by a header row. Idempotent — it only
+	* touches the DOM when the order actually changes, so it never loops through
+	* the mutation observer. Ungrouping restores the original (sorted) order.
+	*/
+	#syncGroups() {
+		const active = this.#groupingActive();
+		if (!active && !this.#wasGrouped) return;
+		const items = [...this.querySelectorAll(ITEM_SELECTOR$3)];
+		for (const el of items) if (!this.#seq.has(el)) this.#seq.set(el, this.#seqNext++);
+		let ordered = items.toSorted((a, b) => this.#seq.get(a) - this.#seq.get(b));
+		if (this.sort !== `none` && ordered.length > 1) ordered = this.#sortRows(ordered);
+		const nodes = [];
+		const info = [];
+		const index = /* @__PURE__ */ new Map();
+		const liveHeaders = /* @__PURE__ */ new Set();
+		if (active) {
+			const label = this.groupLabel;
+			const parts = partitionByGroup(ordered, (el) => this.#groupKeyOf(el), label ? (key, els) => label(key, els.map((el) => this.getItemData(el) ?? el)) : void 0);
+			for (const part of parts) {
+				const count = part.items.filter((el) => this.#isItemVisible(el)).length;
+				const collapsed = count > 0 && this._collapsedGroups.has(part.key);
+				if (count > 0) {
+					const header = this.#headerFor(part.key);
+					header.label = part.label;
+					header.count = count;
+					header.collapsed = collapsed;
+					liveHeaders.add(part.key);
+					nodes.push(header);
+					info.push({
+						key: part.key,
+						label: part.label,
+						count,
+						collapsed: this._collapsedGroups.has(part.key)
+					});
+				}
+				for (const el of part.items) {
+					index.set(el, part.key);
+					el.toggleAttribute(GROUP_COLLAPSED_ATTR, collapsed);
+					nodes.push(el);
+				}
+			}
+		} else {
+			for (const el of ordered) el.removeAttribute(GROUP_COLLAPSED_ATTR);
+			nodes.push(...ordered);
+		}
+		for (const [key, header] of this.#headerEls) if (!liveHeaders.has(key)) {
+			header.remove();
+			this.#headerEls.delete(key);
+		}
+		this.#groupIndex = index;
+		this.#groupList = info;
+		this.#wasGrouped = active;
+		const current = [...this.children].filter((c) => c.matches(`li`) || c.hasAttribute(GROUP_HEADER_ATTR));
+		if (current.length !== nodes.length || current.some((c, i) => c !== nodes[i])) this.append(...nodes);
+		if (this.tickled.tickledId?.hasAttribute(GROUP_COLLAPSED_ATTR)) this.tickled.focus(void 0);
+		this.#syncGroupObserver(active);
 		this.#scheduleGeometry();
 	}
+	/** Filter-search hides rows via `hidden` on the `<li>`s — regroup when that changes. */
+	#syncGroupObserver(active) {
+		if (!active) {
+			this.#groupObserver?.disconnect();
+			this.#groupObserver = void 0;
+			return;
+		}
+		if (this.#groupObserver || !this.isConnected) return;
+		this.#groupObserver = new MutationObserver(() => this.#scheduleGroups());
+		this.#groupObserver.observe(this, {
+			subtree: true,
+			attributes: true,
+			attributeFilter: [`hidden`]
+		});
+	}
+	/** Groups in display order (empty when ungrouped). */
+	get groups() {
+		return this.#groupList;
+	}
+	/** Collapse or expand one group. Fires `list-group-toggle` when the state changes. */
+	setGroupCollapsed(groupKey, collapsed) {
+		if (this._collapsedGroups.has(groupKey) === collapsed) return;
+		const next = new Set(this._collapsedGroups);
+		if (collapsed) next.add(groupKey);
+		else next.delete(groupKey);
+		this._collapsedGroups = next;
+		this._dispatch(`list-group-toggle`, {
+			groupKey,
+			collapsed
+		});
+	}
+	toggleGroup(groupKey) {
+		this.setGroupCollapsed(groupKey, !this._collapsedGroups.has(groupKey));
+	}
+	collapseAllGroups() {
+		for (const g of this.#groupList) this.setGroupCollapsed(g.key, true);
+	}
+	expandAllGroups() {
+		for (const key of [...this._collapsedGroups]) this.setGroupCollapsed(key, false);
+	}
+	#findGroupHeader(path) {
+		for (const target of path) {
+			if (target === this) break;
+			if (target instanceof HTMLElement && target.parentElement === this && target.hasAttribute(GROUP_HEADER_ATTR)) return target;
+		}
+	}
 	#scheduleGeometry() {
 		if (this.#geometryScheduled) return;
 		this.#geometryScheduled = true;
@@ -17326,11 +18373,13 @@ let DetailListElement = class DetailListElement extends LitElement {
 	#recomputeGeometry() {
 		this.#grid = [];
 		this.#positions.clear();
+		this.#tops.clear();
 		if (!this.isConnected) return;
 		const columns = [];
 		for (const el of this._getVisibleItems()) {
 			const rect = el.getBoundingClientRect();
 			if (rect.width === 0 && rect.height === 0) continue;
+			this.#tops.set(el, rect.top);
 			let ci = columns.findIndex((c) => Math.abs(c.left - rect.left) <= 1);
 			if (ci === -1) {
 				columns.push({
@@ -17451,6 +18500,30 @@ let DetailListElement = class DetailListElement extends LitElement {
 		const next = this.#findNextCheckable(cur.col, cur.row, 0, -1);
 		if (next) this.#navigateTo(next);
 	}
+	/**
+	* Left/Right target. Ungrouped lists keep the row-index rule. Grouped lists
+	* have headers at arbitrary heights, so an item's row index no longer equals
+	* its visual row — pick the item in the neighbouring column whose top is
+	* nearest the cursor's (ties go to the upper one).
+	*/
+	#horizontalTarget(from, dir) {
+		if (this.#groupList.length === 0) return this.#findNextCheckable(from.col, from.row, dir, 0);
+		const column = this.#grid[from.col + dir];
+		const current = this.tickled.tickledId;
+		const top = current ? this.#tops.get(current) : void 0;
+		if (!column || top === void 0) return void 0;
+		let best;
+		let bestDelta = Number.POSITIVE_INFINITY;
+		for (const el of column) {
+			if (!this._isCheckable(el)) continue;
+			const delta = Math.abs((this.#tops.get(el) ?? Number.POSITIVE_INFINITY) - top);
+			if (delta < bestDelta) {
+				best = el;
+				bestDelta = delta;
+			}
+		}
+		return best;
+	}
 	#navigateRight() {
 		this.#recomputeGeometry();
 		const cur = this.tickled.tickledId ? this.#positionOf(this.tickled.tickledId) : void 0;
@@ -17458,7 +18531,7 @@ let DetailListElement = class DetailListElement extends LitElement {
 			this.#navigateTo(this.#findFirstCheckable());
 			return;
 		}
-		const next = this.#findNextCheckable(cur.col, cur.row, 1, 0);
+		const next = this.#horizontalTarget(cur, 1);
 		if (next) this.#navigateTo(next);
 		else if (this.itemWrap === `wrap`) this.#navigateTo(this.#findFirstCheckable());
 	}
@@ -17469,13 +18542,14 @@ let DetailListElement = class DetailListElement extends LitElement {
 			this.#navigateTo(this.#findFirstCheckable());
 			return;
 		}
-		const next = this.#findNextCheckable(cur.col, cur.row, -1, 0);
+		const next = this.#horizontalTarget(cur, -1);
 		if (next) this.#navigateTo(next);
 		else if (this.itemWrap === `wrap`) this.#navigateTo(this.#findLastCheckable());
 	}
 	_getVisibleItems() {
 		return Array.from(this.querySelectorAll(ITEM_SELECTOR$3)).filter((el) => {
 			if (el.hidden) return false;
+			if (el.hasAttribute(GROUP_COLLAPSED_ATTR)) return false;
 			if (this.filterPredicate && !this.filterPredicate(el)) return false;
 			return true;
 		});
@@ -17764,6 +18838,20 @@ let DetailListElement = class DetailListElement extends LitElement {
       display: none !important;
     }
 
+    /* Rows of a collapsed group leave the flow; their header stays. */
+    ::slotted([data-group-collapsed]) {
+      display: none !important;
+    }
+
+    /* Group headers are rows in the column flow, the same size as an item. */
+    ::slotted(ixfx-list-group-header) {
+      box-sizing: border-box;
+      flex: none;
+      width: var(--detail-list-column-width, 220px);
+      height: var(--detail-list-item-height, 28px);
+      --list-group-header-height: var(--detail-list-group-header-height, var(--detail-list-item-height, 28px));
+    }
+
     ::slotted(li) {
       box-sizing: border-box;
       display: flex;
@@ -17779,6 +18867,12 @@ let DetailListElement = class DetailListElement extends LitElement {
       outline: 1px solid transparent;
     }
 
+    /* While navigating by keyboard, key-repeat outpaces the 0.1s fade so the
+       cursor smears across rows. Snap instead. */
+    :host([data-keyboard-nav]) ::slotted(li) {
+      transition: none;
+    }
+
     /* In checked mode, only the checkbox column is clickable; the row body
        gets a default cursor so it doesn't suggest otherwise. */
     :host([interaction-mode="checked"]) ::slotted(li) {
@@ -17934,6 +19028,14 @@ __decorate([property({
 })], DetailListElement.prototype, "itemsDraggable", void 0);
 __decorate([property({ attribute: false })], DetailListElement.prototype, "dragPreviewRenderer", void 0);
 __decorate([property({ attribute: false })], DetailListElement.prototype, "dragPreviewSource", void 0);
+__decorate([property({ attribute: `group-by` })], DetailListElement.prototype, "groupBy", void 0);
+__decorate([property({ attribute: false })], DetailListElement.prototype, "groupLabel", void 0);
+__decorate([property({
+	type: Boolean,
+	attribute: `cross-group-selection`,
+	reflect: true
+})], DetailListElement.prototype, "crossGroupSelection", void 0);
+__decorate([state()], DetailListElement.prototype, "_collapsedGroups", void 0);
 __decorate([query(`ul`)], DetailListElement.prototype, "_listEl", void 0);
 DetailListElement = __decorate([safeCustomElement(`ixfx-detail-list`)], DetailListElement);
 //#endregion
@@ -23573,7 +24675,374 @@ let FormElement = class FormElement extends LitElement {
 };
 FormElement = __decorate([safeCustomElement(`ixfx-form`)], FormElement);
 //#endregion
+//#region src/grid-list/grid-list-layout.ts
+/**
+* `itemWidth` is the square's width; `rowHeight` is the full cell height
+* (square, plus the caption band in `separate` / `under` styles).
+* `scrollOffset` is `scrollTop` for `grid`/`column` and `scrollLeft` for `row`.
+*/
+function computeGridWindow(count, itemWidth, rowHeight, gap, viewportWidth, viewportHeight, scrollOffset, orientation, overscan = 2) {
+	const w = Math.max(1, itemWidth);
+	const h = Math.max(1, rowHeight);
+	const g = Math.max(0, gap);
+	const colStride = w + g;
+	const rowStride = h + g;
+	const offset = Math.max(0, scrollOffset);
+	if (orientation === `row`) {
+		const rows = count === 0 ? 0 : 1;
+		const totalWidth = count === 0 ? 0 : (count - 1) * colStride + w;
+		if (count === 0 || viewportWidth <= 0) return {
+			cols: count,
+			rows,
+			totalHeight: 0,
+			totalWidth,
+			startIndex: 0,
+			endIndex: 0,
+			colStride,
+			rowStride,
+			horizontal: true
+		};
+		const firstVisible = Math.max(0, Math.floor(offset / colStride));
+		const lastVisible = Math.ceil((offset + viewportWidth) / colStride);
+		return {
+			cols: count,
+			rows,
+			totalHeight: 0,
+			totalWidth,
+			startIndex: Math.max(0, firstVisible - overscan),
+			endIndex: Math.min(count, lastVisible + overscan),
+			colStride,
+			rowStride,
+			horizontal: true
+		};
+	}
+	const cols = orientation === `column` ? 1 : Math.max(1, Math.floor((Math.max(0, viewportWidth) + g) / colStride));
+	const rows = count === 0 ? 0 : Math.ceil(count / cols);
+	const totalHeight = rows === 0 ? 0 : (rows - 1) * rowStride + h;
+	if (count === 0 || viewportHeight <= 0) return {
+		cols,
+		rows,
+		totalHeight,
+		totalWidth: 0,
+		startIndex: 0,
+		endIndex: 0,
+		colStride,
+		rowStride,
+		horizontal: false
+	};
+	const firstVisibleRow = Math.max(0, Math.floor(offset / rowStride));
+	const lastVisibleRow = Math.ceil((offset + viewportHeight) / rowStride);
+	const rowStart = Math.max(0, firstVisibleRow - overscan);
+	const rowEnd = Math.min(rows, lastVisibleRow + overscan);
+	return {
+		cols,
+		rows,
+		totalHeight,
+		totalWidth: 0,
+		startIndex: rowStart * cols,
+		endIndex: Math.min(count, rowEnd * cols),
+		colStride,
+		rowStride,
+		horizontal: false
+	};
+}
+function buildSections(p, cols, stride, itemExtent) {
+	const g = Math.max(0, p.gap);
+	const horizontal = p.orientation === `row`;
+	const lineCount = (n) => horizontal ? n : Math.ceil(n / cols);
+	const extentFor = (n) => n === 0 ? 0 : (lineCount(n) - 1) * stride + itemExtent;
+	if (!p.groups) {
+		const end = extentFor(p.count);
+		return {
+			sections: [{
+				group: void 0,
+				first: 0,
+				count: p.count,
+				headerOffset: 0,
+				itemsOffset: 0,
+				end
+			}],
+			total: end,
+			count: p.count
+		};
+	}
+	const headerSize = horizontal ? p.headerWidth : p.headerHeight;
+	const sections = [];
+	let cursor = 0;
+	let first = 0;
+	for (const group of p.groups) {
+		const count = group.collapsed ? 0 : group.count;
+		const itemsOffset = cursor + headerSize + g;
+		const end = count === 0 ? cursor + headerSize : itemsOffset + extentFor(count);
+		sections.push({
+			group,
+			first,
+			count,
+			headerOffset: cursor,
+			itemsOffset,
+			end
+		});
+		first += count;
+		cursor = end + g;
+	}
+	return {
+		sections,
+		total: sections.length === 0 ? 0 : sections[sections.length - 1].end,
+		count: first
+	};
+}
+/** Index of the last section whose `headerOffset` is <= `offset` (0 when before all). */
+function sectionAtOffset(sections, offset) {
+	let lo = 0;
+	let hi = sections.length - 1;
+	while (lo < hi) {
+		const mid = lo + hi + 1 >> 1;
+		if (sections[mid].headerOffset <= offset) lo = mid;
+		else hi = mid - 1;
+	}
+	return lo;
+}
+/** Index of the section holding effective item `index` (skips empty sections). */
+function sectionOfIndex(sections, index) {
+	let lo = 0;
+	let hi = sections.length - 1;
+	while (lo < hi) {
+		const mid = lo + hi + 1 >> 1;
+		if (sections[mid].first <= index) lo = mid;
+		else hi = mid - 1;
+	}
+	let s = lo;
+	while (s < sections.length - 1 && sections[s].count === 0) s++;
+	return s;
+}
+function buildLayout(p) {
+	const horizontal = p.orientation === `row`;
+	const w = Math.max(1, p.itemWidth);
+	const h = Math.max(1, p.rowHeight);
+	const g = Math.max(0, p.gap);
+	const colStride = w + g;
+	const rowStride = h + g;
+	const cols = horizontal ? 1 : p.orientation === `column` ? 1 : Math.max(1, Math.floor((Math.max(0, p.viewportWidth) + g) / colStride));
+	const stride = horizontal ? colStride : rowStride;
+	const itemExtent = horizontal ? w : h;
+	const { sections, total, count } = buildSections(p, cols, stride, itemExtent);
+	const grouped = p.groups !== void 0;
+	const headerSize = horizontal ? p.headerWidth : p.headerHeight;
+	const viewportMain = horizontal ? p.viewportWidth : p.viewportHeight;
+	const cellHeight = rowStride - g;
+	const rowY = Math.max(0, (p.viewportHeight - cellHeight) / 2);
+	const positionOf = (index) => {
+		const si = sectionOfIndex(sections, index);
+		const s = sections[si];
+		const local = Math.max(0, index - s.first);
+		if (horizontal) return {
+			x: s.itemsOffset + local * colStride,
+			y: rowY,
+			col: 0,
+			line: local,
+			section: si
+		};
+		const col = cols <= 1 ? 0 : local % cols;
+		const line = cols <= 1 ? local : Math.floor(local / cols);
+		return {
+			x: col * colStride,
+			y: s.itemsOffset + line * rowStride,
+			col,
+			line,
+			section: si
+		};
+	};
+	const window = (offset, overscan = 2) => {
+		const off = Math.max(0, offset);
+		const headers = [];
+		const ranges = [];
+		const lo = off - overscan * stride;
+		const hi = off + viewportMain + overscan * stride;
+		let firstSection = 0;
+		if (sections.length > 1) {
+			let a = 0;
+			let b = sections.length - 1;
+			while (a < b) {
+				const mid = a + b >> 1;
+				if (sections[mid].end >= lo) b = mid;
+				else a = mid + 1;
+			}
+			firstSection = a;
+		}
+		if (viewportMain > 0) for (let si = firstSection; si < sections.length; si++) {
+			const s = sections[si];
+			if (s.headerOffset > hi) break;
+			if (s.group && s.headerOffset + headerSize >= lo) headers.push({
+				key: s.group.key,
+				label: s.group.label,
+				count: s.group.count,
+				collapsed: s.group.collapsed,
+				offset: s.headerOffset,
+				size: headerSize
+			});
+			if (s.count === 0) continue;
+			const rel = off - s.itemsOffset;
+			const viewport = rel < 0 ? viewportMain + rel : viewportMain;
+			if (viewport <= 0) continue;
+			const sw = computeGridWindow(s.count, w, h, g, horizontal ? viewport : p.viewportWidth, horizontal ? p.viewportHeight : viewport, Math.max(0, rel), p.orientation, overscan);
+			if (sw.endIndex > sw.startIndex) ranges.push([s.first + sw.startIndex, s.first + sw.endIndex]);
+		}
+		return {
+			cols: horizontal ? count : cols,
+			rows: 0,
+			totalHeight: horizontal ? 0 : total,
+			totalWidth: horizontal ? total : 0,
+			startIndex: ranges.length > 0 ? ranges[0][0] : 0,
+			endIndex: ranges.length > 0 ? ranges[ranges.length - 1][1] : 0,
+			colStride,
+			rowStride,
+			horizontal,
+			headers,
+			ranges
+		};
+	};
+	const extentOf = (index) => {
+		const { line, section } = positionOf(index);
+		const s = sections[section];
+		const start = s.itemsOffset + line * stride;
+		return [line === 0 && s.group ? s.headerOffset : start, start + itemExtent];
+	};
+	const neighbour = (index, dLine) => {
+		if (count === 0) return index;
+		const si = sectionOfIndex(sections, index);
+		const s = sections[si];
+		const local = index - s.first;
+		const col = local % cols;
+		if (dLine > 0) {
+			const t = local + cols;
+			if (t <= s.count - 1) return s.first + t;
+			const lastLine = Math.floor((s.count - 1) / cols);
+			if (Math.floor(local / cols) < lastLine) return s.first + s.count - 1;
+			for (let n = si + 1; n < sections.length; n++) if (sections[n].count > 0) return sections[n].first + Math.min(col, sections[n].count - 1);
+			return s.first + s.count - 1;
+		}
+		const t = local - cols;
+		if (t >= 0) return s.first + t;
+		for (let n = si - 1; n >= 0; n--) {
+			const prev = sections[n];
+			if (prev.count > 0) {
+				const line = Math.floor((prev.count - 1) / cols);
+				return prev.first + Math.min(line * cols + col, prev.count - 1);
+			}
+		}
+		return s.first;
+	};
+	const hitTest = (x0, x1, y0, y1) => {
+		const out = [];
+		if (count === 0) return out;
+		const main0 = horizontal ? x0 : y0;
+		const main1 = horizontal ? x1 : y1;
+		const start = sectionAtOffset(sections, main0 - stride);
+		for (let si = Math.max(0, start); si < sections.length; si++) {
+			const s = sections[si];
+			if (s.itemsOffset > main1) break;
+			if (s.count === 0 || s.end < main0) continue;
+			if (horizontal) {
+				const a = Math.max(0, Math.floor((x0 - s.itemsOffset) / colStride));
+				const b = Math.min(s.count - 1, Math.floor((x1 - s.itemsOffset) / colStride));
+				for (let i = a; i <= b; i++) out.push(s.first + i);
+			} else {
+				const colLo = Math.max(0, Math.floor(x0 / colStride));
+				const colHi = Math.min(cols - 1, Math.floor(x1 / colStride));
+				const rowLo = Math.max(0, Math.floor((y0 - s.itemsOffset) / rowStride));
+				const rowHi = Math.floor((y1 - s.itemsOffset) / rowStride);
+				for (let row = rowLo; row <= rowHi; row++) for (let col = colLo; col <= colHi; col++) {
+					const local = row * cols + col;
+					if (local >= 0 && local < s.count) out.push(s.first + local);
+				}
+			}
+		}
+		return out;
+	};
+	const anchorAt = (mainOffset) => {
+		if (count === 0) return {
+			index: 0,
+			lineFrac: 0
+		};
+		let si = sectionAtOffset(sections, mainOffset);
+		while (si < sections.length - 1 && sections[si].count === 0) si++;
+		const s = sections[si];
+		if (s.count === 0) return {
+			index: 0,
+			lineFrac: 0
+		};
+		const centreLine = Math.max(0, mainOffset - s.itemsOffset) / stride;
+		const lineFloor = Math.max(0, Math.floor(centreLine));
+		const local = horizontal ? Math.min(s.count - 1, lineFloor) : Math.min(s.count - 1, lineFloor * cols + Math.max(0, Math.floor((cols - 1) / 2)));
+		return {
+			index: s.first + local,
+			lineFrac: centreLine - lineFloor
+		};
+	};
+	const offsetOfAnchor = (index, lineFrac) => {
+		const { line, section } = positionOf(index);
+		return sections[section].itemsOffset + (line + lineFrac) * stride;
+	};
+	const snapTarget = (offset) => {
+		const si = sectionAtOffset(sections, offset);
+		const s = sections[si];
+		let rel = Math.round((offset - s.itemsOffset) / stride);
+		if (grouped) {
+			const lines = s.count === 0 ? 0 : horizontal ? s.count : Math.ceil(s.count / cols);
+			rel = Math.max(0, Math.min(Math.max(0, lines - 1), rel));
+		}
+		const candidates = [s.itemsOffset + rel * stride];
+		if (grouped) {
+			candidates.push(s.headerOffset);
+			if (si + 1 < sections.length) candidates.push(sections[si + 1].headerOffset);
+		}
+		return candidates.reduce((best, c) => Math.abs(c - offset) < Math.abs(best - offset) ? c : best);
+	};
+	return {
+		horizontal,
+		cols,
+		colStride,
+		rowStride,
+		grouped,
+		count,
+		totalExtent: total,
+		window,
+		positionOf,
+		extentOf,
+		neighbour,
+		hitTest,
+		anchorAt,
+		offsetOfAnchor,
+		snapTarget
+	};
+}
+//#endregion
 //#region src/grid-list/grid-list-source.ts
+/** Reorder `effective` raw indices into contiguous groups, dropping collapsed ones. */
+function applyGrouping(effective, cfg, keyOfRaw) {
+	const parts = partitionByGroup(effective, (raw) => cfg.groupKeyOf(raw), cfg.labelOf ? (key, raws) => cfg.labelOf(key, raws.map((r) => cfg.itemAt(r))) : void 0);
+	const order = [];
+	const groups = [];
+	const groupByKey = /* @__PURE__ */ new Map();
+	for (const part of parts) {
+		const collapsed = cfg.collapsed.has(part.key);
+		groups.push({
+			key: part.key,
+			label: part.label,
+			count: part.items.length,
+			collapsed
+		});
+		for (const raw of part.items) {
+			groupByKey.set(keyOfRaw(raw), part.key);
+			if (!collapsed) order.push(raw);
+		}
+	}
+	return {
+		order,
+		groups,
+		groupByKey
+	};
+}
 const ITEM_SELECTOR$2 = `:scope > *`;
 const SYNTHETIC_PREFIX = `gl-auto-`;
 /** Whether `key` is an auto-assigned key for a keyless light-DOM item. */
@@ -23600,6 +25069,9 @@ var ElementGridListSource = class {
 	#searchKeys;
 	#effectiveIndices = [];
 	#keysCache;
+	#grouping;
+	#groups = [];
+	#groupByKey = /* @__PURE__ */ new Map();
 	constructor(host) {
 		this.#host = host;
 		this.refresh();
@@ -23652,6 +25124,16 @@ var ElementGridListSource = class {
 		if (`searchKeys` in opts) this.#searchKeys = opts.searchKeys;
 		this.#recomputeEffective();
 	}
+	setGrouping(config) {
+		this.#grouping = config;
+		this.#recomputeEffective();
+	}
+	groups() {
+		return this.#groups;
+	}
+	groupKeyOfKey(key) {
+		return this.#groupByKey.get(key) ?? null;
+	}
 	refresh() {
 		this.#items = Array.from(this.#host.querySelectorAll(ITEM_SELECTOR$2)).filter((el) => !el.hidden);
 		for (const el of this.#items) {
@@ -23694,9 +25176,21 @@ var ElementGridListSource = class {
 			}
 			effective.push(i);
 		}
-		this.#effectiveIndices = effective;
+		this.#applyGroupingTo(effective);
 		this.#keysCache = void 0;
 	}
+	#applyGroupingTo(effective) {
+		if (this.#grouping === void 0) {
+			this.#effectiveIndices = effective;
+			this.#groups = [];
+			this.#groupByKey = /* @__PURE__ */ new Map();
+			return;
+		}
+		const grouped = applyGrouping(effective, this.#grouping, (raw) => this.#itemKey(this.#items[raw]));
+		this.#effectiveIndices = grouped.order;
+		this.#groups = grouped.groups;
+		this.#groupByKey = grouped.groupByKey;
+	}
 	#itemKey(el) {
 		const userKey = keyForElement(el);
 		if (userKey !== void 0) return userKey;
@@ -23719,6 +25213,9 @@ var DataGridListSource = class {
 	#searchKeys;
 	#effectiveIndices = [];
 	#keysCache;
+	#grouping;
+	#groups = [];
+	#groupByKey = /* @__PURE__ */ new Map();
 	constructor(items, adapter) {
 		this.#items = items;
 		this.#adapter = adapter;
@@ -23784,6 +25281,16 @@ var DataGridListSource = class {
 		if (`searchKeys` in opts) this.#searchKeys = opts.searchKeys;
 		this.#recomputeEffective();
 	}
+	setGrouping(config) {
+		this.#grouping = config;
+		this.#recomputeEffective();
+	}
+	groups() {
+		return this.#groups;
+	}
+	groupKeyOfKey(key) {
+		return this.#groupByKey.get(key) ?? null;
+	}
 	refresh() {
 		this.#recomputeEffective();
 	}
@@ -23808,7 +25315,16 @@ var DataGridListSource = class {
 			if (this.#searchKeys !== void 0 && !this.#searchKeys.has(this.#adapter.key(this.#items[i], i))) continue;
 			effective.push(i);
 		}
-		this.#effectiveIndices = effective;
+		if (this.#grouping === void 0) {
+			this.#effectiveIndices = effective;
+			this.#groups = [];
+			this.#groupByKey = /* @__PURE__ */ new Map();
+		} else {
+			const grouped = applyGrouping(effective, this.#grouping, (raw) => this.#adapter.key(this.#items[raw], raw));
+			this.#effectiveIndices = grouped.order;
+			this.#groups = grouped.groups;
+			this.#groupByKey = grouped.groupByKey;
+		}
 		this.#keysCache = void 0;
 	}
 };
@@ -23824,76 +25340,11 @@ const SNAP_DEBOUNCE_MS = 120;
 * to finish. Kept a touch above the default `--grid-list-item-move-duration`.
 */
 const REFLOW_WINDOW_MS = 320;
-function computeGridWindow(count, itemWidth, rowHeight, gap, viewportWidth, viewportHeight, scrollOffset, orientation, overscan = 2) {
-	const w = Math.max(1, itemWidth);
-	const h = Math.max(1, rowHeight);
-	const g = Math.max(0, gap);
-	const colStride = w + g;
-	const rowStride = h + g;
-	const offset = Math.max(0, scrollOffset);
-	if (orientation === `row`) {
-		const rows = count === 0 ? 0 : 1;
-		const totalWidth = count === 0 ? 0 : (count - 1) * colStride + w;
-		if (count === 0 || viewportWidth <= 0) return {
-			cols: count,
-			rows,
-			totalHeight: 0,
-			totalWidth,
-			startIndex: 0,
-			endIndex: 0,
-			colStride,
-			rowStride,
-			horizontal: true
-		};
-		const firstVisible = Math.max(0, Math.floor(offset / colStride));
-		const lastVisible = Math.ceil((offset + viewportWidth) / colStride);
-		return {
-			cols: count,
-			rows,
-			totalHeight: 0,
-			totalWidth,
-			startIndex: Math.max(0, firstVisible - overscan),
-			endIndex: Math.min(count, lastVisible + overscan),
-			colStride,
-			rowStride,
-			horizontal: true
-		};
-	}
-	const cols = orientation === `column` ? 1 : Math.max(1, Math.floor((Math.max(0, viewportWidth) + g) / colStride));
-	const rows = count === 0 ? 0 : Math.ceil(count / cols);
-	const totalHeight = rows === 0 ? 0 : (rows - 1) * rowStride + h;
-	if (count === 0 || viewportHeight <= 0) return {
-		cols,
-		rows,
-		totalHeight,
-		totalWidth: 0,
-		startIndex: 0,
-		endIndex: 0,
-		colStride,
-		rowStride,
-		horizontal: false
-	};
-	const firstVisibleRow = Math.max(0, Math.floor(offset / rowStride));
-	const lastVisibleRow = Math.ceil((offset + viewportHeight) / rowStride);
-	const rowStart = Math.max(0, firstVisibleRow - overscan);
-	const rowEnd = Math.min(rows, lastVisibleRow + overscan);
-	return {
-		cols,
-		rows,
-		totalHeight,
-		totalWidth: 0,
-		startIndex: rowStart * cols,
-		endIndex: Math.min(count, rowEnd * cols),
-		colStride,
-		rowStride,
-		horizontal: false
-	};
+function readProperty(item, name) {
+	return typeof item === `object` && item !== null ? item[name] : void 0;
 }
-function columnOf(index, cols) {
-	return cols <= 1 ? 0 : index % cols;
-}
-function rowOf(index, cols) {
-	return cols <= 1 ? index : Math.floor(index / cols);
+function readAttribute(el, name) {
+	return el.getAttribute(`data-${name}`);
 }
 /** Shallow key-array equality, treating `undefined` (never dispatched) as different. */
 function sameKeys$1(a, b) {
@@ -23921,6 +25372,11 @@ let GridListElement = class GridListElement extends LitElement {
 		this.marqueeFromCellBlank = false;
 		this.snapToItem = false;
 		this.items = [];
+		this.groupBy = null;
+		this.crossGroupSelection = false;
+		this.groupHeaderHeight = 28;
+		this.groupHeaderWidth = 120;
+		this._collapsedGroups = /* @__PURE__ */ new Set();
 		this._scrollTop = 0;
 		this._scrollLeft = 0;
 		this._viewportHeight = 0;
@@ -23945,6 +25401,12 @@ let GridListElement = class GridListElement extends LitElement {
 				interactionMode: this.interactionMode
 			}),
 			getKey: (k) => k,
+			getGroupKey: (k) => this.groupBy === null ? null : this.#source.groupKeyOfKey(k),
+			crossGroupSelection: () => this.crossGroupSelection,
+			getFallbackGroupKey: () => {
+				const k = this.tickled.tickledId;
+				return k !== void 0 && this.groupBy !== null ? this.#source.groupKeyOfKey(k) : null;
+			},
 			onChange: (selected, previous) => {
 				this._syncItemStates();
 				this.requestUpdate();
@@ -24042,10 +25504,11 @@ let GridListElement = class GridListElement extends LitElement {
 			},
 			shouldStart: (event) => {
 				if (this.marqueeFromCellBlank && this.#isCellBlankPress(event)) return true;
-				for (const node of event.composedPath()) if (node instanceof Element && node.classList.contains(`cell`)) return false;
+				for (const node of event.composedPath()) if (node instanceof Element && (node.classList.contains(`cell`) || node.classList.contains(`group-header`))) return false;
 				return true;
 			}
 		});
+		this.#groupByChanged = false;
 		this.#selectedSnapshot = /* @__PURE__ */ new Set();
 		this.#onScroll = (e) => {
 			const el = e.target;
@@ -24095,15 +25558,25 @@ let GridListElement = class GridListElement extends LitElement {
 			const count = this.#source.count;
 			if (count === 0) return;
 			const win = this.#currentWindow();
-			const move = (delta) => {
-				const from = this.tickled.tickledId ? this.#source.indexOfKey(this.tickled.tickledId) : -1;
-				const nextIndex = Math.max(0, Math.min(count - 1, from + delta));
+			const layout = this.#layout();
+			const current = () => this.tickled.tickledId ? this.#source.indexOfKey(this.tickled.tickledId) : -1;
+			const goto = (nextIndex) => {
 				const nextKey = this.#source.keyAt(nextIndex);
 				if (nextKey) {
 					this.tickled.handleKeyboardNavigation(nextKey);
 					this.#scrollItemIntoView(nextKey);
 				}
 			};
+			const move = (delta) => goto(Math.max(0, Math.min(count - 1, current() + delta)));
+			const moveLines = (dir, lines = 1) => {
+				let index = current();
+				if (index < 0) {
+					move(dir * lines * win.cols);
+					return;
+				}
+				for (let i = 0; i < lines; i++) index = layout.neighbour(index, dir);
+				goto(index);
+			};
 			const perLine = this.orientation === `grid` ? win.cols : 1;
 			switch (e.key) {
 				case `ArrowLeft`:
@@ -24113,10 +25586,12 @@ let GridListElement = class GridListElement extends LitElement {
 					move(1);
 					break;
 				case `ArrowUp`:
-					move(-perLine);
+					if (this.orientation === `grid`) moveLines(-1);
+					else move(-perLine);
 					break;
 				case `ArrowDown`:
-					move(perLine);
+					if (this.orientation === `grid`) moveLines(1);
+					else move(perLine);
 					break;
 				case `Home`:
 					this.tickled.handleKeyboardNavigation(`first`);
@@ -24131,7 +25606,8 @@ let GridListElement = class GridListElement extends LitElement {
 					const mainExtent = win.horizontal ? this._viewportWidth : this._viewportHeight;
 					const mainStride = win.horizontal ? win.colStride : win.rowStride;
 					const visibleLines = Math.max(1, Math.floor(mainExtent / mainStride));
-					move((e.key === `PageDown` ? 1 : -1) * visibleLines * perLine);
+					if (this.orientation === `grid`) moveLines(e.key === `PageDown` ? 1 : -1, visibleLines);
+					else move((e.key === `PageDown` ? 1 : -1) * visibleLines * perLine);
 					break;
 				}
 				case `Enter`: {
@@ -24212,6 +25688,11 @@ let GridListElement = class GridListElement extends LitElement {
         position: relative;
         width: 100%;
       }
+      .group-header {
+        position: absolute;
+        inset: 0 auto auto 0;
+        z-index: 1;
+      }
       .cell {
         position: absolute;
         inset: 0 auto auto 0;
@@ -24505,6 +25986,9 @@ let GridListElement = class GridListElement extends LitElement {
          specificity. Survivors slide to their new slot; a freshly inserted cell
          also fades in. (A removed item's element is already gone, so there's
          nothing left to fade — the gap simply closes as the others slide.) */
+      :host([reflowing]) .group-header {
+        transition: transform var(--grid-list-item-move-duration, 200ms) cubic-bezier(0.2, 0, 0, 1);
+      }
       :host([reflowing]) .cell {
         transition:
           transform var(--grid-list-item-move-duration, 200ms) cubic-bezier(0.2, 0, 0, 1),
@@ -24515,6 +25999,7 @@ let GridListElement = class GridListElement extends LitElement {
         animation: ixfx-list-item-in var(--grid-list-item-move-duration, 200ms) ease both;
       }
       @media (prefers-reduced-motion: reduce) {
+        :host([reflowing]) .group-header { transition: none; }
         :host([reflowing]) .cell { transition: background var(--transition), border-color var(--transition); }
         .cell.entering { animation: none; }
       }
@@ -24656,31 +26141,13 @@ let GridListElement = class GridListElement extends LitElement {
 	* so virtualized off-screen items are covered without DOM measurement.
 	*/
 	#marqueeHitTest(rect) {
-		const count = this.#source.count;
-		if (count === 0) return [];
+		if (this.#source.count === 0) return [];
 		const horizontal = this.orientation === `row`;
-		const win = computeGridWindow(count, this.itemSize, this.#rowHeight(), this.gap, Math.max(1, this._viewportWidth), Math.max(1, this._viewportHeight), horizontal ? this._scrollLeft : this._scrollTop, this.orientation, 0);
-		const out = [];
-		if (horizontal) {
-			const x0 = rect.x + this._scrollLeft;
-			const x1 = x0 + rect.width;
-			const lo = Math.max(0, Math.floor(x0 / win.colStride));
-			const hi = Math.min(count - 1, Math.floor(x1 / win.colStride));
-			for (let i = lo; i <= hi; i++) out.push(i);
-		} else {
-			const x0 = rect.x + this._scrollLeft;
-			const x1 = x0 + rect.width;
-			const y0 = rect.y + this._scrollTop;
-			const y1 = y0 + rect.height;
-			const colLo = Math.max(0, Math.floor(x0 / win.colStride));
-			const colHi = Math.min(win.cols - 1, Math.floor(x1 / win.colStride));
-			const rowLo = Math.max(0, Math.floor(y0 / win.rowStride));
-			const rowHi = Math.floor(y1 / win.rowStride);
-			for (let row = rowLo; row <= rowHi; row++) for (let col = colLo; col <= colHi; col++) {
-				const index = row * win.cols + col;
-				if (index >= 0 && index < count) out.push(index);
-			}
-		}
+		const x0 = rect.x + this._scrollLeft;
+		const x1 = x0 + rect.width;
+		const y0 = horizontal ? 0 : rect.y + this._scrollTop;
+		const y1 = horizontal ? 0 : y0 + rect.height;
+		const out = this.#layout().hitTest(x0, x1, y0, y1);
 		const keys = [];
 		for (const index of out) {
 			const key = this.#source.keyAt(index);
@@ -24830,6 +26297,10 @@ let GridListElement = class GridListElement extends LitElement {
 		if (previousLength === 0 && removedCount === 0) return;
 		if (added.length > 0 && added.length === this.#items.length) return;
 		for (const el of added) this.#entering.add(el);
+		this.#openReflowWindow();
+	}
+	/** Open (or extend) the `[reflowing]` window so moved cells and headers slide. */
+	#openReflowWindow() {
 		this.toggleAttribute(`reflowing`, true);
 		if (this.#reflowTimer) clearTimeout(this.#reflowTimer);
 		this.#reflowTimer = window.setTimeout(() => {
@@ -24886,6 +26357,7 @@ let GridListElement = class GridListElement extends LitElement {
 			this.#sourceElement = new ElementGridListSource(this);
 			this.#source = this.#sourceElement;
 		}
+		this.#source.setGrouping(this.#groupingConfig());
 		this.#applyFilters();
 		if (this.#searchFilterKeys) this.#source.setFilters({ searchKeys: this.#searchFilterKeys });
 	}
@@ -24927,6 +26399,17 @@ let GridListElement = class GridListElement extends LitElement {
 			}
 			this.search?.refresh();
 		}
+		const groupsChanged = changed.has(`groupBy`) || changed.has(`groupLabel`) || changed.has(`_collapsedGroups`);
+		if (groupsChanged && this.hasUpdated) {
+			if (changed.has(`groupBy`)) {
+				if (this._collapsedGroups.size > 0) this._collapsedGroups = /* @__PURE__ */ new Set();
+				this.#groupByChanged = true;
+			}
+			this.#applyGroupingToSource();
+			this.#dropUnreachableCursor();
+			this.#openReflowWindow();
+			this.updateComplete.then(() => this.#emitViewportChange());
+		} else if (groupsChanged) this.#applyGroupingToSource();
 		if (changed.has(`itemSize`) || changed.has(`gap`)) {
 			this.itemSize = Math.max(MIN_ITEM_SIZE, Math.round(this.itemSize));
 			this.gap = Math.max(0, Math.round(this.gap));
@@ -24947,6 +26430,62 @@ let GridListElement = class GridListElement extends LitElement {
 			}
 		}
 	}
+	#groupByChanged;
+	/** Grouping config for the active source, or `undefined` when ungrouped. */
+	#groupingConfig() {
+		const by = this.groupBy;
+		if (by === null || by === void 0 || by === ``) return void 0;
+		const collapsed = this._collapsedGroups;
+		const src = this.#source;
+		if (src instanceof DataGridListSource) return {
+			groupKeyOf: (raw) => resolveGroupKey(by, src.rawItemAt(raw), raw, readProperty),
+			itemAt: (raw) => src.rawItemAt(raw),
+			labelOf: this.groupLabel,
+			collapsed
+		};
+		const elements = src;
+		return {
+			groupKeyOf: (raw) => resolveGroupKey(by, elements.rawElementAt(raw), raw, readAttribute),
+			itemAt: (raw) => elements.rawElementAt(raw),
+			labelOf: this.groupLabel,
+			collapsed
+		};
+	}
+	/** Push the current grouping into the source and refresh the element-mode item cache. */
+	#applyGroupingToSource() {
+		this.#source.setGrouping(this.#groupingConfig());
+		if (this.#source instanceof ElementGridListSource) this.#items = this.#source.effectiveElements();
+	}
+	/** The cursor can't stay on an item that a collapsed group just removed. */
+	#dropUnreachableCursor() {
+		const id = this.tickled.tickledId;
+		if (id !== void 0 && this.#source.indexOfKey(id) < 0) this.tickled.focus(void 0);
+	}
+	/** Groups in display order (empty when ungrouped). */
+	get groups() {
+		return this.groupBy === null ? [] : this.#source.groups();
+	}
+	/** Collapse or expand one group. Fires `list-group-toggle` when the state changes. */
+	setGroupCollapsed(groupKey, collapsed) {
+		if (this._collapsedGroups.has(groupKey) === collapsed) return;
+		const next = new Set(this._collapsedGroups);
+		if (collapsed) next.add(groupKey);
+		else next.delete(groupKey);
+		this._collapsedGroups = next;
+		this._dispatch(`list-group-toggle`, {
+			groupKey,
+			collapsed
+		});
+	}
+	toggleGroup(groupKey) {
+		this.setGroupCollapsed(groupKey, !this._collapsedGroups.has(groupKey));
+	}
+	collapseAllGroups() {
+		for (const g of this.groups) this.setGroupCollapsed(g.key, true);
+	}
+	expandAllGroups() {
+		for (const key of [...this._collapsedGroups]) this.setGroupCollapsed(key, false);
+	}
 	#syncAriaMultiselectable() {
 		this.setAttribute(`aria-multiselectable`, this.selection.canSelectMultiple() ? `true` : `false`);
 	}
@@ -24986,6 +26525,10 @@ let GridListElement = class GridListElement extends LitElement {
 		}
 		this.#applyZoomAnchor();
 		this.#activateTickledPan();
+		if (this.#groupByChanged) {
+			this.#groupByChanged = false;
+			this._dispatch(`list-group-change`, { groupBy: this.groupBy });
+		}
 	}
 	/** Re-anchor the scroll so the item captured in `willUpdate` stays centred. */
 	#applyZoomAnchor() {
@@ -24994,41 +26537,33 @@ let GridListElement = class GridListElement extends LitElement {
 		this.#zoomAnchor = void 0;
 		const vp = this.#viewportRef.value;
 		if (!vp) return;
-		const win = this.#currentWindow();
-		if (win.horizontal) {
-			if (this._viewportWidth <= 0) return;
-			const targetCenter = (index + lineFrac) * win.colStride;
-			const maxScroll = Math.max(0, win.totalWidth - this._viewportWidth);
-			const next = Math.min(maxScroll, Math.max(0, targetCenter - this._viewportWidth / 2));
+		const layout = this.#layout();
+		const horizontal = layout.horizontal;
+		const extent = horizontal ? this._viewportWidth : this._viewportHeight;
+		if (extent <= 0) return;
+		const targetCenter = layout.offsetOfAnchor(index, lineFrac);
+		const maxScroll = Math.max(0, layout.totalExtent - extent);
+		const next = Math.min(maxScroll, Math.max(0, targetCenter - extent / 2));
+		if (horizontal) {
 			if (Math.abs(vp.scrollLeft - next) > .5) {
 				vp.scrollLeft = next;
 				this._scrollLeft = next;
 			}
-			return;
-		}
-		if (this._viewportHeight <= 0) return;
-		const targetCenter = ((win.cols > 0 ? Math.floor(index / win.cols) : 0) + lineFrac) * win.rowStride;
-		const maxScroll = Math.max(0, win.totalHeight - this._viewportHeight);
-		const next = Math.min(maxScroll, Math.max(0, targetCenter - this._viewportHeight / 2));
-		if (Math.abs(vp.scrollTop - next) > .5) {
+		} else if (Math.abs(vp.scrollTop - next) > .5) {
 			vp.scrollTop = next;
 			this._scrollTop = next;
 		}
 	}
 	#captureCentreAnchor(prevOffset, prevExtent, prevItemSize, prevGap, prevCaptionStyle, prevCaptionHeight, prevOrientation) {
-		const count = this.#source?.count ?? 0;
-		if (count === 0) return;
+		if ((this.#source?.count ?? 0) === 0) return;
 		const prevRowHeight = prevItemSize + (prevCaptionStyle === `separate` || prevCaptionStyle === `under` ? prevCaptionHeight : 0);
-		const horizontal = prevOrientation === `row`;
-		const prev = computeGridWindow(count, prevItemSize, prevRowHeight, prevGap, this._viewportWidth, this._viewportHeight, prevOffset, prevOrientation);
-		const mainStride = horizontal ? prev.colStride : prev.rowStride;
-		const centerLine = (prevOffset + prevExtent / 2) / mainStride;
-		const lineFloor = Math.max(0, Math.floor(centerLine));
-		const index = horizontal ? Math.min(count - 1, lineFloor) : Math.min(count - 1, lineFloor * prev.cols + Math.max(0, Math.floor((prev.cols - 1) / 2)));
-		this.#zoomAnchor = {
-			index,
-			lineFrac: centerLine - lineFloor
-		};
+		const prev = this.#buildLayout({
+			itemWidth: prevItemSize,
+			rowHeight: prevRowHeight,
+			gap: prevGap,
+			orientation: prevOrientation
+		});
+		this.#zoomAnchor = prev.anchorAt(prevOffset + prevExtent / 2);
 	}
 	/**
 	* Re-read the viewport after an ancestor's visibility/layout changed.
@@ -25242,37 +26777,75 @@ let GridListElement = class GridListElement extends LitElement {
 		return this.#windowKeys(this.#currentWindow(true));
 	}
 	#windowKeys(win) {
-		return this.#source.keys().slice(win.startIndex, win.endIndex).filter((k) => !isSyntheticKey(k));
+		const keys = this.#source.keys();
+		const out = [];
+		for (const [start, end] of win.ranges) for (let i = start; i < end; i++) if (!isSyntheticKey(keys[i])) out.push(keys[i]);
+		return out;
+	}
+	/** Layout params for the current geometry, with optional overrides (used for zoom anchoring). */
+	#layoutParams(over = {}) {
+		return {
+			count: this.#source.count,
+			groups: this.groupBy === null ? void 0 : this.#source.groups(),
+			itemWidth: this.itemSize,
+			rowHeight: this.#rowHeight(),
+			gap: this.gap,
+			viewportWidth: this._viewportWidth,
+			viewportHeight: this._viewportHeight,
+			orientation: this.orientation,
+			headerHeight: this.groupHeaderHeight,
+			headerWidth: this.groupHeaderWidth,
+			...over
+		};
+	}
+	#buildLayout(over = {}) {
+		return buildLayout(this.#layoutParams(over));
+	}
+	#layoutCache;
+	/** The current layout, rebuilt only when its inputs change (never per scroll). */
+	#layout() {
+		const params = this.#layoutParams();
+		const cached = this.#layoutCache;
+		if (cached) {
+			const a = cached.params;
+			let same = a.groups === params.groups;
+			for (const k of Object.keys(params)) {
+				if (!same) break;
+				same = a[k] === params[k];
+			}
+			if (same) return cached.layout;
+		}
+		const layout = buildLayout(params);
+		this.#layoutCache = {
+			params,
+			layout
+		};
+		return layout;
 	}
 	#currentWindow(noOverscan = false) {
-		const overscan = noOverscan ? 0 : 2;
-		return computeGridWindow(this.#source.count, this.itemSize, this.#rowHeight(), this.gap, this._viewportWidth, this._viewportHeight, this.orientation === `row` ? this._scrollLeft : this._scrollTop, this.orientation, overscan);
+		return this.#layout().window(this.orientation === `row` ? this._scrollLeft : this._scrollTop, noOverscan ? 0 : 2);
 	}
 	/** Adjust the scroll offset so `key` is fully within the viewport. */
 	#scrollItemIntoView(key) {
 		const index = this.#source.indexOfKey(key);
 		const vp = this.#viewportRef.value;
 		if (index < 0 || !vp) return;
-		const win = this.#currentWindow();
-		if (win.horizontal) {
-			const left = index * win.colStride;
-			const right = left + this.itemSize;
+		const [start, end] = this.#layout().extentOf(index);
+		if (this.orientation === `row`) {
 			const viewLeft = vp.scrollLeft;
 			let next = viewLeft;
-			if (left < viewLeft) next = left;
-			else if (right > viewLeft + this._viewportWidth) next = right - this._viewportWidth;
+			if (start < viewLeft) next = start;
+			else if (end > viewLeft + this._viewportWidth) next = end - this._viewportWidth;
 			if (next !== viewLeft) {
 				vp.scrollLeft = next;
 				this._scrollLeft = next;
 			}
 			return;
 		}
-		const top = (win.cols > 0 ? Math.floor(index / win.cols) : 0) * win.rowStride;
-		const bottom = top + this.#rowHeight();
 		const viewTop = vp.scrollTop;
 		let next = viewTop;
-		if (top < viewTop) next = top;
-		else if (bottom > viewTop + this._viewportHeight) next = bottom - this._viewportHeight;
+		if (start < viewTop) next = start;
+		else if (end > viewTop + this._viewportHeight) next = end - this._viewportHeight;
 		if (next !== viewTop) {
 			vp.scrollTop = next;
 			this._scrollTop = next;
@@ -25346,6 +26919,7 @@ let GridListElement = class GridListElement extends LitElement {
       >
         <div class="spacer" style=${spacerStyle}>
           ${this.#source instanceof DataGridListSource ? this.#renderDataCells(win) : this.#renderElementCells(win)}
+          ${this.#renderHeaders(win)}
         </div>
         ${this.#marqueeRect ? html`<div class="marquee" part="marquee" style=${this.#marqueeStyle(this.#marqueeRect)}></div>` : ``}
       </div>
@@ -25353,7 +26927,7 @@ let GridListElement = class GridListElement extends LitElement {
     `;
 	}
 	#renderDataCells(win) {
-		const slice = Array.from({ length: win.endIndex - win.startIndex }, (_, i) => win.startIndex + i);
+		const slice = win.ranges.flatMap(([start, end]) => Array.from({ length: end - start }, (_, i) => start + i));
 		return repeat(slice, (index) => this.#source.keyAt(index), (index) => this.#renderDataCell(index, win));
 	}
 	#renderDataCell(index, win) {
@@ -25368,8 +26942,7 @@ let GridListElement = class GridListElement extends LitElement {
 		const caption = style === `hidden` ? `` : this.#source.labelAt(index);
 		const showCaption = caption !== ``;
 		const cellHeight = win.rowStride - this.gap;
-		const x = win.horizontal ? index * win.colStride : columnOf(index, win.cols) * win.colStride;
-		const y = win.horizontal ? Math.max(0, (this._viewportHeight - cellHeight) / 2) : rowOf(index, win.cols) * win.rowStride;
+		const { x, y } = this.#layout().positionOf(index);
 		const captionCss = separate ? `height:${Math.max(0, this.captionHeight - 4)}px` : style === `under` ? `height:${this.captionHeight}px` : ``;
 		const rawIcon = this.#source.iconAt(index);
 		const icon = appearanceAbsent(rawIcon) ? void 0 : rawIcon;
@@ -25455,8 +27028,25 @@ let GridListElement = class GridListElement extends LitElement {
 		current.startLoop?.();
 	}
 	#renderElementCells(win) {
-		const slice = this.#items.slice(win.startIndex, win.endIndex);
-		return repeat(slice, (_el, i) => this.#source.keyAt(win.startIndex + i), (el, i) => this.#renderCell(el, win.startIndex + i, win));
+		const slice = win.ranges.flatMap(([start, end]) => Array.from({ length: end - start }, (_, i) => start + i));
+		return repeat(slice, (index) => this.#source.keyAt(index), (index) => this.#renderCell(this.#items[index], index, win));
+	}
+	#renderHeaders(win) {
+		if (win.headers.length === 0) return nothing;
+		const horizontal = win.horizontal;
+		return repeat(win.headers, (h) => `__group__${h.key}`, (h) => html`
+        <ixfx-list-group-header
+          class="group-header"
+          part="group-header"
+          data-group-key=${h.key}
+          label=${h.label}
+          count=${h.count}
+          orientation=${horizontal ? `vertical` : `horizontal`}
+          ?collapsed=${h.collapsed}
+          style=${horizontal ? `width:${h.size}px;height:100%;transform:translate(${h.offset}px,0)` : `width:100%;height:${h.size}px;transform:translate(0,${h.offset}px)`}
+          @click=${() => this.toggleGroup(h.key)}
+        ></ixfx-list-group-header>
+      `);
 	}
 	#renderCell(el, index, win) {
 		const key = this.#source.keyAt(index);
@@ -25471,8 +27061,7 @@ let GridListElement = class GridListElement extends LitElement {
 		const caption = style === `hidden` ? `` : this.#captionFor(el);
 		const showCaption = caption !== ``;
 		const cellHeight = win.rowStride - this.gap;
-		const x = win.horizontal ? index * win.colStride : columnOf(index, win.cols) * win.colStride;
-		const y = win.horizontal ? Math.max(0, (this._viewportHeight - cellHeight) / 2) : rowOf(index, win.cols) * win.rowStride;
+		const { x, y } = this.#layout().positionOf(index);
 		const thumbStyle = separate ? `height:${this.itemSize}px` : ``;
 		const captionCss = separate ? `height:${Math.max(0, this.captionHeight - 4)}px` : style === `under` ? `height:${this.captionHeight}px` : ``;
 		return html`
@@ -25571,16 +27160,12 @@ let GridListElement = class GridListElement extends LitElement {
 	#snapToNearestLine() {
 		const vp = this.#viewportRef.value;
 		if (!vp) return;
-		const win = this.#currentWindow();
-		const horizontal = win.horizontal;
-		const stride = horizontal ? win.colStride : win.rowStride;
-		if (stride <= 0) return;
+		const layout = this.#layout();
+		const horizontal = layout.horizontal;
 		const offset = horizontal ? vp.scrollLeft : vp.scrollTop;
-		const extent = horizontal ? win.totalWidth : win.totalHeight;
 		const viewportExtent = horizontal ? this._viewportWidth : this._viewportHeight;
-		const maxScroll = Math.max(0, extent - viewportExtent);
-		const index = Math.round(offset / stride);
-		const target = Math.min(maxScroll, Math.max(0, index * stride));
+		const maxScroll = Math.max(0, layout.totalExtent - viewportExtent);
+		const target = Math.min(maxScroll, Math.max(0, layout.snapTarget(offset)));
 		if (Math.abs(target - offset) < .5) return;
 		vp.scrollTo(horizontal ? {
 			left: target,
@@ -25608,7 +27193,7 @@ let GridListElement = class GridListElement extends LitElement {
 		if (mode === `manual`) return;
 		if (this.selectionMode === `none` && mode !== `checked` && mode !== `sticky`) return;
 		if (this.#dragSelect.isDragging || this.#nativeDragging || this.#nativeDrag.isDragging || this.#postDragSuppressTimer !== 0) return;
-		for (const node of e.composedPath()) if (node instanceof Element && node.classList.contains(`cell`)) return;
+		for (const node of e.composedPath()) if (node instanceof Element && (node.classList.contains(`cell`) || node.classList.contains(`group-header`))) return;
 		this.selection.clear();
 	}
 	#startPostDragSuppressTimer() {
@@ -25709,6 +27294,22 @@ __decorate([property({
 })], GridListElement.prototype, "snapToItem", void 0);
 __decorate([property({ attribute: false })], GridListElement.prototype, "items", void 0);
 __decorate([property({ attribute: false })], GridListElement.prototype, "itemAdapter", void 0);
+__decorate([property({ attribute: `group-by` })], GridListElement.prototype, "groupBy", void 0);
+__decorate([property({ attribute: false })], GridListElement.prototype, "groupLabel", void 0);
+__decorate([property({
+	type: Boolean,
+	attribute: `cross-group-selection`,
+	reflect: true
+})], GridListElement.prototype, "crossGroupSelection", void 0);
+__decorate([property({
+	type: Number,
+	attribute: `group-header-height`
+})], GridListElement.prototype, "groupHeaderHeight", void 0);
+__decorate([property({
+	type: Number,
+	attribute: `group-header-width`
+})], GridListElement.prototype, "groupHeaderWidth", void 0);
+__decorate([state()], GridListElement.prototype, "_collapsedGroups", void 0);
 __decorate([state()], GridListElement.prototype, "_scrollTop", void 0);
 __decorate([state()], GridListElement.prototype, "_scrollLeft", void 0);
 __decorate([state()], GridListElement.prototype, "_viewportHeight", void 0);
@@ -53313,6 +54914,6 @@ function init() {
 	console.log(`Init`);
 }
 //#endregion
-export { AcTextElement, AcTokenElement, BottomDrawerElement, ButtonElement, Checkbox, ColourPicker, ColourPickerPopup, CrumbNavigationElement, CrumbPathController, CrumbPathElement, DEFAULT_SIBLING_SPACING, DataController, DataDisplayComponent, DataGridElement, DataTableElement, DetailListElement, DockHostElement, DockPanelElement, EditableLabel, EditableNumber, FormElement, FormGroupElement, FormPartElement, GridListElement, GroupedItemListerElement, HyperbolicTreeListElement, ICON_CARET_RIGHT, ICON_CHECK, ICON_CHEVRON_DOWN, ICON_CLOSE, IcicleTreeListElement, IncrSearchTreeController as IncrSearchMillerController, IncrSearchTreeController, IxfxHexEditorElement, IxfxIconElement, IxfxTimelineElement, KeyedElementIndex, LIST_ITEM_MOTION_MS, LIST_SEARCH_COMMAND_IDS, LIST_SEARCH_MODES, LabelledRadialInput, LabelledRangeInput, LabelledSliderInput, LedElement, ListDragSelectController, ListNativeDragController, ListSearchController, ListSelectionController, menu_exports as Menu, MillerBaseElement, MillerListElement, MillerTreeController, MulticolListElement, NarrowedTextElement, NotificationManager, NotificationPillElement, PanTextElement, PanelElement, PanelGroupElement, PlotDataSeries, PlotHistogram, PlotMultiAxis, PlotSingleAxis, PlotXyAxis, PolarPad, RadialInputElement, RadioGroup, RangeElement, RangeInput, RangeMultiElement, RatingElement, SelectHorizElement, ShapefillValueElement, SliderInputElement, SlidingNumberElement, SnackbarElement, SnapContainer, SplitButton, SplitLayoutElement, SplitPanelElement, SwipeElement, TabController, TabListElement, TabListItemElement, TabPanelElement, TabPanelsElement, TextShimmerElement, TickledController, TimelineController, TimelineTrackTabElement, TitlebarElement, ToolbarElement, ToolbarGroupElement, TooltipElement, TransitoryLabelElement, TreeBaseElement, TreeController, TreeDataModel, TreeDropController, TreeKeyboardNavController, TreeListElement, TreemapListElement, TwoSplitLayoutElement, VerticalListElement, XyPad, addPanelToStack, animateListItemIn, animateListItemOut, applyAgeModification, applyHighlights, applyIsometry, applySnapshot, applyTreeDrop, attachTimelineInteractions, bottomDrawerCommandId, buildHighlightTargets, buildModel, captionForEntry, clampToDisk, clearHighlights, collectContainerNames, collectDataResult, collectPanelIds, collectStackPaths, composeIsometry, computeCanonicalPositions, computeColour, computeHyperbolicLayout, computeIcicleLayout, computeLeafGeoms, computeTreemapLayout, createAcCompletionProvider, createDataListSearchAdapter, createDefaultListDragPreview, createElementIncrSearch, createElementListSearchAdapter, createEmptyLayout, createEmptyStack, createFuzzySearch, createIncrSearch, createPillRenderer, createSplit, createStack, createTreeListAdapter, createTreeListSearchAdapter, createVerticalListAdapter, decomposeViewIsometry, distribute, dropTargetFor, euclideanRadiusForHyperbolicDistance, extractStack, findHyperbolicIdOf, findHyperbolicKeyPath, findHyperbolicNode, findHyperbolicPath, findHyperbolicPathById, findIcicleNode, findIciclePath, findNode, findPanelNode, findParentOf, findStackOf, findStackPathByName, findTreemapNode, findTreemapPath, geodesicInterpolate, geodesicPath, geodesicSegment, getActiveDragPanelId, getIcon, getIconEntry, getIconFont, getLeafNeighbours, hasIcon, hyperbolicBranchId, hyperbolicChildIds, hyperbolicDistanceForEuclideanRadius, hyperbolicIdDepth, hyperbolicRelativeFrame, iconBus, identityIsometry, init, insertBeside, invertIsometry, isDragging, isHyperbolicDescendantId, isMultiMode, isSplit, isStack, keyForElement, listItemFadeKeyframes, listSearchStyles, mobiusAdd, mobiusFromOrigin, mobiusToOrigin, monitorIndeterminate, moveLeafNodeToEdge, moveLeafStep, norm, normalise, normaliseValue, normalize, panelGapIndex, parseColourScaleAttr, parseLayout, poincareDistance, pointerOverAnyHost, prefersReducedMotion, preserveRestoreWeights, pruneDraggedDescendants, readBaseColour, registerFontIcon, registerIcon, registerListSearchCommands, removePanelFromStack, resolveCssVars, resolveGrid, resolveLeafPath, resolveTracks, rotationIsometry, serializeLayout, setActive, setIconFont, setPanelRestoreWeight, startListItemOutAnimation, svgToDataUri, swapLeaves, tickledItemStyles, tickledStyles, timelineStyles, toSnapshot, toolbarGapIndex, translationFromOrigin, viewIsometry, walk, wrapRoot };
+export { AcTextElement, AcTokenElement, BottomDrawerElement, ButtonElement, Checkbox, CheckedSelect, ColourPicker, ColourPickerPopup, CrumbNavigationElement, CrumbPathController, CrumbPathElement, DEFAULT_SIBLING_SPACING, DataController, DataDisplayComponent, DataGridElement, DataTableElement, DetailListElement, DockHostElement, DockPanelElement, EMPTY_GROUP_LABEL, EditableLabel, EditableNumber, FormElement, FormGroupElement, FormPartElement, GridListElement, GroupedItemListerElement, HyperbolicTreeListElement, ICON_CARET_RIGHT, ICON_CHECK, ICON_CHEVRON_DOWN, ICON_CLOSE, IcicleTreeListElement, IncrSearchTreeController as IncrSearchMillerController, IncrSearchTreeController, IxfxHexEditorElement, IxfxIconElement, IxfxTimelineElement, KeyedElementIndex, LIST_ITEM_MOTION_MS, LIST_SEARCH_COMMAND_IDS, LIST_SEARCH_MODES, LabelledRadialInput, LabelledRangeInput, LabelledSliderInput, LedElement, ListDragSelectController, ListGroupHeaderElement, ListNativeDragController, ListSearchController, ListSelectionController, menu_exports as Menu, MillerBaseElement, MillerListElement, MillerTreeController, MulticolListElement, NarrowedTextElement, NotificationManager, NotificationPillElement, PanTextElement, PanelElement, PanelGroupElement, PlotDataSeries, PlotHistogram, PlotMultiAxis, PlotSingleAxis, PlotXyAxis, PolarPad, RadialInputElement, RadioGroup, RangeElement, RangeInput, RangeMultiElement, RatingElement, SelectHorizElement, ShapefillValueElement, SliderInputElement, SlidingNumberElement, SnackbarElement, SnapContainer, SplitButton, SplitLayoutElement, SplitPanelElement, SwipeElement, TabController, TabListElement, TabListItemElement, TabPanelElement, TabPanelsElement, TextShimmerElement, TickledController, TimelineController, TimelineTrackTabElement, TitlebarElement, ToolbarElement, ToolbarGroupElement, TooltipElement, TransitoryLabelElement, TreeBaseElement, TreeController, TreeDataModel, TreeDropController, TreeKeyboardNavController, TreeListElement, TreemapListElement, TwoSplitLayoutElement, VerticalListElement, XyPad, addPanelToStack, animateListItemIn, animateListItemOut, applyAgeModification, applyHighlights, applyIsometry, applySnapshot, applyTreeDrop, attachTimelineInteractions, bottomDrawerCommandId, buildHighlightTargets, buildModel, captionForEntry, clampToDisk, clearHighlights, collectContainerNames, collectDataResult, collectPanelIds, collectStackPaths, composeIsometry, computeCanonicalPositions, computeColour, computeHyperbolicLayout, computeIcicleLayout, computeLeafGeoms, computeTreemapLayout, createAcCompletionProvider, createDataListSearchAdapter, createDefaultListDragPreview, createElementIncrSearch, createElementListSearchAdapter, createEmptyLayout, createEmptyStack, createFuzzySearch, createIncrSearch, createPillRenderer, createSplit, createStack, createTreeListAdapter, createTreeListSearchAdapter, createVerticalListAdapter, decomposeViewIsometry, defaultGroupLabel, distribute, dropTargetFor, euclideanRadiusForHyperbolicDistance, extractStack, findHyperbolicIdOf, findHyperbolicKeyPath, findHyperbolicNode, findHyperbolicPath, findHyperbolicPathById, findIcicleNode, findIciclePath, findNode, findPanelNode, findParentOf, findStackOf, findStackPathByName, findTreemapNode, findTreemapPath, geodesicInterpolate, geodesicPath, geodesicSegment, getActiveDragPanelId, getIcon, getIconEntry, getIconFont, getLeafNeighbours, hasIcon, hyperbolicBranchId, hyperbolicChildIds, hyperbolicDistanceForEuclideanRadius, hyperbolicIdDepth, hyperbolicRelativeFrame, iconBus, identityIsometry, init, insertBeside, invertIsometry, isDragging, isHyperbolicDescendantId, isMultiMode, isSplit, isStack, keyForElement, listItemFadeKeyframes, listSearchStyles, mobiusAdd, mobiusFromOrigin, mobiusToOrigin, monitorIndeterminate, moveLeafNodeToEdge, moveLeafStep, norm, normalise, normaliseValue, normalize, panelGapIndex, parseColourScaleAttr, parseLayout, partitionByGroup, poincareDistance, pointerOverAnyHost, prefersReducedMotion, preserveRestoreWeights, pruneDraggedDescendants, readBaseColour, registerFontIcon, registerIcon, registerListSearchCommands, removePanelFromStack, resolveCssVars, resolveGrid, resolveGroupKey, resolveLeafPath, resolveTracks, rotationIsometry, serializeLayout, setActive, setIconFont, setPanelRestoreWeight, startListItemOutAnimation, svgToDataUri, swapLeaves, tickledItemStyles, tickledStyles, timelineStyles, toGroupKey, toSnapshot, toggleInSet, toolbarGapIndex, translationFromOrigin, viewIsometry, walk, wrapRoot };
 
 //# sourceMappingURL=index.js.map