@nxgt/material 3.86.2 → 3.88.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;
 };

package/dist/lib/components/ui/dates/half-day-range-field/half-day-end.d.ts

@@ -0,0 +1,21 @@
+import { DateFieldProps } from '../date-field/date-field.js';
+import { HalfDay } from './half-day-range.js';
+export type HalfDayEndFieldsProps = {
+    side: 'start' | 'end';
+    date?: Date;
+    half: HalfDay;
+    onDateChange: (date?: Date) => void;
+    onHalfChange: (half: HalfDay) => void;
+    disabled?: boolean;
+    required?: boolean;
+    error?: boolean;
+    minDate?: Date;
+    maxDate?: Date;
+    disabledDays?: DateFieldProps['disabledDays'];
+    locale?: DateFieldProps['locale'];
+    name?: string;
+    /** The helper text's id, read with each control. */
+    describedBy?: string;
+};
+/** One end: its day (a `DateField`) and a morning / afternoon choice beside it. */
+export declare function HalfDayEndFields({ side, date, half, onDateChange, onHalfChange, error, name, describedBy, ...rest }: HalfDayEndFieldsProps): import("react").JSX.Element;

package/dist/lib/components/ui/dates/half-day-range-field/half-day-ends.d.ts

@@ -0,0 +1,11 @@
+import { ComponentProps } from 'react';
+import { HalfDayEndFields } from './half-day-end.js';
+import { useHalfDayDraft } from './use-half-day-draft.js';
+type Draft = ReturnType<typeof useHalfDayDraft>;
+type EndProps = ComponentProps<typeof HalfDayEndFields>;
+type Props = Pick<Draft, 'draft' | 'setDate' | 'setHalf'> & Pick<EndProps, 'disabled' | 'required' | 'error' | 'minDate' | 'maxDate' | 'disabledDays' | 'locale' | 'describedBy'> & {
+    name?: string;
+};
+/** The two ends side by side; the end's calendar starts at the start's day. */
+export declare function HalfDayEnds({ draft, setDate, setHalf, name, minDate, ...shared }: Props): import("react").JSX.Element;
+export {};

package/dist/lib/components/ui/dates/half-day-range-field/half-day-range-field.d.ts

@@ -0,0 +1,39 @@
+import { ReactNode } from 'react';
+import { DateFieldProps } from '../date-field/date-field.js';
+import { HalfDayRange } from './half-day-range.js';
+export type HalfDayRangeFieldProps = {
+    /** `{ start: { date, half }, end: { date, half } }`, or `undefined` while a day is missing. */
+    value?: HalfDayRange;
+    /** Uncontrolled: the range the field starts with, kept by the field itself. */
+    defaultValue?: HalfDayRange;
+    /**
+     * Called with the range as soon as both days are set, ordered or not (an
+     * end before the start shows a message under the field; the form wrapper's
+     * rule refuses it in the form), and with `undefined` while a day is missing.
+     */
+    onValueChange?: (value?: HalfDayRange) => void;
+    label?: ReactNode;
+    helperText?: ReactNode;
+    error?: boolean;
+    required?: boolean;
+    disabled?: boolean;
+    className?: string;
+    /** A test hook (`data-pw`); the date inputs have no native `name`. */
+    name?: string;
+    id?: string;
+    /** The first day that can be picked, on both ends. */
+    minDate?: Date;
+    /** The last day that can be picked, on both ends. */
+    maxDate?: Date;
+    /** Days that cannot be picked: the calendar's `disabled` matcher. */
+    disabledDays?: DateFieldProps['disabledDays'];
+    locale?: DateFieldProps['locale'];
+};
+/**
+ * A range whose two ends are each a day plus a half (morning or afternoon),
+ * ordered on the half: the start morning of day D is not after the end
+ * afternoon of day D. Each end is a typed or picked `DateField` with a
+ * morning / afternoon toggle; the end's calendar starts at the start's day.
+ * An end before the start is refused with a message under the field.
+ */
+export declare function HalfDayRangeField({ value, defaultValue, onValueChange, label, helperText, error, required, disabled, className, name, id, minDate, maxDate, ...rest }: HalfDayRangeFieldProps): import("react").JSX.Element;

package/dist/lib/components/ui/dates/half-day-range-field/half-day-range-form-field.d.ts

@@ -0,0 +1,3 @@
+import { UseControllerProps } from 'react-hook-form';
+import { HalfDayRangeFieldProps } from './half-day-range-field.js';
+export declare function HalfDayRangeFormField<T extends Record<string, any>>({ control, name, rules, ...props }: Pick<UseControllerProps<T>, 'control' | 'name' | 'rules'> & Omit<HalfDayRangeFieldProps, 'name' | 'value' | 'defaultValue' | 'onValueChange'>): import("react").JSX.Element;

package/dist/lib/components/ui/dates/half-day-range-field/half-day-range.d.ts

@@ -0,0 +1,25 @@
+/** The half of a day an end falls on. */
+export type HalfDay = 'morning' | 'afternoon';
+/** One end of a half-day range: a calendar day and its half. */
+export type HalfDayEnd = {
+    /** Local midnight of the day. */
+    date: Date;
+    half: HalfDay;
+};
+/** Both ends of a range, each a day plus a half; the range is ordered when valid (`isHalfDayRangeOrdered` checks it). */
+export type HalfDayRange = {
+    start: HalfDayEnd;
+    end: HalfDayEnd;
+};
+/** The two halves, in the order of the day (the toggle's items). */
+export declare const HALF_DAYS: readonly HalfDay[];
+/** Orders two ends on the half: negative when `a` comes first, 0 when they are the same half. */
+export declare function compareHalfDays(a: HalfDayEnd, b: HalfDayEnd): number;
+/**
+ * Whether the end is not before the start, on the half: the morning of day D
+ * is not after the afternoon of day D, and the afternoon of D is after the
+ * morning of D (the same half of the same day is one half-day, allowed).
+ */
+export declare function isHalfDayRangeOrdered(range: HalfDayRange): boolean;
+/** The number of half-days the range covers, both ends included. */
+export declare function halfDaysIn(range: HalfDayRange): number;

package/dist/lib/components/ui/dates/half-day-range-field/index.d.ts

@@ -0,0 +1,3 @@
+export * from './half-day-range.js';
+export * from './half-day-range-field.js';
+export * from './half-day-range-form-field.js';

package/dist/lib/components/ui/dates/half-day-range-field/use-half-day-draft.d.ts

@@ -0,0 +1,30 @@
+import { HalfDay, HalfDayRange } from './half-day-range.js';
+export type Side = 'start' | 'end';
+export type Draft = {
+    startDate?: Date;
+    startHalf: HalfDay;
+    endDate?: Date;
+    endHalf: HalfDay;
+};
+export declare function toDraft(value?: HalfDayRange): Draft;
+/** The range both days make, ordered or not; `undefined` while a day is missing. */
+export declare function toRange(draft: Draft): HalfDayRange | undefined;
+export declare function isUnordered(draft: Draft): boolean;
+/**
+ * The two ends being edited. A half-typed range (a day missing) is the
+ * draft's, not a value: `onValueChange(undefined)`. Both days set, the range
+ * goes out as it is, ordered or not (`unordered` says the end is refused, and
+ * the form wrapper's rule refuses it in the form). The draft follows `value`
+ * when it changes from outside (a reset to `undefined` empties it), and keeps
+ * itself without a `value` (uncontrolled, from `defaultValue`).
+ *
+ * Limit: a reset to `undefined` while the emitted value is already
+ * `undefined` is not news, so a half-typed start or a cleared end stays on
+ * screen. Give the field a `key` that changes on reset to empty it.
+ */
+export declare function useHalfDayDraft(value: HalfDayRange | undefined, defaultValue: HalfDayRange | undefined, onValueChange: ((value?: HalfDayRange) => void) | undefined): {
+    draft: Draft;
+    unordered: boolean;
+    setDate: (side: Side, date?: Date) => void;
+    setHalf: (side: Side, half: HalfDay) => void;
+};

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

@@ -2,6 +2,7 @@ export * from './calendar/index.js';
 export * from './date-field/index.js';
 export * from './date-range-field/index.js';
 export * from './duration-field/index.js';
+export * from './half-day-range-field/index.js';
 export * from './mini-month/index.js';
 export * from './now-indicator/index.js';
 export * from './time-field/index.js';