nuxt-ui-tools 1.28.0 → 1.29.0

package/dist/module.json

@@ -5,7 +5,7 @@
   "configKey": "nuxtUiTools",
   "docs": "https://ui.nuxt.com/docs/getting-started/installation/nuxt",
   "name": "nuxt-ui-tools",
-  "version": "1.28.0",
+  "version": "1.29.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "unknown"

package/dist/runtime/i18n/locales/en.js

@@ -748,6 +748,11 @@ export default defineUiToolsLocale({
         label: "Actions for {label}",
         labelAt: "Actions for row {position}"
       },
+      groups: {
+        empty: "Other",
+        select: "Select the whole group",
+        toggle: "Fold or unfold the group"
+      },
       selection: {
         selectAll: "Select all rows",
         selectRow: "Select {label}",

package/dist/runtime/i18n/locales/fr.js

@@ -748,6 +748,11 @@ export default defineUiToolsLocale({
         label: "Actions pour {label}",
         labelAt: "Actions pour la ligne {position}"
       },
+      groups: {
+        empty: "Autres",
+        select: "S\xE9lectionner tout le groupe",
+        toggle: "Replier ou d\xE9plier le groupe"
+      },
       selection: {
         selectAll: "S\xE9lectionner toutes les lignes",
         selectRow: "S\xE9lectionner {label}",

package/dist/runtime/i18n/types.d.ts

@@ -23,6 +23,13 @@ export interface UiToolsTableMessages {
         firstPage: string;
         lastPage: string;
     };
+    /** A row group's header. */
+    groups: {
+        /** The label of the group holding rows with no value. */
+        empty: string;
+        select: string;
+        toggle: string;
+    };
     /** Accessible names of the selection checkboxes. */
     selection: {
         selectAll: string;

package/dist/runtime/table/components/grid/grid-renderer.vue

@@ -11,6 +11,7 @@ import { mergeDataListUiClass, resolveTableRowId } from "../../utils";
 import DataListErrorState from "../data-list/data-list-error-state.vue";
 import ProgressLine from "../layout/progress-line.vue";
 import TableEmptyState from "../table/table-empty-state.vue";
+import TableGroupHeader from "../table/table-group-header.vue";
 import OverlayInsetSpacer from "../utils/overlay-inset-spacer.vue";
 import GridCard from "./grid-card.vue";
 import GridSkeleton from "./grid-skeleton.vue";
@@ -75,12 +76,21 @@ watch(
 );
 function getVirtualRowKey(index) {
   const chunk = rowChunks.value[index];
+  if (chunk?.group) return `grid-group:${chunk.group.key}`;
   const firstRow = chunk?.rows[0];
   return firstRow ? `grid-row:${resolveTableRowId({ index: chunk.start, row: firstRow, rowKey: internals.schema.value.rowKey })}` : `grid-row:${index}`;
 }
 function rowId(row, index) {
   return resolveTableRowId({ index, row, rowKey: internals.schema.value.rowKey });
 }
+const flowItems = computed(
+  () => rowChunks.value.flatMap(
+    (chunk) => chunk.group ? [{ group: chunk.group, index: chunk.start, key: `grid-group:${chunk.group.key}` }] : chunk.rows.map((row, offset) => ({
+      index: chunk.start + offset,
+      key: rowId(row, chunk.start + offset)
+    }))
+  )
+);
 function scrollToTop() {
   viewportRef.value?.scrollTo({ behavior: "auto", left: 0, top: 0 });
 }
@@ -258,6 +268,13 @@ function refreshData() {
 }"
           :data-index="virtualRow.index"
         >
+          <div
+            v-if="rowChunks[virtualRow.index]?.group"
+            class="nut-dl-grid__group min-w-0"
+            :style="{ gridColumn: '1 / -1' }"
+          >
+            <TableGroupHeader :group="rowChunks[virtualRow.index].group" />
+          </div>
           <div
             v-for="(row, offset) in rowChunks[virtualRow.index]?.rows ?? []"
             :key="rowId(row, (rowChunks[virtualRow.index]?.start ?? 0) + offset)"
@@ -275,14 +292,22 @@ function refreshData() {
         :class="mergeDataListUiClass('nut-dl-grid__flow grid', void 0, ui?.flow)"
         :style="{ gridTemplateColumns, gap: `${gap}px` }"
       >
-        <div
-          v-for="(row, index) in tableRows"
-          :key="rowId(row, index)"
-          :class="mergeDataListUiClass('nut-dl-grid__item min-w-0', void 0, ui?.item)"
-          :style="{ gridColumn }"
-        >
-          <GridCard :row-index="index" />
-        </div>
+        <template v-for="item in flowItems" :key="item.key">
+          <div
+            v-if="item.group"
+            class="nut-dl-grid__group min-w-0"
+            :style="{ gridColumn: '1 / -1' }"
+          >
+            <TableGroupHeader :group="item.group" />
+          </div>
+          <div
+            v-else
+            :class="mergeDataListUiClass('nut-dl-grid__item min-w-0', void 0, ui?.item)"
+            :style="{ gridColumn }"
+          >
+            <GridCard :row-index="item.index" />
+          </div>
+        </template>
       </div>
       <OverlayInsetSpacer />
     </div>

package/dist/runtime/table/components/table/table-group-header.d.vue.ts

@@ -0,0 +1,9 @@
+import type { TableGroup } from '../../types/index.js';
+type __VLS_Props = {
+    group: TableGroup;
+    /** Whether the rows beneath it carry checkboxes. */
+    selectable?: boolean;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/table/components/table/table-group-header.vue

@@ -0,0 +1,77 @@
+<script setup>
+import { computed } from "vue";
+import { useUiToolsLocale } from "#ui-tools/i18n";
+import { useTableInternals } from "../../composables/use-table-internals";
+import TableCell from "./table-cell";
+import TableSelectionControl from "./table-selection-control.vue";
+const props = defineProps({
+  group: { type: Object, required: true },
+  selectable: { type: Boolean, required: false }
+});
+const { groups, selection } = useTableInternals();
+const { t } = useUiToolsLocale();
+const collapsed = computed(() => groups.isCollapsed(props.group));
+const params = computed(() => ({ rows: props.group.rows, value: props.group.value }));
+const checked = computed(() => selection.getRowsSelectionState({ rowIds: props.group.rowIds }));
+const showCheckbox = computed(() => props.selectable && selection.selectionEnabled.value);
+function renderLabel() {
+  const label = groups.config.value?.label;
+  if (label) return label(params.value);
+  return props.group.value === void 0 ? t("table.groups.empty") : String(props.group.value);
+}
+function renderSummary() {
+  const summary = groups.config.value?.summary;
+  return summary ? summary(params.value) : props.group.rows.length;
+}
+function toggleSelection() {
+  const { rowIds } = props.group;
+  if (checked.value === true) selection.unselectRows({ rowIds });
+  else selection.selectRows({ rowIds });
+}
+</script>
+
+<template>
+  <div
+    class="nut-dl-group"
+    :data-collapsed="collapsed || void 0"
+    :data-selectable="showCheckbox || void 0"
+    @click="groups.toggle(group)"
+  >
+    <span v-if="showCheckbox" class="nut-dl-group__check">
+      <TableSelectionControl
+        :model-value="checked"
+        :label="t('table.groups.select')"
+        @toggle="toggleSelection"
+      />
+    </span>
+    <button
+      type="button"
+      class="nut-dl-group__toggle"
+      :aria-expanded="!collapsed"
+      :aria-label="t('table.groups.toggle')"
+      @click.stop="groups.toggle(group)"
+    >
+      <svg
+        viewBox="0 0 16 16"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="1.75"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        aria-hidden="true"
+      >
+        <path d="m4 6 4 4 4-4" />
+      </svg>
+    </button>
+    <span class="nut-dl-group__label">
+      <TableCell :index="0" :render="renderLabel" :row="group" />
+    </span>
+    <span class="nut-dl-group__summary">
+      <TableCell :index="0" :render="renderSummary" :row="group" />
+    </span>
+  </div>
+</template>
+
+<style>
+.nut-dl-group{--nut-dl-group-gutter:var(--nut-dl-gutter,0px);box-sizing:border-box;color:var(--ui-text-highlighted);cursor:pointer;font-size:13px;font-weight:600;gap:6px;height:100%;left:0;max-width:100%;min-height:32px;padding-inline:var(--nut-dl-group-gutter);position:sticky;-webkit-user-select:none;-moz-user-select:none;user-select:none;white-space:nowrap}.nut-dl-group,.nut-dl-group__check{align-items:center;display:inline-flex}.nut-dl-group__check{flex:none;margin-right:-6px;width:calc(var(--nut-dl-select-w, 44px) - var(--nut-dl-group-gutter) + var(--nut-dl-cell-x, 0px))}.nut-dl-group__toggle{background:transparent;border:0;border-radius:calc(var(--ui-radius)*1.5);color:var(--ui-text-muted);cursor:pointer;display:grid;flex:none;height:22px;outline:none;padding:0;place-items:center;width:22px}.nut-dl-group__toggle:hover{background:var(--nut-dl-toggle-hover,var(--ui-bg-accented))}.nut-dl-group__toggle:focus-visible{box-shadow:0 0 0 2px var(--ui-primary)}.nut-dl-group__toggle svg{height:16px;transition:transform .16s ease;width:16px}.nut-dl-group[data-collapsed] .nut-dl-group__toggle svg{transform:rotate(-90deg)}.nut-dl-group__label{min-width:0;overflow:hidden;text-overflow:ellipsis}.nut-dl-group__summary{color:var(--ui-text-muted);flex:none;font-size:12px;font-variant-numeric:tabular-nums;font-weight:500}.nut-dl-row.nut-dl-row--group{background:var(--nut-dl-head-bg)}.nut-dl-row.nut-dl-row--group:hover{background:color-mix(in srgb,var(--nut-dl-head-fg) 7%,var(--nut-dl-head-bg))}.nut-dl-group-cell{background:inherit;border-bottom:1px solid var(--nut-dl-line);height:var(--nut-dl-head-h);padding:0}.nut-dl-grid__group{border-bottom:1px solid var(--ui-border)}@media (prefers-reduced-motion:reduce){.nut-dl-group__toggle svg{transition:none}}
+</style>

package/dist/runtime/table/components/table/table-group-header.vue.d.ts

@@ -0,0 +1,9 @@
+import type { TableGroup } from '../../types/index.js';
+type __VLS_Props = {
+    group: TableGroup;
+    /** Whether the rows beneath it carry checkboxes. */
+    selectable?: boolean;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/table/components/table/table-renderer.vue

@@ -6,7 +6,7 @@ import { isFunction, isNumber, isObject } from "../../../shared/utils/predicate"
 import { useDataListUi } from "../../composables/use-data-list-ui";
 import { useTableInternals } from "../../composables/use-table-internals";
 import { useTanstackTable } from "../../composables/use-tanstack-table";
-import { mergeDataListUiClass } from "../../utils";
+import { mergeDataListUiClass, tableGroupOf } from "../../utils";
 import {
   ROW_ACTIONS_COLUMN_ID,
   SELECT_COLUMN_ID,
@@ -54,7 +54,7 @@ const props = defineProps({
   ui: { type: Object, required: false }
 });
 const internals = useTableInternals();
-const { tree } = internals;
+const { groups, tree } = internals;
 const dataListUi = useDataListUi();
 const { locale, t } = useUiToolsLocale();
 const rows = computed(
@@ -89,6 +89,7 @@ const tokenStyle = computed(() => ({
   "--nut-dl-gutter": `${gutter.value}px`,
   "--nut-dl-head-h": `${tokens.value.head}px`,
   "--nut-dl-row-h": `${tokens.value.row}px`,
+  "--nut-dl-select-w": `${SELECT_COLUMN_WIDTH + gutterExtra.value}px`,
   "--nut-dl-tree-gutter": `${TREE_GUTTER_WIDTH}px`,
   "--nut-dl-tree-toggle": `${TREE_TOGGLE_WIDTH}px`,
   "--nut-dl-tree-gap": `${TREE_GAP}px`,
@@ -141,11 +142,13 @@ const pinned = computed(() => {
   };
 });
 function getRowId(row, index) {
-  return internals.selection.getRowId({ index, row });
+  return tableGroupOf(row)?.key ?? internals.selection.getRowId({ index, row });
 }
-const sourceRows = computed(
-  () => tree.enabled.value && rows.value.length > 0 ? tree.visibleRows.value : rows.value
-);
+const sourceRows = computed(() => {
+  if (rows.value.length === 0) return rows.value;
+  if (tree.enabled.value) return tree.visibleRows.value;
+  return groups.enabled.value ? groups.displayRows.value : rows.value;
+});
 const renderRows = computed(() => rowsMounted.value ? sourceRows.value : []);
 const virtualized = computed(
   () => renderRows.value.length >= VIRTUALIZE_ROW_THRESHOLD || renderRows.value.length * columnDefs.value.length >= VIRTUALIZE_CELL_THRESHOLD
@@ -745,7 +748,9 @@ defineExpose({ resetColumnSizing });
             :node="tree.nodeOf(row.id)"
             :expanded="tree.isExpanded(row.id)"
             :checkbox="hasCheckbox(row.id)"
-            :motion="tree.motionOf(row.id)"
+            :motion="tree.motionOf(row.id) ?? groups.motionOf(row.id)"
+            :group="tableGroupOf(row.original)"
+            :col-span="columnCount"
             @toggle="tree.toggleRow(row.id)"
             @select="onSelectRow(row.id, $event)"
           />

package/dist/runtime/table/components/table/table-row.d.vue.ts

@@ -3,7 +3,7 @@
  * so rows that stay on screen while the virtual window slides keep their cells untouched.
  */
 import type { HTMLAttributes } from 'vue';
-import type { GenericObject, TableTreeMotion, TableTreeNode } from '../../types/index.js';
+import type { GenericObject, TableGroup, TableTreeMotion, TableTreeNode } from '../../types/index.js';
 import type { tableRowCells } from './table-layout.js';
 type __VLS_Props = {
     rowId: string;
@@ -20,6 +20,9 @@ type __VLS_Props = {
     checkbox?: boolean;
     /** The row is being revealed or concealed by a branch opening or closing. */
     motion?: TableTreeMotion;
+    /** Set on a group's header row, which spans the columns instead of filling them. */
+    group?: TableGroup;
+    colSpan?: number;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     select: (event: MouseEvent) => any;

package/dist/runtime/table/components/table/table-row.vue

@@ -1,5 +1,6 @@
 <script setup>
 import TableCell from "./table-cell";
+import TableGroupHeader from "./table-group-header.vue";
 import TableTreeControl from "./table-tree-control.vue";
 defineProps({
   rowId: { type: String, required: true },
@@ -12,13 +13,27 @@ defineProps({
   node: { type: Object, required: false },
   expanded: { type: Boolean, required: false },
   checkbox: { type: Boolean, required: false },
-  motion: { type: Object, required: false }
+  motion: { type: Object, required: false },
+  group: { type: Object, required: false },
+  colSpan: { type: Number, required: false }
 });
 const emit = defineEmits(["toggle", "select"]);
 </script>
 
 <template>
   <tr
+    v-if="group"
+    class="nut-dl-row nut-dl-row--group"
+    :class="rowClass"
+    :data-index="index"
+    :data-row-id="rowId"
+  >
+    <td :colspan="colSpan" class="nut-dl-group-cell">
+      <TableGroupHeader :group="group" selectable />
+    </td>
+  </tr>
+  <tr
+    v-else
     class="nut-dl-row group/row"
     :class="[
   selected ? 'nut-dl-row--selected' : '',

package/dist/runtime/table/components/table/table-row.vue.d.ts

@@ -3,7 +3,7 @@
  * so rows that stay on screen while the virtual window slides keep their cells untouched.
  */
 import type { HTMLAttributes } from 'vue';
-import type { GenericObject, TableTreeMotion, TableTreeNode } from '../../types/index.js';
+import type { GenericObject, TableGroup, TableTreeMotion, TableTreeNode } from '../../types/index.js';
 import type { tableRowCells } from './table-layout.js';
 type __VLS_Props = {
     rowId: string;
@@ -20,6 +20,9 @@ type __VLS_Props = {
     checkbox?: boolean;
     /** The row is being revealed or concealed by a branch opening or closing. */
     motion?: TableTreeMotion;
+    /** Set on a group's header row, which spans the columns instead of filling them. */
+    group?: TableGroup;
+    colSpan?: number;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     select: (event: MouseEvent) => any;

package/dist/runtime/table/components/table/table-selection-control.d.vue.ts

@@ -5,6 +5,8 @@ type __VLS_Props = {
     row?: GenericObject;
     /** Where the record sits in the rendered rows: it names the record when the schema has no `rowLabel`. */
     index?: number;
+    /** Names what it selects when that is neither one record nor every row. */
+    label?: string;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     toggle: (event: MouseEvent) => any;

package/dist/runtime/table/components/table/table-selection-control.vue

@@ -7,7 +7,8 @@ import { mergeDataListProps, mergeDataListUiClass } from "../../utils";
 const props = defineProps({
   modelValue: { type: [Boolean, String], required: true },
   row: { type: Object, required: false },
-  index: { type: Number, required: false }
+  index: { type: Number, required: false },
+  label: { type: String, required: false }
 });
 const emit = defineEmits(["toggle"]);
 const dataListUi = useDataListUi();
@@ -20,7 +21,7 @@ const areaClass = computed(
   )
 );
 const ariaLabel = computed(
-  () => props.row ? labels.selectRow({ index: props.index ?? 0, row: props.row }) : labels.selectAll()
+  () => props.label ?? (props.row ? labels.selectRow({ index: props.index ?? 0, row: props.row }) : labels.selectAll())
 );
 const checkboxProps = computed(
   () => mergeDataListProps(

package/dist/runtime/table/components/table/table-selection-control.vue.d.ts

@@ -5,6 +5,8 @@ type __VLS_Props = {
     row?: GenericObject;
     /** Where the record sits in the rendered rows: it names the record when the schema has no `rowLabel`. */
     index?: number;
+    /** Names what it selects when that is neither one record nor every row. */
+    label?: string;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     toggle: (event: MouseEvent) => any;

package/dist/runtime/table/composables/use-table-grid.d.ts

@@ -1,20 +1,24 @@
 import type { ComputedRef } from 'vue';
-import type { GenericObject, TableExternalState, TableGridMode, TableSchemaView } from '../types/index.js';
+import type { GenericObject, TableExternalState, TableGridMode, TableGroup, TableSchemaView } from '../types/index.js';
+import type { useTableGroups } from './use-table-groups.js';
 export interface GridRowChunk<TRow = unknown> {
     index: number;
     start: number;
     end: number;
     rows: TRow[];
+    /** The group this chunk is the header of; a header holds no rows. */
+    group?: TableGroup;
 }
 export interface UseTableGridParams<TRow extends GenericObject = GenericObject> {
     schema: ComputedRef<TableSchemaView>;
     data: ComputedRef<TableExternalState<TRow>>;
+    groups: ReturnType<typeof useTableGroups>;
 }
 export declare function useTableGrid<TRow extends GenericObject>(options: UseTableGridParams<TRow>): {
     cardsPerRow: ComputedRef<number>;
     columnCount: ComputedRef<number>;
     itemColumnSpan: ComputedRef<number>;
     mode: ComputedRef<TableGridMode>;
-    rowChunks: ComputedRef<GridRowChunk<TRow>[]>;
-    rows: ComputedRef<TRow[]>;
+    rowChunks: ComputedRef<GridRowChunk<object>[]>;
+    rows: ComputedRef<object[]>;
 };

package/dist/runtime/table/composables/use-table-grid.js

@@ -19,9 +19,15 @@ export function useTableGrid(options) {
   const cardsPerRow = computed(
     () => Math.max(1, Math.floor(columnCount.value / itemColumnSpan.value))
   );
-  const rows = computed(() => options.data.value.rows);
+  const rows = computed(
+    () => options.groups.enabled.value ? options.groups.orderedRows.value : options.data.value.rows
+  );
   const rowChunks = computed(
-    () => chunkRows({
+    () => options.groups.enabled.value ? chunkGroups({
+      cardsPerRow: cardsPerRow.value,
+      groups: options.groups.groups.value,
+      isCollapsed: options.groups.isCollapsed
+    }) : chunkRows({
       cardsPerRow: cardsPerRow.value,
       rows: rows.value
     })
@@ -48,6 +54,25 @@ function resolveResponsiveGridNumber(value) {
 function isResponsiveGridValueResolver(value) {
   return isFunction(value);
 }
+function chunkGroups(options) {
+  const chunks = [];
+  let offset = 0;
+  for (const group of options.groups) {
+    chunks.push({ end: offset, group, index: chunks.length, rows: [], start: offset });
+    if (!options.isCollapsed(group)) {
+      for (const chunk of chunkRows({ cardsPerRow: options.cardsPerRow, rows: group.rows })) {
+        chunks.push({
+          ...chunk,
+          end: offset + chunk.end,
+          index: chunks.length,
+          start: offset + chunk.start
+        });
+      }
+    }
+    offset += group.rows.length;
+  }
+  return chunks;
+}
 function chunkRows(options) {
   return Array.from(
     { length: Math.ceil(options.rows.length / options.cardsPerRow) },

package/dist/runtime/table/composables/use-table-groups.d.ts

@@ -0,0 +1,28 @@
+import type { ComputedRef } from 'vue';
+import type { TableGroup, TableSchemaView, TableTreeMotion } from '../types/index.js';
+import type { UseTableDataReturn } from './use-table-data.js';
+import type { useTableLayout } from './use-table-layout.js';
+export interface UseTableGroupsParams {
+    schema: ComputedRef<TableSchemaView>;
+    layout: ReturnType<typeof useTableLayout>;
+    queryContent: Pick<UseTableDataReturn, 'data'>;
+}
+/**
+ * Owns row groups: which groups the loaded rows form, which are folded, and the motion of folding
+ * one. The data stays flat; `displayRows` adds the header rows to what the table renders.
+ *
+ * Fold state is the schema's `collapsed` plus the groups the reader toggled, kept per table so a
+ * trip to a record and back finds the list as it was left. A table with `table.tree` has its own
+ * hierarchy and is not grouped.
+ */
+export declare function useTableGroups(params: UseTableGroupsParams): {
+    config: ComputedRef<import("../types/index.js").TableGroupBySchema<object> | undefined>;
+    displayRows: ComputedRef<object[]>;
+    enabled: ComputedRef<boolean>;
+    groups: ComputedRef<TableGroup<object>[]>;
+    isCollapsed: (group: TableGroup) => boolean;
+    motionOf: (rowId: string) => TableTreeMotion | undefined;
+    orderedRows: ComputedRef<object[]>;
+    toggle: (group: TableGroup) => void;
+    visibleRowIds: ComputedRef<string[]>;
+};

package/dist/runtime/table/composables/use-table-groups.js

@@ -0,0 +1,133 @@
+import { usePreferredReducedMotion } from "@vueuse/core";
+import { computed, getCurrentInstance, onMounted, onScopeDispose, ref, shallowRef } from "vue";
+import {
+  ROW_CONCEAL_MS,
+  ROW_MOTION_LIMIT,
+  ROW_REVEAL_MS,
+  ROW_STAGGER_LIMIT,
+  ROW_STAGGER_MS
+} from "../constants/row-motion.js";
+import {
+  buildTableGroups,
+  parseStoredGroupKeys,
+  tableGroupRow,
+  tableGroupsStorageKey
+} from "../utils/groups.js";
+import { resolveTableRowId } from "../utils/rows.js";
+export function useTableGroups(params) {
+  const reducedMotion = usePreferredReducedMotion();
+  const config = computed(() => {
+    const { grid, table } = params.schema.value;
+    if (params.layout.activeLayout.value === "grid") return grid?.groupBy;
+    return table?.tree ? void 0 : table?.groupBy;
+  });
+  const enabled = computed(() => Boolean(config.value));
+  const groups = computed(() => {
+    const groupBy = config.value;
+    if (!groupBy) return [];
+    return buildTableGroups({
+      getRowId: (row, index) => String(resolveTableRowId({ index, row, rowKey: params.schema.value.rowKey })),
+      groupBy,
+      rows: params.queryContent.data.value.rows
+    });
+  });
+  const toggled = ref(/* @__PURE__ */ new Set());
+  const persists = computed(() => params.schema.value.persistence?.preferences !== false);
+  function storage() {
+    try {
+      return typeof window === "undefined" || !persists.value ? null : window.localStorage;
+    } catch {
+      return null;
+    }
+  }
+  function restore() {
+    try {
+      const raw = storage()?.getItem(tableGroupsStorageKey(params.schema.value.tableKey)) ?? null;
+      toggled.value = new Set(parseStoredGroupKeys(raw));
+    } catch {
+      toggled.value = /* @__PURE__ */ new Set();
+    }
+  }
+  function remember() {
+    const key = tableGroupsStorageKey(params.schema.value.tableKey);
+    try {
+      if (toggled.value.size) storage()?.setItem(key, JSON.stringify([...toggled.value]));
+      else storage()?.removeItem(key);
+    } catch {
+      return;
+    }
+  }
+  if (getCurrentInstance()) onMounted(restore);
+  else restore();
+  function startsCollapsed(group) {
+    const collapsed = config.value?.collapsed;
+    return typeof collapsed === "function" ? collapsed({ rows: group.rows, value: group.value }) : Boolean(collapsed);
+  }
+  function isCollapsed(group) {
+    return startsCollapsed(group) !== toggled.value.has(group.key);
+  }
+  function flip(group) {
+    const next = new Set(toggled.value);
+    if (!next.delete(group.key)) next.add(group.key);
+    toggled.value = next;
+    remember();
+  }
+  const motion = shallowRef(null);
+  const closing = ref(null);
+  let timer;
+  function settle() {
+    clearTimeout(timer);
+    closing.value = null;
+    motion.value = null;
+  }
+  function toggle(group) {
+    settle();
+    const opening = isCollapsed(group);
+    flip(group);
+    if (reducedMotion.value === "reduce" || params.layout.activeLayout.value === "grid") return;
+    const moving = group.rowIds.slice(0, ROW_MOTION_LIMIT);
+    motion.value = new Map(
+      moving.map((rowId, order) => [
+        rowId,
+        { kind: opening ? "enter" : "leave", order: Math.min(order, ROW_STAGGER_LIMIT) }
+      ])
+    );
+    if (opening) {
+      timer = setTimeout(
+        settle,
+        ROW_REVEAL_MS + Math.min(moving.length, ROW_STAGGER_LIMIT) * ROW_STAGGER_MS
+      );
+      return;
+    }
+    closing.value = group.key;
+    timer = setTimeout(settle, ROW_CONCEAL_MS);
+  }
+  onScopeDispose(() => clearTimeout(timer));
+  function motionOf(rowId) {
+    return motion.value?.get(rowId);
+  }
+  function rowsListed(group) {
+    return !isCollapsed(group) || closing.value === group.key;
+  }
+  const displayRows = computed(
+    () => groups.value.flatMap((group) => [
+      tableGroupRow(group),
+      ...rowsListed(group) ? group.rows : []
+    ])
+  );
+  const orderedRows = computed(() => groups.value.flatMap((group) => group.rows));
+  const visibleRowIds = computed(
+    () => groups.value.flatMap((group) => isCollapsed(group) ? [] : group.rowIds)
+  );
+  return {
+    config,
+    displayRows,
+    enabled,
+    groups,
+    isCollapsed,
+    motionOf,
+    orderedRows,
+    toggle,
+    visibleRowIds
+  };
+}

package/dist/runtime/table/composables/use-table-internals.d.ts

@@ -228,6 +228,17 @@ declare function createTableInternals<TSchema>(options: {
         rowChunks: import("vue").ComputedRef<import("./use-table-grid.js").GridRowChunk<object>[]>;
         rows: import("vue").ComputedRef<object[]>;
     };
+    groups: {
+        config: import("vue").ComputedRef<import("../types/index.js").TableGroupBySchema<object> | undefined>;
+        displayRows: import("vue").ComputedRef<object[]>;
+        enabled: import("vue").ComputedRef<boolean>;
+        groups: import("vue").ComputedRef<import("../types/index.js").TableGroup<object>[]>;
+        isCollapsed: (group: import("../types/index.js").TableGroup) => boolean;
+        motionOf: (rowId: string) => import("../types/index.js").TableTreeMotion | undefined;
+        orderedRows: import("vue").ComputedRef<object[]>;
+        toggle: (group: import("../types/index.js").TableGroup) => void;
+        visibleRowIds: import("vue").ComputedRef<string[]>;
+    };
     layout: {
         activeLayout: import("vue").WritableComputedRef<import("../types/index.js").TableLayout, import("../types/index.js").TableLayout>;
         gridEnabled: import("vue").ComputedRef<boolean>;
@@ -345,6 +356,9 @@ declare function createTableInternals<TSchema>(options: {
             row: import("../types/index.js").GenericObject;
             index?: number;
         }) => string;
+        getRowsSelectionState: (params: {
+            rowIds: string[];
+        }) => boolean | "indeterminate";
         isRowSelected: (params: {
             rowId: string;
         }) => boolean;
@@ -851,6 +865,17 @@ declare function useProvideTableInternals<TSchema>(options: {
         rowChunks: import("vue").ComputedRef<import("./use-table-grid.js").GridRowChunk<object>[]>;
         rows: import("vue").ComputedRef<object[]>;
     };
+    groups: {
+        config: import("vue").ComputedRef<import("../types/index.js").TableGroupBySchema<object> | undefined>;
+        displayRows: import("vue").ComputedRef<object[]>;
+        enabled: import("vue").ComputedRef<boolean>;
+        groups: import("vue").ComputedRef<import("../types/index.js").TableGroup<object>[]>;
+        isCollapsed: (group: import("../types/index.js").TableGroup) => boolean;
+        motionOf: (rowId: string) => import("../types/index.js").TableTreeMotion | undefined;
+        orderedRows: import("vue").ComputedRef<object[]>;
+        toggle: (group: import("../types/index.js").TableGroup) => void;
+        visibleRowIds: import("vue").ComputedRef<string[]>;
+    };
     layout: {
         activeLayout: import("vue").WritableComputedRef<import("../types/index.js").TableLayout, import("../types/index.js").TableLayout>;
         gridEnabled: import("vue").ComputedRef<boolean>;
@@ -968,6 +993,9 @@ declare function useProvideTableInternals<TSchema>(options: {
             row: import("../types/index.js").GenericObject;
             index?: number;
         }) => string;
+        getRowsSelectionState: (params: {
+            rowIds: string[];
+        }) => boolean | "indeterminate";
         isRowSelected: (params: {
             rowId: string;
         }) => boolean;
@@ -1471,6 +1499,17 @@ declare function useTableInternals(): {
         rowChunks: import("vue").ComputedRef<import("./use-table-grid.js").GridRowChunk<object>[]>;
         rows: import("vue").ComputedRef<object[]>;
     };
+    groups: {
+        config: import("vue").ComputedRef<import("../types/index.js").TableGroupBySchema<object> | undefined>;
+        displayRows: import("vue").ComputedRef<object[]>;
+        enabled: import("vue").ComputedRef<boolean>;
+        groups: import("vue").ComputedRef<import("../types/index.js").TableGroup<object>[]>;
+        isCollapsed: (group: import("../types/index.js").TableGroup) => boolean;
+        motionOf: (rowId: string) => import("../types/index.js").TableTreeMotion | undefined;
+        orderedRows: import("vue").ComputedRef<object[]>;
+        toggle: (group: import("../types/index.js").TableGroup) => void;
+        visibleRowIds: import("vue").ComputedRef<string[]>;
+    };
     layout: {
         activeLayout: import("vue").WritableComputedRef<import("../types/index.js").TableLayout, import("../types/index.js").TableLayout>;
         gridEnabled: import("vue").ComputedRef<boolean>;
@@ -1588,6 +1627,9 @@ declare function useTableInternals(): {
             row: import("../types/index.js").GenericObject;
             index?: number;
         }) => string;
+        getRowsSelectionState: (params: {
+            rowIds: string[];
+        }) => boolean | "indeterminate";
         isRowSelected: (params: {
             rowId: string;
         }) => boolean;

package/dist/runtime/table/composables/use-table-internals.js

@@ -8,6 +8,7 @@ import { useTableData } from "./use-table-data.js";
 import { useTableFilterPresentation } from "./use-table-filter-presentation.js";
 import { useTableFilters } from "./use-table-filters.js";
 import { useTableGrid } from "./use-table-grid.js";
+import { useTableGroups } from "./use-table-groups.js";
 import { useTableLayout } from "./use-table-layout.js";
 import { useTablePagination } from "./use-table-pagination.js";
 import { useTableRowSummary } from "./use-table-row-summary.js";
@@ -35,7 +36,13 @@ function createTableInternals(options) {
     queryContent,
     schema
   });
+  const groups = useTableGroups({
+    layout,
+    queryContent,
+    schema
+  });
   const selection = useTableSelection({
+    groups,
     queryContent,
     schema,
     tree
@@ -60,6 +67,7 @@ function createTableInternals(options) {
   });
   const grid = useTableGrid({
     data: queryContent.data,
+    groups,
     schema
   });
   const tableColumns = useTableColumns({
@@ -112,6 +120,7 @@ function createTableInternals(options) {
     filterPresentation,
     filters,
     grid,
+    groups,
     layout,
     pagination,
     queryContent,

package/dist/runtime/table/composables/use-table-selection.d.ts

@@ -1,11 +1,13 @@
 import type { ComputedRef } from 'vue';
 import type { GenericObject, TableSchemaView } from '../types/index.js';
 import type { useTableData } from './use-table-data.js';
+import type { useTableGroups } from './use-table-groups.js';
 import type { useTableTree } from './use-table-tree.js';
 export interface UseTableSelectionParams {
     schema: ComputedRef<TableSchemaView>;
     queryContent: ReturnType<typeof useTableData>;
     tree: ReturnType<typeof useTableTree>;
+    groups: ReturnType<typeof useTableGroups>;
 }
 export declare function useTableSelection(options: UseTableSelectionParams): {
     allSelected: ComputedRef<boolean>;
@@ -15,6 +17,9 @@ export declare function useTableSelection(options: UseTableSelectionParams): {
         row: GenericObject;
         index?: number;
     }) => string;
+    getRowsSelectionState: (params: {
+        rowIds: string[];
+    }) => boolean | "indeterminate";
     isRowSelected: (params: {
         rowId: string;
     }) => boolean;

package/dist/runtime/table/composables/use-table-selection.js

@@ -61,6 +61,12 @@ export function useTableSelection(options) {
   function isRowSelected(params) {
     return selectedKeys.value.includes(params.rowId);
   }
+  function getRowsSelectionState(params) {
+    const selected = new Set(selectedKeys.value);
+    const count = params.rowIds.filter((rowId) => selected.has(rowId)).length;
+    if (count === 0) return false;
+    return count === params.rowIds.length ? true : "indeterminate";
+  }
   function selectRows(params) {
     if (!selectionEnabled.value) {
       return;
@@ -117,9 +123,12 @@ export function useTableSelection(options) {
     }
     lastTouchedRowId.value = params.rowId;
   }
-  const rangeRowIds = computed(
-    () => options.tree.enabled.value ? options.tree.visibleNodes.value.filter((node) => options.tree.isSelectable(node)).map((node) => node.id) : scopeRowIds.value
-  );
+  const rangeRowIds = computed(() => {
+    if (options.tree.enabled.value) {
+      return options.tree.visibleNodes.value.filter((node) => options.tree.isSelectable(node)).map((node) => node.id);
+    }
+    return options.groups.enabled.value ? options.groups.visibleRowIds.value : scopeRowIds.value;
+  });
   function getRangeRowIds(params) {
     const anchorIndex = rangeRowIds.value.indexOf(params.anchorRowId);
     const targetIndex = rangeRowIds.value.indexOf(params.targetRowId);
@@ -157,6 +166,7 @@ export function useTableSelection(options) {
     bulkScope,
     clearSelection,
     getRowId,
+    getRowsSelectionState,
     isRowSelected,
     lastTouchedRowId,
     partiallySelected,

package/dist/runtime/table/composables/use-table-tree.js

@@ -1,5 +1,12 @@
 import { usePreferredReducedMotion } from "@vueuse/core";
 import { computed, onScopeDispose, reactive, ref, shallowRef } from "vue";
+import {
+  ROW_CONCEAL_MS as CONCEAL_MS,
+  ROW_MOTION_LIMIT as MOTION_ROW_LIMIT,
+  ROW_REVEAL_MS as REVEAL_MS,
+  ROW_STAGGER_LIMIT as STAGGER_ROW_LIMIT,
+  ROW_STAGGER_MS as STAGGER_MS
+} from "../constants/row-motion.js";
 import { resolveTableRowId } from "../utils/rows.js";
 import {
   buildTableTree,
@@ -8,11 +15,6 @@ import {
   getVisibleDescendants,
   isOpenByDefault
 } from "../utils/tree.js";
-const CONCEAL_MS = 120;
-const REVEAL_MS = 190;
-const STAGGER_MS = 24;
-const MOTION_ROW_LIMIT = 24;
-const STAGGER_ROW_LIMIT = 8;
 const EMPTY_INDEX = {
   branches: [],
   byId: /* @__PURE__ */ new Map(),

package/dist/runtime/table/constants/row-motion.d.ts

@@ -0,0 +1,8 @@
+/** How long a closing branch or group plays out before its rows leave the list. */
+export declare const ROW_CONCEAL_MS = 120;
+/** How long the last revealed row takes to settle; the row's CSS owns the actual timing. */
+export declare const ROW_REVEAL_MS = 190;
+export declare const ROW_STAGGER_MS = 24;
+/** Rows beyond these start or stop without a transition: they are mostly off screen anyway. */
+export declare const ROW_MOTION_LIMIT = 24;
+export declare const ROW_STAGGER_LIMIT = 8;

package/dist/runtime/table/constants/row-motion.js

@@ -0,0 +1,5 @@
+export const ROW_CONCEAL_MS = 120;
+export const ROW_REVEAL_MS = 190;
+export const ROW_STAGGER_MS = 24;
+export const ROW_MOTION_LIMIT = 24;
+export const ROW_STAGGER_LIMIT = 8;

package/dist/runtime/table/types/groups.d.ts

@@ -0,0 +1,44 @@
+import type { GenericObject, RenderableType, TableKnownFieldPath } from './utils.js';
+/** What a group's `label`, `summary` and `collapsed` receive. */
+export interface TableGroupParams<TRow extends GenericObject = GenericObject> {
+    /** The value its rows share; `undefined` for rows that have none. */
+    value: unknown;
+    /** Its rows among those loaded, in display order. */
+    rows: TRow[];
+}
+/**
+ * Gathers rows that share a value under a header row that folds them.
+ *
+ * Groups exist only on screen: the data stays flat, so filters, pagination and bulk actions keep
+ * working on rows. They cover the rows that are loaded, so a remote source needs a page large
+ * enough to hold a whole group. A column sort applies inside each group.
+ *
+ * @example
+ * ```ts
+ * table: {
+ *   groupBy: {
+ *     key: 'country',
+ *     label: ({ value }) => countryName(value),
+ *   },
+ * }
+ * ```
+ */
+export interface TableGroupBySchema<TRow extends GenericObject = GenericObject> {
+    /** The row field to group on, or a function for a value the row does not hold as a field. */
+    key: TableKnownFieldPath<TRow> | ((row: TRow) => unknown);
+    /** The header's text. Defaults to the value, or the locale's "Other" for rows with none. */
+    label?: (params: TableGroupParams<TRow>) => RenderableType;
+    /** Shown next to the label. Defaults to the number of rows. */
+    summary?: (params: TableGroupParams<TRow>) => RenderableType;
+    /** Values listed here come first, in this order. The rest follow by value, empty ones last. */
+    order?: readonly unknown[];
+    /** Whether a group starts folded. A group the reader has toggled keeps that state. */
+    collapsed?: boolean | ((params: TableGroupParams<TRow>) => boolean);
+}
+/** One group of the loaded rows, resolved once per data change. */
+export interface TableGroup<TRow extends GenericObject = GenericObject> {
+    readonly key: string;
+    readonly value: unknown;
+    readonly rows: TRow[];
+    readonly rowIds: string[];
+}

package/dist/runtime/table/types/index.d.ts

@@ -3,6 +3,7 @@ export type * from './columns';
 export type * from './context';
 export type * from './data-list';
 export type * from './filters';
+export type * from './groups';
 export type * from './layout';
 export type * from './query-state';
 export type * from './remote-options';

package/dist/runtime/table/types/layout.d.ts

@@ -1,6 +1,7 @@
 import type { ButtonProps } from '@nuxt/ui/components/Button.vue';
 import type { LinkProps } from '@nuxt/ui/components/Link.vue';
 import type { TableColumnCollection, TableSummaryRequest, TableSummaryScope, TableSummaryValue } from './columns.js';
+import type { TableGroupBySchema } from './groups.js';
 import type { TableTreeSchema } from './tree.js';
 import type { GenericObject, TableDefaultSort, TableGridSortOption, TableLayout, TableRowRenderParams, RenderableType, TableSortKey, TableTextValue } from './utils.js';
 export interface TablePersistenceOptions {
@@ -75,12 +76,16 @@ export interface TableGridSchema<TRow extends GenericObject = GenericObject, TCo
     itemSize?: number | string | (() => number | string);
     sortOptions?: TableGridSortOption<TSortKey>[];
     defaultSorting?: TableDefaultSort<TSortKey>;
+    /** Gathers the cards that share a value under a header that folds them. See `TableGroupBySchema`. */
+    groupBy?: TableGroupBySchema<TRow>;
 }
 export interface TableTableSchema<TRow extends GenericObject = GenericObject, TContext extends GenericObject = GenericObject, TPageContext extends GenericObject = GenericObject, TSortKey extends string = TableSortKey<TRow>, TData = unknown> {
     enabled?: boolean | string | (() => boolean | string);
     columns?: TableColumnCollection<TRow, TContext, TPageContext, string, TSortKey, TData>;
     /** Lets rows hold child rows that open beneath them. See `TableTreeSchema`. */
     tree?: TableTreeSchema<TRow>;
+    /** Gathers rows that share a value under a header row that folds them. Ignored with `tree`. See `TableGroupBySchema`. */
+    groupBy?: TableGroupBySchema<TRow>;
     defaultSorting?: TableDefaultSort<TSortKey>;
     selection?: boolean | 'auto';
     summaries?: TableSummariesSchema<TRow>;

package/dist/runtime/table/utils/groups.d.ts

@@ -0,0 +1,14 @@
+import type { GenericObject, TableGroup, TableGroupBySchema } from '../types/index.js';
+/**
+ * Brings the rows sharing a value together. Rows keep their order inside a group, so the sort the
+ * source applied survives in each one.
+ */
+export declare function buildTableGroups<TRow extends GenericObject>(options: {
+    rows: TRow[];
+    groupBy: TableGroupBySchema<TRow>;
+    getRowId: (row: TRow, index: number) => string;
+}): TableGroup<TRow>[];
+export declare function tableGroupRow(group: TableGroup): GenericObject;
+export declare function tableGroupOf(row: GenericObject): TableGroup | undefined;
+export declare function tableGroupsStorageKey(tableKey: string): string;
+export declare function parseStoredGroupKeys(raw: string | null): string[];

package/dist/runtime/table/utils/groups.js

@@ -0,0 +1,55 @@
+import { getTableRowValue } from "./rows.js";
+const GROUP_ROW_KEY = "__nutTableGroup";
+function groupValueOf(row, groupBy) {
+  const { key } = groupBy;
+  const value = typeof key === "function" ? key(row) : getTableRowValue({ path: String(key), row });
+  return value === null || value === void 0 || value === "" ? void 0 : value;
+}
+function compareGroupValues(order, left, right) {
+  const leftRank = order.indexOf(left);
+  const rightRank = order.indexOf(right);
+  if (leftRank !== -1 && rightRank !== -1) return leftRank - rightRank;
+  if (leftRank !== -1) return -1;
+  if (rightRank !== -1) return 1;
+  if (left === void 0) return 1;
+  if (right === void 0) return -1;
+  return String(left).localeCompare(String(right), void 0, { numeric: true });
+}
+export function buildTableGroups(options) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const [index, row] of options.rows.entries()) {
+    const value = groupValueOf(row, options.groupBy);
+    const group = groups.get(value) ?? { rowIds: [], rows: [] };
+    group.rows.push(row);
+    group.rowIds.push(options.getRowId(row, index));
+    groups.set(value, group);
+  }
+  const order = options.groupBy.order ?? [];
+  return [...groups.entries()].sort(([left], [right]) => compareGroupValues(order, left, right)).map(([value, group]) => ({
+    key: `group:${JSON.stringify(value ?? null)}`,
+    rowIds: group.rowIds,
+    rows: group.rows,
+    value
+  }));
+}
+export function tableGroupRow(group) {
+  return { [GROUP_ROW_KEY]: group };
+}
+function isTableGroupRow(row) {
+  return GROUP_ROW_KEY in row;
+}
+export function tableGroupOf(row) {
+  return isTableGroupRow(row) ? row[GROUP_ROW_KEY] : void 0;
+}
+export function tableGroupsStorageKey(tableKey) {
+  return `nuxt-ui-tools:table-groups:${tableKey}`;
+}
+export function parseStoredGroupKeys(raw) {
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.filter((key) => typeof key === "string") : [];
+  } catch {
+    return [];
+  }
+}

package/dist/runtime/table/utils/index.d.ts

@@ -6,6 +6,7 @@ export * from './data-list-ui.js';
 export * from './facets.js';
 export * from './filter-persistence.js';
 export * from './filters/index.js';
+export * from './groups.js';
 export * from './pagination.js';
 export * from './prefetch.js';
 export * from './query-state.js';

package/dist/runtime/table/utils/index.js

@@ -6,6 +6,7 @@ export * from "./data-list-ui.js";
 export * from "./facets.js";
 export * from "./filter-persistence.js";
 export * from "./filters/index.js";
+export * from "./groups.js";
 export * from "./pagination.js";
 export * from "./prefetch.js";
 export * from "./query-state.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-ui-tools",
-  "version": "1.28.0",
+  "version": "1.29.0",
   "description": "Nuxt module and runtime toolkit for UI-heavy Nuxt applications",
   "homepage": "https://github.com/ChronicStone/nuxt-ui-tools#readme",
   "bugs": "https://github.com/ChronicStone/nuxt-ui-tools/issues",