@nxgt/material 2.16.0 → 2.18.0

package/dist/lib/components/ui/fields/form-section/form-section-classes.d.ts

@@ -0,0 +1,30 @@
+/** The heading elements a FormSection's title can render as. */
+export type FormSectionTitleElement = 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+/**
+ * The section: a whole row of the form's grid (`.form-grid-layout`
+ * `[data-slot="form-fields"]`), and a container of its own, so its fields
+ * take columns by the section's width, inside a form or standalone.
+ */
+export declare const formSectionRootClass = "@container col-span-full flex w-full min-w-0 flex-col gap-2";
+/**
+ * The rule between two sections: a top border on a section that follows
+ * another one, never on the first.
+ */
+export declare const formSectionSeparatedClass = "[[data-slot=form-section]+&]:mt-2 [[data-slot=form-section]+&]:border-t [[data-slot=form-section]+&]:pt-4";
+/** The title and the actions, which wrap under the title on a phone. */
+export declare const formSectionHeaderClass = "flex min-w-0 flex-wrap items-center justify-between gap-2";
+/**
+ * Set apart from the fields' labels, which read as titles: small, semibold,
+ * uppercase and muted. `text-muted-foreground` reads 4.5:1 on the form's
+ * background in both themes.
+ */
+export declare const formSectionTitleClass = "min-w-0 break-words font-semibold text-muted-foreground text-sm uppercase tracking-wide";
+export declare const formSectionActionsClass = "flex flex-wrap items-center gap-2";
+export declare const formSectionDescriptionClass = "break-words text-muted-foreground text-sm";
+/**
+ * The fields: one column on a phone, then the form grid's own columns. The
+ * form grid's wide-field rules (a switch, a textarea, chips, files, rich
+ * text on a row of their own) are descendant selectors under
+ * `[data-slot="form-fields"]`, so they still reach the fields in here.
+ */
+export declare const formSectionFieldsClass = "grid min-w-0 grid-cols-1 place-items-start gap-2 @2xl:grid-cols-2 @4xl:grid-cols-3 @6xl:grid-cols-4";

package/dist/lib/components/ui/fields/form-section/form-section.d.ts

@@ -0,0 +1,25 @@
+import { ComponentProps, ReactNode } from 'react';
+import { FormSectionTitleElement } from './form-section-classes';
+export type { FormSectionTitleElement } from './form-section-classes';
+export type FormSectionProps = Omit<ComponentProps<'div'>, 'title'> & {
+    /** The section's heading. */
+    title: ReactNode;
+    /**
+     * The heading element; `'h2'` by default (a section under the page's
+     * `h1`). Pass `'h3'` when the form already sits under an `h2`.
+     */
+    titleAs?: FormSectionTitleElement;
+    /** A line under the title, tied to the group with `aria-describedby`. */
+    description?: ReactNode;
+    /** Controls beside the title (e.g. "Add"), wrapping under it on a phone. */
+    actions?: ReactNode;
+    /** A rule above the section when it follows another FormSection. Default `true`. */
+    separated?: boolean;
+};
+/**
+ * A titled section of a form: a heading, an optional description and
+ * actions, then its fields. Inside `.form-grid-layout`'s
+ * `[data-slot="form-fields"]` it takes a whole row and lays its fields out
+ * in the form's columns; one column on a phone.
+ */
+export declare function FormSection({ title, titleAs: Title, description, actions, separated, className, children, ...props }: FormSectionProps): import("react").JSX.Element;

package/dist/lib/components/ui/fields/form-section/index.d.ts

@@ -0,0 +1 @@
+export * from './form-section';

package/dist/lib/components/ui/fields/index.d.ts

@@ -5,6 +5,7 @@ export * from './country-field';
 export * from './currency-field';
 export * from './email-field';
 export * from './field';
+export * from './form-section';
 export * from './inline-edit';
 export * from './input-group-field';
 export * from './number-field';

package/dist/lib/components/ui/forms/index.d.ts

@@ -1 +1,2 @@
 export * from './form-field';
+export * from './use-code-resolver';

package/dist/lib/components/ui/forms/use-code-resolver.d.ts

@@ -0,0 +1,42 @@
+import { CodeIssue } from '@nxgt/material-core/code-errors';
+import { FieldValues, Resolver } from 'react-hook-form';
+import { z } from 'zod';
+import { Language, Translate } from '../../../i18n/types';
+export { type CodeErrorMap, type CodeIssue, createCodeErrorMap, defaultCodeOf, isEmptyRequired, } from '@nxgt/material-core/code-errors';
+export type CodeResolverOptions = {
+    /**
+     * The app's translator, `createTranslator(mergeResources(resources,
+     * appResources))`: it words the codes (`translate(code, params,
+     * language)`; a key it returns verbatim has no words) and is handed to
+     * `zodLocaleError`, so the app's `material.zod.*` overrides apply. Without
+     * it, every issue is worded by the package's own zod messages. Pass a
+     * stable function (module scope): a new one re-creates the resolver.
+     */
+    translate?: Translate<any>;
+    /**
+     * Which code an issue carries. Defaults to `defaultCodeOf`: a custom
+     * issue's `params.code`. Pass a stable function.
+     */
+    codeOf?: (issue: CodeIssue) => string | undefined;
+    /**
+     * The language to word the errors in. Defaults to `I18nProvider`'s, else
+     * what `zodLocaleError` reads by default (the stored language).
+     */
+    language?: Language;
+};
+/**
+ * A react-hook-form resolver for a zod 4 `schema` whose errors are worded in
+ * the page's language: a refinement carrying a code in `params.code`
+ * (`.refine(isFree, { params: { code: 'errors.taken' } })`) reads as the
+ * app's words for that code, and every other issue as the package's zod
+ * messages (`zodLocaleError`) — zod's own are English only. One resolver
+ * per schema and language, not one per render: switching the language
+ * re-words the errors on the next validation.
+ *
+ * @example
+ * ```tsx
+ * const resolver = useCodeResolver(schema, { translate });
+ * const form = useForm({ resolver, defaultValues });
+ * ```
+ */
+export declare function useCodeResolver<Input extends FieldValues, Output>(schema: z.ZodType<Output, Input>, { translate, codeOf, language: languageOption }?: CodeResolverOptions): Resolver<Input, unknown, Output>;

package/dist/lib/components/ui/layout/auth-card/auth-card-notice.d.ts

@@ -0,0 +1,18 @@
+import { ReactNode } from 'react';
+import { AuthCardNoticeTone } from './auth-card';
+type AuthCardNoticeProps = {
+    notice: ReactNode;
+    tone: AuthCardNoticeTone;
+    /** Whether there is a notice to show. */
+    shown: boolean;
+};
+/**
+ * The notice above the form. A polite status is announced when its text
+ * changes inside a live region that was already in the page, so that region
+ * is always rendered and a non-error notice goes into it. It takes no room
+ * while empty (`empty:-mb-4` cancels the card's gap; `display: none` would
+ * take it out of the accessibility tree). An error is an `alert`, inserted on
+ * demand: that is announced reliably.
+ */
+export declare function AuthCardNotice({ notice, tone, shown }: AuthCardNoticeProps): import("react").JSX.Element;
+export {};

package/dist/lib/components/ui/layout/auth-card/auth-card.d.ts

@@ -0,0 +1,35 @@
+import { ComponentProps, ReactNode } from 'react';
+/** The notice's colour, and its role: `error` is an alert, the rest a status. */
+export type AuthCardNoticeTone = 'info' | 'success' | 'warning' | 'error';
+export type AuthCardProps = Omit<ComponentProps<'main'>, 'title'> & {
+    /** The page's `h1`, at the top of the card. */
+    title: ReactNode;
+    /** A line under the title. */
+    description?: ReactNode;
+    /** A notice above the content: an expired link, a signed-out message. */
+    notice?: ReactNode;
+    /** `'info'` by default; `'error'` makes the notice an alert, the others a status. */
+    noticeTone?: AuthCardNoticeTone;
+    /**
+     * Moves the focus to the title once shown: for an end state that replaced
+     * the form the user acted on ("Check your inbox"), so a screen reader reads
+     * it and the keyboard goes on from there.
+     */
+    focusTitle?: boolean;
+    /** The left of the row above the card: a logo, the product's name. */
+    brand?: ReactNode;
+    /** The right of that row: a language switcher, a theme toggle. */
+    toolbar?: ReactNode;
+    /** Above that row: an update notice, a maintenance banner. */
+    banner?: ReactNode;
+    /** Under the card: links to the terms, to help. */
+    footer?: ReactNode;
+    /** The form. */
+    children: ReactNode;
+};
+/**
+ * The frame of a signed-out page (sign in, sign up, a reset link): one
+ * `main`, a centred card whose title is the page's `h1`, a row above it for
+ * the brand and a toolbar, padded clear of a phone's notch and home bar.
+ */
+export declare function AuthCard({ title, description, notice, noticeTone, focusTitle, brand, toolbar, banner, footer, className, children, ...props }: AuthCardProps): import("react").JSX.Element;

package/dist/lib/components/ui/layout/auth-card/index.d.ts

@@ -0,0 +1 @@
+export * from './auth-card';

package/dist/lib/components/ui/layout/index.d.ts

@@ -1,5 +1,6 @@
 export * from './app-bar';
 export * from './app-shell';
+export * from './auth-card';
 export * from './background';
 export * from './breadcrumb';
 export * from './doc';

package/dist/lib/components/ui/selection/autocomplete/types.d.ts

@@ -3,6 +3,11 @@ import { InputGroupFieldProps } from '../../fields/input-group-field/input-group
 export type AutocompleteOption = {
     value: string;
     label: string;
+    /**
+     * Rendered and announced as disabled: the arrow keys still reach it so that
+     * it is announced, but it is never picked.
+     */
+    disabled?: boolean;
 };
 /**
  * How the list is filtered as the user types: `'accent-insensitive'` (the
@@ -31,7 +36,10 @@ export type AutocompleteSearchProps<T> = {
     onSearchError?: (error: unknown) => void;
     /** Controlled loading, when you fetch `options` yourself from `onQueryChange`. */
     loading?: boolean;
-    /** Controlled failure text, shown and announced in place of the options. */
+    /**
+     * Failure text, shown and announced in place of the options — with
+     * `onSearch` too, where it replaces the generic "The search failed".
+     */
     searchError?: ReactNode;
     /** The pause before `onSearch` and `onQueryChange` run, in ms. Default 250. */
     debounceMs?: number;

package/dist/lib/components/ui/selection/autocomplete/use-autocomplete-status.d.ts

@@ -20,9 +20,9 @@ type List = {
  */
 export declare function useAutocompleteStatus(props: StatusProps, list: List): {
     loading: boolean;
-    failure: ReactNode;
+    failure: string | number | bigint | true | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import('react').ReactPortal | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null;
     hint: string | null;
     emptyText: string | number | bigint | true | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import('react').ReactPortal | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null;
-    announcement: ReactNode;
+    announcement: string | number | bigint | true | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import('react').ReactPortal | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null;
 };
 export {};

package/dist/lib/components/ui/selection/autocomplete/use-autocomplete.d.ts

@@ -20,10 +20,10 @@ export declare function useAutocomplete<T extends AutocompleteOption>(props: Aut
     filter: ((option: T, query: string) => boolean) | null;
     status: {
         loading: boolean;
-        failure: import('react').ReactNode;
+        failure: string | number | bigint | true | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<import('react').ReactNode> | Promise<string | number | bigint | boolean | import('react').ReactPortal | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<import('react').ReactNode> | null | undefined> | null;
         hint: string | null;
         emptyText: string | number | bigint | true | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<import('react').ReactNode> | Promise<string | number | bigint | boolean | import('react').ReactPortal | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<import('react').ReactNode> | null | undefined> | null;
-        announcement: import('react').ReactNode;
+        announcement: string | number | bigint | true | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<import('react').ReactNode> | Promise<string | number | bigint | boolean | import('react').ReactPortal | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<import('react').ReactNode> | null | undefined> | null;
     };
 };
 export {};

package/dist/lib/hooks/index.d.ts

@@ -1,6 +1,7 @@
 export * from './resolve-theme';
 export * from './use-allowed-transitions';
 export { useCspNonce } from './use-csp-nonce';
+export * from './use-focus-on-mount';
 export * from './use-formatters';
 export * from './use-heading-spy';
 export * from './use-is-client';
@@ -10,4 +11,5 @@ export * from './use-navigation';
 export * from './use-number-formatter';
 export * from './use-options';
 export * from './use-search-param';
+export * from './use-submit-once';
 export * from './use-theme';

package/dist/lib/hooks/use-focus-on-mount.d.ts

@@ -0,0 +1,24 @@
+import { RefObject } from 'react';
+/**
+ * A ref whose element takes focus once mounted, and again whenever `focus`
+ * turns true. Put it on the heading of what replaced the content the user
+ * acted on — a wizard's new step, an end state ("Message sent") — so a
+ * screen reader reads it and the keyboard goes on from there instead of from
+ * the top of the page.
+ *
+ * The element needs `tabIndex={-1}` unless it is natively focusable (a
+ * button, a link, a field): a heading is not.
+ *
+ * @example
+ * ```tsx
+ * function Done() {
+ *   const title = useFocusOnMount<HTMLHeadingElement>();
+ *   return (
+ *     <h2 ref={title} tabIndex={-1}>
+ *       Message sent
+ *     </h2>
+ *   );
+ * }
+ * ```
+ */
+export declare function useFocusOnMount<T extends HTMLElement>(focus?: boolean): RefObject<T | null>;

package/dist/lib/hooks/use-submit-once.d.ts

@@ -0,0 +1,32 @@
+import { SubmitGuard } from '@nxgt/material-core/submit-guard';
+export { busySettler, createSubmitGuard, type SubmitGuard, type SubmitOnceOptions, } from '@nxgt/material-core/submit-guard';
+/**
+ * One submit in flight for a form: wraps the submit handler so a second
+ * click, or Enter, before the first request ends is dropped. A disabled or
+ * `loading` button only stops clicks once it has rendered, and never Enter
+ * in a field.
+ *
+ * When the guard opens again:
+ * - **The handler returns the request's promise**: when it ends, fulfilled
+ *   or rejected (the rejection still reaches the caller).
+ * - **`busy` is passed** (a router's navigation state): once it was true and
+ *   is false again — for the run that was on its way when it rose, never a
+ *   newer one. A handler that returns no promise then waits for `busy`.
+ * - **Neither**: a handler that returns no promise (it returned early, or
+ *   did its work synchronously) opens it at once.
+ *
+ * So return the request's promise, or pass `busy`.
+ *
+ * @example
+ * ```tsx
+ * const submitOnce = useSubmitOnce();
+ * const { handleSubmit } = useForm<Values>();
+ * // react-hook-form's handleSubmit returns a promise: the guard opens again
+ * // when `save` ends.
+ * <form onSubmit={submitOnce(handleSubmit(save))}>…</form>
+ *
+ * // A request tracked by a flag instead (a router's navigation state):
+ * const submitOnce = useSubmitOnce(navigation.state !== 'idle');
+ * ```
+ */
+export declare function useSubmitOnce(busy?: boolean): SubmitGuard['once'];

package/dist/lib/i18n/resources/en/en.d.ts

@@ -1272,5 +1272,26 @@ export declare const en: {
             truncated: string;
             content: string;
         };
+        "enrolment-secret": {
+            "qr-label": string;
+            "open-app": string;
+            manual: string;
+            "secret-label": string;
+            copy: string;
+            copied: string;
+        };
+        "recovery-codes": {
+            title: string;
+            warning: string;
+            list: string;
+            copy: string;
+            copied: string;
+            "copy-failed": string;
+            download: string;
+            print: string;
+            saved: string;
+            "saved-required": string;
+            done: string;
+        };
     };
 };

package/dist/lib/i18n/resources/en/material.json.d.ts

@@ -1261,6 +1261,27 @@ declare const _default: {
 		"download": "Download",
 		"truncated": "Showing the first {size} of this file.",
 		"content": "Contents of {name}"
+	},
+	"enrolment-secret": {
+		"qr-label": "QR code to scan with your authenticator app",
+		"open-app": "Open in your authenticator app",
+		"manual": "Or type this key in the app:",
+		"secret-label": "Setup key",
+		"copy": "Copy the key",
+		"copied": "Key copied"
+	},
+	"recovery-codes": {
+		"title": "Recovery codes",
+		"warning": "Each code works once. Keep them somewhere safe: they are shown only now.",
+		"list": "Recovery codes",
+		"copy": "Copy codes",
+		"copied": "Codes copied",
+		"copy-failed": "Copy failed",
+		"download": "Download",
+		"print": "Print",
+		"saved": "I have saved these codes",
+		"saved-required": "Tick the box once your codes are safe",
+		"done": "Done"
 	}
 }
 ;

package/dist/lib/i18n/resources/fr/fr.d.ts

@@ -1272,5 +1272,26 @@ export declare const fr: {
             truncated: string;
             content: string;
         };
+        "enrolment-secret": {
+            "qr-label": string;
+            "open-app": string;
+            manual: string;
+            "secret-label": string;
+            copy: string;
+            copied: string;
+        };
+        "recovery-codes": {
+            title: string;
+            warning: string;
+            list: string;
+            copy: string;
+            copied: string;
+            "copy-failed": string;
+            download: string;
+            print: string;
+            saved: string;
+            "saved-required": string;
+            done: string;
+        };
     };
 };

package/dist/lib/i18n/resources/fr/material.json.d.ts

@@ -1261,6 +1261,27 @@ declare const _default: {
 		"download": "Télécharger",
 		"truncated": "Seuls les premiers {size} de ce fichier sont affichés.",
 		"content": "Contenu de {name}"
+	},
+	"enrolment-secret": {
+		"qr-label": "Code QR à scanner avec votre application d'authentification",
+		"open-app": "Ouvrir dans votre application d'authentification",
+		"manual": "Ou saisissez cette clé dans l'application :",
+		"secret-label": "Clé de configuration",
+		"copy": "Copier la clé",
+		"copied": "Clé copiée"
+	},
+	"recovery-codes": {
+		"title": "Codes de récupération",
+		"warning": "Chaque code ne sert qu'une fois. Gardez-les en lieu sûr : ils ne sont affichés que maintenant.",
+		"list": "Codes de récupération",
+		"copy": "Copier les codes",
+		"copied": "Codes copiés",
+		"copy-failed": "Échec de la copie",
+		"download": "Télécharger",
+		"print": "Imprimer",
+		"saved": "J'ai enregistré ces codes",
+		"saved-required": "Cochez la case une fois vos codes en lieu sûr",
+		"done": "Terminé"
 	}
 }
 ;

package/dist/lib/i18n/resources/resources.d.ts

@@ -1270,6 +1270,27 @@ export declare const resources: {
                 truncated: string;
                 content: string;
             };
+            "enrolment-secret": {
+                "qr-label": string;
+                "open-app": string;
+                manual: string;
+                "secret-label": string;
+                copy: string;
+                copied: string;
+            };
+            "recovery-codes": {
+                title: string;
+                warning: string;
+                list: string;
+                copy: string;
+                copied: string;
+                "copy-failed": string;
+                download: string;
+                print: string;
+                saved: string;
+                "saved-required": string;
+                done: string;
+            };
         };
     };
     fr: {
@@ -2537,6 +2558,27 @@ export declare const resources: {
                 truncated: string;
                 content: string;
             };
+            "enrolment-secret": {
+                "qr-label": string;
+                "open-app": string;
+                manual: string;
+                "secret-label": string;
+                copy: string;
+                copied: string;
+            };
+            "recovery-codes": {
+                title: string;
+                warning: string;
+                list: string;
+                copy: string;
+                copied: string;
+                "copy-failed": string;
+                download: string;
+                print: string;
+                saved: string;
+                "saved-required": string;
+                done: string;
+            };
         };
     };
 };