@nxgt/material 3.86.2 → 3.87.0

package/dist/lib/components/ui/collections/marking-list/types.d.ts

@@ -0,0 +1,74 @@
+import { ComponentProps, ReactNode } from 'react';
+import { Tone } from '../../tones.js';
+/** One choice of the segmented control every row shares: "Present", "Absent". */
+export type MarkingChoice = {
+    /** Stable id, the value a row holds and the callbacks hand back. */
+    id: string;
+    /** The visible label. */
+    label: ReactNode;
+    /**
+     * The label as plain text, for the tally and the accessible names when
+     * `label` is not a string. Defaults to `label` when that is a string.
+     */
+    text?: string;
+    /** Colours the chosen segment and its tally figure (`data-tone`). */
+    tone?: Tone;
+    /** A leading icon; decorative, the label names the choice. */
+    icon?: ReactNode;
+};
+/** One person of the list. */
+export type MarkingRow = {
+    /** Stable id, the key of `value` and of the callbacks. */
+    id: string;
+    /** The person's name. It names the row's choice group. */
+    name: string;
+    /** A line under the name: a class, a number, a status. */
+    description?: ReactNode;
+    /** Before the name: an `Avatar`. */
+    leading?: ReactNode;
+    /**
+     * Locks the row: its choice is read-only (the segments stay focusable, with
+     * `aria-disabled`, and each one is described by this reason) and the reason is
+     * shown under the name ("Excused by the office"). A value it holds still counts
+     * in the tally; a locked row with none counts as `locked`, not `unmarked`.
+     */
+    locked?: ReactNode;
+};
+/** The choice of each row, by row id; a missing id or `null` is unmarked. */
+export type MarkingValue = Record<string, string | null | undefined>;
+export type MarkingListProps = Omit<ComponentProps<'div'>, 'children' | 'onChange'> & {
+    /** The choice set, shared by every row, in display order. */
+    choices: readonly MarkingChoice[];
+    /** The people, in display order. */
+    rows: readonly MarkingRow[];
+    /** The choice of each row (controlled). */
+    value: MarkingValue;
+    /** A segment was pressed; `null` when the chosen segment is pressed again. */
+    onValueChange: (rowId: string, choiceId: string | null) => void;
+    /**
+     * Shows the "Set remaining to" buttons. Pressing one hands the choice and the
+     * ids of the unmarked, unlocked rows; apply it in one update.
+     */
+    onSetRemaining?: (choiceId: string, rowIds: string[]) => void;
+    /** Names the list ("Roll call, class 6A"). Required for assistive technology. */
+    label: string;
+    /** Shows the live tally above the rows. Default `true`. */
+    tally?: boolean;
+    /**
+     * The detail of a row, shown on demand: with it every row gets an expand
+     * button, reached with Right past the last segment. Called only while the row
+     * is expanded. Keep it stable (`useCallback`) so closed rows do not re-render.
+     */
+    renderDetail?: (row: MarkingRow) => ReactNode;
+    /** Ids of the rows whose detail is open at first (uncontrolled). */
+    defaultExpanded?: readonly string[];
+    /** The ids of the open rows (controlled); pair it with `onExpandedChange`. */
+    expanded?: readonly string[];
+    /** The open rows changed. */
+    onExpandedChange?: (ids: string[]) => void;
+    /**
+     * The choices "Set remaining to" offers, by id. Default: all of them. Offer
+     * "Present" alone when the others are not a sensible default.
+     */
+    setRemainingChoices?: readonly string[];
+};

package/dist/lib/components/ui/collections/marking-list/use-marking-expanded.d.ts

@@ -0,0 +1,9 @@
+/** Which rows are open: controlled by `expanded`, else its own state from `initial`. */
+export declare function useMarkingExpanded({ expanded, initial, onChange, }: {
+    expanded?: readonly string[];
+    initial?: readonly string[];
+    onChange?: (ids: string[]) => void;
+}): {
+    ids: readonly string[];
+    toggle: (rowId: string) => void;
+};

package/dist/lib/components/ui/collections/marking-list/use-marking-focus.d.ts

@@ -0,0 +1,22 @@
+import { KeyboardEvent } from 'react';
+/**
+ * Roving focus over every row's cells: the segments, then the expand button
+ * when the list has details. One tab stop for the whole list. Left and Right
+ * move across a row (Right past the last segment reaches the expand button),
+ * Up and Down to the same cell of the previous or next row, stopping at the
+ * first and the last. Home and End go to a row's first and last segment.
+ * Locked rows stay on the path: their segments are focusable. Space and Enter
+ * press the cell (a button), so moving never marks anyone.
+ *
+ * `cols` is the number of cells in a row, `segments` how many of them are
+ * choices. A stop whose column no longer exists (the choices shrank) falls
+ * back to the last one, so the list keeps exactly one tab stop.
+ */
+export declare function useMarkingFocus(rows: readonly {
+    id: string;
+}[], cols: number, segments: number, chosenCol: (rowId: string) => number): {
+    /** The tab stop's column in a row, `-1` for every other row. */
+    tabbableCol: (rowId: string) => number;
+    onFocusCell: (row: string, col: number) => void;
+    onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+};

package/dist/lib/components/ui/collections/marking-list/use-marking-handlers.d.ts

@@ -0,0 +1,11 @@
+import { MarkingBulk } from './use-tally-speech.js';
+/**
+ * The list's callbacks as stable functions, so a parent's new closure does not
+ * re-render closed rows, and the record of the last "Set remaining to" the
+ * tally says once.
+ */
+export declare function useMarkingHandlers(onValueChange: (rowId: string, choiceId: string | null) => void, onSetRemaining?: (choiceId: string, rowIds: string[]) => void): {
+    onPress: (rowId: string, choiceId: string | null) => void;
+    setRemaining: ((choiceId: string, rowIds: string[]) => void) | undefined;
+    bulk: import('react').RefObject<MarkingBulk | null>;
+};

package/dist/lib/components/ui/collections/marking-list/use-tally-speech.d.ts

@@ -0,0 +1,16 @@
+import { RefObject } from 'react';
+import { MarkingTally } from './marking-list.utils.js';
+import { MarkingChoice } from './types.js';
+/** A "Set remaining to" the list just applied, recorded for the tally to say. */
+export type MarkingBulk = {
+    choiceId: string;
+    count: number;
+};
+/**
+ * What the tally says aloud, apart from what it shows. A "Set remaining to"
+ * is said at once ("33 marked Present"); only that, so loading a saved
+ * register stays silent. Single taps are summed up once the marking pauses
+ * ("Unmarked: 3"), compared with the last count spoken, so a change in
+ * another row within the pause does not lose it.
+ */
+export declare function useTallySpeech(choices: readonly MarkingChoice[], tally: MarkingTally, bulk: RefObject<MarkingBulk | null>): string | null;

package/dist/lib/components/ui/collections/page-footer/page-footer.d.ts

@@ -20,6 +20,10 @@ export type PageFooterProps = {
     pageHref?: (params: URLSearchParams) => string;
     /** The cursor's search param names. Default `after` and `trail`. */
     pagingNames?: Partial<PagingNames>;
+    /** How many earlier pages' cursors the URL keeps. Past it the oldest are
+     * dropped into a counted cut mark (`trail=~3,c4,c5`): the range stays exact,
+     * and « Previous » from the cut goes to the first page. Default `20`. */
+    maxTrail?: number;
     /** `'icon'`: icon-only Previous / Next with a tooltip, named "Previous
      * page" / "Next page". Default `'labelled'`. */
     pageControls?: 'labelled' | 'icon';
@@ -42,4 +46,4 @@ export type PageFooterProps = {
  * `ServerTable` draws. Renders nothing for an empty result. Without a
  * `totalCount` (a cursor feed with no total) it is the Previous / Next alone.
  */
-export declare function PageFooter({ pageInfo, totalCount, params, pageSize, count, pageHref, pagingNames, pageControls, live, disabled, hideOnSinglePage, linkComponent, className, ...props }: PageFooterProps): import("react").JSX.Element | null;
+export declare function PageFooter({ pageInfo, totalCount, params, pageSize, count, pageHref, pagingNames, maxTrail, pageControls, live, disabled, hideOnSinglePage, linkComponent, className, ...props }: PageFooterProps): import("react").JSX.Element | null;

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

@@ -1,3 +1,3 @@
 export { defineFilterModel, effectiveConditions, type FilterCodecOptions, type FilterCondition, type FilterFieldError, type FilterFieldErrors, type FilterLockedCondition, type FilterModel, type FilterQuery, type FilterSplitErrors, parseFilterQuery, serializeFilterQuery, splitFilterErrors, } from '@nxgt/material-core/filter';
-export { type CursorConnection, createSorting, FIRST_PAGE, firstPage, isFiltered, isNewQuery, nextPage, type PageCursor, type PagingNames, pagingNames, paramsFromQuery, previousPage, queryFromParams, queryKey, type RouterQuery, readCursor, type ServerPagination, type ServerPaginationOptions, type SortingOptions, serverPagination, type TableFilterBinding, type TableFilterOptions, type TableSort, type TableSorting, tableFilters, withoutFilters, } from '@nxgt/material-core/table-url';
+export { CUT_MARK, type CursorConnection, createSorting, FIRST_PAGE, firstPage, isFiltered, isNewQuery, nextPage, type PageCursor, type PagingNames, type PagingOptions, pageIndex, pageOffset, pagingNames, paramsFromQuery, previousPage, queryFromParams, queryKey, type RouterQuery, readCursor, type ServerPagination, type ServerPaginationOptions, type SortingOptions, serverPagination, type TableFilterBinding, type TableFilterOptions, type TableSort, type TableSorting, tableFilters, withoutFilters, } from '@nxgt/material-core/table-url';
 export * from './server-table.js';

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

@@ -0,0 +1,8 @@
+import { RowData } from '@tanstack/react-table';
+import { ServerTableProps } from './types.js';
+/** The footer's place (offset, Previous, Next, the trail capped by `maxTrail`)
+ * and the first page's href, the way back from an empty page. */
+export declare function serverTablePaging<T extends RowData>(props: ServerTableProps<T>, params: URLSearchParams, heading: URLSearchParams | string): {
+    place: import('@nxgt/material-core/table-url').ServerPagination;
+    firstPageHref: string;
+};

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

@@ -1,4 +1,6 @@
 import { PagingNames } from '@nxgt/material-core/table-url';
+/** The cursors `ServerTable` and `PageFooter` keep in the URL by default. */
+export declare const DEFAULT_MAX_TRAIL = 20;
 /** The footer and paging props of `ServerTable`, apart from the page's data. */
 export type ServerTablePagingProps = {
     /** `'paging'` (default): Previous / Next over the URL's cursor. `'load-more'`: `LoadMoreFooter` ("Showing N of M" from `rows.length` and `totalCount`, the load button while `pageInfo.hasNextPage`, a failed alert with a retry) in place of them, for a list that grows: the page keeps the loaded rows in `rows` and fetches the next itself (`onLoadMore`), so the cursor params are not used. */
@@ -24,4 +26,8 @@ export type ServerTablePagingProps = {
     pageHref?: (params: URLSearchParams) => string;
     /** The cursor's search param names. Default `after` and `trail`. */
     pagingNames?: Partial<PagingNames>;
+    /** How many earlier pages' cursors the URL keeps. Past it the oldest are
+     * dropped into a counted cut mark (`trail=~3,c4,c5`): the range stays exact,
+     * and « Previous » from the cut goes to the first page. Default `20`. */
+    maxTrail?: number;
 };