report-studio 1.2.0 → 1.2.2

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/README.md CHANGED
@@ -5,10 +5,12 @@ JS or React.**
5
5
 
6
6
  ![Adding a text box in the designer, saving, and running the report](https://raw.githubusercontent.com/Shafickbinameer/report-studio/main/.github/demo.gif)
7
7
 
8
+ **[Try it live on StackBlitz](https://stackblitz.com/github/Shafickbinameer/report-studio/tree/main/examples/demo?file=src%2Fmain.js)**: the viewer and the designer in a Vite app, nothing to install.
9
+
8
10
  You draw the report once in a visual designer — headers, footers, groups,
9
11
  tables, text, images — and it is saved as a plain JSON file. At runtime your
10
12
  app feeds that layout its own data and gets back a page-by-page report viewer,
11
- with navigation, zoom, search, print and CSV export.
13
+ with navigation, zoom, search, print, CSV and Excel export.
12
14
 
13
15
  * **Zero runtime dependencies.** The renderer is plain DOM. No server to run,
14
16
  no framework required.
@@ -207,6 +209,32 @@ For CSV, the viewer's export writes every table in the order they print. From
207
209
  code, `toCSV(pages, { table: 'refunds' })` writes one table, and
208
210
  `reportTables(pages)` lists the tables a report has.
209
211
 
212
+ For Excel, the export writes an `.xlsx` workbook with no extra dependency. It
213
+ has a *Report* sheet that reads like the report, plus one sheet per table with
214
+ a frozen, filterable header row. Numbers, booleans and dates in your data stay
215
+ numbers, booleans and dates.
216
+
217
+ The workbook keeps the report's look: fonts, sizes, colours, alignment, cell
218
+ padding, the table grid and header colours, row heights and column widths. On
219
+ the *Report* sheet each text item goes in the column under where it sits on the
220
+ page (the table columns are the grid), rows are spaced like the page, and
221
+ pictures, lines and boxes are drawn where the page has them, rounded corners
222
+ included. A box with text on it paints its fill into the cells underneath,
223
+ because Excel draws shapes above cells and a filled shape would hide the text.
224
+ A text item that prints only a placeholder's number, such as `{sum(amount)}`,
225
+ becomes a real number you can add up.
226
+
227
+ Pictures stored in the layout as `data:` URIs are embedded straight away.
228
+ Pictures loaded from URLs have to be fetched first, so the viewer's Excel
229
+ download starts a moment later for those reports. PNG, JPEG, GIF and BMP are
230
+ embedded; WebP and AVIF are left out.
231
+
232
+ From code, `toXLSX(pages)` returns the file's bytes (empty when there is
233
+ nothing to write); it embeds `data:` pictures only. `await toXLSXAsync(pages)`
234
+ fetches URL pictures first, and `reportImageSources(pages)` lists the URLs it
235
+ would fetch. Pass `{ report: false }` or `{ tables: false }` to leave a kind of
236
+ sheet out, or `{ styled: false }` for plain data with bold headers.
237
+
210
238
  ### Images
211
239
 
212
240
  An image item can get its picture in two ways:
@@ -252,6 +280,10 @@ import 'report-studio/viewer.css';
252
280
  | `report-studio/designer.css` | the designer's styles, likewise |
253
281
  | `report-studio/report.css` | the report alone, for drawing pages with no chrome |
254
282
 
283
+ The stylesheets style only what the viewer and designer draw. Your page's
284
+ fonts, margins and CSS variables are left alone. The toolbar rearranges itself
285
+ when the viewer is narrow, whether it is on a phone or in a side panel.
286
+
255
287
  ## React
256
288
 
257
289
  React components are included. React itself is not bundled: install it
@@ -283,7 +315,7 @@ function SalesReport({ layout, sales }) {
283
315
  * A layout or data the engine can't use throws a `ReportError` while
284
316
  rendering. Wrap the component in an error boundary to show it.
285
317
  * A `ref` gives you the viewer's controls: `next()`, `prev()`, `show(index)`,
286
- `find(text)`, `print()`, `downloadCSV()`, `setZoom(n)`, `fitWidth()`, and
318
+ `find(text)`, `print()`, `downloadCSV()`, `downloadXLSX()`, `setZoom(n)`, `fitWidth()`, and
287
319
  `page`, `pageCount` and `zoom`.
288
320
 
289
321
  The designer is a separate import, like the plain-JS one:
@@ -362,6 +394,10 @@ const store = {
362
394
  id. `loadData` must resolve to `null`, not throw, when a report has no data
363
395
  file yet: that is an ordinary state, not a failure.
364
396
 
397
+ Give the mount element a height, as you do for the viewer. The designer fills
398
+ it, so your own header or tabs can sit above it. An element with no height
399
+ gets the full window.
400
+
365
401
  `createDesigner` returns a handle with the current `layout`, `redraw()` and
366
402
  `destroy()`. `openDesignerWindow(options)` opens the same designer in a window
367
403
  of its own, for the same reason `openViewerWindow` does.