@asteby/metacore-runtime-react 47.1.0 → 48.0.0

package/src/row-action-stage-gate.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest'
+import { isActionAllowedForRowState, isRowActionVisible, lifecycleStageField } from './dynamic-columns'
+
+// Pitsline taller: WorkOrder has a stage machine (stage_field "stage") and its
+// row actions declare requiresState with STAGE keys. The kernel gates on the
+// stage column; the UI must do the same or every action is hidden (the OT
+// row/kanban menu showed only Ver/Editar/Eliminar).
+describe('requiresState gate with a stage machine', () => {
+    const process = { key: 'process', requiresState: ['reception', 'diagnosis', 'in_process'] }
+    const row = { id: '1', status: 'open', stage: 'diagnosis' }
+
+    it('reads the stage field when the model declares one', () => {
+        expect(isActionAllowedForRowState(process, row, 'stage')).toBe(true)
+        expect(isRowActionVisible(process, row, 'stage')).toBe(true)
+        expect(isActionAllowedForRowState(process, { ...row, stage: 'delivered' }, 'stage')).toBe(false)
+    })
+
+    it('keeps the historical status/state lookup without a stage field', () => {
+        expect(isActionAllowedForRowState(process, row)).toBe(false)
+        expect(isActionAllowedForRowState({ requiresState: ['open'] }, row)).toBe(true)
+    })
+
+    it('falls back to status when the stage value is blank', () => {
+        expect(isActionAllowedForRowState({ requiresState: ['open'] }, { status: 'open', stage: '' }, 'stage')).toBe(true)
+    })
+
+    it('resolves the stage field from metadata', () => {
+        expect(lifecycleStageField({ stage_field: 'stage' })).toBe('stage')
+        expect(lifecycleStageField({ stages: [{ key: 'a' }], group_by: 'stage' })).toBe('stage')
+        expect(lifecycleStageField({ group_by: 'status' })).toBeUndefined()
+        expect(lifecycleStageField(undefined)).toBeUndefined()
+    })
+})

package/src/types.ts

@@ -35,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…). */
@@ -55,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 {
@@ -557,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`