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
@@ -18,7 +18,9 @@
18
18
  */
19
19
 
20
20
  import { datasets } from './sample-data.js';
21
- import { BAND_TYPES, hasBand, findBand } from './structure.js';
21
+ import { bandKeys, findBand } from './structure.js';
22
+ import { kindOf, bandLabel as labelOf } from './grouping.js';
23
+ import { levelsOf } from '../engine/tables.js';
22
24
 
23
25
 
24
26
  /** the placeholder that stands in for the field until one is chosen */
@@ -101,6 +103,16 @@ export const TOKENS = [
101
103
  value: `{max(${FIELD})}`,
102
104
  field: true,
103
105
  aggregate: true
106
+ },
107
+ {
108
+ id: 'percentage',
109
+ prefer: ['groupFooter', 'groupHeader', 'reportFooter'],
110
+ label: 'Percentage of total',
111
+ value: `{percentage(sum(${FIELD}))}`,
112
+ note: "This group's sum as a share of the whole table's - add , parent " +
113
+ 'for a share of the group outside, or , 50000 for a share of a target',
114
+ field: true,
115
+ aggregate: true
104
116
  }
105
117
  ];
106
118
 
@@ -135,7 +147,7 @@ const GROUP_SCOPED = ['groupHeader', 'groupFooter'];
135
147
  export function aggregateScope(token, bandType) {
136
148
  if (!token?.aggregate) return null;
137
149
 
138
- return GROUP_SCOPED.includes(bandType) ? 'group' : 'report';
150
+ return GROUP_SCOPED.includes(kindOf(bandType)) ? 'group' : 'report';
139
151
  }
140
152
 
141
153
 
@@ -149,7 +161,7 @@ export function resolvesIn(token, bandType) {
149
161
  if (!token) return false;
150
162
  if (!token.bands?.length) return true;
151
163
 
152
- return token.bands.includes(bandType);
164
+ return token.bands.includes(kindOf(bandType));
153
165
  }
154
166
 
155
167
 
@@ -186,11 +198,15 @@ export function availableFields(layout) {
186
198
 
187
199
  if (layout?.groupBy) found.add(layout.groupBy);
188
200
 
189
- /** a table grouped by a field of its own */
201
+ /** a table grouped by a field of its own, either way it says so */
190
202
  for (const band of (Array.isArray(layout?.bands) ? layout.bands : [])) {
191
203
  for (const item of (band.items || [])) {
192
- if (item?.type === 'table' && typeof item.groupBy === 'string' && item.groupBy) {
193
- found.add(item.groupBy);
204
+ if (item?.type !== 'table') continue;
205
+
206
+ if (typeof item.groupBy === 'string' && item.groupBy) found.add(item.groupBy);
207
+
208
+ for (const level of levelsOf(item)) {
209
+ if (typeof level?.by === 'string' && level.by) found.add(level.by);
194
210
  }
195
211
  }
196
212
  }
@@ -206,16 +222,19 @@ export function availableFields(layout) {
206
222
  * not exist would be offering to create one as a side effect of inserting a
207
223
  * page number.
208
224
  *
225
+ * A grouped table's own group bands are offered by their keys, beside the
226
+ * report's bands of the same kind.
227
+ *
209
228
  * @param {object} layout
210
229
  * @param {object} token
211
- * @returns {string[]} band types, in page order
230
+ * @returns {string[]} band keys, in page order
212
231
  */
213
232
  export function bandChoices(layout, token) {
214
- const present = BAND_TYPES.filter(type => hasBand(layout, type));
233
+ const present = bandKeys(layout);
215
234
 
216
235
  if (!token?.bands?.length) return present;
217
236
 
218
- const allowed = present.filter(type => token.bands.includes(type));
237
+ const allowed = present.filter(key => token.bands.includes(kindOf(key)));
219
238
 
220
239
  /**
221
240
  * A report with no footer band gets the full list rather than an empty one,
@@ -253,7 +272,15 @@ export function defaultBand(layout, token, current = null) {
253
272
  * be selected at the time.
254
273
  */
255
274
  for (const type of (token?.prefer ?? [])) {
256
- if (choices.includes(type)) return type;
275
+ /**
276
+ * A kind, which may be several bands: a subtotal asked for while
277
+ * working on one table's groups goes in that table's footer, not the
278
+ * first grouped table's.
279
+ */
280
+ if (current && kindOf(current) === type && choices.includes(current)) return current;
281
+
282
+ const first = choices.find(key => kindOf(key) === type);
283
+ if (first) return first;
257
284
  }
258
285
 
259
286
  if (current && choices.includes(current) && resolvesIn(token, current)) {
@@ -289,5 +316,5 @@ export function tokenItem(token, field) {
289
316
 
290
317
  /** the band an insert would land on, for the dialog to name */
291
318
  export function bandLabel(layout, type) {
292
- return findBand(layout, type) ? type : null;
319
+ return findBand(layout, type) ? labelOf(type) : null;
293
320
  }
@@ -0,0 +1,487 @@
1
+ /**
2
+ * calculate.js works out a table's calculated columns: a column that shows the
3
+ * result of a calculation over its row rather than a field from the data.
4
+ *
5
+ * { "field": "amount", "label": "Amount", "expression": "{qty} * {price}" }
6
+ *
7
+ * The result is written onto a copy of each row under the column's field, once,
8
+ * before anything else reads the rows - so a calculated column is a field like
9
+ * any other from then on: it is formatted, highlighted, summed by {sum(amount)},
10
+ * grouped and sorted by, measured, searched and exported without any of those
11
+ * knowing it was calculated.
12
+ *
13
+ * The language is small, and read here - nothing is ever handed to eval:
14
+ *
15
+ * {qty} {customer.discount} a field of the row
16
+ * 12 0.18 a number
17
+ * + - * / % ( ) arithmetic, the usual precedence
18
+ * round(x) round(x, 2) to whole numbers, or to places
19
+ * abs(x)
20
+ * sum(x) avg(x) min(x) max(x) count()
21
+ * over every row of the table - sum({total}),
22
+ * or of a calculation, sum({qty} * {price})
23
+ * min(a, b, …) max(a, b, …) the smallest or largest of several values
24
+ * percentage(x) this row's x as a share of x over every row
25
+ * percentage(x, group) … of x over the rows of the row's own group
26
+ * percentage(x, of) … of any other value: a target, a total
27
+ *
28
+ * A calculation whose inputs are not numbers - a blank, a name - is blank, as
29
+ * is anything divided by zero. Columns are worked out left to right, so one can
30
+ * use another's result.
31
+ */
32
+
33
+
34
+ import { toNumber } from './format.js';
35
+ import { levelsOf } from './tables.js';
36
+
37
+
38
+ /** the functions that take every row of the table rather than this one */
39
+ const AGGREGATES = ['sum', 'avg', 'count', 'min', 'max'];
40
+
41
+ /** the functions that take values */
42
+ const FUNCTIONS = ['round', 'abs', 'min', 'max', 'percentage'];
43
+
44
+
45
+ /**
46
+ * A calculation, read - or the reason it cannot be.
47
+ * @param {string} expression
48
+ * @returns {{ast: object}|{error: string}}
49
+ */
50
+ export function parseExpression(expression) {
51
+ if (typeof expression !== 'string' || expression.trim() === '') {
52
+ return { error: 'is empty' };
53
+ }
54
+
55
+ try {
56
+ const parser = createParser(tokenize(expression));
57
+ const ast = parser.expression();
58
+ parser.end();
59
+ return { ast };
60
+ } catch (error) {
61
+ return { error: error.message };
62
+ }
63
+ }
64
+
65
+
66
+ /**
67
+ * The fields a calculation reads, for the designer's sample data and its field
68
+ * lists - `{qty} * {price}` reads qty and price.
69
+ * @param {string} expression
70
+ * @returns {string[]}
71
+ */
72
+ export function expressionFields(expression) {
73
+ const found = new Set();
74
+ for (const [, name] of String(expression ?? '').matchAll(/\{([^{}]+)\}/g)) {
75
+ found.add(name.trim());
76
+ }
77
+ return [...found];
78
+ }
79
+
80
+
81
+ /**
82
+ * Whether a column is calculated.
83
+ * @param {object} column
84
+ * @returns {boolean}
85
+ */
86
+ export function isCalculated(column) {
87
+ return typeof column?.expression === 'string' && column.expression.trim() !== '';
88
+ }
89
+
90
+
91
+ /**
92
+ * A table's rows with its calculated columns filled in.
93
+ *
94
+ * The rows given are the host's data, and are not touched: a table with a
95
+ * calculated column reads copies, and one without reads the rows themselves,
96
+ * as it always has.
97
+ *
98
+ * @param {object} table
99
+ * @param {object[]} rows
100
+ * @returns {object[]}
101
+ */
102
+ export function calculatedRows(table, rows) {
103
+ const columns = (Array.isArray(table?.columns) ? table.columns : []).filter(isCalculated);
104
+ if (columns.length === 0 || !Array.isArray(rows)) return rows;
105
+
106
+ let current = rows.map(row => ({ ...row }));
107
+
108
+ for (const column of columns) {
109
+ const parsed = parseExpression(column.expression);
110
+
111
+ /** validate.js says what is wrong; here the column is only left blank */
112
+ if (parsed.error) {
113
+ for (const row of current) row[column.field] = null;
114
+ continue;
115
+ }
116
+
117
+ const context = createContext(table, current);
118
+ const values = current.map(row => evaluate(parsed.ast, row, context));
119
+ current.forEach((row, n) => { row[column.field] = values[n]; });
120
+
121
+ current = [...current];
122
+ }
123
+
124
+ return current;
125
+ }
126
+
127
+
128
+ /* ---------------- reading ---------------- */
129
+
130
+
131
+ /**
132
+ * The calculation in pieces: numbers, fields, names, and the marks between.
133
+ * @param {string} source
134
+ * @returns {{type: string, value: *, at: number}[]}
135
+ */
136
+ function tokenize(source) {
137
+ const tokens = [];
138
+ let i = 0;
139
+
140
+ while (i < source.length) {
141
+ const ch = source[i];
142
+
143
+ if (/\s/.test(ch)) { i++; continue; }
144
+
145
+ if (ch === '{') {
146
+ const end = source.indexOf('}', i);
147
+ if (end === -1) throw new Error(`has a { at ${i + 1} that is never closed`);
148
+
149
+ const name = source.slice(i + 1, end).trim();
150
+ if (!name) throw new Error(`has an empty {} at ${i + 1}`);
151
+
152
+ tokens.push({ type: 'field', value: name, at: i });
153
+ i = end + 1;
154
+ continue;
155
+ }
156
+
157
+ const number = /^\d+(\.\d+)?|^\.\d+/.exec(source.slice(i));
158
+ if (number) {
159
+ tokens.push({ type: 'number', value: Number(number[0]), at: i });
160
+ i += number[0].length;
161
+ continue;
162
+ }
163
+
164
+ const name = /^[A-Za-z_]\w*/.exec(source.slice(i));
165
+ if (name) {
166
+ tokens.push({ type: 'name', value: name[0], at: i });
167
+ i += name[0].length;
168
+ continue;
169
+ }
170
+
171
+ if ('+-*/%(),'.includes(ch)) {
172
+ tokens.push({ type: ch, value: ch, at: i });
173
+ i++;
174
+ continue;
175
+ }
176
+
177
+ throw new Error(`cannot read "${ch}" at ${i + 1}`);
178
+ }
179
+
180
+ return tokens;
181
+ }
182
+
183
+
184
+ /**
185
+ * A recursive-descent reader: expression > term > unary > primary, so * binds
186
+ * tighter than +, and a minus in front binds tightest of all.
187
+ */
188
+ function createParser(tokens) {
189
+ let at = 0;
190
+
191
+ const peek = () => tokens[at];
192
+ const take = (type) => (peek()?.type === type ? tokens[at++] : null);
193
+ const want = (type, what) => {
194
+ const token = take(type);
195
+ if (!token) throw new Error(`expects ${what}${where()}`);
196
+ return token;
197
+ };
198
+ const where = () => (peek() ? ` at ${peek().at + 1}` : ' at the end');
199
+
200
+ function expression() {
201
+ let node = term();
202
+ for (let op = peek()?.type; op === '+' || op === '-'; op = peek()?.type) {
203
+ at++;
204
+ node = { kind: 'binary', op, left: node, right: term() };
205
+ }
206
+ return node;
207
+ }
208
+
209
+ function term() {
210
+ let node = unary();
211
+ for (let op = peek()?.type; op === '*' || op === '/' || op === '%'; op = peek()?.type) {
212
+ at++;
213
+ node = { kind: 'binary', op, left: node, right: unary() };
214
+ }
215
+ return node;
216
+ }
217
+
218
+ function unary() {
219
+ if (take('-')) return { kind: 'negate', value: unary() };
220
+ if (take('+')) return unary();
221
+ return primary();
222
+ }
223
+
224
+ function primary() {
225
+ const token = peek();
226
+ if (!token) throw new Error('ends where a value is expected');
227
+
228
+ if (take('number')) return { kind: 'number', value: token.value };
229
+ if (take('field')) return { kind: 'field', name: token.value };
230
+
231
+ if (take('(')) {
232
+ const node = expression();
233
+ want(')', 'a )');
234
+ return node;
235
+ }
236
+
237
+ if (take('name')) {
238
+ const name = token.value;
239
+
240
+ if (name === 'group') {
241
+ throw new Error(`uses "group" at ${token.at + 1}, which only means anything in percentage(x, group)`);
242
+ }
243
+ if (!FUNCTIONS.includes(name) && !AGGREGATES.includes(name)) {
244
+ throw new Error(`has no function called "${name}" - it knows ` +
245
+ `${[...new Set([...FUNCTIONS, ...AGGREGATES])].join(', ')}`);
246
+ }
247
+
248
+ want('(', `a ( after ${name}`);
249
+ const args = [];
250
+
251
+ if (!take(')')) {
252
+ do {
253
+ /** `group` is a word percentage() takes, not a value */
254
+ if (name === 'percentage' && args.length === 1 && peek()?.type === 'name'
255
+ && peek().value === 'group') {
256
+ at++;
257
+ args.push({ kind: 'group' });
258
+ } else {
259
+ args.push(expression());
260
+ }
261
+ } while (take(','));
262
+ want(')', `a ) to close ${name}(`);
263
+ }
264
+
265
+ return call(name, args, token);
266
+ }
267
+
268
+ throw new Error(`does not expect "${token.value}"${where()}`);
269
+ }
270
+
271
+ /** a call, checked for the number of values it takes */
272
+ function call(name, args, token) {
273
+ const count = args.length;
274
+ const at = ` at ${token.at + 1}`;
275
+
276
+ if (name === 'count') {
277
+ if (count !== 0) throw new Error(`gives count() nothing - it counts rows${at}`);
278
+ return { kind: 'aggregate', fn: 'count', value: null };
279
+ }
280
+
281
+ if ((name === 'min' || name === 'max') && count > 1) {
282
+ return { kind: 'call', fn: name, args };
283
+ }
284
+
285
+ if (AGGREGATES.includes(name)) {
286
+ if (count !== 1) throw new Error(`gives ${name}() one value${at}`);
287
+ return { kind: 'aggregate', fn: name, value: args[0] };
288
+ }
289
+
290
+ if (name === 'round' && (count < 1 || count > 2)) throw new Error(`gives round() a value and, if you like, places${at}`);
291
+ if (name === 'abs' && count !== 1) throw new Error(`gives abs() one value${at}`);
292
+ if (name === 'percentage' && (count < 1 || count > 2)) {
293
+ throw new Error(`gives percentage() a value and, if you like, what it is a share of${at}`);
294
+ }
295
+
296
+ return { kind: 'call', fn: name, args };
297
+ }
298
+
299
+ return {
300
+ expression,
301
+ end() {
302
+ if (peek()) throw new Error(`has "${peek().value}" left over at ${peek().at + 1}`);
303
+ }
304
+ };
305
+ }
306
+
307
+
308
+ /* ---------------- working out ---------------- */
309
+
310
+
311
+ /**
312
+ * What evaluate needs beyond the row: every row of the table, the rows of the
313
+ * row's own group, and the totals already worked out - an aggregate over every
314
+ * row is the same for every row, and is worked out once.
315
+ */
316
+ function createContext(table, rows) {
317
+ const levels = levelsOf(table).map(level => level?.by).filter(Boolean);
318
+ const groupKey = (row) => levels.map(by => String(row?.[by])).join('\u0000');
319
+
320
+ const groups = new Map();
321
+ if (levels.length) {
322
+ for (const row of rows) {
323
+ const key = groupKey(row);
324
+ if (!groups.has(key)) groups.set(key, []);
325
+ groups.get(key).push(row);
326
+ }
327
+ }
328
+
329
+ return {
330
+ rows,
331
+ groupOf: (row) => (levels.length ? groups.get(groupKey(row)) ?? [row] : rows),
332
+ groupKey,
333
+ cache: new Map()
334
+ };
335
+ }
336
+
337
+
338
+ /**
339
+ * One row's value for a calculation: a number, or null where it has none.
340
+ * @param {object} node
341
+ * @param {object} row
342
+ * @param {object} context
343
+ * @returns {number|null}
344
+ */
345
+ function evaluate(node, row, context) {
346
+ switch (node.kind) {
347
+ case 'number':
348
+ return node.value;
349
+
350
+ case 'field':
351
+ return toNumber(lookup(row, node.name));
352
+
353
+ case 'negate': {
354
+ const value = evaluate(node.value, row, context);
355
+ return value === null ? null : -value;
356
+ }
357
+
358
+ case 'binary': {
359
+ const a = evaluate(node.left, row, context);
360
+ const b = evaluate(node.right, row, context);
361
+ if (a === null || b === null) return null;
362
+
363
+ switch (node.op) {
364
+ case '+': return round(a + b);
365
+ case '-': return round(a - b);
366
+ case '*': return round(a * b);
367
+ case '/': return b === 0 ? null : round(a / b);
368
+ case '%': return b === 0 ? null : round(a % b);
369
+ }
370
+ return null;
371
+ }
372
+
373
+ case 'aggregate':
374
+ return aggregate(node, context.rows, context, 'all');
375
+
376
+ case 'call':
377
+ return callFunction(node, row, context);
378
+
379
+ default:
380
+ return null;
381
+ }
382
+ }
383
+
384
+
385
+ /**
386
+ * An aggregate over some rows, worked out once per scope - 'all' for the whole
387
+ * table, or one group's key - however many rows ask for it.
388
+ */
389
+ function aggregate(node, rows, context, scope) {
390
+ if (!context.cache.has(node)) context.cache.set(node, new Map());
391
+ const known = context.cache.get(node);
392
+ if (known.has(scope)) return known.get(scope);
393
+
394
+ let result;
395
+
396
+ if (node.fn === 'count') {
397
+ result = rows.length;
398
+ } else {
399
+ const values = rows.map(r => evaluate(node.value, r, context)).filter(v => v !== null);
400
+
401
+ if (!values.length) result = null;
402
+ else if (node.fn === 'sum') result = round(values.reduce((a, b) => a + b, 0));
403
+ else if (node.fn === 'avg') result = round(values.reduce((a, b) => a + b, 0) / values.length);
404
+ else if (node.fn === 'min') result = Math.min(...values);
405
+ else if (node.fn === 'max') result = Math.max(...values);
406
+ else result = null;
407
+ }
408
+
409
+ known.set(scope, result);
410
+ return result;
411
+ }
412
+
413
+
414
+ /** the sum a percentage() divides by: one node per percentage, so its total is cached */
415
+ const SHARE_TOTALS = new WeakMap();
416
+
417
+ function shareTotal(node) {
418
+ if (!SHARE_TOTALS.has(node)) {
419
+ SHARE_TOTALS.set(node, { kind: 'aggregate', fn: 'sum', value: node.args[0] });
420
+ }
421
+ return SHARE_TOTALS.get(node);
422
+ }
423
+
424
+
425
+ function callFunction(node, row, context) {
426
+ const value = (n) => evaluate(node.args[n], row, context);
427
+
428
+ switch (node.fn) {
429
+ case 'abs': {
430
+ const x = value(0);
431
+ return x === null ? null : Math.abs(x);
432
+ }
433
+
434
+ case 'round': {
435
+ const x = value(0);
436
+ const places = node.args.length > 1 ? value(1) : 0;
437
+ if (x === null || places === null) return null;
438
+
439
+ const factor = 10 ** Math.max(0, Math.min(10, Math.round(places)));
440
+ return Math.round((x + Number.EPSILON * Math.sign(x)) * factor) / factor;
441
+ }
442
+
443
+ case 'min':
444
+ case 'max': {
445
+ const values = node.args.map((_, n) => value(n));
446
+ if (values.some(v => v === null)) return null;
447
+ return node.fn === 'min' ? Math.min(...values) : Math.max(...values);
448
+ }
449
+
450
+ case 'percentage': {
451
+ const part = value(0);
452
+ if (part === null) return null;
453
+
454
+ const of = node.args[1];
455
+ let whole;
456
+
457
+ if (!of) {
458
+ /** the same calculation, added up over every row */
459
+ whole = aggregate(shareTotal(node), context.rows, context, 'all');
460
+ } else if (of.kind === 'group') {
461
+ /** … over the rows of this row's own group */
462
+ whole = aggregate(shareTotal(node), context.groupOf(row), context,
463
+ `group:${context.groupKey(row)}`);
464
+ } else {
465
+ whole = value(1);
466
+ }
467
+
468
+ if (whole === null || whole === 0) return null;
469
+ return round(part / whole);
470
+ }
471
+
472
+ default:
473
+ return null;
474
+ }
475
+ }
476
+
477
+
478
+ /** a dotted path into the row - `customer.discount` */
479
+ function lookup(row, path) {
480
+ return path.split('.').reduce((node, part) => node?.[part], row);
481
+ }
482
+
483
+
484
+ /** twelve significant digits: 0.1 + 0.2 is 0.3 on a report */
485
+ function round(n) {
486
+ return Number.isFinite(n) ? Number(n.toPrecision(12)) : null;
487
+ }
package/src/engine/csv.js CHANGED
@@ -18,7 +18,8 @@
18
18
  * the encoding.
19
19
  */
20
20
 
21
- import { reportRows, tableRows, columnLabel } from './rows.js';
21
+ import { reportRows, tableRows, columnLabel, groupColumns } from './rows.js';
22
+ import { formatValue } from './format.js';
22
23
 
23
24
  export { reportTables } from './rows.js';
24
25
 
@@ -38,7 +39,12 @@ const FORMULA_LEAD = /^[=+\-@\t\r]/;
38
39
  * @param {string} [options.newline='\r\n'] RFC 4180 line ending
39
40
  * @param {boolean} [options.header=true] emit the column labels as the first row
40
41
  * @param {boolean} [options.groupColumn=true] prepend the group key on a grouped report
41
- * @param {string} [options.groupLabel='Group']
42
+ * @param {string|string[]} [options.groupLabel='Group'] the group column's
43
+ * heading; a list heads one column per level of a nested grouping, which
44
+ * otherwise takes the names of the fields it groups by
45
+ * @param {boolean} [options.formatted=false] write each cell as the report
46
+ * prints it - ₹1,00,000.00, 17/06/2026 - rather than the value itself, which
47
+ * is what another program reading the file wants
42
48
  * @param {boolean} [options.neutraliseFormulas=true] see below
43
49
  * @returns {string} CSV text, empty when the report holds no such table
44
50
  */
@@ -50,26 +56,28 @@ export function toCSV(pages, options = {}) {
50
56
  groupColumn = true,
51
57
  groupLabel = 'Group',
52
58
  neutraliseFormulas = true,
59
+ formatted = false,
53
60
  table: only = null
54
61
  } = options;
55
62
 
56
63
  const table = tableRows(pages, only);
57
64
  if (!table) return '';
58
65
 
59
- const grouped = groupColumn && table.rows.some(r => r.group !== null);
66
+ /** one column per level a table is grouped at; none when it is not, or when asked */
67
+ const groups = groupColumn ? groupColumns(table, groupLabel) : { labels: [], cells: () => [] };
60
68
  const labels = table.columns.map(columnLabel);
61
69
 
62
70
  const lines = [];
63
71
 
64
72
  if (header) {
65
- lines.push(encodeRow(grouped ? [groupLabel, ...labels] : labels,
66
- delimiter, neutraliseFormulas));
73
+ lines.push(encodeRow([...groups.labels, ...labels], delimiter, neutraliseFormulas));
67
74
  }
68
75
 
69
- for (const { group, row } of table.rows) {
70
- const cells = table.columns.map(c => row?.[c.field]);
71
- lines.push(encodeRow(grouped ? [group, ...cells] : cells,
72
- delimiter, neutraliseFormulas));
76
+ for (const entry of table.rows) {
77
+ const cells = table.columns.map(c => formatted
78
+ ? formatValue(entry.row?.[c.field], c.format)
79
+ : entry.row?.[c.field]);
80
+ lines.push(encodeRow([...groups.cells(entry), ...cells], delimiter, neutraliseFormulas));
73
81
  }
74
82
 
75
83
  return lines.join(newline);