@asteby/metacore-runtime-react 9.1.0 → 9.2.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @asteby/metacore-runtime-react
 
+## 9.2.0
+
+### Minor Changes
+
+- 150a907: feat: useOptionsResolver hook + locale-aware Validation via OrgConfigProvider
+
+  **runtime-react:**
+  - New `useOptionsResolver(args)` hook that consumes the v0.9.0 kernel
+    envelope `{ success, data, meta: { type, count } }` from
+    `GET /api/options/:model?field=…`. Replaces the ad-hoc `/data/<model>`
+    reads `<DynamicRelation>` used to do.
+  - `<DynamicForm>` now renders a Ref-driven `<RefSelect>` whenever an
+    `ActionFieldDef.ref` is present — apps stop hardcoding option lists for
+    belongs_to FKs.
+  - `<DynamicRelation>` (kind="many_to_many") prefers the canonical options
+    endpoint via `useOptionsResolver`. The legacy `referencesEndpoint` prop
+    remains a working escape hatch for apps wired against custom routes.
+  - `ColumnDefinition.ref` and `ColumnDefinition.validation` are now part of
+    the metadata contract the SDK reads. `ActionFieldDef.ref` joins the
+    field-level type so addons can declare ref-aware modal fields.
+  - New `setOrgConfigBridge` / `resolveValidatorToken` surface lets apps
+    feed a `useOrgConfig`-backed resolver into the SDK's validator
+    pipeline. Validators with `custom: '$org.<key>'` are resolved at form
+    build time; unresolved tokens degrade to no-op so missing config does
+    not crash forms.
+  - New `registerValidator(slug, fn)` lets apps install their own
+    region-specific validators (e.g. `mx.rfc`, `co.nit`) without leaking
+    fiscal vocabulary into the SDK.
+
+  **app-providers:**
+  - New `OrgConfigProvider` + `useOrgConfig()` companion to
+    `PlatformConfigProvider`. Apps wire a per-org config fetcher and the
+    provider exposes typed `currency`, `locale`, `validators` plus a
+    `resolveValidator(refOrKey)` helper for the `$org.<key>` reference
+    contract the kernel ≥ v0.9.0 emits.
+
 ## 9.1.0
 
 ### Minor Changes

package/dist/dynamic-form-schema.d.ts

@@ -1,5 +1,10 @@
 import { z } from 'zod';
 import type { ActionFieldDef } from './types';
+/**
+ * Apps register validator implementations by slug. The slug is the value
+ * `OrgConfig.validators[<key>]` returns for a $org.<key> reference.
+ */
+export declare function registerValidator(slug: string, fn: (s: z.ZodString) => z.ZodString): void;
 export declare function buildZodSchema(fields: ActionFieldDef[]): z.ZodObject<{
     [x: string]: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
 }, z.core.$strip>;

package/dist/dynamic-form-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dynamic-form-schema.d.ts","sourceRoot":"","sources":["../src/dynamic-form-schema.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAmB,MAAM,KAAK,CAAA;AACxC,OAAO,KAAK,EAAE,cAAc,EAAmB,MAAM,SAAS,CAAA;AAM9D,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE;;kBAMtD;AAuCD,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAU3D"}
+{"version":3,"file":"dynamic-form-schema.d.ts","sourceRoot":"","sources":["../src/dynamic-form-schema.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAmB,MAAM,KAAK,CAAA;AACxC,OAAO,KAAK,EAAE,cAAc,EAAmB,MAAM,SAAS,CAAA;AAiB9D;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,SAAS,GAAG,IAAI,CAEzF;AAcD,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE;;kBAMtD;AA4CD,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAU3D"}

package/dist/dynamic-form-schema.js

@@ -2,6 +2,36 @@
 // callers (and unit tests) can use the zod schema without pulling in React or
 // metacore-ui primitives.
 import { z } from 'zod';
+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 = {
+// 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, fn) {
+    builtinValidators[slug] = fn;
+}
+function applyCustomValidator(s, customToken) {
+    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
 // (regex/min/max) layer on top: for numeric columns they bound the value, for
@@ -46,6 +76,10 @@ function fieldToZod(field) {
         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/dist/dynamic-form.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dynamic-form.d.ts","sourceRoot":"","sources":["../src/dynamic-form.tsx"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAC7C,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAErE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,CAAA;AAExC,MAAM,WAAW,gBAAgB;IAC7B,MAAM,EAAE,cAAc,EAAE,CAAA;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IACnC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/D,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACrB;AAED,wBAAgB,WAAW,CAAC,EACxB,MAAM,EACN,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,WAAuB,EACvB,WAAwB,EACxB,QAAgB,GACnB,EAAE,gBAAgB,2CA4DlB"}
+{"version":3,"file":"dynamic-form.d.ts","sourceRoot":"","sources":["../src/dynamic-form.tsx"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAC7C,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAGrE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,CAAA;AAExC,MAAM,WAAW,gBAAgB;IAC7B,MAAM,EAAE,cAAc,EAAE,CAAA;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IACnC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/D,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACrB;AAED,wBAAgB,WAAW,CAAC,EACxB,MAAM,EACN,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,WAAuB,EACvB,WAAwB,EACxB,QAAgB,GACnB,EAAE,gBAAgB,2CAgElB"}

package/dist/dynamic-form.js

@@ -5,6 +5,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useMemo, useState } from 'react';
 import { Input, Textarea, Label, Switch, Button, Select, SelectContent, SelectItem, SelectTrigger, SelectValue, } from '@asteby/metacore-ui/primitives';
 import { buildZodSchema, resolveWidget } from './dynamic-form-schema';
+import { useOptionsResolver } from './use-options-resolver';
 export { buildZodSchema, resolveWidget };
 export function DynamicForm({ fields, initialValues, onSubmit, onCancel, submitLabel = 'Guardar', cancelLabel = 'Cancelar', disabled = false, }) {
     const [values, setValues] = useState({});
@@ -42,10 +43,17 @@ export function DynamicForm({ fields, initialValues, onSubmit, onCancel, submitL
             setSubmitting(false);
         }
     };
-    return (_jsxs("form", { onSubmit: handleSubmit, className: "grid gap-4", children: [fields.map((field) => (_jsxs("div", { className: "grid gap-2", children: [_jsxs(Label, { htmlFor: field.key, children: [field.label, field.required && _jsx("span", { className: "text-red-500 ml-1", children: "*" })] }), renderField(field, values[field.key], (v) => update(field.key, v)), errors[field.key] && (_jsx("span", { className: "text-red-500 text-sm", role: "alert", children: errors[field.key] }))] }, field.key))), _jsxs("div", { className: "flex justify-end gap-2 pt-2", children: [onCancel && (_jsx(Button, { type: "button", variant: "outline", onClick: onCancel, disabled: submitting || disabled, children: cancelLabel })), _jsx(Button, { type: "submit", disabled: submitting || disabled, children: submitLabel })] })] }));
+    return (_jsxs("form", { onSubmit: handleSubmit, className: "grid gap-4", children: [fields.map((field) => (_jsxs("div", { className: "grid gap-2", children: [_jsxs(Label, { htmlFor: field.key, children: [field.label, field.required && _jsx("span", { className: "text-red-500 ml-1", children: "*" })] }), _jsx(FieldRenderer, { field: field, value: values[field.key], onChange: (v) => update(field.key, v) }), errors[field.key] && (_jsx("span", { className: "text-red-500 text-sm", role: "alert", children: errors[field.key] }))] }, field.key))), _jsxs("div", { className: "flex justify-end gap-2 pt-2", children: [onCancel && (_jsx(Button, { type: "button", variant: "outline", onClick: onCancel, disabled: submitting || disabled, children: cancelLabel })), _jsx(Button, { type: "submit", disabled: submitting || disabled, children: submitLabel })] })] }));
 }
-function renderField(field, value, onChange) {
+function FieldRenderer({ field, value, onChange }) {
     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 _jsx(RefSelect, { field: field, value: value, onChange: onChange });
+    }
     switch (widget) {
         case 'textarea':
             return _jsx(Textarea, { id: field.key, value: value || '', onChange: (e) => onChange(e.target.value), placeholder: field.placeholder });
@@ -68,3 +76,11 @@ function renderField(field, value, onChange) {
             return _jsx(Input, { id: field.key, type: field.type === 'email' ? 'email' : field.type === 'url' ? 'url' : 'text', value: value || '', onChange: (e) => onChange(e.target.value), placeholder: field.placeholder });
     }
 }
+function RefSelect({ field, value, onChange }) {
+    const { options, loading } = useOptionsResolver({
+        modelKey: '', // unused — `ref` drives the URL
+        fieldKey: 'id',
+        ref: field.ref,
+    });
+    return (_jsxs(Select, { value: value || '', onValueChange: onChange, disabled: loading, children: [_jsx(SelectTrigger, { children: _jsx(SelectValue, { placeholder: loading ? 'Cargando…' : (field.placeholder || 'Seleccionar...') }) }), _jsx(SelectContent, { children: options.map((opt) => (_jsx(SelectItem, { value: String(opt.id), children: opt.label }, String(opt.id)))) })] }));
+}

package/dist/dynamic-relation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dynamic-relation.d.ts","sourceRoot":"","sources":["../src/dynamic-relation.tsx"],"names":[],"mappings":"AAyCA,YAAY,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AACrE,OAAO,EACH,kBAAkB,EAClB,uBAAuB,EACvB,kBAAkB,EAClB,yBAAyB,EACzB,wBAAwB,EACxB,aAAa,EACb,wBAAwB,EACxB,eAAe,EACf,cAAc,GACjB,MAAM,4BAA4B,CAAA;AAEnC,MAAM,WAAW,sBAAsB;IACnC,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,wBAAwB,EAAE,MAAM,CAAA;IAChC,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,iBAAiB,EAAE,MAAM,CAAA;IACzB,uBAAuB,EAAE,MAAM,CAAA;IAC/B,WAAW,EAAE,MAAM,CAAA;CACtB;AAiBD,UAAU,WAAW;IACjB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;IACzB,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB,uCAAuC;IACvC,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,2BAA2B;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAA;IACzC,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;CACxB;AAED,MAAM,WAAW,6BAA8B,SAAQ,WAAW;IAC9D,IAAI,EAAE,aAAa,CAAA;IACnB,yFAAyF;IACzF,KAAK,EAAE,MAAM,CAAA;IACb,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAA;IAClB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,8BAA+B,SAAQ,WAAW;IAC/D,IAAI,EAAE,cAAc,CAAA;IACpB,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAA;IACf,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAA;IAClB,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAA;IAClB,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,uEAAuE;IACvE,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,MAAM,oBAAoB,GAC1B,6BAA6B,GAC7B,8BAA8B,CAAA;AAEpC,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,2CAK1D"}
+{"version":3,"file":"dynamic-relation.d.ts","sourceRoot":"","sources":["../src/dynamic-relation.tsx"],"names":[],"mappings":"AA0CA,YAAY,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AACrE,OAAO,EACH,kBAAkB,EAClB,uBAAuB,EACvB,kBAAkB,EAClB,yBAAyB,EACzB,wBAAwB,EACxB,aAAa,EACb,wBAAwB,EACxB,eAAe,EACf,cAAc,GACjB,MAAM,4BAA4B,CAAA;AAEnC,MAAM,WAAW,sBAAsB;IACnC,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,wBAAwB,EAAE,MAAM,CAAA;IAChC,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,iBAAiB,EAAE,MAAM,CAAA;IACzB,uBAAuB,EAAE,MAAM,CAAA;IAC/B,WAAW,EAAE,MAAM,CAAA;CACtB;AAiBD,UAAU,WAAW;IACjB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;IACzB,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB,uCAAuC;IACvC,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,2BAA2B;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAA;IACzC,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;CACxB;AAED,MAAM,WAAW,6BAA8B,SAAQ,WAAW;IAC9D,IAAI,EAAE,aAAa,CAAA;IACnB,yFAAyF;IACzF,KAAK,EAAE,MAAM,CAAA;IACb,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAA;IAClB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,8BAA+B,SAAQ,WAAW;IAC/D,IAAI,EAAE,cAAc,CAAA;IACpB,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAA;IACf,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAA;IAClB,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAA;IAClB,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,uEAAuE;IACvE,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,MAAM,oBAAoB,GAC1B,6BAA6B,GAC7B,8BAA8B,CAAA;AAEpC,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,2CAK1D"}

package/dist/dynamic-relation.js

@@ -10,6 +10,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 { buildCreatePayload, buildPivotAttachPayload, buildPivotRowIndex, buildRelationFilterParams, deriveRelationFormFields, diffSelection, extractSelectedTargetIds, pickOptionLabel, relationRowKey, } from './dynamic-relation-helpers';
 export { buildCreatePayload, buildPivotAttachPayload, buildPivotRowIndex, buildRelationFilterParams, deriveRelationFormFields, diffSelection, extractSelectedTargetIds, pickOptionLabel, relationRowKey, } from './dynamic-relation-helpers';
 const DEFAULT_STRINGS = {
@@ -140,33 +141,58 @@ function ManyToManyRelation({ kind, through, references, foreignKey, referencesK
     const labels = { ...DEFAULT_STRINGS, ...(strings || {}) };
     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(cachedTargetMeta || null);
     const [targetRows, setTargetRows] = useState([]);
     const [pivotRows, setPivotRows] = useState([]);
     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 = [
                 api.get(pivotPath, { params }),
-                api.get(targetPath),
-            ]);
-            if (metaRes && metaRes.data?.success) {
-                const fresh = metaRes.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];
+            if (pivotRes.data.success)
+                setPivotRows(pivotRes.data.data || []);
+            let cursor = 1;
+            if (!targetMeta) {
+                const metaRes = results[cursor++];
+                if (metaRes.data?.success) {
+                    setTargetMeta(metaRes.data.data);
+                    cacheMetadata(references, metaRes.data.data);
+                }
+            }
+            if (!useResolver) {
+                const targetRes = results[cursor++];
+                if (targetRes.data.success)
+                    setTargetRows(targetRes.data.data || []);
             }
-            const pivotList = pivotRes.data;
-            if (pivotList.success)
-                setPivotRows(pivotList.data || []);
-            const targetList = targetRes.data;
-            if (targetList.success)
-                setTargetRows(targetList.data || []);
         }
         catch (err) {
             console.error('DynamicRelation m2m fetch error', err);
@@ -174,16 +200,22 @@ function ManyToManyRelation({ kind, through, references, foreignKey, referencesK
         finally {
             setLoading(false);
         }
-    }, [api, pivotPath, targetPath, foreignKey, parentId, references, targetMeta, cacheMetadata]);
-    useEffect(() => { fetchAll(); }, [fetchAll]);
+    }, [api, pivotPath, foreignKey, parentId, references, targetMeta, cacheMetadata, useResolver, legacyTargetPath]);
+    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), [pivotRows, refKey]);
     const pivotIndex = useMemo(() => buildPivotRowIndex(pivotRows, refKey), [pivotRows, refKey]);
     const handleChange = useCallback(async (next) => {
@@ -212,7 +244,12 @@ function ManyToManyRelation({ kind, through, references, foreignKey, referencesK
                 if (!res.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) {
@@ -221,6 +258,6 @@ function ManyToManyRelation({ kind, through, references, foreignKey, referencesK
         finally {
             setSyncing(false);
         }
-    }, [api, canCreate, canDelete, fetchAll, foreignKey, onChange, parentId, pivotIndex, pivotPath, refKey, selectedIds, syncing]);
-    return (_jsxs("div", { className: className, "data-relation-kind": kind, "data-relation-through": through, "data-relation-references": references, children: [labels.title && (_jsx("div", { className: "pb-3", children: _jsx("h3", { className: "text-sm font-medium", children: labels.title }) })), loading ? (_jsx(Skeleton, { className: "h-10 w-full" })) : options.length === 0 ? (_jsx("div", { className: "text-center text-sm text-muted-foreground py-8 border rounded-md bg-muted/30", children: labels.emptyState })) : (_jsx(MultiSelect, { options: options, selected: selectedIds, onChange: handleChange, placeholder: labels.selectPlaceholder, searchPlaceholder: labels.selectSearchPlaceholder, emptyMessage: labels.selectEmpty }))] }));
+    }, [api, canCreate, canDelete, fetchPivotAndMeta, useResolver, resolved, foreignKey, onChange, parentId, pivotIndex, pivotPath, refKey, selectedIds, syncing]);
+    return (_jsxs("div", { className: className, "data-relation-kind": kind, "data-relation-through": through, "data-relation-references": references, children: [labels.title && (_jsx("div", { className: "pb-3", children: _jsx("h3", { className: "text-sm font-medium", children: labels.title }) })), (loading || (useResolver && resolved.loading)) ? (_jsx(Skeleton, { className: "h-10 w-full" })) : options.length === 0 ? (_jsx("div", { className: "text-center text-sm text-muted-foreground py-8 border rounded-md bg-muted/30", children: labels.emptyState })) : (_jsx(MultiSelect, { options: options, selected: selectedIds, onChange: handleChange, placeholder: labels.selectPlaceholder, searchPlaceholder: labels.selectSearchPlaceholder, emptyMessage: labels.selectEmpty }))] }));
 }

package/dist/index.d.ts

@@ -20,4 +20,7 @@ export { DynamicCRUDPage, type DynamicCRUDPageProps, type DynamicCRUDPageStrings
 export { DynamicRelation, type DynamicRelationProps, type DynamicRelationStrings, type DynamicRelationKind, buildRelationFilterParams, buildCreatePayload, deriveRelationFormFields, relationRowKey, } from './dynamic-relation';
 export { registerModelExtension, getModelExtension, clearModelExtensions, type ModelExtension, type ModelExtensionProps, } from './model-extension-registry';
 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';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,SAAS,CAAA;AACvB,cAAc,mBAAmB,CAAA;AACjC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,gBAAgB,CAAA;AAC9B,OAAO,EACH,qBAAqB,EACrB,KAAK,gBAAgB,GACxB,MAAM,2BAA2B,CAAA;AAClC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,QAAQ,CAAA;AACtB,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA;AACpC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,kBAAkB,CAAA;AAChC,cAAc,gBAAgB,CAAA;AAC9B,YAAY,EACR,kBAAkB,EAClB,YAAY,IAAI,yBAAyB,EACzC,iBAAiB,EACjB,oBAAoB,GACvB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACH,wBAAwB,EACxB,4BAA4B,EAC5B,KAAK,qBAAqB,GAC7B,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EACH,eAAe,EACf,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,GAC9B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACH,eAAe,EACf,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,kBAAkB,EAClB,wBAAwB,EACxB,cAAc,GACjB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACH,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GAC3B,MAAM,4BAA4B,CAAA;AACnC,OAAO,EACH,sBAAsB,EACtB,uBAAuB,GAC1B,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,SAAS,CAAA;AACvB,cAAc,mBAAmB,CAAA;AACjC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,gBAAgB,CAAA;AAC9B,OAAO,EACH,qBAAqB,EACrB,KAAK,gBAAgB,GACxB,MAAM,2BAA2B,CAAA;AAClC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,QAAQ,CAAA;AACtB,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA;AACpC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,kBAAkB,CAAA;AAChC,cAAc,gBAAgB,CAAA;AAC9B,YAAY,EACR,kBAAkB,EAClB,YAAY,IAAI,yBAAyB,EACzC,iBAAiB,EACjB,oBAAoB,GACvB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACH,wBAAwB,EACxB,4BAA4B,EAC5B,KAAK,qBAAqB,GAC7B,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EACH,eAAe,EACf,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,GAC9B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACH,eAAe,EACf,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,kBAAkB,EAClB,wBAAwB,EACxB,cAAc,GACjB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACH,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GAC3B,MAAM,4BAA4B,CAAA;AACnC,OAAO,EACH,sBAAsB,EACtB,uBAAuB,GAC1B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACH,kBAAkB,EAClB,aAAa,EACb,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,GAChC,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACH,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,KAAK,eAAe,GACvB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/index.js

@@ -24,3 +24,6 @@ export { DynamicCRUDPage, } from './dynamic-crud-page';
 export { DynamicRelation, buildRelationFilterParams, buildCreatePayload, deriveRelationFormFields, relationRowKey, } from './dynamic-relation';
 export { registerModelExtension, getModelExtension, clearModelExtensions, } from './model-extension-registry';
 export { isColumnVisibleInTable, getSearchableColumnKeys, } from './column-visibility';
+export { useOptionsResolver, projectOption, } from './use-options-resolver';
+export { setOrgConfigBridge, getOrgConfigBridge, resolveValidatorToken, } from './use-org-config-bridge';
+export { registerValidator } from './dynamic-form-schema';

package/dist/types.d.ts

@@ -74,6 +74,20 @@ export interface ColumnDefinition {
         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 {
     field: string;
@@ -101,6 +115,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 {
     key: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/use-options-resolver.d.ts

@@ -0,0 +1,87 @@
+export interface ResolvedOption {
+    /** Canonical id (server-side primary key). */
+    id: string | number;
+    /** Same as `id` — preserved for legacy frontend parity. */
+    value: string | number;
+    /** Display string. */
+    label: string;
+    /** Same as `label` — preserved for legacy frontend parity. */
+    name: string;
+    description?: string | null;
+    image?: string | null;
+    color?: string | null;
+    icon?: string | null;
+}
+export interface OptionsMeta {
+    /** 'static' for inline options, 'dynamic' for FK-resolved lists. */
+    type: 'static' | 'dynamic' | string;
+    /** Number of options the server returned in this batch. */
+    count: number;
+}
+export interface UseOptionsResolverArgs {
+    /**
+     * The owning model whose options endpoint is queried. Pass the model
+     * key (e.g. 'sales_orders'). Required — passing an empty string puts
+     * the hook in idle mode and no fetch fires.
+     */
+    modelKey: string;
+    /**
+     * Field on `modelKey` to resolve. Maps to `?field=<fieldKey>`.
+     */
+    fieldKey: string;
+    /**
+     * Optional FK target. When set the hook resolves against
+     * `/api/options/<ref>?field=id` instead of `/api/options/<modelKey>`.
+     * This is the canonical path the kernel auto-derives from
+     * `ColumnDef.Ref`. Prefer this over `endpoint`.
+     */
+    ref?: string;
+    /**
+     * Free-text query forwarded as `?q=`. Empty values are skipped so the
+     * server returns the first page unfiltered.
+     */
+    query?: string;
+    /**
+     * Server-side pagination cap. Defaults to 50 (kernel
+     * DefaultOptionsLimit) if omitted.
+     */
+    limit?: number;
+    /**
+     * Toggle to disable fetching entirely (e.g. while a parent row is
+     * still loading). Defaults to true.
+     */
+    enabled?: boolean;
+    /**
+     * Escape hatch for callers that need a non-canonical URL — e.g.
+     * legacy `/options/<custom>?...`. When set it overrides `ref` and
+     * `modelKey` for the fetch path. The query string is built from
+     * `fieldKey` / `query` / `limit` exactly the same way.
+     */
+    endpoint?: string;
+}
+export interface UseOptionsResolverResult {
+    options: ResolvedOption[];
+    meta: OptionsMeta | null;
+    loading: boolean;
+    error: Error | null;
+    /** Forces a refetch. Useful after a parent record updates. */
+    refetch: () => void;
+}
+/**
+ * Resolves select options for a field via the canonical
+ * `/api/options/:model?field=…` endpoint. Returns the v0.9.0 envelope
+ * `{ data, meta: { type, count } }` projected into a stable shape.
+ *
+ * The hook is intentionally minimal: it does NOT debounce `query`
+ * (callers should hold the controlled value and pass it post-debounce)
+ * and does NOT cache across hook instances (apps that need shared state
+ * compose this with TanStack Query in their own layer).
+ */
+export declare function useOptionsResolver(args: UseOptionsResolverArgs): UseOptionsResolverResult;
+/**
+ * Normalizes the wire shape into ResolvedOption. The kernel returns dual
+ * id/value and label/name fields for legacy parity — we accept either
+ * and surface a stable shape downstream.
+ */
+export declare function projectOption(raw: any): ResolvedOption;
+//# sourceMappingURL=use-options-resolver.d.ts.map

package/dist/use-options-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-options-resolver.d.ts","sourceRoot":"","sources":["../src/use-options-resolver.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,cAAc;IAC3B,8CAA8C;IAC9C,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;IACnB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;IACtB,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED,MAAM,WAAW,WAAW;IACxB,oEAAoE;IACpE,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAA;IACnC,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,sBAAsB;IACnC;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,wBAAwB;IACrC,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,IAAI,EAAE,WAAW,GAAG,IAAI,CAAA;IACxB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,IAAI,CAAA;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,sBAAsB,GAAG,wBAAwB,CAiHzF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,GAAG,GAAG,cAAc,CAatD"}

package/dist/use-options-resolver.js

@@ -0,0 +1,147 @@
+// useOptionsResolver — single hook the SDK uses to fetch select options
+// for a metadata-driven field. Replaces the ad-hoc `/data/<model>` reads
+// that DynamicForm and DynamicRelation used to do.
+//
+// Contract (matches kernel ≥ v0.9.0):
+//   GET /api/options/:model?field=<key>&q=<text>&limit=<n>
+//   →  { success: true, data: Option[], meta: { type: 'static'|'dynamic', count } }
+//
+// The hook prefers `ColumnDef.Ref` (auto-derived by the kernel from
+// belongs_to relations) over a hand-wired `searchEndpoint`. Apps that
+// adopt Ref via the kernel auto-derivation get the right behaviour for
+// free; legacy callers that still ship `searchEndpoint` keep working.
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { useApi } from './api-context';
+/**
+ * Resolves select options for a field via the canonical
+ * `/api/options/:model?field=…` endpoint. Returns the v0.9.0 envelope
+ * `{ data, meta: { type, count } }` projected into a stable shape.
+ *
+ * The hook is intentionally minimal: it does NOT debounce `query`
+ * (callers should hold the controlled value and pass it post-debounce)
+ * and does NOT cache across hook instances (apps that need shared state
+ * compose this with TanStack Query in their own layer).
+ */
+export function useOptionsResolver(args) {
+    const { modelKey, fieldKey, ref, query, limit, enabled = true, endpoint, } = args;
+    const api = useApi();
+    const [options, setOptions] = useState([]);
+    const [meta, setMeta] = useState(null);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    // refreshKey is bumped by `refetch` to force the effect to re-run
+    // even when none of the input args changed.
+    const [refreshKey, setRefreshKey] = useState(0);
+    // The URL the hook hits. Ref wins over modelKey because the kernel's
+    // auto-derivation makes ref the canonical pointer; a manual endpoint
+    // wins over both as the explicit override.
+    const url = useMemo(() => {
+        if (endpoint)
+            return endpoint;
+        if (ref)
+            return `/options/${ref}`;
+        if (!modelKey)
+            return '';
+        return `/options/${modelKey}`;
+    }, [endpoint, ref, modelKey]);
+    // The field to query. When using `ref` the canonical lookup field is
+    // `id` (FK targets the target model's PK), unless the caller wants
+    // to override that explicitly via `fieldKey`. We only inject the `id`
+    // default when `ref` is set AND `fieldKey` is empty.
+    const effectiveField = useMemo(() => {
+        if (fieldKey)
+            return fieldKey;
+        if (ref)
+            return 'id';
+        return '';
+    }, [fieldKey, ref]);
+    // Track the in-flight controller so a new fetch can abort the
+    // previous one — matters for typeahead callers passing changing `query`.
+    const abortRef = useRef(null);
+    useEffect(() => {
+        if (!enabled || !url || !effectiveField) {
+            setOptions([]);
+            setMeta(null);
+            setLoading(false);
+            setError(null);
+            return;
+        }
+        // Cancel any pending request before issuing a new one.
+        abortRef.current?.abort();
+        const controller = new AbortController();
+        abortRef.current = controller;
+        setLoading(true);
+        setError(null);
+        const params = { field: effectiveField };
+        if (query)
+            params.q = query;
+        if (typeof limit === 'number' && limit > 0)
+            params.limit = limit;
+        api.get(url, { params, signal: controller.signal })
+            .then((res) => {
+            if (controller.signal.aborted)
+                return;
+            const body = res.data;
+            if (!body || body.success !== true) {
+                throw new Error(body?.message || 'options resolver: unsuccessful response');
+            }
+            const rawOptions = Array.isArray(body.data) ? body.data : [];
+            const projected = rawOptions.map(projectOption);
+            setOptions(projected);
+            // v0.9.0 envelope: meta.type / meta.count. We tolerate
+            // older deployments that still emit a root-level `type`
+            // by reading either spot — the projection prefers the
+            // canonical location so the SDK guides apps to the new
+            // shape without breaking grace-period upgrades.
+            const metaPayload = body.meta && typeof body.meta === 'object'
+                ? body.meta
+                : { type: body.type, count: rawOptions.length };
+            setMeta({
+                type: metaPayload?.type ?? 'dynamic',
+                count: typeof metaPayload?.count === 'number'
+                    ? metaPayload.count
+                    : rawOptions.length,
+            });
+        })
+            .catch((err) => {
+            if (controller.signal.aborted)
+                return;
+            setError(err instanceof Error ? err : new Error(String(err)));
+            setOptions([]);
+            setMeta(null);
+        })
+            .finally(() => {
+            if (!controller.signal.aborted)
+                setLoading(false);
+        });
+        return () => {
+            controller.abort();
+        };
+    }, [api, url, effectiveField, query, limit, enabled, refreshKey]);
+    return {
+        options,
+        meta,
+        loading,
+        error,
+        refetch: () => setRefreshKey((k) => k + 1),
+    };
+}
+/**
+ * Normalizes the wire shape into ResolvedOption. The kernel returns dual
+ * id/value and label/name fields for legacy parity — we accept either
+ * and surface a stable shape downstream.
+ */
+export function projectOption(raw) {
+    const id = raw?.id ?? raw?.value ?? '';
+    const label = String(raw?.label ?? raw?.name ?? id ?? '');
+    return {
+        id,
+        value: raw?.value ?? id,
+        label,
+        name: String(raw?.name ?? label),
+        description: raw?.description ?? null,
+        image: raw?.image ?? null,
+        color: raw?.color ?? null,
+        icon: raw?.icon ?? null,
+    };
+}