@spaethtech/svelte-ui 0.21.1-dev.132.b812036 → 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/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/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.132.b812036",
+  "version": "0.21.1-dev.134.0bfe62d",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/spaethtech/svelte-ui.git"