@asteby/metacore-runtime-react 47.0.0 → 48.0.0

package/src/types.ts

@@ -1,3 +1,4 @@
+import type { OptionFilter } from './option-filter'
 // Shared metadata shape consumed by every host. Some hosts add a `link`
 // action type with a `linkUrl` template — represented here as part of the
 // `type` union so the SDK can render it uniformly.
@@ -34,6 +35,40 @@ export interface DocumentFormLines {
     required?: boolean
     /** Título del paso. Default «Renglones». */
     title?: string
+    /**
+     * Qué captura el grid (ver primitives/document-kinds LinesMode). Default `sale`.
+     * `allocation` cambia el grid por PaymentAllocator (documentos abiertos de la
+     * contraparte); `credit` limita cantidades a facturado − acreditado.
+     */
+    kind?: 'sale' | 'purchase' | 'credit' | 'allocation' | 'workorder'
+    /** Solo `kind: allocation`: de dónde salen los documentos abiertos. */
+    open_documents?: DocumentFormOpenDocuments
+    /**
+     * Cómo se captura el descuento: `percent` (default del grid), `amount`
+     * (importe) o `both`. Debe coincidir con la fórmula del modelo de renglones:
+     * si el backend calcula `quantity * unit_price - discount`, declara `amount`
+     * (con `percent` un 10 % se restaría como $10).
+     */
+    discount_mode?: 'percent' | 'amount' | 'both'
+}
+
+/** Documentos con saldo de la contraparte para PaymentAllocator. */
+export interface DocumentFormOpenDocuments {
+    /** Modelo (p. ej. `customers.Invoice`, `purchases.SupplierInvoice`). */
+    model: string
+    /** Campo del documento que apunta a la contraparte (`customer_id`). */
+    party_field: string
+    balance_field: string
+    number_field: string
+    total_field?: string
+    due_field?: string
+    issued_field?: string
+    /** Columna con el método (PUE/PPD…); el núcleo solo la muestra. */
+    method_field?: string
+    /** Campo del renglón de la acción donde va el id y el monto (`invoice_id`, `amount`). */
+    line_document_field: string
+    line_amount_field: string
+    option_filter?: unknown
 }
 
 /** Un tipo de documento (Factura, Nota de crédito, REP, Global, Traslado…). */
@@ -54,6 +89,67 @@ export interface DocumentFormType {
     endpoint?: string
     /** Texto del botón final. Default «Crear». */
     submit_label?: string
+    /**
+     * `wizard` (default: Datos → Siguiente → Renglones) o `editor`: UNA pantalla
+     * por secciones (contraparte, origen, renglones o reparto, totales, «Opciones
+     * fiscales» plegadas, vista previa opcional). Ver DocumentEditor.
+     */
+    layout?: 'wizard' | 'editor'
+    /** Contraparte del documento (cliente / proveedor). Solo `layout: editor`. */
+    party?: DocumentFormParty
+    /** «Cargar desde…»: documentos origen cuyos renglones se copian. */
+    sources?: DocumentFormSource[]
+    /** Vista previa / validación previa (acción del modelo con `analyze: true`). */
+    preview?: DocumentFormPreview
+    /**
+     * Guardar llamando a una acción del modelo (placement `create`) en vez del
+     * create genérico. P. ej. Payment → `collect_multi_payment_create`, que ya
+     * reparte el pago en PaymentAllocation dentro de una transacción.
+     */
+    submit_action?: string
+}
+
+/** Contraparte: qué campo del encabezado la elige y qué muestra su tarjeta. */
+export interface DocumentFormParty {
+    /** Campo del encabezado (dynamic_select) con el id. P. ej. `customer_id`. */
+    field: string
+    /** Modelo de la contraparte. P. ej. `customers.Customer`. */
+    model: string
+    /** Endpoint de lectura. Default `/data/<model>`. */
+    endpoint?: string
+    /** Columnas de la tarjeta; además se muestran las extensiones `fiscal_data.*`. */
+    summary?: string[]
+    /** Columnas de crédito/saldo (si existen en el modelo). */
+    credit?: { limit?: string; balance?: string; overdue?: string; hold_reason?: string }
+}
+
+/** Un documento origen para «Cargar desde…». */
+export interface DocumentFormSource {
+    key: string
+    label: string
+    /** Modelo origen (p. ej. `quotes.Quote`). Si el addon no está, se oculta. */
+    model: string
+    /** Relación one_to_many con los renglones (p. ej. `items`). */
+    lines: string
+    /** Mapeo renglón origen → LineItem (`description: product_name`, `discount: discount_pct`…). */
+    map?: Record<string, string>
+    /** Campos del encabezado que se copian del origen (`customer_id: customer_id`). */
+    header?: Record<string, string>
+    /** Campo del documento que guarda el vínculo (p. ej. `sales_order_id`). */
+    link_field?: string
+    /** Filtro de opciones del selector del origen (mismo contrato que option_filter). */
+    option_filter?: unknown
+    /** Addon requerido (gating de UI; el servidor revalida). */
+    requires_addon?: string
+}
+
+/** Vista previa: acción de fila sobre el borrador, llamada con `analyze: true`. */
+export interface DocumentFormPreview {
+    /** Clave de la acción (p. ej. `preview_cfdi`, de fiscal_mexico). */
+    action: string
+    /** Addon que la aporta (si no está instalado, el panel muestra solo totales). */
+    requires_addon?: string
+    label?: string
 }
 
 export interface DocumentFormsManifest {
@@ -64,6 +160,21 @@ export interface DocumentFormsManifest {
     types: DocumentFormType[]
 }
 
+/**
+ * Audit columns of a model, served by the kernel (>= v0.188) on the table
+ * metadata. Each value is the COLUMN NAME (the key in the row), not a value;
+ * a key is omitted when the model lacks that column (append-only ledgers have
+ * only `created_*`). Purely additive — older kernels omit `audit` entirely.
+ */
+export interface AuditMeta {
+    created_at?: string
+    created_by?: string
+    updated_at?: string
+    updated_by?: string
+    deleted_at?: string
+    deleted_by?: string
+}
+
 export interface TableMetadata {
     title: string
     endpoint: string
@@ -78,6 +189,11 @@ export interface TableMetadata {
     canExport?: boolean
     canImport?: boolean
     canCreate?: boolean
+    /**
+     * Audit columns (when/who) of the model. Feeds `<AuditInfo>`; absent on
+     * older kernels or models without audit columns.
+     */
+    audit?: AuditMeta
     /**
      * Formularios de alta guiados por tipo de documento (FAC-12). Cuando trae
      * al menos un tipo, `DynamicCRUDPage` abre `DocumentFormDialog` en lugar del
@@ -380,6 +496,16 @@ export interface ColumnDefinition {
      * widgets — `searchEndpoint` stays as the legacy escape hatch.
      */
     ref?: string
+    /**
+     * Hides options of this relation/dynamic picker (e.g. cancelled invoices in
+     * the payments selector). One rule or a list (AND), tested client-side
+     * against the option's extra columns (`meta`): `{ field: 'status', not_in:
+     * ['cancelada'] }`. The options endpoint must return that column. Absent →
+     * the picker lists everything (retrocompat). See `option-filter.ts`.
+     */
+    optionFilter?: OptionFilter
+    /** snake_case alias served by the kernel manifest for `optionFilter`. */
+    option_filter?: OptionFilter
     /**
      * Write-time rules the SDK also pre-flights. Object form `{regex,min,max,custom}`
      * or a Laravel / go-playground string (`required|min:2|email`).
@@ -526,6 +652,12 @@ export interface ActionFieldDef {
     label: string
     type: string
     required?: boolean
+    /**
+     * Campo de solo lectura (escrito por el servidor/sistema): `DynamicForm` lo
+     * oculta y lo excluye de defaults y submit. Acepta el alias `readOnly`.
+     */
+    readonly?: boolean
+    readOnly?: boolean
     /**
      * Explicit nullability flag served by the kernel (v0.77.1+) from
      * `modelbase.FieldDef.Nullable` (populated as `!Required`). An optional `ref`
@@ -546,6 +678,16 @@ export interface ActionFieldDef {
      * `useOptionsResolver` against `/api/options/<ref>?field=id`.
      */
     ref?: string
+    /**
+     * Hides options of this relation/dynamic picker (e.g. cancelled invoices in
+     * the payments selector). One rule or a list (AND), tested client-side
+     * against the option's extra columns (`meta`): `{ field: 'status', not_in:
+     * ['cancelada'] }`. The options endpoint must return that column. Absent →
+     * the picker lists everything (retrocompat). See `option-filter.ts`.
+     */
+    optionFilter?: OptionFilter
+    /** snake_case alias served by the kernel manifest for `optionFilter`. */
+    option_filter?: OptionFilter
     /**
      * snake_case aliases the kernel manifest may serve for a belongs_to FK
      * target instead of `ref`. Treated as equivalent to `ref` by the SDK so a

package/src/use-options-resolver.ts

@@ -12,6 +12,7 @@
 // free; legacy callers that still ship `searchEndpoint` keep working.
 import { useEffect, useMemo, useRef, useState } from 'react'
 import { useApi } from './api-context'
+import { applyOptionFilter, type OptionFilterRule } from './option-filter'
 import { loadQueryPart, optionsBatchToken, optionsModelFromUrl } from './query-batch'
 
 export interface ResolvedOption {
@@ -90,6 +91,13 @@ export interface UseOptionsResolverArgs {
      * `fieldKey` / `query` / `limit` exactly the same way.
      */
     endpoint?: string
+    /**
+     * Client-side rules that hide fetched options (see `option-filter.ts`).
+     * Empty/undefined → no filtering (retrocompat).
+     */
+    optionFilter?: OptionFilterRule[]
+    /** Current selection: never hidden by `optionFilter`, so its label survives. */
+    keepValue?: unknown
 }
 
 export interface UseOptionsResolverResult {
@@ -182,6 +190,8 @@ export function useOptionsResolver(args: UseOptionsResolverArgs): UseOptionsReso
         enabled = true,
         endpoint,
         filterValue,
+        optionFilter,
+        keepValue,
     } = args
 
     const api = useApi()
@@ -322,8 +332,16 @@ export function useOptionsResolver(args: UseOptionsResolverArgs): UseOptionsReso
         }
     }, [api, url, effectiveField, query, limit, enabled, filterValue, refreshKey])
 
+    // Rules arrive as a fresh array each render; key on their content.
+    const filterKey = optionFilter && optionFilter.length > 0 ? JSON.stringify(optionFilter) : ''
+    const visibleOptions = useMemo(
+        () => (filterKey ? applyOptionFilter(options, optionFilter ?? [], keepValue) : options),
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        [options, filterKey, keepValue],
+    )
+
     return {
-        options,
+        options: visibleOptions,
         meta,
         loading,
         error,

package/vitest.config.ts

@@ -5,5 +5,6 @@ export default defineConfig({
         environment: 'node',
         include: ['src/**/*.test.ts', 'src/**/*.test.tsx'],
         setupFiles: ['./vitest.setup.ts'],
+        testTimeout: 15000,
     },
 })

package/vitest.setup.ts

@@ -27,3 +27,10 @@ function installMemoryStorage(name: 'localStorage' | 'sessionStorage') {
 
 installMemoryStorage('localStorage')
 installMemoryStorage('sessionStorage')
+
+// `waitFor` defaults to 1s; the DynamicTable/DynamicKanban suites render large
+// trees and miss it when the whole monorepo's tests run in parallel (turbo).
+// A longer ceiling only affects failing waits, passing tests return immediately.
+import { configure } from '@testing-library/react'
+
+configure({ asyncUtilTimeout: 5000 })