reflex-pdfslick 0.0.1__py3-none-any.whl

reflex_pdfslick/PdfSlickWrapper.tsx

@@ -0,0 +1,268 @@
+/**
+ * PdfSlickWrapper — local React wrapper around `@pdfslick/react`.
+ *
+ * PDFSlick's public surface is the hook `usePDFSlick(url, options)`, not a
+ * drop-in component, and `<PDFSlickThumbnails>` uses a render-prop child that
+ * cannot be expressed from Python. This thin wrapper calls the hook internally,
+ * renders `<PDFSlickViewer>` (and optional thumbnails), subscribes to the
+ * Zustand store via `usePDFSlickStore`, and exposes a clean prop/event API for
+ * the Reflex `PdfSlick` component to bind to.
+ *
+ * It is browser-only (PDF.js), so the Reflex side wraps it as a NoSSRComponent.
+ *
+ * Responsibilities by phase:
+ *  - Phase 1: call the hook, render the viewer, import CSS.
+ *  - Phase 2: subscribe to store slices, forward serializable scalars to Reflex
+ *    events (page, scale, load, error, metadata). Only serializable values
+ *    cross the boundary; Dates become ISO strings, Maps become arrays.
+ *  - Phase 3: apply declarative `command` objects (goto/zoom/rotate/modes/
+ *    print/download) against the imperative `pdfSlick` instance, apply-once.
+ *  - Phase 4: render an optional thumbnails sidebar (vertical or horizontal).
+ */
+import * as React from "react";
+import { GlobalWorkerOptions } from "pdfjs-dist";
+// Vite resolves `?url` to a served/hashed asset URL for the worker file. This
+// uses the SAME hoisted `pdfjs-dist` instance that `@pdfslick/core` imports, so
+// the worker version always matches the PDF.js API version.
+import pdfWorkerUrl from "pdfjs-dist/build/pdf.worker.min.mjs?url";
+import { usePDFSlick, PDFSlickViewer, PDFSlickThumbnails } from "@pdfslick/react";
+import "@pdfslick/react/dist/pdf_viewer.css";
+
+// PDF.js worker fix. `@pdfslick/core` sets
+//   GlobalWorkerOptions.workerSrc = new URL('pdfjs-dist/build/pdf.worker.min.mjs', import.meta.url)
+// at module load, which resolves RELATIVE to the core module directory
+// (.../@pdfslick/core/dist/esm/pdfjs-dist/build/...) — a path that does not
+// exist under Reflex's Vite server, so the worker fails to load ("Setting up
+// fake worker failed"). All ES imports above are evaluated before this module
+// body runs, so core's (broken) assignment has already happened; we override it
+// here with the correctly-resolved worker URL on the same GlobalWorkerOptions.
+if (pdfWorkerUrl) {
+  GlobalWorkerOptions.workerSrc = pdfWorkerUrl as string;
+}
+
+type PdfCommand = {
+  action?: string;
+  page?: number;
+  value?: number | string;
+  mode?: number;
+  degrees?: number;
+};
+
+export type PdfSlickWrapperProps = {
+  url: string;
+  scaleValue?: string;
+  singlePageViewer?: boolean;
+  removePageBorders?: boolean;
+  thumbnailWidth?: number;
+  showThumbnails?: boolean;
+  horizontalThumbnails?: boolean;
+  command?: PdfCommand | null;
+  onDocumentLoad?: (numPages: number) => void;
+  onPageChange?: (page: number) => void;
+  onScaleChange?: (scale: number) => void;
+  onError?: (err: { name: string; message: string }) => void;
+  onMetadata?: (meta: Record<string, unknown>) => void;
+};
+
+/** Convert a possible Date to an ISO string; pass through null/undefined. */
+function toIso(value: unknown): string | null {
+  if (value instanceof Date && !isNaN(value.getTime())) return value.toISOString();
+  if (typeof value === "string" && value) return value;
+  return null;
+}
+
+/** Normalize an unknown error into a serializable {name, message} object. */
+function normalizeError(error: unknown): { name: string; message: string } {
+  if (error && typeof error === "object") {
+    const e = error as { name?: string; message?: string };
+    return { name: e.name ?? "Error", message: e.message ?? String(error) };
+  }
+  return { name: "Error", message: String(error) };
+}
+
+export function PdfSlickWrapper({
+  url,
+  scaleValue = "page-fit",
+  singlePageViewer = false,
+  removePageBorders = false,
+  thumbnailWidth = 212,
+  showThumbnails = false,
+  horizontalThumbnails = false,
+  command = null,
+  onDocumentLoad,
+  onPageChange,
+  onScaleChange,
+  onError,
+  onMetadata,
+}: PdfSlickWrapperProps) {
+  const { viewerRef, thumbsRef, usePDFSlickStore, error } = usePDFSlick(url, {
+    scaleValue,
+    singlePageViewer,
+    removePageBorders,
+    thumbnailWidth,
+  });
+
+  const pageNumber = usePDFSlickStore((s) => s.pageNumber);
+  const numPages = usePDFSlickStore((s) => s.numPages);
+  const scale = usePDFSlickStore((s) => s.scale);
+  const isLoaded = usePDFSlickStore((s) => s.isDocumentLoaded);
+  const pdfSlick = usePDFSlickStore((s) => s.pdfSlick);
+  const store = usePDFSlickStore((s) => s);
+
+  // --- Phase 2: forward store changes to Reflex events --------------------
+  React.useEffect(() => {
+    if (!isLoaded) return;
+    onDocumentLoad?.(numPages);
+    if (onMetadata) {
+      onMetadata({
+        numPages,
+        title: store.title ?? "",
+        author: store.author ?? "",
+        subject: store.subject ?? "",
+        creator: store.creator ?? "",
+        producer: store.producer ?? "",
+        version: store.version ?? "",
+        filename: store.filename ?? "",
+        filesize: store.filesize ?? 0,
+        isLinearized: !!store.isLinearized,
+        creationDate: toIso(store.creationDate),
+        modificationDate: toIso(store.modificationDate),
+      });
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isLoaded, numPages]);
+
+  React.useEffect(() => {
+    onPageChange?.(pageNumber);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [pageNumber]);
+
+  React.useEffect(() => {
+    onScaleChange?.(scale);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [scale]);
+
+  React.useEffect(() => {
+    if (error) onError?.(normalizeError(error));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [error]);
+
+  // --- Phase 3: apply declarative commands once ---------------------------
+  const lastCommandKey = React.useRef<string>("");
+  React.useEffect(() => {
+    if (!command || !command.action || !pdfSlick) return;
+    const key = JSON.stringify(command);
+    if (key === lastCommandKey.current) return;
+    lastCommandKey.current = key;
+
+    const ps = pdfSlick as any;
+    const current = store.pageNumber ?? 1;
+    const total = store.numPages ?? 1;
+    switch (command.action) {
+      case "goto":
+        if (typeof command.page === "number") ps.gotoPage(command.page);
+        break;
+      case "next":
+        ps.gotoPage(Math.min(total, current + 1));
+        break;
+      case "prev":
+        ps.gotoPage(Math.max(1, current - 1));
+        break;
+      case "zoomIn":
+        (ps.viewer ?? ps).increaseScale?.();
+        break;
+      case "zoomOut":
+        (ps.viewer ?? ps).decreaseScale?.();
+        break;
+      case "zoomPreset":
+        if (command.value != null) ps.currentScaleValue = String(command.value);
+        break;
+      case "zoomValue":
+        if (command.value != null) ps.currentScale = Number(command.value);
+        break;
+      case "rotate":
+        if (typeof command.degrees === "number") {
+          const base = store.pagesRotation ?? 0;
+          ps.setRotation(base + command.degrees);
+        }
+        break;
+      case "scrollMode":
+        if (typeof command.mode === "number") ps.setScrollMode(command.mode);
+        break;
+      case "spreadMode":
+        if (typeof command.mode === "number") ps.setSpreadMode(command.mode);
+        break;
+      case "print":
+        ps.triggerPrinting?.();
+        break;
+      case "download":
+        ps.downloadOrSave?.();
+        break;
+      default:
+        break;
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [command, pdfSlick]);
+
+  if (error) {
+    return (
+      <div className="pdfSlick" style={{ padding: "1rem", color: "#b91c1c" }}>
+        Failed to load PDF: {normalizeError(error).message}
+      </div>
+    );
+  }
+
+  const horizontal = showThumbnails && horizontalThumbnails;
+  const thumbsPanel = showThumbnails ? (
+    <div
+      ref={thumbsRef as any}
+      className="pdfSlickThumbs"
+      style={
+        horizontal
+          ? { height: 160, width: "100%", overflowX: "auto", display: "flex", gap: 8, padding: 8 }
+          : { width: 240, height: "100%", overflowY: "auto", padding: 8 }
+      }
+    >
+      <PDFSlickThumbnails {...{ thumbsRef, usePDFSlickStore }}>
+        {({ pageNumber: pn, src, pageLabel, loaded }) => (
+          <div
+            key={pn}
+            onClick={() => pdfSlick?.gotoPage(pn)}
+            style={{
+              cursor: "pointer",
+              padding: 4,
+              outline: pn === pageNumber ? "2px solid #2563eb" : "1px solid #e5e7eb",
+              borderRadius: 4,
+            }}
+          >
+            {loaded && src ? (
+              <img src={src} alt={`Page ${pageLabel ?? pn}`} style={{ display: "block", width: "100%" }} />
+            ) : (
+              <div style={{ height: horizontal ? 120 : 260, width: 160, background: "#e5e7eb" }} />
+            )}
+          </div>
+        )}
+      </PDFSlickThumbnails>
+    </div>
+  ) : null;
+
+  return (
+    <div
+      className="pdfSlick"
+      style={{
+        position: "absolute",
+        inset: 0,
+        display: "flex",
+        flexDirection: horizontal ? "column" : "row",
+      }}
+    >
+      {showThumbnails && !horizontal && thumbsPanel}
+      {showThumbnails && horizontal && thumbsPanel}
+      <div style={{ flex: 1, position: "relative" }}>
+        <PDFSlickViewer {...{ viewerRef, usePDFSlickStore }} />
+      </div>
+    </div>
+  );
+}
+
+export default PdfSlickWrapper;

reflex_pdfslick/__init__.py

@@ -0,0 +1,31 @@
+"""reflex-pdfslick — a native Reflex component wrapping PDFSlick (PDF.js + Zustand).
+
+Public API (stable surface):
+
+    from reflex_pdfslick import pdf_slick, PdfSlick
+    from reflex_pdfslick import ScrollMode, SpreadMode, ScaleValue
+    from reflex_pdfslick import PdfSlickOptions
+    from reflex_pdfslick import commands
+
+``pdf_slick(url=...)`` renders a reactive PDF viewer; viewer state flows into
+Reflex via events (``on_page_change``, ``on_document_load``, ``on_scale_change``,
+``on_error``, ``on_metadata``) and Python drives the viewer through the
+declarative ``command`` prop built with the ``commands`` helpers.
+"""
+
+from . import commands
+from .models import ScaleValue, ScrollMode, SpreadMode
+from .options import PdfSlickOptions
+from .pdfslick import PdfSlick, pdf_slick
+
+__all__ = [
+    "PdfSlick",
+    "pdf_slick",
+    "PdfSlickOptions",
+    "ScaleValue",
+    "ScrollMode",
+    "SpreadMode",
+    "commands",
+]
+
+__version__ = "0.0.1"

reflex_pdfslick/commands.py

@@ -0,0 +1,98 @@
+"""Declarative imperative-control commands for ``PdfSlick``.
+
+PDFSlick's imperative actions live on the ``pdfSlick`` store instance, which
+stays in JS. To drive them from Python we send a small JSON ``command`` object
+into the component's ``command`` prop; the JS wrapper watches it and applies the
+matching action once (apply-then-clear by command identity).
+
+These helpers build those objects so app code never hand-writes the action
+strings. Bind the result to ``PdfSlick(..., command=State.command)`` and set
+``State.command`` from an event handler::
+
+    @rx.event
+    def go_next(self):
+        self.command = commands.next_page()
+
+The action vocabulary mirrors ``specs/api/component-api.md`` §4 and the switch in
+``js/PdfSlickWrapper.tsx``. ``None`` is the idle/cleared value (no-op).
+
+References:
+- ``specs/api/component-api.md`` §4
+- ``specs/technical/architecture.md`` §4.5
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+Command = dict[str, Any]
+
+
+def goto_page(page: int) -> Command:
+    """Jump to a 1-based page number (``pdfSlick.gotoPage(page)``)."""
+    return {"action": "goto", "page": int(page)}
+
+
+def next_page() -> Command:
+    """Go to the next page (clamped to the last page)."""
+    return {"action": "next"}
+
+
+def prev_page() -> Command:
+    """Go to the previous page (clamped to the first page)."""
+    return {"action": "prev"}
+
+
+def zoom_in() -> Command:
+    """Step zoom in (``viewer.increaseScale()``)."""
+    return {"action": "zoomIn"}
+
+
+def zoom_out() -> Command:
+    """Step zoom out (``viewer.decreaseScale()``)."""
+    return {"action": "zoomOut"}
+
+
+def set_zoom_preset(preset: str) -> Command:
+    """Set a named zoom preset (``pdfSlick.currentScaleValue = preset``).
+
+    ``preset`` is one of ``"auto" | "page-actual" | "page-fit" | "page-width"``
+    (see :class:`~reflex_pdfslick.ScaleValue`).
+    """
+    return {"action": "zoomPreset", "value": str(preset)}
+
+
+def set_zoom_value(scale: float) -> Command:
+    """Set an absolute numeric zoom (``pdfSlick.currentScale = scale``)."""
+    return {"action": "zoomValue", "value": float(scale)}
+
+
+def rotate(degrees: int) -> Command:
+    """Rotate pages by a relative delta in degrees (e.g. ``90`` / ``-90``)."""
+    return {"action": "rotate", "degrees": int(degrees)}
+
+
+def set_scroll_mode(mode: int) -> Command:
+    """Set the scroll mode (``pdfSlick.setScrollMode``).
+
+    Accepts a :class:`~reflex_pdfslick.ScrollMode` or a plain int.
+    """
+    return {"action": "scrollMode", "mode": int(mode)}
+
+
+def set_spread_mode(mode: int) -> Command:
+    """Set the spread mode (``pdfSlick.setSpreadMode``).
+
+    Accepts a :class:`~reflex_pdfslick.SpreadMode` or a plain int.
+    """
+    return {"action": "spreadMode", "mode": int(mode)}
+
+
+def print_document() -> Command:
+    """Open the print dialog (``pdfSlick.triggerPrinting()``)."""
+    return {"action": "print"}
+
+
+def download() -> Command:
+    """Download / save the document (``pdfSlick.downloadOrSave()``)."""
+    return {"action": "download"}

reflex_pdfslick/models.py

@@ -0,0 +1,47 @@
+"""Enums and value types mirroring PDFSlick / PDF.js constants.
+
+These mirror the numeric enums re-exported by ``@pdfslick/react`` (originally
+from PDF.js ``ui_utils``) and the accepted ``scaleValue`` strings. Keeping them
+in Python lets the demo app and downstream users avoid magic numbers.
+
+References:
+- ``specs/data-model/store-schema.md``
+- ``specs/api/component-api.md``
+"""
+
+from __future__ import annotations
+
+from enum import Enum, IntEnum
+
+
+class ScrollMode(IntEnum):
+    """PDF.js scroll modes (values match ``pdfjs-dist`` ``ScrollMode``)."""
+
+    VERTICAL = 0
+    HORIZONTAL = 1
+    WRAPPED = 2
+    PAGE = 3
+
+
+class SpreadMode(IntEnum):
+    """PDF.js spread modes (values match ``pdfjs-dist`` ``SpreadMode``)."""
+
+    NONE = 0
+    ODD = 1
+    EVEN = 2
+
+
+class ScaleValue(str, Enum):
+    """Named zoom presets accepted by PDFSlick's ``scaleValue`` option.
+
+    A numeric string (e.g. ``"1.5"``) is also valid and maps to an absolute
+    scale; use it directly as a plain ``str`` where a preset is not enough.
+    """
+
+    AUTO = "auto"
+    PAGE_ACTUAL = "page-actual"
+    PAGE_FIT = "page-fit"
+    PAGE_WIDTH = "page-width"
+
+    def __str__(self) -> str:  # pragma: no cover - convenience
+        return self.value

reflex_pdfslick/options.py

@@ -0,0 +1,41 @@
+"""Typed PDFSlick options object.
+
+Mirrors the ``PDFSlickOptions`` type from ``@pdfslick/core@4.x``. Subclassing
+``rx.PropsBase`` means snake_case Python fields are auto-converted to the
+camelCase keys PDFSlick expects when serialized to a JS object prop.
+
+Only the most commonly used options are surfaced as first-class fields; the full
+upstream option set is documented in ``specs/api/component-api.md``. Unknown or
+advanced keys can still be passed through ``extra``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import reflex as rx
+
+
+class PdfSlickOptions(rx.PropsBase):
+    """Options forwarded to ``usePDFSlick(url, options)``.
+
+    Field names are snake_case in Python and emitted as camelCase to JS, e.g.
+    ``single_page_viewer`` -> ``singlePageViewer``.
+    """
+
+    scale_value: Optional[str] = None  # "auto" | "page-fit" | "page-width" | "page-actual" | numeric
+    single_page_viewer: Optional[bool] = None
+    remove_page_borders: Optional[bool] = None
+    enable_print_auto_rotate: Optional[bool] = None
+    use_only_css_zoom: Optional[bool] = None
+    text_layer_mode: Optional[int] = None
+    annotation_mode: Optional[int] = None
+    annotation_editor_mode: Optional[int] = None
+    thumbnail_width: Optional[int] = None
+    print_resolution: Optional[int] = None
+    max_canvas_pixels: Optional[int] = None
+    filename: Optional[str] = None
+
+    # Escape hatch for advanced/less-common upstream options (e.g.
+    # ``getDocumentParams``). Merged verbatim into the JS options object.
+    extra: dict[str, Any] = {}

reflex_pdfslick/pdfslick.py

@@ -0,0 +1,80 @@
+"""The ``PdfSlick`` Reflex component.
+
+PDFSlick's public entry point is the **hook** ``usePDFSlick(url, options)``, not
+a drop-in component, and its ``<PDFSlickThumbnails>`` uses a render-prop child
+that cannot be expressed from Python. So we ship a small local React wrapper
+(``PdfSlickWrapper.tsx``, beside this module) that calls the hook internally,
+renders
+``<PDFSlickViewer>`` (+ optional thumbnails), subscribes to ``usePDFSlickStore``
+selectors, and exposes a clean prop/event API. See
+``specs/technical/architecture.md`` for the full rationale.
+
+Wiring (Reflex 0.9.x):
+
+- ``library`` points at the local wrapper via ``rx.asset(..., shared=True)``'s
+  ``$/public`` importable path; the npm package is declared in
+  ``lib_dependencies`` so Reflex installs it.
+- PDF.js is browser-only (touches ``window``/``document``/canvas), so the
+  component is a ``rx.NoSSRComponent`` (emits ``next/dynamic(..., {ssr:false})``).
+- The required stylesheet ``@pdfslick/react/dist/pdf_viewer.css`` is imported
+  once via ``add_imports``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import reflex as rx
+
+# Pin the upstream npm package for reproducible builds.
+PDFSLICK_REACT = "@pdfslick/react@4.0.0"
+PDFSLICK_CSS = "@pdfslick/react/dist/pdf_viewer.css"
+# Declared so the wrapper can import the PDF.js worker as a Vite asset and
+# override PDFSlick's broken default ``workerSrc``. The caret range matches
+# ``@pdfslick/core``'s own dependency so the installer resolves a single shared
+# copy — guaranteeing the worker version matches the PDF.js API version.
+PDFJS_DIST = "pdfjs-dist@^6.0.227"
+
+# Resolve the local JS wrapper into a build-time importable module path
+# ("$/public/...") so Reflex bundles our source instead of trying to import a
+# named export from the npm package.
+_WRAPPER_ASSET = rx.asset("PdfSlickWrapper.tsx", shared=True)
+
+
+class PdfSlick(rx.NoSSRComponent):
+    """Reactive PDF viewer wrapping ``@pdfslick/react``."""
+
+    # --- Library wiring -----------------------------------------------------
+    library = _WRAPPER_ASSET.importable_path
+    tag = "PdfSlickWrapper"
+    is_default = True
+    lib_dependencies = [PDFSLICK_REACT, PDFJS_DIST]
+
+    # --- Props (camelCased to JS automatically) -----------------------------
+    url: rx.Var[str]
+    scale_value: rx.Var[str]
+    single_page_viewer: rx.Var[bool]
+    remove_page_borders: rx.Var[bool]
+    thumbnail_width: rx.Var[int]
+    show_thumbnails: rx.Var[bool]
+    horizontal_thumbnails: rx.Var[bool]
+
+    # Declarative imperative-control channel (Phase 3): a command object the
+    # wrapper applies then clears. Built with helpers in ``commands.py``.
+    command: rx.Var[dict[str, Any]]
+
+    # --- Events -------------------------------------------------------------
+    # Each forwards the JS callback's first argument to the Python handler.
+    on_document_load: rx.EventHandler[lambda num_pages: [num_pages]]
+    on_page_change: rx.EventHandler[lambda page: [page]]
+    on_scale_change: rx.EventHandler[lambda scale: [scale]]
+    on_error: rx.EventHandler[lambda err: [err]]
+    on_metadata: rx.EventHandler[lambda meta: [meta]]
+
+    def add_imports(self) -> dict[str, Any]:
+        """Import PDFSlick's required stylesheet exactly once."""
+        return {"": [PDFSLICK_CSS]}
+
+
+# Snake_case factory following Reflex convention.
+pdf_slick = PdfSlick.create

reflex_pdfslick/pdfslick.pyi

@@ -0,0 +1,113 @@
+"""Stub file for custom_components/reflex_pdfslick/pdfslick.py"""
+
+# ------------------- DO NOT EDIT ----------------------
+# This file was generated by `reflex/utils/pyi_generator.py`!
+# ------------------------------------------------------
+from collections.abc import Mapping, Sequence
+from typing import Any, Optional
+from reflex_components_core.core.breakpoints import Breakpoints
+from reflex_base.event import (
+    EventType,
+    PointerEventInfo,
+)
+from reflex_base.vars.base import Var
+import reflex as rx
+
+PDFSLICK_REACT = "@pdfslick/react@4.0.0"
+PDFSLICK_CSS = "@pdfslick/react/dist/pdf_viewer.css"
+PDFJS_DIST = "pdfjs-dist@^6.0.227"
+_WRAPPER_ASSET = rx.asset("PdfSlickWrapper.tsx", shared=True)
+
+class PdfSlick(rx.NoSSRComponent):
+    def add_imports(self) -> dict[str, Any]: ...
+    @classmethod
+    def create(
+        cls,
+        *children,
+        url: Var[str] | str | None = None,
+        scale_value: Var[str] | str | None = None,
+        single_page_viewer: Var[bool] | bool | None = None,
+        remove_page_borders: Var[bool] | bool | None = None,
+        thumbnail_width: Var[int] | int | None = None,
+        show_thumbnails: Var[bool] | bool | None = None,
+        horizontal_thumbnails: Var[bool] | bool | None = None,
+        command: Var[dict[str, Any]] | dict[str, Any] | None = None,
+        style: Sequence[Mapping[str, Any]]
+        | Mapping[str, Any]
+        | Var[Mapping[str, Any]]
+        | Breakpoints
+        | None = None,
+        key: Any | None = None,
+        id: Any | None = None,
+        ref: Var | None = None,
+        class_name: Any | None = None,
+        custom_attrs: dict[str, Any | Var] | None = None,
+        on_blur: Optional[EventType[()]] = None,
+        on_click: Optional[EventType[()] | EventType[PointerEventInfo]] = None,
+        on_context_menu: Optional[EventType[()] | EventType[PointerEventInfo]] = None,
+        on_document_load: Optional[EventType[Any]] = None,
+        on_double_click: Optional[EventType[()] | EventType[PointerEventInfo]] = None,
+        on_error: Optional[EventType[Any]] = None,
+        on_focus: Optional[EventType[()]] = None,
+        on_metadata: Optional[EventType[Any]] = None,
+        on_mount: Optional[EventType[()]] = None,
+        on_mouse_down: Optional[EventType[()]] = None,
+        on_mouse_enter: Optional[EventType[()]] = None,
+        on_mouse_leave: Optional[EventType[()]] = None,
+        on_mouse_move: Optional[EventType[()]] = None,
+        on_mouse_out: Optional[EventType[()]] = None,
+        on_mouse_over: Optional[EventType[()]] = None,
+        on_mouse_up: Optional[EventType[()]] = None,
+        on_page_change: Optional[EventType[Any]] = None,
+        on_scale_change: Optional[EventType[Any]] = None,
+        on_scroll: Optional[EventType[()]] = None,
+        on_scroll_end: Optional[EventType[()]] = None,
+        on_unmount: Optional[EventType[()]] = None,
+        **props,
+    ) -> "PdfSlick":
+        """Create the component.
+
+        Args:
+            *children: The children of the component.
+            url: --- Props (camelCased to JS automatically) -----------------------------
+            scale_value: no description
+            single_page_viewer: no description
+            remove_page_borders: no description
+            thumbnail_width: no description
+            show_thumbnails: no description
+            horizontal_thumbnails: no description
+            command: Declarative imperative-control channel (Phase 3): a command object the wrapper applies then clears. Built with helpers in ``commands.py``.
+            style: The style of the component.
+            key: A unique key for the component.
+            id: The id for the component.
+            ref: The Var to pass as the ref to the component.
+            class_name: The class name for the component.
+            custom_attrs: Attributes passed directly to the component.
+            on_focus: Fired when the element (or some element inside of it) receives focus. For example, it is called when the user clicks on a text input.
+            on_blur: Fired when focus has left the element (or left some element inside of it). For example, it is called when the user clicks outside of a focused text input.
+            on_click: Fired when the user clicks on an element. For example, it's called when the user clicks on a button.
+            on_context_menu: Fired when the user right-clicks on an element.
+            on_double_click: Fired when the user double-clicks on an element.
+            on_mouse_down: Fired when the user presses a mouse button on an element.
+            on_mouse_enter: Fired when the mouse pointer enters the element.
+            on_mouse_leave: Fired when the mouse pointer leaves the element.
+            on_mouse_move: Fired when the mouse pointer moves over the element.
+            on_mouse_out: Fired when the mouse pointer moves out of the element.
+            on_mouse_over: Fired when the mouse pointer moves onto the element.
+            on_mouse_up: Fired when the user releases a mouse button on an element.
+            on_scroll: Fired when the user scrolls the element.
+            on_scroll_end: Fired when scrolling ends on the element.
+            on_mount: Fired when the component is mounted to the page.
+            on_unmount: Fired when the component is removed from the page. Only called during navigation, not on page refresh.
+            on_document_load: --- Events ------------------------------------------------------------- Each forwards the JS callback's first argument to the Python handler.
+            on_page_change: no description
+            on_scale_change: no description
+            on_error: no description
+            on_metadata: no description
+            **props: The props of the component.
+
+        Returns:
+            The component."""
+        ...
+
+pdf_slick = PdfSlick.create

reflex_pdfslick-0.0.1.dist-info/METADATA

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: reflex-pdfslick
+Version: 0.0.1
+Summary: A native Reflex component wrapping PDFSlick (PDF.js + Zustand) to view and interact with PDF documents in pure Python.
+Author-email: Ernesto Crespo <ecrespo@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/ecrespo/reflex-pdfslick
+Project-URL: Repository, https://github.com/ecrespo/reflex-pdfslick
+Project-URL: Issues, https://github.com/ecrespo/reflex-pdfslick/issues
+Project-URL: Documentation, https://github.com/ecrespo/reflex-pdfslick#readme
+Project-URL: Changelog, https://github.com/ecrespo/reflex-pdfslick/releases
+Project-URL: PyPI, https://pypi.org/project/reflex-pdfslick/
+Project-URL: PDFSlick, https://pdfslick.dev/
+Keywords: reflex,reflex-custom-components,pdf,pdfslick,pdfjs,pdf-viewer,component,viewer,thumbnails
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: reflex>=0.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# reflex-pdfslick
+
+[![PyPI version](https://img.shields.io/pypi/v/reflex-pdfslick.svg)](https://pypi.org/project/reflex-pdfslick/)
+[![Python versions](https://img.shields.io/pypi/pyversions/reflex-pdfslick.svg)](https://pypi.org/project/reflex-pdfslick/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/ecrespo/reflex-pdfslick/blob/main/LICENSE)
+[![GitHub](https://img.shields.io/badge/GitHub-ecrespo%2Freflex--pdfslick-181717?logo=github)](https://github.com/ecrespo/reflex-pdfslick)
+
+- **Source:** https://github.com/ecrespo/reflex-pdfslick
+- **Issues:** https://github.com/ecrespo/reflex-pdfslick/issues
+- **PDFSlick (upstream):** https://github.com/pdfslick/pdfslick — https://pdfslick.dev
+
+A native [Reflex](https://reflex.dev/) component that wraps
+[**PDFSlick**](https://pdfslick.dev/) so you can view and interact with PDF
+documents in **pure Python** — no HTML, no `iframe`, no hand-written
+JavaScript.
+
+PDFSlick is built on top of Mozilla's [PDF.js](https://github.com/mozilla/pdf.js)
+and uses [Zustand](https://github.com/pmndrs/zustand) to expose a reactive store
+for the loaded document. `reflex-pdfslick` bridges that store and PDFSlick's
+imperative API into Reflex's declarative, state-driven model: document state
+(page number, page count, zoom, rotation, metadata, thumbnails) flows back to
+Python as events, and Python triggers actions (go to page, zoom, rotate, print,
+download) on the viewer.
+
+> **Project status — `ALPHA` / implemented, pre-release.**
+> The component runtime, imperative controls, and the full 7-example demo
+> gallery are built and covered by tests; the demo compiles to a Reflex
+> production build in CI. The remaining step is the PyPI/GitHub release. See
+> [Roadmap](#roadmap) for details.
+
+```python
+import reflex as rx
+from reflex_pdfslick import pdf_slick
+
+
+class State(rx.State):
+    page_number: int = 1
+    num_pages: int = 0
+
+    @rx.event
+    def on_page_change(self, page: int):
+        self.page_number = page
+
+    @rx.event
+    def on_document_load(self, num_pages: int):
+        self.num_pages = num_pages
+
+
+def index() -> rx.Component:
+    return pdf_slick(
+        url="/sample.pdf",
+        scale_value="page-fit",
+        single_page_viewer=True,
+        on_page_change=State.on_page_change,
+        on_document_load=State.on_document_load,
+        height="700px",
+    )
+
+
+app = rx.App()
+app.add_page(index)
+```
+
+## Why a native component instead of an `iframe`?
+
+Embedding a PDF viewer through an `iframe` or a raw `<embed>` works, but it is
+isolated from your app: you cannot react to page changes, drive the zoom from a
+Python toolbar, or read the document's metadata into your state. Wrapping
+PDFSlick as a first-class Reflex component means:
+
+- **Reactive state** — `page_number`, `num_pages`, `scale`, `rotation`,
+  `is_document_loaded` and document metadata are pushed into Reflex state via
+  typed events.
+- **Imperative control from Python** — go to page, zoom in/out, fit width/page,
+  rotate, switch scroll/spread modes, print and download are exposed as
+  component-level controls.
+- **Reusable & versioned** — installable with `pip`, with the npm dependency
+  (`@pdfslick/react`) pinned for reproducible builds.
+- **SSR-safe** — PDF.js is browser-only, so the component is wrapped as a
+  Reflex `NoSSRComponent` and only ever renders on the client.
+
+## Installation
+
+```shell
+pip install reflex-pdfslick
+# or, from source
+git clone https://github.com/ecrespo/reflex-pdfslick.git
+cd reflex-pdfslick
+pip install -e .
+```
+
+Reflex installs the underlying npm packages automatically on first run. The
+component pins `@pdfslick/react` and `pdfjs-dist` (which pull in
+`@pdfslick/core` and `zustand`) and imports the required stylesheet
+`@pdfslick/react/dist/pdf_viewer.css` for you.
+
+## Custom-component packaging (build & publish)
+
+This repository is a standard [Reflex custom
+component](https://reflex.dev/docs/custom-components/overview/): the package
+lives in `custom_components/reflex_pdfslick/` (shipping the `PdfSlickWrapper.tsx`
+wrapper and a generated `pdfslick.pyi` stub), the demo app in `pdfslick_demo/`,
+and `pyproject.toml` carries the `reflex-custom-components` keyword used by the
+Reflex component gallery to discover it on PyPI.
+
+```shell
+# Build the wheel + sdist into dist/ (also regenerates the .pyi type stubs).
+# PYTHONPATH=. lets the stub generator import custom_components/.
+PYTHONPATH=. uv run reflex component build
+
+# Inspect, then publish to PyPI (bump the version in pyproject.toml first):
+uv run twine upload dist/*        # or: uv publish
+
+# Share on the Reflex community gallery:
+uv run reflex component share
+```
+
+The built wheel includes the React wrapper (`reflex_pdfslick/PdfSlickWrapper.tsx`)
+and the type stub, so `rx.asset(...)` resolves the wrapper when the package is
+installed from PyPI — not only in editable mode.
+
+## Planned API (summary)
+
+The full contract lives in [specs/api/component-api.md](specs/api/component-api.md).
+
+| Prop | Type | Description |
+|---|---|---|
+| `url` | `str` | Path/URL of the PDF to load. |
+| `scale_value` | `str` | `"auto"`, `"page-fit"`, `"page-width"`, `"page-actual"` or a numeric string. |
+| `single_page_viewer` | `bool` | Render a single page at a time. |
+| `thumbnail_width` | `int` | Width (px) of generated thumbnails. |
+| `remove_page_borders` | `bool` | Hide page borders. |
+
+| Event | Payload | Fired when |
+|---|---|---|
+| `on_document_load` | `int` (num pages) | The document finishes loading. |
+| `on_page_change` | `int` (page) | The current page changes. |
+| `on_scale_change` | `float` (scale) | The zoom level changes. |
+| `on_error` | `dict` | Loading/parsing fails. |
+
+Imperative controls (next/previous page, zoom, rotate, print, download) are
+driven from Python state — see the API spec for the dispatch mechanism.
+
+## Examples (demo gallery)
+
+The `pdfslick_demo/` Reflex app mirrors PDFSlick's own example set. Each example
+is documented in the [PRD](specs/prd/pdfslick-component.md) and
+[task breakdown](specs/tasks/task-breakdown.md):
+
+1. **Simple Viewer** — basic viewer with prev/next navigation and zoom.
+2. **Full Viewer App** — toolbar, zoom selector, rotation, scroll/spread modes,
+   document info, search and thumbnails sidebar.
+3. **Thumbnails Layout** — a grid of page thumbnails as the primary surface.
+4. **Horizontal Thumbnails** — a horizontal thumbnail strip.
+5. **Multiple Documents** — several independent viewers on one page.
+6. **Load from ArrayBuffer** — open a PDF from in-memory bytes.
+7. **Error Handling** — graceful handling of load/parse errors.
+
+Run the demo:
+
+```shell
+cd pdfslick_demo
+pip install -r requirements.txt
+reflex run
+```
+
+## Architecture (at a glance)
+
+```
+Python (Reflex app)
+  pdf_slick(url=..., scale_value=..., on_page_change=...)
+        │  compiles to
+        ▼
+React / Next.js (generated by Reflex)
+  <PdfSlickWrapper>  ← local .tsx, NoSSR, calls usePDFSlick(url, options)
+        │  renders <PDFSlickViewer/> + (optional) thumbnails
+        │  subscribes to usePDFSlickStore selectors → emits Reflex events
+        ▼
+@pdfslick/react → @pdfslick/core → PDF.js (pdfjs-dist) + Zustand store
+```
+
+Because PDFSlick's public surface is the **hook** `usePDFSlick(...)` (not a
+drop-in component) and its thumbnails component uses a render-prop child, the
+wrapper is a small local `.tsx` component that calls the hook internally and
+exposes a clean prop/event API to Python. Full rationale and trade-offs are in
+[specs/technical/architecture.md](specs/technical/architecture.md).
+
+## Spec-Driven Design documentation
+
+This project is documented before it is built. The `specs/` directory is the
+source of truth:
+
+| Document | Purpose |
+|---|---|
+| [`specs/prd/pdfslick-component.md`](specs/prd/pdfslick-component.md) | Product requirements, goals, scope, examples. |
+| [`specs/technical/architecture.md`](specs/technical/architecture.md) | Technical design, SSR strategy, wrapper pattern. |
+| [`specs/api/component-api.md`](specs/api/component-api.md) | Public Python API: props, events, controls. |
+| [`specs/data-model/store-schema.md`](specs/data-model/store-schema.md) | PDFSlick store schema and Python ↔ JS mapping. |
+| [`specs/plans/implementation-plan.md`](specs/plans/implementation-plan.md) | Phases, milestones, sequencing. |
+| [`specs/tasks/task-breakdown.md`](specs/tasks/task-breakdown.md) | Granular, trackable task list per phase. |
+| [`specs/research/pdfslick-and-reflex-research.md`](specs/research/pdfslick-and-reflex-research.md) | Primary-source research notes that ground the design. |
+
+## Roadmap
+
+- [x] **Phase 0 — Foundation & SDD**: repository, packaging, SDD artifacts,
+      README, demo skeleton.
+- [x] **Phase 1 — Core wrapper**: `PdfSlickWrapper.tsx`, `pdf_slick` component,
+      props, CSS import, NoSSR.
+- [x] **Phase 2 — Events & state bridge**: page/scale/load/error/metadata events.
+- [x] **Phase 3 — Imperative controls**: navigation, zoom, rotation, modes,
+      print, download (declarative `command` prop + `commands` helpers).
+- [x] **Phase 4 — Thumbnails & multi-document**: vertical/horizontal thumbnails,
+      independent multi-instance viewers.
+- [x] **Phase 5 — Demo gallery** (all 7 examples) **& docs polish**.
+- [x] **Phase 6 — Tests & CI**: 35 unit tests, GitHub Actions (pytest 3.10–3.13,
+      TSX transpile, demo build smoke). Demo compiles to a Reflex production build.
+- [ ] **Release** — PyPI publish + tagged GitHub release *(awaiting maintainer
+      credentials)*.
+
+## Credits
+
+- [PDFSlick](https://pdfslick.dev/) by
+  [Vancho Stojkov](https://github.com/van100j) — the library being wrapped (MIT).
+- [PDF.js](https://github.com/mozilla/pdf.js) by Mozilla.
+- [Reflex](https://reflex.dev/) — the Python web framework.
+
+This wrapper is an independent project and is not affiliated with or endorsed by
+the PDFSlick authors.
+
+## License
+
+[MIT](LICENSE) © Ernesto Crespo

reflex_pdfslick-0.0.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+reflex_pdfslick/PdfSlickWrapper.tsx,sha256=b2snBAZtNqun420O4-Wj_drk1EnZArw49R2-Oift3lk,9399
+reflex_pdfslick/__init__.py,sha256=lBFbdhpNUcYZJgsAEROfObpwL4ANaFXFzJYnCfXLV8A,951
+reflex_pdfslick/commands.py,sha256=TeSq9dv9dhQDs2BnJQvi8mzjBYfbmwIOjXr4oOhMG5A,3011
+reflex_pdfslick/models.py,sha256=6dJn3Y1A33j18iQnv9wysV6dY3ZBchZp_EVhHq6Hysg,1227
+reflex_pdfslick/options.py,sha256=4XdfjLzyNbcmViOwF0lXtVRAZ4bcSmTz3XzP4qF8EDI,1566
+reflex_pdfslick/pdfslick.py,sha256=JcKcR36uYb9um42-r4DmCgHHw2r0Sl9RzIFJX5ytInU,3354
+reflex_pdfslick/pdfslick.pyi,sha256=cWPslTVrGjMuGo-GdZm9QtFOnOSrluJhVxTBvhQOWug,5853
+reflex_pdfslick-0.0.1.dist-info/licenses/LICENSE,sha256=ikDZVzB6LJXytfIXkllDZj9ningVU9BduOAcL8jLKYI,1071
+reflex_pdfslick-0.0.1.dist-info/METADATA,sha256=alXTw9d7ZxZOVLPmsN3KMq2O1lyCTb16queIV5gkC2o,11332
+reflex_pdfslick-0.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+reflex_pdfslick-0.0.1.dist-info/top_level.txt,sha256=LdjY4d1vmIUeKMRRQ_rJ8y7XuJ7qhsyKfHaHXpnn7zs,16
+reflex_pdfslick-0.0.1.dist-info/RECORD,,

reflex_pdfslick-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

reflex_pdfslick-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ernesto Crespo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

reflex_pdfslick-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+reflex_pdfslick