@asteby/metacore-runtime-react 4.0.0

package/src/i18n-provider.tsx

@@ -0,0 +1,33 @@
+// I18nProvider — merges `manifest.i18n` resources from every loaded addon
+// into the host's i18next instance. The host passes the i18n instance; this
+// component just hydrates new namespaces and keeps them live.
+import { useEffect } from 'react'
+import type { i18n as I18nInstance } from 'i18next'
+
+export interface AddonI18nResources {
+    /** Addon key — used as the i18next namespace. */
+    source: string
+    /** Map of locale → key/value tree. */
+    resources: Record<string, Record<string, any>>
+}
+
+export interface I18nProviderProps {
+    /** The host's i18next instance. */
+    i18n: I18nInstance
+    /** All addon translations contributed via `manifest.i18n`. */
+    contributions: AddonI18nResources[]
+    children: React.ReactNode
+}
+
+export function I18nProvider({ i18n, contributions, children }: I18nProviderProps) {
+    useEffect(() => {
+        for (const c of contributions) {
+            for (const [locale, tree] of Object.entries(c.resources)) {
+                // addBundle(locale, namespace, resources, deep?, overwrite?)
+                i18n.addResourceBundle(locale, c.source, tree, true, false)
+            }
+        }
+    }, [i18n, contributions])
+
+    return <>{children}</>
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+// Public surface — keep names stable. `ActionMetadata` is intentionally
+// re-exported once from `./types` (the mirror used by runtime-react internally)
+// and NOT re-exported from `./action-modal-dispatcher` here to avoid a
+// duplicate-symbol conflict; consumers who want the canonical SDK type
+// should import from `@asteby/metacore-sdk` directly.
+export * from './types'
+export * from './options-context'
+export * from './dynamic-table'
+export * from './dynamic-form'
+export {
+    ActionModalDispatcher,
+    type ActionModalProps,
+} from './action-modal-dispatcher'
+export * from './addon-loader'
+export * from './slot'
+export * from './capability-gate'
+export * from './navigation-builder'
+export * from './i18n-provider'
+export * from './api-context'
+export * from './metadata-cache'
+export * from './dynamic-icon'
+export type {
+    ColumnFilterConfig,
+    FilterOption as DynamicColumnFilterOption,
+    GetDynamicColumns,
+    DynamicIconComponent,
+} from './dynamic-columns-shim'
+export { DynamicRecordDialog } from './dialogs/dynamic-record'
+export { ExportDialog } from './dialogs/export'
+export { ImportDialog } from './dialogs/import'

package/src/metadata-cache.ts

@@ -0,0 +1,103 @@
+// Metadata cache — a zustand store that memoizes table/modal metadata
+// responses across dynamic-table mounts. Ported from the ops starter's
+// `@/stores/metadata-cache` so the runtime-react package no longer depends
+// on a host-specific alias.
+//
+// The prefetchAll() method needs an `api` client (axios-like); we keep that
+// as an injectable parameter so the store stays host-agnostic. If a caller
+// never invokes prefetchAll, the `api` dep is not required.
+import { create } from 'zustand'
+import { persist } from 'zustand/middleware'
+import type { TableMetadata } from './types'
+
+export interface MetadataApiClient {
+    get: (url: string, config?: any) => Promise<{ data: any }>
+}
+
+interface MetadataCacheState {
+    cache: Record<string, TableMetadata>
+    modalCache: Record<string, TableMetadata>
+    metadataVersion: string
+    prefetched: boolean
+    getMetadata: (key: string) => TableMetadata | undefined
+    getModalMetadata: (key: string) => TableMetadata | undefined
+    setMetadata: (key: string, metadata: TableMetadata) => void
+    setModalMetadata: (key: string, metadata: TableMetadata) => void
+    hasMetadata: (key: string) => boolean
+    hasModalMetadata: (key: string) => boolean
+    prefetchAll: (api: MetadataApiClient) => Promise<void>
+}
+
+export const useMetadataCache = create<MetadataCacheState>()(
+    persist(
+        (set, get) => ({
+            cache: {},
+            modalCache: {},
+            metadataVersion: '',
+            prefetched: false,
+
+            getMetadata: (key: string) => get().cache[key],
+            getModalMetadata: (key: string) => get().modalCache[key],
+
+            setMetadata: (key: string, metadata: TableMetadata) => {
+                set((state) => ({
+                    cache: { ...state.cache, [key]: metadata },
+                }))
+            },
+
+            setModalMetadata: (key: string, metadata: TableMetadata) => {
+                set((state) => ({
+                    modalCache: { ...state.modalCache, [key]: metadata },
+                }))
+            },
+
+            hasMetadata: (key: string) => key in get().cache,
+            hasModalMetadata: (key: string) => key in get().modalCache,
+
+            prefetchAll: async (api: MetadataApiClient) => {
+                if (get().prefetched) return
+                try {
+                    const res = await api.get('/metadata/all')
+                    const { tables, modals, version } = res.data.data
+
+                    const serverVersion = version || ''
+                    const localVersion = get().metadataVersion
+                    const versionChanged = serverVersion !== localVersion && localVersion !== ''
+
+                    const newCache: Record<string, TableMetadata> = versionChanged ? {} : { ...get().cache }
+                    const newModalCache: Record<string, TableMetadata> = versionChanged ? {} : { ...get().modalCache }
+
+                    if (tables) {
+                        for (const [key, meta] of Object.entries(tables)) {
+                            newCache[key] = meta as TableMetadata
+                        }
+                    }
+                    if (modals) {
+                        for (const [key, meta] of Object.entries(modals)) {
+                            newModalCache[key] = meta as TableMetadata
+                        }
+                    }
+
+                    set({
+                        cache: newCache,
+                        modalCache: newModalCache,
+                        metadataVersion: serverVersion,
+                        prefetched: true,
+                    })
+                } catch {
+                    // Offline or error — keep using cached data.
+                    set({ prefetched: true })
+                }
+            },
+        }),
+        {
+            name: 'metacore-metadata-cache',
+            version: 3,
+            partialize: (state) => ({
+                cache: state.cache,
+                modalCache: state.modalCache,
+                metadataVersion: state.metadataVersion,
+            }),
+        }
+    )
+)

package/src/navigation-builder.tsx

@@ -0,0 +1,77 @@
+// NavigationBuilder — merges a host's base sidebar with `manifest.navigation`
+// contributions from every loaded addon. Pure function + a React hook.
+import { useMemo } from 'react'
+
+export interface NavItem {
+    key: string
+    label: string
+    icon?: string
+    to?: string
+    /** Sort weight; higher = earlier. Default 0. */
+    priority?: number
+    /** Capability required to see this item. */
+    requires?: string
+    /** Nested children (rendered as a collapsible section). */
+    children?: NavItem[]
+    /** Group this item belongs to — items with the same group are clustered. */
+    group?: string
+    /** Source addon key (for debugging / telemetry). */
+    source?: string
+}
+
+export interface AddonNavigationContribution {
+    source: string
+    items: NavItem[]
+}
+
+/** Deep-merge nav trees by `key`. Children are merged recursively; on
+ *  conflict the higher-priority wins, then the later contribution.
+ */
+export function mergeNavigation(base: NavItem[], contributions: AddonNavigationContribution[]): NavItem[] {
+    const byKey = new Map<string, NavItem>()
+    const order: string[] = []
+
+    const absorb = (items: NavItem[], source?: string) => {
+        for (const raw of items) {
+            const item: NavItem = { ...raw, source: raw.source ?? source }
+            const existing = byKey.get(item.key)
+            if (!existing) {
+                byKey.set(item.key, item)
+                order.push(item.key)
+                continue
+            }
+            const a = existing.priority ?? 0
+            const b = item.priority ?? 0
+            const winner = b >= a ? item : existing
+            const loser = b >= a ? existing : item
+            const mergedChildren = (winner.children || loser.children)
+                ? mergeNavigation(winner.children ?? [], [{ source: winner.source ?? '', items: loser.children ?? [] }])
+                : undefined
+            byKey.set(item.key, { ...winner, children: mergedChildren })
+        }
+    }
+
+    absorb(base, 'host')
+    for (const c of contributions) absorb(c.items, c.source)
+
+    return order
+        .map(k => byKey.get(k)!)
+        .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0))
+}
+
+export function useNavigation(base: NavItem[], contributions: AddonNavigationContribution[]): NavItem[] {
+    return useMemo(() => mergeNavigation(base, contributions), [base, contributions])
+}
+
+export interface NavigationBuilderProps {
+    base: NavItem[]
+    contributions: AddonNavigationContribution[]
+    render: (items: NavItem[]) => React.ReactNode
+}
+
+/** Render-prop component for hosts that want the merge logic but render
+ *  the sidebar with their own primitives. */
+export function NavigationBuilder({ base, contributions, render }: NavigationBuilderProps) {
+    const items = useNavigation(base, contributions)
+    return <>{render(items)}</>
+}

package/src/options-context.tsx

@@ -0,0 +1,11 @@
+import React from 'react'
+
+interface OptionsContextValue {
+    optionsMap: Map<string, any[]>
+}
+
+export const OptionsContext = React.createContext<OptionsContextValue>({
+    optionsMap: new Map(),
+})
+
+export const useOptions = () => React.useContext(OptionsContext)

package/src/slot.tsx

@@ -0,0 +1,77 @@
+// Slot / SlotRegistry — named extension points the host renders and addons
+// contribute to at register() time. Keyed by a slot id (e.g. "dashboard.widgets",
+// "invoice.footer"). Each contribution is an arbitrary React element factory.
+import React, { useSyncExternalStore } from 'react'
+
+export type SlotComponent<P = any> = React.ComponentType<P>
+
+interface SlotEntry {
+    id: string
+    component: SlotComponent
+    priority: number
+    source?: string
+}
+
+type Listener = () => void
+
+class SlotRegistryImpl {
+    private slots = new Map<string, SlotEntry[]>()
+    private listeners = new Set<Listener>()
+
+    register(slotId: string, component: SlotComponent, opts?: { priority?: number; source?: string }): () => void {
+        const entry: SlotEntry = { id: slotId, component, priority: opts?.priority ?? 0, source: opts?.source }
+        const list = this.slots.get(slotId) ?? []
+        list.push(entry)
+        list.sort((a, b) => b.priority - a.priority)
+        this.slots.set(slotId, list)
+        this.emit()
+        return () => {
+            const arr = this.slots.get(slotId)
+            if (!arr) return
+            const idx = arr.indexOf(entry)
+            if (idx >= 0) {
+                arr.splice(idx, 1)
+                this.emit()
+            }
+        }
+    }
+
+    get(slotId: string): SlotEntry[] {
+        return this.slots.get(slotId) ?? []
+    }
+
+    subscribe(listener: Listener): () => void {
+        this.listeners.add(listener)
+        return () => { this.listeners.delete(listener) }
+    }
+
+    private emit() { this.listeners.forEach(l => l()) }
+}
+
+export const slotRegistry = new SlotRegistryImpl()
+
+export interface SlotProps {
+    /** Slot id. */
+    name: string
+    /** Props forwarded to each contribution component. */
+    props?: Record<string, any>
+    /** Fallback element shown when no contribution is registered. */
+    fallback?: React.ReactNode
+}
+
+export function Slot({ name, props, fallback = null }: SlotProps) {
+    const entries = useSyncExternalStore(
+        (cb) => slotRegistry.subscribe(cb),
+        () => slotRegistry.get(name),
+        () => slotRegistry.get(name),
+    )
+    if (entries.length === 0) return <>{fallback}</>
+    return (
+        <>
+            {entries.map((entry, i) => {
+                const C = entry.component
+                return <C key={`${entry.source ?? 'anon'}-${i}`} {...(props ?? {})} />
+            })}
+        </>
+    )
+}

package/src/types.ts

@@ -0,0 +1,112 @@
+// Union of the two host copies (link + ops). Ops adds the `link` action type + `linkUrl`.
+export interface TableMetadata {
+    title: string
+    endpoint: string
+    columns: ColumnDefinition[]
+    actions: ActionDefinition[]
+    filters?: FilterDefinition[]
+    perPageOptions: number[]
+    defaultPerPage: number
+    searchPlaceholder: string
+    enableCRUDActions: boolean
+    hasActions: boolean
+    canExport?: boolean
+    canImport?: boolean
+    canCreate?: boolean
+}
+
+export interface FilterDefinition {
+    key: string
+    label: string
+    type: 'select' | 'boolean' | 'date_range' | 'number_range' | 'text'
+    column: string
+    options?: { value: string | boolean; label: string; icon?: string; color?: string }[]
+    searchEndpoint?: string
+}
+
+export interface ColumnDefinition {
+    key: string
+    label: string
+    type: 'text' | 'number' | 'date' | 'select' | 'search' | 'relation-badge-list' | 'avatar' | 'boolean' | 'phone' | 'media-gallery' | 'image'
+    sortable: boolean
+    filterable: boolean
+    hidden?: boolean
+    styleConfig?: Record<string, any>
+    tooltip?: string
+    description?: string
+    cellStyle?: string
+    searchEndpoint?: string
+    filterField?: string
+    basePath?: string
+    displayField?: string
+    iconField?: string
+    relationPath?: string
+    useOptions?: boolean
+    options?: { value: string; label: string; icon?: string; color?: string }[]
+}
+
+export interface ActionCondition {
+    field: string
+    operator: 'eq' | 'neq' | 'in' | 'not_in'
+    value: string | string[]
+}
+
+export interface ActionFieldDef {
+    key: string
+    label: string
+    type: string
+    required?: boolean
+    options?: { value: string; label: string }[]
+    defaultValue?: any
+    placeholder?: string
+    searchEndpoint?: string
+}
+
+export interface ActionDefinition {
+    key: string
+    name: string
+    label: string
+    icon: string
+    class: string
+    color?: string
+    type: 'view' | 'edit' | 'delete' | 'custom' | 'link'
+    linkUrl?: string
+    condition?: ActionCondition
+    confirm?: boolean
+    confirmMessage?: string
+    fields?: ActionFieldDef[]
+    requiresState?: string[]
+    executable?: boolean
+}
+
+export interface ApiResponse<T> {
+    success: boolean
+    data: T
+    meta?: PaginationMeta
+    filters?: Record<string, any>
+    message?: string
+}
+
+export interface PaginationMeta {
+    current_page: number
+    from: number
+    last_page: number
+    per_page: number
+    to: number
+    total: number
+}
+
+// ActionMetadata re-exported from the sdk's action-registry. We mirror the
+// subset needed for the dispatcher so consumers of runtime-react don't have to
+// import the sdk directly for prop typings.
+export interface ActionMetadata {
+    key: string
+    label: string
+    icon: string
+    color?: string
+    confirm?: boolean
+    confirmMessage?: string
+    fields?: ActionFieldDef[]
+    requiresState?: string[]
+    executable?: boolean
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"]
+}