@northslopetech/altitude-ui 2.6.3 → 2.7.0

package/dist/index.d.mts

@@ -346,6 +346,18 @@ declare const Badge: React$1.ForwardRefExoticComponent<BadgeProps & React$1.RefA
  * PDF file input type - can be a URL string or File object.
  */
 type PdfFile = string | File;
+/**
+ * Scroll behavior when navigating to a page.
+ * - 'smooth': Animate scrolling to the target page
+ * - 'instant': Jump immediately to the target page
+ */
+type ScrollBehavior = "smooth" | "instant";
+/**
+ * View mode for PDF display.
+ * - 'continuous': All pages rendered in a scrollable container with virtualization
+ * - 'single': One page at a time with navigation controls
+ */
+type PdfViewMode = "continuous" | "single";
 /**
  * Props for PDF viewer components.
  */
@@ -382,6 +394,35 @@ interface PdfViewerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onE
      * Enable text layer for text selection. Defaults to false for performance.
      */
     enableTextLayer?: boolean;
+    /**
+     * Whether to show the built-in controls bar (navigation buttons, page indicator).
+     */
+    showControls?: boolean;
+    /**
+     * Number of pages to render above and below the viewport for virtualization.
+     * Higher values reduce blank pages during fast scrolling but use more memory.
+     */
+    viewportBuffer?: number;
+    /**
+     * Current page number (1-indexed). Use for controlled mode.
+     * When set, the component expects the parent to manage page state via onPageChange.
+     */
+    page?: number;
+    /**
+     * Callback fired when the current page changes.
+     * Fires when a new page scrolls into the primary viewport or on navigation.
+     */
+    onPageChange?: (page: number) => void;
+    /**
+     * Scroll behavior when navigating to a page via controls or programmatic navigation.
+     */
+    scrollBehavior?: ScrollBehavior;
+    /**
+     * View mode for displaying the PDF.
+     * - 'continuous': Scrollable view with all pages (virtualized)
+     * - 'single': One page at a time with navigation
+     */
+    viewMode?: PdfViewMode;
 }
 
 /**
@@ -415,16 +456,29 @@ declare function initializePdfWorker(workerUrl: string): void;
 
 /**
  * @fileoverview PDF viewer component for Altitude UI.
+ * Uses virtualization for efficient rendering of large PDFs.
  */
 
 /**
  * PDF document viewer component with multi-page support.
  *
+ * Supports both controlled and uncontrolled modes for page state:
+ * - Uncontrolled (default): Component manages page state internally
+ * - Controlled: Parent manages page state via `page` and `onPageChange` props
+ *
  * @example
  * ```tsx
- * // Simple usage
+ * // Simple usage (uncontrolled)
  * <PdfViewer file="/document.pdf" />
  *
+ * // Controlled mode
+ * const [page, setPage] = useState(1);
+ * <PdfViewer
+ *   file="/document.pdf"
+ *   page={page}
+ *   onPageChange={setPage}
+ * />
+ *
  * // With title and callbacks
  * <PdfViewer
  *   file={pdfFile}

package/dist/index.d.ts

@@ -346,6 +346,18 @@ declare const Badge: React$1.ForwardRefExoticComponent<BadgeProps & React$1.RefA
  * PDF file input type - can be a URL string or File object.
  */
 type PdfFile = string | File;
+/**
+ * Scroll behavior when navigating to a page.
+ * - 'smooth': Animate scrolling to the target page
+ * - 'instant': Jump immediately to the target page
+ */
+type ScrollBehavior = "smooth" | "instant";
+/**
+ * View mode for PDF display.
+ * - 'continuous': All pages rendered in a scrollable container with virtualization
+ * - 'single': One page at a time with navigation controls
+ */
+type PdfViewMode = "continuous" | "single";
 /**
  * Props for PDF viewer components.
  */
@@ -382,6 +394,35 @@ interface PdfViewerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onE
      * Enable text layer for text selection. Defaults to false for performance.
      */
     enableTextLayer?: boolean;
+    /**
+     * Whether to show the built-in controls bar (navigation buttons, page indicator).
+     */
+    showControls?: boolean;
+    /**
+     * Number of pages to render above and below the viewport for virtualization.
+     * Higher values reduce blank pages during fast scrolling but use more memory.
+     */
+    viewportBuffer?: number;
+    /**
+     * Current page number (1-indexed). Use for controlled mode.
+     * When set, the component expects the parent to manage page state via onPageChange.
+     */
+    page?: number;
+    /**
+     * Callback fired when the current page changes.
+     * Fires when a new page scrolls into the primary viewport or on navigation.
+     */
+    onPageChange?: (page: number) => void;
+    /**
+     * Scroll behavior when navigating to a page via controls or programmatic navigation.
+     */
+    scrollBehavior?: ScrollBehavior;
+    /**
+     * View mode for displaying the PDF.
+     * - 'continuous': Scrollable view with all pages (virtualized)
+     * - 'single': One page at a time with navigation
+     */
+    viewMode?: PdfViewMode;
 }
 
 /**
@@ -415,16 +456,29 @@ declare function initializePdfWorker(workerUrl: string): void;
 
 /**
  * @fileoverview PDF viewer component for Altitude UI.
+ * Uses virtualization for efficient rendering of large PDFs.
  */
 
 /**
  * PDF document viewer component with multi-page support.
  *
+ * Supports both controlled and uncontrolled modes for page state:
+ * - Uncontrolled (default): Component manages page state internally
+ * - Controlled: Parent manages page state via `page` and `onPageChange` props
+ *
  * @example
  * ```tsx
- * // Simple usage
+ * // Simple usage (uncontrolled)
  * <PdfViewer file="/document.pdf" />
  *
+ * // Controlled mode
+ * const [page, setPage] = useState(1);
+ * <PdfViewer
+ *   file="/document.pdf"
+ *   page={page}
+ *   onPageChange={setPage}
+ * />
+ *
  * // With title and callbacks
  * <PdfViewer
  *   file={pdfFile}