@cosmicdrift/kumiko-framework 0.239.0 → 0.240.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.239.0",
+  "version": "0.240.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.239.0",
+    "@cosmicdrift/kumiko-types": "0.240.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.239.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.240.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/engine/__tests__/screen.test.ts

@@ -435,6 +435,461 @@ describe("r.screen() — registration", () => {
     );
   });
 
+  test("validateBoot rejects a relatedList rowAction with an unregistered write-handler (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "relatedList",
+                title: "s",
+                query: "app:query:foo:list",
+                columns: ["name"],
+                rowActions: [{ id: "sync", label: "actions.sync", handler: "app:write:missing" }],
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /relatedList\).*rowAction "sync" handler "app:write:missing".*not a registered write-handler/,
+    );
+  });
+
+  test("validateBoot accepts a relatedList rowAction bound to a registered write-handler (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.writeHandler(
+          "sync",
+          z.object({}),
+          async () => ({ isSuccess: true as const, data: null }),
+          {
+            access: { roles: ["Admin"] },
+          },
+        );
+        r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+          access: { openToAll: true },
+        });
+        r.queryHandler("foo:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+          access: { openToAll: true },
+        });
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "relatedList",
+                title: "s",
+                query: "app:query:foo:list",
+                columns: ["name"],
+                rowActions: [
+                  {
+                    id: "sync",
+                    label: "actions.sync",
+                    handler: "app:write:sync",
+                    payload: { pick: ["name"] },
+                  },
+                ],
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).not.toThrow();
+  });
+
+  test("validateBoot rejects a relatedList section with both rowClick and a rowActions rowClick:true entry (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("billing", (r) => {
+        r.entity(
+          "invoice",
+          createEntity({ table: "invoices", fields: { name: createTextField() } }),
+        );
+        r.screen({
+          id: "invoice-detail",
+          type: "custom",
+          renderer: { react: { __component: "stub" } },
+          detailFor: "invoice",
+        });
+      }),
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "relatedList",
+                title: "s",
+                query: "app:query:foo:list",
+                columns: ["name"],
+                rowClick: { entity: "invoice" },
+                rowActions: [
+                  {
+                    kind: "navigate",
+                    id: "open",
+                    label: "actions.open",
+                    entity: "invoice",
+                    entityId: "id",
+                    rowClick: true,
+                  },
+                ],
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /relatedList\).*has both a rowClick and 1 rowActions marked rowClick:true/,
+    );
+  });
+
+  test("validateBoot rejects a projectionDetail writeForm section with an empty fieldDefs map (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: {},
+                fields: ["name"],
+                handler: "app:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(/\(writeForm\) has an empty fieldDefs map/);
+  });
+
+  test("validateBoot rejects a projectionDetail writeForm section with zero fields (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: [],
+                handler: "app:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(/\(writeForm\) has zero fields/);
+  });
+
+  test("validateBoot rejects a projectionDetail writeForm field with no entry in fieldDefs (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["sku"],
+                handler: "app:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /\(writeForm\) field "sku" has no entry in fieldDefs/,
+    );
+  });
+
+  test("validateBoot rejects a projectionDetail writeForm section in a wizard layout (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            mode: "wizard",
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["name"],
+                handler: "app:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(/writeForm.*wizard layout/);
+  });
+
+  test("validateBoot rejects a projectionDetail writeForm section with an unregistered write-handler (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["name"],
+                handler: "app:write:missing",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /\(writeForm\) handler "app:write:missing".*not a registered write-handler/,
+    );
+  });
+
+  test("validateBoot accepts a valid projectionDetail writeForm section (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+          access: { openToAll: true },
+        });
+        r.writeHandler(
+          "save",
+          z.object({}),
+          async () => ({ isSuccess: true as const, data: null }),
+          {
+            access: { roles: ["Admin"] },
+          },
+        );
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["name"],
+                handler: "app:write:save",
+                submitLabel: "actions.save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).not.toThrow();
+  });
+
+  // withBootValidatorFixture auto-fills every key requiredKeysFromFeature
+  // reports, so every other boot test in this file passes regardless of
+  // whether required-surface-keys.ts's writeForm branch names the right key
+  // — it would pass even for a wrong namespace. Bypass the fixture (raw
+  // validateBootRaw, no stubTranslations) to pin the actual key contract.
+  test("validateBoot requires a translation for a writeForm field's own label, namespaced under the write-form pseudo-entity (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        // Screens always require their own "screen:<id>.title" key — supplied
+        // here so the throw below isolates the one key this test is about.
+        r.translations({ keys: { "screen:x.title": { en: "X" } } });
+        r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+          access: { openToAll: true },
+        });
+        r.writeHandler(
+          "save",
+          z.object({}),
+          async () => ({ isSuccess: true as const, data: null }),
+          { access: { roles: ["Admin"] } },
+        );
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["name"],
+                handler: "app:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+
+    expect(() => validateBootRaw(features)).toThrow(
+      '[i18n] Feature "app": required translation key missing: "app:entity:__write-form-section__:field:name"',
+    );
+  });
+
+  test("translating the writeForm field's pseudo-entity key lets boot pass", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.translations({
+          keys: {
+            "screen:x.title": { en: "X" },
+            "app:entity:__write-form-section__:field:name": { en: "Name" },
+          },
+        });
+        r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+          access: { openToAll: true },
+        });
+        r.writeHandler(
+          "save",
+          z.object({}),
+          async () => ({ isSuccess: true as const, data: null }),
+          { access: { roles: ["Admin"] } },
+        );
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["name"],
+                handler: "app:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+
+    expect(() => validateBootRaw(features)).not.toThrow();
+  });
+
+  test("validateBoot rejects a writeForm section on entityEdit (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("shop", (r) => {
+        r.entity("product", productEntity());
+        r.screen({
+          id: "product-edit",
+          type: "entityEdit",
+          entity: "product",
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["name"],
+                handler: "shop:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /\(entityEdit\) writeForm section "s".*projectionDetail-only/,
+    );
+  });
+
+  test("validateBoot rejects a writeForm section on configEdit (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("shop", (r) => {
+        r.config({
+          keys: { "site-name": createTenantConfig("text", { default: "" }) },
+        });
+        r.screen({
+          id: "settings",
+          type: "configEdit",
+          scope: "tenant",
+          configKeys: { siteName: "shop:config:site-name" },
+          fields: { siteName: { type: "text" } } as never,
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["name"],
+                handler: "shop:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /\(configEdit\) writeForm section "s".*projectionDetail-only/,
+    );
+  });
+
+  test("validateBoot rejects a writeForm section on actionForm (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("shop", (r) => {
+        r.writeHandler(
+          "restock",
+          z.object({}),
+          async () => ({ isSuccess: true as const, data: null }),
+          { access: { roles: ["Admin"] } },
+        );
+        r.screen({
+          id: "restock",
+          type: "actionForm",
+          handler: "shop:write:restock",
+          fields: { qty: { type: "number" } } as never,
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["name"],
+                handler: "shop:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /\(actionForm\) writeForm section "s".*projectionDetail-only/,
+    );
+  });
+
   test("stores an entityEdit screen with sections + conditional fields", () => {
     const feature = defineFeature("shop", (r) => {
       r.entity("product", productEntity());

package/src/engine/boot-validator/screens.ts

@@ -9,7 +9,12 @@ import { rowMetaFieldNames } from "../../db/table-builder";
 import { LIST_ROW_META_COLUMNS } from "../../ui-types/list-row-meta";
 import { isKebabSegment, isValidQn, qualifyEntityName } from "../qualified-name";
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops";
-import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "../screen-helpers";
+import {
+  isExtensionEditSection,
+  isWriteFormEditSection,
+  normalizeEditField,
+  normalizeListColumn,
+} from "../screen-helpers";
 import type { EntityDefinition, FeatureDefinition } from "../types";
 import type {
   DashboardCustomPanel,
@@ -732,6 +737,93 @@ export function validateScreens(
               );
             }
           }
+          if (section.rowActions !== undefined) {
+            for (const action of section.rowActions) {
+              if (action.kind === "navigate") {
+                const target = resolveRowActionNavigateTarget(
+                  feature.name,
+                  screenId,
+                  "projectionDetail",
+                  "rowAction",
+                  action,
+                  allScreenQns,
+                  navTargetShortIds,
+                  screensByShortId,
+                  detailForScreens,
+                );
+                validateRowActionNavigateParams(
+                  feature.name,
+                  screenId,
+                  "projectionDetail",
+                  undefined,
+                  action,
+                  target,
+                );
+              } else if (!allWriteHandlerQns.has(action.handler)) {
+                throw new Error(
+                  `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section ` +
+                    `"${section.title}" (relatedList) rowAction "${action.id}" handler "${action.handler}" ` +
+                    `is not a registered write-handler. Check the QN spelling (expected ` +
+                    `"<feature>:write:<short>") and that the handler is declared via r.writeHandler(...).`,
+                );
+              }
+            }
+            // section.rowClick (legacy, navigate-only) and a rowActions entry
+            // marked rowClick:true both claim the row-body click — same
+            // at-most-one constraint as entityList/projectionList's
+            // validateAtMostOneRowClick, just spanning two fields instead of one.
+            const rowClickActionCount = section.rowActions.filter(
+              (a) => a.kind === "navigate" && a.rowClick === true,
+            ).length;
+            const legacyRowClickCount = section.rowClick !== undefined ? 1 : 0;
+            if (rowClickActionCount + legacyRowClickCount > 1) {
+              throw new Error(
+                `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                  `(relatedList) has both a rowClick and ${rowClickActionCount} rowActions marked ` +
+                  `rowClick:true — at most one may fire on a row-body click.`,
+              );
+            }
+          }
+          continue;
+        }
+        if (isWriteFormEditSection(section)) {
+          if (Object.keys(section.fieldDefs).length === 0) {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                `(writeForm) has an empty fieldDefs map — declare at least one field type.`,
+            );
+          }
+          if (section.fields.length === 0) {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                `(writeForm) has zero fields — drop the section or add fields to it.`,
+            );
+          }
+          for (const f of section.fields) {
+            const fieldName = normalizeEditField(f).field;
+            if (section.fieldDefs[fieldName] === undefined) {
+              throw new Error(
+                `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                  `(writeForm) field "${fieldName}" has no entry in fieldDefs — every rendered field needs ` +
+                  `a type declared there.`,
+              );
+            }
+          }
+          if (screen.layout.mode === "wizard") {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                `is kind "writeForm" in a wizard layout — a self-persisting form is not supported in a ` +
+                `stepped form. Remove mode: "wizard" or drop the writeForm section.`,
+            );
+          }
+          if (!allWriteHandlerQns.has(section.handler)) {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                `(writeForm) handler "${section.handler}" is not a registered write-handler. Check the QN ` +
+                `spelling (expected "<feature>:write:<short>") and that the handler is declared via ` +
+                `r.writeHandler(...).`,
+            );
+          }
           continue;
         }
         if (section.fields.length === 0) {
@@ -837,6 +929,12 @@ export function validateScreens(
               `primitive (fw#2166).`,
           );
         }
+        if (isWriteFormEditSection(section)) {
+          throw new Error(
+            `[Feature ${feature.name}] Screen "${screenId}" (configEdit) writeForm section ` +
+              `"${section.title}" is not supported — writeForm is a projectionDetail-only primitive.`,
+          );
+        }
         if (section.fields.length === 0) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (configEdit) has a section "${section.title}" ` +
@@ -952,6 +1050,12 @@ export function validateScreens(
               `primitive (fw#2166).`,
           );
         }
+        if (isWriteFormEditSection(section)) {
+          throw new Error(
+            `[Feature ${feature.name}] Screen "${screenId}" (actionForm) writeForm section ` +
+              `"${section.title}" is not supported — writeForm is a projectionDetail-only primitive.`,
+          );
+        }
         if (section.fields.length === 0) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (actionForm) has a section "${section.title}" ` +
@@ -1308,6 +1412,12 @@ export function validateScreens(
               `primitive (fw#2166).`,
           );
         }
+        if (isWriteFormEditSection(section)) {
+          throw new Error(
+            `[Feature ${feature.name}] Screen "${screenId}" (entityEdit) writeForm section ` +
+              `"${section.title}" is not supported — writeForm is a projectionDetail-only primitive.`,
+          );
+        }
         if (section.fields.length === 0) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (entityEdit) has a section "${section.title}" ` +

package/src/engine/index.ts

@@ -242,6 +242,7 @@ export { buildInsertSchema, buildUpdateSchema, fieldToZod } from "./schema-build
 export {
   isExtensionEditSection,
   isFieldsEditSection,
+  isWriteFormEditSection,
   normalizeEditField,
   normalizeListColumn,
 } from "./screen-helpers";

package/src/engine/screen-helpers.ts

@@ -3,6 +3,7 @@ import type {
   EditFieldSpec,
   EditFieldsSection,
   EditSectionSpec,
+  EditWriteFormSection,
   FieldCondition,
   FormatSpec,
   ListColumnSpec,
@@ -16,6 +17,10 @@ export function isFieldsEditSection(section: EditSectionSpec): section is EditFi
   return section.kind === undefined || section.kind === "fields";
 }
 
+export function isWriteFormEditSection(section: EditSectionSpec): section is EditWriteFormSection {
+  return section.kind === "writeForm";
+}
+
 // Type guard — narrows FieldRenderer to FormatSpec. Useful for renderer
 // authors who branch on the three FieldRenderer variants without manual
 // "format" in renderer checks.

package/src/engine/types/index.ts

@@ -275,6 +275,7 @@ export type {
   EditLayout,
   EditRelatedListSection,
   EditSectionSpec,
+  EditWriteFormSection,
   EntityEditScreenDefinition,
   EntityListScreenDefinition,
   FieldCondition,

package/src/i18n/required-surface-keys.ts

@@ -1,4 +1,8 @@
-import { isExtensionEditSection, normalizeListColumn } from "../engine/screen-helpers";
+import {
+  isExtensionEditSection,
+  isWriteFormEditSection,
+  normalizeListColumn,
+} from "../engine/screen-helpers";
 import type {
   ActionFormScreenDefinition,
   ConfigEditScreenDefinition,
@@ -27,6 +31,11 @@ export const CONFIG_EDIT_ENTITY = "__config-edit__";
 /** Pseudo-entity for projectionDetail field labels (renderer projection-detail-shim). */
 export const PROJECTION_DETAIL_ENTITY = "__projection-detail__";
 
+/** Pseudo-entity for a projectionDetail writeForm section's own fieldDefs
+ *  (distinct from PROJECTION_DETAIL_ENTITY — the section's fields aren't
+ *  drawn from the host record's display entity). */
+export const WRITE_FORM_SECTION_ENTITY = "__write-form-section__";
+
 export function fieldLabelKey(featureName: string, entityName: string, fieldName: string): string {
   return `${featureName}:entity:${entityName}:field:${fieldName}`;
 }
@@ -247,6 +256,16 @@ export function requiredKeysFromScreen(
             const normalized = normalizeListColumn(col);
             if (normalized.label !== undefined) pushKey(out, normalized.label);
           }
+          for (const action of section.rowActions ?? []) pushRowActionKeys(out, action);
+          continue;
+        }
+        if (isWriteFormEditSection(section)) {
+          pushKey(out, section.title);
+          pushKey(out, section.submitLabel);
+          for (const f of section.fields) {
+            const fieldName = editFieldName(f);
+            out.add(fieldLabelKey(featureName, WRITE_FORM_SECTION_ENTITY, fieldName));
+          }
           continue;
         }
         pushKey(out, section.title);

package/src/ui-types/index.ts

@@ -30,6 +30,7 @@ export {
   isExtensionEditSection,
   isFieldsEditSection,
   isFormatSpec,
+  isWriteFormEditSection,
   normalizeEditField,
   normalizeListColumn,
 } from "../engine/screen-helpers";
@@ -74,6 +75,7 @@ export type {
   EditLayout,
   EditRelatedListSection,
   EditSectionSpec,
+  EditWriteFormSection,
   EntityEditScreenDefinition,
   EntityListScreenDefinition,
   FieldCondition,
@@ -100,7 +102,10 @@ export type {
 export type { TargetRef } from "../engine/types/target-ref";
 export type { TreeAction, TreeNode, TreeNodeState } from "../engine/types/tree-node";
 export type { WorkspaceDefinition } from "../engine/types/workspace";
-export { PROJECTION_DETAIL_ENTITY } from "../i18n/required-surface-keys";
+export {
+  PROJECTION_DETAIL_ENTITY,
+  WRITE_FORM_SECTION_ENTITY,
+} from "../i18n/required-surface-keys";
 export type {
   AppSchema,
   FeatureSchema,