canvu-react 0.4.67 → 0.4.69

package/dist/raster-image-canvas-CCOmB4NY.d.ts

@@ -0,0 +1,219 @@
+import { V as VectorSceneItem, R as Rect } from './types-fJNwEnHf.js';
+
+/**
+ * Kind of binary selected through the built-in canvu asset ingestion flow.
+ *
+ * Use this to branch your backend upload logic when images and PDFs should be
+ * stored differently.
+ */
+type VectorViewportAssetKind = "image" | "pdf";
+/**
+ * Original browser `File` intercepted from the built-in asset flow.
+ *
+ * This is the high-level hook for apps that want canvu to keep its native file
+ * UX while still uploading the raw binary to their backend or object storage.
+ *
+ * The same request shape is also reused by
+ * {@link ingestAssetFilesToSceneItems}, so custom import flows and the native
+ * viewport UX can share one backend contract.
+ */
+type VectorViewportAssetUploadRequest = {
+    /** Original browser file before canvu converts it into scene items. */
+    file: File;
+    /** High-level bucket for routing image vs PDF upload behavior. */
+    kind: VectorViewportAssetKind;
+};
+/**
+ * Persisted metadata returned by a custom asset upload.
+ *
+ * The returned `pluginData` is shallow-merged into every `VectorSceneItem`
+ * created from the uploaded file, making it available to custom persistence
+ * adapters and later hydration flows.
+ *
+ * @example
+ * ```ts
+ * const assetStore: VectorViewportAssetStore = {
+ *   async upload({ file, kind }) {
+ *     const form = new FormData();
+ *     form.append("file", file);
+ *     form.append("kind", kind);
+ *
+ *     const response = await fetch("/api/canvu/assets", {
+ *       method: "POST",
+ *       body: form,
+ *     });
+ *
+ *     const asset = await response.json();
+ *     return {
+ *       pluginData: {
+ *         assetId: asset.id,
+ *         assetKey: asset.key,
+ *         mimeType: file.type,
+ *       },
+ *     };
+ *   },
+ *   async resolve({ assetIds }) {
+ *     const response = await fetch("/api/canvu/assets/resolve", {
+ *       method: "POST",
+ *       headers: { "content-type": "application/json" },
+ *       body: JSON.stringify({ assetIds }),
+ *     });
+ *
+ *     return response.json();
+ *   },
+ * };
+ * ```
+ */
+type VectorViewportAssetUploadResult = {
+    /**
+     * Opaque persisted metadata attached to created items.
+     *
+     * Use this for asset ids, bucket keys, original file names, or any backend
+     * reference needed to rehydrate the binary later from your own persistence
+     * adapter.
+     */
+    pluginData?: VectorSceneItem["pluginData"];
+};
+/**
+ * Request to resolve persisted asset ids back into runtime URLs.
+ *
+ * This is useful inside custom persistence adapters when you want to rehydrate
+ * signed URLs or CDN URLs after loading a snapshot.
+ */
+type VectorViewportAssetResolveRequest = {
+    assetIds: string[];
+};
+/**
+ * Runtime URL payload returned by a custom asset resolver.
+ */
+type VectorViewportAssetResolveResult = Record<string, {
+    url: string;
+    thumbnailUrl?: string;
+}>;
+type VectorViewportAssetHydrationRequest = {
+    assetId: string;
+    kind: VectorViewportAssetKind;
+    pageNumber?: number;
+    scale?: number;
+};
+/**
+ * High-level hook for apps that want to persist raw binaries out-of-band while
+ * keeping canvu's built-in file UX.
+ *
+ * `upload` is used by the built-in file picker / drag-and-drop flow and by
+ * {@link ingestAssetFilesToSceneItems}. `resolve` is optional for custom
+ * persistence adapters and future hydration flows.
+ */
+type VectorViewportAssetStore = {
+    upload: (request: VectorViewportAssetUploadRequest) => Promise<VectorViewportAssetUploadResult | undefined>;
+    resolve?: (request: VectorViewportAssetResolveRequest) => Promise<VectorViewportAssetResolveResult>;
+    getHydrationRequest?: (item: VectorSceneItem) => VectorViewportAssetHydrationRequest | null;
+};
+
+/**
+ * Input passed to `imageCanvasRendering.resolveSourceSize`.
+ *
+ * Use it when the item's current `imageIntrinsicSize` is only a preview size,
+ * but your backing image service can provide a larger source for zoomed canvas
+ * rendering. Return the effective source size Canvu should cap against before
+ * computing the next bitmap target.
+ */
+type RasterImageCanvasSourceSizeRequest = {
+    item: VectorSceneItem;
+    href: string;
+    intrinsicSize: {
+        width: number;
+        height: number;
+    };
+    contentRect: Rect;
+    viewportSize: {
+        width: number;
+        height: number;
+    };
+    cameraZoom: number;
+    devicePixelRatio: number;
+};
+/**
+ * Maps an image item to the effective source size used for zoom-aware bitmap
+ * sizing.
+ *
+ * Return `null`/`undefined` to use the item's `imageIntrinsicSize`.
+ */
+type RasterImageCanvasSourceSizeResolver = (request: RasterImageCanvasSourceSizeRequest) => {
+    width: number;
+    height: number;
+} | null | undefined;
+/**
+ * Input passed to `imageCanvasRendering.resolveRenderTarget`.
+ *
+ * Use it to map the current image item and zoom-derived bitmap size to the best
+ * available resized URL from your image service. Apps that do not provide a
+ * resolver still get canvas drawing from the original `imageRasterHref`.
+ *
+ * @example
+ * ```ts
+ * const resolveRenderTarget = ({ href, targetSize }) =>
+ *   `${href}&w=${targetSize.width}`;
+ * ```
+ */
+type RasterImageCanvasRenderRequest = {
+    item: VectorSceneItem;
+    href: string;
+    intrinsicSize: {
+        width: number;
+        height: number;
+    };
+    sourceSize: {
+        width: number;
+        height: number;
+    };
+    contentRect: Rect;
+    targetSize: {
+        width: number;
+        height: number;
+    };
+    viewportSize: {
+        width: number;
+        height: number;
+    };
+    cameraZoom: number;
+    devicePixelRatio: number;
+};
+/**
+ * Resolved raster source for a zoom-aware canvas redraw.
+ *
+ * Return a stable `sourceKey` when multiple URLs may represent the same bitmap
+ * quality tier. Canvu uses it to avoid redundant redraws and to keep the
+ * previous canvas visible until a sharper target has decoded.
+ */
+type RasterImageCanvasRenderTarget = {
+    href: string;
+    sourceKey?: string;
+};
+/**
+ * Maps an image item plus requested bitmap size to the URL that should be
+ * decoded into the canvas overlay.
+ *
+ * Return a string for simple URL rewriting, an object when you need a custom
+ * `sourceKey`, or `null`/`undefined` to keep using the item's `imageRasterHref`.
+ */
+type RasterImageCanvasRenderTargetResolver = (request: RasterImageCanvasRenderRequest) => string | RasterImageCanvasRenderTarget | null | undefined;
+/**
+ * Enables zoom-aware canvas rendering for image items in `VectorViewport`.
+ *
+ * This is intended for large raster pages such as PDFs. The original SVG image
+ * remains mounted as a fallback, while Canvu decodes and draws a canvas bitmap
+ * sized for the current zoom. On zoom out, Canvu keeps the sharper bitmap
+ * already drawn instead of downgrading immediately.
+ */
+type RasterImageCanvasRenderingOptions = {
+    resolveSourceSize?: RasterImageCanvasSourceSizeResolver;
+    resolveRenderTarget?: RasterImageCanvasRenderTargetResolver;
+    devicePixelRatio?: number;
+    pixelHeadroom?: number;
+    maxPixelCount?: number;
+    maxDimension?: number;
+    upscaleRedrawRatio?: number;
+};
+
+export type { RasterImageCanvasRenderingOptions as R, VectorViewportAssetKind as V, VectorViewportAssetStore as a, RasterImageCanvasRenderRequest as b, RasterImageCanvasRenderTarget as c, RasterImageCanvasRenderTargetResolver as d, RasterImageCanvasSourceSizeRequest as e, RasterImageCanvasSourceSizeResolver as f, VectorViewportAssetHydrationRequest as g, VectorViewportAssetResolveRequest as h, VectorViewportAssetResolveResult as i, VectorViewportAssetUploadRequest as j, VectorViewportAssetUploadResult as k };

package/dist/raster-image-canvas-nK9kM9UJ.d.cts

@@ -0,0 +1,219 @@
+import { V as VectorSceneItem, R as Rect } from './types-fJNwEnHf.cjs';
+
+/**
+ * Kind of binary selected through the built-in canvu asset ingestion flow.
+ *
+ * Use this to branch your backend upload logic when images and PDFs should be
+ * stored differently.
+ */
+type VectorViewportAssetKind = "image" | "pdf";
+/**
+ * Original browser `File` intercepted from the built-in asset flow.
+ *
+ * This is the high-level hook for apps that want canvu to keep its native file
+ * UX while still uploading the raw binary to their backend or object storage.
+ *
+ * The same request shape is also reused by
+ * {@link ingestAssetFilesToSceneItems}, so custom import flows and the native
+ * viewport UX can share one backend contract.
+ */
+type VectorViewportAssetUploadRequest = {
+    /** Original browser file before canvu converts it into scene items. */
+    file: File;
+    /** High-level bucket for routing image vs PDF upload behavior. */
+    kind: VectorViewportAssetKind;
+};
+/**
+ * Persisted metadata returned by a custom asset upload.
+ *
+ * The returned `pluginData` is shallow-merged into every `VectorSceneItem`
+ * created from the uploaded file, making it available to custom persistence
+ * adapters and later hydration flows.
+ *
+ * @example
+ * ```ts
+ * const assetStore: VectorViewportAssetStore = {
+ *   async upload({ file, kind }) {
+ *     const form = new FormData();
+ *     form.append("file", file);
+ *     form.append("kind", kind);
+ *
+ *     const response = await fetch("/api/canvu/assets", {
+ *       method: "POST",
+ *       body: form,
+ *     });
+ *
+ *     const asset = await response.json();
+ *     return {
+ *       pluginData: {
+ *         assetId: asset.id,
+ *         assetKey: asset.key,
+ *         mimeType: file.type,
+ *       },
+ *     };
+ *   },
+ *   async resolve({ assetIds }) {
+ *     const response = await fetch("/api/canvu/assets/resolve", {
+ *       method: "POST",
+ *       headers: { "content-type": "application/json" },
+ *       body: JSON.stringify({ assetIds }),
+ *     });
+ *
+ *     return response.json();
+ *   },
+ * };
+ * ```
+ */
+type VectorViewportAssetUploadResult = {
+    /**
+     * Opaque persisted metadata attached to created items.
+     *
+     * Use this for asset ids, bucket keys, original file names, or any backend
+     * reference needed to rehydrate the binary later from your own persistence
+     * adapter.
+     */
+    pluginData?: VectorSceneItem["pluginData"];
+};
+/**
+ * Request to resolve persisted asset ids back into runtime URLs.
+ *
+ * This is useful inside custom persistence adapters when you want to rehydrate
+ * signed URLs or CDN URLs after loading a snapshot.
+ */
+type VectorViewportAssetResolveRequest = {
+    assetIds: string[];
+};
+/**
+ * Runtime URL payload returned by a custom asset resolver.
+ */
+type VectorViewportAssetResolveResult = Record<string, {
+    url: string;
+    thumbnailUrl?: string;
+}>;
+type VectorViewportAssetHydrationRequest = {
+    assetId: string;
+    kind: VectorViewportAssetKind;
+    pageNumber?: number;
+    scale?: number;
+};
+/**
+ * High-level hook for apps that want to persist raw binaries out-of-band while
+ * keeping canvu's built-in file UX.
+ *
+ * `upload` is used by the built-in file picker / drag-and-drop flow and by
+ * {@link ingestAssetFilesToSceneItems}. `resolve` is optional for custom
+ * persistence adapters and future hydration flows.
+ */
+type VectorViewportAssetStore = {
+    upload: (request: VectorViewportAssetUploadRequest) => Promise<VectorViewportAssetUploadResult | undefined>;
+    resolve?: (request: VectorViewportAssetResolveRequest) => Promise<VectorViewportAssetResolveResult>;
+    getHydrationRequest?: (item: VectorSceneItem) => VectorViewportAssetHydrationRequest | null;
+};
+
+/**
+ * Input passed to `imageCanvasRendering.resolveSourceSize`.
+ *
+ * Use it when the item's current `imageIntrinsicSize` is only a preview size,
+ * but your backing image service can provide a larger source for zoomed canvas
+ * rendering. Return the effective source size Canvu should cap against before
+ * computing the next bitmap target.
+ */
+type RasterImageCanvasSourceSizeRequest = {
+    item: VectorSceneItem;
+    href: string;
+    intrinsicSize: {
+        width: number;
+        height: number;
+    };
+    contentRect: Rect;
+    viewportSize: {
+        width: number;
+        height: number;
+    };
+    cameraZoom: number;
+    devicePixelRatio: number;
+};
+/**
+ * Maps an image item to the effective source size used for zoom-aware bitmap
+ * sizing.
+ *
+ * Return `null`/`undefined` to use the item's `imageIntrinsicSize`.
+ */
+type RasterImageCanvasSourceSizeResolver = (request: RasterImageCanvasSourceSizeRequest) => {
+    width: number;
+    height: number;
+} | null | undefined;
+/**
+ * Input passed to `imageCanvasRendering.resolveRenderTarget`.
+ *
+ * Use it to map the current image item and zoom-derived bitmap size to the best
+ * available resized URL from your image service. Apps that do not provide a
+ * resolver still get canvas drawing from the original `imageRasterHref`.
+ *
+ * @example
+ * ```ts
+ * const resolveRenderTarget = ({ href, targetSize }) =>
+ *   `${href}&w=${targetSize.width}`;
+ * ```
+ */
+type RasterImageCanvasRenderRequest = {
+    item: VectorSceneItem;
+    href: string;
+    intrinsicSize: {
+        width: number;
+        height: number;
+    };
+    sourceSize: {
+        width: number;
+        height: number;
+    };
+    contentRect: Rect;
+    targetSize: {
+        width: number;
+        height: number;
+    };
+    viewportSize: {
+        width: number;
+        height: number;
+    };
+    cameraZoom: number;
+    devicePixelRatio: number;
+};
+/**
+ * Resolved raster source for a zoom-aware canvas redraw.
+ *
+ * Return a stable `sourceKey` when multiple URLs may represent the same bitmap
+ * quality tier. Canvu uses it to avoid redundant redraws and to keep the
+ * previous canvas visible until a sharper target has decoded.
+ */
+type RasterImageCanvasRenderTarget = {
+    href: string;
+    sourceKey?: string;
+};
+/**
+ * Maps an image item plus requested bitmap size to the URL that should be
+ * decoded into the canvas overlay.
+ *
+ * Return a string for simple URL rewriting, an object when you need a custom
+ * `sourceKey`, or `null`/`undefined` to keep using the item's `imageRasterHref`.
+ */
+type RasterImageCanvasRenderTargetResolver = (request: RasterImageCanvasRenderRequest) => string | RasterImageCanvasRenderTarget | null | undefined;
+/**
+ * Enables zoom-aware canvas rendering for image items in `VectorViewport`.
+ *
+ * This is intended for large raster pages such as PDFs. The original SVG image
+ * remains mounted as a fallback, while Canvu decodes and draws a canvas bitmap
+ * sized for the current zoom. On zoom out, Canvu keeps the sharper bitmap
+ * already drawn instead of downgrading immediately.
+ */
+type RasterImageCanvasRenderingOptions = {
+    resolveSourceSize?: RasterImageCanvasSourceSizeResolver;
+    resolveRenderTarget?: RasterImageCanvasRenderTargetResolver;
+    devicePixelRatio?: number;
+    pixelHeadroom?: number;
+    maxPixelCount?: number;
+    maxDimension?: number;
+    upscaleRedrawRatio?: number;
+};
+
+export type { RasterImageCanvasRenderingOptions as R, VectorViewportAssetKind as V, VectorViewportAssetStore as a, RasterImageCanvasRenderRequest as b, RasterImageCanvasRenderTarget as c, RasterImageCanvasRenderTargetResolver as d, RasterImageCanvasSourceSizeRequest as e, RasterImageCanvasSourceSizeResolver as f, VectorViewportAssetHydrationRequest as g, VectorViewportAssetResolveRequest as h, VectorViewportAssetResolveResult as i, VectorViewportAssetUploadRequest as j, VectorViewportAssetUploadResult as k };