@pattern-stack/codegen 0.20.2 → 0.22.0

package/CHANGELOG.md

@@ -4,6 +4,54 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.21.0] — 2026-06-06
+
+**FieldMeta enrichment (ADR-040, Phase A of type-aware rendering).** The
+frontend emitter's per-entity field metadata now carries enough vocabulary for
+consumers to build metadata-driven rendering (the swe-brain renderer kit
+consumes this in its Phase B). All additive.
+
+### Added
+
+- **Full `ui_*` hint passthrough.** `ui_group`, `ui_visible`, `ui_placeholder`,
+  `ui_help`, and `ui_format` were accepted by the schema but dropped before
+  emission. They now survive parser → derivation → emitted `FieldMeta`
+  (`group` / `visible` / `placeholder` / `help` / `format`). `format` was
+  previously only ever the hardcoded timestamp `{ dateFormat: 'relative' }`;
+  authored `ui_format` now passes through.
+- **Key-field curation (qField parity).** New YAML keys `ui_key_field` +
+  `ui_key_field_order` surface as `isKeyField` / `keyFieldOrder` on the row
+  (the qField / EAV `field_definitions` names — one vocabulary, multiple
+  homes), and `<camel>Metadata` gains `keyFields`: the ordered curated
+  field-name list (sorted by `keyFieldOrder`, declaration order for ties) that
+  drives card/preview field selection.
+- **Family/behavior common-field bundles** (timestamps precedent): the
+  `soft_delete` behavior now contributes a `deletedAt` row
+  (datetime / tertiary / relative); entities whose declared fields carry the
+  synced/integrated shape (both `external_id` AND `provider`) get
+  `group: 'external_sync'` defaulted onto those fields (plus
+  `provider_metadata` when present) — a derivation default only, authored
+  `ui_group` always wins. Behavior-contributed columns (not in the parsed
+  field map) still get no rows: the emitter never emits a row for a column it
+  cannot see.
+- **EAV `data_type` → `FieldType` contract.** `EAV_DATA_TYPE_TO_FIELD_TYPE`
+  (`string→text, integer/decimal→number, boolean→boolean, date→date,
+  datetime→datetime, json→json, reference→reference, picklist→enum,
+  multipicklist→enum`; multi-select rendering is consumer-side) is exported
+  from the package root AND emitted into every generated
+  `fields/field-meta.ts`, rendered from the same source object so the copies
+  cannot drift. See ADR-040 for the convergence story
+  (qField/CatalogField ↔ codegen FieldMeta ↔ EAV `field_definitions`).
+
+### Tests
+
+- emit-fields suite: hint passthrough (incl. author-override-beats-default and
+  string escaping), key-field curation + `keyFields` ordering, soft_delete /
+  external-sync bundles, EAV contract completeness vs the emitted copy.
+- Frontend golden fixtures now exercise the new surface; the snapshot locks
+  curation ordering (`first_name` before `email` despite declaration order),
+  the `deletedAt` bundle, and the `external_sync` group default.
+
 ## [0.20.2] — 2026-06-06
 
 Two consumer-found fixes (dogfooding swe-brain on 0.20.1).

package/README.md

@@ -209,11 +209,15 @@ frontend:
     columnMapperNeedsCall: true      # call the mapper (fn()) vs reference (fn)
     apiBaseUrlImport: null   # when set, import API_BASE_URL from it as baseURL
     apiUrl: /api             # REST base path when no apiBaseUrlImport
+  fields:
+    textareaThreshold: 500  # string→textarea cutoff (strict >); null DISABLES
 ```
 
 `null`-disables convention: an **absent** `auth.function` defaults to
 `getAuthorizationHeader`; an **explicit `null`** disables it entirely (no header
-lines emitted). Likewise `sync.columnMapper: null` omits the Electric mapper.
+lines emitted). Likewise `sync.columnMapper: null` omits the Electric mapper, and
+`fields.textareaThreshold: null` disables the string→textarea heuristic entirely
+(bounded strings always render as `text` unless the author sets `ui_type: textarea`).
 
 ### Per-entity sync mode (`entity.sync`)
 

package/dist/{chunk-BKP72EDW.js → chunk-6DQEIXYU.js}

@@ -1,3 +1,6 @@
+import {
+  MemoryJobOrchestrator
+} from "./chunk-VQOAATIG.js";
 import {
   DrizzleJobRunService
 } from "./chunk-3VEVGL74.js";
@@ -7,6 +10,12 @@ import {
 import {
   DrizzleJobStepService
 } from "./chunk-DV4RV2DC.js";
+import {
+  MemoryJobStepService
+} from "./chunk-PNZSGAB2.js";
+import {
+  MemoryJobStore
+} from "./chunk-SNQ3TOWP.js";
 import {
   BULLMQ_CONNECTION,
   BULLMQ_RESOLVED_CONFIG,
@@ -15,15 +24,6 @@ import {
 import {
   DrizzleJobOrchestrator
 } from "./chunk-E6PLM6QG.js";
-import {
-  MemoryJobOrchestrator
-} from "./chunk-VQOAATIG.js";
-import {
-  MemoryJobStepService
-} from "./chunk-PNZSGAB2.js";
-import {
-  MemoryJobStore
-} from "./chunk-SNQ3TOWP.js";
 import {
   JOBS_LISTEN_NOTIFY,
   JOBS_MULTI_TENANT,
@@ -114,4 +114,4 @@ JobsDomainModule = __decorateClass([
 export {
   JobsDomainModule
 };
-//# sourceMappingURL=chunk-BKP72EDW.js.map
+//# sourceMappingURL=chunk-6DQEIXYU.js.map

package/dist/{chunk-KK5A7B2T.js → chunk-6ECCJVYW.js}

@@ -120,7 +120,12 @@ var UiMetadataSchema = z.object({
   ui_visible: z.boolean().optional(),
   ui_placeholder: z.string().optional(),
   ui_help: z.string().optional(),
-  ui_format: z.record(z.unknown()).optional()
+  ui_format: z.record(z.unknown()).optional(),
+  // Key-field curation (ADR-040): curated/displayed fields that drive card &
+  // preview surfaces. Names mirror qField / EAV `field_definitions`
+  // (`isKeyField` / `keyFieldOrder`) — one metadata vocabulary, multiple homes.
+  ui_key_field: z.boolean().optional(),
+  ui_key_field_order: z.number().optional()
 });
 var BaseFieldSchema = z.object({
   type: FieldTypeSchema,
@@ -1371,6 +1376,22 @@ function detectYamlType(filePath) {
 }
 
 // src/parser/load-entities.ts
+function parseUiMetadata(fieldDef) {
+  return {
+    label: fieldDef.ui_label,
+    type: fieldDef.ui_type,
+    importance: fieldDef.ui_importance,
+    group: fieldDef.ui_group,
+    sortable: fieldDef.ui_sortable,
+    filterable: fieldDef.ui_filterable,
+    visible: fieldDef.ui_visible,
+    placeholder: fieldDef.ui_placeholder,
+    help: fieldDef.ui_help,
+    format: fieldDef.ui_format,
+    keyField: fieldDef.ui_key_field,
+    keyFieldOrder: fieldDef.ui_key_field_order
+  };
+}
 function transformToEntity(result) {
   const { definition, filePath } = result;
   const queries = definition.queries?.filter((q) => "by" in q).map((q) => ({
@@ -1413,15 +1434,7 @@ function transformToEntity(result) {
         min: fieldDef.min,
         max: fieldDef.max
       },
-      ui: {
-        label: fieldDef.ui_label,
-        type: fieldDef.ui_type,
-        importance: fieldDef.ui_importance,
-        group: fieldDef.ui_group,
-        sortable: fieldDef.ui_sortable,
-        filterable: fieldDef.ui_filterable,
-        visible: fieldDef.ui_visible
-      }
+      ui: parseUiMetadata(fieldDef)
     };
     entity.fields.set(name, field);
   }
@@ -1614,15 +1627,7 @@ function transformToRelationshipDefinition(result) {
           min: fieldDef.min,
           max: fieldDef.max
         },
-        ui: {
-          label: fieldDef.ui_label,
-          type: fieldDef.ui_type,
-          importance: fieldDef.ui_importance,
-          group: fieldDef.ui_group,
-          sortable: fieldDef.ui_sortable,
-          filterable: fieldDef.ui_filterable,
-          visible: fieldDef.ui_visible
-        }
+        ui: parseUiMetadata(fieldDef)
       };
       fields.set(name, field);
     }
@@ -4066,6 +4071,111 @@ registerLibraryPattern(KnowledgePattern);
 registerLibraryPattern(MetadataPattern);
 registerLibraryPattern(JunctionPattern);
 
+// src/emitters/frontend/field-meta.ts
+var DEFAULT_TEXTAREA_THRESHOLD = 500;
+var CAMEL = (s) => s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+function formatLabel(fieldName) {
+  return fieldName.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+function inferUiType(field, opts = {}) {
+  if (field.ui.type) return field.ui.type;
+  if (Array.isArray(field.choices) && field.choices.length > 0) return "enum";
+  if (field.foreignKey) return "reference";
+  const nameLower = field.name.toLowerCase();
+  if (nameLower.includes("email")) return "email";
+  if (nameLower.includes("url") || nameLower.includes("website")) return "url";
+  if (nameLower.includes("password")) return "password";
+  if (nameLower.includes("price") || nameLower.includes("amount") || nameLower.includes("cost") || nameLower.includes("value") || nameLower.includes("revenue")) {
+    return "money";
+  }
+  if (nameLower.includes("percent") || nameLower.includes("rate")) {
+    return "percentage";
+  }
+  const threshold = opts.textareaThreshold === void 0 ? DEFAULT_TEXTAREA_THRESHOLD : opts.textareaThreshold;
+  switch (field.type) {
+    case "string":
+      return threshold !== null && field.constraints.maxLength && field.constraints.maxLength > threshold ? "textarea" : "text";
+    case "integer":
+    case "decimal":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "uuid":
+      return "text";
+    case "date":
+      return "date";
+    case "datetime":
+      return "datetime";
+    case "json":
+      return "json";
+    default:
+      return "text";
+  }
+}
+function inferUiImportance(field) {
+  if (field.ui.importance) return field.ui.importance;
+  const nameLower = field.name.toLowerCase();
+  if (["id", "created_at", "updated_at", "deleted_at"].includes(nameLower)) {
+    return "tertiary";
+  }
+  if (field.foreignKey && nameLower.endsWith("_id")) return "secondary";
+  if (field.required) return "primary";
+  if (nameLower.includes("name") || nameLower.includes("title")) return "primary";
+  return "secondary";
+}
+function isEntityRefField(field) {
+  if (field.type === "entity_ref") return true;
+  return field.name.endsWith("_entity_type") || field.name.endsWith("_entity_id");
+}
+function deriveFieldMeta(field, defaults = {}, opts = {}) {
+  const hasChoices = Array.isArray(field.choices) && field.choices.length > 0;
+  const meta = {
+    field: CAMEL(field.name),
+    label: field.ui.label ?? formatLabel(field.name),
+    type: inferUiType(field, opts),
+    importance: inferUiImportance(field),
+    sortable: field.ui.sortable ?? false,
+    filterable: field.ui.filterable ?? false
+  };
+  const group = field.ui.group ?? defaults.group;
+  if (group !== void 0) meta.group = group;
+  if (field.ui.visible !== void 0) meta.visible = field.ui.visible;
+  if (field.ui.placeholder !== void 0) meta.placeholder = field.ui.placeholder;
+  if (field.ui.help !== void 0) meta.help = field.ui.help;
+  if (field.ui.format !== void 0) meta.format = field.ui.format;
+  if (hasChoices) meta.choices = field.choices;
+  if (field.foreignKey) meta.reference = field.foreignKey.table;
+  if (field.ui.keyField) {
+    meta.isKeyField = true;
+    if (field.ui.keyFieldOrder !== void 0) {
+      meta.keyFieldOrder = field.ui.keyFieldOrder;
+    }
+  }
+  return meta;
+}
+var EXTERNAL_SYNC_GROUP = "external_sync";
+var EXTERNAL_SYNC_FIELDS = /* @__PURE__ */ new Set([
+  "external_id",
+  "provider",
+  "provider_metadata"
+]);
+function hasExternalSyncShape(fieldNames) {
+  const names = new Set(fieldNames);
+  return names.has("external_id") && names.has("provider");
+}
+var EAV_DATA_TYPE_TO_FIELD_TYPE = {
+  string: "text",
+  integer: "number",
+  decimal: "number",
+  boolean: "boolean",
+  date: "date",
+  datetime: "datetime",
+  json: "json",
+  reference: "reference",
+  picklist: "enum",
+  multipicklist: "enum"
+};
+
 // src/index.ts
 async function analyzeDomain(entitiesDir, relationshipsOrOptions) {
   const opts = typeof relationshipsOrOptions === "string" ? { relationshipsDir: relationshipsOrOptions } : relationshipsOrOptions ?? {};
@@ -4186,7 +4296,13 @@ export {
   KnowledgePattern,
   MetadataPattern,
   IntegratedPattern,
+  isEntityRefField,
+  deriveFieldMeta,
+  EXTERNAL_SYNC_GROUP,
+  EXTERNAL_SYNC_FIELDS,
+  hasExternalSyncShape,
+  EAV_DATA_TYPE_TO_FIELD_TYPE,
   analyzeDomain,
   validateEntities
 };
-//# sourceMappingURL=chunk-KK5A7B2T.js.map
+//# sourceMappingURL=chunk-6ECCJVYW.js.map