@50arms/ui 0.0.0-stage → 35.1.0

package/dist/types/components/drag-drop/context.d.ts

@@ -0,0 +1,85 @@
+import { type ReactNode } from "react";
+import type { DragAxis, DragId, ContainerId, DragSession, GroupId, PieceId } from "../../lib/dnd";
+import type { ContainerShift } from "./shift";
+export interface DragDropContextValue {
+    session: DragSession;
+    /**
+     * The id of THIS board's instructions paragraph, generated per board.
+     *
+     * Per board, not per page: the engine's `DRAG_INSTRUCTIONS_ID` is a module
+     * constant, so two boards on one page emit the same id twice and every
+     * handle's `aria-describedby` then resolves to whichever the browser saw
+     * first. A duplicate id is valid HTML that no check reads, and the symptom —
+     * one board's handles describing the other's — is invisible to everything
+     * except a screen reader.
+     */
+    instructionsId: string;
+    /**
+     * What the carried card SHOWS — never how, whether, or where it is carried.
+     *
+     * There is exactly one carry mechanism (`DragDrop.tsx#CarriedCard`: a `fixed`
+     * clone portalled to the body) and every item uses it, so this is content and
+     * nothing else. Absent — the ordinary case — the clone renders the carried
+     * item's OWN children, which is the only version of the card that cannot
+     * drift from the row it stands for.
+     *
+     * This used to be a `lifted` boolean counting mounted `<DragDropOverlay>`s,
+     * and it selected a MECHANISM: overlay mounted meant a portalled clone,
+     * absent meant the row transformed itself in flow. Two mechanisms is what
+     * this field no longer is. A board that forgot the overlay got a card that
+     * could not leave its own scroll container, which is a defect a consumer had
+     * no way to know it owed — and the reason the mechanism is not a choice.
+     */
+    renderCarried: ((id: DragId) => ReactNode) | undefined;
+    /** Items and containers publish their spoken names here at mount. */
+    registerLabel: (kind: "item" | "container", id: string, label: string | undefined) => () => void;
+    /**
+     * THE CENSUS — what this board is actually made of, so a board that cannot
+     * work can say so.
+     *
+     * A misconfiguration that produces SILENCE is a library defect, not a
+     * consumer defect, and this surface is full of the shape: a board whose rows
+     * have no drag source renders perfectly, announces itself correctly, passes
+     * every test, and cannot be dragged at all. No error, nothing to see. Same
+     * for a board with no `onDragEnd`, which drags beautifully and drops nothing.
+     *
+     * Parts report themselves here at mount; `DragDrop` reads the tally once the
+     * page has settled and warns in development. See `DragDrop.tsx#useCensus`.
+     */
+    census: DragDropCensus;
+}
+export interface DragDropCensus {
+    /** One row. `container` and `index` are reported so duplicates can be found. */
+    item: (id: string, container: string, index: number) => () => void;
+    /** One thing the sensors can actually attach to — a grip, or a whole surface. */
+    source: (id: string) => () => void;
+}
+export interface DragDropContainerContextValue {
+    id: ContainerId;
+    axis: DragAxis;
+    /** Null when no drag is in flight — nothing moves and no gap is open. */
+    shift: ContainerShift | null;
+}
+export interface DragDropItemContextValue {
+    id: DragId;
+    /** The element the pointer and keyboard sensors attach to. */
+    setHandleRef: (el: HTMLElement | null) => void;
+    /** Spoken name, used to build the handle's accessible name. */
+    label: string | undefined;
+}
+/** DX-5522: the group box an item is drawn in, and (DX-5521) the piece of it. */
+export interface DragDropGroupContextValue {
+    id: GroupId;
+    piece: PieceId;
+}
+export declare const DragDropProvider: import("react").Provider<DragDropContextValue | null>;
+export declare const DragDropContainerProvider: import("react").Provider<DragDropContainerContextValue | null>;
+export declare const DragDropItemProvider: import("react").Provider<DragDropItemContextValue | null>;
+export declare const DragDropGroupProvider: import("react").Provider<DragDropGroupContextValue | null>;
+export declare const DragDropCloneProvider: import("react").Provider<boolean>;
+export declare function useDragDropClone(): boolean;
+/** The group box this item is drawn in, or null for an item drawn on its own — never throws: most items have none. */
+export declare function useDragDropGroup(): DragDropGroupContextValue | null;
+export declare function useDragDrop(component: string): DragDropContextValue;
+export declare function useDragDropContainer(component: string): DragDropContainerContextValue;
+export declare function useDragDropItem(component: string): DragDropItemContextValue;

package/dist/types/components/drag-drop/recipe.d.ts

@@ -0,0 +1,163 @@
+export declare const dnd: import("tailwind-variants").TVReturnType<{
+    axis: {
+        y: {
+            container: string;
+            item: string;
+            groupFrame: string;
+            groupItems: string;
+            marker: string;
+            landing: string;
+            handle: string;
+            surface: string;
+        };
+        x: {
+            container: string;
+            item: string;
+            groupFrame: string;
+            groupItems: string;
+            marker: string;
+            landing: string;
+            handle: string;
+            surface: string;
+        };
+    };
+    moving: {
+        true: {
+            shift: string[];
+            groupFrame: string[];
+        };
+        false: {};
+    };
+    mode: {
+        pointer: {
+            overlay: string;
+        };
+        keyboard: {
+            overlay: string[];
+        };
+    };
+    continuesAfter: {
+        true: {};
+        false: {};
+    };
+}, {
+    root: string;
+    container: string;
+    item: string;
+    shift: string;
+    groupFrame: string;
+    groupItems: string;
+    marker: string[];
+    landing: string;
+    surface: string[];
+    handle: string[];
+    overlay: string[];
+}, undefined, {
+    axis: {
+        y: {
+            container: string;
+            item: string;
+            groupFrame: string;
+            groupItems: string;
+            marker: string;
+            landing: string;
+            handle: string;
+            surface: string;
+        };
+        x: {
+            container: string;
+            item: string;
+            groupFrame: string;
+            groupItems: string;
+            marker: string;
+            landing: string;
+            handle: string;
+            surface: string;
+        };
+    };
+    moving: {
+        true: {
+            shift: string[];
+            groupFrame: string[];
+        };
+        false: {};
+    };
+    mode: {
+        pointer: {
+            overlay: string;
+        };
+        keyboard: {
+            overlay: string[];
+        };
+    };
+    continuesAfter: {
+        true: {};
+        false: {};
+    };
+}, {
+    root: string;
+    container: string;
+    item: string;
+    shift: string;
+    groupFrame: string;
+    groupItems: string;
+    marker: string[];
+    landing: string;
+    surface: string[];
+    handle: string[];
+    overlay: string[];
+}, import("tailwind-variants").TVReturnTypeLike<{
+    axis: {
+        y: {
+            container: string;
+            item: string;
+            groupFrame: string;
+            groupItems: string;
+            marker: string;
+            landing: string;
+            handle: string;
+            surface: string;
+        };
+        x: {
+            container: string;
+            item: string;
+            groupFrame: string;
+            groupItems: string;
+            marker: string;
+            landing: string;
+            handle: string;
+            surface: string;
+        };
+    };
+    moving: {
+        true: {
+            shift: string[];
+            groupFrame: string[];
+        };
+        false: {};
+    };
+    mode: {
+        pointer: {
+            overlay: string;
+        };
+        keyboard: {
+            overlay: string[];
+        };
+    };
+    continuesAfter: {
+        true: {};
+        false: {};
+    };
+}, {
+    root: string;
+    container: string;
+    item: string;
+    shift: string;
+    groupFrame: string;
+    groupItems: string;
+    marker: string[];
+    landing: string;
+    surface: string[];
+    handle: string[];
+    overlay: string[];
+}>>;

package/dist/types/components/drag-drop/shift.d.ts

@@ -0,0 +1,153 @@
+import type { ContainerId, DragAxis, DragState, LayoutSnapshot, PieceId, Point } from "../../lib/dnd";
+/**
+ * DX-5522: where the insertion marker is drawn, which is the part of the picture a group box makes ambiguous. A boundary
+ * between two items at the edge of a group box is the trailing edge of one entry and the leading edge of the next, and a
+ * marker drawn at the DOM position of either would sit inside a box the card does not belong to. So the kind says which
+ * element draws it, and every kind sits where the gap is, never straddling a box edge:
+ *
+ *   item-before / item-after   an item draws it directly before / after itself (inside its group box when it has one);
+ *   group-before / group-after the group box draws it outside its own frame, between two entries of the container: the
+ *                              box's first piece before it, its last piece after it (DX-5521, see `PieceId`);
+ *   group-empty                the carried card is the only card of its group box: the piece it was in draws it there;
+ *   container-empty            the container holds nothing else, so it draws the marker itself.
+ */
+export type MarkerPlacement = {
+    kind: "item-before";
+    restIndex: number;
+} | {
+    kind: "item-after";
+    restIndex: number;
+} | {
+    kind: "group-before";
+    piece: PieceId;
+} | {
+    kind: "group-after";
+    piece: PieceId;
+} | {
+    kind: "group-empty";
+    piece: PieceId;
+} | {
+    kind: "container-empty";
+};
+/** A marker's placement and the displacement it takes (the home slot's closing only: it IS the gap). */
+export interface MarkerSlot {
+    placement: MarkerPlacement;
+    shift: number;
+}
+/**
+ * DX-5522: what a group box does while a card is carried. Its cards move by `itemShift` like any others; the box around
+ * them is the consumer's, and it has to follow them or the cards that slide out of it draw over whatever lies outside.
+ * DX-5521: stated per PIECE of the box (see `PieceId`): a box drawn in one piece is the case it always was.
+ */
+export interface GroupShift {
+    /** How far the piece's near edge and header (everything above its first card) move: the net displacement at its top edge. */
+    headShift: number;
+    /**
+     * How much the piece's far edge moves relative to its near edge: negative when the carried card leaves the piece (it
+     * shrinks by the card's slot), positive when the marker opens a gap inside it (it grows by the gap), zero otherwise.
+     */
+    frameDelta: number;
+}
+export interface ContainerShift {
+    axis: DragAxis;
+    /** Items in this container with the carried one removed. */
+    restCount: number;
+    /**
+     * The carried item's extent along the axis — the size of the hole that opens.
+     * The step neighbours move by is this PLUS the spacing between two items,
+     * because the arriving item brings its own gap with it.
+     */
+    gapSize: number;
+    /** `gapSize` plus the measured spacing: how far one neighbour moves. */
+    step: number;
+    /** Measured spacing between two adjacent items of this container. */
+    spacing: number;
+    /** Insertion index in this container, or null when it is not the target. */
+    markerAt: number | null;
+    /** The marker's placement and displacement, or null when this container draws none. */
+    marker: MarkerSlot | null;
+    /** Displacement along the axis, in px, for the rest item at `restIndex`. */
+    itemShift: (restIndex: number) => number;
+    /** DX-5522 / DX-5521: what each piece of a group box in this container does, by piece id. */
+    pieces: ReadonlyMap<PieceId, GroupShift>;
+}
+/**
+ * Where a pointer-carried card sits on screen, in VIEWPORT coordinates — what
+ * makes the thing under the cursor BE the thing you picked up.
+ *
+ * A VIEWPORT POINT, NOT A DISPLACEMENT, AND THAT IS THE WHOLE FIX. This was an
+ * offset from the card's resting box for exactly as long as the ROW did the
+ * carrying, under an in-flow `translate` on a child of the measured element.
+ * Two things are wrong with carrying a card in flow and neither can be tuned
+ * away:
+ *
+ *   IT CANNOT LEAVE.  A descendant of a scroll container is clipped by it. A
+ *                     card carried past the edge of its own list is cut off at
+ *                     that edge, and the container cannot stop clipping — it is
+ *                     the scroller, and a scrolling axis forces its cross axis
+ *                     to a non-`visible` value (see `recipe.ts`).
+ *   IT INFLATES.      A transformed in-flow element contributes to its
+ *                     ancestor's SCROLLABLE OVERFLOW REGION, so the held row
+ *                     grew the extent of the very container it was inside —
+ *                     measured 512 -> 607px on a straight 90px sideways drag,
+ *                     which is auto-scroll theft and then a runaway.
+ *
+ * Neither is about SIZE, so neither is fixed by shrinking the card: the growth
+ * is the card following the hand, and a held object has to follow the hand on
+ * BOTH axes or it slides out from under the cursor the moment the hand moves
+ * the other way. Measured: dropping the 2% lift scale took a 95.12px overhang
+ * to 90.00px, and 90px was the pointer's own sideways travel. So the card is
+ * carried by a `fixed` clone portalled to the body (`DragDrop.tsx#CarriedCard`)
+ * — out of the flow entirely, where there is no ancestor to clip it and no
+ * extent to inflate.
+ *
+ * `grab` is where inside the box the press landed, so the card tracks the point
+ * that was actually pressed rather than snapping a corner to the cursor.
+ *
+ * Null in keyboard mode: there is no pointer to follow, and a keyboard drag
+ * moves slot to slot with the marker saying where. That is not a fallback — it
+ * is a different question with a different honest answer, and `gapRect` is it.
+ */
+export declare function carriedPoint(state: DragState): Point | null;
+/**
+ * Everything one container needs to render the shift, or null when no drag is
+ * in flight and nothing should move.
+ *
+ * THE HOME SLOT CLOSES WHENEVER A DRAG IS LIVE, with no condition on it, and
+ * that is a consequence of there being ONE carry mechanism rather than a
+ * simplification of two. There used to be a `lifted` argument here, because a
+ * portalled clone and an in-flow `translate` were different answers to "is the
+ * card still in its slot" and a keyboard drag with no clone was a third. Every
+ * drag now lifts the card out into a portalled clone — pointer and keyboard
+ * alike — so the slot is empty every time, and a caller cannot get this wrong
+ * by forgetting to say so.
+ */
+export declare function containerShift(layout: LayoutSnapshot | null, state: DragState, container: ContainerId): ContainerShift | null;
+/** A rect in viewport coordinates. */
+export interface GapRect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
+/**
+ * Where the opened gap sits on screen, for a carried card that has no pointer
+ * to follow.
+ *
+ * Viewport coordinates, taken from the same snapshot the shift is computed
+ * from, so the two cannot disagree about where the hole is. The snapshot is
+ * re-taken whenever the keyboard insertion point moves out of view
+ * (`autoscroll.ts#keepKeyboardTargetVisible`), which is the only thing that
+ * moves these boxes during a keyboard drag.
+ */
+export declare function gapRect(layout: LayoutSnapshot | null, state: DragState): GapRect | null;
+/**
+ * The shift as an inline style.
+ *
+ * `translate` rather than `transform`, so a component can still rotate or scale
+ * the same element without the two having to be composed into one string — the
+ * floating clone does exactly that.
+ */
+export declare function shiftStyle(axis: DragAxis, distance: number): {
+    translate: string;
+};

package/dist/types/components/edit/activation.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The controlled activation pair every pencil-activated field takes, and the
+ * pair `EditGutter` hands out — so wiring a pencil to a field is one spread.
+ *
+ * `editing` says whether the field is open. The field calls
+ * `onEditingChange(false)` when it closes itself (a landed commit, Escape) and
+ * when it declines to open (read-only); it never calls `onEditingChange(true)`
+ * for an opening the caller made. The pair is all-or-nothing: a controlled
+ * `editing` with no way to hand the closed state back would leave the field
+ * shut after its first commit while the caller still believes it is open.
+ */
+export interface EditActivation {
+    editing: boolean;
+    onEditingChange: (editing: boolean) => void;
+}
+/**
+ * Throws when a caller controls `editing` without `onEditingChange`. The
+ * types already forbid it; this covers a caller that got past them (a cast,
+ * a spread of `any`, plain JavaScript). DX-3372 review P0.
+ */
+export declare function assertActivationPair(component: string, editing: boolean | undefined, onEditingChange: ((editing: boolean) => void) | undefined): void;

package/dist/types/components/edit/outcome.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The caller's refusal of a value, with the reason that will be shown.
+ */
+export interface EditRefusal {
+    refusal: string;
+}
+/** What `onCommit` may report. Returning nothing accepts the value. */
+export type EditOutcome = void | EditRefusal;
+/** Every in-place editor's `onCommit`: the new value and the value editing began from. */
+export type EditCommit = (value: string, base: string) => EditOutcome | Promise<EditOutcome>;
+export declare function isRefusal(outcome: EditOutcome): outcome is EditRefusal;
+export declare function isPromise(outcome: EditOutcome | Promise<EditOutcome>): outcome is Promise<EditOutcome>;
+/**
+ * A refusal nobody can read leaves the field open with nothing beside it — the
+ * exact silent failure the outcome contract exists to rule out — so an empty
+ * reason is a programming error, thrown rather than rendered.
+ */
+export declare function assertReadableRefusal(component: string, reason: string, source: "validate" | "onCommit"): void;
+/**
+ * THE MESSAGE IS AN OVERLAY, for the reason `InlineEdit` measured: in normal
+ * flow a refusal grows the control's own wrapper, which inside a fixed-height
+ * row shoves everything beside it. Absolutely positioned, it cannot contribute
+ * height. The parent must be `relative`.
+ */
+export declare function OutcomeMessage({ id, children, className, }: {
+    id?: string;
+    children: string;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/types/components/edit/use-edit-session.d.ts

@@ -0,0 +1,77 @@
+import { type EditCommit, type EditOutcome } from "./outcome";
+export type CommitMode = "wait" | "close";
+export type SaveResult = {
+    outcome: EditOutcome;
+} | {
+    error: unknown;
+};
+export interface EditSessionOptions {
+    /** Named in the thrown message when a refusal carries an empty reason. */
+    component: string;
+    /** The committed value — "unchanged" is measured against it. Read live. */
+    value: string;
+    onCommit: EditCommit;
+    onError?: (error: unknown) => void;
+    failureMessage: string;
+    /** End editing after a commit that landed (or had nothing to write). */
+    close: () => void;
+    /** Put focus back on the field after a refusal or a failure. */
+    refocus: () => void;
+    /** `"close"` closes at once on a promise-returning commit. Default `"wait"`. */
+    commitMode?: CommitMode;
+    /** Open the field again so a late refusal or failure can show. */
+    reopen: () => void;
+}
+/** What the next opening starts from after a late refusal or failure. */
+export interface Restore {
+    text: string;
+    base: string;
+    refusal: string | null;
+    failure: string | null;
+}
+export interface EditSession {
+    pending: boolean;
+    refusal: string | null;
+    failure: string | null;
+    /** The message on screen, if any — a refusal or a failure. */
+    blocked: string | null;
+    /** The value this session began from — `onCommit`'s `base`. */
+    readonly base: string;
+    /**
+     * Start a new session. `refusal` seeds the message slot (live validation).
+     * Returns the text the field starts with: `base`, or the text of a save
+     * that was refused after the field closed.
+     */
+    begin: (base: string, refusal?: string | null, restore?: Restore | null) => string;
+    /**
+     * What a pending reopen restores, or null. Read it before `begin` consumes
+     * it and hand it back to `begin`: a StrictMode remount runs `begin` twice,
+     * and only the first finds it still pending (DXUI-81).
+     */
+    restored: () => Restore | null;
+    /** Finish the current session: every save still out becomes stale. */
+    end: () => void;
+    /** Commit `next` — unchanged check (see the module comment), `validate`, `onCommit`, outcome. */
+    commit: (next: string, validate?: (next: string) => string | null) => void;
+    refuse: (reason: string, source: "validate" | "onCommit") => void;
+    fail: (error: unknown) => void;
+    setPending: (pending: boolean) => void;
+    isPending: () => boolean;
+    setRefusal: (refusal: string | null) => void;
+    clearFailure: () => void;
+    /** The current session's token, for a caller that tracks its own save. */
+    token: () => number;
+    /** Whether a save from any session is still out. */
+    busy: () => boolean;
+    /** The in-flight save, settled or not — chain after it to stay in order. */
+    inFlight: () => Promise<void> | null;
+    /**
+     * Track a save sent under `token`. `onResult` runs only if that session is
+     * still current when it settles; otherwise `onStale` does (after a stale
+     * rejection has reached `onError`).
+     */
+    track: (save: Promise<EditOutcome>, token: number, onResult: (result: SaveResult) => void, onStale?: (result: SaveResult) => void) => void;
+    /** Run `fn` once no save is out — dropped if this session ends first. */
+    whenIdle: (fn: () => void) => void;
+}
+export declare function useEditSession(options: EditSessionOptions): EditSession;

package/dist/types/components/file-viewer/FileViewer.d.ts

@@ -0,0 +1,2 @@
+import type { FileViewerProps } from "./types";
+export declare function FileViewer({ open, onOpenChange, files, initialFileId, initialPageId, onFrameChange, title, subtitle, onDownload, markLabel, headerActions, overlay, renderBody, }: FileViewerProps): import("react").JSX.Element;

package/dist/types/components/file-viewer/PageNumberJumpField.d.ts

@@ -0,0 +1,9 @@
+export interface PageNumberJumpFieldProps {
+    /** Attempts the jump for the typed number; returns whether a match was found.
+        `false` renders `noMatch(typed)` as the inline error. */
+    onJump: (pageNumber: number) => boolean;
+    /** The error line for a page number that did not match, phrased by the caller —
+        one names the document ("No page 999 in report.pdf."), another does not. */
+    noMatch: (typed: string) => string;
+}
+export declare function PageNumberJumpField({ onJump, noMatch }: PageNumberJumpFieldProps): import("react").JSX.Element;

package/dist/types/components/file-viewer/ViewerControls.d.ts

@@ -0,0 +1,20 @@
+import { type ReactNode } from "react";
+import type { ViewerFile, ViewerFrame } from "./types";
+import type { useViewerZoom } from "./use-viewer-zoom";
+export declare function FrameNav({ frame, onGo }: {
+    frame: ViewerFrame;
+    onGo: (next: number) => void;
+}): import("react").JSX.Element;
+export interface ViewerControlsProps {
+    frame: ViewerFrame;
+    frames: ViewerFrame[];
+    go: (index: number) => void;
+    zoom: ReturnType<typeof useViewerZoom>;
+    zoomable: boolean;
+    markLabel: string;
+    headerActions?: (frame: ViewerFrame) => ReactNode;
+    onDownload?: (file: ViewerFile) => void;
+    /** In the overflow popover: the entries say what they are, not just draw it. */
+    labelled?: boolean;
+}
+export declare function ViewerControls({ frame, frames, go, zoom, zoomable, markLabel, headerActions, onDownload, labelled }: ViewerControlsProps): import("react").JSX.Element;

package/dist/types/components/file-viewer/ViewerRail.d.ts

@@ -0,0 +1,10 @@
+import type { ViewerFrame } from "./types";
+export interface ViewerRailProps {
+    frames: ViewerFrame[];
+    index: number;
+    markLabel: string;
+    onSelect: (index: number) => void;
+    /** Collapsed by the header toggle. Stays in the DOM, so a host can re-open it. */
+    hidden: boolean;
+}
+export declare function ViewerRail({ frames, index, markLabel, onSelect, hidden }: ViewerRailProps): import("react").JSX.Element;

package/dist/types/components/file-viewer/ViewerStage.d.ts

@@ -0,0 +1,22 @@
+import { type ReactNode } from "react";
+import type { useViewerZoom, ViewerFit } from "./use-viewer-zoom";
+import type { ViewerFile, ViewerFrame } from "./types";
+export type ViewerZoom = ReturnType<typeof useViewerZoom>;
+/** How a frame is shown. `fit` is null for everything the camera does not move. */
+export interface StageKind {
+    kind: "zoom" | "video" | "file" | "custom";
+    /** How the frame opens; null for everything the camera does not move. */
+    fit: ViewerFit | null;
+}
+export declare function stageKindOf(frame: ViewerFrame, custom: ReactNode): StageKind;
+export interface ViewerStageProps {
+    frame: ViewerFrame;
+    /** What `stageKindOf` said about this frame (the shell already needed it). */
+    kind: StageKind["kind"];
+    /** The host's `renderBody(file)` result for a pageless file. */
+    custom: ReactNode;
+    zoom: ViewerZoom;
+    onDownload?: (file: ViewerFile) => void;
+    overlay: ReactNode;
+}
+export declare function ViewerStage({ frame, kind, custom, zoom, onDownload, overlay }: ViewerStageProps): import("react").JSX.Element;

package/dist/types/components/file-viewer/frames.d.ts

@@ -0,0 +1,28 @@
+import type { UiStrings } from "../../lib/i18n";
+import type { ViewerFile, ViewerFrame } from "./types";
+/** Where the reader is. The ids are the truth; `index` only says where to land
+    when both have vanished (the nearest position). */
+export interface Cursor {
+    fileId: string;
+    pageId: string | null;
+    index: number;
+}
+export declare function framesOf(files: readonly ViewerFile[]): ViewerFrame[];
+export declare function cursorOf(frame: ViewerFrame): Cursor;
+/** A stable identity for the frame on the stage, for keys and change detection. */
+export declare function frameKeyOf(frame: ViewerFrame): string;
+/** The frame the cursor names, else the one nearest its last index. */
+export declare function resolveCursor(frames: readonly ViewerFrame[], cursor: Cursor | null): ViewerFrame | null;
+export interface Start {
+    fileId?: string | null;
+    pageId?: string | null;
+}
+/**
+ * Where a viewer opens: the frame whose page id is `pageId` (inside `fileId`
+ * when given), else the first marked frame (inside `fileId` when given), else
+ * the first frame (of `fileId` when given). An id that matches nothing falls
+ * through to the next rule — a stale deep link opens the document, not nothing.
+ */
+export declare function startFrame(frames: readonly ViewerFrame[], start: Start): ViewerFrame | null;
+/** The frame's name, for a screen reader and for an alt attribute. */
+export declare function frameLabel(frame: ViewerFrame, strings: UiStrings["fileViewer"], fmt: (n: number) => string): string;

package/dist/types/components/file-viewer/index.d.ts

@@ -0,0 +1,3 @@
+export { FileViewer } from "./FileViewer";
+export { PageNumberJumpField, type PageNumberJumpFieldProps } from "./PageNumberJumpField";
+export type { FileViewerProps, ViewerFile, ViewerFrame, ViewerPage } from "./types";