@xh/hoist 90.0.0 → 90.1.0
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.
- package/CHANGELOG.md +136 -54
- package/admin/columns/Tracking.ts +9 -3
- package/admin/tabs/activity/tracking/ActivityTrackingModel.ts +155 -47
- package/admin/tabs/activity/tracking/ActivityTrackingPanel.ts +25 -4
- package/admin/tabs/activity/tracking/chart/AggChartModel.ts +2 -3
- package/appcontainer/ImpersonationBarModel.ts +8 -5
- package/build/types/admin/tabs/activity/tracking/ActivityTrackingModel.d.ts +25 -5
- package/build/types/cmp/cubegrid/CubeGrid.d.ts +26 -0
- package/build/types/cmp/cubegrid/CubeGridModel.d.ts +103 -0
- package/build/types/cmp/cubegrid/CubeGridPivotModel.d.ts +181 -0
- package/build/types/cmp/cubegrid/Types.d.ts +85 -0
- package/build/types/cmp/cubegrid/index.d.ts +4 -0
- package/build/types/cmp/dataview/DataViewModel.d.ts +6 -10
- package/build/types/cmp/grid/GridModel.d.ts +8 -33
- package/build/types/cmp/grid/Types.d.ts +51 -1
- package/build/types/cmp/grid/columns/Column.d.ts +2 -1
- package/build/types/cmp/grid/columns/ColumnGroup.d.ts +6 -0
- package/build/types/cmp/grid/helpers/GridCountLabel.d.ts +6 -3
- package/build/types/cmp/grid/impl/ColumnWidthCalculator.d.ts +6 -0
- package/build/types/cmp/grid/impl/GridLikeModel.d.ts +3 -0
- package/build/types/cmp/grid/impl/MenuSupport.d.ts +13 -0
- package/build/types/cmp/pdfviewer/PdfViewer.d.ts +14 -0
- package/build/types/cmp/pdfviewer/PdfViewerModel.d.ts +150 -0
- package/build/types/cmp/pdfviewer/Types.d.ts +55 -0
- package/build/types/cmp/pdfviewer/impl/PdfFindInputModel.d.ts +14 -0
- package/build/types/cmp/pdfviewer/impl/PdfViewerToolbarModel.d.ts +34 -0
- package/build/types/cmp/pdfviewer/impl/ZoomOptions.d.ts +10 -0
- package/build/types/cmp/pdfviewer/index.d.ts +3 -0
- package/build/types/cmp/statcard/StatCard.d.ts +90 -0
- package/build/types/cmp/statcard/index.d.ts +1 -0
- package/build/types/cmp/store/StoreFilterField.d.ts +8 -9
- package/build/types/cmp/store/impl/StoreFilterFieldImplModel.d.ts +4 -4
- package/build/types/cmp/zoneGrid/ZoneGridModel.d.ts +6 -10
- package/build/types/core/types/Types.d.ts +6 -0
- package/build/types/data/Field.d.ts +8 -1
- package/build/types/data/Store.d.ts +12 -0
- package/build/types/data/cube/Cube.d.ts +2 -0
- package/build/types/data/cube/CubeField.d.ts +3 -2
- package/build/types/data/cube/Query.d.ts +66 -4
- package/build/types/data/cube/View.d.ts +82 -4
- package/build/types/data/cube/ViewRowData.d.ts +13 -0
- package/build/types/data/cube/aggregate/MedianAggregator.d.ts +19 -0
- package/build/types/data/cube/aggregate/SumIfSameAggregator.d.ts +30 -0
- package/build/types/data/cube/impl/RowCache.d.ts +5 -0
- package/build/types/data/cube/impl/RowDataGenerator.d.ts +26 -0
- package/build/types/data/cube/impl/ViewDiagnostics.d.ts +27 -0
- package/build/types/data/cube/pivot/PivotCellRow.d.ts +27 -0
- package/build/types/data/cube/pivot/PivotPath.d.ts +45 -0
- package/build/types/data/cube/pivot/impl/PivotCells.d.ts +111 -0
- package/build/types/data/cube/pivot/impl/PivotReference.d.ts +39 -0
- package/build/types/data/cube/pivot/impl/PivotStructure.d.ts +105 -0
- package/build/types/data/cube/row/BaseRow.d.ts +12 -0
- package/build/types/data/cube/row/LeafRow.d.ts +4 -4
- package/build/types/data/cube/row/ParentRow.d.ts +20 -4
- package/build/types/data/cube/row/RowUpdate.d.ts +2 -0
- package/build/types/data/index.d.ts +3 -0
- package/build/types/desktop/cmp/button/grid/ColAutosizeButton.d.ts +6 -3
- package/build/types/desktop/cmp/button/grid/ColChooserButton.d.ts +7 -3
- package/build/types/desktop/cmp/button/grid/ExpandToLevelButton.d.ts +6 -3
- package/build/types/desktop/cmp/button/grid/ExportButton.d.ts +6 -3
- package/build/types/desktop/cmp/grid/find/GridFindField.d.ts +8 -9
- package/build/types/desktop/cmp/grid/find/impl/GridFindFieldImplModel.d.ts +3 -4
- package/build/types/desktop/cmp/pdfviewer/impl/PdfViewerToolbar.d.ts +12 -0
- package/build/types/desktop/cmp/statcard/impl/StatCardInfoImpl.d.ts +12 -0
- package/build/types/dynamics/desktop.d.ts +2 -0
- package/build/types/dynamics/mobile.d.ts +1 -0
- package/build/types/icon/Icon.d.ts +12 -0
- package/build/types/kit/pdfjs/index.d.ts +23 -0
- package/build/types/kit/pdfjs/styles.d.ts +2 -0
- package/build/types/kit/swiper/index.d.ts +7 -7
- package/build/types/mobile/cmp/button/grid/ColAutosizeButton.d.ts +6 -3
- package/build/types/mobile/cmp/button/grid/ColChooserButton.d.ts +6 -3
- package/build/types/mobile/cmp/button/grid/ExpandCollapseButton.d.ts +4 -4
- package/build/types/mobile/cmp/button/grid/ExpandToLevelButton.d.ts +4 -4
- package/build/types/mobile/cmp/pdfviewer/impl/PdfViewerToolbar.d.ts +12 -0
- package/cmp/README.md +3 -0
- package/cmp/ag-grid/AgGrid.ts +25 -3
- package/cmp/cubegrid/CubeGrid.ts +60 -0
- package/cmp/cubegrid/CubeGridModel.ts +365 -0
- package/cmp/cubegrid/CubeGridPivotModel.ts +943 -0
- package/cmp/cubegrid/README.md +343 -0
- package/cmp/cubegrid/Types.ts +105 -0
- package/cmp/cubegrid/index.ts +10 -0
- package/cmp/dataview/DataViewModel.ts +13 -8
- package/cmp/grid/Grid.scss +21 -5
- package/cmp/grid/GridModel.ts +41 -47
- package/cmp/grid/Types.ts +58 -1
- package/cmp/grid/columns/Column.ts +3 -1
- package/cmp/grid/columns/ColumnGroup.ts +10 -0
- package/cmp/grid/helpers/GridCountLabel.ts +12 -5
- package/cmp/grid/impl/ColumnGroupHeader.ts +18 -4
- package/cmp/grid/impl/ColumnWidthCalculator.ts +24 -0
- package/cmp/grid/impl/GridLikeModel.ts +17 -0
- package/cmp/grid/impl/MenuSupport.ts +36 -20
- package/cmp/pdfviewer/PdfViewer.scss +48 -0
- package/cmp/pdfviewer/PdfViewer.ts +102 -0
- package/cmp/pdfviewer/PdfViewerModel.ts +641 -0
- package/cmp/pdfviewer/README.md +224 -0
- package/cmp/pdfviewer/Types.ts +72 -0
- package/cmp/pdfviewer/impl/PdfFindInputModel.ts +44 -0
- package/cmp/pdfviewer/impl/PdfViewerToolbarModel.ts +45 -0
- package/cmp/pdfviewer/impl/ZoomOptions.ts +36 -0
- package/cmp/pdfviewer/index.ts +9 -0
- package/cmp/statcard/StatCard.scss +181 -0
- package/cmp/statcard/StatCard.ts +320 -0
- package/cmp/statcard/index.ts +1 -0
- package/cmp/store/StoreFilterField.ts +8 -9
- package/cmp/store/impl/StoreFilterFieldImplModel.ts +14 -14
- package/cmp/zoneGrid/ZoneGridModel.ts +13 -8
- package/core/types/Types.ts +7 -0
- package/data/Field.ts +10 -0
- package/data/Store.ts +25 -2
- package/data/cube/Cube.ts +5 -0
- package/data/cube/CubeField.ts +5 -0
- package/data/cube/Query.ts +170 -17
- package/data/cube/README.md +77 -2
- package/data/cube/View.ts +211 -32
- package/data/cube/ViewRowData.ts +22 -0
- package/data/cube/aggregate/MedianAggregator.ts +88 -0
- package/data/cube/aggregate/SumIfSameAggregator.ts +128 -0
- package/data/cube/impl/RowCache.ts +32 -11
- package/data/cube/impl/RowDataGenerator.ts +96 -4
- package/data/cube/impl/ViewDiagnostics.ts +47 -0
- package/data/cube/pivot/PivotCellRow.ts +73 -0
- package/data/cube/pivot/PivotPath.ts +67 -0
- package/data/cube/pivot/impl/PivotCells.ts +538 -0
- package/data/cube/pivot/impl/PivotReference.ts +125 -0
- package/data/cube/pivot/impl/PivotStructure.ts +500 -0
- package/data/cube/row/BaseRow.ts +26 -0
- package/data/cube/row/LeafRow.ts +9 -8
- package/data/cube/row/ParentRow.ts +58 -25
- package/data/cube/row/RowUpdate.ts +8 -0
- package/data/index.ts +3 -0
- package/desktop/appcontainer/AppContainer.ts +5 -1
- package/desktop/cmp/button/grid/ColAutosizeButton.ts +21 -5
- package/desktop/cmp/button/grid/ColChooserButton.ts +11 -5
- package/desktop/cmp/button/grid/ExpandToLevelButton.ts +20 -5
- package/desktop/cmp/button/grid/ExportButton.ts +19 -7
- package/desktop/cmp/dash/canvas/DashCanvas.ts +26 -2
- package/desktop/cmp/grid/find/GridFindField.ts +8 -9
- package/desktop/cmp/grid/find/impl/GridFindFieldImplModel.ts +15 -16
- package/desktop/cmp/grid/impl/colchooser/ColChooserBucketModel.ts +1 -1
- package/desktop/cmp/pdfviewer/impl/PdfViewerToolbar.ts +190 -0
- package/desktop/cmp/statcard/impl/StatCardInfoImpl.ts +27 -0
- package/docs/README.md +6 -2
- package/docs/doc-registry.json +21 -5
- package/docs/upgrade-notes/v90-upgrade-notes.md +130 -0
- package/docs/version-compatibility.md +2 -1
- package/dynamics/desktop.ts +4 -0
- package/dynamics/mobile.ts +2 -0
- package/format/FormatNumber.ts +6 -2
- package/icon/Icon.ts +18 -0
- package/icon/index.ts +32 -0
- package/kit/README.md +2 -0
- package/kit/pdfjs/PdfJs.scss +25 -0
- package/kit/pdfjs/index.ts +103 -0
- package/kit/pdfjs/pdf_viewer.css +6481 -0
- package/kit/pdfjs/styles.ts +12 -0
- package/mcp/README.md +13 -0
- package/mcp/data/import-paths.ts +4 -8
- package/mcp/data/index-cache.ts +2 -1
- package/mcp/data/ts-registry.ts +8 -29
- package/mcp/util/paths.ts +26 -0
- package/mobile/appcontainer/AppContainer.ts +3 -1
- package/mobile/cmp/button/grid/ColAutosizeButton.ts +20 -5
- package/mobile/cmp/button/grid/ColChooserButton.ts +12 -5
- package/mobile/cmp/button/grid/ExpandCollapseButton.ts +10 -6
- package/mobile/cmp/button/grid/ExpandToLevelButton.ts +10 -6
- package/mobile/cmp/pdfviewer/impl/PdfViewerToolbar.ts +137 -0
- package/package.json +14 -8
- package/public/msal-redirect-bridge.min.js +1 -1
- package/styles/vars.scss +59 -0
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
# PDF Viewer Package
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
The `/cmp/pdfviewer/` package provides `PdfViewer` and its backing `PdfViewerModel`, which
|
|
6
|
+
display PDF documents inside a Hoist app. The viewer is built on Mozilla's
|
|
7
|
+
[pdf.js](https://mozilla.github.io/pdf.js/), the engine inside Firefox.
|
|
8
|
+
|
|
9
|
+
**Key features:**
|
|
10
|
+
- Load documents from a URL, a `FetchOptions` object, or bytes the app already holds
|
|
11
|
+
- Pages render on demand as they scroll into view
|
|
12
|
+
- Selectable text and working links
|
|
13
|
+
- Find with match highlighting, zoom presets that refit on resize, and rotation
|
|
14
|
+
- A built-in toolbar configured with tokens, and open to custom elements
|
|
15
|
+
- Observable state and actions on the model for app-built controls
|
|
16
|
+
- Light and dark themes, with styling through CSS variables
|
|
17
|
+
|
|
18
|
+
The component and model are cross-platform. The toolbar has a desktop and a mobile version.
|
|
19
|
+
|
|
20
|
+
## Installation
|
|
21
|
+
|
|
22
|
+
Hoist declares `pdfjs-dist` as an optional peer dependency. Add it to your app to opt in:
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
pnpm add pdfjs-dist
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
No bootstrap call or build config is needed. Hoist loads pdf.js the first time a viewer shows a
|
|
29
|
+
document. The app bundler splits the library, its worker, and its CSS into separate chunks, so
|
|
30
|
+
apps pay no bundle cost until then. Apps that never import this package do not need `pdfjs-dist`.
|
|
31
|
+
|
|
32
|
+
Hoist uses the pdf.js "legacy" build, which supports a wider range of browsers than its modern
|
|
33
|
+
build.
|
|
34
|
+
|
|
35
|
+
## Basic Usage
|
|
36
|
+
|
|
37
|
+
Create the model in your own model, and render the component where the document should appear:
|
|
38
|
+
|
|
39
|
+
```typescript
|
|
40
|
+
import {pdfViewer, PdfViewerModel} from '@xh/hoist/cmp/pdfviewer';
|
|
41
|
+
|
|
42
|
+
class DocDetailModel extends HoistModel {
|
|
43
|
+
@managed pdfViewerModel = new PdfViewerModel({
|
|
44
|
+
filename: 'statement.pdf',
|
|
45
|
+
persistWith: {localStorageKey: 'docDetail'}
|
|
46
|
+
});
|
|
47
|
+
|
|
48
|
+
showDoc(docId: string) {
|
|
49
|
+
this.pdfViewerModel.setSource(`api/docs/${docId}/content`);
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
const docDetail = hoistCmp.factory<DocDetailModel>(({model}) =>
|
|
54
|
+
panel({title: 'Document', item: pdfViewer({model: model.pdfViewerModel})})
|
|
55
|
+
);
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
The component fills its container by default (`flex: 1`). It shows a loading mask while a
|
|
59
|
+
document loads, an error with a Retry button if the load fails, and a placeholder when there
|
|
60
|
+
is no source.
|
|
61
|
+
|
|
62
|
+
## Sources
|
|
63
|
+
|
|
64
|
+
Set the document with the `source` config or `setSource()`. Pass null to clear it.
|
|
65
|
+
|
|
66
|
+
| Source | Loaded via | Typical use |
|
|
67
|
+
|--------|------------|-------------|
|
|
68
|
+
| URL string | `XH.fetch()` | Server endpoint. Relative URLs resolve against `XH.baseUrl`. |
|
|
69
|
+
| `FetchOptions` | `XH.fetch()` | A POST that generates a PDF, or custom params and headers |
|
|
70
|
+
| `Blob` or `File` | Read in place | A blob from an authenticated API call, or a local file before upload |
|
|
71
|
+
| `ArrayBuffer` or `Uint8Array` | Copied | Bytes the app already holds |
|
|
72
|
+
|
|
73
|
+
URL sources go through `XH.fetch()`, so they get the same auth, headers, and error handling as
|
|
74
|
+
any other Hoist request. pdf.js moves the bytes it parses to its worker. The model copies app
|
|
75
|
+
buffers first, so your `ArrayBuffer` or `Uint8Array` stays usable.
|
|
76
|
+
|
|
77
|
+
When the source changes, the model closes the old document and loads the new one. A newer
|
|
78
|
+
source always wins over a load still in progress.
|
|
79
|
+
|
|
80
|
+
## Toolbar
|
|
81
|
+
|
|
82
|
+
Configure the built-in toolbar with the `toolbar` config:
|
|
83
|
+
|
|
84
|
+
- `true` (default) - the platform defaults from `PdfViewerModel.defaults`
|
|
85
|
+
- `false` - no toolbar
|
|
86
|
+
- An array of tokens and custom elements, rendered in order
|
|
87
|
+
|
|
88
|
+
| Token | Renders |
|
|
89
|
+
|-------|---------|
|
|
90
|
+
| `pageNav` | Previous and next buttons, page number input |
|
|
91
|
+
| `zoom` | Zoom out and in buttons, zoom level menu |
|
|
92
|
+
| `find` | Search input, match count, previous and next buttons |
|
|
93
|
+
| `rotate` | Rotate clockwise button |
|
|
94
|
+
| `download` | Download button |
|
|
95
|
+
| `-` | Separator |
|
|
96
|
+
| `filler` | Flexible space, to push later items right |
|
|
97
|
+
|
|
98
|
+
Any other item renders as given. Use this to add your own buttons:
|
|
99
|
+
|
|
100
|
+
```typescript
|
|
101
|
+
new PdfViewerModel({
|
|
102
|
+
toolbar: [
|
|
103
|
+
'pageNav',
|
|
104
|
+
'filler',
|
|
105
|
+
'find',
|
|
106
|
+
'-',
|
|
107
|
+
button({text: 'Approve', onClick: () => this.approveAsync()}),
|
|
108
|
+
'download'
|
|
109
|
+
]
|
|
110
|
+
});
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
To change the toolbar for the whole app, set `PdfViewerModel.defaults.toolbar` or
|
|
114
|
+
`PdfViewerModel.defaults.mobileToolbar` at startup.
|
|
115
|
+
|
|
116
|
+
The mobile toolbar renders the same tokens in a compact form. It leaves out the page number input,
|
|
117
|
+
the zoom in and out buttons, the find-previous button, and keyboard shortcuts.
|
|
118
|
+
|
|
119
|
+
## Model API
|
|
120
|
+
|
|
121
|
+
The built-in toolbar uses only the public model API. Custom controls can bind to the same
|
|
122
|
+
state, or you can drive the viewer from code.
|
|
123
|
+
|
|
124
|
+
| Member | Kind | Description |
|
|
125
|
+
|--------|------|-------------|
|
|
126
|
+
| `pageNumber`, `pageCount` | observable | Current page, from 1, and total pages |
|
|
127
|
+
| `goToPage()`, `nextPage()`, `previousPage()` | action | Navigate. `goToPage()` clamps out-of-range values. |
|
|
128
|
+
| `scale`, `currentScale` | observable | Requested zoom (preset or number), and the resolved number |
|
|
129
|
+
| `setScale()`, `zoomIn()`, `zoomOut()` | action | Change zoom |
|
|
130
|
+
| `rotation`, `rotate()` | observable, action | Page rotation in degrees, in 90-degree steps |
|
|
131
|
+
| `findAsync()`, `clearFind()` | async, action | Search and resolve with the result, or clear |
|
|
132
|
+
| `findQuery`, `isFinding` | observable | Query of the current find, and true while it searches |
|
|
133
|
+
| `findMatchCount`, `findMatchNumber` | observable | Match total, and the selected match from 1 |
|
|
134
|
+
| `findNext()`, `findPrevious()` | action | Select and scroll to a match |
|
|
135
|
+
| `downloadAsync()` | action | Save the loaded document as `downloadFilename` |
|
|
136
|
+
| `hasSource`, `hasDocument` | getter | A source is set, and a document has loaded |
|
|
137
|
+
| `pdfDocument` | observable | The pdf.js `PDFDocumentProxy`, for direct API access |
|
|
138
|
+
| `loadObserver`, `lastLoadException` | load support | Standard Hoist load state |
|
|
139
|
+
|
|
140
|
+
Zoom presets are `page-width` (the default), `page-fit`, `page-actual`, and `auto`. A preset
|
|
141
|
+
refits the document whenever the viewer resizes. A number is a fixed scale, where 1 is 100%.
|
|
142
|
+
|
|
143
|
+
Pass `persistWith` to save the user's zoom level. The model persists `scale` only.
|
|
144
|
+
|
|
145
|
+
## Searching
|
|
146
|
+
|
|
147
|
+
`findAsync(query)` runs a search and resolves once pdf.js has searched every page. It is the
|
|
148
|
+
only way to search - the toolbar find input calls it too. Use the result when the app needs to
|
|
149
|
+
know whether text was found, such as to locate a quoted passage:
|
|
150
|
+
|
|
151
|
+
```typescript
|
|
152
|
+
const result = await pdfViewerModel.findAsync(passage);
|
|
153
|
+
if (result.status === 'found') {
|
|
154
|
+
// The viewer has scrolled to the match on page result.pageNumber.
|
|
155
|
+
}
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
The result has a `status`, plus `matchCount`, `matchNumber`, and the `pageNumber` of the
|
|
159
|
+
selected match. The status is one of:
|
|
160
|
+
|
|
161
|
+
- `found` - the viewer highlighted every match and scrolled to the first one at or after the
|
|
162
|
+
current page.
|
|
163
|
+
- `notFound` - nothing matched, or the query was empty.
|
|
164
|
+
- `cancelled` - a newer find, a source change, a failed load, or `destroy()` ended the search
|
|
165
|
+
first. A call with no source also resolves as cancelled.
|
|
166
|
+
|
|
167
|
+
Each call runs a new search, even for the same query, so a repeated call scrolls back to a
|
|
168
|
+
match. A call made before the document loads waits for it to load and display. Match counts
|
|
169
|
+
reset to zero as soon as a search starts. The query stays set when the source changes, and runs
|
|
170
|
+
again on the new document. Call `clearFind()` to clear it.
|
|
171
|
+
|
|
172
|
+
Matching is case-insensitive and ignores diacritics. pdf.js normalizes quotes, ligatures,
|
|
173
|
+
whitespace, line breaks, and words hyphenated at a line end. A match cannot span pages, and
|
|
174
|
+
there is no fuzzy matching - trim a truncated passage, such as one ending in "…", before
|
|
175
|
+
searching.
|
|
176
|
+
|
|
177
|
+
## Styling
|
|
178
|
+
|
|
179
|
+
The viewer follows the Hoist theme. Override these CSS variables to adjust it:
|
|
180
|
+
|
|
181
|
+
| Variable | Default |
|
|
182
|
+
|----------|---------|
|
|
183
|
+
| `--xh-pdf-viewer-bg` | `--xh-bg-alt` |
|
|
184
|
+
| `--xh-pdf-viewer-page-shadow` | A soft drop shadow, darker in the dark theme |
|
|
185
|
+
| `--xh-pdf-viewer-page-gap-px` | `10px` |
|
|
186
|
+
| `--xh-pdf-viewer-highlight-bg` | Translucent amber |
|
|
187
|
+
| `--xh-pdf-viewer-highlight-selected-bg` | Translucent orange |
|
|
188
|
+
|
|
189
|
+
Pages keep their own colors in the dark theme, as in other PDF readers.
|
|
190
|
+
|
|
191
|
+
## How It Works
|
|
192
|
+
|
|
193
|
+
- `kit/pdfjs` loads pdf.js with dynamic imports and checks its version. It starts one worker
|
|
194
|
+
for the whole app, and serves the wasm image decoders and fonts that pdf.js requests. The
|
|
195
|
+
decoders handle JPEG2000 and JBIG2 images, which are common in scanned documents.
|
|
196
|
+
- `PdfViewerModel` owns the document and the pdf.js `PDFViewer`. It turns pdf.js events into
|
|
197
|
+
MobX state.
|
|
198
|
+
- `PdfViewer` renders the scroll container that pdf.js draws into, plus the mask, error, and
|
|
199
|
+
placeholder states.
|
|
200
|
+
- The pdf.js stylesheet also styles Mozilla's full viewer app, with generic selectors such as
|
|
201
|
+
`button` and `.dialog`. Hoist ships a copy scoped to `.xh-pdf-viewer`, so its rules never apply
|
|
202
|
+
outside a viewer. `scripts/generate-pdfjs-css.mjs` builds it, and `pnpm check:vendored` keeps it
|
|
203
|
+
in step with the installed pdf.js.
|
|
204
|
+
- The platform toolbars install through `@xh/hoist/dynamics`. They never import the model, even
|
|
205
|
+
as a type, and use a small interface instead. pdf.js thus stays out of the build and the type
|
|
206
|
+
check of apps that do not use the viewer.
|
|
207
|
+
|
|
208
|
+
## Limitations
|
|
209
|
+
|
|
210
|
+
- No print, thumbnails, outline sidebar, or annotation editing yet.
|
|
211
|
+
- No gesture zoom. Pinch on touch devices and ctrl+wheel are not handled - pdf.js leaves these to
|
|
212
|
+
its full viewer app, which Hoist does not use. Use the toolbar zoom controls. Pinch zoom is
|
|
213
|
+
planned for when an app needs the viewer on mobile.
|
|
214
|
+
- Password-protected documents show a load error. A password prompt is planned, through the
|
|
215
|
+
pdf.js `onPassword` callback.
|
|
216
|
+
- CJK text in documents that do not embed their character maps can render incorrectly. Hoist
|
|
217
|
+
does not bundle the pdf.js CMap files.
|
|
218
|
+
- Documents load in full before display. pdf.js range requests and streaming are not used.
|
|
219
|
+
|
|
220
|
+
## Related Packages
|
|
221
|
+
|
|
222
|
+
- [`/cmp/layout/`](../layout/README.md) - `placeholder` and layout containers used by the viewer
|
|
223
|
+
- [`/svc/`](../../svc/README.md) - `FetchService`, which loads URL and `FetchOptions` sources
|
|
224
|
+
- [`/kit/`](../../kit/README.md) - third-party library wrappers, including `kit/pdfjs`
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* This file belongs to Hoist, an application development toolkit
|
|
3
|
+
* developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
|
|
4
|
+
*
|
|
5
|
+
* Copyright © 2026 Extremely Heavy Industries Inc.
|
|
6
|
+
*/
|
|
7
|
+
import type {FetchOptions} from '@xh/hoist/svc';
|
|
8
|
+
import type {ReactNode} from 'react';
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* A PDF document to display. Either:
|
|
12
|
+
* - a URL, fetched via `XH.fetch()` - relative URLs resolve against `XH.baseUrl`.
|
|
13
|
+
* - a {@link FetchOptions} object, for POSTs, params, or custom headers.
|
|
14
|
+
* - the PDF bytes, as a `Blob` (or `File`), `ArrayBuffer`, or `Uint8Array`.
|
|
15
|
+
*/
|
|
16
|
+
export type PdfSource = string | FetchOptions | Blob | ArrayBuffer | Uint8Array;
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* Zoom level for a {@link PdfViewerModel}. Either a numeric scale (1 = 100%) or a preset that
|
|
20
|
+
* re-fits the document as the viewer resizes:
|
|
21
|
+
* - `page-width` - fit page width to the viewer.
|
|
22
|
+
* - `page-fit` - fit the entire page within the viewer.
|
|
23
|
+
* - `page-actual` - display at actual size (100%).
|
|
24
|
+
* - `auto` - page width, capped at actual size.
|
|
25
|
+
*/
|
|
26
|
+
export type PdfScale = 'page-width' | 'page-fit' | 'page-actual' | 'auto' | number;
|
|
27
|
+
|
|
28
|
+
/** Result of {@link PdfViewerModel.findAsync}. */
|
|
29
|
+
export interface PdfFindResult {
|
|
30
|
+
/**
|
|
31
|
+
* Outcome of the search:
|
|
32
|
+
* - `found` - the query matched, and the viewer scrolled to the selected match.
|
|
33
|
+
* - `notFound` - the query matched nowhere in the document, or was empty.
|
|
34
|
+
* - `cancelled` - the search ended early, due to a newer find, a source change, a failed
|
|
35
|
+
* load, or `destroy()`. Also returned when there is no source to search.
|
|
36
|
+
*/
|
|
37
|
+
status: 'found' | 'notFound' | 'cancelled';
|
|
38
|
+
|
|
39
|
+
/** The query searched for. */
|
|
40
|
+
query: string;
|
|
41
|
+
|
|
42
|
+
/** Count of matches across the document. */
|
|
43
|
+
matchCount: number;
|
|
44
|
+
|
|
45
|
+
/** Index of the selected match across the document, from 1. Zero if none. */
|
|
46
|
+
matchNumber: number;
|
|
47
|
+
|
|
48
|
+
/** Page of the selected match, from 1. Null if none. */
|
|
49
|
+
pageNumber: number;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* Built-in toolbar items:
|
|
54
|
+
* - `pageNav` - previous/next buttons and a page number input.
|
|
55
|
+
* - `zoom` - zoom in/out buttons and a zoom level menu.
|
|
56
|
+
* - `find` - search input with match count and previous/next buttons.
|
|
57
|
+
* - `rotate` - rotate pages clockwise.
|
|
58
|
+
* - `download` - download the document.
|
|
59
|
+
* - `-` - a separator.
|
|
60
|
+
* - `filler` - a flexible spacer, to right-align subsequent items.
|
|
61
|
+
*/
|
|
62
|
+
export type PdfViewerToolbarToken =
|
|
63
|
+
'pageNav' | 'zoom' | 'find' | 'rotate' | 'download' | '-' | 'filler';
|
|
64
|
+
|
|
65
|
+
/** A built-in toolbar token or any custom element, such as a button. */
|
|
66
|
+
export type PdfViewerToolbarItem = PdfViewerToolbarToken | ReactNode;
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Toolbar config for a {@link PdfViewerModel} - `true` for the platform default items (see
|
|
70
|
+
* {@link PdfViewerModel.defaults}), `false` to hide the toolbar, or a list of items.
|
|
71
|
+
*/
|
|
72
|
+
export type PdfViewerToolbarSpec = boolean | PdfViewerToolbarItem[];
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* This file belongs to Hoist, an application development toolkit
|
|
3
|
+
* developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
|
|
4
|
+
*
|
|
5
|
+
* Copyright © 2026 Extremely Heavy Industries Inc.
|
|
6
|
+
*/
|
|
7
|
+
import {HoistModel} from '@xh/hoist/core';
|
|
8
|
+
import {bindable} from '@xh/hoist/mobx';
|
|
9
|
+
import type {PdfViewerToolbarModel} from './PdfViewerToolbarModel';
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Local model for a toolbar find input. Holds the text as the user types, and runs a find once
|
|
13
|
+
* typing pauses. Shows a query set by the app via `findAsync()`.
|
|
14
|
+
*
|
|
15
|
+
* @internal
|
|
16
|
+
*/
|
|
17
|
+
export class PdfFindInputModel extends HoistModel {
|
|
18
|
+
override xhImpl = true;
|
|
19
|
+
|
|
20
|
+
@bindable accessor query: string;
|
|
21
|
+
|
|
22
|
+
private readonly viewerModel: PdfViewerToolbarModel;
|
|
23
|
+
|
|
24
|
+
constructor(viewerModel: PdfViewerToolbarModel) {
|
|
25
|
+
super();
|
|
26
|
+
this.viewerModel = viewerModel;
|
|
27
|
+
this.query = viewerModel.findQuery;
|
|
28
|
+
|
|
29
|
+
this.addReaction(
|
|
30
|
+
{
|
|
31
|
+
track: () => viewerModel.findQuery,
|
|
32
|
+
run: findQuery => (this.query = findQuery)
|
|
33
|
+
},
|
|
34
|
+
{
|
|
35
|
+
track: () => this.query,
|
|
36
|
+
// Skip the viewer's own query, so showing it does not search again.
|
|
37
|
+
run: query => {
|
|
38
|
+
if (query !== viewerModel.findQuery) viewerModel.findAsync(query);
|
|
39
|
+
},
|
|
40
|
+
debounce: 200
|
|
41
|
+
}
|
|
42
|
+
);
|
|
43
|
+
}
|
|
44
|
+
}
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* This file belongs to Hoist, an application development toolkit
|
|
3
|
+
* developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
|
|
4
|
+
*
|
|
5
|
+
* Copyright © 2026 Extremely Heavy Industries Inc.
|
|
6
|
+
*/
|
|
7
|
+
import type {HoistModel} from '@xh/hoist/core';
|
|
8
|
+
import type {PdfScale, PdfViewerToolbarItem} from '../Types';
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* The members of {@link PdfViewerModel} that the platform toolbars use.
|
|
12
|
+
*
|
|
13
|
+
* Every app's AppContainer loads the toolbars. Typing them against this interface, not the model,
|
|
14
|
+
* keeps `tsc` from reaching the model's pdf.js imports in apps that do not install `pdfjs-dist`.
|
|
15
|
+
*
|
|
16
|
+
* @internal
|
|
17
|
+
*/
|
|
18
|
+
export interface PdfViewerToolbarModel extends HoistModel {
|
|
19
|
+
readonly toolbar: PdfViewerToolbarItem[];
|
|
20
|
+
readonly hasDocument: boolean;
|
|
21
|
+
|
|
22
|
+
readonly pageNumber: number;
|
|
23
|
+
readonly pageCount: number;
|
|
24
|
+
readonly canGoNext: boolean;
|
|
25
|
+
readonly canGoPrevious: boolean;
|
|
26
|
+
goToPage(pageNumber: number): void;
|
|
27
|
+
nextPage(): void;
|
|
28
|
+
previousPage(): void;
|
|
29
|
+
|
|
30
|
+
readonly scale: PdfScale;
|
|
31
|
+
setScale(scale: PdfScale): void;
|
|
32
|
+
zoomIn(): void;
|
|
33
|
+
zoomOut(): void;
|
|
34
|
+
rotate(degrees?: number): void;
|
|
35
|
+
|
|
36
|
+
readonly findQuery: string;
|
|
37
|
+
readonly findMatchCount: number;
|
|
38
|
+
readonly findMatchNumber: number;
|
|
39
|
+
readonly isFinding: boolean;
|
|
40
|
+
findAsync(query: string): Promise<unknown>;
|
|
41
|
+
findNext(): void;
|
|
42
|
+
findPrevious(): void;
|
|
43
|
+
|
|
44
|
+
downloadAsync(): Promise<void>;
|
|
45
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* This file belongs to Hoist, an application development toolkit
|
|
3
|
+
* developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
|
|
4
|
+
*
|
|
5
|
+
* Copyright © 2026 Extremely Heavy Industries Inc.
|
|
6
|
+
*/
|
|
7
|
+
import {isNumber} from 'lodash';
|
|
8
|
+
import type {PdfViewerToolbarModel} from './PdfViewerToolbarModel';
|
|
9
|
+
import type {PdfScale} from '../Types';
|
|
10
|
+
|
|
11
|
+
const PRESETS: {value: PdfScale; label: string}[] = [
|
|
12
|
+
{value: 'page-width', label: 'Fit width'},
|
|
13
|
+
{value: 'page-fit', label: 'Fit page'},
|
|
14
|
+
{value: 'page-actual', label: 'Actual size'},
|
|
15
|
+
{value: 'auto', label: 'Automatic'}
|
|
16
|
+
];
|
|
17
|
+
|
|
18
|
+
const PERCENTS = [0.5, 0.75, 1, 1.25, 1.5, 2, 3];
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Options for a zoom level select, including the current scale if not otherwise listed.
|
|
22
|
+
* @internal
|
|
23
|
+
*/
|
|
24
|
+
export function getZoomOptions(model: PdfViewerToolbarModel): {value: PdfScale; label: string}[] {
|
|
25
|
+
const {scale} = model,
|
|
26
|
+
ret = [...PRESETS, ...PERCENTS.map(value => ({value, label: formatScale(value)}))];
|
|
27
|
+
|
|
28
|
+
if (isNumber(scale) && !PERCENTS.includes(scale)) {
|
|
29
|
+
ret.push({value: scale, label: formatScale(scale)});
|
|
30
|
+
}
|
|
31
|
+
return ret;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
function formatScale(scale: number): string {
|
|
35
|
+
return `${Math.round(scale * 100)}%`;
|
|
36
|
+
}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* This file belongs to Hoist, an application development toolkit
|
|
3
|
+
* developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
|
|
4
|
+
*
|
|
5
|
+
* Copyright © 2026 Extremely Heavy Industries Inc.
|
|
6
|
+
*/
|
|
7
|
+
export * from './PdfViewer';
|
|
8
|
+
export * from './PdfViewerModel';
|
|
9
|
+
export type * from './Types';
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* This file belongs to Hoist, an application development toolkit
|
|
3
|
+
* developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
|
|
4
|
+
*
|
|
5
|
+
* Copyright © 2026 Extremely Heavy Industries Inc.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
.xh-stat-card-strip {
|
|
9
|
+
display: flex;
|
|
10
|
+
flex: none;
|
|
11
|
+
flex-wrap: wrap;
|
|
12
|
+
gap: var(--xh-stat-card-strip-gap);
|
|
13
|
+
padding: var(--xh-stat-card-strip-padding);
|
|
14
|
+
|
|
15
|
+
// Equal shares of the strip, regardless of content width. A card's minimum width - its value, or
|
|
16
|
+
// the floor set on its header - decides when cards wrap to a new row.
|
|
17
|
+
> .xh-stat-card {
|
|
18
|
+
flex: 1 1 0;
|
|
19
|
+
|
|
20
|
+
> .xh-stat-card__header {
|
|
21
|
+
min-width: var(--xh-stat-card-min-content-width);
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
// The title and detail report no intrinsic width (`contain: inline-size`), so they truncate
|
|
25
|
+
// rather than set the card's minimum width. Only in a strip - a card on its own sizes to all
|
|
26
|
+
// of its lines.
|
|
27
|
+
> .xh-stat-card__header,
|
|
28
|
+
> .xh-stat-card__detail {
|
|
29
|
+
contain: inline-size;
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
// Set when the cards no longer fit on one row. The component measures the column count, so later
|
|
34
|
+
// rows line up under the first instead of stretching to fill.
|
|
35
|
+
&--grid {
|
|
36
|
+
display: grid;
|
|
37
|
+
grid-template-columns: repeat(var(--xh-stat-card-strip-columns), minmax(0, 1fr));
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
.xh-stat-card {
|
|
42
|
+
display: flex;
|
|
43
|
+
flex-direction: column;
|
|
44
|
+
// Main (vertical) axis - when a strip stretches a card to its tallest neighbor, split the slack
|
|
45
|
+
// above and below so the text of adjacent cards reads as one row.
|
|
46
|
+
justify-content: center;
|
|
47
|
+
position: relative;
|
|
48
|
+
// Clip, not hidden - a flex item that is a scroll container loses its content-based minimum
|
|
49
|
+
// width, which is what keeps a card from getting narrower than its value.
|
|
50
|
+
overflow: clip;
|
|
51
|
+
padding: var(--xh-stat-card-padding);
|
|
52
|
+
background-color: var(--xh-stat-card-bg);
|
|
53
|
+
border: var(--xh-stat-card-border);
|
|
54
|
+
border-radius: var(--xh-stat-card-border-radius);
|
|
55
|
+
color: var(--xh-text-color);
|
|
56
|
+
|
|
57
|
+
// Swaps in the large-size variables, so the rules below draw both sizes.
|
|
58
|
+
&--large {
|
|
59
|
+
--xh-stat-card-detail-font-size: var(--xh-stat-card-large-detail-font-size);
|
|
60
|
+
--xh-stat-card-min-content-width: var(--xh-stat-card-large-min-content-width);
|
|
61
|
+
--xh-stat-card-padding: var(--xh-stat-card-large-padding);
|
|
62
|
+
--xh-stat-card-sub-value-font-size: var(--xh-stat-card-large-sub-value-font-size);
|
|
63
|
+
--xh-stat-card-title-font-size: var(--xh-stat-card-large-title-font-size);
|
|
64
|
+
--xh-stat-card-value-font-size: var(--xh-stat-card-large-value-font-size);
|
|
65
|
+
--xh-stat-card-value-gap: var(--xh-stat-card-large-value-gap);
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
&--intent-primary {
|
|
69
|
+
border-color: var(--xh-stat-card-primary-color);
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
&--intent-success {
|
|
73
|
+
border-color: var(--xh-stat-card-success-color);
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
&--intent-warning {
|
|
77
|
+
border-color: var(--xh-stat-card-warning-color);
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
&--intent-danger {
|
|
81
|
+
border-color: var(--xh-stat-card-danger-color);
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
// Drawn inside the card's border, so it shows whatever the border is set to and does not shift
|
|
85
|
+
// content between accented and plain cards.
|
|
86
|
+
&--accented::after {
|
|
87
|
+
content: '';
|
|
88
|
+
position: absolute;
|
|
89
|
+
inset: 0;
|
|
90
|
+
pointer-events: none;
|
|
91
|
+
border-color: var(--xh-stat-card-accent-color);
|
|
92
|
+
border-radius: inherit;
|
|
93
|
+
border-style: solid;
|
|
94
|
+
border-width: var(--xh-stat-card-accent-top) var(--xh-stat-card-accent-right)
|
|
95
|
+
var(--xh-stat-card-accent-bottom) var(--xh-stat-card-accent-left);
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
&--clickable {
|
|
99
|
+
cursor: pointer;
|
|
100
|
+
|
|
101
|
+
&:hover {
|
|
102
|
+
background-color: var(--xh-stat-card-hover-bg);
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
&:focus-visible {
|
|
106
|
+
outline: 2px solid var(--xh-focus-outline-color);
|
|
107
|
+
outline-offset: -4px;
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
&__title,
|
|
112
|
+
&__value-primary,
|
|
113
|
+
&__sub-value,
|
|
114
|
+
&__detail {
|
|
115
|
+
min-width: 0;
|
|
116
|
+
overflow: hidden;
|
|
117
|
+
text-overflow: ellipsis;
|
|
118
|
+
white-space: nowrap;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
&__header {
|
|
122
|
+
display: flex;
|
|
123
|
+
align-items: center;
|
|
124
|
+
gap: var(--xh-pad-half-px);
|
|
125
|
+
font-size: var(--xh-stat-card-title-font-size);
|
|
126
|
+
color: var(--xh-stat-card-title-color);
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
&__title {
|
|
130
|
+
flex: 0 1 auto;
|
|
131
|
+
letter-spacing: var(--xh-stat-card-title-letter-spacing);
|
|
132
|
+
text-transform: var(--xh-stat-card-title-text-transform);
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
// Never shrinks - the icon is what advertises its tooltip.
|
|
136
|
+
&__info {
|
|
137
|
+
display: flex;
|
|
138
|
+
flex: none;
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
&__value {
|
|
142
|
+
display: flex;
|
|
143
|
+
align-items: baseline;
|
|
144
|
+
gap: var(--xh-stat-card-value-gap);
|
|
145
|
+
font-size: var(--xh-stat-card-value-font-size);
|
|
146
|
+
font-weight: var(--xh-stat-card-value-font-weight);
|
|
147
|
+
line-height: 1.25;
|
|
148
|
+
// Hold the line's height when there is no value, so cards in a strip stay aligned.
|
|
149
|
+
min-height: 1.25em;
|
|
150
|
+
|
|
151
|
+
// A card shows one figure, not a column of them, so drop the space that `fmtNumber` reserves
|
|
152
|
+
// after a positive ledger value to line it up with the ")" of negatives.
|
|
153
|
+
.xh-ledger-align {
|
|
154
|
+
display: none;
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
&__value-primary {
|
|
159
|
+
flex: 0 1 auto;
|
|
160
|
+
|
|
161
|
+
// A unit appended by `fmtNumber`'s `label` option.
|
|
162
|
+
.xh-units-label {
|
|
163
|
+
font-size: var(--xh-stat-card-sub-value-font-size);
|
|
164
|
+
font-weight: normal;
|
|
165
|
+
color: var(--xh-stat-card-detail-color);
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
// Part of the value line, so it sets the card's minimum width along with the value.
|
|
170
|
+
&__sub-value {
|
|
171
|
+
flex: 0 1 auto;
|
|
172
|
+
font-size: var(--xh-stat-card-sub-value-font-size);
|
|
173
|
+
font-weight: normal;
|
|
174
|
+
color: var(--xh-text-color);
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
&__detail {
|
|
178
|
+
font-size: var(--xh-stat-card-detail-font-size);
|
|
179
|
+
color: var(--xh-stat-card-detail-color);
|
|
180
|
+
}
|
|
181
|
+
}
|