@terpjs/react-core 0.8.0 → 0.10.0

package/src/admin/AuditLogAdmin.tsx

@@ -6,6 +6,8 @@ import { useTerpClient } from "../TerpProvider";
 import { DataView, HttpDataViewRepository, useServerDataView } from "../dataview";
 import type { DataViewColumn } from "../dataview";
 import { DetailList } from "../layout";
+import { Code } from "../typography";
+import { useFormatDateTime } from "../format";
 import { useStrings } from "../uiText";
 import type { TerpStrings } from "../uiText";
 import { unwrap } from "../unwrap";
@@ -14,20 +16,23 @@ import { adminCrumb, renderAdminCrumb } from "./crumbs";
 
 type AuditEventRead = components["schemas"]["AuditEventRead"];
 
-function buildColumns(strings: TerpStrings): DataViewColumn<AuditEventRead>[] {
+function buildColumns(
+  strings: TerpStrings,
+  formatDateTime: (value: string) => string,
+): DataViewColumn<AuditEventRead>[] {
   return [
     {
       id: "created_at",
       header: strings.whenColumn,
       accessor: (e) => e.created_at,
-      cell: (e) => new Date(e.created_at).toLocaleString(),
-      meta: { mobileSlot: "date", width: 170 },
+      cell: (e) => formatDateTime(e.created_at),
+      meta: { mobileSlot: "date", width: "md" },
     },
     {
       id: "action",
       header: strings.actionColumn,
       accessor: (e) => e.action,
-      meta: { mobileSlot: "status", width: 100 },
+      meta: { mobileSlot: "status", width: "xs" },
     },
     {
       id: "target",
@@ -41,20 +46,11 @@ function buildColumns(strings: TerpStrings): DataViewColumn<AuditEventRead>[] {
       header: strings.actorColumn,
       accessor: (e) => e.actor_id ?? "",
       cell: (e) => (e.actor_id === null ? "—" : e.actor_id.slice(0, 8)),
-      meta: { mobileSlot: "subtitle", width: 110 },
+      meta: { mobileSlot: "subtitle", width: "sm" },
     },
   ];
 }
 
-const payloadStyle = {
-  margin: 0,
-  padding: "var(--space-3)",
-  background: "var(--color-neutral-100)",
-  borderRadius: "var(--radius-md)",
-  fontSize: "var(--font-size-sm, 0.875rem)",
-  overflowX: "auto" as const,
-};
-
 /**
  * The packaged audit-log screen (`/admin/audit`): the append-only trail every
  * mutation lands in (ADR 0007), newest first as served, read-only by design.
@@ -65,7 +61,11 @@ export function AuditLogAdmin() {
   const strings = useStrings();
   const serverQuery = useServerDataView({ initialPageSize: 25 });
 
-  const columns = useMemo(() => buildColumns(strings), [strings]);
+  const formatDateTime = useFormatDateTime();
+  const columns = useMemo(
+    () => buildColumns(strings, formatDateTime),
+    [strings, formatDateTime],
+  );
   const repository = useMemo(
     () =>
       new HttpDataViewRepository<AuditEventRead>({
@@ -106,7 +106,12 @@ export function AuditLogAdmin() {
               ]}
             />
             {event.payload !== null && (
-              <pre style={payloadStyle}>{JSON.stringify(event.payload, null, 2)}</pre>
+              // `Code block`, not a hand-rolled <pre>. The comment that used to sit here cited
+              // Code's own rationale for the tabIndex it was copying — a scroll container no
+              // keyboard can reach is the SC 2.1.1 failure axe reports as
+              // `scrollable-region-focusable` — which is a long way of saying this WAS a Code
+              // block, written out again under a second marker. It carries the tabIndex itself.
+              <Code block>{JSON.stringify(event.payload, null, 2)}</Code>
             )}
           </div>
         )}

package/src/admin/GroupCreate.tsx

@@ -15,9 +15,13 @@ import { useStrings } from "../uiText";
 import { unwrap } from "../unwrap";
 
 import { adminCrumb, renderAdminCrumb } from "./crumbs";
+import { routeFieldErrors } from "./fieldErrors";
 
 const FORM_ID = "terp-admin-group-create";
 
+/** The inputs this form renders, and so the only reasons it can put anywhere the user will see. */
+const RENDERED_FIELDS = ["name", "description"] as const;
+
 /** Dedicated group-creation page (`/admin/groups/new`). */
 export function GroupCreate() {
   const client = useTerpClient();
@@ -27,10 +31,14 @@ export function GroupCreate() {
   const [name, setName] = useState("");
   const [description, setDescription] = useState("");
   const [creating, setCreating] = useState(false);
+  const [fieldErrors, setFieldErrors] = useState<Readonly<Record<string, string>>>({});
 
   async function onSubmit(event: FormEvent) {
     event.preventDefault();
     setCreating(true);
+    // Cleared on every attempt: the server re-validates the whole body, so its answer is the
+    // complete set of what is wrong, and a stale key would sit under a field already fixed.
+    setFieldErrors({});
     try {
       const group = unwrap(
         await client.POST("/api/v1/groups/", { body: { name, description } }),
@@ -41,7 +49,13 @@ export function GroupCreate() {
         params: { groupId: group.id },
       });
     } catch (error) {
-      toast.warning(error instanceof Error ? error.message : strings.requestFailed);
+      // A reason that names a field belongs on that field; anything unattributed, or attributed
+      // to a field this form does not render, stays a toast.
+      const { shown, leftover } = routeFieldErrors(error, RENDERED_FIELDS);
+      setFieldErrors(shown);
+      if (Object.keys(shown).length === 0 || leftover) {
+        toast.warning(error instanceof Error ? error.message : strings.requestFailed);
+      }
     } finally {
       setCreating(false);
     }
@@ -75,12 +89,12 @@ export function GroupCreate() {
         />
       }
     >
-      <div style={{ maxWidth: "32rem" }}>
+      <div data-terp="admin-form">
         <Stack id={FORM_ID} as="form" gap={4} onSubmit={onSubmit}>
-          <Field label={strings.groupName}>
+          <Field label={strings.groupName} error={fieldErrors.name}>
             <Input value={name} onChange={(event) => setName(event.target.value)} required />
           </Field>
-          <Field label={strings.description}>
+          <Field label={strings.description} error={fieldErrors.description}>
             <Input value={description} onChange={(event) => setDescription(event.target.value)} />
           </Field>
         </Stack>

package/src/admin/GroupDetail.tsx

@@ -17,8 +17,9 @@ import { useRecord } from "../useRecord";
 import { useToast } from "../toast";
 import { Button } from "../ui/Button";
 import { Input } from "../ui/Input";
+import { useFormatDate, useFormatDateTime } from "../format";
 import { useStrings } from "../uiText";
-import { unwrap } from "../unwrap";
+import { ApiError, unwrap } from "../unwrap";
 
 import { adminCrumb, renderAdminCrumb } from "./crumbs";
 
@@ -47,12 +48,16 @@ export function GroupDetail() {
   const strings = useStrings();
   const suggestionsId = useId();
 
+  const formatDate = useFormatDate();
+  const formatDateTime = useFormatDateTime();
   const [membersVersion, setMembersVersion] = useState(0);
   const [grantsVersion, setGrantsVersion] = useState(0);
   const [memberQuery, setMemberQuery] = useState("");
+  const [memberError, setMemberError] = useState<string | undefined>(undefined);
   const [suggestions, setSuggestions] = useState<UserRead[]>([]);
   const [adding, setAdding] = useState(false);
   const [permission, setPermission] = useState("");
+  const [permissionError, setPermissionError] = useState<string | undefined>(undefined);
   const [granting, setGranting] = useState(false);
   const [deleteOpen, setDeleteOpen] = useState(false);
   const [deleting, setDeleting] = useState(false);
@@ -124,11 +129,11 @@ export function GroupDetail() {
         id: "created_at",
         header: strings.createdColumn,
         accessor: (m) => m.created_at,
-        cell: (m) => new Date(m.created_at).toLocaleDateString(),
-        meta: { mobileSlot: "date", width: 120 },
+        cell: (m) => formatDate(m.created_at),
+        meta: { mobileSlot: "date", width: "sm" },
       },
     ],
-    [strings],
+    [strings, formatDate],
   );
 
   const grantColumns: DataViewColumn<GrantRead>[] = useMemo(
@@ -143,11 +148,11 @@ export function GroupDetail() {
         id: "created_at",
         header: strings.createdColumn,
         accessor: (g) => g.created_at,
-        cell: (g) => new Date(g.created_at).toLocaleDateString(),
-        meta: { mobileSlot: "date", width: 120 },
+        cell: (g) => formatDate(g.created_at),
+        meta: { mobileSlot: "date", width: "sm" },
       },
     ],
-    [strings],
+    [strings, formatDate],
   );
 
   const membersRepository = useMemo(
@@ -190,11 +195,36 @@ export function GroupDetail() {
     toast.warning(error instanceof Error ? error.message : strings.requestFailed);
   }
 
+  /**
+   * Route a failure to the input it is about, or to the toast when it is about anything else.
+   *
+   * The key is named rather than inferred from whichever reason came first, because neither of
+   * these two forms submits only what the user typed: adding a member posts a `user_id` resolved
+   * from the typed email, and granting posts the group's own `subject_id` beside the permission.
+   * A reason about either of those is not something the one visible input can be edited to fix,
+   * so it belongs where every other unattributed failure on this screen already goes.
+   */
+  function failedField(
+    error: unknown,
+    key: string,
+    set: (message: string | undefined) => void,
+  ): void {
+    if (error instanceof ApiError) {
+      const message = error.fields[key];
+      if (message !== undefined) {
+        set(message);
+        return;
+      }
+    }
+    failed(error);
+  }
+
   async function onAddMember(event: FormEvent) {
     event.preventDefault();
     const needle = memberQuery.trim();
     if (needle === "") return;
     setAdding(true);
+    setMemberError(undefined);
     try {
       // Resolve the typed email to an account: exact match among the current
       // suggestions first, else one direct directory query.
@@ -208,7 +238,11 @@ export function GroupDetail() {
         match = page.items.find((user) => user.email === needle);
       }
       if (match === undefined) {
-        toast.warning(strings.userNotFound);
+        // On the field for the same reason a 422 now is: "no account matches that email" is
+        // about the email the user just typed, and it is the only input on this form. Leaving it
+        // a toast would have this one form answer server reasons on the field and client reasons
+        // above it, which is a distinction the user has no way to perceive.
+        setMemberError(strings.userNotFound);
         return;
       }
       unwrap(
@@ -223,7 +257,7 @@ export function GroupDetail() {
       setMembersVersion((v) => v + 1);
       void group.reload();
     } catch (error) {
-      failed(error);
+      failedField(error, "user_id", setMemberError);
     } finally {
       setAdding(false);
     }
@@ -252,6 +286,7 @@ export function GroupDetail() {
   async function onGrant(event: FormEvent) {
     event.preventDefault();
     setGranting(true);
+    setPermissionError(undefined);
     try {
       unwrap(
         await client.POST("/api/v1/access/grants", {
@@ -262,7 +297,7 @@ export function GroupDetail() {
       setPermission("");
       setGrantsVersion((v) => v + 1);
     } catch (error) {
-      failed(error);
+      failedField(error, "permission", setPermissionError);
     } finally {
       setGranting(false);
     }
@@ -334,16 +369,16 @@ export function GroupDetail() {
             items={[
               { label: strings.description, value: record.description || "-" },
               { label: strings.members, value: record.member_count },
-              { label: strings.createdColumn, value: new Date(record.created_at).toLocaleString() },
+              { label: strings.createdColumn, value: formatDateTime(record.created_at) },
             ]}
           />
         )}
         <Stack gap={3}>
-          <h2 style={{ margin: 0, fontSize: "var(--font-size-base)" }}>
+          <h2 data-terp="admin-section-title">
             {strings.members}
           </h2>
           <Stack as="form" direction="row" gap={2} align="end" wrap onSubmit={onAddMember}>
-            <Field label={strings.userField}>
+            <Field label={strings.userField} error={memberError}>
               <Input
                 type="email"
                 value={memberQuery}
@@ -376,11 +411,11 @@ export function GroupDetail() {
           />
         </Stack>
         <Stack gap={3}>
-          <h2 style={{ margin: 0, fontSize: "var(--font-size-base)" }}>
+          <h2 data-terp="admin-section-title">
             {strings.permissions}
           </h2>
           <Stack as="form" direction="row" gap={2} align="end" wrap onSubmit={onGrant}>
-            <Field label={strings.permission}>
+            <Field label={strings.permission} error={permissionError}>
               <Input
                 value={permission}
                 onChange={(event) => setPermission(event.target.value)}

package/src/admin/GroupsAdmin.tsx

@@ -9,6 +9,7 @@ import { useTerpClient } from "../TerpProvider";
 import { DataView, HttpDataViewRepository, useServerDataView } from "../dataview";
 import type { DataViewColumn } from "../dataview";
 import { Button } from "../ui/Button";
+import { useFormatDate } from "../format";
 import { useStrings } from "../uiText";
 import type { TerpStrings } from "../uiText";
 import { unwrap } from "../unwrap";
@@ -17,7 +18,10 @@ import { adminCrumb, renderAdminCrumb } from "./crumbs";
 
 type GroupRead = components["schemas"]["GroupRead"];
 
-function buildColumns(strings: TerpStrings): DataViewColumn<GroupRead>[] {
+function buildColumns(
+  strings: TerpStrings,
+  formatDate: (value: string) => string,
+): DataViewColumn<GroupRead>[] {
   return [
     { id: "name", header: strings.groupName, accessor: (g) => g.name, meta: { mobileSlot: "title" } },
     {
@@ -30,14 +34,14 @@ function buildColumns(strings: TerpStrings): DataViewColumn<GroupRead>[] {
       id: "member_count",
       header: strings.members,
       accessor: (g) => g.member_count,
-      meta: { mobileSlot: "status", width: 110 },
+      meta: { mobileSlot: "status", width: "sm" },
     },
     {
       id: "created_at",
       header: strings.createdColumn,
       accessor: (g) => g.created_at,
-      cell: (g) => new Date(g.created_at).toLocaleDateString(),
-      meta: { mobileSlot: "date", width: 120 },
+      cell: (g) => formatDate(g.created_at),
+      meta: { mobileSlot: "date", width: "sm" },
     },
   ];
 }
@@ -53,7 +57,11 @@ export function GroupsAdmin() {
   const navigate = useNavigate();
   const serverQuery = useServerDataView({ initialPageSize: 10 });
 
-  const columns = useMemo(() => buildColumns(strings), [strings]);
+  const formatDate = useFormatDate();
+  const columns = useMemo(
+    () => buildColumns(strings, formatDate),
+    [strings, formatDate],
+  );
   const repository = useMemo(
     () =>
       new HttpDataViewRepository<GroupRead>({

package/src/admin/UserCreate.tsx

@@ -16,10 +16,14 @@ import { useStrings } from "../uiText";
 import { unwrap } from "../unwrap";
 
 import { adminCrumb, renderAdminCrumb } from "./crumbs";
+import { routeFieldErrors } from "./fieldErrors";
 import { adminRoleOptions } from "./roles";
 
 const FORM_ID = "terp-admin-user-create";
 
+/** The inputs this form renders, and so the only reasons it can put anywhere the user will see. */
+const RENDERED_FIELDS = ["email", "password", "role"] as const;
+
 /** Dedicated account-provisioning page (`/admin/users/new`). */
 export function UserCreate() {
   const client = useTerpClient();
@@ -30,11 +34,16 @@ export function UserCreate() {
   const [password, setPassword] = useState("");
   const [role, setRole] = useState("10");
   const [creating, setCreating] = useState(false);
+  const [fieldErrors, setFieldErrors] = useState<Readonly<Record<string, string>>>({});
   const roles = adminRoleOptions(strings);
 
   async function onSubmit(event: FormEvent) {
     event.preventDefault();
     setCreating(true);
+    // Cleared on every attempt, not merged: the server re-validates the whole body, so its
+    // answer is the complete set of what is wrong. Keeping a stale key would leave an error
+    // under a field the user just fixed.
+    setFieldErrors({});
     try {
       const user = unwrap(
         await client.POST("/api/v1/users/", {
@@ -47,7 +56,15 @@ export function UserCreate() {
         params: { userId: user.id },
       });
     } catch (error) {
-      toast.warning(error instanceof Error ? error.message : strings.requestFailed);
+      // A reason that names a field belongs on that field, not floating above the form in a
+      // toast the user has to hold in their head while looking for the input it means. Anything
+      // the server did not attribute — or attributed to something this form has no input for —
+      // stays a toast, which is where the delete and revoke handlers correctly leave it.
+      const { shown, leftover } = routeFieldErrors(error, RENDERED_FIELDS);
+      setFieldErrors(shown);
+      if (Object.keys(shown).length === 0 || leftover) {
+        toast.warning(error instanceof Error ? error.message : strings.requestFailed);
+      }
     } finally {
       setCreating(false);
     }
@@ -81,9 +98,9 @@ export function UserCreate() {
         />
       }
     >
-      <div style={{ maxWidth: "32rem" }}>
+      <div data-terp="admin-form">
         <Stack id={FORM_ID} as="form" gap={4} onSubmit={onSubmit}>
-          <Field label={strings.email}>
+          <Field label={strings.email} error={fieldErrors.email}>
             <Input
               type="email"
               value={email}
@@ -91,22 +108,34 @@ export function UserCreate() {
               required
             />
           </Field>
-          <Field label={strings.password}>
+          <Field label={strings.password} error={fieldErrors.password}>
             <Input
               type="password"
+              // The admin is setting someone else's password, so this is never the browser's saved
+              // credential: `new-password` stops a manager offering the admin's own.
+              autoComplete="new-password"
               value={password}
               onChange={(event) => setPassword(event.target.value)}
               required
             />
           </Field>
-          <Field label={strings.role}>
-            <Select value={role} onChange={(event) => setRole(event.target.value)}>
-              {roles.map((option) => (
-                <option key={option.rank} value={option.rank}>
-                  {option.label}
-                </option>
-              ))}
-            </Select>
+          <Field label={strings.role} error={fieldErrors.role}>
+            {/* `options` + `onValueChange` rather than an `<option>` per rank and a raw
+                change event: the same three rows, as data. No cast is removed here — this file
+                never had one, because `role` was already a plain string — and `T` degrades to
+                `string` for the same reason, since the option values are `String(rank)` rather
+                than members of a declared union. What this conversion buys is the list, not the
+                type: the rank is a number in the ladder and a string in the DOM, which is why
+                `String(rank)` is the option value and `role` stays a string until the POST body
+                coerces it. The typed half has its exhibit in an app that owns an enum. */}
+            <Select
+              options={roles.map((option) => ({
+                value: String(option.rank),
+                label: option.label,
+              }))}
+              value={role}
+              onValueChange={setRole}
+            />
           </Field>
         </Stack>
       </div>

package/src/admin/UserDetail.tsx

@@ -13,6 +13,7 @@ import { useRecord } from "../useRecord";
 import { useToast } from "../toast";
 import { Button } from "../ui/Button";
 import { Input } from "../ui/Input";
+import { useFormatDateTime } from "../format";
 import { useStrings } from "../uiText";
 import { unwrap } from "../unwrap";
 
@@ -30,6 +31,7 @@ export function UserDetail() {
   const userId = useDeclaredParam("userId");
   const client = useTerpClient();
   const strings = useStrings();
+  const formatDateTime = useFormatDateTime();
   const toast = useToast();
   const [pendingLifecycle, setPendingLifecycle] = useState<PendingLifecycle | null>(null);
   const [mutating, setMutating] = useState(false);
@@ -173,7 +175,7 @@ export function UserDetail() {
               label: strings.statusColumn,
               value: record.is_active ? strings.statusActive : strings.statusDeactivated,
             },
-            { label: strings.createdColumn, value: new Date(record.created_at).toLocaleString() },
+            { label: strings.createdColumn, value: formatDateTime(record.created_at) },
           ]}
         />
       )}
@@ -211,6 +213,7 @@ export function UserDetail() {
           <Field label={strings.newPassword}>
             <Input
               type="password"
+              autoComplete="new-password"
               value={resetPassword}
               onChange={(event) => setResetPassword(event.target.value)}
               required

package/src/admin/UsersAdmin.tsx

@@ -9,6 +9,7 @@ import { useTerpClient } from "../TerpProvider";
 import { DataView, HttpDataViewRepository, useServerDataView } from "../dataview";
 import type { DataViewColumn } from "../dataview";
 import { Button } from "../ui/Button";
+import { useFormatDate } from "../format";
 import { useStrings } from "../uiText";
 import type { TerpStrings } from "../uiText";
 import { unwrap } from "../unwrap";
@@ -18,7 +19,10 @@ import { adminRoleLabel } from "./roles";
 
 type UserRead = components["schemas"]["UserRead"];
 
-function buildColumns(strings: TerpStrings): DataViewColumn<UserRead>[] {
+function buildColumns(
+  strings: TerpStrings,
+  formatDate: (value: string) => string,
+): DataViewColumn<UserRead>[] {
   return [
     { id: "email", header: strings.email, accessor: (u) => u.email, meta: { mobileSlot: "title" } },
     {
@@ -26,20 +30,20 @@ function buildColumns(strings: TerpStrings): DataViewColumn<UserRead>[] {
       header: strings.role,
       accessor: (u) => u.role,
       cell: (u) => adminRoleLabel(strings, u.role),
-      meta: { mobileSlot: "subtitle", width: 100 },
+      meta: { mobileSlot: "subtitle", width: "xs" },
     },
     {
       id: "is_active",
       header: strings.statusColumn,
       accessor: (u) => (u.is_active ? strings.statusActive : strings.statusDeactivated),
-      meta: { mobileSlot: "status", width: 110 },
+      meta: { mobileSlot: "status", width: "sm" },
     },
     {
       id: "created_at",
       header: strings.createdColumn,
       accessor: (u) => u.created_at,
-      cell: (u) => new Date(u.created_at).toLocaleDateString(),
-      meta: { mobileSlot: "date", width: 120 },
+      cell: (u) => formatDate(u.created_at),
+      meta: { mobileSlot: "date", width: "sm" },
     },
   ];
 }
@@ -55,7 +59,11 @@ export function UsersAdmin() {
   const navigate = useNavigate();
   const serverQuery = useServerDataView({ initialPageSize: 10 });
 
-  const columns = useMemo(() => buildColumns(strings), [strings]);
+  const formatDate = useFormatDate();
+  const columns = useMemo(
+    () => buildColumns(strings, formatDate),
+    [strings, formatDate],
+  );
   const repository = useMemo(
     () =>
       new HttpDataViewRepository<UserRead>({