create-astram-app 0.1.2 → 0.2.0

package/template/frontend/src/pages/audit/AuditPage.jsx

@@ -0,0 +1,268 @@
+/**
+ * AuditPage — the read-only Audit log viewer. Mirrors the structure of
+ * `pages/access/AccessPage.jsx` (AppShell + PageHeader + EntityList wiring, the same
+ * useAuth()/useSearchParams()/useCallback `load()` shape) but is IMMUTABLE: no add/edit/
+ * delete, no row-action menu, no routed-modal child routes — audit events cannot be
+ * changed from here.
+ *
+ * Paging is CURSOR-based (`before` / `nextCursor`), not page-number based — the backend
+ * (`@astram/frontend-core`'s `createAuditService().list()`) returns `{ ok, data, nextCursor }`, not
+ * a `total`/`page` shape, so `EntityListPager` (which drives page/limit) does not fit; a
+ * simple Prev/Next pair built from the existing `Button` primitive drives the cursor
+ * instead (no new reusable component — same primitives EntityList itself imports).
+ *
+ * ⛔ No raw UUIDs: rows carry NONE (the backend already strips ids — `AuditReadService`
+ * server-side). Only `actorLabel` / `tenantLabel` / `action` / `occurredAt` / `detail` are
+ * ever rendered.
+ *
+ * Tenant column: audit rows always carry a `tenantLabel` (the server auto-scopes a non-
+ * root to their own tenant already), but the column is only USEFUL for a
+ * root (whose results can legitimately span tenants) — for anyone else, every row's
+ * tenantLabel is trivially their own tenant, so the column is hidden as noise. The current
+ * `useAuth().profile` (`GET /auth/me` DTO) does not yet expose an `isRoot`
+ * flag (see `profile-resolver.ts`); this reads it defensively as `profile?.isRoot`
+ * (safe no-op today) OR'd with a same-page fallback signal that needs no backend change:
+ * the column also shows itself the moment the loaded rows actually contain more than one
+ * distinct tenantLabel (which can only happen for a root, since a non-root's
+ * results are pinned to one tenant server-side) — so real multi-tenant data is never
+ * hidden even before the profile flag exists.
+ */
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useSearchParams } from 'react-router-dom';
+import { History } from 'lucide-react';
+import { useAuth } from '@/auth/AuthContext';
+import AppShell from '@/shell/AppShell';
+import PageHeader from '@/components/PageHeader';
+import EntityList from '@/components/EntityList';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+
+/** Readable absolute date-time — e.g. "13 Jul 2026, 4:05 PM"; '—' when missing/invalid. */
+function formatDateTime(ms) {
+  if (!ms && ms !== 0) return '—';
+  const d = new Date(ms);
+  return Number.isNaN(d.getTime()) ? '—' : d.toLocaleString();
+}
+
+/** Compact "key: value, key: value" rendering of the detail map; '—' when empty. */
+function formatDetail(detail) {
+  const entries = Object.entries(detail || {});
+  if (entries.length === 0) return '—';
+  return entries
+    .map(([k, v]) => `${k}: ${typeof v === 'object' && v !== null ? JSON.stringify(v) : v}`)
+    .join(', ');
+}
+
+/** Seed the filter state from the URL so a reload / shared link restores the view. */
+function readQueryFromParams(sp) {
+  return {
+    type: sp.get('type') || '',
+    actor: sp.get('actor') || '',
+    tenant: sp.get('tenant') || '',
+    before: sp.get('before') || undefined,
+  };
+}
+
+const DEFAULT_LIMIT = 25;
+
+export default function AuditPage() {
+  const { tokens, audit, profile } = useAuth();
+  const token = tokens?.accessToken;
+  const [searchParams, setSearchParams] = useSearchParams();
+
+  const [rows, setRows] = useState([]);
+  const [nextCursor, setNextCursor] = useState(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState('');
+
+  // `query` holds the filters + the cursor stack (so "Prev" can pop back). `before` is the
+  // cursor for the CURRENT page (undefined = first page).
+  const [query, setQuery] = useState(() => readQueryFromParams(searchParams));
+  const [cursorStack, setCursorStack] = useState([]); // history of `before` values for Prev
+
+  // query (minus paging) → URL (replace, no history spam) — mirrors AccessPage.
+  useEffect(() => {
+    const p = new URLSearchParams();
+    if (query.type) p.set('type', query.type);
+    if (query.actor) p.set('actor', query.actor);
+    if (query.tenant) p.set('tenant', query.tenant);
+    setSearchParams(p, { replace: true });
+  }, [query.type, query.actor, query.tenant, setSearchParams]);
+
+  const load = useCallback(async () => {
+    if (!token) return;
+    setLoading(true);
+    const r = await audit.list(token, {
+      ...(query.type ? { type: query.type } : {}),
+      ...(query.actor ? { actor: query.actor } : {}),
+      ...(query.tenant ? { tenant: query.tenant } : {}),
+      ...(query.before ? { before: query.before } : {}),
+      limit: DEFAULT_LIMIT,
+    });
+    if (r.ok) {
+      setRows(r.data || []);
+      setNextCursor(r.nextCursor || null);
+      setError('');
+    } else {
+      setRows([]);
+      setNextCursor(null);
+      setError(r.error || 'Could not load the audit log.');
+    }
+    setLoading(false);
+  }, [audit, token, query]);
+
+  useEffect(() => {
+    load();
+  }, [load]);
+
+  // Any filter change starts a fresh cursor walk (reset inline, not in an effect).
+  const onTypeChange = useCallback((e) => {
+    setCursorStack([]);
+    setQuery((q) => ({ ...q, type: e.target.value, before: undefined }));
+  }, []);
+  const onActorChange = useCallback((e) => {
+    setCursorStack([]);
+    setQuery((q) => ({ ...q, actor: e.target.value, before: undefined }));
+  }, []);
+  const onTenantChange = useCallback((e) => {
+    setCursorStack([]);
+    setQuery((q) => ({ ...q, tenant: e.target.value, before: undefined }));
+  }, []);
+
+  const onNext = useCallback(() => {
+    if (!nextCursor) return;
+    setCursorStack((s) => [...s, query.before]);
+    setQuery((q) => ({ ...q, before: nextCursor }));
+  }, [nextCursor, query.before]);
+
+  const onPrev = useCallback(() => {
+    setCursorStack((s) => {
+      if (s.length === 0) return s;
+      const prevCursor = s[s.length - 1];
+      setQuery((q) => ({ ...q, before: prevCursor }));
+      return s.slice(0, -1);
+    });
+  }, []);
+
+  // Root tenant-column gating: prefer the profile flag once it exists; until then,
+  // fall back to detecting real multi-tenant results in the loaded page (see file header).
+  const showTenantColumn = useMemo(() => {
+    if (profile?.isRoot) return true;
+    const distinctTenants = new Set(rows.map((r) => r.tenantLabel).filter(Boolean));
+    return distinctTenants.size > 1;
+  }, [profile, rows]);
+
+  const columns = useMemo(() => {
+    const cols = [
+      {
+        key: 'occurredAt',
+        label: 'Time',
+        render: (row) => (
+          <span className="whitespace-nowrap text-sm text-foreground">
+            {formatDateTime(row.occurredAt)}
+          </span>
+        ),
+      },
+      {
+        key: 'actorLabel',
+        label: 'Actor',
+        render: (row) => <span className="text-sm text-foreground">{row.actorLabel || '—'}</span>,
+      },
+      {
+        key: 'action',
+        label: 'Action',
+        render: (row) => (
+          <Badge variant="info" className="font-normal">
+            {row.action || '(event)'}
+          </Badge>
+        ),
+      },
+    ];
+    if (showTenantColumn) {
+      cols.push({
+        key: 'tenantLabel',
+        label: 'Tenant',
+        render: (row) => <span className="text-sm text-foreground">{row.tenantLabel || '—'}</span>,
+      });
+    }
+    cols.push({
+      key: 'detail',
+      label: 'Detail',
+      render: (row) => (
+        <span className="text-xs text-muted-foreground">{formatDetail(row.detail)}</span>
+      ),
+    });
+    return cols;
+  }, [showTenantColumn]);
+
+  return (
+    <AppShell section="Identity" title="Audit">
+      <div className="p-4">
+        <PageHeader
+          section="Identity"
+          title="Audit"
+          icon={History}
+          actions={
+            <div className="flex flex-wrap items-center gap-2">
+              <Input
+                value={query.type}
+                onChange={onTypeChange}
+                placeholder="Filter by action…"
+                className="h-9 w-40"
+                aria-label="Filter by action"
+              />
+              <Input
+                value={query.actor}
+                onChange={onActorChange}
+                placeholder="Filter by actor…"
+                className="h-9 w-40"
+                aria-label="Filter by actor"
+              />
+              {showTenantColumn && (
+                <Input
+                  value={query.tenant}
+                  onChange={onTenantChange}
+                  placeholder="Filter by tenant…"
+                  className="h-9 w-40"
+                  aria-label="Filter by tenant"
+                />
+              )}
+            </div>
+          }
+        />
+
+        <EntityList
+          columns={columns}
+          rows={rows}
+          loading={loading}
+          error={error}
+          emptyLabel="No audit events."
+        />
+
+        {!error && (rows.length > 0 || loading) && (
+          <div className="mt-3 flex items-center justify-end gap-2">
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              onClick={onPrev}
+              disabled={cursorStack.length === 0 || loading}
+            >
+              Prev
+            </Button>
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              onClick={onNext}
+              disabled={!nextCursor || loading}
+            >
+              Next
+            </Button>
+          </div>
+        )}
+      </div>
+    </AppShell>
+  );
+}

package/template/frontend/src/pages/companies/CompaniesPage.jsx

@@ -0,0 +1,232 @@
+/**
+ * CompaniesPage — the Companies management screen: a list of companies with routed-modal
+ * Add/Edit and a themed delete confirm. This is a LAYOUT route: it owns the list and
+ * renders `<Outlet context={{ onRefresh }} />`, so the Add/Edit child routes
+ * (/companies/add, /companies/edit/:uuid) render CompanyForm as an overlay on top of the
+ * still-mounted list and can trigger a re-fetch on success.
+ *
+ * Data loads on mount via the shared identity client service (mirrors TwoFactorPage's
+ * load-on-mount + refresh pattern). Companies management is root-only server-side;
+ * a non-root gets a 403 which we render as a graceful "need platform-admin access"
+ * message (the EntityList `error` state) rather than a broken screen.
+ *
+ * ⛔ No raw UUIDs: columns render `fields.name` / `fields.status`; the row uuid (`row.id`)
+ * is used only as a key and for routing to the edit page.
+ */
+import { useCallback, useEffect, useState } from 'react';
+import { Outlet, useNavigate, useSearchParams } from 'react-router-dom';
+import { Building2 } from 'lucide-react';
+import { toast } from 'sonner';
+import { useAuth } from '@/auth/AuthContext';
+import AppShell from '@/shell/AppShell';
+import PageHeader from '@/components/PageHeader';
+import EntityList, { EntityListControls, EntityListPager } from '@/components/EntityList';
+import ConfirmDialog from '@/components/ConfirmDialog';
+import { Badge } from '@/components/ui/badge';
+
+/** Compact absolute date — e.g. "13 Jul 2026"; '—' when missing/invalid. */
+function formatDate(v) {
+  if (!v) return '—';
+  try {
+    return new Date(v).toLocaleDateString(undefined, {
+      day: 'numeric',
+      month: 'short',
+      year: 'numeric',
+    });
+  } catch {
+    return '—';
+  }
+}
+
+// Sortable columns (server-side): Name, Status, Created. `sortKey` is the engine field KEY.
+const COLUMNS = [
+  {
+    key: 'name',
+    label: 'Name',
+    sortable: true,
+    sortKey: 'name',
+    render: (row) => row.fields?.name || '(unnamed)',
+  },
+  {
+    key: 'status',
+    label: 'Status',
+    sortable: true,
+    sortKey: 'status',
+    render: (row) => {
+      const status = row.fields?.status || 'active';
+      return (
+        <Badge variant={status === 'active' ? 'success' : 'secondary'} className="capitalize">
+          {status}
+        </Badge>
+      );
+    },
+  },
+  {
+    key: 'createdAt',
+    label: 'Created',
+    sortable: true,
+    sortKey: 'createdAt',
+    render: (row) => formatDate(row.fields?.createdAt),
+  },
+];
+
+const DEFAULT_LIMIT = 25;
+
+/**
+ * Seed the initial DataTable query from the URL so a reload / shared link restores
+ * EXACTLY the view (page + limit + search + sortBy + sortOrder). Absent params fall
+ * back to the defaults; values are clamped/guarded so a hand-edited URL can't poison state.
+ */
+function readQueryFromParams(sp) {
+  const page = Number.parseInt(sp.get('page') ?? '', 10);
+  const limit = Number.parseInt(sp.get('limit') ?? '', 10);
+  const sortOrder = (sp.get('sortOrder') || '').toLowerCase();
+  return {
+    page: Number.isFinite(page) && page >= 1 ? page : 1,
+    limit: Number.isFinite(limit) && limit >= 1 && limit <= 200 ? limit : DEFAULT_LIMIT,
+    search: sp.get('search') || '',
+    sortBy: sp.get('sortBy') || 'createdAt',
+    sortOrder: sortOrder === 'asc' || sortOrder === 'desc' ? sortOrder : 'desc',
+  };
+}
+
+export default function CompaniesPage() {
+  const { tokens, identity } = useAuth();
+  const token = tokens?.accessToken;
+  const navigate = useNavigate();
+  const [searchParams, setSearchParams] = useSearchParams();
+
+  const [rows, setRows] = useState([]);
+  const [total, setTotal] = useState(0);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState('');
+
+  // The DataTable query state — the PAGE owns it; EntityList is controlled by it.
+  // Seed ONCE from the URL (initializer runs only on mount) → single source of truth.
+  const [query, setQuery] = useState(() => readQueryFromParams(searchParams));
+
+  // Sync query → URL on every change (replace:true — no history spam). Only non-default
+  // page/limit/search are emitted to keep the URL clean; sortBy/sortOrder are always
+  // meaningful so they're always emitted. Reads only `query` — never the URL — so no loop.
+  useEffect(() => {
+    const p = new URLSearchParams();
+    if (query.page > 1) p.set('page', String(query.page));
+    if (query.limit !== DEFAULT_LIMIT) p.set('limit', String(query.limit));
+    if (query.search) p.set('search', query.search);
+    if (query.sortBy) p.set('sortBy', query.sortBy);
+    if (query.sortOrder) p.set('sortOrder', query.sortOrder);
+    setSearchParams(p, { replace: true });
+  }, [query, setSearchParams]);
+
+  // Delete confirm state (ConfirmDialog — the API fires ONLY from onConfirm).
+  const [deleteTarget, setDeleteTarget] = useState(null);
+  const [deleteBusy, setDeleteBusy] = useState(false);
+
+  const load = useCallback(async () => {
+    if (!token) return;
+    setLoading(true);
+    const r = await identity.listCompanies(token, query);
+    if (r.ok) {
+      setRows(r.rows || []);
+      setTotal(r.total || 0);
+      setError('');
+    } else {
+      setRows([]);
+      setTotal(0);
+      setError(r.error || 'Could not load companies.');
+    }
+    setLoading(false);
+  }, [identity, token, query]);
+
+  useEffect(() => {
+    load();
+  }, [load]);
+
+  // Query-change handlers: search/limit reset to page 1; sort toggles asc↔desc.
+  const onSearchChange = useCallback(
+    (search) => setQuery((q) => ({ ...q, search, page: 1 })),
+    [],
+  );
+  const onSortChange = useCallback(
+    (sortBy, sortOrder) => setQuery((q) => ({ ...q, sortBy, sortOrder })),
+    [],
+  );
+  const onPageChange = useCallback((page) => setQuery((q) => ({ ...q, page })), []);
+  const onLimitChange = useCallback(
+    (limit) => setQuery((q) => ({ ...q, limit, page: 1 })),
+    [],
+  );
+
+  const onConfirmDelete = async () => {
+    if (!deleteTarget) return;
+    setDeleteBusy(true);
+    const r = await identity.deleteCompany(token, deleteTarget.id);
+    setDeleteBusy(false);
+    if (!r.ok) {
+      toast.error(r.error || 'Could not delete the company.');
+      return;
+    }
+    setDeleteTarget(null);
+    toast.success('Company deleted');
+    await load();
+  };
+
+  return (
+    <AppShell section="Identity" title="Companies">
+      <div className="p-4">
+        <PageHeader
+          section="Identity"
+          title="Companies"
+          icon={Building2}
+          actions={
+            <EntityListControls
+              search={query.search}
+              onSearchChange={onSearchChange}
+              searchPlaceholder="Search companies…"
+              addLabel="Add company"
+              onAdd={() => navigate('/companies/add')}
+            />
+          }
+        />
+
+        <EntityList
+          columns={COLUMNS}
+          rows={rows}
+          search={query.search}
+          sortBy={query.sortBy}
+          sortOrder={query.sortOrder}
+          loading={loading}
+          error={error}
+          emptyLabel="No companies yet. Add one to get started."
+          onEdit={(row) => navigate(`/companies/edit/${row.id}`)}
+          onDelete={(row) => setDeleteTarget(row)}
+          onSortChange={onSortChange}
+        />
+
+        <EntityListPager
+          total={total}
+          page={query.page}
+          limit={query.limit}
+          loading={loading}
+          error={error}
+          onPageChange={onPageChange}
+          onLimitChange={onLimitChange}
+        />
+      </div>
+
+      {/* Add / Edit render here as a routed overlay; onRefresh re-fetches the list. */}
+      <Outlet context={{ onRefresh: load }} />
+
+      <ConfirmDialog
+        open={!!deleteTarget}
+        title={deleteTarget ? `Delete “${deleteTarget.fields?.name || 'this company'}”?` : 'Delete company?'}
+        message="This permanently removes the company and its memberships. This cannot be undone."
+        confirmLabel="Delete"
+        destructive
+        busy={deleteBusy}
+        onConfirm={onConfirmDelete}
+        onCancel={() => setDeleteTarget(null)}
+      />
+    </AppShell>
+  );
+}

package/template/frontend/src/pages/companies/CompanyForm.jsx

@@ -0,0 +1,127 @@
+/**
+ * CompanyForm — the Add/Edit company form, rendered as a routed-modal overlay by the
+ * /companies/add and /companies/edit/:uuid child routes (under CompaniesPage's layout).
+ * The SAME component serves add + edit: `useParams()` → a `:uuid` means edit (load the
+ * record first), else add. It closes via `navigate(-1)` (back-button semantics) and, on
+ * success, toasts + calls the layout's `onRefresh` (via `useOutletContext`) to re-fetch.
+ *
+ * Fields: Name (required) + Status (edit only — a new company defaults server-side).
+ * ⛔ The `:uuid` is a route param only — never rendered as visible text.
+ */
+import { useEffect, useState } from 'react';
+import { useNavigate, useOutletContext, useParams } from 'react-router-dom';
+import { toast } from 'sonner';
+import { useAuth } from '@/auth/AuthContext';
+import EntityFormModal from '@/components/EntityFormModal';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+
+export default function CompanyForm() {
+  const { tokens, identity } = useAuth();
+  const token = tokens?.accessToken;
+  const { uuid } = useParams();
+  const isEdit = Boolean(uuid);
+  const navigate = useNavigate();
+  const { onRefresh } = useOutletContext() ?? {};
+
+  const [name, setName] = useState('');
+  const [status, setStatus] = useState('active');
+  const [loading, setLoading] = useState(isEdit);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState('');
+
+  // On edit, load the current record so the form pre-fills with its display fields.
+  useEffect(() => {
+    if (!isEdit || !token) return undefined;
+    let active = true;
+    (async () => {
+      const r = await identity.getCompany(token, uuid);
+      if (!active) return;
+      if (r.ok) {
+        setName(r.record?.fields?.name || '');
+        setStatus(r.record?.fields?.status || 'active');
+      } else {
+        setError(r.error || 'Could not load the company.');
+      }
+      setLoading(false);
+    })();
+    return () => {
+      active = false;
+    };
+  }, [identity, token, uuid, isEdit]);
+
+  const close = () => navigate(-1);
+
+  const onSubmit = async () => {
+    const trimmed = name.trim();
+    if (!trimmed) {
+      setError('Enter a company name.');
+      return;
+    }
+    setError('');
+    setBusy(true);
+    const r = isEdit
+      ? await identity.updateCompany(token, uuid, { name: trimmed, status })
+      : await identity.createCompany(token, trimmed);
+    setBusy(false);
+    if (!r.ok) {
+      setError(r.error || 'Could not save the company.');
+      return;
+    }
+    toast.success(isEdit ? 'Company updated' : 'Company created');
+    onRefresh?.();
+    close();
+  };
+
+  return (
+    <EntityFormModal
+      title={isEdit ? 'Edit company' : 'Add company'}
+      description={isEdit ? undefined : 'Create a new tenant company.'}
+      open
+      onClose={close}
+      onSubmit={onSubmit}
+      submitLabel={isEdit ? 'Save changes' : 'Create company'}
+      busy={busy || loading}
+      error={error}
+    >
+      <div className="space-y-1.5">
+        <Label htmlFor="company-name" variant="field">
+          Name
+        </Label>
+        <Input
+          id="company-name"
+          autoFocus
+          maxLength={120}
+          placeholder="e.g. Acme Corp"
+          value={name}
+          disabled={loading}
+          onChange={(e) => setName(e.target.value)}
+        />
+      </div>
+
+      {isEdit && (
+        <div className="space-y-1.5">
+          <Label htmlFor="company-status" variant="field">
+            Status
+          </Label>
+          <Select value={status} disabled={loading} onValueChange={setStatus}>
+            <SelectTrigger id="company-status">
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="active">Active</SelectItem>
+              <SelectItem value="inactive">Inactive</SelectItem>
+            </SelectContent>
+          </Select>
+        </div>
+      )}
+    </EntityFormModal>
+  );
+}