@scalewing/react 1.40.0 → 1.42.0

package/dist/components/denomination-grid/types.js

@@ -1 +1,7 @@
-export {};
+/** How a negative count reads: in the danger colour, or plain text. */
+export const denominationNegativeAppearances = ['danger', 'plain'];
+/**
+ * The widths below which a strip is drawn transposed: the denominations as
+ * rows, the grid's rows as columns.
+ */
+export const denominationTransposeBreakpoints = ['md', 'lg'];

package/dist/components/denomination-grid/validate-options.d.ts

@@ -0,0 +1,7 @@
+import { type DenominationGridLayout, type DenominationGridRow } from './types.js';
+/**
+ * The grid's later options: a known negative appearance per row, a known
+ * transpose breakpoint on a strip only, and a whole count of digits (3 to
+ * 6) for a grid with entry rows.
+ */
+export declare function assertDenominationOptions(layout: DenominationGridLayout, rows: readonly DenominationGridRow[], transposeBelow: unknown, countDigits: unknown): void;

package/dist/components/denomination-grid/validate-options.js

@@ -0,0 +1,27 @@
+import { denominationNegativeAppearances, denominationTransposeBreakpoints, } from './types.js';
+/** The digits an entry count can be given room for. */
+const countDigitsRange = { min: 3, max: 6 };
+/**
+ * The grid's later options: a known negative appearance per row, a known
+ * transpose breakpoint on a strip only, and a whole count of digits (3 to
+ * 6) for a grid with entry rows.
+ */
+export function assertDenominationOptions(layout, rows, transposeBelow, countDigits) {
+    if (rows.some((row) => row.negativeAppearance !== undefined &&
+        !denominationNegativeAppearances.includes(row.negativeAppearance)))
+        throw new RangeError("negativeAppearance must be 'danger' or 'plain'");
+    if (transposeBelow !== undefined) {
+        if (!denominationTransposeBreakpoints.includes(transposeBelow))
+            throw new RangeError("transposeBelow must be 'md' or 'lg'");
+        if (layout !== 'strip')
+            throw new RangeError('transposeBelow needs the strip layout');
+    }
+    if (countDigits !== undefined) {
+        if (!Number.isInteger(countDigits) ||
+            countDigits < countDigitsRange.min ||
+            countDigits > countDigitsRange.max)
+            throw new RangeError('countDigits must be a whole number from 3 to 6');
+        if (!rows.some((row) => row.entry))
+            throw new RangeError('countDigits needs entry rows');
+    }
+}

package/dist/components/dialog/DialogFooter.d.ts

@@ -2,13 +2,14 @@ import { type ReactNode } from 'react';
 import { type ActionBarSummary } from '../action-bar/ActionBarSummary.js';
 type DialogFooterProps = {
     summary?: ActionBarSummary;
+    status?: ReactNode;
     children?: ReactNode;
 };
 /**
- * The dialog's pinned footer: the summary figure (in a polite live region,
- * as in ActionBar) at the start, the actions at the end. Rendered only when
- * the dialog has a footer or a summary, and then always with its status
- * region, so a new figure is announced.
+ * The dialog's pinned footer: the summary figure and the status line (in
+ * one polite live region, as in ActionBar) at the start, the actions at the
+ * end. Rendered only when the dialog has a footer, a summary or a status,
+ * and then always with its live region, so a new figure is announced.
  */
-export declare function DialogFooter({ children, summary }: DialogFooterProps): import("react").JSX.Element;
+export declare function DialogFooter({ children, status, summary }: DialogFooterProps): import("react").JSX.Element;
 export {};

package/dist/components/dialog/DialogFooter.js

@@ -1,11 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { ActionBarSummaryLine, } from '../action-bar/ActionBarSummary.js';
 /**
- * The dialog's pinned footer: the summary figure (in a polite live region,
- * as in ActionBar) at the start, the actions at the end. Rendered only when
- * the dialog has a footer or a summary, and then always with its status
- * region, so a new figure is announced.
+ * The dialog's pinned footer: the summary figure and the status line (in
+ * one polite live region, as in ActionBar) at the start, the actions at the
+ * end. Rendered only when the dialog has a footer, a summary or a status,
+ * and then always with its live region, so a new figure is announced.
  */
-export function DialogFooter({ children, summary }) {
-    return (_jsxs("div", { className: "sw-dialog-footer", children: [_jsx("div", { className: "sw-dialog-footer-status", role: "status", children: summary ? _jsx(ActionBarSummaryLine, { summary: summary }) : null }), children ? (_jsx("div", { className: "sw-dialog-footer-actions", children: children })) : null] }));
+export function DialogFooter({ children, status, summary }) {
+    return (_jsxs("div", { className: "sw-dialog-footer", children: [_jsxs("div", { className: "sw-dialog-footer-status", role: "status", children: [summary ? _jsx(ActionBarSummaryLine, { summary: summary }) : null, status !== undefined ? (_jsx("span", { className: "sw-dialog-footer-note", children: status })) : null] }), children ? (_jsx("div", { className: "sw-dialog-footer-actions", children: children })) : null] }));
 }

package/dist/components/dialog/validate.d.ts

@@ -0,0 +1,24 @@
+import { type Breakpoint } from '../../css/breakpoints.js';
+import { type DialogAppearance } from '../../css/css-dialog-banded.js';
+import { type ThemeCanvas } from '../../css/css-canvas-grouped.js';
+import { type ActionBarSummary } from '../action-bar/ActionBarSummary.js';
+export declare const dialogSizes: readonly ["md", "lg", "xl"];
+/**
+ * `md` is the reading width (32rem) for a message or a short form; `lg`
+ * (56rem) holds a row of six fields or a data grid without folding it;
+ * `xl` (65rem) holds a grid of six count columns with its labels and total.
+ */
+export type DialogSize = (typeof dialogSizes)[number];
+/** `alertdialog` for a dialog that interrupts to warn, such as an idle sign-out. */
+export type DialogRole = 'dialog' | 'alertdialog';
+export type DialogChecks = {
+    size: DialogSize;
+    role: DialogRole | undefined;
+    description: string | undefined;
+    summary: ActionBarSummary | undefined;
+    appearance: DialogAppearance;
+    canvas: ThemeCanvas;
+    sheetBelow: Breakpoint | undefined;
+    sheetGrabber: boolean;
+};
+export declare function assertDialogProps({ appearance, canvas, description, role, sheetBelow, sheetGrabber, size, summary, }: DialogChecks): void;

package/dist/components/dialog/validate.js

@@ -0,0 +1,23 @@
+import { dialogAppearances, } from '../../css/css-dialog-banded.js';
+import { themeCanvases, } from '../../css/css-canvas-grouped.js';
+import { assertActionBarSummary, } from '../action-bar/ActionBarSummary.js';
+export const dialogSizes = ['md', 'lg', 'xl'];
+const dialogRoles = ['dialog', 'alertdialog'];
+function oneOf(values, value, prop) {
+    if (!values.includes(value))
+        throw new RangeError(`Unknown Dialog ${prop}: ${String(value)}`);
+}
+export function assertDialogProps({ appearance, canvas, description, role, sheetBelow, sheetGrabber, size, summary, }) {
+    oneOf(dialogSizes, size, 'size');
+    oneOf(dialogAppearances, appearance, 'appearance');
+    oneOf(themeCanvases, canvas, 'canvas');
+    if (role !== undefined)
+        oneOf(dialogRoles, role, 'role');
+    if (description !== undefined &&
+        (typeof description !== 'string' || !description.trim()))
+        throw new RangeError('Dialog description must not be empty');
+    if (sheetGrabber && !sheetBelow)
+        throw new RangeError('Dialog sheetGrabber needs sheetBelow');
+    if (summary)
+        assertActionBarSummary(summary);
+}

package/dist/components/document-viewer/document-viewer-labels.d.ts

@@ -0,0 +1,23 @@
+/** The viewer's words, all in the consumer's language. */
+export type DocumentViewerLabels = {
+    /** Names the step to the page before, such as "Previous page". */
+    previous: string;
+    /** Names the step to the page after, such as "Next page". */
+    next: string;
+    /** Where the reader is, such as `(page, count) => \`Page ${page} of ${count}\``. */
+    page: (page: number, pageCount: number) => string;
+    /** While the PDF opens, such as "Opening the PDF…". */
+    loading: string;
+    /** When it cannot be shown, such as "This PDF couldn't be shown". */
+    failed: string;
+    /** A line under `failed`, such as what the reader can do instead. */
+    failedDetail?: string;
+};
+/** Fails closed on missing words: the viewer has no words of its own. */
+export declare function assertDocumentViewer({ label, labels, workerSrc, }: {
+    label: string;
+    labels: DocumentViewerLabels;
+    workerSrc: string;
+}): void;
+/** The page shown: the one asked for, kept between 1 and the last page. */
+export declare function shownPage(page: number, pageCount: number): number;

package/dist/components/document-viewer/document-viewer-labels.js

@@ -0,0 +1,23 @@
+function isBlank(text) {
+    return typeof text !== 'string' || text.trim() === '';
+}
+/** Fails closed on missing words: the viewer has no words of its own. */
+export function assertDocumentViewer({ label, labels, workerSrc, }) {
+    if (isBlank(label))
+        throw new RangeError('DocumentViewer label must be non-empty text');
+    if (isBlank(workerSrc))
+        throw new RangeError('DocumentViewer workerSrc must be a URL');
+    for (const key of ['previous', 'next', 'loading', 'failed'])
+        if (isBlank(labels?.[key]))
+            throw new RangeError(`DocumentViewer labels.${key} must be non-empty text`);
+    if (typeof labels.page !== 'function')
+        throw new RangeError('DocumentViewer labels.page must be a function');
+    if (labels.failedDetail !== undefined && isBlank(labels.failedDetail))
+        throw new RangeError('DocumentViewer labels.failedDetail must be non-empty text');
+}
+/** The page shown: the one asked for, kept between 1 and the last page. */
+export function shownPage(page, pageCount) {
+    if (!Number.isInteger(page))
+        return 1;
+    return Math.min(Math.max(page, 1), Math.max(pageCount, 1));
+}

package/dist/components/document-viewer/page-box.d.ts

@@ -0,0 +1,8 @@
+import { type CSSProperties } from 'react';
+/** A US Letter page's height over its width, the box's shape until known. */
+export declare const letterAspect: number;
+/**
+ * The page box's size, read by the generated `sw-document-viewer-page`
+ * rule: its width in CSS pixels and its height over its width.
+ */
+export declare function pageBoxStyle(width: number, aspect: number | null): CSSProperties;

package/dist/components/document-viewer/page-box.js

@@ -0,0 +1,12 @@
+/** A US Letter page's height over its width, the box's shape until known. */
+export const letterAspect = 11 / 8.5;
+/**
+ * The page box's size, read by the generated `sw-document-viewer-page`
+ * rule: its width in CSS pixels and its height over its width.
+ */
+export function pageBoxStyle(width, aspect) {
+    return {
+        '--sw-document-page-width': `${Math.max(0, Math.round(width))}px`,
+        '--sw-document-page-aspect': String(aspect ?? letterAspect),
+    };
+}

package/dist/components/document-viewer/pdf-document.d.ts

@@ -0,0 +1,32 @@
+import { type PdfPageSize } from './render-pdf-page.js';
+export type { PdfPageSize };
+/** An open PDF, as DocumentViewer uses it. */
+export type PdfDocument = {
+    pageCount: number;
+    /**
+     * Draws page `page` (from 1) `width` CSS pixels wide into `canvas`, and
+     * its text into `text` (transparent, for reading and selecting), and
+     * resolves with its size. `signal` cancels it.
+     */
+    renderPage: (options: {
+        page: number;
+        width: number;
+        canvas: HTMLCanvasElement;
+        text: HTMLElement;
+        signal: AbortSignal;
+    }) => Promise<PdfPageSize>;
+    /** The aspect (height over width) of page `page`, without drawing it. */
+    pageAspect: (page: number) => Promise<number>;
+    destroy: () => Promise<void>;
+};
+/** Whether an error is PDF.js reporting a cancelled render or text layer. */
+export declare function isCancelled(error: unknown): boolean;
+/**
+ * Opens a PDF from its bytes with PDF.js's legacy build (the modern one
+ * needs browsers newer than the ones stores run, such as for
+ * `Map.prototype.getOrInsertComputed`), loaded on first use (so a page
+ * without a viewer never downloads it), in a module worker started from
+ * `workerSrc` and ended with the document. Rejects when the bytes are not
+ * a PDF PDF.js can open.
+ */
+export declare function openPdf(data: ArrayBuffer | Uint8Array, workerSrc: string): Promise<PdfDocument>;

package/dist/components/document-viewer/pdf-document.js

@@ -0,0 +1,66 @@
+import { copyPdfBytes, hardenedPdfOptions } from './pdf-options.js';
+import { renderPdfPage } from './render-pdf-page.js';
+/** Whether an error is PDF.js reporting a cancelled render or text layer. */
+export function isCancelled(error) {
+    return (error instanceof Error &&
+        (error.name === 'RenderingCancelledException' ||
+            error.name === 'AbortException'));
+}
+/**
+ * Opens a PDF from its bytes with PDF.js's legacy build (the modern one
+ * needs browsers newer than the ones stores run, such as for
+ * `Map.prototype.getOrInsertComputed`), loaded on first use (so a page
+ * without a viewer never downloads it), in a module worker started from
+ * `workerSrc` and ended with the document. Rejects when the bytes are not
+ * a PDF PDF.js can open.
+ */
+export async function openPdf(data, workerSrc) {
+    const pdfjs = await import('pdfjs-dist/legacy/build/pdf.mjs');
+    const port = new Worker(workerSrc, { type: 'module' });
+    const worker = pdfjs.PDFWorker.create({
+        port,
+        verbosity: hardenedPdfOptions.verbosity,
+    });
+    const task = pdfjs.getDocument({
+        ...hardenedPdfOptions,
+        data: copyPdfBytes(data),
+        worker,
+    });
+    // The worker always ends, even when PDF.js fails to close the document.
+    async function destroy() {
+        try {
+            await task.destroy();
+        }
+        finally {
+            worker.destroy();
+            port.terminate();
+        }
+    }
+    let document;
+    try {
+        document = await task.promise;
+    }
+    catch (error) {
+        // The open error is the one reported, never a failure to close.
+        await destroy().catch(() => undefined);
+        throw error;
+    }
+    const loaded = document;
+    return {
+        pageCount: loaded.numPages,
+        destroy,
+        async pageAspect(page) {
+            const { width, height } = (await loaded.getPage(page)).getViewport({
+                scale: 1,
+            });
+            return height / width;
+        },
+        async renderPage({ page, ...target }) {
+            return renderPdfPage({
+                page: await loaded.getPage(page),
+                ...target,
+                createTextLayer: (options) => new pdfjs.TextLayer(options),
+            });
+        },
+    };
+}

package/dist/components/document-viewer/pdf-options.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The options every document opens with: nothing is fetched beyond the
+ * bytes given, no font, character map, colour profile or WebAssembly file
+ * (PDF.js falls back to system fonts and skips what it cannot decode), no
+ * XFA forms, no streaming or range requests, and no code evaluation.
+ *
+ * `isEvalSupported` is absent from PDF.js 6.4.299, whose bundles hold no
+ * `eval` or `new Function`; it stays here, set to `false`, so the
+ * hardening reads the same as the Teisoro API's and survives a downgrade.
+ */
+export declare const hardenedPdfOptions: {
+    readonly isEvalSupported: false;
+    readonly useWorkerFetch: false;
+    readonly useWasm: false;
+    readonly useSystemFonts: true;
+    readonly disableFontFace: false;
+    readonly enableXfa: false;
+    readonly disableRange: true;
+    readonly disableStream: true;
+    readonly disableAutoFetch: true;
+    readonly stopAtErrors: false;
+    readonly verbosity: 0;
+};
+/** The largest canvas drawn, in device pixels: within every browser's limit. */
+export declare const maxCanvasPixels = 16000000;
+/**
+ * The device-pixel ratio a page of `width` by `height` CSS pixels is drawn
+ * at: the screen's, lowered so the canvas stays under `maxCanvasPixels`.
+ */
+export declare function canvasRatio(width: number, height: number, deviceRatio: number): number;
+/**
+ * A private copy of the bytes: PDF.js hands its data to the worker, which
+ * detaches the buffer, so the consumer's own bytes (kept for a download)
+ * are never touched.
+ */
+export declare function copyPdfBytes(data: ArrayBuffer | Uint8Array): Uint8Array;

package/dist/components/document-viewer/pdf-options.js

@@ -0,0 +1,46 @@
+/**
+ * The options every document opens with: nothing is fetched beyond the
+ * bytes given, no font, character map, colour profile or WebAssembly file
+ * (PDF.js falls back to system fonts and skips what it cannot decode), no
+ * XFA forms, no streaming or range requests, and no code evaluation.
+ *
+ * `isEvalSupported` is absent from PDF.js 6.4.299, whose bundles hold no
+ * `eval` or `new Function`; it stays here, set to `false`, so the
+ * hardening reads the same as the Teisoro API's and survives a downgrade.
+ */
+export const hardenedPdfOptions = {
+    isEvalSupported: false,
+    useWorkerFetch: false,
+    useWasm: false,
+    useSystemFonts: true,
+    disableFontFace: false,
+    enableXfa: false,
+    disableRange: true,
+    disableStream: true,
+    disableAutoFetch: true,
+    stopAtErrors: false,
+    verbosity: 0,
+};
+/** The largest canvas drawn, in device pixels: within every browser's limit. */
+export const maxCanvasPixels = 16_000_000;
+/**
+ * The device-pixel ratio a page of `width` by `height` CSS pixels is drawn
+ * at: the screen's, lowered so the canvas stays under `maxCanvasPixels`.
+ */
+export function canvasRatio(width, height, deviceRatio) {
+    const ratio = deviceRatio > 0 ? deviceRatio : 1;
+    const area = width * height * ratio * ratio;
+    if (area <= maxCanvasPixels)
+        return ratio;
+    return Math.sqrt(maxCanvasPixels / (width * height));
+}
+/**
+ * A private copy of the bytes: PDF.js hands its data to the worker, which
+ * detaches the buffer, so the consumer's own bytes (kept for a download)
+ * are never touched.
+ */
+export function copyPdfBytes(data) {
+    return data instanceof Uint8Array
+        ? data.slice()
+        : new Uint8Array(data.slice(0));
+}

package/dist/components/document-viewer/render-pdf-page.d.ts

@@ -0,0 +1,20 @@
+import { type PDFPageProxy, type TextLayer } from 'pdfjs-dist';
+/** A page drawn: its CSS size at the width asked for. */
+export type PdfPageSize = {
+    width: number;
+    height: number;
+};
+/**
+ * Draws one page `width` CSS pixels wide into `canvas`, at the screen's
+ * pixel ratio (capped), and its text into `text` (PDF.js's transparent
+ * text layer, at the scale the generated rules read). `signal` cancels
+ * both.
+ */
+export declare function renderPdfPage({ page, width, canvas, text, signal, createTextLayer, }: {
+    page: PDFPageProxy;
+    width: number;
+    canvas: HTMLCanvasElement;
+    text: HTMLElement;
+    signal: AbortSignal;
+    createTextLayer: (options: ConstructorParameters<typeof TextLayer>[0]) => TextLayer;
+}): Promise<PdfPageSize>;

package/dist/components/document-viewer/render-pdf-page.js

@@ -0,0 +1,38 @@
+import { canvasRatio } from './pdf-options.js';
+/**
+ * Draws one page `width` CSS pixels wide into `canvas`, at the screen's
+ * pixel ratio (capped), and its text into `text` (PDF.js's transparent
+ * text layer, at the scale the generated rules read). `signal` cancels
+ * both.
+ */
+export async function renderPdfPage({ page, width, canvas, text, signal, createTextLayer, }) {
+    const base = page.getViewport({ scale: 1 });
+    const viewport = page.getViewport({ scale: width / base.width });
+    const ratio = canvasRatio(viewport.width, viewport.height, window.devicePixelRatio);
+    canvas.width = Math.floor(viewport.width * ratio);
+    canvas.height = Math.floor(viewport.height * ratio);
+    const render = page.render({
+        canvas,
+        viewport,
+        transform: ratio === 1 ? undefined : [ratio, 0, 0, ratio, 0, 0],
+    });
+    text.replaceChildren();
+    text.style.setProperty('--total-scale-factor', String(viewport.scale));
+    const layer = createTextLayer({
+        textContentSource: page.streamTextContent(),
+        container: text,
+        viewport,
+    });
+    const cancel = () => {
+        render.cancel();
+        layer.cancel();
+    };
+    signal.addEventListener('abort', cancel, { once: true });
+    try {
+        await Promise.all([render.promise, layer.render()]);
+    }
+    finally {
+        signal.removeEventListener('abort', cancel);
+    }
+    return { width: viewport.width, height: viewport.height };
+}

package/dist/components/document-viewer/scroll-chain.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Scrolls by `amount` pixels along one axis as a finger would: the
+ * element first, then each box around it that scrolls, up to the
+ * document, each taking what it can until the amount is spent.
+ */
+export declare function scrollChainBy(start: Element, axis: 'x' | 'y', amount: number): void;

package/dist/components/document-viewer/scroll-chain.js

@@ -0,0 +1,23 @@
+const scrolling = /^(auto|scroll|overlay)$/;
+function scrolls(element, axis) {
+    if (element === element.ownerDocument.scrollingElement)
+        return true;
+    const style = getComputedStyle(element);
+    return scrolling.test(axis === 'x' ? style.overflowX : style.overflowY);
+}
+/**
+ * Scrolls by `amount` pixels along one axis as a finger would: the
+ * element first, then each box around it that scrolls, up to the
+ * document, each taking what it can until the amount is spent.
+ */
+export function scrollChainBy(start, axis, amount) {
+    let left = amount;
+    for (let element = start; element && Math.abs(left) >= 0.5; element = element.parentElement) {
+        if (!scrolls(element, axis))
+            continue;
+        const key = axis === 'x' ? 'scrollLeft' : 'scrollTop';
+        const was = element[key];
+        element[key] = was + left;
+        left -= element[key] - was;
+    }
+}

package/dist/components/document-viewer/use-error-report.d.ts

@@ -0,0 +1,5 @@
+/**
+ * A stable function that reports an error to the consumer's latest
+ * `onError`, so a new callback each render never restarts a page's draw.
+ */
+export declare function useErrorReport(onError: ((error: unknown) => void) | undefined): (error: unknown) => void;

package/dist/components/document-viewer/use-error-report.js

@@ -0,0 +1,13 @@
+'use client';
+import { useCallback, useEffect, useRef } from 'react';
+/**
+ * A stable function that reports an error to the consumer's latest
+ * `onError`, so a new callback each render never restarts a page's draw.
+ */
+export function useErrorReport(onError) {
+    const latest = useRef(onError);
+    useEffect(() => {
+        latest.current = onError;
+    });
+    return useCallback((error) => latest.current?.(error), []);
+}

package/dist/components/document-viewer/use-page-render.d.ts

@@ -0,0 +1,21 @@
+import { type RefObject } from 'react';
+import { type PdfDocument } from './pdf-document.js';
+export type PageRenderState = 'drawing' | 'drawn' | 'failed';
+/**
+ * Draws the shown page at `width` CSS pixels into the canvas and text
+ * layer, again whenever the page or the width changes, cancelling a draw
+ * that is no longer wanted. The page is visible while it draws, so it
+ * appears as PDF.js paints it. `aspect` is its height over its width, for
+ * the page's box, known before its first draw ends.
+ */
+export declare function usePageRender({ document, page, width, canvas, text, onError, }: {
+    document: PdfDocument | null;
+    page: number;
+    width: number;
+    canvas: RefObject<HTMLCanvasElement | null>;
+    text: RefObject<HTMLDivElement | null>;
+    onError: (error: unknown) => void;
+}): {
+    state: PageRenderState;
+    aspect: number | null;
+};

package/dist/components/document-viewer/use-page-render.js

@@ -0,0 +1,70 @@
+'use client';
+import { useEffect, useState } from 'react';
+import { isCancelled } from './pdf-document.js';
+/**
+ * Draws the shown page at `width` CSS pixels into the canvas and text
+ * layer, again whenever the page or the width changes, cancelling a draw
+ * that is no longer wanted. The page is visible while it draws, so it
+ * appears as PDF.js paints it. `aspect` is its height over its width, for
+ * the page's box, known before its first draw ends.
+ */
+export function usePageRender({ document, page, width, canvas, text, onError, }) {
+    const [outcome, setOutcome] = useState(null);
+    const [shape, setShape] = useState(null);
+    useEffect(() => {
+        if (!document || !canvas.current || !text.current || width <= 0)
+            return;
+        const abort = new AbortController();
+        document
+            .renderPage({
+            page,
+            width,
+            canvas: canvas.current,
+            text: text.current,
+            signal: abort.signal,
+        })
+            .then((size) => {
+            if (abort.signal.aborted)
+                return;
+            setOutcome({
+                document,
+                page,
+                width,
+                state: 'drawn',
+                aspect: size.height / size.width,
+            });
+        }, (error) => {
+            if (abort.signal.aborted || isCancelled(error))
+                return;
+            setOutcome({ document, page, width, state: 'failed', aspect: null });
+            onError(error);
+        });
+        return () => abort.abort();
+    }, [document, page, width, canvas, text, onError]);
+    // The box takes the page's shape as soon as it is known.
+    useEffect(() => {
+        if (!document)
+            return;
+        let live = true;
+        document.pageAspect(page).then((aspect) => {
+            if (live)
+                setShape({ document, page, aspect });
+        }, () => undefined);
+        return () => {
+            live = false;
+        };
+    }, [document, page]);
+    const current = outcome &&
+        outcome.document === document &&
+        outcome.page === page &&
+        outcome.width === width
+        ? outcome
+        : null;
+    const known = shape && shape.document === document && shape.page === page
+        ? shape.aspect
+        : null;
+    return {
+        state: current?.state ?? 'drawing',
+        aspect: known ?? current?.aspect ?? null,
+    };
+}

package/dist/components/document-viewer/use-pdf-document.d.ts

@@ -0,0 +1,22 @@
+import { type PdfDocument } from './pdf-document.js';
+export type PdfDocumentState = {
+    status: 'loading';
+} | {
+    status: 'ready';
+    document: PdfDocument;
+} | {
+    status: 'failed';
+    error: unknown;
+};
+/**
+ * Opens the PDF in `data` and closes it (and its worker) when the bytes
+ * change or the viewer goes away. New bytes start a new open and show as
+ * loading until it settles, so a consumer's Try again is new bytes (or a
+ * new `key`).
+ */
+export declare function usePdfDocument(data: ArrayBuffer | Uint8Array, workerSrc: string, callbacks: {
+    onLoad?: (info: {
+        pageCount: number;
+    }) => void;
+    onError?: (error: unknown) => void;
+}): PdfDocumentState;