@asteby/metacore-runtime-react 46.4.0 → 47.1.0

package/src/audit-info.tsx

@@ -0,0 +1,219 @@
+/**
+ * audit-info.tsx
+ *
+ * <AuditInfo> — discreet "when and who" footer for a record: created, modified
+ * and (if tombstoned) deleted, each with the actor and a relative + absolute
+ * date. Driven only by the kernel's `TableMetadata.audit` (column names) and
+ * the record row — manifests declare nothing.
+ *
+ * Actor resolution (no extra requests), in order:
+ *   1. the host's `resolveActor(id)` when it returns a name;
+ *   2. the record's expanded sibling (`created_by_id` → `row.created_by`,
+ *      `{ label | name | title }` or a plain string);
+ *   3. the system actor id → "Sistema" / "System";
+ *   4. a short id (first 8 chars) — never a long uuid.
+ *
+ * Renders nothing when `audit` is absent or the record has none of its values.
+ */
+import * as React from 'react'
+import { useTranslation } from 'react-i18next'
+import { formatDistanceToNow } from 'date-fns'
+import { es, enUS } from 'date-fns/locale'
+import { ChevronDown, ChevronRight, History } from 'lucide-react'
+import { cn } from '@asteby/metacore-ui/lib'
+import { formatDateCell } from './dynamic-columns'
+import { objectLabel } from './dynamic-relation-helpers'
+import { isNilUuid } from './nil-uuid'
+import { useTimeZone } from './org-runtime-context'
+import type { AuditMeta } from './types'
+
+/** The kernel's actor for unattended work (schedules, webhooks, connectors). */
+export const SYSTEM_ACTOR_ID = '00000000-0000-0000-0000-000000000001'
+
+const AUDIT_KEYS: (keyof AuditMeta)[] = [
+    'created_at',
+    'created_by',
+    'updated_at',
+    'updated_by',
+    'deleted_at',
+    'deleted_by',
+]
+
+/**
+ * Defensive reader for the served `audit` block: keeps only known keys whose
+ * value is a non-empty string; returns `undefined` when nothing usable remains.
+ */
+export function readAuditMeta(raw: unknown): AuditMeta | undefined {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined
+    const src = raw as Record<string, unknown>
+    const out: AuditMeta = {}
+    for (const k of AUDIT_KEYS) {
+        const v = src[k]
+        if (typeof v === 'string' && v.trim() !== '') out[k] = v
+    }
+    return Object.keys(out).length ? out : undefined
+}
+
+export interface AuditActor {
+    /** Display text. */
+    name: string
+    /** True when the name is a real resolved label (not a short id). */
+    resolved: boolean
+}
+
+/** Resolves the actor stored in `row[idColumn]` to something human. */
+export function resolveAuditActor(
+    row: Record<string, unknown>,
+    idColumn: string | undefined,
+    opts: { resolveActor?: (id: string) => string | undefined; systemLabel: string },
+): AuditActor | null {
+    if (!idColumn) return null
+    const raw = row[idColumn]
+    // The column itself may already be an expanded object.
+    const own = objectLabel(raw)
+    const id = typeof raw === 'string' ? raw.trim() : ''
+    if (!own && (!id || isNilUuid(id))) return null
+    if (id.toLowerCase() === SYSTEM_ACTOR_ID) return { name: opts.systemLabel, resolved: true }
+    if (id) {
+        const fromHost = opts.resolveActor?.(id)
+        if (fromHost) return { name: fromHost, resolved: true }
+    }
+    if (own) return { name: own, resolved: true }
+    const base = idColumn.endsWith('_id') ? idColumn.slice(0, -3) : idColumn
+    const sibling = base === idColumn ? undefined : row[base]
+    const siblingName =
+        objectLabel(sibling) ?? (typeof sibling === 'string' && sibling.trim() !== '' ? sibling : undefined)
+    if (siblingName) return { name: siblingName, resolved: true }
+    return { name: id.length > 8 ? id.slice(0, 8) : id, resolved: false }
+}
+
+const COPY = {
+    es: {
+        title: 'Historial del registro',
+        created: 'Creado por {{who}}',
+        updated: 'Modificado por {{who}}',
+        deleted: 'Eliminado por {{who}}',
+        createdAt: 'Creado',
+        updatedAt: 'Modificado',
+        deletedAt: 'Eliminado',
+        system: 'Sistema',
+    },
+    en: {
+        title: 'Record history',
+        created: 'Created by {{who}}',
+        updated: 'Modified by {{who}}',
+        deleted: 'Deleted by {{who}}',
+        createdAt: 'Created',
+        updatedAt: 'Modified',
+        deletedAt: 'Deleted',
+        system: 'System',
+    },
+} as const
+
+export interface AuditInfoProps {
+    /** The record row (keys are the column names `audit` points at). */
+    record: Record<string, unknown> | null | undefined
+    /** `TableMetadata.audit`. Absent → renders nothing. */
+    audit: AuditMeta | null | undefined
+    /** Optional host resolver uuid → display name (e.g. from a users cache). */
+    resolveActor?: (id: string) => string | undefined
+    /** IANA timezone; defaults to the org runtime timezone. */
+    timeZone?: string
+    /** BCP-47 locale; defaults to the i18n language. */
+    locale?: string
+    /** Start expanded. Default: collapsed. */
+    defaultOpen?: boolean
+    className?: string
+}
+
+interface Line {
+    key: string
+    text: string
+    absolute: string
+    title?: string
+    relative: string
+}
+
+export function AuditInfo({
+    record,
+    audit,
+    resolveActor,
+    timeZone,
+    locale,
+    defaultOpen = false,
+    className,
+}: AuditInfoProps) {
+    const { t, i18n } = useTranslation()
+    const ctxTz = useTimeZone()
+    const [open, setOpen] = React.useState(defaultOpen)
+
+    const meta = readAuditMeta(audit)
+    if (!meta || !record) return null
+
+    const lang = (locale || i18n?.language || 'es').toLowerCase().startsWith('en') ? 'en' : 'es'
+    const copy = COPY[lang]
+    const dfLocale = lang === 'en' ? enUS : es
+    const tz = timeZone ?? ctxTz
+    const tt = (key: keyof typeof copy, vars?: Record<string, string>) =>
+        t(`audit.${key}`, { defaultValue: copy[key], ...vars }) as string
+
+    const build = (
+        key: string,
+        atCol: string | undefined,
+        byCol: string | undefined,
+        whoKey: 'created' | 'updated' | 'deleted',
+        whenKey: 'createdAt' | 'updatedAt' | 'deletedAt',
+    ): Line | null => {
+        const f = atCol ? formatDateCell(record[atCol], undefined, dfLocale, tz) : null
+        if (!f) return null
+        const actor = resolveAuditActor(record, byCol, { resolveActor, systemLabel: tt('system') })
+        const date = new Date(record[atCol as string] as string)
+        const relative = formatDistanceToNow(date, { addSuffix: true, locale: dfLocale })
+        return {
+            key,
+            text: actor ? tt(whoKey, { who: actor.name }) : tt(whenKey),
+            absolute: f.display,
+            title: f.title,
+            relative,
+        }
+    }
+
+    const lines = [
+        build('created', meta.created_at, meta.created_by, 'created', 'createdAt'),
+        // Hide "modified" when it is the creation instant itself (never edited).
+        meta.updated_at && record[meta.updated_at] !== record[meta.created_at ?? '']
+            ? build('updated', meta.updated_at, meta.updated_by, 'updated', 'updatedAt')
+            : null,
+        build('deleted', meta.deleted_at, meta.deleted_by, 'deleted', 'deletedAt'),
+    ].filter((l): l is Line => l !== null)
+
+    if (lines.length === 0) return null
+
+    const Chevron = open ? ChevronDown : ChevronRight
+    return (
+        <div className={cn('text-xs text-muted-foreground', className)} data-testid="audit-info">
+            <button
+                type="button"
+                className="flex items-center gap-1.5 hover:text-foreground"
+                aria-expanded={open}
+                onClick={() => setOpen(o => !o)}
+            >
+                <Chevron className="h-3.5 w-3.5" />
+                <History className="h-3.5 w-3.5" />
+                <span>{tt('title')}</span>
+            </button>
+            {open && (
+                <ul className="mt-2 space-y-1 pl-6">
+                    {lines.map(l => (
+                        <li key={l.key} data-audit-line={l.key}>
+                            <span>{l.text}</span>
+                            {' · '}
+                            <time title={l.title}>{l.absolute}</time>
+                            <span className="opacity-70"> ({l.relative})</span>
+                        </li>
+                    ))}
+                </ul>
+            )}
+        </div>
+    )
+}

package/src/business/catalog.ts

@@ -94,4 +94,28 @@ export const BUSINESS_COMPONENTS: readonly BusinessComponentSpec[] = [
             'recommendationsToLines',
         ],
     },
+    {
+        name: 'VehiclePicker',
+        value: 'value: VehicleResult | null',
+        events: ['onChange'],
+        permissions: ['<model>.create (alta rápida; default Vehicle → vehicle.create)'],
+        usedBy: ['POS', 'Recepción de vehículo', 'OT', 'Cotización', 'Pedido'],
+        helpers: ['describeVehicle'],
+    },
+    {
+        name: 'RelateDocuments',
+        value: 'value: RelatedDocument[] (related_document_id + relation_type)',
+        events: ['onChange'],
+        permissions: [],
+        usedBy: ['Nota de crédito', 'Devolución', 'Sustitución de CFDI', 'REP'],
+        helpers: ['serializeRelatedDocuments'],
+    },
+    {
+        name: 'PrintSendDialog',
+        value: 'document: PrintableDocument (+ open)',
+        events: ['onSend', 'onPrint', 'onOpenChange'],
+        permissions: [],
+        usedBy: ['Cotización', 'Factura', 'Nota de crédito', 'Pedido', 'OC'],
+        helpers: [],
+    },
 ] as const

package/src/business/index.ts

@@ -16,3 +16,6 @@ export * from './return'
 export * from './return-wizard'
 export * from './inspection'
 export * from './inspection-checklist'
+export * from './vehicle-picker'
+export * from './relate-documents'
+export * from './print-send-dialog'

package/src/business/print-send-dialog.tsx

@@ -0,0 +1,175 @@
+// PrintSendDialog — imprimir o enviar un documento ya emitido (cotización,
+// factura, nota de crédito…). El SDK NO llama a un proveedor de mensajería: el
+// host recibe `onSend(channel, destination, document)` y decide qué hacer.
+// Imprimir usa la URL del PDF que pasa el host (o su propio `onPrint`).
+import { useEffect, useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { Mail, MessageCircle, Printer, Loader2 } from 'lucide-react'
+import {
+    Button,
+    Dialog,
+    DialogContent,
+    DialogDescription,
+    DialogFooter,
+    DialogHeader,
+    DialogTitle,
+    Input,
+} from '@asteby/metacore-ui/primitives'
+import { FormErrorBanner } from './feedback'
+
+export type SendChannel = 'email' | 'whatsapp'
+
+export interface PrintableDocument {
+    folio: string
+    /** URL del PDF ya generado. Sin ella no hay «Imprimir». */
+    pdfUrl?: string
+    /** Texto de cabecera («Factura», «Cotización»). */
+    title?: string
+    /** Destinos sugeridos (datos del cliente). */
+    email?: string
+    phone?: string
+}
+
+export interface PrintSendDialogProps {
+    open: boolean
+    onOpenChange: (open: boolean) => void
+    document: PrintableDocument
+    /** Canales de envío disponibles. Default: ambos. Vacío = solo imprimir. */
+    channels?: SendChannel[]
+    /**
+     * Envío a cargo del host. Si rechaza, el mensaje se muestra en el diálogo.
+     * Sin `onSend` no se ofrece enviar.
+     */
+    onSend?: (channel: SendChannel, destination: string, document: PrintableDocument) => Promise<void> | void
+    /** Reemplaza la impresión por defecto (abrir `pdfUrl` en otra pestaña). */
+    onPrint?: (document: PrintableDocument) => void
+}
+
+function defaultPrint(doc: PrintableDocument): void {
+    if (!doc.pdfUrl || typeof window === 'undefined') return
+    window.open(doc.pdfUrl, '_blank', 'noopener,noreferrer')
+}
+
+export function PrintSendDialog({
+    open,
+    onOpenChange,
+    document: doc,
+    channels = ['email', 'whatsapp'],
+    onSend,
+    onPrint,
+}: PrintSendDialogProps) {
+    const { t } = useTranslation()
+    const [channel, setChannel] = useState<SendChannel>(channels[0] ?? 'email')
+    const [destination, setDestination] = useState('')
+    const [sending, setSending] = useState(false)
+    const [sent, setSent] = useState(false)
+    const [error, setError] = useState<string | undefined>()
+
+    const suggested = channel === 'email' ? doc.email : doc.phone
+    useEffect(() => {
+        if (open) {
+            setDestination(suggested ?? '')
+            setSent(false)
+            setError(undefined)
+        }
+    }, [open, channel, suggested])
+
+    const canSend = !!onSend && channels.length > 0
+    const send = async () => {
+        const dest = destination.trim()
+        if (!onSend || !dest) return
+        setSending(true)
+        setError(undefined)
+        setSent(false)
+        try {
+            await onSend(channel, dest, doc)
+            setSent(true)
+        } catch (e) {
+            const msg = (e as { message?: unknown } | undefined)?.message
+            setError(
+                typeof msg === 'string' && msg
+                    ? msg
+                    : t('printSend.error', { defaultValue: 'No se pudo enviar el documento. Inténtalo de nuevo.' }),
+            )
+        } finally {
+            setSending(false)
+        }
+    }
+
+    const channelLabel = (c: SendChannel) =>
+        c === 'email' ? t('printSend.email', { defaultValue: 'Correo' }) : t('printSend.whatsapp', { defaultValue: 'WhatsApp' })
+
+    return (
+        <Dialog open={open} onOpenChange={onOpenChange}>
+            <DialogContent className="sm:max-w-md">
+                <DialogHeader>
+                    <DialogTitle>
+                        {t('printSend.title', { defaultValue: 'Imprimir o enviar' })}
+                        {doc.title ? ` · ${doc.title}` : ''}
+                    </DialogTitle>
+                    <DialogDescription>{doc.folio}</DialogDescription>
+                </DialogHeader>
+
+                <div className="space-y-4">
+                    <Button
+                        type="button"
+                        variant="outline"
+                        className="w-full justify-start"
+                        disabled={!doc.pdfUrl && !onPrint}
+                        onClick={() => (onPrint ?? defaultPrint)(doc)}
+                    >
+                        <Printer className="mr-2 size-4" aria-hidden />
+                        {t('printSend.print', { defaultValue: 'Imprimir' })}
+                    </Button>
+
+                    {canSend && (
+                        <div className="space-y-2">
+                            {channels.length > 1 && (
+                                <div className="flex gap-2" role="group" aria-label={t('printSend.channel', { defaultValue: 'Canal de envío' })}>
+                                    {channels.map((c) => (
+                                        <Button
+                                            key={c}
+                                            type="button"
+                                            size="sm"
+                                            variant={c === channel ? 'default' : 'outline'}
+                                            aria-pressed={c === channel}
+                                            onClick={() => setChannel(c)}
+                                        >
+                                            {c === 'email' ? <Mail className="mr-1.5 size-4" aria-hidden /> : <MessageCircle className="mr-1.5 size-4" aria-hidden />}
+                                            {channelLabel(c)}
+                                        </Button>
+                                    ))}
+                                </div>
+                            )}
+                            <Input
+                                value={destination}
+                                type={channel === 'email' ? 'email' : 'tel'}
+                                aria-label={t('printSend.destination', { defaultValue: 'Destino' })}
+                                placeholder={channel === 'email' ? 'cliente@ejemplo.com' : '+52 55 0000 0000'}
+                                onChange={(e) => setDestination(e.target.value)}
+                            />
+                            <FormErrorBanner message={error} />
+                            {sent && (
+                                <p role="status" className="text-sm text-emerald-600 dark:text-emerald-400">
+                                    {t('printSend.sent', { defaultValue: 'Enviado.' })}
+                                </p>
+                            )}
+                        </div>
+                    )}
+                </div>
+
+                <DialogFooter>
+                    <Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
+                        {t('common.close', { defaultValue: 'Cerrar' })}
+                    </Button>
+                    {canSend && (
+                        <Button type="button" onClick={send} disabled={sending || !destination.trim()}>
+                            {sending && <Loader2 className="mr-2 size-4 animate-spin" aria-hidden />}
+                            {t('printSend.send', { defaultValue: 'Enviar' })}
+                        </Button>
+                    )}
+                </DialogFooter>
+            </DialogContent>
+        </Dialog>
+    )
+}

package/src/business/relate-documents.tsx

@@ -0,0 +1,182 @@
+// RelateDocuments — relaciona uno o más documentos origen (CFDI) desde un
+// formulario: nota de crédito, devolución, sustitución. El valor es DATO
+// (`related_document_id`, `relation_type`, UUID/folio para mostrar), no un flujo
+// de un solo módulo. El SDK no embebe catálogos fiscales: los tipos de relación
+// (p. ej. SAT 01/03/04) llegan por la prop `relationTypes`.
+import { useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { Link2, Search, X } from 'lucide-react'
+import { Badge, Button, Input } from '@asteby/metacore-ui'
+import { useAsyncSearch } from './use-async-search'
+
+export interface RelatableDocument {
+    id: string
+    /** UUID fiscal (CFDI), cuando ya está timbrado. */
+    uuid?: string
+    folio?: string
+    /** Texto libre para mostrar («Factura A-120 · Cliente X»). */
+    label?: string
+    total?: number
+}
+
+export interface RelationTypeOption {
+    /** Clave que viaja en `relation_type` (p. ej. `"01"`). */
+    value: string
+    label: string
+}
+
+/** Un documento relacionado: lo que el formulario guarda. */
+export interface RelatedDocument {
+    related_document_id: string
+    relation_type: string
+    /** Solo para mostrar. */
+    uuid?: string
+    folio?: string
+    label?: string
+}
+
+export interface RelateDocumentsProps {
+    value: RelatedDocument[]
+    onChange: (value: RelatedDocument[]) => void
+    /** Catálogo de tipos de relación (lo aporta el addon). */
+    relationTypes: RelationTypeOption[]
+    /** Búsqueda de documentos origen. Estable (useCallback). */
+    search: (q: string, signal: AbortSignal) => Promise<RelatableDocument[]>
+    /** Tipo preseleccionado al agregar. Default: el primero del catálogo. */
+    defaultRelationType?: string
+    /** Máximo de documentos relacionados. Sin tope por defecto. */
+    max?: number
+    disabled?: boolean
+    placeholder?: string
+}
+
+function docTitle(d: { folio?: string; label?: string; uuid?: string; id?: string }): string {
+    return d.label || d.folio || d.uuid || d.id || ''
+}
+
+export function RelateDocuments({
+    value,
+    onChange,
+    relationTypes,
+    search,
+    defaultRelationType,
+    max,
+    disabled,
+    placeholder,
+}: RelateDocumentsProps) {
+    const { t } = useTranslation()
+    const [text, setText] = useState('')
+    const [pendingType, setPendingType] = useState<string>(defaultRelationType ?? relationTypes[0]?.value ?? '')
+    const { results, loading, error } = useAsyncSearch(text, search, { minChars: 2 })
+    const full = max != null && value.length >= max
+    const typeLabel = (v: string) => relationTypes.find((r) => r.value === v)?.label ?? v
+
+    const add = (d: RelatableDocument) => {
+        if (full || value.some((x) => x.related_document_id === d.id)) return
+        onChange([
+            ...value,
+            { related_document_id: d.id, relation_type: pendingType, uuid: d.uuid, folio: d.folio, label: d.label },
+        ])
+        setText('')
+    }
+    const remove = (id: string) => onChange(value.filter((x) => x.related_document_id !== id))
+    const setType = (id: string, relation_type: string) =>
+        onChange(value.map((x) => (x.related_document_id === id ? { ...x, relation_type } : x)))
+
+    const selectCls = 'h-9 rounded-md border bg-background px-2 text-sm'
+
+    return (
+        <div data-slot="relate-documents" className="space-y-2">
+            {value.length > 0 && (
+                <ul className="divide-y rounded-md border">
+                    {value.map((d) => (
+                        <li key={d.related_document_id} className="flex flex-wrap items-center gap-2 px-2 py-1.5">
+                            <Link2 className="size-4 text-muted-foreground" aria-hidden />
+                            <div className="min-w-0 flex-1">
+                                <p className="truncate text-sm font-medium">{docTitle({ folio: d.folio, label: d.label, id: d.related_document_id })}</p>
+                                {d.uuid && <p className="break-all font-mono text-xs text-muted-foreground">{d.uuid}</p>}
+                            </div>
+                            <select
+                                className={selectCls}
+                                disabled={disabled}
+                                value={d.relation_type}
+                                aria-label={t('relateDocuments.type', { defaultValue: 'Tipo de relación' })}
+                                onChange={(e) => setType(d.related_document_id, e.target.value)}
+                            >
+                                {!relationTypes.some((r) => r.value === d.relation_type) && (
+                                    <option value={d.relation_type}>{typeLabel(d.relation_type)}</option>
+                                )}
+                                {relationTypes.map((r) => (
+                                    <option key={r.value} value={r.value}>{r.label}</option>
+                                ))}
+                            </select>
+                            {!disabled && (
+                                <Button type="button" size="icon" variant="ghost" onClick={() => remove(d.related_document_id)} aria-label={t('relateDocuments.remove', { defaultValue: 'Quitar relación' })}>
+                                    <X className="size-4" />
+                                </Button>
+                            )}
+                        </li>
+                    ))}
+                </ul>
+            )}
+
+            {!full && !disabled && (
+                <div className="space-y-2">
+                    <div className="flex items-center gap-1.5">
+                        <div className="relative flex-1">
+                            <Search className="pointer-events-none absolute left-2.5 top-2.5 size-4 text-muted-foreground" aria-hidden />
+                            <Input
+                                className="pl-8"
+                                value={text}
+                                placeholder={placeholder ?? t('relateDocuments.placeholder', { defaultValue: 'Buscar por folio o UUID' })}
+                                onChange={(e) => setText(e.target.value)}
+                            />
+                        </div>
+                        <select
+                            className={selectCls}
+                            value={pendingType}
+                            aria-label={t('relateDocuments.newType', { defaultValue: 'Tipo para el documento nuevo' })}
+                            onChange={(e) => setPendingType(e.target.value)}
+                        >
+                            {relationTypes.map((r) => (
+                                <option key={r.value} value={r.value}>{r.label}</option>
+                            ))}
+                        </select>
+                    </div>
+                    {loading && <p className="text-sm text-muted-foreground">{t('common.searching', { defaultValue: 'Buscando…' })}</p>}
+                    {error && !loading && (
+                        <p role="alert" className="text-sm text-destructive">
+                            {t('relateDocuments.error', { defaultValue: 'No se pudo buscar documentos. Inténtalo de nuevo.' })}
+                        </p>
+                    )}
+                    {!loading && !error && text.trim().length >= 2 && results.length === 0 && (
+                        <p className="text-sm text-muted-foreground">{t('relateDocuments.empty', { defaultValue: 'No encontramos ese documento.' })}</p>
+                    )}
+                    {results.length > 0 && (
+                        <ul role="listbox" className="max-h-64 divide-y overflow-auto rounded-md border">
+                            {results.map((d) => {
+                                const already = value.some((x) => x.related_document_id === d.id)
+                                return (
+                                    <li key={d.id} role="option" aria-selected={already}>
+                                        <button type="button" disabled={already} className="flex w-full items-center justify-between gap-2 px-2 py-1.5 text-left hover:bg-accent disabled:opacity-50" onClick={() => add(d)}>
+                                            <span>
+                                                <span className="block text-sm font-medium">{docTitle(d)}</span>
+                                                {d.uuid && <span className="block break-all font-mono text-xs text-muted-foreground">{d.uuid}</span>}
+                                            </span>
+                                            {already && <Badge variant="muted">{t('relateDocuments.added', { defaultValue: 'Agregado' })}</Badge>}
+                                        </button>
+                                    </li>
+                                )
+                            })}
+                        </ul>
+                    )}
+                </div>
+            )}
+        </div>
+    )
+}
+
+/** Valor a enviar al servidor: solo los datos, sin los campos de visualización. */
+export function serializeRelatedDocuments(value: RelatedDocument[]): Array<Pick<RelatedDocument, 'related_document_id' | 'relation_type'>> {
+    return value.map(({ related_document_id, relation_type }) => ({ related_document_id, relation_type }))
+}