@jskit-ai/http-web 0.1.78 → 0.1.80

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/http-web",
-  "version": "0.1.78",
+  "version": "0.1.80",
   "type": "module",
   "scripts": {
     "test": "node --test --test-concurrency=1"
@@ -44,14 +44,14 @@
     "./client/support/contractGuards": "./src/client/support/contractGuards.js"
   },
   "dependencies": {
-    "@jskit-ai/resource-crud-core": "0.1.175",
+    "@jskit-ai/resource-crud-core": "0.1.177",
     "@mdi/js": "^7.4.47"
   },
   "peerDependencies": {
-    "@jskit-ai/http-runtime": "0.1.231",
-    "@jskit-ai/kernel": "0.1.233",
-    "@jskit-ai/realtime": "0.1.230",
-    "@jskit-ai/shell-web": "0.1.237",
+    "@jskit-ai/http-runtime": "0.1.233",
+    "@jskit-ai/kernel": "0.1.235",
+    "@jskit-ai/realtime": "0.1.232",
+    "@jskit-ai/shell-web": "0.1.239",
     "@tanstack/vue-query": "^5.90.5",
     "vue": "^3.5.13",
     "vue-router": "^5.0.4",

package/patterns/crud-screen-set/PATTERN.md

@@ -42,6 +42,13 @@ questionnaire.
 - Resource-load errors stay inside the screen with retry. Command success and
   failure use JSKIT's shared toast/snackbar feedback path.
 - URLs are route templates or route objects resolved through the screen runtime.
+- Browser URL templates include the configured surface prefix; unlike API
+  suffixes, `/new` and `/` are absolute browser paths. Use the complete route or
+  `paths.page()` for a link without record placeholders, and the owning CRUD
+  runtime's `resolveParams()` for record placeholders.
+- `CrudListScreen` applies `createLabel` to all create actions. Its responsive
+  card and table layouts both remain in the DOM; Playwright text assertions
+  should filter to visible matches rather than match a hidden layout too.
 - Product field components are ordinary application source.
 - Query keys and placement sources describe the resource, not an authoring tool.
 - No generated-file markers, overwrite contracts, receipts, or provenance remain.
@@ -63,6 +70,29 @@ filters and actions explicit without adding empty screen machinery elsewhere.
 
 ## Variation points
 
+`useCrudAddEditScreen()` requires `addEditOptions.queryKeyFactory` even when
+`readEnabled` is false. Include the resource, surface, route scope and record
+id (or a distinct new-record marker) so form cache entries stay separate.
+The New/Edit examples supply it; list/view screen wrappers derive their
+standard keys from `resourceNamespace`.
+
+Save navigation is configured in the top-level `saveSuccess` object. The default
+prefers a configured record-view URL, then the list. A create-and-list variation
+sets `navigateToView: false` and `listUrlTemplate` to its list route. Set both
+`navigateToView` and `navigateToList` to `false` to stay on the form. A custom
+`addEditOptions.onSaveSuccess` replaces default invalidation and navigation;
+it is unnecessary for ordinary list navigation. The generic CRUD guide explains
+this contract under **Save navigation**.
+
+Ownership and permission-bootstrap mode are different options. For a public
+resource on a public surface, use `ownershipFilter: "public"` in form options
+or lower-level request composables. List/view screen wrappers derive request
+scope from the configured surface and do not expose this option. Keep the
+default `access: "auto"` when there are no permission
+requirements. `access` accepts only `auto`, `always`, or `never`; `public` is
+not an access mode. `always` requires bootstrap permissions even when there
+are no permission requirements. Do not add accounts to satisfy that override.
+
 Change routes, labels, visible fields, field components, filters, query params,
 realtime events, delete availability, and action definitions. Use the screen
 slots for domain-specific content. Use a lower-level request composable only

package/patterns/crud-screen-set/example/books/BookEditPage.vue

@@ -21,6 +21,7 @@ const screen = useCrudAddEditScreen({
   addEditOptions: {
     apiUrlTemplate: "/books/:bookId",
     placementSource: "crud.books.edit",
+    queryKeyFactory: (surfaceId = "", scope = "") => ["crud", "books", surfaceId, scope, routeRecordId.value],
     writeMethod: "PATCH",
     requestRecoveryLabel: "Book",
     fallbackLoadError: "Unable to load this book.",

package/patterns/crud-screen-set/example/books/BookNewPage.vue

@@ -15,6 +15,7 @@ const screen = useCrudAddEditScreen({
   addEditOptions: {
     apiSuffix: "/books",
     placementSource: "crud.books.new",
+    queryKeyFactory: (surfaceId = "", scope = "") => ["crud", "books", surfaceId, scope, "new"],
     readEnabled: false,
     writeMethod: "POST",
     recordIdParam: "bookId",

package/src/client/components/CrudListScreen.vue

@@ -314,7 +314,7 @@ function setSelectableRowsSelected(selected = true) {
       variant="flat"
       :to="listPrimaryAction"
     >
-      New
+      {{ createLabel }}
     </v-btn>
   </section>
 </template>

package/test/crudScreenComponents.test.js

@@ -3,6 +3,12 @@ import path from "node:path";
 import test from "node:test";
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
+import { registerHooks } from "node:module";
+import { compileScript, parse } from "@vue/compiler-sfc";
+import { createSSRApp, defineComponent, h } from "vue";
+import { renderToString } from "vue/server-renderer";
+import { createMemoryHistory, createRouter } from "vue-router";
 
 const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
 const PACKAGE_DIR = path.resolve(TEST_DIRECTORY, "..");
@@ -15,6 +21,58 @@ async function readClientFile(...parts) {
   return readFile(path.join(PACKAGE_DIR, "src", "client", ...parts), "utf8");
 }
 
+test("every CRUD list create action retains its configured label and destination", async () => {
+  const componentUrl = new URL("../src/client/components/CrudListScreen.vue", import.meta.url).href;
+  const hooks = registerHooks({
+    load(url, context, nextLoad) {
+      if (!url.endsWith(".vue")) return nextLoad(url, context);
+      if (url !== componentUrl) {
+        return { format: "module", shortCircuit: true, source: "export default { render: () => null };" };
+      }
+      const { descriptor } = parse(readFileSync(new URL(url), "utf8"));
+      return {
+        format: "module", shortCircuit: true,
+        source: compileScript(descriptor, { id: "crud-list-create-label", inlineTemplate: true }).content
+      };
+    }
+  });
+  let CrudListScreen;
+  try {
+    ({ default: CrudListScreen } = await import(componentUrl));
+  } finally {
+    hooks.deregister();
+  }
+
+  for (const populated of [false, true]) {
+    for (const createLabel of [undefined, "Add book"]) {
+      const screen = {
+        records: {}, listPrimaryAction: "/books/new",
+        displayRows: populated ? [{ key: "1", recordKey: "1", record: { title: "Kindred" } }] : [],
+        resolveRecordTitle: (record) => record.title
+      };
+      const app = createSSRApp({ render: () => h(CrudListScreen, {
+        screen, ...(createLabel === undefined ? {} : { createLabel })
+      }) });
+      const router = createRouter({
+        history: createMemoryHistory(), routes: [{ path: "/books", component: { render: () => null } }]
+      });
+      await router.push("/books");
+      app.use(router);
+      app.component("VBtn", defineComponent({
+        props: { to: { type: [String, Object], default: undefined } },
+        setup: (props, { slots }) => () => h("a", { href: props.to }, slots.default?.())
+      }));
+      for (const name of ["VSheet", "VTable", "VTextField", "VSkeletonLoader", "VCheckboxBtn"]) {
+        app.component(name, defineComponent({ setup: (_props, { slots }) => () => h("div", slots.default?.()) }));
+      }
+      const html = await renderToString(app);
+      const labels = [...html.matchAll(/<a[^>]*href="\/books\/new"[^>]*>(.*?)<\/a>/gs)]
+        .map((match) => match[1].trim());
+      assert.deepEqual(labels, Array(populated ? 2 : 3).fill(createLabel ?? "New record"));
+    }
+  }
+});
+
 test("CRUD screen components own list/view/form chrome centrally", async () => {
   const listSource = await readComponent("CrudListScreen.vue");
   const viewSource = await readComponent("CrudViewScreen.vue");

package/test/crudScreenPattern.test.js

@@ -1,11 +1,20 @@
 import assert from "node:assert/strict";
 import { execFile } from "node:child_process";
 import { readdir, readFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { registerHooks } from "node:module";
 import path from "node:path";
 import test from "node:test";
 import { promisify } from "node:util";
 import { fileURLToPath } from "node:url";
 import { compileScript, compileTemplate, parse } from "@vue/compiler-sfc";
+import { createSSRApp, h } from "vue";
+import { renderToString } from "vue/server-renderer";
+import { createMemoryHistory, createRouter } from "vue-router";
+import { QueryClient, VueQueryPlugin } from "@tanstack/vue-query";
+import { defineCrudResource } from "@jskit-ai/resource-crud-core/shared/crudResource";
+import { useCrudAddEditScreen } from "../src/client/composables/useCrudAddEditScreen.js";
+import { useCrudListScreen } from "../src/client/composables/useCrudListScreen.js";
 
 const execFileAsync = promisify(execFile);
 const patternRoot = path.resolve(
@@ -14,6 +23,84 @@ const patternRoot = path.resolve(
 );
 const exampleRoot = path.join(patternRoot, "example", "books");
 
+const hooks = registerHooks({
+  resolve(specifier, context, nextResolve) {
+    if (specifier === "@local/books/shared") {
+      return { shortCircuit: true, url: new URL("../../resource-crud-core/patterns/resource-contract/example/bookResource.js", import.meta.url).href };
+    }
+    return nextResolve(specifier, context);
+  },
+  load(url, context, nextLoad) {
+    if (!url.endsWith(".vue")) return nextLoad(url, context);
+    const { descriptor } = parse(readFileSync(new URL(url), "utf8"));
+    return { format: "module", shortCircuit: true, source: compileScript(descriptor, { id: url }).content };
+  }
+});
+
+test("the human guide's public create/list configuration works without bootstrap permissions", async () => {
+  const guide = await readFile(new URL("../../agent-docs/site/guide/framework/crud-operations.md", import.meta.url), "utf8");
+  const snippets = Array.from(guide.matchAll(/```js\n([\s\S]*?)\n```/gu), (match) => match[1]);
+  const resource = new Function("defineCrudResource", `${snippets.find((source) => source.startsWith("const bookResource"))}\nreturn bookResource;`)(defineCrudResource);
+  const options = new Function(`return ({${snippets.find((source) => source.startsWith("addEditOptions:"))}});`)();
+  const router = createRouter({ history: createMemoryHistory(), routes: [{ path: "/books/:bookId?", component: { render: () => h("div") } }] });
+  await router.push("/books/new");
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  const writes = [];
+  const saved = [];
+  const client = {
+    async request(path, requestOptions) {
+      assert.equal(path, "/api/books");
+      assert.equal(requestOptions.csrf, false);
+      if (requestOptions.method === "GET") return { items: [...saved], nextCursor: null };
+      writes.push(requestOptions.body);
+      const record = { id: "1", ...requestOptions.body };
+      saved.push(record);
+      return record;
+    }
+  };
+  let form;
+  let list;
+  const app = createSSRApp({
+    setup() {
+      form = useCrudAddEditScreen({
+        ...options,
+        resource,
+        operationName: "create",
+        formFields: [{ key: "title", type: "string" }],
+        addEditOptions: { ...options.addEditOptions, client }
+      });
+      list = useCrudListScreen({ resource, resourceNamespace: "books", apiSuffix: "/books", readEnabled: false, client });
+      return () => h("div");
+    }
+  });
+  app.use(router);
+  app.use(VueQueryPlugin, { queryClient });
+  app.provide("jskit.shell-web.runtime.web-placement.client", {
+    getPlacements: () => [],
+    getContext: () => ({ surfaceConfig: { defaultSurfaceId: "home", enabledSurfaceIds: ["home"], surfacesById: { home: { id: "home", enabled: true, routeBase: "/", pagesRoot: "", requiresWorkspace: false } } } })
+  });
+  try {
+    await renderToString(app);
+    assert.equal(form.addEdit.loadError, "");
+    assert.equal(form.addEdit.isSubmitDisabled, false);
+    await form.addEdit.submit();
+    assert.equal(writes.length, 0);
+    form.formState.title = "Public book";
+    await form.addEdit.submit();
+    assert.deepEqual(writes, [{ title: "Public book" }]);
+    assert.equal(router.currentRoute.value.path, "/books");
+    await list.records.reload();
+    assert.deepEqual(list.records.items, [{ id: "1", title: "Public book" }]);
+    assert.deepEqual(Object.keys(resource.operations), ["list", "view", "create"]);
+    assert.equal(Object.hasOwn(resource.schema, "userId"), false);
+  } finally {
+    queryClient.clear();
+  }
+});
+const { default: BookNewPage } = await import("../patterns/crud-screen-set/example/books/BookNewPage.vue");
+const { default: BookEditPage } = await import("../patterns/crud-screen-set/example/books/BookEditPage.vue");
+hooks.deregister();
+
 test("CRUD screen pattern is thin app-owned source over shared public screens", async () => {
   const files = (await readdir(exampleRoot)).sort();
   const sources = await Promise.all(files.map((file) => readFile(path.join(exampleRoot, file), "utf8")));
@@ -58,3 +145,34 @@ test("CRUD screen pattern is thin app-owned source over shared public screens",
     }
   }
 });
+
+test("published New/Edit page setup runs the real CRUD form composables with distinct cache keys", async () => {
+  for (const [Page, routePath, marker] of [[BookNewPage, "/books/new", "new"], [BookEditPage, "/books/42/edit", "42"]]) {
+    const router = createRouter({
+      history: createMemoryHistory(),
+      routes: [{ path: "/books/new", component: { render: () => h("div") } }, { path: "/books/:bookId/edit", component: { render: () => h("div") } }]
+    });
+    await router.push(routePath);
+    const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+    let screen;
+    const app = createSSRApp({
+      ...Page,
+      setup(props, context) {
+        screen = Page.setup(props, context).screen;
+        return () => h("div");
+      }
+    });
+    app.use(router);
+    app.use(VueQueryPlugin, { queryClient });
+    app.provide("jskit.shell-web.runtime.web-placement.client", {
+      getPlacements: () => [],
+      getContext: () => ({ surfaceConfig: { defaultSurfaceId: "app", enabledSurfaceIds: ["app"], surfacesById: { app: { id: "app", enabled: true, routeBase: "/", pagesRoot: "", requiresWorkspace: false } } } })
+    });
+    await renderToString(app);
+    assert.equal(screen.addEdit.loadError, "");
+    if (marker === "new") assert.equal(screen.addEdit.isSubmitDisabled, false);
+    const keys = queryClient.getQueryCache().getAll().map((query) => query.queryKey);
+    assert.equal(keys.some((key) => key[0] === "crud" && key[1] === "books" && key.includes(marker)), true);
+    queryClient.clear();
+  }
+});