@mistriwork/engine 1.0.0-rc.15 → 1.0.0-rc.17

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 (58) hide show
  1. package/README.md +5 -0
  2. package/dist/host.d.ts +46 -0
  3. package/dist/host.js +51 -0
  4. package/dist/server/cli/startup.js +7 -2
  5. package/dist/server/cli/usage.d.ts +2 -0
  6. package/dist/server/cli/usage.js +12 -1
  7. package/dist/server/clientHttp.js +20 -3
  8. package/dist/server/config/profile.d.ts +10 -3
  9. package/dist/server/config/profile.js +28 -4
  10. package/dist/server/connections.js +9 -0
  11. package/dist/server/http/baselineHeaders.d.ts +13 -3
  12. package/dist/server/http/baselineHeaders.js +6 -0
  13. package/dist/server/http/exportRoute.d.ts +74 -0
  14. package/dist/server/http/exportRoute.js +206 -169
  15. package/dist/server/http/frontDoor.d.ts +41 -0
  16. package/dist/server/http/frontDoor.js +36 -0
  17. package/dist/server/http/recordCompose.d.ts +3 -0
  18. package/dist/server/http/recordCompose.js +1 -0
  19. package/dist/server/http/reply.js +6 -0
  20. package/dist/server/http/serverCore.d.ts +2 -2
  21. package/dist/server/http/serverCore.js +16 -32
  22. package/dist/server/journal.d.ts +35 -6
  23. package/dist/server/journal.js +79 -8
  24. package/dist/server/journalStore.d.ts +37 -0
  25. package/dist/server/journalStore.js +352 -0
  26. package/dist/server/migrate/cli.js +8 -1
  27. package/dist/server/migrate/target.d.ts +8 -0
  28. package/dist/server/migrate/target.js +15 -0
  29. package/dist/server/seed/seed.js +46 -11
  30. package/dist/shared/appCards.d.ts +4 -0
  31. package/dist/shared/appCards.js +5 -0
  32. package/dist/shared/appListColumns.d.ts +7 -0
  33. package/dist/shared/appListColumns.js +13 -0
  34. package/dist/shared/breakdown.js +8 -2
  35. package/dist/shared/computed.d.ts +16 -2
  36. package/dist/shared/computed.js +23 -4
  37. package/dist/shared/computedValue.js +23 -0
  38. package/dist/shared/listQuestion.js +2 -2
  39. package/dist/shared/mentionLookup.js +3 -1
  40. package/dist/shared/page.js +23 -5
  41. package/dist/shared/pageAnatomy.js +2 -0
  42. package/dist/shared/pageConfig.d.ts +1 -1
  43. package/dist/shared/pageConfig.js +68 -18
  44. package/dist/shared/pageModel.d.ts +42 -5
  45. package/dist/shared/pagePaths.js +4 -1
  46. package/dist/shared/pagePlans.d.ts +2 -2
  47. package/dist/shared/pagePlans.js +3 -3
  48. package/dist/shared/recordLabel.d.ts +12 -3
  49. package/dist/shared/recordLabel.js +39 -18
  50. package/dist/shared/recordReads.d.ts +6 -30
  51. package/dist/shared/recordReads.js +32 -2
  52. package/dist/shared/rollups.d.ts +4 -4
  53. package/dist/shared/rollups.js +1 -1
  54. package/dist/shared/schema.d.ts +7 -0
  55. package/dist/shared/schema.js +17 -0
  56. package/dist/shared/servedApp.d.ts +1 -1
  57. package/dist/shared/viewLabels.js +22 -17
  58. package/package.json +5 -2
@@ -57,6 +57,8 @@ export interface PageFields {
57
57
  region?: SectionRegion;
58
58
  /** The tab of the record's section strip this section is drawn in; sections sharing a name share a panel. */
59
59
  tab?: string;
60
+ /** A mark drawn before the section's heading: one of the App's icons. */
61
+ icon?: import('./appIcons.js').AppIconName;
60
62
  title?: string;
61
63
  /** Paths relative to the root. Empty means "whatever the schema suggests". */
62
64
  paths?: string[];
@@ -84,6 +86,10 @@ export interface PageFields {
84
86
  `properties`: the record form's property rail — caption beside value, a hairline between rows, every
85
87
  field kept (an empty one is where a value is set) and editable in place where the record may change. */
86
88
  presentation?: 'summary' | 'headline' | 'facts' | 'table' | 'properties' | 'card' | 'header';
89
+ /** Authored `empty: 'hide' | 'show'` on a block of fields: the values the record does not have are left out ('hide') or
90
+ said as a dash ('show'). A property rail (the aside's default) hides them unless it says 'show'; a block with nothing
91
+ left to say is not drawn. A field the reader may fill in place stays, as the place to set it. */
92
+ emptyMode?: 'hide' | 'show';
87
93
  /** `fields`: each property is picked or typed in place; where the reader may not write the column, an action of theirs that sets it is offered as the picker. */
88
94
  edit?: true;
89
95
  /** `header`: the record's head as the author says it (a `header` section, DSL `header({ … })`), drawn in the head wherever it is
@@ -105,6 +111,8 @@ export interface PageFields {
105
111
  actions?: PageHeadlineAction[];
106
112
  /** A headline's second figure, under the first and smaller: an estimate, a unit price. */
107
113
  subfigure?: string;
114
+ /** A headline's line under its figure, read from a column of the record: an income's frequency. */
115
+ subtitle?: string;
108
116
  /** A headline's earlier value of its figure — a was-price — struck through beside it when it has one above the figure. */
109
117
  was?: string;
110
118
  /** A headline's line of small print under its actions: what the figures assume. */
@@ -150,6 +158,8 @@ export interface PageMetric {
150
158
  region?: SectionRegion;
151
159
  /** The tab of the record's section strip this section is drawn in; sections sharing a name share a panel. */
152
160
  tab?: string;
161
+ /** A mark drawn before the section's heading: one of the App's icons. */
162
+ icon?: import('./appIcons.js').AppIconName;
153
163
  title?: string;
154
164
  fn: 'count' | 'sum' | 'min' | 'max' | 'avg';
155
165
  /**
@@ -243,6 +253,8 @@ export interface PageList {
243
253
  The record itself is left out when `from` is the page's own table. Such a list has no `path` (it is ''):
244
254
  its rows are not the record's children. */
245
255
  similar?: PageSimilar;
256
+ /** A `current()` card's reference column whose record it opens in place of its own row (a link table's far side). */
257
+ opens?: string;
246
258
  /**
247
259
  * Written as `embed(view, { whose })`: the key of the App list view this
248
260
  * section draws, its rows narrowed to those pointing at the record. The
@@ -256,6 +268,8 @@ export interface PageList {
256
268
  region?: SectionRegion;
257
269
  /** The tab of the record's section strip this section is drawn in; sections sharing a name share a panel. */
258
270
  tab?: string;
271
+ /** A mark drawn before the section's heading: one of the App's icons. */
272
+ icon?: import('./appIcons.js').AppIconName;
259
273
  title?: string;
260
274
  from: string;
261
275
  path: string;
@@ -319,6 +333,8 @@ export interface PageBreakdown {
319
333
  region?: SectionRegion;
320
334
  /** The tab of the record's section strip this section is drawn in; sections sharing a name share a panel. */
321
335
  tab?: string;
336
+ /** A mark drawn before the section's heading: one of the App's icons. */
337
+ icon?: import('./appIcons.js').AppIconName;
322
338
  title?: string;
323
339
  from: string;
324
340
  path: string;
@@ -334,6 +350,8 @@ export interface PageBreakdown {
334
350
  filter?: string;
335
351
  /** Groups shown, biggest first. */
336
352
  limit?: number;
353
+ /** Authored `empty: 'hide'`: the section is left out while there is nothing to count, rather than drawn empty. */
354
+ emptyMode?: 'hide';
337
355
  /** How each figure is said, as a metric's: `percent` (0–100), `number` or `money`; and a word after it. */
338
356
  format?: FigureFormat;
339
357
  unit?: string;
@@ -357,6 +375,8 @@ export interface PageChart {
357
375
  region?: SectionRegion;
358
376
  /** The tab of the record's section strip this section is drawn in; sections sharing a name share a panel. */
359
377
  tab?: string;
378
+ /** A mark drawn before the section's heading: one of the App's icons. */
379
+ icon?: import('./appIcons.js').AppIconName;
360
380
  title?: string;
361
381
  from: string;
362
382
  path: string;
@@ -381,6 +401,12 @@ export interface PageChart {
381
401
  height?: number;
382
402
  /** A goal ruled across a line or stacked bars. */
383
403
  target?: number;
404
+ /** A line's curve, as on a dashboard chart: "smooth" draws a monotone curve through the points. */
405
+ curve?: 'smooth' | 'straight';
406
+ /** A donut's words for the figure in its middle ("Total visitors"), as on a dashboard chart. */
407
+ total?: string;
408
+ /** Authored `empty: 'hide'`: the section is left out while there is nothing to draw, rather than drawn empty. */
409
+ emptyMode?: 'hide';
384
410
  /** How each figure is said, as a metric's: `percent` (0–100), `number` or `money`; and a word after it. */
385
411
  format?: FigureFormat;
386
412
  unit?: string;
@@ -429,10 +455,10 @@ export interface TimelineStream {
429
455
  path: string;
430
456
  /** The date column the stream is ordered and merged by. */
431
457
  at: string;
432
- /** The line itself: a column of `from`, or a dotted path. */
433
- show: string;
434
- /** A quieter second word — a kind, an author. */
435
- detail?: string;
458
+ /** The row's text, its main value: a column of `from`, or a dotted path. It leads a row nobody wrote; in a message it sits under who, the badge and when. */
459
+ text: string;
460
+ /** The row's badge: a quieter word — a kind, a status. In a message it sits beside who and when, over the text; after the text in a row nobody wrote. */
461
+ badge?: string;
436
462
  /** Who wrote it: a column of `from`, or a dotted path — said beside its date. */
437
463
  by?: string;
438
464
  /** Extra narrowing, in the query language, resolved against `from`. */
@@ -457,9 +483,12 @@ export interface PageTimeline {
457
483
  region?: SectionRegion;
458
484
  /** The tab of the record's section strip this section is drawn in; sections sharing a name share a panel. */
459
485
  tab?: string;
486
+ /** A mark drawn before the section's heading: one of the App's icons. */
487
+ icon?: import('./appIcons.js').AppIconName;
460
488
  title?: string;
461
489
  streams: TimelineStream[];
462
- /** Per stream, before the merge. */
490
+ /** Per stream, before the merge: the rows drawn first. Where a stream has more, a "Show more" asks for another
491
+ `limit` of each, on demand. */
463
492
  limit?: number;
464
493
  /** A composer: adds a row of the first stream, bound to this record. */
465
494
  create?: RelatedCreate<string>;
@@ -559,6 +588,8 @@ interface PageHistory {
559
588
  region?: SectionRegion;
560
589
  /** The tab of the record's section strip this section is drawn in; sections sharing a name share a panel. */
561
590
  tab?: string;
591
+ /** A mark drawn before the section's heading: one of the App's icons. */
592
+ icon?: import('./appIcons.js').AppIconName;
562
593
  title?: string;
563
594
  /** Writes shown before "Show earlier changes", 1 to 100. Default 8. */
564
595
  limit?: number;
@@ -580,6 +611,8 @@ interface PageFlows {
580
611
  region?: SectionRegion;
581
612
  /** The tab of the record's section strip this section is drawn in; sections sharing a name share a panel. */
582
613
  tab?: string;
614
+ /** A mark drawn before the section's heading: one of the App's icons. */
615
+ icon?: import('./appIcons.js').AppIconName;
583
616
  title?: string;
584
617
  width?: SectionWidth;
585
618
  offsetLeft?: SectionOffset;
@@ -601,6 +634,8 @@ interface PageDiagram {
601
634
  region?: SectionRegion;
602
635
  /** The tab of the record's section strip this section is drawn in; sections sharing a name share a panel. */
603
636
  tab?: string;
637
+ /** A mark drawn before the section's heading: one of the App's icons. */
638
+ icon?: import('./appIcons.js').AppIconName;
604
639
  title?: string;
605
640
  width?: SectionWidth;
606
641
  offsetLeft?: SectionOffset;
@@ -623,6 +658,8 @@ export interface PageCustom {
623
658
  kind: 'custom';
624
659
  region?: SectionRegion;
625
660
  tab?: string;
661
+ /** A mark drawn before the section's heading: one of the App's icons. */
662
+ icon?: import('./appIcons.js').AppIconName;
626
663
  title?: string;
627
664
  component: import('./appComponents.js').ComponentDecl;
628
665
  /** The record's own fields the component reads, label paths welcome. */
@@ -3,7 +3,7 @@
3
3
  * root, the filter that pins it to one root row, and the list and metric
4
4
  * views a section runs. Pure; nothing fetches.
5
5
  */
6
- import { columnOrRollup, findTable, labelColumn, primaryKey } from './schema.js';
6
+ import { columnOrRollup, findTable, labelColumn, linkTarget, primaryKey, } from './schema.js';
7
7
  import { MAX_PATH_DEPTH, hopName, parseViewQuery, validateView } from './view.js';
8
8
  import { quoteValue, saidAt } from './query.js';
9
9
  import { DEFAULT_PAGE_LIST_LIMIT, GROUPS_DEFAULT } from './pageModel.js';
@@ -503,9 +503,12 @@ export function listView(schema, page, section, key, index, now, ofKeys, rootVal
503
503
  : [];
504
504
  /* A current card is titled by its row's name, which its facts leave out. */
505
505
  const titled = section.presentation === 'card' ? [labelColumn(table)].filter((name) => Boolean(name)) : [];
506
+ /* A card over a link table is named by, and opens, the record its far reference names: that column is read. */
507
+ const opened = section.presentation === 'card' ? [linkTarget(table, section.path, section.opens)].filter((name) => Boolean(name)) : [];
506
508
  const columns = [
507
509
  ...new Set([
508
510
  ...titled,
511
+ ...opened,
509
512
  ...(section.columns?.length ? section.columns : defaultColumns(table, section.path, resolved.path)),
510
513
  ...cardColumns,
511
514
  ...groupFactPaths(section),
@@ -21,8 +21,8 @@ type HttpPagePlan = {
21
21
  streams: Array<{
22
22
  from: string;
23
23
  at: string;
24
- show: string;
25
- detail?: string;
24
+ text: string;
25
+ badge?: string;
26
26
  by?: string;
27
27
  /** With a `side`: the stream's key columns, and the same read narrowed to the other party's rows. */
28
28
  key?: string[];
@@ -44,7 +44,7 @@ export function planPageSections(schema, page, key, ofKeys, now = new Date(), ro
44
44
  from: stream.from,
45
45
  path: stream.path,
46
46
  columns: [
47
- ...new Set([stream.at, stream.show, stream.detail, stream.by, ...streamMarks(stream), ...keyColumns, reacts].filter((c) => Boolean(c))),
47
+ ...new Set([stream.at, stream.text, stream.badge, stream.by, ...streamMarks(stream), ...keyColumns, reacts].filter((c) => Boolean(c))),
48
48
  ],
49
49
  filter: stream.filter,
50
50
  orderBy: [{ column: stream.at, direction: 'desc' }],
@@ -58,8 +58,8 @@ export function planPageSections(schema, page, key, ofKeys, now = new Date(), ro
58
58
  return {
59
59
  from: stream.from,
60
60
  at: stream.at,
61
- show: stream.show,
62
- detail: stream.detail,
61
+ text: stream.text,
62
+ badge: stream.badge,
63
63
  by: stream.by,
64
64
  view: built.view,
65
65
  empty: built.empty,
@@ -16,15 +16,18 @@
16
16
  */
17
17
  /** The last segment that names a record's templated label. */
18
18
  export declare const LABEL_SEGMENT = "$label";
19
- type LabelPart = {
20
- text: string;
21
- } | {
19
+ export type LabelField = {
22
20
  path: string;
23
21
  mask?: {
24
22
  prefix?: string;
25
23
  };
26
24
  words?: Record<string, string>;
27
25
  };
26
+ type LabelPart = {
27
+ text: string;
28
+ } | (LabelField & {
29
+ or?: LabelField[];
30
+ });
28
31
  /** Whether an authored record label is a template rather than a path. */
29
32
  export declare const isLabelTemplate: (text: unknown) => text is string;
30
33
  /** The prefix a `$label` path hangs off ('' for the base's own), or undefined for any other path. */
@@ -36,10 +39,16 @@ export declare function parseLabelTemplate(template: string): {
36
39
  } | {
37
40
  problem: string;
38
41
  };
42
+ /** A template field's text, written back from its alternatives' own (a masked one marked, a worded one with its words). */
43
+ export declare const fieldText: (alternatives: readonly string[]) => string;
39
44
  /** A template field for a path whose stored values are said as words, as the server writes it into a served template. */
40
45
  export declare const wordedField: (path: string, words: Record<string, string>) => string;
46
+ /** The same inside a fallback chain, without its braces. */
47
+ export declare const wordedPath: (path: string, words: Record<string, string>) => string;
41
48
  /** A template field for a masked path, as the server writes it into a served template. */
42
49
  export declare const maskedField: (path: string, prefix?: string) => string;
50
+ /** The same inside a fallback chain, without its braces. */
51
+ export declare const maskedPath: (path: string, prefix?: string) => string;
43
52
  /** Whether an authored template writes a mask itself: that is the column's display rule's to say. */
44
53
  export declare const writesMask: (template: string) => boolean;
45
54
  /**
@@ -16,6 +16,8 @@
16
16
  */
17
17
  /** The last segment that names a record's templated label. */
18
18
  export const LABEL_SEGMENT = '$label';
19
+ /** The words between a field's alternatives. */
20
+ const FALLBACK = ' ?? ';
19
21
  const MASK_MARK = '|masked';
20
22
  /* Or its words: `{token|words:…}`, the column's display rule (`values`,
21
23
  `humanize`, a vocabulary's words) reaching the name the way it reaches a
@@ -58,23 +60,17 @@ export function parseLabelTemplate(template) {
58
60
  const end = rest.indexOf('}', open);
59
61
  if (end === -1)
60
62
  return { problem: `"${template}" opens a "{" it never closes.` };
61
- let field = rest.slice(open + 1, end);
62
- let words;
63
- const worded = field.indexOf(WORDS_MARK);
64
- if (worded !== -1) {
65
- words = readWords(field.slice(worded + WORDS_MARK.length));
66
- if (!words)
67
- return { problem: `"{${field}}" in "${template}" is not a column or a reference path, like {id} or {customer_id.name}.` };
68
- field = field.slice(0, worded);
63
+ const alternatives = rest.slice(open + 1, end).split(/\s\?\?\s/);
64
+ const fields = [];
65
+ for (const field of alternatives) {
66
+ const one = parseField(field, template);
67
+ if ('problem' in one)
68
+ return one;
69
+ fields.push(one);
70
+ paths.push(one.path);
69
71
  }
70
- const marked = field.indexOf(MASK_MARK);
71
- const path = (marked === -1 ? field : field.slice(0, marked)).trim();
72
- const after = marked === -1 ? undefined : field.slice(marked + MASK_MARK.length);
73
- if (!FIELD.test(path) || path.split('.').includes(LABEL_SEGMENT) || (after !== undefined && after !== '' && !after.startsWith(':'))) {
74
- return { problem: `"{${field}}" in "${template}" is not a column or a reference path, like {id} or {customer_id.name}.` };
75
- }
76
- parts.push({ path, ...(after === undefined ? {} : { mask: after ? { prefix: after.slice(1) } : {} }), ...(words ? { words } : {}) });
77
- paths.push(path);
72
+ const [first, ...others] = fields;
73
+ parts.push(others.length ? { ...first, or: others } : first);
78
74
  rest = rest.slice(end + 1);
79
75
  }
80
76
  if (!paths.length)
@@ -86,6 +82,27 @@ export function parseLabelTemplate(template) {
86
82
  }
87
83
  return { parts, paths };
88
84
  }
85
+ /* One field's path and the marks the server writes after it (mask, words), or why it is not one. */
86
+ function parseField(source, template) {
87
+ let field = source;
88
+ let words;
89
+ const worded = field.indexOf(WORDS_MARK);
90
+ if (worded !== -1) {
91
+ words = readWords(field.slice(worded + WORDS_MARK.length));
92
+ if (!words)
93
+ return { problem: `"{${field}}" in "${template}" is not a column or a reference path, like {id} or {customer_id.name}.` };
94
+ field = field.slice(0, worded);
95
+ }
96
+ const marked = field.indexOf(MASK_MARK);
97
+ const path = (marked === -1 ? field : field.slice(0, marked)).trim();
98
+ const after = marked === -1 ? undefined : field.slice(marked + MASK_MARK.length);
99
+ if (!FIELD.test(path) || path.split('.').includes(LABEL_SEGMENT) || (after !== undefined && after !== '' && !after.startsWith(':'))) {
100
+ return { problem: `"{${field}}" in "${template}" is not a column or a reference path, like {id} or {customer_id.name}.` };
101
+ }
102
+ return { path, ...(after === undefined ? {} : { mask: after ? { prefix: after.slice(1) } : {} }), ...(words ? { words } : {}) };
103
+ }
104
+ /** A template field's text, written back from its alternatives' own (a masked one marked, a worded one with its words). */
105
+ export const fieldText = (alternatives) => `{${alternatives.join(FALLBACK)}}`;
89
106
  /* A words map as a field carries it, or undefined when it is not one: every
90
107
  key and word a string every engine reads alike inside quotes. */
91
108
  function readWords(encoded) {
@@ -104,9 +121,13 @@ function readWords(encoded) {
104
121
  return Object.fromEntries(entries);
105
122
  }
106
123
  /** A template field for a path whose stored values are said as words, as the server writes it into a served template. */
107
- export const wordedField = (path, words) => `{${path}${WORDS_MARK}${encodeURIComponent(JSON.stringify(words))}}`;
124
+ export const wordedField = (path, words) => `{${wordedPath(path, words)}}`;
125
+ /** The same inside a fallback chain, without its braces. */
126
+ export const wordedPath = (path, words) => `${path}${WORDS_MARK}${encodeURIComponent(JSON.stringify(words))}`;
108
127
  /** A template field for a masked path, as the server writes it into a served template. */
109
- export const maskedField = (path, prefix) => `{${path}${MASK_MARK}${prefix ? `:${prefix}` : ''}}`;
128
+ export const maskedField = (path, prefix) => `{${maskedPath(path, prefix)}}`;
129
+ /** The same inside a fallback chain, without its braces. */
130
+ export const maskedPath = (path, prefix) => `${path}${MASK_MARK}${prefix ? `:${prefix}` : ''}`;
110
131
  /** Whether an authored template writes a mask itself: that is the column's display rule's to say. */
111
132
  export const writesMask = (template) => template.includes(MASK_MARK) || template.includes(WORDS_MARK);
112
133
  /**
@@ -1,32 +1,3 @@
1
- /**
2
- * What a record page reads, as the requests its sections send.
3
- *
4
- * A record page used to reach its reader in three waves of requests — the
5
- * root and the plan, then a request or two per section, then the history —
6
- * and at 20 ms to the database each wave was a round of admissions and
7
- * statements: a lender's loan finished at 0.9 s. The server now answers the
8
- * whole page in one request (server/http/recordCompose.ts, and the tenant
9
- * host's own): it plans the page, then asks each section's read on the
10
- * section's behalf, through the same route and the same grants as the
11
- * section's own request, and hands every answer back beside the plan. The
12
- * client keeps them for the requests they answer (client/composedReads.ts),
13
- * and a section that asks finds its answer waiting.
14
- *
15
- * So the one rule is that server and client build each request alike, and
16
- * the builders live here, used by both: the sections' own modules call them
17
- * for the request they send, and the server calls them to know what the
18
- * sections will ask. A request built differently is only asked again — the
19
- * section sends it, as it always did — so a drift costs a request, never a
20
- * wrong answer.
21
- *
22
- * The record's own row is the one read that is not asked alike: every fields
23
- * section, the header, the root probe and a custom section's record fields
24
- * read the one row, each for its columns, and which of them ask together
25
- * depends on what is drawn (a tab not yet opened asks nothing). The server
26
- * reads every column any of them names, once, and each is answered with
27
- * exactly its part (`rowPart`), as the client's own shared read already was
28
- * (pageFieldsRead.ts).
29
- */
30
1
  import { type DatabaseSchema, type TableMeta } from './schema.js';
31
2
  import { type PageSection } from './pageModel.js';
32
3
  import type { HttpBreakdownDefinition, HttpFilter } from './resourceHttp.js';
@@ -47,18 +18,23 @@ export interface RecordReadNames {
47
18
  readonly defined?: (tableId: string) => Readonly<Record<string, {
48
19
  per?: string;
49
20
  }>> | undefined;
21
+ /** A column's display rule (`resources.<r>.display`), where a shown column's `subtitle` is read with the record. */
22
+ readonly display?: (tableId: string, column: string) => {
23
+ subtitle?: string;
24
+ } | null | undefined;
50
25
  }
51
26
  /** The parts of a section its reads are built from (client pageModel.ts PageSection, shared page.ts). */
52
27
  export interface ReadSection {
53
28
  readonly kind: PageSection['kind'];
54
29
  readonly hidden?: boolean;
55
- readonly emptyMode?: 'hide' | 'collapse';
30
+ readonly emptyMode?: 'hide' | 'collapse' | 'show';
56
31
  /** A grouped related list reads its groups, then each group's rows (the rows wait on the groups). */
57
32
  readonly group?: unknown;
58
33
  readonly presentation?: unknown;
59
34
  readonly paths?: readonly string[];
60
35
  readonly status?: string;
61
36
  readonly subfigure?: string;
37
+ readonly subtitle?: string;
62
38
  readonly was?: string;
63
39
  readonly actions?: ReadonlyArray<{
64
40
  readonly prefill?: Readonly<Record<string, string>>;
@@ -27,6 +27,8 @@
27
27
  * exactly its part (`rowPart`), as the client's own shared read already was
28
28
  * (pageFieldsRead.ts).
29
29
  */
30
+ import { subtitlePath } from './subtitlePath.js';
31
+ import { listSecondLineColumns } from './appListColumns.js';
30
32
  import { findTable, labelPath, primaryKey } from './schema.js';
31
33
  import { DEFAULT_HISTORY_LIMIT, kindReading } from './pageModel.js';
32
34
  import { assertNever } from './model.js';
@@ -73,6 +75,21 @@ export function defaultFieldPaths(base, app) {
73
75
  const read = base.columns.filter((c) => !app || !(surrogate(c) || version(c))).map((c) => c.name);
74
76
  return read.length ? read : base.columns.map((c) => c.name);
75
77
  }
78
+ /**
79
+ * The second lines of the columns at `paths`: a column whose rule has a `subtitle` is drawn with it wherever it is a
80
+ * field, a header's fact or a card's title, so the record reads it too (the same rule a list's cell reads,
81
+ * listQuestion.ts subtitleColumns). A path through a reference reads it from the table it reaches.
82
+ */
83
+ function secondLines(names, base, paths) {
84
+ if (!names.display)
85
+ return [];
86
+ return paths.flatMap((path) => {
87
+ const hop = path.lastIndexOf('.');
88
+ const owner = hop < 0 ? base.id : tableAtPrefix(names.schema, base.id, path.slice(0, hop))?.id;
89
+ const second = owner ? subtitlePath(names.display(owner, path.slice(hop + 1)), path) : undefined;
90
+ return second ? [second] : [];
91
+ });
92
+ }
76
93
  /** A fields section's columns: what it shows, the names of what it references, the record's name, and its workflow's field. */
77
94
  export function fieldsColumns(names, base, section) {
78
95
  const paths = section.paths?.length ? [...section.paths] : defaultFieldPaths(base, names.app);
@@ -82,6 +99,7 @@ export function fieldsColumns(names, base, section) {
82
99
  const extra = section.presentation === 'headline'
83
100
  ? [
84
101
  ...(section.subfigure ? [section.subfigure] : []),
102
+ ...(section.subtitle ? [section.subtitle] : []),
85
103
  ...(section.was ? [section.was] : []),
86
104
  ...(section.actions ?? []).flatMap((action) => [
87
105
  ...Object.values(action.prefill ?? {}),
@@ -89,7 +107,8 @@ export function fieldsColumns(names, base, section) {
89
107
  ]),
90
108
  ].filter((path) => !paths.includes(path))
91
109
  : [];
92
- const projection = referenceProjection(names.schema, base, [...paths, ...new Set(extra)], section.names !== false && names.app, (table) => namePathOf(names, table));
110
+ const seconds = secondLines(names, base, [...new Set([...paths, ...(section.presentation === 'headline' ? extra : [])])]);
111
+ const projection = referenceProjection(names.schema, base, [...new Set([...paths, ...extra, ...seconds])], section.names !== false && names.app, (table) => namePathOf(names, table));
93
112
  const fetched = projection.fetched;
94
113
  if (namePath && !fetched.includes(namePath))
95
114
  fetched.push(namePath);
@@ -129,6 +148,10 @@ export function headerColumns(names, base, section) {
129
148
  const namePath = namePathOf(names, base);
130
149
  if (namePath && !fetched.includes(namePath))
131
150
  fetched.push(namePath);
151
+ /* A fact's second line is drawn under its value, as a field's is. */
152
+ for (const second of secondLines(names, base, section.paths ?? []))
153
+ if (!fetched.includes(second))
154
+ fetched.push(second);
132
155
  return { fetched, labels: projection.labels };
133
156
  }
134
157
  /** The key as a filter on the record's own row, one equality per key column. */
@@ -154,11 +177,18 @@ function probeColumns(names, base) {
154
177
  const namePath = namePathOf(names, base);
155
178
  return [...primaryKey(base), ...(namePath ? [namePath] : [])];
156
179
  }
180
+ const isCards = (presentation) => typeof presentation === 'object' && presentation !== null && presentation.kind === 'cards';
157
181
  /** A related list's first request: its planned view at the reader's page size, with the names and keys a row needs. */
158
182
  export function listView(names, section, plan, rows) {
159
183
  const table = names.table ? names.table(section.from ?? '') : findTable(names.schema, section.from ?? '');
160
184
  const limit = section.limit ?? rows;
161
- const view = plan.view && !section.limit ? { ...plan.view, limit } : plan.view;
185
+ const sized = plan.view && !section.limit ? { ...plan.view, limit } : plan.view;
186
+ /* Cards read the second lines of the columns they draw with one (appListColumns.ts listSecondLineColumns). */
187
+ const drawn = sized?.columns;
188
+ const seconds = table && drawn && isCards(section.presentation)
189
+ ? secondLines(names, table, listSecondLineColumns(section.presentation)).filter((path) => !drawn.some((c) => c.path === path))
190
+ : [];
191
+ const view = seconds.length ? { ...sized, columns: [...drawn, ...seconds.map((path) => ({ path }))] } : sized;
162
192
  const explicit = (target) => (names.recordLabel(target.id) === undefined ? undefined : namePathOf(names, target));
163
193
  return view && table
164
194
  ? recordView(names.schema, table, view, names.app, (target) => namePathOf(names, target), explicit)
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Rollups: one number about the rows that point at a record — an order's
3
3
  * line total, an account's open deals — declared once on the resource
4
- * (`rollups: { line_total: sum('order_line', 'amount') }`) and read wherever
4
+ * (`rollups: { line_total: rollup.sum('order_line', 'amount') }`) and read wherever
5
5
  * a column of the record is: a list's `show`, a sort, a tab's condition, a
6
6
  * record page's fields, a card's figure and facts, a queue's facts, a
7
7
  * picker's query, a dashboard's measure and a breakdown's key — and through
@@ -28,7 +28,7 @@
28
28
  import type { Filter } from './filter.js';
29
29
  import type { ComputedColumn } from './computed.js';
30
30
  import type { ColumnMeta } from './schema.js';
31
- export declare const ROLLUP_FNS: readonly ['count', 'sum', 'min', 'max', 'latest'];
31
+ export declare const ROLLUP_FNS: readonly ['count', 'sum', 'avg', 'min', 'max', 'latest'];
32
32
  export type RollupFn = (typeof ROLLUP_FNS)[number];
33
33
  /** A rollup as the catalog serves it and a view carries it: no request ever supplies one. */
34
34
  export interface Rollup {
@@ -99,13 +99,13 @@ export interface Rollup {
99
99
  type: string;
100
100
  /**
101
101
  * Set when `column` names a rollup of the child rather than one of its
102
- * columns — a customer's `lines: sum('sales_order', 'lines')`, the count
102
+ * columns — a customer's `lines: rollup.sum('sales_order', 'lines')`, the count
103
103
  * of its orders' lines, which is how a rollup reaches two hops. The inner
104
104
  * rollup is compiled inside the outer one's aggregate, each through its own
105
105
  * child's relation, so a row policy narrows both levels. One level only:
106
106
  * the inner one reads a column (appRollupRules says so when it does not).
107
107
  *
108
- * A rollup whose `whose` walks two references (`sum('time_entry', 'hours',
108
+ * A rollup whose `whose` walks two references (`rollup.sum('time_entry', 'hours',
109
109
  * { whose: 'task_id.project_id' })`) is served in the same shape: the outer
110
110
  * reads the middle table (`task.project_id`) with no column of its own,
111
111
  * the inner the rows and column declared, with the declared query. A count
@@ -1,4 +1,4 @@
1
- export const ROLLUP_FNS = ['count', 'sum', 'min', 'max', 'latest'];
1
+ export const ROLLUP_FNS = ['count', 'sum', 'avg', 'min', 'max', 'latest'];
2
2
  /** A rollup read as a column: never written, null only where there are no rows to read (a count is 0). */
3
3
  export function rollupColumnMeta(name, rollup) {
4
4
  return {
@@ -527,3 +527,10 @@ export declare function comparableType(type: string | undefined): boolean;
527
527
  * as a plain value of a comparable type: the write is then as blind as ever.
528
528
  */
529
529
  export declare function expectedValues(table: Pick<TableMeta, 'columns'>, values: Record<string, unknown>, row: Record<string, unknown> | undefined): Record<string, string | number | boolean | null> | undefined;
530
+ /**
531
+ * The reference a card over `table`'s row opens, where that row is a link (join) table's: the far side. The author's
532
+ * `opens` where they name one; otherwise, a table that is two references and nothing else of note (its key and
533
+ * dates aside) opens the one that `whose` — the reference back to the page's record — does not name. Any other table
534
+ * opens its own row, and gives none.
535
+ */
536
+ export declare function linkTarget(table: TableMeta, whose: string, opens?: string): string | undefined;
@@ -625,3 +625,20 @@ export function expectedValues(table, values, row) {
625
625
  }
626
626
  return Object.keys(expected).length ? expected : undefined;
627
627
  }
628
+ /**
629
+ * The reference a card over `table`'s row opens, where that row is a link (join) table's: the far side. The author's
630
+ * `opens` where they name one; otherwise, a table that is two references and nothing else of note (its key and
631
+ * dates aside) opens the one that `whose` — the reference back to the page's record — does not name. Any other table
632
+ * opens its own row, and gives none.
633
+ */
634
+ export function linkTarget(table, whose, opens) {
635
+ if (opens)
636
+ return opens;
637
+ if (whose.includes('.'))
638
+ return undefined;
639
+ const references = table.columns.filter((column) => column.references && column.references.table !== table.id);
640
+ if (references.length !== 2 || !references.some((column) => column.name === whose))
641
+ return undefined;
642
+ const plain = table.columns.every((column) => column.primaryKey || references.includes(column) || (column.type !== undefined && columnKind(column.type) === 'date'));
643
+ return plain ? references.find((column) => column.name !== whose)?.name : undefined;
644
+ }
@@ -329,7 +329,7 @@ export interface AppDisplayRule {
329
329
  /** Every value no `values` key names said as words (`IN_REVIEW` → "In review"): the authored `values: true`,
330
330
  and implied by `values: { … }`, so a vocabulary never reads half in words and half in codes. */
331
331
  humanize?: true;
332
- /** Another column of the same record, said as a muted second line under the value in lists. */
332
+ /** Another column of the same record, said as a muted second line under the value wherever it has room (appListColumns.ts listSecondLineColumns). */
333
333
  subtitle?: string;
334
334
  /** A value renderer: the author's component draws the value in an App (appComponents.ts); sort, filter,
335
335
  totals and export keep the raw value, and the rest of the rule dresses it until the renderer arrives. */
@@ -355,23 +355,28 @@ export function viewPaths(schema, view, plan, style, relations) {
355
355
  return named(style.concat(parts.map((part) => {
356
356
  if ('text' in part)
357
357
  return literal(part.text);
358
- const value = style.text(plain(at(prefix, part.path)));
359
- /* A masked column says its placeholder in the name too, computed here
360
- like the rest of it, so no list, picker or breadcrumb reads the value. */
361
- if (part.mask?.prefix) {
362
- return `CASE WHEN SUBSTR(${value}, 1, ${[...part.mask.prefix].length}) = ${literal(part.mask.prefix)} THEN ${literal(part.mask.prefix + MASK)} ELSE COALESCE(${value}, '') END`;
363
- }
364
- if (part.mask)
365
- return `CASE WHEN ${value} IS NULL THEN '' ELSE ${literal(MASK)} END`;
366
- /* A stored value said as its display rule's word, as a cell says it:
367
- the words are the catalog's, held to what every engine reads alike. */
368
- if (part.words) {
369
- const cases = Object.entries(part.words)
370
- .map(([stored, word]) => `WHEN ${literal(stored)} THEN ${literal(word)}`)
371
- .join(' ');
372
- return `CASE ${value} ${cases} ELSE COALESCE(${value}, '') END`;
373
- }
374
- return `COALESCE(${value}, '')`;
358
+ const one = (field) => {
359
+ const value = style.text(plain(at(prefix, field.path)));
360
+ /* A masked column says its placeholder in the name too, computed here
361
+ like the rest of it, so no list, picker or breadcrumb reads the value. */
362
+ if (field.mask?.prefix) {
363
+ return `CASE WHEN SUBSTR(${value}, 1, ${[...field.mask.prefix].length}) = ${literal(field.mask.prefix)} THEN ${literal(field.mask.prefix + MASK)} ELSE COALESCE(${value}, '') END`;
364
+ }
365
+ if (field.mask)
366
+ return `CASE WHEN ${value} IS NULL THEN '' ELSE ${literal(MASK)} END`;
367
+ /* A stored value said as its display rule's word, as a cell says it:
368
+ the words are the catalog's, held to what every engine reads alike. */
369
+ if (field.words) {
370
+ const cases = Object.entries(field.words)
371
+ .map(([stored, word]) => `WHEN ${literal(stored)} THEN ${literal(word)}`)
372
+ .join(' ');
373
+ return `CASE ${value} ${cases} ELSE COALESCE(${value}, '') END`;
374
+ }
375
+ return `COALESCE(${value}, '')`;
376
+ };
377
+ /* A fallback chain is its first alternative with a value: each said as it would alone, an empty text
378
+ counting as none, so a blank nickname gives way to the name behind it. */
379
+ return part.or ? `COALESCE(${[part, ...part.or].map((field) => `NULLIF(${one(field)}, '')`).join(', ')}, '')` : one(part);
375
380
  })));
376
381
  };
377
382
  /* The catalog's type of what a path reads where it reads one column as it is stored, as `qualify` writes it plain: