create-astram-app 0.11.1 → 0.12.0

package/template/frontend/src/pages/org-structure/orgStructure.test.mjs

@@ -0,0 +1,199 @@
+// orgStructure.test.mjs — G-012: the Org structure page's permission keys, name rules (spec §10),
+// advisory delete hint, display rows (names only, never ids) and toast text.
+//
+//   node --test src/pages/org-structure/orgStructure.test.mjs
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  KINDS,
+  LABELS,
+  MAX_NAME_LENGTH,
+  PERMISSIONS,
+  canManage,
+  deleteHint,
+  displayRows,
+  outcome,
+  usedByLabel,
+  validateName,
+} from './orgStructure.js';
+
+describe('permission keys', () => {
+  test('department and branch keys match the server routes', () => {
+    assert.deepEqual(KINDS, ['department', 'branch']);
+    assert.deepEqual(PERMISSIONS.department, {
+      read: 'identity:company_department:read',
+      create: 'identity:department:create',
+      update: 'identity:department:update',
+      delete: 'identity:department:delete',
+    });
+    assert.deepEqual(PERMISSIONS.branch, {
+      read: 'identity:company_branch:read',
+      create: 'identity:branch:create',
+      update: 'identity:branch:update',
+      delete: 'identity:branch:delete',
+    });
+  });
+});
+
+describe('canManage', () => {
+  const holding =
+    (...keys) =>
+    (k) =>
+      keys.includes(k);
+
+  test('read only: lists without write buttons', () => {
+    assert.deepEqual(canManage(holding('identity:company_department:read'), 'department'), {
+      read: true,
+      create: false,
+      rename: false,
+      remove: false,
+    });
+  });
+
+  test('with the Org Structure bundle keys: every action', () => {
+    const can = holding(...Object.values(PERMISSIONS.branch));
+    assert.deepEqual(canManage(can, 'branch'), {
+      read: true,
+      create: true,
+      rename: true,
+      remove: true,
+    });
+    // A branch key never unlocks departments.
+    assert.equal(canManage(can, 'department').create, false);
+  });
+
+  test('fails closed: no projection, an unknown kind, or a non-boolean answer', () => {
+    const none = { read: false, create: false, rename: false, remove: false };
+    assert.deepEqual(canManage(undefined, 'department'), none);
+    assert.deepEqual(
+      canManage(() => true, 'team'),
+      none,
+    );
+    assert.deepEqual(
+      canManage(() => 'yes', 'department'),
+      none,
+    );
+  });
+});
+
+describe('validateName (spec §10)', () => {
+  test('trims and collapses whitespace', () => {
+    assert.deepEqual(validateName('  Sales   Ops '), { ok: true, value: 'Sales Ops' });
+    assert.deepEqual(validateName('Sales\t\nOps'), { ok: true, value: 'Sales Ops' });
+  });
+
+  test('normalises to NFC', () => {
+    const decomposed = 'Qualité';
+    const r = validateName(decomposed);
+    assert.equal(r.ok, true);
+    assert.equal(r.value, 'Qualité');
+  });
+
+  test('refuses control characters (C0 and C1)', () => {
+    for (const bad of ['Sa\u0000les', 'Sa\u0007les', 'Sa\u007fles', 'Sa\u0085les', 'Sa\u009fles']) {
+      assert.deepEqual(validateName(bad), {
+        ok: false,
+        error: 'The name cannot contain control characters.',
+      });
+    }
+  });
+
+  test('refuses an empty or blank name', () => {
+    for (const blank of ['', '   ', '\n\t', undefined, null]) {
+      assert.deepEqual(validateName(blank), { ok: false, error: 'Enter a name.' });
+    }
+  });
+
+  test('1 to 150 characters after normalising, counted as characters', () => {
+    assert.equal(MAX_NAME_LENGTH, 150);
+    assert.equal(validateName('x'.repeat(150)).ok, true);
+    assert.equal(validateName(`  ${'x'.repeat(150)}  `).ok, true);
+    assert.deepEqual(validateName('x'.repeat(151)), {
+      ok: false,
+      error: 'The name can be at most 150 characters.',
+    });
+    // 150 astral characters are 300 UTF-16 units but 150 characters.
+    assert.equal(validateName('\u{1F600}'.repeat(150)).ok, true);
+  });
+});
+
+describe('deleteHint and usedByLabel (advisory)', () => {
+  test('used by assignments ⇒ disabled with the count', () => {
+    assert.deepEqual(deleteHint({ usedBy: 3 }), { disabled: true, hint: 'Used by 3 assignments' });
+    assert.deepEqual(deleteHint({ usedBy: 1 }), { disabled: true, hint: 'Used by 1 assignment' });
+  });
+
+  test('unused, or no count from the server ⇒ enabled (the server decides)', () => {
+    assert.deepEqual(deleteHint({ usedBy: 0 }), { disabled: false, hint: '' });
+    assert.deepEqual(deleteHint({}), { disabled: false, hint: '' });
+    assert.deepEqual(deleteHint(null), { disabled: false, hint: '' });
+  });
+
+  test('"used by N" only when the server sent a count', () => {
+    assert.equal(usedByLabel({ usedBy: 0 }), 'Used by 0 assignments');
+    assert.equal(usedByLabel({ usedBy: 2 }), 'Used by 2 assignments');
+    assert.equal(usedByLabel({}), '');
+  });
+});
+
+describe('displayRows', () => {
+  test('sorted by name; labels are names, never ids', () => {
+    const rows = displayRows([
+      { uuid: 'd-2', name: 'Sales', usedBy: 2 },
+      { uuid: 'd-1', name: 'Finance' },
+      { uuid: 'd-3', name: '' },
+      { name: 'No id' },
+    ]);
+    assert.deepEqual(rows, [
+      { uuid: 'd-3', label: '(unnamed)' },
+      { uuid: 'd-1', label: 'Finance' },
+      { uuid: 'd-2', label: 'Sales', usedBy: 2 },
+    ]);
+    for (const r of rows) assert.notEqual(r.label, r.uuid);
+  });
+
+  test('no rows ⇒ empty', () => {
+    assert.deepEqual(displayRows(undefined), []);
+  });
+});
+
+describe('outcome', () => {
+  test('success text per kind and action', () => {
+    assert.deepEqual(outcome({ ok: true }, 'department', 'create'), {
+      kind: 'success',
+      text: 'Department added',
+    });
+    assert.deepEqual(outcome({ ok: true }, 'branch', 'rename'), {
+      kind: 'success',
+      text: 'Branch renamed',
+    });
+    assert.deepEqual(outcome({ ok: true }, 'branch', 'delete'), {
+      kind: 'success',
+      text: 'Branch deleted',
+    });
+  });
+
+  test('a refusal → the server message', () => {
+    const message = 'A department named "Qualité" already exists in this company.';
+    assert.deepEqual(outcome({ ok: false, error: message }, 'department', 'create'), {
+      kind: 'error',
+      text: message,
+    });
+  });
+
+  test('no message → a fixed fallback', () => {
+    assert.deepEqual(outcome({ ok: false }, 'department', 'delete'), {
+      kind: 'error',
+      text: 'Could not delete the department.',
+    });
+    assert.deepEqual(outcome(null, 'branch', 'create'), {
+      kind: 'error',
+      text: 'Could not add the branch.',
+    });
+  });
+
+  test('labels and empty states', () => {
+    assert.equal(LABELS.department.empty, 'No departments yet');
+    assert.equal(LABELS.branch.empty, 'No branches yet');
+  });
+});

package/template/frontend/src/pages/roles/RoleForm.jsx

@@ -2,9 +2,12 @@
  * RoleForm — the Add/Edit role form (a single Name field), rendered as a routed-modal
  * overlay by /roles/add and /roles/edit/:uuid under RolesPage's layout. The SAME
  * component serves add + edit via `useParams()` (a `:uuid` → edit, load first; else add).
+ * Add creates the role in the company selected on RolesPage (`createCompanyRole`, G-013); the
+ * name is checked with the server's rule first (`validateRoleName`), and a refusal (duplicate
+ * name in this company, bad name, out of reach) is toasted with the server's message.
  * Closes via `navigate(-1)`; on success toasts + calls the layout's `onRefresh`.
  *
- * ⛔ The `:uuid` is a route param only — never rendered as visible text.
+ * ⛔ The `:uuid` and the company uuid are params only — never rendered as visible text.
  */
 import { useEffect, useState } from 'react';
 import { useNavigate, useOutletContext, useParams } from 'react-router-dom';
@@ -13,6 +16,7 @@ import { useAuth } from '@/auth/AuthContext';
 import EntityFormModal from '@/components/EntityFormModal';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
+import { roleOutcome, validateRoleName } from './roleRules';
 
 export default function RoleForm() {
   const { tokens, identity } = useAuth();
@@ -20,7 +24,8 @@ export default function RoleForm() {
   const { uuid } = useParams();
   const isEdit = Boolean(uuid);
   const navigate = useNavigate();
-  const { onRefresh } = useOutletContext() ?? {};
+  const { onRefresh, company } = useOutletContext() ?? {};
+  const companyUuid = company?.value ?? null;
 
   const [name, setName] = useState('');
   const [loading, setLoading] = useState(isEdit);
@@ -47,38 +52,50 @@ export default function RoleForm() {
   }, [identity, token, uuid, isEdit]);
 
   const close = () => navigate(-1);
+  const noCompany = !isEdit && !companyUuid;
 
   const onSubmit = async () => {
-    const trimmed = name.trim();
-    if (!trimmed) {
-      setError('Enter a role name.');
+    if (noCompany) {
+      setError('Choose a company first.');
+      return;
+    }
+    const checked = validateRoleName(name);
+    if (!checked.ok) {
+      setError(checked.error);
       return;
     }
     setError('');
     setBusy(true);
     const r = isEdit
-      ? await identity.updateRole(token, uuid, { name: trimmed })
-      : await identity.createRole(token, trimmed);
+      ? await identity.updateRole(token, uuid, { name: checked.value })
+      : await identity.createCompanyRole(token, companyUuid, checked.value);
     setBusy(false);
-    if (!r.ok) {
-      setError(r.error || 'Could not save the role.');
+    const o = roleOutcome(r, isEdit ? 'rename' : 'create');
+    if (o.kind === 'error') {
+      toast.error(o.text);
       return;
     }
-    toast.success(isEdit ? 'Role updated' : 'Role created');
+    toast.success(o.text);
     onRefresh?.();
     close();
   };
 
+  const description = isEdit
+    ? undefined
+    : company?.label
+      ? `Create a named grant in ${company.label}.`
+      : 'Create a named grant in the selected company.';
+
   return (
     <EntityFormModal
       title={isEdit ? 'Edit role' : 'Add role'}
-      description={isEdit ? undefined : 'Create a named grant.'}
+      description={description}
       open
       onClose={close}
       onSubmit={onSubmit}
       submitLabel={isEdit ? 'Save changes' : 'Create role'}
       busy={busy || loading}
-      error={error}
+      error={noCompany ? 'Choose a company on the Roles page first.' : error}
     >
       <div className="space-y-1.5">
         <Label htmlFor="role-name" variant="field">
@@ -87,10 +104,11 @@ export default function RoleForm() {
         <Input
           id="role-name"
           autoFocus
-          maxLength={120}
+          maxLength={300}
           placeholder="e.g. Admin, Approver, Viewer"
           value={name}
-          disabled={loading}
+          disabled={loading || noCompany}
+          aria-invalid={!!error}
           onChange={(e) => setName(e.target.value)}
         />
       </div>

package/template/frontend/src/pages/roles/RolesPage.jsx

@@ -1,21 +1,32 @@
 /**
- * RolesPage — the Roles management screen (name-only catalog). Same routed-modal CRUD
- * shape as CompaniesPage: a layout route owning the list + `<Outlet context={{ onRefresh }} />`
- * for the /roles/add and /roles/edit/:uuid child routes. Loads on mount via the shared
- * identity client service; a 403 (roles are root-only server-side) degrades to a
- * graceful "need platform-admin access" message.
+ * RolesPage — the Roles management screen (name-only catalog), per company (G-013). Pick a
+ * company from the caller's reachable companies (`identity.listCompanies`, as the Org structure
+ * page), then list and create that company's own roles (`listCompanyRoles`,
+ * `createCompanyRole`). Each company owns its roles: the same name may exist in another company,
+ * and a role can only be posted in its own company.
  *
- * ⛔ No raw UUIDs: the single column renders `fields.name`; `row.id` is a key/route param only.
+ * Same routed-modal CRUD shape as CompaniesPage: a layout route owning the list +
+ * `<Outlet context={{ onRefresh, company }} />` for the /roles/add and /roles/edit/:uuid child
+ * routes. The server walls every route to the caller's subtree (404 outside it) and decides every
+ * write; refusals (duplicate name in this company, bad name) are toasted with the server's
+ * message. Buttons show only for callers holding the role keys (`roleRules.js`; UX only).
+ *
+ * ⛔ No raw UUIDs: the columns render `fields.name`; `row.id` and the company uuid are
+ * keys/route params only.
  */
-import { useCallback, useEffect, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { Outlet, useNavigate, useSearchParams } from 'react-router-dom';
-import { ShieldCheck } from 'lucide-react';
+import { RefreshCw, ShieldCheck } 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 { Button } from '@/components/ui/button';
+import { Label } from '@/components/ui/label';
+import { SearchableSelect } from '@/components/ui/searchable-select';
+import { EMPTY_ROLES_LABEL, canManageRoles, nameOptions, roleOutcome } from './roleRules';
 
 /** Compact absolute date — e.g. "13 Jul 2026"; '—' when missing/invalid. */
 function formatDate(v) {
@@ -70,15 +81,22 @@ function readQueryFromParams(sp) {
 }
 
 export default function RolesPage() {
-  const { tokens, identity } = useAuth();
+  const { tokens, identity, can } = useAuth();
   const token = tokens?.accessToken;
   const navigate = useNavigate();
   const [searchParams, setSearchParams] = useSearchParams();
+  const perms = canManageRoles(can);
+
+  // The company whose roles are shown: `{ value: uuid, label: name }`; the uuid is never shown.
+  const [company, setCompany] = useState(null);
+  const [companyError, setCompanyError] = useState('');
+  const [companiesLoaded, setCompaniesLoaded] = useState(false);
 
   const [rows, setRows] = useState([]);
   const [total, setTotal] = useState(0);
-  const [loading, setLoading] = useState(true);
+  const [loading, setLoading] = useState(false);
   const [error, setError] = useState('');
+  const request = useRef(0);
 
   // Seed ONCE from the URL (initializer runs only on mount) → single source of truth.
   const [query, setQuery] = useState(() => readQueryFromParams(searchParams));
@@ -99,10 +117,53 @@ export default function RolesPage() {
   const [deleteTarget, setDeleteTarget] = useState(null);
   const [deleteBusy, setDeleteBusy] = useState(false);
 
-  const load = useCallback(async () => {
+  // The caller's reachable companies, searchable and paged by the server, sorted by name.
+  const fetchCompanies = useCallback(
+    async ({ search, page, limit }) => {
+      const r = await identity.listCompanies(token, {
+        page,
+        limit,
+        search,
+        sortBy: 'name',
+        sortOrder: 'asc',
+      });
+      if (!r.ok) return { options: [], total: 0, page };
+      return { options: nameOptions(r.rows), total: r.total ?? 0, page: r.page ?? page };
+    },
+    [identity, token],
+  );
+
+  // Start on the first reachable company by name, so a one-company admin sees it at once.
+  const loadFirstCompany = useCallback(async () => {
     if (!token) return;
+    const r = await identity.listCompanies(token, {
+      page: 1,
+      limit: 1,
+      sortBy: 'name',
+      sortOrder: 'asc',
+    });
+    setCompaniesLoaded(true);
+    if (!r.ok) {
+      setCompanyError(r.error || 'Could not load companies.');
+      return;
+    }
+    setCompanyError('');
+    const [first] = nameOptions(r.rows);
+    if (first) setCompany((current) => current ?? first);
+  }, [identity, token]);
+
+  useEffect(() => {
+    loadFirstCompany();
+  }, [loadFirstCompany]);
+
+  const companyUuid = company?.value ?? null;
+
+  const load = useCallback(async () => {
+    if (!token || !companyUuid) return;
+    const mine = ++request.current;
     setLoading(true);
-    const r = await identity.listRoles(token, query);
+    const r = await identity.listCompanyRoles(token, companyUuid, query);
+    if (mine !== request.current) return; // a newer company or query superseded this one
     if (r.ok) {
       setRows(r.rows || []);
       setTotal(r.total || 0);
@@ -113,12 +174,32 @@ export default function RolesPage() {
       setError(r.error || 'Could not load roles.');
     }
     setLoading(false);
-  }, [identity, token, query]);
+  }, [identity, token, companyUuid, query]);
 
   useEffect(() => {
     load();
   }, [load]);
 
+  const onCompanyChange = (value) => {
+    if (!value) {
+      request.current += 1; // drop any in-flight list for the old company
+      setCompany(null);
+      setRows([]);
+      setTotal(0);
+      setError('');
+      setLoading(false);
+      return;
+    }
+    if (value === companyUuid) return;
+    // Clear the old company's rows so they never show under the new company's name.
+    setRows([]);
+    setTotal(0);
+    setCompany({ value, label: '' });
+    setQuery((q) => ({ ...q, page: 1 }));
+  };
+  const onCompanyLabel = (label) =>
+    setCompany((current) => (current && label ? { ...current, label } : current));
+
   const onSearchChange = useCallback((search) => setQuery((q) => ({ ...q, search, page: 1 })), []);
   const onSortChange = useCallback(
     (sortBy, sortOrder) => setQuery((q) => ({ ...q, sortBy, sortOrder })),
@@ -130,20 +211,20 @@ export default function RolesPage() {
   const onConfirmDelete = async () => {
     if (!deleteTarget) return;
     setDeleteBusy(true);
-    const r = await identity.deleteRole(token, deleteTarget.id);
+    const o = roleOutcome(await identity.deleteRole(token, deleteTarget.id), 'delete');
     setDeleteBusy(false);
-    if (!r.ok) {
-      toast.error(r.error || 'Could not delete the role.');
+    if (o.kind === 'error') {
+      toast.error(o.text);
       return;
     }
     setDeleteTarget(null);
-    toast.success('Role deleted');
+    toast.success(o.text);
     await load();
   };
 
   return (
     <AppShell section="Identity" title="Roles">
-      <div className="p-4">
+      <div className="space-y-4 p-4">
         <PageHeader
           section="Identity"
           title="Roles"
@@ -154,37 +235,81 @@ export default function RolesPage() {
               onSearchChange={onSearchChange}
               searchPlaceholder="Search roles…"
               addLabel="Add role"
-              onAdd={() => navigate('/roles/add')}
+              onAdd={perms.create && company ? () => navigate('/roles/add') : undefined}
             />
           }
         />
 
-        <EntityList
-          columns={COLUMNS}
-          rows={rows}
-          search={query.search}
-          sortBy={query.sortBy}
-          sortOrder={query.sortOrder}
-          loading={loading}
-          error={error}
-          emptyLabel="No roles yet. Add one to get started."
-          onEdit={(row) => navigate(`/roles/edit/${row.id}`)}
-          onDelete={(row) => setDeleteTarget(row)}
-          onSortChange={onSortChange}
-        />
+        <div className="max-w-md space-y-1.5">
+          <Label htmlFor="roles-company" variant="field">
+            Company
+          </Label>
+          <SearchableSelect
+            id="roles-company"
+            aria-label="Company"
+            value={companyUuid}
+            selectedLabel={company?.label || null}
+            onChange={onCompanyChange}
+            onLabelChange={onCompanyLabel}
+            fetchPage={fetchCompanies}
+            placeholder="Select a company"
+            searchPlaceholder="Search companies"
+          />
+          {companyError && (
+            <div className="flex items-center gap-2 text-sm text-destructive">
+              <span>{companyError}</span>
+              <Button type="button" variant="outline" size="sm" onClick={loadFirstCompany}>
+                <RefreshCw className="size-4" />
+                Retry
+              </Button>
+            </div>
+          )}
+        </div>
 
-        <EntityListPager
-          total={total}
-          page={query.page}
-          limit={query.limit}
-          loading={loading}
-          error={error}
-          onPageChange={onPageChange}
-          onLimitChange={onLimitChange}
-        />
+        {company ? (
+          <div>
+            {error && (
+              <div className="mb-2 flex justify-end">
+                <Button type="button" variant="outline" size="sm" onClick={load} disabled={loading}>
+                  <RefreshCw className="size-4" />
+                  Retry
+                </Button>
+              </div>
+            )}
+
+            <EntityList
+              columns={COLUMNS}
+              rows={rows}
+              search={query.search}
+              sortBy={query.sortBy}
+              sortOrder={query.sortOrder}
+              loading={loading}
+              error={error}
+              emptyLabel={EMPTY_ROLES_LABEL}
+              onEdit={perms.rename ? (row) => navigate(`/roles/edit/${row.id}`) : undefined}
+              onDelete={perms.remove ? (row) => setDeleteTarget(row) : undefined}
+              onSortChange={onSortChange}
+            />
+
+            <EntityListPager
+              total={total}
+              page={query.page}
+              limit={query.limit}
+              loading={loading}
+              error={error}
+              onPageChange={onPageChange}
+              onLimitChange={onLimitChange}
+            />
+          </div>
+        ) : (
+          companiesLoaded &&
+          !companyError && (
+            <p className="text-sm text-muted-foreground">Choose a company to see its roles.</p>
+          )
+        )}
       </div>
 
-      <Outlet context={{ onRefresh: load }} />
+      <Outlet context={{ onRefresh: load, company }} />
 
       <ConfirmDialog
         open={!!deleteTarget}