@asteby/metacore-runtime-react 28.6.0 → 28.8.0

package/src/entity-select.tsx

@@ -0,0 +1,316 @@
+// EntitySelect — the shared, permission-aware single-select for a related model.
+//
+// A searchable async combobox over a kernel model's records, plus the two
+// affordances every "pick a related record" control should have, exactly like
+// the dynamic create modal's relation fields (Categoría/Marca) do:
+//
+//   - nothing selected → a "+" that opens the model's CREATE dialog, and
+//     auto-selects the record it creates;
+//   - a record selected → a pencil that opens that record's EDIT dialog.
+//
+// Both affordances are gated by the kernel permissions (useCan): the "+" only
+// shows when the user can create the model, the pencil only when they can edit
+// it. Everything is DYNAMIC — the create/edit form comes from the model's
+// `/metadata/modal/:model` schema via <CreateRecordDialog>, so no per-model form
+// code is needed. This lives in the SDK so POS, purchases and any future addon
+// share ONE implementation instead of each re-porting a bespoke picker.
+import { useCallback, useEffect, useState } from 'react'
+import { Search, X, Plus, Pencil, type LucideIcon } from 'lucide-react'
+import {
+    Button,
+    Command,
+    CommandEmpty,
+    CommandGroup,
+    CommandInput,
+    CommandItem,
+    CommandList,
+    Popover,
+    PopoverContent,
+    PopoverTrigger,
+} from '@asteby/metacore-ui'
+import { CreateRecordDialog } from './dialogs/create-record-dialog'
+import { useCan } from './permissions-context'
+import { useApi } from './api-context'
+
+/** One searchable option: `value` is the id, `label` the display text. */
+export interface EntitySelectOption {
+    value: string
+    label: string
+    description?: string
+}
+
+export interface EntitySelectProps {
+    /** Kernel model key (e.g. "Supplier", "Warehouse", "Category"). */
+    model: string
+    /** Currently selected id (or null). */
+    value: string | null
+    /** Label of the selected record (rendered without a re-fetch). */
+    label: string | null
+    /** Called with (id, label) on select/create/clear. */
+    onSelect: (id: string | null, label: string | null) => void
+    /** Async search over the model. Callers pass their `/api/options/<model>` fetcher. */
+    fetcher: (q: string, signal: AbortSignal) => Promise<EntitySelectOption[]>
+
+    icon?: LucideIcon
+    placeholder?: string
+    searchPlaceholder?: string
+    emptyText?: string
+    /** Preload first results on open and drop the 2-char gate. */
+    preload?: boolean
+
+    /**
+     * Permission overrides. By default create/edit are gated by the kernel
+     * permissions `<model>.create` / `<model>.update` (useCan). Pass explicit
+     * booleans to force them (e.g. a read-only surface).
+     */
+    canCreate?: boolean
+    canEdit?: boolean
+
+    /**
+     * CRUD endpoint base for the create/edit dialog. Defaults to the standard
+     * org-scoped `/data/<model>/me`, with edit at `/data/<model>/me/<id>`.
+     */
+    endpoint?: string
+    /** Record field used as the label after create/edit (default "name"). */
+    labelField?: string
+    /** Disable the whole control. */
+    disabled?: boolean
+}
+
+/** Lowercase model → permission capability namespace (Supplier → supplier). */
+function capabilityNamespace(model: string): string {
+    return model.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase()
+}
+
+export function EntitySelect({
+    model,
+    value,
+    label,
+    onSelect,
+    fetcher,
+    icon: Icon,
+    placeholder = 'Seleccionar…',
+    searchPlaceholder = 'Buscar…',
+    emptyText = 'Sin resultados',
+    preload = false,
+    canCreate,
+    canEdit,
+    endpoint,
+    labelField = 'name',
+    disabled = false,
+}: EntitySelectProps) {
+    const can = useCan()
+    const api = useApi()
+
+    const ns = capabilityNamespace(model)
+    const mayCreate = canCreate ?? can(`${ns}.create`)
+    const mayEdit = canEdit ?? can(`${ns}.update`)
+    const base = endpoint ?? `/data/${model}/me`
+
+    const [open, setOpen] = useState(false)
+    const [dialogOpen, setDialogOpen] = useState(false)
+    const [dialogRecordId, setDialogRecordId] = useState<string | undefined>(undefined)
+    const [searchTerm, setSearchTerm] = useState('')
+    const [results, setResults] = useState<EntitySelectOption[]>([])
+    const [isLoading, setIsLoading] = useState(false)
+
+    const minChars = preload ? 0 : 2
+
+    const run = useCallback(
+        async (q: string, signal: AbortSignal) => {
+            if (q.length < minChars) {
+                setResults([])
+                return
+            }
+            setIsLoading(true)
+            try {
+                const rows = await fetcher(q, signal)
+                if (!signal.aborted) setResults(rows)
+            } catch {
+                if (!signal.aborted) setResults([])
+            } finally {
+                if (!signal.aborted) setIsLoading(false)
+            }
+        },
+        [fetcher, minChars],
+    )
+
+    useEffect(() => {
+        if (!open) return
+        const controller = new AbortController()
+        const timeout = setTimeout(() => run(searchTerm, controller.signal), 250)
+        return () => {
+            clearTimeout(timeout)
+            controller.abort()
+        }
+    }, [searchTerm, run, open])
+
+    const pick = (row: EntitySelectOption) => {
+        onSelect(row.value, row.label)
+        setOpen(false)
+        setSearchTerm('')
+    }
+
+    const clear = (e: React.MouseEvent) => {
+        e.stopPropagation()
+        onSelect(null, null)
+    }
+
+    const openCreate = (e: React.MouseEvent) => {
+        e.stopPropagation()
+        setDialogRecordId(undefined)
+        setDialogOpen(true)
+    }
+    const openEdit = (e: React.MouseEvent) => {
+        e.stopPropagation()
+        if (!value) return
+        setDialogRecordId(value)
+        setDialogOpen(true)
+    }
+
+    // Read the {id,label} off a saved record and select it. The transport
+    // matches the standard org-scoped CRUD the dynamic modal uses, so create/edit
+    // stay consistent with the rest of the app.
+    const selectSaved = (rec: Record<string, unknown> | undefined | null) => {
+        if (!rec) return
+        const id = rec.id != null ? String(rec.id) : value ?? ''
+        const lbl =
+            (rec[labelField] != null && String(rec[labelField])) ||
+            (rec.name != null && String(rec.name)) ||
+            label ||
+            id
+        onSelect(id, lbl)
+    }
+
+    return (
+        <div className="flex items-center gap-1.5">
+            <Popover open={open} onOpenChange={disabled ? undefined : setOpen}>
+                <PopoverTrigger asChild>
+                    <Button
+                        variant="outline"
+                        disabled={disabled}
+                        className="w-full flex-1 justify-start gap-2 font-normal"
+                    >
+                        {Icon && <Icon className="text-muted-foreground size-4 shrink-0" />}
+                        <span className="flex-1 truncate text-left">{label ?? placeholder}</span>
+                        {value && (
+                            <span
+                                role="button"
+                                tabIndex={0}
+                                onClick={clear}
+                                onKeyDown={(e) => {
+                                    if (e.key === 'Enter' || e.key === ' ')
+                                        clear(e as unknown as React.MouseEvent)
+                                }}
+                                className="hover:bg-accent ml-auto shrink-0 rounded-sm p-0.5"
+                            >
+                                <X className="size-3.5" />
+                            </span>
+                        )}
+                    </Button>
+                </PopoverTrigger>
+                <PopoverContent
+                    className="p-0"
+                    align="start"
+                    style={{ width: 'var(--radix-popover-trigger-width)' }}
+                >
+                    <Command shouldFilter={false}>
+                        <CommandInput
+                            placeholder={searchPlaceholder}
+                            value={searchTerm}
+                            onValueChange={setSearchTerm}
+                        />
+                        <CommandList>
+                            {isLoading && (
+                                <div className="text-muted-foreground py-4 text-center text-sm">
+                                    Buscando…
+                                </div>
+                            )}
+                            {!isLoading &&
+                                searchTerm.length >= minChars &&
+                                results.length === 0 && <CommandEmpty>{emptyText}</CommandEmpty>}
+                            {!isLoading && results.length > 0 && (
+                                <CommandGroup className="max-h-64 overflow-auto">
+                                    {results.map((row) => (
+                                        <CommandItem
+                                            key={row.value}
+                                            value={row.value}
+                                            onSelect={() => pick(row)}
+                                            className="flex flex-col items-start gap-0.5"
+                                        >
+                                            <span className="text-sm font-medium">{row.label}</span>
+                                            {row.description && (
+                                                <span className="text-muted-foreground text-xs">
+                                                    {row.description}
+                                                </span>
+                                            )}
+                                        </CommandItem>
+                                    ))}
+                                </CommandGroup>
+                            )}
+                            {!isLoading && !preload && searchTerm.length < minChars && (
+                                <div className="text-muted-foreground flex flex-col items-center gap-1 py-6">
+                                    <Search className="size-5" />
+                                    <span className="text-xs">Escribe al menos 2 caracteres</span>
+                                </div>
+                            )}
+                        </CommandList>
+                    </Command>
+                </PopoverContent>
+            </Popover>
+
+            {/* Selected → edit (pencil); empty → create (+). Each gated by perms. */}
+            {value
+                ? mayEdit && (
+                      <Button
+                          type="button"
+                          variant="outline"
+                          size="icon"
+                          disabled={disabled}
+                          onClick={openEdit}
+                          aria-label="Editar"
+                          title="Editar"
+                          className="shrink-0"
+                      >
+                          <Pencil className="size-4" />
+                      </Button>
+                  )
+                : mayCreate && (
+                      <Button
+                          type="button"
+                          variant="outline"
+                          size="icon"
+                          disabled={disabled}
+                          onClick={openCreate}
+                          aria-label="Crear"
+                          title="Crear"
+                          className="shrink-0"
+                      >
+                          <Plus className="size-4" />
+                      </Button>
+                  )}
+
+            {dialogOpen && (
+                <CreateRecordDialog
+                    modelKey={model}
+                    open={dialogOpen}
+                    onOpenChange={setDialogOpen}
+                    recordId={dialogRecordId}
+                    endpoint={base}
+                    onCreate={async (data) => {
+                        const res = await api.post(base, data)
+                        const rec = (res.data?.data ?? res.data) as Record<string, unknown>
+                        selectSaved(rec)
+                        return rec.id != null ? { id: String(rec.id) } : undefined
+                    }}
+                    onUpdate={async (id, data) => {
+                        const res = await api.put(`${base}/${id}`, data)
+                        const rec = (res.data?.data ?? res.data) as Record<string, unknown>
+                        selectSaved({ id, ...rec })
+                        return { id: String(id) }
+                    }}
+                />
+            )}
+        </div>
+    )
+}

package/src/index.ts

@@ -175,6 +175,8 @@ export * from './navigation-builder'
 export * from './i18n-provider'
 export * from './api-context'
 export * from './use-addon-settings'
+export * from './use-print-document'
+export * from './print-document-button'
 export * from './metadata-cache'
 export {
     ADDON_MANIFEST_CHANGED_TYPE,
@@ -242,6 +244,8 @@ export { DynamicRecordDialog, ViewValue } from './dialogs/dynamic-record'
 export { normalizeRefFieldsForSubmit } from './dialogs/normalize-submit'
 export type { DynamicRecordDialogProps, FieldDef, FieldOption, GetImageUrl } from './dialogs/dynamic-record'
 export { CreateRecordDialog } from './dialogs/create-record-dialog'
+export { EntitySelect } from './entity-select'
+export type { EntitySelectProps, EntitySelectOption } from './entity-select'
 export { ViewRecordDialog } from './dialogs/view-record-dialog'
 export type {
     ModelKey,

package/src/print-document-button.tsx

@@ -0,0 +1,75 @@
+// PrintDocumentButton — a drop-in button that prints/downloads a server-rendered
+// document via usePrintDocument, so an addon doesn't re-wire the hook + loading
+// state every time. Headless-friendly: it renders a plain <button> you style
+// with `className`, disables itself while the PDF is fetching, and reports
+// failures through `onError` (no toast dependency baked in).
+//
+// Example:
+//   <PrintDocumentButton model="SalesOrder" id={sale.id} documentKey="sale_ticket"
+//     className="btn">Imprimir ticket</PrintDocumentButton>
+import React, { useCallback, useState } from 'react'
+import { usePrintDocument, type PrintDocumentArgs } from './use-print-document'
+
+export interface PrintDocumentButtonProps
+    extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'onError'> {
+    /** Model KEY the document is declared against (e.g. "SalesOrder"). */
+    model: string
+    /** Record id. */
+    id: string
+    /** Document key from contributions.documents[].key (e.g. "sale_ticket"). */
+    documentKey: string
+    /** print (default) | download | open — see usePrintDocument. */
+    mode?: PrintDocumentArgs['mode']
+    /** Download filename (mode="download"). */
+    filename?: string
+    /** Called if the fetch/print fails (surface it to a toast in the host). */
+    onError?: (err: unknown) => void
+    /** Rendered while the PDF is being fetched, in place of children. */
+    pendingLabel?: React.ReactNode
+    children?: React.ReactNode
+}
+
+export function PrintDocumentButton({
+    model,
+    id,
+    documentKey,
+    mode,
+    filename,
+    onError,
+    pendingLabel,
+    children,
+    disabled,
+    onClick,
+    ...rest
+}: PrintDocumentButtonProps) {
+    const printDocument = usePrintDocument()
+    const [busy, setBusy] = useState(false)
+
+    const handleClick = useCallback(
+        async (e: React.MouseEvent<HTMLButtonElement>) => {
+            onClick?.(e)
+            if (e.defaultPrevented) return
+            setBusy(true)
+            try {
+                await printDocument({ model, id, key: documentKey, mode, filename })
+            } catch (err) {
+                onError?.(err)
+            } finally {
+                setBusy(false)
+            }
+        },
+        [printDocument, model, id, documentKey, mode, filename, onError, onClick],
+    )
+
+    return (
+        <button
+            type="button"
+            {...rest}
+            disabled={disabled || busy}
+            aria-busy={busy || undefined}
+            onClick={handleClick}
+        >
+            {busy && pendingLabel != null ? pendingLabel : children}
+        </button>
+    )
+}

package/src/types.ts

@@ -1,6 +1,27 @@
 // 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.
+/** One spreadsheet column of a model's import template. Mirrors the kernel's
+ *  `modelbase.ImportColumn`. */
+export interface ImportColumnMeta {
+    key: string
+    header: string
+    aliases?: string[]
+    required?: boolean
+    type?: string
+    example?: string
+    hint?: string
+    generator?: string
+}
+
+/** A model's spreadsheet-import declaration. Mirrors `modelbase.ImportSpec`. */
+export interface ImportSpecMeta {
+    columns: ImportColumnMeta[]
+    maxRows?: number
+    sheetName?: string
+    instructions?: string[]
+}
+
 export interface TableMetadata {
     title: string
     endpoint: string
@@ -15,6 +36,16 @@ export interface TableMetadata {
     canExport?: boolean
     canImport?: boolean
     canCreate?: boolean
+    /**
+     * The model's spreadsheet-import declaration, served by the kernel: the
+     * columns of the generated template and the headers accepted when parsing
+     * a filled file back in. The kernel derives it from the model's form
+     * fields when the model declares nothing, and omits the field entirely
+     * when the model has no importable column — so its presence is the signal
+     * that importing is meaningful for this model. Purely additive; older
+     * kernels omit it.
+     */
+    import?: ImportSpecMeta
     /**
      * Child relations of this model, served by the kernel (>= v0.41.0). A
      * generic detail page renders one `DynamicRelation` panel per entry via

package/src/use-print-document.ts

@@ -0,0 +1,112 @@
+// usePrintDocument — THE standard primitive for printing/downloading a
+// server-rendered document (ticket, receipt, order) from any federated addon or
+// host surface, without each addon reimplementing PDF fetching.
+//
+// The host (ops) renders documents declared in an addon's
+// `contributions.documents[]` via a country/business-agnostic engine
+// (pdf_chrome + document_render + org branding) and serves them at:
+//
+//   GET /api/data/:model/:id/documents/:key.pdf  → application/pdf
+//
+// The endpoint is auth-gated (Bearer), so we CANNOT just window.open the URL —
+// that request carries no Authorization header and 401s. Instead we fetch the
+// PDF through the injected ApiClient (which carries the token), turn the bytes
+// into a blob URL, and print/download/open that. Re-printing is just calling
+// this again — the render is an idempotent GET.
+//
+// The ApiClient is a PEER via <ApiProvider> (same one useAddonSettings uses), so
+// this hook constructs no client of its own.
+import { useCallback } from 'react'
+import { useApi } from './api-context'
+
+export interface PrintDocumentArgs {
+    /** The model KEY the document is declared against (e.g. "SalesOrder"). */
+    model: string
+    /** The record id. */
+    id: string
+    /** The document key from contributions.documents[].key (e.g. "sale_ticket"). */
+    key: string
+    /**
+     * print  → open the PDF in a hidden iframe and fire the browser print dialog
+     *          (default; best for thermal tickets — one click to the printer).
+     * download → save the PDF to disk.
+     * open   → open the PDF in a new tab (user prints from the viewer).
+     */
+    mode?: 'print' | 'download' | 'open'
+    /** Filename for the download mode (defaults to "<key>.pdf"). */
+    filename?: string
+}
+
+/**
+ * Returns a `printDocument(args)` callback. Resolves once the PDF has been
+ * fetched and the browser action (print/download/open) has been kicked off;
+ * rejects if the fetch fails (surface the error to a toast). Returns the blob
+ * URL created, revoked automatically after a minute.
+ */
+export function usePrintDocument() {
+    const api = useApi()
+    return useCallback(
+        async ({
+            model,
+            id,
+            key,
+            mode = 'print',
+            filename,
+        }: PrintDocumentArgs): Promise<string> => {
+            const url = `/data/${encodeURIComponent(model)}/${encodeURIComponent(
+                id,
+            )}/documents/${encodeURIComponent(key)}.pdf`
+            const res = await api.get(url, { responseType: 'blob' })
+            const blob =
+                res.data instanceof Blob
+                    ? res.data
+                    : new Blob([res.data], { type: 'application/pdf' })
+            const blobUrl = URL.createObjectURL(blob)
+            const cleanup = () => setTimeout(() => URL.revokeObjectURL(blobUrl), 60_000)
+
+            if (mode === 'download') {
+                const a = document.createElement('a')
+                a.href = blobUrl
+                a.download = filename || `${key}.pdf`
+                document.body.appendChild(a)
+                a.click()
+                a.remove()
+                cleanup()
+                return blobUrl
+            }
+
+            if (mode === 'open') {
+                window.open(blobUrl, '_blank')
+                cleanup()
+                return blobUrl
+            }
+
+            // mode === 'print': hidden iframe + contentWindow.print(). This is the
+            // reliable cross-browser way to auto-open the print dialog for a PDF
+            // blob (window.open + print() is blocked by the PDF viewer in Chrome).
+            const iframe = document.createElement('iframe')
+            iframe.style.position = 'fixed'
+            iframe.style.right = '0'
+            iframe.style.bottom = '0'
+            iframe.style.width = '0'
+            iframe.style.height = '0'
+            iframe.style.border = '0'
+            iframe.src = blobUrl
+            iframe.onload = () => {
+                try {
+                    iframe.contentWindow?.focus()
+                    iframe.contentWindow?.print()
+                } catch {
+                    // Popup/print blocked — fall back to opening the PDF.
+                    window.open(blobUrl, '_blank')
+                }
+                // Keep the iframe around long enough for the print dialog to read it.
+                setTimeout(() => iframe.remove(), 60_000)
+                cleanup()
+            }
+            document.body.appendChild(iframe)
+            return blobUrl
+        },
+        [api],
+    )
+}