create-astram-app 0.11.0 → 0.12.0

package/template/frontend/src/pages/companies/moveAction.test.mjs

@@ -0,0 +1,91 @@
+// moveAction.test.mjs — G-011: the Companies page shows "Move under…" only to callers holding
+// identity:company:update (UX only; the server decides), offers the other visible companies by
+// name after "Top level" (labelled for platform admins; the server refuses it for anyone else), and
+// toasts the server's reason on a refusal.
+//
+//   node --test src/pages/companies/moveAction.test.mjs
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  MOVE_PERMISSION,
+  TOP_LEVEL,
+  TOP_LEVEL_LABEL,
+  canMove,
+  parentOptions,
+  parentUuidOf,
+  moveOutcome,
+} from './moveAction.js';
+
+const ROWS = [
+  { id: 'c-b', fields: { name: 'Beta' } },
+  { id: 'c-a', fields: { name: 'Alpha' } },
+  { id: 'c-x', fields: {} },
+];
+
+describe('canMove', () => {
+  test('the permission key is identity:company:update', () => {
+    assert.equal(MOVE_PERMISSION, 'identity:company:update');
+  });
+
+  test('shown for a row when the caller holds the key', () => {
+    assert.equal(canMove({ id: 'c-a' }, true), true);
+  });
+
+  test('hidden without the permission, or without a row', () => {
+    assert.equal(canMove({ id: 'c-a' }, false), false);
+    assert.equal(canMove(null, true), false);
+    assert.equal(canMove({}, true), false);
+  });
+});
+
+describe('parentOptions', () => {
+  test('"Top level" first, then every other visible company by name, sorted; never the moving one', () => {
+    assert.deepEqual(parentOptions(ROWS, 'c-b'), [
+      { value: TOP_LEVEL, label: 'Top level (platform admins only)' },
+      { value: 'c-x', label: '(unnamed)' },
+      { value: 'c-a', label: 'Alpha' },
+    ]);
+  });
+
+  test('the "Top level" label says who may use it', () => {
+    assert.equal(TOP_LEVEL_LABEL, 'Top level (platform admins only)');
+  });
+
+  test('labels are names, never ids', () => {
+    for (const o of parentOptions(ROWS, 'none')) assert.notEqual(o.label, o.value);
+  });
+
+  test('no rows → only "Top level"', () => {
+    assert.deepEqual(parentOptions(undefined, 'c-a'), [
+      { value: TOP_LEVEL, label: TOP_LEVEL_LABEL },
+    ]);
+  });
+});
+
+describe('parentUuidOf', () => {
+  test('"Top level" is sent as null; a company as its uuid', () => {
+    assert.equal(parentUuidOf(TOP_LEVEL), null);
+    assert.equal(parentUuidOf('c-a'), 'c-a');
+  });
+});
+
+describe('moveOutcome', () => {
+  test('success → "Company moved"', () => {
+    assert.deepEqual(moveOutcome({ ok: true }), { kind: 'success', text: 'Company moved' });
+  });
+
+  test('a refusal → the server message', () => {
+    assert.deepEqual(moveOutcome({ ok: false, error: 'That move would create a cycle.' }), {
+      kind: 'error',
+      text: 'That move would create a cycle.',
+    });
+  });
+
+  test('no message → a fixed fallback', () => {
+    assert.deepEqual(moveOutcome({ ok: false }), {
+      kind: 'error',
+      text: 'Could not move the company.',
+    });
+    assert.deepEqual(moveOutcome(null), { kind: 'error', text: 'Could not move the company.' });
+  });
+});

package/template/frontend/src/pages/org-structure/OrgStructurePage.jsx

@@ -0,0 +1,408 @@
+/**
+ * OrgStructurePage — a company's departments and branches (G-012). Pick a company from the
+ * caller's reachable companies (`identity.listCompanies`), then manage each list: Add, Rename and
+ * Delete (themed ConfirmDialog; the API call runs only from its confirm handler).
+ *
+ * Each company owns its departments and branches; the server walls every route to the caller's
+ * subtree (404 outside it) and decides every write. Buttons show only for callers holding the
+ * write keys (`orgStructure.js`; UX only). "Used by N assignments" disables Delete as a hint; the
+ * server still refuses (409) a delete while any assignment uses the row, and that message is
+ * toasted. Names come from the server; no uuid is ever shown.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { MapPin, Network, Pencil, Plus, RefreshCw, Trash2 } from 'lucide-react';
+import { toast } from 'sonner';
+import { useAuth } from '@/auth/AuthContext';
+import AppShell from '@/shell/AppShell';
+import PageHeader from '@/components/PageHeader';
+import EntityList from '@/components/EntityList';
+import ConfirmDialog from '@/components/ConfirmDialog';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { SearchableSelect } from '@/components/ui/searchable-select';
+import {
+  KINDS,
+  LABELS,
+  canManage,
+  deleteHint,
+  displayRows,
+  outcome,
+  usedByLabel,
+  validateName,
+} from './orgStructure';
+
+/** The identity-service calls per kind. */
+const CALLS = {
+  department: {
+    list: (identity, ...a) => identity.listDepartments(...a),
+    create: (identity, ...a) => identity.createDepartment(...a),
+    rename: (identity, ...a) => identity.renameDepartment(...a),
+    remove: (identity, ...a) => identity.deleteDepartment(...a),
+  },
+  branch: {
+    list: (identity, ...a) => identity.listBranches(...a),
+    create: (identity, ...a) => identity.createBranch(...a),
+    rename: (identity, ...a) => identity.renameBranch(...a),
+    remove: (identity, ...a) => identity.deleteBranch(...a),
+  },
+};
+
+const ICONS = { department: Network, branch: MapPin };
+
+/**
+ * The Add / Rename dialog: one name field, checked with the server's rules before sending.
+ * Mounted only while open, so each opening starts from the current name (rename) or empty (add).
+ */
+function NameDialog({ dialog, busy, onSubmit, onCancel }) {
+  const [name, setName] = useState(dialog.row ? dialog.row.label : '');
+  const [error, setError] = useState('');
+  const fieldId = `org-${dialog.kind}-name`;
+  const one = LABELS[dialog.kind].one;
+  const submit = () => {
+    const checked = validateName(name);
+    if (!checked.ok) {
+      setError(checked.error);
+      return;
+    }
+    setError('');
+    onSubmit(checked.value);
+  };
+
+  return (
+    <ConfirmDialog
+      open
+      title={dialog.row ? `Rename “${dialog.row.label}”` : `Add a ${one}`}
+      message={dialog.row ? `Enter the new name for this ${one}.` : `Name the new ${one}.`}
+      confirmLabel={dialog.row ? 'Rename' : 'Add'}
+      busy={busy}
+      onConfirm={submit}
+      onCancel={onCancel}
+    >
+      <div className="space-y-1.5">
+        <Label htmlFor={fieldId} variant="field">
+          Name
+        </Label>
+        <Input
+          id={fieldId}
+          value={name}
+          onChange={(e) => setName(e.target.value)}
+          maxLength={300}
+          autoFocus
+          aria-invalid={!!error}
+          aria-describedby={error ? `${fieldId}-error` : undefined}
+        />
+        {error && (
+          <p id={`${fieldId}-error`} className="text-xs text-destructive">
+            {error}
+          </p>
+        )}
+      </div>
+    </ConfirmDialog>
+  );
+}
+
+/** One list (Departments or Branches) for the chosen company. */
+function OrgUnitList({ kind, companyUuid, perms, token, identity }) {
+  const labels = LABELS[kind];
+  const Icon = ICONS[kind];
+  const [rows, setRows] = useState([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState('');
+  const [dialog, setDialog] = useState(null);
+  const [dialogBusy, setDialogBusy] = useState(false);
+  const [deleteTarget, setDeleteTarget] = useState(null);
+  const [deleteBusy, setDeleteBusy] = useState(false);
+  const request = useRef(0);
+
+  const load = useCallback(async () => {
+    if (!token || !companyUuid || !perms.read) return;
+    const mine = ++request.current;
+    setLoading(true);
+    const r = await CALLS[kind].list(identity, token, companyUuid);
+    if (mine !== request.current) return; // a newer company or reload superseded this one
+    if (r.ok) {
+      setRows(displayRows(r.rows));
+      setError('');
+    } else {
+      setRows([]);
+      setError(r.error || `Could not load ${labels.title.toLowerCase()}.`);
+    }
+    setLoading(false);
+  }, [identity, token, companyUuid, kind, perms.read, labels.title]);
+
+  useEffect(() => {
+    load();
+  }, [load]);
+
+  const onSubmitName = async (name) => {
+    if (!dialog) return;
+    setDialogBusy(true);
+    const r = dialog.row
+      ? await CALLS[kind].rename(identity, token, dialog.row.uuid, name)
+      : await CALLS[kind].create(identity, token, companyUuid, name);
+    setDialogBusy(false);
+    const o = outcome(r, kind, dialog.row ? 'rename' : 'create');
+    if (o.kind === 'error') {
+      toast.error(o.text);
+      return;
+    }
+    setDialog(null);
+    toast.success(o.text);
+    await load();
+  };
+
+  const onConfirmDelete = async () => {
+    if (!deleteTarget) return;
+    setDeleteBusy(true);
+    const o = outcome(await CALLS[kind].remove(identity, token, deleteTarget.uuid), kind, 'delete');
+    setDeleteBusy(false);
+    if (o.kind === 'error') {
+      toast.error(o.text);
+      return;
+    }
+    setDeleteTarget(null);
+    toast.success(o.text);
+    await load();
+  };
+
+  const columns = [
+    { key: 'name', label: 'Name', render: (row) => row.fields.name },
+    { key: 'usedBy', label: 'Used by', render: (row) => usedByLabel(row.unit) || '—' },
+  ];
+  if (perms.rename || perms.remove) {
+    columns.push({
+      key: 'actions',
+      label: 'Actions',
+      render: (row) => {
+        const hint = deleteHint(row.unit);
+        return (
+          <div className="flex items-center justify-end gap-1">
+            {perms.rename && (
+              <Button
+                type="button"
+                variant="ghost"
+                size="sm"
+                onClick={() => setDialog({ kind, row: row.unit })}
+                aria-label={`Rename ${row.unit.label}`}
+              >
+                <Pencil className="size-4" />
+                Rename
+              </Button>
+            )}
+            {perms.remove && (
+              <Button
+                type="button"
+                variant="ghost"
+                size="sm"
+                className="text-destructive hover:bg-destructive/10 hover:text-destructive"
+                disabled={hint.disabled}
+                title={hint.hint || undefined}
+                onClick={() => setDeleteTarget(row.unit)}
+                aria-label={
+                  hint.disabled
+                    ? `Delete ${row.unit.label} (${hint.hint})`
+                    : `Delete ${row.unit.label}`
+                }
+              >
+                <Trash2 className="size-4" />
+                Delete
+              </Button>
+            )}
+          </div>
+        );
+      },
+    });
+  }
+  // EntityList's row shape: `id` is a key only, `fields.name` the label.
+  const listRows = rows.map((unit) => ({ id: unit.uuid, fields: { name: unit.label }, unit }));
+  const headingId = `org-${kind}-heading`;
+
+  return (
+    <section aria-labelledby={headingId} className="min-w-0 space-y-3">
+      <div className="flex items-center justify-between gap-2">
+        <h2 id={headingId} className="flex items-center gap-2 text-base font-semibold">
+          <Icon className="size-4 text-primary" aria-hidden="true" />
+          {labels.title}
+        </h2>
+        <div className="flex items-center gap-2">
+          {error && perms.read && (
+            <Button type="button" variant="outline" size="sm" onClick={load} disabled={loading}>
+              <RefreshCw className="size-4" />
+              Retry
+            </Button>
+          )}
+          {perms.create && perms.read && (
+            <Button
+              type="button"
+              size="sm"
+              onClick={() => setDialog({ kind, row: null })}
+              disabled={loading || !!error}
+            >
+              <Plus className="size-4" />
+              Add {labels.one}
+            </Button>
+          )}
+        </div>
+      </div>
+
+      {perms.read ? (
+        <EntityList
+          columns={columns}
+          rows={listRows}
+          loading={loading}
+          error={error}
+          emptyLabel={labels.empty}
+        />
+      ) : (
+        <p className="rounded-xl border p-6 text-sm text-muted-foreground">
+          You do not have access to {labels.title.toLowerCase()}.
+        </p>
+      )}
+
+      {dialog && (
+        <NameDialog
+          dialog={dialog}
+          busy={dialogBusy}
+          onSubmit={onSubmitName}
+          onCancel={() => setDialog(null)}
+        />
+      )}
+
+      <ConfirmDialog
+        open={!!deleteTarget}
+        title={deleteTarget ? `Delete “${deleteTarget.label}”?` : `Delete ${labels.one}?`}
+        message={`This removes the ${labels.one} from this company. It cannot be undone.`}
+        confirmLabel="Delete"
+        destructive
+        busy={deleteBusy}
+        onConfirm={onConfirmDelete}
+        onCancel={() => setDeleteTarget(null)}
+      />
+    </section>
+  );
+}
+
+export default function OrgStructurePage() {
+  const { tokens, identity, can } = useAuth();
+  const token = tokens?.accessToken;
+  // The company whose units 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);
+
+  // 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: (r.rows || [])
+          .filter((row) => row && row.id)
+          .map((row) => ({ value: row.id, label: row.fields?.name || '(unnamed)' })),
+        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 = (r.rows || []).find((row) => row && row.id);
+    if (first) {
+      setCompany(
+        (current) => current ?? { value: first.id, label: first.fields?.name || '(unnamed)' },
+      );
+    }
+  }, [identity, token]);
+
+  useEffect(() => {
+    loadFirstCompany();
+  }, [loadFirstCompany]);
+
+  const onCompanyChange = (value) => {
+    if (!value) {
+      setCompany(null);
+      return;
+    }
+    setCompany((current) => (current?.value === value ? current : { value, label: '' }));
+  };
+  const onCompanyLabel = (label) =>
+    setCompany((current) => (current && label ? { ...current, label } : current));
+
+  return (
+    <AppShell section="Identity" title="Org structure">
+      <div className="space-y-4 p-4">
+        <PageHeader section="Identity" title="Org structure" icon={Network} />
+
+        <div className="max-w-md space-y-1.5">
+          <Label htmlFor="org-company" variant="field">
+            Company
+          </Label>
+          <SearchableSelect
+            id="org-company"
+            aria-label="Company"
+            value={company?.value ?? null}
+            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>
+
+        {company ? (
+          <div className="grid gap-6 lg:grid-cols-2">
+            {KINDS.map((kind) => (
+              <OrgUnitList
+                key={`${kind}:${company.value}`}
+                kind={kind}
+                companyUuid={company.value}
+                perms={canManage(can, kind)}
+                token={token}
+                identity={identity}
+              />
+            ))}
+          </div>
+        ) : (
+          companiesLoaded &&
+          !companyError && (
+            <p className="text-sm text-muted-foreground">
+              Choose a company to see its departments and branches.
+            </p>
+          )
+        )}
+      </div>
+    </AppShell>
+  );
+}

package/template/frontend/src/pages/org-structure/orgStructure.js

@@ -0,0 +1,140 @@
+// orgStructure.js — the Org structure page's pure logic (G-012): permission keys, the name rules,
+// the delete hint and the toast text. Tested by orgStructure.test.mjs; OrgStructurePage renders
+// from it. Showing, hiding or disabling a button is UX only: the server decides every write
+// (permission, subtree wall, duplicate name, in-use check).
+
+/** The two org-unit kinds the page manages. */
+export const KINDS = ['department', 'branch'];
+
+/** Permission keys per kind: the list route's read key and the three write keys. */
+export const PERMISSIONS = {
+  department: {
+    read: 'identity:company_department:read',
+    create: 'identity:department:create',
+    update: 'identity:department:update',
+    delete: 'identity:department:delete',
+  },
+  branch: {
+    read: 'identity:company_branch:read',
+    create: 'identity:branch:create',
+    update: 'identity:branch:update',
+    delete: 'identity:branch:delete',
+  },
+};
+
+/** Labels per kind, for headings, buttons, empty states and toasts. */
+export const LABELS = {
+  department: { one: 'department', title: 'Departments', empty: 'No departments yet' },
+  branch: { one: 'branch', title: 'Branches', empty: 'No branches yet' },
+};
+
+/** The longest name the server stores (column width). */
+export const MAX_NAME_LENGTH = 150;
+
+/**
+ * What the caller may do with one kind, from the auth-facts `can(key)` (the same projection
+ * `useCan` reads). UX only.
+ * @param {(key: string) => boolean} can
+ * @param {'department' | 'branch'} kind
+ * @returns {{ read: boolean, create: boolean, rename: boolean, remove: boolean }}
+ */
+export function canManage(can, kind) {
+  const keys = PERMISSIONS[kind];
+  if (!keys || typeof can !== 'function') {
+    return { read: false, create: false, rename: false, remove: false };
+  }
+  return {
+    read: can(keys.read) === true,
+    create: can(keys.create) === true,
+    rename: can(keys.update) === true,
+    remove: can(keys.delete) === true,
+  };
+}
+
+// U+0000–U+001F and U+007F–U+009F.
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/;
+
+/**
+ * The server's name rules (spec §10), checked before sending so the user sees the problem at once:
+ * NFC, trim and collapse whitespace, refuse control characters and an empty result, 1–150
+ * characters. The server applies the same rules and decides; `value` is what it will store.
+ * @param {unknown} name
+ * @returns {{ ok: true, value: string } | { ok: false, error: string }}
+ */
+export function validateName(name) {
+  const value = String(name ?? '')
+    .normalize('NFC')
+    .trim()
+    .replace(/\s+/g, ' ');
+  if (CONTROL.test(value))
+    return { ok: false, error: 'The name cannot contain control characters.' };
+  if (value.length === 0) return { ok: false, error: 'Enter a name.' };
+  if ([...value].length > MAX_NAME_LENGTH) {
+    return { ok: false, error: `The name can be at most ${MAX_NAME_LENGTH} characters.` };
+  }
+  return { ok: true, value };
+}
+
+/**
+ * Whether Delete is offered for a row. `usedBy` > 0 ⇒ disabled with the reason; `usedBy` absent
+ * (the caller cannot read assignments) ⇒ enabled. Advisory only: `usedBy` counts the assignments
+ * the caller can see, and the server refuses (409) a delete while any assignment uses the row.
+ * @param {{ usedBy?: number } | null | undefined} row
+ * @returns {{ disabled: boolean, hint: string }}
+ */
+export function deleteHint(row) {
+  const n = row && typeof row.usedBy === 'number' ? row.usedBy : 0;
+  if (n > 0) {
+    return { disabled: true, hint: `Used by ${n} ${n === 1 ? 'assignment' : 'assignments'}` };
+  }
+  return { disabled: false, hint: '' };
+}
+
+/**
+ * The "used by N" text for a row, or '' when the server sent no count.
+ * @param {{ usedBy?: number } | null | undefined} row
+ */
+export function usedByLabel(row) {
+  if (!row || typeof row.usedBy !== 'number') return '';
+  return `Used by ${row.usedBy} ${row.usedBy === 1 ? 'assignment' : 'assignments'}`;
+}
+
+/**
+ * Rows sorted by name for display, labels only (an unnamed row shows "(unnamed)", never its id).
+ * @param {Array<{ uuid?: string, name?: string, usedBy?: number }> | null | undefined} rows
+ * @returns {Array<{ uuid: string, label: string, usedBy?: number }>}
+ */
+export function displayRows(rows) {
+  return (rows || [])
+    .filter((r) => r && typeof r.uuid === 'string' && r.uuid.length > 0)
+    .map((r) => ({
+      uuid: r.uuid,
+      label: typeof r.name === 'string' && r.name.length > 0 ? r.name : '(unnamed)',
+      ...(typeof r.usedBy === 'number' ? { usedBy: r.usedBy } : {}),
+    }))
+    .sort((a, b) => a.label.localeCompare(b.label));
+}
+
+const DONE = { create: 'added', rename: 'renamed', delete: 'deleted' };
+const VERB = { create: 'add', rename: 'rename', delete: 'delete' };
+
+/**
+ * The toast for a create / rename / delete result: success text, or the server's message on a
+ * refusal (duplicate name, still in use, out of reach), else a fixed fallback.
+ * @param {{ ok: boolean, error?: string } | null | undefined} result
+ * @param {'department' | 'branch'} kind
+ * @param {'create' | 'rename' | 'delete'} action
+ * @returns {{ kind: 'success' | 'error', text: string }}
+ */
+export function outcome(result, kind, action) {
+  const one = LABELS[kind]?.one ?? 'item';
+  if (!result || !result.ok) {
+    return {
+      kind: 'error',
+      text: (result && result.error) || `Could not ${VERB[action] ?? 'save'} the ${one}.`,
+    };
+  }
+  const title = one.charAt(0).toUpperCase() + one.slice(1);
+  return { kind: 'success', text: `${title} ${DONE[action] ?? 'saved'}` };
+}