@gravitee/graphene-core 3.25.0 → 3.26.0

package/snippets/list-page/useEntityList.ts

@@ -0,0 +1,142 @@
+// The entity list's data and state: the only file that calls the entities service.
+//
+// The list state lives in the URL, so a reload, a shared link and the Back button restore it: `q`,
+// `status`, `type` (repeated for several types), `page`, `size` and `sort` (`name:asc`, `createdAt:desc`).
+// Defaults are not written. A new criterion (search, filter, sort) returns to page 1 and replaces the
+// history entry; changing the page or its size adds one.
+
+import { keepPreviousData, useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import type { OnChangeFn, SortingState } from '@tanstack/react-table';
+import { useEffect, useState } from 'react';
+import { useSearchParams } from 'react-router-dom';
+import {
+  deleteEntity,
+  ENTITY_STATUSES,
+  ENTITY_TYPES,
+  type EntityPage,
+  type EntitySort,
+  type EntityType,
+  listEntities,
+  type ListEntitiesParams,
+} from './entities.service';
+
+export const PAGE_SIZE_OPTIONS = [10, 25, 50, 100];
+const DEFAULT_PAGE_SIZE = 10;
+// Your API's default order: the table header shows it, and the URL leaves it out.
+const DEFAULT_SORT: EntitySort = 'createdAt:desc';
+const SORT_PATTERN = /^(name|createdAt):(asc|desc)$/;
+
+type ListParamKey = 'q' | 'status' | 'type' | 'page' | 'size' | 'sort';
+
+/** The list state the URL holds. `q` is the search as typed: the field gets it back unchanged. */
+export function readListState(searchParams: URLSearchParams) {
+  const status = searchParams.get('status');
+  const types = searchParams.getAll('type');
+  const page = Number(searchParams.get('page'));
+  const size = Number(searchParams.get('size'));
+  const sort = searchParams.get('sort');
+  return {
+    q: searchParams.get('q') ?? '',
+    status: ENTITY_STATUSES.find((value) => value === status),
+    type: ENTITY_TYPES.filter((value) => types.includes(value)),
+    page: Number.isInteger(page) && page > 1 ? page : 1,
+    size: PAGE_SIZE_OPTIONS.includes(size) ? size : DEFAULT_PAGE_SIZE,
+    sort: sort && SORT_PATTERN.test(sort) ? (sort as EntitySort) : DEFAULT_SORT,
+  };
+}
+
+/** A copy of the URL with `changes` applied: an empty value removes its key, an array repeats it. */
+export function withChanges(
+  current: URLSearchParams,
+  changes: Partial<Record<ListParamKey, string | string[] | undefined>>,
+) {
+  const next = new URLSearchParams(current);
+  for (const [key, value] of Object.entries(changes)) {
+    next.delete(key);
+    for (const item of [value ?? []].flat()) {
+      if (item !== '') next.append(key, item);
+    }
+  }
+  return next;
+}
+
+export function useEntityList() {
+  const [searchParams, setSearchParams] = useSearchParams();
+  const state = readListState(searchParams);
+  const params: ListEntitiesParams = { ...state, q: state.q.trim() || undefined };
+
+  const query = useQuery({
+    queryKey: ['entities', params],
+    queryFn: () => listEntities(params),
+    placeholderData: keepPreviousData,
+  });
+
+  // keepPreviousData holds the previous page only while the next one loads, and a retry with nothing
+  // loaded clears the error while it runs. Keep the last page that loaded and the last error, so that
+  // the rows, the toolbar and the alert stay on screen until the next answer: the search field never
+  // disappears while the user types, and the alert does not vanish while Retry runs.
+  const [lastLoaded, setLastLoaded] = useState<EntityPage>();
+  const [lastError, setLastError] = useState<Error | null>(null);
+  const answered = query.isSuccess && !query.isPlaceholderData;
+  if (answered && query.data !== lastLoaded) setLastLoaded(query.data);
+  if (answered && lastError) setLastError(null);
+  if (query.error && query.error !== lastError) setLastError(query.error);
+
+  // A page past the last one (its last row deleted, an old link) shows the last page instead.
+  const lastPage = Math.max(1, Math.ceil((query.data?.totalCount ?? 0) / state.size));
+  const pastTheEnd = answered && state.page > lastPage;
+  useEffect(() => {
+    if (pastTheEnd) {
+      setSearchParams((current) => withChanges(current, { page: lastPage > 1 ? String(lastPage) : undefined }), {
+        replace: true,
+      });
+    }
+  }, [pastTheEnd, lastPage, setSearchParams]);
+
+  const setCriteria = (changes: Parameters<typeof withChanges>[1]) =>
+    setSearchParams((current) => withChanges(current, { ...changes, page: undefined }), { replace: true });
+  const setPaging = (changes: Parameters<typeof withChanges>[1]) =>
+    setSearchParams((current) => withChanges(current, changes));
+
+  const [sortField, sortDirection] = state.sort.split(':');
+  const sorting: SortingState = [{ id: sortField, desc: sortDirection === 'desc' }];
+  const onSortingChange: OnChangeFn<SortingState> = (updater) => {
+    const [next] = typeof updater === 'function' ? updater(sorting) : updater;
+    const sort = next ? `${next.id}:${next.desc ? 'desc' : 'asc'}` : DEFAULT_SORT;
+    setCriteria({ sort: sort === DEFAULT_SORT ? undefined : sort });
+  };
+
+  return {
+    ...state,
+    sorting,
+    onSortingChange,
+    hasCriteria: params.q !== undefined || state.status !== undefined || state.type.length > 0,
+    // Decide the page's state only from a settled answer, never from the placeholder of the last one.
+    settled: answered && !pastTheEnd,
+    result: query.data ?? lastLoaded,
+    error: query.error ?? (query.isFetching ? lastError : null),
+    isFetching: query.isFetching || pastTheEnd,
+    refetch: query.refetch,
+    setQuery: (q: string) => setCriteria({ q }),
+    setStatus: (status: string | undefined) => setCriteria({ status }),
+    setTypes: (types: EntityType[]) => setCriteria({ type: types }),
+    setPage: (page: number) => setPaging({ page: page > 1 ? String(page) : undefined }),
+    setPageSize: (size: number) =>
+      setPaging({ size: size === DEFAULT_PAGE_SIZE ? undefined : String(size), page: undefined }),
+    reset: () => setCriteria({ q: undefined, status: undefined, type: undefined }),
+  };
+}
+
+/**
+ * Deletes an entity, then refetches every page of the list without waiting for it: the caller hears the
+ * outcome as soon as the delete answers, while its row is still on screen.
+ */
+export function useDeleteEntity() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: deleteEntity,
+    onSuccess: () => {
+      void queryClient.invalidateQueries({ queryKey: ['entities'] });
+    },
+  });
+}

package/snippets/data-table-list-page.tsx

@@ -1,316 +0,0 @@
-// Snippet: Entity List page with DataTable
-//
-// Use when building a list page for server-paginated entity data (APIs, Applications,
-// Policies, Agents, Plans, etc.) — any CRUD list where users manage entities.
-//
-// Do NOT use for:
-// - Static key-value detail panels (use raw Table)
-// - Time-series/triage explorers (logs, traces) — see Record Explorer pattern (deferred)
-// - Tables with fewer than 5 fixed rows
-//
-// Empty state pattern (page-level decision):
-// - totalCount === 0 && !hasFilters → DataTableEmptyState variant="first-use" (INSTEAD of DataTable)
-// - filteredCount === 0 && hasFilters → DataTableEmptyState variant="no-results" (INSIDE DataTable)
-//
-// Header button coordination:
-// - First-use → header hides "Add" button; empty state owns the primary CTA
-// - Has data  → header shows "Add" button (primary); table is main content
-// - Both buttons trigger the same creation flow
-//
-// See Storybook "Composed/DataTableEmptyState → Integration" for interactive example.
-//
-// Column ordering (left to right):
-// 1. Name (link, always first, font-medium hover:underline)
-// 2. Status badge (lifecycle state)
-// 3. Category badges (type, version, security)
-// 4. Dates (relative format + full tooltip)
-// 5. Owner/actor (truncated text)
-// 6. Actions (always last, sr-only header)
-//
-// Minimum 3 data columns (excluding actions). Fewer → use Item list or card grid.
-// Target 4-7 visible columns. More than 7 → enable column visibility.
-// Do NOT show raw entity IDs as visible columns.
-//
-// Actions column: ALWAYS use MoreVerticalIcon (⋮) + DropdownMenu.
-// Never render a row of inline icon buttons. Single-action exception: exactly 1
-// action may be a lone icon button without a dropdown.
-//
-// See Storybook "Patterns/Data Table → ApiList" for interactive example.
-
-import {
-  Badge,
-  Button,
-  DataTable,
-  DataTableColumnHeader,
-  DataTableEmptyState,
-  DateCell,
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuSeparator,
-  DropdownMenuTrigger,
-  FacetedFilter,
-  PageHeader,
-  SearchField,
-} from '@gravitee/graphene-core';
-import {
-  GlobeIcon,
-  MoreVerticalIcon,
-  PencilIcon,
-  PlusIcon,
-  SearchIcon,
-  Trash2Icon,
-} from '@gravitee/graphene-core/icons';
-import type { ColumnDef, SortingState } from '@tanstack/react-table';
-import { useEffect, useReducer, useState } from 'react';
-
-// Replace with your entity type
-interface Entity {
-  id: string;
-  name: string;
-  status: 'active' | 'inactive' | 'draft';
-  createdAt: string;
-  owner: string;
-}
-
-// Replace with your API fetch function
-declare function fetchEntities(params: {
-  page: number;
-  perPage: number;
-  sortBy?: string;
-  sortOrder?: 'asc' | 'desc';
-  search?: string;
-  status?: string[];
-}): Promise<{ data: Entity[]; totalCount: number }>;
-
-const STATUS_VARIANTS = {
-  active: 'success',
-  inactive: 'secondary',
-  draft: 'outline',
-} as const;
-
-const statusOptions = [
-  { value: 'active', label: 'Active' },
-  { value: 'inactive', label: 'Inactive' },
-  { value: 'draft', label: 'Draft' },
-];
-
-const columns: ColumnDef<Entity, unknown>[] = [
-  {
-    accessorKey: 'name',
-    header: ({ column }) => <DataTableColumnHeader column={column} title="Name" />,
-    cell: ({ row }) => (
-      <a href={`#/entities/${row.original.id}`} className="font-medium hover:underline">
-        {row.original.name}
-      </a>
-    ),
-  },
-  {
-    accessorKey: 'status',
-    header: ({ column }) => <DataTableColumnHeader column={column} title="Status" />,
-    cell: ({ row }) => <Badge variant={STATUS_VARIANTS[row.original.status]}>{row.original.status}</Badge>,
-  },
-  {
-    accessorKey: 'createdAt',
-    header: ({ column }) => <DataTableColumnHeader column={column} title="Created" />,
-    cell: ({ row }) => <DateCell value={row.original.createdAt} />,
-  },
-  {
-    accessorKey: 'owner',
-    header: 'Owner',
-    enableSorting: false,
-    cell: ({ row }) => <span className="max-w-[150px] truncate text-muted-foreground">{row.original.owner}</span>,
-  },
-  {
-    id: 'actions',
-    header: () => <span className="sr-only">Actions</span>,
-    enableSorting: false,
-    enableHiding: false,
-    cell: () => (
-      <div className="flex justify-end">
-        <DropdownMenu>
-          <DropdownMenuTrigger asChild>
-            <Button variant="ghost" size="icon-xs">
-              <MoreVerticalIcon className="size-4" />
-            </Button>
-          </DropdownMenuTrigger>
-          <DropdownMenuContent align="end">
-            <DropdownMenuItem>
-              <PencilIcon className="size-3.5" />
-              Edit
-            </DropdownMenuItem>
-            <DropdownMenuSeparator />
-            <DropdownMenuItem className="text-destructive">
-              <Trash2Icon className="size-3.5" />
-              Delete
-            </DropdownMenuItem>
-          </DropdownMenuContent>
-        </DropdownMenu>
-      </div>
-    ),
-  },
-];
-
-interface FetchState {
-  data: Entity[];
-  totalCount: number;
-  loading: boolean;
-}
-
-type FetchAction = { type: 'loading' } | { type: 'success'; data: Entity[]; totalCount: number };
-
-function fetchReducer(state: FetchState, action: FetchAction): FetchState {
-  if (action.type === 'loading') return { ...state, loading: true };
-  return { data: action.data, totalCount: action.totalCount, loading: false };
-}
-
-export function EntityListPage() {
-  const [page, setPage] = useState(1);
-  const [pageSize, setPageSize] = useState(10);
-  const [query, setQuery] = useState('');
-  const [sorting, setSorting] = useState<SortingState>([]);
-  const [statusFilter, setStatusFilter] = useState<string[]>([]);
-  const [state, dispatch] = useReducer(fetchReducer, { data: [], totalCount: 0, loading: true });
-
-  useEffect(() => {
-    let active = true;
-    dispatch({ type: 'loading' });
-    fetchEntities({
-      page,
-      perPage: pageSize,
-      sortBy: sorting[0]?.id,
-      sortOrder: sorting[0]?.desc ? 'desc' : 'asc',
-      search: query || undefined,
-      status: statusFilter.length ? statusFilter : undefined,
-    }).then((res) => {
-      if (active) dispatch({ type: 'success', data: res.data, totalCount: res.totalCount });
-    });
-    return () => {
-      active = false;
-    };
-  }, [page, pageSize, sorting, query, statusFilter]);
-
-  const handleSortingChange = (updater: SortingState | ((prev: SortingState) => SortingState)) => {
-    setSorting(typeof updater === 'function' ? updater(sorting) : updater);
-    setPage(1);
-  };
-
-  const handleStatusChange = (values: string[]) => {
-    setStatusFilter(values);
-    setPage(1);
-  };
-
-  const { data, totalCount, loading } = state;
-  const hasFilters = query || statusFilter.length > 0;
-  const isFirstUse = totalCount === 0 && !hasFilters && !loading;
-
-  return (
-    <div className="flex flex-col gap-6">
-      <PageHeader
-        title="Entities"
-        description="Manage your entity catalog."
-        actions={
-          !isFirstUse && (
-            <Button size="sm">
-              <PlusIcon />
-              Add entity
-            </Button>
-          )
-        }
-      />
-
-      {isFirstUse ? (
-        <div className="rounded-lg border">
-          <DataTableEmptyState
-            variant="first-use"
-            icon={<GlobeIcon />}
-            title="No entities yet"
-            description="Get started by creating your first entity."
-            primaryAction={
-              <Button size="sm">
-                <PlusIcon />
-                Create entity
-              </Button>
-            }
-          />
-        </div>
-      ) : (
-        <DataTable
-          columns={columns}
-          data={data}
-          loading={loading}
-          skeletonCount={pageSize}
-          sorting={sorting}
-          onSortingChange={handleSortingChange}
-          enableColumnVisibility
-          serverSide
-          pagination={{
-            page,
-            pageSize,
-            totalCount,
-            pageSizeOptions: [10, 25, 50, 100],
-            onPageChange: setPage,
-            onPageSizeChange: (size) => {
-              setPageSize(size);
-              setPage(1);
-            },
-          }}
-          emptyMessage={
-            <DataTableEmptyState
-              variant="no-results"
-              icon={<SearchIcon />}
-              title="No entities match your search"
-              description="Try adjusting your search terms or clearing filters."
-              action={
-                <Button
-                  size="sm"
-                  variant="outline"
-                  onClick={() => {
-                    setQuery('');
-                    setStatusFilter([]);
-                    setPage(1);
-                  }}
-                >
-                  Clear filters
-                </Button>
-              }
-            />
-          }
-          toolbar={
-            <>
-              <SearchField
-                aria-label="Search entities"
-                placeholder="Search..."
-                value={query}
-                onValueChange={(value) => {
-                  setQuery(value);
-                  setPage(1);
-                }}
-                className="w-64"
-              />
-              <FacetedFilter
-                title="Status"
-                options={statusOptions}
-                selected={statusFilter}
-                onChange={handleStatusChange}
-              />
-              {hasFilters && (
-                <Button
-                  variant="ghost"
-                  size="sm"
-                  onClick={() => {
-                    setQuery('');
-                    setStatusFilter([]);
-                    setPage(1);
-                  }}
-                >
-                  Reset
-                </Button>
-              )}
-            </>
-          }
-        />
-      )}
-    </div>
-  );
-}