ezship 0.1.12 → 0.1.14

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.
package/commands.mjs CHANGED
@@ -426,6 +426,82 @@ export function parseSchedules(source, files) {
426
426
  });
427
427
  return errors.length ? { entries: [], errors } : { entries, errors };
428
428
  }
429
+
430
+ /**
431
+ * The optional page.json of a Site and of the Global Workspace (ADR 0148): the deployed page's settings. The
432
+ * Global one sets every Site's, a Site's own overrides it key by key, and the Pipeline writes the result
433
+ * into the page's head.
434
+ * @type {typeof import("./commands.d.mts").PAGE_FILE}
435
+ */
436
+ export const PAGE_FILE = "page.json";
437
+ /** @type {typeof import("./commands.d.mts").PAGE_ICON_MAX} */
438
+ export const PAGE_ICON_MAX = 16_000;
439
+ const PAGE_KEYS = ["icon"];
440
+ /**
441
+ * The browser icon of a page whose Site and Global Workspace set none: a ship's wheel.
442
+ * @type {typeof import("./commands.d.mts").DEFAULT_PAGE_ICON}
443
+ */
444
+ export const DEFAULT_PAGE_ICON =
445
+ '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">' +
446
+ '<g fill="none" stroke="#9a5b24" stroke-linecap="round">' +
447
+ '<path stroke-width="2" d="M16 4v24M4 16h24M7.5 7.5l17 17M24.5 7.5l-17 17"/>' +
448
+ '<path stroke-width="3.6" d="M16 1.8v3M16 27.2v3M1.8 16h3M27.2 16h3M5.96 5.96l2.12 2.12M23.92 23.92l2.12 2.12M26.04 5.96l-2.12 2.12M8.08 23.92l-2.12 2.12"/>' +
449
+ '<circle cx="16" cy="16" r="9.6" stroke-width="3"/>' +
450
+ "</g>" +
451
+ '<circle cx="16" cy="16" r="3.6" fill="#9a5b24"/>' +
452
+ '<circle cx="16" cy="16" r="1.3" fill="#f3d9a8"/>' +
453
+ "</svg>";
454
+
455
+ /**
456
+ * The settings of a page.json and every problem with it; page is empty when there is any problem.
457
+ * @type {typeof import("./commands.d.mts").parsePage}
458
+ */
459
+ export function parsePage(source) {
460
+ let parsed;
461
+ try {
462
+ parsed = JSON.parse(source);
463
+ } catch (error) {
464
+ const why = error instanceof Error ? error.message : String(error);
465
+ return { page: {}, errors: [`${PAGE_FILE} is not JSON: ${why}`] };
466
+ }
467
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
468
+ return {
469
+ page: {},
470
+ errors: [`${PAGE_FILE} is a JSON object: { "icon": "<svg ...>...</svg>" }.`],
471
+ };
472
+ /** @type {string[]} */
473
+ const errors = [];
474
+ for (const key of Object.keys(parsed))
475
+ if (!PAGE_KEYS.includes(key))
476
+ errors.push(`${PAGE_FILE}: unknown key "${key}"; it has ${PAGE_KEYS.join(", ")}.`);
477
+ const { icon } = /** @type {Record<string, unknown>} */ (parsed);
478
+ if (icon !== undefined) {
479
+ const svg = typeof icon === "string" ? icon.trim() : "";
480
+ if (!/^<svg[\s>]/.test(svg) || !/<\/svg>$|\/>$/.test(svg))
481
+ errors.push(
482
+ `${PAGE_FILE}: icon is the markup of one SVG image, from <svg to </svg>, as a JSON string.`,
483
+ );
484
+ else if (!/^<svg[^>]*\sxmlns=["']http:\/\/www\.w3\.org\/2000\/svg["']/.test(svg))
485
+ errors.push(
486
+ `${PAGE_FILE}: icon's <svg> needs xmlns="http://www.w3.org/2000/svg", or browsers draw nothing.`,
487
+ );
488
+ else if (svg.length > PAGE_ICON_MAX)
489
+ errors.push(`${PAGE_FILE}: icon is at most ${PAGE_ICON_MAX} characters of SVG.`);
490
+ }
491
+ if (errors.length) return { page: {}, errors };
492
+ return { page: icon === undefined ? {} : { icon: /** @type {string} */ (icon).trim() }, errors };
493
+ }
494
+
495
+ /**
496
+ * The browser icon a Site's page shows: its own page.json's, else the Global Workspace's, else the default.
497
+ * @type {typeof import("./commands.d.mts").pageIcon}
498
+ */
499
+ export function pageIcon(files, global) {
500
+ const own = (/** @type {string | undefined} */ source) =>
501
+ source === undefined ? undefined : parsePage(source).page.icon;
502
+ return own(files[PAGE_FILE]) ?? own(global[PAGE_FILE]) ?? DEFAULT_PAGE_ICON;
503
+ }
504
+
429
505
  /**
430
506
  * lib/<name>.ts in the Global Workspace (ADR 0077): pure TypeScript every Site's pages, components and server
431
507
  * functions import as `global/lib/<name>`. Named exports; whatever reads or writes takes the database as an argument.
@@ -683,7 +759,7 @@ export function isValidFilePath(path) {
683
759
  const INVALID_PATH = (p) =>
684
760
  `Invalid path: ${p}. Use relative paths like components/Hello.tsx (no leading slash, no ..).`;
685
761
 
686
- const SITE_SHAPE = `A Site is ${MAIN_FILE}, required ${CONTEXT_FILE}, ${PAGES_DIR}<route>.tsx, ${COMPONENTS_DIR}<Name>.tsx, ${HOOKS_DIR}use<Name>.ts, ${FUNCTIONS_DIR}<name>.ts, ${LOCAL_DIR}<name>.ts, ${LISTENERS_DIR}<name>.ts, ${CONSTANTS_FILE}, ${DOCS_DIR}<name>.md (Markdown docs), optional ${LISTENERS_FILE} and optional ${STYLE_FILE}. Schema, generated types and scheduled jobs belong to the Global Workspace.`;
762
+ const SITE_SHAPE = `A Site is ${MAIN_FILE}, required ${CONTEXT_FILE}, ${PAGES_DIR}<route>.tsx, ${COMPONENTS_DIR}<Name>.tsx, ${HOOKS_DIR}use<Name>.ts, ${FUNCTIONS_DIR}<name>.ts, ${LOCAL_DIR}<name>.ts, ${LISTENERS_DIR}<name>.ts, ${CONSTANTS_FILE}, ${DOCS_DIR}<name>.md (Markdown docs), optional ${LISTENERS_FILE}, optional ${PAGE_FILE} (the browser icon) and optional ${STYLE_FILE}. Schema, generated types and scheduled jobs belong to the Global Workspace.`;
687
763
 
688
764
  /**
689
765
  * Why required context is invalid, or null. Content quality is guided by the instructions, not parsed.
@@ -802,7 +878,7 @@ const hookPathError = (/** @type {string} */ path, /** @type {string} */ shape)
802
878
  export function siteFileError(path) {
803
879
  if (!isValidFilePath(path)) return INVALID_PATH(path);
804
880
  if (functionName(path) || localFunctionName(path) || listenerName(path)) return null;
805
- if (path === LISTENERS_FILE) return null;
881
+ if (path === LISTENERS_FILE || path === PAGE_FILE) return null;
806
882
  // ADR 0136: schedules belong to the Instance.
807
883
  if (path === SCHEDULES_FILE || path.startsWith(JOBS_DIR))
808
884
  return `${path}: scheduled jobs belong to the Global Workspace now: global/${SCHEDULES_FILE} and global/${JOBS_DIR}<name>.ts (ez global put). Move what a job shares with this Site to global/lib/<name>.ts and global/constants.ts, then delete the Site's copy.`;
@@ -839,7 +915,7 @@ export function siteFileError(path) {
839
915
  return `${path} is not a Site file. ${SITE_SHAPE}`;
840
916
  }
841
917
 
842
- const GLOBAL_SHAPE = `The Global Workspace is required ${CONTEXT_FILE}, ${COMPONENTS_DIR}<Name>.tsx, ${DOCUMENTS_DIR}<Name>.tsx (PDF templates), ${HOOKS_DIR}use<Name>.ts (custom hooks), ${LIB_DIR}<name>.ts (shared logic), ${CONSTANTS_FILE} (plain values), ${SHELL_FILE} (optional), ${SESSION_FILE} (Provided values and Session State, optional), ${STYLE_FILE} (the theme, optional), ${SCHEMA_FILE}, ${ACCESS_FILE} (who reads and writes which rows, optional), ${RULES_DIR}<table>.ts (each Table's derive and guard rules, optional), ${WORKFLOWS_DIR}<table>.ts (a Table's status workflow, optional), ${JOBS_DIR}<name>.ts (scheduled jobs, optional), ${SCHEDULES_FILE} (when each job runs, optional), ${DOCS_DIR}<name>.md (Markdown docs, optional) and generated ${TYPES_FILE}.`;
918
+ const GLOBAL_SHAPE = `The Global Workspace is required ${CONTEXT_FILE}, ${COMPONENTS_DIR}<Name>.tsx, ${DOCUMENTS_DIR}<Name>.tsx (PDF templates), ${HOOKS_DIR}use<Name>.ts (custom hooks), ${LIB_DIR}<name>.ts (shared logic), ${CONSTANTS_FILE} (plain values), ${SHELL_FILE} (optional), ${SESSION_FILE} (Provided values and Session State, optional), ${STYLE_FILE} (the theme, optional), ${SCHEMA_FILE}, ${ACCESS_FILE} (who reads and writes which rows, optional), ${RULES_DIR}<table>.ts (each Table's derive and guard rules, optional), ${WORKFLOWS_DIR}<table>.ts (a Table's status workflow, optional), ${JOBS_DIR}<name>.ts (scheduled jobs, optional), ${SCHEDULES_FILE} (when each job runs, optional), ${DOCS_DIR}<name>.md (Markdown docs, optional), ${PAGE_FILE} (every Site's browser icon, optional) and generated ${TYPES_FILE}.`;
843
919
 
844
920
  /**
845
921
  * Why a path may not be in the Global Workspace, or null when it may.
@@ -856,6 +932,7 @@ export function globalFileError(path) {
856
932
  path === SCHEMA_FILE ||
857
933
  path === ACCESS_FILE ||
858
934
  path === SCHEDULES_FILE ||
935
+ path === PAGE_FILE ||
859
936
  path === TYPES_FILE
860
937
  )
861
938
  return null;
@@ -1002,9 +1079,10 @@ Generated db/types.d.ts is the reference for row types; do not copy it here.
1002
1079
 
1003
1080
  ## Shared UI
1004
1081
  Map components, constants, Shell.tsx and the theme to their responsibilities and usage.
1005
- The Instance started with a theme (style.css), a Shell (the top bar; BRAND in constants.ts) and the
1006
- components Badge, StateBadge, Stat, Panel, Empty, Field, Money, When, Yes, DataTable, Pager and SearchBox;
1007
- edit, replace or delete them, and record here what you decide about them.
1082
+ The Instance started with a theme (style.css: tokens in :root, then the classes), a Shell (the top bar;
1083
+ BRAND in constants.ts) and the components Button, PageHeader, Panel, Stat, Badge, StateBadge, Notice,
1084
+ Dialog, ConfirmDialog, Tabs, FilterChips, SearchBox, DataTable, Pager, DetailList, Field, Empty, Money,
1085
+ When and Yes; edit, replace or delete them, and record here what you decide about them.
1008
1086
 
1009
1087
  ## Decisions and constraints
1010
1088
  Record shared decisions, their reasons, known limitations and open questions.
@@ -1016,134 +1094,332 @@ Record shared decisions, their reasons, known limitations and open questions.
1016
1094
 
1017
1095
  /**
1018
1096
  * What a new Instance's Global Workspace starts with, on top of DEFAULT_GLOBAL_FILES: a theme, a Shell with a
1019
- * nav slot, and the components every suite so far has rebuilt (Badge, StateBadge, Stat, Panel, Empty, Field,
1020
- * Money, When, Yes, DataTable, Pager, SearchBox; docs/adr/0108). Written once at
1097
+ * nav slot and the menu, and the components every suite so far has rebuilt (docs/adr/0108, 0147). Written once at
1021
1098
  * Instance creation as Version 0; a customer edits, replaces or deletes them like any global file. Not a
1022
1099
  * Framework Kit (`planning/react-sites/issues/01`): nothing here is imported unless a Site imports it.
1023
1100
  * @type {typeof import("./commands.d.mts").STARTER_GLOBAL_FILES}
1024
1101
  */
1025
1102
  export const STARTER_GLOBAL_FILES = Object.freeze({
1026
- "style.css": `/* The starter theme, loaded before every Site's own style.css. Edit or replace it; the classes below are what the starter components use. */
1103
+ "style.css": `/* The starter theme, loaded before every Site's own style.css. Rebrand by changing the tokens in :root; the
1104
+ classes below are what the starter components and the Framework's RecordForm and RecordList draw with. */
1027
1105
  :root {
1028
- --bg: #f3f4f1;
1106
+ --bg: #f6f7f9;
1029
1107
  --surface: #ffffff;
1030
- --text: #1a1f1a;
1031
- --muted: #6b7280;
1032
- --line: #e3e5df;
1033
- --line-strong: #c9ccc3;
1034
- --primary: #0f6b4f;
1035
- --primary-hover: #0c5740;
1036
- --accent: #e8f3ee;
1037
- --warn: #b45309;
1038
- --warn-bg: #fef3c7;
1039
- --danger: #b91c1c;
1040
- --danger-bg: #fee2e2;
1041
- --danger-hover: #991b1b;
1042
- --info-bg: #dbeafe;
1043
- --info: #1d4ed8;
1044
- --ok-bg: #dcfce7;
1045
- --ok: #166534;
1046
- --dark: #12211b;
1108
+ --surface-2: #f1f3f6;
1109
+ --hover: #eef0f4;
1110
+ --text: #16181d;
1111
+ --muted: #646b78;
1112
+ --faint: #9aa1ad;
1113
+ --line: #e3e6eb;
1114
+ --line-strong: #cdd2da;
1115
+ --primary: #2f5bd3;
1116
+ --primary-hover: #2449b3;
1117
+ --primary-soft: #edf2fd;
1118
+ --primary-text: #ffffff;
1119
+ --focus: rgb(47 91 211 / 0.35);
1120
+ --ok: #18794e;
1121
+ --ok-bg: #e7f6ee;
1122
+ --info: #2f5bd3;
1123
+ --info-bg: #edf2fd;
1124
+ --warn: #9a5b00;
1125
+ --warn-bg: #fdf3dc;
1126
+ --danger: #c4302b;
1127
+ --danger-hover: #a3231f;
1128
+ --danger-bg: #fdecec;
1129
+ --dark: #1d2129;
1130
+ --radius: 6px;
1131
+ --radius-lg: 10px;
1132
+ --shadow: 0 1px 2px rgb(16 24 40 / 0.05);
1133
+ --shadow-lg: 0 16px 48px rgb(16 24 40 / 0.18);
1134
+ --control: 2.25rem;
1135
+ --font: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", sans-serif;
1136
+ --mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
1137
+ /* Kept for Site styles written against the first starter theme. */
1138
+ --accent: var(--primary-soft);
1139
+ }
1140
+ /* Fingers need bigger targets than a mouse: every control grows on a touch screen. */
1141
+ @media (pointer: coarse) {
1142
+ :root { --control: 2.75rem; }
1047
1143
  }
1048
- * { box-sizing: border-box; }
1049
- body { margin: 0; background: var(--bg); color: var(--text); font: 15px/1.45 system-ui, -apple-system, "Segoe UI", sans-serif; }
1050
- button, input, select, textarea { font: inherit; }
1051
- a { color: var(--primary); }
1052
- h1 { font-size: 1.5rem; margin: 0; letter-spacing: -0.01em; }
1053
- h2 { font-size: 1.05rem; font-weight: 650; margin: 0; }
1054
- h3 { font-size: 0.95rem; font-weight: 650; margin: 0; }
1055
-
1056
- .ez-shell { display: flex; flex-wrap: wrap; gap: 2px 4px; padding: 4px 16px; background: #0b1611; font-size: 12px; }
1057
- .ez-shell a { color: #9fb3a8; padding: 4px 10px; border-radius: 6px; text-decoration: none; }
1058
- .ez-shell a[aria-current="page"] { background: #1f3a2e; color: #fff; }
1059
-
1060
- .topbar { display: flex; align-items: center; gap: 14px; padding: 10px 20px; background: var(--dark); color: #fff; }
1061
- .topbar .brand { font-weight: 700; letter-spacing: 0.12em; font-size: 12px; text-transform: uppercase; color: #bfe3d2; }
1062
- .topbar .app-name { font-weight: 600; font-size: 15px; }
1063
- .topbar nav { margin-left: auto; display: flex; gap: 4px; flex-wrap: wrap; }
1064
- .topbar nav a { color: #cfd9d3; text-decoration: none; padding: 6px 10px; border-radius: 6px; font-size: 13px; }
1065
- .topbar nav a:hover { background: #24382f; color: #fff; }
1066
- .topbar nav a[aria-current] { background: var(--primary); color: #fff; }
1067
-
1068
- .subnav { display: flex; gap: 2px; padding: 0 20px; background: var(--surface); border-bottom: 1px solid var(--line); overflow-x: auto; }
1069
- .subnav a { padding: 10px 12px; text-decoration: none; color: var(--muted); border-bottom: 2px solid transparent; white-space: nowrap; font-weight: 500; }
1070
- .subnav a[aria-current] { color: var(--primary); border-bottom-color: var(--primary); }
1071
-
1072
- .main { padding: 20px; max-width: 1400px; }
1073
- .page-head { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; margin-bottom: 16px; }
1074
- .page-head .spacer { flex: 1; }
1075
- .stack { display: flex; flex-direction: column; gap: 12px; }
1076
- .row { display: flex; flex-wrap: wrap; gap: 10px; align-items: center; }
1077
- .row-end { display: flex; flex-wrap: wrap; gap: 10px; align-items: flex-end; }
1078
- .grid-2, .grid-3, .grid-4 { display: grid; grid-template-columns: 1fr; gap: 14px; }
1079
- @media (min-width: 760px) { .grid-2 { grid-template-columns: 1fr 1fr; } .grid-3 { grid-template-columns: repeat(3, 1fr); } .grid-4 { grid-template-columns: repeat(4, 1fr); } }
1080
- .muted { color: var(--muted); }
1081
- .small { font-size: 0.85rem; }
1082
- .num { font-variant-numeric: tabular-nums; text-align: right; }
1083
- .mono { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 0.9em; }
1084
- .strong { font-weight: 600; }
1085
1144
 
1086
- .panel { background: var(--surface); border: 1px solid var(--line); border-radius: 10px; }
1087
- .panel > .panel-head { display: flex; align-items: center; gap: 10px; padding: 10px 14px; border-bottom: 1px solid var(--line); }
1088
- .panel > .panel-head .spacer { flex: 1; }
1089
- .panel > .panel-body { padding: 14px; }
1090
- .panel > .panel-body.flush { padding: 0; overflow-x: auto; border-radius: 0 0 9px 9px; }
1145
+ /* ---- base ---- */
1146
+ *, *::before, *::after { box-sizing: border-box; }
1147
+ html { -webkit-text-size-adjust: 100%; }
1148
+ body { margin: 0; background: var(--bg); color: var(--text); font: 14px/1.5 var(--font); -webkit-font-smoothing: antialiased; }
1149
+ h1, h2, h3, h4, p { margin: 0; }
1150
+ h1 { font-size: 1.375rem; line-height: 1.3; font-weight: 650; letter-spacing: -0.015em; }
1151
+ h2 { font-size: 1rem; line-height: 1.4; font-weight: 600; }
1152
+ h3 { font-size: 0.875rem; line-height: 1.4; font-weight: 600; }
1153
+ a { color: var(--primary); text-underline-offset: 2px; }
1154
+ a:hover { color: var(--primary-hover); }
1155
+ hr { border: 0; border-top: 1px solid var(--line); margin: 16px 0; }
1156
+ code, kbd, pre { font-family: var(--mono); font-size: 0.9em; }
1157
+ :focus-visible { outline: 2px solid var(--primary); outline-offset: 2px; }
1158
+ ::selection { background: var(--focus); }
1159
+
1160
+ /* ---- form controls: styled wherever they appear, inside a Field or not ---- */
1161
+ button, input, select, textarea { font: inherit; color: inherit; }
1162
+ input:not([type="checkbox"], [type="radio"], [type="range"], [type="file"], [type="color"]), select, textarea {
1163
+ max-width: 100%; min-height: var(--control); padding: 0 10px;
1164
+ background: var(--surface); border: 1px solid var(--line-strong); border-radius: var(--radius);
1165
+ transition: border-color 0.12s, box-shadow 0.12s;
1166
+ }
1167
+ textarea { padding: 8px 10px; min-height: 5.5rem; resize: vertical; line-height: 1.45; }
1168
+ select {
1169
+ appearance: none; padding-right: 30px; cursor: pointer;
1170
+ background: var(--surface) url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 12 12'%3E%3Cpath d='M3 4.5 6 7.5 9 4.5' fill='none' stroke='%23646b78' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E") no-repeat right 10px center;
1171
+ }
1172
+ input:hover:not(:disabled, :focus), select:hover:not(:disabled, :focus), textarea:hover:not(:disabled, :focus) { border-color: var(--faint); }
1173
+ input:focus, select:focus, textarea:focus { outline: none; border-color: var(--primary); box-shadow: 0 0 0 3px var(--focus); }
1174
+ input:disabled, select:disabled, textarea:disabled { background: var(--surface-2); color: var(--muted); cursor: not-allowed; }
1175
+ input[aria-invalid="true"], select[aria-invalid="true"], textarea[aria-invalid="true"], .field.invalid :is(input, select, textarea) { border-color: var(--danger); }
1176
+ input::placeholder, textarea::placeholder { color: var(--faint); }
1177
+ input[type="checkbox"], input[type="radio"] { width: 16px; height: 16px; margin: 0; accent-color: var(--primary); cursor: pointer; }
1178
+ input[type="file"] { font-size: 0.875rem; }
1179
+
1180
+ /* ---- layout ---- */
1181
+ .main { width: 100%; max-width: 1440px; margin: 0 auto; padding: 24px; }
1182
+ .stack { display: flex; flex-direction: column; gap: 16px; }
1183
+ .stack-sm { display: flex; flex-direction: column; gap: 8px; }
1184
+ .stack-lg { display: flex; flex-direction: column; gap: 28px; }
1185
+ .row { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; }
1186
+ .row-end { display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-end; }
1187
+ .toolbar { display: flex; flex-wrap: wrap; gap: 8px 12px; align-items: flex-end; }
1188
+ .toolbar > .field { width: auto; flex: 1 1 180px; max-width: 320px; }
1189
+ .spacer { flex: 1; }
1190
+ .grid-2, .grid-3, .grid-4 { display: grid; grid-template-columns: minmax(0, 1fr); gap: 16px; align-items: start; }
1191
+ @media (min-width: 760px) {
1192
+ .grid-2 { grid-template-columns: repeat(2, minmax(0, 1fr)); }
1193
+ .grid-3 { grid-template-columns: repeat(3, minmax(0, 1fr)); }
1194
+ .grid-4 { grid-template-columns: repeat(2, minmax(0, 1fr)); }
1195
+ }
1196
+ @media (min-width: 1100px) { .grid-4 { grid-template-columns: repeat(4, minmax(0, 1fr)); } }
1197
+ @media (max-width: 640px) { .main { padding: 16px; } }
1091
1198
 
1092
- .stat { background: var(--surface); border: 1px solid var(--line); border-radius: 10px; padding: 12px 14px; }
1093
- .stat .label { color: var(--muted); font-size: 0.8rem; text-transform: uppercase; letter-spacing: 0.05em; }
1094
- .stat .value { font-size: 1.7rem; font-weight: 700; margin-top: 2px; font-variant-numeric: tabular-nums; }
1095
- .stat .hint { color: var(--muted); font-size: 0.8rem; }
1096
- .stat.warn .value { color: var(--warn); }
1097
- .stat.danger .value { color: var(--danger); }
1098
- .stat.ok .value { color: var(--ok); }
1199
+ /* ---- text ---- */
1200
+ .muted { color: var(--muted); }
1201
+ .small { font-size: 0.8125rem; }
1202
+ .strong { font-weight: 600; }
1203
+ .num { font-variant-numeric: tabular-nums; text-align: right; }
1204
+ .mono { font-family: var(--mono); font-size: 0.9em; }
1205
+ .nowrap { white-space: nowrap; }
1206
+ .truncate { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
1207
+
1208
+ /* ---- Shell ---- */
1209
+ .topbar { position: sticky; top: 0; z-index: 100; display: flex; align-items: center; gap: 16px; min-height: 52px; padding: 0 24px; background: var(--surface); border-bottom: 1px solid var(--line); }
1210
+ .topbar .brand { display: flex; align-items: baseline; gap: 10px; min-width: 0; white-space: nowrap; }
1211
+ .topbar .brand-name { font-weight: 700; font-size: 0.8125rem; letter-spacing: 0.06em; text-transform: uppercase; color: var(--muted); }
1212
+ .topbar .app-name { font-weight: 600; font-size: 0.9375rem; overflow: hidden; text-overflow: ellipsis; }
1213
+ .topbar nav { display: flex; gap: 2px; margin-left: auto; overflow-x: auto; scrollbar-width: none; }
1214
+ .topbar nav a { display: inline-flex; align-items: center; min-height: 34px; padding: 0 10px; border-radius: var(--radius); color: var(--muted); text-decoration: none; font-weight: 500; white-space: nowrap; }
1215
+ .topbar nav a:hover { background: var(--hover); color: var(--text); }
1216
+ .topbar nav a[aria-current] { background: var(--primary-soft); color: var(--primary); }
1217
+ @media (max-width: 640px) {
1218
+ .topbar { flex-wrap: wrap; gap: 4px 12px; padding: 8px 16px; }
1219
+ .topbar .brand { flex: 1; }
1220
+ .topbar nav { order: 2; width: 100%; margin-left: -10px; }
1221
+ }
1099
1222
 
1100
- table.data { width: 100%; border-collapse: collapse; font-size: 0.9rem; }
1101
- table.data th { text-align: left; color: var(--muted); font-weight: 600; font-size: 0.75rem; text-transform: uppercase; letter-spacing: 0.04em; padding: 8px 12px; border-bottom: 1px solid var(--line); white-space: nowrap; }
1102
- table.data td { padding: 8px 12px; border-bottom: 1px solid var(--line); vertical-align: middle; }
1103
- table.data tr:last-child td { border-bottom: 0; }
1223
+ /* ---- PageHeader (and RecordList's heading) ---- */
1224
+ .page-head { display: flex; flex-wrap: wrap; align-items: center; gap: 12px 16px; margin-bottom: 20px; }
1225
+ :is(.stack, .stack-sm, .stack-lg) > .page-head { margin-bottom: 0; }
1226
+ .page-head .page-title { display: flex; flex-direction: column; gap: 4px; min-width: 0; }
1227
+ .page-head .page-title p { color: var(--muted); max-width: 72ch; }
1228
+ .page-head .back { display: inline-flex; align-items: center; gap: 4px; color: var(--muted); font-size: 0.8125rem; text-decoration: none; }
1229
+ .page-head .back:hover { color: var(--text); }
1230
+ .page-head .meta { display: flex; flex-wrap: wrap; gap: 6px; align-items: center; }
1231
+ .page-head .actions { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; }
1232
+ .page-head input[type="search"] { width: 260px; }
1233
+
1234
+ /* ---- Panel ---- */
1235
+ .panel { background: var(--surface); border: 1px solid var(--line); border-radius: var(--radius-lg); box-shadow: var(--shadow); min-width: 0; }
1236
+ .panel > .panel-head { display: flex; flex-wrap: wrap; align-items: center; gap: 8px 12px; padding: 12px 16px; border-bottom: 1px solid var(--line); }
1237
+ .panel > .panel-head .panel-title { display: flex; flex-direction: column; gap: 2px; min-width: 0; }
1238
+ .panel > .panel-head .panel-title p { color: var(--muted); font-size: 0.8125rem; }
1239
+ .panel > .panel-head .actions { display: flex; flex-wrap: wrap; gap: 6px; margin-left: auto; }
1240
+ .panel > .panel-body { padding: 16px; }
1241
+ .panel > .panel-body.flush { padding: 0; overflow-x: auto; }
1242
+ .panel > .panel-body.flush:last-child { border-radius: 0 0 var(--radius-lg) var(--radius-lg); }
1243
+ .panel > .panel-foot { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; padding: 10px 16px; border-top: 1px solid var(--line); background: var(--surface-2); border-radius: 0 0 var(--radius-lg) var(--radius-lg); }
1244
+
1245
+ /* ---- Button ---- */
1246
+ /* inline-flex centres the label in a <Link className="btn"> too, which has no button's own centring. */
1247
+ .btn {
1248
+ position: relative; display: inline-flex; align-items: center; justify-content: center; gap: 6px; flex-shrink: 0;
1249
+ min-height: var(--control); padding: 0 14px; border-radius: var(--radius); border: 1px solid var(--line-strong);
1250
+ background: var(--surface); color: var(--text); font-weight: 500; line-height: 1.2; white-space: nowrap;
1251
+ text-decoration: none; cursor: pointer; user-select: none; box-shadow: var(--shadow);
1252
+ transition: background-color 0.12s, border-color 0.12s, color 0.12s;
1253
+ }
1254
+ .btn:hover { background: var(--hover); color: var(--text); }
1255
+ .btn.primary { background: var(--primary); border-color: var(--primary); color: var(--primary-text); }
1256
+ .btn.primary:hover { background: var(--primary-hover); border-color: var(--primary-hover); }
1257
+ .btn.danger { background: var(--danger); border-color: var(--danger); color: #fff; }
1258
+ .btn.danger:hover { background: var(--danger-hover); border-color: var(--danger-hover); }
1259
+ .btn.ghost { background: transparent; border-color: transparent; box-shadow: none; color: var(--muted); }
1260
+ .btn.ghost:hover { background: var(--hover); color: var(--text); }
1261
+ .btn.sm { min-height: calc(var(--control) - 0.5rem); padding: 0 10px; font-size: 0.8125rem; }
1262
+ .btn.icon { padding: 0; width: var(--control); }
1263
+ .btn.sm.icon { width: calc(var(--control) - 0.5rem); }
1264
+ .btn:disabled, .btn[aria-disabled="true"] { opacity: 0.55; cursor: not-allowed; pointer-events: none; }
1265
+ .btn[aria-busy="true"] { opacity: 1; cursor: progress; }
1266
+ .btn[aria-busy="true"] > .label { visibility: hidden; }
1267
+ .btn[aria-busy="true"] > .spinner { position: absolute; }
1268
+
1269
+ .spinner { display: inline-block; width: 14px; height: 14px; border: 2px solid currentColor; border-right-color: transparent; border-radius: 50%; animation: ez-spin 0.7s linear infinite; }
1270
+ @keyframes ez-spin { to { transform: rotate(360deg); } }
1271
+
1272
+ /* ---- Field ---- */
1273
+ .field { display: flex; flex-direction: column; gap: 6px; min-width: 0; }
1274
+ .field > span:first-child { font-size: 0.8125rem; font-weight: 500; color: var(--text); }
1275
+ .field .req { color: var(--danger); margin-left: 2px; }
1276
+ .field .field-hint { font-size: 0.8125rem; color: var(--muted); font-weight: 400; }
1277
+ .field .field-error { font-size: 0.8125rem; color: var(--danger); font-weight: 400; }
1278
+ .field :is(input:not([type="checkbox"], [type="radio"]), select, textarea) { width: 100%; }
1279
+ .field .readonly { min-height: var(--control); display: flex; align-items: center; color: var(--text); }
1280
+ .check { display: inline-flex; align-items: center; gap: 8px; min-height: var(--control); cursor: pointer; }
1281
+
1282
+ /* ---- SearchBox ---- */
1283
+ .search-input { position: relative; display: flex; align-items: center; }
1284
+ .search-input input {
1285
+ padding-left: 32px; padding-right: 32px;
1286
+ background: var(--surface) url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='14' height='14' viewBox='0 0 16 16'%3E%3Ccircle cx='7' cy='7' r='5' fill='none' stroke='%239aa1ad' stroke-width='1.6'/%3E%3Cpath d='m11 11 3.5 3.5' stroke='%239aa1ad' stroke-width='1.6' stroke-linecap='round'/%3E%3C/svg%3E") no-repeat 10px center;
1287
+ }
1288
+ .search-input input::-webkit-search-cancel-button { display: none; }
1289
+ .search-input .clear { position: absolute; right: 4px; display: grid; place-items: center; width: 26px; height: 26px; border: 0; border-radius: 4px; background: none; color: var(--muted); cursor: pointer; font-size: 16px; line-height: 1; }
1290
+ .search-input .clear:hover { background: var(--hover); color: var(--text); }
1291
+
1292
+ /* ---- DataTable (and RecordList) ---- */
1293
+ .table-wrap { overflow-x: auto; }
1294
+ table.data { width: 100%; border-collapse: separate; border-spacing: 0; font-size: 0.875rem; }
1295
+ table.data th { position: sticky; top: 0; z-index: 1; text-align: left; vertical-align: bottom; padding: 8px 12px; background: var(--surface-2); border-bottom: 1px solid var(--line); color: var(--muted); font-size: 0.75rem; font-weight: 600; letter-spacing: 0.02em; white-space: nowrap; }
1296
+ table.data td { padding: 9px 12px; border-bottom: 1px solid var(--line); vertical-align: middle; }
1297
+ table.data tbody tr:last-child td { border-bottom: 0; }
1298
+ table.data tbody tr:hover td { background: var(--surface-2); }
1104
1299
  table.data tr.clickable { cursor: pointer; }
1105
- table.data tr.clickable:hover td, table.data tr.clickable:focus-visible td { background: var(--accent); }
1106
1300
  table.data tr.clickable:focus-visible { outline: 2px solid var(--primary); outline-offset: -2px; }
1301
+ table.data tr.selected td, table.data tr.selected:hover td { background: var(--primary-soft); }
1302
+ table.data tr.selected td:first-child { box-shadow: inset 3px 0 0 var(--primary); }
1107
1303
  table.data th.num, table.data td.num { text-align: right; }
1304
+ table.data td.empty-cell { padding: 0; }
1305
+ table.data td.empty-cell:hover, table.data tbody tr:has(.empty-cell):hover td { background: none; }
1306
+ table.data .sort { display: inline-flex; align-items: center; gap: 4px; padding: 0; margin: 0; border: 0; background: none; color: inherit; font: inherit; letter-spacing: inherit; cursor: pointer; }
1307
+ table.data .sort:hover { color: var(--text); }
1308
+ table.data .sort .mark { width: 10px; color: var(--faint); }
1309
+ table.data th[aria-sort] .sort, table.data th[aria-sort] .sort .mark { color: var(--text); }
1310
+ table.data th.num .sort { flex-direction: row-reverse; }
1311
+ /* A phone scrolls a wide table sideways instead of breaking every cell into lines. */
1312
+ @media (max-width: 640px) { table.data td { white-space: nowrap; } }
1313
+ .data-foot { padding: 8px 12px; border-top: 1px solid var(--line); color: var(--muted); font-size: 0.8125rem; }
1314
+
1315
+ .skeleton { display: block; height: 0.8em; border-radius: 4px; background: linear-gradient(90deg, var(--surface-2) 25%, var(--hover) 50%, var(--surface-2) 75%); background-size: 200% 100%; animation: ez-shimmer 1.2s ease-in-out infinite; }
1316
+ @keyframes ez-shimmer { to { background-position: -200% 0; } }
1317
+
1318
+ /* ---- Pager ---- */
1319
+ .pager { display: flex; align-items: center; justify-content: flex-end; gap: 8px; padding: 10px 12px; }
1320
+ .pager .where { color: var(--muted); font-size: 0.8125rem; font-variant-numeric: tabular-nums; margin-right: auto; }
1321
+ .ez-pager { padding: 0 2px; }
1322
+
1323
+ /* ---- Empty ---- */
1324
+ .empty { display: flex; flex-direction: column; align-items: center; gap: 6px; padding: 40px 24px; text-align: center; color: var(--muted); }
1325
+ .empty .empty-title { color: var(--text); font-weight: 600; }
1326
+ .empty .empty-action { margin-top: 8px; }
1327
+
1328
+ /* ---- Badge ---- */
1329
+ .badge { display: inline-flex; align-items: center; gap: 5px; height: 22px; padding: 0 8px; border-radius: 999px; font-size: 0.75rem; font-weight: 500; line-height: 1; white-space: nowrap; background: var(--surface-2); color: var(--muted); border: 1px solid var(--line); }
1330
+ .badge::before { content: ""; width: 6px; height: 6px; border-radius: 50%; background: currentColor; opacity: 0.8; }
1331
+ .badge.ok { background: var(--ok-bg); color: var(--ok); border-color: transparent; }
1332
+ .badge.info { background: var(--info-bg); color: var(--info); border-color: transparent; }
1333
+ .badge.warn { background: var(--warn-bg); color: var(--warn); border-color: transparent; }
1334
+ .badge.danger { background: var(--danger-bg); color: var(--danger); border-color: transparent; }
1335
+ .badge.dark { background: var(--dark); color: #fff; border-color: transparent; }
1336
+
1337
+ /* ---- Stat ---- */
1338
+ .stat { display: flex; flex-direction: column; gap: 4px; padding: 14px 16px; background: var(--surface); border: 1px solid var(--line); border-radius: var(--radius-lg); box-shadow: var(--shadow); min-width: 0; }
1339
+ .stat .label { color: var(--muted); font-size: 0.8125rem; font-weight: 500; }
1340
+ .stat .value { font-size: 1.625rem; line-height: 1.2; font-weight: 650; letter-spacing: -0.02em; font-variant-numeric: tabular-nums; }
1341
+ .stat .hint { color: var(--muted); font-size: 0.8125rem; }
1342
+ .stat.ok .value { color: var(--ok); }
1343
+ .stat.info .value { color: var(--info); }
1344
+ .stat.warn .value { color: var(--warn); }
1345
+ .stat.danger .value { color: var(--danger); }
1108
1346
 
1109
- .badge { display: inline-block; padding: 2px 8px; border-radius: 999px; font-size: 0.75rem; font-weight: 600; background: #eceeea; color: #374151; white-space: nowrap; }
1110
- .badge.ok { background: var(--ok-bg); color: var(--ok); }
1111
- .badge.info { background: var(--info-bg); color: var(--info); }
1112
- .badge.warn { background: var(--warn-bg); color: var(--warn); }
1113
- .badge.danger { background: var(--danger-bg); color: var(--danger); }
1114
- .badge.dark { background: var(--dark); color: #fff; }
1115
-
1116
- /* inline-flex centres the label in a <Link className="btn"> too (a link has no button's own centring), without an underline. */
1117
- .btn { display: inline-flex; align-items: center; justify-content: center; text-decoration: none; min-height: 2.4rem; padding: 0 1rem; border-radius: 8px; border: 1px solid var(--line-strong); font-weight: 500; cursor: pointer; background: var(--surface); color: var(--text); }
1118
- .btn:hover { background: #f5f6f3; }
1119
- .btn.primary { background: var(--primary); border-color: var(--primary); color: #fff; }
1120
- .btn.primary:hover { background: var(--primary-hover); }
1121
- .btn.danger { background: var(--danger); border-color: var(--danger); color: #fff; }
1122
- .btn.danger:hover { background: var(--danger-hover); }
1123
- .btn.sm { min-height: 1.9rem; padding: 0 0.7rem; font-size: 0.85rem; }
1124
- .btn:disabled { opacity: 0.5; cursor: not-allowed; }
1125
-
1126
- .field { display: flex; flex-direction: column; gap: 4px; min-width: 120px; }
1127
- .field > span { font-size: 0.8rem; color: var(--muted); font-weight: 500; }
1128
- .field input, .field select, .field textarea { min-height: 2.4rem; padding: 0 10px; border: 1px solid var(--line-strong); border-radius: 8px; background: var(--surface); }
1129
- .field textarea { padding: 8px 10px; }
1130
- .field input:focus, .field select:focus, .field textarea:focus { outline: 2px solid var(--primary); outline-offset: 1px; border-color: var(--primary); }
1131
-
1132
- .empty { padding: 28px; text-align: center; color: var(--muted); }
1133
- .pager { display: flex; align-items: center; justify-content: flex-end; gap: 10px; padding: 10px 14px; }
1134
- .search-input { display: flex; gap: 6px; align-items: center; }
1135
- .search-input input { flex: 1; }
1136
- .notice { padding: 10px 14px; border-radius: 8px; background: var(--info-bg); color: var(--info); }
1137
- .notice.danger { background: var(--danger-bg); color: var(--danger); }
1138
- .notice.ok { background: var(--ok-bg); color: var(--ok); }
1139
-
1140
- .bar { display: flex; height: 10px; border-radius: 999px; overflow: hidden; background: #eceeea; }
1141
- .bar > span { display: block; height: 100%; }
1142
- .timeline { list-style: none; margin: 0; padding: 0; }
1143
- .timeline li { display: grid; grid-template-columns: 170px 90px 1fr; gap: 10px; padding: 8px 0; border-bottom: 1px solid var(--line); font-size: 0.9rem; }
1144
- .timeline li:last-child { border-bottom: 0; }
1347
+ /* ---- Notice ---- */
1348
+ .notice { display: flex; align-items: flex-start; gap: 10px; padding: 10px 12px; border-radius: var(--radius); border: 1px solid transparent; background: var(--info-bg); color: var(--text); border-left: 3px solid var(--info); }
1349
+ .notice .notice-body { flex: 1; min-width: 0; display: flex; flex-direction: column; gap: 2px; overflow-wrap: anywhere; }
1350
+ .notice .notice-title { font-weight: 600; }
1351
+ .notice .dismiss { flex-shrink: 0; display: grid; place-items: center; width: 24px; height: 24px; margin: -2px -4px -2px 0; border: 0; border-radius: 4px; background: none; color: var(--muted); cursor: pointer; font-size: 16px; line-height: 1; }
1352
+ .notice .dismiss:hover { background: rgb(0 0 0 / 0.06); color: var(--text); }
1353
+ .notice.ok { background: var(--ok-bg); border-left-color: var(--ok); }
1354
+ .notice.warn { background: var(--warn-bg); border-left-color: var(--warn); }
1355
+ .notice.danger { background: var(--danger-bg); border-left-color: var(--danger); }
1356
+ .notice.floating { position: fixed; left: 50%; bottom: 24px; z-index: 900; width: max-content; max-width: calc(100vw - 32px); transform: translateX(-50%); box-shadow: var(--shadow-lg); animation: ez-rise 0.14s ease-out; }
1357
+ @media (max-width: 640px) { .notice.floating { left: 16px; right: 16px; bottom: 16px; width: auto; transform: none; } }
1358
+
1359
+ /* ---- Tabs ---- */
1360
+ .tabs { display: flex; gap: 4px; border-bottom: 1px solid var(--line); overflow-x: auto; scrollbar-width: none; }
1361
+ .tabs .tab { position: relative; display: inline-flex; align-items: center; gap: 6px; min-height: 38px; padding: 0 12px; margin-bottom: -1px; border: 0; border-bottom: 2px solid transparent; background: none; color: var(--muted); font-weight: 500; text-decoration: none; white-space: nowrap; cursor: pointer; }
1362
+ .tabs .tab:hover { color: var(--text); }
1363
+ .tabs .tab[aria-current] { color: var(--text); border-bottom-color: var(--primary); }
1364
+ .tabs .count { min-width: 20px; padding: 0 6px; border-radius: 999px; background: var(--surface-2); color: var(--muted); font-size: 0.75rem; line-height: 18px; text-align: center; font-variant-numeric: tabular-nums; }
1365
+ .tabs .tab[aria-current] .count { background: var(--primary-soft); color: var(--primary); }
1366
+
1367
+ /* ---- FilterChips ---- */
1368
+ .chips { display: flex; flex-wrap: wrap; gap: 6px; align-items: center; }
1369
+ .chips .chips-label { color: var(--muted); font-size: 0.8125rem; margin-right: 2px; }
1370
+ .chip { display: inline-flex; align-items: center; gap: 6px; height: 28px; padding: 0 10px; border: 1px solid var(--line-strong); border-radius: 999px; background: var(--surface); color: var(--text); font-size: 0.8125rem; font-weight: 500; cursor: pointer; }
1371
+ .chip:hover { background: var(--hover); }
1372
+ .chip[aria-pressed="true"] { background: var(--primary-soft); border-color: var(--primary); color: var(--primary); }
1373
+ .chip .count { color: var(--muted); font-variant-numeric: tabular-nums; }
1374
+ .chip[aria-pressed="true"] .count { color: inherit; }
1375
+ @media (pointer: coarse) { .chip { height: 36px; padding: 0 14px; } }
1376
+
1377
+ /* ---- DetailList ---- */
1378
+ .details { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, var(--detail-min, 200px)), 1fr)); gap: 16px 24px; margin: 0; }
1379
+ .details > div { display: flex; flex-direction: column; gap: 2px; min-width: 0; }
1380
+ .details > div.wide { grid-column: 1 / -1; }
1381
+ .details dt { color: var(--muted); font-size: 0.8125rem; }
1382
+ .details dd { margin: 0; overflow-wrap: anywhere; }
1383
+ .details.one { grid-template-columns: minmax(0, 1fr); }
1384
+ .details.one > div { display: grid; grid-template-columns: minmax(120px, 30%) minmax(0, 1fr); gap: 12px; padding: 8px 0; border-bottom: 1px solid var(--line); }
1385
+ .details.one > div:last-child { border-bottom: 0; }
1386
+
1387
+ /* ---- Dialog ---- */
1388
+ .dialog-backdrop { position: fixed; inset: 0; z-index: 1000; display: flex; align-items: flex-start; justify-content: center; padding: 10vh 16px 16px; background: rgb(15 18 25 / 0.45); overflow-y: auto; animation: ez-fade 0.12s ease-out; }
1389
+ .dialog { display: flex; flex-direction: column; width: 100%; max-width: 32rem; max-height: calc(90vh - 16px); background: var(--surface); border-radius: var(--radius-lg); box-shadow: var(--shadow-lg); animation: ez-rise 0.14s ease-out; }
1390
+ .dialog.sm { max-width: 26rem; }
1391
+ .dialog.lg { max-width: 48rem; }
1392
+ .dialog .dialog-head { display: flex; align-items: flex-start; gap: 12px; padding: 16px 20px 12px; }
1393
+ .dialog .dialog-head .dialog-title { flex: 1; display: flex; flex-direction: column; gap: 4px; min-width: 0; }
1394
+ .dialog .dialog-head p { color: var(--muted); }
1395
+ .dialog .dialog-body { padding: 4px 20px 16px; overflow-y: auto; display: flex; flex-direction: column; gap: 14px; }
1396
+ .dialog .dialog-foot { display: flex; flex-wrap: wrap; justify-content: flex-end; gap: 8px; padding: 12px 20px; border-top: 1px solid var(--line); background: var(--surface-2); border-radius: 0 0 var(--radius-lg) var(--radius-lg); }
1397
+ @media (max-width: 640px) {
1398
+ .dialog-backdrop { align-items: flex-end; padding: 0; }
1399
+ .dialog, .dialog.sm, .dialog.lg { max-width: none; max-height: 92vh; border-radius: var(--radius-lg) var(--radius-lg) 0 0; }
1400
+ .dialog .dialog-foot { border-radius: 0; }
1401
+ .dialog .dialog-foot .btn { flex: 1; }
1402
+ }
1403
+ @keyframes ez-fade { from { opacity: 0; } }
1404
+ @keyframes ez-rise { from { opacity: 0; transform: translateY(8px); } }
1405
+
1406
+ @media (prefers-reduced-motion: reduce) {
1407
+ *, *::before, *::after { animation-duration: 0.01ms !important; animation-iteration-count: 1 !important; transition-duration: 0.01ms !important; }
1408
+ .spinner { animation: ez-spin 1.4s linear infinite !important; }
1409
+ }
1410
+
1411
+ /* ---- print: the page, without the frame and its controls ---- */
1412
+ @media print {
1413
+ body { background: #fff; font-size: 12px; }
1414
+ .topbar { position: static; }
1415
+ .topbar nav { display: none; }
1416
+ .pager, .btn, .tabs, .notice.floating, .chips, .search-input, .dialog-backdrop { display: none !important; }
1417
+ .main { padding: 0; max-width: none; }
1418
+ .panel, .stat { box-shadow: none; break-inside: avoid; }
1419
+ table.data th { position: static; }
1420
+ }
1145
1421
  `,
1146
- "components/Badge.tsx": `/** A pill for a short value. \`tone\` colours it; a workflow state draws with StateBadge instead. */
1422
+ "components/Badge.tsx": `/** A pill for a short value such as a status. \`tone\` colours it; a workflow state draws with StateBadge instead. */
1147
1423
  export default function Badge({
1148
1424
  value,
1149
1425
  tone,
@@ -1151,90 +1427,497 @@ export default function Badge({
1151
1427
  value: string | null | undefined;
1152
1428
  tone?: "ok" | "info" | "warn" | "danger" | "dark" | null;
1153
1429
  }) {
1154
- return <span className={\`badge \${tone ?? ""}\`}>{value ?? "—"}</span>;
1430
+ return <span className={tone ? \`badge \${tone}\` : "badge"}>{value ?? "—"}</span>;
1155
1431
  }
1156
1432
  `,
1157
- "components/StateBadge.tsx": `import { useWorkflow, type WritableTable } from "@ezship/react";
1158
- import Badge from "./Badge";
1433
+ "components/Button.tsx": `import { useTransition, type ReactNode } from "react";
1434
+ import { Link, run, useFormStatus } from "@ezship/react";
1159
1435
 
1160
- /** A row's workflow state, with the label and tone its global/workflows/<table>.ts gives the state. */
1161
- export default function StateBadge({
1162
- table,
1163
- value,
1436
+ /**
1437
+ * A button. \`action\` may be async: the button shows a spinner and ignores clicks until it settles, and a
1438
+ * failure shows the standard notice. \`confirm\` asks first. \`to\` draws a link that looks like a button.
1439
+ * A \`type="submit"\` button inside a <form action> shows the form's pending state.
1440
+ */
1441
+ export default function Button({
1442
+ children,
1443
+ variant = "secondary",
1444
+ size,
1445
+ action,
1446
+ confirm: question,
1447
+ to,
1448
+ type = "button",
1449
+ disabled,
1450
+ label,
1451
+ title,
1164
1452
  }: {
1165
- table: WritableTable;
1166
- value: string | null | undefined;
1453
+ children: ReactNode;
1454
+ variant?: "primary" | "secondary" | "danger" | "ghost";
1455
+ size?: "sm";
1456
+ /** What a click does; a returned promise keeps the button busy until it settles. */
1457
+ action?: () => unknown;
1458
+ /** A question the person confirms before \`action\` runs, such as "Delete this order?". */
1459
+ confirm?: string;
1460
+ /** A route of this Site: the button is a link. */
1461
+ to?: string;
1462
+ type?: "button" | "submit";
1463
+ disabled?: boolean;
1464
+ /** The accessible name, for a button whose children are only a symbol. */
1465
+ label?: string;
1466
+ title?: string;
1167
1467
  }) {
1168
- const flow = useWorkflow(table);
1169
- const state = value ? flow?.states[value] : undefined;
1170
- return <Badge value={state?.label ?? value} tone={state?.tone} />;
1468
+ const [running, start] = useTransition();
1469
+ const form = useFormStatus();
1470
+ const busy = running || (type === "submit" && form.pending);
1471
+ const className = ["btn", variant === "secondary" ? "" : variant, size ?? ""].join(" ").trim();
1472
+ if (to)
1473
+ return (
1474
+ <Link
1475
+ to={to}
1476
+ className={className}
1477
+ aria-label={label}
1478
+ title={title}
1479
+ aria-disabled={disabled || undefined}
1480
+ tabIndex={disabled ? -1 : undefined}
1481
+ >
1482
+ {children}
1483
+ </Link>
1484
+ );
1485
+ return (
1486
+ <button
1487
+ type={type}
1488
+ className={className}
1489
+ disabled={disabled || busy}
1490
+ aria-busy={busy || undefined}
1491
+ aria-label={label}
1492
+ title={title}
1493
+ onClick={
1494
+ action
1495
+ ? () => {
1496
+ if (question && !confirm(question)) return;
1497
+ start(async () => {
1498
+ await run(async () => action());
1499
+ });
1500
+ }
1501
+ : undefined
1502
+ }
1503
+ >
1504
+ {busy ? <span className="spinner" aria-hidden="true" /> : null}
1505
+ <span className="label">{children}</span>
1506
+ </button>
1507
+ );
1171
1508
  }
1172
1509
  `,
1173
- "components/Stat.tsx": `/** A KPI tile: a label, a large value and an optional hint line. */
1174
- export default function Stat({
1510
+ "components/ConfirmDialog.tsx": `import { startTransition, useActionState, type ReactNode } from "react";
1511
+ import { attempt } from "@ezship/react";
1512
+ import Dialog from "./Dialog";
1513
+ import Notice from "./Notice";
1514
+
1515
+ /**
1516
+ * Asks before a consequential step. \`onConfirm\` may be async: the dialog stays open and busy until it
1517
+ * settles, shows what it threw in place, and closes only when \`onConfirm\` closes it. For a plain yes or
1518
+ * no, Button's \`confirm\` asks with the browser's own dialog.
1519
+ */
1520
+ export default function ConfirmDialog({
1521
+ title,
1522
+ children,
1523
+ confirmLabel = "Confirm",
1524
+ tone = "primary",
1525
+ onConfirm,
1526
+ onCancel,
1527
+ }: {
1528
+ title: string;
1529
+ children?: ReactNode;
1530
+ confirmLabel?: string;
1531
+ tone?: "primary" | "danger";
1532
+ onConfirm: () => unknown;
1533
+ onCancel: () => void;
1534
+ }) {
1535
+ const [error, confirmIt, pending] = useActionState(
1536
+ attempt(async () => {
1537
+ await onConfirm();
1538
+ }),
1539
+ null,
1540
+ );
1541
+ return (
1542
+ <Dialog
1543
+ title={title}
1544
+ size="sm"
1545
+ onClose={pending ? () => undefined : onCancel}
1546
+ footer={
1547
+ <>
1548
+ <button type="button" className="btn" disabled={pending} onClick={onCancel}>
1549
+ Cancel
1550
+ </button>
1551
+ <button
1552
+ type="button"
1553
+ className={\`btn \${tone}\`}
1554
+ disabled={pending}
1555
+ aria-busy={pending || undefined}
1556
+ onClick={() => startTransition(confirmIt)}
1557
+ >
1558
+ {pending ? <span className="spinner" aria-hidden="true" /> : null}
1559
+ <span className="label">{confirmLabel}</span>
1560
+ </button>
1561
+ </>
1562
+ }
1563
+ >
1564
+ {children ? <div>{children}</div> : null}
1565
+ {error ? <Notice tone="danger">{error}</Notice> : null}
1566
+ </Dialog>
1567
+ );
1568
+ }
1569
+ `,
1570
+ "components/DataTable.tsx": `import type { ReactNode } from "react";
1571
+ import Empty from "./Empty";
1572
+
1573
+ type Sort = { key: string; desc?: boolean };
1574
+
1575
+ /**
1576
+ * A table of rows keyed by id: a column per { label, cell }. A column with \`sort\` has a header button that
1577
+ * calls \`onSort\`; sort in the query (order: [desc ? \`-\${key}\` : key]) and pass the current \`sort\` back.
1578
+ * \`onRow\` makes rows clickable (also with Tab and Enter), \`selected\` highlights a row, \`loading\` with no
1579
+ * rows shows placeholders, and \`footer\` is a line under the rows ("Showing the first 500").
1580
+ */
1581
+ export default function DataTable<R extends { id: string }>({
1582
+ rows,
1583
+ columns,
1584
+ onRow,
1585
+ selected,
1586
+ sort,
1587
+ onSort,
1588
+ loading,
1589
+ empty = "Nothing here yet.",
1590
+ footer,
1175
1591
  label,
1176
- value,
1177
- hint,
1178
- tone,
1179
1592
  }: {
1180
- label: string;
1181
- value: string | number;
1182
- hint?: string;
1183
- tone?: "ok" | "warn" | "danger";
1593
+ rows: readonly R[];
1594
+ columns: readonly {
1595
+ label: string;
1596
+ cell: (row: R) => ReactNode;
1597
+ align?: "left" | "right";
1598
+ /** The key \`onSort\` receives, usually the column's name. */
1599
+ sort?: string;
1600
+ /** A fixed width such as "8rem"; the other columns share the rest. */
1601
+ width?: string;
1602
+ }[];
1603
+ onRow?: (row: R) => void;
1604
+ selected?: string | null;
1605
+ sort?: Sort | null;
1606
+ onSort?: (sort: Sort) => void;
1607
+ loading?: boolean;
1608
+ empty?: ReactNode;
1609
+ footer?: ReactNode;
1610
+ /** What the table lists, for screen readers. */
1611
+ label?: string;
1184
1612
  }) {
1613
+ const align = (c: { align?: "left" | "right" }) => (c.align === "right" ? "num" : undefined);
1185
1614
  return (
1186
- <div className={\`stat \${tone ?? ""}\`}>
1187
- <div className="label">{label}</div>
1188
- <div className="value">{value}</div>
1189
- {hint ? <div className="hint">{hint}</div> : null}
1615
+ <div className="table-wrap">
1616
+ <table className="data" aria-label={label} aria-busy={loading || undefined}>
1617
+ <thead>
1618
+ <tr>
1619
+ {columns.map((c) => {
1620
+ const on = c.sort !== undefined && sort?.key === c.sort;
1621
+ return (
1622
+ <th
1623
+ key={c.label}
1624
+ scope="col"
1625
+ className={align(c)}
1626
+ style={c.width ? { width: c.width } : undefined}
1627
+ aria-sort={on ? (sort?.desc ? "descending" : "ascending") : undefined}
1628
+ >
1629
+ {c.sort !== undefined && onSort ? (
1630
+ <button
1631
+ type="button"
1632
+ className="sort"
1633
+ onClick={() => onSort({ key: c.sort ?? c.label, desc: on && !sort?.desc })}
1634
+ >
1635
+ {c.label}
1636
+ <span className="mark" aria-hidden="true">
1637
+ {on ? (sort?.desc ? "↓" : "↑") : "↕"}
1638
+ </span>
1639
+ </button>
1640
+ ) : (
1641
+ c.label
1642
+ )}
1643
+ </th>
1644
+ );
1645
+ })}
1646
+ </tr>
1647
+ </thead>
1648
+ <tbody>
1649
+ {rows.length === 0 && loading
1650
+ ? ["a", "b", "c"].map((k) => (
1651
+ <tr key={k}>
1652
+ {columns.map((c) => (
1653
+ <td key={c.label}>
1654
+ <span className="skeleton" />
1655
+ </td>
1656
+ ))}
1657
+ </tr>
1658
+ ))
1659
+ : null}
1660
+ {rows.length === 0 && !loading ? (
1661
+ <tr>
1662
+ <td className="empty-cell" colSpan={columns.length}>
1663
+ {typeof empty === "string" ? <Empty text={empty} /> : empty}
1664
+ </td>
1665
+ </tr>
1666
+ ) : null}
1667
+ {rows.map((row) => (
1668
+ <tr
1669
+ key={row.id}
1670
+ className={
1671
+ [onRow ? "clickable" : "", row.id === selected ? "selected" : ""]
1672
+ .join(" ")
1673
+ .trim() || undefined
1674
+ }
1675
+ aria-selected={selected === undefined ? undefined : row.id === selected}
1676
+ onClick={onRow ? () => onRow(row) : undefined}
1677
+ tabIndex={onRow ? 0 : undefined}
1678
+ onKeyDown={
1679
+ onRow
1680
+ ? (e) => {
1681
+ // Only the row itself: Enter on a link or button inside it does that control's job.
1682
+ if (e.target !== e.currentTarget || (e.key !== "Enter" && e.key !== " "))
1683
+ return;
1684
+ e.preventDefault();
1685
+ onRow(row);
1686
+ }
1687
+ : undefined
1688
+ }
1689
+ >
1690
+ {columns.map((c) => (
1691
+ <td key={c.label} className={align(c)}>
1692
+ {c.cell(row)}
1693
+ </td>
1694
+ ))}
1695
+ </tr>
1696
+ ))}
1697
+ </tbody>
1698
+ </table>
1699
+ {footer ? <div className="data-foot">{footer}</div> : null}
1190
1700
  </div>
1191
1701
  );
1192
1702
  }
1193
1703
  `,
1194
- "components/Panel.tsx": `import type { ReactNode } from "react";
1704
+ "components/DetailList.tsx": `import type { ReactNode } from "react";
1195
1705
 
1196
- /** A titled card. \`flush\` removes the body padding so a table can sit edge to edge. */
1197
- export default function Panel({
1706
+ /**
1707
+ * A record's fields read-only, as label and value: in a grid of columns, or \`layout="rows"\` for one label
1708
+ * beside its value per line. An empty value shows a dash; \`wide\` lets a long value span the grid.
1709
+ */
1710
+ export default function DetailList({
1711
+ items,
1712
+ layout = "grid",
1713
+ }: {
1714
+ items: readonly { label: string; value: ReactNode; wide?: boolean }[];
1715
+ layout?: "grid" | "rows";
1716
+ }) {
1717
+ return (
1718
+ <dl className={layout === "rows" ? "details one" : "details"}>
1719
+ {items.map((item) => (
1720
+ <div key={item.label} className={item.wide ? "wide" : undefined}>
1721
+ <dt>{item.label}</dt>
1722
+ <dd>
1723
+ {item.value === null || item.value === undefined || item.value === "" ? (
1724
+ <span className="muted">—</span>
1725
+ ) : (
1726
+ item.value
1727
+ )}
1728
+ </dd>
1729
+ </div>
1730
+ ))}
1731
+ </dl>
1732
+ );
1733
+ }
1734
+ `,
1735
+ "components/Dialog.tsx": `import type { ReactNode } from "react";
1736
+
1737
+ /**
1738
+ * A modal dialog over the page, drawn while it is rendered: render it when open and close it in \`onClose\`,
1739
+ * which Escape, the close button and a click on the backdrop call. The close button takes focus, unless a
1740
+ * control inside has autoFocus. On a phone it is a sheet from the bottom. \`footer\` holds the buttons.
1741
+ */
1742
+ export default function Dialog({
1198
1743
  title,
1199
- actions,
1200
- flush,
1744
+ description,
1745
+ onClose,
1746
+ footer,
1747
+ size,
1201
1748
  children,
1202
1749
  }: {
1203
- title?: string;
1204
- actions?: ReactNode;
1205
- flush?: boolean;
1206
- children: ReactNode;
1750
+ title: string;
1751
+ description?: ReactNode;
1752
+ onClose: () => void;
1753
+ footer?: ReactNode;
1754
+ size?: "sm" | "lg";
1755
+ children?: ReactNode;
1207
1756
  }) {
1208
1757
  return (
1209
- <section className="panel">
1210
- {title || actions ? (
1211
- <div className="panel-head">
1212
- {title ? <h2>{title}</h2> : null}
1213
- <span className="spacer" />
1214
- {actions}
1758
+ <div
1759
+ className="dialog-backdrop"
1760
+ onMouseDown={(e) => {
1761
+ if (e.target === e.currentTarget) onClose();
1762
+ }}
1763
+ onKeyDown={(e) => {
1764
+ if (e.key !== "Escape") return;
1765
+ e.stopPropagation();
1766
+ onClose();
1767
+ }}
1768
+ >
1769
+ <div
1770
+ className={size ? \`dialog \${size}\` : "dialog"}
1771
+ role="dialog"
1772
+ aria-modal="true"
1773
+ aria-label={title}
1774
+ >
1775
+ <div className="dialog-head">
1776
+ <div className="dialog-title">
1777
+ <h2>{title}</h2>
1778
+ {description ? <p>{description}</p> : null}
1779
+ </div>
1780
+ <button
1781
+ type="button"
1782
+ className="btn ghost sm icon"
1783
+ aria-label="Close"
1784
+ autoFocus
1785
+ onClick={onClose}
1786
+ >
1787
+ ×
1788
+ </button>
1215
1789
  </div>
1216
- ) : null}
1217
- <div className={\`panel-body \${flush ? "flush" : ""}\`}>{children}</div>
1218
- </section>
1790
+ {children ? <div className="dialog-body">{children}</div> : null}
1791
+ {footer ? <div className="dialog-foot">{footer}</div> : null}
1792
+ </div>
1793
+ </div>
1219
1794
  );
1220
1795
  }
1221
1796
  `,
1222
- "components/Empty.tsx": `/** The empty state of a list. */
1223
- export default function Empty({ text }: { text: string }) {
1224
- return <div className="empty">{text}</div>;
1797
+ "components/Empty.tsx": `import type { ReactNode } from "react";
1798
+
1799
+ /** The empty state of a list or page: a line of text, with an optional title above and an action below. */
1800
+ export default function Empty({
1801
+ text,
1802
+ title,
1803
+ action,
1804
+ }: {
1805
+ text: string;
1806
+ title?: string;
1807
+ action?: ReactNode;
1808
+ }) {
1809
+ return (
1810
+ <div className="empty">
1811
+ {title ? <span className="empty-title">{title}</span> : null}
1812
+ <span>{text}</span>
1813
+ {action ? <div className="empty-action">{action}</div> : null}
1814
+ </div>
1815
+ );
1225
1816
  }
1226
1817
  `,
1227
1818
  "components/Field.tsx": `import type { ReactNode } from "react";
1228
1819
 
1229
- /** A labelled form control. */
1230
- export default function Field({ label, children }: { label: string; children: ReactNode }) {
1820
+ /**
1821
+ * A labelled form control: put one input, select, textarea or picker inside. \`hint\` explains it, \`error\`
1822
+ * replaces the hint in red and marks the control invalid, \`required\` adds a mark (the check is the form's).
1823
+ */
1824
+ export default function Field({
1825
+ label,
1826
+ hint,
1827
+ error,
1828
+ required,
1829
+ children,
1830
+ }: {
1831
+ label: string;
1832
+ hint?: ReactNode;
1833
+ error?: string | null;
1834
+ required?: boolean;
1835
+ children: ReactNode;
1836
+ }) {
1231
1837
  return (
1232
- <label className="field">
1233
- <span>{label}</span>
1838
+ <label className={error ? "field invalid" : "field"}>
1839
+ <span>
1840
+ {label}
1841
+ {required ? (
1842
+ <span className="req" aria-hidden="true">
1843
+ *
1844
+ </span>
1845
+ ) : null}
1846
+ </span>
1234
1847
  {children}
1848
+ {error ? (
1849
+ <span className="field-error" role="alert">
1850
+ {error}
1851
+ </span>
1852
+ ) : hint ? (
1853
+ <span className="field-hint">{hint}</span>
1854
+ ) : null}
1235
1855
  </label>
1236
1856
  );
1237
1857
  }
1858
+ `,
1859
+ "components/FilterChips.tsx": `/**
1860
+ * Toggle chips for filtering by a few values, such as statuses: \`value\` is the chosen ones, and none chosen
1861
+ * means all (the "All" chip). \`single\` allows one at a time. Filter in the query with { col: { in: value } }.
1862
+ */
1863
+ export default function FilterChips({
1864
+ options,
1865
+ value,
1866
+ onChange,
1867
+ label,
1868
+ all = "All",
1869
+ single,
1870
+ }: {
1871
+ options: readonly (string | { value: string; label?: string; count?: number | null })[];
1872
+ value: readonly string[];
1873
+ onChange: (value: string[]) => void;
1874
+ label?: string;
1875
+ /** The label of the chip that clears the choice; null hides it. */
1876
+ all?: string | null;
1877
+ single?: boolean;
1878
+ }) {
1879
+ return (
1880
+ <div className="chips" role="group" aria-label={label ?? "Filter"}>
1881
+ {label ? <span className="chips-label">{label}</span> : null}
1882
+ {all === null ? null : (
1883
+ <button
1884
+ type="button"
1885
+ className="chip"
1886
+ aria-pressed={value.length === 0}
1887
+ onClick={() => onChange([])}
1888
+ >
1889
+ {all}
1890
+ </button>
1891
+ )}
1892
+ {options.map((o) => {
1893
+ const option = typeof o === "string" ? { value: o } : o;
1894
+ const on = value.includes(option.value);
1895
+ return (
1896
+ <button
1897
+ key={option.value}
1898
+ type="button"
1899
+ className="chip"
1900
+ aria-pressed={on}
1901
+ onClick={() =>
1902
+ onChange(
1903
+ on
1904
+ ? value.filter((v) => v !== option.value)
1905
+ : single
1906
+ ? [option.value]
1907
+ : [...value, option.value],
1908
+ )
1909
+ }
1910
+ >
1911
+ {option.label ?? option.value}
1912
+ {option.count === undefined || option.count === null ? null : (
1913
+ <span className="count">{option.count}</span>
1914
+ )}
1915
+ </button>
1916
+ );
1917
+ })}
1918
+ </div>
1919
+ );
1920
+ }
1238
1921
  `,
1239
1922
  "components/Money.tsx": `import type { Cents } from "@ezship/react";
1240
1923
 
@@ -1249,103 +1932,112 @@ export default function Money({ cents }: { cents: Cents | null | undefined }) {
1249
1932
  );
1250
1933
  }
1251
1934
  `,
1252
- "components/When.tsx": `/** A timestamp rendered as a short local date and time. */
1253
- export default function When({ at }: { at: number | null | undefined }) {
1254
- if (!at) return <span className="muted">—</span>;
1255
- const d = new Date(at);
1256
- const pad = (n: number) => (n < 10 ? \`0\${n}\` : String(n));
1935
+ "components/Notice.tsx": `import type { ReactNode } from "react";
1936
+
1937
+ /**
1938
+ * A message in the page: info by default, or ok, warn or danger. A danger notice is announced at once.
1939
+ * \`onDismiss\` adds a close button. \`floating\` pins it to the bottom of the screen, for the outcome of an
1940
+ * action the person may have scrolled away from. For a failed one-click write, \`run\` (or Button's action)
1941
+ * shows the standard notice instead.
1942
+ */
1943
+ export default function Notice({
1944
+ tone = "info",
1945
+ title,
1946
+ children,
1947
+ onDismiss,
1948
+ floating,
1949
+ }: {
1950
+ tone?: "info" | "ok" | "warn" | "danger";
1951
+ title?: string;
1952
+ children?: ReactNode;
1953
+ onDismiss?: () => void;
1954
+ floating?: boolean;
1955
+ }) {
1257
1956
  return (
1258
- <span className="mono" title={d.toISOString()}>
1259
- {\`\${d.getFullYear()}-\${pad(d.getMonth() + 1)}-\${pad(d.getDate())} \${pad(d.getHours())}:\${pad(d.getMinutes())}\`}
1260
- </span>
1957
+ <div
1958
+ className={\`notice \${tone}\${floating ? " floating" : ""}\`}
1959
+ role={tone === "danger" ? "alert" : "status"}
1960
+ >
1961
+ <div className="notice-body">
1962
+ {title ? <span className="notice-title">{title}</span> : null}
1963
+ {children ? <span>{children}</span> : null}
1964
+ </div>
1965
+ {onDismiss ? (
1966
+ <button type="button" className="dismiss" aria-label="Dismiss" onClick={onDismiss}>
1967
+ ×
1968
+ </button>
1969
+ ) : null}
1970
+ </div>
1261
1971
  );
1262
1972
  }
1263
1973
  `,
1264
- "components/Yes.tsx": `/** A boolean as Yes or No, and a dash when it is unset. */
1265
- export default function Yes({ value }: { value: boolean | null | undefined }) {
1266
- if (value === null || value === undefined) return <span className="muted">—</span>;
1267
- return <span>{value ? "Yes" : "No"}</span>;
1268
- }
1269
- `,
1270
- "components/DataTable.tsx": `import type { ReactNode } from "react";
1271
- import Empty from "./Empty";
1974
+ "components/PageHeader.tsx": `import type { ReactNode } from "react";
1975
+ import { Link } from "@ezship/react";
1272
1976
 
1273
1977
  /**
1274
- * A table of rows keyed by id: a column per { label, cell }, an optional click per row, an empty text. A
1275
- * clickable row is also reachable with Tab and opens with Enter or Space.
1978
+ * The top of a page: an optional back link, the title, a description, badges or facts beside the title
1979
+ * (\`meta\`) and the page's buttons (\`actions\`) on the right.
1276
1980
  */
1277
- export default function DataTable<R extends { id: string }>({
1278
- rows,
1279
- columns,
1280
- onRow,
1281
- empty = "Nothing here yet.",
1981
+ export default function PageHeader({
1982
+ title,
1983
+ description,
1984
+ back,
1985
+ meta,
1986
+ actions,
1282
1987
  }: {
1283
- rows: readonly R[];
1284
- columns: readonly { label: string; cell: (row: R) => ReactNode; align?: "left" | "right" }[];
1285
- onRow?: (row: R) => void;
1286
- empty?: string;
1988
+ title: ReactNode;
1989
+ description?: ReactNode;
1990
+ back?: { to: string; label?: string };
1991
+ meta?: ReactNode;
1992
+ actions?: ReactNode;
1287
1993
  }) {
1288
- if (rows.length === 0) return <Empty text={empty} />;
1289
1994
  return (
1290
- <table className="data">
1291
- <thead>
1292
- <tr>
1293
- {columns.map((c) => (
1294
- <th key={c.label} className={c.align === "right" ? "num" : undefined}>
1295
- {c.label}
1296
- </th>
1297
- ))}
1298
- </tr>
1299
- </thead>
1300
- <tbody>
1301
- {rows.map((row) => (
1302
- <tr
1303
- key={row.id}
1304
- className={onRow ? "clickable" : undefined}
1305
- onClick={onRow ? () => onRow(row) : undefined}
1306
- tabIndex={onRow ? 0 : undefined}
1307
- onKeyDown={
1308
- onRow
1309
- ? (e) => {
1310
- // Only the row itself: Enter on a link or button inside it does that control's job.
1311
- if (e.target !== e.currentTarget || (e.key !== "Enter" && e.key !== " "))
1312
- return;
1313
- e.preventDefault();
1314
- onRow(row);
1315
- }
1316
- : undefined
1317
- }
1318
- >
1319
- {columns.map((c) => (
1320
- <td key={c.label} className={c.align === "right" ? "num" : undefined}>
1321
- {c.cell(row)}
1322
- </td>
1323
- ))}
1324
- </tr>
1325
- ))}
1326
- </tbody>
1327
- </table>
1995
+ <header className="page-head">
1996
+ <div className="page-title">
1997
+ {back ? (
1998
+ <Link className="back" to={back.to}>
1999
+ ← {back.label ?? "Back"}
2000
+ </Link>
2001
+ ) : null}
2002
+ <div className="row">
2003
+ <h1>{title}</h1>
2004
+ {meta ? <div className="meta">{meta}</div> : null}
2005
+ </div>
2006
+ {description ? <p>{description}</p> : null}
2007
+ </div>
2008
+ <span className="spacer" />
2009
+ {actions ? <div className="actions">{actions}</div> : null}
2010
+ </header>
1328
2011
  );
1329
2012
  }
1330
2013
  `,
1331
2014
  "components/Pager.tsx": `/**
1332
2015
  * Previous and next over a list read with limit and offset. Read one row more than the page shows
1333
- * (limit: size + 1) and pass more={rows.length > size}; show rows.slice(0, size).
2016
+ * (limit: size + 1), pass more={rows.length > size} and show rows.slice(0, size). With \`total\` (from
2017
+ * useLive.count) it says "21–40 of 134"; without, the page number.
1334
2018
  */
1335
2019
  export default function Pager({
1336
2020
  offset,
1337
2021
  size,
1338
2022
  more,
2023
+ total,
1339
2024
  onOffset,
1340
2025
  }: {
1341
2026
  offset: number;
1342
2027
  size: number;
1343
2028
  more: boolean;
2029
+ total?: number | null;
1344
2030
  onOffset: (offset: number) => void;
1345
2031
  }) {
1346
2032
  if (offset === 0 && !more) return null;
2033
+ const last = total === undefined || total === null ? null : Math.min(offset + size, total);
1347
2034
  return (
1348
- <div className="pager">
2035
+ <nav className="pager" aria-label="Pages">
2036
+ <span className="where">
2037
+ {last === null
2038
+ ? \`Page \${Math.floor(offset / size) + 1}\`
2039
+ : \`\${offset + 1}–\${last} of \${total}\`}
2040
+ </span>
1349
2041
  <button
1350
2042
  type="button"
1351
2043
  className="btn sm"
@@ -1354,7 +2046,6 @@ export default function Pager({
1354
2046
  >
1355
2047
  Previous
1356
2048
  </button>
1357
- <span className="muted small">Page {Math.floor(offset / size) + 1}</span>
1358
2049
  <button
1359
2050
  type="button"
1360
2051
  className="btn sm"
@@ -1363,34 +2054,93 @@ export default function Pager({
1363
2054
  >
1364
2055
  Next
1365
2056
  </button>
1366
- </div>
2057
+ </nav>
1367
2058
  );
1368
2059
  }
1369
2060
  `,
1370
- "components/SearchBox.tsx": `/** A labelled search input with a clear button. Filter with { col: { like: \`%\${q}%\` } } or in code. */
2061
+ "components/Panel.tsx": `import type { ReactNode } from "react";
2062
+
2063
+ /**
2064
+ * A titled card. \`flush\` removes the body padding so a DataTable sits edge to edge; \`footer\` is a strip
2065
+ * below the body for totals or secondary buttons.
2066
+ */
2067
+ export default function Panel({
2068
+ title,
2069
+ description,
2070
+ actions,
2071
+ footer,
2072
+ flush,
2073
+ children,
2074
+ }: {
2075
+ title?: ReactNode;
2076
+ description?: ReactNode;
2077
+ actions?: ReactNode;
2078
+ footer?: ReactNode;
2079
+ flush?: boolean;
2080
+ children: ReactNode;
2081
+ }) {
2082
+ return (
2083
+ <section className="panel">
2084
+ {title || actions ? (
2085
+ <div className="panel-head">
2086
+ <div className="panel-title">
2087
+ {title ? <h2>{title}</h2> : null}
2088
+ {description ? <p>{description}</p> : null}
2089
+ </div>
2090
+ {actions ? <div className="actions">{actions}</div> : null}
2091
+ </div>
2092
+ ) : null}
2093
+ <div className={flush ? "panel-body flush" : "panel-body"}>{children}</div>
2094
+ {footer ? <div className="panel-foot">{footer}</div> : null}
2095
+ </section>
2096
+ );
2097
+ }
2098
+ `,
2099
+ "components/SearchBox.tsx": `/**
2100
+ * A labelled search input with a clear button; Escape clears it too. Filter in the query with
2101
+ * { col: { like: \`%\${q}%\` } }, and debounce the value (useDebounced) when every keystroke would query.
2102
+ */
1371
2103
  export default function SearchBox({
1372
2104
  value,
1373
2105
  onChange,
1374
2106
  label = "Search",
1375
2107
  placeholder,
2108
+ hideLabel,
2109
+ autoFocus,
1376
2110
  }: {
1377
2111
  value: string;
1378
2112
  onChange: (value: string) => void;
1379
2113
  label?: string;
1380
2114
  placeholder?: string;
2115
+ /** Keep the label for screen readers only, as in a toolbar. */
2116
+ hideLabel?: boolean;
2117
+ autoFocus?: boolean;
1381
2118
  }) {
1382
2119
  return (
1383
2120
  <label className="field search">
1384
- <span>{label}</span>
2121
+ {hideLabel ? null : <span>{label}</span>}
1385
2122
  <span className="search-input">
1386
2123
  <input
1387
2124
  type="search"
1388
2125
  value={value}
1389
- placeholder={placeholder}
2126
+ placeholder={placeholder ?? (hideLabel ? \`\${label}…\` : undefined)}
2127
+ aria-label={hideLabel ? label : undefined}
2128
+ autoFocus={autoFocus}
1390
2129
  onChange={(e) => onChange(e.target.value)}
2130
+ onKeyDown={(e) => {
2131
+ if (e.key === "Escape" && value) {
2132
+ e.stopPropagation();
2133
+ onChange("");
2134
+ }
2135
+ }}
1391
2136
  />
1392
2137
  {value ? (
1393
- <button type="button" className="btn sm" aria-label="Clear" onClick={() => onChange("")}>
2138
+ <button
2139
+ type="button"
2140
+ className="clear"
2141
+ aria-label={\`Clear \${label.toLowerCase()}\`}
2142
+ onClick={() => onChange("")}
2143
+ >
1394
2144
  ×
1395
2145
  </button>
1396
2146
  ) : null}
@@ -1398,27 +2148,135 @@ export default function SearchBox({
1398
2148
  </label>
1399
2149
  );
1400
2150
  }
2151
+ `,
2152
+ "components/Stat.tsx": `/** A KPI tile: a label, a large value and an optional hint line; \`tone\` colours the value. */
2153
+ export default function Stat({
2154
+ label,
2155
+ value,
2156
+ hint,
2157
+ tone,
2158
+ }: {
2159
+ label: string;
2160
+ value: string | number | null | undefined;
2161
+ hint?: string;
2162
+ tone?: "ok" | "info" | "warn" | "danger";
2163
+ }) {
2164
+ return (
2165
+ <div className={tone ? \`stat \${tone}\` : "stat"}>
2166
+ <div className="label">{label}</div>
2167
+ <div className="value">{value === null || value === undefined ? "—" : value}</div>
2168
+ {hint ? <div className="hint">{hint}</div> : null}
2169
+ </div>
2170
+ );
2171
+ }
2172
+ `,
2173
+ "components/StateBadge.tsx": `import { useWorkflow, type WritableTable } from "@ezship/react";
2174
+ import Badge from "./Badge";
2175
+
2176
+ /** A row's workflow state, with the label and tone its global/workflows/<table>.ts gives the state. */
2177
+ export default function StateBadge({
2178
+ table,
2179
+ value,
2180
+ }: {
2181
+ table: WritableTable;
2182
+ value: string | null | undefined;
2183
+ }) {
2184
+ const flow = useWorkflow(table);
2185
+ const state = value ? flow?.states[value] : undefined;
2186
+ return <Badge value={state?.label ?? value} tone={state?.tone} />;
2187
+ }
2188
+ `,
2189
+ "components/Tabs.tsx": `import { Link } from "@ezship/react";
2190
+
2191
+ /**
2192
+ * A row of tabs. A tab with \`to\` is a link to that route and is current when the route is; the others are
2193
+ * buttons, current when their \`value\` is \`value\`, and call \`onChange\`. \`count\` draws a number beside it.
2194
+ */
2195
+ export default function Tabs({
2196
+ tabs,
2197
+ value,
2198
+ onChange,
2199
+ label = "Views",
2200
+ }: {
2201
+ tabs: readonly { value: string; label: string; count?: number | null; to?: string }[];
2202
+ value?: string | null;
2203
+ onChange?: (value: string) => void;
2204
+ /** What the tabs choose between, for screen readers. */
2205
+ label?: string;
2206
+ }) {
2207
+ return (
2208
+ <nav className="tabs" aria-label={label}>
2209
+ {tabs.map((t) => {
2210
+ const inner = (
2211
+ <>
2212
+ {t.label}
2213
+ {t.count === undefined || t.count === null ? null : (
2214
+ <span className="count">{t.count}</span>
2215
+ )}
2216
+ </>
2217
+ );
2218
+ return t.to ? (
2219
+ <Link key={t.value} to={t.to} className="tab">
2220
+ {inner}
2221
+ </Link>
2222
+ ) : (
2223
+ <button
2224
+ key={t.value}
2225
+ type="button"
2226
+ className="tab"
2227
+ aria-current={t.value === value ? "true" : undefined}
2228
+ onClick={() => onChange?.(t.value)}
2229
+ >
2230
+ {inner}
2231
+ </button>
2232
+ );
2233
+ })}
2234
+ </nav>
2235
+ );
2236
+ }
2237
+ `,
2238
+ "components/When.tsx": `/** A timestamp as a short local date and time (\`date\` for the date alone), with the exact time on hover. */
2239
+ export default function When({ at, date }: { at: number | null | undefined; date?: boolean }) {
2240
+ if (!at) return <span className="muted">—</span>;
2241
+ const d = new Date(at);
2242
+ const pad = (n: number) => (n < 10 ? \`0\${n}\` : String(n));
2243
+ const day = \`\${d.getFullYear()}-\${pad(d.getMonth() + 1)}-\${pad(d.getDate())}\`;
2244
+ return (
2245
+ <time className="nowrap" dateTime={d.toISOString()} title={d.toString()}>
2246
+ {date ? day : \`\${day} \${pad(d.getHours())}:\${pad(d.getMinutes())}\`}
2247
+ </time>
2248
+ );
2249
+ }
2250
+ `,
2251
+ "components/Yes.tsx": `/** A boolean as Yes or No, and a dash when it is unset. */
2252
+ export default function Yes({ value }: { value: boolean | null | undefined }) {
2253
+ if (value === null || value === undefined) return <span className="muted">—</span>;
2254
+ return <span>{value ? "Yes" : "No"}</span>;
2255
+ }
1401
2256
  `,
1402
2257
  [CONSTANTS_FILE]: `/** The Instance's name as the starter Shell's top bar shows it. */
1403
2258
  export const BRAND = "My company";
1404
2259
  `,
1405
2260
  [SHELL_FILE]: `import type { ReactNode } from "react";
1406
- import { NavSlot, useSites } from "@ezship/react";
2261
+ import { NavSlot, SiteMenu, useSites } from "@ezship/react";
1407
2262
  import { BRAND } from "./constants";
1408
2263
 
1409
- /** Every Site's frame: a top bar with the brand, the Site's name and its links (its <Nav> in App.tsx). */
2264
+ /** Every Site's frame: a top bar with the brand, the Site's name, its links (its <Nav> in App.tsx) and the menu. */
1410
2265
  export default function Shell({ children }: { children: ReactNode }) {
1411
2266
  const site = useSites().find((s) => s.current);
1412
2267
  return (
1413
2268
  <>
1414
2269
  <header className="topbar">
1415
- <span className="brand">{BRAND}</span>
1416
- {site ? <span className="app-name">{site.name}</span> : null}
1417
- <nav>
2270
+ <div className="brand">
2271
+ <span className="brand-name">{BRAND}</span>
2272
+ {site ? <span className="app-name">{site.name}</span> : null}
2273
+ </div>
2274
+ <nav aria-label="Pages">
1418
2275
  <NavSlot />
1419
2276
  </nav>
2277
+ <SiteMenu />
1420
2278
  </header>
1421
- <div className="main">{children}</div>
2279
+ <main className="main">{children}</main>
1422
2280
  </>
1423
2281
  );
1424
2282
  }
@@ -1746,6 +2604,8 @@ export function checkGlobalStructure(files) {
1746
2604
  if (SCHEDULES_FILE in files)
1747
2605
  for (const error of parseSchedules(files[SCHEDULES_FILE], files).errors)
1748
2606
  top(SCHEDULES_FILE, "schedules", error);
2607
+ if (PAGE_FILE in files)
2608
+ for (const error of parsePage(files[PAGE_FILE]).errors) top(PAGE_FILE, "page", error);
1749
2609
  for (const [path, source] of Object.entries(files)) {
1750
2610
  const bad = globalFileError(path);
1751
2611
  if (bad) {
@@ -1930,6 +2790,8 @@ export function checkStructure(files) {
1930
2790
  ? parseListeners(files[LISTENERS_FILE], files)
1931
2791
  : { errors: [], warnings: parseListeners("[]", files).warnings };
1932
2792
  for (const error of listeners.errors) top(LISTENERS_FILE, "listeners", error);
2793
+ if (PAGE_FILE in files)
2794
+ for (const error of parsePage(files[PAGE_FILE]).errors) top(PAGE_FILE, "page", error);
1933
2795
  for (const warning of listeners.warnings) {
1934
2796
  top(warning.split(" ")[0] ?? LISTENERS_FILE, "listener-unlisted", warning);
1935
2797
  const last = out[out.length - 1];
@@ -2129,6 +2991,7 @@ export const CHECK_RULES = Object.freeze(
2129
2991
  ["schema", "error", "a db/schema.sql problem", "follow `ez help db`"],
2130
2992
  ["schedules", "error", "a schedules.json problem", "follow `ez help jobs`"],
2131
2993
  ["listeners", "error", "a listeners.json problem (docs/adr/0092)", "follow `ez help jobs`"],
2994
+ ["page", "error", "a page.json problem (docs/adr/0148)", "follow `ez help files`"],
2132
2995
  [
2133
2996
  "listener-unlisted",
2134
2997
  "warning",
@@ -2531,6 +3394,34 @@ export const SUPPORT_BODY_MAX = 20_000;
2531
3394
  /** @type {typeof import("./commands.d.mts").SUPPORT_REQUESTS_PER_DAY} */
2532
3395
  export const SUPPORT_REQUESTS_PER_DAY = 10;
2533
3396
 
3397
+ // ---- Emails (docs/adr/0149) ---------------------------------------------------------------------------
3398
+
3399
+ /**
3400
+ * What `email.send` takes and how much the Host sends: Emails per invocation, the subject's and the body's
3401
+ * length, a button's label and link, and the Instance's day and a sender's minute (over them, `dropped`).
3402
+ * @type {typeof import("./commands.d.mts").EMAIL_LIMITS}
3403
+ */
3404
+ export const EMAIL_LIMITS = Object.freeze({
3405
+ perInvocation: 50,
3406
+ subject: 200,
3407
+ body: 256_000,
3408
+ buttonLabel: 80,
3409
+ buttonHref: 2000,
3410
+ perDay: 1000,
3411
+ perMinute: 30,
3412
+ attempts: 3,
3413
+ });
3414
+ /** @type {typeof import("./commands.d.mts").EMAIL_STATUSES} */
3415
+ export const EMAIL_STATUSES = Object.freeze([
3416
+ "queued",
3417
+ "sending",
3418
+ "sent",
3419
+ "logged",
3420
+ "failed",
3421
+ "uncertain",
3422
+ "dropped",
3423
+ ]);
3424
+
2534
3425
  // ---- Integrations (docs/adr/0092, 0094) -----------------------------------------------------------------
2535
3426
  //
2536
3427
  // An Instance's named external services, set by Admins, called by server code with a credential it never
@@ -2909,6 +3800,13 @@ export const ROUTES = Object.freeze({
2909
3800
  openSupportRequest: { method: "POST", path: `${INSTANCE}/support`, args: (input) => body(input) },
2910
3801
  listSupportRequests: { method: "GET", path: `${INSTANCE}/support` },
2911
3802
  supportRequest: { method: "GET", path: `${INSTANCE}/support/:id`, args: byId },
3803
+ // Emails server code sent (docs/adr/0149): every Builder reads them; a Limited Builder only their Sites'.
3804
+ listEmails: {
3805
+ method: "GET",
3806
+ path: `${INSTANCE}/emails`,
3807
+ args: (filter) => ({ query: { ...filter } }),
3808
+ },
3809
+ emailInfo: { method: "GET", path: `${INSTANCE}/emails/:id`, args: byId },
2912
3810
  // Integrations (docs/adr/0092): Admins set them; every Builder lists them and their calls.
2913
3811
  listIntegrations: { method: "GET", path: `${INSTANCE}/integrations` },
2914
3812
  setIntegration: {
@@ -3350,11 +4248,15 @@ const SITE_FILES = `${aligned([
3350
4248
  ],
3351
4249
  [CONSTANTS_FILE, 'plain values only: `export const STATUSES = ["open", "done"] as const`'],
3352
4250
  [STYLE_FILE, "this Site's styles, loaded after the global theme"],
4251
+ [
4252
+ PAGE_FILE,
4253
+ '{ "icon": "<svg xmlns=...>...</svg>" }: this Site\'s browser icon, over the global one',
4254
+ ],
3353
4255
  [`${DOCS_DIR}<name>.md`, "Markdown docs and notes for Builders: never built or served"],
3354
4256
  ])}
3355
4257
  Every folder is flat (no subfolders); function, listener and local file names are camelCase
3356
- (saveItem.ts). Everything but App.tsx and CONTEXT.md is optional. There is no HTML file, package.json,
3357
- config or other folder.`;
4258
+ (saveItem.ts). Everything but App.tsx and CONTEXT.md is optional. There is no HTML file, package.json
4259
+ or other folder.`;
3358
4260
 
3359
4261
  /** The Global Workspace's shape, from globalFileError's constants. */
3360
4262
  const GLOBAL_FILES = `${aligned([
@@ -3377,7 +4279,7 @@ const GLOBAL_FILES = `${aligned([
3377
4279
  [`global/${STYLE_FILE}`, "the theme, loaded before every Site's own style.css"],
3378
4280
  [
3379
4281
  `global/${SHELL_FILE}`,
3380
- "the frame around every Site (top bar, <NavSlot />, provided values)",
4282
+ "the frame around every Site (top bar, <NavSlot />, <SiteMenu />, provided values)",
3381
4283
  "ez help frame",
3382
4284
  ],
3383
4285
  [
@@ -3402,9 +4304,16 @@ const GLOBAL_FILES = `${aligned([
3402
4304
  ],
3403
4305
  [`global/${DOCUMENTS_DIR}<Name>.tsx`, "PDF templates", "ez help documents"],
3404
4306
  [`global/${DOCS_DIR}<name>.md`, "Markdown docs and notes every Site's Builders share"],
4307
+ [
4308
+ `global/${PAGE_FILE}`,
4309
+ '{ "icon": "<svg xmlns=...>...</svg>" }: every Site\'s browser icon (default: a ship\'s wheel)',
4310
+ ],
3405
4311
  ])}
3406
- A new Instance starts with a theme, a Shell, and the components Badge, StateBadge, Stat, Panel, Empty, Field,
3407
- Money, When, Yes, DataTable, Pager and SearchBox: use them before writing your own (\`ez global ls\`).`;
4312
+ A new Instance starts with a theme, a Shell, and the components Button (an async action shows busy, a failure
4313
+ the standard notice; confirm asks first), PageHeader, Panel, Stat, Badge, StateBadge, Notice, Dialog,
4314
+ ConfirmDialog, Tabs, FilterChips, SearchBox, DataTable (sortable headers, selection, loading), Pager,
4315
+ DetailList, Field (hint, error), Empty, Money, When and Yes: use them before writing your own
4316
+ (\`ez global ls\`; each file's doc comment says how).`;
3408
4317
 
3409
4318
  /** `ez help` without a topic: the onboarding every task needs. */
3410
4319
  export const CONVENTIONS = `You build one app, a Site, of an ezship Instance through the \`ez\` command. This is the short guide every
@@ -3549,6 +4458,8 @@ How to work
3549
4458
  6. \`ez preview\` (or \`ez dev\`, which keeps it current) and give the user \`ez link --preview <name>\`;
3550
4459
  a successful preview is also a check. Its data is the live data.
3551
4460
  7. Keep CONTEXT.md and the docs current, \`ez pull\`, \`ez push -m "<what it is for>"\`, and \`ez deploy\` once the user agrees.
4461
+ Before you ask, \`ez status\`: its "global:" line names the Global changes pushed since the live app
4462
+ was built, which the deploy brings in too; name them to the user.
3552
4463
  Ask the user before \`ez deploy\` and before every App Database write: \`ez db sql\` INSERT, UPDATE or DELETE,
3553
4464
  \`ez db attach\`, \`ez db redact\` and \`ez function call\`. \`ez check\`, \`ez format\` and \`ez preview\` are free
3554
4465
  to run. When ezship itself fails (a command errors in a way no change to the code fixes, or the platform does
@@ -3734,8 +4645,8 @@ calls hooks at its top level and returns values, never markup:
3734
4645
  A hook is for React state and live data; logic that needs neither belongs in global/lib (ez help functions).
3735
4646
  The Shell and navigation: App.tsx renders the Site's links once in <Nav>{links}</Nav>; the global Shell draws
3736
4647
  them at <NavSlot />, and without a Shell they render in place. [advice] Never copy a top bar or brand into
3737
- App.tsx: that is the Shell's. The Framework always adds the account and Change Site menu; useSites() lists
3738
- the Sites the viewer may open, for a Shell.
4648
+ App.tsx: that is the Shell's. The Shell places the account and Change Site menu with <SiteMenu />; without
4649
+ one placed, the Framework draws it in a bar of its own. useSites() lists the Sites the viewer may open.
3739
4650
  The viewer: sign-in and membership are the platform's. useAuth() -> { user: { id, email, name } | null,
3740
4651
  membership: "active" | "blocked" | null, me (the viewer as a MEMBER column holds them), groups, loading };
3741
4652
  signIn() and signOut() are their own imports, not fields of useAuth().`;
@@ -3957,6 +4868,34 @@ With attachTo the FILE column is set when the PDF is ready (useLive shows it); w
3957
4868
  keeps the ids a column held before. Input is JSON up to 1 MB; at most 200 pages.
3958
4869
  Test a deployed one: \`ez document render Invoice '<json>'\`.`;
3959
4870
 
4871
+ const EMAIL_TOPIC = `Email: notifications, reports and reminders from server functions, jobs and Listeners.
4872
+ \`email\` and \`link\` are in their context:
4873
+ await email.send({
4874
+ to: "group(verifier)", // or user.me, a MEMBER column, a Member's address, or an array
4875
+ subject: \`Sample \${s.code} is ready to verify\`,
4876
+ body: \`**\${s.code}** from \${s.client} has all its analyses in.\`,
4877
+ button: { label: "Verify it", href: link("/samples/" + s.id) },
4878
+ });
4879
+ [runtime] \`send\` is a write in the invocation's transaction: a rollback sends nothing, and the Host delivers
4880
+ after the commit, from its own address with the Instance's name, in the Instance's look. Call Integrations
4881
+ before it. It reaches Members only: a group(<name>) access.sql declares (each Member holding it), a MEMBER value
4882
+ or an active Member's address; anyone else is dropped, never thrown, and the answer counts them:
4883
+ { emails: [ids], dropped }. A malformed message throws.
4884
+ The body is Markdown, never HTML: paragraphs, # headings, **bold**, *italic*, \`code\`, [links](https://...),
4885
+ - and 1. lists, pipe tables (good for reports) and fenced code. The subject is one line.
4886
+ link("/path") is the absolute URL of a page of this Site (of your Preview, from a Preview);
4887
+ link("<site>", "/path") of another Site. A job has no Site of its own, so it always names one.
4888
+ [runtime] Limits: ${EMAIL_LIMITS.perInvocation} Emails per invocation, a ${EMAIL_LIMITS.subject}-character subject, a ${EMAIL_LIMITS.body / 1000} KB body; ${EMAIL_LIMITS.perDay}
4889
+ a day per Instance and ${EMAIL_LIMITS.perMinute} a minute per Site function or job, over which an Email is dropped (quota). A digest in a
4890
+ job (one Email per person, a table of their items) stays under them.
4891
+ [runtime] Mail from a Preview goes only to you, the Builder who owns it, marked [Preview] and saying whom it
4892
+ would have reached: push to a Preview, \`ez function call <name> '<json>' --preview <name>\`, read your inbox.
4893
+ \`ez schedule run\` and deployed code mail for real.
4894
+ A refusal before the mail service accepted an Email is retried up to ${EMAIL_LIMITS.attempts} times; one whose answer was lost is
4895
+ \`uncertain\` and never sent again.
4896
+ See what was sent: \`ez email list [--site <id>] [--status dropped]\`, \`ez email show <id>\`.
4897
+ Members' preferences (mutes, digests) are the app's: keep them in a Table and choose \`to\` from it.`;
4898
+
3960
4899
  /**
3961
4900
  * `ez help recipes`: complete, minimal pieces. Each recipe is data so the Pipeline's tests build every one
3962
4901
  * of them against the starter Global Workspace (packages/build/src/recipes.test.ts).
@@ -4056,41 +4995,12 @@ and offers Delete only when onDeleted is given. required is the form's own rule:
4056
4995
  schema: null,
4057
4996
  global: {},
4058
4997
  files: {
4059
- "components/Modal.tsx": `import type { ReactNode } from "react";
4060
-
4061
- /** A dialog over the page: a title, its body and a footer of buttons. */
4062
- export default function Modal({
4063
- title,
4064
- onClose,
4065
- footer,
4066
- children,
4067
- }: {
4068
- title: string;
4069
- onClose: () => void;
4070
- footer: ReactNode;
4071
- children: ReactNode;
4072
- }) {
4073
- return (
4074
- <div className="modal-backdrop">
4075
- <div className="modal" role="dialog" aria-modal="true" aria-label={title}>
4076
- <div className="modal-head">
4077
- <h2>{title}</h2>
4078
- <button type="button" className="btn sm" onClick={onClose}>
4079
- Close
4080
- </button>
4081
- </div>
4082
- <div className="modal-body">{children}</div>
4083
- <div className="modal-foot">{footer}</div>
4084
- </div>
4085
- </div>
4086
- );
4087
- }
4088
- `,
4089
4998
  "components/CreditLimitDialog.tsx": `import { startTransition, useActionState, useState } from "react";
4090
4999
  import { attempt, db, fromCents, toCents } from "@ezship/react";
4091
5000
  import type { Customer } from "global/db/types";
5001
+ import Dialog from "global/Dialog";
4092
5002
  import Field from "global/Field";
4093
- import Modal from "./Modal";
5003
+ import Notice from "global/Notice";
4094
5004
 
4095
5005
  /** Changes one customer's credit limit: checks the amount, saves it, and shows a refusal in place. */
4096
5006
  export default function CreditLimitDialog({
@@ -4113,8 +5023,9 @@ export default function CreditLimitDialog({
4113
5023
  null,
4114
5024
  );
4115
5025
  return (
4116
- <Modal
4117
- title={\`Credit limit for \${customer.name ?? "this customer"}\`}
5026
+ <Dialog
5027
+ title="Credit limit"
5028
+ description={customer.name}
4118
5029
  onClose={onClose}
4119
5030
  footer={
4120
5031
  <>
@@ -4132,11 +5043,11 @@ export default function CreditLimitDialog({
4132
5043
  </>
4133
5044
  }
4134
5045
  >
4135
- {error ? <div className="notice danger">{error}</div> : null}
4136
- <Field label="Credit limit (USD)">
4137
- <input value={amount} inputMode="decimal" onChange={(e) => setAmount(e.target.value)} />
5046
+ {error ? <Notice tone="danger">{error}</Notice> : null}
5047
+ <Field label="Credit limit (USD)" hint="Orders over the limit go on hold.">
5048
+ <input value={amount} inputMode="decimal" autoFocus onChange={(e) => setAmount(e.target.value)} />
4138
5049
  </Field>
4139
- </Modal>
5050
+ </Dialog>
4140
5051
  );
4141
5052
  }
4142
5053
  `,
@@ -4145,6 +5056,8 @@ import { useLive } from "@ezship/react";
4145
5056
  import type { Customer } from "global/db/types";
4146
5057
  import DataTable from "global/DataTable";
4147
5058
  import Money from "global/Money";
5059
+ import PageHeader from "global/PageHeader";
5060
+ import Panel from "global/Panel";
4148
5061
  import CreditLimitDialog from "../components/CreditLimitDialog";
4149
5062
 
4150
5063
  /** Active customers and their credit limits; a row opens the dialog that changes one. */
@@ -4153,51 +5066,30 @@ export default function Credit() {
4153
5066
  const [editing, setEditing] = useState<Customer | null>(null);
4154
5067
  return (
4155
5068
  <>
4156
- <h1>Credit limits</h1>
4157
- <DataTable
4158
- rows={customers}
4159
- columns={[
4160
- { label: "Customer", cell: (c) => c.name },
4161
- { label: "Limit", cell: (c) => <Money cents={c.credit_limit} />, align: "right" },
4162
- ]}
4163
- onRow={setEditing}
4164
- empty="No active customers."
4165
- />
5069
+ <PageHeader title="Credit limits" description="Open a customer to change their limit." />
5070
+ <Panel flush>
5071
+ <DataTable
5072
+ rows={customers}
5073
+ columns={[
5074
+ { label: "Customer", cell: (c) => c.name },
5075
+ { label: "Limit", cell: (c) => <Money cents={c.credit_limit} />, align: "right" },
5076
+ ]}
5077
+ onRow={setEditing}
5078
+ selected={editing?.id ?? null}
5079
+ empty="No active customers."
5080
+ />
5081
+ </Panel>
4166
5082
  {editing ? <CreditLimitDialog customer={editing} onClose={() => setEditing(null)} /> : null}
4167
5083
  </>
4168
5084
  );
4169
5085
  }
4170
- `,
4171
- "style.css": `.modal-backdrop {
4172
- position: fixed;
4173
- inset: 0;
4174
- display: grid;
4175
- place-items: center;
4176
- background: rgb(0 0 0 / 0.35);
4177
- }
4178
- .modal {
4179
- width: min(28rem, calc(100vw - 2rem));
4180
- background: var(--surface, #fff);
4181
- border-radius: 8px;
4182
- padding: 1rem;
4183
- }
4184
- .modal-head,
4185
- .modal-foot {
4186
- display: flex;
4187
- justify-content: space-between;
4188
- align-items: center;
4189
- gap: 0.5rem;
4190
- }
4191
- .modal-foot {
4192
- justify-content: flex-end;
4193
- margin-top: 1rem;
4194
- }
4195
5086
  `,
4196
5087
  },
4197
- notes: `Uses the customers Table of record-list. The Framework has no Modal: components/Modal.tsx is the Site's own
4198
- (move it to global/components/ when other Sites want it). The action's state is the error: attempt() turns a
4199
- thrown validation message or a refused write into it, and the dialog closes only on success. Dispatch with
4200
- startTransition(save), never onClick={save}.`,
5088
+ notes: `Uses the customers Table of record-list. Dialog is the starter's (global/Dialog): rendered while open, closed
5089
+ by Escape, its close button or the backdrop, all of which call onClose. The action's state is the error:
5090
+ attempt() turns a thrown validation message or a refused write into it, and the dialog closes only on
5091
+ success. Dispatch with startTransition(save), never onClick={save}. For one click with no form, the starter
5092
+ Button's action does the same: busy while it runs, the standard notice if it fails.`,
4201
5093
  },
4202
5094
  {
4203
5095
  name: "integration-call",
@@ -4500,6 +5392,11 @@ export const HELP_TOPICS = Object.freeze([
4500
5392
  text: () => LOCAL_TOPIC,
4501
5393
  },
4502
5394
  { name: "documents", summary: "PDF templates and renders", text: () => DOCUMENTS_TOPIC },
5395
+ {
5396
+ name: "email",
5397
+ summary: "Email to Members from server functions, jobs and Listeners; link() to pages",
5398
+ text: () => EMAIL_TOPIC,
5399
+ },
4503
5400
  {
4504
5401
  name: "db",
4505
5402
  summary:
@@ -4586,6 +5483,14 @@ export const COMMANDS = [
4586
5483
  help: "render a Global Document to a permanent PDF from this Site's deployment or your Preview; waits for it",
4587
5484
  },
4588
5485
  { usage: "ez document renders", help: "this Site's recent Renders, newest first" },
5486
+ {
5487
+ usage: "ez email list [--site <id>] [--status <status>] [--since <YYYY-MM-DD>] [--limit <n>]",
5488
+ help: "the Emails the Instance's server code sent, newest first: status, sender, recipient, subject",
5489
+ },
5490
+ {
5491
+ usage: "ez email show <id> [--html]",
5492
+ help: "one Email: why it was dropped or failed, and what it said (the message as rendered with --html)",
5493
+ },
4589
5494
  {
4590
5495
  usage: "ez document status <id>",
4591
5496
  help: "one Render: queued, rendering, ready (with its file id) or failed (with why)",
@@ -4604,7 +5509,7 @@ export const COMMANDS = [
4604
5509
  },
4605
5510
  {
4606
5511
  usage: "ez status",
4607
- help: "the shared files' version, what you pulled, your unpushed changes, what deploy would do to the schema",
5512
+ help: "the shared files' version, what you pulled, your unpushed changes, what deploy would do to the schema and which Global changes it brings in",
4608
5513
  },
4609
5514
  {
4610
5515
  usage: "ez pull [--force] [--version <n>] [--all]",
@@ -4612,7 +5517,7 @@ export const COMMANDS = [
4612
5517
  },
4613
5518
  {
4614
5519
  usage: 'ez push [-m "<message>"] [--prune] [--force] [--dry-run] [--acknowledge-exposure]',
4615
- help: "replace the shared files with the working copy, deleting the pulled files you removed (--prune also deletes shared files this copy never pulled); -m says what the push is for, shown by ez versions; in <instance>/global, the Global Workspace's, after `ez global check` passes for it and every Site (--force skips that; admins only); a global push lists what takes effect now (defaults, access rules, session.ts, rules), --dry-run shows that and each changed rule's effect without pushing, --acknowledge-exposure accepts access rules that let Members read more",
5520
+ help: "replace the shared files with the working copy, deleting the pulled files you removed (--prune also deletes shared files this copy never pulled); -m says what the push is for, shown by ez versions; in <instance>/global, the Global Workspace's, after `ez global check` passes for it and every Site (--force skips that; admins only); a global push lists what takes effect now (defaults, access rules, session.ts, rules), --dry-run shows that and each changed rule's effect without pushing (a Site push refuses it), --acknowledge-exposure accepts access rules that let Members read more",
4616
5521
  },
4617
5522
  { usage: "ez deploy", help: "ship the shared files to the live app" },
4618
5523
  {
@@ -4917,6 +5822,15 @@ export function ago(at) {
4917
5822
  return `${Math.round(s / 86400)}d ago`;
4918
5823
  }
4919
5824
 
5825
+ /** @type {typeof import("./commands.d.mts").pinnedGlobalPath} */
5826
+ export const pinnedGlobalPath = (path) =>
5827
+ path !== SESSION_FILE &&
5828
+ path !== SCHEDULES_FILE &&
5829
+ jobName(path) === null &&
5830
+ path !== CONTEXT_FILE &&
5831
+ docName(path) === null &&
5832
+ path !== TYPES_FILE;
5833
+
4920
5834
  /**
4921
5835
  * A Global push's two kinds of change (docs/adr/0096): Live ones took effect for every deployed Site at once;
4922
5836
  * the rest reach each Site at its next Preview or Deploy.
@@ -4993,9 +5907,7 @@ function liveLines(result) {
4993
5907
  }`,
4994
5908
  );
4995
5909
  }
4996
- const pinned = result.written.filter(
4997
- (p) => p !== SESSION_FILE && p !== SCHEDULES_FILE && !jobName(p),
4998
- );
5910
+ const pinned = result.written.filter(pinnedGlobalPath);
4999
5911
  if (pinned.length)
5000
5912
  lines.push(`Takes effect at each Site's next Preview or Deploy: ${pinned.join(", ")}`);
5001
5913
  return lines;
@@ -5105,6 +6017,59 @@ async function schemaStatus(ws, files, instance, siteId) {
5105
6017
  return { lines, data: { ok: true, created, added, indexed, conflicts: plan.conflicts } };
5106
6018
  }
5107
6019
 
6020
+ /**
6021
+ * What the Site's next deploy brings in from the Global Workspace (docs/adr/0141): the pushed Global files that
6022
+ * changed since the Version its live app was built with, as the Host recorded that deploy. A deploy builds the
6023
+ * pushed Global, so unpushed Global changes are not among them.
6024
+ * @type {typeof import("./commands.d.mts").globalSinceDeploy}
6025
+ */
6026
+ export async function globalSinceDeploy(site, global) {
6027
+ const deployed = site.deployedGlobal;
6028
+ if (site.deployedAt === null || typeof deployed !== "number") return null;
6029
+ const newest = (await global.remoteStatus()).version.n;
6030
+ if (newest <= deployed)
6031
+ return { deployed, current: newest, paths: { added: [], changed: [], removed: [] } };
6032
+ const [before, after] = await Promise.all([
6033
+ deployed === 0
6034
+ ? { files: /** @type {Record<string, string>} */ ({}) }
6035
+ : global.fetchAll(deployed).catch(() => null),
6036
+ global.fetchAll(),
6037
+ ]);
6038
+ const current = after.version.n;
6039
+ if (!before) return { deployed, current, paths: null };
6040
+ const was = before.files;
6041
+ const now = after.files;
6042
+ /** @param {string[]} paths */
6043
+ const pinned = (paths) => paths.filter(pinnedGlobalPath).sort();
6044
+ return {
6045
+ deployed,
6046
+ current,
6047
+ paths: {
6048
+ added: pinned(Object.keys(now).filter((p) => !(p in was))),
6049
+ changed: pinned(Object.keys(now).filter((p) => p in was && was[p] !== now[p])),
6050
+ removed: pinned(Object.keys(was).filter((p) => !(p in now))),
6051
+ },
6052
+ };
6053
+ }
6054
+
6055
+ /**
6056
+ * `ez status`'s Global line: what a deploy brings in from the Global Workspace.
6057
+ * @param {import("./types.d.mts").GlobalSinceDeploy} g
6058
+ */
6059
+ function globalStatusLine(g) {
6060
+ const live = `the live app was built with Global v${g.deployed}`;
6061
+ if (!g.paths)
6062
+ return `global: deploy would bring in Global v${g.current} (${live}, no longer retained, so its changes cannot be listed)`;
6063
+ const { added, changed, removed } = g.paths;
6064
+ if (added.length + changed.length + removed.length === 0)
6065
+ return `global: up to date (${live}${g.current > g.deployed ? `; v${g.current} changed nothing a deploy brings in` : ""})`;
6066
+ const parts = [];
6067
+ if (added.length) parts.push(`added ${added.join(", ")}`);
6068
+ if (changed.length) parts.push(`changed ${changed.join(", ")}`);
6069
+ if (removed.length) parts.push(`removed ${removed.join(", ")}`);
6070
+ return `global: deploy would bring in Global v${g.current} (${live}): ${parts.join("; ")}`;
6071
+ }
6072
+
5108
6073
  /**
5109
6074
  * A short human label for a command, for the chat UI ("Read index.html"). Never shows the argv itself.
5110
6075
  * @type {typeof import("./commands.d.mts").describeCommand}
@@ -5216,6 +6181,8 @@ export function describeCommand(argv) {
5216
6181
  if (a === "create") return `Created API Key ${b ?? ""}`.trim();
5217
6182
  if (a === "revoke") return `Revoked API Key ${b ?? ""}`.trim();
5218
6183
  return "Listed the API Keys";
6184
+ case "email":
6185
+ return a === "show" ? `Read email ${b ?? ""}`.trim() : "Listed the emails server code sent";
5219
6186
  case "support":
5220
6187
  if (a === "open") return "Asked the Host's developers for help";
5221
6188
  return a === "show"
@@ -5610,6 +6577,14 @@ async function execute(ws, argv, stdin) {
5610
6577
  ? null
5611
6578
  : await schemaStatus(ws, (await ws.globalFiles?.()) ?? {}, remote.instance, remote.id);
5612
6579
  if (schema) lines.push(...schema.lines);
6580
+ // What the deploy also brings in from the Global Workspace (docs/adr/0141); never fails the status.
6581
+ const brings = global
6582
+ ? null
6583
+ : await (async () => {
6584
+ const g = await ws.globalWorkspace?.();
6585
+ return g ? globalSinceDeploy(remote, g) : null;
6586
+ })().catch(() => null);
6587
+ if (brings) lines.push(globalStatusLine(brings));
5613
6588
  return out(lines.join("\n"), {
5614
6589
  site: { instance: remote.instance, id: remote.id, name: remote.name },
5615
6590
  version: remote.version,
@@ -5619,6 +6594,7 @@ async function execute(ws, argv, stdin) {
5619
6594
  behind: !!(pulled && remote.version.n > pulled.version.n),
5620
6595
  changes,
5621
6596
  schema: schema?.data ?? null,
6597
+ global: brings,
5622
6598
  });
5623
6599
  }
5624
6600
 
@@ -5683,6 +6659,12 @@ async function execute(ws, argv, stdin) {
5683
6659
  throw usage('ez push [-m "<message>"] [--prune] [--force]');
5684
6660
  const checked = messageText(message, "The message");
5685
6661
  if ("error" in checked) throw new Error(checked.error);
6662
+ // --dry-run reports a Global push's Live changes (docs/adr/0096). A Site push has none, and ignoring the
6663
+ // flag would push for real, so it is refused before anything is sent.
6664
+ if (!global && flags.has("--dry-run"))
6665
+ throw new Error(
6666
+ "--dry-run is for the Global Workspace (ez global push --dry-run); here it would push for real. Nothing was pushed. Run ez status to see what a push sends.",
6667
+ );
5686
6668
  const files = await ws.files();
5687
6669
  if (global && SCHEMA_FILE in files) await regenerateTypes(ws, SCHEMA_FILE);
5688
6670
  await regenerateInventory(ws);
@@ -6918,6 +7900,69 @@ async function execute(ws, argv, stdin) {
6918
7900
  throw usage(syntax);
6919
7901
  }
6920
7902
 
7903
+ case "email": {
7904
+ // docs/adr/0149: the Emails the Instance's server code sent, newest first.
7905
+ const syntax =
7906
+ "ez email list [--site <id>] [--status <status>] [--since <YYYY-MM-DD>] [--limit <n>] | ez email show <id> [--html]";
7907
+ const [sub, ...rest] = args;
7908
+ if (sub === "show") {
7909
+ const html = rest.includes("--html");
7910
+ const words = rest.filter((w) => w !== "--html");
7911
+ if (words.length !== 1 || words[0].startsWith("--")) throw usage(syntax);
7912
+ const e = await ws.emailInfo(words[0]);
7913
+ if (html) return out(e.html, e);
7914
+ return out(
7915
+ [
7916
+ e.subject,
7917
+ `${e.status}${e.reason ? ` (${e.reason})` : ""}; to ${e.recipient}${e.member ? ` (${e.member})` : ""}`,
7918
+ `from ${e.site === GLOBAL_ID ? "" : `${e.site} `}${e.sender}${e.preview ? " in a Preview" : ""}, ${ago(e.createdAt)}${e.attempts > 1 ? `, ${e.attempts} attempts` : ""}`,
7919
+ "",
7920
+ e.text,
7921
+ ].join("\n"),
7922
+ e,
7923
+ );
7924
+ }
7925
+ if (sub !== "list") throw usage(syntax);
7926
+ /** @type {import("./types.d.mts").EmailFilter} */
7927
+ const filter = {};
7928
+ for (let i = 0; i < rest.length; i += 2) {
7929
+ const [flag, value] = [rest[i], rest[i + 1]];
7930
+ if (value === undefined || value.startsWith("--")) throw usage(syntax);
7931
+ if (flag === "--site") filter.site = value;
7932
+ else if (flag === "--status") {
7933
+ if (!EMAIL_STATUSES.includes(/** @type {import("./types.d.mts").EmailStatus} */ (value)))
7934
+ throw new Error(`--status is one of ${EMAIL_STATUSES.join(", ")}.`);
7935
+ filter.status = /** @type {import("./types.d.mts").EmailStatus} */ (value);
7936
+ } else if (flag === "--since") {
7937
+ const since = /^\d{4}-\d{2}-\d{2}$/.test(value) ? Date.parse(`${value}T00:00:00Z`) : NaN;
7938
+ if (Number.isNaN(since)) throw new Error("--since is a date, YYYY-MM-DD (UTC).");
7939
+ filter.since = since;
7940
+ } else if (flag === "--limit") {
7941
+ const limit = Number(value);
7942
+ if (!Number.isInteger(limit) || limit < 1 || limit > 200)
7943
+ throw new Error("--limit is 1 to 200.");
7944
+ filter.limit = limit;
7945
+ } else throw usage(syntax);
7946
+ }
7947
+ const emails = await ws.listEmails(filter);
7948
+ if (!emails.length) return out("No emails yet.", emails);
7949
+ return out(
7950
+ emails
7951
+ .map((e) =>
7952
+ [
7953
+ e.id,
7954
+ e.status + (e.reason && e.status !== "sent" ? ` (${e.reason})` : ""),
7955
+ ago(e.createdAt),
7956
+ `${e.site === GLOBAL_ID ? "" : `${e.site}/`}${e.sender}${e.preview ? " (preview)" : ""}`,
7957
+ e.recipient,
7958
+ e.subject,
7959
+ ].join(" "),
7960
+ )
7961
+ .join("\n"),
7962
+ emails,
7963
+ );
7964
+ }
7965
+
6921
7966
  case "support": {
6922
7967
  // docs/adr/0080: a request to the Host's Developers, not to this Instance's Admins.
6923
7968
  const syntax =