viewdoc 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,316 @@
+import * as react from 'react';
+import { ReactNode, CSSProperties } from 'react';
+
+type DocViewerFileType = 'image' | 'pdf' | 'docx' | 'xlsx';
+/**
+ * Extracts the file extension from a URL's pathname (ignoring query strings/fragments,
+ * which matters for presigned URLs like S3's that carry dots in their query params).
+ */
+declare function getUrlExtension(uri: string): string | null;
+/** Maps a URL (or explicit extension/mime hint) to the viewer type DocViewer should render. */
+declare function detectFileType(uri: string, hint?: string): DocViewerFileType | null;
+
+interface ViewerTheme {
+    /** Background color of the viewer canvas area. */
+    background?: string;
+    /** Background color of the toolbar strip. */
+    toolbarBackground?: string;
+    /** Border color under the toolbar. */
+    toolbarBorderColor?: string;
+    /** Hover background for toolbar buttons. */
+    toolbarButtonHoverBackground?: string;
+    /** Text/icon color used across the toolbar. */
+    textColor?: string;
+    /** Corner radius of the outer viewer container. */
+    borderRadius?: string;
+    /** Corner radius of individual toolbar buttons. */
+    toolbarButtonRadius?: string;
+}
+
+interface Position {
+    x: number;
+    y: number;
+}
+interface UseDraggableOptions {
+    defaultPosition?: Position;
+    /** Allow dragging via the returned handle props. Default: true. */
+    draggable?: boolean;
+}
+interface DraggableControls {
+    position: Position;
+    onDragHandlePointerDown: (e: React.PointerEvent) => void;
+}
+declare function useDraggable(options?: UseDraggableOptions): DraggableControls;
+
+interface DocViewerProps {
+    /** URL of the file to display. */
+    uri: string;
+    /** Used as alt text / suggested download filename, and (if no `type` is given) as a fallback source for extension detection. */
+    fileName?: string;
+    /**
+     * Force the viewer type instead of auto-detecting from the URL. Use this when the URL has no
+     * reliable extension (e.g. a presigned URL pointing at an opaque key), or to pass a MIME type
+     * (e.g. 'application/pdf', 'image/png').
+     */
+    type?: DocViewerFileType | string;
+    /** Rendered when the file type can't be detected and no `type` override was given. */
+    fallback?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    /** Width of the viewer. Accepts any CSS size (e.g. 1200, '1200px', '100%'). Default: 1200. */
+    width?: number | string;
+    /** Height of the viewer. Accepts any CSS size (e.g. 700, '700px', '100vh'). Default: 700. */
+    height?: number | string;
+    minScale?: number;
+    maxScale?: number;
+    zoomStep?: number;
+    enableZoomControls?: boolean;
+    enableWheelZoom?: boolean;
+    enableFullscreen?: boolean;
+    enableDownload?: boolean;
+    onDownload?: () => void;
+    theme?: ViewerTheme;
+    /** Render as a floating window (position: fixed) that can be dragged, instead of filling the parent. Default: true. */
+    floating?: boolean;
+    /** When floating, allow dragging the window by its toolbar. Default: true. */
+    windowDraggable?: boolean;
+    /** Initial position when floating. Default: centered in the viewport. */
+    defaultPosition?: Position;
+}
+declare function DocViewer({ uri, fileName, type, fallback, ...rest }: DocViewerProps): react.JSX.Element;
+
+interface ImageViewerProps {
+    /** URL or data URI of the image to display. */
+    uri: string;
+    /** Used as alt text and as the suggested filename on download. */
+    fileName?: string;
+    className?: string;
+    style?: CSSProperties;
+    /** Width of the viewer. Accepts any CSS size (e.g. 1200, '1200px', '100%'). Default: 1200. */
+    width?: number | string;
+    /** Height of the viewer. Accepts any CSS size (e.g. 700, '700px', '100vh'). Default: 700. */
+    height?: number | string;
+    /** Minimum zoom scale. Default: 0.1 */
+    minScale?: number;
+    /** Maximum zoom scale. Default: 8 */
+    maxScale?: number;
+    /** Zoom increment per step (buttons / Ctrl+scroll). Default: 0.25 */
+    zoomStep?: number;
+    /** Show zoom in/out and reset-to-100% controls. Default: true. */
+    enableZoomControls?: boolean;
+    /** Allow Ctrl/Cmd + scroll wheel to zoom. Default: true. */
+    enableWheelZoom?: boolean;
+    /** Allow click-drag-release panning of the image. Default: true. */
+    enablePan?: boolean;
+    /** Show the fullscreen toggle button. Default: true. */
+    enableFullscreen?: boolean;
+    /** Show the download button. Default: true. */
+    enableDownload?: boolean;
+    /** Called when the download button is clicked. If omitted, downloads `uri` directly. */
+    onDownload?: () => void;
+    /** Colors/radii to override the default look (toolbar background, text color, etc). */
+    theme?: ViewerTheme;
+    /** Render as a floating window (position: fixed) that can be dragged, instead of filling the parent. Default: true. */
+    floating?: boolean;
+    /** When floating, allow dragging the window by its toolbar. Default: true. */
+    windowDraggable?: boolean;
+    /** Initial position when floating. Default: centered in the viewport. */
+    defaultPosition?: Position;
+}
+declare function ImageViewer({ uri, fileName, className, style, width, height, minScale, maxScale, zoomStep, enableZoomControls, enableWheelZoom, enablePan, enableFullscreen, enableDownload, onDownload, theme, floating, windowDraggable, defaultPosition, }: ImageViewerProps): react.JSX.Element;
+
+interface PdfViewerProps {
+    /** URL or data URI of the PDF to display. */
+    uri: string;
+    /** Used as the suggested filename on download. */
+    fileName?: string;
+    className?: string;
+    style?: CSSProperties;
+    /** Width of the viewer. Accepts any CSS size (e.g. 1200, '1200px', '100%'). Default: 1200. */
+    width?: number | string;
+    /** Height of the viewer. Accepts any CSS size (e.g. 700, '700px', '100vh'). Default: 700. */
+    height?: number | string;
+    /** Minimum zoom scale. Default: 0.25 */
+    minScale?: number;
+    /** Maximum zoom scale. Default: 5 */
+    maxScale?: number;
+    /** Zoom increment per step (buttons / Ctrl+scroll). Default: 0.25 */
+    zoomStep?: number;
+    /** Canvas render resolution multiplier (crispness at high zoom). Default: 1.5 */
+    renderScale?: number;
+    /** Show zoom in/out and reset-to-100% controls. Default: true. */
+    enableZoomControls?: boolean;
+    /** Allow Ctrl/Cmd + scroll wheel to zoom. Default: true. */
+    enableWheelZoom?: boolean;
+    /** Show the fullscreen toggle button. Default: true. */
+    enableFullscreen?: boolean;
+    /** Show the download button. Default: true. */
+    enableDownload?: boolean;
+    /** Called when the download button is clicked. If omitted, downloads `uri` directly. */
+    onDownload?: () => void;
+    /** Colors/radii to override the default look (toolbar background, text color, etc). */
+    theme?: ViewerTheme;
+    /** Render as a floating window (position: fixed) that can be dragged, instead of filling the parent. Default: true. */
+    floating?: boolean;
+    /** When floating, allow dragging the window by its toolbar. Default: true. */
+    windowDraggable?: boolean;
+    /** Initial position when floating. Default: centered in the viewport. */
+    defaultPosition?: Position;
+}
+declare function PdfViewer({ uri, fileName, className, style, width, height, minScale, maxScale, zoomStep, renderScale, enableZoomControls, enableWheelZoom, enableFullscreen, enableDownload, onDownload, theme, floating, windowDraggable, defaultPosition, }: PdfViewerProps): react.JSX.Element;
+
+interface DocxViewerProps {
+    /** URL of the .docx file to display. */
+    uri: string;
+    /** Used as the suggested filename on download. */
+    fileName?: string;
+    className?: string;
+    style?: CSSProperties;
+    /** Width of the viewer. Accepts any CSS size (e.g. 1200, '1200px', '100%'). Default: 1200. */
+    width?: number | string;
+    /** Height of the viewer. Accepts any CSS size (e.g. 700, '700px', '100vh'). Default: 700. */
+    height?: number | string;
+    /** Minimum zoom scale. Default: 0.5 */
+    minScale?: number;
+    /** Maximum zoom scale. Default: 3 */
+    maxScale?: number;
+    /** Zoom increment per step (buttons / Ctrl+scroll). Default: 0.25 */
+    zoomStep?: number;
+    /** Show zoom in/out and reset-to-100% controls. Default: true. */
+    enableZoomControls?: boolean;
+    /** Allow Ctrl/Cmd + scroll wheel to zoom. Default: true. */
+    enableWheelZoom?: boolean;
+    /** Show the fullscreen toggle button. Default: true. */
+    enableFullscreen?: boolean;
+    /** Show the download button. Default: true. */
+    enableDownload?: boolean;
+    /** Called when the download button is clicked. If omitted, downloads `uri` directly. */
+    onDownload?: () => void;
+    /** Colors/radii to override the default look (toolbar background, text color, etc). */
+    theme?: ViewerTheme;
+    /** Render as a floating window (position: fixed) that can be dragged, instead of filling the parent. Default: true. */
+    floating?: boolean;
+    /** When floating, allow dragging the window by its toolbar. Default: true. */
+    windowDraggable?: boolean;
+    /** Initial position when floating. Default: centered in the viewport. */
+    defaultPosition?: Position;
+}
+declare function DocxViewer({ uri, fileName, className, style, width, height, minScale, maxScale, zoomStep, enableZoomControls, enableWheelZoom, enableFullscreen, enableDownload, onDownload, theme, floating, windowDraggable, defaultPosition, }: DocxViewerProps): react.JSX.Element;
+
+interface XlsxViewerProps {
+    /** URL of the .xlsx/.xls (legacy binary supported)/.csv file to display. */
+    uri: string;
+    /** Used as the suggested filename on download. */
+    fileName?: string;
+    className?: string;
+    style?: CSSProperties;
+    /** Width of the viewer. Accepts any CSS size (e.g. 1200, '1200px', '100%'). Default: 1200. */
+    width?: number | string;
+    /** Height of the viewer. Accepts any CSS size (e.g. 700, '700px', '100vh'). Default: 700. */
+    height?: number | string;
+    /** Minimum zoom scale. Default: 0.5 */
+    minScale?: number;
+    /** Maximum zoom scale. Default: 3 */
+    maxScale?: number;
+    /** Zoom increment per step (buttons / Ctrl+scroll). Default: 0.25 */
+    zoomStep?: number;
+    /** Show zoom in/out and reset-to-100% controls. Default: true. */
+    enableZoomControls?: boolean;
+    /** Allow Ctrl/Cmd + scroll wheel to zoom. Default: true. */
+    enableWheelZoom?: boolean;
+    /** Show the fullscreen toggle button. Default: true. */
+    enableFullscreen?: boolean;
+    /** Show the download button. Default: true. */
+    enableDownload?: boolean;
+    /** Called when the download button is clicked. If omitted, downloads `uri` directly. */
+    onDownload?: () => void;
+    /** Colors/radii to override the default look (toolbar background, text color, etc). */
+    theme?: ViewerTheme;
+    /** Render as a floating window (position: fixed) that can be dragged, instead of filling the parent. Default: true. */
+    floating?: boolean;
+    /** When floating, allow dragging the window by its toolbar. Default: true. */
+    windowDraggable?: boolean;
+    /** Initial position when floating. Default: centered in the viewport. */
+    defaultPosition?: Position;
+}
+declare function XlsxViewer({ uri, fileName, className, style, width, height, minScale, maxScale, zoomStep, enableZoomControls, enableWheelZoom, enableFullscreen, enableDownload, onDownload, theme, floating, windowDraggable, defaultPosition, }: XlsxViewerProps): react.JSX.Element;
+
+interface ZoomPanState {
+    scale: number;
+    translateX: number;
+    translateY: number;
+}
+interface ZoomPanOptions {
+    minScale?: number;
+    maxScale?: number;
+    zoomStep?: number;
+    /** Allow click-drag-release panning by transforming the content. Default: true. */
+    enablePan?: boolean;
+    /** Allow Ctrl/Cmd + scroll wheel zoom. Default: true. */
+    enableWheelZoom?: boolean;
+    /** Allow click-drag-release scrolling of a natively-scrollable container (used instead of enablePan for scrollable content like PDF pages). Default: false. */
+    enableDragScroll?: boolean;
+}
+interface ZoomPanControls extends ZoomPanState {
+    containerRef: React.RefObject<HTMLDivElement>;
+    zoomIn: () => void;
+    zoomOut: () => void;
+    resetZoom: () => void;
+    setScale: (scale: number) => void;
+    handlers: {
+        onWheel: (e: React.WheelEvent) => void;
+        onPointerDown: (e: React.PointerEvent) => void;
+        onPointerMove: (e: React.PointerEvent) => void;
+        onPointerUp: (e: React.PointerEvent) => void;
+    };
+}
+declare function useZoomPan(options?: ZoomPanOptions): ZoomPanControls;
+
+interface ViewerShellProps {
+    zoomPan: ZoomPanControls;
+    onDownload?: () => void;
+    toolbarExtra?: ReactNode;
+    children: ReactNode;
+    /** Show the zoom in/out/reset-to-100% controls. Default: true. */
+    enableZoomControls?: boolean;
+    /** Show the fullscreen toggle button. Default: true. */
+    enableFullscreen?: boolean;
+    /** Allow click-drag-release panning of the content. Default: true. */
+    enablePan?: boolean;
+    /** Colors/radii to override the default look. Any field left out keeps the default. */
+    theme?: ViewerTheme;
+    /** Width of the viewer. Accepts any CSS size (e.g. 1200, '1200px', '100%'). Default: 1200. */
+    width?: number | string;
+    /** Height of the viewer. Accepts any CSS size (e.g. 700, '700px', '100vh'). Default: 700. */
+    height?: number | string;
+    /** Render as a floating window (position: fixed) that can be dragged, instead of filling the parent container. Default: true. */
+    floating?: boolean;
+    /** When floating, allow dragging the window by its toolbar. Default: true. */
+    draggable?: boolean;
+    /** Initial position when floating. Default: centered in the viewport. */
+    defaultPosition?: Position;
+    /** CSS transform-origin for the zoomed content. Default: 'center center'. */
+    transformOrigin?: string;
+}
+declare function ViewerShell({ zoomPan, onDownload, toolbarExtra, children, enableZoomControls, enableFullscreen, enablePan, theme, width, height, floating, draggable, defaultPosition, transformOrigin, }: ViewerShellProps): react.JSX.Element;
+
+interface ToolbarProps {
+    scale: number;
+    onZoomIn: () => void;
+    onZoomOut: () => void;
+    onReset: () => void;
+    onFullscreen?: () => void;
+    onDownload?: () => void;
+    /** Whether the viewer is currently in fullscreen mode (controls which icon is shown). */
+    isFullscreen?: boolean;
+    /** Show zoom in/out/reset controls. Default: true. */
+    showZoomControls?: boolean;
+    /** Icon shown at the start of the toolbar; pointer-down on it starts dragging. */
+    dragHandle?: ReactNode;
+    /** Pointer-down handler attached to the drag handle icon. */
+    onDragHandlePointerDown?: (e: React.PointerEvent) => void;
+    extra?: ReactNode;
+}
+declare function Toolbar({ scale, onZoomIn, onZoomOut, onReset, onFullscreen, onDownload, isFullscreen, showZoomControls, dragHandle, onDragHandlePointerDown, extra, }: ToolbarProps): react.JSX.Element;
+
+export { DocViewer, type DocViewerFileType, type DocViewerProps, DocxViewer, type DocxViewerProps, type DraggableControls, ImageViewer, type ImageViewerProps, PdfViewer, type PdfViewerProps, type Position, Toolbar, type UseDraggableOptions, ViewerShell, type ViewerTheme, XlsxViewer, type XlsxViewerProps, type ZoomPanControls, type ZoomPanOptions, type ZoomPanState, detectFileType, getUrlExtension, useDraggable, useZoomPan };