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

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 (73) hide show
  1. package/README.md +5 -0
  2. package/dist/adapters/adapter.d.ts +35 -2
  3. package/dist/adapters/adapter.js +32 -1
  4. package/dist/adapters/postgres.js +8 -4
  5. package/dist/adapters/scoped/scopedReads.js +23 -5
  6. package/dist/adapters/scoped/sqliteTriggers.js +65 -38
  7. package/dist/adapters/sqlite.js +8 -4
  8. package/dist/host.d.ts +46 -0
  9. package/dist/host.js +51 -0
  10. package/dist/server/columnGrants.d.ts +5 -0
  11. package/dist/server/connections.d.ts +1 -0
  12. package/dist/server/connections.js +20 -1
  13. package/dist/server/http/exportRoute.d.ts +74 -0
  14. package/dist/server/http/exportRoute.js +206 -169
  15. package/dist/server/http/firstPaint.d.ts +5 -1
  16. package/dist/server/http/firstPaint.js +4 -4
  17. package/dist/server/http/reply.js +6 -0
  18. package/dist/server/httpConnection.d.ts +4 -2
  19. package/dist/server/httpConnection.js +10 -3
  20. package/dist/server/journal.d.ts +35 -6
  21. package/dist/server/journal.js +79 -8
  22. package/dist/server/journalStore.d.ts +37 -0
  23. package/dist/server/journalStore.js +375 -0
  24. package/dist/server/resourceReadHttp.d.ts +4 -2
  25. package/dist/server/resourceReadHttp.js +40 -4
  26. package/dist/server/resourceReadOperations.d.ts +4 -0
  27. package/dist/server/scaffoldMachine.js +12 -1
  28. package/dist/shared/appListColumns.d.ts +7 -0
  29. package/dist/shared/appListColumns.js +13 -0
  30. package/dist/shared/boardLanes.d.ts +44 -0
  31. package/dist/shared/boardLanes.js +69 -0
  32. package/dist/shared/builtInThemes.js +26 -20
  33. package/dist/shared/dashboardAsks.d.ts +2 -0
  34. package/dist/shared/filter.d.ts +2 -0
  35. package/dist/shared/filter.js +3 -2
  36. package/dist/shared/form.d.ts +24 -1
  37. package/dist/shared/form.js +53 -0
  38. package/dist/shared/keysetPage.js +3 -0
  39. package/dist/shared/listInference.d.ts +91 -0
  40. package/dist/shared/listInference.js +323 -0
  41. package/dist/shared/listPresentations.d.ts +3 -0
  42. package/dist/shared/listQuestion.d.ts +2 -0
  43. package/dist/shared/listQuestion.js +3 -2
  44. package/dist/shared/pageAnatomy.d.ts +27 -3
  45. package/dist/shared/pageAnatomy.js +217 -36
  46. package/dist/shared/pageModel.d.ts +17 -1
  47. package/dist/shared/pageModel.js +8 -0
  48. package/dist/shared/query.d.ts +2 -0
  49. package/dist/shared/query.js +11 -3
  50. package/dist/shared/reads.d.ts +9 -0
  51. package/dist/shared/reads.js +9 -0
  52. package/dist/shared/recordLabel.d.ts +5 -0
  53. package/dist/shared/recordLabel.js +22 -2
  54. package/dist/shared/recordReads.d.ts +30 -0
  55. package/dist/shared/recordReads.js +101 -19
  56. package/dist/shared/referenceSubline.d.ts +18 -0
  57. package/dist/shared/referenceSubline.js +62 -0
  58. package/dist/shared/resourceHttp.d.ts +5 -0
  59. package/dist/shared/rowScope.js +52 -6
  60. package/dist/shared/schema.d.ts +2 -0
  61. package/dist/shared/servedApp.d.ts +19 -1
  62. package/dist/shared/servedApp.js +10 -0
  63. package/dist/shared/themeLooks.js +61 -35
  64. package/dist/shared/themeRecipeWords.d.ts +5 -0
  65. package/dist/shared/themeRecipeWords.js +6 -1
  66. package/dist/shared/themeRecipes.d.ts +5 -0
  67. package/dist/shared/themeRecipes.js +3 -0
  68. package/dist/shared/themeType.js +2 -1
  69. package/dist/shared/view.js +29 -2
  70. package/dist/shared/viewLabels.js +16 -0
  71. package/dist/shared/viewPaths.d.ts +9 -0
  72. package/package.json +6 -1
  73. package/schema/theme.d.ts +8 -4
@@ -28,8 +28,11 @@
28
28
  * (pageFieldsRead.ts).
29
29
  */
30
30
  import { subtitlePath } from './subtitlePath.js';
31
+ import { listSecondLineColumns } from './appListColumns.js';
31
32
  import { findTable, labelPath, primaryKey } from './schema.js';
32
- import { DEFAULT_HISTORY_LIMIT, kindReading } from './pageModel.js';
33
+ import { DEFAULT_HISTORY_LIMIT, HISTORY_TAB, isInferredPage, kindReading } from './pageModel.js';
34
+ import { resolvePath } from './pagePaths.js';
35
+ import { COUNT_EACH_MAX } from './reads.js';
33
36
  import { assertNever } from './model.js';
34
37
  import { andQuery, quoteValue } from './query.js';
35
38
  import { tabMatches } from './addressParams.js';
@@ -74,6 +77,21 @@ export function defaultFieldPaths(base, app) {
74
77
  const read = base.columns.filter((c) => !app || !(surrogate(c) || version(c))).map((c) => c.name);
75
78
  return read.length ? read : base.columns.map((c) => c.name);
76
79
  }
80
+ /**
81
+ * The second lines of the columns at `paths`: a column whose rule has a `subtitle` is drawn with it wherever it is a
82
+ * field, a header's fact or a card's title, so the record reads it too (the same rule a list's cell reads,
83
+ * listQuestion.ts subtitleColumns). A path through a reference reads it from the table it reaches.
84
+ */
85
+ function secondLines(names, base, paths) {
86
+ if (!names.display)
87
+ return [];
88
+ return paths.flatMap((path) => {
89
+ const hop = path.lastIndexOf('.');
90
+ const owner = hop < 0 ? base.id : tableAtPrefix(names.schema, base.id, path.slice(0, hop))?.id;
91
+ const second = owner ? subtitlePath(names.display(owner, path.slice(hop + 1)), path) : undefined;
92
+ return second ? [second] : [];
93
+ });
94
+ }
77
95
  /** A fields section's columns: what it shows, the names of what it references, the record's name, and its workflow's field. */
78
96
  export function fieldsColumns(names, base, section) {
79
97
  const paths = section.paths?.length ? [...section.paths] : defaultFieldPaths(base, names.app);
@@ -91,16 +109,7 @@ export function fieldsColumns(names, base, section) {
91
109
  ]),
92
110
  ].filter((path) => !paths.includes(path))
93
111
  : [];
94
- /* A column whose rule has a `subtitle` is drawn with it wherever it is a field, so the record reads it too
95
- (the same rule a list's cell reads, listQuestion.ts subtitleColumns). */
96
- const seconds = names.display
97
- ? [...new Set([...paths, ...(section.presentation === 'headline' ? extra : [])])].flatMap((path) => {
98
- const hop = path.lastIndexOf('.');
99
- const owner = hop < 0 ? base.id : tableAtPrefix(names.schema, base.id, path.slice(0, hop))?.id;
100
- const second = owner ? subtitlePath(names.display(owner, path.slice(hop + 1)), path) : undefined;
101
- return second ? [second] : [];
102
- })
103
- : [];
112
+ const seconds = secondLines(names, base, [...new Set([...paths, ...(section.presentation === 'headline' ? extra : [])])]);
104
113
  const projection = referenceProjection(names.schema, base, [...new Set([...paths, ...extra, ...seconds])], section.names !== false && names.app, (table) => namePathOf(names, table));
105
114
  const fetched = projection.fetched;
106
115
  if (namePath && !fetched.includes(namePath))
@@ -141,6 +150,17 @@ export function headerColumns(names, base, section) {
141
150
  const namePath = namePathOf(names, base);
142
151
  if (namePath && !fetched.includes(namePath))
143
152
  fetched.push(namePath);
153
+ /* An inferred page's line under the record's name (pageAnatomy.ts). */
154
+ if (section.subtitle && !fetched.includes(section.subtitle))
155
+ fetched.push(section.subtitle);
156
+ /* And where a fact runs until: a visit's end, said with its start as one range. */
157
+ for (const end of Object.values(section.spans ?? {}))
158
+ if (!fetched.includes(end))
159
+ fetched.push(end);
160
+ /* A fact's second line is drawn under its value, as a field's is. */
161
+ for (const second of secondLines(names, base, section.paths ?? []))
162
+ if (!fetched.includes(second))
163
+ fetched.push(second);
144
164
  return { fetched, labels: projection.labels };
145
165
  }
146
166
  /** The key as a filter on the record's own row, one equality per key column. */
@@ -166,11 +186,18 @@ function probeColumns(names, base) {
166
186
  const namePath = namePathOf(names, base);
167
187
  return [...primaryKey(base), ...(namePath ? [namePath] : [])];
168
188
  }
189
+ const isCards = (presentation) => typeof presentation === 'object' && presentation !== null && presentation.kind === 'cards';
169
190
  /** A related list's first request: its planned view at the reader's page size, with the names and keys a row needs. */
170
191
  export function listView(names, section, plan, rows) {
171
192
  const table = names.table ? names.table(section.from ?? '') : findTable(names.schema, section.from ?? '');
172
193
  const limit = section.limit ?? rows;
173
- const view = plan.view && !section.limit ? { ...plan.view, limit } : plan.view;
194
+ const sized = plan.view && !section.limit ? { ...plan.view, limit } : plan.view;
195
+ /* Cards read the second lines of the columns they draw with one (appListColumns.ts listSecondLineColumns). */
196
+ const drawn = sized?.columns;
197
+ const seconds = table && drawn && isCards(section.presentation)
198
+ ? secondLines(names, table, listSecondLineColumns(section.presentation)).filter((path) => !drawn.some((c) => c.path === path))
199
+ : [];
200
+ const view = seconds.length ? { ...sized, columns: [...drawn, ...seconds.map((path) => ({ path }))] } : sized;
174
201
  const explicit = (target) => (names.recordLabel(target.id) === undefined ? undefined : namePathOf(names, target));
175
202
  return view && table
176
203
  ? recordView(names.schema, table, view, names.app, (target) => namePathOf(names, target), explicit)
@@ -219,14 +246,33 @@ export function historyBody(base, key, limit) {
219
246
  * is opened, as ever, and asked for nothing here.
220
247
  */
221
248
  export function drawnSections(schema, page, tab, appPage) {
249
+ return laidSections(schema, page, tab, appPage).drawn;
250
+ }
251
+ /** The address word a tab of a run of lists answers to: its list's title or table, an inferred page's history's own. */
252
+ function listTabToken(schema, section) {
253
+ return section.kind === 'history' ? HISTORY_TAB : (section.title ?? findTable(schema, section.from ?? '')?.name ?? section.from ?? '');
254
+ }
255
+ /**
256
+ * A section a run of lists draws as one of its tabs: a list that is no picture and has no width an author gave it,
257
+ * and on an inferred page its history, which ends the strip (pageAnatomy.ts) — read when its tab is opened, never
258
+ * with the page.
259
+ */
260
+ export function tabbedSection(section, appPage, inferred) {
261
+ return ((section.kind === 'list' && section.presentation !== 'gallery' && (section.width === undefined || !appPage)) ||
262
+ (inferred && section.kind === 'history'));
263
+ }
264
+ /** What drawnSections says, and each run of related lists by its sections' indexes: a strip of tabs, or a list alone. */
265
+ function laidSections(schema, page, tab, appPage) {
222
266
  const drawn = new Set();
267
+ const runs = [];
268
+ const inferred = isInferredPage(page, appPage);
223
269
  const shownAll = page.sections.map((section, index) => ({ section, index })).filter(({ section }) => !section.hidden);
224
270
  const header = shownAll.find(({ section }) => section.kind === 'fields' && section.presentation === 'header');
225
271
  if (header)
226
272
  drawn.add(header.index);
227
273
  const hasAside = page.sections.some((section) => section.region === 'aside' && !section.hidden);
228
274
  const autoTabs = appPage ? page.listTabs === true : page.listTabs !== false;
229
- const tabbed = (section) => section.kind === 'list' && section.presentation !== 'gallery' && (section.width === undefined || !appPage);
275
+ const tabbed = (section) => tabbedSection(section, appPage, inferred);
230
276
  const lay = (items, listTabs, scoped) => {
231
277
  for (let i = 0; i < items.length; i += 1) {
232
278
  if (!(listTabs && autoTabs && tabbed(items[i].section))) {
@@ -237,14 +283,15 @@ export function drawnSections(schema, page, tab, appPage) {
237
283
  while (end + 1 < items.length && tabbed(items[end + 1].section))
238
284
  end += 1;
239
285
  const run = items.slice(i, end + 1);
240
- if (run.length === 1)
286
+ if (run.length === 1) {
241
287
  drawn.add(run[0].index);
288
+ runs.push([run[0].index]);
289
+ }
242
290
  else {
243
- const token = (item) => scoped
244
- ? `section:${item.index}`
245
- : (item.section.title ?? findTable(schema, item.section.from ?? '')?.name ?? item.section.from ?? '');
291
+ const token = (item) => (scoped ? `section:${item.index}` : listTabToken(schema, item.section));
246
292
  const asked = run.findIndex((item) => tabMatches(token(item), tab));
247
293
  drawn.add(run[asked === -1 ? 0 : asked].index);
294
+ runs.push(run.map((item) => item.index));
248
295
  }
249
296
  i = end;
250
297
  }
@@ -275,7 +322,35 @@ export function drawnSections(schema, page, tab, appPage) {
275
322
  });
276
323
  lay(shown.slice(first).filter((item) => !item.section.tab), true, scoped);
277
324
  }
278
- return drawn;
325
+ return { drawn, runs };
326
+ }
327
+ /** A related tab's count's ceiling, as a list's total has one: past it the tab says "10,000+". */
328
+ export const RELATED_COUNT_LIMIT = 10_000;
329
+ /**
330
+ * The question a related tab's count asks, in the words `/api/counts` reads: the rows of its list that point at the
331
+ * record (`booking class_session_id = 5`), under the list's own narrowing. One hop to the record by its whole key,
332
+ * which is what an inferred page lists; any other list has no question, and its tab keeps the count's room empty.
333
+ */
334
+ export function relatedCountQuestion(schema, section, base, key) {
335
+ if (section.kind !== 'list' || !section.from || !section.path || section.of || section.similar || section.group)
336
+ return undefined;
337
+ const hop = resolvePath(schema, section.from, section.path).path;
338
+ if (hop?.hops.length !== 1 || hop.endsAt !== base.id)
339
+ return undefined;
340
+ const { from, to } = hop.hops[0];
341
+ if (to.columns.some((column) => key[column] === undefined || key[column] === null))
342
+ return undefined;
343
+ const meets = from.columns.map((column, i) => `${column} = ${quoteValue(String(key[to.columns[i]]))}`).join(' and ');
344
+ return `${section.from} ${andQuery(meets, section.filter)}`;
345
+ }
346
+ /**
347
+ * Every count a strip of related tabs shows, in one request: one statement for them all where each is a plain
348
+ * condition (countEach), never a list's read per tab. The client's strip asks this very body (PageSections.tsx),
349
+ * so on a composed page it is answered from the compose.
350
+ */
351
+ export function relatedCountsBody(schema, sections, base, key) {
352
+ const items = [...new Set(sections.flatMap((section) => relatedCountQuestion(schema, section, base, key) ?? []))].slice(0, COUNT_EACH_MAX);
353
+ return items.length ? { items, countLimit: RELATED_COUNT_LIMIT } : undefined;
279
354
  }
280
355
  /**
281
356
  * Every read a record page's sections will ask for when it opens on `tab`,
@@ -286,7 +361,7 @@ export function drawnSections(schema, page, tab, appPage) {
286
361
  * asked for.
287
362
  */
288
363
  export function recordPageReads(names, page, base, plans, key, options) {
289
- const drawn = drawnSections(names.schema, page, options.tab, names.app);
364
+ const { drawn, runs } = laidSections(names.schema, page, options.tab, names.app);
290
365
  /* Each reader of the row with its own columns, too: the one read of all of
291
366
  them is refused whole where any column is, and then each is asked alone,
292
367
  as the sections would have been. */
@@ -376,5 +451,12 @@ export function recordPageReads(names, page, base, plans, key, options) {
376
451
  assertNever(section.kind, 'page section kind');
377
452
  }
378
453
  });
454
+ /* An inferred page's tabs say how many rows each holds, all of them in one read; a list alone says it in its head. */
455
+ if (isInferredPage(page, names.app))
456
+ for (const run of runs) {
457
+ const body = relatedCountsBody(names.schema, run.map((index) => page.sections[index]), base, key);
458
+ if (body)
459
+ reads.push({ path: '/api/counts', body });
460
+ }
379
461
  return { row: [...new Set(parts.flatMap((part) => part.columns))], parts, reads };
380
462
  }
@@ -0,0 +1,18 @@
1
+ import { type DatabaseSchema, type TableMeta } from './schema.js';
2
+ export interface Subline {
3
+ /** The column, or a path through one reference (`account_id.name`), the second line reads. */
4
+ path: string;
5
+ /** The App said it (a display `subtitle`): drawn under every choice, not only where two names collide. */
6
+ declared: boolean;
7
+ }
8
+ /**
9
+ * The second line for a table's records, named by `label` (the column the reference is said by). Undefined where
10
+ * nothing tells them apart better than their key, which the caller already has.
11
+ */
12
+ export declare function referenceSubline(schema: DatabaseSchema | undefined, table: TableMeta, label: string | undefined, display?: Readonly<Record<string, {
13
+ subtitle?: unknown;
14
+ } | null | undefined>>): Subline | undefined;
15
+ /** A second line's value as read: a timestamp is said by its day, an empty value is no line. */
16
+ export declare function sublineText(value: unknown): string | undefined;
17
+ /** The names shown more than once among some choices: where a second line is drawn when the App did not ask for it. */
18
+ export declare function collidingNames(labels: readonly string[]): Set<string>;
@@ -0,0 +1,62 @@
1
+ /**
2
+ * The second line that tells two records of one name apart, wherever a
3
+ * reference is chosen or shown: a picker's choices, its chips, a record's
4
+ * aside cards. Two customers called "Ana Silva" are one choice too many until
5
+ * one reads "ana@north.example" under it.
6
+ *
7
+ * The rule is the list inference's sub-line, carried on: the subtitle the
8
+ * App's display rule gives the name column wins, then a code the record is
9
+ * quoted by (its number, SKU, reference — unique by the catalog), then the
10
+ * identifying fields a reference has and a list row does not need: an email,
11
+ * the parent it belongs to by name, the day it was made.
12
+ */
13
+ import { CODE } from './listInference.js';
14
+ import { columnKind, findTable, labelColumn, primaryKey } from './schema.js';
15
+ const EMAIL = /(^|_)e?mail(_address)?$/i;
16
+ const MADE = /^(created|opened|started|joined|hired|registered)(_at|_on|_date)?$|^(date_)?(created|opened)$/i;
17
+ const text = (column) => columnKind(column.type) === 'text';
18
+ /** Whether a reference points at a table whose records have a name of their own, and which column says it. */
19
+ function parentName(schema, column) {
20
+ const target = column.references ? findTable(schema, column.references.table) : undefined;
21
+ const named = target && labelColumn(target);
22
+ return target && named && !primaryKey(target).includes(named) ? named : undefined;
23
+ }
24
+ /**
25
+ * The second line for a table's records, named by `label` (the column the reference is said by). Undefined where
26
+ * nothing tells them apart better than their key, which the caller already has.
27
+ */
28
+ export function referenceSubline(schema, table, label, display) {
29
+ const own = (name) => table.columns.find((column) => column.name === name);
30
+ const subtitle = label ? display?.[label]?.subtitle : undefined;
31
+ if (typeof subtitle === 'string' && subtitle !== label && own(subtitle))
32
+ return { path: subtitle, declared: true };
33
+ const plain = table.columns.filter((column) => column.name !== label && !column.primaryKey && !column.references);
34
+ const code = plain.find((column) => text(column) && CODE.test(column.name) && (table.unique ?? []).includes(column.name));
35
+ if (code)
36
+ return { path: code.name, declared: false };
37
+ const email = plain.find((column) => text(column) && EMAIL.test(column.name));
38
+ if (email)
39
+ return { path: email.name, declared: false };
40
+ const parent = schema
41
+ ? table.columns.find((column) => column.name !== label && column.references && !column.nullable && parentName(schema, column))
42
+ : undefined;
43
+ if (parent)
44
+ return { path: `${parent.name}.${parentName(schema, parent)}`, declared: false };
45
+ const made = plain.find((column) => columnKind(column.type) === 'date' && MADE.test(column.name));
46
+ return made ? { path: made.name, declared: false } : undefined;
47
+ }
48
+ /** A second line's value as read: a timestamp is said by its day, an empty value is no line. */
49
+ export function sublineText(value) {
50
+ if (value === undefined || value === null || value === '')
51
+ return undefined;
52
+ const said = String(value);
53
+ return /^\d{4}-\d{2}-\d{2}[T ]\d{2}:/.test(said) ? said.slice(0, 10) : said;
54
+ }
55
+ /** The names shown more than once among some choices: where a second line is drawn when the App did not ask for it. */
56
+ export function collidingNames(labels) {
57
+ const seen = new Set();
58
+ const twice = new Set();
59
+ for (const label of labels)
60
+ (seen.has(label) ? twice : seen).add(label);
61
+ return twice;
62
+ }
@@ -42,6 +42,11 @@ interface HttpRunRequest extends HttpPaginationInput {
42
42
  countLimit?: number;
43
43
  /** `none` for a caller that never shows a total; `exact` is `exactCount`. */
44
44
  count?: 'none' | 'exact' | 'estimate';
45
+ /** A board's lanes in one read: the first `limit` rows (1 to 100) of each value of the column `by`, no total. */
46
+ lanes?: {
47
+ by: string;
48
+ limit: number;
49
+ };
45
50
  /** A page by key: the rows after a boundary (a reply's `bounds.last`), before one (`bounds.first`),
46
51
  * or the list's last `limit` rows. `offset` then only names the page; an order that cannot page by key reads by it. */
47
52
  after?: Boundary;
@@ -22,6 +22,36 @@ export const ROW_SCOPE_LIMITS = Object.freeze({
22
22
  const invalid = () => {
23
23
  throw new Refusal('Invalid row scope.');
24
24
  };
25
+ /* Past a size bound the scope is refused, never cut short, and the refusal says which bound, by how much and what to
26
+ do instead: "Invalid row scope." alone sent a policy author to guess, and one capped its own list to fit — a silent
27
+ truncation of who may see what, which is the thing the bound exists to refuse. */
28
+ const NEXT_STEP = 'Narrow the policy, or scope by a relationship instead of a list: give each scoped table a single-value column (its owner or tenant) and compare it with "=" (docs: Row access, "Bounds").';
29
+ const counted = (n) => n.toLocaleString('en-US');
30
+ const pastBound = (what, size, bound, unit, per, more = false) => {
31
+ const over = more ? 'more than ' : '';
32
+ throw new Refusal(`Invalid row scope: ${what} ${over}${counted(size)} ${unit}, ${over}${counted(size - bound)} past the bound of ${counted(bound)} ${per}. ${NEXT_STEP}`);
33
+ };
34
+ /** How many values a scope holds, as the copy counts them (a value met twice counts twice), for a refusal to say how
35
+ * far past the bound it went. Reads only data properties (never an accessor), as deep as the copy goes, and stops
36
+ * counting at `cap`, so a cycle ends. */
37
+ function valuesIn(input, cap) {
38
+ const pending = [[input, 0]];
39
+ let count = 0;
40
+ while (pending.length && count < cap) {
41
+ const [value, depth] = pending.pop();
42
+ count += 1;
43
+ if (!value || typeof value !== 'object' || depth >= 8)
44
+ continue;
45
+ for (const key of Reflect.ownKeys(value)) {
46
+ if (Array.isArray(value) && key === 'length')
47
+ continue;
48
+ const descriptor = Object.getOwnPropertyDescriptor(value, key);
49
+ if (descriptor && 'value' in descriptor && descriptor.enumerable)
50
+ pending.push([descriptor.value, depth + 1]);
51
+ }
52
+ }
53
+ return count;
54
+ }
25
55
  /** Copy before validation so accessors, prototypes and later mutation cannot
26
56
  * change what was checked. Bounds apply to the entire scope, not each table.
27
57
  * Frozen nested values stay private; Readonly<Record> alone is not a snapshot.
@@ -30,7 +60,12 @@ export function captureRowScope(input) {
30
60
  let nodes = 0;
31
61
  let characters = 0;
32
62
  const copy = (value, depth = 0) => {
33
- if (++nodes > ROW_SCOPE_LIMITS.nodes || depth > 8)
63
+ if (++nodes > ROW_SCOPE_LIMITS.nodes) {
64
+ const cap = ROW_SCOPE_LIMITS.nodes * 64;
65
+ const all = valuesIn(input, cap);
66
+ return pastBound('the scope holds', all, ROW_SCOPE_LIMITS.nodes, 'values', 'in one scope', all >= cap);
67
+ }
68
+ if (depth > 8)
34
69
  return invalid();
35
70
  if (typeof value === 'string') {
36
71
  characters += value.length;
@@ -47,11 +82,11 @@ export function captureRowScope(input) {
47
82
  if (array ? proto !== Array.prototype : proto !== Object.prototype && proto !== null)
48
83
  return invalid();
49
84
  const keys = Reflect.ownKeys(value);
50
- if (keys.length > ROW_SCOPE_LIMITS.array + 1)
51
- return invalid();
52
85
  if (array) {
53
86
  const length = Object.getOwnPropertyDescriptor(value, 'length')?.value;
54
- if (!Number.isInteger(length) || length > ROW_SCOPE_LIMITS.array || keys.length !== length + 1)
87
+ if (Number.isInteger(length) && length > ROW_SCOPE_LIMITS.array)
88
+ return pastBound('a list holds', length, ROW_SCOPE_LIMITS.array, 'values', 'per list');
89
+ if (!Number.isInteger(length) || keys.length !== length + 1)
55
90
  return invalid();
56
91
  const result = [];
57
92
  for (let i = 0; i < length; i++) {
@@ -62,6 +97,8 @@ export function captureRowScope(input) {
62
97
  }
63
98
  return Object.freeze(result);
64
99
  }
100
+ if (keys.length > ROW_SCOPE_LIMITS.array)
101
+ return pastBound('a record holds', keys.length, ROW_SCOPE_LIMITS.array, 'keys', 'per record');
65
102
  const result = Object.create(null);
66
103
  for (const key of keys) {
67
104
  if (typeof key !== 'string')
@@ -77,8 +114,11 @@ export function captureRowScope(input) {
77
114
  return Object.freeze(result);
78
115
  };
79
116
  const scope = copy(input);
80
- if (!scope || typeof scope !== 'object' || Array.isArray(scope) || Object.keys(scope).length > ROW_SCOPE_LIMITS.resources)
117
+ if (!scope || typeof scope !== 'object' || Array.isArray(scope))
81
118
  return invalid();
119
+ const resources = Object.keys(scope).length;
120
+ if (resources > ROW_SCOPE_LIMITS.resources)
121
+ return pastBound('the scope names', resources, ROW_SCOPE_LIMITS.resources, 'resources', 'in one scope');
82
122
  return scope;
83
123
  }
84
124
  /* The scopes this module copied, froze and checked, each with the catalogs it
@@ -166,7 +206,13 @@ export function snapshotRowScope(schema, input) {
166
206
  if (!Array.isArray(group) || !group.length)
167
207
  return invalid();
168
208
  for (const condition of group) {
169
- if (++conditions > ROW_SCOPE_LIMITS.conditions || !record(condition))
209
+ if (++conditions > ROW_SCOPE_LIMITS.conditions) {
210
+ // The copy is plain frozen data, so counting every group is safe; it says how far past the bound it went.
211
+ const all = Object.values(scope).reduce((sum, entry) => sum +
212
+ (record(entry) && Array.isArray(entry.groups) ? entry.groups.reduce((n, g) => n + (Array.isArray(g) ? g.length : 0), 0) : 0), 0);
213
+ return pastBound('the scope holds', all, ROW_SCOPE_LIMITS.conditions, 'conditions', 'in one scope');
214
+ }
215
+ if (!record(condition))
170
216
  return invalid();
171
217
  if (Object.keys(condition).some((key) => !['column', 'op', 'value'].includes(key)))
172
218
  return invalid();
@@ -377,6 +377,8 @@ export declare function declaredOrder(column: Pick<ColumnMeta, 'type' | 'allowed
377
377
  export interface Order {
378
378
  column: string;
379
379
  direction: 'asc' | 'desc';
380
+ /** An empty value after every other, whichever way the column runs (a sort's `nulls last`). */
381
+ nulls?: 'last';
380
382
  }
381
383
  /**
382
384
  * The order a table's rows are shown in when the query does not say.
@@ -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. */
@@ -482,6 +482,11 @@ export interface AppShell {
482
482
  /** With the side placement: folding the sidebar leaves a rail of the
483
483
  entries' icons by default. Set false to hide it completely. */
484
484
  rail?: boolean;
485
+ /** With the side placement: where the bar's furniture stands at a desk — in the sidebar itself (`'sidebar'`, the
486
+ default), whose head holds the mark, New and the search, and whose foot holds the bell and the account, each
487
+ room's own head row then its first line; or across the top of the window (`'bar'`). Unsaid beside `rail: false`,
488
+ the bar (sidebarShell.js `headerInSidebar`). */
489
+ header?: (typeof SHELL_HEADERS)[number];
485
490
  /** Show the sidebar menu filter. Defaults to false in Apps. */
486
491
  menuSearch?: boolean;
487
492
  /** Show live row counts beside the App menu's lists of work: a list whose condition picks its machine's unfinished states, a date at or before today (said in the danger's ink), or the reader (me). A list's own count: true or false says otherwise. Defaults to false; Workbench estimates remain. */
@@ -532,6 +537,8 @@ export interface AppSidebar {
532
537
  };
533
538
  }
534
539
  export declare const PLACEMENTS: readonly ['side', 'top'];
540
+ /** Where a side-placed App's bar stands (`ui.shell.header`). */
541
+ export declare const SHELL_HEADERS: readonly ['bar', 'sidebar'];
535
542
  /** An entry as served: the view it opens, the command that view runs when it is a form, and its words. */
536
543
  export interface ServedShellNew {
537
544
  view: string;
@@ -668,6 +675,11 @@ export interface ServedApp<View extends object = ServedDashboardView | ServedFor
668
675
  page?: true;
669
676
  record?: true;
670
677
  };
678
+ /** The menu holds more than `DIRECTORY_AT` places: a Directory room lists them all, at `/{app}/all-pages`. Its icon
679
+ is named here so its glyph rides the payload, as the assistant's does. */
680
+ directory?: {
681
+ icon: import('./appIcons.js').AppIconName;
682
+ };
671
683
  }
672
684
  /** A menu node as the view order reads it: a view's reference, a group of nodes, or a link elsewhere. */
673
685
  export type ServedNavNode = {
@@ -693,4 +705,10 @@ export declare function viewOrder(app: {
693
705
  /** The assistant's own room, where its App gives it a page (`placement: 'page'`, appAssistant.ts): its word in
694
706
  * nav, and its address, `/{app}/assistant` and `/{app}/assistant/{conversation}` for one conversation. */
695
707
  export declare const ASSISTANT_ROOM = "assistant";
708
+ /** The Directory's address, `/{app}/all-pages`: every list, page and New of a long menu, with a filter box. */
709
+ export declare const DIRECTORY_ROOM = "all-pages";
710
+ /** How many places a menu holds before a Directory is offered beside it: past a dozen, scanning a menu is a search. */
711
+ export declare const DIRECTORY_AT = 12;
712
+ /** The places a served menu leads to — its views and its links, not the headings over them. */
713
+ export declare function navPlaces(nav: readonly AppPayloadNavNode[]): number;
696
714
  export {};
@@ -1,4 +1,6 @@
1
1
  export const PLACEMENTS = ['side', 'top'];
2
+ /** Where a side-placed App's bar stands (`ui.shell.header`). */
3
+ export const SHELL_HEADERS = ['bar', 'sidebar'];
2
4
  /**
3
5
  * The entries this reader may use, in the App's order. Its words are the
4
6
  * entry's own, else a list's noun ("Ticket", its resource's singular) or the
@@ -43,3 +45,11 @@ export function viewOrder(app) {
43
45
  /** The assistant's own room, where its App gives it a page (`placement: 'page'`, appAssistant.ts): its word in
44
46
  * nav, and its address, `/{app}/assistant` and `/{app}/assistant/{conversation}` for one conversation. */
45
47
  export const ASSISTANT_ROOM = 'assistant';
48
+ /** The Directory's address, `/{app}/all-pages`: every list, page and New of a long menu, with a filter box. */
49
+ export const DIRECTORY_ROOM = 'all-pages';
50
+ /** How many places a menu holds before a Directory is offered beside it: past a dozen, scanning a menu is a search. */
51
+ export const DIRECTORY_AT = 12;
52
+ /** The places a served menu leads to — its views and its links, not the headings over them. */
53
+ export function navPlaces(nav) {
54
+ return nav.reduce((count, node) => count + ('children' in node ? navPlaces(node.children) : 1), 0);
55
+ }