@tristan2828/ui-foundation 4.8.0 → 4.9.1

package/conventions/docs/add-an-entity.md

@@ -178,7 +178,12 @@ is a filled-in example while the Widgets demo is still here).
    a toast naming the row and the server's reason; the lists refetch
    after). Its specs cover a flip that saves, the keyboard, and a failed
    save putting the switch back. Copy `useSaveWidgetField` whenever the
-   plan has a `toggle` or any quick action, and only then.
+   plan has a `toggle` or any quick action, and only then. It finds the
+   record under the entity's own detail and list keys: on a screen that
+   holds it in a query of its own, a plain change (`{ field: value }`) is
+   still sent but only shows once that query refetches, and a change
+   built from the record (`(record) => …`) is refused, with a console
+   warning naming the keys searched.
    - `src/routes/widgets/use-widgets.ts`, `use-widget-categories.ts` →
      `src/routes/<entity>/use-<entity>.ts` (TanStack Query hooks over the
      new gateway module)

package/dist/hooks/use-record-update.js

@@ -21,6 +21,10 @@
 //   or the AppError's).
 // - **The lists refetch once the last save settles**, so a filter on the
 //   field drops the row once the server agrees.
+// - **A record in neither cache** (the screen holds it in a query of its
+//   own) still saves an object change, shown once that query refetches; a
+//   function change has nothing to build on and is refused like any other
+//   refusal. Both warn in the console, naming the keys searched.
 //
 // Editing in place uses the same save with `optimistic: false` and
 // `toastOnError: false`: nothing changes on screen until the server
@@ -35,6 +39,11 @@ function recordStates(queryClient) {
         states.set(queryClient, (map = new Map()));
     return map;
 }
+// A function change with no record in either cache to build it from.
+const notLoaded = {
+    kind: 'server',
+    message: "It isn't loaded on this page. Reload and try again",
+};
 function resolve(change, record) {
     return typeof change === 'function' ? change(record) : change;
 }
@@ -94,9 +103,19 @@ export function recordUpdateMutationOptions(queryClient, { id, detailKey, listsK
         scope: { id: `record-update:${key}` },
         mutationFn: (change) => {
             const confirmed = map.get(key)?.confirmed ?? cached();
-            if (!confirmed)
-                return Promise.reject(new Error('The record to update is not loaded'));
-            return update(id, resolve(change, confirmed));
+            if (confirmed)
+                return update(id, resolve(change, confirmed));
+            // The screen holds the record somewhere these keys don't reach (a
+            // query gathering a related list's records, say). An object change
+            // needs no current record, so it's still sent; a function change
+            // can't be built, and says so rather than doing nothing. Warned in
+            // every build: the package has no dev flag every app's bundler sets.
+            console.warn(`useRecordUpdate: record ${String(id)} isn't cached under ${JSON.stringify(detailKey)} ` +
+                `or any list under ${JSON.stringify(listsKey)}, so the change isn't shown until the server answers` +
+                (typeof change === 'function' ? ', and a change built from the record can\'t be sent' : ''));
+            if (typeof change === 'function')
+                return Promise.reject(notLoaded);
+            return update(id, change);
         },
         onMutate: async (change) => {
             let state = map.get(key);
@@ -120,7 +139,8 @@ export function recordUpdateMutationOptions(queryClient, { id, detailKey, listsK
                 return;
             // What was sent: the change built on the record it was sent against.
             const record = state.confirmed;
-            const sent = record && resolve(context.entry.change, record);
+            const { change } = context.entry;
+            const sent = record ? resolve(change, record) : typeof change === 'function' ? undefined : change;
             settle(state, context.entry);
             if (toastOnError)
                 toast.error(`Couldn't update ${record ? name(record) : 'this record'}: ${refusalReason(error, sent)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.8.0",
+  "version": "4.9.1",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {

package/vite/index.d.ts

@@ -3,12 +3,24 @@ import type { Plugin } from 'vite'
 export type BuildInfoOptions = {
   /** The app's repository, e.g. `https://github.com/me/app`. `BUILD_REPO_URL` wins over it. */
   repoUrl?: string
+  /**
+   * The Alembic versions folder, from the Vite root (`backend/migrations/versions`).
+   * Adds `schema`, the head revision, to `build-info.json`; no head or
+   * several fails the build.
+   */
+  alembic?: string
+  /**
+   * More fields for `build-info.json`, merged in. `api`, `commit`, `pr`,
+   * `builtAt` and `schema` are the plugin's own: returning one fails the build.
+   */
+  extra?: () => Record<string, unknown>
 }
 
 /**
  * On `vite build`, writes `dist/build-info.json` (`api`: "real" or "mock",
- * `commit`, `pr`, `builtAt`) and sets `import.meta.env.VITE_BUILD_COMMIT`,
- * `VITE_BUILD_PR` and `VITE_BUILD_REPO_URL` from `BUILD_COMMIT`,
- * `BUILD_PR` and `BUILD_REPO_URL`.
+ * `commit`, `pr`, `builtAt`, and `schema` with `alembic`) and sets
+ * `import.meta.env.VITE_BUILD_COMMIT`, `VITE_BUILD_PR` and
+ * `VITE_BUILD_REPO_URL` from `BUILD_COMMIT`, `BUILD_PR` and
+ * `BUILD_REPO_URL`.
  */
 export default function buildInfo(options?: BuildInfoOptions): Plugin

package/vite/index.js

@@ -13,21 +13,72 @@
 //   BUILD_REPO_URL (the repoUrl option when that's unset), for AppShell's
 //   `version`. Unset, they're empty strings and nothing is shown.
 //
+// - with `alembic` (the migrations' versions folder, from the Vite root),
+//   adds `schema`: the head revision the backend migrates to. Read from the
+//   files, so the build needs no Python. No head, or several, fails the
+//   build, as `alembic upgrade head` would refuse at start.
+// - with `extra`, merges what it returns into the file. It can't replace the
+//   fields above: the backend's production check reads `api`.
+//
 // Build only: in development the three are undefined. Plain JavaScript, like
 // the eslint entry: Vite loads the config before any TypeScript tooling runs.
 
+import fs from 'node:fs'
+import path from 'node:path'
+
+const OWN_FIELDS = ['api', 'commit', 'pr', 'builtAt', 'schema']
+
 /** @param {string | undefined} value */
 function clean(value) {
   const trimmed = value?.trim()
   return trimmed ? trimmed : null
 }
 
-/** @param {{ repoUrl?: string }} [options] */
+// `revision = "abc"` or `revision: str = "abc"`, as Alembic writes them.
+const REVISION = /^revision(?:\s*:[^=\n]+)?\s*=\s*(['"])([^'"]+)\1/m
+// None, one revision, or a tuple of them (a merge), possibly over lines.
+const DOWN_REVISION = /^down_revision(?:\s*:[^=\n]+)?\s*=\s*(\([^)]*\)|[^\n]*)/m
+
+/**
+ * The one revision no other migration names as its down_revision.
+ * @param {string} dir
+ */
+function alembicHead(dir) {
+  if (!fs.existsSync(dir)) throw new Error(`buildInfo: no Alembic versions folder at ${dir}.`)
+  const revisions = new Set()
+  const downs = new Set()
+  for (const file of fs.readdirSync(dir).filter((name) => name.endsWith('.py'))) {
+    const source = fs.readFileSync(path.join(dir, file), 'utf8')
+    const revision = REVISION.exec(source)
+    if (!revision) continue
+    revisions.add(revision[2])
+    const down = DOWN_REVISION.exec(source)?.[1] ?? ''
+    for (const [, , name] of down.matchAll(/(['"])([^'"]+)\1/g)) downs.add(name)
+  }
+  const heads = [...revisions].filter((revision) => !downs.has(revision)).sort()
+  if (heads.length === 1) return heads[0]
+  throw new Error(
+    heads.length === 0
+      ? `buildInfo: no Alembic head in ${dir} (no migrations, or they form a loop).`
+      : `buildInfo: several Alembic heads in ${dir} (${heads.join(', ')}); alembic upgrade head would refuse. Merge them first.`,
+  )
+}
+
+/**
+ * @param {{
+ *   repoUrl?: string,
+ *   alembic?: string,
+ *   extra?: () => Record<string, unknown>,
+ * }} [options]
+ */
 export default function buildInfo(options = {}) {
   const commit = clean(process.env.BUILD_COMMIT)
   const pr = clean(process.env.BUILD_PR)
   const repoUrl = clean(process.env.BUILD_REPO_URL) ?? clean(options.repoUrl)
   let api = 'mock'
+  let root = process.cwd()
+  /** @type {Record<string, unknown>} */
+  let fields = {}
 
   return {
     name: 'ui-foundation:build-info',
@@ -44,12 +95,26 @@ export default function buildInfo(options = {}) {
     configResolved(config) {
       // The same test as the app's main.tsx: anything but "real" ships MSW.
       api = config.env.VITE_API === 'real' ? 'real' : 'mock'
+      root = config.root
+    },
+    // Read before bundling, so a bad migration chain fails the build early.
+    buildStart() {
+      fields = {}
+      if (options.alembic) fields.schema = alembicHead(path.resolve(root, options.alembic))
+      if (options.extra) {
+        const extra = options.extra()
+        const taken = Object.keys(extra).filter((key) => OWN_FIELDS.includes(key))
+        if (taken.length > 0) {
+          throw new Error(`buildInfo: extra can't set ${taken.join(', ')}; build-info.json's own fields.`)
+        }
+        Object.assign(fields, extra)
+      }
     },
     generateBundle() {
       this.emitFile({
         type: 'asset',
         fileName: 'build-info.json',
-        source: `${JSON.stringify({ api, commit, pr, builtAt: new Date().toISOString() }, null, 2)}\n`,
+        source: `${JSON.stringify({ api, commit, pr, builtAt: new Date().toISOString(), ...fields }, null, 2)}\n`,
       })
     },
   }