@nxgt/material 2.15.0 → 2.17.0

package/dist/lib/components/ui/display/recovery-codes/types.d.ts

@@ -0,0 +1,64 @@
+import { ComponentProps, ReactNode } from 'react';
+/** The heading levels the title may take. */
+export type RecoveryCodesTitleElement = 'h2' | 'h3' | 'h4';
+/** Every built-in string of {@link RecoveryCodes}, each overridable. */
+export type RecoveryCodesLabels = {
+    /** Names the list of codes. "Recovery codes". */
+    list: string;
+    /** The copy button. "Copy codes". */
+    copy: string;
+    /** Announced once the codes are on the clipboard. "Codes copied". */
+    copied: string;
+    /** Announced when the clipboard refused them. "Copy failed". */
+    copyFailed: string;
+    /** The download button. "Download". */
+    download: string;
+    /** The print button. "Print". */
+    print: string;
+    /** The confirmation's label. "I have saved these codes". */
+    saved: string;
+    /** Under the confirmation once "Done" was pressed before it was ticked. */
+    savedRequired: string;
+    /** The button that calls `onDone`. "Done". */
+    done: string;
+};
+export type RecoveryCodesProps = Omit<ComponentProps<'div'>, 'title'> & {
+    /** The one-time codes, in the order they are shown and saved. */
+    codes: readonly string[];
+    /** The card's heading. "Recovery codes" by default. */
+    title?: ReactNode;
+    /** The heading element; `'h2'` by default. */
+    titleAs?: RecoveryCodesTitleElement;
+    /** A line under the title. */
+    description?: ReactNode;
+    /**
+     * A warning above the codes; a built-in one by default ("Each code works
+     * once…"). `false` hides it. Not printed.
+     */
+    warning?: ReactNode;
+    /**
+     * Moves the focus to the title once shown, as the codes replaced what the
+     * user acted on. Default `true`.
+     */
+    focusTitle?: boolean;
+    /** The downloaded file's name. Default `"recovery-codes.txt"`. */
+    fileName?: string;
+    /**
+     * The file's first line (the account the codes belong to); the title's
+     * text when it is a string, else "Recovery codes".
+     */
+    fileHeading?: string;
+    /** The file's second line; the warning's text when it is a string. */
+    fileNote?: string;
+    /**
+     * Called by the "Done" button, which is shown only when this is given and
+     * calls it only once the confirmation is ticked.
+     */
+    onDone?: () => void;
+    /** The confirmation, controlled; uncontrolled when left out. */
+    saved?: boolean;
+    /** Called when the confirmation is ticked or unticked. */
+    onSavedChange?: (saved: boolean) => void;
+    /** Overrides for the built-in strings. */
+    labels?: Partial<RecoveryCodesLabels>;
+};

package/dist/lib/components/ui/display/recovery-codes/use-recovery-codes-labels.d.ts

@@ -0,0 +1,7 @@
+import { RecoveryCodesLabels } from './types';
+/** The built-in title and warning, and the labels with their overrides. */
+export declare function useRecoveryCodesLabels(overrides?: Partial<RecoveryCodesLabels>): {
+    labels: RecoveryCodesLabels;
+    title: string;
+    warning: string;
+};

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/select-field/select-field.d.ts

@@ -13,8 +13,11 @@ export type SelectFieldProps = {
     options: SelectOption[];
     className?: string;
     renderOption?: (option: SelectOption) => ReactNode;
+    /** Names the trigger by another element's id, when `label` is not shown. */
+    'aria-labelledby'?: string;
 } & ComponentProps<typeof Select>;
-export declare function SelectField({ value, error, helperText, label, options, placeholder, className, renderOption, ...props }: SelectFieldProps): import("react").JSX.Element;
-export declare function SelectFieldTrigger({ value, error, helperText, label, placeholder, required, className, name, }: Pick<SelectFieldProps, 'error' | 'helperText' | 'label' | 'placeholder' | 'value' | 'required' | 'name'> & {
+export declare function SelectField({ value, error, helperText, label, options, placeholder, className, renderOption, 'aria-labelledby': ariaLabelledby, ...props }: SelectFieldProps): import("react").JSX.Element;
+export declare function SelectFieldTrigger({ value, error, helperText, label, placeholder, required, className, name, ariaLabelledby, }: Pick<SelectFieldProps, 'error' | 'helperText' | 'label' | 'placeholder' | 'value' | 'required' | 'name'> & {
     className?: string;
+    ariaLabelledby?: string;
 }): import("react").JSX.Element;

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

@@ -351,7 +351,7 @@ declare const _default: {
 			"go-to-first-page": "Go to first page",
 			"go-to-last-page": "Go to last page",
 			"rows-per-page": "Rows per page",
-			"rows-selected": "{count} of {total} {count, plural, =0 {row selected} one {row selected} other {rows selected} }",
+			"rows-selected": "{count, plural, =0 {No rows selected} one {# row selected} other {# rows selected}} of {total}",
 			"page-of": "Page {page} of {total}",
 			"label": "Pagination",
 			"range": "{from}–{to} of {total}",
@@ -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

@@ -351,7 +351,7 @@ declare const _default: {
 			"go-to-first-page": "Aller à la première page",
 			"go-to-last-page": "Aller à la dernière page",
 			"rows-per-page": "Lignes par page",
-			"rows-selected": "{count} sur {total} {count, plural, =0 {ligne sélectionnée} one {ligne sélectionnée} other {lignes sélectionnées} }",
+			"rows-selected": "{count, plural, =0 {Aucune ligne sélectionnée} one {# ligne sélectionnée} other {# lignes sélectionnées}} sur {total}",
 			"page-of": "Page {page} sur {total}",
 			"label": "Pagination",
 			"range": "{from}–{to} sur {total}",
@@ -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;
+            };
         };
     };
 };