@gopherium/react-auth 0.15.0 → 0.16.0

package/README.md

@@ -6,15 +6,24 @@ Session authentication for React apps backed by gouncer's authkit.
 
 - `@gopherium/react-auth` is the headless core: the auth API client,
   `useSession`, `useLogout`, `sessionQueryKey`, the slot-based
-  `AuthGate`, `createAuthQueryClient`, and `isSessionRevoked`.
+  `AuthGate`, `createAuthQueryClient`, `isSessionRevoked`, and
+  `catalogFor`, which answers the `es-ES` and `fr-FR` catalogues of the
+  text domain `DOMAIN`.
 - `@gopherium/react-auth/admin` is the user administration API client.
 - `@gopherium/react-auth/wpds` renders the WordPress Design System UI:
-  `LoginScreen` (brand prop), `AccountPanel`, `UsersScreen`,
-  `NewUserScreen`, `usersMenuItem`, `SetupCodeStep`, which asks for
-  the one-time setup code as Jenkins' "Unlock Jenkins" does, and
-  `SetupAccountStep`, the account rows of WordPress's installer with
-  its password strength meter. Import
+  `LoginScreen` (brand prop), `AccountPanel`, `usersMenuItem`,
+  `SetupCodeStep`, which asks for the one-time setup code as Jenkins'
+  "Unlock Jenkins" does, and `SetupAccountStep`, the account rows of
+  WordPress's installer with its password strength meter, and
+  `PasswordField` with `usePasswordField`, that step's password row for
+  any form that sets a password. Import
   `@gopherium/react-auth/wpds/style.css` alongside it.
+- `@gopherium/react-auth/wpds/users` is the Users page on WordPress
+  DataViews: `UsersPage`, `usersListDefaults`, the view it opens on as
+  data for godmin's `useListView`, `RoleSelect`, the role menu with the
+  fewest capabilities first, `roleLabelOf`, and `errorMessageOf`, the
+  words the list toasts a failed account write in. It is its own entry,
+  so an app that only signs people in never resolves its peers.
 - `@gopherium/react-auth/testing` is the msw harness: `server`,
   `installTestEnvironment`, `seedSession`, `defaultUser`, and canned
   handlers for the auth endpoints.
@@ -63,6 +72,51 @@ with a `Field.VisualLabel`, as the step's Confirm Password row is.
 />
 ```
 
+## Password field
+
+An Add User form takes the step's password row with WordPress's
+"Generate password" button first. `labelPosition="top"` stacks each
+label above its field as a godmin form does, where the installer's
+default `side` puts it beside the field. Send `password.value` once
+`password.ready` is true.
+
+```tsx
+const password = usePasswordField({ length: 24, userInputs: [name, email] })
+
+<PasswordField password={password} generateFirst labelPosition="top" readOnly={sending} />
+```
+
+## Users page
+
+The app holds the view in its address with godmin's `useListView`, as
+every other list does, and hands the page the result and its own words
+as data. Its route keeps the view with `validateSearch: listSearch`.
+
+```tsx
+const list = useListView<View>(usersListDefaults({ perPage: settings?.pageSize }))
+
+<UsersPage
+  list={list}
+  pageSizes={settings?.pageSizes}
+  sizesFailed={settingsFailed}
+  roleLabels={{ admin: __('Administrator'), member: __('Member') }}
+  addLink={<Link to="/users/new" />}
+  headingLevel={2}
+/>
+```
+
+- An app with no page size setting passes a fixed `perPage` to
+  `usersListDefaults`. The list shows as loading until it has a page
+  size or `sizesFailed`.
+- A row the server marks `editable: false`, and the reader's own row,
+  offer no action.
+- `errorMessages` gives words to the error codes only the app's
+  transport answers. The codes authkit answers carry WordPress's words.
+- `columns` adds a column after Role as data: a label and, for each
+  account id, the text, the words a screen reader hears and an optional
+  link element. Pass its id to `usersListDefaults` as well, to show it.
+- `showAvatars={false}` drops the Avatar field when the site shows none.
+
 ## Consumer requirements
 
 - `react` and `@tanstack/react-query` are peer dependencies; the app
@@ -72,6 +126,10 @@ with a `Field.VisualLabel`, as the step's Confirm Password row is.
   development, proxy `/api` to your backend so the `__Host-` session
   cookie is first-party.
 - `/wpds` needs the `@wordpress/ui` and `@wordpress/icons` peers.
+- `/wpds/users` also needs `@gopherium/godmin` 0.28, `@gopherium/gottext`,
+  `@wordpress/dataviews`, `@wordpress/components` and `@wordpress/date`,
+  and godmin's `Toaster` above the page, whose toasts show each name
+  whole. The app loads the DataViews and components stylesheets.
 - The account step loads zxcvbn, about 400 kB gzipped, as its own chunk
   the first time it renders. Vite reports that chunk as larger than
   500 kB.

package/dist/account.d.ts

@@ -5,8 +5,11 @@ export declare const accountSchema: z.ZodObject<{
     email: z.ZodString;
     name: z.ZodString;
     disabled: z.ZodBoolean;
+    confirmed: z.ZodBoolean;
     role: z.ZodDefault<z.ZodString>;
     created_at: z.ZodCoercedDate<unknown>;
+    editable: z.ZodBoolean;
+    avatar: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 /** Account is a user account as the server answers it. */
 export type Account = z.infer<typeof accountSchema>;

package/dist/account.js

@@ -6,6 +6,9 @@ export const accountSchema = z.object({
     email: z.string(),
     name: z.string(),
     disabled: z.boolean(),
+    confirmed: z.boolean(),
     role: z.string().default(''),
     created_at: z.coerce.date(),
+    editable: z.boolean(),
+    avatar: z.string().optional(),
 });

package/dist/admin/errors.d.ts

@@ -0,0 +1,62 @@
+import { ValidationError } from '../api.js';
+/**
+ * EmailTakenError is thrown when a new user's email is already in use.
+ */
+export declare class EmailTakenError extends Error {
+    readonly code = "email_taken";
+}
+/**
+ * RoleRefusedError is thrown when the actor holds no role the server admits.
+ */
+export declare class RoleRefusedError extends Error {
+    readonly code = "role_insufficient";
+}
+/**
+ * SelfRoleError is thrown when an account changes its own role.
+ */
+export declare class SelfRoleError extends Error {
+    readonly code = "self_role_refused";
+}
+/**
+ * SelfDisableError is thrown when an account disables itself.
+ */
+export declare class SelfDisableError extends Error {
+    readonly code = "self_disable_refused";
+}
+/**
+ * LastPrivilegedError is thrown when a write would leave no enabled
+ * account holding a privileged role.
+ */
+export declare class LastPrivilegedError extends Error {
+    readonly code = "last_privileged_refused";
+}
+/**
+ * RoleUnknownError is thrown when a write names a role nobody declared.
+ */
+export declare class RoleUnknownError extends ValidationError {
+    readonly code = "role_unknown";
+}
+/**
+ * UserNotEditableError is thrown when the reader may not edit the account.
+ */
+export declare class UserNotEditableError extends Error {
+    readonly code = "user_not_editable";
+}
+/**
+ * RoleNotGrantableError is thrown when the reader may not give the role.
+ */
+export declare class RoleNotGrantableError extends Error {
+    readonly code = "role_not_grantable";
+}
+/**
+ * RoleChangedError is thrown when the account's role changed before the write landed.
+ */
+export declare class RoleChangedError extends Error {
+    readonly code = "role_changed";
+}
+/**
+ * UserNotFoundError is thrown when no account has the identifier a write names.
+ */
+export declare class UserNotFoundError extends Error {
+    readonly code = "user_not_found";
+}

package/dist/admin/errors.js

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: Apache-2.0
+import { ValidationError } from '../api.js';
+/**
+ * EmailTakenError is thrown when a new user's email is already in use.
+ */
+export class EmailTakenError extends Error {
+    code = 'email_taken';
+}
+/**
+ * RoleRefusedError is thrown when the actor holds no role the server admits.
+ */
+export class RoleRefusedError extends Error {
+    code = 'role_insufficient';
+}
+/**
+ * SelfRoleError is thrown when an account changes its own role.
+ */
+export class SelfRoleError extends Error {
+    code = 'self_role_refused';
+}
+/**
+ * SelfDisableError is thrown when an account disables itself.
+ */
+export class SelfDisableError extends Error {
+    code = 'self_disable_refused';
+}
+/**
+ * LastPrivilegedError is thrown when a write would leave no enabled
+ * account holding a privileged role.
+ */
+export class LastPrivilegedError extends Error {
+    code = 'last_privileged_refused';
+}
+/**
+ * RoleUnknownError is thrown when a write names a role nobody declared.
+ */
+export class RoleUnknownError extends ValidationError {
+    code = 'role_unknown';
+}
+/**
+ * UserNotEditableError is thrown when the reader may not edit the account.
+ */
+export class UserNotEditableError extends Error {
+    code = 'user_not_editable';
+}
+/**
+ * RoleNotGrantableError is thrown when the reader may not give the role.
+ */
+export class RoleNotGrantableError extends Error {
+    code = 'role_not_grantable';
+}
+/**
+ * RoleChangedError is thrown when the account's role changed before the write landed.
+ */
+export class RoleChangedError extends Error {
+    code = 'role_changed';
+}
+/**
+ * UserNotFoundError is thrown when no account has the identifier a write names.
+ */
+export class UserNotFoundError extends Error {
+    code = 'user_not_found';
+}

package/dist/admin/fieldError.d.ts

@@ -0,0 +1,19 @@
+/** UserField is a field of the Add User form an error can be about. */
+export type UserField = 'email' | 'name' | 'password';
+/** FieldError is the Add User field an error is about and the message shown under it. */
+export interface FieldError {
+    field: UserField;
+    message: string;
+}
+/**
+ * Returns the password hint with the server's minimum as its number.
+ * @param min - The fewest characters the server accepts.
+ * @returns The hint.
+ */
+export declare function passwordHint(min: number): string;
+/**
+ * Returns the Add User field an error is about and the message shown under it.
+ * @param error - The error createUser threw.
+ * @returns The field and its message, or undefined for an error about no one field.
+ */
+export declare function fieldError(error: unknown): FieldError | undefined;

package/dist/admin/fieldError.js

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: Apache-2.0
+import { __, _n, sprintf } from '@wordpress/i18n';
+import { ValidationError } from '../api.js';
+import { DOMAIN } from '../domain.js';
+import { EmailTakenError } from './errors.js';
+const fieldMessages = new Map([
+    ['email_taken', ['email', () => __('This email is already registered. Please choose another one.', DOMAIN)]],
+    ['email_invalid', ['email', () => __('The email address is not correct.', DOMAIN)]],
+    ['name_required', ['name', () => __('Please provide a name.', DOMAIN)]],
+    ['name_too_long', ['name', () => __('This name is too long.', DOMAIN)]],
+    ['password_too_short', ['password', (meta) => (typeof meta.min === 'number' ? passwordHint(meta.min) : undefined)]],
+    ['password_too_long', ['password', () => __('This password is too long.', DOMAIN)]],
+]);
+/**
+ * Returns the password hint with the server's minimum as its number.
+ * @param min - The fewest characters the server accepts.
+ * @returns The hint.
+ */
+export function passwordHint(min) {
+    const hint = _n('Hint: The password should be at least %d character long. ' +
+        'To make it stronger, use upper and lower case letters, numbers, and symbols like ! " ? $ %% ^ & ).', 'Hint: The password should be at least %d characters long. ' +
+        'To make it stronger, use upper and lower case letters, numbers, and symbols like ! " ? $ %% ^ & ).', min, DOMAIN);
+    return sprintf(hint, min);
+}
+/**
+ * Returns the code and meta an error a create threw carries.
+ * @param error - The error the create threw.
+ * @returns The code, empty when it carries none, and the meta.
+ */
+function detailsOf(error) {
+    if (error instanceof ValidationError) {
+        return [error.code ?? '', error.meta ?? {}];
+    }
+    return [error instanceof EmailTakenError ? error.code : '', {}];
+}
+/**
+ * Returns the Add User field an error is about and the message shown under it.
+ * @param error - The error createUser threw.
+ * @returns The field and its message, or undefined for an error about no one field.
+ */
+export function fieldError(error) {
+    const [code, meta] = detailsOf(error);
+    const known = fieldMessages.get(code);
+    const message = known?.[1](meta);
+    return known && message !== undefined ? { field: known[0], message } : undefined;
+}

package/dist/admin/index.d.ts

@@ -1,6 +1,5 @@
 import { z } from 'zod';
 import type { Account as User } from '../account.js';
-import { ValidationError } from '../api.js';
 export declare const usersQueryKey: readonly ["users"];
 export type { Account as User } from '../account.js';
 export interface NewUser {
@@ -21,43 +20,10 @@ declare const invitationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     activation_link: z.ZodString;
 }, z.core.$strip>], "delivered">;
 export type Invitation = z.infer<typeof invitationSchema>;
-/**
- * EmailTakenError is thrown when a new user's email is already in use.
- */
-export declare class EmailTakenError extends Error {
-}
 export { ValidationError } from '../api.js';
-/**
- * RoleRefusedError is thrown when the actor holds no role the server admits.
- */
-export declare class RoleRefusedError extends Error {
-}
-/**
- * SelfRoleError is thrown when an account changes its own role.
- */
-export declare class SelfRoleError extends Error {
-}
-/**
- * LastPrivilegedError is thrown when a write would leave no enabled
- * account holding a privileged role.
- */
-export declare class LastPrivilegedError extends Error {
-}
-/**
- * RoleUnknownError is thrown when a write names a role nobody declared.
- */
-export declare class RoleUnknownError extends ValidationError {
-}
-/**
- * RoleBeyondReachError is thrown when the actor may not hand out the role or change the account.
- */
-export declare class RoleBeyondReachError extends Error {
-}
-/**
- * RoleChangedError is thrown when the account's role changed before the write landed.
- */
-export declare class RoleChangedError extends Error {
-}
+export { EmailTakenError, LastPrivilegedError, RoleChangedError, RoleNotGrantableError, RoleRefusedError, RoleUnknownError, SelfDisableError, SelfRoleError, UserNotEditableError, UserNotFoundError, } from './errors.js';
+export { fieldError } from './fieldError.js';
+export type { FieldError, UserField } from './fieldError.js';
 /**
  * Returns every user account.
  * @param signal - Aborts the in-flight request.
@@ -89,3 +55,10 @@ export declare function setUserRole(id: string, role: string): Promise<void>;
  * @returns The delivery report, carrying the link when nothing mailed it.
  */
 export declare function invite(input: NewInvite): Promise<Invitation>;
+/**
+ * Sends a new invitation to a pending account, ending the link sent before,
+ * and holds every transport to the invitation contract.
+ * @param email - The address of the invited account.
+ * @returns The delivery report, carrying the link when nothing mailed it.
+ */
+export declare function resendInvite(email: string): Promise<Invitation>;

package/dist/admin/index.js

@@ -2,81 +2,42 @@
 import { __ } from '@wordpress/i18n';
 import { z } from 'zod';
 import { accountSchema } from '../account.js';
-import { RateLimitedError, UnauthorizedError, ValidationError } from '../api.js';
+import { RateLimitedError, UnauthorizedError, ValidationError, refusalOf } from '../api.js';
 import { DOMAIN } from '../domain.js';
 import { resolveTransport } from '../transport.js';
+import { EmailTakenError, LastPrivilegedError, RoleChangedError, RoleNotGrantableError, RoleRefusedError, RoleUnknownError, SelfDisableError, SelfRoleError, UserNotEditableError, UserNotFoundError, } from './errors.js';
 export const usersQueryKey = ['users'];
 const invitationSchema = z.discriminatedUnion('delivered', [
     z.object({ delivered: z.literal(true) }),
     z.object({ delivered: z.literal(false), activation_link: z.string().trim().min(1) }),
 ]);
-/**
- * EmailTakenError is thrown when a new user's email is already in use.
- */
-export class EmailTakenError extends Error {
-}
 export { ValidationError } from '../api.js';
-/**
- * RoleRefusedError is thrown when the actor holds no role the server admits.
- */
-export class RoleRefusedError extends Error {
-}
-/**
- * SelfRoleError is thrown when an account changes its own role.
- */
-export class SelfRoleError extends Error {
-}
-/**
- * LastPrivilegedError is thrown when a write would leave no enabled
- * account holding a privileged role.
- */
-export class LastPrivilegedError extends Error {
-}
-/**
- * RoleUnknownError is thrown when a write names a role nobody declared.
- */
-export class RoleUnknownError extends ValidationError {
-}
-/**
- * RoleBeyondReachError is thrown when the actor may not hand out the role or change the account.
- */
-export class RoleBeyondReachError extends Error {
-}
-/**
- * RoleChangedError is thrown when the account's role changed before the write landed.
- */
-export class RoleChangedError extends Error {
-}
-const errorSchema = z.object({ error: z.string(), code: z.string().optional() });
+export { EmailTakenError, LastPrivilegedError, RoleChangedError, RoleNotGrantableError, RoleRefusedError, RoleUnknownError, SelfDisableError, SelfRoleError, UserNotEditableError, UserNotFoundError, } from './errors.js';
+export { fieldError } from './fieldError.js';
 const roleErrors = new Map([
     ['role_unknown', RoleUnknownError],
-    ['role_beyond_reach', RoleBeyondReachError],
+    ['user_not_editable', UserNotEditableError],
+    ['role_not_grantable', RoleNotGrantableError],
 ]);
 const accountErrors = new Map([
     ...roleErrors,
     ['role_changed', RoleChangedError],
+    ['user_not_found', UserNotFoundError],
+    ['last_privileged_refused', LastPrivilegedError],
+    ['role_insufficient', RoleRefusedError],
+]);
+const disableErrors = new Map([
+    ...accountErrors,
+    ['self_disable_refused', SelfDisableError],
 ]);
 const roleChangeErrors = new Map([
     ...accountErrors,
-    ['role_insufficient', RoleRefusedError],
     ['self_role_refused', SelfRoleError],
-    ['last_privileged_refused', LastPrivilegedError],
 ]);
-/**
- * Returns the code and message a refused response carries.
- * @param response - The refused HTTP response.
- * @param fallback - The message to use when the body is unreadable.
- * @returns The error code, if any, and its message.
- */
-async function errorOf(response, fallback) {
-    try {
-        const held = errorSchema.parse(await response.json());
-        return { code: held.code, message: held.error };
-    }
-    catch {
-        return { message: fallback };
-    }
-}
+const creationStatusErrors = new Map([[409, () => new EmailTakenError('email already in use')]]);
+const invitationStatusErrors = new Map([[429, () => new RateLimitedError('too many attempts')]]);
+const inviteRoute = { path: '/api/users/invite', write: 'inviting' };
+const resendRoute = { path: '/api/users/invite/resend', write: 'resending invitation' };
 /**
  * Returns the typed error a refused response's code names.
  * @param refused - The code and message the response carries.
@@ -90,20 +51,42 @@ function typedError(refused, errors = roleErrors) {
 /**
  * Returns the error a refused account write throws.
  * @param response - The refused HTTP response.
- * @param fallback - The message to use when the body is unreadable.
- * @param write - Names the write in the error for any other status.
+ * @param post - The write, with the message for an unreadable body and its name for any other status.
  * @returns The error to throw.
  */
-async function writeError(response, fallback, write) {
-    const refused = await errorOf(response, fallback);
+async function writeError(response, post) {
+    const refused = await refusalOf(response, post.fallback);
     const typed = typedError(refused);
     if (typed) {
         return typed;
     }
     if (response.status === 422) {
-        return new ValidationError(refused.message);
+        return new ValidationError(refused.message, refused);
     }
-    return new Error(`${write} failed with status ${response.status}`);
+    return new Error(`${post.write} failed with status ${response.status}`);
+}
+/**
+ * Posts an account write over REST and returns the body it answers.
+ * @param post - The route, the fields it reads and the error each known status throws.
+ * @returns The answered body, still to be parsed.
+ */
+async function postAccountWrite(post) {
+    const response = await fetch(post.path, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(post.body),
+    });
+    if (response.status === 401) {
+        throw new UnauthorizedError('session expired');
+    }
+    const known = post.errorsByStatus.get(response.status);
+    if (known) {
+        throw known();
+    }
+    if (!response.ok) {
+        throw await writeError(response, post);
+    }
+    return response.json();
 }
 /**
  * Lists the accounts over REST.
@@ -126,21 +109,29 @@ async function restFetchUsers(signal) {
  * @returns The created user.
  */
 async function restCreateUser(input) {
-    const response = await fetch('/api/users', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(input),
+    const created = await postAccountWrite({
+        path: '/api/users',
+        body: input,
+        write: 'creating user',
+        fallback: __('invalid user details', DOMAIN),
+        errorsByStatus: creationStatusErrors,
     });
-    if (response.status === 401) {
-        throw new UnauthorizedError('session expired');
-    }
-    if (response.status === 409) {
-        throw new EmailTakenError('email already in use');
-    }
-    if (!response.ok) {
-        throw await writeError(response, __('invalid user details', DOMAIN), 'creating user');
-    }
-    return accountSchema.parse(await response.json());
+    return accountSchema.parse(created);
+}
+/**
+ * Posts an invitation write over REST and answers its delivery report.
+ * @param route - The invitation route and the name its errors give the write.
+ * @param body - The fields the route reads.
+ * @returns The delivery report, carrying the link when nothing mailed it.
+ */
+async function postInvitation(route, body) {
+    const report = await postAccountWrite({
+        ...route,
+        body,
+        fallback: __('invalid invitation details', DOMAIN),
+        errorsByStatus: invitationStatusErrors,
+    });
+    return invitationSchema.parse(report);
 }
 /**
  * Sends an invitation over REST, answering the same shape whatever the
@@ -149,21 +140,15 @@ async function restCreateUser(input) {
  * @returns The delivery report, carrying the link when nothing mailed it.
  */
 async function restInvite(input) {
-    const response = await fetch('/api/users/invite', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(input),
-    });
-    if (response.status === 401) {
-        throw new UnauthorizedError('session expired');
-    }
-    if (response.status === 429) {
-        throw new RateLimitedError('too many attempts');
-    }
-    if (!response.ok) {
-        throw await writeError(response, __('invalid invitation details', DOMAIN), 'inviting');
-    }
-    return invitationSchema.parse(await response.json());
+    return postInvitation(inviteRoute, input);
+}
+/**
+ * Sends a new invitation to a pending account over REST, ending the link sent before.
+ * @param email - The address of the invited account.
+ * @returns The delivery report, carrying the link when nothing mailed it.
+ */
+async function restResendInvite(email) {
+    return postInvitation(resendRoute, { email });
 }
 /**
  * Updates an account's disabled flag over REST.
@@ -180,8 +165,8 @@ async function restSetUserDisabled(id, disabled) {
         throw new UnauthorizedError('session expired');
     }
     if (!response.ok) {
-        const refused = await errorOf(response, __('the account could not be updated', DOMAIN));
-        throw typedError(refused, accountErrors) ?? new Error(`updating user failed with status ${response.status}`);
+        const refused = await refusalOf(response, __('the account could not be updated', DOMAIN));
+        throw typedError(refused, disableErrors) ?? new Error(`updating user failed with status ${response.status}`);
     }
 }
 /**
@@ -201,7 +186,7 @@ async function restSetUserRole(id, role) {
     if (response.status === 401) {
         throw new UnauthorizedError('session expired');
     }
-    const refused = await errorOf(response, __('the account could not be updated', DOMAIN));
+    const refused = await refusalOf(response, __('the account could not be updated', DOMAIN));
     throw typedError(refused, roleChangeErrors) ?? new Error(`updating role failed with status ${response.status}`);
 }
 /**
@@ -245,3 +230,12 @@ export async function setUserRole(id, role) {
 export async function invite(input) {
     return invitationSchema.parse(await resolveTransport('invite', restInvite)(input));
 }
+/**
+ * Sends a new invitation to a pending account, ending the link sent before,
+ * and holds every transport to the invitation contract.
+ * @param email - The address of the invited account.
+ * @returns The delivery report, carrying the link when nothing mailed it.
+ */
+export async function resendInvite(email) {
+    return invitationSchema.parse(await resolveTransport('resendInvite', restResendInvite)(email));
+}