create-astram-app 0.1.3 → 0.3.0

package/template/frontend/src/pages/users/UserForm.jsx

@@ -0,0 +1,167 @@
+/**
+ * UserForm — the Add/Edit user form, rendered as a routed-modal overlay by /users/add
+ * and /users/edit/:uuid under UsersPage's layout. The SAME component serves add + edit
+ * via `useParams()` (a `:uuid` → edit, load first; else add). Closes via `navigate(-1)`;
+ * on success toasts + calls the layout's `onRefresh`.
+ *
+ * Fields: Username (required) + Email. On edit, Status is also editable.
+ *
+ * ⛔ The `:uuid` is a route param only — never rendered as visible text.
+ *
+ * PHASE 5 — the Assignments (membership + posting) editor is rendered on the EDIT path,
+ * BELOW these profile fields (a user must exist before it can be assigned into a company).
+ * On the ADD path it stays hidden (create the user first, then edit to assign). The edit
+ * modal widens to fit the multi-row posting tables.
+ */
+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 { Separator } from '@/components/ui/separator';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import AssignmentsEditor from './AssignmentsEditor';
+
+export default function UserForm() {
+  const { tokens, identity } = useAuth();
+  const token = tokens?.accessToken;
+  const { uuid } = useParams();
+  const isEdit = Boolean(uuid);
+  const navigate = useNavigate();
+  const { onRefresh } = useOutletContext() ?? {};
+
+  const [username, setUsername] = useState('');
+  const [email, setEmail] = 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.getUser(token, uuid);
+      if (!active) return;
+      if (r.ok) {
+        setUsername(r.record?.fields?.username || '');
+        setEmail(r.record?.fields?.email || '');
+        setStatus(r.record?.fields?.status || 'active');
+      } else {
+        setError(r.error || 'Could not load the user.');
+      }
+      setLoading(false);
+    })();
+    return () => {
+      active = false;
+    };
+  }, [identity, token, uuid, isEdit]);
+
+  const close = () => navigate(-1);
+
+  const onSubmit = async () => {
+    const trimmedUser = username.trim();
+    const trimmedEmail = email.trim();
+    if (!trimmedUser) {
+      setError('Enter a username.');
+      return;
+    }
+    setError('');
+    setBusy(true);
+    const r = isEdit
+      ? await identity.updateUser(token, uuid, {
+          username: trimmedUser,
+          email: trimmedEmail,
+          status,
+        })
+      : await identity.createUser(token, { username: trimmedUser, email: trimmedEmail });
+    setBusy(false);
+    if (!r.ok) {
+      setError(r.error || 'Could not save the user.');
+      return;
+    }
+    toast.success(isEdit ? 'User updated' : 'User created');
+    onRefresh?.();
+    close();
+  };
+
+  return (
+    <EntityFormModal
+      title={isEdit ? 'Edit user' : 'Add user'}
+      description={isEdit ? undefined : 'Create a new user.'}
+      open
+      onClose={close}
+      onSubmit={onSubmit}
+      submitLabel={isEdit ? 'Save changes' : 'Create user'}
+      busy={busy || loading}
+      error={error}
+      contentClassName={isEdit ? 'sm:max-w-2xl' : 'sm:max-w-md'}
+    >
+      <div className="space-y-1.5">
+        <Label htmlFor="user-username" variant="field">
+          Username
+        </Label>
+        <Input
+          id="user-username"
+          autoFocus
+          maxLength={120}
+          placeholder="e.g. jsmith"
+          value={username}
+          disabled={loading}
+          onChange={(e) => setUsername(e.target.value)}
+        />
+      </div>
+
+      <div className="space-y-1.5">
+        <Label htmlFor="user-email" variant="field">
+          Email
+        </Label>
+        <Input
+          id="user-email"
+          type="email"
+          maxLength={200}
+          placeholder="e.g. jsmith@acme.com"
+          value={email}
+          disabled={loading}
+          onChange={(e) => setEmail(e.target.value)}
+        />
+      </div>
+
+      {isEdit && (
+        <div className="space-y-1.5">
+          <Label htmlFor="user-status" variant="field">
+            Status
+          </Label>
+          <Select value={status} disabled={loading} onValueChange={setStatus}>
+            <SelectTrigger id="user-status">
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="active">Active</SelectItem>
+              <SelectItem value="inactive">Inactive</SelectItem>
+            </SelectContent>
+          </Select>
+        </div>
+      )}
+
+      {/* The Assignments (membership + posting) editor — edit path only, since a user must
+          exist before it can be assigned into a company. It manages its own data + saves
+          (per-membership atomic replacePostings), independent of this form's submit. */}
+      {isEdit && !loading && (
+        <>
+          <Separator className="my-1" />
+          <AssignmentsEditor userUuid={uuid} />
+        </>
+      )}
+    </EntityFormModal>
+  );
+}

package/template/frontend/src/pages/users/UsersPage.jsx

@@ -0,0 +1,232 @@
+/**
+ * UsersPage — the Users management screen: a list of users with routed-modal Add/Edit
+ * and a themed delete confirm. Same layout-route shape as CompaniesPage/RolesPage
+ * (list + `<Outlet context={{ onRefresh }} />` for /users/add and /users/edit/:uuid).
+ * Loads on mount via the shared identity client service; a 403 (users are root-only
+ * server-side for now) degrades to a graceful "need platform-admin access" message.
+ *
+ * The user EDIT page (/users/edit/:uuid) is where the Assignments (membership + posting)
+ * editor will live in Phase 5 — UserForm leaves a clear placeholder for it.
+ *
+ * ⛔ No raw UUIDs: columns render username/email/status; `row.id` is a key/route param only.
+ */
+import { useCallback, useEffect, useState } from 'react';
+import { Outlet, useNavigate, useSearchParams } from 'react-router-dom';
+import { Users } 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): Username, Email, Status, Created.
+const COLUMNS = [
+  {
+    key: 'username',
+    label: 'Username',
+    sortable: true,
+    sortKey: 'username',
+    render: (row) => row.fields?.username || '(unnamed)',
+  },
+  {
+    key: 'email',
+    label: 'Email',
+    sortable: true,
+    sortKey: 'email',
+    render: (row) => row.fields?.email || '—',
+  },
+  {
+    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 UsersPage() {
+  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('');
+
+  // 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]);
+
+  const [deleteTarget, setDeleteTarget] = useState(null);
+  const [deleteBusy, setDeleteBusy] = useState(false);
+
+  const load = useCallback(async () => {
+    if (!token) return;
+    setLoading(true);
+    const r = await identity.listUsers(token, query);
+    if (r.ok) {
+      setRows(r.rows || []);
+      setTotal(r.total || 0);
+      setError('');
+    } else {
+      setRows([]);
+      setTotal(0);
+      setError(r.error || 'Could not load users.');
+    }
+    setLoading(false);
+  }, [identity, token, query]);
+
+  useEffect(() => {
+    load();
+  }, [load]);
+
+  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.deleteUser(token, deleteTarget.id);
+    setDeleteBusy(false);
+    if (!r.ok) {
+      toast.error(r.error || 'Could not delete the user.');
+      return;
+    }
+    setDeleteTarget(null);
+    toast.success('User deleted');
+    await load();
+  };
+
+  return (
+    <AppShell section="Identity" title="Users">
+      <div className="p-4">
+        <PageHeader
+          section="Identity"
+          title="Users"
+          icon={Users}
+          actions={
+            <EntityListControls
+              search={query.search}
+              onSearchChange={onSearchChange}
+              searchPlaceholder="Search users…"
+              addLabel="Add user"
+              onAdd={() => navigate('/users/add')}
+            />
+          }
+        />
+
+        <EntityList
+          columns={COLUMNS}
+          rows={rows}
+          search={query.search}
+          sortBy={query.sortBy}
+          sortOrder={query.sortOrder}
+          loading={loading}
+          error={error}
+          emptyLabel="No users yet. Add one to get started."
+          onEdit={(row) => navigate(`/users/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>
+
+      <Outlet context={{ onRefresh: load }} />
+
+      <ConfirmDialog
+        open={!!deleteTarget}
+        title={deleteTarget ? `Delete “${deleteTarget.fields?.username || 'this user'}”?` : 'Delete user?'}
+        message="This permanently removes the user and all their company memberships. This cannot be undone."
+        confirmLabel="Delete"
+        destructive
+        busy={deleteBusy}
+        onConfirm={onConfirmDelete}
+        onCancel={() => setDeleteTarget(null)}
+      />
+    </AppShell>
+  );
+}

package/template/frontend/src/platform/httpClient.js

@@ -0,0 +1,125 @@
+/**
+ * The WEB HttpClient adapter — the platform half of @astram/frontend-core's injected HTTP
+ * contract. Uses the browser `fetch`, same-origin `/api` (proxied by Vite to the
+ * server's /auth/* routes). A mobile app provides its OWN adapter (RN fetch + its
+ * base URL) implementing the same shape; the shared logic is identical for both.
+ */
+
+const BASE = '/api';
+
+async function toResponse(res) {
+  let data = null;
+  try {
+    data = res.status === 204 ? null : await res.json();
+  } catch {
+    data = null;
+  }
+  return { ok: res.ok, status: res.status, data };
+}
+
+/**
+ * The app-wide enforced-re-enroll interceptor. When a request is rejected with a 403
+ * whose body is EXACTLY `{ error: 'reenrollment_required' }` (the server's re-enroll
+ * gate, §4), fire the supplied callback so the app can force the re-enroll screen.
+ * Matched narrowly on that single error code so an unrelated future permission-deny 403
+ * never trips it. Best-effort: a throwing callback must not break the HTTP result.
+ */
+function maybeSignalReenroll(result, onReenrollRequired) {
+  if (
+    typeof onReenrollRequired === 'function' &&
+    result.status === 403 &&
+    result.data &&
+    result.data.error === 'reenrollment_required'
+  ) {
+    try {
+      onReenrollRequired();
+    } catch {
+      /* the signal is best-effort — never let it break the request result */
+    }
+  }
+  return result;
+}
+
+/**
+ * @param {{ onReenrollRequired?: () => void }} [config]
+ *   `onReenrollRequired` — invoked when any response is a 403 `reenrollment_required`
+ *   (the enforced-re-enroll gate). The consumer (AuthContext) uses it to flip the app
+ *   into the forced re-enroll flow app-wide, regardless of which call triggered it.
+ * @returns {import('@astram/frontend-core').HttpClient}
+ */
+export function createWebHttpClient(config = {}) {
+  const { onReenrollRequired } = config;
+
+  return {
+    async post(path, body, opts = {}) {
+      try {
+        const res = await fetch(`${BASE}${path}`, {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json',
+            ...(opts.bearerToken ? { authorization: `Bearer ${opts.bearerToken}` } : {}),
+          },
+          body: JSON.stringify(body),
+        });
+        return maybeSignalReenroll(await toResponse(res), onReenrollRequired);
+      } catch {
+        return { ok: false, status: 0, data: null };
+      }
+    },
+    async patch(path, body, opts = {}) {
+      try {
+        const res = await fetch(`${BASE}${path}`, {
+          method: 'PATCH',
+          headers: {
+            'content-type': 'application/json',
+            ...(opts.bearerToken ? { authorization: `Bearer ${opts.bearerToken}` } : {}),
+          },
+          body: JSON.stringify(body),
+        });
+        return maybeSignalReenroll(await toResponse(res), onReenrollRequired);
+      } catch {
+        return { ok: false, status: 0, data: null };
+      }
+    },
+    async put(path, body, opts = {}) {
+      try {
+        const res = await fetch(`${BASE}${path}`, {
+          method: 'PUT',
+          headers: {
+            'content-type': 'application/json',
+            ...(opts.bearerToken ? { authorization: `Bearer ${opts.bearerToken}` } : {}),
+          },
+          body: JSON.stringify(body),
+        });
+        return maybeSignalReenroll(await toResponse(res), onReenrollRequired);
+      } catch {
+        return { ok: false, status: 0, data: null };
+      }
+    },
+    async delete(path, body, opts = {}) {
+      try {
+        const res = await fetch(`${BASE}${path}`, {
+          method: 'DELETE',
+          headers: {
+            'content-type': 'application/json',
+            ...(opts.bearerToken ? { authorization: `Bearer ${opts.bearerToken}` } : {}),
+          },
+          body: JSON.stringify(body),
+        });
+        return maybeSignalReenroll(await toResponse(res), onReenrollRequired);
+      } catch {
+        return { ok: false, status: 0, data: null };
+      }
+    },
+    async get(path, opts = {}) {
+      try {
+        const res = await fetch(`${BASE}${path}`, {
+          headers: opts.bearerToken ? { authorization: `Bearer ${opts.bearerToken}` } : {},
+        });
+        return maybeSignalReenroll(await toResponse(res), onReenrollRequired);
+      } catch {
+        return { ok: false, status: 0, data: null };
+      }
+    },
+  };
+}

package/template/frontend/src/platform/returnPathStore.js

@@ -0,0 +1,43 @@
+/**
+ * The WEB return-path store — the localStorage half of the return-path feature. The
+ * PURE logic (which paths are restorable + obfuscation) lives in @astram/frontend-core; this file
+ * is only the platform glue (localStorage), mirroring platform/sessionStore.js. A mobile
+ * app would provide its own store over AsyncStorage using the same shared encode/decode.
+ *
+ * Stored in localStorage ALWAYS (independent of "Remember me"), so a return works across a
+ * full page reload / browser restart — the reason this isn't just React Router location
+ * state (which is in-memory and lost on reload).
+ */
+import { encodeReturnPath, decodeReturnPath } from '@astram/frontend-core';
+
+const KEY = 'app-return-path';
+
+/** Persist `path` (obfuscated) as the place to return to after the next login. No-op for
+ * non-restorable paths or when storage is unavailable. */
+export function saveReturnPath(path) {
+  const blob = encodeReturnPath(path);
+  if (!blob) return;
+  try {
+    localStorage.setItem(KEY, blob);
+  } catch {
+    /* storage full / disabled — restore just falls back to /dashboard */
+  }
+}
+
+/** The saved return path, or null if none / corrupt / storage unavailable. */
+export function loadReturnPath() {
+  try {
+    return decodeReturnPath(localStorage.getItem(KEY));
+  } catch {
+    return null;
+  }
+}
+
+/** Forget the saved return path (called once it's been consumed at login). */
+export function clearReturnPath() {
+  try {
+    localStorage.removeItem(KEY);
+  } catch {
+    /* ignore */
+  }
+}

package/template/frontend/src/platform/sessionStore.js

@@ -0,0 +1,29 @@
+/**
+ * The WEB session store — the platform half of @astram/frontend-core's SessionStore contract,
+ * backed by localStorage. A mobile app provides its own (AsyncStorage). The shared
+ * session helpers never touch storage directly; the app injects this.
+ */
+
+const KEY = 'app-session';
+
+/** @returns {import('@astram/frontend-core').SessionStore} */
+export function createWebSessionStore() {
+  return {
+    load() {
+      try {
+        const raw = localStorage.getItem(KEY);
+        return raw ? JSON.parse(raw) : null;
+      } catch {
+        return null;
+      }
+    },
+    save(state) {
+      try {
+        if (state) localStorage.setItem(KEY, JSON.stringify(state));
+        else localStorage.removeItem(KEY);
+      } catch {
+        /* storage unavailable — session stays in memory only */
+      }
+    },
+  };
+}