@nxgt/material 3.60.0 → 3.63.0

package/dist/lib/components/ui/layout/app-shell/route-transition.d.ts

@@ -1,12 +1,16 @@
 import { ReactElement, ViewTransitionClass, ViewTransitionProps } from 'react';
 /**
  * `ActivityLayout`'s `routeTransition`: `false` for none, `true` for the
- * default, or the props of React's `<ViewTransition>` (minus `children` and
+ * default (the region fades only when the pathname changes, not on a search
+ * or hash change, a fetcher or a revalidation), or the props of React's `<ViewTransition>` (minus `children` and
  * `ref`) to tune it: the app's classes (a class, or a map by transition
  * type), a `name`, callbacks.
  */
 export type RouteTransition = boolean | Omit<ViewTransitionProps, 'children' | 'ref'>;
-/** The class the library's reduced-motion rule and cross-fade target. */
+/**
+ * The class the library's reduced-motion rule and cross-fade target. Put it
+ * on a nested `<ViewTransition>` to fade with the same timing as the shell.
+ */
 export declare const ROUTE_TRANSITION_CLASS = "nxgt-route";
 /**
  * The attribute `<html>` carries while an `ActivityLayout` with the
@@ -44,6 +48,20 @@ export declare function routeTransitionProps(transition: Exclude<RouteTransition
     onExit?: ((instance: import('react').ViewTransitionInstance, types: Array<string>) => void | (() => void)) | undefined;
     onShare?: ((instance: import('react').ViewTransitionInstance, types: Array<string>) => void | (() => void)) | undefined;
 };
+/**
+ * `transition`, with the default (`true`) gated on the pathname: its update
+ * animation runs only for a render whose pathname differs from the last
+ * committed one. React Router runs search-param navigations, fetchers and
+ * revalidations as untyped transitions too, and those would fade the whole
+ * region (and drop keystrokes typed into a search inside it). An explicit
+ * value is returned as is, so the app keeps its own control.
+ */
+export declare function useGatedRouteTransition(transition: RouteTransition): RouteTransition;
+/**
+ * `transition` for a render at `pathname`, the last commit being at
+ * `committed`: only `true` is gated (see {@link useGatedRouteTransition}).
+ */
+export declare function gateRouteTransition(transition: RouteTransition, committed: string, pathname: string): RouteTransition;
 /**
  * The app's one persistent route boundary, around the content region.
  * Never keyed by location, so a navigation updates it instead of remounting.

package/dist/lib/components/ui/layout/app-shell/shapes-clear-content.d.ts

@@ -9,8 +9,9 @@ export declare const CONTROLS = "input, textarea, select, button, a[href], img,
  * The surfaces of the page: a card, a panel, a table, a list. A glyph
  * is dropped when it meets one of these whole boxes, not only the text inside
  * (which left glyphs half hidden at a card's edge, and between its lines).
+ * `.bg-card` is a plain element drawn as a card.
  */
-export declare const SURFACES = "[data-slot=\"card\"], [data-slot=\"stat-card\"], [data-slot=\"table-wrapper\"], [data-slot=\"data-table-items\"], [data-slot=\"data-table-cards\"], [data-slot=\"data-table-tiles\"], [data-slot=\"data-grid\"], [data-slot=\"alert\"], [data-slot=\"banner\"], [role=\"alert\"], [role=\"alertdialog\"], [role=\"dialog\"], table, ul, ol";
+export declare const SURFACES = "[data-slot=\"card\"], [data-slot=\"stat-card\"], [data-slot=\"table-wrapper\"], [data-slot=\"data-table-items\"], [data-slot=\"data-table-cards\"], [data-slot=\"data-table-tiles\"], [data-slot=\"data-grid\"], [data-slot=\"alert\"], [data-slot=\"banner\"], [role=\"alert\"], [role=\"alertdialog\"], [role=\"dialog\"], table, ul, ol, .bg-card";
 /**
  * The drop rule: whether a glyph lies over (or within `margin` of) any
  * occupied box of the content. A glyph that does is dropped whole, never

package/dist/lib/components/ui/widgets/code-editor/configure-monaco.d.ts

@@ -6,5 +6,7 @@ import { loader } from '@monaco-editor/react';
  * CDN, nothing for a strict CSP to allow — or `paths.vs` to serve Monaco's
  * files from your origin. Call it once, before the first editor mounts. The
  * self-hosting guide (docs/guides/code-editor.md) has the workers' setup.
+ *
+ * It also gives the `<style>` elements Monaco injects the page's CSP nonce.
  */
 export declare function configureMonaco(options: Parameters<typeof loader.config>[0]): void;

package/dist/lib/components/ui/widgets/education/questions/index.d.ts

@@ -1,3 +1,5 @@
 export { QuestionCard } from './question.js';
 export { answerParts, isAnswerCorrect, isAnswered, parseAnswerNumber, } from './question.utils.js';
-export type { Question, QuestionAnswer, QuestionImage, QuestionKind, QuestionMedia, QuestionMediaKind, QuestionOption, QuestionPoints, QuestionProps, QuestionVerdict, } from './types.js';
+export { QuestionMediaView } from './question-media-view.js';
+export type { QuestionMediaFile, QuestionMediaViewProps, } from './question-media-view.types.js';
+export type { Question, QuestionAnswer, QuestionCodeField, QuestionImage, QuestionKind, QuestionMedia, QuestionMediaKind, QuestionOption, QuestionPoints, QuestionProps, QuestionVerdict, } from './types.js';

package/dist/lib/components/ui/widgets/education/questions/partials/question-content.d.ts

@@ -1,3 +1,3 @@
 import { QuestionProps } from '../types.js';
 /** A question's fieldset: prompt, header, media, hint, the answer body and the feedback. */
-export declare function QuestionContent({ question, value, onValueChange, revealed: revealedProp, verdict, points, feedback, disabled, variant, density, showShortcuts, number, showFeedback, }: QuestionProps): import("react").JSX.Element;
+export declare function QuestionContent({ question, value, onValueChange, revealed: revealedProp, verdict, points, feedback, disabled, readOnly, busy, renderCode, variant, density, showShortcuts, number, showFeedback, }: QuestionProps): import("react").JSX.Element;

package/dist/lib/components/ui/widgets/education/questions/partials/question-top.d.ts

@@ -0,0 +1,6 @@
+import { QuestionProps } from '../types.js';
+/** The prompt (the fieldset's legend), the header, the media and the hint. */
+export declare function QuestionTop({ question, number, density, revealed, promptId, }: Pick<QuestionProps, 'question' | 'number' | 'density'> & {
+    revealed: boolean;
+    promptId: string;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/widgets/education/questions/question-long-text.d.ts

@@ -0,0 +1,5 @@
+import { QuestionProps } from './types.js';
+/** A multi-line answer: `open` (prose) or `code` (the `renderCode` field, else a monospace textarea). */
+export declare function QuestionLongText({ question, value, onValueChange, revealed, verdict, disabled, readOnly, busy, renderCode, labelledBy, }: QuestionProps & {
+    labelledBy: string;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/widgets/education/questions/question-media-content.d.ts

@@ -0,0 +1,24 @@
+import { MouseEvent, Ref } from 'react';
+import { QuestionMediaCaption, QuestionMediaFile } from './question-media-view.types.js';
+/** The alert of a file that did not load, with Reload when the host can. */
+export declare function MediaErrorAlert({ onReload, onReloadBlur, reloading, }: {
+    onReload?: (event: MouseEvent<HTMLButtonElement>) => void;
+    /** Focus went to another control: Reload's focus intent is over. */
+    onReloadBlur?: () => void;
+    reloading: boolean;
+}): import("react").JSX.Element;
+/** A document as a plain link: it fetches nothing, so no `connect-src` or CORS. */
+export declare function DocumentLink({ media }: {
+    media: QuestionMediaFile;
+}): import("react").JSX.Element;
+type ContentProps = {
+    media: QuestionMediaFile;
+    family: 'image' | 'audio' | 'video' | 'document';
+    documents: 'link' | 'preview';
+    captions?: QuestionMediaCaption[];
+    onFail: () => void;
+    imageRef: Ref<HTMLImageElement>;
+};
+/** The file itself, by family. */
+export declare function MediaContent({ media, family, documents, captions, onFail, imageRef, }: ContentProps): import("react").JSX.Element;
+export {};

package/dist/lib/components/ui/widgets/education/questions/question-media-helpers.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The file's family: `kind` when the host gave one, else the MIME `type`
+ * (case-insensitive), else an image (as `QuestionCard` reads `Question.media`).
+ * There is no `kind: 'video'`: a video is picked by its `type`.
+ */
+export declare function mediaFamily(media: {
+    type?: string;
+    kind?: string;
+}): "document" | "image" | "video" | "audio";
+/** The short name of a MIME type: "PDF" for `application/pdf`. */
+export declare const contentTypeLabel: (contentType: string) => string;

package/dist/lib/components/ui/widgets/education/questions/question-media-view.d.ts

@@ -0,0 +1,18 @@
+import { QuestionMediaViewProps } from './question-media-view.types.js';
+export { contentTypeLabel, mediaFamily } from './question-media-helpers.js';
+/**
+ * A question's file, picked by its type: an image, an audio clip, a video, or
+ * a document (a link that opens in a new tab and fetches nothing, or
+ * `FilePreview` with `documents="preview"`). It takes the shape of
+ * `Question.media` (plus `size`), so a question's `media` goes straight in. The
+ * file is named for assistive technology (`name`, else `alt`, else a generic
+ * name). When it fails to load (a presigned link that expired) an alert says
+ * so and, with `onReload`, offers a Reload button; a new `src` is a new
+ * chance, and focus then moves to the file if it was on Reload. A reload that
+ * returns the same `src` keeps the error. A document link cannot report that
+ * it expired.
+ *
+ * `QuestionCard` draws its own `media` without an error state; it should reuse
+ * this view (follow-up #2021). Vue twin: `vue` issue #2020.
+ */
+export declare function QuestionMediaView({ media, onReload, reloading, documents, captions, className, }: QuestionMediaViewProps): import("react").JSX.Element;

package/dist/lib/components/ui/widgets/education/questions/question-media-view.types.d.ts

@@ -0,0 +1,32 @@
+import { QuestionMedia } from './types.js';
+/**
+ * A file attached to a question: the shape of `Question.media` (`src`, `alt`,
+ * `type`, `kind`, `name`) plus its size, so `question.media` can be passed
+ * straight in. `type` (a MIME type: `image/png`, `audio/mpeg`, `video/mp4`,
+ * `application/pdf`) picks the rendering; without it the file is an image.
+ */
+export type QuestionMediaFile = QuestionMedia & {
+    /** Size in bytes, shown in a document link. */
+    size?: number | null;
+};
+/** A caption track of a video. */
+export type QuestionMediaCaption = {
+    src: string;
+    /** BCP 47 tag of the track's language (`en`, `fr`). */
+    srclang: string;
+    /** The name shown in the player's captions menu. */
+    label: string;
+    default?: boolean;
+};
+export type QuestionMediaViewProps = {
+    media: QuestionMediaFile;
+    /** Called by the Reload button of the error alert; without it the alert has no button. */
+    onReload?: () => void;
+    /** The Reload button is busy: the new link is being fetched. */
+    reloading?: boolean;
+    /** A document is a link to a new tab (default, fetches nothing) or a `FilePreview`. */
+    documents?: 'link' | 'preview';
+    /** Caption tracks of a video; a clip with speech needs them (or a transcript next to it). */
+    captions?: QuestionMediaCaption[];
+    className?: string;
+};

package/dist/lib/components/ui/widgets/education/questions/question-options.d.ts

@@ -1,5 +1,5 @@
 import { Question, QuestionOption, QuestionProps } from './types.js';
-type QuestionOptionsProps = Pick<QuestionProps, 'revealed' | 'verdict' | 'disabled' | 'density' | 'showShortcuts'> & {
+type QuestionOptionsProps = Pick<QuestionProps, 'revealed' | 'verdict' | 'disabled' | 'readOnly' | 'busy' | 'density' | 'showShortcuts'> & {
     question: Question;
     options: QuestionOption[];
     value: string[];
@@ -7,5 +7,5 @@ type QuestionOptionsProps = Pick<QuestionProps, 'revealed' | 'verdict' | 'disabl
     labelledBy?: string;
     onToggle: (id: string) => void;
 };
-export declare function QuestionOptions({ question, options, value, multiple, revealed, verdict, disabled, density, showShortcuts, labelledBy, onToggle, }: QuestionOptionsProps): import("react").JSX.Element;
+export declare function QuestionOptions({ question, options, value, multiple, revealed, verdict, disabled, readOnly, busy, density, showShortcuts, labelledBy, onToggle, }: QuestionOptionsProps): import("react").JSX.Element;
 export {};

package/dist/lib/components/ui/widgets/education/questions/question-text.d.ts

@@ -1,3 +1,3 @@
 import { QuestionProps } from './types.js';
 /** A typed answer: `text`, or `number` (a decimal keypad, an optional unit). */
-export declare function QuestionText({ question, value, onValueChange, revealed, verdict, disabled, showFeedback, }: QuestionProps): import("react").JSX.Element;
+export declare function QuestionText({ question, value, onValueChange, revealed, verdict, disabled, readOnly, busy, showFeedback, }: QuestionProps): import("react").JSX.Element;

package/dist/lib/components/ui/widgets/education/questions/question.d.ts

@@ -1,2 +1,2 @@
 import { QuestionProps } from './types.js';
-export declare function QuestionCard({ question, value, onValueChange, revealed, verdict, points, feedback, disabled, className, variant, density, showShortcuts, number, showFeedback, }: QuestionProps): import("react").JSX.Element;
+export declare function QuestionCard({ question, value, onValueChange, revealed, verdict, points, feedback, disabled, readOnly, busy, renderCode, className, variant, density, showShortcuts, number, showFeedback, }: QuestionProps): import("react").JSX.Element;

package/dist/lib/components/ui/widgets/education/questions/types.d.ts

@@ -1,5 +1,11 @@
 import { ReactNode } from 'react';
-export type QuestionKind = 'choice' | 'multi' | 'boolean' | 'text' | 'number';
+/**
+ * `text` is a one-line answer; `open` a multi-line one (a textarea with a
+ * counter); `code` source code (a code editor from `renderCode`, else a
+ * monospace textarea). `open` and `code` have no `correct`: a grader gives the
+ * `verdict`.
+ */
+export type QuestionKind = 'choice' | 'multi' | 'boolean' | 'text' | 'number' | 'open' | 'code';
 export type QuestionImage = {
     src: string;
     alt?: string;
@@ -53,6 +59,27 @@ export type Question = {
     tolerance?: number;
     /** `number`: the unit shown after the field ("km", "%"). */
     unit?: string;
+    /** `open`, `code`: the most characters accepted; a counter shows while editable. */
+    maxLength?: number;
+    /** `code`: the language of the code ("python"), given to `renderCode`. */
+    language?: string;
+};
+/**
+ * What `renderCode` gets to draw the code field of a `code` question. The
+ * editor must be named by the prompt (`label`, or `aria-labelledby={labelledBy}`)
+ * and honour `readOnly` and `disabled`.
+ */
+export type QuestionCodeField = {
+    value: string;
+    onChange: (value: string) => void;
+    /** The prompt's id: name the field with `aria-labelledby`. */
+    labelledBy: string;
+    /** The prompt, as a text label for editors that take one. */
+    label: string;
+    language?: string;
+    maxLength?: number;
+    readOnly: boolean;
+    disabled: boolean;
 };
 export type QuestionProps = {
     question: Question;
@@ -72,6 +99,16 @@ export type QuestionProps = {
     /** A grader's remark, shown in the verdict banner (needs `verdict`). */
     feedback?: string;
     disabled?: boolean;
+    /** The answer is shown but not editable (already submitted), without the revealed marks. Every kind honours it. */
+    readOnly?: boolean;
+    /** An answer is being saved: the field is locked like `readOnly` and `aria-busy`. Every kind honours it. */
+    busy?: boolean;
+    /**
+     * The code field of a `code` question, e.g. `@nxgt/material/code-editor`'s
+     * `CodeEditor` (kept out of this bundle: Monaco is heavy). Without it the
+     * field is a monospace textarea.
+     */
+    renderCode?: (field: QuestionCodeField) => ReactNode;
     className?: string;
     /** `card` (the default) is framed; `plain` sits inside another surface. */
     variant?: 'card' | 'plain';

package/dist/lib/components/ui/widgets/education/questions/use-reload-focus.d.ts

@@ -0,0 +1,13 @@
+import { MouseEvent } from 'react';
+/**
+ * Where the focus goes when Reload works. The intent is set when Reload is
+ * pressed with the focus on its button, and honoured only for the `src` change
+ * that answers it. It ends when a new failure is recorded, when the reload
+ * ends with the same `src` (`reloading` back to false), or when the focus
+ * moves to another control.
+ */
+export declare function useReloadFocus(src: string, reloading: boolean, onReload: (() => void) | undefined): {
+    frame: import('react').RefObject<HTMLDivElement | null>;
+    end: () => void;
+    reload: ((event: MouseEvent<HTMLButtonElement>) => void) | undefined;
+};

package/dist/lib/hooks/drafts-store.d.ts

@@ -0,0 +1,4 @@
+/** Reads and writes the drafts of one store key; every error reads as no drafts. */
+export type DraftsStore = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> | undefined;
+export declare function readDrafts<T>(storage: DraftsStore, storageKey: string, parse: (raw: string) => T | undefined): Record<string, T>;
+export declare function writeDrafts<T>(storage: DraftsStore, storageKey: string, drafts: Record<string, T>, serialize: (value: T) => string): void;

package/dist/lib/hooks/index.d.ts

@@ -1,7 +1,9 @@
 export * from './resolve-theme.js';
+export * from './unsaved-guard-rules.js';
 export * from './use-allowed-transitions.js';
 export * from './use-countdown.js';
 export { useCspNonce } from './use-csp-nonce.js';
+export * from './use-drafts.js';
 export * from './use-focus-on-mount.js';
 export * from './use-formatters.js';
 export * from './use-heading-spy.js';
@@ -11,7 +13,9 @@ export * from './use-mobile.js';
 export * from './use-navigation.js';
 export * from './use-number-formatter.js';
 export * from './use-options.js';
+export * from './use-react-router-block.js';
 export * from './use-scroll-away.js';
 export * from './use-search-param.js';
 export * from './use-submit-once.js';
 export * from './use-theme.js';
+export * from './use-unsaved-guard/index.js';

package/dist/lib/hooks/unsaved-guard-rules.d.ts

@@ -0,0 +1,30 @@
+/** The part of a location a guard compares. */
+export interface GuardLocation {
+    pathname: string;
+    search: string;
+    hash: string;
+}
+/** What a router tells its blocker: where the page is, and where it goes. */
+export interface BlockContext {
+    currentLocation: GuardLocation;
+    nextLocation: GuardLocation;
+}
+/** Decides whether going from `current` to `next` counts as leaving. */
+export type LeavePredicate = (current: GuardLocation, next: GuardLocation) => boolean;
+/**
+ * The default notion of leaving: the pathname or the query string differs (a
+ * filter or period param remounts most pages). A hash change alone is not a
+ * leave. With `ignoreSearch`, only the pathname counts, for a page whose state
+ * lives in a step that a query change keeps mounted.
+ */
+export declare function isLeaving(current: GuardLocation, next: GuardLocation, options?: {
+    ignoreSearch?: boolean;
+}): boolean;
+/** Whether the guard blocks this navigation right now. Pure, for tests. */
+export declare function shouldBlockNavigation({ dirty, released, context, leaves, ignoreSearch, }: {
+    dirty: boolean;
+    released: boolean;
+    context: BlockContext;
+    leaves?: LeavePredicate;
+    ignoreSearch?: boolean;
+}): boolean;

package/dist/lib/hooks/use-drafts.d.ts

@@ -0,0 +1,75 @@
+import { DraftsStore } from './drafts-store.js';
+/** A store, or a function that returns it (preferred: it is called only on the client). */
+export type DraftsStorage = DraftsStore | (() => DraftsStore);
+export interface UseDraftsOptions<T> {
+    /** Turns a value into a string for the store. Default: `JSON.stringify`. */
+    serialize?: (value: T) => string;
+    /**
+     * Turns a stored string back into a value; throw or return `undefined` to
+     * ignore a damaged entry. Default: `JSON.parse`.
+     */
+    parse?: (raw: string) => T | undefined;
+    /**
+     * The store, or a function that returns it (preferred, so nothing touches
+     * `window` during render): `() => localStorage`. Default: the tab's
+     * `sessionStorage`.
+     */
+    storage?: DraftsStorage;
+}
+export interface UseDraftsResult<T> {
+    /** The draft of `key`, or `undefined`. */
+    get: (key: string) => T | undefined;
+    /** Keeps `value` as the draft of `key`. */
+    set: (key: string, value: T) => void;
+    /** Drops the draft of `key`: call it when its value is saved. */
+    drop: (key: string) => void;
+    /** Drops every draft of this store. */
+    clear: () => void;
+    /** The keys that hold an unsaved draft, in the order they were first set. */
+    keys: readonly string[];
+    /** False until the stored drafts were read, after the first render. */
+    loaded: boolean;
+}
+/**
+ * Drops every draft of a store key without a mounted hook: call it at
+ * sign-out so the next person on the tab sees none. A mounted `useDrafts` of
+ * the same key keeps what it holds until it is remounted or calls `clear()`.
+ *
+ * @example
+ * ```ts
+ * clearDrafts('quiz-1');
+ * clearDrafts('quiz-1', () => localStorage);
+ * ```
+ */
+export declare function clearDrafts(storageKey: string, storage?: DraftsStorage): void;
+/**
+ * Unsent values kept by key in the tab's `sessionStorage`, so a reload, the
+ * back button or a jump to another step of a form loses no typed text.
+ *
+ * - **SSR-safe**: the first render, on the server and on the client, has no
+ *   drafts; they are read in an effect (`loaded` turns true), so hydration
+ *   never mismatches.
+ * - **Storage errors are swallowed**: a private window, a blocked or full
+ *   store, or a damaged entry reads and writes as no draft.
+ * - **Written at once**: `set`, `drop` and `clear` write the store in the
+ *   call, so a `drop` or `clear` before `loaded` wins over the stored copy.
+ * - **Cleared on submit**: call `drop(key)` (or `clear()`) once the value is
+ *   saved; an empty set removes the store key.
+ * - **A new `storageKey`** starts from that key's stored drafts, with
+ *   `loaded` false until they are read; the old key's drafts stay in the
+ *   store under the old key.
+ * - **Two instances on one key** each read at mount and merge on write;
+ *   they do not update each other live.
+ *
+ * @example
+ * ```tsx
+ * const drafts = useDrafts<string>('quiz-1');
+ * <Textarea
+ *   value={drafts.get('q3') ?? ''}
+ *   onChange={(e) => drafts.set('q3', e.target.value)}
+ * />
+ * // after the answer is saved:
+ * drafts.drop('q3');
+ * ```
+ */
+export declare function useDrafts<T = string>(storageKey: string, options?: UseDraftsOptions<T>): UseDraftsResult<T>;

package/dist/lib/hooks/use-react-router-block.d.ts

@@ -0,0 +1,11 @@
+import { BlockAdapter } from './use-unsaved-guard/types.js';
+/**
+ * The React Router adapter for `useUnsavedGuard`: needs a data router
+ * (`createBrowserRouter`, or `createMemoryRouter` in a story or test).
+ *
+ * @example
+ * ```tsx
+ * const { release, dialog } = useUnsavedGuard(isDirty, { block: useReactRouterBlock });
+ * ```
+ */
+export declare const useReactRouterBlock: BlockAdapter;

package/dist/lib/hooks/use-unsaved-guard/guard-core.d.ts

@@ -0,0 +1,30 @@
+import { BlockContext, LeavePredicate } from '../unsaved-guard-rules.js';
+import { Dirty } from './types.js';
+export declare const readDirty: (dirty: Dirty) => boolean;
+/**
+ * The framework-free state of a guard: a one-shot release and the two checks
+ * (a navigation, a tab unload). Plain functions so a node test can drive them.
+ */
+export declare function createGuardCore(getDirty: () => Dirty): {
+    /**
+     * The next leaving navigation check passes, then the guard re-arms. A
+     * release no navigation consumed expires when the current task ends, so a
+     * later edit is guarded again.
+     */
+    release(): void;
+    rearm: () => void;
+    /** Drops a pending expiry timer (unmount). */
+    dispose: () => void;
+    /** A navigation check: only an actual leave consumes a release. */
+    shouldBlock(context: BlockContext, rules: {
+        leaves?: LeavePredicate;
+        ignoreSearch?: boolean;
+    }): boolean;
+    /** A tab unload check: a release stays until the navigation consumes it. */
+    shouldWarnUnload(): boolean;
+};
+export type GuardCore = ReturnType<typeof createGuardCore>;
+/** Warns the browser on unload while the core says so; returns the cleanup. */
+export declare function listenBeforeUnload(target: Pick<Window, 'addEventListener' | 'removeEventListener'>, core: Pick<GuardCore, 'shouldWarnUnload'>): () => void;
+/** Runs `onBlock`: true when nothing is left to lose; a throw or no hook is false. */
+export declare function flushBeforeAsking(onBlock: (() => boolean | Promise<boolean>) | undefined): Promise<boolean>;

package/dist/lib/hooks/use-unsaved-guard/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './use-discard-guard.js';
+export * from './use-unsaved-guard.js';

package/dist/lib/hooks/use-unsaved-guard/types.d.ts

@@ -0,0 +1,63 @@
+import { ReactNode } from 'react';
+import { BlockContext, LeavePredicate } from '../unsaved-guard-rules.js';
+export type BlockState = 'unblocked' | 'blocked' | 'proceeding';
+/** What a router's blocker gives back. */
+export interface BlockResult {
+    state: BlockState;
+    /** Lets the blocked navigation go through. */
+    proceed: () => void;
+    /** Cancels the blocked navigation: the user stays. */
+    reset: () => void;
+}
+/**
+ * A router adapter: a hook that registers `shouldBlock` with the router and
+ * returns its blocker. `useReactRouterBlock` is the React Router one; any
+ * router with a blocker (TanStack Router's `useBlocker`, …) fits in a few lines.
+ */
+export type BlockAdapter = (shouldBlock: (context: BlockContext) => boolean) => BlockResult;
+/** A boolean, or a function read when the navigation happens (never stale). */
+export type Dirty = boolean | (() => boolean);
+export interface UnsavedGuardLabels {
+    title?: string;
+    description?: string;
+    stayLabel?: string;
+    leaveLabel?: string;
+}
+export interface UseUnsavedGuardOptions extends UnsavedGuardLabels {
+    /** The router adapter, for example `useReactRouterBlock`. */
+    block: BlockAdapter;
+    /**
+     * What counts as leaving. Default: the pathname or the query string
+     * differs. Overrides `ignoreSearch`.
+     */
+    leaves?: LeavePredicate;
+    /** Only a pathname change counts (a query change between steps is free). */
+    ignoreSearch?: boolean;
+    /**
+     * Runs when a navigation is blocked, before the dialog. Resolve `true` when
+     * nothing is left to lose (pending saves flushed): the navigation goes
+     * through silently. Resolve `false` (or throw) to ask.
+     */
+    onBlock?: () => boolean | Promise<boolean>;
+}
+export interface UseUnsavedGuardResult {
+    /**
+     * Synchronous, one-shot: the next navigation that really leaves (not a hash
+     * change, nor a query change under `ignoreSearch`) passes, and a tab unload
+     * prompt stays quiet until then; the guard then re-arms by itself. A release
+     * no navigation consumed expires when the current task ends, so call it right
+     * before `navigate()`. A boolean `dirty` turning true again re-arms it too.
+     */
+    release: () => void;
+    /** Render it once, anywhere in the page. */
+    dialog: ReactNode;
+}
+export interface UseDiscardGuardResult {
+    /**
+     * Runs `action` (close the dialog or sheet) at once when the form is clean,
+     * and after the user chose "Leave" when it is dirty.
+     */
+    close: (action: () => void) => void;
+    /** Render it once, beside the form. */
+    dialog: ReactNode;
+}

package/dist/lib/hooks/use-unsaved-guard/use-discard-guard.d.ts

@@ -0,0 +1,15 @@
+import { Dirty, UnsavedGuardLabels, UseDiscardGuardResult } from './types.js';
+/**
+ * The guard of a form inside a dialog or a sheet: closing asks first, only
+ * when the form is dirty. Route its close button, Escape and overlay click
+ * through `close(action)`.
+ *
+ * @example
+ * ```tsx
+ * const { close, dialog } = useDiscardGuard(form.formState.isDirty);
+ * <Sheet open={open} onOpenChange={(next) => (next ? setOpen(true) : close(() => setOpen(false)))}>
+ *   …{dialog}
+ * </Sheet>
+ * ```
+ */
+export declare function useDiscardGuard(dirty: Dirty, labels?: UnsavedGuardLabels): UseDiscardGuardResult;

package/dist/lib/hooks/use-unsaved-guard/use-unsaved-guard.d.ts

@@ -0,0 +1,19 @@
+import { Dirty, UseUnsavedGuardOptions, UseUnsavedGuardResult } from './types.js';
+/**
+ * Blocks in-app navigation while a form is dirty (a "Leave without saving?"
+ * dialog) and asks the browser to confirm closing or reloading the tab.
+ * Router-agnostic: the router comes in through `block`.
+ *
+ * @example
+ * ```tsx
+ * const { release, dialog } = useUnsavedGuard(form.formState.isDirty, {
+ *   block: useReactRouterBlock,
+ * });
+ * async function onSubmit(values) {
+ *   await save(values);
+ *   release();
+ *   navigate('/items');
+ * }
+ * ```
+ */
+export declare function useUnsavedGuard(dirty: Dirty, options: UseUnsavedGuardOptions): UseUnsavedGuardResult;

package/dist/lib/i18n/resources/en/en.d.ts

@@ -303,6 +303,7 @@ export declare const en: {
             true: string;
             false: string;
             "answer-placeholder": string;
+            "code-placeholder": string;
             expected: string;
             next: string;
             previous: string;
@@ -319,6 +320,19 @@ export declare const en: {
             "kind-multi": string;
             "kind-boolean": string;
             "kind-text": string;
+            "kind-open": string;
+            "kind-code": string;
+        };
+        "question-media": {
+            image: string;
+            audio: string;
+            video: string;
+            document: string;
+            "error-title": string;
+            "error-description": string;
+            reload: string;
+            open: string;
+            "new-tab": string;
         };
         quiz: {
             count: string;
@@ -1339,6 +1353,12 @@ export declare const en: {
             dark: string;
             system: string;
         };
+        unsaved: {
+            title: string;
+            description: string;
+            stay: string;
+            leave: string;
+        };
         "load-more": {
             shown: string;
             "shown-count": string;