@asteby/metacore-runtime-react 13.5.1 → 13.6.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @asteby/metacore-runtime-react
 
+## 13.6.0
+
+### Minor Changes
+
+- ee91499: feat(runtime-react): metadata-driven DynamicRelations, DynamicRelation scope filters, and an upload field widget
+
+  Three additive primitives for generic detail pages and file-bearing actions
+  (kernel >= v0.41.0):
+  - **`DynamicRelations`** — a metadata-driven panel list. Given a parent record
+    and `TableMetadata.relations[]` (the new `RelationMeta[]` the kernel serves),
+    it renders one `DynamicRelation` panel per relation, merging each relation's
+    static `scope` (polymorphic discriminators like `{ owner_model: "Customer" }`)
+    plus `{ <foreign_key>: parentId }` into the panel's `filters`. This is what a
+    generic detail page renders to show "a Customer's vehicles, addresses,
+    attachments".
+  - **`DynamicRelation.filters`** — new optional `filters?: Record<string,string>`
+    prop so a relation can be scoped by MORE than one column (the polymorphic
+    case: `foreign_key=owner_id` AND `owner_model=Customer`). Each entry threads
+    into the child list query as an additional `f_<col>=eq:<val>` param alongside
+    the foreign-key filter, is hidden from the rendered child columns, and is
+    folded into create/attach payloads so new children carry the scope.
+  - **`upload` field widget** — `type:"upload"` / `widget:"upload"` action fields
+    now render a themed file picker (semantic tokens) that POSTs the file to the
+    host upload endpoint as multipart and stores the returned file url/path as the
+    field value. Honors `accept` and `maxSize` (tolerates kernel snake_case
+    `max_size`/`storage_path`). Wired into BOTH the standalone `DynamicForm`
+    renderer and the `ActionModalDispatcher` renderer so they stay in sync.
+
+  All purely additive — zero behavioural change for existing relations, forms, and
+  action modals.
+
+## 13.5.2
+
+### Patch Changes
+
+- bc99aec: Gate per-row table actions by the row's `status` against the action's `requiresState`.
+
+  Row actions that declare a non-empty `requiresState` (camelCase or the snake_case
+  `requires_state` served by the backend) are now hidden in the row-action dropdown
+  unless the row's `status` value is one of the declared states. For example, an
+  "Iniciar trabajo" action with `requiresState: ['reception']` no longer appears on an
+  order already in `in_progress`.
+
+  Additive and null-safe: actions without `requiresState` (or an empty array) are always
+  shown, and rows without a `status` field surface every action, so there is no
+  regression for existing models.
+
 ## 13.5.1
 
 ### Patch Changes

package/dist/action-modal-dispatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action-modal-dispatcher.d.ts","sourceRoot":"","sources":["../src/action-modal-dispatcher.tsx"],"names":[],"mappings":"AA8CA,OAAO,EACH,KAAK,cAAc,EACnB,KAAK,gBAAgB,EAExB,MAAM,sBAAsB,CAAA;AAE7B,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAA;AAEhD,wBAAgB,qBAAqB,CAAC,EAClC,IAAI,EACJ,YAAY,EACZ,MAAM,EACN,KAAK,EACL,MAAM,EACN,QAAQ,EACR,SAAS,GACZ,EAAE,gBAAgB,kDAiDlB"}
+{"version":3,"file":"action-modal-dispatcher.d.ts","sourceRoot":"","sources":["../src/action-modal-dispatcher.tsx"],"names":[],"mappings":"AA+CA,OAAO,EACH,KAAK,cAAc,EACnB,KAAK,gBAAgB,EAExB,MAAM,sBAAsB,CAAA;AAE7B,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAA;AAEhD,wBAAgB,qBAAqB,CAAC,EAClC,IAAI,EACJ,YAAY,EACZ,MAAM,EACN,KAAK,EACL,MAAM,EACN,QAAQ,EACR,SAAS,GACZ,EAAE,gBAAgB,kDAiDlB"}

package/dist/action-modal-dispatcher.js

@@ -17,6 +17,7 @@ import { DynamicIcon } from './dynamic-icon';
 import { DynamicLineItems } from './dynamic-line-items';
 import { DynamicSelectField } from './dynamic-select-field';
 import { DynamicDateField } from './dynamic-date-field';
+import { UploadField } from './upload-field';
 import { isLineItemsField, resolveWidget } from './dynamic-form-schema';
 // Canonical registry lives in @asteby/metacore-sdk
 import { getActionComponent, } from '@asteby/metacore-sdk';
@@ -155,6 +156,11 @@ function renderField(field, value, onChange) {
     if (widget === 'dynamic_select') {
         return _jsx(DynamicSelectField, { field: field, value: value, onChange: onChange });
     }
+    // File upload → themed picker that POSTs the file to the host upload
+    // endpoint and stores the returned url/path. Kept in sync with DynamicForm.
+    if (widget === 'upload') {
+        return _jsx(UploadField, { field: field, value: value, onChange: onChange });
+    }
     switch (widget) {
         case 'textarea':
             return _jsx(Textarea, { id: field.key, value: value || '', onChange: (e) => onChange(e.target.value), placeholder: field.placeholder });

package/dist/dynamic-columns.d.ts

@@ -14,6 +14,19 @@ export interface DynamicColumnsHelpers {
      */
     apiBaseUrl?: string;
 }
+/**
+ * State-machine gate for per-row actions.
+ *
+ * An action that declares a non-empty `requiresState` (camelCase) / `requires_state`
+ * (snake_case, as served by some backends) is only surfaced for rows whose `status`
+ * field value is contained in that array. This hides e.g. an "Iniciar trabajo"
+ * action (requiresState: ['reception']) on an order already in `in_progress`.
+ *
+ * Null-safe & non-regressive:
+ *   - action without requiresState (or empty array)  → always shown.
+ *   - row with no `status` field                      → all actions shown.
+ */
+export declare const isActionAllowedForRowState: (action: any, row: any) => boolean;
 /**
  * Builds the canonical column factory used by `<DynamicTable>` when the host
  * does not supply its own. Pass `{ getImageUrl, apiBaseUrl }` to wire avatar

package/dist/dynamic-columns.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"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;AAOD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,GAAI,QAAQ,GAAG,EAAE,KAAK,GAAG,KAAG,OAMlE,CAAA;AAmHD;;;;GAIG;AACH,wBAAgB,4BAA4B,CACxC,OAAO,GAAE,qBAA0B,GACpC,iBAAiB,CAsXnB;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBACL,CAAA"}

package/dist/dynamic-columns.js

@@ -21,6 +21,27 @@ 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);
+/**
+ * State-machine gate for per-row actions.
+ *
+ * An action that declares a non-empty `requiresState` (camelCase) / `requires_state`
+ * (snake_case, as served by some backends) is only surfaced for rows whose `status`
+ * field value is contained in that array. This hides e.g. an "Iniciar trabajo"
+ * action (requiresState: ['reception']) on an order already in `in_progress`.
+ *
+ * Null-safe & non-regressive:
+ *   - action without requiresState (or empty array)  → always shown.
+ *   - row with no `status` field                      → all actions shown.
+ */
+export const isActionAllowedForRowState = (action, row) => {
+    const requires = action?.requiresState ?? action?.requires_state;
+    if (!Array.isArray(requires) || requires.length === 0)
+        return true;
+    const status = row?.status;
+    if (status === undefined || status === null || status === '')
+        return true;
+    return requires.map(String).includes(String(status));
+};
 const lowerFirst = (value) => {
     if (!value)
         return value;
@@ -311,6 +332,7 @@ export function makeDefaultGetDynamicColumns(helpers = {}) {
                 maxSize: 80,
                 meta: {},
                 cell: ({ row }) => (_jsx("div", { className: "flex items-center justify-end", children: _jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsxs(Button, { variant: "ghost", className: "h-8 w-8 p-0", children: [_jsx("span", { className: "sr-only", children: "Abrir men\u00FA" }), _jsx(MoreHorizontal, { className: "h-4 w-4" })] }) }), _jsx(DropdownMenuContent, { align: "end", children: resolvedActions
+                                    .filter((action) => isActionAllowedForRowState(action, row.original))
                                     .filter((action) => {
                                     if (!action.condition)
                                         return true;

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

@@ -54,4 +54,14 @@ export interface BalanceState {
  */
 export declare function evaluateBalance(field: ActionFieldDef, rows: any[] | undefined): BalanceState | undefined;
 export declare function resolveWidget(field: ActionFieldDef): string;
+/**
+ * Normalizes an upload field's config, tolerating both the camelCase authored
+ * SDK shape and the snake_case the kernel serves (`max_size`, `storage_path`).
+ * Pure — shared by both field renderers and unit tests.
+ */
+export declare function getUploadConfig(field: ActionFieldDef): {
+    accept?: string;
+    maxSize?: number;
+    storagePath?: string;
+};
 //# sourceMappingURL=dynamic-form-schema.d.ts.map

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

@@ -1 +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;AAiB9D;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,SAAS,GAAG,IAAI,CAEzF;AAcD,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE;;kBAMtD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,cAAc,EAAE,CAGrE;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC1B,KAAK,EAAE,cAAc,GACtB;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAatG;AAED,6EAA6E;AAC7E,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAO3C;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACjC,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,GAAG,EAAE,GAAG,SAAS,GACxB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWxB;AAED,MAAM,WAAW,YAAY;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,OAAO,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC3B,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,GAAG,EAAE,GAAG,SAAS,GACxB,YAAY,GAAG,SAAS,CAgB1B;AAqDD,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAa3D"}
+{"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;AAiB9D;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,SAAS,GAAG,IAAI,CAEzF;AAcD,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE;;kBAMtD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,cAAc,EAAE,CAGrE;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC1B,KAAK,EAAE,cAAc,GACtB;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAatG;AAED,6EAA6E;AAC7E,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAO3C;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACjC,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,GAAG,EAAE,GAAG,SAAS,GACxB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWxB;AAED,MAAM,WAAW,YAAY;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,OAAO,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC3B,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,GAAG,EAAE,GAAG,SAAS,GACxB,YAAY,GAAG,SAAS,CAgB1B;AAqDD,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAgB3D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG;IACpD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;CACvB,CAaA"}

package/dist/dynamic-form-schema.js

@@ -199,6 +199,27 @@ export function resolveWidget(field) {
         case 'boolean': return 'switch';
         case 'number': return 'number';
         case 'date': return 'date';
+        // File upload: POSTs to the host upload endpoint and stores the returned
+        // file url/path as the field value. Rendered by `UploadField`.
+        case 'upload': return 'upload';
         default: return 'text';
     }
 }
+/**
+ * Normalizes an upload field's config, tolerating both the camelCase authored
+ * SDK shape and the snake_case the kernel serves (`max_size`, `storage_path`).
+ * Pure — shared by both field renderers and unit tests.
+ */
+export function getUploadConfig(field) {
+    const accept = field.accept;
+    const maxSizeRaw = field.maxSize ?? field.max_size;
+    const maxSize = typeof maxSizeRaw === 'number' && Number.isFinite(maxSizeRaw) && maxSizeRaw > 0
+        ? maxSizeRaw
+        : undefined;
+    const storagePath = field.storagePath ?? field.storage_path;
+    return {
+        accept: accept || undefined,
+        maxSize,
+        storagePath: storagePath || undefined,
+    };
+}

package/dist/dynamic-form.d.ts

@@ -4,6 +4,7 @@ export { buildZodSchema, resolveWidget };
 export { DynamicLineItems } from './dynamic-line-items';
 export { DynamicSelectField } from './dynamic-select-field';
 export { DynamicDateField } from './dynamic-date-field';
+export { UploadField } from './upload-field';
 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;AAC7C,OAAO,EACH,cAAc,EACd,aAAa,EAGhB,MAAM,uBAAuB,CAAA;AAM9B,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,CAAA;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAEvD,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,2CAkGlB"}
+{"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,EACH,cAAc,EACd,aAAa,EAGhB,MAAM,uBAAuB,CAAA;AAO9B,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,CAAA;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAE5C,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,2CAkGlB"}

package/dist/dynamic-form.js

@@ -9,10 +9,12 @@ import { useOptionsResolver } from './use-options-resolver';
 import { DynamicLineItems } from './dynamic-line-items';
 import { DynamicSelectField } from './dynamic-select-field';
 import { DynamicDateField } from './dynamic-date-field';
+import { UploadField } from './upload-field';
 export { buildZodSchema, resolveWidget };
 export { DynamicLineItems } from './dynamic-line-items';
 export { DynamicSelectField } from './dynamic-select-field';
 export { DynamicDateField } from './dynamic-date-field';
+export { UploadField } from './upload-field';
 export function DynamicForm({ fields, initialValues, onSubmit, onCancel, submitLabel = 'Guardar', cancelLabel = 'Cancelar', disabled = false, }) {
     const [values, setValues] = useState({});
     const [errors, setErrors] = useState({});
@@ -91,6 +93,11 @@ function FieldRenderer({ field, value, onChange }) {
     if (widget === 'dynamic_select') {
         return _jsx(DynamicSelectField, { field: field, value: value, onChange: onChange });
     }
+    // File upload → themed picker that POSTs to the host upload endpoint and
+    // stores the returned file url/path as the field value.
+    if (widget === 'upload') {
+        return _jsx(UploadField, { field: field, value: value, onChange: onChange });
+    }
     // Ref-driven select: hook into useOptionsResolver so the canonical
     // /api/options/<ref>?field=id endpoint feeds the dropdown. This is
     // the path the kernel auto-derives for FK columns; legacy callers

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

@@ -14,7 +14,7 @@ export interface TargetRowLike {
  * `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>;
+export declare function buildRelationFilterParams(foreignKey: string, parentId: string | number, extraFilters?: Record<string, string> | null): 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

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

@@ -1 +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"}
+{"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,EACzB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,GAC7C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmBxB;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

@@ -4,13 +4,28 @@
  * `f_<column>=eq:<value>` convention enforced by `query/params.go` in the
  * kernel.
  */
-export function buildRelationFilterParams(foreignKey, parentId) {
+export function buildRelationFilterParams(foreignKey, parentId, extraFilters) {
     if (!foreignKey)
         throw new Error('foreignKey requerido');
     if (parentId === undefined || parentId === null || parentId === '') {
         throw new Error('parentId requerido');
     }
-    return { [`f_${foreignKey}`]: `eq:${String(parentId)}` };
+    const params = {
+        [`f_${foreignKey}`]: `eq:${String(parentId)}`,
+    };
+    // Additional static-equality scope columns (polymorphic case: the FK plus
+    // e.g. owner_model=Customer). Each becomes its own `f_<col>=eq:<val>` param.
+    // The foreign-key entry above wins if a caller redundantly repeats it.
+    if (extraFilters) {
+        for (const [col, val] of Object.entries(extraFilters)) {
+            if (!col || col === foreignKey)
+                continue;
+            if (val === undefined || val === null)
+                continue;
+            params[`f_${col}`] = `eq:${String(val)}`;
+        }
+    }
+    return params;
 }
 /**
  * Builds the POST body for creating a child row. The foreign key is forced to

package/dist/dynamic-relation.d.ts

@@ -17,6 +17,14 @@ export interface DynamicRelationStrings {
 interface CommonProps {
     /** id del registro padre. */
     parentId: string | number;
+    /**
+     * Filtros estáticos extra (igualdad) aplicados ADEMÁS del foreign-key.
+     * Caso polimórfico: una tabla de hijos compartida (attachments,
+     * addresses) scopeada por `foreign_key=owner_id` Y `owner_model=Customer`.
+     * Cada entrada se thread-ea como `f_<col>=eq:<val>` junto al FK en la query
+     * de la lista hija. Aditivo: sin filters el comportamiento es idéntico.
+     */
+    filters?: Record<string, string>;
     /** Hidden columns; el FK siempre se oculta automáticamente. */
     hiddenColumns?: string[];
     /** Permisos visibles. Default true. */

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

@@ -1 +1 @@
-{"version":3,"file":"dynamic-relation.d.ts","sourceRoot":"","sources":["../src/dynamic-relation.tsx"],"names":[],"mappings":"AA0CA,YAAY,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AACrE,OAAO,EACH,kBAAkB,EAClB,uBAAuB,EACvB,kBAAkB,EAClB,yBAAyB,EACzB,wBAAwB,EACxB,aAAa,EACb,wBAAwB,EACxB,eAAe,EACf,cAAc,GACjB,MAAM,4BAA4B,CAAA;AAEnC,MAAM,WAAW,sBAAsB;IACnC,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,wBAAwB,EAAE,MAAM,CAAA;IAChC,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,iBAAiB,EAAE,MAAM,CAAA;IACzB,uBAAuB,EAAE,MAAM,CAAA;IAC/B,WAAW,EAAE,MAAM,CAAA;CACtB;AAiBD,UAAU,WAAW;IACjB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;IACzB,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB,uCAAuC;IACvC,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,2BAA2B;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAA;IACzC,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;CACxB;AAED,MAAM,WAAW,6BAA8B,SAAQ,WAAW;IAC9D,IAAI,EAAE,aAAa,CAAA;IACnB,yFAAyF;IACzF,KAAK,EAAE,MAAM,CAAA;IACb,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAA;IAClB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,8BAA+B,SAAQ,WAAW;IAC/D,IAAI,EAAE,cAAc,CAAA;IACpB,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAA;IACf,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAA;IAClB,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAA;IAClB,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,uEAAuE;IACvE,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,MAAM,oBAAoB,GAC1B,6BAA6B,GAC7B,8BAA8B,CAAA;AAEpC,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,2CAK1D"}
+{"version":3,"file":"dynamic-relation.d.ts","sourceRoot":"","sources":["../src/dynamic-relation.tsx"],"names":[],"mappings":"AA0CA,YAAY,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AACrE,OAAO,EACH,kBAAkB,EAClB,uBAAuB,EACvB,kBAAkB,EAClB,yBAAyB,EACzB,wBAAwB,EACxB,aAAa,EACb,wBAAwB,EACxB,eAAe,EACf,cAAc,GACjB,MAAM,4BAA4B,CAAA;AAEnC,MAAM,WAAW,sBAAsB;IACnC,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,wBAAwB,EAAE,MAAM,CAAA;IAChC,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,iBAAiB,EAAE,MAAM,CAAA;IACzB,uBAAuB,EAAE,MAAM,CAAA;IAC/B,WAAW,EAAE,MAAM,CAAA;CACtB;AAiBD,UAAU,WAAW;IACjB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;IACzB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB,uCAAuC;IACvC,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,2BAA2B;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAA;IACzC,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;CACxB;AAED,MAAM,WAAW,6BAA8B,SAAQ,WAAW;IAC9D,IAAI,EAAE,aAAa,CAAA;IACnB,yFAAyF;IACzF,KAAK,EAAE,MAAM,CAAA;IACb,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAA;IAClB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,8BAA+B,SAAQ,WAAW;IAC/D,IAAI,EAAE,cAAc,CAAA;IACpB,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAA;IACf,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAA;IAClB,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAA;IAClB,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,uEAAuE;IACvE,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,MAAM,oBAAoB,GAC1B,6BAA6B,GAC7B,8BAA8B,CAAA;AAEpC,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,2CAK1D"}

package/dist/dynamic-relation.js

@@ -33,7 +33,7 @@ export function DynamicRelation(props) {
     }
     return _jsx(OneToManyRelation, { ...props });
 }
-function OneToManyRelation({ kind, model, foreignKey, parentId, endpoint, hiddenColumns = [], canCreate = true, canDelete = true, canEdit = true, strings, className, onChange, }) {
+function OneToManyRelation({ kind, model, foreignKey, parentId, filters, endpoint, hiddenColumns = [], canCreate = true, canDelete = true, canEdit = true, strings, className, onChange, }) {
     const api = useApi();
     const { getMetadata, setMetadata: cacheMetadata } = useMetadataCache();
     const cachedMeta = getMetadata(model);
@@ -46,10 +46,14 @@ function OneToManyRelation({ kind, model, foreignKey, parentId, endpoint, hidden
     const [rowToDelete, setRowToDelete] = useState(null);
     const [submitting, setSubmitting] = useState(false);
     const dataEndpoint = endpoint || `/data/${model}`;
+    // Stable dependency key for the filters object (callers usually pass a fresh
+    // literal each render). Keeps fetchAll from re-firing on identity churn while
+    // still reacting to real scope changes.
+    const filtersKey = useMemo(() => (filters ? JSON.stringify(filters) : ''), [filters]);
     const fetchAll = useCallback(async () => {
         setLoading(true);
         try {
-            const params = buildRelationFilterParams(foreignKey, parentId);
+            const params = buildRelationFilterParams(foreignKey, parentId, filters);
             const [metaRes, dataRes] = await Promise.all([
                 metadata ? Promise.resolve(null) : api.get(`/metadata/table/${model}`),
                 api.get(dataEndpoint, { params }),
@@ -69,15 +73,18 @@ function OneToManyRelation({ kind, model, foreignKey, parentId, endpoint, hidden
         finally {
             setLoading(false);
         }
-    }, [api, dataEndpoint, foreignKey, parentId, metadata, model, cacheMetadata]);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [api, dataEndpoint, foreignKey, parentId, filtersKey, metadata, model, cacheMetadata]);
     useEffect(() => { fetchAll(); }, [fetchAll]);
     const formFields = useMemo(() => deriveRelationFormFields(metadata, foreignKey), [metadata, foreignKey]);
     const visibleColumns = useMemo(() => {
         if (!metadata?.columns)
             return [];
-        const hidden = new Set([foreignKey, ...hiddenColumns]);
+        // Hide the FK and every scope column — they're fixed for this parent and
+        // would just render the same value on every row.
+        const hidden = new Set([foreignKey, ...Object.keys(filters || {}), ...hiddenColumns]);
         return metadata.columns.filter(c => !hidden.has(c.key) && !c.hidden);
-    }, [metadata, foreignKey, hiddenColumns]);
+    }, [metadata, foreignKey, filtersKey, hiddenColumns]);
     const handleSubmit = useCallback(async (values) => {
         setSubmitting(true);
         try {
@@ -87,7 +94,10 @@ function OneToManyRelation({ kind, model, foreignKey, parentId, endpoint, hidden
                     throw new Error('update failed');
             }
             else {
-                const payload = buildCreatePayload(foreignKey, parentId, values);
+                // Scope columns (polymorphic discriminators like owner_model)
+                // are fixed for this relation, so a newly created child must
+                // carry them too — otherwise it would not match the list filter.
+                const payload = { ...(filters || {}), ...buildCreatePayload(foreignKey, parentId, values) };
                 const res = await api.post(dataEndpoint, payload);
                 if (!res.data?.success)
                     throw new Error('create failed');
@@ -103,7 +113,8 @@ function OneToManyRelation({ kind, model, foreignKey, parentId, endpoint, hidden
         finally {
             setSubmitting(false);
         }
-    }, [api, dataEndpoint, editingRow, fetchAll, foreignKey, onChange, parentId]);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [api, dataEndpoint, editingRow, fetchAll, foreignKey, filtersKey, onChange, parentId]);
     const handleDelete = useCallback(async () => {
         if (!rowToDelete)
             return;
@@ -135,7 +146,7 @@ function formatCell(value) {
         return JSON.stringify(value);
     return String(value);
 }
-function ManyToManyRelation({ kind, through, references, foreignKey, referencesKey, parentId, pivotEndpoint, referencesEndpoint, displayKey, canCreate = true, canDelete = true, strings, className, onChange, }) {
+function ManyToManyRelation({ kind, through, references, foreignKey, referencesKey, parentId, filters, pivotEndpoint, referencesEndpoint, displayKey, canCreate = true, canDelete = true, strings, className, onChange, }) {
     const api = useApi();
     const { getMetadata, setMetadata: cacheMetadata } = useMetadataCache();
     const labels = { ...DEFAULT_STRINGS, ...(strings || {}) };
@@ -162,10 +173,11 @@ function ManyToManyRelation({ kind, through, references, foreignKey, referencesK
         ref: useResolver ? references : undefined,
         enabled: useResolver,
     });
+    const filtersKey = useMemo(() => (filters ? JSON.stringify(filters) : ''), [filters]);
     const fetchPivotAndMeta = useCallback(async () => {
         setLoading(true);
         try {
-            const params = buildRelationFilterParams(foreignKey, parentId);
+            const params = buildRelationFilterParams(foreignKey, parentId, filters);
             const tasks = [
                 api.get(pivotPath, { params }),
             ];
@@ -200,7 +212,8 @@ function ManyToManyRelation({ kind, through, references, foreignKey, referencesK
         finally {
             setLoading(false);
         }
-    }, [api, pivotPath, foreignKey, parentId, references, targetMeta, cacheMetadata, useResolver, legacyTargetPath]);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [api, pivotPath, foreignKey, parentId, filtersKey, references, targetMeta, cacheMetadata, useResolver, legacyTargetPath]);
     useEffect(() => { fetchPivotAndMeta(); }, [fetchPivotAndMeta]);
     const options = useMemo(() => {
         if (useResolver) {
@@ -231,7 +244,7 @@ function ManyToManyRelation({ kind, through, references, foreignKey, referencesK
         setSyncing(true);
         try {
             for (const targetId of toAdd) {
-                const payload = buildPivotAttachPayload(foreignKey, parentId, refKey, targetId);
+                const payload = buildPivotAttachPayload(foreignKey, parentId, refKey, targetId, filters || undefined);
                 const res = await api.post(pivotPath, payload);
                 if (!res.data?.success)
                     throw new Error('attach failed');
@@ -258,6 +271,7 @@ function ManyToManyRelation({ kind, through, references, foreignKey, referencesK
         finally {
             setSyncing(false);
         }
-    }, [api, canCreate, canDelete, fetchPivotAndMeta, useResolver, resolved, foreignKey, onChange, parentId, pivotIndex, pivotPath, refKey, selectedIds, syncing]);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [api, canCreate, canDelete, fetchPivotAndMeta, useResolver, resolved, foreignKey, filtersKey, onChange, parentId, pivotIndex, pivotPath, refKey, selectedIds, syncing]);
     return (_jsxs("div", { className: className, "data-relation-kind": kind, "data-relation-through": through, "data-relation-references": references, children: [labels.title && (_jsx("div", { className: "pb-3", children: _jsx("h3", { className: "text-sm font-medium", children: labels.title }) })), (loading || (useResolver && resolved.loading)) ? (_jsx(Skeleton, { className: "h-10 w-full" })) : options.length === 0 ? (_jsx("div", { className: "text-center text-sm text-muted-foreground py-8 border rounded-md bg-muted/30", children: labels.emptyState })) : (_jsx(MultiSelect, { options: options, selected: selectedIds, onChange: handleChange, placeholder: labels.selectPlaceholder, searchPlaceholder: labels.selectSearchPlaceholder, emptyMessage: labels.selectEmpty }))] }));
 }

package/dist/dynamic-relations.d.ts

@@ -0,0 +1,51 @@
+import { 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 declare function resolveParentId(record: {
+    [k: string]: unknown;
+} | null | undefined, parentIdKey?: string): string | number | 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 declare function buildRelationFilters(relation: Pick<RelationMeta, 'foreign_key' | 'scope'>, parentId: string | number): Record<string, string>;
+export declare function DynamicRelations({ record, relations, parentIdKey, className, panelClassName, canCreate, canDelete, canEdit, strings, onChange, }: DynamicRelationsProps): import("react/jsx-runtime").JSX.Element | null;
+//# sourceMappingURL=dynamic-relations.d.ts.map

package/dist/dynamic-relations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-relations.d.ts","sourceRoot":"","sources":["../src/dynamic-relations.tsx"],"names":[],"mappings":"AAaA,OAAO,EAAmB,KAAK,sBAAsB,EAAE,MAAM,oBAAoB,CAAA;AACjF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE3C,MAAM,WAAW,qBAAqB;IAClC;;;OAGG;IACH,MAAM,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,GAAG,SAAS,CAAA;IACzE,gEAAgE;IAChE,SAAS,EAAE,YAAY,EAAE,GAAG,IAAI,GAAG,SAAS,CAAA;IAC5C;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,mCAAmC;IACnC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAA;IACzC,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,YAAY,KAAK,IAAI,CAAA;CAC9C;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC3B,MAAM,EAAE;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,EACnD,WAAW,SAAO,GACnB,MAAM,GAAG,MAAM,GAAG,SAAS,CAM7B;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAChC,QAAQ,EAAE,IAAI,CAAC,YAAY,EAAE,aAAa,GAAG,OAAO,CAAC,EACrD,QAAQ,EAAE,MAAM,GAAG,MAAM,GAC1B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUxB;AAOD,wBAAgB,gBAAgB,CAAC,EAC7B,MAAM,EACN,SAAS,EACT,WAAkB,EAClB,SAAS,EACT,cAAc,EACd,SAAgB,EAChB,SAAgB,EAChB,OAAc,EACd,OAAO,EACP,QAAQ,GACX,EAAE,qBAAqB,kDA4DvB"}

package/dist/dynamic-relations.js

@@ -0,0 +1,76 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// 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 } from './dynamic-relation';
+/**
+ * Normalizes the parent id off the record, tolerating a custom `parentIdKey`.
+ * Returns `undefined` when unusable so callers can guard rendering.
+ */
+export function resolveParentId(record, parentIdKey = 'id') {
+    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, parentId) {
+    const out = {};
+    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, idx) {
+    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, }) {
+    const parentId = useMemo(() => resolveParentId(record, parentIdKey), [record, parentIdKey]);
+    if (parentId === undefined || !relations || relations.length === 0) {
+        return null;
+    }
+    return (_jsx("div", { className: className, "data-dynamic-relations": "", children: relations.map((rel, idx) => {
+            const filters = buildRelationFilters(rel, parentId);
+            const panelStrings = {
+                ...(strings || {}),
+                ...(rel.label ? { title: rel.label } : {}),
+            };
+            if (rel.kind === 'many_to_many') {
+                return (_jsx(DynamicRelation, { 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 }, relationKey(rel, idx)));
+            }
+            return (_jsx(DynamicRelation, { 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 }, relationKey(rel, idx)));
+        }) }));
+}

package/dist/index.d.ts

@@ -25,6 +25,7 @@ export { ExportDialog } from './dialogs/export';
 export { ImportDialog } from './dialogs/import';
 export { DynamicCRUDPage, type DynamicCRUDPageProps, type DynamicCRUDPageStrings, type DynamicCRUDPageClasses, } from './dynamic-crud-page';
 export { DynamicRelation, type DynamicRelationProps, type DynamicRelationStrings, type DynamicRelationKind, buildRelationFilterParams, buildCreatePayload, deriveRelationFormFields, relationRowKey, } from './dynamic-relation';
+export { DynamicRelations, resolveParentId, buildRelationFilters, type DynamicRelationsProps, } from './dynamic-relations';
 export { registerModelExtension, getModelExtension, clearModelExtensions, type ModelExtension, type ModelExtensionProps, } from './model-extension-registry';
 export { isColumnVisibleInTable, getSearchableColumnKeys, } from './column-visibility';
 export { useOptionsResolver, projectOption, type ResolvedOption, type OptionsMeta, type UseOptionsResolverArgs, type UseOptionsResolverResult, } from './use-options-resolver';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -28,6 +28,7 @@ export { ExportDialog } from './dialogs/export';
 export { ImportDialog } from './dialogs/import';
 export { DynamicCRUDPage, } from './dynamic-crud-page';
 export { DynamicRelation, buildRelationFilterParams, buildCreatePayload, deriveRelationFormFields, relationRowKey, } from './dynamic-relation';
+export { DynamicRelations, resolveParentId, buildRelationFilters, } from './dynamic-relations';
 export { registerModelExtension, getModelExtension, clearModelExtensions, } from './model-extension-registry';
 export { isColumnVisibleInTable, getSearchableColumnKeys, } from './column-visibility';
 export { useOptionsResolver, projectOption, } from './use-options-resolver';