@mistriwork/engine 1.0.0-rc.17 → 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 (63) 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/themeLooks.js +61 -35
  54. package/dist/shared/themeRecipeWords.d.ts +5 -0
  55. package/dist/shared/themeRecipeWords.js +6 -1
  56. package/dist/shared/themeRecipes.d.ts +5 -0
  57. package/dist/shared/themeRecipes.js +3 -0
  58. package/dist/shared/themeType.js +2 -1
  59. package/dist/shared/view.js +29 -2
  60. package/dist/shared/viewLabels.js +16 -0
  61. package/dist/shared/viewPaths.d.ts +9 -0
  62. package/package.json +4 -1
  63. package/schema/theme.d.ts +8 -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
+ }
@@ -59,7 +59,7 @@ function withPalettes(look) {
59
59
  The title weight (`type.roles.title.weight`) is never past 700: a heavier
60
60
  ask resolved a book face to its Black cut, a masthead where a title was
61
61
  meant, and broke the record's head. Mono titles at 700; Lumen's and Sage's
62
- softer titles at 600; Workshop's condensed capitals at 700.
62
+ softer titles at 600; Workshop's condensed bold at 700.
63
63
 
64
64
  Each wears every palette in lookPalettes.ts; its own colors are its
65
65
  default palette's (Workshop's Safety orange, Lumen's Cobalt, Mono's and
@@ -67,30 +67,40 @@ function withPalettes(look) {
67
67
  book's own deep green). */
68
68
  const HOUSE = [
69
69
  {
70
- // The desk as a workbench, ported from a field report's theme: warm paper,
71
- // ink-black type and fills, and one restrained hue — Safety orange unless
72
- // a palette says another. The hue reaches only the marks a reader takes
73
- // for the brand color: the primary verb (the ink's words on it, as a
74
- // hazard tag prints them), links and the current tab's rule, a 3px marker
75
- // beside the menu's ink block (like a tool's slot on a pegboard), the
76
- // focus ring, a checked box and the first chart series. Fills, rules and
77
- // selection stay the ink, and nothing is tinted. Titles, section heads
78
- // and labels are Barlow's semi-condensed bold in capitals, the rest
79
- // Barlow; heavy 2px ink rules part the sections and stand under a
80
- // table's heads, corners are near-square and nothing floats; the menu
81
- // sits on a faint grain (workshopLook.css; docs/design.md, Workshop).
70
+ // The desk as a workbench, ported from a field report's theme, and
71
+ // refreshed in rc.18 so the work sits on white: the warm paper and its
72
+ // grain frame it (the top bar, the menu and one band behind a page's
73
+ // head: a list's title, tabs and filters, a record's trail, name and
74
+ // facts), as a sheet is clipped to a board, and rows, fields and cards
75
+ // stay white. Ink-black type and one restrained hue — Safety orange
76
+ // unless a palette says another. The hue reaches only the marks a reader
77
+ // takes for the brand color: the primary verb, filled, with the ink's
78
+ // words on it as a hazard tag prints them (the look's one idea), links
79
+ // and the current tab's rule, a 3px marker beside the menu's current
80
+ // entry (like a tool's slot on a pegboard), the focus ring, a checked
81
+ // box and the first chart series. The current entry is a soft tint of
82
+ // the menu's ink, by day and by night: the brightest thing on a screen
83
+ // is the orange verb, never the menu. Barlow's semi-condensed bold sets
84
+ // the titles, in sentence case, a stat's figures and the App's name, the
85
+ // one word in capitals (the brand's stamp); sections, tabs, column heads
86
+ // and labels are Barlow in sentence case, the labels in the muted ink.
87
+ // Hairlines part the sections and close a table's heads, corners are
88
+ // near-square and nothing floats (workshopLook.css; docs/design.md,
89
+ // Workshop).
82
90
  id: 'workshop',
83
91
  label: 'Workshop',
84
92
  defaultPalette: 'safety',
85
93
  colors: {
86
94
  light: {
87
- ground: '#f2ede3',
88
- surface: '#faf8f3',
89
- raised: '#ece6da',
95
+ // White to work on; the paper (#f2ede3) is the frame's: the menu, the bar and the band behind a page's head,
96
+ // which is the raised ground (recipes.header 'band'), so a hovered row is the paper too.
97
+ ground: '#fbfaf7',
98
+ surface: '#ffffff',
99
+ raised: '#f2ede3',
90
100
  ink: '#1b1813',
91
101
  inkMuted: '#4f483d',
92
102
  inkSubtle: '#5f574b',
93
- line: '#ddd5c6',
103
+ line: '#e6e1d8',
94
104
  lineStrong: '#8b8274',
95
105
  lineControl: '#7d7466',
96
106
  accentInk: '#1b1813',
@@ -100,54 +110,65 @@ const HOUSE = [
100
110
  shadow: '#3a3020',
101
111
  status: { good: '#106b38', warning: '#934a06', critical: '#c52a2a', info: '#2f5578' },
102
112
  nav: {
103
- ground: '#ebe5d9',
113
+ ground: '#f2ede3',
104
114
  ink: '#1b1813',
105
115
  muted: '#4f483d',
106
116
  line: '#d8cfbe',
107
117
  accent: '#1b1813',
118
+ // The current entry: the ink at 7% over the paper, in the ink, its orange slot kept (workshopLook.css).
119
+ current: '#e3ded4',
120
+ onCurrent: '#1b1813',
108
121
  },
109
- rules: { section: '#1b1813', head: '#1b1813' },
122
+ // Hairlines, not 2px of ink: a section and a table's heads stand on the rule a row does.
123
+ rules: { section: '#e6e1d8', head: '#e6e1d8' },
110
124
  chart: ['#2b2620', '#9a6cf7', '#0e9a6c', '#d97706', '#e0428a', '#0e8fb0', '#a3510b', '#94a3b8'],
111
125
  },
112
126
  dark: {
113
- ground: '#15130f',
114
- surface: '#1d1a15',
115
- raised: '#26221c',
127
+ ground: '#121110',
128
+ surface: '#1a1917',
129
+ raised: '#24221f',
116
130
  ink: '#efe9de',
117
131
  inkMuted: '#c2b9aa',
118
132
  inkSubtle: '#a59c8d',
119
- line: '#2f2a22',
133
+ line: '#2c2a26',
120
134
  lineStrong: '#6d6555',
121
135
  lineControl: '#7a7262',
122
136
  accentInk: '#efe9de',
123
- accentSoft: '#2c261e',
137
+ accentSoft: '#2a2723',
124
138
  primary: '#efe9de',
125
139
  link: '#efe9de',
126
140
  status: { good: '#4ade80', warning: '#fbbf24', critical: '#f87171', info: '#91a8ff' },
127
141
  nav: {
128
- ground: '#110f0c',
142
+ ground: '#0f0e0d',
129
143
  ink: '#efe9de',
130
144
  muted: '#b3aa9b',
131
- line: '#26221c',
145
+ line: '#24221f',
132
146
  accent: '#efe9de',
147
+ // The ink at 10% over the menu's ground, not the inverted cream block, which was the brightest thing on a
148
+ // screen at night.
149
+ current: '#252422',
150
+ onCurrent: '#efe9de',
133
151
  },
134
- rules: { section: '#8a8170', head: '#8a8170' },
152
+ rules: { section: '#2c2a26', head: '#2c2a26' },
135
153
  chart: ['#d9d0c0', '#9a78ec', '#12a678', '#c88317', '#e0559b', '#1597b9', '#d26b3b', '#6b7694'],
136
154
  },
137
155
  },
138
156
  shape: {
139
157
  radius: { control: '2px', field: '2px', pill: '2px', panel: '2px' },
140
158
  elevation: 'flat',
141
- border: { panel: '1px', rule: '2px' },
159
+ border: { panel: '1px', rule: '1px' },
142
160
  },
143
161
  type: {
144
162
  font: { ui: BARLOW, data: BARLOW, heading: BARLOW_CONDENSED },
145
163
  base: '14px',
146
164
  roles: {
147
- title: { face: 'heading', size: '30px', weight: 700, case: 'upper', tracking: '0.01em', leading: 1.1 },
148
- heading: { face: 'heading', size: '22px', weight: 700, case: 'upper', tracking: '0.01em' },
149
- section: { face: 'heading', size: '15px', weight: 700, case: 'upper', tracking: '0.04em' },
150
- label: { face: 'heading', weight: 700, case: 'upper', tracking: '0.06em' },
165
+ // A page still names itself in the workshop's voice, the condensed bold, in sentence case.
166
+ title: { face: 'heading', size: '28px', weight: 700, case: 'none', tracking: '0em', leading: 1.15 },
167
+ heading: { face: 'heading', size: '23px', weight: 700, case: 'none', tracking: '0em' },
168
+ section: { face: 'ui', size: '15px', weight: 600, case: 'none', tracking: '0em' },
169
+ // A step under the base, in the semibold the look already ships: Barlow comes at 400 and 600 only, so a 500
170
+ // drew at 400, as loud as the values under it. The muted ink (parts below) keeps the 600 quieter than a value.
171
+ label: { face: 'ui', size: '12px', weight: 600, case: 'none', tracking: '0em' },
151
172
  data: { features: ['tnum'] },
152
173
  figure: { face: 'heading', size: '38px', weight: 700, features: ['tnum'] },
153
174
  nav: { weight: 500 },
@@ -162,7 +183,8 @@ const HOUSE = [
162
183
  bar: 'ruled',
163
184
  tabs: 'rule',
164
185
  windows: 'segmented',
165
- stat: 'ruled',
186
+ // One divided strip of figures, not a 2px ink rule over each.
187
+ stat: 'divided',
166
188
  section: 'open',
167
189
  fields: 'open',
168
190
  table: 'open',
@@ -170,14 +192,17 @@ const HOUSE = [
170
192
  board: 'ruled',
171
193
  chart: 'plain',
172
194
  buttons: 'keyed',
195
+ // A filter not yet asked for is a key on a solid edge, as the search beside it is, not a dashed place.
196
+ filters: 'solid',
173
197
  links: 'plain',
174
- rules: 'ink',
198
+ rules: 'hairline',
175
199
  avatar: 'plain',
176
200
  workflow: 'markers',
177
201
  banner: 'plain',
178
202
  steps: 'strip',
179
203
  lanes: 'tag',
180
- header: 'plain',
204
+ // The paper under a page's head: the frame reaches the title, tabs and filters, and the rows start on white.
205
+ header: 'band',
181
206
  },
182
207
  },
183
208
  {
@@ -283,6 +308,7 @@ const HOUSE = [
283
308
  board: 'strip',
284
309
  chart: 'line',
285
310
  buttons: 'raised',
311
+ filters: 'quiet',
286
312
  rules: 'hairline',
287
313
  avatar: 'round',
288
314
  workflow: 'markers',
@@ -127,6 +127,11 @@ export declare const RECIPE_WORDS: {
127
127
  readonly band: 'A record’s head and a list’s are one band of the raised ground from edge to edge: the trail, the title, its status, facts and verbs, a list’s tabs and filters; the contents keep their edge.';
128
128
  readonly hero: 'A band, with the record’s avatar large beside its title (above it on a phone); a record without one, and a list, draw the band.';
129
129
  };
130
+ readonly filters: {
131
+ readonly dashed: 'A list’s filter not yet asked for is its name behind a +, on a dashed hairline: a place for a filter, not a field.';
132
+ readonly solid: 'A list’s filter not yet asked for is its name behind a + on a solid edge: a key, as the search beside it is, not a place.';
133
+ readonly quiet: 'A list’s filter not yet asked for has no edge, its name in the muted ink, until a pointer is over it: then it sits on the raised ground.';
134
+ };
130
135
  readonly required: {
131
136
  readonly star: 'A required field wears a red star after its label; an optional one wears nothing.';
132
137
  readonly 'optional-word': 'A required field wears nothing and an optional one says “(optional)” after its label, quietly; the form’s own words, in the reader’s language.';
@@ -115,6 +115,11 @@ export const RECIPE_WORDS = {
115
115
  band: 'A record’s head and a list’s are one band of the raised ground from edge to edge: the trail, the title, its status, facts and verbs, a list’s tabs and filters; the contents keep their edge.',
116
116
  hero: 'A band, with the record’s avatar large beside its title (above it on a phone); a record without one, and a list, draw the band.',
117
117
  },
118
+ filters: {
119
+ dashed: 'A list’s filter not yet asked for is its name behind a +, on a dashed hairline: a place for a filter, not a field.',
120
+ solid: 'A list’s filter not yet asked for is its name behind a + on a solid edge: a key, as the search beside it is, not a place.',
121
+ quiet: 'A list’s filter not yet asked for has no edge, its name in the muted ink, until a pointer is over it: then it sits on the raised ground.',
122
+ },
118
123
  required: {
119
124
  star: 'A required field wears a red star after its label; an optional one wears nothing.',
120
125
  'optional-word': 'A required field wears nothing and an optional one says “(optional)” after its label, quietly; the form’s own words, in the reader’s language.',
@@ -149,7 +154,7 @@ export const TYPE_WORDS = {
149
154
  heading: 'A list naming itself over its rows: its face, size (16px to 28px), leading, tracking, weight (omitted, the title’s), case and features.',
150
155
  section: 'A section’s title on a record and a dashboard: its face, case and features; a dashboard’s section title also takes a size (12px to 20px), tracking and weight.',
151
156
  body: 'Prose, fields and the interface, at the base size: its leading (1.35 to 1.8) and features.',
152
- label: 'A column’s head, a stat’s label and a record’s tabs, at the base size: their face, tracking, weight (400 to 700), case and features; upper sets them a step smaller.',
157
+ label: 'A column’s head, a stat’s label and a record’s tabs, at the base size: their face, size (11px to 14px), tracking, weight (400 to 700), case and features; upper sets them a step smaller unless a size is said.',
153
158
  data: 'A table’s cells and a record’s values, in the data face at the base size: their features, tabular figures kept, and its reach: every value, or figures only (figures, keys and dates, a record header’s facts too).',
154
159
  figure: 'A stat’s figure: its face, size (18px to 40px), tracking, weight and features, tabular figures kept.',
155
160
  nav: 'The menu’s entries in the bar, at the base size: their face, tracking, weight (400 to 600) and case; upper sets them a step smaller.',