dash-pdf-components 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +75 -12
  2. package/dash_pdf_components/dash_pdf_components.js +1 -1
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -10,16 +10,41 @@ For the common single-page viewer, use `PDF`:
10
10
 
11
11
  ```python
12
12
  import dash_pdf_components as dpc
13
+ from dash import get_asset_url
13
14
 
14
15
  dpc.PDF(
15
16
  id="pdf",
16
- file="/assets/document.pdf",
17
+ file=get_asset_url("document.pdf"),
17
18
  pageNumber=1,
18
19
  width=720,
19
20
  )
20
21
  ```
21
22
 
22
- `PDF` combines document loading and one rendered page. Navigation controls can update `PDF.pageNumber`, `PDF.scale`, and `PDF.rotate`; callbacks can read `PDF.numPages`, `PDF.loadProgress`, `PDF.pageData`, `PDF.renderData`, and `PDF.errorData` from the same component.
23
+ `PDF` combines document loading and page rendering. Navigation controls can update `PDF.pageNumber`, `PDF.scale`, and `PDF.rotate`; callbacks can read `PDF.numPages`, `PDF.documentData`, `PDF.loadProgress`, `PDF.pageData`, `PDF.renderData`, and `PDF.errorData` from the same component.
24
+
25
+ Render every page without a page-generation callback:
26
+
27
+ ```python
28
+ dpc.PDF(
29
+ file=get_asset_url("document.pdf"),
30
+ pages="all",
31
+ fit="width",
32
+ style={"height": "70vh"},
33
+ )
34
+ ```
35
+
36
+ `pageNumber` controls the current page; `pages` controls which pages are mounted.
37
+ Omit `pages` for single-page reading, use `"all"` for continuous reading, or a
38
+ list such as `[1, 3, 5]` for selected pages. Lists preserve order; duplicates and
39
+ invalid or out-of-range page numbers are ignored. In continuous reading,
40
+ navigation scrolls to the destination and scrolling updates `pageNumber`.
41
+ Links to pages outside an explicit selection only emit `itemClickData`, without
42
+ changing the selection. `pageNumber="all"` remains supported but is deprecated.
43
+
44
+ `fit="width"` sizes each page to the container's available width;
45
+ `fit="page"` fits both dimensions and requires an explicit container height.
46
+ These modes respond to resizing and rotation and override `width` and `height`.
47
+ `scale` multiplies the fitted size, so zooming may introduce scrollbars.
23
48
 
24
49
  ## API
25
50
 
@@ -33,7 +58,18 @@ Use the smallest API that fits the layout:
33
58
  | `Thumbnail` | Clickable page preview inside `Document` |
34
59
  | `Outline` | PDF table of contents inside `Document` |
35
60
 
36
- `PDF` accepts the commonly used React-PDF options directly: `file`, `pageNumber`, `width`, `height`, `scale`, `rotate`, `renderTextLayer`, `renderAnnotationLayer`, `renderForms`, `loading`, `error`, and `noData`. Advanced PDF.js loading options remain available through `options`, `assetBaseUrl`, and `workerSrc`.
61
+ `PDF` accepts the commonly used React-PDF options directly: `file`, `pageNumber`, `width`, `height`, `scale`, `rotate`, `renderTextLayer`, `renderAnnotationLayer`, `renderForms`, `error`, and `noData`. Advanced PDF.js loading options remain available through `options`, `assetBaseUrl`, and `workerSrc`.
62
+
63
+ `Document.documentData`, `Page.pageData`, and `Thumbnail.pageData` are the
64
+ recommended names for loaded results. Their existing `loadData` aliases remain
65
+ available for compatibility. Page and layer results identify their `pageNumber`
66
+ and describe the latest event, not a collection of every rendered page.
67
+
68
+ All components expose Dash's loading state through `data-dash-is-loading`, so
69
+ `dcc.Loading` can manage callback loading consistently. React-PDF's built-in
70
+ loading messages are disabled; no `loading` property is needed. PDF resource
71
+ fetching is separate from Dash callback loading and can be monitored through
72
+ `loadProgress` and `numPages` when an application needs its own indicator.
37
73
 
38
74
  Use the composable API only when the layout needs multiple pages, thumbnails, or an outline:
39
75
 
@@ -51,6 +87,42 @@ dpc.Document(
51
87
 
52
88
  The package intentionally has no toolbar, theme system, locale system, or Ant Design dependency. Build navigation, zoom, rotation, and download controls with ordinary Dash components. See [`usage.py`](usage.py) for a complete example.
53
89
 
90
+ ## Reader demo
91
+
92
+ Run a rendering-only demo without installing a UI library:
93
+
94
+ ```bash
95
+ PDF_DEMO=basic python usage.py
96
+ ```
97
+
98
+ This uses `PDF(pages="all", fit="width")` and has no toolbar or application callbacks.
99
+
100
+ The default reader demo includes PDF upload, an encrypted document (password: `dash-pdf`), page navigation, zoom, rotation, download, bookmarks, thumbnails, and single-page or continuous reading. It uses Ant Design when `dash-antd-components` is installed, otherwise Mantine when `dash-mantine-components` is installed. These UI libraries are optional and are not package dependencies. Its advanced layout keeps `Document + Page + Outline + Thumbnail` so every view shares the same loaded PDF.
101
+
102
+ Install either UI library and run the demo:
103
+
104
+ ```bash
105
+ pip install dash-pdf-components dash-ant-design
106
+ python usage.py
107
+ ```
108
+
109
+ For Mantine:
110
+
111
+ ```bash
112
+ pip install dash-pdf-components dash-mantine-components dash-iconify
113
+ python usage.py
114
+ ```
115
+
116
+ When both libraries are installed, Ant Design is selected by default. Set `PDF_UI=antd` or `PDF_UI=mantine` to choose explicitly, for example `PDF_UI=mantine python usage.py`. Keep the [`assets`](assets) directory alongside `usage.py`; it contains the demo PDFs and shared reader styles and callbacks. For a source checkout, build the components using the development commands below before running the demo.
117
+
118
+ ### Ant Design
119
+
120
+ ![PDF reader using dash-antd-components](docs/images/pdf-antd.png)
121
+
122
+ ### Mantine
123
+
124
+ ![PDF reader using dash-mantine-components](docs/images/pdf-mantine.png)
125
+
54
126
  React-PDF uses PDF.js internally. The matching Worker, character maps, standard fonts, WASM, ICC profiles, and annotation images load from this package by default. Set `assetBaseUrl` on `PDF` or `Document` to replace them with a version-matched CDN:
55
127
 
56
128
  ```python
@@ -63,12 +135,3 @@ dpc.PDF(
63
135
  `workerSrc`, `imageResourcesPath`, and individual `options` values such as `cMapUrl`, `standardFontDataUrl`, `wasmUrl`, and `iccUrl` override the defaults. These options are also available on `Document`.
64
136
 
65
137
  Internal PDF links navigate automatically. `PDF` and a single rendered `Page` switch to the destination page, while documents rendering multiple pages scroll to the mounted destination. `itemClickData` remains available for observing navigation.
66
-
67
- ## Development
68
-
69
- ```bash
70
- pnpm install
71
- uv sync
72
- pnpm build
73
- uv build --no-sources
74
- ```