create-astram-app 0.1.3 → 0.3.0

package/template/frontend/src/components/EntityFormModal.jsx

@@ -0,0 +1,154 @@
+/**
+ * EntityFormModal — the routed-modal overlay for the identity Add/Edit forms. Built on
+ * the shadcn Dialog primitive (`dialog.tsx`) so it inherits the app's light/dark
+ * theming, focus trap, and Escape-to-close.
+ *
+ * This is the "routed-modal" pattern: the modal is rendered by an Add/Edit CHILD ROUTE
+ * (e.g. /companies/add, /companies/edit/:uuid) under the list's layout, so the URL is
+ * bookmarkable and the back button closes it — while looking like a lightweight overlay.
+ * The list stays mounted behind it.
+ *
+ * The `children` are the form fields; the form wrapper submits on Enter (the primary is
+ * `type="submit"`), matching native dialog behavior. `busy` disables both buttons so a
+ * slow request can't be double-fired or cancelled mid-flight.
+ *
+ * Props:
+ *   title        — dialog heading
+ *   description  — optional sub-line
+ *   open         — controlled open state (the child route passes `true`)
+ *   onClose      — () => void   (Escape / scrim / Cancel → typically navigate(-1))
+ *   onSubmit     — () => void   (fired by Enter or the primary button; the parent runs the API)
+ *   submitLabel  — primary button label (default "Save")
+ *   cancelLabel  — ghost cancel label (default "Cancel")
+ *   busy         — request in flight → buttons disabled
+ *   error        — an error string shown above the buttons
+ *   contentClassName — optional override for the dialog width (default a compact form);
+ *                      wider forms (e.g. the user edit page with its assignments editor)
+ *                      pass a roomier max-width.
+ *   expandable   — show the OCA-style expand/collapse (full-screen) toggle in the header
+ *                  (default true). Full-screen is the natural escape for the roomier
+ *                  assignments modal; small forms keep it but it's harmless.
+ *   children     — the form fields
+ *
+ * Overflow containment: the DialogContent is a CSS grid, and the form → body chain all
+ * carry `min-w-0` so a wide descendant (the assignments posting table) can shrink below
+ * its content width — which lets that table's own `overflow-x-auto` wrapper scroll it
+ * INSIDE the modal instead of forcing the modal past its `max-w`. The body also scrolls
+ * vertically (`overflow-y-auto` + a max-height) so a tall assignments editor never spills.
+ *
+ * Full-screen: the expand toggle flips a local `expanded` flag; when set, the content
+ * overrides its centered/bounded classes to fill the viewport (`inset-0 w-screen h-screen
+ * max-w-none rounded-none`, no translate) — the OCA `.dsa-modal--full` treatment.
+ */
+import { useState } from 'react';
+import { Loader2, Maximize2, Minimize2 } from 'lucide-react';
+import { cn } from '@/lib/utils';
+import { Button } from '@/components/ui/button';
+import { Alert, AlertDescription } from '@/components/ui/alert';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+
+export default function EntityFormModal({
+  title,
+  description,
+  open,
+  onClose,
+  onSubmit,
+  submitLabel = 'Save',
+  cancelLabel = 'Cancel',
+  busy = false,
+  error = '',
+  contentClassName = 'sm:max-w-md',
+  expandable = true,
+  children,
+}) {
+  const [expanded, setExpanded] = useState(false);
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(next) => {
+        // Close only via the dialog's own affordances, and never mid-request.
+        if (!next && !busy) onClose?.();
+      }}
+    >
+      <DialogContent
+        showCloseButton={!busy}
+        className={cn(
+          // `min-w-0` lets the grid's content track shrink below a wide child's
+          // intrinsic width (the grid min-width:auto trap), so the inner posting
+          // table's overflow-x-auto is what absorbs extra width — the modal never
+          // exceeds its max-width. `overflow-hidden` clips any residual bleed.
+          'flex max-h-[calc(100vh-4rem)] min-w-0 flex-col overflow-hidden',
+          expanded
+            ? // OCA `.dsa-modal--full`: fill the viewport, square corners, no offset.
+              'inset-0 h-screen max-h-screen w-screen max-w-none translate-x-0 translate-y-0 rounded-none sm:max-w-none'
+            : contentClassName,
+        )}
+      >
+        {/* A form wrapper so Enter in any field submits (fires onSubmit); the primary
+            button is type="submit". `min-w-0` + flex-col so the body can scroll and the
+            wide posting table shrinks rather than stretching the modal. */}
+        <form
+          onSubmit={(e) => {
+            e.preventDefault();
+            if (!busy) onSubmit?.();
+          }}
+          className="flex min-w-0 flex-1 flex-col overflow-hidden"
+        >
+          <DialogHeader>
+            <DialogTitle>{title}</DialogTitle>
+            {description && <DialogDescription>{description}</DialogDescription>}
+          </DialogHeader>
+
+          {/* Scrollable body: `min-w-0` propagates the shrink to children; `overflow-y-auto`
+              keeps a tall assignments editor inside the modal. */}
+          <div className="mt-4 mb-6 min-w-0 flex-1 space-y-4 overflow-y-auto">
+            {children}
+            {error && (
+              <Alert variant="destructive">
+                <AlertDescription>{error}</AlertDescription>
+              </Alert>
+            )}
+          </div>
+
+          <DialogFooter>
+            <Button
+              type="button"
+              variant="ghost"
+              onClick={onClose}
+              disabled={busy}
+              className="w-full sm:w-auto"
+            >
+              {cancelLabel}
+            </Button>
+            <Button type="submit" disabled={busy} className="w-full sm:w-auto">
+              {busy && <Loader2 className="size-4 animate-spin" />}
+              {submitLabel}
+            </Button>
+          </DialogFooter>
+        </form>
+
+        {/* Expand / collapse (full-screen) toggle — sits to the LEFT of the Dialog's own
+            close X (which is `absolute top-4 right-4`). OCA's modal expand affordance. */}
+        {expandable && (
+          <button
+            type="button"
+            onClick={() => setExpanded((v) => !v)}
+            aria-label={expanded ? 'Exit full screen' : 'Expand to full screen'}
+            title={expanded ? 'Exit full screen' : 'Expand to full screen'}
+            className="ring-offset-background focus:ring-ring absolute top-4 right-11 rounded-xs opacity-70 transition-opacity hover:opacity-100 focus:ring-2 focus:ring-offset-2 focus:outline-hidden disabled:pointer-events-none"
+          >
+            {expanded ? <Minimize2 className="size-4" /> : <Maximize2 className="size-4" />}
+          </button>
+        )}
+      </DialogContent>
+    </Dialog>
+  );
+}

package/template/frontend/src/components/EntityList.jsx

@@ -0,0 +1,480 @@
+/**
+ * EntityList — a reusable, server-driven OCA-styled DataTable for the identity
+ * management pages (Companies / Roles / Users). Re-skinned onto the shared shadcn
+ * `Table` primitive (`ui/table.tsx`, tuned to OCA's matured DataTable look —
+ * mono-uppercase headers, hairline borders, dense cells, row hover, a horizontal-
+ * scroll wrapper, and a STICKY-RIGHT actions column). Wrapped in a `Card` so it
+ * inherits the app's light/dark card depth.
+ *
+ * SERVER-DRIVEN (OCA DataTable pattern): this component is CONTROLLED by the page.
+ * It renders a search box, sortable column headers, and a footer pager, but owns NO
+ * query state — the page holds `{ page, limit, search, sortBy, sortOrder }`, refetches
+ * on any change, and passes rows + total + that state + the change callbacks down.
+ * Search is DEBOUNCED (~300ms) inside the component so keystrokes don't spam the
+ * server; sorting + paging fire immediately. This fixes the real bug: the list no
+ * longer silently caps at the engine's default page — it pages the true `total`, and
+ * search + sort run on the SERVER (not a client filter over one page).
+ *
+ * Responsive: at ≤640px the table REFLOWS to a stack of cards — each row becomes a
+ * card of label:value pairs with the row's actions beneath — instead of only
+ * horizontal-scrolling. Desktop keeps the table with the sticky actions column.
+ *
+ * ⛔ NEVER renders a raw UUID as visible text. Each column supplies a `key` (or a
+ * `render(row)`) that resolves to a display NAME/label; the row's uuid lives only in
+ * `row.id`, used as the React key + handed to onEdit/onDelete for routing — never shown.
+ *
+ * Props:
+ *   title       — card heading (e.g. "Companies")
+ *   description — optional sub-line under the heading
+ *   icon        — optional lucide icon component for the heading
+ *   columns     — [{ key, label, render?, sortable?, sortKey? }]
+ *                 render(row) wins over row.fields[key]; sortable columns get a
+ *                 clickable header (sortKey defaults to key) that toggles asc→desc.
+ *   rows        — [{ id, fields:{…} }] (the engine list shape, ONE page)
+ *   total       — the FILTERED total row count (from the server) — drives the pager
+ *   page        — current 1-based page (controlled)
+ *   limit       — current page size (controlled)
+ *   search      — current search term (controlled)
+ *   sortBy      — current sort field key ('' = unsorted, controlled)
+ *   sortOrder   — 'asc' | 'desc' (controlled)
+ *   loading     — show a loading line
+ *   error       — an error string (e.g. a graceful 403 message) shown instead of rows
+ *   emptyLabel  — text for the no-rows state
+ *   searchPlaceholder — placeholder for the search box (default "Search…")
+ *   addLabel    — the Add button label (default "Add")
+ *   pageSizes   — selectable page sizes (default [10, 25, 50])
+ *   onAdd       — () => void
+ *   onEdit      — (row) => void
+ *   onDelete    — (row) => void
+ *   onSearchChange — (term: string) => void      (page resets to 1)
+ *   onSortChange   — (sortBy: string, sortOrder) => void
+ *   onPageChange   — (page: number) => void
+ *   onLimitChange  — (limit: number) => void      (page resets to 1)
+ */
+import { useEffect, useRef, useState } from 'react';
+import {
+  ArrowUpDown,
+  ChevronDown,
+  ChevronLeft,
+  ChevronRight,
+  ChevronUp,
+  Loader2,
+  Pencil,
+  Plus,
+  Search,
+  Trash2,
+} from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from '@/components/ui/card';
+import { Alert, AlertDescription } from '@/components/ui/alert';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui/table';
+
+/** Resolve one cell's DISPLAY value — render(row) if given, else row.fields[key]. */
+function cellValue(col, row) {
+  if (typeof col.render === 'function') return col.render(row);
+  const v = row?.fields?.[col.key];
+  return v === null || v === undefined || v === '' ? '—' : v;
+}
+
+/** The sort key a column sorts by — explicit `sortKey`, else its `key`. */
+function colSortKey(col) {
+  return col.sortKey ?? col.key;
+}
+
+/** The Edit / Delete action buttons — shared by the desktop cell + the mobile card. */
+function RowActions({ row, onEdit, onDelete }) {
+  return (
+    <div className="flex items-center justify-end gap-1">
+      {onEdit && (
+        <Button type="button" variant="ghost" size="sm" onClick={() => onEdit(row)}>
+          <Pencil className="size-4" />
+          Edit
+        </Button>
+      )}
+      {onDelete && (
+        <Button
+          type="button"
+          variant="ghost"
+          size="sm"
+          className="text-destructive hover:bg-destructive/10 hover:text-destructive"
+          onClick={() => onDelete(row)}
+        >
+          <Trash2 className="size-4" />
+          Delete
+        </Button>
+      )}
+    </div>
+  );
+}
+
+/**
+ * A debounced search input. Holds the keystrokes locally and only calls
+ * `onSearchChange` after `delay` ms of quiet — so typing doesn't hit the server on
+ * every character. Stays in sync if the controlled `value` prop changes externally
+ * (e.g. a reset).
+ */
+function SearchBox({ value, onSearchChange, placeholder = 'Search…', delay = 300 }) {
+  const [draft, setDraft] = useState(value ?? '');
+  const timer = useRef(null);
+  // Sync down when the controlled value changes from the outside (not our own keystroke).
+  useEffect(() => {
+    setDraft(value ?? '');
+  }, [value]);
+
+  const onChange = (e) => {
+    const next = e.target.value;
+    setDraft(next);
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = setTimeout(() => {
+      onSearchChange?.(next);
+    }, delay);
+  };
+
+  // Flush any pending debounce on unmount.
+  useEffect(() => () => timer.current && clearTimeout(timer.current), []);
+
+  return (
+    <div className="relative w-full sm:w-56">
+      <Search className="pointer-events-none absolute left-2.5 top-1/2 size-4 -translate-y-1/2 text-muted-foreground" />
+      <Input
+        type="search"
+        value={draft}
+        onChange={onChange}
+        placeholder={placeholder}
+        className="h-9 pl-8"
+        aria-label="Search"
+      />
+    </div>
+  );
+}
+
+/**
+ * EntityListControls — the search box + Add button, extracted so a page can place them
+ * INLINE with its PageHeader (right-aligned) instead of inside the list card. Renders
+ * nothing it isn't wired for (search only if `onSearchChange`, Add only if `onAdd`).
+ */
+export function EntityListControls({
+  search = '',
+  onSearchChange,
+  searchPlaceholder = 'Search…',
+  addLabel = 'Add',
+  onAdd,
+}) {
+  const showSearch = Boolean(onSearchChange);
+  if (!showSearch && !onAdd) return null;
+  return (
+    <>
+      {showSearch && (
+        <div className="min-w-0 flex-1 sm:flex-none">
+          <SearchBox
+            value={search}
+            onSearchChange={onSearchChange}
+            placeholder={searchPlaceholder}
+          />
+        </div>
+      )}
+      {onAdd && (
+        <Button type="button" size="sm" onClick={onAdd} className="shrink-0">
+          <Plus className="size-4" />
+          {addLabel}
+        </Button>
+      )}
+    </>
+  );
+}
+
+/**
+ * EntityListPager — the footer pager (rows-per-page + range + Prev/Next), extracted so a
+ * page can render it OUTSIDE/below the list card. Renders only when paging is wired and
+ * there's a result to page (or while loading, to avoid flicker).
+ */
+export function EntityListPager({
+  total = 0,
+  page = 1,
+  limit = 25,
+  loading = false,
+  error = '',
+  pageSizes = [10, 25, 50],
+  onPageChange,
+  onLimitChange,
+}) {
+  const showPager = Boolean(onPageChange || onLimitChange);
+  if (!showPager || error || !(total > 0 || loading)) return null;
+  return (
+    <TableFooterBar
+      total={total}
+      page={page}
+      limit={limit}
+      pageSizes={pageSizes}
+      onPageChange={onPageChange}
+      onLimitChange={onLimitChange}
+    />
+  );
+}
+
+/**
+ * A sortable header cell. Clicking cycles the sort for this column: if it isn't the
+ * active sort → asc; if active asc → desc; if active desc → asc (a simple asc↔desc
+ * toggle once engaged). Shows a chevron for the active direction, a neutral
+ * up/down glyph otherwise.
+ */
+function SortableHead({ col, sortBy, sortOrder, onSortChange }) {
+  const key = colSortKey(col);
+  const active = sortBy === key;
+  const nextOrder = active && sortOrder === 'asc' ? 'desc' : 'asc';
+  const Indicator = !active ? ArrowUpDown : sortOrder === 'desc' ? ChevronDown : ChevronUp;
+  return (
+    <TableHead>
+      <button
+        type="button"
+        onClick={() => onSortChange?.(key, nextOrder)}
+        className="-mx-1 -my-1 inline-flex items-center gap-1 rounded px-1 py-1 hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        aria-label={`Sort by ${col.label}`}
+      >
+        {col.label}
+        <Indicator
+          className={active ? 'size-3.5 text-foreground' : 'size-3.5 text-muted-foreground/60'}
+        />
+      </button>
+    </TableHead>
+  );
+}
+
+/**
+ * The footer pager — "X–Y of N", a page-size selector, and Prev/Next. Mono, subtle
+ * (OCA's `.oca-dt-foot` look). Prev disabled on page 1; Next disabled on the last page.
+ */
+function TableFooterBar({ total, page, limit, pageSizes, onPageChange, onLimitChange }) {
+  const totalPages = Math.max(1, Math.ceil(total / Math.max(1, limit)));
+  const safePage = Math.min(Math.max(1, page), totalPages);
+  const from = total === 0 ? 0 : (safePage - 1) * limit + 1;
+  const to = Math.min(total, safePage * limit);
+
+  return (
+    <div className="mt-3 flex flex-wrap items-center justify-between gap-3 px-1 text-xs">
+      <div className="flex items-center gap-2 text-muted-foreground">
+        <span>Rows per page</span>
+        <Select value={String(limit)} onValueChange={(v) => onLimitChange?.(Number(v))}>
+          <SelectTrigger className="h-8 w-[4.5rem]" aria-label="Rows per page">
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            {pageSizes.map((n) => (
+              <SelectItem key={n} value={String(n)}>
+                {n}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </div>
+
+      <div className="flex items-center gap-3">
+        <span className="font-mono tabular-nums text-muted-foreground">
+          {from}–{to} of {total}
+        </span>
+        <div className="flex items-center gap-1">
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            className="h-8 px-2"
+            onClick={() => onPageChange?.(safePage - 1)}
+            disabled={safePage <= 1}
+            aria-label="Previous page"
+          >
+            <ChevronLeft className="size-4" />
+            Prev
+          </Button>
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            className="h-8 px-2"
+            onClick={() => onPageChange?.(safePage + 1)}
+            disabled={safePage >= totalPages}
+            aria-label="Next page"
+          >
+            Next
+            <ChevronRight className="size-4" />
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default function EntityList({
+  title,
+  description,
+  icon: Icon,
+  columns = [],
+  rows = [],
+  search = '',
+  sortBy = '',
+  sortOrder = 'asc',
+  loading = false,
+  error = '',
+  emptyLabel = 'Nothing here yet.',
+  onEdit,
+  onDelete,
+  onSortChange,
+}) {
+  const hasActions = Boolean(onEdit || onDelete);
+
+  return (
+    <Card className="gap-0 overflow-hidden py-0">
+      {/* Card header carries ONLY the title/description now — the search + Add controls
+          moved OUT to the page's PageHeader (via <EntityListControls/>), and the pager
+          moved BELOW the card (via <EntityListPager/>). Rendered only when a title or
+          description is supplied; a page that shows its title elsewhere can omit both. */}
+      {(title || description) && (
+        <CardHeader>
+          {title && (
+            <CardTitle className="flex items-center gap-2 text-base">
+              {Icon && <Icon className="size-4 text-primary" />}
+              {title}
+            </CardTitle>
+          )}
+          {description && <CardDescription className="mt-1">{description}</CardDescription>}
+        </CardHeader>
+      )}
+      <CardContent className="p-0">
+        {error ? (
+          <Alert variant="destructive" className="m-4 w-auto">
+            <AlertDescription>{error}</AlertDescription>
+          </Alert>
+        ) : (
+          <>
+            {/* Desktop / tablet: the OCA table with a sticky-right Actions column. The
+                table SHELL (header row) always renders — on no rows / no search results
+                the body shows a single "No records found" row instead of the table
+                vanishing (loading shows a spinner row). Total column count = data columns
+                + the actions column, so the empty/loading cell spans the full width. */}
+            <div className="hidden sm:block">
+              <Table>
+                <TableHeader>
+                  <TableRow className="hover:bg-transparent">
+                    {columns.map((col) =>
+                      col.sortable && onSortChange ? (
+                        <SortableHead
+                          key={col.key ?? col.label}
+                          col={col}
+                          sortBy={sortBy}
+                          sortOrder={sortOrder}
+                          onSortChange={onSortChange}
+                        />
+                      ) : (
+                        <TableHead key={col.key ?? col.label}>{col.label}</TableHead>
+                      ),
+                    )}
+                    {hasActions && <TableHead sticky>Actions</TableHead>}
+                  </TableRow>
+                </TableHeader>
+                <TableBody>
+                  {loading ? (
+                    <TableRow className="hover:bg-transparent">
+                      <TableCell colSpan={columns.length + (hasActions ? 1 : 0)}>
+                        <div className="flex items-center justify-center gap-2 py-8 text-sm text-muted-foreground">
+                          <Loader2 className="size-4 animate-spin" />
+                          Loading…
+                        </div>
+                      </TableCell>
+                    </TableRow>
+                  ) : rows.length === 0 ? (
+                    <TableRow className="hover:bg-transparent">
+                      <TableCell colSpan={columns.length + (hasActions ? 1 : 0)}>
+                        <p className="py-8 text-center text-sm text-muted-foreground">
+                          {search ? `No records found for “${search}”.` : emptyLabel}
+                        </p>
+                      </TableCell>
+                    </TableRow>
+                  ) : (
+                    rows.map((row, i) => (
+                      <TableRow key={typeof row.id === 'string' ? row.id : i}>
+                        {columns.map((col) => (
+                          <TableCell key={col.key ?? col.label}>{cellValue(col, row)}</TableCell>
+                        ))}
+                        {hasActions && (
+                          <TableCell sticky>
+                            <RowActions row={row} onEdit={onEdit} onDelete={onDelete} />
+                          </TableCell>
+                        )}
+                      </TableRow>
+                    ))
+                  )}
+                </TableBody>
+              </Table>
+            </div>
+
+            {/* Mobile (≤640px): the table reflows to a stack of cards — each row is a
+                card of label:value pairs, actions beneath. Loading + empty states mirror
+                the desktop table (message stays inside the card region). */}
+            <div className="space-y-3 sm:hidden">
+              {loading ? (
+                <div className="flex items-center justify-center gap-2 py-8 text-sm text-muted-foreground">
+                  <Loader2 className="size-4 animate-spin" />
+                  Loading…
+                </div>
+              ) : rows.length === 0 ? (
+                <p className="py-8 text-center text-sm text-muted-foreground">
+                  {search ? `No records found for “${search}”.` : emptyLabel}
+                </p>
+              ) : (
+                rows.map((row, i) => (
+                  <div
+                    key={typeof row.id === 'string' ? row.id : i}
+                    className="rounded-lg border border-border bg-background p-3"
+                  >
+                    <dl className="space-y-2">
+                      {columns.map((col) => (
+                        <div
+                          key={col.key ?? col.label}
+                          className="flex items-start justify-between gap-3"
+                        >
+                          <dt className="font-mono text-[0.62rem] font-semibold uppercase tracking-[0.08em] text-muted-foreground">
+                            {col.label}
+                          </dt>
+                          <dd className="min-w-0 text-right text-sm text-foreground/90">
+                            {cellValue(col, row)}
+                          </dd>
+                        </div>
+                      ))}
+                    </dl>
+                    {hasActions && (
+                      <div className="mt-3 border-t border-border pt-2">
+                        <RowActions row={row} onEdit={onEdit} onDelete={onDelete} />
+                      </div>
+                    )}
+                  </div>
+                ))
+              )}
+            </div>
+          </>
+        )}
+        {/* The pager now lives OUTSIDE the card — render <EntityListPager/> below the
+            <EntityList/> in the page. */}
+      </CardContent>
+    </Card>
+  );
+}

package/template/frontend/src/components/PageHeader.jsx

@@ -0,0 +1,54 @@
+/**
+ * PageHeader — the top-of-page header for the management screens: a bold page title
+ * with a breadcrumb underneath (replacing the old one-line sub-description). The
+ * breadcrumb moved OUT of the app header (top bar) and down here so it sits with the
+ * content it labels.
+ *
+ * The breadcrumb reads "Section › Page" (e.g. Identity › Companies) — the section is a
+ * plain muted segment, the current page is emphasized. The leading icon sits beside the
+ * HEADING (not the breadcrumb), echoing the app's identity motif. When no `section` is
+ * given the breadcrumb shows just the page crumb.
+ *
+ * Props:
+ *   title    — the page heading (also the last, emphasized breadcrumb crumb)
+ *   section  — optional parent section label (e.g. "Identity") shown before the page
+ *   icon     — optional lucide icon shown beside the heading (default Shield)
+ *   actions  — optional node rendered right-aligned INLINE with the title on desktop;
+ *              wraps below the title on small screens (e.g. a list's search + Add button).
+ */
+import { ChevronRight, Shield } from 'lucide-react';
+
+export default function PageHeader({ title, section, icon: Icon = Shield, actions }) {
+  const titleAndCrumb = (
+    <div className="min-w-0">
+      <h1 className="flex items-center gap-2 text-xl font-bold tracking-tight">
+        <Icon className="size-5 text-primary" />
+        {title}
+      </h1>
+      {/* Breadcrumb (relocated from the app header): Section › Page — no leading icon. */}
+      <nav aria-label="Breadcrumb" className="mt-1 flex items-center gap-2 text-sm text-muted-foreground">
+        {section ? (
+          <>
+            <span>{section}</span>
+            <ChevronRight className="size-3" />
+            <span className="font-medium text-foreground">{title}</span>
+          </>
+        ) : (
+          <span className="font-medium text-foreground">{title}</span>
+        )}
+      </nav>
+    </div>
+  );
+
+  // Desktop: title+breadcrumb (left) and actions (right) on ONE row, vertically centred.
+  // Mobile (≤640px): stack — title, then breadcrumb, then the actions BELOW (full-width),
+  // achieved by the flex-col order (actions come after the title/crumb block).
+  return (
+    <div className="mb-4 flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+      {titleAndCrumb}
+      {actions && (
+        <div className="flex shrink-0 items-center gap-2 max-sm:w-full">{actions}</div>
+      )}
+    </div>
+  );
+}