@sjolystinnovation/app-kit 0.21.0 → 1.0.0

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/errorStateStrings.ts

@@ -0,0 +1,16 @@
+// Plain values, with no "use client", so a server component can import them.
+
+/** The error page's text. Pass the app's own language. The defaults are English. */
+export interface ErrorStateStrings {
+  title: string;
+  body: string;
+  tryAgain: string;
+  home: string;
+}
+
+export const defaultErrorStateStrings: ErrorStateStrings = {
+  title: "Temporarily unavailable",
+  body: "We can't reach the service right now. Please try again shortly.",
+  tryAgain: "Try again",
+  home: "Go to the front page",
+};

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

@@ -1,25 +1,21 @@
 export { Alert } from "./Alert";
 export type { AlertProps } from "./Alert";
-export { ContentImage, CONTENT_IMAGE_WIDTHS, contentImagePath, contentImageSrcSet } from "./ContentImage";
+export { ContentImage, 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 { ErrorState } from "./ErrorState";
+export type { ErrorStateProps } from "./ErrorState";
+export { defaultErrorStateStrings } from "./errorStateStrings";
+export type { ErrorStateStrings } from "./errorStateStrings";
+export { NotFoundState } from "./NotFoundState";
+export type { NotFoundStateProps } from "./NotFoundState";
+export { defaultNotFoundStateStrings } from "./notFoundStateStrings";
+export type { NotFoundStateStrings } from "./notFoundStateStrings";
 export { PasswordInput } from "./PasswordInput";
 export type { PasswordInputProps } from "./PasswordInput";
 export { ResetPasswordFlow } from "./ResetPasswordFlow";
 export type { ResetPasswordFlowProps } from "./ResetPasswordFlow";
 export { defaultResetPasswordFlowStrings } from "./resetPasswordFlowStrings";
-export type { ResetPasswordFlowStrings } from "./resetPasswordFlowStrings";
+export type { ResetPasswordErrorStrings, ResetPasswordFlowStrings, ResetPasswordValidationStrings } from "./resetPasswordFlowStrings";
 export { TextArea } from "./TextArea";
 export type { TextAreaProps } from "./TextArea";
 export { TextInput } from "./TextInput";

package/src/ui/notFoundStateStrings.ts

@@ -0,0 +1,14 @@
+// Plain values, with no "use client", so a server component can import them.
+
+/** 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 defaultNotFoundStateStrings: NotFoundStateStrings = {
+  code: "404",
+  body: "This page does not exist.",
+  home: "Go home",
+};

package/src/ui/resetPasswordFlowStrings.ts

@@ -1,34 +1,65 @@
 // Plain values, with no "use client", so a server component can import them.
 
+/**
+ * The flow's text for each field error code of SjolystInnovation.AppKit.Auth's reset endpoints,
+ * shown under the email, code or new password field. `{max}` in `passwordTooShort` becomes the
+ * API's least number of characters. The flow shows the API's own message for a code that is not
+ * here, such as `weakPassword` from a password rule the app adds.
+ */
+export interface ResetPasswordValidationStrings {
+  required: string;
+  invalidEmail: string;
+  passwordTooShort: string;
+  passwordRequiresDigit: string;
+  passwordRequiresLower: string;
+  passwordRequiresUpper: string;
+  passwordRequiresNonAlphanumeric: string;
+}
+
+/**
+ * The flow's text for each code of SjolystInnovation.AppKit.Auth's reset endpoints that is not
+ * about one field. The flow shows the API's own message for a code that is not here.
+ */
+export interface ResetPasswordErrorStrings {
+  /** The code is wrong or expired, or the email has no active account. */
+  invalidResetCode: string;
+  /** Five wrong codes in a row. The user has to ask for a new code. */
+  tooManyResetAttempts: string;
+}
+
 /**
  * The reset flow's text. Pass the app's own language. The defaults are English. A text that is null
  * is left out of the page.
  */
 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;
+  /** The field error texts, by code. Any code left out keeps its default. */
+  validation: ResetPasswordValidationStrings;
+  /** The texts for the other refusals, by code. Any code left out keeps its default. */
+  errors: ResetPasswordErrorStrings;
 }
 
 export const defaultResetPasswordFlowStrings: ResetPasswordFlowStrings = {
@@ -49,4 +80,17 @@ export const defaultResetPasswordFlowStrings: ResetPasswordFlowStrings = {
   done: null,
   passwordInvalid: null,
   somethingWentWrong: "Something went wrong",
+  validation: {
+    required: "Required.",
+    invalidEmail: "Not a valid email address.",
+    passwordTooShort: "Passwords must be at least {max} characters.",
+    passwordRequiresDigit: "Passwords must have at least one digit ('0'-'9').",
+    passwordRequiresLower: "Passwords must have at least one lowercase ('a'-'z').",
+    passwordRequiresUpper: "Passwords must have at least one uppercase ('A'-'Z').",
+    passwordRequiresNonAlphanumeric: "Passwords must have at least one non alphanumeric character.",
+  },
+  errors: {
+    invalidResetCode: "Invalid or expired reset code.",
+    tooManyResetAttempts: "Too many attempts. Request a new reset code.",
+  },
 };

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);