@asteby/metacore-runtime-react 9.1.0 → 10.0.0

package/CHANGELOG.md

@@ -1,5 +1,180 @@
 # @asteby/metacore-runtime-react
 
+## 10.0.0
+
+### Minor Changes
+
+- 9ce8269: feat: hot-swap reload policy (RFC-0001 D4 close)
+
+  Closes the gap between `useManifestHotSwapSubscriber` (already invalidates
+  the metadata cache) and the federation container of an already-mounted
+  addon, which keeps the old code in memory until something forces a
+  re-evaluation.
+
+  **runtime-react:**
+  - New `hotswap-reload-policy` module ships three policies and a single
+    hook that wires the chosen policy to the manifest hot-swap stream:
+    - `useHotSwapReload(client, { strategy })` returns `{ addonVersionMap }`
+      — a reactive map `addonKey → hashShort` that hosts wire into
+      `<AddonRoute version={addonVersionMap[addonKey]} ... />`. Default
+      strategy is `"rekey"`: React unmounts and remounts the addon subtree
+      on every swap, which forces the federation loader to re-fetch
+      `remoteEntry.js?v=<hash8>` and re-evaluate the exposed module.
+    - `strategy: "page-reload"` is an opt-in `window.location.reload()`
+      escape hatch for immersive addons with critical in-progress state
+      (POS, kitchen-display). Pair with `onBeforeReload` to surface an
+      "unsaved changes" prompt — returning `false` cancels the reload.
+    - `strategy: "manual"` only invokes `onSwap` with the message;
+      the host decides what to do.
+  - `clearFederationContainer(scope)` helper for hosts that hit
+    `Container already registered` after a re-key; call it from the
+    `onSwap` callback before the addon route re-mounts.
+  - `applyHotSwapReload` exported for non-React shells that want to
+    drive the policy from a vanilla container.
+
+  **sdk:**
+  - `loadFederatedAddon(spec, addonKey, version?)` accepts an optional
+    `version` so the loader cache-busts `remoteEntry.js` via
+    `?v=<hash8>` when the manifest hash bumps. Cache key includes the
+    version so a fresh hash triggers a fresh load instead of returning
+    the memoized old container.
+  - New `withVersionParam(url, hash)` helper (idempotent, fragment-safe,
+    replaces prior `v=` entries) exported for symmetry — the
+    runtime-react module re-uses the same algorithm.
+
+  **starter-core:**
+  - `<AddonRoute>` accepts a new optional `version?: string` prop. When
+    it changes, the route's children are wrapped in a `Fragment` with a
+    new `key`, forcing the federation loader to re-evaluate.
+
+  ### Host wire-up (4-5 lines)
+
+  ```tsx
+  const ws = useWebSocket()
+  useManifestHotSwapSubscriber(ws)                         // metadata cache
+  const { addonVersionMap } = useHotSwapReload(ws, { strategy: 'rekey' })
+  // …in your router:
+  <AddonRoute version={addonVersionMap[addonKey]} shell={renderShell}>
+    <AddonLoader scope={addonKey} url={remoteEntryUrl} api={api} />
+  </AddonRoute>
+  ```
+
+  Re-keying is intentionally destructive: any state inside the addon is
+  lost because the code version changed. Hosts that need a confirmation
+  gate should pass `onBeforeReload` and prompt the user before the swap
+  applies.
+
+- 04362f2: feat: immersive layout, federation shared-deps helper polish, wasm client
+
+  **sdk:**
+  - `FrontendSpec` now carries `layout?: "shell" | "immersive"`. Mirrors the
+    upcoming kernel-side `manifest.FrontendSpec.Layout` field. `undefined` is
+    treated as `"shell"` (legacy behaviour) so the change is purely additive.
+    Exposed as the `AddonLayout` type alias for explicit consumers.
+  - New `wasm-client` module — frontend twin of `kernel/runtime/wasm`. Ships
+    `loadAddonWasm({ url, integrity, imports })` (SRI verification + instantiate
+    pipeline) and `callAddonExport(instance, fn, payload)` honouring the same
+    `ptr<<32 | len` packed ABI the Go example backends use (`alloc`, `free`,
+    `memory`). Lets POS / kitchen-display / signage addons run their compiled
+    module locally for sub-50ms latency without a webhook round trip. Typed
+    errors (`WasmIntegrityError`, `WasmAbiError`) surface failure cause cleanly.
+
+  **runtime-react:**
+  - New `<AddonLayoutProvider>`, `useAddonLayout()`, `useAddonLayoutControl()`
+    and `useDeclareAddonLayout()` API in `addon-layout-context`. The host shell
+    reads the active layout and hides Sidebar / Topbar / breadcrumbs when an
+    addon declares `layout: "immersive"`. Cleanup restores chrome on unmount,
+    so navigating away from an immersive addon brings the shell back.
+  - `<AddonLoader>` accepts an optional `layout` prop and propagates it through
+    the context, so hosts get the chrome switch wired without per-route plumbing.
+
+  **starter-config:**
+  - `metacoreFederationShared()` now accepts `extra: Record<string, ShareConfig>`
+    for the typical "I just want to add a package with explicit config" case
+    (`extra: { lodash: { singleton: true } }`). The existing `extras: string[]`
+    and `overrides` knobs are retained for backwards compatibility.
+  - `METACORE_FEDERATION_SINGLETONS` adds `@asteby/metacore-app-providers` so
+    the SDK's transport-agnostic platform provider keeps a single instance
+    between host and addons.
+
+- ba60c8f: feat: immersive route wrapper + manifest hot-swap subscriber (RFC-0001 D1 + D4)
+
+  **runtime-react:**
+  - `metadata-cache` gains `invalidateAddon(addonKey, matcher?)` and `clearAll()`
+    so consumers can flush scoped cache entries when an addon's manifest hash
+    changes. The default matcher recognises `addonKey`, `${addonKey}.`,
+    `${addonKey}:` and `${addonKey}/` prefixes; hosts that namespace their
+    `model` keys differently can pass a custom matcher.
+  - New `manifest-hotswap-subscriber` module ships:
+    - `ADDON_MANIFEST_CHANGED_TYPE` — the `ws.MessageType` constant the kernel
+      emits via `bridge.WSManifestBroadcaster`.
+    - `wireHotSwapInvalidation(client, options?)` — imperative helper hosts call
+      once at boot. Accepts any object exposing `subscribe(type, handler)`
+      (structurally compatible with `useWebSocket().subscribe`), invalidates
+      the metadata cache for the bumped addon, and optionally invokes an
+      `onSwap` side-effect callback (handy for forcing a `window.location.reload()`
+      when the running addon's bundle hash changes, since metadata invalidation
+      alone does not swap the federation container already in memory).
+    - `useManifestHotSwapSubscriber(client)` — React hook variant for hosts
+      that prefer mounting the wire-up next to their WebSocket provider.
+
+  **starter-core:**
+  - New `AddonRoute` component closes the host side of RFC-0001 D1 (immersive
+    end-to-end). It reads `useAddonLayout()` from runtime-react and either
+    renders the addon inside a caller-provided shell renderer (default
+    `"shell"` layout) or strips chrome and pins the addon to the viewport
+    (`fixed inset-0 z-50`) when the active layout is `"immersive"`. Supports
+    both prop-driven layout (no shell flash for always-immersive routes like
+    POS / kitchen-display) and context-driven layout (addon calls
+    `useDeclareAddonLayout("immersive")` after mount). Cleanup restores
+    `"shell"` so navigating away brings the chrome back.
+
+  Together these closures unblock zero-polling hot-swap reloads in the
+  metadata layer and let immersive addons own the viewport without each app
+  re-implementing the shell branch.
+
+### Patch Changes
+
+- Updated dependencies [9ce8269]
+- Updated dependencies [04362f2]
+  - @asteby/metacore-sdk@2.5.0
+
+## 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/addon-layout-context.d.ts

@@ -0,0 +1,49 @@
+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;
+}
+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 declare function AddonLayoutProvider({ initial, children, }: AddonLayoutProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * 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 declare function useAddonLayout(): AddonLayout;
+/**
+ * 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 declare function useAddonLayoutControl(): AddonLayoutState;
+/**
+ * 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 declare function useDeclareAddonLayout(layout: AddonLayout | undefined): void;
+//# sourceMappingURL=addon-layout-context.d.ts.map

package/dist/addon-layout-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addon-layout-context.d.ts","sourceRoot":"","sources":["../src/addon-layout-context.tsx"],"names":[],"mappings":"AA2CA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAEvD,YAAY,EAAE,WAAW,EAAE,CAAA;AAE3B,UAAU,gBAAgB;IACtB,2DAA2D;IAC3D,MAAM,EAAE,WAAW,CAAA;IACnB;;;;;OAKG;IACH,SAAS,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAA;CAC3C;AAWD,MAAM,WAAW,wBAAwB;IACrC,0CAA0C;IAC1C,OAAO,CAAC,EAAE,WAAW,CAAA;IACrB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAChC,OAAiB,EACjB,QAAQ,GACX,EAAE,wBAAwB,2CAW1B;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,WAAW,CAE5C;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,gBAAgB,CAExD;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,IAAI,CAY3E"}

package/dist/addon-layout-context.js

@@ -0,0 +1,94 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// 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';
+const defaultState = {
+    layout: 'shell',
+    setLayout: () => {
+        /* noop — provider missing; consumers degrade to legacy "shell" */
+    },
+};
+const AddonLayoutContext = createContext(defaultState);
+/**
+ * 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, }) {
+    const [layout, setLayout] = useState(initial);
+    const value = useMemo(() => ({ layout, setLayout }), [layout]);
+    return (_jsx(AddonLayoutContext.Provider, { value: value, children: children }));
+}
+/**
+ * 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() {
+    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() {
+    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) {
+    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/dist/addon-loader.d.ts

@@ -1,4 +1,4 @@
-import type { AddonAPI } from '@asteby/metacore-sdk';
+import type { AddonAPI, AddonLayout } from '@asteby/metacore-sdk';
 declare global {
     interface Window {
         [key: string]: any;
@@ -21,7 +21,19 @@ 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;
 }
-export declare function AddonLoader({ scope, url, module, api, fallback, onReady, onError, children, }: AddonLoaderProps): import("react/jsx-runtime").JSX.Element;
+export declare function AddonLoader({ scope, url, module, api, fallback, onReady, onError, layout, children, }: AddonLoaderProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=addon-loader.d.ts.map

package/dist/addon-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"addon-loader.d.ts","sourceRoot":"","sources":["../src/addon-loader.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AAEpD,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,MAAM;QACZ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;QAClB,wBAAwB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;QAC3D,wBAAwB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KACrD;CACJ;AAED,MAAM,WAAW,gBAAgB;IAC7B,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAA;IACb,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAA;IACX,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,+DAA+D;IAC/D,GAAG,EAAE,QAAQ,CAAA;IACb,wCAAwC;IACxC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC1B,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAA;IAC9B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC7B;AAuCD,wBAAgB,WAAW,CAAC,EACxB,KAAK,EACL,GAAG,EACH,MAAqB,EACrB,GAAG,EACH,QAAe,EACf,OAAO,EACP,OAAO,EACP,QAAQ,GACX,EAAE,gBAAgB,2CAgClB"}
+{"version":3,"file":"addon-loader.d.ts","sourceRoot":"","sources":["../src/addon-loader.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAGjE,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,MAAM;QACZ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;QAClB,wBAAwB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;QAC3D,wBAAwB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KACrD;CACJ;AAED,MAAM,WAAW,gBAAgB;IAC7B,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAA;IACb,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAA;IACX,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,+DAA+D;IAC/D,GAAG,EAAE,QAAQ,CAAA;IACb,wCAAwC;IACxC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC1B,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAA;IAC9B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC7B;AAuCD,wBAAgB,WAAW,CAAC,EACxB,KAAK,EACL,GAAG,EACH,MAAqB,EACrB,GAAG,EACH,QAAe,EACf,OAAO,EACP,OAAO,EACP,MAAM,EACN,QAAQ,GACX,EAAE,gBAAgB,2CAsClB"}

package/dist/addon-loader.js

@@ -3,6 +3,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 // 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 { useDeclareAddonLayout } from './addon-layout-context';
 const loadedScripts = new Map();
 function loadScript(url, scope) {
     const key = `${scope}::${url}`;
@@ -34,10 +35,15 @@ async function loadRemote(scope, module) {
     const factory = await container.get(module);
     return factory();
 }
-export function AddonLoader({ scope, url, module = './register', api, fallback = null, onReady, onError, children, }) {
+export function AddonLoader({ scope, url, module = './register', api, fallback = null, onReady, onError, layout, children, }) {
     const [status, setStatus] = useState('loading');
     const [error, setError] = useState(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/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"}