@nxgt/material 3.45.0 → 3.47.0

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

@@ -0,0 +1,44 @@
+import { ComponentProps, ReactNode } from 'react';
+import { VerificationCodeIcons, VerificationCodeLabels, VerificationCodeProps, VerificationKind } from '../../fields/verification-code/types.js';
+import { CardTitleElement } from '../../primitives/card/card.js';
+/** The words of {@link RecoveryCodesStatus} itself, each overridable. */
+export type RecoveryCodesStatusLabels = {
+    /** The title. "Recovery codes". */
+    title: string;
+    /** Under the title: what the codes are for. */
+    description: string;
+    /** How many are left; an ICU message of `{count}`. */
+    remaining: (count: number) => string;
+    /** Said instead of the count when none is left. */
+    noneLeft: string;
+    /** The warning that goes with it. */
+    noneLeftHint: string;
+    /** The button, and the form's submit button. "New codes". */
+    newCodes: string;
+    /** Under the count: what making a new set does. */
+    newCodesHint: string;
+};
+export type RecoveryCodesStatusProps = Omit<ComponentProps<'div'>, 'title' | 'children'> & Pick<VerificationCodeProps, 'attemptsLeft' | 'locked' | 'error' | 'pending' | 'allowRecovery' | 'length'> & {
+    /** How many codes are left; `null` or left out when the count is not known. */
+    remaining?: number | null;
+    /**
+     * Asks for a new set. With `requireCode` it gets the code typed and what
+     * it is (the app's, or a recovery code); without, no argument. Show the
+     * new codes with {@link RecoveryCodes} once it succeeds.
+     */
+    onRegenerate: (code?: string, options?: {
+        kind: VerificationKind;
+    }) => unknown;
+    /**
+     * Ask for a code before making a new set: a {@link VerificationCode}
+     * under the count. `false` draws a plain button. On by default.
+     */
+    requireCode?: boolean;
+    title?: ReactNode;
+    /** The heading level of the title. `'h2'` by default. */
+    titleAs?: CardTitleElement;
+    /** Under the title. Overrides `labels.description`; `false` leaves it out. */
+    description?: ReactNode;
+    labels?: Partial<RecoveryCodesStatusLabels & VerificationCodeLabels>;
+    icons?: VerificationCodeIcons;
+};

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

@@ -0,0 +1,3 @@
+import { RecoveryCodesStatusLabels } from './types.js';
+/** The built-in words (English or the active language), with their overrides. */
+export declare function useRecoveryCodesStatusLabels(overrides?: Partial<RecoveryCodesStatusLabels>): RecoveryCodesStatusLabels;

package/dist/lib/components/ui/display/timeline/index.d.ts

@@ -5,4 +5,4 @@ export type { TimelineProps } from './timeline.js';
 export { Timeline } from './timeline.js';
 export type { TimelineItemProps } from './timeline-item.js';
 export { TimelineItem } from './timeline-item.js';
-export type { TimelineItemData, TimelineTimestamp, TimelineTone, } from './types.js';
+export type { TimelineItemData, TimelineLayout, TimelineTimestamp, TimelineTone, } from './types.js';

package/dist/lib/components/ui/display/timeline/partials/timeline-day-heading.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The heading that opens a day: "Today", "Yesterday", a weekday or a date,
+ * read in `timeZone` when given so a server and a browser label it alike,
+ * and the day's count (read as "3 events"). Its `id` is what the day's items
+ * point to with `aria-describedby`.
+ */
+export declare function TimelineDayHeading({ id, date, count, now, timeZone, level, }: {
+    id: string;
+    date: Date;
+    count: number;
+    now?: Date;
+    timeZone?: string;
+    level: 2 | 3 | 4 | 5 | 6;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/display/timeline/partials/timeline-empty.d.ts

@@ -0,0 +1,8 @@
+import { ReactNode } from 'react';
+/** The loading skeleton, or the empty message, of a Timeline with no items to list. */
+export declare function TimelineEmpty({ loading, label, empty, className, }: {
+    loading: boolean;
+    label: string;
+    empty?: ReactNode;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/display/timeline/partials/timeline-groups.d.ts

@@ -0,0 +1,22 @@
+import { ReactNode } from 'react';
+import { TimelineRow } from '../timeline-rows.js';
+import { TimelineLayout } from '../types.js';
+/**
+ * The rows of the list, flat: the items and, when days show, a day heading
+ * before each run, rendered inside the run's first item, ahead of its content
+ * (a list may only hold `<li>`s, so a presentational row between them would
+ * fail axe's `list` rule). The heading never wraps the items, so an item keeps
+ * its parent and its key when the headings appear after mount, and its state
+ * with them. Every item of the run points to the heading with
+ * `aria-describedby`, which keeps the group named for assistive technology
+ * without a nested list.
+ */
+export declare function TimelineGroups({ rows, baseId, layout, now, timeZone, headingLevel, total, }: {
+    rows: TimelineRow[];
+    baseId: string;
+    layout: TimelineLayout;
+    now?: Date;
+    timeZone?: string;
+    headingLevel: 2 | 3 | 4 | 5 | 6;
+    total: number;
+}): ReactNode[];

package/dist/lib/components/ui/display/timeline/partials/timeline-item-body.d.ts

@@ -0,0 +1,13 @@
+import { ReactNode } from 'react';
+import { TimelineItemData, TimelineTone } from '../types.js';
+/** The title, time, description and children of an item, in its text column. */
+export declare function TimelineItemBody({ item, time, isLast, auto, flip, card, tone, row, }: {
+    item: TimelineItemData;
+    time: ReactNode;
+    isLast: boolean;
+    auto: boolean;
+    flip: boolean;
+    card: boolean;
+    tone: TimelineTone;
+    row: string;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/display/timeline/partials/timeline-item-card.d.ts

@@ -0,0 +1,5 @@
+/** The card behind an item that has `children`: a rounded surface with a tone bar on its start side (its end side when flipped). */
+export declare function TimelineItemCard({ isLast, flip, }: {
+    isLast: boolean;
+    flip: boolean;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/display/timeline/partials/timeline-item-rail.d.ts

@@ -0,0 +1,8 @@
+import { TimelineItemData } from '../types.js';
+/** The marker and the connector below it, in the item's first column. */
+export declare function TimelineItemRail({ item, isLast, auto, row, }: {
+    item: TimelineItemData;
+    isLast: boolean;
+    auto: boolean;
+    row: string;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/display/timeline/partials/timeline-item-time.d.ts

@@ -0,0 +1,12 @@
+import { ReactNode } from 'react';
+/**
+ * The time of an item. In the wide layout it leaves the flow and sits across
+ * the rail from the card, `--timeline-time-gap` (set on the item) beyond the
+ * card's edge, on the logical side that faces the rail, so it mirrors in RTL.
+ */
+export declare function TimelineItemTime({ children, auto, flip, card, }: {
+    children: ReactNode;
+    auto: boolean;
+    flip: boolean;
+    card: boolean;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/display/timeline/partials/timeline-skeleton.d.ts

@@ -0,0 +1,4 @@
+/** The loading rows: a marker, its rail and two lines of text, three times. */
+export declare function TimelineSkeleton({ isLast }: {
+    isLast: boolean;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/display/timeline/timeline-item.d.ts

@@ -1,7 +1,18 @@
-import { TimelineItemData } from './types.js';
+import { ReactNode } from 'react';
+import { TimelineItemData, TimelineLayout } from './types.js';
 export type TimelineItemProps = {
     item: TimelineItemData;
     isLast?: boolean;
+    /** See `Timeline`. Default `auto`. */
+    layout?: TimelineLayout;
+    /** Position in the list: from the wide breakpoint on, odd ones sit on the start side. */
+    index?: number;
+    /** The reference instant for the relative time (as `RelativeTime`). Default: now. */
+    now?: Date;
+    /** The id of the element that names the group this item belongs to (a day heading). */
+    describedBy?: string;
+    /** A day heading rendered first, across the item's whole width. */
+    heading?: ReactNode;
     className?: string;
 };
-export declare function TimelineItem({ item, isLast, className, }: TimelineItemProps): import("react").JSX.Element;
+export declare function TimelineItem({ item, isLast, layout, index, now, describedBy, heading, className, }: TimelineItemProps): import("react").JSX.Element;

package/dist/lib/components/ui/display/timeline/timeline-marker.d.ts

@@ -0,0 +1,12 @@
+import { ReactNode } from 'react';
+import { ShapeTone } from '../shape/shape-tones.js';
+import { TimelineItemData, TimelineTone } from './types.js';
+export declare function toneChannel(tone: TimelineTone): ShapeTone;
+/**
+ * The marker of an item: its tone's shape in the tone's container (never the
+ * solid saturated colour) holding the icon, or a dot; an avatar replaces it.
+ */
+export declare function TimelineMarker({ item, className, }: {
+    item: TimelineItemData;
+    className?: string;
+}): ReactNode;

package/dist/lib/components/ui/display/timeline/timeline-rows.d.ts

@@ -0,0 +1,23 @@
+import { TimelineItemData } from './types.js';
+/** One row of the flat list: a day header, or an item (with the day it sits in). */
+export type TimelineRow = {
+    kind: 'day';
+    group: number;
+    date: Date;
+    count: number;
+} | {
+    kind: 'item';
+    item: TimelineItemData;
+    /** Position in the whole list. */
+    index: number;
+    /** The day header that labels it; unset before any dated item. */
+    group?: number;
+};
+/**
+ * The items in the order given, with a day header before each run of
+ * consecutive items on the same calendar day in `timeZone` (default: the
+ * runtime's). The list is not sorted: a day that comes back later opens a new
+ * run. An item without a valid `timestamp` stays in the run before it; those
+ * before any dated item have no header.
+ */
+export declare function buildRows(items: TimelineItemData[], timeZone?: string, withDays?: boolean): TimelineRow[];

package/dist/lib/components/ui/display/timeline/timeline.d.ts

@@ -1,10 +1,40 @@
 import { ReactNode } from 'react';
-import { TimelineItemData } from './types.js';
+import { TimelineItemData, TimelineLayout } from './types.js';
 export type TimelineProps = {
     items: TimelineItemData[];
     loading?: boolean;
     empty?: ReactNode;
+    /**
+     * Opens each day with a heading ("Today", "Yesterday", the date: a
+     * `DaySeparator`) and its count. Days are runs of the same local day in
+     * `timestamp`, in the order given. The list stays one flat `<ol>` and each
+     * heading sits inside the first item of its day, so an item keeps its parent
+     * and its state when the headings appear; each item
+     * points to its day with `aria-describedby`.
+     */
+    grouped?: boolean;
+    /** The level of the day headings, 2 to 6. Default 3. */
+    headingLevel?: 2 | 3 | 4 | 5 | 6;
+    /**
+     * `auto` (default) alternates the two sides once the Timeline's own
+     * container is 48rem wide, whatever the viewport, and is one rail below;
+     * `rail` never alternates. `auto` measures its own container, so its
+     * parent needs a definite width (a block, a grid cell, `w-96`): in a
+     * shrink-to-fit parent (`w-fit`, an inline flex item) it collapses to 0
+     * wide. Use `rail` there.
+     */
+    layout?: TimelineLayout;
+    /**
+     * The IANA zone (`'America/Toronto'`) the days of `grouped` are cut in.
+     * Default: the runtime's. With `now`, the day headings also render on the
+     * server; without both, there are none on the server and on the first client
+     * render, and they appear once mounted (the items do not remount), so the
+     * two never differ.
+     */
+    timeZone?: string;
+    /** The reference instant for "Today" and "Yesterday" (as `RelativeTime`). Default: now. */
+    now?: Date;
     className?: string;
     'aria-label'?: string;
 };
-export declare function Timeline({ items, loading, empty, className, 'aria-label': ariaLabel, }: TimelineProps): import("react").JSX.Element;
+export declare function Timeline({ items, loading, empty, grouped, headingLevel, layout, timeZone, now, className, 'aria-label': ariaLabel, }: TimelineProps): import("react").JSX.Element;

package/dist/lib/components/ui/display/timeline/types.d.ts

@@ -12,3 +12,9 @@ export type TimelineItemData = {
     tone?: TimelineTone;
     children?: ReactNode;
 };
+/**
+ * `auto` (default): one rail, and two sides alternating once the Timeline's
+ * own container is wide (from 48rem); it needs a parent with a definite
+ * width. `rail`: always one rail.
+ */
+export type TimelineLayout = 'auto' | 'rail';

package/dist/lib/components/ui/feedback/alert/alert.d.ts

@@ -8,5 +8,11 @@ export type AlertProps = {
     icon?: ReactNode;
     title?: ReactNode;
     description?: ReactNode;
+    /**
+     * Buttons or links under the text (a "Continue" link, a "Retry" button),
+     * wrapping on a narrow screen. They are the host's; `Button` and
+     * `LinkButton` already keep a 44px target on a coarse pointer.
+     */
+    actions?: ReactNode;
 } & Omit<ComponentProps<'div'>, 'title' | 'description'> & AlertVariantProps;
-export declare function Alert({ description, icon, title, className, variant, ...props }: AlertProps): import("react").JSX.Element;
+export declare function Alert({ description, actions, icon, title, className, variant, ...props }: AlertProps): import("react").JSX.Element;

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

@@ -18,5 +18,6 @@ export * from './scroll-progress/index.js';
 export * from './skeleton/index.js';
 export * from './spinner/index.js';
 export * from './step-dots/index.js';
+export * from './step-up-dialog/index.js';
 export * from './toast/index.js';
 export * from './typing-indicator/index.js';

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

@@ -0,0 +1,2 @@
+export * from './step-up-dialog.js';
+export type { StepUpDialogLabels, StepUpDialogProps } from './types.js';

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

@@ -0,0 +1,15 @@
+import { 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'> & {
+    formId: string;
+    labels: NonNullable<StepUpDialogProps['labels']>;
+    /** What is said instead of the field (requesting, confirming). */
+    statusText: ReactNode;
+};
+/**
+ * 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 {};

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

@@ -0,0 +1,22 @@
+import { ButtonVariant } from '../../../actions/button/button.js';
+type Props = {
+    /** The id of the code form the Confirm button submits. */
+    formId: string;
+    cancelVariant: ButtonVariant;
+    cancelLabel: string;
+    confirmLabel: string;
+    /** An accepted code is being finished: both buttons are off. */
+    confirming: boolean;
+    pending?: boolean;
+    /** No field to answer (still requesting) or the code is held by a lock. */
+    disabled: boolean;
+    /** The id of the lock note that explains a disabled Confirm. */
+    lockNoteId?: string;
+    onCancel: () => void;
+};
+/**
+ * Cancel and Confirm on one row, even on a phone. Confirm is the form's
+ * submit button (`form={formId}`); a locked code leaves Cancel usable.
+ */
+export declare function StepUpFooter({ formId, cancelVariant, cancelLabel, confirmLabel, confirming, pending, disabled, lockNoteId, onCancel, }: Props): import("react").JSX.Element;
+export {};

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

@@ -0,0 +1,10 @@
+import { ReactNode, RefObject } from 'react';
+type Props = {
+    /** The title takes the focus on open and whenever the field goes. */
+    titleRef: RefObject<HTMLHeadingElement | null>;
+    title: ReactNode;
+    description: ReactNode;
+};
+/** The title (focusable by code, not by Tab) and the line under it. */
+export declare function StepUpHeader({ titleRef, title, description }: Props): import("react").JSX.Element;
+export {};

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

@@ -0,0 +1,16 @@
+import { StepUpDialogProps } from './types.js';
+/**
+ * "Confirm it's you": a dialog that asks for a one-time code before the app
+ * goes on with a sensitive action. It is presentational: it holds no state
+ * machine and fetches nothing, it shows the answer it is given through the
+ * props of {@link VerificationCode} (`via`, `attemptsLeft`, `locked`,
+ * `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
+ * 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.
+ */
+export declare function StepUpDialog({ open, onCancel, cancelVariant, via, destination, requestError, 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

@@ -0,0 +1,55 @@
+import { ReactNode } from 'react';
+import { ButtonVariant } from '../../actions/button/button.js';
+import { VerificationCodeIcons, VerificationCodeLabels, VerificationCodeProps } from '../../fields/verification-code/types.js';
+/** The words of {@link StepUpDialog} itself, each overridable. */
+export type StepUpDialogLabels = {
+    /** The title. "Confirm it's you". */
+    title: string;
+    /** Under the title while the code is still being requested. */
+    description: string;
+    /** Under the title for a code from an authenticator app. */
+    descriptionApp: string;
+    /** Under the title for an e-mailed code, with no destination to name. */
+    descriptionEmail: string;
+    /** Under the title for an e-mailed code; `destination` is the address as text. */
+    descriptionEmailTo: (destination: string) => string;
+    /** Said while the code is being requested. "Sending you a code…". */
+    requesting: string;
+    /** The Cancel button. */
+    cancel: string;
+    /** Said once the code was accepted and the host finishes its action. */
+    confirmed: string;
+};
+export type StepUpDialogProps = Pick<VerificationCodeProps, 'attemptsLeft' | 'locked' | 'error' | 'retryAfter' | 'pending' | 'onSubmit' | 'onResend' | 'resent' | 'length' | 'allowRecovery'> & {
+    open: boolean;
+    /**
+     * Escape, a click outside and Cancel call it, except while `confirming`.
+     * The host closes the dialog (`open`); focus goes back to what opened it.
+     */
+    onCancel: () => void;
+    /** The Cancel button's variant. Default `'tonal'`; `'outlined'` restores the earlier look. */
+    cancelVariant?: ButtonVariant;
+    /**
+     * How the code was issued. Left out, the code is still being requested:
+     * the field is not drawn and a status line says so.
+     */
+    via?: VerificationCodeProps['via'];
+    /** Where an e-mailed code went: the address, or any node. */
+    destination?: ReactNode;
+    /** The request for a code failed; shown as an alert in place of the field. */
+    requestError?: ReactNode;
+    /**
+     * 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
+     * host closes the dialog.
+     */
+    confirming?: boolean;
+    /** The status line while `confirming`. Overrides `labels.confirmed`. */
+    confirmedLabel?: ReactNode;
+    /** The title. Overrides `labels.title`. */
+    title?: ReactNode;
+    /** Under the title. Overrides the text that follows `via`. */
+    description?: ReactNode;
+    labels?: Partial<StepUpDialogLabels & VerificationCodeLabels>;
+    icons?: VerificationCodeIcons;
+};

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

@@ -0,0 +1,3 @@
+import { StepUpDialogLabels } from './types.js';
+/** The built-in words (English or the active language), with their overrides. */
+export declare function useStepUpLabels(overrides?: Partial<StepUpDialogLabels>): StepUpDialogLabels;

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

@@ -0,0 +1,12 @@
+import { StepUpDialogProps } from './types.js';
+type Input = Pick<StepUpDialogProps, 'via' | 'requestError' | 'confirming' | 'locked' | 'attemptsLeft'>;
+/**
+ * Whether the code field is there (a code requested, no failed request,
+ * nothing accepted yet), and whether the code is held by a lock, which turns
+ * Confirm off: the one rule of {@link isHeld}, with the page-wide lock.
+ */
+export declare function useStepUpState({ via, requestError, confirming, locked, attemptsLeft, }: Input): {
+    fieldShown: boolean;
+    held: boolean;
+};
+export {};

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

@@ -0,0 +1,5 @@
+/**
+ * The ref of the dialog's title, which takes the focus when the dialog is
+ * open and the field is not (a code being requested, a code accepted).
+ */
+export declare function useTitleFocus(open: boolean, fieldShown: boolean): import('react').RefObject<HTMLHeadingElement | null>;