@asteby/metacore-runtime-react 9.1.0 → 9.2.0

package/dist/use-org-config-bridge.d.ts

@@ -0,0 +1,28 @@
+export interface OrgConfigBridge {
+    /** Resolves a `$org.<key>` reference (or plain key) to a literal id. */
+    resolveValidator: (refOrKey: string) => string | null;
+    /** When true the app actually has a provider mounted. */
+    available: boolean;
+}
+/**
+ * Apps that consume `runtime-react` AND `@asteby/metacore-app-providers`
+ * call this once near the root (typically inside the OrgConfigProvider
+ * children) so the SDK reads the same resolver. Hosts without an org
+ * provider can ignore this entirely; the SDK's null bridge keeps every
+ * call returning `null` so $org.<key> tokens stay verbatim in the form
+ * — same fallback the kernel uses for unresolved references.
+ */
+export declare function setOrgConfigBridge(bridge: OrgConfigBridge | null): void;
+/**
+ * Returns the active bridge. Pure read — no React hook so it can be
+ * called from non-component code (zod schema builders, helpers).
+ */
+export declare function getOrgConfigBridge(): OrgConfigBridge;
+/**
+ * Resolves a Validation token into the validator identifier the SDK
+ * should apply. Returns the resolved literal when the org config knows
+ * the key, or the original token when it doesn't (so apps can decide).
+ * Plain literals (no `$org.` prefix) pass through.
+ */
+export declare function resolveValidatorToken(token: string | undefined | null): string | null;
+//# sourceMappingURL=use-org-config-bridge.d.ts.map

package/dist/use-org-config-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-org-config-bridge.d.ts","sourceRoot":"","sources":["../src/use-org-config-bridge.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,eAAe;IAC5B,wEAAwE;IACxE,gBAAgB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAA;IACrD,yDAAyD;IACzD,SAAS,EAAE,OAAO,CAAA;CACrB;AASD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,QAEhE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAKrF"}

package/dist/use-org-config-bridge.js

@@ -0,0 +1,50 @@
+// Bridge to `useOrgConfig` from `@asteby/metacore-app-providers` without
+// adding it as a hard dependency of `runtime-react`. The provider package
+// is a peer; in apps that mount it the hook returns the live config, in
+// apps that don't the SDK falls through to a no-op shim that resolves
+// every reference to null. Forms then leave $org.<key> tokens in place
+// rather than crashing — the operator notices the missing config when
+// the validator fails to fire, not at app boot.
+//
+// Why a bridge: runtime-react cannot import `@asteby/metacore-app-providers`
+// directly without inverting the dependency graph (app-providers depends
+// on runtime-react today via peerDependenciesMeta). The shim shape
+// matches `OrgConfigContextValue` so DynamicForm code reads through one
+// stable interface regardless of provider mount.
+const NULL_BRIDGE = {
+    resolveValidator: () => null,
+    available: false,
+};
+let activeBridge = NULL_BRIDGE;
+/**
+ * Apps that consume `runtime-react` AND `@asteby/metacore-app-providers`
+ * call this once near the root (typically inside the OrgConfigProvider
+ * children) so the SDK reads the same resolver. Hosts without an org
+ * provider can ignore this entirely; the SDK's null bridge keeps every
+ * call returning `null` so $org.<key> tokens stay verbatim in the form
+ * — same fallback the kernel uses for unresolved references.
+ */
+export function setOrgConfigBridge(bridge) {
+    activeBridge = bridge ?? NULL_BRIDGE;
+}
+/**
+ * Returns the active bridge. Pure read — no React hook so it can be
+ * called from non-component code (zod schema builders, helpers).
+ */
+export function getOrgConfigBridge() {
+    return activeBridge;
+}
+/**
+ * Resolves a Validation token into the validator identifier the SDK
+ * should apply. Returns the resolved literal when the org config knows
+ * the key, or the original token when it doesn't (so apps can decide).
+ * Plain literals (no `$org.` prefix) pass through.
+ */
+export function resolveValidatorToken(token) {
+    if (!token)
+        return null;
+    if (!token.startsWith('$org.'))
+        return token;
+    const resolved = activeBridge.resolveValidator(token);
+    return resolved ?? token;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteby/metacore-runtime-react",
-  "version": "9.1.0",
+  "version": "9.2.0",
   "description": "React runtime for metacore hosts — renders addon contributions dynamically",
   "repository": {
     "type": "git",
@@ -57,7 +57,7 @@
     "react-i18next": "^17.0.0",
     "sonner": "^2.0.0",
     "tsx": "^4.21.0",
-    "typescript": "^5.6.0",
+    "typescript": "^6.0.0",
     "vitest": "^4.0.0",
     "zustand": "^5.0.0",
     "@asteby/metacore-sdk": "2.4.0",

package/src/__tests__/use-options-resolver.test.ts

@@ -0,0 +1,127 @@
+import { afterEach, describe, it, expect, vi } from 'vitest'
+import { projectOption } from '../use-options-resolver'
+import {
+    resolveValidatorToken,
+    setOrgConfigBridge,
+} from '../use-org-config-bridge'
+
+// `useOptionsResolver` itself is a React hook and would need jsdom +
+// react-test-renderer to exercise end-to-end. The bridge tests here
+// pin down the projection layer (the only impure shape conversion the
+// hook performs) so consumers can rely on the v0.9.0 envelope reading
+// without spinning up a renderer.
+
+describe('projectOption', () => {
+    it('mirrors id into value and label into name when missing', () => {
+        const out = projectOption({ id: 'abc', label: 'Hello' })
+        expect(out.id).toBe('abc')
+        expect(out.value).toBe('abc')
+        expect(out.label).toBe('Hello')
+        expect(out.name).toBe('Hello')
+    })
+
+    it('preserves explicit value and name when provided', () => {
+        const out = projectOption({ id: 1, value: 'one', label: 'L', name: 'N' })
+        expect(out.value).toBe('one')
+        expect(out.name).toBe('N')
+    })
+
+    it('coerces label to string from numeric id when none provided', () => {
+        const out = projectOption({ id: 42 })
+        expect(out.label).toBe('42')
+        expect(out.name).toBe('42')
+    })
+
+    it('preserves optional decoration fields', () => {
+        const out = projectOption({
+            id: 'x', label: 'X',
+            description: 'desc', image: '/a.png',
+            color: '#fff', icon: 'IconStar',
+        })
+        expect(out.description).toBe('desc')
+        expect(out.image).toBe('/a.png')
+        expect(out.color).toBe('#fff')
+        expect(out.icon).toBe('IconStar')
+    })
+
+    it('null-safes missing optionals to null', () => {
+        const out = projectOption({ id: 'x', label: 'X' })
+        expect(out.description).toBeNull()
+        expect(out.image).toBeNull()
+        expect(out.color).toBeNull()
+        expect(out.icon).toBeNull()
+    })
+
+    it('survives empty payload (defensive)', () => {
+        const out = projectOption({})
+        expect(out.id).toBe('')
+        expect(out.value).toBe('')
+        expect(out.label).toBe('')
+        expect(out.name).toBe('')
+    })
+})
+
+// The envelope shape the hook expects from the kernel is exercised here
+// with a mocked transport so apps can document the wire contract in a
+// single place. `useOptionsResolver` reads `body.data` for options and
+// `body.meta.{type, count}` for the discriminator — the legacy
+// root-level `body.type` is also accepted for grace-period upgrades.
+describe('options envelope contract', () => {
+    it('v0.9.0 shape carries meta.type and meta.count', () => {
+        const wire = {
+            success: true,
+            data: [
+                { id: '1', label: 'One' },
+                { id: '2', label: 'Two' },
+            ],
+            meta: { type: 'dynamic', count: 2 },
+        }
+        // Smoke-check the projection a real call would do.
+        expect(wire.data.map(projectOption)).toHaveLength(2)
+        expect(wire.meta.type).toBe('dynamic')
+        expect(wire.meta.count).toBe(2)
+    })
+
+    it('legacy shape is identifiable but consumers should migrate', () => {
+        const legacy = {
+            success: true,
+            data: [{ id: '1', label: 'One' }],
+            // root-level type, not under meta — the SDK reads it as a
+            // fallback but logs no warning (kernel ≥ v0.9.0 emits the
+            // canonical shape; older deployments are an interop case).
+            type: 'static',
+        } as any
+        expect(legacy.type).toBe('static')
+        expect(legacy.meta).toBeUndefined()
+    })
+})
+
+// Sanity-check the resolver bridge: when no provider is mounted
+// `resolveValidatorToken` returns the original token. Apps that mount
+// `OrgConfigProvider` swap that for the resolved literal.
+describe('OrgConfigBridge integration', () => {
+    afterEach(() => {
+        // Reset to the null bridge so independent tests do not leak state.
+        setOrgConfigBridge(null)
+    })
+
+    it('resolveValidatorToken passes through plain literals', () => {
+        expect(resolveValidatorToken('mx.rfc')).toBe('mx.rfc')
+        expect(resolveValidatorToken(null)).toBeNull()
+        expect(resolveValidatorToken('')).toBeNull()
+    })
+
+    it('resolveValidatorToken returns the $org reference verbatim when no bridge mounted', () => {
+        // Default null bridge: ref keys resolve to null → token preserved.
+        expect(resolveValidatorToken('$org.tax_id')).toBe('$org.tax_id')
+    })
+
+    it('setOrgConfigBridge swaps the active resolver and survives clearing', () => {
+        const spy = vi.fn((key: string) => (key === '$org.tax_id' ? 'mx.rfc' : null))
+        setOrgConfigBridge({ resolveValidator: spy, available: true })
+        expect(resolveValidatorToken('$org.tax_id')).toBe('mx.rfc')
+        expect(spy).toHaveBeenCalledWith('$org.tax_id')
+        setOrgConfigBridge(null)
+        expect(resolveValidatorToken('$org.tax_id')).toBe('$org.tax_id')
+    })
+})

package/src/dynamic-form-schema.ts

@@ -3,6 +3,37 @@
 // metacore-ui primitives.
 import { z, type ZodTypeAny } from 'zod'
 import type { ActionFieldDef, FieldValidation } from './types'
+import { resolveValidatorToken } from './use-org-config-bridge'
+
+/**
+ * Built-in validators the SDK knows how to apply by symbolic name. Apps
+ * that wire `OrgConfigProvider` map `$org.<key>` references to one of
+ * these slugs (or to a custom slug they register). Unknown slugs are a
+ * no-op so unresolved $org references degrade to "no extra check"
+ * rather than a runtime crash — matches the kernel's pass-through
+ * semantics for unresolved references.
+ */
+const builtinValidators: Record<string, (s: z.ZodString) => z.ZodString> = {
+    // The SDK ships ZERO fiscal vocabulary by default. Apps register
+    // their own validators (mx.rfc, co.nit, pe.ruc, etc.) via
+    // `registerValidator` so kernel/SDK stay region-agnostic.
+}
+
+/**
+ * Apps register validator implementations by slug. The slug is the value
+ * `OrgConfig.validators[<key>]` returns for a $org.<key> reference.
+ */
+export function registerValidator(slug: string, fn: (s: z.ZodString) => z.ZodString): void {
+    builtinValidators[slug] = fn
+}
+
+function applyCustomValidator(s: z.ZodString, customToken: string | undefined): z.ZodString {
+    if (!customToken) return s
+    const resolved = resolveValidatorToken(customToken)
+    if (!resolved) return s
+    const fn = builtinValidators[resolved]
+    return fn ? fn(s) : s
+}
 
 // Builds a zod object schema from an ActionFieldDef[]. Required fields stay
 // non-empty; optional fields accept undefined / "". Validation rules
@@ -44,6 +75,11 @@ function fieldToZod(field: ActionFieldDef): ZodTypeAny {
     if (field.type === 'email') s = s.email('Email inválido')
     if (field.type === 'url') s = s.url('URL inválida')
 
+    // Custom validator: a literal slug (`mx.rfc`) OR a `$org.<key>`
+    // reference resolved through the OrgConfigProvider. Unknown slugs
+    // pass through as no-ops so apps never crash on missing config.
+    s = applyCustomValidator(s, v.custom)
+
     if (field.required) {
         return s.min(Math.max(typeof v.min === 'number' ? v.min : 1, 1), `${field.label} es requerido`)
     }

package/src/dynamic-form.tsx

@@ -16,6 +16,7 @@ import {
 } from '@asteby/metacore-ui/primitives'
 import type { ActionFieldDef } from './types'
 import { buildZodSchema, resolveWidget } from './dynamic-form-schema'
+import { useOptionsResolver, type ResolvedOption } from './use-options-resolver'
 
 export { buildZodSchema, resolveWidget }
 
@@ -81,7 +82,11 @@ export function DynamicForm({
                         {field.label}
                         {field.required && <span className="text-red-500 ml-1">*</span>}
                     </Label>
-                    {renderField(field, values[field.key], (v: any) => update(field.key, v))}
+                    <FieldRenderer
+                        field={field}
+                        value={values[field.key]}
+                        onChange={(v: any) => update(field.key, v)}
+                    />
                     {errors[field.key] && (
                         <span className="text-red-500 text-sm" role="alert">{errors[field.key]}</span>
                     )}
@@ -99,8 +104,21 @@ export function DynamicForm({
     )
 }
 
-function renderField(field: ActionFieldDef, value: any, onChange: (v: any) => void) {
+interface FieldRendererProps {
+    field: ActionFieldDef
+    value: any
+    onChange: (v: any) => void
+}
+
+function FieldRenderer({ field, value, onChange }: FieldRendererProps) {
     const widget = resolveWidget(field)
+    // Ref-driven select: hook into useOptionsResolver so the canonical
+    // /api/options/<ref>?field=id endpoint feeds the dropdown. This is
+    // the path the kernel auto-derives for FK columns; legacy callers
+    // shipping inline `options` keep working in the branch below.
+    if (widget === 'select' && field.ref) {
+        return <RefSelect field={field} value={value} onChange={onChange} />
+    }
     switch (widget) {
         case 'textarea':
             return <Textarea id={field.key} value={value || ''} onChange={(e: React.ChangeEvent<HTMLTextAreaElement>) => onChange(e.target.value)} placeholder={field.placeholder} />
@@ -131,3 +149,23 @@ function renderField(field: ActionFieldDef, value: any, onChange: (v: any) => vo
     }
 }
 
+function RefSelect({ field, value, onChange }: FieldRendererProps) {
+    const { options, loading } = useOptionsResolver({
+        modelKey: '',          // unused — `ref` drives the URL
+        fieldKey: 'id',
+        ref: field.ref,
+    })
+    return (
+        <Select value={value || ''} onValueChange={onChange} disabled={loading}>
+            <SelectTrigger>
+                <SelectValue placeholder={loading ? 'Cargando…' : (field.placeholder || 'Seleccionar...')} />
+            </SelectTrigger>
+            <SelectContent>
+                {options.map((opt: ResolvedOption) => (
+                    <SelectItem key={String(opt.id)} value={String(opt.id)}>{opt.label}</SelectItem>
+                ))}
+            </SelectContent>
+        </Select>
+    )
+}
+

package/src/dynamic-relation.tsx

@@ -25,6 +25,7 @@ import { Plus, Trash2, Pencil } from 'lucide-react'
 import { useApi } from './api-context'
 import { useMetadataCache } from './metadata-cache'
 import { DynamicForm } from './dynamic-form'
+import { useOptionsResolver } from './use-options-resolver'
 import type { ApiResponse, TableMetadata } from './types'
 import {
     buildCreatePayload,
@@ -380,7 +381,13 @@ function ManyToManyRelation({
 
     const refKey = referencesKey || `${references}_id`
     const pivotPath = pivotEndpoint || `/data/${through}`
-    const targetPath = referencesEndpoint || `/data/${references}`
+    // referencesEndpoint is preserved as a legacy escape hatch — when set
+    // we keep the old `/data/<references>` raw fetch path (so apps that
+    // depend on a custom server route do not break). When unset we use
+    // the canonical `/api/options/:references` endpoint via
+    // useOptionsResolver, which is what the kernel auto-derives Ref to.
+    const useResolver = !referencesEndpoint
+    const legacyTargetPath = referencesEndpoint || `/data/${references}`
 
     const cachedTargetMeta = getMetadata(references)
     const [targetMeta, setTargetMeta] = useState<TableMetadata | null>(cachedTargetMeta || null)
@@ -389,41 +396,65 @@ function ManyToManyRelation({
     const [loading, setLoading] = useState(true)
     const [syncing, setSyncing] = useState(false)
 
-    const fetchAll = useCallback(async () => {
+    // Canonical path: SDK options resolver. Only fires when no legacy
+    // override is set. The hook is a no-op when `useResolver` is false.
+    const resolved = useOptionsResolver({
+        modelKey: '',
+        fieldKey: 'id',
+        ref: useResolver ? references : undefined,
+        enabled: useResolver,
+    })
+
+    const fetchPivotAndMeta = useCallback(async () => {
         setLoading(true)
         try {
             const params = buildRelationFilterParams(foreignKey, parentId)
-            const [metaRes, pivotRes, targetRes] = await Promise.all([
-                targetMeta ? Promise.resolve(null) : api.get(`/metadata/table/${references}`),
+            const tasks: Promise<unknown>[] = [
                 api.get(pivotPath, { params }),
-                api.get(targetPath),
-            ])
-            if (metaRes && (metaRes as any).data?.success) {
-                const fresh = (metaRes as { data: ApiResponse<TableMetadata> }).data.data
-                setTargetMeta(fresh)
-                cacheMetadata(references, fresh)
+            ]
+            if (!targetMeta) tasks.push(api.get(`/metadata/table/${references}`))
+            // Legacy fallback path: the resolver is disabled, fetch the
+            // target rows the old way so callers that depend on a custom
+            // route keep working.
+            if (!useResolver) tasks.push(api.get(legacyTargetPath))
+            const results = await Promise.all(tasks)
+            const pivotRes = results[0] as { data: ApiResponse<any[]> }
+            if (pivotRes.data.success) setPivotRows(pivotRes.data.data || [])
+            let cursor = 1
+            if (!targetMeta) {
+                const metaRes = results[cursor++] as { data: ApiResponse<TableMetadata> }
+                if (metaRes.data?.success) {
+                    setTargetMeta(metaRes.data.data)
+                    cacheMetadata(references, metaRes.data.data)
+                }
+            }
+            if (!useResolver) {
+                const targetRes = results[cursor++] as { data: ApiResponse<any[]> }
+                if (targetRes.data.success) setTargetRows(targetRes.data.data || [])
             }
-            const pivotList = (pivotRes as { data: ApiResponse<any[]> }).data
-            if (pivotList.success) setPivotRows(pivotList.data || [])
-            const targetList = (targetRes as { data: ApiResponse<any[]> }).data
-            if (targetList.success) setTargetRows(targetList.data || [])
         } catch (err) {
             console.error('DynamicRelation m2m fetch error', err)
         } finally {
             setLoading(false)
         }
-    }, [api, pivotPath, targetPath, foreignKey, parentId, references, targetMeta, cacheMetadata])
+    }, [api, pivotPath, foreignKey, parentId, references, targetMeta, cacheMetadata, useResolver, legacyTargetPath])
 
-    useEffect(() => { fetchAll() }, [fetchAll])
+    useEffect(() => { fetchPivotAndMeta() }, [fetchPivotAndMeta])
 
     const options = useMemo(() => {
+        if (useResolver) {
+            return resolved.options.map((o) => ({
+                value: String(o.id),
+                label: o.label,
+            }))
+        }
         return targetRows
             .filter(r => r && r.id !== undefined && r.id !== null && r.id !== '')
             .map(r => ({
                 value: String(r.id),
                 label: pickOptionLabel(r, displayKey, targetMeta?.columns),
             }))
-    }, [targetRows, displayKey, targetMeta])
+    }, [useResolver, resolved.options, targetRows, displayKey, targetMeta])
 
     const selectedIds = useMemo(
         () => extractSelectedTargetIds(pivotRows, refKey),
@@ -454,14 +485,18 @@ function ManyToManyRelation({
                 const res = await api.delete(`${pivotPath}/${pivotId}`)
                 if (!(res as any).data?.success) throw new Error('detach failed')
             }
-            await fetchAll()
+            await fetchPivotAndMeta()
+            // Refresh resolver-driven options when active so newly attached
+            // targets reflect immediately. Refetching the pivot rows alone
+            // is enough when the resolver branch is off.
+            if (useResolver) resolved.refetch()
             onChange?.()
         } catch (err) {
             console.error('DynamicRelation m2m sync error', err)
         } finally {
             setSyncing(false)
         }
-    }, [api, canCreate, canDelete, fetchAll, foreignKey, onChange, parentId, pivotIndex, pivotPath, refKey, selectedIds, syncing])
+    }, [api, canCreate, canDelete, fetchPivotAndMeta, useResolver, resolved, foreignKey, onChange, parentId, pivotIndex, pivotPath, refKey, selectedIds, syncing])
 
     return (
         <div
@@ -476,7 +511,7 @@ function ManyToManyRelation({
                 </div>
             )}
 
-            {loading ? (
+            {(loading || (useResolver && resolved.loading)) ? (
                 <Skeleton className="h-10 w-full" />
             ) : options.length === 0 ? (
                 <div className="text-center text-sm text-muted-foreground py-8 border rounded-md bg-muted/30">

package/src/index.ts

@@ -60,3 +60,18 @@ export {
     isColumnVisibleInTable,
     getSearchableColumnKeys,
 } from './column-visibility'
+export {
+    useOptionsResolver,
+    projectOption,
+    type ResolvedOption,
+    type OptionsMeta,
+    type UseOptionsResolverArgs,
+    type UseOptionsResolverResult,
+} from './use-options-resolver'
+export {
+    setOrgConfigBridge,
+    getOrgConfigBridge,
+    resolveValidatorToken,
+    type OrgConfigBridge,
+} from './use-org-config-bridge'
+export { registerValidator } from './dynamic-form-schema'

package/src/types.ts

@@ -70,6 +70,20 @@ export interface ColumnDefinition {
     relationPath?: string
     useOptions?: boolean
     options?: { value: string; label: string; icon?: string; color?: string }[]
+    /**
+     * FK target model. When the kernel auto-derives this from a
+     * belongs_to relation (or an author sets it explicitly), the SDK
+     * resolves the column's options against `/api/options/<ref>?field=id`
+     * via `useOptionsResolver`. Wins over `searchEndpoint` for select
+     * widgets — `searchEndpoint` stays as the legacy escape hatch.
+     */
+    ref?: string
+    /**
+     * Server-side validation rules the SDK can also pre-flight in the
+     * form layer. `custom` may be a literal slug or a $org.<key>
+     * reference resolved through the OrgConfigProvider.
+     */
+    validation?: FieldValidation
 }
 
 export interface ActionCondition {
@@ -81,6 +95,10 @@ export interface ActionCondition {
 // Mirrors `ValidationRule` from packages/sdk/src/generated/manifest.ts. Kept
 // inline here so runtime-react does not import generated kernel types directly
 // — apps and addons author ActionFieldDef literals.
+//
+// `custom` accepts either a literal validator slug (e.g. `mx.rfc`) registered
+// via `registerValidator`, or a `$org.<key>` reference resolved through the
+// OrgConfigProvider — same contract as kernel ColumnDef.Validation.Custom.
 export interface FieldValidation {
     regex?: string
     min?: number
@@ -111,6 +129,12 @@ export interface ActionFieldDef {
     searchEndpoint?: string
     validation?: FieldValidation
     widget?: FieldWidget | string
+    /**
+     * FK target model — same semantics as ColumnDefinition.ref. When
+     * present, DynamicForm resolves the field's options through
+     * `useOptionsResolver` against `/api/options/<ref>?field=id`.
+     */
+    ref?: string
 }
 
 export interface ActionDefinition {