@cosmicdrift/kumiko-bundled-features 0.24.1 → 0.26.0

package/src/custom-fields/constants.ts

@@ -28,13 +28,14 @@ export const CustomFieldsQueries = {
 // `component: { react: { __component: CUSTOM_FIELDS_FORM_EXTENSION_NAME } }`.
 export const CUSTOM_FIELDS_FORM_EXTENSION_NAME = "CustomFieldsFormSection";
 
-// Event-Type-Names (qualified at registration via r.defineEvent — final
-// names are `custom-fields:event:field-definition-created` etc.).
-// Short-names MUST be in kebab-case (no dots): qualifyEntityName runs toKebab
-// which collapses dots to dashes, so a dotted short-name diverges from the
-// registry key when handlers hand-build the qualified string.
-export const FIELD_DEFINITION_CREATED_EVENT = "field-definition-created";
-export const FIELD_DEFINITION_UPDATED_EVENT = "field-definition-updated";
+// Entity-CRUD auto-events for the `field-definition` entity. registry.ts emits
+// these as `${entityName}.created`/`.updated` (dot form) — they do NOT run
+// through r.defineEvent/toKebab, so the dot MUST stay.
+export const FIELD_DEFINITION_CREATED_EVENT = "field-definition.created";
+export const FIELD_DEFINITION_UPDATED_EVENT = "field-definition.updated";
+// Qualified at registration via r.defineEvent — final name is
+// `custom-fields:event:field-definition-deleted`. Short-name MUST be kebab
+// (no dots): qualifyEntityName runs toKebab which collapses dots to dashes.
 export const FIELD_DEFINITION_DELETED_EVENT = "field-definition-deleted";
 
 // Custom-field-VALUE events. Live auf host-aggregate stream (ES-Option-B).

package/src/custom-fields/db/queries/field-access.ts

@@ -11,6 +11,6 @@ export async function selectSerializedFieldDefinition(
     "SELECT serialized_field FROM read_custom_field_definitions WHERE entity_name = $1 AND field_key = $2 AND tenant_id = $3 LIMIT 1",
     [entityName, fieldKey, tenantId],
   );
-  const first = (rows as ReadonlyArray<Record<string, unknown>>)[0];
+  const first = (rows as ReadonlyArray<Record<string, unknown>>)[0]; // @cast-boundary db-row
   return first ? (first["serialized_field"] ?? null) : null;
 }

package/src/custom-fields/db/queries/projection.ts

@@ -1,15 +1,23 @@
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 
 function quoteTable(tableName: string): string {
   return `"${tableName.replace(/"/g, '""')}"`;
 }
 
 function bindJsonbParam(value: unknown): { sql: string; bound: unknown } {
-  // postgres-js infers boolean params as boolean[] candidates — route via text::jsonb.
-  if (typeof value === "boolean") {
+  // Scalar JSON primitives can't bind directly to ::jsonb — Postgres rejects a
+  // bound boolean/number with "cannot cast type boolean/integer to jsonb" (and
+  // Bun.SQL infers boolean[] candidates). Route them through ::text::jsonb with
+  // a JSON-encoded literal. Objects/arrays/strings already bind as ::jsonb.
+  if (typeof value === "boolean" || typeof value === "number") {
     return { sql: "$1::text::jsonb", bound: JSON.stringify(value) };
   }
+  // JSON.stringify throws on bigint; its decimal string is a valid JSON number literal.
+  if (typeof value === "bigint") {
+    return { sql: "$1::text::jsonb", bound: value.toString() };
+  }
   return { sql: "$1::jsonb", bound: value };
 }
 
@@ -21,7 +29,7 @@ export async function setCustomFieldValue(
   fieldKey: string,
   value: unknown,
   aggregateId: string,
-  tenantId: string,
+  tenantId: TenantId,
 ): Promise<void> {
   const tbl = quoteTable(tableName);
   const escapedKey = fieldKey.replace(/'/g, "''");
@@ -37,7 +45,7 @@ export async function clearCustomFieldKey(
   tableName: string,
   fieldKey: string,
   aggregateId: string,
-  tenantId: string,
+  tenantId: TenantId,
 ): Promise<void> {
   const tbl = quoteTable(tableName);
   await asRawClient(db).unsafe(
@@ -54,7 +62,7 @@ export async function removeCustomFieldKeyForTenant(
   db: DbRunner,
   tableName: string,
   fieldKey: string,
-  tenantId: string,
+  tenantId: TenantId,
 ): Promise<void> {
   const tbl = quoteTable(tableName);
   await asRawClient(db).unsafe(

package/src/custom-fields/db/queries/quota.ts

@@ -6,7 +6,7 @@ export async function countTenantFieldDefinitions(db: TenantDb, tenantId: string
     "SELECT COUNT(*)::int AS n FROM read_custom_field_definitions WHERE tenant_id = $1",
     [tenantId],
   );
-  const rows = rowsResult as ReadonlyArray<Record<string, unknown>>;
+  const rows = rowsResult as ReadonlyArray<Record<string, unknown>>; // @cast-boundary db-row
   const first = rows[0];
   if (!first) return 0;
   const n = first["n"];

package/src/custom-fields/db/queries/retention.ts

@@ -25,15 +25,29 @@ export async function selectHostRowsWithCustomFields(
   return Array.isArray(rowsResult) ? rowsResult : [];
 }
 
-export async function updateHostRowCustomFields(
+export async function applyRetentionRemovals(
   db: DbRunner,
   tableName: string,
-  customFields: Record<string, unknown>,
+  deleteKeys: readonly string[],
+  anonymizeKeys: readonly string[],
   rowId: string,
 ): Promise<void> {
   const quoted = `"${tableName.replace(/"/g, '""')}"`;
-  await asRawClient(db).unsafe(`UPDATE ${quoted} SET custom_fields = $1::jsonb WHERE id = $2`, [
-    customFields,
-    rowId,
-  ]);
+  // Atomic per-row jsonb edit instead of read-modify-write of the whole
+  // object: delete-keys are dropped (`- $1::text[]`), anonymize-keys are set
+  // to JSON null via a merge patch. Operating on the live row value preserves
+  // a concurrent set-custom-field on any *other* key — no lost update.
+  await asRawClient(db).unsafe(
+    `UPDATE ${quoted} SET custom_fields = CASE
+       WHEN jsonb_typeof(custom_fields) = 'object' THEN
+         (custom_fields - $1::text[])
+         || COALESCE(
+              (SELECT jsonb_object_agg(k, 'null'::jsonb) FROM unnest($2::text[]) AS k),
+              '{}'::jsonb
+            )
+       ELSE custom_fields
+     END
+     WHERE id = $3`,
+    [deleteKeys, anonymizeKeys, rowId],
+  );
 }

package/src/custom-fields/executor.ts

@@ -0,0 +1,10 @@
+import { createEntityExecutor } from "@cosmicdrift/kumiko-framework/engine";
+import { fieldDefinitionEntity } from "./entity";
+
+// Single field-definition executor shared by the four define/delete handlers.
+// createEntityExecutor is side-effect-free; instantiating it once keeps the
+// table+executor pair in one place instead of rebuilding it per handler module.
+export const { executor: fieldDefinitionExecutor } = createEntityExecutor(
+  "field-definition",
+  fieldDefinitionEntity,
+);

package/src/custom-fields/feature.ts

@@ -37,7 +37,12 @@
 //    Value-Validation gegen serializedField → set-custom-field via fieldToZod —
 //    alle erledigt.)
 
-import { defineEntityListHandler, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  defineEntityListHandler,
+  defineFeature,
+  type FeatureRegistrar,
+  type WriteHandlerDef,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import {
   CUSTOM_FIELD_CLEARED_EVENT,
@@ -71,12 +76,14 @@ const fieldDefinitionDeletedSchema = z.object({
   tenantId: z.string().optional(),
 });
 
-// Singleton feature-definition mit typed exports. Handler + wire-for-entity
-// importieren diesen `customFieldsFeature` und greifen lazy in ihrer
-// runtime-arrow-fn auf `.exports.<event>.name` zu — der module-cycle
-// (feature.ts -> handlers/*.write.ts -> feature.ts) löst sich auf weil
-// kein top-level-access stattfindet.
-export const customFieldsFeature = defineFeature(CUSTOM_FIELDS_FEATURE_NAME, (r) => {
+// Shared registration body for both the singleton and the quota-variant.
+// Only the define-tenant-field handler differs (quota baked in or not); every
+// other entity/event/handler is registered identically here so a new
+// event/handler can never silently miss the quota variant.
+function registerCustomFields(
+  r: FeatureRegistrar<typeof CUSTOM_FIELDS_FEATURE_NAME>,
+  defineTenantHandler: WriteHandlerDef,
+) {
   r.entity("field-definition", fieldDefinitionEntity);
 
   // Event-types — qualified als "custom-fields:event:<short-name>".
@@ -101,7 +108,7 @@ export const customFieldsFeature = defineFeature(CUSTOM_FIELDS_FEATURE_NAME, (r)
   r.extendsRegistrar(CUSTOM_FIELDS_EXTENSION, {});
 
   // Definition-CRUD handlers (B1).
-  r.writeHandler(defineTenantFieldHandler);
+  r.writeHandler(defineTenantHandler);
   r.writeHandler(defineSystemFieldHandler);
   r.writeHandler(deleteTenantFieldHandler);
   r.writeHandler(deleteSystemFieldHandler);
@@ -116,7 +123,16 @@ export const customFieldsFeature = defineFeature(CUSTOM_FIELDS_FEATURE_NAME, (r)
   );
 
   return { setEvent, clearedEvent, fieldDefinitionDeletedEvent };
-});
+}
+
+// Singleton feature-definition mit typed exports. Handler + wire-for-entity
+// importieren diesen `customFieldsFeature` und greifen lazy in ihrer
+// runtime-arrow-fn auf `.exports.<event>.name` zu — der module-cycle
+// (feature.ts -> handlers/*.write.ts -> feature.ts) löst sich auf weil
+// kein top-level-access stattfindet.
+export const customFieldsFeature = defineFeature(CUSTOM_FIELDS_FEATURE_NAME, (r) =>
+  registerCustomFields(r, defineTenantFieldHandler),
+);
 
 // Backwards-compat-wrapper. Bestehende Caller (z.B. integration-tests,
 // host-apps) nutzen weiterhin `createCustomFieldsFeature()`. Returnt den
@@ -133,34 +149,11 @@ export function createCustomFieldsFeature(
   if (opts.fieldDefinitionLimitPerTenant === undefined) {
     return customFieldsFeature;
   }
-  return defineFeature(CUSTOM_FIELDS_FEATURE_NAME, (r) => {
-    r.entity("field-definition", fieldDefinitionEntity);
-
-    const setEvent = r.defineEvent(CUSTOM_FIELD_SET_EVENT, customFieldSetSchema);
-    const clearedEvent = r.defineEvent(CUSTOM_FIELD_CLEARED_EVENT, customFieldClearedSchema);
-    const fieldDefinitionDeletedEvent = r.defineEvent(
-      FIELD_DEFINITION_DELETED_EVENT,
-      fieldDefinitionDeletedSchema,
-    );
-
-    r.extendsRegistrar(CUSTOM_FIELDS_EXTENSION, {});
-
-    r.writeHandler(
-      createDefineTenantFieldHandler({
-        fieldDefinitionLimitPerTenant: opts.fieldDefinitionLimitPerTenant,
-      }),
-    );
-    r.writeHandler(defineSystemFieldHandler);
-    r.writeHandler(deleteTenantFieldHandler);
-    r.writeHandler(deleteSystemFieldHandler);
-
-    r.writeHandler(setCustomFieldHandler);
-    r.writeHandler(clearCustomFieldHandler);
-
-    r.queryHandler(
-      defineEntityListHandler("field-definition", fieldDefinitionEntity, tenantAdminAccess),
-    );
-
-    return { setEvent, clearedEvent, fieldDefinitionDeletedEvent };
-  });
+  const limit = opts.fieldDefinitionLimitPerTenant;
+  return defineFeature(CUSTOM_FIELDS_FEATURE_NAME, (r) =>
+    registerCustomFields(
+      r,
+      createDefineTenantFieldHandler({ fieldDefinitionLimitPerTenant: limit }),
+    ),
+  );
 }

package/src/custom-fields/handlers/clear-custom-field.write.ts

@@ -7,7 +7,11 @@ import { checkFieldAccessForWrite } from "../lib/field-access";
 export const clearCustomFieldPayloadSchema = z.object({
   entityName: z.string().min(1).max(64),
   entityId: z.string().min(1),
-  fieldKey: z.string().min(1).max(64),
+  fieldKey: z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(/^[a-zA-Z][a-zA-Z0-9_-]*$/),
 });
 export type ClearCustomFieldPayload = z.infer<typeof clearCustomFieldPayloadSchema>;
 

package/src/custom-fields/handlers/define-system-field.write.ts

@@ -1,14 +1,9 @@
-import {
-  createEntityExecutor,
-  SYSTEM_TENANT_ID,
-  type WriteHandlerDef,
-} from "@cosmicdrift/kumiko-framework/engine";
+import { SYSTEM_TENANT_ID, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { fieldDefinitionAggregateId } from "../aggregate-id";
-import { fieldDefinitionEntity } from "../entity";
+import { fieldDefinitionExecutor } from "../executor";
+import { buildFieldDefinitionColumns } from "../lib/field-definition-row";
 import { type DefineFieldPayload, defineFieldPayloadSchema } from "../schemas";
 
-const { executor } = createEntityExecutor("field-definition", fieldDefinitionEntity);
-
 // define-system-field — SystemAdmin definiert eine system-weite Custom-Field-
 // Definition die für ALLE Tenants gilt. tenantId wird auf SYSTEM_TENANT_ID
 // gesetzt (NICHT vom Caller — SystemAdmin's event.user.tenantId würde sonst
@@ -38,20 +33,8 @@ export const defineSystemFieldHandler: WriteHandlerDef = {
     // — the row lives in the system-scope-stream.
     const systemUser = { ...event.user, tenantId: SYSTEM_TENANT_ID };
 
-    return executor.create(
-      {
-        id: aggregateId,
-        entityName: payload.entityName,
-        fieldKey: payload.fieldKey,
-        type: payload.serializedField.type,
-        required: payload.required,
-        searchable: payload.searchable,
-        displayOrder: payload.displayOrder,
-        serializedField: JSON.stringify({
-          ...payload.serializedField,
-          label: payload.label,
-        }),
-      },
+    return fieldDefinitionExecutor.create(
+      { id: aggregateId, ...buildFieldDefinitionColumns(payload) },
       systemUser,
       ctx.db,
     );

package/src/custom-fields/handlers/define-tenant-field.write.ts

@@ -1,16 +1,11 @@
-import {
-  createEntityExecutor,
-  isSystemTenant,
-  type WriteHandlerDef,
-} from "@cosmicdrift/kumiko-framework/engine";
+import { isSystemTenant, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
 import { fieldDefinitionAggregateId } from "../aggregate-id";
-import { fieldDefinitionEntity } from "../entity";
+import { fieldDefinitionExecutor } from "../executor";
+import { buildFieldDefinitionColumns } from "../lib/field-definition-row";
 import { countTenantFieldDefinitions } from "../lib/quota";
 import { type DefineFieldPayload, defineFieldPayloadSchema } from "../schemas";
 
-const { executor } = createEntityExecutor("field-definition", fieldDefinitionEntity);
-
 // define-tenant-field — TenantAdmin definiert eine Custom-Field-Definition
 // für seinen eigenen Tenant. tenantId wird automatisch aus event.user.tenantId
 // abgeleitet (NICHT vom Caller setzbar — verhindert Cross-Tenant-Mutation).
@@ -32,8 +27,15 @@ const { executor } = createEntityExecutor("field-definition", fieldDefinitionEnt
 // `unprocessable` + reason `cap_exceeded` BEFORE attempting the insert.
 // The factory below closes over the limit; the legacy const-export keeps
 // behavior unchanged for callers who didn't opt into a limit.
+//
+// Soft cap, not a hard guarantee: the count-then-insert is not serialized, so
+// N concurrent defines with distinct fieldKeys can each read `current < limit`
+// and overshoot by up to N. Acceptable here — defining fields is an admin-only,
+// low-frequency action and the limit is not wired to billing/tier enforcement.
+// If an exact cap is ever needed, serialize via advisory lock or a count
+// constraint at the insert.
 export interface DefineTenantFieldOptions {
-  /** Hard quota — `>= limit` definitions per tenant rejects further defines. */
+  /** Soft cap — `>= limit` definitions per tenant rejects further defines (see header: concurrent defines may overshoot). */
   readonly fieldDefinitionLimitPerTenant?: number;
 }
 
@@ -73,20 +75,8 @@ export function createDefineTenantFieldHandler(
         payload.fieldKey,
       );
 
-      return executor.create(
-        {
-          id: aggregateId,
-          entityName: payload.entityName,
-          fieldKey: payload.fieldKey,
-          type: payload.serializedField.type,
-          required: payload.required,
-          searchable: payload.searchable,
-          displayOrder: payload.displayOrder,
-          serializedField: JSON.stringify({
-            ...payload.serializedField,
-            label: payload.label,
-          }),
-        },
+      return fieldDefinitionExecutor.create(
+        { id: aggregateId, ...buildFieldDefinitionColumns(payload) },
         event.user,
         ctx.db,
       );

package/src/custom-fields/handlers/delete-system-field.write.ts

@@ -1,15 +1,9 @@
-import {
-  createEntityExecutor,
-  SYSTEM_TENANT_ID,
-  type WriteHandlerDef,
-} from "@cosmicdrift/kumiko-framework/engine";
+import { SYSTEM_TENANT_ID, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { fieldDefinitionAggregateId } from "../aggregate-id";
-import { fieldDefinitionEntity } from "../entity";
+import { fieldDefinitionExecutor } from "../executor";
 import { customFieldsFeature } from "../feature";
 import { type DeleteFieldPayload, deleteFieldPayloadSchema } from "../schemas";
 
-const { executor } = createEntityExecutor("field-definition", fieldDefinitionEntity);
-
 // delete-system-field — SystemAdmin entfernt eine system-weite Field-
 // Definition. Konsequenz: KEIN Tenant kann mehr neue Werte dafür setzen,
 // existing Werte in read_<entity>.customFields jsonb bleiben aber bestehen
@@ -29,7 +23,7 @@ export const deleteSystemFieldHandler: WriteHandlerDef = {
     );
 
     const systemUser = { ...event.user, tenantId: SYSTEM_TENANT_ID };
-    const result = await executor.delete({ id: aggregateId }, systemUser, ctx.db);
+    const result = await fieldDefinitionExecutor.delete({ id: aggregateId }, systemUser, ctx.db);
 
     // Cascade-cleanup-Event — host-entity-MSPs entfernen orphan values aus
     // ihrer customFields jsonb. Im selben TX = atomic.

package/src/custom-fields/handlers/delete-tenant-field.write.ts

@@ -1,15 +1,9 @@
-import {
-  createEntityExecutor,
-  isSystemTenant,
-  type WriteHandlerDef,
-} from "@cosmicdrift/kumiko-framework/engine";
+import { isSystemTenant, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { fieldDefinitionAggregateId } from "../aggregate-id";
-import { fieldDefinitionEntity } from "../entity";
+import { fieldDefinitionExecutor } from "../executor";
 import { customFieldsFeature } from "../feature";
 import { type DeleteFieldPayload, deleteFieldPayloadSchema } from "../schemas";
 
-const { executor } = createEntityExecutor("field-definition", fieldDefinitionEntity);
-
 // delete-tenant-field — TenantAdmin löscht eigene Field-Definition.
 // Spec-Promise (Plan-Doc v2 "wie Entity-Delete"): Events bleiben im event-
 // store für Audit-Trail. Read-Projection-Row wird entfernt. B2 wird die
@@ -36,7 +30,7 @@ export const deleteTenantFieldHandler: WriteHandlerDef = {
 
     const aggregateId = fieldDefinitionAggregateId(tenantId, payload.entityName, payload.fieldKey);
 
-    const result = await executor.delete({ id: aggregateId }, event.user, ctx.db);
+    const result = await fieldDefinitionExecutor.delete({ id: aggregateId }, event.user, ctx.db);
 
     // Emit cascade-cleanup-Event NACH erfolgreichem Delete. host-entity-MSPs
     // (registriert via wireCustomFieldsFor) konsumieren das + entfernen orphan

package/src/custom-fields/lib/field-access.ts

@@ -34,6 +34,10 @@ export async function loadFieldDefinition(
 
 // Pure access-check on an already-loaded definition. Returns the required
 // roles when the caller is denied, or `null` when access is allowed.
+//
+// Contract: `fieldAccess.write` entries MUST be verbatim membership-system role
+// names (e.g. "TenantAdmin", not "Admin") — match is exact like framework-wide
+// `engine/access.ts`; no normalization, so a drifted name denies silently.
 export function fieldWriteAccessDeniedRoles(
   field: SerializedFieldShape | null,
   userRoles: ReadonlyArray<string>,

package/src/custom-fields/lib/field-definition-row.ts

@@ -0,0 +1,33 @@
+import type { DefineFieldPayload } from "../schemas";
+
+export interface FieldDefinitionColumns {
+  readonly entityName: string;
+  readonly fieldKey: string;
+  readonly type: string;
+  readonly required: boolean;
+  readonly searchable: boolean;
+  readonly displayOrder: number;
+  readonly serializedField: string;
+}
+
+// The required/searchable/displayOrder columns are a denormalized projection of
+// serializedField — derive, don't default. Zod gives top-level `required` a
+// `.default(false)`, so "caller omitted it" is indistinguishable from `false`
+// post-parse; serializedField-present therefore wins to preserve caller intent.
+export function buildFieldDefinitionColumns(payload: DefineFieldPayload): FieldDefinitionColumns {
+  const sf = payload.serializedField;
+  const required = typeof sf["required"] === "boolean" ? sf["required"] : payload.required;
+  const searchable = typeof sf["searchable"] === "boolean" ? sf["searchable"] : payload.searchable;
+  const displayOrder =
+    typeof sf["displayOrder"] === "number" ? sf["displayOrder"] : payload.displayOrder;
+
+  return {
+    entityName: payload.entityName,
+    fieldKey: payload.fieldKey,
+    type: sf.type,
+    required,
+    searchable,
+    displayOrder,
+    serializedField: JSON.stringify({ ...sf, label: payload.label }),
+  };
+}

package/src/custom-fields/run-retention.ts

@@ -18,9 +18,9 @@
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import {
+  applyRetentionRemovals,
   selectFieldDefinitionsWithSerialized,
   selectHostRowsWithCustomFields,
-  updateHostRowCustomFields,
 } from "./db/queries/retention";
 import { parseSerializedField } from "./lib/parse-serialized-field";
 
@@ -122,17 +122,18 @@ export async function runCustomFieldsRetention(
     // skip: nothing on this row aged out — no UPDATE needed.
     if (removals.length === 0) continue;
 
-    const mutated: Record<string, unknown> = { ...row.customFields };
+    const deleteKeys: string[] = [];
+    const anonymizeKeys: string[] = [];
     for (const { key, strategy } of removals) {
       if (strategy === "delete") {
-        delete mutated[key];
+        deleteKeys.push(key);
       } else {
-        mutated[key] = null;
+        anonymizeKeys.push(key);
       }
       removalsByFieldKey[key] = (removalsByFieldKey[key] ?? 0) + 1;
     }
 
-    await updateHostRowCustomFields(opts.db, tableName, mutated, row.id);
+    await applyRetentionRemovals(opts.db, tableName, deleteKeys, anonymizeKeys, row.id);
     rowsUpdated++;
   }
 

package/src/custom-fields/web/__tests__/custom-fields-form-section.test.tsx

@@ -8,6 +8,7 @@ import { defaultPrimitives } from "@cosmicdrift/kumiko-renderer-web";
 import { fireEvent, render, screen } from "@testing-library/react";
 import type { ReactNode } from "react";
 import { CustomFieldsFormSection } from "../custom-fields-form-section";
+import { defaultTranslations } from "../i18n";
 
 type FieldRow = {
   id: string;
@@ -21,6 +22,13 @@ type FieldRow = {
 const dispatchSpy = mock(async () => ({ isSuccess: true, data: undefined }));
 let mockedQueryRows: readonly FieldRow[] = [];
 
+const useQuerySpy = mock((_type: string, _params: unknown, _options?: { enabled?: boolean }) => ({
+  data: { rows: mockedQueryRows },
+  loading: false,
+  error: null,
+  refetch: mock(),
+}));
+
 const actual_renderer = await import("@cosmicdrift/kumiko-renderer");
 mock.module("@cosmicdrift/kumiko-renderer", () => ({
   ...actual_renderer,
@@ -29,17 +37,12 @@ mock.module("@cosmicdrift/kumiko-renderer", () => ({
     query: mock(),
     batch: mock(),
   })),
-  useQuery: mock(() => ({
-    data: { rows: mockedQueryRows },
-    loading: false,
-    error: null,
-    refetch: mock(),
-  })),
+  useQuery: useQuerySpy,
 }));
 
 function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
   return (
-    <LocaleProvider resolver={createStaticLocaleResolver()}>
+    <LocaleProvider resolver={createStaticLocaleResolver()} fallbackBundles={[defaultTranslations]}>
       <PrimitivesProvider value={defaultPrimitives}>{children}</PrimitivesProvider>
     </LocaleProvider>
   );
@@ -107,8 +110,9 @@ describe("CustomFieldsFormSection", () => {
     });
   });
 
-  test("shows create-mode banner when entityId is null", () => {
+  test("shows create-mode banner when entityId is null and skips the fieldDefinition query", () => {
     mockedQueryRows = [];
+    useQuerySpy.mockClear();
 
     render(
       <Wrapper>
@@ -116,8 +120,14 @@ describe("CustomFieldsFormSection", () => {
       </Wrapper>,
     );
 
-    expect(screen.getByTestId("custom-fields-form-create-mode")).toBeTruthy();
+    const banner = screen.getByTestId("custom-fields-form-create-mode");
+    expect(banner).toBeTruthy();
     expect(screen.queryByTestId("custom-fields-form-section")).toBeNull();
+    // The banner shows the translated string, not the raw i18n key.
+    expect(banner.textContent).toBe("Save the entity first to add custom field values.");
+    // create-mode discards the query result via the early return, so the
+    // fetch-on-mount must be disabled — no wasted server roundtrip.
+    expect(useQuerySpy.mock.calls[0]?.[2]).toEqual({ enabled: false });
   });
 
   test("shows empty banner when no fieldDefinitions match entityName", () => {
@@ -138,7 +148,32 @@ describe("CustomFieldsFormSection", () => {
       </Wrapper>,
     );
 
-    expect(screen.getByTestId("custom-fields-form-empty")).toBeTruthy();
+    const banner = screen.getByTestId("custom-fields-form-empty");
+    expect(banner).toBeTruthy();
     expect(screen.queryByTestId("custom-fields-form-section")).toBeNull();
+    // Translated + interpolated with the host entity name, not the raw key.
+    expect(banner.textContent).toBe('No custom fields defined for "component".');
+  });
+
+  test("save button renders the translated label, not the raw i18n key", () => {
+    mockedQueryRows = [
+      {
+        id: "f1",
+        entityName: "component",
+        fieldKey: "vendor",
+        type: "text",
+        required: false,
+        displayOrder: 1,
+      },
+    ];
+
+    render(
+      <Wrapper>
+        <CustomFieldsFormSection entityName="component" entityId="row-42" />
+      </Wrapper>,
+    );
+
+    const saveBtn = screen.getByTestId("custom-fields-form-save");
+    expect(saveBtn.textContent).toBe("Save custom fields");
   });
 });

package/src/custom-fields/web/client-plugin.tsx

@@ -14,6 +14,7 @@
 import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
 import { CUSTOM_FIELDS_FEATURE_NAME, CUSTOM_FIELDS_FORM_EXTENSION_NAME } from "../constants";
 import { CustomFieldsFormSection } from "./custom-fields-form-section";
+import { defaultTranslations } from "./i18n";
 
 export function customFieldsClient(): ClientFeatureDefinition {
   return {
@@ -21,5 +22,6 @@ export function customFieldsClient(): ClientFeatureDefinition {
     extensionSectionComponents: {
       [CUSTOM_FIELDS_FORM_EXTENSION_NAME]: CustomFieldsFormSection,
     },
+    translations: defaultTranslations,
   };
 }