@nxgt/material 3.49.0 → 3.50.0

package/dist/lib/components/ui/feedback/step-up-dialog/partials/step-up-body.d.ts

@@ -1,15 +1,17 @@
-import { ReactNode } from 'react';
+import { ComponentProps, ReactNode } from 'react';
 import { StepUpDialogProps } from '../types.js';
-type Props = Pick<StepUpDialogProps, 'via' | 'requestError' | 'confirming' | 'attemptsLeft' | 'locked' | 'error' | 'retryAfter' | 'pending' | 'onSubmit' | 'onResend' | 'resent' | 'length' | 'allowRecovery' | 'icons'> & {
+import { StepUpRequestError } from './step-up-request-error.js';
+type Props = Pick<StepUpDialogProps, 'via' | 'requestError' | 'confirming' | 'attemptsLeft' | 'locked' | 'error' | 'retryAfter' | 'pending' | 'onSubmit' | 'onResend' | 'resent' | 'length' | 'allowRecovery' | 'autoFocus' | 'icons'> & {
     formId: string;
     labels: NonNullable<StepUpDialogProps['labels']>;
     /** What is said instead of the field (requesting, confirming). */
     statusText: ReactNode;
+    retry: Omit<ComponentProps<typeof StepUpRequestError>, 'requestError'>;
 };
 /**
  * What sits between the title and the footer: the code form, or, when it is
  * not there (a code still being requested, a request that failed, an
  * accepted code), the status line or the alert that replaces it.
  */
-export declare function StepUpBody({ via, requestError, confirming, formId, labels, statusText, icons, ...code }: Props): import("react").JSX.Element;
+export declare function StepUpBody({ via, requestError, confirming, formId, labels, statusText, icons, retry, ...code }: Props): import("react").JSX.Element;
 export {};

package/dist/lib/components/ui/feedback/step-up-dialog/partials/step-up-request-error.d.ts

@@ -0,0 +1,15 @@
+import { FocusEvent, ReactNode, RefObject } from 'react';
+type Props = {
+    requestError: ReactNode;
+    /** The "Retry" button is drawn only with a handler. */
+    onRetry?: () => void;
+    retryLabel: string;
+    retrying: boolean;
+    /** Retries that finished: a new key tells the live region again, even for the same text. */
+    settled: number;
+    retryRef: RefObject<HTMLButtonElement | null>;
+    onRetryBlur: (event: FocusEvent) => void;
+};
+/** The alert that replaces the field when the code could not be requested, with "Retry" when the host offers it. */
+export declare function StepUpRequestError({ requestError, onRetry, retryLabel, retrying, settled, retryRef, onRetryBlur, }: Props): import("react").JSX.Element;
+export {};

package/dist/lib/components/ui/feedback/step-up-dialog/step-up-dialog.d.ts

@@ -7,10 +7,13 @@ import { StepUpDialogProps } from './types.js';
  * `error`, `pending`, `resent`, `onSubmit`, `onResend`), which the app
  * wires to its own model.
  *
- * The title takes the focus on open and whenever the field goes (a code
+ * The title takes the focus on open (unless `autoFocus` sends it to the
+ * field) and whenever the field goes (a code
  * being requested, a code accepted); the field takes it after a refusal; on
  * close it goes back to what opened the dialog. Escape, a click outside and
  * Cancel call `onCancel`, except while `confirming`. A locked code leaves
- * Cancel usable.
+ * Cancel usable. A failed code request (`requestError`) offers "Retry" when
+ * `onRetry` is set: the focus stays on it while it runs and goes to the
+ * field once the request succeeds.
  */
-export declare function StepUpDialog({ open, onCancel, cancelVariant, via, destination, requestError, confirming, confirmedLabel, title, description, labels: labelOverrides, icons, ...code }: StepUpDialogProps): import("react").JSX.Element;
+export declare function StepUpDialog({ open, onCancel, cancelVariant, via, destination, requestError, onRetry, confirming, confirmedLabel, title, description, labels: labelOverrides, icons, ...code }: StepUpDialogProps): import("react").JSX.Element;

package/dist/lib/components/ui/feedback/step-up-dialog/types.d.ts

@@ -19,8 +19,10 @@ export type StepUpDialogLabels = {
     cancel: string;
     /** Said once the code was accepted and the host finishes its action. */
     confirmed: string;
+    /** The "Retry" button of a failed code request (see `onRetry`). */
+    retry: string;
 };
-export type StepUpDialogProps = Pick<VerificationCodeProps, 'attemptsLeft' | 'locked' | 'error' | 'retryAfter' | 'pending' | 'onSubmit' | 'onResend' | 'resent' | 'length' | 'allowRecovery'> & {
+export type StepUpDialogProps = Pick<VerificationCodeProps, 'attemptsLeft' | 'locked' | 'error' | 'retryAfter' | 'pending' | 'onSubmit' | 'onResend' | 'resent' | 'length' | 'allowRecovery' | 'autoFocus'> & {
     open: boolean;
     /**
      * Escape, a click outside and Cancel call it, except while `confirming`.
@@ -38,6 +40,15 @@ export type StepUpDialogProps = Pick<VerificationCodeProps, 'attemptsLeft' | 'lo
     destination?: ReactNode;
     /** The request for a code failed; shown as an alert in place of the field. */
     requestError?: ReactNode;
+    /**
+     * Draws a "Retry" button in the `requestError` alert. Pressing it calls
+     * this; while the returned promise is pending the button is busy and keeps
+     * the focus. Answer by clearing `requestError` and setting `via` (the code
+     * field takes the focus) or by setting a new `requestError` (the focus
+     * stays on "Retry" and the new text is announced). Left out, the alert
+     * has no button.
+     */
+    onRetry?: () => unknown;
     /**
      * The code was accepted and the host re-runs its action: the field goes,
      * a status line shows `labels.confirmed` and Cancel is disabled until the

package/dist/lib/components/ui/feedback/step-up-dialog/use-retry-focus.d.ts

@@ -0,0 +1,27 @@
+import { RefObject } from 'react';
+type Input = {
+    open: boolean;
+    fieldShown: boolean;
+    requestError: unknown;
+    confirming: boolean;
+    formId: string;
+    titleRef: RefObject<HTMLElement | null>;
+};
+/**
+ * Where the focus goes around a "Retry": it stays on the button while the
+ * retry runs and when the request fails again (the button may be taken away
+ * and put back by the host meanwhile, the title holding the focus in the
+ * gap), and goes to the code field once the request succeeds. Only after a
+ * press of "Retry", and only while the focus is still free (the page, the
+ * dialog itself, the title or the button): a focus the user moved elsewhere is left alone.
+ */
+export declare function useRetryFocus({ open, fieldShown, requestError, confirming, formId, titleRef, }: Input): {
+    retryRef: RefObject<HTMLButtonElement | null>;
+    /** On "Retry": the focus it holds is followed from here on. */
+    arm: () => void;
+    /** On the button's blur: a focus that went to another control is not ours any more. */
+    release: (event: {
+        relatedTarget: EventTarget | null;
+    }) => void;
+};
+export {};

package/dist/lib/components/ui/feedback/step-up-dialog/use-retry.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The retry of a failed code request: `run` calls the host's `onRetry` and
+ * stays `retrying` until what it returned settles (a thrown or rejected
+ * retry is the host's to show as a new `requestError`). `settled` counts the
+ * retries that finished, so the alert is told again, even for the same text.
+ */
+export declare function useRetry(onRetry: (() => unknown) | undefined): {
+    retrying: boolean;
+    settled: number;
+    run: () => Promise<void>;
+};