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

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 (64) hide show
  1. package/dist/adapters/adapter.d.ts +35 -2
  2. package/dist/adapters/adapter.js +32 -1
  3. package/dist/adapters/postgres.js +8 -4
  4. package/dist/adapters/scoped/scopedReads.js +23 -5
  5. package/dist/adapters/scoped/sqliteTriggers.js +65 -38
  6. package/dist/adapters/sqlite.js +8 -4
  7. package/dist/server/columnGrants.d.ts +5 -0
  8. package/dist/server/connections.d.ts +1 -0
  9. package/dist/server/connections.js +13 -3
  10. package/dist/server/http/firstPaint.d.ts +5 -1
  11. package/dist/server/http/firstPaint.js +4 -4
  12. package/dist/server/httpConnection.d.ts +4 -2
  13. package/dist/server/httpConnection.js +10 -3
  14. package/dist/server/journalStore.d.ts +2 -2
  15. package/dist/server/journalStore.js +33 -10
  16. package/dist/server/resourceReadHttp.d.ts +4 -2
  17. package/dist/server/resourceReadHttp.js +40 -4
  18. package/dist/server/resourceReadOperations.d.ts +4 -0
  19. package/dist/server/scaffoldMachine.js +12 -1
  20. package/dist/shared/boardLanes.d.ts +44 -0
  21. package/dist/shared/boardLanes.js +69 -0
  22. package/dist/shared/builtInThemes.js +26 -20
  23. package/dist/shared/dashboardAsks.d.ts +2 -0
  24. package/dist/shared/filter.d.ts +2 -0
  25. package/dist/shared/filter.js +3 -2
  26. package/dist/shared/form.d.ts +24 -1
  27. package/dist/shared/form.js +53 -0
  28. package/dist/shared/keysetPage.js +3 -0
  29. package/dist/shared/listInference.d.ts +91 -0
  30. package/dist/shared/listInference.js +323 -0
  31. package/dist/shared/listPresentations.d.ts +3 -0
  32. package/dist/shared/listQuestion.d.ts +2 -0
  33. package/dist/shared/listQuestion.js +1 -0
  34. package/dist/shared/pageAnatomy.d.ts +27 -3
  35. package/dist/shared/pageAnatomy.js +217 -36
  36. package/dist/shared/pageModel.d.ts +17 -1
  37. package/dist/shared/pageModel.js +8 -0
  38. package/dist/shared/query.d.ts +2 -0
  39. package/dist/shared/query.js +11 -3
  40. package/dist/shared/reads.d.ts +9 -0
  41. package/dist/shared/reads.js +9 -0
  42. package/dist/shared/recordLabel.d.ts +5 -0
  43. package/dist/shared/recordLabel.js +22 -2
  44. package/dist/shared/recordReads.d.ts +30 -0
  45. package/dist/shared/recordReads.js +72 -8
  46. package/dist/shared/referenceSubline.d.ts +18 -0
  47. package/dist/shared/referenceSubline.js +62 -0
  48. package/dist/shared/resourceHttp.d.ts +5 -0
  49. package/dist/shared/rowScope.js +52 -6
  50. package/dist/shared/schema.d.ts +2 -0
  51. package/dist/shared/servedApp.d.ts +18 -0
  52. package/dist/shared/servedApp.js +10 -0
  53. package/dist/shared/theme.js +20 -3
  54. package/dist/shared/themeLooks.js +61 -35
  55. package/dist/shared/themeRecipeWords.d.ts +5 -0
  56. package/dist/shared/themeRecipeWords.js +6 -1
  57. package/dist/shared/themeRecipes.d.ts +6 -1
  58. package/dist/shared/themeRecipes.js +4 -0
  59. package/dist/shared/themeType.js +2 -1
  60. package/dist/shared/view.js +29 -2
  61. package/dist/shared/viewLabels.js +16 -0
  62. package/dist/shared/viewPaths.d.ts +9 -0
  63. package/package.json +4 -1
  64. package/schema/theme.d.ts +9 -4
@@ -30,7 +30,9 @@
30
30
  import { subtitlePath } from './subtitlePath.js';
31
31
  import { listSecondLineColumns } from './appListColumns.js';
32
32
  import { findTable, labelPath, primaryKey } from './schema.js';
33
- 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';
34
36
  import { assertNever } from './model.js';
35
37
  import { andQuery, quoteValue } from './query.js';
36
38
  import { tabMatches } from './addressParams.js';
@@ -148,6 +150,13 @@ export function headerColumns(names, base, section) {
148
150
  const namePath = namePathOf(names, base);
149
151
  if (namePath && !fetched.includes(namePath))
150
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);
151
160
  /* A fact's second line is drawn under its value, as a field's is. */
152
161
  for (const second of secondLines(names, base, section.paths ?? []))
153
162
  if (!fetched.includes(second))
@@ -237,14 +246,33 @@ export function historyBody(base, key, limit) {
237
246
  * is opened, as ever, and asked for nothing here.
238
247
  */
239
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) {
240
266
  const drawn = new Set();
267
+ const runs = [];
268
+ const inferred = isInferredPage(page, appPage);
241
269
  const shownAll = page.sections.map((section, index) => ({ section, index })).filter(({ section }) => !section.hidden);
242
270
  const header = shownAll.find(({ section }) => section.kind === 'fields' && section.presentation === 'header');
243
271
  if (header)
244
272
  drawn.add(header.index);
245
273
  const hasAside = page.sections.some((section) => section.region === 'aside' && !section.hidden);
246
274
  const autoTabs = appPage ? page.listTabs === true : page.listTabs !== false;
247
- const tabbed = (section) => section.kind === 'list' && section.presentation !== 'gallery' && (section.width === undefined || !appPage);
275
+ const tabbed = (section) => tabbedSection(section, appPage, inferred);
248
276
  const lay = (items, listTabs, scoped) => {
249
277
  for (let i = 0; i < items.length; i += 1) {
250
278
  if (!(listTabs && autoTabs && tabbed(items[i].section))) {
@@ -255,14 +283,15 @@ export function drawnSections(schema, page, tab, appPage) {
255
283
  while (end + 1 < items.length && tabbed(items[end + 1].section))
256
284
  end += 1;
257
285
  const run = items.slice(i, end + 1);
258
- if (run.length === 1)
286
+ if (run.length === 1) {
259
287
  drawn.add(run[0].index);
288
+ runs.push([run[0].index]);
289
+ }
260
290
  else {
261
- const token = (item) => scoped
262
- ? `section:${item.index}`
263
- : (item.section.title ?? findTable(schema, item.section.from ?? '')?.name ?? item.section.from ?? '');
291
+ const token = (item) => (scoped ? `section:${item.index}` : listTabToken(schema, item.section));
264
292
  const asked = run.findIndex((item) => tabMatches(token(item), tab));
265
293
  drawn.add(run[asked === -1 ? 0 : asked].index);
294
+ runs.push(run.map((item) => item.index));
266
295
  }
267
296
  i = end;
268
297
  }
@@ -293,7 +322,35 @@ export function drawnSections(schema, page, tab, appPage) {
293
322
  });
294
323
  lay(shown.slice(first).filter((item) => !item.section.tab), true, scoped);
295
324
  }
296
- 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;
297
354
  }
298
355
  /**
299
356
  * Every read a record page's sections will ask for when it opens on `tab`,
@@ -304,7 +361,7 @@ export function drawnSections(schema, page, tab, appPage) {
304
361
  * asked for.
305
362
  */
306
363
  export function recordPageReads(names, page, base, plans, key, options) {
307
- const drawn = drawnSections(names.schema, page, options.tab, names.app);
364
+ const { drawn, runs } = laidSections(names.schema, page, options.tab, names.app);
308
365
  /* Each reader of the row with its own columns, too: the one read of all of
309
366
  them is refused whole where any column is, and then each is asked alone,
310
367
  as the sections would have been. */
@@ -394,5 +451,12 @@ export function recordPageReads(names, page, base, plans, key, options) {
394
451
  assertNever(section.kind, 'page section kind');
395
452
  }
396
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
+ }
397
461
  return { row: [...new Set(parts.flatMap((part) => part.columns))], parts, reads };
398
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.
@@ -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
+ }
@@ -707,6 +707,11 @@ function stateFindings(theme, name, at, palette, all) {
707
707
  names its own block (nav.current) is measured on that instead. */
708
708
  if (recipes.nav === 'pill' && !palette.navCurrent)
709
709
  check("navAccent/accentSoft over navGround (the pill menu's current entry)", color('navAccent'), soft && nav ? over(soft, nav) : undefined);
710
+ /* A round avatar look draws the sidebar's identity mark in the menu's accent on a 12% tint of that accent, laid on
711
+ the menu's ground (lumenLook.css). */
712
+ const navAccent = color('navAccent');
713
+ if (recipes.avatar === 'round')
714
+ check('navAccent/its own tint over navGround (the identity mark)', navAccent, tintOver(navAccent, nav));
710
715
  /* The search is a field on the surface in the page's ink (themeFamilies.css), a pair the page's checks read; the
711
716
  dark bar alone draws it on an 8% ink tint of its own ground in its muted ink (brandLook.css). */
712
717
  if (recipes.bar === 'dark')
@@ -758,13 +763,17 @@ function stateFindings(theme, name, at, palette, all) {
758
763
  for (const [part, style] of Object.entries(theme.parts ?? {})) {
759
764
  if (!style || (style.ground === undefined && style.ink === undefined))
760
765
  continue;
761
- const ink = style.ink ? pathRole(style.ink) : partInk(part);
766
+ const round = recipes.avatar === 'round';
767
+ const ink = style.ink ? pathRole(style.ink) : partInk(part, round);
762
768
  const ground = style.ground ? pathRole(style.ground) : partGround(part, palette);
763
769
  if (!ink || !ground)
764
770
  continue;
765
771
  const said = (role) => rolePath(role);
766
772
  const label = `parts.${part}: ${ink} on ${ground}`;
767
- const foreground = color(ink), background = color(ground);
773
+ /* A round mark left on its own ground is drawn on a 12% tint of the menu's accent over the menu (lumenLook.css),
774
+ not on the menu's ground itself. */
775
+ const tinted = part === 'identityMark' && round && !style.ground;
776
+ const foreground = color(ink), background = tinted ? tintOver(color('navAccent'), color('navGround')) : color(ground);
768
777
  if (!foreground || !background)
769
778
  continue;
770
779
  const ratio = measuredContrast(foreground, background);
@@ -781,9 +790,15 @@ function stateFindings(theme, name, at, palette, all) {
781
790
  }
782
791
  return result;
783
792
  }
793
+ /** The round identity mark's ground: its accent at 12% over the menu (lumenLook.css). */
794
+ function tintOver(accent, ground) {
795
+ return accent && ground ? over(mixColor(accent, [0, 0, 0, 0], 0.12), ground) : undefined;
796
+ }
784
797
  /** The ink a part's words are drawn in when its style says none: the menu's for the menu's parts, the link's for a
785
798
  link; a primary button's is the ink drawn on the accent fill. */
786
- function partInk(part) {
799
+ function partInk(part, round) {
800
+ if (part === 'identityMark')
801
+ return round ? 'navAccent' : 'navInk';
787
802
  if (part === 'button.primary')
788
803
  return 'onAccent';
789
804
  if (/^(?:nav|bar|logo)\b/.test(part))
@@ -792,6 +807,8 @@ function partInk(part) {
792
807
  }
793
808
  /** The ground a part is drawn on when its style says none. */
794
809
  function partGround(part, palette) {
810
+ if (part === 'identityMark')
811
+ return 'navGround';
795
812
  if (/^(?:nav|bar|logo)\b/.test(part))
796
813
  return 'navGround';
797
814
  if (part === 'button.primary')