From fa940031fdf5b031b717396b0ff77f8280bafede Mon Sep 17 00:00:00 2001 From: Jose Antonio Alatorre Date: Sat, 14 Nov 2026 14:56:16 +0100 Subject: [PATCH 1/2] feat(sdk): group resource rows without changing bulk selection Co-authored-by: Codex --- command-center-sdk/CHANGELOG.md | 12 +++ command-center-sdk/README.md | 4 + .../skills/views/build-resource-list/SKILL.md | 7 ++ command-center-sdk/docs/resources.md | 25 ++++++ command-center-sdk/package.json | 2 +- command-center-sdk/src/localization/index.ts | 1 + command-center-sdk/src/views/DataTable.tsx | 72 +++++++++++++++-- command-center-sdk/src/views/README.md | 9 +++ .../ResourceListPage.grouping.client.test.tsx | 77 +++++++++++++++++++ .../src/views/ResourceListPage.tsx | 5 ++ command-center-sdk/styles.css | 14 ++++ .../sdk-consumer-fixture/src/consumer.tsx | 8 ++ package-lock.json | 6 +- package.json | 2 +- 14 files changed, 233 insertions(+), 11 deletions(-) create mode 100644 command-center-sdk/src/views/ResourceListPage.grouping.client.test.tsx diff --git a/command-center-sdk/CHANGELOG.md b/command-center-sdk/CHANGELOG.md index 50a29728..a9ffee2a 100644 --- a/command-center-sdk/CHANGELOG.md +++ b/command-center-sdk/CHANGELOG.md @@ -1,5 +1,17 @@ # Changelog +## 0.5.20 + +Compatibility axes: additive React `DataTableRowGrouping` and `rowGrouping` props through +`/views`, plus `selectAllPageRows` localization text. No contract ID, wire payload, schema, +fixture, iframe protocol, theme token, or persisted storage change; no backend rollout required. + +- Group current-page resource rows with accessible collapsible headers in table and phone forms. +- Keep collapsed rows in page-wide selection and preserve explicit/all-matching discovery, + preflight, confirmation, execution, refresh and selection cleanup. +- Document page-scoped labels and the consumer/SDK ownership boundary in the resource guide, + view README, packaged list skill, and packed consumer example. + ## 0.5.19 - Add optional validated locale to v1 iframe initialization and live context. Older diff --git a/command-center-sdk/README.md b/command-center-sdk/README.md index 630e572c..0e07cedf 100644 --- a/command-center-sdk/README.md +++ b/command-center-sdk/README.md @@ -1,5 +1,9 @@ # Command Center SDK +Resource lists can group their current page with `rowGrouping` on `ResourceListPage` from +`@dev-mainsequence/command-center-sdk/views`. Collapsing a group preserves row selection and the +existing bulk-action lifecycle. See [grouping resource rows](docs/resources.md#group-rows-without-changing-selection). + `@dev-mainsequence/command-center-sdk` is the public TypeScript/React package for building Command Center-compatible navigation, responsive application layouts, application feedback, application controls, resource applications, themes, backend contracts, and static-site iframe integrations. diff --git a/command-center-sdk/agent_scaffold/skills/views/build-resource-list/SKILL.md b/command-center-sdk/agent_scaffold/skills/views/build-resource-list/SKILL.md index 4d894157..6fe233f3 100644 --- a/command-center-sdk/agent_scaffold/skills/views/build-resource-list/SKILL.md +++ b/command-center-sdk/agent_scaffold/skills/views/build-resource-list/SKILL.md @@ -52,6 +52,13 @@ The collection operation remains authoritative for rows and pagination. ## Do Not Rebuild Owned Behavior +For collapsible categories, pass `rowGrouping` with `getGroupId(item)` and +`renderGroupLabel(groupId, items)` to the same `ResourceListPage`. This groups only the supplied +page; labels must say when their count is page-scoped. Collapsing is presentation, not filtering: +select-all still includes collapsed rows, and the existing explicit/all-matching bulk lifecycle +is unchanged. Do not split groups into independent list instances or build parallel selection. +Group state is memory-only; `renderCard` takes precedence over grouping. + Do not create a parallel page header, toolbar, search row, result counter, selection bar, action button strip, pagination footer, confirmation flow, or custom collection loading state. Do not use a native select or bespoke dropdown for SDK-owned list filters. diff --git a/command-center-sdk/docs/resources.md b/command-center-sdk/docs/resources.md index 2dac426b..6b39bf21 100644 --- a/command-center-sdk/docs/resources.md +++ b/command-center-sdk/docs/resources.md @@ -228,6 +228,31 @@ pagination becomes previous, page summary, next. Row actions collapse into a men more than two or the pointer is coarse. Pass `"table"` or `"stacked"` to fix the form. See [Mobile and touch](./concepts/mobile.md). +### Group rows without changing selection + +Use the public `rowGrouping` contribution on `ResourceListPage` when an existing paginated list +needs collapsible categories. The same `DataTableRowGrouping` type works with `DataTable`. + +```tsx +import { ResourceListPage, type DataTableRowGrouping } from "@dev-mainsequence/command-center-sdk/views"; + +const organizationGroups: DataTableRowGrouping = { + getGroupId: (service) => service.organization, + renderGroupLabel: (organization, rows) => `${organization} · ${rows.length} on this page`, +}; + +; +``` + +The consumer supplies group identity and label; the SDK renders accessible disclosure buttons in +both table and phone forms. Rows are grouped by first occurrence and keep their relative order. +Only current-page rows reach the label renderer. For complete organization totals, the backend +must provide them; do not infer them from a page. A collapse is not a filter: **Select all rows on +this page** includes collapsed groups. Explicit selected UIDs and all-matching queries continue +through the same discovery, preflight, confirmation, execution, and refresh flow. Group expansion +is transient and does not change backend queries, pagination or persisted storage. Empty and +failed collections keep their standard states. `renderCard` takes precedence over grouping. + ## Build a resource detail Keep the selected UID, query, and tab ids in the host, in the URL when they must survive a reload. diff --git a/command-center-sdk/package.json b/command-center-sdk/package.json index ec555f21..9347cccc 100644 --- a/command-center-sdk/package.json +++ b/command-center-sdk/package.json @@ -1,6 +1,6 @@ { "name": "@dev-mainsequence/command-center-sdk", - "version": "0.5.19", + "version": "0.5.20", "private": false, "description": "The framework-neutral SDK for building Command Center-compatible resource applications, navigation, layouts, themes, feedback, and embeds.", "type": "module", diff --git a/command-center-sdk/src/localization/index.ts b/command-center-sdk/src/localization/index.ts index 855e00c6..cf4cf671 100644 --- a/command-center-sdk/src/localization/index.ts +++ b/command-center-sdk/src/localization/index.ts @@ -92,6 +92,7 @@ export const sdkEnglishMessages = { "selectAllMatching": "Select all {{count}} matching {{itemLabel}}", "selectRow": "Select row", "selectAllRows": "Select all visible rows", + "selectAllPageRows": "Select all rows on this page", "loadingActions": "Loading actions", "loadingItems": "Loading {{itemLabel}}…", "emptyItems": "No {{itemLabel}} yet.", diff --git a/command-center-sdk/src/views/DataTable.tsx b/command-center-sdk/src/views/DataTable.tsx index a741935a..7ce047d7 100644 --- a/command-center-sdk/src/views/DataTable.tsx +++ b/command-center-sdk/src/views/DataTable.tsx @@ -1,5 +1,7 @@ import { useSdkTranslation } from "../localization/react.js"; -import type { KeyboardEvent, ReactNode } from "react"; +import { useState, type KeyboardEvent, type ReactNode } from "react"; +import { ChevronDown, ChevronRight } from "lucide-react"; +import { Button } from "../controls/index.js"; import { useCommandCenterViewport, type CommandCenterViewportState } from "../layout/viewport.js"; import { @@ -33,6 +35,13 @@ export interface ResourceRowAction { export type DataTablePresentation = "auto" | "stacked" | "table"; export type ResolvedDataTablePresentation = Exclude; +/** Presentation-only grouping of the supplied page; never narrows selection or the query. */ +export interface DataTableRowGrouping { + getGroupId: (item: T) => string; + /** Receives only current-page rows, never an inferred collection total. */ + renderGroupLabel: (groupId: string, items: readonly T[]) => ReactNode; +} + export interface DataTableProps { columns: readonly ResourceColumnDefinition[]; emptyContent?: ReactNode; @@ -40,6 +49,7 @@ export interface DataTableProps { isSelected?: (id: Id) => boolean; isRowSelectable?: (item: T) => boolean; items: readonly T[]; + rowGrouping?: DataTableRowGrouping; /** Label of the per-row overflow menu. */ rowActionsLabel?: string; rowActions?: readonly ResourceRowAction[]; @@ -136,6 +146,7 @@ export function DataTable({ isSelected, isRowSelectable, items, + rowGrouping, moreDetailsLabel: moreDetailsLabelProp, onActivateRow, onSortChange, @@ -152,12 +163,47 @@ export function DataTable({ const emptyContent = emptyContentProp ?? t("noTableResults"); const moreDetailsLabel = moreDetailsLabelProp ?? t("moreDetails"); const rowActionsLabel = rowActionsLabelProp ?? t("actions"); - const selectionLabel = selectionLabelProp ?? t("selectAllRows"); + const selectionLabel = selectionLabelProp ?? t(rowGrouping ? "selectAllPageRows" : "selectAllRows"); const viewport = useCommandCenterViewport(); const resolvedPresentation = resolveDataTablePresentation(presentation, viewport); const selectable = Boolean(isSelected && onToggleAll && onToggleSelection); const resolvedColumns = resolveResourceColumnImportance(columns); + const [collapsedGroups, setCollapsedGroups] = useState>(() => new Set()); + type Entry = { kind: "row"; item: T } | { kind: "group"; id: string; items: readonly T[] }; + const entries: Entry[] = []; + if (rowGrouping) { + const groups = new Map(); + for (const item of items) { + const id = rowGrouping.getGroupId(item); + const group = groups.get(id) ?? []; + group.push(item); + groups.set(id, group); + } + for (const [id, groupItems] of groups) { + entries.push({ kind: "group", id, items: groupItems }); + if (!collapsedGroups.has(id)) entries.push(...groupItems.map((item) => ({ kind: "row" as const, item }))); + } + } else { + entries.push(...items.map((item) => ({ kind: "row" as const, item }))); + } + const renderGroupToggle = (entry: Extract) => ( + + ); const activateFromKeyboard = (event: KeyboardEvent, item: T) => { if (!onActivateRow || (event.key !== "Enter" && event.key !== " ")) { @@ -206,12 +252,18 @@ export function DataTable({
{emptyContent}
) : (
    - {items.map((item) => { + {entries.map((entry) => { + if (entry.kind === "group") return ( +
  1. + {renderGroupToggle(entry)} +
  2. + ); + const item = entry.item; const id = getId(item); const rowSelectable = isRowSelectable ? isRowSelectable(item) : true; return (
  3. ({ ) : ( - items.map((item) => { + entries.map((entry) => { + if (entry.kind === "group") return ( + + + {renderGroupToggle(entry)} + + + ); + const item = entry.item; const id = getId(item); const rowSelectable = isRowSelectable ? isRowSelectable(item) : true; return ( = { + getGroupId: (row) => row.organization, + renderGroupLabel: (id, rows) => `${id} (${rows.length})`, +}; +const action: ResourceBulkActionDefinition = { + id: "review", label: "Review", endpoint: "/rows/review/", method: "POST", + selection_modes: ["explicit", "all_matching"], options: [], + preflight_endpoint: "/rows/review/preflight/", + confirmation: { title: "Review rows", button_label: "Review" }, +}; +const page = { items, pageInfo: { pageIndex: 0, pageSize: 2, totalItems: 12, hasNextPage: true, hasPreviousPage: false } }; +const roots: ReturnType[] = []; +afterEach(() => { + roots.splice(0).forEach((root) => act(() => root.unmount())); + document.body.innerHTML = ""; +}); +function button(text: string) { + const found = [...document.body.querySelectorAll('button')].find((node) => node.textContent === text); + expect(found, text).toBeDefined(); + return found!; +} + +describe.each(["table", "stacked"])("grouped %s resource list", (presentation) => { + it.each([false, true])("preserves collapsed rows through select-all, preflight and execution (all matching: %s)", async (allMatching) => { + const executeBulkAction = vi.fn().mockResolvedValue([]); + const preflightBulkAction = vi.fn().mockResolvedValue({ allowed: true, impacts: [], items: [], matchedCount: allMatching ? 12 : 2, raw: {} }); + const definition: ResourceApplicationDefinition = { + id: "rows", label: "Rows", itemLabel: "rows", getId: (row) => row.uid, + columns: [{ id: "name", header: "Name", getValue: (row) => row.name }], + adapter: { list: vi.fn().mockResolvedValue(page), listBulkActions: vi.fn().mockResolvedValue([action]), preflightBulkAction, executeBulkAction }, + }; + const container = document.createElement("div"); document.body.append(container); + const root = createRoot(container); roots.push(root); + await act(async () => root.render( +
    + {input.selectedItems.map((row) => row.uid).join(",")} + +
    } + />, + )); + await act(async () => button("Organization A (1)").click()); + expect(button("Organization A (1)").getAttribute("aria-expanded")).toBe("false"); + expect(container.querySelectorAll('[data-cc-data-table-row]')).toHaveLength(1); + const selectAll = container.querySelector('input[aria-label="Select all rows on this page"]')!; + await act(async () => selectAll.click()); + expect(container.textContent).toContain("2 selected on this page."); + // Reopening proves the SDK selected a row whose checkbox was not mounted. + await act(async () => button("Organization A (1)").click()); + expect([...container.querySelectorAll('input[type="checkbox"]')].every((input) => input.checked)).toBe(true); + await act(async () => button("Organization A (1)").click()); + if (allMatching) await act(async () => button("Select all 12 matching rows").click()); + await act(async () => button("Actions").click()); + await act(async () => button("Review").click()); + const selection = allMatching ? { mode: "all_matching", query: { search: "", filters: {} } } + : { mode: "explicit", uids: ["a", "b"] }; + expect(preflightBulkAction).toHaveBeenCalledWith(action, expect.objectContaining({ selection })); + if (!allMatching) expect(container.querySelector('[data-selected-items]')?.textContent).toBe("a,b"); + await act(async () => button("Confirm test operation").click()); + expect(executeBulkAction).toHaveBeenCalledWith(action, expect.objectContaining({ selection })); + expect(container.textContent).not.toContain("selected on this page"); + }); +}); diff --git a/command-center-sdk/src/views/ResourceListPage.tsx b/command-center-sdk/src/views/ResourceListPage.tsx index 77735af9..4018051f 100644 --- a/command-center-sdk/src/views/ResourceListPage.tsx +++ b/command-center-sdk/src/views/ResourceListPage.tsx @@ -37,6 +37,7 @@ import { DataTable, resolveDataTablePresentation, type DataTablePresentation, + type DataTableRowGrouping, type ResourceRowAction, } from "./DataTable.js"; import { ResourceCardGrid } from "./ResourceCardGrid.js"; @@ -107,6 +108,8 @@ export interface ResourceListPageProps { searchable?: boolean; /** Table form; `auto` stacks rows below the `sm` breakpoint. Ignored when `renderCard` is set. */ tablePresentation?: DataTablePresentation; + /** Group current-page rows visually; select-all and bulk actions include collapsed rows. */ + rowGrouping?: DataTableRowGrouping; toolbarLeading?: ReactNode; toolbarTrailing?: ReactNode; onBulkActionSuccess?: (action: ResourceBulkActionDefinition, response: unknown) => void; @@ -199,6 +202,7 @@ export function ResourceListPage({ refreshKey, renderBulkActionConfirmation, renderCard, + rowGrouping, rowActions = [], searchPlaceholder, searchable = true, @@ -946,6 +950,7 @@ export function ResourceListPage({ renderCard={renderCard} /> ) : td { + padding: 0; +} + +.cc-data-table__group-toggle { + width: 100%; + justify-content: flex-start; + text-align: start; +} + +.cc-data-table__group { + list-style: none; +} + .cc-resource-card-grid { display: grid; gap: 1rem; diff --git a/examples/sdk-consumer-fixture/src/consumer.tsx b/examples/sdk-consumer-fixture/src/consumer.tsx index 83422e5e..f77d5479 100644 --- a/examples/sdk-consumer-fixture/src/consumer.tsx +++ b/examples/sdk-consumer-fixture/src/consumer.tsx @@ -48,6 +48,8 @@ import { getThemeCategoricalPalette } from "@dev-mainsequence/command-center-sdk import { graphiteTheme } from "@dev-mainsequence/command-center-sdk/theme/presets"; import { ResourceDetailShell, + ResourceListPage, + type DataTableRowGrouping, ResourcePagination, ResourceTransferList, type ResourceDetailBreadcrumbLeadContext, @@ -299,6 +301,7 @@ export const packedStaticSiteHostHtml = renderToStaticMarkup( ); export const packedSdkSurfaceSmoke = { + ResourceListPage, ApplicationCard, ApplicationCardGrid, ActivityIndicator, @@ -318,3 +321,8 @@ export const packedSdkSurfaceSmoke = { mainSequenceTheme, verifyCommandCenterPageLayout, } satisfies Record; + +export const packedRowGrouping: DataTableRowGrouping<{ organization: string }> = { + getGroupId: (item) => item.organization, + renderGroupLabel: (organization, items) => `${organization} · ${items.length} on this page`, +}; diff --git a/package-lock.json b/package-lock.json index 196956d9..238e8357 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "command-center-sdk-repository", - "version": "0.5.19", + "version": "0.5.20", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "command-center-sdk-repository", - "version": "0.5.19", + "version": "0.5.20", "workspaces": [ "command-center-sdk", "command-center-ai" @@ -54,7 +54,7 @@ }, "command-center-sdk": { "name": "@dev-mainsequence/command-center-sdk", - "version": "0.5.19", + "version": "0.5.20", "hasInstallScript": true, "license": "Apache-2.0", "dependencies": { diff --git a/package.json b/package.json index 700f6304..d6c94bc6 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "command-center-sdk-repository", "private": true, - "version": "0.5.19", + "version": "0.5.20", "type": "module", "workspaces": [ "command-center-sdk", From f17a94f16b3bacc857864ccd62b8782cf0bfb286 Mon Sep 17 00:00:00 2001 From: Jose Antonio Alatorre Date: Sat, 14 Nov 2026 15:03:08 +0100 Subject: [PATCH 2/2] fix(sdk): keep grouped mobile toolbars compact Co-authored-by: Codex --- command-center-sdk/CHANGELOG.md | 1 + command-center-sdk/styles.css | 6 +++++- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/command-center-sdk/CHANGELOG.md b/command-center-sdk/CHANGELOG.md index a9ffee2a..02f43ba7 100644 --- a/command-center-sdk/CHANGELOG.md +++ b/command-center-sdk/CHANGELOG.md @@ -7,6 +7,7 @@ Compatibility axes: additive React `DataTableRowGrouping` and `rowGrouping` p fixture, iframe protocol, theme token, or persisted storage change; no backend rollout required. - Group current-page resource rows with accessible collapsible headers in table and phone forms. +- Keep a stacked mobile toolbar's search field at its natural height rather than its desktop flex basis. - Keep collapsed rows in page-wide selection and preserve explicit/all-matching discovery, preflight, confirmation, execution, refresh and selection cleanup. - Document page-scoped labels and the consumer/SDK ownership boundary in the resource guide, diff --git a/command-center-sdk/styles.css b/command-center-sdk/styles.css index 2418e5be..be301892 100644 --- a/command-center-sdk/styles.css +++ b/command-center-sdk/styles.css @@ -1249,7 +1249,7 @@ h3), overflow: hidden; } -.cc-data-table__group > td { +.cc-data-table .cc-data-table__group > td { padding: 0; } @@ -2878,6 +2878,10 @@ h3), flex-direction: column; } + .cc-resource-toolbar__search { + flex-basis: auto; + } + .cc-resource-search { align-items: stretch; flex-direction: column;