@asteby/metacore-runtime-react 9.0.0 → 9.2.0

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,
+    };
+}

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

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

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

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

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

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

package/package.json

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

package/src/__tests__/column-visibility.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect } from 'vitest'
+
+import {
+    isColumnVisibleInTable,
+    getSearchableColumnKeys,
+} from '../column-visibility'
+import type { ColumnDefinition, TableMetadata } from '../types'
+
+const baseCol = (overrides: Partial<ColumnDefinition> = {}): ColumnDefinition => ({
+    key: 'name',
+    label: 'Name',
+    type: 'text',
+    sortable: true,
+    filterable: false,
+    ...overrides,
+})
+
+const baseMeta = (columns: ColumnDefinition[]): TableMetadata => ({
+    title: 'Mock',
+    endpoint: '/data/mock',
+    columns,
+    actions: [],
+    perPageOptions: [10],
+    defaultPerPage: 10,
+    searchPlaceholder: 'Search…',
+    enableCRUDActions: true,
+    hasActions: false,
+})
+
+describe('isColumnVisibleInTable', () => {
+    it('keeps columns with no visibility flag (legacy zero-value)', () => {
+        expect(isColumnVisibleInTable(baseCol())).toBe(true)
+    })
+
+    it('keeps columns with visibility="all"', () => {
+        expect(isColumnVisibleInTable(baseCol({ visibility: 'all' }))).toBe(true)
+    })
+
+    it('keeps columns with visibility="table"', () => {
+        expect(isColumnVisibleInTable(baseCol({ visibility: 'table' }))).toBe(true)
+    })
+
+    it('hides columns with visibility="modal"', () => {
+        expect(isColumnVisibleInTable(baseCol({ visibility: 'modal' }))).toBe(false)
+    })
+
+    it('hides columns with visibility="list"', () => {
+        expect(isColumnVisibleInTable(baseCol({ visibility: 'list' }))).toBe(false)
+    })
+
+    it('hides columns with the legacy hidden boolean even if visibility="all"', () => {
+        expect(isColumnVisibleInTable(baseCol({ hidden: true, visibility: 'all' }))).toBe(false)
+    })
+
+    it('hides columns with an unknown visibility value (fail-closed)', () => {
+        expect(isColumnVisibleInTable(baseCol({ visibility: 'detail' as any }))).toBe(false)
+    })
+})
+
+describe('getSearchableColumnKeys', () => {
+    it('returns null when no column declares searchable (legacy metadata)', () => {
+        const meta = baseMeta([
+            baseCol({ key: 'name' }),
+            baseCol({ key: 'email' }),
+        ])
+        expect(getSearchableColumnKeys(meta)).toBe(null)
+    })
+
+    it('returns only the searchable keys when at least one column declares it', () => {
+        const meta = baseMeta([
+            baseCol({ key: 'name', searchable: true }),
+            baseCol({ key: 'email', searchable: true }),
+            baseCol({ key: 'phone', searchable: false }),
+            baseCol({ key: 'created_at' }), // undefined → not searchable
+        ])
+        expect(getSearchableColumnKeys(meta)).toEqual(['name', 'email'])
+    })
+
+    it('returns an empty array when every column is explicitly opted out', () => {
+        const meta = baseMeta([
+            baseCol({ key: 'name', searchable: false }),
+            baseCol({ key: 'email', searchable: false }),
+        ])
+        expect(getSearchableColumnKeys(meta)).toEqual([])
+    })
+
+    it('treats searchable=true on a single column as the explicit allowlist', () => {
+        const meta = baseMeta([
+            baseCol({ key: 'name', searchable: true }),
+            baseCol({ key: 'internal_notes' }),
+        ])
+        expect(getSearchableColumnKeys(meta)).toEqual(['name'])
+    })
+
+    it('handles missing columns array defensively', () => {
+        const meta = { columns: undefined as unknown as ColumnDefinition[] }
+        expect(getSearchableColumnKeys(meta as any)).toBe(null)
+    })
+})
+
+describe('column-visibility integration with mock metadata', () => {
+    it('filtering and search keys can be derived from a single mock', () => {
+        const meta = baseMeta([
+            baseCol({ key: 'id', visibility: 'list', searchable: false }),
+            baseCol({ key: 'name', visibility: 'all', searchable: true }),
+            baseCol({ key: 'email', visibility: 'table', searchable: true }),
+            baseCol({ key: 'password_hash', visibility: 'modal', searchable: false }),
+            baseCol({ key: 'profile', visibility: 'modal', searchable: false }),
+        ])
+
+        const tableColumns = meta.columns.filter(isColumnVisibleInTable).map(c => c.key)
+        expect(tableColumns).toEqual(['name', 'email'])
+
+        expect(getSearchableColumnKeys(meta)).toEqual(['name', 'email'])
+    })
+})

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

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

package/src/column-visibility.ts

@@ -0,0 +1,43 @@
+// Pure helpers that map kernel `manifest.ColumnDef` metadata flags
+// (Visibility, Searchable) into client-side decisions:
+//   - which columns the dynamic table should render
+//   - which column keys are in scope for the global search
+//
+// Kept side-effect free and free of React/UI imports so the same logic can
+// be tested with plain unit tests against mock metadata.
+
+import type { ColumnDefinition, TableMetadata } from './types'
+
+/**
+ * Whether a column should render in a list/index table view.
+ *
+ * A column is hidden when its `visibility` is scoped away from the table
+ * (`'modal'`: only the create/edit dialog; `'list'`: only API payloads) or
+ * when the legacy `hidden` boolean is set. Empty / `'all'` / `'table'` keep
+ * the column visible — preserving zero-value behaviour for metadata emitted
+ * by older kernels that don't set `visibility` at all.
+ */
+export function isColumnVisibleInTable(col: ColumnDefinition): boolean {
+    if (col.hidden) return false
+    const v = col.visibility
+    if (!v) return true
+    return v === 'all' || v === 'table'
+}
+
+/**
+ * Returns the keys of columns that opt into the model's full-text search,
+ * or `null` when no column declares `searchable` at all.
+ *
+ * `null` is the legacy signal: the host should NOT narrow the search request
+ * (every column participates, matching pre-Searchable kernels). An empty
+ * array is meaningful — it means every column has been explicitly opted out
+ * and the host should disable the global search input.
+ */
+export function getSearchableColumnKeys(
+    metadata: Pick<TableMetadata, 'columns'>,
+): string[] | null {
+    const cols = metadata.columns ?? []
+    const declared = cols.some(c => typeof c.searchable === 'boolean')
+    if (!declared) return null
+    return cols.filter(c => c.searchable === true).map(c => c.key)
+}

package/src/dynamic-columns.tsx

@@ -35,6 +35,7 @@ import { generateBadgeStyles, getInitials } from '@asteby/metacore-ui/lib'
 import { OptionsContext } from './options-context'
 import { DynamicIcon } from './dynamic-icon'
 import type { TableMetadata, ColumnDefinition } from './types'
+import { isColumnVisibleInTable } from './column-visibility'
 import type {
     ColumnFilterConfig,
     GetDynamicColumns,
@@ -221,7 +222,9 @@ export function makeDefaultGetDynamicColumns(
         ]
 
         metadata.columns.forEach((col) => {
-            if (col.hidden) return
+            // Honors both the legacy `hidden` boolean and the kernel's
+            // `visibility` scope (skips `'modal'` and `'list'`).
+            if (!isColumnVisibleInTable(col)) return
 
             const translatedLabel = col.label
             const filterConfig = filterConfigs?.get(col.key)