@ai-matrx/office 0.8.45 → 0.8.47

package/dist/pdf.d.ts

@@ -0,0 +1,255 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { ComingSoonEntry } from '@ai-matrx/kit/coming-soon';
+
+/**
+ * The page decisions of one workspace session: which pages are turned, left out, or moved. Pure.
+ *
+ * Decisions are PENDING: the viewer and the page grid show them at once, and "Apply" sends them
+ * to the server as the smallest list of page operations (`compilePageOps`). Pages are named by
+ * their ORIGINAL 1-based number everywhere, so a decision survives any later move.
+ */
+type Turn = 0 | 90 | 180 | 270;
+interface PageDecisions {
+    /** Original page numbers in the order the person wants them (deleted pages stay in the list). */
+    order: number[];
+    /** Extra clockwise turn per original page; absent = 0. */
+    turns: Record<number, Turn>;
+    /** Original page numbers left out. */
+    deleted: number[];
+}
+declare function freshDecisions(pageCount: number): PageDecisions;
+declare function turnPages(d: PageDecisions, pages: readonly number[], by: 90 | -90 | 180): PageDecisions;
+declare function deletePages(d: PageDecisions, pages: readonly number[]): PageDecisions;
+declare function restorePages(d: PageDecisions, pages: readonly number[]): PageDecisions;
+/** The new order, as the grid reports it (a list of original page numbers). */
+declare function reorderPages(d: PageDecisions, order: readonly number[]): PageDecisions;
+declare function isDirty(d: PageDecisions): boolean;
+/** The pages that will remain, in their new order. */
+declare function keptOrder(d: PageDecisions): number[];
+type PageOp = {
+    kind: "rotate";
+    pages: number[];
+    rotation: 90 | 180 | 270;
+} | {
+    kind: "delete";
+    pages: number[];
+} | {
+    kind: "reorder";
+    newOrder: number[];
+};
+/**
+ * The server operations that make the document match the decisions, in the order they must run:
+ * turns (original numbering), deletions (original numbering), then one reorder over what remains
+ * (renumbered 1..n). Nothing is emitted for a decision that changes nothing.
+ */
+declare function compilePageOps(d: PageDecisions): PageOp[];
+
+/**
+ * What the PDF workspace needs from the app that mounts it. The package owns the chrome (rail,
+ * panels, top bar, find, undo, shortcuts); the host owns everything that touches a server, a route
+ * or the PDF engine: it injects them as ONE object (`PdfWorkspaceHost`), the same way the Sheets and
+ * Docs hosts inject theirs. Nothing here fails silently: an operation that cannot run REJECTS with a
+ * sentence and the shell shows it; an optional port that is absent hides its control (no dead button).
+ */
+
+/** What the shell hands the injected viewer. */
+interface PdfViewerState {
+    /** 1 = the container's width (the viewer's own zoom unit). */
+    zoom: number;
+    spread: "single" | "two-up";
+    /** Pending turns per page, degrees clockwise (see `PageDecisions`). */
+    rotations: Record<number, number>;
+    /** Changes when the file changed on the server: the viewer must load it again. */
+    reloadKey: number;
+    /** The document parsed with this many pages. */
+    onDocumentLoad(pageCount: number): void;
+    /** A page was measured, in PDF points (crop and fit-page need it). */
+    onPageSize(page: number, widthPt: number, heightPt: number): void;
+}
+type PdfRunRequest = {
+    tool: "apply-pages";
+    ops: PageOp[];
+} | {
+    tool: "extract-pages";
+    pages: number[];
+} | {
+    tool: "split";
+    maxPagesPerPart: number;
+} | {
+    tool: "crop";
+    pages: number[];
+    box: {
+        x0: number;
+        y0: number;
+        x1: number;
+        y1: number;
+    };
+} | {
+    tool: "redact";
+    pattern: string;
+    reason: string;
+} | {
+    tool: "compress";
+    level: 1 | 2 | 3 | 4 | 5;
+} | {
+    tool: "extract-text";
+} | {
+    tool: "extract-tables";
+    pages: number[];
+};
+type PdfRunResult = 
+/** The file itself changed (a new version): the shell reloads the viewer. */
+{
+    kind: "replaced";
+    version?: number;
+}
+/** A new file was made (the original is untouched). */
+ | {
+    kind: "file";
+    fileId: string;
+    name?: string;
+} | {
+    kind: "text";
+    text: string;
+} | {
+    kind: "tables";
+    tables: Array<{
+        page: number;
+        rows: string[][];
+    }>;
+};
+interface PdfWorkspaceHost {
+    file: {
+        id: string;
+        name: string;
+    };
+    /** The injected windowed viewer (`@ai-matrx/media/viewers/pdf`, continuous layout, no toolbar). */
+    renderViewer(state: PdfViewerState): ReactNode;
+    /** One page thumbnail (the left panel). Absent: the panel numbers its pages only. */
+    renderThumbnail?(page: number, widthPx: number): ReactNode;
+    /** Run one tool on the server. Rejects with a sentence on failure. */
+    run(request: PdfRunRequest): Promise<PdfRunResult>;
+    /** Open another page of the app for the same file (Scan, Sign). */
+    openTool(tool: "scan" | "sign"): void;
+    /** Open a file the workspace made. */
+    openFile(fileId: string): void;
+    download(): void;
+    /** Absent: no Share control. */
+    share?(): void;
+    /** Rename the file. Absent: the name is read-only. */
+    rename?(name: string): Promise<void>;
+    /** Print the whole file (`pages` null) or just these. Absent: no Print control. */
+    print?(pages: number[] | null): Promise<void>;
+    /** The layers (optional content) of the document. Absent: the Layers tab announces it is not built. */
+    layers?: {
+        list(): Promise<Array<{
+            id: string;
+            name: string;
+            visible: boolean;
+        }>>;
+        set(id: string, visible: boolean): Promise<void>;
+    };
+    /** The server's redaction pattern catalog (ids are the server's contract). Absent: a free pattern field. */
+    redactPatterns?(): Promise<Array<{
+        id: string;
+        label: string;
+    }>>;
+    /** False while the device is offline: the save pill says so and edits are not queued. */
+    online?: boolean;
+    /** Show a failure to the person (the host's toast). Defaults to an inline banner. */
+    notify?(message: string, tone: "error" | "info"): void;
+}
+
+interface PdfWorkspaceProps {
+    host: PdfWorkspaceHost;
+    className?: string;
+}
+declare function PdfWorkspace({ host, className }: PdfWorkspaceProps): react.JSX.Element;
+
+/**
+ * The PDF workspace's tool rail, as data. Pure (no React, no icons): the host registers the
+ * Coming-soon rows from here (`PDF_COMING_SOON`), the shell draws the rail from it, and the tests
+ * check that the two agree.
+ *
+ * A tool is `ready` only where a real capability stands behind it today (`capability` names the
+ * server operation or app route). Anything else is `soon`: the rail shows it plainly marked, and
+ * choosing it announces its registered promise through `@ai-matrx/kit/coming-soon`. There is no
+ * third state, so no dead button.
+ */
+
+type PdfToolId = "browse" | "organize" | "extract-pages" | "split" | "crop" | "redact" | "compress" | "scan" | "sign" | "extract-data" | "edit" | "forms" | "protect" | "ocr" | "convert" | "compare" | "stamp";
+interface PdfToolDef {
+    id: PdfToolId;
+    label: string;
+    /** Single-key shortcut that picks the tool (shown in the tooltip and the shortcut map). */
+    key?: string;
+    status: "ready" | "soon";
+    /** The server operation or route behind a ready tool; the wiring test reads it. */
+    capability?: string;
+    /** What choosing a ready tool does: show its panel, or leave for another page. */
+    opens: "panel" | "page" | "none";
+    group: 0 | 1 | 2;
+    /** One short line under the panel title. */
+    hint?: string;
+}
+declare const PDF_TOOLS: readonly PdfToolDef[];
+declare const pdfTool: (id: string) => PdfToolDef | undefined;
+/** The Coming-soon id of an unbuilt tool. */
+declare const comingSoonIdOf: (id: PdfToolId) => string;
+/** One row per unbuilt tool, ready for `registerComingSoon` or the host's registry table. */
+declare const PDF_COMING_SOON: Record<string, ComingSoonEntry>;
+
+type PdfActionId = "undo" | "redo" | "find" | "print" | "save" | "zoom-in" | "zoom-out" | "zoom-fit-width" | "zoom-fit-page" | "page-next" | "page-prev" | "page-first" | "page-last" | "rotate-right" | "rotate-left" | "delete-pages" | "select-all-pages" | "toggle-pages" | "toggle-properties" | "read-mode" | "two-up" | "shortcuts" | `tool:${string}`;
+interface PdfShortcut {
+    action: PdfActionId;
+    label: string;
+    /** Display keys: "Mod+Z" shows as Cmd+Z on a Mac and Ctrl+Z elsewhere. */
+    keys: string;
+    section: "Edit" | "View" | "Pages" | "Tools";
+}
+declare const PDF_SHORTCUTS: readonly PdfShortcut[];
+interface KeyLike {
+    key: string;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    shiftKey: boolean;
+    altKey: boolean;
+}
+/** The action a key press means, or null. Never matches while `typing` (a text field has the key). */
+declare function matchShortcut(e: KeyLike, typing: boolean): PdfActionId | null;
+/** "Mod+Shift+Z" → "⌘⇧Z" on a Mac, "Ctrl+Shift+Z" elsewhere. */
+declare function formatKeys(keys: string, mac: boolean): string;
+
+/**
+ * The session's one undo/redo stack. Pure and generic: the workspace keeps page decisions and tool
+ * form values in it, each step with the label the menu shows ("Undo Rotate 3 pages"). A new step
+ * clears what was undone; the stack holds at most `limit` steps. Saved versions of the file are the
+ * durable undo: applying changes empties this stack.
+ */
+interface History<T> {
+    past: Array<{
+        label: string;
+        value: T;
+    }>;
+    present: {
+        label: string;
+        value: T;
+    };
+    future: Array<{
+        label: string;
+        value: T;
+    }>;
+}
+declare const HISTORY_LIMIT = 100;
+declare function startHistory<T>(value: T): History<T>;
+declare function pushStep<T>(h: History<T>, label: string, value: T, limit?: number): History<T>;
+declare function undo<T>(h: History<T>): History<T>;
+declare function redo<T>(h: History<T>): History<T>;
+declare const canUndo: (h: History<unknown>) => boolean;
+declare const canRedo: (h: History<unknown>) => boolean;
+/** The label of the step Undo would take back. */
+declare const undoLabel: (h: History<unknown>) => string;
+declare const redoLabel: (h: History<unknown>) => string;
+
+export { HISTORY_LIMIT, type History, type KeyLike, PDF_COMING_SOON, PDF_SHORTCUTS, PDF_TOOLS, type PageDecisions, type PageOp, type PdfActionId, type PdfRunRequest, type PdfRunResult, type PdfShortcut, type PdfToolDef, type PdfToolId, type PdfViewerState, PdfWorkspace, type PdfWorkspaceHost, type PdfWorkspaceProps, type Turn, canRedo, canUndo, comingSoonIdOf, compilePageOps, deletePages, formatKeys, freshDecisions, isDirty, keptOrder, matchShortcut, pdfTool, pushStep, redo, redoLabel, reorderPages, restorePages, startHistory, turnPages, undo, undoLabel };