@gravitee/graphene-core 3.25.0 → 3.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravitee/graphene-core",
-  "version": "3.25.0",
+  "version": "3.26.0",
   "type": "module",
   "description": "Gravitee's Graphene design system: accessible React components, design tokens, icons, and shared ESLint/TypeScript configs. Built on shadcn/ui and Tailwind.",
   "keywords": [
@@ -163,8 +163,10 @@
   "devDependencies": {
     "@hookform/resolvers": "5.4.0",
     "@monaco-editor/react": "4.7.0",
+    "@tanstack/react-query": "5.100.14",
     "monaco-editor": "0.52.2",
     "react-hook-form": "7.78.0",
+    "react-router-dom": "7.15.1",
     "shadcn": "4.11.0",
     "vitest": "4.1.8",
     "zod": "4.4.3"

package/snippets/list-page/DeleteEntityDialog.tsx

@@ -0,0 +1,71 @@
+// Confirms the deletion of one entity, runs it and reports the outcome in a toast (the app mounts the
+// Toaster once: the Gamma shell does). The row's ⋮ menu opens it. While the delete runs, the dialog
+// cannot be dismissed; a failure keeps it open so the user can try again or cancel.
+
+import {
+  Button,
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  toast,
+} from '@gravitee/graphene-core';
+import { Trash2Icon } from '@gravitee/graphene-core/icons';
+import type { Entity } from './entities.service';
+import { useDeleteEntity } from './useEntityList';
+
+interface DeleteEntityDialogProps {
+  readonly entity: Entity;
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+  /** Runs once the entity is deleted, before the dialog closes. */
+  readonly onDeleted: () => void;
+  /** Where the focus goes when the dialog closes: the element that opened it is often gone by then. */
+  readonly onCloseAutoFocus?: (event: Event) => void;
+}
+
+export function DeleteEntityDialog({
+  entity,
+  open,
+  onOpenChange,
+  onDeleted,
+  onCloseAutoFocus,
+}: DeleteEntityDialogProps) {
+  const { mutate, isPending } = useDeleteEntity();
+
+  const confirm = () =>
+    mutate(entity.id, {
+      onSuccess: () => {
+        toast.success(`Deleted ${entity.name}`);
+        onDeleted();
+        onOpenChange(false);
+      },
+      onError: (error) => toast.error(`Could not delete ${entity.name}`, { description: error.message }),
+    });
+
+  return (
+    <Dialog open={open} onOpenChange={(next) => !isPending && onOpenChange(next)}>
+      <DialogContent showCloseButton={false} onCloseAutoFocus={onCloseAutoFocus}>
+        <DialogHeader>
+          <DialogTitle>Delete {entity.name}?</DialogTitle>
+          {/* Say what stops working once it is gone, when something does. */}
+          <DialogDescription>This deletes the entity for good. It cannot be undone.</DialogDescription>
+        </DialogHeader>
+        <DialogFooter>
+          <DialogClose asChild>
+            <Button variant="outline" disabled={isPending}>
+              Cancel
+            </Button>
+          </DialogClose>
+          <Button variant="destructive" disabled={isPending} onClick={confirm}>
+            <Trash2Icon aria-hidden="true" />
+            {isPending ? 'Deleting...' : 'Delete entity'}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/snippets/list-page/EntitiesPage.tsx

@@ -0,0 +1,221 @@
+// Snippet: entity list page
+//
+// Use for the list page of an entity the user manages (APIs, applications, plans, agents...), fetched
+// page by page from the server, with search, filters, sorting, row actions and creation.
+//
+// Do NOT use for:
+// - Static key-value detail panels (use raw Table)
+// - Time-series or triage explorers (logs, traces): no snippet yet
+// - Tables with fewer than 5 fixed rows
+//
+// This folder: EntitiesPage.tsx (the page), useEntityList.ts (query and URL state), entityColumns.tsx
+// (the columns), EntityActionsMenu.tsx (the row menu), DeleteEntityDialog.tsx (the delete confirmation)
+// and entities.service.ts (sample data, to replace with your API client). Copy the folder, then rename
+// Entity and entities after your resource.
+//
+// States, decided once the query has settled, never from the previous page kept while loading:
+// - Loading: skeleton rows on the first load; later fetches keep the rows under DataTable's overlay.
+// - Error: an alert with Retry above the last loaded rows, saying they may be out of date; the alert
+//   alone when nothing has loaded yet.
+// - First use (no entity, no criterion): DataTableEmptyState "first-use" INSTEAD of the table, without
+//   a button.
+// - No results (a criterion active): DataTableEmptyState "no-results" INSIDE the table, without a
+//   button: the search field's clear button and Reset clear the criteria.
+// - Data: the rows.
+// The header's Add button stays in every state: one creation CTA on screen.
+//
+// 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. The View menu (enableColumnVisibility) hides and shows them: keep the
+// name and the actions always visible (enableHiding: false), and give a column whose header is a
+// component a meta.label, or the menu shows its id.
+// Do NOT show raw entity IDs as visible columns.
+//
+// Actions column: ALWAYS use MoreVerticalIcon (⋮) + DropdownMenu, named after the row.
+// Never render a row of inline icon buttons. Single-action exception: exactly 1
+// action may be a lone icon button without a dropdown. Delete comes last and asks for confirmation
+// in a Dialog, then reports the outcome in a toast.
+//
+// See Storybook "Patterns/List Page" for the five states.
+
+import {
+  Alert,
+  AlertAction,
+  AlertDescription,
+  AlertTitle,
+  Button,
+  DataTable,
+  DataTableEmptyState,
+  FacetedFilter,
+  Label,
+  PageHeader,
+  SearchField,
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@gravitee/graphene-core';
+import { BoxesIcon, CircleXIcon, PlusIcon, SearchIcon } from '@gravitee/graphene-core/icons';
+import { useId, useRef } from 'react';
+import { Link } from 'react-router-dom';
+import { EntityDeletedContext } from './EntityActionsMenu';
+import { ENTITY_STATUSES, ENTITY_TYPES } from './entities.service';
+import { entityColumns, STATUS_BADGES, TYPE_LABELS } from './entityColumns';
+import { PAGE_SIZE_OPTIONS, useEntityList } from './useEntityList';
+
+const ALL_STATUSES = 'all';
+const TYPE_OPTIONS = ENTITY_TYPES.map((value) => ({ value, label: TYPE_LABELS[value] }));
+
+export function EntitiesPage() {
+  // Your module's permission check. Gamma modules read it with `useHasPermission` from
+  // `@gravitee/gamma-modules-sdk`, for example `useHasPermission({ anyOf: ['{ENTITY_CREATE_PERMISSION}'] })`.
+  const canCreate = true;
+  const list = useEntityList();
+  const searchRef = useRef<HTMLInputElement>(null);
+  const statusId = useId();
+
+  const { result, error, settled } = list;
+  const totalCount = result?.totalCount ?? 0;
+  const isFirstUse = settled && totalCount === 0 && !list.hasCriteria;
+  const announcement =
+    !settled || isFirstUse ? '' : totalCount === 0 ? 'No results' : `${totalCount} result${totalCount > 1 ? 's' : ''}`;
+
+  const reset = () => {
+    list.reset();
+    searchRef.current?.focus();
+  };
+  // A deleted entity takes its row and ⋮ with it: the focus moves to the search field, as after Reset.
+  const focusSearch = () => searchRef.current?.focus();
+
+  return (
+    <div className="flex flex-col gap-6">
+      <PageHeader
+        title="Entities"
+        // One sentence on what this resource is for, never a restatement of the title.
+        description="The entities your teams publish, with their status, type and owner."
+        actions={
+          canCreate && (
+            <Button asChild>
+              <Link to="new">
+                <PlusIcon />
+                Add entity
+              </Link>
+            </Button>
+          )
+        }
+      />
+
+      {/* Tells a screen reader the outcome of a search once the list settles. */}
+      <p role="status" className="sr-only">
+        {announcement}
+      </p>
+
+      {error && (
+        <Alert variant="destructive">
+          <CircleXIcon />
+          <AlertTitle>Could not load entities</AlertTitle>
+          <AlertDescription>{result ? 'The list below may be out of date.' : error.message}</AlertDescription>
+          <AlertAction align="center">
+            <Button variant="outline" size="xs" disabled={list.isFetching} onClick={() => list.refetch()}>
+              {list.isFetching ? 'Retrying...' : 'Retry'}
+            </Button>
+          </AlertAction>
+        </Alert>
+      )}
+
+      {isFirstUse ? (
+        // A flagship list may replace this block with an educational landing.
+        <div className="rounded-lg border">
+          <DataTableEmptyState
+            variant="first-use"
+            icon={<BoxesIcon />}
+            title="No entities yet"
+            description="Add your first entity to follow its status, type and owner here."
+          />
+        </div>
+      ) : (
+        (result || !error) && (
+          <EntityDeletedContext value={focusSearch}>
+            <DataTable
+              aria-label="Entities"
+              columns={entityColumns}
+              data={result?.data ?? []}
+              serverSide
+              enableColumnVisibility
+              loading={list.isFetching}
+              skeletonCount={list.size}
+              sorting={list.sorting}
+              onSortingChange={list.onSortingChange}
+              // Rows keyed by entity: when a row goes, its ⋮ never passes to the next entity.
+              tableOptions={{ getRowId: (entity) => entity.id }}
+              pagination={{
+                page: list.page,
+                pageSize: list.size,
+                totalCount,
+                pageSizeOptions: PAGE_SIZE_OPTIONS,
+                onPageChange: list.setPage,
+                onPageSizeChange: list.setPageSize,
+              }}
+              emptyMessage={
+                <DataTableEmptyState
+                  variant="no-results"
+                  icon={<SearchIcon />}
+                  title="No entities found"
+                  description="Try another search, or adjust the filters."
+                />
+              }
+              toolbar={
+                <div className="flex min-w-0 flex-wrap items-center gap-2">
+                  <SearchField
+                    ref={searchRef}
+                    aria-label="Search entities"
+                    placeholder="Search entities..."
+                    value={list.q}
+                    onValueChange={list.setQuery}
+                    className="w-64"
+                  />
+                  {/* The filters and Reset wrap together, never Reset alone. */}
+                  <div className="flex flex-wrap items-center gap-2">
+                    <Label htmlFor={statusId} className="sr-only">
+                      Status
+                    </Label>
+                    <Select
+                      value={list.status ?? ALL_STATUSES}
+                      onValueChange={(value) => list.setStatus(value === ALL_STATUSES ? undefined : value)}
+                    >
+                      <SelectTrigger id={statusId} className="min-w-32">
+                        <SelectValue />
+                      </SelectTrigger>
+                      <SelectContent>
+                        <SelectItem value={ALL_STATUSES}>All statuses</SelectItem>
+                        {ENTITY_STATUSES.map((status) => (
+                          <SelectItem key={status} value={status}>
+                            {STATUS_BADGES[status].value}
+                          </SelectItem>
+                        ))}
+                      </SelectContent>
+                    </Select>
+                    <FacetedFilter title="Type" options={TYPE_OPTIONS} selected={list.type} onChange={list.setTypes} />
+                    {list.hasCriteria && (
+                      <Button variant="ghost" size="sm" onClick={reset}>
+                        Reset
+                      </Button>
+                    )}
+                  </div>
+                </div>
+              }
+            />
+          </EntityDeletedContext>
+        )
+      )}
+    </div>
+  );
+}

package/snippets/list-page/EntityActionsMenu.tsx

@@ -0,0 +1,69 @@
+// The ⋮ menu of a row: named after the entity, Edit first, the destructive Delete last, which asks for
+// confirmation before anything is deleted.
+
+import {
+  Button,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '@gravitee/graphene-core';
+import { MoreVerticalIcon, PencilIcon, Trash2Icon } from '@gravitee/graphene-core/icons';
+import { createContext, use, useRef, useState } from 'react';
+import { Link } from 'react-router-dom';
+import { DeleteEntityDialog } from './DeleteEntityDialog';
+import type { Entity } from './entities.service';
+
+/**
+ * Where the focus goes once a row's entity is deleted, since its row and ⋮ go with it. The page provides it
+ * around the table; without it, the focus falls back on the page body.
+ */
+export const EntityDeletedContext = createContext<() => void>(() => {});
+
+export function EntityActionsMenu({ entity }: { readonly entity: Entity }) {
+  const onDeleted = use(EntityDeletedContext);
+  const [confirmingDelete, setConfirmingDelete] = useState(false);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const deleted = useRef(false);
+
+  return (
+    <div className="flex justify-end">
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button ref={triggerRef} variant="ghost" size="icon-xs" aria-label={`Actions for ${entity.name}`}>
+            <MoreVerticalIcon />
+          </Button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end">
+          <DropdownMenuItem asChild>
+            <Link to={`./${entity.id}/edit`}>
+              <PencilIcon />
+              Edit
+            </Link>
+          </DropdownMenuItem>
+          <DropdownMenuSeparator />
+          <DropdownMenuItem variant="destructive" onSelect={() => setConfirmingDelete(true)}>
+            <Trash2Icon />
+            Delete
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+      <DeleteEntityDialog
+        entity={entity}
+        open={confirmingDelete}
+        onOpenChange={setConfirmingDelete}
+        onDeleted={() => {
+          deleted.current = true;
+        }}
+        // The menu that opened the dialog is closed by then. Cancelled: give the focus back to the ⋮.
+        // Deleted: the ⋮ goes with its row, so the focus goes where the page says.
+        onCloseAutoFocus={(event) => {
+          event.preventDefault();
+          if (deleted.current) onDeleted();
+          else triggerRef.current?.focus();
+        }}
+      />
+    </div>
+  );
+}

package/snippets/list-page/entities.service.ts

@@ -0,0 +1,108 @@
+// Sample data service: replace it with your API client.
+//
+// `useEntityList.ts` is the only file that calls this service: point its query and its delete at your
+// module's API client, then delete this file. The other files import only its types and value lists.
+//
+// Until then the snippet runs as-is: about 50 entities in memory, answered after 300 ms, filtered on the
+// name, the status and the type, then sorted and paged the way a server endpoint does it.
+
+export type EntityStatus = 'active' | 'inactive' | 'draft';
+export type EntityType = 'internal' | 'external' | 'partner';
+export type EntitySortField = 'name' | 'createdAt';
+export type EntitySort = `${EntitySortField}:${'asc' | 'desc'}`;
+
+export interface Entity {
+  id: string;
+  name: string;
+  status: EntityStatus;
+  type: EntityType;
+  /** ISO 8601 date. */
+  createdAt: string;
+  owner: string;
+}
+
+export interface ListEntitiesParams {
+  /** Part of the name, case-insensitive. */
+  q?: string;
+  status?: EntityStatus;
+  /** Entities of any of these types. */
+  type?: EntityType[];
+  sort?: EntitySort;
+  /** 1-based. */
+  page: number;
+  size: number;
+}
+
+export interface EntityPage {
+  data: Entity[];
+  totalCount: number;
+}
+
+export const ENTITY_STATUSES: EntityStatus[] = ['active', 'inactive', 'draft'];
+export const ENTITY_TYPES: EntityType[] = ['internal', 'external', 'partner'];
+
+type ServiceMode = 'data' | 'empty' | 'error' | 'slow';
+
+const ADJECTIVES = ['Amber', 'Blue', 'Coral', 'Crimson', 'Golden', 'Ivory', 'Jade', 'Onyx', 'Silver', 'Violet'];
+const NOUNS = ['Falcon', 'Harbor', 'Meadow', 'River', 'Summit'];
+const OWNERS = ['Alex Martin', 'Sam Rivera', 'Jordan Lee', 'Taylor Kim', 'Morgan Chen', 'Casey Dubois'];
+const STATUS_CYCLE: EntityStatus[] = ['active', 'active', 'inactive', 'active', 'draft'];
+const HOUR = 3_600_000;
+
+let mode: ServiceMode = 'data';
+let entities = sampleEntities();
+
+/** 50 entities, newest first, created over the last four weeks. */
+export function sampleEntities(): Entity[] {
+  const now = Date.now();
+  return Array.from({ length: 50 }, (_, index) => ({
+    id: `entity-${index + 1}`,
+    name: `${ADJECTIVES[index % ADJECTIVES.length]} ${NOUNS[Math.floor(index / ADJECTIVES.length)]}`,
+    status: STATUS_CYCLE[index % STATUS_CYCLE.length],
+    type: ENTITY_TYPES[Math.floor(index / 2) % ENTITY_TYPES.length],
+    createdAt: new Date(now - (index * 13 + 2) * HOUR).toISOString(),
+    owner: OWNERS[index % OWNERS.length],
+  }));
+}
+
+/**
+ * For the Storybook story and the tests: `data` (the default), `empty` (no entity at all), `error` (every
+ * call rejects) or `slow` (answers after 3 s). Also puts back the entities deleted so far.
+ */
+export function configureEntitiesService(options: { mode: ServiceMode }) {
+  mode = options.mode;
+  entities = sampleEntities();
+}
+
+export function listEntities({ q, status, type, sort, page, size }: ListEntitiesParams): Promise<EntityPage> {
+  return respond(() => {
+    const search = q?.toLowerCase();
+    const matches = (mode === 'empty' ? [] : entities).filter(
+      (entity) =>
+        (!search || entity.name.toLowerCase().includes(search)) &&
+        (!status || entity.status === status) &&
+        (!type?.length || type.includes(entity.type)),
+    );
+    if (sort) {
+      const [field, direction] = sort.split(':') as [EntitySortField, 'asc' | 'desc'];
+      matches.sort((a, b) => a[field].localeCompare(b[field]) * (direction === 'asc' ? 1 : -1));
+    }
+    return { data: matches.slice((page - 1) * size, page * size), totalCount: matches.length };
+  });
+}
+
+export function deleteEntity(id: string): Promise<void> {
+  return respond(() => {
+    entities = entities.filter((entity) => entity.id !== id);
+  });
+}
+
+/** Answers like a server: after a delay, or with an error when the service is configured to fail. */
+export function respond<T>(answer: () => T): Promise<T> {
+  return new Promise((resolve, reject) => {
+    setTimeout(
+      () => (mode === 'error' ? reject(new Error('Service unavailable (503)')) : resolve(answer())),
+      mode === 'slow' ? 3000 : 300,
+    );
+  });
+}

package/snippets/list-page/entityColumns.tsx

@@ -0,0 +1,79 @@
+// The columns of the entity list, left to right: name, status, type, creation date, owner, actions.
+
+import {
+  Badge,
+  BadgeCell,
+  type BadgeCellProps,
+  DataTableColumnHeader,
+  DateCell,
+  TruncatedCell,
+} from '@gravitee/graphene-core';
+import { CircleCheckIcon, CircleIcon, CircleMinusIcon } from '@gravitee/graphene-core/icons';
+import type { ColumnDef } from '@tanstack/react-table';
+import { Link } from 'react-router-dom';
+import { EntityActionsMenu } from './EntityActionsMenu';
+import type { Entity, EntityStatus, EntityType } from './entities.service';
+
+// A status pairs its colour with an icon and a label: it never relies on colour alone.
+export const STATUS_BADGES: Record<EntityStatus, BadgeCellProps> = {
+  active: { value: 'Active', variant: 'success', icon: <CircleCheckIcon aria-hidden="true" /> },
+  inactive: { value: 'Inactive', variant: 'secondary', icon: <CircleMinusIcon aria-hidden="true" /> },
+  draft: { value: 'Draft', variant: 'outline', icon: <CircleIcon aria-hidden="true" /> },
+};
+export const TYPE_LABELS: Record<EntityType, string> = {
+  internal: 'Internal',
+  external: 'External',
+  partner: 'Partner',
+};
+// Categories stay neutral. `highlight` (violet), the one accent that carries no state, sets apart the
+// type to notice; never red, green or amber, which mean error, success and warning.
+const TYPE_VARIANTS = { internal: 'highlight', external: 'secondary', partner: 'secondary' } as const;
+
+/** Name and Created sort on the server, and name themselves in the View menu with `meta.label`. */
+export const entityColumns: ColumnDef<Entity, unknown>[] = [
+  {
+    accessorKey: 'name',
+    header: ({ column }) => <DataTableColumnHeader column={column} title="Name" />,
+    meta: { label: 'Name' },
+    enableHiding: false,
+    cell: ({ row }) => (
+      <Link
+        to={`./${row.original.id}`}
+        className="rounded-lg font-medium outline-none hover:underline focus-visible:ring-3 focus-visible:ring-ring/50"
+      >
+        {row.original.name}
+      </Link>
+    ),
+  },
+  {
+    accessorKey: 'status',
+    header: 'Status',
+    enableSorting: false,
+    cell: ({ row }) => <BadgeCell {...STATUS_BADGES[row.original.status]} />,
+  },
+  {
+    accessorKey: 'type',
+    header: 'Type',
+    enableSorting: false,
+    cell: ({ row }) => <Badge variant={TYPE_VARIANTS[row.original.type]}>{TYPE_LABELS[row.original.type]}</Badge>,
+  },
+  {
+    accessorKey: 'createdAt',
+    header: ({ column }) => <DataTableColumnHeader column={column} title="Created" />,
+    meta: { label: 'Created' },
+    cell: ({ row }) => <DateCell value={row.original.createdAt} />,
+  },
+  {
+    accessorKey: 'owner',
+    header: 'Owner',
+    enableSorting: false,
+    cell: ({ row }) => <TruncatedCell value={row.original.owner} />,
+  },
+  {
+    id: 'actions',
+    header: () => <span className="sr-only">Actions</span>,
+    enableSorting: false,
+    enableHiding: false,
+    cell: ({ row }) => <EntityActionsMenu entity={row.original} />,
+  },
+];

package/snippets/list-page/snippet.json

@@ -0,0 +1,6 @@
+{
+  "dependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "react-router-dom": "^7.0.0"
+  }
+}