@nxgt/material 3.49.0 → 3.51.0

package/dist/lib/components/ui/collections/server-table/partials/server-table-bulk.d.ts

@@ -6,7 +6,8 @@ import { useServerTable } from '../use-server-table.js';
 export declare function ServerTableBulk<T extends RowData>({ props, state, phone, tableRoot, }: {
     props: ServerTableProps<T>;
     state: ReturnType<typeof useServerTable<T>>;
-    phone?: boolean;
+    /** A number: how many buttons stay on a phone's bar (default 3). */
+    phone?: boolean | number;
     /** The stable outer `data-slot="server-table"` element: it outlives the
      * table/cards/tiles view swap that makes `state.table` transiently null. */
     tableRoot: () => HTMLElement | null;

package/dist/lib/components/ui/collections/server-table/partials/server-table-controls.d.ts

@@ -0,0 +1,16 @@
+import { ReactNode } from 'react';
+/**
+ * The band's controls zone when `bulkActions` has the Filter's bar to
+ * replace (#1718): the search landmark and the selection bar share one grid
+ * cell. While rows are selected the landmark stays mounted (its search text
+ * and focus handling intact) but is `invisible` and `inert`, and keeps its
+ * size, so the bar takes its place and nothing moves.
+ */
+export declare function ServerTableControls({ bar, inline, children, }: {
+    /** The selection bar; `null` while nothing is selected. */
+    bar: ReactNode;
+    /** `bandActions: 'inline'`: the zone keeps a phone's row with a lone icon action. */
+    inline: boolean;
+    /** The search landmark. */
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/collections/server-table/partials/server-table-empty-chips.d.ts

@@ -1,8 +1,10 @@
 /**
  * "Nothing matches": the user's filters that narrow the list, as chips
  * removed by their ✕ (a kept field, a widening switch such as "Show archived" or a scope such as the period, is not
- * one, a locked condition stays in the band), then "Clear all" while two
- * or a search remain. A removal focuses the next chip, then "Clear all",
+ * one, a locked condition stays in the band), then "Clear all" (worded by
+ * `empty.clear`) whenever a chip or a search remains. A removal focuses the next chip, then "Clear all",
  * then the search (the core's `focusAfterRemove`, from `empty`).
  */
-export declare function ServerTableEmptyChips(): import("react").JSX.Element | null;
+export declare function ServerTableEmptyChips({ clear }: {
+    clear?: string;
+}): import("react").JSX.Element | null;

package/dist/lib/components/ui/collections/server-table/partials/server-table-grid.d.ts

@@ -6,9 +6,11 @@ import { useServerTable } from '../use-server-table.js';
  * page), and the empty page, which stays while the next answer loads.
  * Both follow the app's `loading` only: a write still unanswered holds
  * back what is told, never the table. */
-export declare function ServerTableGrid<T extends RowData>({ props, state, tableRoot, }: {
+export declare function ServerTableGrid<T extends RowData>({ props, state, tableRoot, hosted, }: {
     props: ServerTableProps<T>;
     state: ReturnType<typeof useServerTable<T>>;
     /** The stable outer table element, for the bulk buttons' focus. */
     tableRoot: () => HTMLElement | null;
+    /** The band's selection bar holds the bulk actions: no toolbar row (#1718). */
+    hosted?: boolean;
 }): import("react").JSX.Element;

package/dist/lib/components/ui/collections/server-table/partials/server-table-selection-bar.d.ts

@@ -0,0 +1,17 @@
+import { RowData } from '@tanstack/react-table';
+import { ReactNode } from 'react';
+import { ServerTableProps } from '../types.js';
+import { useServerTable } from '../use-server-table.js';
+/**
+ * The selection mode of the band: it is mounted only while rows are
+ * selected, over the filter bar (which stays mounted, hidden). The count is
+ * not a live region: the footer's polite status tells it once.
+ */
+export declare function ServerTableSelectionBar<T extends RowData>({ props, state, tableRoot, phone, onCancel, }: {
+    props: ServerTableProps<T>;
+    state: ReturnType<typeof useServerTable<T>>;
+    tableRoot: () => HTMLElement | null;
+    /** Below 768px: the first bulk action keeps its button, the rest go into More. */
+    phone: boolean;
+    onCancel: () => void;
+}): ReactNode;

package/dist/lib/components/ui/collections/server-table/partials/server-table-view.d.ts

@@ -0,0 +1,15 @@
+import { RowData } from '@tanstack/react-table';
+import { RefObject } from 'react';
+import { ServerTableProps } from '../types.js';
+import { TableAnswer } from '../use-table-answer.js';
+export type Scope = {
+    /** The bar's focus root: the whole list, its chips row and the page's
+     * actions (a `FilterSheetTrigger` placed there) included. */
+    rootRef?: RefObject<HTMLElement | null>;
+    focusSearch: () => void;
+};
+export declare function ServerTableView<T extends RowData>({ props, answer, scope, }: {
+    props: ServerTableProps<T>;
+    answer: TableAnswer;
+    scope?: Scope;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/collections/server-table/partials/use-server-table-phone-row.d.ts

@@ -0,0 +1,14 @@
+import { RowData } from '@tanstack/react-table';
+import { ServerTableProps } from '../types.js';
+/** A phone's second header row for a list in cards or tiles (#1719): whether
+ * it is drawn (`inRow`), its two slot elements and the context value that
+ * hands them to the list bar. */
+export declare function useServerTablePhoneRow<T extends RowData>(props: ServerTableProps<T>): {
+    inRow: boolean;
+    slots: {
+        start: HTMLElement;
+        sort: HTMLElement;
+    } | null;
+    setStart: import('react').Dispatch<import('react').SetStateAction<HTMLElement | null>>;
+    setSort: import('react').Dispatch<import('react').SetStateAction<HTMLElement | null>>;
+};

package/dist/lib/components/ui/collections/server-table/partials/use-server-table-selection-slots.d.ts

@@ -0,0 +1,24 @@
+import { RowData } from '@tanstack/react-table';
+import { ReactNode, RefObject } from 'react';
+import { ServerTableProps } from '../types.js';
+import { useServerTable } from '../use-server-table.js';
+/**
+ * Where the selection shows (`bulkActions`, rows selected):
+ * - `bar`: the band's selection bar (#1718), in place of the filter bar and
+ *   the page's actions. It needs the Filter's bar to replace, a single row for
+ *   it (not a phone's second row, not the facets panel); otherwise `hosted`
+ *   is false and the table's toolbar keeps the bulk actions;
+ * - `phoneBulk`: a phone's second row (#1719) holds them instead.
+ */
+export declare function useServerTableSelectionSlots<T extends RowData>({ props, state, tableRoot, listRef, inRow, }: {
+    props: ServerTableProps<T>;
+    state: ReturnType<typeof useServerTable<T>>;
+    tableRoot: () => HTMLElement | null;
+    listRef: RefObject<HTMLElement | null>;
+    /** A phone's second row hosts the list bar. */
+    inRow: boolean;
+}): {
+    hosted: boolean;
+    bar: ReactNode;
+    phoneBulk: ReactNode;
+};

package/dist/lib/components/ui/collections/server-table/types-paging.d.ts

@@ -0,0 +1,17 @@
+import { PagingNames } from '@nxgt/material-core/table-url';
+/** The footer and paging props of `ServerTable`, apart from the page's data. */
+export type ServerTablePagingProps = {
+    /** How the footer's Previous and Next are drawn: `'labelled'` (default) or
+     * `'icon'`, icon-only buttons with a tooltip and a name that says the page
+     * ("Previous page"); a page given as an href stays a link. */
+    pageControls?: 'labelled' | 'icon';
+    /** Hides the footer's range and Previous / Next when the result is a single
+     * page (no previous page, no next page). Default `false`. The count is
+     * still announced by the live region, but no longer shown: show it in the
+     * `description` or keep the footer. A selection's "N rows selected" stays. */
+    hideOnSinglePage?: boolean;
+    /** A page's href. Default ``(params) => `?${params}` ``. */
+    pageHref?: (params: URLSearchParams) => string;
+    /** The cursor's search param names. Default `after` and `trail`. */
+    pagingNames?: Partial<PagingNames>;
+};

package/dist/lib/components/ui/collections/server-table/types.d.ts

@@ -1,7 +1,7 @@
 import { FilterDefaults, FilterFieldErrors, FilterLockedCondition, FilterModel } from '@nxgt/material-core/filter';
 import { IconStyleInput } from '@nxgt/material-core/icons';
 import { ErrorStateKind } from '@nxgt/material-core/states';
-import { PagingNames, TableFilterBinding, TableSorting } from '@nxgt/material-core/table-url';
+import { TableFilterBinding, TableSorting } from '@nxgt/material-core/table-url';
 import { RowData } from '@tanstack/react-table';
 import { ReactNode, Ref } from 'react';
 import { StateHeadingLevel } from '../../feedback/state-frame/state-frame.js';
@@ -9,6 +9,7 @@ import { DataTableProps } from '../data-table/types.js';
 import { FilterBarFieldProps, FilterQueryProps } from '../filter/internal.js';
 import { ListEmptyContent } from '../list-empty/list-empty.js';
 import { ServerTableBulkAction } from './bulk-action.js';
+import { ServerTablePagingProps } from './types-paging.js';
 /** What a bulk action can do to the selection once it acted. */
 export type ServerTableSelection = {
     /** Empties the selection; the table takes the focus the toolbar had. */
@@ -123,7 +124,7 @@ export type ServerTableFilterHandle = {
 };
 /** The `DataTable` props `ServerTable` passes through as they are. */
 export type PassedThrough<T extends RowData> = Pick<DataTableProps<T>, 'columns' | 'maxHeight' | 'scrollLabel' | 'showViewOptions' | 'renderExpandedRow' | 'options' | 'loading' | 'loadingRows' | 'getRowHref' | 'onRowClick' | 'linkComponent' | 'density' | 'layout' | 'cardDensity' | 'renderCard' | 'renderTile' | 'enableRowSelection' | 'rowSelectionDisabledReason'>;
-export type ServerTableProps<T extends RowData> = PassedThrough<T> & {
+export type ServerTableProps<T extends RowData> = PassedThrough<T> & ServerTablePagingProps & {
     /** The URL's search params, as the router reads them. */
     params: URLSearchParams;
     /** The router's setter, called with new search params: React Router's
@@ -172,10 +173,6 @@ export type ServerTableProps<T extends RowData> = PassedThrough<T> & {
      * half the room above and under it (a list under a sticky app bar). The
      * controls keep their size (the Filter's `density` is theirs). */
     bandDensity?: 'comfortable' | 'compact';
-    /** How the footer's Previous and Next are drawn: `'labelled'` (default) or
-     * `'icon'`, icon-only buttons with a tooltip and a name that says the page
-     * ("Previous page"); a page given as an href stays a link. */
-    pageControls?: 'labelled' | 'icon';
     /** With `filter`: a handle to focus the Filter's first control, for the
      * app to move the focus there (after its own action). */
     filterRef?: Ref<ServerTableFilterHandle>;
@@ -191,10 +188,6 @@ export type ServerTableProps<T extends RowData> = PassedThrough<T> & {
      * across pages, and a new query empties the selection. Which rows can be
      * is `enableRowSelection`; why one cannot, `rowSelectionDisabledReason`. */
     bulkActions?: ((ids: string[], selection: ServerTableSelection) => ReactNode) | readonly ServerTableBulkAction<T>[];
-    /** A page's href. Default ``(params) => `?${params}` ``. */
-    pageHref?: (params: URLSearchParams) => string;
-    /** The cursor's search param names. Default `after` and `trail`. */
-    pagingNames?: Partial<PagingNames>;
     /** Without `filter`: what the live region says once a new query is
      * answered. Default "N results" (`material.server-table.results`). */
     resultsLabel?: (count: number) => string;

package/dist/lib/components/ui/collections/server-table/use-selection-band.d.ts

@@ -0,0 +1,14 @@
+import { RefObject } from 'react';
+/** The element that gets the focus back once the selection bar is gone: the
+ * control that started the selection when it is still on the page, else the
+ * list. */
+export declare function focusAfterCancel(starter: HTMLElement | null, list: HTMLElement | null): HTMLElement | null;
+/**
+ * The focus of the selection band (#1718). On the first selection it keeps
+ * the control that had the focus inside the list (the row's box, the
+ * header's); `cancel()` marks that the bar's own Cancel is the cause, and
+ * once the bar has unmounted the focus goes back to that control, or else to
+ * the list. A selection cleared another way (a bulk action's
+ * `selection.clear()`, a new query) keeps its own focus handling.
+ */
+export declare function useSelectionBand(selecting: boolean, root: RefObject<HTMLElement | null>, list: RefObject<HTMLElement | null>): () => void;

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>;
+};