@asteby/metacore-runtime-react 9.1.0 → 10.0.0

package/src/__tests__/wasm-client-sri.test.ts

@@ -0,0 +1,82 @@
+// Wasm-client SRI smoke tests — lives in runtime-react because the SDK
+// package does not (yet) carry a vitest setup of its own. We import the
+// helper through the workspace specifier so the test exercises the same
+// public boundary downstream apps see.
+//
+// The SRI logic is decoupled from WebAssembly instantiation by design, so
+// these tests run in plain Node without needing a real `.wasm` module.
+
+import { describe, it, expect } from 'vitest'
+import {
+    verifyIntegrity,
+    WasmIntegrityError,
+} from '@asteby/metacore-sdk'
+
+function bytes(input: string): Uint8Array {
+    return new TextEncoder().encode(input)
+}
+
+async function digestB64(algo: 'SHA-256' | 'SHA-384' | 'SHA-512', input: string) {
+    const buf = await crypto.subtle.digest(algo, bytes(input))
+    const view = new Uint8Array(buf)
+    let bin = ''
+    for (let i = 0; i < view.byteLength; i++) bin += String.fromCharCode(view[i]!)
+    return btoa(bin)
+}
+
+describe('verifyIntegrity', () => {
+    it('accepts a matching sha384 digest', async () => {
+        const payload = 'hello, metacore wasm world'
+        const hash = await digestB64('SHA-384', payload)
+        await expect(
+            verifyIntegrity(bytes(payload), `sha384-${hash}`),
+        ).resolves.toBeUndefined()
+    })
+
+    it('accepts a matching sha256 digest', async () => {
+        const payload = '{"hello":"world"}'
+        const hash = await digestB64('SHA-256', payload)
+        await expect(
+            verifyIntegrity(bytes(payload), `sha256-${hash}`),
+        ).resolves.toBeUndefined()
+    })
+
+    it('throws WasmIntegrityError on digest mismatch', async () => {
+        const payload = 'hello'
+        const wrong = await digestB64('SHA-384', 'tampered')
+        await expect(
+            verifyIntegrity(bytes(payload), `sha384-${wrong}`),
+        ).rejects.toBeInstanceOf(WasmIntegrityError)
+    })
+
+    it('passes when ANY space-separated token matches', async () => {
+        const payload = 'multi-hash'
+        const bad = await digestB64('SHA-384', 'other')
+        const good = await digestB64('SHA-256', payload)
+        await expect(
+            verifyIntegrity(bytes(payload), `sha384-${bad} sha256-${good}`),
+        ).resolves.toBeUndefined()
+    })
+
+    it('is a no-op when integrity is the empty string', async () => {
+        await expect(verifyIntegrity(bytes('anything'), '')).resolves.toBeUndefined()
+    })
+
+    it('rejects malformed integrity tokens', async () => {
+        await expect(
+            verifyIntegrity(bytes('x'), 'this-has-no-algo'),
+        ).rejects.toBeInstanceOf(WasmIntegrityError)
+    })
+
+    it('rejects unsupported algorithms', async () => {
+        await expect(
+            verifyIntegrity(bytes('x'), 'md5-deadbeef'),
+        ).rejects.toBeInstanceOf(WasmIntegrityError)
+    })
+
+    it('handles length-mismatched digests as a clean mismatch', async () => {
+        await expect(
+            verifyIntegrity(bytes('x'), 'sha256-short'),
+        ).rejects.toBeInstanceOf(WasmIntegrityError)
+    })
+})

package/src/addon-layout-context.tsx

@@ -0,0 +1,137 @@
+// AddonLayoutContext — broadcast the active addon entry's layout selection
+// (`shell` vs `immersive`) up to the host so it can hide/show its chrome
+// (Sidebar, Topbar, breadcrumbs) when an immersive addon is mounted.
+//
+// Why a context rather than a prop on the host shell:
+//
+//   1. The host shell is rendered ABOVE the addon route in the tree, but the
+//      decision about what layout the addon wants comes from the addon itself
+//      (manifest.frontend.layout) which the AddonLoader knows about at mount
+//      time. A bottom-up signal via context inverts the dependency cleanly.
+//
+//   2. Addon entries can swap layouts at runtime (think a kiosk-mode toggle
+//      inside a POS). A context value reactively updates the host without
+//      asking each route to wire props.
+//
+//   3. When the user navigates AWAY from an immersive addon, the AddonLoader
+//      unmounts, its layout context updater fires `setLayout("shell")` from
+//      a cleanup effect, and the chrome restores automatically.
+//
+// Host integration (starter-core, ops, …):
+//
+//   function AppShell({ children }) {
+//     const layout = useAddonLayout()
+//     const chrome = layout !== "immersive"
+//     return (
+//       <div className={chrome ? "grid grid-cols-[280px_1fr]" : "h-dvh w-dvw"}>
+//         {chrome && <Sidebar />}
+//         <main>{chrome && <Topbar />}{children}</main>
+//       </div>
+//     )
+//   }
+//
+// The context defaults to `"shell"`, so apps that never mount an
+// `<AddonLayoutProvider>` keep the legacy behaviour.
+
+import {
+    createContext,
+    useCallback,
+    useContext,
+    useEffect,
+    useMemo,
+    useState,
+} from 'react'
+import type { AddonLayout } from '@asteby/metacore-sdk'
+
+export type { AddonLayout }
+
+interface AddonLayoutState {
+    /** Active layout. `"shell"` (default) or `"immersive"`. */
+    layout: AddonLayout
+    /**
+     * Imperative setter for the host or an addon-loader to mutate the active
+     * layout. Exposed for advanced use; most callers should use
+     * `useDeclareAddonLayout(layout)` from a route component, which scopes the
+     * change to the route's mount lifetime.
+     */
+    setLayout: (layout: AddonLayout) => void
+}
+
+const defaultState: AddonLayoutState = {
+    layout: 'shell',
+    setLayout: () => {
+        /* noop — provider missing; consumers degrade to legacy "shell" */
+    },
+}
+
+const AddonLayoutContext = createContext<AddonLayoutState>(defaultState)
+
+export interface AddonLayoutProviderProps {
+    /** Initial layout — usually `"shell"`. */
+    initial?: AddonLayout
+    children: React.ReactNode
+}
+
+/**
+ * Wrap the host app once, above the router outlet. The provider keeps the
+ * currently-active layout in state; addon-loader and `useDeclareAddonLayout`
+ * mutate it from below.
+ */
+export function AddonLayoutProvider({
+    initial = 'shell',
+    children,
+}: AddonLayoutProviderProps) {
+    const [layout, setLayout] = useState<AddonLayout>(initial)
+    const value = useMemo<AddonLayoutState>(
+        () => ({ layout, setLayout }),
+        [layout],
+    )
+    return (
+        <AddonLayoutContext.Provider value={value}>
+            {children}
+        </AddonLayoutContext.Provider>
+    )
+}
+
+/**
+ * Read the currently-active layout. The host shell calls this and decides
+ * whether to render its chrome. Returns `"shell"` when no provider is
+ * mounted, so apps that have not adopted immersive addons keep working.
+ */
+export function useAddonLayout(): AddonLayout {
+    return useContext(AddonLayoutContext).layout
+}
+
+/**
+ * Imperative API — the value returned mirrors `useAddonLayout()` but also
+ * exposes the setter for hosts that need to flip the layout outside of a
+ * route lifecycle (e.g. a hotkey forcing kiosk mode). Most addon entries do
+ * NOT need this; prefer `useDeclareAddonLayout`.
+ */
+export function useAddonLayoutControl(): AddonLayoutState {
+    return useContext(AddonLayoutContext)
+}
+
+/**
+ * Declare the layout from the addon side. Mounts the value, restores
+ * `"shell"` on unmount. Skip when `layout` is undefined so route components
+ * can pass `manifest.frontend?.layout` directly without branching.
+ *
+ *   function PosEntry({ manifest }: { manifest: Manifest }) {
+ *     useDeclareAddonLayout(manifest.frontend?.layout)
+ *     return <PosScreen />
+ *   }
+ */
+export function useDeclareAddonLayout(layout: AddonLayout | undefined): void {
+    const { setLayout } = useAddonLayoutControl()
+    // useCallback so the effect only re-runs on a real layout change, not on
+    // every render of the consumer that happens to forward an inline literal.
+    const apply = useCallback(setLayout, [setLayout])
+    useEffect(() => {
+        if (!layout || layout === 'shell') return
+        apply(layout)
+        return () => {
+            apply('shell')
+        }
+    }, [layout, apply])
+}

package/src/addon-loader.tsx

@@ -2,7 +2,8 @@
 // waits for the `window[scope]` container to initialize, then calls the
 // addon's `register(api)` export with the AddonAPI injected by the host.
 import { useEffect, useRef, useState } from 'react'
-import type { AddonAPI } from '@asteby/metacore-sdk'
+import type { AddonAPI, AddonLayout } from '@asteby/metacore-sdk'
+import { useDeclareAddonLayout } from './addon-layout-context'
 
 declare global {
     interface Window {
@@ -27,6 +28,18 @@ export interface AddonLoaderProps {
     onReady?: () => void
     /** Called if loading fails. */
     onError?: (err: Error) => void
+    /**
+     * Layout the host shell should render the addon under, mirroring
+     * `manifest.frontend.layout`. Default (undefined / `"shell"`) keeps the
+     * legacy chrome (Sidebar, Topbar, breadcrumbs). `"immersive"` flips the
+     * shared {@link useAddonLayout} context so the host shell hides chrome
+     * while the addon is mounted and restores it on unmount.
+     *
+     * Hosts that consume the context (see `useAddonLayout` /
+     * `<AddonLayoutProvider>`) do NOT need to branch on this prop themselves
+     * — the loader sets the context value via {@link useDeclareAddonLayout}.
+     */
+    layout?: AddonLayout
     children?: React.ReactNode
 }
 
@@ -75,12 +88,19 @@ export function AddonLoader({
     fallback = null,
     onReady,
     onError,
+    layout,
     children,
 }: AddonLoaderProps) {
     const [status, setStatus] = useState<'loading' | 'ready' | 'error'>('loading')
     const [error, setError] = useState<Error | null>(null)
     const didRegister = useRef(false)
 
+    // Propagate the addon's preferred layout to the host shell via context.
+    // No-op when `layout` is undefined or `"shell"` (legacy default). Cleanup
+    // restores `"shell"` automatically when the loader unmounts, so chrome
+    // returns as soon as the user navigates away from an immersive addon.
+    useDeclareAddonLayout(layout)
+
     useEffect(() => {
         let cancelled = false
         ;(async () => {

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">