@open-mercato/ui 0.4.6-develop-ce2a0728a5 → 0.4.6-develop-77fa3b7ed8

package/AGENTS.md

@@ -122,11 +122,20 @@ import { IconButton } from '@open-mercato/ui/primitives/icon-button'
 ## DataTable Guidelines
 
 - Use `DataTable` as the default list view.
+- DataTable extension spots include: `data-table:<tableId>:columns`, `:row-actions`, `:bulk-actions`, `:filters` (in addition to `:header`/`:footer`).
 - Populate `columns` with explicit renderers and set `meta.truncate`/`meta.maxWidth` where truncation is needed.
 - For filters, use `FilterBar`/`FilterOverlay` with async option loaders; keep `pageSize` at or below 100.
 - Support exports using `buildCrudExportUrl` and pass `exportOptions` to `DataTable`.
 - Use `RowActions` for per-row actions and include navigation via `onRowClick` or action links.
 - Keep table state (paging, sorting, filters, search) in component state and reload on scope changes.
+- Keep `extensionTableId` stable and deterministic; host pages should not derive it from transient UI state.
+- Render injected row actions and bulk actions through `RowActions`/bulk action handlers so injected actions follow the same guard and i18n behavior as built-ins.
+
+## CrudForm Field Injection (UMES Phase G)
+
+- `CrudForm` automatically resolves injected field widgets from `crud-form:<entityId>:fields`; always pass a stable `entityId`.
+- Keep host field/group IDs stable so injected fields can target groups deterministically across versions.
+- Use injected fields for cross-module form augmentation; keep core module fields in the base form config.
 
 ## Menu Injection (UMES Phase A/B)
 
@@ -158,6 +167,13 @@ import { IconButton } from '@open-mercato/ui/primitives/icon-button'
 ## Component Reuse
 
 - Prefer existing UI primitives and backend components from `@open-mercato/ui` before creating new ones.
+- For replacement-aware hosts, expose stable handle IDs (`page:*`, `data-table:*`, `crud-form:*`, `section:*`) so overrides are deterministic.
 - Reference @`.ai/specs/SPEC-001-2026-01-21-ui-reusable-components.md` for the reusable component catalog and usage patterns.
 - For dialogs and forms, keep the interaction model consistent: `Cmd/Ctrl + Enter` to submit, `Escape` to cancel.
 - Favor composable, data-first helpers (custom field helpers, CRUD helpers, filter utilities) over bespoke logic.
+
+## Component Replacement (UMES Phase H)
+
+- When a host surface is replacement-aware, resolve implementations via `useRegisteredComponent(handle, Fallback)` instead of hardcoded component references.
+- Prefer additive override modes (`wrapper`, `props`) before full `replace`; reserve `replace` for cases where compatibility is preserved.
+- Keep handle IDs stable and document them when introducing new replacement-aware surfaces.

package/dist/backend/CrudForm.js

@@ -65,12 +65,27 @@ import { useInjectionSpotEvents, InjectionSpot, useInjectionWidgets } from "./in
 import { dispatchBackendMutationError } from "./injection/mutationEvents.js";
 import { VersionHistoryAction } from "./version-history/VersionHistoryAction.js";
 import { parseBooleanWithDefault } from "@open-mercato/shared/lib/boolean";
+import { useInjectionDataWidgets } from "./injection/useInjectionDataWidgets.js";
+import { InjectedField } from "./injection/InjectedField.js";
+import { evaluateInjectedVisibility } from "./injection/visibility-utils.js";
+import { ComponentReplacementHandles } from "@open-mercato/shared/modules/widgets/component-registry";
 const EMPTY_OPTIONS = [];
 const FOCUSABLE_SELECTOR = '[data-crud-focus-target], input:not([type="hidden"]):not([disabled]), textarea:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
 const CRUDFORM_EXTENDED_EVENTS_ENABLED = parseBooleanWithDefault(
   process.env.NEXT_PUBLIC_OM_CRUDFORM_EXTENDED_EVENTS_ENABLED,
   true
 );
+function readByDotPath(source, path) {
+  if (!source || !path) return void 0;
+  if (Object.prototype.hasOwnProperty.call(source, path)) return source[path];
+  const segments = path.split(".").filter(Boolean);
+  let current = source;
+  for (const segment of segments) {
+    if (!current || typeof current !== "object" || Array.isArray(current)) return void 0;
+    current = current[segment];
+  }
+  return current;
+}
 const FIELDSET_ICON_COMPONENTS = {
   layers: Layers,
   tag: Tag,
@@ -135,7 +150,8 @@ function CrudForm({
   versionHistory,
   contentHeader,
   customFieldsetBindings,
-  injectionSpotId
+  injectionSpotId,
+  replacementHandle
 }) {
   React.useEffect(() => {
     loadGeneratedFieldRegistrations().catch(() => {
@@ -207,6 +223,11 @@ function CrudForm({
     }
     return void 0;
   }, [injectionSpotId, resolvedEntityIds]);
+  const resolvedReplacementHandle = React.useMemo(() => {
+    if (replacementHandle) return replacementHandle;
+    if (resolvedEntityIds.length) return ComponentReplacementHandles.crudForm(resolvedEntityIds[0].replace(/[:]+/g, "."));
+    return ComponentReplacementHandles.crudForm("unknown");
+  }, [replacementHandle, resolvedEntityIds]);
   const headerInjectionSpotId = resolvedInjectionSpotId ? `${resolvedInjectionSpotId}:header` : void 0;
   const recordId = React.useMemo(() => {
     const raw = values.id;
@@ -235,6 +256,9 @@ function CrudForm({
     context: injectionContext,
     triggerOnLoad: true
   });
+  const { widgets: injectedFieldWidgets } = useInjectionDataWidgets(
+    resolvedInjectionSpotId ? `${resolvedInjectionSpotId}:fields` : "__disabled__:fields"
+  );
   const { triggerEvent: triggerInjectionEvent } = useInjectionSpotEvents(resolvedInjectionSpotId ?? "", injectionWidgets);
   const extendedInjectionEventsEnabled = CRUDFORM_EXTENDED_EVENTS_ENABLED && Boolean(resolvedInjectionSpotId);
   const transformValidationErrors = React.useCallback(
@@ -745,12 +769,66 @@ function CrudForm({
     fieldsetsByEntity,
     resolvedEntityIds
   ]);
+  const injectedFieldDefinitions = React.useMemo(() => {
+    const definitions = [];
+    for (const widget of injectedFieldWidgets) {
+      if (!("fields" in widget)) continue;
+      for (const field of widget.fields ?? []) {
+        definitions.push(field);
+      }
+    }
+    return definitions;
+  }, [injectedFieldWidgets]);
+  const injectedFieldContext = React.useMemo(() => {
+    const recordValues = values;
+    const organizationId = typeof recordValues.organizationId === "string" ? recordValues.organizationId : null;
+    const tenantId = typeof recordValues.tenantId === "string" ? recordValues.tenantId : null;
+    const userId = typeof recordValues.userId === "string" ? recordValues.userId : null;
+    return {
+      organizationId,
+      tenantId,
+      userId,
+      record: recordValues
+    };
+  }, [values]);
+  const hiddenInjectedFieldIds = React.useMemo(() => {
+    const hidden = /* @__PURE__ */ new Set();
+    for (const definition of injectedFieldDefinitions) {
+      if (!evaluateInjectedVisibility(definition.visibleWhen, values, injectedFieldContext)) {
+        hidden.add(definition.id);
+      }
+    }
+    return hidden;
+  }, [injectedFieldContext, injectedFieldDefinitions, values]);
+  const injectedFieldIdSet = React.useMemo(
+    () => new Set(injectedFieldDefinitions.map((definition) => definition.id)),
+    [injectedFieldDefinitions]
+  );
+  const injectedCrudFields = React.useMemo(() => {
+    return injectedFieldDefinitions.map((definition) => ({
+      id: definition.id,
+      label: definition.label,
+      type: "custom",
+      readOnly: definition.readOnly,
+      component: ({ value, setValue: setValue2, values: formValues }) => /* @__PURE__ */ jsx(
+        InjectedField,
+        {
+          field: definition,
+          value,
+          onChange: (_, nextValue) => setValue2(nextValue),
+          context: injectedFieldContext,
+          formData: formValues ?? values
+        }
+      )
+    }));
+  }, [injectedFieldContext, injectedFieldDefinitions, values]);
   const allFields = React.useMemo(() => {
-    if (!cfFields.length) return fields;
-    const provided = new Set(fields.map((f) => f.id));
+    const base = [...fields, ...injectedCrudFields];
+    if (!cfFields.length) return base;
+    const provided = new Set(base.map((f) => f.id));
     const extras = cfFields.filter((f) => !provided.has(f.id));
-    return [...fields, ...extras];
-  }, [fields, cfFields]);
+    return [...base, ...extras];
+  }, [fields, injectedCrudFields, cfFields]);
   const fieldById = React.useMemo(() => {
     return new globalThis.Map(allFields.map((f) => [f.id, f]));
   }, [allFields]);
@@ -778,12 +856,31 @@ function CrudForm({
     pairs.sort((a, b) => b.priority - a.priority);
     return pairs.map((p) => p.group);
   }, [injectionWidgets, injectionContext, pending, setValues, values]);
-  const shouldAutoGroup = (!groups || groups.length === 0) && injectionGroupCards.length > 0;
+  const groupsWithInjectedFields = React.useMemo(() => {
+    if (!groups || groups.length === 0 || injectedFieldDefinitions.length === 0) return groups;
+    const cloned = groups.map((group) => ({ ...group, fields: [...group.fields ?? []] }));
+    const fallbackIndex = cloned.length - 1;
+    for (const definition of injectedFieldDefinitions) {
+      const targetIndex = cloned.findIndex((group) => group.id === definition.group);
+      const index = targetIndex >= 0 ? targetIndex : fallbackIndex;
+      if (targetIndex < 0 && process.env.NODE_ENV !== "production") {
+        console.warn(`[CrudForm] Injected field "${definition.id}" targets group "${definition.group}" which does not exist. Appended to last group.`);
+      }
+      if (index < 0) continue;
+      const fieldEntries = cloned[index].fields ?? [];
+      if (!fieldEntries.some((entry) => typeof entry === "string" && entry === definition.id)) {
+        fieldEntries.push(definition.id);
+      }
+      cloned[index].fields = fieldEntries;
+    }
+    return cloned;
+  }, [groups, injectedFieldDefinitions]);
+  const shouldAutoGroup = (!groupsWithInjectedFields || groupsWithInjectedFields.length === 0) && injectionGroupCards.length > 0;
   const resolvedGroupsForLayout = React.useMemo(() => {
-    const baseGroups = groups && groups.length ? groups : [];
+    const baseGroups = groupsWithInjectedFields && groupsWithInjectedFields.length ? groupsWithInjectedFields : [];
     const autoGroup = shouldAutoGroup ? [{ id: "__auto-fields__", fields: allFields }] : [];
     return [...baseGroups.length ? baseGroups : autoGroup, ...injectionGroupCards];
-  }, [allFields, groups, injectionGroupCards, shouldAutoGroup]);
+  }, [allFields, groupsWithInjectedFields, injectionGroupCards, shouldAutoGroup]);
   const useGroupedLayout = resolvedGroupsForLayout.length > 0;
   const stackedInjectionWidgets = React.useMemo(
     () => (injectionWidgets ?? []).filter((widget) => (widget.placement?.kind ?? "stack") === "stack"),
@@ -977,7 +1074,16 @@ function CrudForm({
     initialValuesSnapshotRef.current = snapshot;
     let mergedValues = null;
     setValues((prev) => {
-      mergedValues = { ...prev, ...initialValues };
+      const merged = { ...prev, ...initialValues };
+      for (const definition of injectedFieldDefinitions) {
+        if (merged[definition.id] !== void 0) continue;
+        const extracted = readByDotPath(initialValues, definition.id);
+        if (extracted !== void 0) {
+          ;
+          merged[definition.id] = extracted;
+        }
+      }
+      mergedValues = merged;
       return mergedValues;
     });
     if (!extendedInjectionEventsEnabled || !mergedValues) return;
@@ -1000,7 +1106,7 @@ function CrudForm({
     return () => {
       cancelled = true;
     };
-  }, [extendedInjectionEventsEnabled, initialValues, triggerInjectionEvent]);
+  }, [extendedInjectionEventsEnabled, initialValues, injectedFieldDefinitions, triggerInjectionEvent]);
   const buildFieldsetEditorHref = React.useCallback(
     (includeViewParam) => {
       if (!fieldsetEditorTarget) return null;
@@ -1044,6 +1150,7 @@ function CrudForm({
     for (const field of allFields) {
       if (!field.required) continue;
       if (field.disabled) continue;
+      if (hiddenInjectedFieldIds.has(field.id)) continue;
       const v = values[field.id];
       const isArray = Array.isArray(v);
       const isString = typeof v === "string";
@@ -1098,9 +1205,17 @@ function CrudForm({
       } catch {
       }
     }
+    const widgetValues = { ...values };
+    for (const hiddenId of hiddenInjectedFieldIds) {
+      delete widgetValues[hiddenId];
+    }
+    const coreValues = { ...widgetValues };
+    for (const injectedId of injectedFieldIdSet) {
+      delete coreValues[injectedId];
+    }
     let parsedValues;
     if (schema) {
-      const res = schema.safeParse(values);
+      const res = schema.safeParse(coreValues);
       if (!res.success) {
         const fieldErrors = {};
         res.error.issues.forEach((issue) => {
@@ -1116,14 +1231,20 @@ function CrudForm({
       }
       parsedValues = res.data;
     } else {
-      parsedValues = values;
+      parsedValues = coreValues;
     }
-    let submitValues = parsedValues;
+    let submitValues = widgetValues;
+    let coreSubmitValues = parsedValues;
     if (extendedInjectionEventsEnabled) {
       try {
         const result = await triggerInjectionEvent("transformFormData", submitValues, injectionContext);
         if (result.data) {
           submitValues = result.data;
+          const projectedCoreValues = { ...result.data };
+          for (const injectedId of injectedFieldIdSet) {
+            delete projectedCoreValues[injectedId];
+          }
+          coreSubmitValues = schema ? schema.parse(projectedCoreValues) : projectedCoreValues;
         }
       } catch (err) {
         console.error("[CrudForm] Error in transformFormData:", err);
@@ -1181,10 +1302,10 @@ function CrudForm({
     try {
       if (injectionRequestHeaders && Object.keys(injectionRequestHeaders).length > 0) {
         await withScopedApiRequestHeaders(injectionRequestHeaders, async () => {
-          await onSubmit?.(submitValues);
+          await onSubmit?.(coreSubmitValues);
         });
       } else {
-        await onSubmit?.(submitValues);
+        await onSubmit?.(coreSubmitValues);
       }
       if (resolvedInjectionSpotId) {
         try {
@@ -1573,7 +1694,7 @@ function CrudForm({
     const col1Content = renderGroupedCards(col1);
     const col2Content = renderGroupedCards(col2);
     const hasSecondaryColumn = col2Content.length > 0;
-    return /* @__PURE__ */ jsxs("div", { className: "space-y-4", ref: rootRef, children: [
+    return /* @__PURE__ */ jsxs("div", { className: "space-y-4", ref: rootRef, "data-component-handle": resolvedReplacementHandle, children: [
       !embedded ? /* @__PURE__ */ jsx(
         FormHeader,
         {
@@ -1646,7 +1767,7 @@ function CrudForm({
       ConfirmDialogElement
     ] });
   }
-  return /* @__PURE__ */ jsxs("div", { className: "space-y-4", ref: rootRef, children: [
+  return /* @__PURE__ */ jsxs("div", { className: "space-y-4", ref: rootRef, "data-component-handle": resolvedReplacementHandle, children: [
     !embedded ? /* @__PURE__ */ jsx(
       FormHeader,
       {