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.
Files changed (46) hide show
  1. package/README.md +254 -3
  2. package/dist/designer-Dj330bWd.js +4690 -0
  3. package/dist/designer.js +1 -1
  4. package/dist/index.js +2 -2
  5. package/dist/react-designer.js +1 -1
  6. package/dist/react.js +1 -1
  7. package/dist/viewer-BewnkhfP.js +4028 -0
  8. package/package.json +2 -2
  9. package/src/designer/blank.js +0 -1
  10. package/src/designer/canvas.js +172 -54
  11. package/src/designer/designer.js +313 -12
  12. package/src/designer/dialog.js +609 -5
  13. package/src/designer/fields.js +128 -11
  14. package/src/designer/geometry.js +77 -4
  15. package/src/designer/grouping.js +556 -0
  16. package/src/designer/icons.js +9 -0
  17. package/src/designer/menu.js +50 -6
  18. package/src/designer/panel.js +478 -38
  19. package/src/designer/rulers.js +14 -6
  20. package/src/designer/sample-data.js +112 -31
  21. package/src/designer/select.js +3 -2
  22. package/src/designer/structure.js +126 -12
  23. package/src/designer/styles.css +661 -27
  24. package/src/designer/tokens.js +38 -11
  25. package/src/engine/calculate.js +487 -0
  26. package/src/engine/csv.js +17 -9
  27. package/src/engine/format.js +483 -0
  28. package/src/engine/group.js +350 -70
  29. package/src/engine/highlight.js +224 -0
  30. package/src/engine/index.js +8 -1
  31. package/src/engine/measure.js +53 -26
  32. package/src/engine/paginate.js +189 -92
  33. package/src/engine/resolve.js +117 -10
  34. package/src/engine/rows.js +71 -8
  35. package/src/engine/search.js +12 -4
  36. package/src/engine/tables.js +309 -11
  37. package/src/engine/validate.js +265 -8
  38. package/src/engine/xlsx-style.js +50 -4
  39. package/src/engine/xlsx.js +91 -21
  40. package/src/index.js +18 -0
  41. package/src/render/items.js +61 -10
  42. package/src/render/report.css +0 -5
  43. package/types/index.d.ts +96 -8
  44. package/types/layout.d.ts +156 -2
  45. package/dist/designer-DQlfKnTr.js +0 -3416
  46. 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
- One table per report can be grouped. Set *Group by* on that table. A layout
205
- with a report-wide *Group by* still groups its first table. The group header
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: