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

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 (43) hide show
  1. package/dist/server/cli/startup.js +7 -2
  2. package/dist/server/cli/usage.d.ts +2 -0
  3. package/dist/server/cli/usage.js +12 -1
  4. package/dist/server/clientHttp.js +20 -3
  5. package/dist/server/config/profile.d.ts +10 -3
  6. package/dist/server/config/profile.js +28 -4
  7. package/dist/server/http/baselineHeaders.d.ts +13 -3
  8. package/dist/server/http/baselineHeaders.js +6 -0
  9. package/dist/server/http/frontDoor.d.ts +41 -0
  10. package/dist/server/http/frontDoor.js +36 -0
  11. package/dist/server/http/recordCompose.d.ts +3 -0
  12. package/dist/server/http/recordCompose.js +1 -0
  13. package/dist/server/http/serverCore.d.ts +2 -2
  14. package/dist/server/http/serverCore.js +16 -32
  15. package/dist/server/migrate/cli.js +8 -1
  16. package/dist/server/migrate/target.d.ts +8 -0
  17. package/dist/server/migrate/target.js +15 -0
  18. package/dist/server/seed/seed.js +46 -11
  19. package/dist/shared/appCards.d.ts +4 -0
  20. package/dist/shared/appCards.js +5 -0
  21. package/dist/shared/breakdown.js +8 -2
  22. package/dist/shared/computed.d.ts +16 -2
  23. package/dist/shared/computed.js +23 -4
  24. package/dist/shared/computedValue.js +23 -0
  25. package/dist/shared/mentionLookup.js +3 -1
  26. package/dist/shared/page.js +23 -5
  27. package/dist/shared/pageAnatomy.js +2 -0
  28. package/dist/shared/pageConfig.d.ts +1 -1
  29. package/dist/shared/pageConfig.js +68 -18
  30. package/dist/shared/pageModel.d.ts +42 -5
  31. package/dist/shared/pagePaths.js +4 -1
  32. package/dist/shared/pagePlans.d.ts +2 -2
  33. package/dist/shared/pagePlans.js +3 -3
  34. package/dist/shared/recordLabel.d.ts +12 -3
  35. package/dist/shared/recordLabel.js +39 -18
  36. package/dist/shared/recordReads.d.ts +6 -30
  37. package/dist/shared/recordReads.js +13 -1
  38. package/dist/shared/rollups.d.ts +4 -4
  39. package/dist/shared/rollups.js +1 -1
  40. package/dist/shared/schema.d.ts +7 -0
  41. package/dist/shared/schema.js +17 -0
  42. package/dist/shared/viewLabels.js +22 -17
  43. package/package.json +3 -2
@@ -9,7 +9,7 @@ import { parseRelatedCreate } from './relatedCreate.js';
9
9
  import { parseListEmpty } from './listEmpty.js';
10
10
  import { CHART_SHAPES, FIGURE_FORMATS, FIGURE_FORMAT_WORDS, allowKeys, humanName } from './model.js';
11
11
  import { headingOf } from './appNoun.js';
12
- import { CARDS_MAX_LINES, parseCards, parseFacts } from './appCards.js';
12
+ import { CARDS_MAX_LINES, HEADER_MAX_FACTS, parseCards, parseFacts } from './appCards.js';
13
13
  import { parseIcon } from './appIcons.js';
14
14
  import { slug } from './slug.js';
15
15
  import { parsePageLayout } from './pageLayouts.js';
@@ -74,7 +74,7 @@ export const PAGE_KEYS = ['label', 'base', 'connection', 'listTabs', 'empty', 's
74
74
  export const APP_PAGE_KEYS = PAGE_KEYS.filter((key) => key !== 'connection' && key !== 'label');
75
75
  /* `aside` and `layout` are an App page's alone: the Workbench's pages draw what they say, in the record's one skeleton. */
76
76
  const WORKBENCH_PAGE_KEYS = PAGE_KEYS.filter((key) => key !== 'aside' && key !== 'layout');
77
- const SECTION_COMMON = ['kind', 'title', 'region', 'tab', 'width', 'offsetLeft', 'offsetRight', 'hidden', 'when'];
77
+ const SECTION_COMMON = ['kind', 'title', 'icon', 'region', 'tab', 'width', 'offsetLeft', 'offsetRight', 'hidden', 'when'];
78
78
  /** A tab's name is a word or two across the strip, not a sentence. */
79
79
  const MAX_TAB_NAME = 40;
80
80
  /** The keys each page section kind takes. Anything else is refused by name. A `segment` is read before the
@@ -82,22 +82,22 @@ const MAX_TAB_NAME = 40;
82
82
  /* `view` is an authored kind with no section of its own: `embed(view, { whose })`
83
83
  is read into a related list that remembers the view (PageList.view). */
84
84
  export const PAGE_SECTION_KEYS = {
85
- fields: [...SECTION_COMMON, 'show', 'columns', 'names', 'presentation', 'editable'],
85
+ fields: [...SECTION_COMMON, 'show', 'columns', 'names', 'presentation', 'editable', 'empty'],
86
86
  /* The record a reference names, in a box of its own: the first shown field is its title, the rest its facts. */
87
87
  card: [...SECTION_COMMON, 'show'],
88
88
  /* A figure with its facts, its earlier value, its estimate and the calls to action beside it. */
89
- headline: [...SECTION_COMMON, 'show', 'links', 'subfigure', 'was', 'note'],
89
+ headline: [...SECTION_COMMON, 'show', 'links', 'subfigure', 'subtitle', 'was', 'note'],
90
90
  /* The record's head: drawn where the head is, so nothing that would place it elsewhere. */
91
91
  header: ['kind', 'status', 'facts', 'primary', 'destructive', 'actions'],
92
92
  /* The one current related row as a card: nothing to page, sum or add under it. */
93
- current: ['kind', 'title', 'region', 'tab', 'width', 'when', 'from', 'whose', 'show', 'query', 'sort', 'empty'],
93
+ current: ['kind', 'title', 'icon', 'region', 'tab', 'width', 'when', 'from', 'whose', 'show', 'query', 'sort', 'empty', 'opens'],
94
94
  timeline: [...SECTION_COMMON, 'streams', 'limit', 'create', 'newest', 'composer', 'tone', 'compact', 'side', 'reactions'],
95
95
  history: [...SECTION_COMMON, 'limit'],
96
96
  flows: [...SECTION_COMMON],
97
97
  diagram: [...SECTION_COMMON],
98
98
  custom: [...SECTION_COMMON, 'component', 'record', 'rows', 'figures', 'props'],
99
99
  metric: [...SECTION_COMMON, 'from', 'whose', 'about', 'measure', 'query', 'segment', 'format', 'unit'],
100
- breakdown: [...SECTION_COMMON, 'from', 'whose', 'about', 'by', 'measure', 'query', 'segment', 'limit', 'format', 'unit'],
100
+ breakdown: [...SECTION_COMMON, 'from', 'whose', 'about', 'by', 'measure', 'query', 'segment', 'limit', 'format', 'unit', 'empty'],
101
101
  chart: [
102
102
  ...SECTION_COMMON,
103
103
  'from',
@@ -106,6 +106,8 @@ export const PAGE_SECTION_KEYS = {
106
106
  'by',
107
107
  'measure',
108
108
  'shape',
109
+ 'curve',
110
+ 'total',
109
111
  'sort',
110
112
  'query',
111
113
  'segment',
@@ -114,8 +116,9 @@ export const PAGE_SECTION_KEYS = {
114
116
  'target',
115
117
  'format',
116
118
  'unit',
119
+ 'empty',
117
120
  ],
118
- note: [...SECTION_COMMON, 'text', 'icon', 'action', 'variant'],
121
+ note: [...SECTION_COMMON, 'text', 'action', 'variant'],
119
122
  view: [...SECTION_COMMON, 'view', 'whose', 'about', 'limit'],
120
123
  list: [
121
124
  ...SECTION_COMMON,
@@ -133,12 +136,13 @@ export const PAGE_SECTION_KEYS = {
133
136
  'totals',
134
137
  'same',
135
138
  'near',
139
+ 'opens',
136
140
  'rowActions',
137
141
  'actions',
138
142
  'group',
139
143
  ],
140
144
  };
141
- export const STREAM_KEYS = ['from', 'whose', 'at', 'show', 'detail', 'author', 'query', 'about', 'side', 'tone', 'compact'];
145
+ export const STREAM_KEYS = ['from', 'whose', 'at', 'text', 'badge', 'author', 'query', 'about', 'side', 'tone', 'compact'];
142
146
  /**
143
147
  * One page body: a tablewalk.json page, whose `id` is its own or derives
144
148
  * from the name, or an App page, whose id is its key. The body is the same
@@ -366,6 +370,7 @@ function parseSection(entry, at, config) {
366
370
  const placement = {
367
371
  ...(region === undefined ? {} : { region }),
368
372
  ...(tab === undefined ? {} : { tab }),
373
+ ...(s.icon === undefined ? {} : { icon: parseIcon(s.icon, at) }),
369
374
  };
370
375
  if (s.create !== undefined && kind !== 'list' && kind !== 'timeline')
371
376
  throw new Error(`${at}: create belongs on a related list or a timeline.`);
@@ -393,6 +398,7 @@ function parseSection(entry, at, config) {
393
398
  ? {
394
399
  actions: `belongs on a headline(figure, { links }). ${retiredFieldsForms()}`,
395
400
  subfigure: `belongs on a headline(figure, { subfigure }). ${retiredFieldsForms()}`,
401
+ subtitle: `belongs on a headline(figure, { subtitle }). ${retiredFieldsForms()}`,
396
402
  was: `belongs on a headline(figure, { was }). ${retiredFieldsForms()}`,
397
403
  note: `belongs on a headline(figure, { note }). ${retiredFieldsForms()}`,
398
404
  }
@@ -418,12 +424,18 @@ function parseSection(entry, at, config) {
418
424
  if (s.editable === true && s.presentation !== undefined && !['summary', 'properties'].includes(s.presentation)) {
419
425
  throw new Error(`${at}: "editable" belongs on the fields a reader edits — a summary or a property rail; a ${String(s.presentation)} says values, it does not hold them.`);
420
426
  }
427
+ if (s.empty !== undefined && s.empty !== 'hide' && s.empty !== 'show') {
428
+ throw new Error(`${at} has "empty": ${JSON.stringify(s.empty)}. A block of fields leaves out the values a record does not have ('hide') or says each as a dash ('show'); a property rail hides them unless it says 'show'.`);
429
+ }
421
430
  if (s.was !== undefined && (typeof s.was !== 'string' || !FIELD_PATH.test(s.was.trim()))) {
422
431
  throw new Error(`${at} has a "was" that is not a field name, like "was_price": the figure's earlier value.`);
423
432
  }
424
433
  if (s.subfigure !== undefined && (typeof s.subfigure !== 'string' || !FIELD_PATH.test(s.subfigure.trim()))) {
425
434
  throw new Error(`${at} has a "subfigure" that is not a field name or a label path like "account_id.name".`);
426
435
  }
436
+ if (s.subtitle !== undefined && (typeof s.subtitle !== 'string' || !FIELD_PATH.test(s.subtitle.trim()))) {
437
+ throw new Error(`${at} has a "subtitle" that is not a field name or a label path like "income_frequency": the line under the figure.`);
438
+ }
427
439
  if (s.note !== undefined && (typeof s.note !== 'string' || !s.note.trim() || s.note.trim().length > 300)) {
428
440
  throw new Error(`${at} has a "note" that is not text of at most 300 characters.`);
429
441
  }
@@ -446,8 +458,10 @@ function parseSection(entry, at, config) {
446
458
  names: s.names === false ? false : undefined,
447
459
  ...(s.presentation === undefined ? {} : { presentation: s.presentation }),
448
460
  ...(s.editable === true ? { edit: true } : {}),
461
+ ...(s.empty === 'hide' || s.empty === 'show' ? { emptyMode: s.empty } : {}),
449
462
  ...(s.links === undefined ? {} : { actions: parseHeadlineActions(s.links, at) }),
450
463
  ...(s.subfigure === undefined ? {} : { subfigure: s.subfigure.trim() }),
464
+ ...(s.subtitle === undefined ? {} : { subtitle: s.subtitle.trim() }),
451
465
  ...(s.was === undefined ? {} : { was: s.was.trim() }),
452
466
  ...(s.note === undefined ? {} : { note: s.note.trim() }),
453
467
  };
@@ -467,6 +481,14 @@ function parseSection(entry, at, config) {
467
481
  throw new Error(`${here} is not an object.`);
468
482
  const t = raw;
469
483
  refuseRenamed(t, here, ['path', 'tint']);
484
+ /* The parts as the row draws them. `show` and `detail` read the opposite of how they were drawn (the main value
485
+ leads, the badge sits beside who and when): they are refused with their new names, not read. */
486
+ for (const [was, now] of [
487
+ ['show', 'text'],
488
+ ['detail', 'badge'],
489
+ ])
490
+ if (t[was] !== undefined)
491
+ throw new Error(`${here} has "${was}", which is now "${now}"${now === 'text' ? " — the row's main value" : ' — the quiet word beside who and when'}.`);
470
492
  allowKeys(t, STREAM_KEYS, here);
471
493
  const from = typeof t.from === 'string' ? t.from.trim() : '';
472
494
  if (!from)
@@ -477,9 +499,9 @@ function parseSection(entry, at, config) {
477
499
  const atCol = typeof t.at === 'string' ? t.at.trim() : '';
478
500
  if (!atCol)
479
501
  throw new Error(`${here} has no "at" — the date column the stream is ordered by.`);
480
- const show = typeof t.show === 'string' ? t.show.trim() : '';
481
- if (!show)
482
- throw new Error(`${here} has no "show" — the line each row becomes.`);
502
+ const text = typeof t.text === 'string' ? t.text.trim() : '';
503
+ if (!text)
504
+ throw new Error(`${here} has no "text" — the line each row becomes.`);
483
505
  /* `query` is the one spelling; the internal stream keeps its `filter`.
484
506
  `author` says who wrote a row, where `by` groups one everywhere else;
485
507
  the internal stream keeps its `by`. */
@@ -501,8 +523,8 @@ function parseSection(entry, at, config) {
501
523
  from,
502
524
  path,
503
525
  at: atCol,
504
- show,
505
- detail: t.detail === undefined ? undefined : String(t.detail).trim() || undefined,
526
+ text,
527
+ badge: t.badge === undefined ? undefined : String(t.badge).trim() || undefined,
506
528
  by: t.author === undefined ? undefined : String(t.author).trim() || undefined,
507
529
  filter: filterRaw === undefined ? undefined : String(filterRaw).trim() || undefined,
508
530
  ...(typeof t.side === 'string' ? { side: t.side.trim() } : {}),
@@ -631,7 +653,6 @@ function parseSection(entry, at, config) {
631
653
  ...(when ? { when } : {}),
632
654
  ...(s.variant === undefined ? {} : { variant: s.variant }),
633
655
  text: s.text.trim(),
634
- ...(s.icon === undefined ? {} : { icon: parseIcon(s.icon, at) }),
635
656
  ...(action ? { action } : {}),
636
657
  };
637
658
  }
@@ -681,7 +702,10 @@ function parseSection(entry, at, config) {
681
702
  editable: 'is gone: the lines of a record are edited in its form (a form\'s "lines")',
682
703
  order: 'is gone with the editable lines; a list sorts with "sort"',
683
704
  }
684
- : {});
705
+ : {
706
+ subtitle: "is a second line under a record's own figure, read from a column of the record (headline(figure, { subtitle })); " +
707
+ 'a measured figure has no record\'s column to read it from. Say it in the figure\'s "unit" or its title',
708
+ });
685
709
  const from = typeof s.from === 'string' ? s.from.trim() : '';
686
710
  if (!from)
687
711
  throw new Error(`${at} has no "from" table.`);
@@ -768,6 +792,20 @@ function parseSection(entry, at, config) {
768
792
  sort = parsed[0].direction === 'desc' ? `${parsed[0].column} desc` : parsed[0].column;
769
793
  }
770
794
  }
795
+ if (s.curve !== undefined) {
796
+ if (s.curve !== 'smooth' && s.curve !== 'straight')
797
+ throw new Error(`${at} has a "curve" of ${JSON.stringify(s.curve)}. Use "smooth" or "straight".`);
798
+ if (s.shape !== undefined && s.shape !== 'line')
799
+ throw new Error(`${at} is a ${String(s.shape)} chart; only a line has a "curve".`);
800
+ }
801
+ if (s.total !== undefined) {
802
+ if (s.shape !== 'donut')
803
+ throw new Error(`${at} has a "total", which names a donut's middle figure; it is not a donut.`);
804
+ if (typeof s.total !== 'string' || !s.total.trim() || s.total.trim().length > 40)
805
+ throw new Error(`${at} has a "total" that is not a few words (at most 40 characters): what the middle figure counts.`);
806
+ }
807
+ if (s.empty !== undefined && s.empty !== 'hide')
808
+ throw new Error(`${at} has "empty": ${JSON.stringify(s.empty)}. A chart takes 'hide', which leaves it out while it has nothing to draw.`);
771
809
  const { fn, column } = parseMeasure(s.measure, at);
772
810
  return {
773
811
  kind: 'chart',
@@ -790,6 +828,9 @@ function parseSection(entry, at, config) {
790
828
  ...(s.limit === undefined ? {} : { limit: s.limit }),
791
829
  ...(s.height === undefined ? {} : { height: s.height }),
792
830
  ...(s.target === undefined ? {} : { target: s.target }),
831
+ ...(s.curve === undefined ? {} : { curve: s.curve }),
832
+ ...(s.total === undefined ? {} : { total: s.total.trim() }),
833
+ ...(s.empty === 'hide' ? { emptyMode: 'hide' } : {}),
793
834
  ...figureWords,
794
835
  };
795
836
  }
@@ -801,6 +842,8 @@ function parseSection(entry, at, config) {
801
842
  if (s.limit !== undefined && (typeof s.limit !== 'number' || !Number.isInteger(s.limit) || s.limit < 1)) {
802
843
  throw new Error(`${at} has a "limit" that is not a positive whole number.`);
803
844
  }
845
+ if (s.empty !== undefined && s.empty !== 'hide')
846
+ throw new Error(`${at} has "empty": ${JSON.stringify(s.empty)}. A breakdown takes 'hide', which leaves it out while it has nothing to count.`);
804
847
  const measure = parseMeasure(s.measure, at);
805
848
  return {
806
849
  kind: 'breakdown',
@@ -821,6 +864,7 @@ function parseSection(entry, at, config) {
821
864
  by,
822
865
  filter,
823
866
  limit: s.limit,
867
+ ...(s.empty === 'hide' ? { emptyMode: 'hide' } : {}),
824
868
  ...figureWords,
825
869
  };
826
870
  }
@@ -840,8 +884,13 @@ function parseSection(entry, at, config) {
840
884
  /* The one current row as a card — the active lease, the latest visit —
841
885
  chosen by the list's query and sort: one row, so nothing to page, sum
842
886
  or add under it. */
843
- if (current && (s.empty === false || s.empty === 'hide' || s.empty === 'collapse'))
844
- throw new Error(`${at} is a current() card; say what no row means with "empty" guidance rather than leaving it out.`);
887
+ /* The reference a card over a link table opens, instead of the link row: judged against the catalog with the page. */
888
+ if (s.opens !== undefined && !current)
889
+ throw new Error(`${at} has "opens", which belongs on a current() card.`);
890
+ if (s.opens !== undefined && (typeof s.opens !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(s.opens.trim())))
891
+ throw new Error(`${at} has an "opens" that is not a reference column of "${from}", e.g. "conversation_id".`);
892
+ if (current && (s.empty === false || s.empty === 'collapse'))
893
+ throw new Error(`${at} is a current() card; say what no row means with "empty" guidance, or leave it out while there is none with empty: 'hide'.`);
845
894
  if (s.presentation !== undefined && s.presentation !== 'gallery' && !current) {
846
895
  const raw = s.presentation;
847
896
  if (!raw || typeof raw !== 'object' || Array.isArray(raw) || raw.kind !== 'cards') {
@@ -929,6 +978,7 @@ function parseSection(entry, at, config) {
929
978
  ...(shown?.labels ? { labels: shown.labels } : {}),
930
979
  filter,
931
980
  limit: s.presentation === 'card' ? 1 : s.limit,
981
+ ...(typeof s.opens === 'string' ? { opens: s.opens.trim() } : {}),
932
982
  orderBy: parseSort(s.sort, at),
933
983
  ...(s.create === undefined ? {} : s.create === false ? { noCreate: true } : { create: parseRelatedCreate(s.create, at) }),
934
984
  ...(s.empty === undefined || emptyMode ? {} : { empty: parseListEmpty(s.empty, at) }),
@@ -1047,7 +1097,7 @@ function parseHeader(s, at) {
1047
1097
  if (['status', 'facts', 'primary', 'destructive', 'actions'].every((key) => s[key] === undefined)) {
1048
1098
  throw new Error(`${at}: a record header says something: a "status", "facts", its "primary" verb, its "destructive" ones or the "actions" it draws.`);
1049
1099
  }
1050
- const facts = s.facts === undefined ? undefined : parseFacts(s.facts, `${at}, header`);
1100
+ const facts = s.facts === undefined ? undefined : parseFacts(s.facts, `${at}, header`, 'facts', HEADER_MAX_FACTS);
1051
1101
  return {
1052
1102
  kind: 'fields',
1053
1103
  presentation: 'header',
@@ -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
  /**