@asteby/metacore-runtime-react 8.0.0 → 9.1.0

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # @asteby/metacore-runtime-react
 
+## 9.1.0
+
+### Minor Changes
+
+- 2e50839: feat(runtime-react): leer `visibility` y `searchable` en metadata de columnas.
+  - `ColumnDefinition` tipa los nuevos campos `visibility?` (`"all" | "table" | "modal" | "list"`) y `searchable?` que el kernel ya emite (`manifest.ColumnDef`). Backwards compat: zero-value preserva el comportamiento previo.
+  - `<DynamicTable>` ahora oculta del listado las columnas con `visibility === "modal"` (y `"list"`) además del legacy `hidden`. Las columnas sin `visibility` o con `"all" | "table"` siguen visibles.
+  - Cuando al menos una columna declara `searchable` el SDK acota el global search a esas columnas vía el nuevo query param `search_columns=<keys>`. Si todas las columnas se opt-out (`searchable: false`), el SDK deja de mandar `search` al backend. Si ninguna columna trae el flag (kernel anterior a v0.8.x), no se cambia nada.
+  - Nuevos helpers públicos `isColumnVisibleInTable(col)` y `getSearchableColumnKeys(metadata)` exportados desde el barrel; tests con metadata mock cubren los pasos legacy + opt-in + opt-out total.
+
+## 9.0.0
+
+### Minor Changes
+
+- d51ef45: feat(runtime-react): `DynamicForm` aplica `Validation` (regex/min/max) al schema zod generado y soporta widgets `textarea`/`richtext`/`color`.
+  - `ActionFieldDef` extendido con `validation?: FieldValidation` (regex/min/max/custom — espejo del `ValidationRule` del manifest del kernel) y `widget?: FieldWidget | string`.
+  - `DynamicForm` ahora deriva un schema zod por field y valida en el submit, mostrando errores inline en lugar del `alert()` previo. Min/max aplica como longitud para strings y como bound para numéricos (mismo dual semantics que el kernel). Regex malformada del manifest se ignora silenciosamente para no tirar el render.
+  - Nuevo export `buildZodSchema(fields)` para que callers reutilicen el mismo schema fuera del form.
+  - Renderer mapea widgets explícitos a primitivos de `@asteby/metacore-ui`:
+    - `textarea` → `Textarea`
+    - `richtext` → `Textarea` con `data-widget="richtext"` (puente hasta que aterrice un primitivo MDX/rich; mantiene el contrato sin romper consumers).
+    - `color` → `Input type="color"`.
+  - Backwards compat: zero-value (sin `validation`/`widget`) preserva el comportamiento previo (widget inferido por `type`, sin reglas de validación más allá de `required`).
+
+- 88b176c: feat(runtime-react): `<DynamicRelation kind="many_to_many">` — multi-select sobre la tabla destino, sync transparente contra la tabla pivote (`through`).
+
+  API mínima:
+
+  ```tsx
+  <DynamicRelation
+    kind="many_to_many"
+    through="org_members" // tabla pivote
+    references="users" // tabla destino sobre la que se hace multi-select
+    foreignKey="organization_id" // FK del pivot al padre
+    parentId={org.id}
+  />
+  ```
+
+  - `referencesKey` por default es `${references}_id` (override opcional). Endpoints `/data/${through}` y `/data/${references}` con override por prop si la app expone rutas custom.
+  - Lectura: lista pivot rows filtradas por `f_<foreignKey>=eq:<parentId>` (mismo envelope kernel `{success, data, meta}` que `<DynamicTable>`); lista target rows del modelo `references`.
+  - Escritura: el `<MultiSelect>` dispara un diff entre la selección previa y la nueva. Cada nuevo target → `POST /data/${through}` con `{[foreignKey]: parentId, [referencesKey]: targetId}`. Cada target removido → `DELETE /data/${through}/<pivotRowId>`.
+  - Permisos por prop (`canCreate` controla attach, `canDelete` controla detach — default `true`).
+  - Label de cada opción: `displayKey` prop si está; si no se infiere de la metadata (primer column no-id no-hidden); fallback al `id`.
+  - Nuevos helpers puros exportados: `buildPivotAttachPayload`, `extractSelectedTargetIds`, `buildPivotRowIndex`, `diffSelection`, `pickOptionLabel`.
+
+  `kind="one_to_many"` no cambia.
+
+- 88b176c: feat(runtime-react): nuevo `<DynamicRelation kind="one_to_many">` — lista inline editable que cuelga del registro padre.
+
+  API mínima:
+
+  ```tsx
+  <DynamicRelation
+    kind="one_to_many"
+    model="line_items"
+    foreignKey="invoice_id"
+    parentId={id}
+  />
+  ```
+
+  - Lista filas del modelo hijo filtradas por `f_<foreignKey>=eq:<parentId>` (envelope kernel `{success, data, meta}`).
+  - Crear/Editar via `<DynamicForm>` derivado del `TableMetadata.columns` del modelo; la FK queda fija al `parentId` y se oculta automáticamente del form y de la lista.
+  - Quitar via `DELETE /data/<model>/<id>` con confirm dialog.
+  - Permisos por prop (`canCreate` / `canEdit` / `canDelete` — default `true`) y strings traducibles via prop `strings`.
+  - Helpers puros exportados (`buildRelationFilterParams`, `buildCreatePayload`, `deriveRelationFormFields`, `relationRowKey`) para que callers reutilicen las convenciones fuera del componente.
+  - `kind="many_to_many"` queda stubbed (renderiza `not-implemented`) — sigue como follow-up; la RFC completa vive en `packages/runtime-react/docs/relations.md`.
+  - Ejemplo end-to-end en `examples/dynamic-relation-one-to-many/`.
+
+### Patch Changes
+
+- Updated dependencies [ec9ad56]
+  - @asteby/metacore-sdk@2.4.0
+
 ## 8.0.0
 
 ### Patch Changes

package/dist/column-visibility.d.ts

@@ -0,0 +1,22 @@
+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 declare function isColumnVisibleInTable(col: ColumnDefinition): boolean;
+/**
+ * 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 declare function getSearchableColumnKeys(metadata: Pick<TableMetadata, 'columns'>): string[] | null;
+//# sourceMappingURL=column-visibility.d.ts.map

package/dist/column-visibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-visibility.d.ts","sourceRoot":"","sources":["../src/column-visibility.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE9D;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAKrE;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACnC,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,GACzC,MAAM,EAAE,GAAG,IAAI,CAKjB"}

package/dist/column-visibility.js

@@ -0,0 +1,40 @@
+// 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.
+/**
+ * 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) {
+    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) {
+    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/dist/dynamic-columns.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dynamic-columns.d.ts","sourceRoot":"","sources":["../src/dynamic-columns.tsx"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EAER,iBAAiB,EACpB,MAAM,wBAAwB,CAAA;AAE/B,qEAAqE;AACrE,MAAM,WAAW,qBAAqB;IAClC;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;IACtC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACtB;AAwHD;;;;GAIG;AACH,wBAAgB,4BAA4B,CACxC,OAAO,GAAE,qBAA0B,GACpC,iBAAiB,CAmXnB;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBACL,CAAA"}
+{"version":3,"file":"dynamic-columns.d.ts","sourceRoot":"","sources":["../src/dynamic-columns.tsx"],"names":[],"mappings":"AAsCA,OAAO,KAAK,EAER,iBAAiB,EACpB,MAAM,wBAAwB,CAAA;AAE/B,qEAAqE;AACrE,MAAM,WAAW,qBAAqB;IAClC;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;IACtC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACtB;AAwHD;;;;GAIG;AACH,wBAAgB,4BAA4B,CACxC,OAAO,GAAE,qBAA0B,GACpC,iBAAiB,CAqXnB;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBACL,CAAA"}

package/dist/dynamic-columns.js

@@ -18,6 +18,7 @@ import { DataTableColumnHeader, FilterableColumnHeader, } from '@asteby/metacore
 import { generateBadgeStyles, getInitials } from '@asteby/metacore-ui/lib';
 import { OptionsContext } from './options-context';
 import { DynamicIcon } from './dynamic-icon';
+import { isColumnVisibleInTable } from './column-visibility';
 const defaultGetImageUrl = (path) => path;
 const getNestedValue = (obj, path) => path.split('.').reduce((acc, part) => acc && acc[part], obj);
 const lowerFirst = (value) => {
@@ -123,7 +124,9 @@ export function makeDefaultGetDynamicColumns(helpers = {}) {
             },
         ];
         metadata.columns.forEach((col) => {
-            if (col.hidden)
+            // 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);

package/dist/dynamic-form-schema.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+import type { ActionFieldDef } from './types';
+export declare function buildZodSchema(fields: ActionFieldDef[]): z.ZodObject<{
+    [x: string]: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+}, z.core.$strip>;
+export declare function resolveWidget(field: ActionFieldDef): string;
+//# sourceMappingURL=dynamic-form-schema.d.ts.map

package/dist/dynamic-form-schema.d.ts.map

@@ -0,0 +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"}

package/dist/dynamic-form-schema.js

@@ -0,0 +1,68 @@
+// Pure schema-building helpers for DynamicForm. Lives in its own module so
+// callers (and unit tests) can use the zod schema without pulling in React or
+// metacore-ui primitives.
+import { z } from 'zod';
+// 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
+// strings they bound length — same dual semantics the kernel uses.
+export function buildZodSchema(fields) {
+    const shape = {};
+    for (const field of fields) {
+        shape[field.key] = fieldToZod(field);
+    }
+    return z.object(shape);
+}
+function fieldToZod(field) {
+    const v = field.validation ?? {};
+    const isNumeric = field.type === 'number';
+    const isBool = field.type === 'boolean';
+    if (isBool) {
+        const base = z.boolean();
+        return field.required ? base : base.optional();
+    }
+    if (isNumeric) {
+        let s = z.coerce.number();
+        if (typeof v.min === 'number')
+            s = s.min(v.min, `Debe ser ≥ ${v.min}`);
+        if (typeof v.max === 'number')
+            s = s.max(v.max, `Debe ser ≤ ${v.max}`);
+        if (field.required)
+            return s;
+        return z.preprocess((val) => (val === '' || val == null ? undefined : val), s.optional());
+    }
+    let s = z.string();
+    if (typeof v.min === 'number')
+        s = s.min(v.min, `Mínimo ${v.min} caracteres`);
+    if (typeof v.max === 'number')
+        s = s.max(v.max, `Máximo ${v.max} caracteres`);
+    if (v.regex) {
+        try {
+            s = s.regex(new RegExp(v.regex), `Formato inválido`);
+        }
+        catch { /* malformed regex from manifest — skip rather than throw at render time */ }
+    }
+    if (field.type === 'email')
+        s = s.email('Email inválido');
+    if (field.type === 'url')
+        s = s.url('URL inválida');
+    if (field.required) {
+        return s.min(Math.max(typeof v.min === 'number' ? v.min : 1, 1), `${field.label} es requerido`);
+    }
+    return s.optional().or(z.literal(''));
+}
+// Resolves the renderer widget for a field. Explicit `widget` wins; otherwise
+// it is inferred from `type` to preserve the legacy behaviour (zero-value =
+// same render as before).
+export function resolveWidget(field) {
+    if (field.widget)
+        return field.widget;
+    switch (field.type) {
+        case 'textarea': return 'textarea';
+        case 'select': return 'select';
+        case 'boolean': return 'switch';
+        case 'number': return 'number';
+        case 'date': return 'date';
+        default: return 'text';
+    }
+}

package/dist/dynamic-form.d.ts

@@ -1,4 +1,6 @@
 import type { ActionFieldDef } from './types';
+import { buildZodSchema, resolveWidget } from './dynamic-form-schema';
+export { buildZodSchema, resolveWidget };
 export interface DynamicFormProps {
     fields: ActionFieldDef[];
     initialValues?: Record<string, any>;

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;AAE7C,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,2CA+ClB"}
+{"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"}

package/dist/dynamic-form.js

@@ -2,44 +2,63 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // Minimal standalone DynamicForm. Factored from the dynamic-record-dialog
 // pattern + ActionFieldDef renderer so callers can reuse the form layout
 // outside the full record-edit modal.
-import { useEffect, useState } from 'react';
+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';
+export { buildZodSchema, resolveWidget };
 export function DynamicForm({ fields, initialValues, onSubmit, onCancel, submitLabel = 'Guardar', cancelLabel = 'Cancelar', disabled = false, }) {
     const [values, setValues] = useState({});
+    const [errors, setErrors] = useState({});
     const [submitting, setSubmitting] = useState(false);
+    const schema = useMemo(() => buildZodSchema(fields), [fields]);
     useEffect(() => {
         const defaults = {};
         for (const f of fields) {
             defaults[f.key] = initialValues?.[f.key] ?? f.defaultValue ?? (f.type === 'boolean' ? false : '');
         }
         setValues(defaults);
+        setErrors({});
     }, [fields, initialValues]);
     const update = (k, v) => setValues((prev) => ({ ...prev, [k]: v }));
     const handleSubmit = async (e) => {
         e.preventDefault();
-        for (const f of fields) {
-            if (f.required && !values[f.key] && values[f.key] !== false) {
-                alert(`${f.label} es requerido`);
-                return;
+        const result = schema.safeParse(values);
+        if (!result.success) {
+            const next = {};
+            for (const issue of result.error.issues) {
+                const key = issue.path[0];
+                if (typeof key === 'string' && !next[key])
+                    next[key] = issue.message;
             }
+            setErrors(next);
+            return;
         }
+        setErrors({});
         setSubmitting(true);
         try {
-            await onSubmit(values);
+            await onSubmit(result.data);
         }
         finally {
             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))] }, 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: "*" })] }), 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 })] })] }));
 }
 function renderField(field, value, onChange) {
-    switch (field.type) {
+    const widget = resolveWidget(field);
+    switch (widget) {
         case 'textarea':
             return _jsx(Textarea, { id: field.key, value: value || '', onChange: (e) => onChange(e.target.value), placeholder: field.placeholder });
+        case 'richtext':
+            // Until a real rich-text primitive lands in metacore-ui this maps
+            // to a tagged Textarea. The data attribute lets app-level theming
+            // / future MDX editor pick it up without breaking the contract.
+            return _jsx(Textarea, { id: field.key, "data-widget": "richtext", value: value || '', onChange: (e) => onChange(e.target.value), placeholder: field.placeholder });
+        case 'color':
+            return _jsx(Input, { id: field.key, type: "color", value: value || '#000000', onChange: (e) => onChange(e.target.value) });
         case 'select':
             return (_jsxs(Select, { value: value || '', onValueChange: onChange, children: [_jsx(SelectTrigger, { children: _jsx(SelectValue, { placeholder: field.placeholder || 'Seleccionar...' }) }), _jsx(SelectContent, { children: field.options?.map((opt) => _jsx(SelectItem, { value: opt.value, children: opt.label }, opt.value)) })] }));
-        case 'boolean':
+        case 'switch':
             return _jsx(Switch, { id: field.key, checked: !!value, onCheckedChange: onChange });
         case 'number':
             return _jsx(Input, { id: field.key, type: "number", value: value ?? '', onChange: (e) => onChange(e.target.valueAsNumber || ''), placeholder: field.placeholder });

package/dist/dynamic-relation-helpers.d.ts

@@ -0,0 +1,77 @@
+import type { ActionFieldDef, ColumnDefinition, TableMetadata } from './types';
+export type DynamicRelationKind = 'one_to_many' | 'many_to_many';
+export interface PivotRowLike {
+    id?: string | number | null;
+    [k: string]: unknown;
+}
+export interface TargetRowLike {
+    id?: string | number | null;
+    [k: string]: unknown;
+}
+/**
+ * Builds the query params used by `<DynamicRelation kind="one_to_many">` to
+ * scope a child list to a single parent record. Mirrors the
+ * `f_<column>=eq:<value>` convention enforced by `query/params.go` in the
+ * kernel.
+ */
+export declare function buildRelationFilterParams(foreignKey: string, parentId: string | number): Record<string, string>;
+/**
+ * Builds the POST body for creating a child row. The foreign key is forced to
+ * `parentId` regardless of what the form returned — the inline form hides the
+ * FK input but a misbehaving caller (or a manual override) should not be able
+ * to redirect the row to a different parent.
+ */
+export declare function buildCreatePayload(foreignKey: string, parentId: string | number, formValues: Record<string, any>): Record<string, any>;
+/**
+ * Maps a `TableMetadata.columns` shape into `ActionFieldDef[]` so the inline
+ * form can be rendered with `<DynamicForm>`. Excludes the foreign-key column
+ * (already fixed to parentId) and any column flagged `hidden`. Falls back to
+ * sensible widget hints derived from `ColumnDefinition.type`.
+ */
+export declare function deriveRelationFormFields(metadata: Pick<TableMetadata, 'columns'> | null | undefined, foreignKey: string): ActionFieldDef[];
+/**
+ * Stable id for relation rows. Falls back to a synthetic
+ * `__rel-<foreignKey>-<index>` when the row has no id — keeps React keys
+ * stable and lets optimistic creates render before the backend assigns an id.
+ */
+export declare function relationRowKey(row: {
+    id?: string | number | null;
+} | undefined, index: number, foreignKey: string): string;
+/**
+ * Builds the POST body for attaching a target row to the parent through the
+ * pivot table. Both FKs are required: `foreignKey -> parentId` (pivot side)
+ * and `referencesKey -> targetId` (target side). Extra pivot fields can be
+ * passed via `extra` (e.g. `role`, `position`); never override the two FKs.
+ */
+export declare function buildPivotAttachPayload(foreignKey: string, parentId: string | number, referencesKey: string, targetId: string | number, extra?: Record<string, any>): Record<string, any>;
+/**
+ * From a list of pivot rows, returns the set of currently-attached target ids
+ * coerced to string (the form expected by `<MultiSelect>` `selected`).
+ * Skips rows missing the FK (defensive — the kernel should never return them).
+ */
+export declare function extractSelectedTargetIds(pivotRows: ReadonlyArray<PivotRowLike> | null | undefined, referencesKey: string): string[];
+/**
+ * Builds a `targetId -> pivotRowId` lookup so detach can DELETE the pivot row
+ * by its own id without re-fetching. When several pivot rows point at the
+ * same target (shouldn't happen with a unique constraint but the kernel does
+ * not guarantee it), the *last* one wins — detach will only drop one at a
+ * time, the next render will surface the leftover.
+ */
+export declare function buildPivotRowIndex(pivotRows: ReadonlyArray<PivotRowLike> | null | undefined, referencesKey: string): Map<string, string | number>;
+/**
+ * Diffs the previous selection against the next one and returns the work to
+ * apply: target ids that need a POST (toAdd) and ids that need a DELETE
+ * (toRemove). Both arrays are deduped and order-stable to make tests
+ * deterministic.
+ */
+export declare function diffSelection(prev: ReadonlyArray<string>, next: ReadonlyArray<string>): {
+    toAdd: string[];
+    toRemove: string[];
+};
+/**
+ * Picks a human-readable label for a target row. Tries `displayKey` first,
+ * then walks the metadata columns in order looking for the first non-id /
+ * non-FK string-ish value. Falls back to the row id, then to '—'.
+ */
+export declare function pickOptionLabel(row: TargetRowLike | null | undefined, displayKey: string | undefined, columns: ReadonlyArray<ColumnDefinition> | null | undefined): string;
+//# sourceMappingURL=dynamic-relation-helpers.d.ts.map

package/dist/dynamic-relation-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-relation-helpers.d.ts","sourceRoot":"","sources":["../src/dynamic-relation-helpers.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE9E,MAAM,MAAM,mBAAmB,GAAG,aAAa,GAAG,cAAc,CAAA;AAEhE,MAAM,WAAW,YAAY;IACzB,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IAC3B,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,aAAa;IAC1B,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IAC3B,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACrC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GAAG,MAAM,GAC1B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMxB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAC9B,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GAAG,MAAM,EACzB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAChC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAGrB;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACpC,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,GAAG,IAAI,GAAG,SAAS,EAC3D,UAAU,EAAE,MAAM,GACnB,cAAc,EAAE,CAelB;AAcD;;;;GAIG;AACH,wBAAgB,cAAc,CAC1B,GAAG,EAAE;IAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,SAAS,EAChD,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GACnB,MAAM,CAKR;AAMD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACnC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GAAG,MAAM,EACzB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,GAAG,MAAM,EACzB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAcrB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACpC,SAAS,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,IAAI,GAAG,SAAS,EACzD,aAAa,EAAE,MAAM,GACtB,MAAM,EAAE,CASV;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAC9B,SAAS,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,IAAI,GAAG,SAAS,EACzD,aAAa,EAAE,MAAM,GACtB,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAU9B;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CACzB,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,EAC3B,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAC5B;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAYzC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC3B,GAAG,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,EACrC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,EAAE,aAAa,CAAC,gBAAgB,CAAC,GAAG,IAAI,GAAG,SAAS,GAC5D,MAAM,CAiBR"}

package/dist/dynamic-relation-helpers.js

@@ -0,0 +1,186 @@
+/**
+ * Builds the query params used by `<DynamicRelation kind="one_to_many">` to
+ * scope a child list to a single parent record. Mirrors the
+ * `f_<column>=eq:<value>` convention enforced by `query/params.go` in the
+ * kernel.
+ */
+export function buildRelationFilterParams(foreignKey, parentId) {
+    if (!foreignKey)
+        throw new Error('foreignKey requerido');
+    if (parentId === undefined || parentId === null || parentId === '') {
+        throw new Error('parentId requerido');
+    }
+    return { [`f_${foreignKey}`]: `eq:${String(parentId)}` };
+}
+/**
+ * Builds the POST body for creating a child row. The foreign key is forced to
+ * `parentId` regardless of what the form returned — the inline form hides the
+ * FK input but a misbehaving caller (or a manual override) should not be able
+ * to redirect the row to a different parent.
+ */
+export function buildCreatePayload(foreignKey, parentId, formValues) {
+    if (!foreignKey)
+        throw new Error('foreignKey requerido');
+    return { ...formValues, [foreignKey]: parentId };
+}
+/**
+ * Maps a `TableMetadata.columns` shape into `ActionFieldDef[]` so the inline
+ * form can be rendered with `<DynamicForm>`. Excludes the foreign-key column
+ * (already fixed to parentId) and any column flagged `hidden`. Falls back to
+ * sensible widget hints derived from `ColumnDefinition.type`.
+ */
+export function deriveRelationFormFields(metadata, foreignKey) {
+    if (!metadata?.columns)
+        return [];
+    const out = [];
+    for (const col of metadata.columns) {
+        if (col.key === foreignKey)
+            continue;
+        if (col.hidden)
+            continue;
+        out.push({
+            key: col.key,
+            label: col.label,
+            type: columnTypeToFieldType(col),
+            required: false,
+            options: col.options?.map(o => ({ value: String(o.value), label: o.label })),
+        });
+    }
+    return out;
+}
+function columnTypeToFieldType(col) {
+    switch (col.type) {
+        case 'number': return 'number';
+        case 'boolean': return 'boolean';
+        case 'date': return 'date';
+        case 'select': return 'select';
+        case 'text':
+        default:
+            return 'string';
+    }
+}
+/**
+ * Stable id for relation rows. Falls back to a synthetic
+ * `__rel-<foreignKey>-<index>` when the row has no id — keeps React keys
+ * stable and lets optimistic creates render before the backend assigns an id.
+ */
+export function relationRowKey(row, index, foreignKey) {
+    if (row && row.id !== undefined && row.id !== null && row.id !== '') {
+        return String(row.id);
+    }
+    return `__rel-${foreignKey}-${index}`;
+}
+// ---------------------------------------------------------------------------
+// many_to_many helpers
+// ---------------------------------------------------------------------------
+/**
+ * Builds the POST body for attaching a target row to the parent through the
+ * pivot table. Both FKs are required: `foreignKey -> parentId` (pivot side)
+ * and `referencesKey -> targetId` (target side). Extra pivot fields can be
+ * passed via `extra` (e.g. `role`, `position`); never override the two FKs.
+ */
+export function buildPivotAttachPayload(foreignKey, parentId, referencesKey, targetId, extra) {
+    if (!foreignKey)
+        throw new Error('foreignKey requerido');
+    if (!referencesKey)
+        throw new Error('referencesKey requerido');
+    if (parentId === undefined || parentId === null || parentId === '') {
+        throw new Error('parentId requerido');
+    }
+    if (targetId === undefined || targetId === null || targetId === '') {
+        throw new Error('targetId requerido');
+    }
+    return {
+        ...(extra || {}),
+        [foreignKey]: parentId,
+        [referencesKey]: targetId,
+    };
+}
+/**
+ * From a list of pivot rows, returns the set of currently-attached target ids
+ * coerced to string (the form expected by `<MultiSelect>` `selected`).
+ * Skips rows missing the FK (defensive — the kernel should never return them).
+ */
+export function extractSelectedTargetIds(pivotRows, referencesKey) {
+    if (!pivotRows || !referencesKey)
+        return [];
+    const out = [];
+    for (const row of pivotRows) {
+        const v = row[referencesKey];
+        if (v === undefined || v === null || v === '')
+            continue;
+        out.push(String(v));
+    }
+    return out;
+}
+/**
+ * Builds a `targetId -> pivotRowId` lookup so detach can DELETE the pivot row
+ * by its own id without re-fetching. When several pivot rows point at the
+ * same target (shouldn't happen with a unique constraint but the kernel does
+ * not guarantee it), the *last* one wins — detach will only drop one at a
+ * time, the next render will surface the leftover.
+ */
+export function buildPivotRowIndex(pivotRows, referencesKey) {
+    const map = new Map();
+    if (!pivotRows || !referencesKey)
+        return map;
+    for (const row of pivotRows) {
+        const target = row[referencesKey];
+        if (target === undefined || target === null || target === '')
+            continue;
+        if (row.id === undefined || row.id === null || row.id === '')
+            continue;
+        map.set(String(target), row.id);
+    }
+    return map;
+}
+/**
+ * Diffs the previous selection against the next one and returns the work to
+ * apply: target ids that need a POST (toAdd) and ids that need a DELETE
+ * (toRemove). Both arrays are deduped and order-stable to make tests
+ * deterministic.
+ */
+export function diffSelection(prev, next) {
+    const prevSet = new Set(prev);
+    const nextSet = new Set(next);
+    const toAdd = [];
+    for (const id of next) {
+        if (!prevSet.has(id) && !toAdd.includes(id))
+            toAdd.push(id);
+    }
+    const toRemove = [];
+    for (const id of prev) {
+        if (!nextSet.has(id) && !toRemove.includes(id))
+            toRemove.push(id);
+    }
+    return { toAdd, toRemove };
+}
+/**
+ * Picks a human-readable label for a target row. Tries `displayKey` first,
+ * then walks the metadata columns in order looking for the first non-id /
+ * non-FK string-ish value. Falls back to the row id, then to '—'.
+ */
+export function pickOptionLabel(row, displayKey, columns) {
+    if (!row)
+        return '—';
+    if (displayKey) {
+        const v = row[displayKey];
+        if (v !== undefined && v !== null && v !== '')
+            return String(v);
+    }
+    if (columns) {
+        for (const col of columns) {
+            if (col.key === 'id' || col.hidden)
+                continue;
+            const v = row[col.key];
+            if (v === undefined || v === null || v === '')
+                continue;
+            if (typeof v === 'object')
+                continue;
+            return String(v);
+        }
+    }
+    if (row.id !== undefined && row.id !== null && row.id !== '')
+        return String(row.id);
+    return '—';
+}