create-astram-app 0.1.2 → 0.2.0

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>
+  );
+}

package/template/frontend/src/components/access/CollapsibleGroup.jsx

@@ -0,0 +1,34 @@
+/**
+ * CollapsibleGroup — a lightweight controlled collapsible for the Assign-access dialog's
+ * "permissions by object" groups (the design's accordion, built with our tokens since the
+ * component library has no accordion). Header bar (caret + title + an "X of Y" count badge)
+ * toggles the body. Purely presentational + controlled; the parent owns `open`.
+ */
+import { ChevronRight } from 'lucide-react';
+import { cn } from '@/lib/utils';
+import { Badge } from '@/components/ui/badge';
+
+export default function CollapsibleGroup({ title, count, total, open, onToggle, right, children }) {
+  return (
+    <div className="rounded-md border border-border">
+      <button
+        type="button"
+        onClick={onToggle}
+        className="flex w-full items-center gap-2 rounded-t-md bg-muted/60 px-3 py-2 text-left text-sm font-medium text-foreground hover:bg-muted"
+        aria-expanded={open}
+      >
+        <ChevronRight
+          className={cn('size-4 shrink-0 text-muted-foreground transition-transform', open && 'rotate-90')}
+        />
+        <span className="flex-1">{title}</span>
+        {typeof count === 'number' && typeof total === 'number' && (
+          <Badge variant="secondary" className="rounded-full font-normal">
+            {count} of {total}
+          </Badge>
+        )}
+        {right}
+      </button>
+      {open && <div className="border-t border-border p-3">{children}</div>}
+    </div>
+  );
+}