report-studio 1.2.2 → 1.3.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/README.md +254 -3
- package/dist/designer-Dj330bWd.js +4690 -0
- package/dist/designer.js +1 -1
- package/dist/index.js +2 -2
- package/dist/react-designer.js +1 -1
- package/dist/react.js +1 -1
- package/dist/viewer-BewnkhfP.js +4028 -0
- package/package.json +2 -2
- package/src/designer/blank.js +0 -1
- package/src/designer/canvas.js +172 -54
- package/src/designer/designer.js +313 -12
- package/src/designer/dialog.js +609 -5
- package/src/designer/fields.js +128 -11
- package/src/designer/geometry.js +77 -4
- package/src/designer/grouping.js +556 -0
- package/src/designer/icons.js +9 -0
- package/src/designer/menu.js +50 -6
- package/src/designer/panel.js +478 -38
- package/src/designer/rulers.js +14 -6
- package/src/designer/sample-data.js +112 -31
- package/src/designer/select.js +3 -2
- package/src/designer/structure.js +126 -12
- package/src/designer/styles.css +661 -27
- package/src/designer/tokens.js +38 -11
- package/src/engine/calculate.js +487 -0
- package/src/engine/csv.js +17 -9
- package/src/engine/format.js +483 -0
- package/src/engine/group.js +350 -70
- package/src/engine/highlight.js +224 -0
- package/src/engine/index.js +8 -1
- package/src/engine/measure.js +53 -26
- package/src/engine/paginate.js +189 -92
- package/src/engine/resolve.js +117 -10
- package/src/engine/rows.js +71 -8
- package/src/engine/search.js +12 -4
- package/src/engine/tables.js +309 -11
- package/src/engine/validate.js +265 -8
- package/src/engine/xlsx-style.js +50 -4
- package/src/engine/xlsx.js +91 -21
- package/src/index.js +18 -0
- package/src/render/items.js +61 -10
- package/src/render/report.css +0 -5
- package/types/index.d.ts +96 -8
- package/types/layout.d.ts +156 -2
- package/dist/designer-DQlfKnTr.js +0 -3416
- package/dist/viewer-BSPNCNRU.js +0 -2912
package/README.md
CHANGED
|
@@ -201,9 +201,8 @@ Totals can name the dataset they add up:
|
|
|
201
201
|
The named dataset does not need a table of its own. Any array in the data can
|
|
202
202
|
be totalled this way.
|
|
203
203
|
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
and footer bands are shared, which is why only one table can use them.
|
|
204
|
+
Any number of tables can be grouped, each by a field of its own — see
|
|
205
|
+
[Grouping](#grouping).
|
|
207
206
|
|
|
208
207
|
For CSV, the viewer's export writes every table in the order they print. From
|
|
209
208
|
code, `toCSV(pages, { table: 'refunds' })` writes one table, and
|
|
@@ -235,6 +234,258 @@ fetches URL pictures first, and `reportImageSources(pages)` lists the URLs it
|
|
|
235
234
|
would fetch. Pass `{ report: false }` or `{ tables: false }` to leave a kind of
|
|
236
235
|
sheet out, or `{ styled: false }` for plain data with bold headers.
|
|
237
236
|
|
|
237
|
+
### Grouping
|
|
238
|
+
|
|
239
|
+
Set *Group by* on a table and its rows are split into groups by that field.
|
|
240
|
+
Each grouped table has its own group header, drawn above each group, and group
|
|
241
|
+
footer, drawn under it, so two grouped tables can look different and total
|
|
242
|
+
different things. In the layout file a table carries them as `grouping`:
|
|
243
|
+
|
|
244
|
+
```json
|
|
245
|
+
{
|
|
246
|
+
"type": "table", "id": "refunds", "dataset": "refunds",
|
|
247
|
+
"grouping": [{
|
|
248
|
+
"by": "reason",
|
|
249
|
+
"header": { "height": 24, "items": [ { "id": "reason", "type": "text", "value": "Reason: {reason}" } ] },
|
|
250
|
+
"footer": { "height": 20, "items": [ { "id": "subtotal", "type": "text", "value": "Subtotal {sum(amount)}" } ] }
|
|
251
|
+
}]
|
|
252
|
+
}
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
Inside a group band, `{reason}` is the group's value and `{sum(amount)}` adds
|
|
256
|
+
up that group's rows only. A group that runs over a page break prints its
|
|
257
|
+
header again on the next page and its footer only once, where it ends. Either
|
|
258
|
+
band may be `null`, but not both.
|
|
259
|
+
|
|
260
|
+
#### Ordering groups, and a page per group
|
|
261
|
+
|
|
262
|
+
By default, groups come in the order their values first appear in the data.
|
|
263
|
+
Each level can change that, either in the layout file or with *Order groups*
|
|
264
|
+
and *New page for each group* in the designer:
|
|
265
|
+
|
|
266
|
+
- `"sort": "asc"` or `"desc"` orders that level's groups by value. Numbers
|
|
267
|
+
sort as numbers, so 9 comes before 10, and "Item 9" comes before "Item 10".
|
|
268
|
+
Inner levels are sorted within each outer group.
|
|
269
|
+
- `"newPage": true` starts every group of that level on a new page, except the
|
|
270
|
+
table's first group. The page repeats the column labels and every level's
|
|
271
|
+
header. A group longer than a page still continues onto the next.
|
|
272
|
+
|
|
273
|
+
#### Groups within groups
|
|
274
|
+
|
|
275
|
+
A table can be grouped more than once — by region, and within each region by
|
|
276
|
+
city. In the designer, select a grouped table and press *Group within each
|
|
277
|
+
group*. Then type the field into *Then group by*. Each level can be moved out
|
|
278
|
+
or removed from there. In the layout file, each level is one more entry in
|
|
279
|
+
`grouping`, with the outermost first:
|
|
280
|
+
|
|
281
|
+
```json
|
|
282
|
+
"grouping": [
|
|
283
|
+
{ "by": "region",
|
|
284
|
+
"header": { "height": 24, "items": [ { "id": "r", "type": "text", "value": "Region {region}" } ] },
|
|
285
|
+
"footer": { "height": 20, "items": [ { "id": "rt", "type": "text", "value": "Region total {sum(amount)}" } ] } },
|
|
286
|
+
{ "by": "city",
|
|
287
|
+
"header": { "height": 20, "items": [ { "id": "c", "type": "text", "value": "{city}" } ] },
|
|
288
|
+
"footer": { "height": 20, "items": [ { "id": "ct", "type": "text", "value": "City total {sum(amount)}" } ] } }
|
|
289
|
+
]
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
- Each inner group sits inside its outer one. "Oslo" under North and "Oslo"
|
|
293
|
+
under South are two separate groups.
|
|
294
|
+
- Each level's aggregates cover its own group. The region footer adds up the
|
|
295
|
+
whole region, and the city footer adds up that city only.
|
|
296
|
+
- Headers print outermost first where their groups start. Footers print
|
|
297
|
+
innermost first where their groups end. The last city of a region prints its
|
|
298
|
+
city footer and then the region footer.
|
|
299
|
+
- The column labels head each outermost group, not every city.
|
|
300
|
+
- A page that continues a group repeats every level's header, so it still shows
|
|
301
|
+
"North › Oslo". The footers that finish a group are kept on the same page as
|
|
302
|
+
its last row.
|
|
303
|
+
- No two levels may group by the same field, and a table may be grouped at
|
|
304
|
+
most 8 levels deep (`MAX_GROUP_LEVELS`).
|
|
305
|
+
- In CSV and XLSX exports, each level gets its own column. The columns are
|
|
306
|
+
named after the fields; pass `groupLabel: ['Region', 'City']` to name them
|
|
307
|
+
yourself.
|
|
308
|
+
|
|
309
|
+
Layouts written before 2.0 group with a report-wide or per-table `groupBy` and
|
|
310
|
+
the report's own *groupHeader* and *groupFooter* bands. They still work
|
|
311
|
+
unchanged, and the designer moves them onto the table when it opens them.
|
|
312
|
+
`normalizeGrouping(layout)` does the same from code.
|
|
313
|
+
|
|
314
|
+
### Number and date formats
|
|
315
|
+
|
|
316
|
+
Select a text item, or look at a table column's card. Then press its **Format**
|
|
317
|
+
button to choose how its values print. You can also right-click a text item
|
|
318
|
+
and choose **Format…**, or right-click a table cell and choose **Format
|
|
319
|
+
"Amount" column…** to format the column under the pointer. The Format Editor
|
|
320
|
+
offers:
|
|
321
|
+
|
|
322
|
+
- **Number, Currency or Percent:** decimal places, digit groups (`1,234,567`,
|
|
323
|
+
Indian `12,34,567`, or none), how negatives show (`-1,234`, `(1,234)` or
|
|
324
|
+
`1,234-`), and how zero shows (`0.00`, `-` or blank). Currency also has a
|
|
325
|
+
symbol, placed before or after the number. Percent multiplies by 100, so
|
|
326
|
+
`0.125` prints as `12.50%`.
|
|
327
|
+
- **Date or Date & time:** a layout such as `dd/MM/yyyy`, `dd-MMM-yyyy` or
|
|
328
|
+
`d MMMM yyyy`, or a pattern of your own built from `yyyy MM MMM dd HH hh mm
|
|
329
|
+
ss a`.
|
|
330
|
+
- **As it comes:** no formatting, which is the default.
|
|
331
|
+
|
|
332
|
+
A sample line shows real values as you choose. In the layout file, a format
|
|
333
|
+
sits on the item or the column:
|
|
334
|
+
|
|
335
|
+
```json
|
|
336
|
+
{ "field": "amount", "label": "Amount", "format": { "type": "currency", "decimals": 0 } }
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
**The report's defaults.** How digits are grouped, the currency symbol and the
|
|
340
|
+
date layout are set once for the whole report, under *Numbers and dates* on the
|
|
341
|
+
report rail (`layout.format`). An item's format only stores what differs from
|
|
342
|
+
them, so changing the report's defaults changes every format that didn't ask
|
|
343
|
+
for something else. A new report is neutral: `1,234,567`, no symbol, and
|
|
344
|
+
`2026-06-17`. **Use Indian** sets `₹`, `1,00,000` and `dd/MM/yyyy` in one
|
|
345
|
+
click.
|
|
346
|
+
|
|
347
|
+
```json
|
|
348
|
+
"format": { "grouping": "indian", "symbol": "₹", "pattern": "dd/MM/yyyy" }
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
What it applies to:
|
|
352
|
+
|
|
353
|
+
- **Table cells.** Each cell prints in its column's format, and row heights are
|
|
354
|
+
measured on the printed text.
|
|
355
|
+
- **Text placeholders, totals and group totals.** In a text item such as
|
|
356
|
+
`Total {sum(amount)}`, every placeholder prints in the item's format, and the
|
|
357
|
+
words stay as typed. `{count()}` always prints as a plain count.
|
|
358
|
+
- **`{today}`** prints in the report's date layout, or the item's own if it has
|
|
359
|
+
a date format.
|
|
360
|
+
- **Dates** come from the data as written (`2026-06-17`), so they never shift a
|
|
361
|
+
day across time zones. Values that aren't the format's type (a name in a
|
|
362
|
+
number column, an impossible date) print as they are.
|
|
363
|
+
- **Excel.** Numbers stay real numbers and dates become real Excel dates, each
|
|
364
|
+
shown with a matching Excel number format, so the workbook still adds up and
|
|
365
|
+
sorts. A text item that is a single placeholder, such as a grand total,
|
|
366
|
+
becomes a formatted number on the Report sheet. Excel has no lakh grouping,
|
|
367
|
+
so Indian grouping uses conditional formats (`[>=10000000]` and
|
|
368
|
+
`[>=100000]`). As a result, a negative number of a lakh or more shows
|
|
369
|
+
international grouping in Excel, and the "zero shows as" choice isn't carried
|
|
370
|
+
over.
|
|
371
|
+
- **CSV** writes the values themselves (`100000`, `2026-06-17`) by default.
|
|
372
|
+
Pass `{ formatted: true }` to write what's printed.
|
|
373
|
+
|
|
374
|
+
`formatValue(value, format, defaults)` and `excelNumberFormat(format, defaults)`
|
|
375
|
+
are exported for hosts that need the same rules.
|
|
376
|
+
|
|
377
|
+
### Calculated columns
|
|
378
|
+
|
|
379
|
+
A column can show a calculation instead of a field: type it into the
|
|
380
|
+
**Calculation** box on the column's card. The result is worked out for each row
|
|
381
|
+
and stored under the column's field, so from then on it behaves like any other
|
|
382
|
+
field. It's formatted and highlighted, totalled by `{sum(amount)}` in any band,
|
|
383
|
+
grouped and sorted by, and exported to Excel and CSV.
|
|
384
|
+
|
|
385
|
+
```json
|
|
386
|
+
{ "field": "amount", "label": "Amount", "expression": "{qty} * {price}", "format": { "type": "currency" } }
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
| Calculation | Gives |
|
|
390
|
+
|---|---|
|
|
391
|
+
| `{qty} * {price}` | arithmetic on fields: `+ - * / %` and brackets |
|
|
392
|
+
| `round({amount} * 0.18, 2)` | GST at 18%, to 2 places |
|
|
393
|
+
| `{amount} + {tax}` | a column can use an earlier column's result |
|
|
394
|
+
| `{amount} - avg({amount})` | how far each row is from the average |
|
|
395
|
+
| `percentage({amount})` | each row's share of the table total |
|
|
396
|
+
| `percentage({amount}, group)` | each row's share of its own group |
|
|
397
|
+
| `percentage({qty}, 500)` | each row as a share of a target |
|
|
398
|
+
| `max({qty}, 1)` / `abs({diff})` | the larger of two values / without the sign |
|
|
399
|
+
|
|
400
|
+
- **Totals over the table:** `sum()`, `avg()`, `min()`, `max()` and `count()`
|
|
401
|
+
work over every row of the table, and can take a calculation themselves:
|
|
402
|
+
`sum({qty} * {price})`.
|
|
403
|
+
- **Missing inputs:** if an input isn't a number (a blank, a name), or a value
|
|
404
|
+
is divided by zero, the result is blank rather than an error.
|
|
405
|
+
- **Errors:** a calculation that can't be read is reported with what's wrong
|
|
406
|
+
and where, for example `expression ends where a value is expected`.
|
|
407
|
+
- **Shares:** a column whose calculation is a `percentage()` prints as a
|
|
408
|
+
percentage unless it has a format of its own.
|
|
409
|
+
- **Your data:** the rows you pass in are never changed; calculated values go
|
|
410
|
+
onto copies.
|
|
411
|
+
|
|
412
|
+
### Percentages
|
|
413
|
+
|
|
414
|
+
`{percentage(...)}` gives a value as a share of another, such as each
|
|
415
|
+
product's share of total sales. It works in any band and prints as a
|
|
416
|
+
percentage.
|
|
417
|
+
|
|
418
|
+
| Placeholder | Means | Example |
|
|
419
|
+
|---|---|---|
|
|
420
|
+
| `{percentage(sum(total))}` | this group's sum ÷ the whole table's | `57.08%` |
|
|
421
|
+
| `{percentage(sum(total), parent)}` | this group's sum ÷ the group outside it (nested grouping) | city as a share of its region |
|
|
422
|
+
| `{percentage(sum(total), 50000)}` | ÷ a target | `112.40%` of target |
|
|
423
|
+
| `{percentage(sum(total), max(total))}` | ÷ another aggregate over the whole table | |
|
|
424
|
+
| `{percentage(1000)}` | a number ÷ the table's money column total | `0.09%` |
|
|
425
|
+
| `{percentage(count())}` | this group's rows ÷ all rows | |
|
|
426
|
+
|
|
427
|
+
- **The part** can be any aggregate (`sum`, `count`, `avg`, `min`, `max`) or a
|
|
428
|
+
plain number. **What it's divided by** is optional: leave it out for the
|
|
429
|
+
whole table's total, or give a number, another aggregate, or `parent`.
|
|
430
|
+
- **A plain number** with nothing to divide by is taken as a share of the
|
|
431
|
+
table's money column: the first column formatted as currency, then as a
|
|
432
|
+
number, then the right-most column that holds numbers.
|
|
433
|
+
- **In a report band** (not a group band), the part is the whole table, so
|
|
434
|
+
`{percentage(sum(total))}` is 100%. Give a target or another aggregate
|
|
435
|
+
instead.
|
|
436
|
+
- **How it prints:** with 2 decimals by default. Give the text item a Percent
|
|
437
|
+
format to change the decimals or the negative style. It prints as a
|
|
438
|
+
percentage even inside a currency-formatted item.
|
|
439
|
+
- **Dividing by zero:** a share of zero, or of a field with no numbers, prints
|
|
440
|
+
blank.
|
|
441
|
+
- **Highlight rules** test the percentage as read (57.08), not the fraction.
|
|
442
|
+
- **Excel:** a text item that is only a percentage goes into Excel as the
|
|
443
|
+
fraction (0.5708) with a `0.00%` format.
|
|
444
|
+
- **Designer:** "Percentage of total" is in the placeholder tool next to Sum
|
|
445
|
+
and the other aggregates.
|
|
446
|
+
|
|
447
|
+
### Conditional formatting
|
|
448
|
+
|
|
449
|
+
Highlight values by what they are, like Crystal Reports' Highlighting Expert:
|
|
450
|
+
show negative amounts in red, shade overdue invoices, mark totals over a
|
|
451
|
+
target in green. Rules can go in three places:
|
|
452
|
+
|
|
453
|
+
- **A table column**, under *Highlight* on its card, or by right-clicking a
|
|
454
|
+
cell and choosing *Highlight "Amount" column…*. A rule tests the cell's
|
|
455
|
+
value or another field of its row, and styles that cell.
|
|
456
|
+
- **A table's rows**, under *Row highlight* on the table's rail, or *Highlight
|
|
457
|
+
rows…* on the right-click menu. A rule tests a field of the row and styles
|
|
458
|
+
every cell in it. A column's own rules are applied on top, so a red figure
|
|
459
|
+
in a shaded row is both.
|
|
460
|
+
- **A text item**, under *Format → Highlight*. A rule tests the value it
|
|
461
|
+
prints (when the item is a single placeholder such as `{sum(amount)}`), or
|
|
462
|
+
any field of the data. In a group footer, it tests that group's own total.
|
|
463
|
+
|
|
464
|
+
Each rule is a condition and a style:
|
|
465
|
+
|
|
466
|
+
```json
|
|
467
|
+
"highlight": [
|
|
468
|
+
{ "when": { "op": "<", "value": 0 }, "style": { "color": "#b3261e", "fontWeight": "bold" } },
|
|
469
|
+
{ "when": { "op": ">=", "value": 100000 }, "style": { "color": "#1d6b3a", "background": "#e6f4ea" } }
|
|
470
|
+
],
|
|
471
|
+
"rowHighlight": [
|
|
472
|
+
{ "when": { "field": "status", "op": "=", "value": "Overdue" }, "style": { "background": "#fdecec" } }
|
|
473
|
+
]
|
|
474
|
+
```
|
|
475
|
+
|
|
476
|
+
- **Rule order.** Rules are checked in order, and only the first one that
|
|
477
|
+
holds is used. The editor's ↑ button changes the order.
|
|
478
|
+
- **Tests:** equals, is not, less/more than, at most/at least, between (both
|
|
479
|
+
ends included), contains, starts with, is empty, is not empty.
|
|
480
|
+
- **How values compare.** Numbers compare as numbers (`"1200"` counts), dates
|
|
481
|
+
by their day, and text ignores case. A word is never ordered against a
|
|
482
|
+
number or a date, so `"Pending" >= 1000` doesn't hold.
|
|
483
|
+
- **Styles:** text colour, fill, bold and italic. A rule changes only what it
|
|
484
|
+
names.
|
|
485
|
+
- **Where it applies.** The page, its row heights (a bold cell is measured
|
|
486
|
+
bold) and both Excel sheets all use the same rules. Excel cells are styled
|
|
487
|
+
as printed; they aren't live Excel conditional formats.
|
|
488
|
+
|
|
238
489
|
### Images
|
|
239
490
|
|
|
240
491
|
An image item can get its picture in two ways:
|