@spaethtech/svelte-ui 0.21.1-dev.131.6298c61 → 0.21.1-dev.134.0bfe62d

package/dist/components/DataTable.svelte

@@ -1,7 +1,8 @@
 <!--
 /**
  * DataTable — config-driven, responsive 12-col data table over a DataGrid (svelte-ui/data).
- * Selectable rows, expandable rows, per-row + bulk action menus, sortable headers, paginated footer.
+ * Selectable rows, expandable rows, per-row + bulk action menus, sortable headers, paginated footer,
+ * and optional grouping (rows sectioned under headings via the grid's `groupBy`).
  * Styled on the svelte-ui theme; menus use the Popup/Menu primitives (top layer, flip vs viewport).
  *
  * Compound component: every control is built from our own core components — icon controls and
@@ -33,6 +34,7 @@
   import Select from "./Select.svelte";
   import Checkbox from "./Checkbox.svelte";
   import Menu from "./Menu.svelte";
+  import Badge from "./Badge/Badge.svelte";
   import type { Column, GridPlacement, MenuItem, DataGrid } from "../data/table/index.js";
   import type { Size } from "../types/sizes.js";
   import { resolveScalar, type Responsive } from "../types/responsive.js";
@@ -43,7 +45,9 @@
     selectable = false,
     expandable = false,
     reorderable = false,
+    collapsibleGroups = false,
     expanded,
+    groupHeader,
     rowActions,
     bulkActions,
     onReorder,
@@ -63,7 +67,18 @@
      *  ends of the visible page — with server pagination, this
      *  reorders WITHIN the visible page only. */
     reorderable?: boolean;
+    /** When the grid has a `groupBy`, give each group header a collapse chevron (member rows hide
+     *  while the header stays). View-only — collapsed rows remain in `rows`/selection. Default
+     *  `false`, so grouping shows static headings and nothing changes for ungrouped tables. */
+    collapsibleGroups?: boolean;
     expanded?: Snippet<[T]>;
+    /** Override the group header row's content (the grid must have a `groupBy`). Receives the group's
+     *  `key`/`label`, the per-page `count`, whether it's `collapsed`, and a `toggle()` to collapse it.
+     *  Omit for the default (label + count badge, plus a chevron when `collapsibleGroups`). Build it
+     *  from library components (Composition Standard) — no raw `<button>`. */
+    groupHeader?: Snippet<
+      [{ key: string; label: string; count: number; collapsed: boolean; toggle: () => void }]
+    >;
     /** Per-row kebab menu. Return `null`/`undefined`/`[]` for a row with no actions — the kebab still
      *  renders (columns stay aligned) but is disabled, rather than opening an empty/all-disabled menu. */
     rowActions?: (row: T) => MenuItem[] | null | undefined;
@@ -210,6 +225,45 @@
     }),
   );
 
+  // ── grouping (section the current page) ──────────────────────────────────
+  // Model A: we group only the rows we're handed. The grid orders a column-id groupBy group-first
+  // (so members are contiguous); a group that straddles a page edge simply repeats its header on the
+  // next page. Counts are per-page.
+  const grouped = $derived(grid.grouped);
+  type GroupMeta = { key: string; label: string; count: number };
+  const groupMetas = $derived.by(() => {
+    const m = new Map<string, GroupMeta>();
+    if (!grouped) return m;
+    for (const r of rows) {
+      const g = grid.groupOf(r);
+      if (!g) continue;
+      const ex = m.get(g.key);
+      if (ex) ex.count++;
+      else m.set(g.key, { key: g.key, label: g.label, count: 1 });
+    }
+    return m;
+  });
+  type RowItem = { kind: "row"; row: T; i: number };
+  type GroupItem = { kind: "group" } & GroupMeta;
+  // Flatten the page into render items: a group header wherever the group key changes, then its
+  // rows (skipped while the group is collapsed). Ungrouped → just the rows, unchanged.
+  const renderList = $derived.by<(RowItem | GroupItem)[]>(() => {
+    if (!grouped) return rows.map((row, i) => ({ kind: "row", row, i }) as RowItem);
+    const out: (RowItem | GroupItem)[] = [];
+    let prev: string | null = null;
+    rows.forEach((row, i) => {
+      const g = grid.groupOf(row);
+      const key = g ? g.key : "";
+      if (key !== prev) {
+        out.push({ kind: "group", key, label: g?.label ?? key, count: groupMetas.get(key)?.count ?? 0 });
+        prev = key;
+      }
+      if (collapsibleGroups && grid.isGroupCollapsed(key)) return; // header stays, members hidden
+      out.push({ kind: "row", row, i });
+    });
+    return out;
+  });
+
   // Invisible icon-slot sizing for the empty-state spacer. Sized to
   // heightVar via inline style at each use site (kept as a snippet
   // of class + style below).
@@ -382,8 +436,75 @@
           ></div>{/if}
       </div>
     {:else}
-      {#each rows as row, rowIndex (grid.getRowId(row))}
-        {@const id = grid.getRowId(row)}
+      {#each renderList as item (item.kind === "group" ? `g:${item.key}` : grid.getRowId(item.row))}
+        {#if item.kind === "group"}
+          {@const collapsed = grid.isGroupCollapsed(item.key)}
+          <!-- Full-bleed group heading row. role="row" + a single full-width cell (the table uses
+               role-on-div semantics without colspan, so this mirrors the empty-state row). The surface
+               fill distinguishes it from data rows in every variant, ghost included. When collapsible,
+               the WHOLE row is the toggle (mouse + keyboard) and the chevron sits in the tail column,
+               aligned with the per-row kebab / bulk-actions button. -->
+          <!-- svelte-ignore a11y_click_events_have_key_events -->
+          <div
+            role="row"
+            class="flex items-center {cellGap} {cellPad} [background-color:var(--ui-color-surface)] {collapsibleGroups
+              ? 'cursor-pointer select-none hover:[background-color:var(--ui-color-hover)]'
+              : ''}"
+            style="min-height: {heightVar}"
+            tabindex={collapsibleGroups ? 0 : undefined}
+            aria-label={collapsibleGroups
+              ? `${item.label} ${collapsed ? i18n.messages.expand : i18n.messages.collapse}`
+              : undefined}
+            onclick={collapsibleGroups ? () => grid.toggleGroup(item.key) : undefined}
+            onkeydown={collapsibleGroups
+              ? (e) => {
+                  if (e.key === "Enter" || e.key === " ") {
+                    e.preventDefault();
+                    grid.toggleGroup(item.key);
+                  }
+                }
+              : undefined}
+          >
+            <div role="cell" class="flex min-w-0 grow items-center gap-2 font-semibold">
+              {#if groupHeader}
+                {@render groupHeader({
+                  key: item.key,
+                  label: item.label,
+                  count: item.count,
+                  collapsed,
+                  toggle: () => grid.toggleGroup(item.key),
+                })}
+              {:else}
+                <span class="truncate">{item.label}</span>
+              {/if}
+            </div>
+            <!-- Right cluster: the count badge sits immediately left of the collapse chevron. The
+                 chevron is the SAME inert ghost Button the per-row kebab / bulk control uses (identical
+                 square box + centred icon), so it lines up exactly in that column; it's aria-hidden +
+                 tabindex -1 + pointer-events:none, so the WHOLE row keeps owning the click/keyboard
+                 toggle and this is not a nested interactive control. -->
+            <div class="flex shrink-0 items-center gap-1">
+              {#if !groupHeader}
+                <Badge text={String(item.count)} {size} />
+              {/if}
+              {#if collapsibleGroups}
+                <Button
+                  variant="ghost"
+                  {size}
+                  tabindex={-1}
+                  aria-hidden="true"
+                  class="pointer-events-none"
+                >
+                  {#snippet icon()}{#if collapsed}<IconChevronRight />{:else}<IconChevronDown
+                      />{/if}{/snippet}
+                </Button>
+              {/if}
+            </div>
+          </div>
+        {:else}
+          {@const row = item.row}
+          {@const rowIndex = item.i}
+          {@const id = grid.getRowId(row)}
         <!-- Row + its expand panel form one hover group, so they always share the SAME background
 			     (transparent by default; both take the hover tint together). -->
         <div class="group">
@@ -488,6 +609,7 @@
             </div>
           {/if}
         </div>
+        {/if}
       {/each}
     {/if}
   </div>

package/dist/components/DataTable.svelte.d.ts

@@ -16,7 +16,22 @@ declare function $$render<T>(): {
          *  ends of the visible page — with server pagination, this
          *  reorders WITHIN the visible page only. */
         reorderable?: boolean;
+        /** When the grid has a `groupBy`, give each group header a collapse chevron (member rows hide
+         *  while the header stays). View-only — collapsed rows remain in `rows`/selection. Default
+         *  `false`, so grouping shows static headings and nothing changes for ungrouped tables. */
+        collapsibleGroups?: boolean;
         expanded?: Snippet<[T]>;
+        /** Override the group header row's content (the grid must have a `groupBy`). Receives the group's
+         *  `key`/`label`, the per-page `count`, whether it's `collapsed`, and a `toggle()` to collapse it.
+         *  Omit for the default (label + count badge, plus a chevron when `collapsibleGroups`). Build it
+         *  from library components (Composition Standard) — no raw `<button>`. */
+        groupHeader?: Snippet<[{
+            key: string;
+            label: string;
+            count: number;
+            collapsed: boolean;
+            toggle: () => void;
+        }]>;
         /** Per-row kebab menu. Return `null`/`undefined`/`[]` for a row with no actions — the kebab still
          *  renders (columns stay aligned) but is disabled, rather than opening an empty/all-disabled menu. */
         rowActions?: (row: T) => MenuItem[] | null | undefined;

package/dist/components/SideBarMenu/SideBarMenu.svelte

@@ -95,8 +95,9 @@
     link?: string;
     badge?: SideBarMenuBadge;
     /** Child items — rendered as a fly-out popout. Recursive: a child that itself has children
-     *  cascades into a further popout (or steps deeper in `stepped` mode). */
-    children?: SideBarMenuItem[];
+     *  cascades into a further popout (or steps deeper in `stepped` mode). May include
+     *  `{ divider: true }` entries to draw a separator between children. */
+    children?: SideBarMenuEntry[];
     /** Action row (no `link`) — renders a `<button>` and calls this on click. For a "toggle"
      *  row (an AI panel, etc.) or a non-navigating action. Runs after the drawer/popout reset. */
     onclick?: (e: MouseEvent) => void;
@@ -114,6 +115,20 @@
      *  the default `currentPath` segment-boundary match against `link`. */
     activeMatch?: SideBarMenuActiveRule;
   };
+
+  /**
+   * A horizontal rule between adjacent rows in an `items` / `bottomItems` / `children` list — a 1px
+   * full-bleed separator (`--ui-border-color`) drawn between the two rows it sits between. It adds no
+   * navigable row and (visually) only the 1px line, so it never disturbs the fixed-height row rhythm.
+   * Leading, trailing, and consecutive dividers collapse — a divider renders ONLY between two real
+   * rows. Honoured identically in the fly-out popout, the stepped sub-view, and the inline
+   * expanded/drawer rail. Use the discriminated form `{ divider: true }` so a genuinely malformed item
+   * still falls through to the visible "malformed item" row rather than silently becoming a separator.
+   */
+  export type SideBarMenuDivider = { divider: true };
+
+  /** A SideBarMenu list entry: either a {@link SideBarMenuItem} or a {@link SideBarMenuDivider}. */
+  export type SideBarMenuEntry = SideBarMenuItem | SideBarMenuDivider;
 </script>
 
 <script lang="ts">
@@ -159,8 +174,8 @@
     class: additionalClass = "",
     ...rest
   }: {
-    items?: SideBarMenuItem[];
-    bottomItems?: SideBarMenuItem[];
+    items?: SideBarMenuEntry[];
+    bottomItems?: SideBarMenuEntry[];
     currentPath: string;
     size?: Size;
     /**
@@ -492,7 +507,34 @@
   // reserving group that lack an icon still get an empty box so everything aligns. The main rail counts
   // `items` + `bottomItems` as ONE group (so top/bottom align); each popout / stepped sub-view is its
   // own group.
-  const anyIcon = (list: SideBarMenuItem[]) => list.some((i) => i.icon || i.badge);
+  // ── Dividers ────────────────────────────────────────────────────
+  // A list entry is either a real item or a `{ divider: true }` separator. Dividers are not navigable
+  // rows — they render as a 1px full-bleed rule BETWEEN two real rows (see `renderRows`).
+  const isDivider = (e: SideBarMenuEntry): e is SideBarMenuDivider =>
+    typeof e === "object" && e !== null && (e as SideBarMenuDivider).divider === true;
+  const itemsOnly = (list: SideBarMenuEntry[] = []): SideBarMenuItem[] =>
+    list.filter((e): e is SideBarMenuItem => !isDivider(e));
+
+  // Normalize a list into the rows to render, each tagged with whether a divider precedes it. Leading,
+  // trailing, and consecutive dividers collapse — `dividerBefore` is set only when a divider sits
+  // between two real rows. `index` is the entry's ORIGINAL position in the list, so open-path ids
+  // (`top:3`, `id>5`) stay stable and unique no matter how many dividers precede a row.
+  type RenderRow = { item: SideBarMenuItem; index: number; dividerBefore: boolean };
+  function renderRows(list: SideBarMenuEntry[] = []): RenderRow[] {
+    const out: RenderRow[] = [];
+    let pending = false;
+    list.forEach((e, index) => {
+      if (isDivider(e)) {
+        if (out.length > 0) pending = true; // drop leading; collapse runs of dividers
+        return;
+      }
+      out.push({ item: e, index, dividerBefore: pending });
+      pending = false;
+    });
+    return out; // a trailing divider is never consumed → dropped
+  }
+
+  const anyIcon = (list: SideBarMenuEntry[] = []) => itemsOnly(list).some((i) => i.icon || i.badge);
   const railReserve = $derived(anyIcon(items) || anyIcon(bottomItems));
 
   // ── Mobile drawer state ─────────────────────────────────────────
@@ -605,7 +647,8 @@
     } else if (item.link && pathMatches(item.link, currentPath)) {
       return true;
     }
-    if (item.children?.length) return item.children.some(isItemActive);
+    const kids = itemsOnly(item.children);
+    if (kids.length) return kids.some(isItemActive);
     return false;
   }
   // A row's OWN active state (drives `aria-current`) — its own rule/link only, never descendants.
@@ -919,7 +962,7 @@
   {@const active = isItemActive(item)}
   {@const ownActive = isItemOwnActive(item)}
   {@const reserveIcon = opts.reserveIcon ?? true}
-  {@const hasChildren = (item.children?.length ?? 0) > 0}
+  {@const hasChildren = itemsOnly(item.children).length > 0}
   {@const isParent = hasChildren || !!item.popout}
   {@const hasLink = !!item.link}
   {@const isOpen = !!opts.id && isOnPath(opts.id)}
@@ -1028,7 +1071,7 @@
   depth: number,
 )}
   {@render row(item, { id, isPopoutChild: depth > 0, reserveIcon })}
-  {#if (((item.children?.length ?? 0) > 0) || !!item.popout) && !isStepped}
+  {#if (itemsOnly(item.children).length > 0 || !!item.popout) && !isStepped}
     {@const top = depth === 0}
     {@const geom = top
       ? geometryFor(id, group)
@@ -1085,9 +1128,9 @@
 {#snippet popoutPanel(item: SideBarMenuItem, id: ItemId, group: "top" | "bottom", maxHeight: string)}
   {@const popoutId = popoutDomId(id)}
   {@const isOpen = isOnPath(id)}
-  {@const kids = item.children ?? []}
-  {@const win = popoutWindow(id, kids.length)}
-  {@const childReserve = anyIcon(kids)}
+  {@const rows = renderRows(item.children)}
+  {@const win = popoutWindow(id, rows.length)}
+  {@const childReserve = anyIcon(item.children)}
   {@const rowsShown = (win.up ? 1 : 0) + (win.end - win.start) + (win.down ? 1 : 0)}
   {@const bd = popoutBorder(id, group, !id.includes(">"), rowsShown)}
   <!-- Nav submenu popout — a list of links (NOT role="menu"); Tab navigates, per the disclosure-nav
@@ -1106,7 +1149,7 @@
       : (e) => {
           if (win.up || win.down) {
             e.preventDefault();
-            stepPopout(id, kids.length, Math.sign(e.deltaY) * 3);
+            stepPopout(id, rows.length, Math.sign(e.deltaY) * 3);
           }
         }}
     onkeydown={item.popout
@@ -1114,10 +1157,10 @@
       : (e) => {
           if (e.key === "ArrowDown") {
             e.preventDefault();
-            stepPopout(id, kids.length, 1);
+            stepPopout(id, rows.length, 1);
           } else if (e.key === "ArrowUp") {
             e.preventDefault();
-            stepPopout(id, kids.length, -1);
+            stepPopout(id, rows.length, -1);
           }
         }}
   >
@@ -1129,15 +1172,20 @@
         {@render item.popout()}
       </div>
     {:else}
-      {#if win.up}{@render arrowRow(id, kids.length, -1)}{/if}
+      {#if win.up}{@render arrowRow(id, rows.length, -1)}{/if}
       <ul class="flex flex-col">
-        {#each kids.slice(win.start, win.end) as child, i (child.label)}
+        {#each rows.slice(win.start, win.end) as r, i (r.index)}
+          <!-- A divider renders only BETWEEN real rows: suppress it at the window's top edge (i===0),
+               where there's nothing above it and it would collide with the panel border. -->
+          {#if r.dividerBefore && i > 0}
+            <li class="list-none border-t [border-color:var(--ui-border-color)]" role="separator"></li>
+          {/if}
           <li class="list-none">
-            {@render menuNode(child, `${id}>${win.start + i}`, group, childReserve, 1)}
+            {@render menuNode(r.item, `${id}>${r.index}`, group, childReserve, 1)}
           </li>
         {/each}
       </ul>
-      {#if win.down}{@render arrowRow(id, kids.length, 1)}{/if}
+      {#if win.down}{@render arrowRow(id, rows.length, 1)}{/if}
     {/if}
   </div>
 {/snippet}
@@ -1203,20 +1251,29 @@
 		     return here — there is no in-drawer back row by design so
 		     the back affordance stays in a single, consistent spot. -->
     {@const currentParent = stepPath[stepPath.length - 1]}
-    {@const stepReserve = anyIcon(currentParent.children ?? [])}
+    {@const stepRows = renderRows(currentParent.children)}
+    {@const stepReserve = anyIcon(currentParent.children)}
     <ul class="flex flex-col {scrollList}">
-      {#each currentParent.children ?? [] as child, ci (child.label)}
+      {#each stepRows as r, i (r.index)}
+        {#if r.dividerBefore && i > 0}
+          <li class="list-none border-t [border-color:var(--ui-border-color)]" role="separator"></li>
+        {/if}
         <li class="list-none">
-          {@render row(child, { id: `step:${ci}`, isPopoutChild: true, reserveIcon: stepReserve })}
+          {@render row(r.item, { id: `step:${r.index}`, isPopoutChild: true, reserveIcon: stepReserve })}
         </li>
       {/each}
     </ul>
   {:else}
-    {#if items.length > 0}
+    {@const topRows = renderRows(items)}
+    {@const bottomRows = renderRows(bottomItems)}
+    {#if topRows.length > 0}
       <ul class="flex flex-col {scrollList}">
-        {#each items as item, idx (item.label)}
+        {#each topRows as r, i (r.index)}
+          {#if r.dividerBefore && i > 0}
+            <li class="list-none border-t [border-color:var(--ui-border-color)]" role="separator"></li>
+          {/if}
           <li class="list-none">
-            {@render menuNode(item, `top:${idx}`, "top", railReserve, 0)}
+            {@render menuNode(r.item, `top:${r.index}`, "top", railReserve, 0)}
           </li>
         {/each}
       </ul>
@@ -1224,15 +1281,18 @@
 
     <!-- With items present, the scrollable top list (flex-1) already fills the gap; only add a spacer
          to push the bottom cluster down when there are no top items. -->
-    {#if items.length === 0 && bottomItems.length > 0}
+    {#if topRows.length === 0 && bottomRows.length > 0}
       <div class="flex-1"></div>
     {/if}
 
-    {#if bottomItems.length > 0}
+    {#if bottomRows.length > 0}
       <ul class="flex flex-col shrink-0">
-        {#each bottomItems as item, idx (item.label)}
+        {#each bottomRows as r, i (r.index)}
+          {#if r.dividerBefore && i > 0}
+            <li class="list-none border-t [border-color:var(--ui-border-color)]" role="separator"></li>
+          {/if}
           <li class="list-none">
-            {@render menuNode(item, `bottom:${idx}`, "bottom", railReserve, 0)}
+            {@render menuNode(r.item, `bottom:${r.index}`, "bottom", railReserve, 0)}
           </li>
         {/each}
       </ul>

package/dist/components/SideBarMenu/SideBarMenu.svelte.d.ts

@@ -75,8 +75,9 @@ export type SideBarMenuItem = {
     link?: string;
     badge?: SideBarMenuBadge;
     /** Child items — rendered as a fly-out popout. Recursive: a child that itself has children
-     *  cascades into a further popout (or steps deeper in `stepped` mode). */
-    children?: SideBarMenuItem[];
+     *  cascades into a further popout (or steps deeper in `stepped` mode). May include
+     *  `{ divider: true }` entries to draw a separator between children. */
+    children?: SideBarMenuEntry[];
     /** Action row (no `link`) — renders a `<button>` and calls this on click. For a "toggle"
      *  row (an AI panel, etc.) or a non-navigating action. Runs after the drawer/popout reset. */
     onclick?: (e: MouseEvent) => void;
@@ -94,14 +95,28 @@ export type SideBarMenuItem = {
      *  the default `currentPath` segment-boundary match against `link`. */
     activeMatch?: SideBarMenuActiveRule;
 };
+/**
+ * A horizontal rule between adjacent rows in an `items` / `bottomItems` / `children` list — a 1px
+ * full-bleed separator (`--ui-border-color`) drawn between the two rows it sits between. It adds no
+ * navigable row and (visually) only the 1px line, so it never disturbs the fixed-height row rhythm.
+ * Leading, trailing, and consecutive dividers collapse — a divider renders ONLY between two real
+ * rows. Honoured identically in the fly-out popout, the stepped sub-view, and the inline
+ * expanded/drawer rail. Use the discriminated form `{ divider: true }` so a genuinely malformed item
+ * still falls through to the visible "malformed item" row rather than silently becoming a separator.
+ */
+export type SideBarMenuDivider = {
+    divider: true;
+};
+/** A SideBarMenu list entry: either a {@link SideBarMenuItem} or a {@link SideBarMenuDivider}. */
+export type SideBarMenuEntry = SideBarMenuItem | SideBarMenuDivider;
 import type { HTMLAttributes } from "svelte/elements";
 import type { Size } from "../../types/sizes.js";
 import { type Variant } from "../../types/variants.js";
 import { type Breakpoint } from "../../types/breakpoints.js";
 type ModesMap = Partial<Record<Breakpoint, SideBarMenuMode>>;
 type $$ComponentProps = {
-    items?: SideBarMenuItem[];
-    bottomItems?: SideBarMenuItem[];
+    items?: SideBarMenuEntry[];
+    bottomItems?: SideBarMenuEntry[];
     currentPath: string;
     size?: Size;
     /**

package/dist/data/table/grid.svelte.d.ts

@@ -1,6 +1,6 @@
 import { SvelteSet } from "svelte/reactivity";
 import type { DataSet, QueryColumn } from "../dataset";
-import type { Column, FetchFn, GridState, Sort } from "./types";
+import type { Column, FetchFn, GridState, GroupBy, GroupKey, Sort } from "./types";
 export type GridOptions<T> = {
     columns: Column<T>[];
     fetch: FetchFn<T>;
@@ -12,6 +12,9 @@ export type GridOptions<T> = {
     /** Per-row selection lock. Return `false` to make a row non-selectable: its checkbox is disabled,
      *  it's excluded from select-all, and `toggleRow`/`selected` never include it. Default: all selectable. */
     selectableRow?: (row: T) => boolean;
+    /** Section rows under group headings. A column id (ordered group-first automatically) or a function
+     *  returning the group identity. See {@link GroupBy}. Undefined → no grouping. */
+    groupBy?: GroupBy<T>;
 };
 /**
  * Shared, reactive controller for a data table. Implements {@link DataSet} (so any `<Query>` can
@@ -30,11 +33,15 @@ export declare class DataGrid<T> implements DataSet {
     sort: Sort | null;
     page: number;
     perPage: number;
+    /** Active grouping (reactive, so toggling it live re-sections the table). See {@link GroupBy}. */
+    groupBy: GroupBy<T> | undefined;
     rows: T[];
     total: number;
     loading: boolean;
     readonly selected: SvelteSet<string>;
     readonly expanded: SvelteSet<string>;
+    /** Keys of groups the user has collapsed (view-only; member rows stay in `rows`/selection). */
+    readonly collapsedGroups: SvelteSet<string>;
     constructor(opts: GridOptions<T>);
     get queryColumns(): QueryColumn[];
     get dirty(): boolean;
@@ -61,5 +68,16 @@ export declare class DataGrid<T> implements DataSet {
     toggleExpand(id: string): void;
     get allExpanded(): boolean;
     toggleExpandAll(): void;
+    get grouped(): boolean;
+    /** Resolve a row's group identity (null when not grouping). A column-id groupBy reads `row[id]`
+     *  (stringified); a function groupBy returns the identity (a bare string becomes `{key,label}`). */
+    groupOf(row: T): GroupKey | null;
+    /** Distinct group keys present on the current page, in first-seen order. */
+    get pageGroupKeys(): string[];
+    isGroupCollapsed(key: string): boolean;
+    toggleGroup(key: string): void;
+    get allGroupsCollapsed(): boolean;
+    /** Collapse every group on the page, or expand them all if all are already collapsed. */
+    toggleAllGroups(): void;
 }
 export declare function createGrid<T>(opts: GridOptions<T>): DataGrid<T>;

package/dist/data/table/grid.svelte.js

@@ -17,16 +17,21 @@ export class DataGrid {
     sort = $state(null);
     page = $state(1);
     perPage = $state(25);
+    /** Active grouping (reactive, so toggling it live re-sections the table). See {@link GroupBy}. */
+    groupBy = $state(undefined);
     rows = $state([]);
     total = $state(0);
     loading = $state(false);
     selected = new SvelteSet();
     expanded = new SvelteSet();
+    /** Keys of groups the user has collapsed (view-only; member rows stay in `rows`/selection). */
+    collapsedGroups = new SvelteSet();
     constructor(opts) {
         this.columns = opts.columns;
         this.fetch = opts.fetch;
         this.getRowId = opts.getRowId ?? ((r) => String(r.id));
         this.selectableRow = opts.selectableRow ?? (() => true);
+        this.groupBy = opts.groupBy;
         this.perPage = opts.perPage ?? 25;
         this.perPageOptions = opts.perPageOptions ?? [10, 25, 50, 100];
         this.sort = opts.initialSort ?? null;
@@ -63,7 +68,15 @@ export class DataGrid {
     }
     // ---- table view-state ----
     get request() {
-        return { q: this.applied, sort: this.sort, page: this.page, perPage: this.perPage };
+        return {
+            q: this.applied,
+            sort: this.sort,
+            page: this.page,
+            perPage: this.perPage,
+            // Only a column-id groupBy is serializable → emit it so the fetch orders group-first. A
+            // function groupBy is client-only (ordering is the consumer's), so `group` stays null.
+            group: typeof this.groupBy === "string" ? { key: this.groupBy, dir: "asc" } : null,
+        };
     }
     get pageCount() {
         return Math.max(1, Math.ceil(this.total / this.perPage));
@@ -146,6 +159,60 @@ export class DataGrid {
         else
             ids.forEach((id) => this.expanded.add(id));
     }
+    // ---- grouping (current page) ----
+    get grouped() {
+        return this.groupBy != null;
+    }
+    /** Resolve a row's group identity (null when not grouping). A column-id groupBy reads `row[id]`
+     *  (stringified); a function groupBy returns the identity (a bare string becomes `{key,label}`). */
+    groupOf(row) {
+        const g = this.groupBy;
+        if (g == null)
+            return null;
+        if (typeof g === "function") {
+            const r = g(row);
+            return typeof r === "string" ? { key: r, label: r } : r;
+        }
+        const v = row[g];
+        const s = v == null ? "" : String(v);
+        return { key: s, label: s };
+    }
+    /** Distinct group keys present on the current page, in first-seen order. */
+    get pageGroupKeys() {
+        if (this.groupBy == null)
+            return [];
+        const seen = new Set();
+        const out = [];
+        for (const r of this.rows) {
+            const g = this.groupOf(r);
+            if (g && !seen.has(g.key)) {
+                seen.add(g.key);
+                out.push(g.key);
+            }
+        }
+        return out;
+    }
+    isGroupCollapsed(key) {
+        return this.collapsedGroups.has(key);
+    }
+    toggleGroup(key) {
+        if (this.collapsedGroups.has(key))
+            this.collapsedGroups.delete(key);
+        else
+            this.collapsedGroups.add(key);
+    }
+    get allGroupsCollapsed() {
+        const ks = this.pageGroupKeys;
+        return ks.length > 0 && ks.every((k) => this.collapsedGroups.has(k));
+    }
+    /** Collapse every group on the page, or expand them all if all are already collapsed. */
+    toggleAllGroups() {
+        const ks = this.pageGroupKeys;
+        if (this.allGroupsCollapsed)
+            ks.forEach((k) => this.collapsedGroups.delete(k));
+        else
+            ks.forEach((k) => this.collapsedGroups.add(k));
+    }
 }
 export function createGrid(opts) {
     return new DataGrid(opts);

package/dist/data/table/local.js

@@ -50,10 +50,23 @@ export function localFetch(source, columns, opts = {}) {
                 now: opts.now?.(),
             }))
             : all.slice();
-        if (state.sort) {
-            const key = sortKeyOf(state.sort.col);
-            const dir = state.sort.dir === "desc" ? -1 : 1;
-            filtered.sort((a, b) => naturalCompare(value(a, key), value(b, key)) * dir);
+        // Group-first ordering: when the grid passes a serializable `group` (a column-id groupBy), sort by
+        // the group key PRIMARY so members are contiguous, then by the user's column sort WITHIN each group.
+        const gkey = state.group ? sortKeyOf(state.group.key) : null;
+        const gdir = state.group?.dir === "desc" ? -1 : 1;
+        const skey = state.sort ? sortKeyOf(state.sort.col) : null;
+        const sdir = state.sort?.dir === "desc" ? -1 : 1;
+        if (gkey || skey) {
+            filtered.sort((a, b) => {
+                if (gkey) {
+                    const c = naturalCompare(value(a, gkey), value(b, gkey)) * gdir;
+                    if (c !== 0)
+                        return c;
+                }
+                if (skey && skey !== gkey)
+                    return naturalCompare(value(a, skey), value(b, skey)) * sdir;
+                return 0;
+            });
         }
         const total = filtered.length;
         const start = (state.page - 1) * state.perPage;

package/dist/data/table/types.d.ts

@@ -6,6 +6,25 @@ export type Sort = {
     col: string;
     dir: SortDir;
 };
+/** A row's group identity under `groupBy`. `key` dedupes rows into a group and drives collapse
+ *  state; `label` is what the group header shows. */
+export type GroupKey = {
+    key: string;
+    label: string;
+};
+/**
+ * How `DataTable` sections rows under group headings. Either:
+ * - a **column id** — the group value is `row[id]` (stringified), and the grid orders rows by it
+ *   FIRST (then by the active column sort) so members are contiguous; serializable, so a remote
+ *   `query()` can honour it via {@link GridState.group}; or
+ * - a **function** — returns the group identity directly (or a bare string used as both key + label).
+ *   Client-only / non-serializable: the view still sections, but YOU must order the rows by group
+ *   (set a matching sort) — `GridState.group` is not emitted for the function form.
+ *
+ * Grouping sections the rows of the **current page** (a group spanning a page edge repeats its header
+ * on the next page); pair it with a group-key sort + a large/`"all"` perPage for complete groups.
+ */
+export type GroupBy<T> = string | ((row: T) => GroupKey | string);
 /** Our custom breakpoints + Tailwind defaults. `base` = mobile-first (no prefix).
  *
  *  Pixel boundaries (defined in theme.css `@theme`):
@@ -45,6 +64,14 @@ export type GridState = {
     sort: Sort | null;
     page: number;
     perPage: number;
+    /** Set when `groupBy` is a **column id**: order rows by this key FIRST (then by `sort`, within each
+     *  group) so group members are contiguous. Serializable, so a remote `query()` can honour it. `null`
+     *  when ungrouped or grouping by a function. Optional — pre-existing fetchers that ignore it still
+     *  work (grouping just needs the rows to already be group-contiguous). */
+    group?: {
+        key: string;
+        dir: SortDir;
+    } | null;
 };
 export type FetchResult<T> = {
     rows: T[];

package/dist/index.d.ts

@@ -76,7 +76,7 @@ export { default as Disclosure2 } from "./components/Disclosure2.svelte";
 export { default as Accordion2 } from "./components/Accordion2.svelte";
 export { default as DatePicker2 } from "./components/DatePicker2.svelte";
 export { default as SideBarMenu } from "./components/SideBarMenu/SideBarMenu.svelte";
-export type { SideBarMenuItem, SideBarMenuBadge, SideBarMenuBadgeVariant, SideBarMenuApi, SideBarMenuMode, SideBarMenuActiveRule, } from "./components/SideBarMenu/SideBarMenu.svelte";
+export type { SideBarMenuItem, SideBarMenuDivider, SideBarMenuEntry, SideBarMenuBadge, SideBarMenuBadgeVariant, SideBarMenuApi, SideBarMenuMode, SideBarMenuActiveRule, } from "./components/SideBarMenu/SideBarMenu.svelte";
 export { Breadcrumbs } from "./components/Breadcrumbs/index.js";
 export type { BreadcrumbItem } from "./components/Breadcrumbs/index.js";
 export { default as TabStrip } from "./components/TabStrip/TabStrip.svelte";

package/docs/components.md

@@ -483,10 +483,25 @@ Config-driven, responsive 12-column data table over a `DataGrid`.
 
 - **Location**: `src/lib/components/DataTable.svelte`
 - **Props**: `grid` (`DataGrid<T>` from `@spaethtech/svelte-ui/data`), `selectable`, `expandable`, `expanded`
-  (snippet), `rowActions` (`(row) => MenuItem[] | null`), `bulkActions`
+  (snippet), `rowActions` (`(row) => MenuItem[] | null`), `bulkActions`, `collapsibleGroups`, `groupHeader`
+  (snippet)
 - **Features**: selectable + expandable rows, sortable headers, per-row & bulk action menus
-  (via `Menu`/`Popup`), paginated footer. A **compound component** — all controls are
-  `<Button variant="plain" size="sm">` / `<Select size="sm">` / `<Checkbox>`.
+  (via `Menu`/`Popup`), paginated footer, optional **grouping** (below). A **compound component** — all
+  controls are `<Button variant="plain" size="sm">` / `<Select size="sm">` / `<Checkbox>`.
+- **Grouping (`groupBy`)**: pass **`groupBy: string | (row) => GroupKey | string`** to `createGrid` — a
+  **column id** (value `row[id]`, stringified; the grid orders rows **group-first** automatically) or a
+  **function** returning the group identity (client-only — order the rows yourself). `DataTable` then
+  draws a full-bleed **group-header row** at each group-key change, showing the label + a per-page count
+  `Badge`. Set **`collapsibleGroups`** to make the whole header row a toggle (mouse + keyboard) with a
+  chevron in the tail column (aligned to the kebab); collapse is **view-only** — member rows stay in
+  `grid.rows`/selection (`grid.collapsedGroups`, `toggleGroup(key)`, `toggleAllGroups()`). A
+  **`groupHeader`** snippet (`{ key, label, count, collapsed, toggle }`) replaces the default header for
+  aggregates/chips (build it from library components). **Model — grouping sections the _current page_**:
+  a column-id `groupBy` emits an optional **`group`** field on `GridState` (`{ key, dir }`) that
+  `localFetch` applies as the primary sort (user sort applies *within* each group) and a remote `query()`
+  honours as `ORDER BY <group>, <sort>`; a group spanning a page edge repeats its header on the next
+  page, and counts are per-page. Pair grouping with a group-key sort + a large/`"all"` perPage for
+  complete-looking groups. Ungrouped tables are unchanged.
 - **`rowActions` per row**: return `null`/`undefined`/`[]` for a row with no actions — the kebab still
   renders (the tail column stays aligned across rows) but is **disabled**, rather than opening an empty
   or all-greyed menu. Return items to enable it.

package/docs/usage.md

@@ -1144,16 +1144,27 @@ bar with `Query` over a `DataSet`.
     // optional: lock specific rows out of selection (disabled checkbox, excluded from select-all,
     // never in grid.selected — so bulkActions(selected) never sees them)
     selectableRow: (r) => !r.locked,
+    // optional: section rows under headings. A column id orders rows group-first automatically;
+    // a (row) => GroupKey | string function groups client-side (order the rows yourself).
+    groupBy: "status",
   });
 </script>
 
 <DataTable
   {grid}
   selectable
+  collapsibleGroups
   rowActions={(row) => [{ label: "Edit", icon: IconPencil, onclick: () => edit(row) }]}
 />
 ```
 
+**Grouping** sections the *current page*: a group header (label + per-page count) prints at each
+group-key change, `collapsibleGroups` makes the whole header row a collapse toggle, and a `groupHeader`
+snippet (`{ key, label, count, collapsed, toggle }`) overrides the default. A group spanning a page edge
+repeats its header on the next page — pair `groupBy` with a group-key sort and a large/`"all"` perPage
+for complete groups. `localFetch` orders a column-id `groupBy` group-first for you; a remote `query()`
+reads `GridState.group` (`{ key, dir }`) and does `ORDER BY <group>, <sort>`.
+
 `import { createGrid, localFetch, matchesRow } from "@spaethtech/svelte-ui/data";` — `localFetch` is the
 client-side counterpart to a remote `query()`; `matchesRow(row, ast)` is the underlying AST evaluator if
 you need to filter an array yourself. See the live demo for the full DataTable + Query walkthrough.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaethtech/svelte-ui",
-  "version": "0.21.1-dev.131.6298c61",
+  "version": "0.21.1-dev.134.0bfe62d",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/spaethtech/svelte-ui.git"