@asteby/metacore-runtime-react 9.0.0 → 9.2.0

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/dynamic-table.tsx

@@ -69,6 +69,7 @@ import { defaultGetDynamicColumns } from './dynamic-columns'
 import { OptionsContext } from './options-context'
 import { ActionModalDispatcher } from './action-modal-dispatcher'
 import type { TableMetadata, ApiResponse, ActionMetadata } from './types'
+import { getSearchableColumnKeys } from './column-visibility'
 import { DynamicRecordDialog } from './dialogs/dynamic-record'
 import { ExportDialog } from './dialogs/export'
 import { ImportDialog } from './dialogs/import'
@@ -324,13 +325,30 @@ export function DynamicTable({
         initMetadataAndOptions()
     }, [model]) // eslint-disable-line react-hooks/exhaustive-deps
 
+    // Derived from `metadata.columns[].searchable`. `null` means the kernel
+    // didn't emit the flag for any column → preserve legacy "search every
+    // column" behaviour by not narrowing the request. An empty array means
+    // every column was explicitly opted out → skip sending `search` at all.
+    const searchableKeys = useMemo(
+        () => (metadata ? getSearchableColumnKeys(metadata) : null),
+        [metadata],
+    )
+
     const buildFilterParams = useCallback(() => {
         const params: Record<string, any> = {}
         if (sorting.length > 0) {
             params.sortBy = sorting[0].id
             params.order = sorting[0].desc ? 'desc' : 'asc'
         }
-        if (globalFilter) params.search = globalFilter
+        if (globalFilter) {
+            if (searchableKeys === null) {
+                params.search = globalFilter
+            } else if (searchableKeys.length > 0) {
+                params.search = globalFilter
+                params.search_columns = searchableKeys.join(',')
+            }
+            // searchableKeys === [] → drop the search request entirely
+        }
         columnFilters.forEach((filter: { id: string; value: unknown }) => { params[`f_${filter.id}`] = filter.value })
         if (defaultFilters) Object.entries(defaultFilters).forEach(([key, value]) => { params[`f_${key}`] = value })
         Object.entries(dynamicFilters).forEach(([key, values]) => {
@@ -352,7 +370,7 @@ export function DynamicTable({
             params['f_created_at'] = `${startDate}_${endDate}`
         }
         return params
-    }, [sorting, globalFilter, columnFilters, defaultFilters, dynamicFilters, dateRange])
+    }, [sorting, globalFilter, columnFilters, defaultFilters, dynamicFilters, dateRange, searchableKeys])
 
     const hasActiveFilters = useMemo(() => {
         if (globalFilter) return true

package/src/index.ts

@@ -56,3 +56,22 @@ export {
     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'

package/src/types.ts

@@ -26,6 +26,18 @@ export interface FilterDefinition {
     searchEndpoint?: string
 }
 
+/**
+ * Where a column is rendered. Mirrors `manifest.ColumnDef.Visibility` in the
+ * kernel:
+ *   - `''` / `'all'` — visible everywhere (default).
+ *   - `'table'`     — only the list/index page.
+ *   - `'modal'`     — only the create/edit modal.
+ *   - `'list'`      — only API list payloads (omitted from UI).
+ * Hosts may extend the union with their own scopes; the SDK only acts on the
+ * canonical values above.
+ */
+export type ColumnVisibility = 'all' | 'table' | 'modal' | 'list' | (string & {})
+
 export interface ColumnDefinition {
     key: string
     label: string
@@ -33,6 +45,19 @@ export interface ColumnDefinition {
     sortable: boolean
     filterable: boolean
     hidden?: boolean
+    /**
+     * Scopes where this column is rendered. When `'modal'` (or `'list'`) the
+     * column is hidden from the table even if `hidden` is unset. Empty/`'all'`/
+     * `'table'` keep the column visible. See `column-visibility.ts`.
+     */
+    visibility?: ColumnVisibility
+    /**
+     * Opts the column into the model's full-text/contains search. Independent
+     * of `filterable` (which drives column-level filter chips). When at least
+     * one column declares `searchable`, the SDK narrows the global search to
+     * those columns; otherwise legacy "search every column" behaviour applies.
+     */
+    searchable?: boolean
     styleConfig?: Record<string, any>
     tooltip?: string
     description?: string
@@ -45,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 {
@@ -56,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
@@ -86,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 {

package/src/use-options-resolver.ts

@@ -0,0 +1,232 @@
+// 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'
+
+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 function useOptionsResolver(args: UseOptionsResolverArgs): UseOptionsResolverResult {
+    const {
+        modelKey,
+        fieldKey,
+        ref,
+        query,
+        limit,
+        enabled = true,
+        endpoint,
+    } = args
+
+    const api = useApi()
+    const [options, setOptions] = useState<ResolvedOption[]>([])
+    const [meta, setMeta] = useState<OptionsMeta | null>(null)
+    const [loading, setLoading] = useState(false)
+    const [error, setError] = useState<Error | null>(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<AbortController | null>(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: Record<string, string | number> = { 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 as { data: any }).data
+                if (!body || body.success !== true) {
+                    throw new Error(body?.message || 'options resolver: unsuccessful response')
+                }
+                const rawOptions: any[] = 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: any) => {
+                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: any): ResolvedOption {
+    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,
+    }
+}