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
@@ -0,0 +1,483 @@
1
+ /**
2
+ * format.js turns a value into the text a report prints, and into the number
3
+ * format a spreadsheet shows it with - one description of a format, read the
4
+ * same way by both, so the page and the workbook cannot disagree.
5
+ *
6
+ * A format is a plain object, carried by a text item or a table column:
7
+ *
8
+ * { type: 'currency', decimals: 2, grouping: 'indian', symbol: '₹' }
9
+ *
10
+ * type 'text' (as it comes - the default), 'number', 'currency',
11
+ * 'percent', 'date' or 'datetime'
12
+ * decimals places after the point, 0 to 6
13
+ * grouping 'international' 100,000 | 'indian' 1,00,000 | 'none' 100000
14
+ * negative 'minus' -1,234 | 'brackets' (1,234) | 'trailing' 1,234-
15
+ * zero 'zero' 0.00 | 'dash' - | 'blank' (nothing)
16
+ * symbol a currency's symbol, such as '₹' or '$'
17
+ * symbolPosition 'before' ₹1,234 | 'after' 1,234 ₹
18
+ * pattern a date's layout, from the tokens in DATE_TOKENS
19
+ *
20
+ * The report has defaults of its own, as `layout.format` - the same keys with
21
+ * no `type` - and an item's format says only what differs. Neutral unless the
22
+ * report says otherwise: international grouping, no symbol, ISO dates.
23
+ *
24
+ * A value that is not of the format's type is printed as it comes: a name in a
25
+ * number column is still a name.
26
+ *
27
+ * Nothing here touches the document or the clock, and the time zone plays no
28
+ * part: a date is printed from its own year, month and day, so `2026-06-17` is
29
+ * the 17th wherever the report is built.
30
+ */
31
+
32
+
33
+ /** what a format says when neither it nor the report says otherwise */
34
+ export const DEFAULT_FORMAT = Object.freeze({
35
+ type: 'text',
36
+ decimals: 2,
37
+ grouping: 'international',
38
+ negative: 'minus',
39
+ zero: 'zero',
40
+ symbol: '',
41
+ symbolPosition: 'before',
42
+ pattern: 'yyyy-MM-dd'
43
+ });
44
+
45
+ /** the report defaults the designer offers in one click */
46
+ export const INDIAN_DEFAULTS = Object.freeze({
47
+ grouping: 'indian',
48
+ symbol: '₹',
49
+ symbolPosition: 'before',
50
+ pattern: 'dd/MM/yyyy'
51
+ });
52
+
53
+ export const FORMAT_TYPES = ['text', 'number', 'currency', 'percent', 'date', 'datetime'];
54
+ export const GROUPINGS = ['international', 'indian', 'none'];
55
+ export const NEGATIVES = ['minus', 'brackets', 'trailing'];
56
+ export const ZEROS = ['zero', 'dash', 'blank'];
57
+ export const SYMBOL_POSITIONS = ['before', 'after'];
58
+
59
+ /**
60
+ * The currency symbols the designer offers, most used here first. Any other
61
+ * text works as a symbol too - the designer takes it as a custom one.
62
+ */
63
+ export const CURRENCY_SYMBOLS = [
64
+ { value: '', label: 'None' },
65
+ { value: '₹', label: '₹ Indian rupee' },
66
+ { value: 'Rs.', label: 'Rs. Rupee' },
67
+ { value: '$', label: '$ Dollar' },
68
+ { value: '€', label: '€ Euro' },
69
+ { value: '£', label: '£ Pound' },
70
+ { value: '¥', label: '¥ Yen / Yuan' },
71
+ { value: 'AED', label: 'AED UAE dirham' },
72
+ { value: 'SAR', label: 'SAR Saudi riyal' },
73
+ { value: 'S$', label: 'S$ Singapore dollar' }
74
+ ];
75
+
76
+ /** the date layouts the designer offers; any other pattern of DATE_TOKENS works too */
77
+ export const DATE_PATTERNS = [
78
+ 'dd/MM/yyyy', 'dd-MMM-yyyy', 'd MMMM yyyy', 'MM/dd/yyyy', 'yyyy-MM-dd'
79
+ ];
80
+
81
+ export const DATETIME_PATTERNS = [
82
+ 'dd/MM/yyyy HH:mm', 'dd/MM/yyyy hh:mm a', 'dd-MMM-yyyy HH:mm', 'yyyy-MM-dd HH:mm'
83
+ ];
84
+
85
+ export const MAX_DECIMALS = 6;
86
+
87
+ const NUMBER_TYPES = ['number', 'currency', 'percent'];
88
+ const DATE_TYPES = ['date', 'datetime'];
89
+
90
+ const MONTHS = ['January', 'February', 'March', 'April', 'May', 'June', 'July',
91
+ 'August', 'September', 'October', 'November', 'December'];
92
+
93
+ /**
94
+ * The tokens a date pattern is made of, longest first so `MMMM` is not read as
95
+ * two `MM`s. Anything else in a pattern is printed as it stands.
96
+ */
97
+ const DATE_TOKENS = /yyyy|yy|MMMM|MMM|MM|M|dd|d|HH|H|hh|h|mm|ss|a/g;
98
+
99
+ /** a plain number written as text - "1200", "-3.5" - which a CSV or a form will hand over */
100
+ const NUMERIC_TEXT = /^-?\d+(\.\d+)?$/;
101
+
102
+ /** `2026-06-17`, optionally with a time - what JSON carries a date as */
103
+ const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?)?(Z|[+-]\d{2}:?\d{2})?$/;
104
+
105
+
106
+ /**
107
+ * A format with the report's defaults filled in under it, every key present -
108
+ * or null when there is nothing to format, so the caller prints as it always
109
+ * has.
110
+ *
111
+ * @param {object|null|undefined} format an item's or a column's
112
+ * @param {object|null|undefined} [defaults] the report's `layout.format`
113
+ * @returns {object|null}
114
+ */
115
+ export function effectiveFormat(format, defaults) {
116
+ if (format == null || typeof format !== 'object') return null;
117
+ if (!FORMAT_TYPES.includes(format.type) || format.type === 'text') return null;
118
+
119
+ const inherited = defaults && typeof defaults === 'object' ? defaults : {};
120
+ const merged = { ...DEFAULT_FORMAT, ...withoutType(inherited), ...format };
121
+
122
+ merged.decimals = clampDecimals(merged.decimals);
123
+ if (!GROUPINGS.includes(merged.grouping)) merged.grouping = DEFAULT_FORMAT.grouping;
124
+ if (!NEGATIVES.includes(merged.negative)) merged.negative = DEFAULT_FORMAT.negative;
125
+ if (!ZEROS.includes(merged.zero)) merged.zero = DEFAULT_FORMAT.zero;
126
+ if (!SYMBOL_POSITIONS.includes(merged.symbolPosition)) {
127
+ merged.symbolPosition = DEFAULT_FORMAT.symbolPosition;
128
+ }
129
+ if (typeof merged.symbol !== 'string') merged.symbol = '';
130
+ if (typeof merged.pattern !== 'string' || merged.pattern === '') {
131
+ merged.pattern = merged.type === 'datetime' ? 'yyyy-MM-dd HH:mm' : DEFAULT_FORMAT.pattern;
132
+ }
133
+
134
+ return merged;
135
+ }
136
+
137
+
138
+ /**
139
+ * The format a {percentage()} prints in: the item's own when it is a percent
140
+ * format, so its places and negatives are the ones chosen; otherwise a plain
141
+ * percentage to two places - a share is never money or a date, whatever the
142
+ * item around it is formatted as.
143
+ * @param {object|null|undefined} format the item's, settled
144
+ * @returns {object}
145
+ */
146
+ export function percentFormat(format) {
147
+ return format?.type === 'percent' ? format : { type: 'percent', decimals: 2 };
148
+ }
149
+
150
+
151
+ /**
152
+ * The text a value prints as.
153
+ *
154
+ * @param {*} value from the data
155
+ * @param {object|null|undefined} format an item's or column's
156
+ * @param {object|null|undefined} [defaults] the report's
157
+ * @returns {string} '' for null and undefined
158
+ */
159
+ export function formatValue(value, format, defaults) {
160
+ if (value === null || value === undefined) return '';
161
+
162
+ const f = effectiveFormat(format, defaults);
163
+ if (!f) return String(value);
164
+
165
+ if (NUMBER_TYPES.includes(f.type)) {
166
+ const number = toNumber(value);
167
+ return number === null ? String(value) : formatNumber(number, f);
168
+ }
169
+
170
+ const parts = dateParts(value);
171
+ return parts === null ? String(value) : formatDate(parts, f.pattern);
172
+ }
173
+
174
+
175
+ /**
176
+ * A value as the number it stands for, or null: a number, or text that is
177
+ * plainly one. "007" is a number here - a column formatted as a number has
178
+ * said its values are numbers.
179
+ * @param {*} value
180
+ * @returns {number|null}
181
+ */
182
+ export function toNumber(value) {
183
+ if (typeof value === 'number') return Number.isFinite(value) ? value : null;
184
+ if (typeof value !== 'string') return null;
185
+
186
+ const text = value.trim();
187
+ return NUMERIC_TEXT.test(text) ? Number(text) : null;
188
+ }
189
+
190
+
191
+ /**
192
+ * A value's date, as the parts it was written with - or null for what is not a
193
+ * date. A Date is read in local time, as the host that made it meant it; an
194
+ * ISO string is read as written, offset and all ignored, because "17 June at
195
+ * 09:00" is what the data says and what the report should print.
196
+ *
197
+ * @param {*} value
198
+ * @returns {{year: number, month: number, day: number, hour: number,
199
+ * minute: number, second: number}|null} month 1 to 12
200
+ */
201
+ export function dateParts(value) {
202
+ if (value instanceof Date) {
203
+ if (Number.isNaN(value.getTime())) return null;
204
+
205
+ return {
206
+ year: value.getFullYear(), month: value.getMonth() + 1, day: value.getDate(),
207
+ hour: value.getHours(), minute: value.getMinutes(), second: value.getSeconds()
208
+ };
209
+ }
210
+
211
+ if (typeof value !== 'string') return null;
212
+
213
+ const match = value.trim().match(ISO_DATE);
214
+ if (!match) return null;
215
+
216
+ const [, y, mo, d, h = '0', mi = '0', s = '0'] = match;
217
+ const parts = {
218
+ year: Number(y), month: Number(mo), day: Number(d),
219
+ hour: Number(h), minute: Number(mi), second: Number(s)
220
+ };
221
+
222
+ /** 2026-02-31 is not a day; printing it as one would be inventing data */
223
+ const check = new Date(Date.UTC(parts.year, parts.month - 1, parts.day));
224
+ if (check.getUTCMonth() !== parts.month - 1 || check.getUTCDate() !== parts.day) return null;
225
+ if (parts.hour > 23 || parts.minute > 59 || parts.second > 59) return null;
226
+
227
+ return parts;
228
+ }
229
+
230
+
231
+ /**
232
+ * One line a person reads to know what a format does - the rail's summary.
233
+ * @param {object|null|undefined} format
234
+ * @param {object|null|undefined} [defaults]
235
+ * @returns {string}
236
+ */
237
+ export function describeFormat(format, defaults) {
238
+ const f = effectiveFormat(format, defaults);
239
+ if (!f) return 'As it comes';
240
+
241
+ if (DATE_TYPES.includes(f.type)) {
242
+ return `${f.type === 'date' ? 'Date' : 'Date & time'} · ${f.pattern}`;
243
+ }
244
+
245
+ const name = { number: 'Number', currency: 'Currency', percent: 'Percent' }[f.type];
246
+ const sample = formatValue(f.type === 'percent' ? 1234.5678 : 1234567.891, f);
247
+
248
+ return `${name} · ${sample}`;
249
+ }
250
+
251
+
252
+ /* ---------------- numbers ---------------- */
253
+
254
+
255
+ /**
256
+ * Rounds to the format's places with Intl - which rounds 1.005 to 1.01, where
257
+ * toFixed gives 1.00 - and then groups and signs the digits here, because
258
+ * Indian grouping, a trailing minus and a symbol after the figure are not
259
+ * things every Intl locale offers.
260
+ */
261
+ function formatNumber(number, f) {
262
+ const scaled = f.type === 'percent' ? number * 100 : number;
263
+
264
+ const digits = plainDigits(Math.abs(scaled), f.decimals);
265
+ const isZero = /^[0.]*$/.test(digits);
266
+
267
+ if (isZero && f.zero === 'blank') return '';
268
+ if (isZero && f.zero === 'dash') return '-';
269
+
270
+ const [whole, fraction] = digits.split('.');
271
+ let body = group(whole, f.grouping) + (fraction ? `.${fraction}` : '');
272
+
273
+ if (f.type === 'percent') body += '%';
274
+ if (f.type === 'currency' && f.symbol) {
275
+ body = f.symbolPosition === 'after' ? `${body} ${f.symbol}` : `${f.symbol}${body}`;
276
+ }
277
+
278
+ /** -0.001 at two places is 0.00, not -0.00 */
279
+ if (scaled >= 0 || isZero) return body;
280
+
281
+ switch (f.negative) {
282
+ case 'brackets': return `(${body})`;
283
+ case 'trailing': return `${body}-`;
284
+ default: return `-${body}`;
285
+ }
286
+ }
287
+
288
+
289
+ const PLAIN = new Map();
290
+
291
+ /** an unsigned number to exactly `decimals` places, digits only: "1234567.89" */
292
+ function plainDigits(number, decimals) {
293
+ if (!PLAIN.has(decimals)) {
294
+ PLAIN.set(decimals, new Intl.NumberFormat('en-US', {
295
+ minimumFractionDigits: decimals,
296
+ maximumFractionDigits: decimals,
297
+ useGrouping: false
298
+ }));
299
+ }
300
+
301
+ return PLAIN.get(decimals).format(number);
302
+ }
303
+
304
+
305
+ /** the whole part of a number, grouped: 1234567 as 1,234,567 or 12,34,567 */
306
+ function group(whole, grouping) {
307
+ if (grouping === 'none' || whole.length <= 3) return whole;
308
+
309
+ if (grouping === 'indian') {
310
+ /** the last three digits, then pairs - 12,34,567 */
311
+ const head = whole.slice(0, -3);
312
+ const tail = whole.slice(-3);
313
+ return `${head.replace(/\B(?=(\d{2})+$)/g, ',')},${tail}`;
314
+ }
315
+
316
+ return whole.replace(/\B(?=(\d{3})+$)/g, ',');
317
+ }
318
+
319
+
320
+ function clampDecimals(value) {
321
+ const n = Math.round(Number(value));
322
+ if (!Number.isFinite(n)) return DEFAULT_FORMAT.decimals;
323
+ return Math.min(MAX_DECIMALS, Math.max(0, n));
324
+ }
325
+
326
+
327
+ function withoutType(defaults) {
328
+ const { type, ...rest } = defaults;
329
+ void type;
330
+ return rest;
331
+ }
332
+
333
+
334
+ /* ---------------- dates ---------------- */
335
+
336
+
337
+ function formatDate(parts, pattern) {
338
+ const pad = (n) => String(n).padStart(2, '0');
339
+ const hour12 = parts.hour % 12 === 0 ? 12 : parts.hour % 12;
340
+
341
+ return pattern.replace(DATE_TOKENS, (token) => {
342
+ switch (token) {
343
+ case 'yyyy': return String(parts.year).padStart(4, '0');
344
+ case 'yy': return pad(parts.year % 100);
345
+ case 'MMMM': return MONTHS[parts.month - 1];
346
+ case 'MMM': return MONTHS[parts.month - 1].slice(0, 3);
347
+ case 'MM': return pad(parts.month);
348
+ case 'M': return String(parts.month);
349
+ case 'dd': return pad(parts.day);
350
+ case 'd': return String(parts.day);
351
+ case 'HH': return pad(parts.hour);
352
+ case 'H': return String(parts.hour);
353
+ case 'hh': return pad(hour12);
354
+ case 'h': return String(hour12);
355
+ case 'mm': return pad(parts.minute);
356
+ case 'ss': return pad(parts.second);
357
+ case 'a': return parts.hour < 12 ? 'AM' : 'PM';
358
+ default: return token;
359
+ }
360
+ });
361
+ }
362
+
363
+
364
+ /* ---------------- spreadsheets ---------------- */
365
+
366
+
367
+ /**
368
+ * The Excel number format code that shows a value the way formatValue prints
369
+ * it - so a workbook cell keeps the real number or date and still reads as the
370
+ * report does. null when the format leaves the value as it comes.
371
+ *
372
+ * Indian grouping has no Excel code of its own: Excel groups in threes only.
373
+ * It is said with two conditional sections - a crore and over, a lakh and over
374
+ * - so 1,00,000.00 reads the same on any machine whatever its region. Those
375
+ * conditions take the sections a negative and a zero would otherwise have, so
376
+ * under Indian grouping a negative below a lakh's size keeps a plain minus and
377
+ * the zero style is not carried over.
378
+ *
379
+ * @param {object|null|undefined} format
380
+ * @param {object|null|undefined} [defaults]
381
+ * @returns {string|null}
382
+ */
383
+ export function excelNumberFormat(format, defaults) {
384
+ const f = effectiveFormat(format, defaults);
385
+ if (!f) return null;
386
+
387
+ if (DATE_TYPES.includes(f.type)) return excelDate(f.pattern);
388
+
389
+ const places = f.decimals > 0 ? `.${'0'.repeat(f.decimals)}` : '';
390
+ const percent = f.type === 'percent' ? '%' : '';
391
+ const symbol = f.type === 'currency' && f.symbol ? quote(f.symbol) : '';
392
+
393
+ const dress = (digits) => {
394
+ const body = `${digits}${places}${percent}`;
395
+ if (!symbol) return body;
396
+ return f.symbolPosition === 'after' ? `${body}${quote(' ')}${symbol}` : `${symbol}${body}`;
397
+ };
398
+
399
+ if (f.grouping === 'indian') {
400
+ return [
401
+ `[>=10000000]${dress('##\\,##\\,##\\,##0')}`,
402
+ `[>=100000]${dress('##\\,##\\,##0')}`,
403
+ dress('#,##0')
404
+ ].join(';');
405
+ }
406
+
407
+ const positive = dress(f.grouping === 'none' ? '0' : '#,##0');
408
+
409
+ const negative = {
410
+ minus: `-${positive}`,
411
+ brackets: `(${positive})`,
412
+ trailing: `${positive}-`
413
+ }[f.negative];
414
+
415
+ const zero = {
416
+ zero: positive,
417
+ dash: quote('-'),
418
+ blank: ''
419
+ }[f.zero];
420
+
421
+ return `${positive};${negative};${zero}`;
422
+ }
423
+
424
+
425
+ /**
426
+ * A date pattern in Excel's terms. Every character that is not a date token is
427
+ * escaped, because Excel reads a bare `/` or `:` as the reader's own date and
428
+ * time separators - and dd/MM/yyyy has to stay slashes on a machine set to
429
+ * dots.
430
+ */
431
+ function excelDate(pattern) {
432
+ let out = '';
433
+ let last = 0;
434
+
435
+ for (const match of pattern.matchAll(DATE_TOKENS)) {
436
+ out += escapeLiteral(pattern.slice(last, match.index));
437
+ out += {
438
+ yyyy: 'yyyy', yy: 'yy', MMMM: 'mmmm', MMM: 'mmm', MM: 'mm', M: 'm',
439
+ dd: 'dd', d: 'd', HH: 'hh', H: 'h', hh: 'hh', h: 'h',
440
+ mm: 'mm', ss: 'ss', a: 'AM/PM'
441
+ }[match[0]];
442
+ last = match.index + match[0].length;
443
+ }
444
+
445
+ return out + escapeLiteral(pattern.slice(last));
446
+ }
447
+
448
+
449
+ function escapeLiteral(text) {
450
+ return [...text].map(ch => (ch === ' ' ? ' ' : `\\${ch}`)).join('');
451
+ }
452
+
453
+
454
+ /** text Excel prints as it stands, inside a format code */
455
+ function quote(text) {
456
+ return `"${String(text).replace(/"/g, '')}"`;
457
+ }
458
+
459
+
460
+ /**
461
+ * A value as Excel's own: the number, or the date as a serial - days since
462
+ * 1899-12-30, the time as the fraction of a day - or null when the value is not
463
+ * of the format's type and has to go in as text.
464
+ *
465
+ * @param {*} value
466
+ * @param {object|null|undefined} format
467
+ * @param {object|null|undefined} [defaults]
468
+ * @returns {number|null}
469
+ */
470
+ export function excelValue(value, format, defaults) {
471
+ const f = effectiveFormat(format, defaults);
472
+ if (!f) return null;
473
+
474
+ if (NUMBER_TYPES.includes(f.type)) return toNumber(value);
475
+
476
+ const parts = dateParts(value);
477
+ if (!parts) return null;
478
+
479
+ const days = Date.UTC(parts.year, parts.month - 1, parts.day) / 86400000 + 25569;
480
+ const time = (parts.hour * 3600 + parts.minute * 60 + parts.second) / 86400;
481
+
482
+ return f.type === 'date' ? days : days + time;
483
+ }