@asteby/metacore-runtime-react 6.0.0 → 6.4.0

package/src/dynamic-crud-page.tsx

@@ -0,0 +1,275 @@
+// DynamicCRUDPage — drop-in route component for any model that has
+// `DefineTable` metadata on the backend. Pulls the title and CRUD flag
+// from `/metadata/table/<model>`, mounts <DynamicTable>, wires
+// `<DynamicRecordDialog>` for create, and exposes `<ExportDialog>` /
+// `<ImportDialog>` from a single toolbar.
+//
+// The whole thing exists so apps stop reinventing the same ~150 LOC of
+// page chrome around DynamicTable. Override anything via props:
+//
+//   <DynamicCRUDPage
+//     model="customers"
+//     endpoint="/dynamic/customers"        // default: /dynamic/<model>
+//     title="Mis clientes"                 // default: metadata.title
+//     newLabel="Nuevo cliente"             // default: "New <singular>"
+//     hideExport hideImport hideCreate     // toolbar trimming
+//     headerExtras={<MyBranchSwitcher />}  // injected before the title row
+//     toolbarExtras={<MyExtraActions />}   // injected before "Nuevo X"
+//     i18n={{ refresh: 'Refrescar', export: 'Exportar', ... }}
+//     onChange={() => analytics.track('table.refresh')}
+//   />
+//
+// Apps that only need to swap the create endpoint or hide a button keep
+// the boilerplate to one line. Apps that need richer per-model headers
+// register a model-extension registry and feed it via `headerExtras`.
+import React, {
+    useCallback,
+    useEffect,
+    useMemo,
+    useState,
+} from 'react'
+import { Plus, Download, Upload, RefreshCw } from 'lucide-react'
+import { useApi } from './api-context'
+import { useMetadataCache } from './metadata-cache'
+import { DynamicTable } from './dynamic-table'
+import { DynamicRecordDialog } from './dialogs/dynamic-record'
+import { ExportDialog } from './dialogs/export'
+import { ImportDialog } from './dialogs/import'
+import { getModelExtension } from './model-extension-registry'
+import type { TableMetadata } from './types'
+
+export interface DynamicCRUDPageStrings {
+    refresh?: string
+    export?: string
+    import?: string
+    /** Used as the create button label when `newLabel` is not provided.
+     *  Receives the singular form of the title. */
+    newPrefix?: string
+}
+
+const defaultStrings: Required<DynamicCRUDPageStrings> = {
+    refresh: 'Refresh',
+    export: 'Export',
+    import: 'Import',
+    newPrefix: 'New',
+}
+
+export interface DynamicCRUDPageClasses {
+    root?: string
+    container?: string
+    header?: string
+    title?: string
+    toolbar?: string
+    tableWrapper?: string
+}
+
+export interface DynamicCRUDPageProps {
+    /** Model key as registered on the backend (e.g. "customers"). */
+    model: string
+    /** Override the data endpoint. Defaults to `/dynamic/<model>`. */
+    endpoint?: string
+    /** Override the human title. Defaults to `metadata.title`. */
+    title?: string
+    /** Override the create button label. Defaults to `${newPrefix} ${singular}`. */
+    newLabel?: string
+    /** Strings used in default labels — pass when the host has its own i18n. */
+    i18n?: DynamicCRUDPageStrings
+    /** Hide the create button + dialog even when metadata says CRUD is enabled. */
+    hideCreate?: boolean
+    hideExport?: boolean
+    hideImport?: boolean
+    hideRefresh?: boolean
+    /** Slot rendered above the title row (e.g. branch switcher, kpi strip). */
+    headerExtras?: React.ReactNode
+    /** Slot rendered in the toolbar, before the create button. */
+    toolbarExtras?: React.ReactNode
+    /** Tailwind class overrides for layout primitives. */
+    classes?: DynamicCRUDPageClasses
+    /** Fired after a create/import/refresh successfully reloads the table. */
+    onChange?: () => void
+}
+
+/**
+ * Page-level CRUD shell wired around <DynamicTable>. Hosts mount a single
+ * `<DynamicCRUDPage model="..." />` per route and the SDK takes care of
+ * metadata fetch, dialogs and toolbar.
+ */
+export function DynamicCRUDPage(props: DynamicCRUDPageProps) {
+    const {
+        model,
+        endpoint,
+        title: titleOverride,
+        newLabel,
+        i18n,
+        hideCreate,
+        hideExport,
+        hideImport,
+        hideRefresh,
+        headerExtras,
+        toolbarExtras,
+        classes,
+        onChange,
+    } = props
+
+    const strings = { ...defaultStrings, ...(i18n ?? {}) }
+    const dataEndpoint = endpoint ?? `/dynamic/${model}`
+    const ext = getModelExtension(model)
+
+    const api = useApi()
+    const cachedMeta = useMetadataCache((s) => s.getMetadata(model))
+
+    const [metadata, setMetadata] = useState<TableMetadata | null>(cachedMeta ?? null)
+    const [refreshKey, setRefreshKey] = useState(0)
+    const [openCreate, setOpenCreate] = useState(false)
+    const [openExport, setOpenExport] = useState(false)
+    const [openImport, setOpenImport] = useState(false)
+
+    useEffect(() => {
+        if (cachedMeta) {
+            setMetadata(cachedMeta)
+            return
+        }
+        let cancelled = false
+        api
+            .get(`/metadata/table/${model}`)
+            .then((res) => {
+                if (cancelled) return
+                const meta = (res.data?.data ?? res.data) as TableMetadata
+                setMetadata(meta ?? null)
+            })
+            .catch(() => {
+                if (!cancelled) setMetadata(null)
+            })
+        return () => {
+            cancelled = true
+        }
+    }, [model, cachedMeta, api])
+
+    const title = titleOverride ?? ext?.title ?? metadata?.title ?? model
+    const resolvedNewLabel = newLabel ?? ext?.newLabel
+    const singular = useMemo(() => {
+        const t = title.replace(/s$/i, '')
+        return t.charAt(0).toUpperCase() + t.slice(1)
+    }, [title])
+
+    const enableCRUD = metadata?.enableCRUDActions ?? false
+    const effectiveHideCreate = hideCreate || ext?.hideCreate
+    const effectiveHideExport = hideExport || ext?.hideExport
+    const effectiveHideImport = hideImport || ext?.hideImport
+    const effectiveHideRefresh = hideRefresh || ext?.hideRefresh
+    const showCreate = enableCRUD && !effectiveHideCreate
+    const showImport = enableCRUD && !effectiveHideImport
+    const showExport = !effectiveHideExport
+    const showRefresh = !effectiveHideRefresh
+
+    const handleRefresh = useCallback(() => {
+        setRefreshKey((k) => k + 1)
+        onChange?.()
+    }, [onChange])
+
+    const rootCls = classes?.root ?? 'flex flex-col h-full overflow-hidden'
+    const containerCls = classes?.container ?? 'flex flex-col flex-1 p-6 lg:p-8 gap-4 overflow-hidden'
+    const headerCls = classes?.header ?? 'flex items-center justify-between shrink-0'
+    const titleCls = classes?.title ?? 'text-2xl font-bold tracking-tight'
+    const toolbarCls = classes?.toolbar ?? 'flex items-center gap-2'
+    const tableWrapperCls = classes?.tableWrapper ?? 'flex-1 min-h-0'
+
+    return (
+        <div className={rootCls}>
+            <div className={containerCls}>
+                {ext?.headerExtras && <ext.headerExtras model={model} onRefresh={handleRefresh} />}
+                {headerExtras}
+                <div className={headerCls}>
+                    {metadata ? (
+                        <h1 className={titleCls}>{title}</h1>
+                    ) : (
+                        <div className='h-8 w-48 bg-muted rounded animate-pulse' />
+                    )}
+                    <div className={toolbarCls}>
+                        {showRefresh && (
+                            <button
+                                type='button'
+                                onClick={handleRefresh}
+                                aria-label={strings.refresh}
+                                className='inline-flex items-center justify-center size-9 rounded-md border border-border bg-background hover:bg-accent text-foreground'
+                            >
+                                <RefreshCw className='size-4' />
+                            </button>
+                        )}
+                        {metadata && showExport && (
+                            <button
+                                type='button'
+                                onClick={() => setOpenExport(true)}
+                                className='inline-flex items-center gap-2 h-9 px-3 rounded-md border border-border bg-background hover:bg-accent text-sm font-medium text-foreground'
+                            >
+                                <Download className='size-4' />
+                                {strings.export}
+                            </button>
+                        )}
+                        {metadata && showImport && (
+                            <button
+                                type='button'
+                                onClick={() => setOpenImport(true)}
+                                className='inline-flex items-center gap-2 h-9 px-3 rounded-md border border-border bg-background hover:bg-accent text-sm font-medium text-foreground'
+                            >
+                                <Upload className='size-4' />
+                                {strings.import}
+                            </button>
+                        )}
+                        {ext?.toolbarExtras && <ext.toolbarExtras model={model} onRefresh={handleRefresh} />}
+                        {toolbarExtras}
+                        {showCreate && (
+                            <button
+                                type='button'
+                                onClick={() => setOpenCreate(true)}
+                                className='inline-flex items-center gap-2 h-9 px-3 rounded-md bg-primary text-primary-foreground hover:opacity-90 text-sm font-medium'
+                            >
+                                <Plus className='size-4' />
+                                {resolvedNewLabel ?? `${strings.newPrefix} ${singular}`}
+                            </button>
+                        )}
+                    </div>
+                </div>
+
+                <div className={tableWrapperCls}>
+                    <DynamicTable
+                        key={model}
+                        model={model}
+                        endpoint={dataEndpoint}
+                        refreshTrigger={refreshKey}
+                    />
+                </div>
+            </div>
+
+            {showCreate && (
+                <DynamicRecordDialog
+                    open={openCreate}
+                    onOpenChange={setOpenCreate}
+                    mode='create'
+                    model={model}
+                    endpoint={dataEndpoint}
+                    onSaved={handleRefresh}
+                />
+            )}
+
+            {metadata && showExport && (
+                <ExportDialog
+                    open={openExport}
+                    onOpenChange={setOpenExport}
+                    model={model}
+                    metadata={metadata}
+                />
+            )}
+
+            {metadata && showImport && (
+                <ImportDialog
+                    open={openImport}
+                    onOpenChange={setOpenImport}
+                    model={model}
+                    metadata={metadata}
+                    onImported={handleRefresh}
+                />
+            )}
+        </div>
+    )
+}

package/src/dynamic-table.tsx

@@ -1,6 +1,6 @@
 // DynamicTable — metadata-driven CRUD table used by every metacore host.
-// Ported from the ops starter but with the host-specific aliases swapped
-// for metacore packages + context-injected peer deps:
+// Originally extracted from a host app and generalized so the host-specific
+// aliases are swapped for metacore packages + context-injected peer deps:
 //   * `@/lib/api` → <ApiProvider> (see api-context.tsx)
 //   * `@/stores/branch-store` → <BranchProvider> (optional)
 //   * `@/stores/metadata-cache` → internal ./metadata-cache zustand store
@@ -65,6 +65,7 @@ import { Progress } from './dialogs/_primitives'
 import { useMetadataCache } from './metadata-cache'
 import { useApi, useCurrentBranch } from './api-context'
 import type { ColumnFilterConfig, GetDynamicColumns } from './dynamic-columns-shim'
+import { defaultGetDynamicColumns } from './dynamic-columns'
 import { OptionsContext } from './options-context'
 import { ActionModalDispatcher } from './action-modal-dispatcher'
 import type { TableMetadata, ApiResponse, ActionMetadata } from './types'
@@ -477,8 +478,12 @@ export function DynamicTable({
 
     const columnFilterConfigs = useMemo(() => {
         const map = new Map<string, ColumnFilterConfig>()
-        if (!metadata?.filters) return map
-        for (const f of metadata.filters) {
+        if (!metadata) return map
+        // Explicit `metadata.filters` wins. When the backend does not emit
+        // them, derive a filter chip from every column flagged
+        // `filterable: true` — keeps the kernel API minimal (one flag on the
+        // column) while still rendering the FilterableColumnHeader.
+        for (const f of metadata.filters ?? []) {
             const fType = f.type as ColumnFilterConfig['filterType']
             let options: { label: string; value: string; icon?: string; color?: string }[] = []
             if (f.options && f.options.length > 0) {
@@ -498,6 +503,31 @@ export function DynamicTable({
                 searchEndpoint: f.searchEndpoint,
             })
         }
+        for (const c of metadata.columns ?? []) {
+            if (!c.filterable || map.has(c.key)) continue
+            const hasStaticOptions = (c.options?.length ?? 0) > 0
+            const hasEndpoint = !!c.searchEndpoint
+            if (!hasStaticOptions && !hasEndpoint && c.type !== 'boolean') continue
+            const options = hasStaticOptions
+                ? c.options!.map(o => ({
+                      label: o.label,
+                      value: String(o.value),
+                      icon: o.icon,
+                      color: o.color,
+                  }))
+                : hasEndpoint && filterOptionsMap.has(c.searchEndpoint!)
+                  ? filterOptionsMap.get(c.searchEndpoint!) || []
+                  : []
+            map.set(c.key, {
+                filterType: 'select',
+                filterKey: c.key,
+                options,
+                selectedValues: dynamicFilters[c.key] || [],
+                onFilterChange: handleDynamicFilterChange,
+                loading: hasEndpoint && !filterOptionsMap.has(c.searchEndpoint!),
+                searchEndpoint: c.searchEndpoint,
+            })
+        }
         return map
     }, [metadata, filterOptionsMap, dynamicFilters, handleDynamicFilterChange])
 
@@ -757,10 +787,3 @@ export function DynamicTable({
     )
 }
 
-/** Sensible default when hosts don't provide their own getDynamicColumns. */
-const defaultGetDynamicColumns: GetDynamicColumns = (metadata, _handleAction, _t, _lang, _filters) =>
-    (metadata.columns ?? []).map((col: any) => ({
-        accessorKey: col.name,
-        header: col.label ?? col.name,
-        enableSorting: col.sortable ?? false,
-    }))

package/src/index.ts

@@ -25,6 +25,24 @@ export type {
     GetDynamicColumns,
     DynamicIconComponent,
 } from './dynamic-columns-shim'
+export {
+    defaultGetDynamicColumns,
+    makeDefaultGetDynamicColumns,
+    type DynamicColumnsHelpers,
+} from './dynamic-columns'
 export { DynamicRecordDialog } from './dialogs/dynamic-record'
 export { ExportDialog } from './dialogs/export'
 export { ImportDialog } from './dialogs/import'
+export {
+    DynamicCRUDPage,
+    type DynamicCRUDPageProps,
+    type DynamicCRUDPageStrings,
+    type DynamicCRUDPageClasses,
+} from './dynamic-crud-page'
+export {
+    registerModelExtension,
+    getModelExtension,
+    clearModelExtensions,
+    type ModelExtension,
+    type ModelExtensionProps,
+} from './model-extension-registry'

package/src/metadata-cache.ts

@@ -1,7 +1,7 @@
 // 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.
+// responses across dynamic-table mounts. Generalized from a host-app
+// metadata-cache store 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

package/src/model-extension-registry.tsx

@@ -0,0 +1,46 @@
+// Per-model UI extension registry. Apps register once at boot and
+// `<DynamicCRUDPage>` composes the registered extension automatically — no
+// per-route forking, no copy-paste of the page shell.
+//
+//   import { registerModelExtension } from '@asteby/metacore-runtime-react'
+//
+//   registerModelExtension('customers', {
+//       headerExtras: CustomersKpiStrip,
+//       toolbarExtras: BulkAssignButton,
+//       hideImport: true,
+//   })
+//
+// The registry is a module-level singleton — intentional. A React context
+// would force every consumer to wrap a provider just to read a static
+// configuration that is set once at app boot.
+import * as React from 'react'
+
+export interface ModelExtensionProps {
+    model: string
+    onRefresh: () => void
+}
+
+export interface ModelExtension {
+    headerExtras?: React.ComponentType<ModelExtensionProps>
+    toolbarExtras?: React.ComponentType<ModelExtensionProps>
+    hideCreate?: boolean
+    hideExport?: boolean
+    hideImport?: boolean
+    hideRefresh?: boolean
+    title?: string
+    newLabel?: string
+}
+
+const registry = new Map<string, ModelExtension>()
+
+export function registerModelExtension(model: string, ext: ModelExtension): void {
+    registry.set(model, ext)
+}
+
+export function getModelExtension(model: string): ModelExtension | undefined {
+    return registry.get(model)
+}
+
+export function clearModelExtensions(): void {
+    registry.clear()
+}

package/src/types.ts

@@ -1,4 +1,6 @@
-// Union of the two host copies (link + ops). Ops adds the `link` action type + `linkUrl`.
+// Shared metadata shape consumed by every host. Some hosts add a `link`
+// action type with a `linkUrl` template — represented here as part of the
+// `type` union so the SDK can render it uniformly.
 export interface TableMetadata {
     title: string
     endpoint: string