@asteby/metacore-runtime-react 13.5.2 → 13.6.0

package/src/dynamic-relations.tsx

@@ -0,0 +1,160 @@
+// DynamicRelations — metadata-driven panel list. Given a parent record and the
+// `TableMetadata.relations[]` the kernel serves (>= v0.41.0), it renders one
+// `<DynamicRelation>` panel per relation. This is what a generic detail page
+// renders to surface "a Customer's vehicles, addresses, attachments" without
+// hand-wiring each child list.
+//
+// For every RelationMeta it:
+//   - maps `kind` straight through (one_to_many | many_to_many),
+//   - uses `through` as the child/pivot model and `foreign_key` as the FK,
+//   - merges the relation's static `scope` (polymorphic discriminators, e.g.
+//     { owner_model: "Customer" }) into the panel's `filters` so the child list
+//     is scoped by the FK AND every scope column.
+import { useMemo } from 'react'
+import { DynamicRelation, type DynamicRelationStrings } from './dynamic-relation'
+import type { RelationMeta } from './types'
+
+export interface DynamicRelationsProps {
+    /**
+     * The parent record. Its `id` (or `parentIdKey`) seeds every child list's
+     * foreign-key filter. Null/undefined → renders nothing (loading guard).
+     */
+    record: { id?: string | number; [k: string]: unknown } | null | undefined
+    /** The relations to render — typically `metadata.relations`. */
+    relations: RelationMeta[] | null | undefined
+    /**
+     * Which field of `record` holds the parent id. Default `'id'`. Lets a host
+     * key relations off a non-`id` primary key.
+     */
+    parentIdKey?: string
+    /** Wrapper className for the whole stack. */
+    className?: string
+    /** Per-panel wrapper className. */
+    panelClassName?: string
+    /**
+     * Permisos propagados a cada panel. Default true. A host can lock the whole
+     * detail page read-only by passing canCreate/canDelete/canEdit = false.
+     */
+    canCreate?: boolean
+    canDelete?: boolean
+    canEdit?: boolean
+    /** Translatable strings forwarded to each DynamicRelation. */
+    strings?: Partial<DynamicRelationStrings>
+    /** Bubble up when any panel's data changes (create/delete/attach/detach). */
+    onChange?: (relation: RelationMeta) => void
+}
+
+/**
+ * Normalizes the parent id off the record, tolerating a custom `parentIdKey`.
+ * Returns `undefined` when unusable so callers can guard rendering.
+ */
+export function resolveParentId(
+    record: { [k: string]: unknown } | null | undefined,
+    parentIdKey = 'id',
+): string | number | undefined {
+    if (!record) return undefined
+    const raw = record[parentIdKey]
+    if (raw === undefined || raw === null || raw === '') return undefined
+    if (typeof raw === 'number' || typeof raw === 'string') return raw
+    return undefined
+}
+
+/**
+ * Merges a relation's static `scope` with its foreign-key entry into the flat
+ * `filters` map `<DynamicRelation>` expects. The FK is included so a panel that
+ * only consumes `filters` (rather than the dedicated `foreignKey` prop) stays
+ * correctly scoped; `<DynamicRelation>` already de-dups the FK so passing it in
+ * both places is safe.
+ */
+export function buildRelationFilters(
+    relation: Pick<RelationMeta, 'foreign_key' | 'scope'>,
+    parentId: string | number,
+): Record<string, string> {
+    const out: Record<string, string> = {}
+    if (relation.scope) {
+        for (const [k, v] of Object.entries(relation.scope)) {
+            if (!k || v === undefined || v === null) continue
+            out[k] = String(v)
+        }
+    }
+    if (relation.foreign_key) out[relation.foreign_key] = String(parentId)
+    return out
+}
+
+/** Stable React key for a relation panel. */
+function relationKey(rel: RelationMeta, idx: number): string {
+    return rel.name || `${rel.through}-${rel.foreign_key}-${idx}`
+}
+
+export function DynamicRelations({
+    record,
+    relations,
+    parentIdKey = 'id',
+    className,
+    panelClassName,
+    canCreate = true,
+    canDelete = true,
+    canEdit = true,
+    strings,
+    onChange,
+}: DynamicRelationsProps) {
+    const parentId = useMemo(
+        () => resolveParentId(record, parentIdKey),
+        [record, parentIdKey],
+    )
+
+    if (parentId === undefined || !relations || relations.length === 0) {
+        return null
+    }
+
+    return (
+        <div className={className} data-dynamic-relations="">
+            {relations.map((rel, idx) => {
+                const filters = buildRelationFilters(rel, parentId)
+                const panelStrings: Partial<DynamicRelationStrings> = {
+                    ...(strings || {}),
+                    ...(rel.label ? { title: rel.label } : {}),
+                }
+                if (rel.kind === 'many_to_many') {
+                    return (
+                        <DynamicRelation
+                            key={relationKey(rel, idx)}
+                            kind="many_to_many"
+                            through={rel.through}
+                            // The pivot's reference table is unknown from
+                            // RelationMeta alone; default to the through model so
+                            // the panel degrades to the pivot list. Hosts with a
+                            // declared `references` should render DynamicRelation
+                            // directly. (one_to_many is the common detail-page case.)
+                            references={rel.through}
+                            foreignKey={rel.foreign_key}
+                            parentId={parentId}
+                            filters={filters}
+                            className={panelClassName}
+                            canCreate={canCreate}
+                            canDelete={canDelete}
+                            strings={panelStrings}
+                            onChange={onChange ? () => onChange(rel) : undefined}
+                        />
+                    )
+                }
+                return (
+                    <DynamicRelation
+                        key={relationKey(rel, idx)}
+                        kind="one_to_many"
+                        model={rel.through}
+                        foreignKey={rel.foreign_key}
+                        parentId={parentId}
+                        filters={filters}
+                        className={panelClassName}
+                        canCreate={canCreate}
+                        canDelete={canDelete}
+                        canEdit={canEdit}
+                        strings={panelStrings}
+                        onChange={onChange ? () => onChange(rel) : undefined}
+                    />
+                )
+            })}
+        </div>
+    )
+}

package/src/index.ts

@@ -93,6 +93,12 @@ export {
     deriveRelationFormFields,
     relationRowKey,
 } from './dynamic-relation'
+export {
+    DynamicRelations,
+    resolveParentId,
+    buildRelationFilters,
+    type DynamicRelationsProps,
+} from './dynamic-relations'
 export {
     registerModelExtension,
     getModelExtension,

package/src/types.ts

@@ -15,6 +15,42 @@ export interface TableMetadata {
     canExport?: boolean
     canImport?: boolean
     canCreate?: boolean
+    /**
+     * Child relations of this model, served by the kernel (>= v0.41.0). A
+     * generic detail page renders one `DynamicRelation` panel per entry via
+     * `<DynamicRelations>` to surface, e.g., a Customer's vehicles, addresses
+     * and attachments. Absent on hosts/older kernels — purely additive.
+     */
+    relations?: RelationMeta[]
+}
+
+/**
+ * Describes one child relation of a parent model, mirroring the kernel
+ * `RelationMeta` shape (>= v0.41.0). Drives the metadata-driven
+ * `<DynamicRelations>` panel list. All keys are snake_case as served by the
+ * kernel; the SDK reads them as-is.
+ */
+export interface RelationMeta {
+    /** Stable identifier for the relation (used as a React key / data attr). */
+    name: string
+    /** Cardinality. The SDK maps this onto `DynamicRelation.kind`. */
+    kind: 'one_to_many' | 'many_to_many'
+    /**
+     * Child model key (the `through` model). For one_to_many this is the model
+     * whose rows are listed; for many_to_many it is the pivot table.
+     */
+    through: string
+    /** Child column holding the FK back to the parent. */
+    foreign_key: string
+    /**
+     * Static equality filters applied on top of the foreign-key scope. Used for
+     * polymorphic children (e.g. `{ "owner_model": "Customer" }`) so a shared
+     * attachments/addresses table is narrowed to this parent's rows. Each entry
+     * becomes a `f_<col>=eq:<val>` query param.
+     */
+    scope?: Record<string, string>
+    /** Human-readable panel header. */
+    label?: string
 }
 
 export interface FilterDefinition {
@@ -118,6 +154,7 @@ export type FieldWidget =
     | 'select'
     | 'dynamic_select'
     | 'switch'
+    | 'upload'
 
 export interface ActionFieldDef {
     key: string
@@ -161,6 +198,27 @@ export interface ActionFieldDef {
      * reconcile. Mirrors kernel v3 `ActionField.balance`.
      */
     balance?: FieldBalanceRule
+    /**
+     * `upload` widget: comma-separated accept list forwarded to the file input
+     * `accept` attribute (e.g. `"image/*,.pdf"`). Tolerates the snake_case the
+     * kernel may serve. Optional — when absent any file type is allowed.
+     */
+    accept?: string
+    /**
+     * `upload` widget: maximum file size in bytes. The renderer rejects larger
+     * files client-side before POSTing. Tolerates kernel snake_case `max_size`.
+     */
+    maxSize?: number
+    /** snake_case alias served by the kernel manifest for `maxSize`. */
+    max_size?: number
+    /**
+     * `upload` widget: server-side storage bucket/prefix the host writes the
+     * file under, forwarded to the upload endpoint as `storage_path`. Tolerates
+     * kernel snake_case `storage_path`.
+     */
+    storagePath?: string
+    /** snake_case alias served by the kernel manifest for `storagePath`. */
+    storage_path?: string
 }
 
 /**

package/src/upload-field.tsx

@@ -0,0 +1,168 @@
+// UploadField — the `upload` widget renderer shared by DynamicForm's
+// FieldRenderer and the action-modal-dispatcher's renderField so the two stay
+// in lockstep. Renders a themed Button that proxies a hidden <input type=file>,
+// POSTs the picked file to the host upload endpoint as multipart/form-data, and
+// stores the returned file url/path as the field value.
+//
+// Endpoint assumption: `POST /uploads` (multipart) returning
+//   { success: true, data: { file_url?, url?, path?, file_path? } }
+// matching the kernel envelope. A field may override the path via
+// `field.searchEndpoint` (reused as the upload endpoint escape hatch) — kept
+// generic so this carries no host-specific route. Honors field.accept /
+// field.maxSize and forwards field.storagePath as `storage_path`.
+import { useCallback, useRef, useState } from 'react'
+import { Button } from '@asteby/metacore-ui/primitives'
+import { Loader2, Paperclip, X } from 'lucide-react'
+import { useApi } from './api-context'
+import { getUploadConfig } from './dynamic-form-schema'
+import type { ActionFieldDef } from './types'
+
+export interface UploadFieldProps {
+    field: ActionFieldDef
+    value: any
+    onChange: (v: any) => void
+}
+
+/** Default host upload endpoint. Overridable per-field via `searchEndpoint`. */
+const DEFAULT_UPLOAD_ENDPOINT = '/uploads'
+
+/**
+ * Pulls the stored file url/path out of an upload response envelope, tolerating
+ * the common key shapes a host might return. Pure — exported for tests.
+ */
+export function extractUploadedValue(payload: any): string {
+    if (payload === null || payload === undefined) return ''
+    if (typeof payload === 'string') return payload
+    const d = (payload && typeof payload === 'object' && 'data' in payload ? payload.data : payload) ?? payload
+    if (typeof d === 'string') return d
+    if (d && typeof d === 'object') {
+        const candidate =
+            d.file_url ?? d.fileUrl ?? d.url ?? d.file_path ?? d.filePath ?? d.path
+        if (typeof candidate === 'string') return candidate
+    }
+    return ''
+}
+
+/** Short, human display name for an already-stored file value (a url/path). */
+export function uploadedDisplayName(value: unknown): string {
+    if (typeof value !== 'string' || value === '') return ''
+    const cleaned = value.split('?')[0]
+    const parts = cleaned.split('/')
+    return parts[parts.length - 1] || cleaned
+}
+
+export function UploadField({ field, value, onChange }: UploadFieldProps) {
+    const api = useApi()
+    const inputRef = useRef<HTMLInputElement | null>(null)
+    const [uploading, setUploading] = useState(false)
+    const [error, setError] = useState<string | null>(null)
+
+    const { accept, maxSize, storagePath } = getUploadConfig(field)
+    const endpoint = field.searchEndpoint || DEFAULT_UPLOAD_ENDPOINT
+
+    const handlePick = useCallback(() => {
+        if (uploading) return
+        inputRef.current?.click()
+    }, [uploading])
+
+    const handleFile = useCallback(
+        async (e: React.ChangeEvent<HTMLInputElement>) => {
+            const file = e.target.files?.[0]
+            // Reset the input so picking the same file again re-fires change.
+            if (inputRef.current) inputRef.current.value = ''
+            if (!file) return
+            setError(null)
+            if (maxSize && file.size > maxSize) {
+                const mb = (maxSize / (1024 * 1024)).toFixed(1)
+                setError(`Archivo muy grande (máx. ${mb} MB).`)
+                return
+            }
+            const form = new FormData()
+            form.append('file', file)
+            if (storagePath) form.append('storage_path', storagePath)
+            setUploading(true)
+            try {
+                const res = await api.post(endpoint, form, {
+                    headers: { 'Content-Type': 'multipart/form-data' },
+                })
+                const body = (res as { data?: any })?.data
+                if (body && body.success === false) {
+                    setError(body.message || 'No se pudo subir el archivo.')
+                    return
+                }
+                const stored = extractUploadedValue(body)
+                if (!stored) {
+                    setError('Respuesta de subida inválida.')
+                    return
+                }
+                onChange(stored)
+            } catch (err: any) {
+                setError(err?.response?.data?.message || 'No se pudo subir el archivo.')
+            } finally {
+                setUploading(false)
+            }
+        },
+        [api, endpoint, maxSize, storagePath, onChange],
+    )
+
+    const handleClear = useCallback(() => {
+        if (uploading) return
+        setError(null)
+        onChange('')
+    }, [uploading, onChange])
+
+    const hasValue = typeof value === 'string' && value !== ''
+
+    return (
+        <div className="grid gap-1.5" data-widget="upload">
+            <input
+                ref={inputRef}
+                id={field.key}
+                type="file"
+                accept={accept}
+                className="sr-only"
+                onChange={handleFile}
+                tabIndex={-1}
+                aria-hidden="true"
+            />
+            <div className="flex items-center gap-2">
+                <Button
+                    type="button"
+                    variant="outline"
+                    size="sm"
+                    onClick={handlePick}
+                    disabled={uploading}
+                >
+                    {uploading ? (
+                        <Loader2 className="mr-2 h-4 w-4 animate-spin" />
+                    ) : (
+                        <Paperclip className="mr-2 h-4 w-4" />
+                    )}
+                    {hasValue ? 'Reemplazar' : field.placeholder || 'Subir archivo'}
+                </Button>
+                {hasValue && !uploading && (
+                    <div className="flex min-w-0 items-center gap-1 text-sm text-muted-foreground">
+                        <span className="truncate" title={String(value)}>
+                            {uploadedDisplayName(value)}
+                        </span>
+                        <Button
+                            type="button"
+                            variant="ghost"
+                            size="sm"
+                            className="h-6 w-6 p-0"
+                            onClick={handleClear}
+                            aria-label="Quitar archivo"
+                        >
+                            <X className="h-3.5 w-3.5" />
+                        </Button>
+                    </div>
+                )}
+            </div>
+            {error && (
+                <span className="text-sm text-destructive" role="alert">
+                    {error}
+                </span>
+            )}
+        </div>
+    )
+}