feat(web): P3.1 dynamic custom field renderer (DynamicExtFields)

Tier 1 customization comes alive in the SPA: custom fields declared in YAML metadata now render automatically in create forms without any compile-time knowledge of the field. New component: DynamicExtFields - Fetches custom field declarations from the existing /api/v1/_meta/metadata/custom-fields/{entityName} endpoint - Renders one input per declared field, type-matched: string → text, integer → number (step=1), decimal/money/ quantity → number (step=0.01), boolean → checkbox, date → date picker, dateTime → datetime-local, enum → select dropdown, uuid → text - Labels resolve from labelTranslations using the active locale (i18n integration) - Required fields show a red asterisk - Values are collected in the ext map and sent with the create request Wired into: CreateItemPage (entityName="Item"), CreatePartnerPage (entityName="Partner"). Both now show a "Custom fields" section below the static fields when the entity has custom field declarations in metadata. No new backend code — the existing /api/v1/_meta/metadata/ custom-fields endpoint already returns exactly the shape the component needs. This is P3.1: the runtime form renderer for Tier 1 customization.

feat(web): P3.1 dynamic custom field renderer (DynamicExtFields)
Tier 1 customization comes alive in the SPA: custom fields declared in YAML metadata now render automatically in create forms without any compile-time knowledge of the field. New component: DynamicExtFields - Fetches custom field declarations from the existing /api/v1/_meta/metadata/custom-fields/{entityName} endpoint - Renders one input per declared field, type-matched: string → text, integer → number (step=1), decimal/money/ quantity → number (step=0.01), boolean → checkbox, date → date picker, dateTime → datetime-local, enum → select dropdown, uuid → text - Labels resolve from labelTranslations using the active locale (i18n integration) - Required fields show a red asterisk - Values are collected in the ext map and sent with the create request Wired into: CreateItemPage (entityName="Item"), CreatePartnerPage (entityName="Partner"). Both now show a "Custom fields" section below the static fields when the entity has custom field declarations in metadata. No new backend code — the existing /api/v1/_meta/metadata/ custom-fields endpoint already returns exactly the shape the component needs. This is P3.1: the runtime form renderer for Tier 1 customization.
zichun
1 parent d8856b6a
Showing 3 changed files with 185 additions and 2 deletions
web/src/components/DynamicExtFields.tsx
web/src/pages/CreateItemPage.tsx
web/src/pages/CreatePartnerPage.tsx
+// Dynamic form fields for Tier 1 custom fields (the JSONB `ext` column).
+//
+// Fetches the custom field declarations for an entity from
+// /api/v1/_meta/metadata/custom-fields/{entityName} and renders
+// one input per declared field. The SPA doesn't need to know the
+// entity's custom fields at compile time — a business analyst
+// declares a field in YAML metadata, the framework validates it
+// on every save, and this component renders it automatically.
+//
+// This is P3.1 — the runtime form renderer for Tier 1 customization.
+
+import { useEffect, useState } from 'react'
+import { useLocale } from '@/i18n/LocaleContext'
+
+interface CustomFieldDecl {
+  key: string
+  targetEntity: string
+  type: { kind: string; maxLength?: number; precision?: number; scale?: number; allowedValues?: string[] }
+  required: boolean
+  labelTranslations: Record<string, string>
+}
+
+interface Props {
+  entityName: string
+  values: Record<string, unknown>
+  onChange: (key: string, value: unknown) => void
+}
+
+export function DynamicExtFields({ entityName, values, onChange }: Props) {
+  const [fields, setFields] = useState<CustomFieldDecl[]>([])
+  const { locale } = useLocale()
+
+  useEffect(() => {
+    fetch(`/api/v1/_meta/metadata/custom-fields/${entityName}`)
+      .then((r) => r.json())
+      .then((data: CustomFieldDecl[]) => setFields(data))
+      .catch(() => setFields([]))
+  }, [entityName])
+
+  if (fields.length === 0) return null
+
+  const label = (f: CustomFieldDecl): string => {
+    const langKey = locale.replace('-', '_').toLowerCase()
+    return (
+      f.labelTranslations[locale] ??
+      f.labelTranslations[langKey] ??
+      f.labelTranslations['en'] ??
+      f.labelTranslations['en-US'] ??
+      f.key
+    )
+  }
+
+  return (
+    <div className="border-t border-slate-200 pt-4 mt-4">
+      <div className="text-xs font-semibold uppercase tracking-wide text-slate-400 mb-3">
+        Custom fields
+      </div>
+      <div className="grid grid-cols-1 gap-3 sm:grid-cols-2">
+        {fields.map((f) => {
+          const val = values[f.key]
+          return (
+            <div key={f.key}>
+              <label className="block text-sm font-medium text-slate-700">
+                {label(f)}
+                {f.required && <span className="text-rose-500 ml-0.5">*</span>}
+              </label>
+              {renderInput(f, val, (v) => onChange(f.key, v))}
+            </div>
+          )
+        })}
+      </div>
+    </div>
+  )
+}
+
+function renderInput(
+  f: CustomFieldDecl,
+  value: unknown,
+  onChange: (v: unknown) => void,
+) {
+  const cls = 'mt-1 w-full rounded-md border border-slate-300 px-3 py-2 text-sm'
+
+  switch (f.type.kind) {
+    case 'boolean':
+      return (
+        <input
+          type="checkbox"
+          checked={Boolean(value)}
+          onChange={(e) => onChange(e.target.checked)}
+          className="mt-2 rounded border-slate-300"
+        />
+      )
+    case 'integer':
+      return (
+        <input
+          type="number"
+          step="1"
+          value={value != null ? String(value) : ''}
+          onChange={(e) => onChange(e.target.value ? Number(e.target.value) : null)}
+          required={f.required}
+          className={cls}
+        />
+      )
+    case 'decimal':
+    case 'money':
+    case 'quantity':
+      return (
+        <input
+          type="number"
+          step="0.01"
+          value={value != null ? String(value) : ''}
+          onChange={(e) => onChange(e.target.value ? Number(e.target.value) : null)}
+          required={f.required}
+          className={cls}
+        />
+      )
+    case 'date':
+      return (
+        <input
+          type="date"
+          value={value != null ? String(value) : ''}
+          onChange={(e) => onChange(e.target.value || null)}
+          required={f.required}
+          className={cls}
+        />
+      )
+    case 'dateTime':
+      return (
+        <input
+          type="datetime-local"
+          value={value != null ? String(value) : ''}
+          onChange={(e) => onChange(e.target.value || null)}
+          required={f.required}
+          className={cls}
+        />
+      )
+    case 'enum':
+      return (
+        <select
+          value={value != null ? String(value) : ''}
+          onChange={(e) => onChange(e.target.value || null)}
+          required={f.required}
+          className={cls}
+        >
+          <option value="">—</option>
+          {f.type.allowedValues?.map((v) => (
+            <option key={v} value={v}>{v}</option>
+          ))}
+        </select>
+      )
+    case 'string':
+    case 'uuid':
+    default:
+      return (
+        <input
+          type="text"
+          maxLength={f.type.maxLength}
+          value={value != null ? String(value) : ''}
+          onChange={(e) => onChange(e.target.value || null)}
+          required={f.required}
+          className={cls}
+        />
+      )
+  }
+}
@@ -4,6 +4,7 @@ import { catalog } from &#39;@/api/client&#39;
 import type { Uom } from '@/types/api'
 import { PageHeader } from '@/components/PageHeader'
 import { ErrorBox } from '@/components/ErrorBox'
+import { DynamicExtFields } from '@/components/DynamicExtFields'
  
 const ITEM_TYPES = ['GOOD', 'SERVICE', 'DIGITAL'] as const
  
@@ -15,6 +16,7 @@ export function CreateItemPage() {
   const [itemType, setItemType] = useState<string>('GOOD')
   const [baseUomCode, setBaseUomCode] = useState('')
   const [uoms, setUoms] = useState<Uom[]>([])
+  const [ext, setExt] = useState<Record<string, unknown>>({})
   const [submitting, setSubmitting] = useState(false)
   const [error, setError] = useState<Error | null>(null)
  
@@ -30,10 +32,12 @@ export function CreateItemPage() {
     setError(null)
     setSubmitting(true)
     try {
+      const extPayload = Object.keys(ext).length > 0 ? ext : undefined
       await catalog.createItem({
         code, name, itemType, baseUomCode,
         description: description || null,
-      })
+        ...(extPayload ? { ext: extPayload } : {}),
+      } as Parameters<typeof catalog.createItem>[0])
       navigate('/items')
     } catch (err: unknown) {
       setError(err instanceof Error ? err : new Error(String(err)))
@@ -81,6 +85,11 @@ export function CreateItemPage() {
           <input type="text" value={description} onChange={(e) => setDescription(e.target.value)}
             className="mt-1 w-full rounded-md border border-slate-300 px-3 py-2 text-sm" />
         </div>
+        <DynamicExtFields
+          entityName="Item"
+          values={ext}
+          onChange={(k, v) => setExt((prev) => ({ ...prev, [k]: v }))}
+        />
         {error && <ErrorBox error={error} />}
         <button type="submit" className="btn-primary" disabled={submitting}>
           {submitting ? 'Creating...' : 'Create Item'}
@@ -3,6 +3,7 @@ import { useNavigate } from &#39;react-router-dom&#39;
 import { partners } from '@/api/client'
 import { PageHeader } from '@/components/PageHeader'
 import { ErrorBox } from '@/components/ErrorBox'
+import { DynamicExtFields } from '@/components/DynamicExtFields'
  
 const PARTNER_TYPES = ['CUSTOMER', 'SUPPLIER', 'BOTH'] as const
  
@@ -13,6 +14,7 @@ export function CreatePartnerPage() {
   const [type, setType] = useState<string>('CUSTOMER')
   const [email, setEmail] = useState('')
   const [phone, setPhone] = useState('')
+  const [ext, setExt] = useState<Record<string, unknown>>({})
   const [submitting, setSubmitting] = useState(false)
   const [error, setError] = useState<Error | null>(null)
  
@@ -21,11 +23,13 @@ export function CreatePartnerPage() {
     setError(null)
     setSubmitting(true)
     try {
+      const extPayload = Object.keys(ext).length > 0 ? ext : undefined
       await partners.create({
         code, name, type,
         email: email || null,
         phone: phone || null,
-      })
+        ...(extPayload ? { ext: extPayload } : {}),
+      } as Parameters<typeof partners.create>[0])
       navigate('/partners')
     } catch (err: unknown) {
       setError(err instanceof Error ? err : new Error(String(err)))
@@ -71,6 +75,11 @@ export function CreatePartnerPage() {
               className="mt-1 w-full rounded-md border border-slate-300 px-3 py-2 text-sm" />
           </div>
         </div>
+        <DynamicExtFields
+          entityName="Partner"
+          values={ext}
+          onChange={(k, v) => setExt((prev) => ({ ...prev, [k]: v }))}
+        />
         {error && <ErrorBox error={error} />}
         <button type="submit" className="btn-primary" disabled={submitting}>
           {submitting ? 'Creating...' : 'Create Partner'}