@nxgt/material 3.55.0 → 3.57.0

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;

package/dist/lib/components/ui/feedback/countdown-timer/countdown-ring.d.ts

@@ -0,0 +1,7 @@
+import { CountdownTone } from './countdown-timer.utils.js';
+/** The ring that empties as the time runs out; decoration, the clock carries the time. */
+export declare function CountdownRing({ tone, fraction, size, }: {
+    tone: CountdownTone;
+    fraction: number;
+    size: 'sm' | 'md';
+}): import("react").JSX.Element;

package/dist/lib/components/ui/feedback/countdown-timer/countdown-timer.d.ts

@@ -12,6 +12,12 @@ export type CountdownTimerProps = {
     criticalAt?: number;
     /** Its name; "Time remaining" by default. */
     label?: string;
+    /**
+     * What the warning tone says beside the clock, with a clock icon, so low
+     * time is not shown by colour alone. "Little time left" by default; `false`
+     * hides the icon and the words (the announcement then speaks the time only).
+     */
+    warningText?: string | false;
     size?: 'sm' | 'md';
 } & Omit<ComponentProps<'div'>, 'children'>;
 /**
@@ -20,4 +26,4 @@ export type CountdownTimerProps = {
  * assistive tech hears it only when it crosses a threshold and when the time
  * is up, never every second.
  */
-export declare function CountdownTimer({ duration, paused, onExpire, warningAt, criticalAt, label, size, className, ...props }: CountdownTimerProps): import("react").JSX.Element;
+export declare function CountdownTimer({ duration, paused, onExpire, warningAt, criticalAt, label, warningText, size, className, ...props }: CountdownTimerProps): import("react").JSX.Element;