@ixfx/components 0.11.6 → 0.11.8

package/dist/{detail-list-CmdCxddo.d.ts → detail-list-lE_5UWVl.d.ts}

@@ -3,8 +3,10 @@ import { r as IDataProvider } from "./data-provider-BAn_-oR1.js";
 import { F as ListDragPreviewSourceResolver, P as ListDragPreviewRenderer, R as ListNativeDragStartEvent } from "./tree-component-DukLqesg.js";
 import { n as ListViewportChangeEvent } from "./list-viewport-types-BRZsLcvp.js";
 import { S as ListSearchController } from "./index-CMsmZ6Or.js";
+import { a as ListGroupEventMap, o as ListGroupInfo, s as ListGroupLabel } from "./grouping-CUKgmkMm.js";
 import { i as ListInteractionMode, l as ListSelectionMode, r as ListElementEventMap } from "./list-selection-types-PjKdhF-a.js";
 import { n as CustomCheckboxOptions, t as AddItemOptions } from "./vertical-list-DTp-UIUE.js";
+import "./list-group-header.js";
 import { LitElement, PropertyValues } from "lit";
 import { CommandId, CommandRegistry } from "@clinth/ui-commands";
 //#region src/detail-list/types.d.ts
@@ -20,6 +22,12 @@ type DetailSortItem = {
 type DetailSortComparator = (a: DetailSortItem, b: DetailSortItem) => number;
 /** Turns one object item into row content — a plain string or a DOM node. */
 type DetailFormatter = (item: unknown, index: number) => string | Node;
+/**
+ * How a detail list derives an item's group key: a property name (object
+ * items) or `data-<name>` attribute, or a function of the item's data (`undefined`
+ * for declarative rows) and its `<li>` element.
+ */
+type DetailGroupBy = string | ((data: unknown, el: Element) => string);
 //#endregion
 //#region src/detail-list/detail-list.d.ts
 /**
@@ -95,6 +103,21 @@ declare class DetailListElement extends LitElement {
    */
   dragPreviewRenderer: ListDragPreviewRenderer<Element> | undefined;
   dragPreviewSource: ListDragPreviewSourceResolver<Element> | undefined;
+  /**
+   * Group rows under collapsible headers that flow inline in the columns. A
+   * string names an item property (object items) or a `data-<name>` attribute;
+   * a function derives the key from `(data, element)`. `null` = ungrouped.
+   * Groups appear in first-encounter order (after sorting and filtering).
+   */
+  groupBy: DetailGroupBy | null;
+  /** Header label for a group. Defaults to the key (`(none)` for the empty key). */
+  groupLabel: ListGroupLabel | undefined;
+  /**
+   * Let selection span groups. When `false` (default) selecting in one group
+   * clears the others and Shift-range / select-all stay inside one group.
+   */
+  crossGroupSelection: boolean;
+  private _collapsedGroups;
   private _listEl;
   private readonly selection;
   private tickled;
@@ -106,6 +129,7 @@ declare class DetailListElement extends LitElement {
   connectedCallback(): void;
   disconnectedCallback(): void;
   firstUpdated(): void;
+  protected willUpdate(changed: PropertyValues): void;
   updated(changed: PropertyValues): void;
   /** The most recently selected item, or `undefined` if nothing is selected. */
   get selectedItem(): Element | undefined;
@@ -170,6 +194,13 @@ declare class DetailListElement extends LitElement {
   /** Move the cursor to the item with this key and scroll it into view. */
   focusKey(key: string): void;
   selectedFilter(kind: `selected` | `checked` | `either`): Generator<Element>;
+  /** Groups in display order (empty when ungrouped). */
+  get groups(): readonly ListGroupInfo[];
+  /** Collapse or expand one group. Fires `list-group-toggle` when the state changes. */
+  setGroupCollapsed(groupKey: string, collapsed: boolean): void;
+  toggleGroup(groupKey: string): void;
+  collapseAllGroups(): void;
+  expandAllGroups(): void;
   private _getVisibleItems;
   /**
    * Set the column width to fit the widest visible item.
@@ -199,6 +230,8 @@ declare class DetailListElement extends LitElement {
   private _dispatchCancelable;
   private _onPointerOver;
   private _onPointerLeave;
+  /** Restores hover transitions once the pointer takes over from the keyboard. */
+  private _endKeyboardNav;
   private _onKeyDown;
   private _onClick;
   private _onDblClick;
@@ -213,10 +246,10 @@ declare global {
   }
   interface HTMLElementEventMap extends DetailListElementEventMap {}
 }
-interface DetailListElementEventMap extends ListElementEventMap {
+interface DetailListElementEventMap extends ListElementEventMap, ListGroupEventMap {
   'detail-list-viewport-change': ListViewportChangeEvent;
   'list-native-drag-start': ListNativeDragStartEvent<Element>;
 }
 //#endregion
-export { DetailSortItem as a, DetailSortComparator as i, DetailListElementEventMap as n, DetailSortMode as o, DetailFormatter as r, DetailListElement as t };
-//# sourceMappingURL=detail-list-CmdCxddo.d.ts.map
+export { DetailSortComparator as a, DetailGroupBy as i, DetailListElementEventMap as n, DetailSortItem as o, DetailFormatter as r, DetailSortMode as s, DetailListElement as t };
+//# sourceMappingURL=detail-list-lE_5UWVl.d.ts.map

package/dist/detail-list-lE_5UWVl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detail-list-lE_5UWVl.d.ts","names":[],"sources":["../src/detail-list/types.ts","../src/detail-list/detail-list.ts"],"mappings":";;;;;;;;;;;;;KACY;;KAGA;WACD,SAAS;WACT;WACA;;;KAIC,wBAAwB,GAAG,gBAAgB,GAAG;;KAG9C,mBAAmB,eAAe,2BAA2B;;;;;;KAc7D,2BAA2B,eAAe,IAAI;;;;;;;;;;;;;;;;;;;;cCkI7C,0BAA0B;;EAErC,eAAe;EAGf,iBAAiB;EAGjB,MAAM;EAGN;EAGA,gBAAgB;EAGhB;EAGA,UAAU;EAGV;EAGA,WAAW;EAGX;;;;;EAOA;;;;;EAOA;;;;;;EAQA;EAGA;EAGA,mBAAmB,IAAI;;;;;;EAQvB;;EAIA,oBAAoB,gCAAgC;;;;;;EAQpD;;;;;;EAQA;;;;;EAOA,qBAAqB,wBAAwB;EAG7C,mBAAmB,8BAA8B;;;;;;;EASjD,SAAS;;EAIT,YAAY;;;;;EAOZ;UAEiB;UAGT;mBAiCS;UAqBT;UAyFA;;WAoGC,QAAM,qBAAA;;MAYX,YAAY;EAoBP;EAkEA;EA+BA;YASU,WAAW,SAAS;EAS9B,QAAQ,SAAS;;MA+DtB,gBAAgB;;MAKhB,iBAAiB,YAAY;;;;;;EASjC;EAIA,QAAQ,MAAM,kBAAkB,UAAU;;;;;EAwB1C,WAAW,MAAM,UAAU;;EAY3B,YAAY,OAAO,SAAS,WAAW;EAIvC;;;;;EAcA,SAAS,gBAAgB;;;;;EAiBzB,YAAY,MAAM;;;;;;;;;;EAalB;;;;;;EAsBA,SAAS,WAAW,WAAW,OAAO;EAItC,OAAO,MAAM;EAIb,WAAW,OAAO,SAAS;EAI3B,SAAS,MAAM;EAIf;EAIA;;MAQI,gBAAgB;;MAKhB;;EAMJ,WAAW,MAAM;;EAKjB,gBAAgB,MAAM;;EAKtB,mBAAmB,MAAM;;EAKzB,SAAS;EAgBP,eAAe,0CAA0C,UAAU;;MA8VjE,mBAAmB;;EAKvB,kBAAkB,kBAAkB;EAYpC,YAAY;EAIZ;EAKA;UAwRQ;;;;;;;;;EAoBF,kBAAkB;UAwBhB;;UAOA;UA2DA;UAiBA;;;;;;;UA2DA;;UAoBA;UAcA;UAYA;UAQA;UA6DA;UAMA;;UAKA;UAIA;UA+EA;UAiBA;UAMA;UAUA;SAUQ,sBAAM;EAyKb,wBAAM;;QAsBT;YACI;IACR,oBAAoB;;YAGZ,4BAA4B;;UAGvB,kCAAkC,qBAAqB;EACtE,+BAA+B;EAC/B,0BAA0B,yBAAyB"}

package/dist/detail-list.d.ts

@@ -1,5 +1,6 @@
 import { I as ListDragSource, L as ListNativeDragStartDetail, M as ListDragPreview, N as ListDragPreviewContext, P as ListDragPreviewRenderer, R as ListNativeDragStartEvent, j as ListDragEntry } from "./tree-component-DukLqesg.js";
 import { n as ListViewportChangeEvent, t as ListViewportChangeDetail } from "./list-viewport-types-BRZsLcvp.js";
+import { i as ListGroupChangeEvent, l as ListGroupToggleDetail, n as ListGroupBy, o as ListGroupInfo, r as ListGroupChangeDetail, s as ListGroupLabel, u as ListGroupToggleEvent } from "./grouping-CUKgmkMm.js";
 import { n as CustomCheckboxOptions, t as AddItemOptions } from "./vertical-list-DTp-UIUE.js";
-import { a as DetailSortItem, i as DetailSortComparator, n as DetailListElementEventMap, o as DetailSortMode, r as DetailFormatter, t as DetailListElement } from "./detail-list-CmdCxddo.js";
-export { type AddItemOptions, type CustomCheckboxOptions, type DetailFormatter, DetailListElement, DetailListElementEventMap, type DetailSortComparator, type DetailSortItem, type DetailSortMode, type ListDragEntry, type ListDragPreview, type ListDragPreviewContext, type ListDragPreviewRenderer, type ListDragSource, type ListNativeDragStartDetail, type ListNativeDragStartEvent, type ListViewportChangeDetail, type ListViewportChangeEvent };
+import { a as DetailSortComparator, i as DetailGroupBy, n as DetailListElementEventMap, o as DetailSortItem, r as DetailFormatter, s as DetailSortMode, t as DetailListElement } from "./detail-list-lE_5UWVl.js";
+export { type AddItemOptions, type CustomCheckboxOptions, type DetailFormatter, type DetailGroupBy, DetailListElement, DetailListElementEventMap, type DetailSortComparator, type DetailSortItem, type DetailSortMode, type ListDragEntry, type ListDragPreview, type ListDragPreviewContext, type ListDragPreviewRenderer, type ListDragSource, type ListGroupBy, type ListGroupChangeDetail, type ListGroupChangeEvent, type ListGroupInfo, type ListGroupLabel, type ListGroupToggleDetail, type ListGroupToggleEvent, type ListNativeDragStartDetail, type ListNativeDragStartEvent, type ListViewportChangeDetail, type ListViewportChangeEvent };

package/dist/detail-list.js

@@ -4,17 +4,29 @@ import { n as safeCustomElement, t as __decorate } from "./decorate-VRK8rslU.js"
 import "./icon-1gpwtPx8.js";
 import { t as DataController } from "./data-controller-DOlmqNKb.js";
 import { c as createElementListSearchAdapter, i as ListSearchController, n as listSearchStyles, o as registerListSearchCommands, r as LIST_SEARCH_MODES, u as keyForElement } from "./incr-search-D91M4Ozq.js";
+import { a as toGroupKey, r as partitionByGroup } from "./grouping-RYPnHkrS.js";
 import { t as ListNativeDragController } from "./list-native-drag-controller-B9xO0XWn.js";
-import { r as ListDragSelectController, t as ListSelectionController } from "./list-selection-controller-SA4piSBi.js";
+import { r as ListDragSelectController, t as ListSelectionController } from "./list-selection-controller-BeE70lbB.js";
 import { n as animateListItemIn, r as animateListItemOut } from "./list-item-animation-BUoEKi5s.js";
 import { t as scrollFadeStyles } from "./scroll-fade-BrNUIYnm.js";
 import { n as appearanceColor, t as appearanceAbsent } from "./item-appearance-BjcMyauw.js";
+import "./list-group-header.js";
 import { LitElement, css, html, nothing, render } from "lit";
-import { property, query } from "lit/decorators.js";
+import { property, query, state } from "lit/decorators.js";
 import { createCommandRegistry } from "@clinth/ui-commands";
 //#region src/detail-list/detail-list.ts
 const ITEM_SELECTOR = `: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
@@ -63,14 +75,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({
@@ -81,6 +105,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`, {
@@ -162,6 +192,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;
 			}
@@ -185,6 +216,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`) {
@@ -194,6 +228,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();
@@ -249,7 +284,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 });
@@ -268,6 +309,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;
@@ -279,6 +322,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;
@@ -382,6 +436,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);
@@ -393,6 +449,7 @@ let DetailListElement = class DetailListElement extends LitElement {
 			this.#processChildren();
 			this.#animateChildMutations(records);
 			this.#scheduleGeometry();
+			this.#scheduleGroups();
 		});
 		this.#mutationObserver.observe(this, {
 			childList: true,
@@ -402,6 +459,7 @@ let DetailListElement = class DetailListElement extends LitElement {
 		for (const el of this.querySelectorAll(ITEM_SELECTOR)) 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
@@ -428,6 +486,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);
@@ -441,6 +501,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;
@@ -455,8 +517,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 = [];
@@ -473,6 +549,7 @@ let DetailListElement = class DetailListElement extends LitElement {
 		if (changed.has(`filterPredicate`)) {
 			this.#applyFilterPredicate();
 			this.#scheduleGeometry();
+			this.#scheduleGroups();
 		}
 		if (changed.has(`interactionMode`)) {
 			this.selection.clearAnchor();
@@ -512,6 +589,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
@@ -521,6 +599,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();
 		});
@@ -531,6 +610,8 @@ let DetailListElement = class DetailListElement extends LitElement {
 	}
 	clearItems() {
 		this.replaceChildren();
+		this.#headerEls.clear();
+		this.#scheduleGroups();
 		this.selection.reset();
 		this.#builtFromProvider = [];
 		this.#providerBuilt = 0;
@@ -548,6 +629,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
@@ -667,6 +749,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`);
@@ -718,6 +801,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);
@@ -736,6 +820,16 @@ let DetailListElement = class DetailListElement extends LitElement {
 		if (this.sort === `none`) return;
 		const rows = [...this.querySelectorAll(ITEM_SELECTOR)];
 		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,
@@ -765,9 +859,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)];
+		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;
@@ -779,11 +1011,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({
@@ -904,6 +1138,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;
@@ -911,7 +1169,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());
 	}
@@ -922,13 +1180,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)).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;
 		});
@@ -1217,6 +1476,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;
@@ -1232,6 +1505,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) {
@@ -1387,6 +1666,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