@sjolystinnovation/app-kit 0.21.0 → 0.22.0

package/src/session/react/SessionExpiryGuard.tsx

@@ -3,8 +3,8 @@
 import { getSession, signOut, useSession } from "next-auth/react";
 import { useEffect, useId, useRef, useState, useSyncExternalStore } from "react";
 import { Alert } from "../../ui/Alert";
-import { CredentialsForm } from "../../ui/CredentialsForm";
-import { SignInRejected, type CredentialsFormStrings } from "../../ui/credentialsFormStrings";
+import { CredentialsForm } from "./CredentialsForm";
+import { SignInRejected, type CredentialsFormStrings } from "./credentialsFormStrings";
 import { withDefaults, type TextOverrides } from "../../ui/withDefaults";
 import {
   closeSessionPrompt,
@@ -34,10 +34,11 @@ function msUntilNextChange(remaining: number): number | null {
 }
 
 
+/** Props for `SessionExpiryGuard`. */
 export interface SessionExpiryGuardProps {
-  /** Where a sign-in as a different user is sent after it is signed out. */
+  /** The path a sign-in as a different user is sent to after it is signed out. */
   loginHref: string;
-  /** Runs after the prompt signs the user back in, such as to show a toast. */
+  /** A function that runs after the prompt signs the user back in, such as to show a toast. */
   onRestored?: (() => void) | undefined;
   strings?: TextOverrides<SessionExpiryGuardStrings> | undefined;
   formStrings?: TextOverrides<CredentialsFormStrings> | undefined;

package/src/{ui → session/react}/credentialsFormStrings.ts

@@ -1,6 +1,6 @@
 // Plain values, with no "use client", so a server component can import them.
 
-/** Thrown from `onSignedIn` to refuse a sign-in. Its message is shown in the form. */
+/** Thrown from `onSignedIn` to refuse a sign-in. The form shows its message. */
 export class SignInRejected extends Error {}
 
 /** The form's text. Pass the app's own language. The defaults are English. */

package/src/session/react/index.ts

@@ -4,9 +4,15 @@ export { SessionExpiryGuard } from "./SessionExpiryGuard";
 export type { SessionExpiryGuardProps } from "./SessionExpiryGuard";
 export { defaultSessionExpiryGuardStrings } from "./sessionExpiryGuardStrings";
 export type { SessionExpiryGuardStrings } from "./sessionExpiryGuardStrings";
-export { useSessionGate } from "./useSessionGate";
-export type { SessionGate } from "./useSessionGate";
 export { AppSessionProvider } from "./AppSessionProvider";
 export type { AppSessionProviderProps } from "./AppSessionProvider";
 export { RoleGate } from "./RoleGate";
 export type { RoleGateProps } from "./RoleGate";
+export { CredentialsForm } from "./CredentialsForm";
+export type { CredentialsFormProps } from "./CredentialsForm";
+export { SignInRejected, defaultCredentialsFormStrings } from "./credentialsFormStrings";
+export type { CredentialsFormStrings } from "./credentialsFormStrings";
+export { LoginPage } from "./LoginPage";
+export type { LoginPageProps } from "./LoginPage";
+export { defaultLoginPageStrings } from "./loginPageStrings";
+export type { LoginPageStrings } from "./loginPageStrings";

package/src/{ui → session/react}/loginPageStrings.ts

@@ -4,7 +4,7 @@
 export interface LoginPageStrings {
   title: string;
   forgotPassword: string;
-  /** Shown before the register link, such as "No account?". Null leaves it out. */
+  /** The text shown before the register link, such as "No account?". Null leaves it out. */
   registerPrompt: string | null;
   register: string;
 }

package/src/session/react/sessionExpiryGuardStrings.ts

@@ -7,7 +7,7 @@
 export interface SessionExpiryGuardStrings {
   expiredTitle: string;
   expiredBody: string;
-  /** Every `{minutes}` is replaced with the minutes left. */
+  /** The warning before expiry. Every `{minutes}` is replaced with the minutes left. */
   expiringSoon: string;
   reSignIn: string;
   notRestored: string;

package/src/session/react/useSessionGate.ts

@@ -6,7 +6,7 @@ import { useState, useSyncExternalStore } from "react";
 import { getSessionPromptOpen, isTerminalSessionError, subscribeSessionPrompt } from "../expiry";
 
 /**
- * Whether a protected page may render, and whether it must stay rendered.
+ * Checks whether a protected page may render, and whether it must stay rendered.
  *
  * Every gate on the way down should use this, so they all agree. A nested layout that decides on
  * its own can blank the page. That undoes the in-place recovery the re-sign-in prompt exists for.
@@ -44,8 +44,8 @@ export function useSessionGate() {
     wasUsable,
     recovering,
     /**
-     * The one answer every gate on the way down uses. A layout that decides this again can blank
-     * the page that the gate above it chose to keep.
+     * Whether the page may render. Every gate on the way down uses this one answer. A layout that
+     * decides it again can blank the page that the gate above it chose to keep.
      */
     mayRender:
       recovering ||

package/src/testing/index.ts

@@ -20,7 +20,7 @@ export const auth = {
   update: vi.fn(),
 };
 
-/** A signed-in session with `roles`. Defaults to an admin. */
+/** Builds a signed-in session with `roles`. Defaults to an admin. */
 export function makeSession({ roles = ["Admin"], ...overrides }: Partial<Session> & { roles?: string[] } = {}): Session {
   return {
     user: { id: "1", name: "admin", email: "a@b.no", roles },
@@ -40,7 +40,7 @@ export function setSession(session: Session | null | "loading"): void {
         : { data: session, status: "authenticated" };
 }
 
-/** The `next-auth/react` module, reading `auth`. */
+/** Builds the `next-auth/react` module, reading `auth`. */
 export function nextAuthMock() {
   return {
     useSession: () => ({ ...auth.state, update: (...args: unknown[]) => auth.update(...args) }),
@@ -58,7 +58,7 @@ export const navigation = {
   router: { push: vi.fn(), replace: vi.fn(), refresh: vi.fn(), back: vi.fn(), forward: vi.fn(), prefetch: vi.fn() },
 };
 
-/** The `next/navigation` hooks, reading `navigation`. */
+/** Builds the `next/navigation` hooks, reading `navigation`. */
 export function nextNavigationMock() {
   return {
     useRouter: () => navigation.router,
@@ -79,7 +79,7 @@ export const toastSpies = {
   dismiss: vi.fn(),
 };
 
-/** The `sonner` module, or `@sjolystinnovation/app-kit/toast`. A bare `toast(text)` goes to `toastSpies.message`. */
+/** Builds the `sonner` module, or `@sjolystinnovation/app-kit/toast`. A bare `toast(text)` goes to `toastSpies.message`. */
 export function toastMock() {
   const toast = Object.assign((...args: unknown[]) => toastSpies.message(...args), {
     success: (...args: unknown[]) => toastSpies.success(...args),
@@ -97,7 +97,7 @@ export function toastMock() {
 /** The HTTP calls of an app's axios instance as spies. */
 export const axiosSpies = { get: vi.fn(), post: vi.fn(), put: vi.fn(), patch: vi.fn(), delete: vi.fn() };
 
-/** A module whose default export is an axios instance, such as the app's `services/axiosInstance`. */
+/** Builds a module whose default export is an axios instance, such as the app's `services/axiosInstance`. */
 export function axiosInstanceMock() {
   return { default: axiosSpies };
 }

package/src/ui/Alert.tsx

@@ -1,16 +1,17 @@
 import type { ReactNode } from "react";
 import { cx } from "./cx";
 
+/** Props for `Alert`. */
 export interface AlertProps {
   variant?: "error" | "success" | "info" | "warning";
   /**
-   * Defaults to alert, which a screen reader interrupts for. A screen reader announces status
-   * without interrupting, on every change of its text. Use none when a separate live region
-   * announces the text.
+   * The ARIA role. A screen reader interrupts for `alert`. It announces `status` without
+   * interrupting, on every change of its text. Use `none` when a separate live region announces the
+   * text. Defaults to `alert`.
    */
   role?: "alert" | "status" | "none";
   /**
-   * Classes for placing the alert, such as a margin. Restyle it through the theme variables. A
+   * The classes for placing the alert, such as a margin. Restyle it through the theme variables. A
    * class that clashes with the alert's own wins or loses by the order Tailwind emits them in.
    */
   className?: string;
@@ -24,6 +25,7 @@ const styles: Record<NonNullable<AlertProps["variant"]>, string> = {
   warning: "bg-alert-warning-bg border-alert-warning-border text-alert-warning-text",
 };
 
+/** Renders a message in an error, success, info, or warning box. */
 export function Alert({ variant = "info", role = "alert", className, children }: AlertProps) {
   return (
     <div className={cx("rounded-alert border px-3 py-2 text-sm", styles[variant], className)} role={role}>

package/src/ui/ContentImage.tsx

@@ -1,42 +1,43 @@
 /** The widths the API serves an uploaded image at, as webp. */
 export const CONTENT_IMAGE_WIDTHS: readonly number[] = [384, 640, 768, 1024, 1366, 1600];
 
-/** Where the browser fetches an uploaded image. Site-relative, through the app's content images rewrite. */
+/** Builds the site-relative path where the browser fetches an uploaded image, through the app's content images rewrite. */
 export function contentImagePath(id: string, base = "/content-images"): string {
   return `${base}/${encodeURIComponent(id)}`;
 }
 
 /**
- * The `srcset` for an uploaded image. The API serves the nearest webp at or above the requested
- * width, or the original when the browser does not accept webp.
+ * Builds the `srcset` for an uploaded image. The API serves the nearest webp at or above the
+ * requested width, or the original when the browser does not accept webp.
  */
 export function contentImageSrcSet(id: string, widths: readonly number[] = CONTENT_IMAGE_WIDTHS, base?: string): string {
   return widths.map(w => `${contentImagePath(id, base)}?w=${w} ${w}w`).join(", ");
 }
 
+/** Props for `ContentImage`. */
 export interface ContentImageProps {
-  /** Uploaded image id. Null falls back to `fallbackSrc`, which is served as it is. */
+  /** The uploaded image's id. Null falls back to `fallbackSrc`, which is served as it is. */
   imageId: string | null;
-  /** Empty for an image that carries no meaning of its own, such as a decorative backdrop. */
+  /** The alt text. Leave it empty for an image that carries no meaning of its own, such as a decorative backdrop. */
   alt: string;
-  /** Widths the image is shown at. Required, since a browser assumes 100vw without it. */
+  /** The widths the image is shown at. It is required, since a browser assumes 100vw without it. */
   sizes: string;
   /** A static path for when there is no uploaded image. */
   fallbackSrc?: string | undefined;
   className?: string | undefined;
-  /** Intrinsic size, to reserve space. Only needed where the layout fixes no ratio. */
+  /** The intrinsic size, to reserve space. You only need it where the layout fixes no ratio. */
   width?: number | undefined;
   height?: number | undefined;
-  /** Set on the one image visible without scrolling. It loads eagerly, at high priority. */
+  /** Whether this is the one image visible without scrolling. That image loads eagerly, at high priority. */
   priority?: boolean | undefined;
   "aria-hidden"?: boolean | undefined;
-  /** Path the content images rewrite serves, `/content-images` by default. */
+  /** The path the content images rewrite serves. Defaults to `/content-images`. */
   base?: string | undefined;
-  /** Widths in the `srcset`. Defaults to the widths the API serves. */
+  /** The widths in the `srcset`. Defaults to the widths the API serves. */
   widths?: readonly number[] | undefined;
 }
 
-/** An image from the content API, served responsively from the `sizes` a call site declares. */
+/** Renders an image from the content API, served responsively from the `sizes` a call site declares. */
 export function ContentImage({
   imageId,
   alt,

package/src/ui/ErrorState.tsx

@@ -4,6 +4,7 @@ import Link from "next/link";
 import { cx } from "./cx";
 import { withDefaults, type TextOverrides } from "./withDefaults";
 
+/** The error page's text. Pass the app's own language. The defaults are English. */
 export interface ErrorStateStrings {
   title: string;
   body: string;
@@ -18,17 +19,18 @@ export const defaultErrorStateStrings: ErrorStateStrings = {
   home: "Go to the front page",
 };
 
+/** Props for `ErrorState`. */
 export interface ErrorStateProps {
   /** The `reset` Next passes to an `error.tsx`. It renders the page again. */
   reset: () => void;
-  /** Where the front page link goes, such as `/` or `/en`. */
+  /** The front page link's target, such as `/` or `/en`. */
   homeHref: string;
   strings?: TextOverrides<ErrorStateStrings> | undefined;
-  /** Classes for placing it, on the outer element. */
+  /** The classes for placing the component, on its outer element. */
   className?: string | undefined;
 }
 
-/** What an `error.tsx` shows when a page cannot be rendered. The response is still a 500. */
+/** Renders the content of an `error.tsx` when a page cannot be rendered. The response is still a 500. */
 export function ErrorState({ reset, homeHref, strings, className }: ErrorStateProps) {
   const text = withDefaults(defaultErrorStateStrings, strings);
   return (

package/src/ui/NotFoundState.tsx

@@ -2,29 +2,31 @@ import Link from "next/link";
 import { cx } from "./cx";
 import { withDefaults, type TextOverrides } from "./withDefaults";
 
-export interface NotFoundStrings {
+/** The not-found page's text. Pass the app's own language. The defaults are English. */
+export interface NotFoundStateStrings {
   code: string;
   body: string;
   home: string;
 }
 
-export const defaultNotFoundStrings: NotFoundStrings = {
+export const defaultNotFoundStateStrings: NotFoundStateStrings = {
   code: "404",
   body: "This page does not exist.",
   home: "Go home",
 };
 
+/** Props for `NotFoundState`. */
 export interface NotFoundStateProps {
-  /** Where the home link goes, such as `/` or `/en`. */
+  /** The home link's target, such as `/` or `/en`. */
   homeHref: string;
-  strings?: TextOverrides<NotFoundStrings> | undefined;
-  /** Classes for placing it, on the outer element. */
+  strings?: TextOverrides<NotFoundStateStrings> | undefined;
+  /** The classes for placing the component, on its outer element. */
   className?: string | undefined;
 }
 
-/** What a `not-found.tsx` shows. The message is the page's heading. */
+/** Renders the content of a `not-found.tsx`. The message is the page's heading. */
 export function NotFoundState({ homeHref, strings, className }: NotFoundStateProps) {
-  const text = withDefaults(defaultNotFoundStrings, strings);
+  const text = withDefaults(defaultNotFoundStateStrings, strings);
   return (
     <div className={cx("min-h-[60vh] flex flex-col items-center justify-center gap-4 px-4 text-center", className)}>
       <span className="text-6xl font-black font-state-code text-state-code">{text.code}</span>

package/src/ui/PasswordInput.tsx

@@ -4,21 +4,22 @@ import { EyeIcon, EyeSlashIcon } from "@heroicons/react/24/outline";
 import { useState, type InputHTMLAttributes } from "react";
 import { FieldError, FieldLabel, inputClass, useField } from "./field";
 
-/** The input's type is left out: the component switches it to show and hide the value. */
+/** Props for `PasswordInput`. They leave out the input's `type`, since the component switches it to show and hide the value. */
 export interface PasswordInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type"> {
   label: string;
   error?: string | undefined;
-  /** Accessible name of the toggle while the password is hidden. */
+  /** The accessible name of the toggle while the password is hidden. */
   showPasswordLabel?: string | undefined;
-  /** Accessible name of the toggle while the password is visible. */
+  /** The accessible name of the toggle while the password is visible. */
   hidePasswordLabel?: string | undefined;
   /**
-   * Classes for placing the field, such as a margin. They go on the outer element, which holds the
-   * label, the input and the error. Restyle the field through the theme variables.
+   * The classes for placing the field, such as a margin. They go on the outer element, which holds
+   * the label, the input, and the error. Restyle the field through the theme variables.
    */
   className?: string;
 }
 
+/** Renders a labeled password field with a button that shows and hides the value. */
 export function PasswordInput({
   label,
   error,

package/src/ui/ResetPasswordFlow.tsx

@@ -10,18 +10,20 @@ import { defaultResetPasswordFlowStrings, type ResetPasswordFlowStrings } from "
 import { TextInput } from "./TextInput";
 import { withDefaults, type TextOverrides } from "./withDefaults";
 
+/** Props for `ResetPasswordFlow`. */
 export interface ResetPasswordFlowProps {
-  /** Asks the API to email a reset code, such as `createUserService`'s `requestPasswordReset`. */
+  /** A function that asks the API to email a reset code, such as `createUserService`'s `requestPasswordReset`. */
   requestReset: (data: { email: string }) => Promise<unknown>;
-  /** Sets the new password with the code, such as `createUserService`'s `resetPassword`. */
+  /** A function that sets the new password with the code, such as `createUserService`'s `resetPassword`. */
   reset: (data: { email: string; code: string; newPassword: string }) => Promise<{ message?: string } | unknown>;
-  /** Where the sign-in links go. */
+  /** The path the sign-in links go to. */
   loginHref: string;
-  /** From the emailed link. A code opens the flow on its last step. */
+  /** The email from the emailed link. */
   initialEmail?: string | undefined;
+  /** The code from the emailed link. A code opens the flow on its last step. */
   initialCode?: string | undefined;
   strings?: TextOverrides<ResetPasswordFlowStrings> | undefined;
-  /** Replaces the page's outer spacing, such as when the flow sits inside the app's own card. */
+  /** The classes that replace the page's outer spacing, such as when the flow sits inside the app's own card. */
   className?: string | undefined;
   /** The password rule messages, for the app's own language. */
   passwordStrings?: TextOverrides<PasswordStrings> | undefined;
@@ -31,9 +33,9 @@ const button =
   "w-full rounded-button bg-button-primary-bg text-button-primary-text font-semibold py-2.5 hover:brightness-95 disabled:opacity-60 transition";
 
 /**
- * Password reset in two steps: the email asks for a code, then the code and a new password set it. The
- * new password is checked against the API's rules before it is sent. A link with the email and code,
- * such as an invite, opens on the second step.
+ * Renders password reset in two steps: the email asks for a code, then the code and a new password
+ * set it. The flow checks the new password against the API's rules before it sends it. A link with
+ * the email and code, such as an invite, opens on the second step.
  */
 export function ResetPasswordFlow({
   requestReset,

package/src/ui/TextArea.tsx

@@ -3,20 +3,22 @@
 import { useCallback, useEffect, useRef, type TextareaHTMLAttributes } from "react";
 import { FieldError, FieldLabel, inputClass, useField } from "./field";
 
+/** Props for `TextArea`. */
 export interface TextAreaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
   label: string;
   error?: string | undefined;
   /**
-   * Classes for placing the field, such as a margin. They go on the outer element, which holds the
-   * label, the text area and the error. Restyle the field through the theme variables.
+   * The classes for placing the field, such as a margin. They go on the outer element, which holds
+   * the label, the text area, and the error. Restyle the field through the theme variables.
    */
   className?: string | undefined;
-  /** Grows with its text, from `rows` lines up to `maxRows` lines. On by default. */
+  /** Whether the box grows with its text, from `rows` lines up to `maxRows` lines. Defaults to `true`. */
   autoGrow?: boolean | undefined;
-  /** The most lines an auto-growing box shows before it scrolls. Defaults to 12. */
+  /** The most lines an auto-growing box shows before it scrolls. Defaults to `12`. */
   maxRows?: number | undefined;
 }
 
+/** Renders a labeled text area that can grow with its text. */
 export function TextArea({ label, error, className, autoGrow = true, maxRows = 12, rows = 3, onInput, ...props }: TextAreaProps) {
   const field = useField(props, error);
   const ref = useRef<HTMLTextAreaElement>(null);

package/src/ui/TextInput.tsx

@@ -3,16 +3,18 @@
 import type { InputHTMLAttributes } from "react";
 import { FieldError, FieldLabel, inputClass, useField } from "./field";
 
+/** Props for `TextInput`. */
 export interface TextInputProps extends InputHTMLAttributes<HTMLInputElement> {
   label: string;
   error?: string | undefined;
   /**
-   * Classes for placing the field, such as a margin. They go on the outer element, which holds the
-   * label, the input and the error. Restyle the field through the theme variables.
+   * The classes for placing the field, such as a margin. They go on the outer element, which holds
+   * the label, the input, and the error. Restyle the field through the theme variables.
    */
   className?: string | undefined;
 }
 
+/** Renders a labeled text input with an optional error message. */
 export function TextInput({ label, error, className, ...props }: TextInputProps) {
   const field = useField(props, error);
 

package/src/ui/Toggle.tsx

@@ -5,14 +5,14 @@ import { cx } from "./cx";
 
 type ToggleBase = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onChange" | "role" | "type" | "aria-checked"> & {
   checked: boolean;
-  /** Called with the new state when the switch is flipped. */
+  /** A function called with the new state when the switch is flipped. */
   onChange: (checked: boolean) => void;
 };
 
-/** A switch needs a name. Either a visible `label`, or an `aria-label` when there is none. */
+/** Props for `Toggle`. A switch needs a name: either a visible `label`, or an `aria-label` when there is none. */
 export type ToggleProps = ToggleBase & ({ label: string } | { label?: undefined; "aria-label": string });
 
-/** An on and off switch, for a setting that takes effect at once. */
+/** Renders an on and off switch, for a setting that takes effect at once. */
 export function Toggle({ checked, onChange, label, className, disabled, onClick, ...props }: ToggleProps) {
   const handleClick = (event: MouseEvent<HTMLButtonElement>) => {
     onClick?.(event);

package/src/ui/field.tsx

@@ -3,13 +3,13 @@
 import { useId, type AriaAttributes, type ReactNode } from "react";
 import { cx } from "./cx";
 
-/** The props of a field control that useField reads. An `<input>` and a `<textarea>` both have them. */
+/** The props of a field control that `useField` reads. An `<input>` and a `<textarea>` both have them. */
 export type FieldControlProps = Pick<AriaAttributes, "aria-required" | "aria-invalid" | "aria-describedby"> & {
   id?: string | undefined;
   required?: boolean | undefined;
 };
 
-/** The ids and aria attributes a labelled input needs, from the caller's own props. */
+/** Builds the ids and aria attributes a labeled input needs, from the caller's own props. */
 export function useField(props: FieldControlProps, error: string | undefined) {
   // A generated id ties the label to its own control, even when two fields on a page share a name.
   const generated = useId();
@@ -29,7 +29,7 @@ export function useField(props: FieldControlProps, error: string | undefined) {
   };
 }
 
-/** The input's look, with the error border when there is an error. */
+/** Builds the input's classes, with the error border when there is an error. */
 export function inputClass(error: string | undefined, extra?: string): string {
   return cx(
     "w-full rounded-input border px-3 py-input-y text-sm bg-input-bg text-input-text placeholder-input-placeholder focus:outline-hidden focus:ring-(length:--input-focus-ring-width) focus:ring-input-focus-ring",
@@ -38,6 +38,7 @@ export function inputClass(error: string | undefined, extra?: string): string {
   );
 }
 
+/** Renders a field's label, with a star when the field is required. */
 export function FieldLabel({ htmlFor, required, children }: { htmlFor: string; required: boolean | undefined; children: ReactNode }) {
   return (
     <label htmlFor={htmlFor} className="block text-field-label font-medium text-field-label-text mb-field-label">
@@ -47,6 +48,7 @@ export function FieldLabel({ htmlFor, required, children }: { htmlFor: string; r
   );
 }
 
+/** Renders a field's error message, or nothing when there is none. */
 export function FieldError({ id, error }: { id: string; error: string | undefined }) {
   if (!error) return null;
   return (

package/src/ui/index.ts

@@ -2,18 +2,10 @@ export { Alert } from "./Alert";
 export type { AlertProps } from "./Alert";
 export { ContentImage, CONTENT_IMAGE_WIDTHS, contentImagePath, contentImageSrcSet } from "./ContentImage";
 export type { ContentImageProps } from "./ContentImage";
-export { CredentialsForm } from "./CredentialsForm";
-export type { CredentialsFormProps } from "./CredentialsForm";
-export { SignInRejected, defaultCredentialsFormStrings } from "./credentialsFormStrings";
-export type { CredentialsFormStrings } from "./credentialsFormStrings";
 export { ErrorState, defaultErrorStateStrings } from "./ErrorState";
 export type { ErrorStateProps, ErrorStateStrings } from "./ErrorState";
-export { LoginPage } from "./LoginPage";
-export type { LoginPageProps } from "./LoginPage";
-export { defaultLoginPageStrings } from "./loginPageStrings";
-export type { LoginPageStrings } from "./loginPageStrings";
-export { NotFoundState, defaultNotFoundStrings } from "./NotFoundState";
-export type { NotFoundStateProps, NotFoundStrings } from "./NotFoundState";
+export { NotFoundState, defaultNotFoundStateStrings } from "./NotFoundState";
+export type { NotFoundStateProps, NotFoundStateStrings } from "./NotFoundState";
 export { PasswordInput } from "./PasswordInput";
 export type { PasswordInputProps } from "./PasswordInput";
 export { ResetPasswordFlow } from "./ResetPasswordFlow";

package/src/ui/resetPasswordFlowStrings.ts

@@ -6,27 +6,27 @@
  */
 export interface ResetPasswordFlowStrings {
   title: string;
-  /** Shown before the sign-in link under the title, such as "Remembered it?". */
+  /** The text shown before the sign-in link under the title, such as "Remembered it?". */
   signInPrompt: string | null;
   signIn: string;
-  /** The link back to sign-in once the password is set. */
+  /** The text of the link back to sign-in once the password is set. */
   backToSignIn: string;
-  /** Shown above the email field on the first step. */
+  /** The text shown above the email field on the first step. */
   intro: string | null;
-  /** Shown at the top of the second step, once a code is on its way. */
+  /** The text shown at the top of the second step, once a code is on its way. */
   codeSent: string | null;
   email: string;
   code: string;
   newPassword: string;
-  /** Shown under the new password field. */
+  /** The text shown under the new password field. */
   passwordHint: string | null;
   requestCode: string;
   requestingCode: string;
   setPassword: string;
   settingPassword: string;
-  /** Shown when the password is set. Null shows the API's own message, or only the link when it sends none. */
+  /** The text shown when the password is set. Null shows the API's own message, or only the link when the API sends none. */
   done: string | null;
-  /** Shown for a password the rules refuse. Null lists each rule it breaks. */
+  /** The text shown for a password the rules refuse. Null lists each rule it breaks. */
   passwordInvalid: string | null;
   somethingWentWrong: string;
 }

package/src/validation/fieldErrors.ts

@@ -1,11 +1,12 @@
 import type { z } from "zod";
 
-/** Picks the text shown for an issue, such as a translated message by the issue's code. */
+/** A function that picks the text shown for an issue, such as a translated message by the issue's code. */
 export type IssueMessage = (issue: z.core.$ZodIssue) => string;
 
 /**
- * A failed parse's issues by the top-level field they belong to, for showing beside each input. By
- * default each field gets its first issue's message. With `all: true` it gets every message, in order.
+ * Groups a failed parse's issues by the top-level field they belong to, for showing beside each
+ * input. By default each field gets its first issue's message. With `all: true` it gets every
+ * message, in order.
  * `message` replaces zod's text, such as with the app's own translations. Issues without a field,
  * from a refinement of the whole object, are left out.
  */

package/src/validation/password.ts

@@ -6,11 +6,11 @@ export { PASSWORD_MIN_LENGTH, defaultPasswordStrings, passwordProblems } from ".
 export type { PasswordStrings } from "./passwordRules";
 
 /**
- * A zod schema for a new password, with the rules the APIs enforce through ASP.NET Identity. Identity
- * counts only ASCII letters and digits, so "Å" is neither an uppercase nor a lowercase letter here.
- * Length counts UTF-16 code units, as Identity does. There is no upper limit, because Identity has
- * none. An app whose API sets one adds it with `.max()`. A failing password gets one issue per rule
- * it breaks.
+ * Builds a zod schema for a new password, with the rules the APIs enforce through ASP.NET Identity.
+ * Identity counts only ASCII letters and digits, so "Å" is neither an uppercase nor a lowercase
+ * letter here. Length counts UTF-16 code units, as Identity does. There is no upper limit, because
+ * Identity has none. An app whose API sets one adds it with `.max()`. A failing password gets one
+ * issue per rule it breaks.
  */
 export function passwordSchema(strings?: TextOverrides<PasswordStrings>) {
   const text = withDefaults(defaultPasswordStrings, strings);

package/src/validation/passwordRules.ts

@@ -21,8 +21,8 @@ export const defaultPasswordStrings: PasswordStrings = {
 };
 
 /**
- * The message of every password rule the password breaks, in the order `passwordSchema` checks them.
- * An empty list means the APIs accept it.
+ * Lists the message of every password rule the password breaks, in the order `passwordSchema`
+ * checks them. An empty list means the APIs accept it.
  */
 export function passwordProblems(password: string, strings?: TextOverrides<PasswordStrings>): string[] {
   const text = withDefaults(defaultPasswordStrings, strings);