@nxgt/material 3.54.0 → 3.56.0

package/dist/lib/components/ui/display/seat-ring/partials/seat-item.d.ts

@@ -0,0 +1,17 @@
+import { KeyboardEvent } from 'react';
+import { Seat, SeatRingProps } from '../types.js';
+type Props = Pick<SeatRingProps, 'renderAvatar' | 'renderStatus' | 'renderBadge' | 'renderEmptySeat'> & {
+    seat: Seat;
+    index: number;
+    mode: 'single' | 'multiple' | null;
+    selected: boolean;
+    tabStop: boolean;
+    highlighted: boolean;
+    register: (node: HTMLElement | null) => void;
+    onPick: () => void;
+    onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+    onFocus: () => void;
+};
+/** One seat: an `option` of a listbox when selectable, a `listitem` otherwise. */
+export declare function SeatItem({ seat, index, mode, selected, tabStop, highlighted, register, onPick, onKeyDown, onFocus, ...slots }: Props): import("react").JSX.Element;
+export {};

package/dist/lib/components/ui/display/seat-ring/seat-ring.d.ts

@@ -0,0 +1,9 @@
+import { SeatRingProps } from './types.js';
+/**
+ * Participants as seats: around a circle when there is room, a grid on a
+ * phone. A list of seats (`role="list"`), or with `selectionMode` a listbox
+ * (`aria-selected`, roving focus: arrows, Home and End move, Space or Enter
+ * picks). Layout switches by the component's own width (a container query),
+ * so it also follows a narrow column or a dialog.
+ */
+export declare function SeatRing(props: SeatRingProps): import("react").JSX.Element;

package/dist/lib/components/ui/display/seat-ring/seat-ring.utils.d.ts

@@ -0,0 +1,9 @@
+import { Seat, SeatRingSize } from './types.js';
+/**
+ * The most seats drawn on a circle: what fits, without two seats
+ * touching, in the narrowest box the circle is drawn in (32, 38 and 46rem
+ * by size); more is a grid.
+ */
+export declare const RING_LIMIT: Record<SeatRingSize, number>;
+/** Whether a seat can be chosen. */
+export declare function pickable(seat: Seat): boolean;

package/dist/lib/components/ui/display/seat-ring/types.d.ts

@@ -0,0 +1,67 @@
+import { ComponentProps, ReactNode } from 'react';
+import { StatusTone } from '../status-indicator/status-indicator.js';
+/** A seat's state in words (never colour alone): its label is always shown and read out. */
+export type SeatStatus = {
+    /** "Ready", "Away", "Eliminated"…: shown under the name and part of the seat's name. */
+    label: string;
+    /** The dot's tone (neutral without one). */
+    tone?: StatusTone;
+};
+export type Seat = {
+    id: string;
+    /** The seat's name: shown, and the seat's accessible name with its status. */
+    label: string;
+    /** A photo (`src`) or the fallback; without either, the label's initials. */
+    avatar?: {
+        src?: string;
+        fallback?: ReactNode;
+    };
+    status?: SeatStatus;
+    /** A small mark at the seat's corner: a host crown, a role icon, a count. */
+    badge?: ReactNode;
+    /** Cannot be picked: `aria-disabled`, still reachable by keyboard. */
+    disabled?: boolean;
+    /** Nobody sits here: a dashed placeholder, never selectable. */
+    empty?: boolean;
+};
+export type SeatRingSize = 'sm' | 'md' | 'lg';
+/** What the ring draws for a seat, besides the default look. */
+export type SeatRingSlots = {
+    renderAvatar?: (seat: Seat) => ReactNode;
+    renderStatus?: (seat: Seat) => ReactNode;
+    renderBadge?: (seat: Seat) => ReactNode;
+    /** The content of an empty seat (default: a dashed circle and "Empty seat"). */
+    renderEmptySeat?: (seat: Seat) => ReactNode;
+    /** The middle of the ring (a timer, a title); above the seats in the grid. */
+    centerSlot?: ReactNode;
+};
+export type SeatRingSelection = {
+    selectionMode?: 'none';
+    value?: never;
+    defaultValue?: never;
+    onValueChange?: never;
+} | {
+    selectionMode: 'single';
+    value?: string | null;
+    defaultValue?: string | null;
+    onValueChange?: (value: string | null) => void;
+} | {
+    selectionMode: 'multiple';
+    value?: string[];
+    defaultValue?: string[];
+    onValueChange?: (value: string[]) => void;
+};
+export type SeatRingProps = Omit<ComponentProps<'div'>, 'children' | 'role' | 'value' | 'defaultValue' | 'onChange'> & SeatRingSlots & SeatRingSelection & {
+    seats: Seat[];
+    /**
+     * `ring` (default): seats around a circle when the box is at least
+     * 32 to 46rem wide (by `size`), a grid below it and above the ring's
+     * seat limit; `grid`: always the grid.
+     */
+    layout?: 'ring' | 'grid';
+    size?: SeatRingSize;
+    /** The seat to emphasise (whose turn it is): `aria-current` in a list. */
+    highlightedId?: string;
+    /** Names the list or the listbox; give it (or `aria-labelledby`). */
+    'aria-label'?: string;
+};

package/dist/lib/components/ui/display/seat-ring/use-seat-ring.d.ts

@@ -0,0 +1,12 @@
+import { KeyboardEvent } from 'react';
+import { Seat, SeatRingProps } from './types.js';
+/** The selection, the roving tab stop and the keys of a selectable ring. */
+export declare function useSeatRing(props: SeatRingProps): {
+    mode: "multiple" | "single" | null;
+    value: string[];
+    stop: string | undefined;
+    pick: (seat: Seat) => void;
+    onKeyDown: (event: KeyboardEvent<HTMLElement>, seat: Seat) => void;
+    register: (id: string) => (node: HTMLElement | null) => void;
+    setFocused: import('react').Dispatch<import('react').SetStateAction<string | undefined>>;
+};

package/dist/lib/components/ui/display/secret-card/index.d.ts

@@ -0,0 +1,2 @@
+export * from './secret-card.js';
+export type { SecretCardLabels, SecretCardProps, SecretCardState, } from './types.js';

package/dist/lib/components/ui/display/secret-card/secret-card.d.ts

@@ -0,0 +1,11 @@
+import { SecretCardProps } from './types.js';
+/**
+ * A card whose secret face is hidden until a deliberate tap or click: a
+ * private role, a one-time code, a recovery key. The secret (`back`) is not
+ * rendered while hidden, so it is not in the markup, not read by a screen
+ * reader and not copied. The reveal is a real button with one name and
+ * `aria-expanded` for the state; changes a click does not explain
+ * (`autoHideMs`, the parent) are announced politely. The flip runs only after
+ * a change and without `prefers-reduced-motion`.
+ */
+export declare function SecretCard(props: SecretCardProps): import("react").JSX.Element;

package/dist/lib/components/ui/display/secret-card/types.d.ts

@@ -0,0 +1,49 @@
+import { ComponentProps, ReactNode } from 'react';
+import { Tone } from '../../tones.js';
+/** The words the card says: its button and what a screen reader hears after a change. */
+export type SecretCardLabels = {
+    /** The button's name, the same hidden or shown: `aria-expanded` carries the state (default "Show secret"). */
+    reveal: string;
+    /** Announced politely when the secret is shown by something other than a click on the button (default "Secret revealed"). */
+    revealed: string;
+    /** Announced politely when it is hidden by something other than a click on the button, an auto-hide or the parent (default "Secret hidden"). */
+    hidden: string;
+};
+export type SecretCardState = 'hidden' | 'revealed';
+/** Controlled (`revealed` and `onRevealedChange`) or not (`defaultRevealed`), never both. */
+export type SecretCardReveal = {
+    revealed: boolean;
+    onRevealedChange: (revealed: boolean) => void;
+    defaultRevealed?: never;
+} | {
+    revealed?: never;
+    defaultRevealed?: boolean;
+    onRevealedChange?: (revealed: boolean) => void;
+};
+export type SecretCardProps = Omit<ComponentProps<'div'>, 'children' | 'title' | 'defaultValue'> & SecretCardReveal & {
+    /** The card's name, always shown: "Your role", "Recovery key". */
+    title: ReactNode;
+    /** A hint shown only while the secret is hidden ("Tap to see it, then hide it"). */
+    description?: ReactNode;
+    /** A decorative icon or illustration before the title. */
+    icon?: ReactNode;
+    /** A named tone or one the app declared (`data-tone`). */
+    tone?: Tone;
+    /**
+     * The hidden face, under the title: anything that is no secret.
+     * Default: a neutral pattern.
+     */
+    front?: ReactNode;
+    /**
+     * The secret. It is not rendered, so it is not in the markup, read out
+     * or copied, until the card is revealed.
+     */
+    back: ReactNode;
+    /** Buttons beside the reveal button (a copy button, "Next player"). */
+    actions?: ReactNode;
+    /** Hides the secret again after this many milliseconds shown. */
+    autoHideMs?: number;
+    /** The card cannot be revealed. A revealed card can always be hidden. */
+    disabled?: boolean;
+    labels?: Partial<SecretCardLabels>;
+};

package/dist/lib/components/ui/display/secret-card/use-secret-card.d.ts

@@ -0,0 +1,20 @@
+import { SecretCardLabels, SecretCardProps } from './types.js';
+/**
+ * The reveal state (controlled or not), the optional auto-hide, the focus
+ * kept on the button when the face under it is swapped, and a polite message
+ * for the changes a click on the button does not explain (auto-hide, the
+ * parent): a click is already said by `aria-expanded`.
+ */
+export declare function useSecretCard(props: SecretCardProps): {
+    shown: boolean;
+    faceId: string;
+    message: string | null;
+    changed: boolean;
+    labels: SecretCardLabels;
+    button: import('react').RefObject<HTMLButtonElement | null>;
+    toggle: () => void;
+    faceProps: {
+        onFocus: () => void;
+        onBlur: () => void;
+    };
+};

package/dist/lib/components/ui/display/vote-tally/announcer.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The debounce behind the live status, apart from React so it can be tested
+ * with fake timers. `follow(text, delay)` is called each time the text or the
+ * delay changes: a text equal to the last one said (or the first one) cancels
+ * what is pending, any other waits `delay` ms from now, and `say` gets it only
+ * if nothing newer arrived meanwhile.
+ */
+export declare function createAnnouncer(initial: string, say: (text: string) => void): {
+    follow(text: string, delay: number): void;
+    cancel: () => void;
+};

package/dist/lib/components/ui/display/vote-tally/index.d.ts

@@ -0,0 +1,2 @@
+export type { VoteOption, VoteRow, Voter, VoteTallyProps, VoteTallySlots, VoteTallySort, VoteTallyVoters, } from './types.js';
+export * from './vote-tally.js';

package/dist/lib/components/ui/display/vote-tally/partials/tally-bar.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The bar: decorative (the row's text carries the number). An SVG so the
+ * width is an attribute, never a `style` (strict CSP); its width transition
+ * is in the stylesheet, and only without reduced motion.
+ */
+export declare function TallyBar({ percent }: {
+    percent: number;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/display/vote-tally/partials/tally-row.d.ts

@@ -0,0 +1,9 @@
+import { VoteRow, VoteTallyProps } from '../types.js';
+type Props = Pick<VoteTallyProps, 'renderOption' | 'renderVoters' | 'showLeader'> & {
+    row: VoteRow;
+    voters: NonNullable<VoteTallyProps['showVoters']>;
+    maxVoters: number;
+};
+/** One option: label and marks, "n votes, x%" as text, a decorative bar, voters. */
+export declare function TallyRow({ row, voters, maxVoters, showLeader, renderOption, renderVoters, }: Props): import("react").JSX.Element;
+export {};

package/dist/lib/components/ui/display/vote-tally/partials/tally-voters.d.ts

@@ -0,0 +1,9 @@
+import { VoteRow, VoteTallyVoters } from '../types.js';
+type Props = {
+    row: VoteRow;
+    mode: VoteTallyVoters;
+    max: number;
+};
+/** Who voted for an option: an avatar group or a line of names, both named. */
+export declare function TallyVoters({ row, mode, max }: Props): import("react").JSX.Element | null;
+export {};

package/dist/lib/components/ui/display/vote-tally/types.d.ts

@@ -0,0 +1,73 @@
+import { ComponentProps, ReactNode } from 'react';
+/** Someone who voted: shown as an avatar (or a name) and read out by name. */
+export type Voter = {
+    id: string;
+    /** The voter's name: the avatar's accessible name and the text in `names` mode. */
+    label: string;
+    /** A photo (`src`) or the fallback; without either, the label's initials. */
+    avatar?: {
+        src?: string;
+        fallback?: ReactNode;
+    };
+};
+export type VoteOption = {
+    id: string;
+    /** The option's name: a candidate, an answer, a player. */
+    label: string;
+    /** Votes it received (a whole number, 0 or more). */
+    count: number;
+    /** Who voted for it, when the vote is public. */
+    voters?: Voter[];
+    /** A photo or fallback shown beside the label. */
+    avatar?: {
+        src?: string;
+        fallback?: ReactNode;
+    };
+};
+/** How a row's rank and share are known to the slots. */
+export type VoteRow = {
+    option: VoteOption;
+    /** 1-based place; options with the same count share it. */
+    rank: number;
+    /** Share of the total, 0 to 100, whole number. */
+    percent: number;
+    /** Has the top count, alone. */
+    leader: boolean;
+    /** Shares the top count with another option. */
+    tied: boolean;
+    /** The viewer's own vote. */
+    selected: boolean;
+};
+export type VoteTallySort = 'count' | 'none';
+export type VoteTallyVoters = 'none' | 'avatars' | 'names';
+export type VoteTallySlots = {
+    /** Replaces an option's label cell (avatar, name and marks). */
+    renderOption?: (row: VoteRow) => ReactNode;
+    /** Replaces the voters under a bar. */
+    renderVoters?: (row: VoteRow) => ReactNode;
+    header?: ReactNode;
+    footer?: ReactNode;
+};
+export type VoteTallyProps = {
+    options: VoteOption[];
+    /** The base of the shares; the sum of the counts when omitted. Abstentions are not in it. */
+    total?: number;
+    /** `count` ranks by votes, highest first (ties keep their order); `none` keeps the given order. */
+    sort?: VoteTallySort;
+    /** The viewer's own choice, marked "Your vote" in words. */
+    selectedId?: string;
+    /** Marks the leader, or the tied options, in words ("Leader", "Tie"), and says them in the live status. Off: no mark, the status gives the votes cast. On by default. */
+    showLeader?: boolean;
+    /** `avatars` shows who voted as an avatar group, `names` as text. */
+    showVoters?: VoteTallyVoters;
+    /** How many voters show before "+N". 5 by default. */
+    maxVoters?: number;
+    /** The bar's width eases when a count changes (only the width); never under reduced motion. On by default. */
+    animated?: boolean;
+    /** People who voted for nobody: counted and shown beneath the bars. */
+    abstainCount?: number;
+    /** Shown while there is no vote. */
+    emptyLabel?: ReactNode;
+    /** Milliseconds a change waits before it is announced. 1000 by default. */
+    announceDelay?: number;
+} & VoteTallySlots & Omit<ComponentProps<'div'>, 'children'>;

package/dist/lib/components/ui/display/vote-tally/use-announcement.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The text a polite live region should say, once `text` has stopped changing
+ * for `delay` ms. The first text is never said (it is the page as loaded,
+ * not news), a return to what was last said is not said again, and a burst of
+ * live updates becomes one announcement. `null` while there is nothing to say.
+ */
+export declare function useAnnouncement(text: string, delay: number): string | null;

package/dist/lib/components/ui/display/vote-tally/use-tally-summary.d.ts

@@ -0,0 +1,3 @@
+import { Tally } from './vote-tally.utils.js';
+/** One sentence on where the vote stands: the leader, the tie, the abstentions. */
+export declare function useTallySummary(result: Tally, abstain: number, showLeader?: boolean): string;

package/dist/lib/components/ui/display/vote-tally/vote-tally.d.ts

@@ -0,0 +1,10 @@
+import { VoteTallyProps } from './types.js';
+/**
+ * A live ranked tally of a vote: one row per option with its count and share
+ * as text ("Ada, 3 votes, 42%"), a decorative bar, and who voted for it. A
+ * leader, a tie and the viewer's own vote are marked in words, never by
+ * colour alone. Counts may change at any time: bars ease only without
+ * reduced motion, and a polite live region says what changed, once the
+ * changes stop for `announceDelay`.
+ */
+export declare function VoteTally(props: VoteTallyProps): import("react").JSX.Element;

package/dist/lib/components/ui/display/vote-tally/vote-tally.utils.d.ts

@@ -0,0 +1,18 @@
+import { VoteOption, VoteRow, VoteTallySort } from './types.js';
+export type Tally = {
+    rows: VoteRow[];
+    /** The base of the shares. */
+    total: number;
+    /** Top count, 0 without a vote. */
+    top: number;
+    /** Several options share the top count. */
+    tie: boolean;
+};
+/**
+ * Ranks the options and works out each share. Options with the same count
+ * share a rank and are never ordered by an arbitrary leader: with the top
+ * count held by several, none is a `leader`, all are `tied`.
+ */
+export declare function tally(options: VoteOption[], sort: VoteTallySort, total?: number, selectedId?: string, marks?: boolean): Tally;
+/** Whole votes an option is shown with. */
+export declare const votesOf: (option: VoteOption) => number;