@asteby/metacore-runtime-react 34.0.2 → 35.0.0

package/src/display-value.tsx

@@ -78,24 +78,102 @@ export const RelationThumbnail: React.FC<{
     size?: number
 }> = ({ src, alt, getImageUrl, size = 20 }) => (
     <Avatar
-        className="shrink-0 rounded-md bg-muted/50 p-[3px] ring-1 ring-border/40"
+        className="shrink-0 rounded-md"
         style={{ width: size, height: size }}
     >
         {/* object-contain: brand logos are typically wide/rectangular, so
             object-cover (fills the square, cropping the sides) was cutting
-            them off. contain lets the whole mark show, letterboxed by the
-            padded neutral background above instead of clipped. */}
+            them off. contain shows the whole mark without a padded plate. */}
         <AvatarImage
             src={getImageUrl ? getImageUrl(src) : src}
             alt={alt}
             className="object-contain"
         />
-        <AvatarFallback className="rounded-md bg-primary/10 text-[8px] font-bold text-primary">
+        <AvatarFallback className="rounded-md bg-transparent text-[8px] font-bold text-muted-foreground">
             {getInitials(alt)}
         </AvatarFallback>
     </Avatar>
 )
 
+/**
+ * Landscape-friendly identity block: wide image ON TOP, label (and optional
+ * subtitle) UNDERNEATH. Use for brand logos, product photos and any mark that
+ * is wider than it is tall — a square thumb next to text crops logos and
+ * wastes the cell. Declared via `display: "image_stack"` on a column (image
+ * URL or FK relation with a logo/photo sibling).
+ *
+ * No padded card / muted plate behind the mark — that ate table row height.
+ * The image is sized with max-width/max-height and `object-contain` only.
+ *
+ * Sizes (CSS, not Tailwind arbitrary — host safelists vary):
+ *   sm — compact table (~88×32)
+ *   md — default table (~112×40)
+ *   lg — detail/modal (~180×72)
+ */
+export const ImageStack: React.FC<{
+    src?: string | null
+    label?: string | null
+    subtitle?: string | null
+    getImageUrl?: (path: string) => string
+    size?: 'sm' | 'md' | 'lg'
+    className?: string
+}> = ({ src, label, subtitle, getImageUrl, size = 'md', className }) => {
+    const dims =
+        size === 'lg'
+            ? { w: 180, h: 72, text: 'text-sm' }
+            : size === 'sm'
+              ? { w: 88, h: 32, text: 'text-[11px]' }
+              : { w: 112, h: 40, text: 'text-xs' }
+    const alt = label || ''
+    const resolved = src
+        ? getImageUrl
+            ? getImageUrl(src)
+            : src
+        : undefined
+    const [broken, setBroken] = React.useState(false)
+    React.useEffect(() => {
+        setBroken(false)
+    }, [resolved])
+
+    return (
+        <span
+            className={`inline-flex max-w-[220px] flex-col items-start gap-0.5 ${className ?? ''}`}
+            title={subtitle ? `${alt} · ${subtitle}` : alt || undefined}
+        >
+            {resolved && !broken ? (
+                <img
+                    src={resolved}
+                    alt={alt}
+                    className="block object-contain"
+                    style={{ maxWidth: dims.w, maxHeight: dims.h, width: 'auto', height: 'auto' }}
+                    onError={() => setBroken(true)}
+                />
+            ) : (
+                <span
+                    className="flex items-center text-[10px] font-semibold tracking-wide text-muted-foreground"
+                    style={{ minHeight: Math.round(dims.h * 0.55) }}
+                >
+                    {getInitials(alt || '?')}
+                </span>
+            )}
+            {(label || subtitle) && (
+                <span className={`flex w-full min-w-0 flex-col items-start leading-tight ${dims.text}`}>
+                    {label ? (
+                        <span className="w-full truncate text-left font-medium text-foreground/90">
+                            {label}
+                        </span>
+                    ) : null}
+                    {subtitle ? (
+                        <span className="w-full truncate text-left text-[0.7em] text-muted-foreground">
+                            {subtitle}
+                        </span>
+                    ) : null}
+                </span>
+            )}
+        </span>
+    )
+}
+
 export interface DisplayOption {
     value: string
     label: string

package/src/dynamic-columns.tsx

@@ -47,6 +47,7 @@ import { objectLabel } from './dynamic-relation-helpers'
 import {
     OptionBadge,
     RelationThumbnail,
+    ImageStack,
     statusColorFor,
     useIsDarkTheme,
 } from './display-value'
@@ -494,7 +495,7 @@ export const resolveRelationLabel = (col: ColumnDefinition, row: any): string =>
 export const resolveRelationImage = (col: ColumnDefinition, row: any): string => {
     const sibling = getNestedValue(row, relationKeyFor(col))
     if (sibling && typeof sibling === 'object') {
-        const img = sibling.image ?? sibling.avatar ?? sibling.photo
+        const img = sibling.image ?? sibling.avatar ?? sibling.photo ?? sibling.logo ?? sibling.thumbnail
         if (img !== undefined && img !== null && img !== '') return String(img)
     }
     return ''
@@ -603,16 +604,33 @@ export const resolveRelationSubtitle = (col: ColumnDefinition, row: any): string
  * carries an `image`. Falls back to the raw id when no sibling was resolved, and
  * to an empty marker when there is no value at all. Domain-agnostic: works for
  * every `belongs_to` column (category, supplier, brand, …) without per-addon code.
+ *
+ * When `stack` is true (column `display: "image_stack"`), the landscape mark
+ * sits ON TOP of the label — wide logos fit without cropping and the cell
+ * stays readable in dense tables.
  */
 const RelationCell: React.FC<{
     col: ColumnDefinition
     row: any
     getImageUrl?: (path: string) => string
-}> = ({ col, row, getImageUrl }) => {
+    /** Landscape stack: image above, text below (display: image_stack). */
+    stack?: boolean
+}> = ({ col, row, getImageUrl, stack = false }) => {
     const display = resolveRelationLabel(col, row)
     if (!display) return <EmptyCell />
     const image = resolveRelationImage(col, row)
     const subtitle = resolveRelationSubtitle(col, row)
+    if (stack) {
+        return (
+            <ImageStack
+                src={image || undefined}
+                label={display}
+                subtitle={subtitle || undefined}
+                getImageUrl={getImageUrl}
+                size="md"
+            />
+        )
+    }
     // FLAT reference cell: no tinted capsule around the pair. A reference is
     // data, not a status — the pill treatment (and its per-label tint) made a
     // products/warehouses listing read as a wall of badges. What identifies the
@@ -751,15 +769,29 @@ const AvatarCell: React.FC<{
 export const ImageCell: React.FC<{
     value: unknown
     getImageUrl: (path: string) => string
-}> = ({ value, getImageUrl }) => {
-    if (!value) return <span className="text-muted-foreground">-</span>
-    if (isLucideIconName(value)) {
+    /** Optional caption under the image (display: image_stack). */
+    label?: string
+    stack?: boolean
+}> = ({ value, getImageUrl, label, stack = false }) => {
+    if (!value && !label) return <span className="text-muted-foreground">-</span>
+    if (value && isLucideIconName(value)) {
         return (
             <div className="h-10 w-10 flex items-center justify-center rounded bg-muted">
                 <DynamicIcon name={value} className="h-5 w-5" />
             </div>
         )
     }
+    if (stack) {
+        return (
+            <ImageStack
+                src={value ? String(value) : undefined}
+                label={label}
+                getImageUrl={getImageUrl}
+                size="md"
+            />
+        )
+    }
+    if (!value) return <span className="text-muted-foreground">-</span>
     return (
         <div className="h-10 w-10 relative rounded overflow-hidden bg-muted flex items-center justify-center">
             <img
@@ -916,6 +948,45 @@ export function makeDefaultGetDynamicColumns(
                         return <ReferenceCell col={col} row={row.original} />
                     }
 
+                    // Landscape stack: wide image ON TOP, label UNDERNEATH.
+                    // Declared via `display: "image_stack"` on an image column
+                    // or on a belongs_to FK whose sibling carries a logo/photo
+                    // (brand marks, product cards). Fits logos that are wider
+                    // than tall without cropping into a square thumb.
+                    if (renderAs === 'image_stack') {
+                        // FK relation (brand_id → brands) OR any column that
+                        // already resolved a sibling with an image — stack it.
+                        // Don't require `col.ref` alone: enrichment sometimes
+                        // leaves type=text while cellStyle carries image_stack.
+                        const looksRelation =
+                            !!col.ref ||
+                            (typeof col.key === 'string' &&
+                                col.key.endsWith('_id') &&
+                                resolveRelationLabel(col, row.original) != null)
+                        if (looksRelation) {
+                            return (
+                                <RelationCell
+                                    col={col}
+                                    row={row.original}
+                                    getImageUrl={getImageUrl}
+                                    stack
+                                />
+                            )
+                        }
+                        const labelField = styleCfg(col, 'label_field', 'labelField')
+                        const caption = labelField
+                            ? String(getNestedValue(row.original, labelField) ?? '')
+                            : undefined
+                        return (
+                            <ImageCell
+                                value={value}
+                                getImageUrl={getImageUrl}
+                                label={caption || undefined}
+                                stack
+                            />
+                        )
+                    }
+
                     // Resolved FK relation chip. Triggers on an explicit
                     // `cellStyle: 'relation'` or on any column carrying a `ref`
                     // (a belongs_to FK) that isn't being rendered as an
@@ -1283,6 +1354,24 @@ export function makeDefaultGetDynamicColumns(
                             return <ImageCell value={imageValue} getImageUrl={getImageUrl} />
                         }
 
+                        case 'image_stack': {
+                            // Defensive: normally handled above before the
+                            // switch; kept so a late `type: image_stack` without
+                            // cellStyle still stacks.
+                            const labelField = styleCfg(col, 'label_field', 'labelField')
+                            const caption = labelField
+                                ? String(getNestedValue(row.original, labelField) ?? '')
+                                : undefined
+                            return (
+                                <ImageCell
+                                    value={value}
+                                    getImageUrl={getImageUrl}
+                                    label={caption || undefined}
+                                    stack
+                                />
+                            )
+                        }
+
                         default: {
                             if (typeof value === 'object' && value !== null) {
                                 return (

package/src/dynamic-select-field.tsx

@@ -22,6 +22,7 @@
 // value). A dedicated `?ids=` lookup is a follow-up; create flows — the common
 // case — start empty and never hit this.
 import { useEffect, useRef, useState } from 'react'
+import { useTranslation } from 'react-i18next'
 import {
     Badge,
     Button,
@@ -40,6 +41,7 @@ import { Check, ChevronsUpDown, Loader2, Plus, ScanLine } from 'lucide-react'
 import { resolveColorCss } from '@asteby/metacore-ui/lib'
 import { BarcodeScanner } from './barcode-scanner'
 import { DynamicIcon, isLucideIconName } from './dynamic-icon'
+import { useDebouncedValue } from './use-debounced-value'
 import { useOptionsResolver, type ResolvedOption } from './use-options-resolver'
 import { getDependsOn, getFieldRef, resolveOptionsSource } from './dynamic-form-schema'
 import type { ActionFieldDef } from './types'
@@ -140,12 +142,7 @@ export function OptionLead({
 }
 
 function useDebounced<T>(value: T, ms: number): T {
-    const [debounced, setDebounced] = useState(value)
-    useEffect(() => {
-        const t = setTimeout(() => setDebounced(value), ms)
-        return () => clearTimeout(t)
-    }, [value, ms])
-    return debounced
+    return useDebouncedValue(value, ms)
 }
 
 export interface DynamicSelectFieldProps {
@@ -209,6 +206,9 @@ export function DynamicSelectField({
     descriptionAsBadge = false,
     hideCreate = false,
 }: DynamicSelectFieldProps) {
+    const { t } = useTranslation()
+    const ph = (fallback: string) =>
+        field.placeholder ? t(field.placeholder, { defaultValue: field.placeholder }) : fallback
     const [open, setOpen] = useState(false)
     const [search, setSearch] = useState('')
     const [scanOpen, setScanOpen] = useState(false)
@@ -357,7 +357,7 @@ export function DynamicSelectField({
                     <span className={'min-w-0 flex-1 truncate ' + (selectedOption ? '' : 'text-muted-foreground')}>
                         {/* Never flash the raw id: until the eager fetch resolves the
                             option, show a loading hint instead of String(value). */}
-                        {selectedOption?.label ?? (loading ? 'Cargando…' : field.placeholder || '—')}
+                        {selectedOption?.label ?? (loading ? 'Cargando…' : ph('—'))}
                     </span>
                 </span>
             </Button>
@@ -390,7 +390,7 @@ export function DynamicSelectField({
                         <span className={'min-w-0 flex-1 truncate ' + (selectedLabel ? '' : 'text-muted-foreground')}>
                             {blockedByDependency
                                 ? (dependsHint || DEFAULT_DEPENDS_HINT)
-                                : selectedLabel || field.placeholder || 'Buscar…'}
+                                : selectedLabel || ph('Buscar…')}
                         </span>
                         {descriptionAsBadge && selectedOption?.description ? (
                             <Badge variant="secondary" className="shrink-0 font-normal tabular-nums">
@@ -410,7 +410,7 @@ export function DynamicSelectField({
             >
                 <Command shouldFilter={false}>
                     <CommandInput
-                        placeholder={field.placeholder || 'Buscar…'}
+                        placeholder={ph('Buscar…')}
                         value={search}
                         onValueChange={setSearch}
                     />

package/src/dynamic-table.tsx

@@ -72,6 +72,7 @@ import { dedupeById, useInfiniteScrollSentinel } from './use-infinite-scroll'
 import { OptionsContext } from './options-context'
 import type { TableMetadata, ApiResponse } from './types'
 import { getSearchableColumnKeys } from './column-visibility'
+import { useDebouncedValue } from './use-debounced-value'
 import { useCan, usePermissionsActive, gateTableMetadata } from './permissions-context'
 import { useDynamicRowActions } from './dynamic-row-actions'
 import { ExportDialog } from './dialogs/export'
@@ -320,6 +321,8 @@ export function DynamicTable({
         pageSize: storedPageSizeRef.current ?? 10,
     })
     const [globalFilter, setGlobalFilter] = useState('')
+    // Debounce search → URL + fetch so each keystroke does not thrash the server.
+    const debouncedGlobalFilter = useDebouncedValue(globalFilter)
     const [rowCount, setRowCount] = useState(bootData?.rowCount ?? 0)
 
     const [dateRange, setDateRange] = useState<DateRange | undefined>(undefined)
@@ -474,7 +477,7 @@ export function DynamicTable({
             params.set('sortBy', sorting[0].id)
             params.set('order', sorting[0].desc ? 'desc' : 'asc')
         }
-        if (globalFilter) params.set('search', globalFilter)
+        if (debouncedGlobalFilter) params.set('search', debouncedGlobalFilter)
         Object.entries(dynamicFilters).forEach(([key, values]) => {
             if (values.length === 0) return
             if (defaultFilters && key in defaultFilters) return
@@ -495,7 +498,7 @@ export function DynamicTable({
         const newUrl = search ? `${window.location.pathname}?${search}` : window.location.pathname
         lastSelfSearch.current = search ? `?${search}` : ''
         window.history.replaceState(null, '', newUrl)
-    }, [enableUrlSync, urlSynced, pagination, sorting, globalFilter, dynamicFilters, defaultFilters])
+    }, [enableUrlSync, urlSynced, pagination, sorting, debouncedGlobalFilter, dynamicFilters, defaultFilters])
 
     // The host router can rewrite the query string WITHOUT remounting the
     // table — e.g. sidebar sibling entries deep-link different `f_` filters
@@ -670,11 +673,11 @@ export function DynamicTable({
             params.sortBy = sorting[0].id
             params.order = sorting[0].desc ? 'desc' : 'asc'
         }
-        if (globalFilter) {
+        if (debouncedGlobalFilter) {
             if (searchableKeys === null) {
-                params.search = globalFilter
+                params.search = debouncedGlobalFilter
             } else if (searchableKeys.length > 0) {
-                params.search = globalFilter
+                params.search = debouncedGlobalFilter
                 params.search_columns = searchableKeys.join(',')
             }
             // searchableKeys === [] → drop the search request entirely
@@ -700,7 +703,7 @@ export function DynamicTable({
             params['f_created_at'] = `${startDate}_${endDate}`
         }
         return params
-    }, [sorting, globalFilter, columnFilters, defaultFilters, dynamicFilters, dateRange, searchableKeys])
+    }, [sorting, debouncedGlobalFilter, columnFilters, defaultFilters, dynamicFilters, dateRange, searchableKeys])
 
     const hasActiveFilters = useMemo(() => {
         if (globalFilter) return true

package/src/index.ts

@@ -119,6 +119,7 @@ export {
     type UseDynamicFiltersOptions,
     type UseDynamicFiltersResult,
 } from './use-dynamic-filters'
+export { useDebouncedValue, SEARCH_DEBOUNCE_MS } from './use-debounced-value'
 export * from './dynamic-form'
 export {
     FilePickButton,
@@ -265,6 +266,12 @@ export {
     type UrlKind,
     type LinkifyOptions,
 } from './rich-url'
+export {
+    ImageStack,
+    OptionBadge,
+    statusColorFor,
+    useIsDarkTheme,
+} from './display-value'
 export {
     CollectionCell,
     formatScalar,

package/src/metadata-cache.ts

@@ -178,7 +178,14 @@ export const useMetadataCache = create<MetadataCacheState>()(
         }),
         {
             name: 'metacore-metadata-cache',
-            version: 3,
+            // Bump when display hints (e.g. image_stack) must wipe stale cache.
+            version: 4,
+            migrate: () => ({
+                cache: {},
+                modalCache: {},
+                metadataVersion: '',
+                prefetched: false,
+            }),
             partialize: (state) => ({
                 cache: state.cache,
                 modalCache: state.modalCache,

package/src/types.ts

@@ -252,6 +252,8 @@ export interface ColumnDefinition {
         | 'phone'
         | 'media-gallery'
         | 'image'
+        // Landscape stack: wide image on top, label underneath (logos/photos).
+        | 'image_stack'
         // Declarative pro cell renderers (resolved via `cellStyle ?? type`).
         | 'url'
         | 'link'

package/src/use-debounced-value.ts

@@ -0,0 +1,17 @@
+import { useEffect, useState } from 'react'
+
+/** Default delay for free-text search → server/URL (table, kanban, relation). */
+export const SEARCH_DEBOUNCE_MS = 350
+
+/**
+ * Returns `value` delayed by `ms`. The input stays live; only the returned
+ * value lags — use it for fetches and URL sync so typing does not thrash.
+ */
+export function useDebouncedValue<T>(value: T, ms: number = SEARCH_DEBOUNCE_MS): T {
+  const [debounced, setDebounced] = useState(value)
+  useEffect(() => {
+    const t = setTimeout(() => setDebounced(value), ms)
+    return () => clearTimeout(t)
+  }, [value, ms])
+  return debounced
+}

package/src/use-dynamic-filters.ts

@@ -14,6 +14,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { useApi } from './api-context'
 import { DATE_CELL_TYPES } from './dynamic-columns'
 import { getSearchableColumnKeys } from './column-visibility'
+import { useDebouncedValue } from './use-debounced-value'
 import { useFacetLoaders, isLongTextColumn } from './use-facet-loaders'
 import type { ColumnFilterConfig, FilterOption } from './dynamic-columns-shim'
 import type { TableMetadata } from './types'
@@ -82,6 +83,7 @@ export function useDynamicFilters(
 
   const [dynamicFilters, setDynamicFilters] = useState<Record<string, string[]>>({})
   const [globalFilter, setGlobalFilter] = useState('')
+  const debouncedGlobalFilter = useDebouncedValue(globalFilter)
   const [filterOptionsMap, setFilterOptionsMap] = useState<
     Map<string, FilterOption[]>
   >(new Map())
@@ -343,11 +345,11 @@ export function useDynamicFilters(
   // DynamicTable.buildFilterParams (IN:/RANGE:/GTE:/LTE:/ILIKE:/plain).
   const filterParams = useMemo(() => {
     const params: Record<string, any> = {}
-    if (globalFilter) {
+    if (debouncedGlobalFilter) {
       if (searchableKeys === null) {
-        params.search = globalFilter
+        params.search = debouncedGlobalFilter
       } else if (searchableKeys.length > 0) {
-        params.search = globalFilter
+        params.search = debouncedGlobalFilter
         params.search_columns = searchableKeys.join(',')
       }
       // searchableKeys === [] → no searchable column, skip the search param.
@@ -371,7 +373,7 @@ export function useDynamicFilters(
       else params[`f_${key}`] = `IN:${values.join(',')}`
     })
     return params
-  }, [globalFilter, searchableKeys, defaultFilters, dynamicFilters])
+  }, [debouncedGlobalFilter, searchableKeys, defaultFilters, dynamicFilters])
 
   const activeFilterCount = useMemo(() => {
     let n = Object.values(dynamicFilters).filter((v) => v.length > 0).length

package/src/use-print-document.ts

@@ -33,10 +33,36 @@ export interface PrintDocumentArgs {
      * 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"). */
+    /**
+     * Hint filename for download mode. Prefer leaving this unset: the server
+     * expands `{{record.*}}` into Content-Disposition. A raw template string
+     * (e.g. "cfdi-{{record.number}}.pdf") must NOT be used as a.download —
+     * that is how downloads end up literally named with mustache braces.
+     */
     filename?: string
 }
 
+/** Parse filename from Content-Disposition (RFC 5987 / quoted). */
+export function filenameFromContentDisposition(header: string | undefined | null): string | undefined {
+    if (!header) return undefined
+    const star = /filename\*\s*=\s*UTF-8''([^;]+)/i.exec(header)
+    if (star?.[1]) {
+        try {
+            return decodeURIComponent(star[1].trim().replace(/^"|"$/g, ''))
+        } catch {
+            return star[1].trim().replace(/^"|"$/g, '')
+        }
+    }
+    const plain = /filename\s*=\s*"([^"]+)"|filename\s*=\s*([^;]+)/i.exec(header)
+    const raw = (plain?.[1] ?? plain?.[2] ?? '').trim()
+    return raw || undefined
+}
+
+/** True when a caller passed an unexpanded mustache template as filename. */
+export function looksLikeFilenameTemplate(name: string | undefined): boolean {
+    return !!name && /\{\{/.test(name)
+}
+
 /**
  * Returns a `printDocument(args)` callback. Resolves once the PDF has been
  * fetched and the browser action (print/download/open) has been kicked off;
@@ -65,9 +91,19 @@ export function usePrintDocument() {
             const cleanup = () => setTimeout(() => URL.revokeObjectURL(blobUrl), 60_000)
 
             if (mode === 'download') {
+                const headers = (res as { headers?: Record<string, string> }).headers || {}
+                const fromHeader =
+                    filenameFromContentDisposition(
+                        headers['content-disposition'] || headers['Content-Disposition'],
+                    ) || undefined
+                // Prefer server-expanded name; never use a raw {{record.*}} template.
+                const downloadName =
+                    fromHeader ||
+                    (!looksLikeFilenameTemplate(filename) ? filename : undefined) ||
+                    `${key}.pdf`
                 const a = document.createElement('a')
                 a.href = blobUrl
-                a.download = filename || `${key}.pdf`
+                a.download = downloadName
                 document.body.appendChild(a)
                 a.click()
                 a.remove()