@gravitee/graphene-core 3.25.0 → 3.26.0

package/USAGE_GUIDE.md

@@ -482,7 +482,7 @@ Follow these steps to apply the layout width system to an existing consumer modu
 4. **Remove ad-hoc width constraints** — delete any `max-w-*` classes on page-level wrapper divs. The design system owns content width.
 5. **Verify** — resize the browser to confirm content stays centered without clipping on narrow viewports.
 
-See `node_modules/@gravitee/graphene-core/snippets/data-table-list-page.tsx` and `creation-wizard-page.tsx` for complete examples.
+See the folder `node_modules/@gravitee/graphene-core/snippets/list-page/` and `creation-wizard-page.tsx` for complete examples.
 
 ### Page header
 
@@ -606,7 +606,7 @@ export function ApisPage() {
 
 Use `DataTable` for any entity list — whether the data is fetched page-by-page from an API or loaded in full on the client. The component provides sorting, filtering, pagination, column visibility, row selection, and bulk actions through a composable slot API.
 
-**To implement:** copy the snippet from `node_modules/@gravitee/graphene-core/snippets/data-table-list-page.tsx` and replace the entity type, column definitions, and fetch function with your data. See Storybook **Patterns/Data Table → ApiList** for the full interactive example.
+**To implement:** copy the folder `node_modules/@gravitee/graphene-core/snippets/list-page/` into your module, rename `Entity` and `entities` after your resource, and point `useEntityList.ts` at your API client instead of the sample `entities.service.ts`. Its `snippet.json` lists the packages it needs beyond Graphene's peers (`@tanstack/react-query`, `react-router-dom`). See Storybook **Patterns/List Page** for the page in its five states.
 
 #### When to use DataTable vs raw Table
 
@@ -656,11 +656,12 @@ Use `DataTable` for any entity list — whether the data is fetched page-by-page
 
 #### Search and filters
 
-- Search and filters live in the DataTable `toolbar` slot.
-- Search: `SearchField` in the toolbar with `className="w-64"`; it debounces 300 ms and reports the settled query, reset the page to 1 in `onValueChange`.
-- **Do NOT add a search field to a server-paginated table unless the backend endpoint supports a text search parameter** (`query`, `q`, or equivalent). Client-side search on a single page of server-paginated data is misleading — users will miss matches on other pages. If the backend does not support search, either request the backend change or omit the search field entirely.
-- Use `FacetedFilter` for multi-select categorical filters.
-- Show a "Reset" button when any filter is active.
+- Search and filters live in the DataTable `toolbar` slot, inside `<div className="flex min-w-0 flex-wrap items-center gap-2">`: DataTable's own toolbar row does not wrap, this container does. Group the filters and Reset in a nested `flex flex-wrap items-center gap-2` so that they wrap together.
+- Search: `SearchField` first, with an `aria-label` that says what is searched, a placeholder, and `className="w-64"`. It debounces 300 ms and reports the settled query: reset the page to 1 in `onValueChange`.
+- **Do NOT add a search field to a server-paginated table unless the backend endpoint supports a text search parameter** (`query`, `q`, or equivalent). Client-side search on a single page of server-paginated data is misleading: users will miss matches on other pages. If the backend does not support search, either request the backend change or omit the search field entirely.
+- Single-choice filter: a `Select` whose default option is "All ..." ("All statuses"), named by a `Label` in `sr-only`, with a minimum width (`min-w-32`) so that it does not jump as its value changes.
+- Multiple-choice filter: a `FacetedFilter`.
+- Reset: a `Button variant="ghost" size="sm"`, rendered only while a criterion is active. It clears every criterion and the page, then moves the focus to the search field (pass a `ref` to `SearchField`).
 
 #### Row navigation
 
@@ -675,6 +676,9 @@ Use **name-column-as-link**: the primary identifier column (always leftmost) is
 - **Quick-action escape hatch:** one high-discoverability action (e.g. "Deploy") may appear as an inline icon *alongside* the dropdown, but the dropdown must still exist.
 - Use `MoreVerticalIcon` (⋮) for table rows. Do not use `MoreHorizontalIcon` — the horizontal variant is for toolbars and card headers.
 - Destructive actions go last in the menu, after a `DropdownMenuSeparator`.
+- Name the ⋮ button after its row: ``aria-label={`Actions for ${entity.name}`}``.
+- A destructive action asks for confirmation in a `Dialog` before it runs, then reports the outcome in a toast (`toast` from `@gravitee/graphene-core`, shown by the app's `Toaster`). When the dialog closes, give the focus back to the ⋮ if the user cancelled. Once the entity is deleted, its row and ⋮ go: move the focus to the search field, as Reset does. See `EntityActionsMenu.tsx` and `DeleteEntityDialog.tsx` in the list page snippet.
+- Key the rows by entity (`tableOptions={{ getRowId: (entity) => entity.id }}`), so that a removed row never hands its focused ⋮ to the next entity. Not with `selectionMode="multi"` for now: `onSelectionChange` still maps the selection by row index.
 
 #### Column ordering
 
@@ -688,7 +692,9 @@ Use **name-column-as-link**: the primary identifier column (always leftmost) is
 
 **Minimum 3 data columns** (excluding actions). If an entity has fewer than 3 meaningful attributes, use a simpler component (Item list, card grid) instead of DataTable.
 
-Target **4-7 visible columns**. More than 7 → enable column visibility and hide low-priority columns by default. Do NOT show raw entity IDs as visible columns.
+Target **4-7 visible columns**. List pages show the View menu (`enableColumnVisibility`), with the name and the actions always visible (`enableHiding: false`); more than 7 → hide the low-priority columns by default. Do NOT show raw entity IDs as visible columns.
+
+`enableColumnVisibility` adds the View menu, which names each column by its `meta.label`, else by its header when that is text: give a column whose header is a component, such as a sortable `DataTableColumnHeader`, a `meta: { label: 'Created' }`, or the menu shows its id.
 
 #### Cell renderers
 
@@ -704,56 +710,59 @@ Import from `@gravitee/graphene-core`:
 
 #### Empty states
 
-Use `DataTableEmptyState` — it enforces the correct structure for both scenarios:
+Use `DataTableEmptyState` for both cases, and decide only once the query has settled: never conclude "empty" from the previous page kept while the next one loads (`isPlaceholderData`).
 
-**`variant="first-use"`** — collection is genuinely empty (user has never created entities)
-- Render **instead of** `DataTable` (no table chrome needed)
-- Wrap in `<div className="rounded-lg border">` for containment
-- Props: `icon`, `title`, `description`, `primaryAction`, optional `secondaryAction`, optional `children` for educational content (flow diagrams, feature pillars)
-- Decision: `totalCount === 0 && !hasActiveFilters`
+**`variant="first-use"`**: the collection is empty and no criterion is active.
+- Render it **instead of** `DataTable`, wrapped in `<div className="rounded-lg border">`.
+- In a list page: an icon, a title, one sentence, and **no button**. The header's Add button is the one creation CTA (see below).
+- `primaryAction`, `secondaryAction` and `children` exist for other surfaces, such as an educational first-use landing.
+- Decision: `totalCount === 0 && !hasCriteria`.
 
-**`variant="no-results"`** — active filters/search returned zero matches
-- Render **inside** `DataTable` as the `emptyMessage` prop (keep toolbar visible)
-- Props: `icon` (use `SearchIcon`), `title`, `description`, `action` (e.g. "Clear filters")
-- Decision: `filteredCount === 0 && hasActiveFilters`
+**`variant="no-results"`**: a search or a filter matched nothing.
+- Render it **inside** `DataTable` as `emptyMessage`, so the toolbar stays.
+- `icon={<SearchIcon />}`, a title ("No APIs found"), one sentence inviting to adjust the search or the filters, and **no button**: the search field's clear button and the toolbar's Reset clear the criteria.
+- Its `action` slot exists for the rare table without a Reset in its toolbar.
+- Decision: `totalCount === 0 && hasCriteria`.
 
 ```tsx
-// Page-level decision pattern
+// Page-level decision, once the query has settled
 {isFirstUse ? (
   <div className="rounded-lg border">
-    <DataTableEmptyState variant="first-use" icon={<GlobeIcon />} title="No APIs yet" ... />
+    <DataTableEmptyState variant="first-use" icon={<GlobeIcon />} title="No APIs yet" description="..." />
   </div>
 ) : (
   <DataTable
-    emptyMessage={<DataTableEmptyState variant="no-results" icon={<SearchIcon />} ... />}
+    emptyMessage={<DataTableEmptyState variant="no-results" icon={<SearchIcon />} title="No APIs found" description="..." />}
     ...
   />
 )}
 ```
 
-See Storybook **Composed/DataTableEmptyState → Integration** for the full interactive example.
+See Storybook **Patterns/List Page** (states `empty` and `no-results`) for the full interactive example.
 
 #### Header button coordination
 
-Pages with a primary "Add Entity" button in the header follow one rule: **the header button only appears when data exists**. During first-use, the empty state owns the primary CTA.
+The Add button stays in the header in every state: one creation CTA on screen.
 
-| State | Header button | Content area |
+| State | Header | Content area |
 |---|---|---|
-| **First-use** (`totalCount === 0 && !hasFilters`) | Hidden | `DataTableEmptyState variant="first-use"` with primary CTA |
-| **Has data** (`totalCount > 0`) | Primary `+ Add Entity` | DataTable |
-| **No results** (filters active, zero matches) | Primary `+ Add Entity` | `DataTableEmptyState variant="no-results"` with "Clear filters" |
+| **First use** (`totalCount === 0`, no criterion) | Add | `DataTableEmptyState variant="first-use"` instead of the table, without a button |
+| **Data** (`totalCount > 0`) | Add | `DataTable` |
+| **No results** (a criterion active, zero matches) | Add | `DataTable` with `DataTableEmptyState variant="no-results"` inside, without a button |
 
-Both the header button and the empty state CTA trigger the same creation flow. No visual downgrade (both are primary variant buttons). No transition animation between states.
+Gate the button on the permission, never on the list's state:
 
 ```tsx
 <PageHeader
-  title="Entities"
-  description="Manage your entity catalog."
+  title="APIs"
+  description="Design, deploy and secure the APIs your gateways expose to consumers."
   actions={
-    !isFirstUse && (
-      <Button size="sm">
-        <PlusIcon />
-        Add entity
+    canCreate && (
+      <Button asChild>
+        <Link to="new">
+          <PlusIcon />
+          Add API
+        </Link>
       </Button>
     )
   }
@@ -762,9 +771,26 @@ Both the header button and the empty state CTA trigger the same creation flow. N
 
 #### Loading state
 
+- Fetch with TanStack Query and `placeholderData: keepPreviousData`, and pass `loading={isFetching}`: the first load shows skeleton rows, and later fetches keep the rows under DataTable's overlay. There is no code to write for either.
 - Pass `skeletonCount={pageSize}` to prevent layout shift.
 - `loadingDelay={200}` (default) prevents flash on fast responses.
 
+#### Error state
+
+- A destructive `Alert` above the table: a short title ("Could not load APIs") and a Retry button that calls `refetch()`, disabled while it runs.
+- Keep the last loaded page on screen under the alert, with the toolbar and the pagination, and say that it may be out of date. `keepPreviousData` holds the previous page only while the next one loads, so keep the last successful response in your list hook: the search field must never disappear while the user types.
+- When nothing has loaded yet, the alert alone, with the error message.
+
+#### List state in the URL
+
+Keep the list state in the URL with `useSearchParams` (react-router-dom), so that a reload, a shared link and the Back button restore it:
+
+- Keys: `q` for the search, one key per filter (`status`), repeated for a multiple choice (`type=internal&type=partner`), `page`, `size`, and `sort` as `field:asc` or `field:desc`.
+- Defaults are not written, and every value is read with a fallback: an unknown status, size or sort gives the default.
+- A new criterion (search, filter, sort) deletes `page` and replaces the history entry; changing the page or its size adds one.
+- Give the search back to `SearchField` exactly as it reported it, and trim it where it is used (the request).
+- A page past the last one (its last row deleted, an old link) goes to the last page.
+
 #### `serverSide` prop
 
 Set `serverSide` when data is fetched page-by-page from an API. It disables TanStack's built-in sort/filter/pagination models so you control everything via your fetch logic.

package/dist/composed/DataTable/DataTable.d.ts

@@ -1,5 +1,14 @@
-import { ColumnDef, OnChangeFn, SortingState, TableOptions } from '@tanstack/react-table';
+import { ColumnDef, OnChangeFn, RowData, SortingState, TableOptions } from '@tanstack/react-table';
 import { ReactNode } from 'react';
+declare module '@tanstack/react-table' {
+    interface ColumnMeta<TData extends RowData, TValue> {
+        /**
+         * The column's name in the View menu (`enableColumnVisibility`), for a header that is not text,
+         * such as a sortable `DataTableColumnHeader`. Without it, the menu shows the column id.
+         */
+        label?: string;
+    }
+}
 interface DataTablePaginationConfig {
     readonly page: number;
     readonly pageSize: number;
@@ -21,6 +30,10 @@ interface DataTableProps<TData> {
     /** Called when the user clicks a sortable column header. Use to trigger a server re-fetch with the new sort params. */
     readonly onSortingChange?: OnChangeFn<SortingState>;
     readonly emptyMessage?: ReactNode;
+    /**
+     * Adds the View menu, which shows and hides the columns whose `enableHiding` is not false. It names a
+     * column by its `meta.label`, else by its header when that is text, else by its id.
+     */
     readonly enableColumnVisibility?: boolean;
     readonly enableColumnResizing?: boolean;
     /** Makes the table header sticky. Consumer should set a max-height via className. */

package/dist/composed/DataTable/DataTable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DataTable.d.ts","sourceRoot":"","sources":["../../../src/composed/DataTable/DataTable.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"DataTable.d.ts","sourceRoot":"","sources":["../../../src/composed/DataTable/DataTable.tsx"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -26965,7 +26965,7 @@ function uK({ table: e }) {
 				checked: e.getIsVisible(),
 				onCheckedChange: (t) => e.toggleVisibility(!!t),
 				className: "text-sm",
-				children: typeof e.columnDef.header == "string" ? e.columnDef.header : e.id
+				children: e.columnDef.meta?.label ?? (typeof e.columnDef.header == "string" ? e.columnDef.header : e.id)
 			}, e.id))
 		]
 	})] });