@asteby/metacore-runtime-react 28.0.3 → 28.2.0

package/src/__tests__/dynamic-table-pages.test.tsx

@@ -0,0 +1,160 @@
+// @vitest-environment happy-dom
+//
+// DynamicTable classic pagination ('pages', the default mode):
+//   1. The pager footer renders; clicking page 2 issues a NEW query with
+//      page=2 and REPLACES the visible rows (no accumulation).
+//   2. Changing the filters resets back to page 1.
+//   3. The chosen page size persists per table in localStorage and is adopted
+//      on the next mount (over the model's server default).
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+
+vi.mock('@tanstack/react-router', () => ({
+    useNavigate: () => () => {},
+}))
+const I18N = {
+    t: (_k: string, o?: { defaultValue?: string; count?: number; total?: number }) => {
+        if (o?.defaultValue && o.count != null && o.total != null) {
+            return o.defaultValue.replace('{{count}}', String(o.count)).replace('{{total}}', String(o.total))
+        }
+        return o?.defaultValue ?? _k
+    },
+    i18n: { language: 'es' },
+}
+vi.mock('react-i18next', () => ({ useTranslation: () => I18N }))
+
+import { DynamicTable } from '../dynamic-table'
+import { ApiProvider, type ApiClient } from '../api-context'
+import { useMetadataCache } from '../metadata-cache'
+import type { TableMetadata } from '../types'
+
+afterEach(cleanup)
+
+function meta(): TableMetadata {
+    return {
+        title: 'Issues',
+        endpoint: '/data/issue',
+        group_by: 'stage',
+        columns: [
+            { key: 'title', label: 'Title', type: 'text', sortable: true, filterable: false, searchable: true },
+        ],
+        actions: [],
+        perPageOptions: [10, 20, 50],
+        defaultPerPage: 10,
+        searchPlaceholder: 'Buscar...',
+        enableCRUDActions: false,
+        hasActions: false,
+    }
+}
+
+function fakeApi(total: number): ApiClient {
+    const ok = (data: unknown) => ({ data: { success: true, data, meta: { total } } })
+    const page = (n: number, size: number) => {
+        const start = (n - 1) * size
+        const rows: Array<{ id: number; title: string }> = []
+        for (let i = start; i < Math.min(start + size, total); i++) {
+            rows.push({ id: i + 1, title: `Issue ${i + 1}` })
+        }
+        return rows
+    }
+    return {
+        get: vi.fn(async (url: string, cfg?: any) => {
+            if (url.startsWith('/metadata/table/')) return ok(meta())
+            if (url.endsWith('/facets')) return ok([])
+            const p = cfg?.params?.page ?? 1
+            const size = cfg?.params?.per_page ?? 10
+            return ok(page(p, size))
+        }),
+        post: vi.fn(async () => ok(null)),
+        put: vi.fn(async () => ok(null)),
+        delete: vi.fn(async () => ok(null)),
+    }
+}
+
+function dataCalls(api: ApiClient) {
+    return (api.get as any).mock.calls.filter((c: any[]) => c[0] === '/data/issue')
+}
+
+describe('DynamicTable classic pages mode (default)', () => {
+    beforeEach(() => {
+        localStorage.clear()
+        sessionStorage.clear()
+        useMetadataCache.getState().setMetadata('issue', meta())
+    })
+
+    it('changes page: new query with page=2 and REPLACES the rows', async () => {
+        const api = fakeApi(45)
+        render(
+            <ApiProvider client={api}>
+                <DynamicTable model="issue" pagination="pages" enableUrlSync={false} />
+            </ApiProvider>,
+        )
+
+        // Page 1 loads with the model's default size.
+        await waitFor(() => {
+            const first = dataCalls(api)[0]
+            expect(first?.[1]?.params).toMatchObject({ page: 1, per_page: 10 })
+        })
+        await waitFor(() => expect(screen.getAllByText('Issue 1').length).toBeGreaterThan(0))
+
+        // Click the pager's page "2" button.
+        const btn2 = screen.getAllByRole('button').find((b) => b.textContent?.trim().endsWith('2'))
+        expect(btn2).toBeTruthy()
+        fireEvent.click(btn2!)
+
+        await waitFor(() => {
+            const pages = dataCalls(api).map((c: any[]) => c[1]?.params?.page)
+            expect(pages).toContain(2)
+        })
+        // Rows were REPLACED, not accumulated: page-2 rows in, page-1 rows out.
+        await waitFor(() => expect(screen.getAllByText('Issue 11').length).toBeGreaterThan(0))
+        expect(screen.queryByText('Issue 1')).toBeNull()
+    })
+
+    it('resets to page 1 when the filters change', async () => {
+        const api = fakeApi(45)
+        const { rerender } = render(
+            <ApiProvider client={api}>
+                <DynamicTable model="issue" pagination="pages" enableUrlSync={false} />
+            </ApiProvider>,
+        )
+        await waitFor(() => expect(screen.getAllByText('Issue 1').length).toBeGreaterThan(0))
+        const btn2 = screen.getAllByRole('button').find((b) => b.textContent?.trim().endsWith('2'))
+        fireEvent.click(btn2!)
+        await waitFor(() => expect(screen.getAllByText('Issue 11').length).toBeGreaterThan(0))
+
+        // Change the active filters via defaultFilters (part of buildFilterParams).
+        rerender(
+            <ApiProvider client={api}>
+                <DynamicTable
+                    model="issue"
+                    pagination="pages"
+                    enableUrlSync={false}
+                    defaultFilters={{ stage: 'done' }}
+                />
+            </ApiProvider>,
+        )
+
+        // The filtered request goes back to page 1.
+        await waitFor(() => {
+            const withFilter = dataCalls(api).filter((c: any[]) => c[1]?.params?.f_stage === 'done')
+            expect(withFilter.length).toBeGreaterThan(0)
+            expect(withFilter.every((c: any[]) => c[1]?.params?.page === 1)).toBe(true)
+        })
+        await waitFor(() => expect(screen.getAllByText('Issue 1').length).toBeGreaterThan(0))
+    })
+
+    it('adopts the per-table page size persisted in localStorage', async () => {
+        localStorage.setItem('mc:tbl:pageSize:v1|issue', '20')
+        const api = fakeApi(45)
+        render(
+            <ApiProvider client={api}>
+                <DynamicTable model="issue" enableUrlSync={false} />
+            </ApiProvider>,
+        )
+        await waitFor(() => {
+            const first = dataCalls(api)[0]
+            expect(first?.[1]?.params).toMatchObject({ page: 1, per_page: 20 })
+        })
+    })
+})

package/src/__tests__/icon-picker-field.test.tsx

@@ -0,0 +1,67 @@
+// @vitest-environment happy-dom
+//
+// IconPickerField — the `icon` form widget: lucide search grid (icon mode) and
+// delegation to UploadField (image mode). UploadField is stubbed so the image
+// mode asserts delegation without needing an ApiProvider.
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen, fireEvent } from '@testing-library/react'
+
+vi.mock('../upload-field', () => ({
+    UploadField: ({ field, value }: any) => (
+        <div data-testid="upload-field" data-field-key={field.key} data-value={String(value ?? '')} />
+    ),
+}))
+
+import { IconPickerField, looksLikeImageValue } from '../icon-picker-field'
+import type { ActionFieldDef } from '../types'
+
+afterEach(cleanup)
+
+const field: ActionFieldDef = { key: 'icon', label: 'Ícono', type: 'text', widget: 'icon' }
+
+describe('IconPickerField', () => {
+    it('busca "credit", muestra CreditCard y al click emite onChange con el nombre', () => {
+        const onChange = vi.fn()
+        render(<IconPickerField field={field} value="" onChange={onChange} />)
+        fireEvent.change(screen.getByLabelText('Buscar ícono'), { target: { value: 'credit' } })
+        const option = screen.getByRole('option', { name: 'CreditCard' })
+        fireEvent.click(option)
+        expect(onChange).toHaveBeenCalledWith('CreditCard')
+    })
+
+    it('resalta el seleccionado y muestra el preview grande', () => {
+        render(<IconPickerField field={field} value="CreditCard" onChange={() => {}} />)
+        expect(screen.getByTestId('icon-picker-preview')).toBeTruthy()
+        expect(
+            screen.getByRole('option', { name: 'CreditCard' }).getAttribute('aria-selected'),
+        ).toBe('true')
+    })
+
+    it('limita el grid a 48 resultados', () => {
+        render(<IconPickerField field={field} value="" onChange={() => {}} />)
+        expect(screen.getAllByRole('option').length).toBeLessThanOrEqual(48)
+    })
+
+    it('modo imagen delega a UploadField con los mismos props', () => {
+        render(<IconPickerField field={field} value="" onChange={() => {}} />)
+        fireEvent.click(screen.getByRole('tab', { name: 'Imagen' }))
+        const stub = screen.getByTestId('upload-field')
+        expect(stub.getAttribute('data-field-key')).toBe('icon')
+    })
+
+    it('arranca en modo Imagen cuando el valor parece path/URL', () => {
+        render(<IconPickerField field={field} value="/uploads/logo.png" onChange={() => {}} />)
+        expect(screen.getByTestId('upload-field').getAttribute('data-value')).toBe('/uploads/logo.png')
+    })
+})
+
+describe('looksLikeImageValue', () => {
+    it('distingue paths/URLs de nombres lucide', () => {
+        expect(looksLikeImageValue('/uploads/a.png')).toBe(true)
+        expect(looksLikeImageValue('logo.png')).toBe(true)
+        expect(looksLikeImageValue('https://x/y')).toBe(true)
+        expect(looksLikeImageValue('CreditCard')).toBe(false)
+        expect(looksLikeImageValue('credit-card')).toBe(false)
+        expect(looksLikeImageValue('')).toBe(false)
+    })
+})

package/src/__tests__/image-cell-lucide.test.tsx

@@ -0,0 +1,52 @@
+// @vitest-environment happy-dom
+//
+// ImageCell — an `image` cell whose value is a lucide icon name (PascalCase or
+// kebab, as stored by the `icon` form widget) renders the glyph instead of a
+// broken <img>; real paths/urls keep rendering an <img>.
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, render } from '@testing-library/react'
+import { ImageCell } from '../dynamic-columns'
+import { isLucideIconName, resolveLucideIconName } from '../dynamic-icon'
+
+afterEach(cleanup)
+
+const getImageUrl = (p: string) => `/img${p}`
+
+describe('ImageCell con nombre lucide', () => {
+    it('renderiza el ícono (svg) para un nombre PascalCase, sin <img>', () => {
+        const { container } = render(<ImageCell value="CreditCard" getImageUrl={getImageUrl} />)
+        expect(container.querySelector('svg')).toBeTruthy()
+        expect(container.querySelector('img')).toBeNull()
+    })
+
+    it('renderiza el ícono también para el slug kebab "credit-card"', () => {
+        const { container } = render(<ImageCell value="credit-card" getImageUrl={getImageUrl} />)
+        expect(container.querySelector('svg')).toBeTruthy()
+        expect(container.querySelector('img')).toBeNull()
+    })
+
+    it('un path real sigue renderizando <img> con getImageUrl aplicado', () => {
+        const { container } = render(<ImageCell value="/uploads/x.png" getImageUrl={getImageUrl} />)
+        const img = container.querySelector('img')
+        expect(img?.getAttribute('src')).toBe('/img/uploads/x.png')
+    })
+
+    it('valor vacío cae al guion', () => {
+        const { container } = render(<ImageCell value="" getImageUrl={getImageUrl} />)
+        expect(container.textContent).toBe('-')
+    })
+})
+
+describe('resolveLucideIconName / isLucideIconName', () => {
+    it('normaliza kebab a PascalCase', () => {
+        expect(resolveLucideIconName('credit-card')).toBe('CreditCard')
+        expect(resolveLucideIconName('CreditCard')).toBe('CreditCard')
+    })
+    it('rechaza paths, vacíos y el base "Icon"', () => {
+        expect(resolveLucideIconName('/a/b.png')).toBeNull()
+        expect(resolveLucideIconName('logo.png')).toBeNull()
+        expect(resolveLucideIconName('')).toBeNull()
+        expect(resolveLucideIconName('Icon')).toBeNull()
+        expect(isLucideIconName('no-such-icon-xyz')).toBe(false)
+    })
+})

package/src/dynamic-columns.tsx

@@ -664,6 +664,38 @@ const AvatarCell: React.FC<{
  * does not supply its own. Pass `{ getImageUrl, apiBaseUrl }` to wire avatar
  * URL resolution.
  */
+/**
+ * `image`-type cell body. A value that is a lucide icon name (PascalCase or
+ * kebab slug, e.g. "Banknote" / "credit-card") — the convention the `icon`
+ * form widget stores — renders the glyph instead of an <img> that would 404
+ * into an empty grey box. Exported for tests.
+ */
+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)) {
+        return (
+            <div className="h-10 w-10 flex items-center justify-center rounded bg-muted">
+                <DynamicIcon name={value} className="h-5 w-5" />
+            </div>
+        )
+    }
+    return (
+        <div className="h-10 w-10 relative rounded overflow-hidden bg-muted flex items-center justify-center">
+            <img
+                src={getImageUrl(String(value))}
+                alt="Thumbnail"
+                className="h-full w-full object-contain"
+                onError={(e) => {
+                    ;(e.currentTarget as HTMLImageElement).style.display = 'none'
+                }}
+            />
+        </div>
+    )
+}
+
 export function makeDefaultGetDynamicColumns(
     helpers: DynamicColumnsHelpers = {},
 ): GetDynamicColumns {
@@ -1155,29 +1187,7 @@ export function makeDefaultGetDynamicColumns(
                                 (Array.isArray(row.original.media)
                                     ? row.original.media.find((m: any) => m.type === 'image')?.url
                                     : null)
-                            if (!imageValue) return <span className="text-muted-foreground">-</span>
-                            // Lucide icon name, not an image path (e.g. an addon's
-                            // `icon` column seeded as "Banknote") — render the glyph;
-                            // an <img> here would 404 into an empty grey box.
-                            if (isLucideIconName(imageValue)) {
-                                return (
-                                    <div className="h-10 w-10 flex items-center justify-center rounded bg-muted">
-                                        <DynamicIcon name={imageValue} className="h-5 w-5" />
-                                    </div>
-                                )
-                            }
-                            return (
-                                <div className="h-10 w-10 relative rounded overflow-hidden bg-muted flex items-center justify-center">
-                                    <img
-                                        src={getImageUrl(String(imageValue))}
-                                        alt="Thumbnail"
-                                        className="h-full w-full object-contain"
-                                        onError={(e) => {
-                                            ;(e.currentTarget as HTMLImageElement).style.display = 'none'
-                                        }}
-                                    />
-                                </div>
-                            )
+                            return <ImageCell value={imageValue} getImageUrl={getImageUrl} />
                         }
 
                         default: {

package/src/dynamic-form.tsx

@@ -28,12 +28,14 @@ import { DynamicLineItems } from './dynamic-line-items'
 import { DynamicSelectField } from './dynamic-select-field'
 import { DynamicDateField } from './dynamic-date-field'
 import { UploadField } from './upload-field'
+import { IconPickerField } from './icon-picker-field'
 
 export { buildZodSchema, resolveWidget }
 export { DynamicLineItems } from './dynamic-line-items'
 export { DynamicSelectField } from './dynamic-select-field'
 export { DynamicDateField } from './dynamic-date-field'
 export { UploadField } from './upload-field'
+export { IconPickerField } from './icon-picker-field'
 
 export interface DynamicFormProps {
     fields: ActionFieldDef[]
@@ -264,6 +266,12 @@ function FieldRenderer({
     if (widget === 'upload') {
         return <UploadField field={field} value={value} onChange={onChange} />
     }
+    // Icon picker → lucide glyph search grid, with an "Imagen" mode that
+    // delegates to the same UploadField as `upload`. Stores a plain string:
+    // lucide name or uploaded url/path.
+    if (widget === 'icon') {
+        return <IconPickerField field={field} value={value} onChange={onChange} />
+    }
     // Ref-driven select: hook into useOptionsResolver so the canonical
     // /api/options/<ref>?field=id endpoint feeds the dropdown. This is
     // the path the kernel auto-derives for FK columns; legacy callers

package/src/dynamic-icon.tsx

@@ -9,19 +9,37 @@ export interface DynamicIconProps {
 }
 
 export function DynamicIcon({ name, className }: DynamicIconProps) {
-    const Icon = (icons as unknown as Record<string, React.ComponentType<{ className?: string }>>)[name]
+    const resolved = resolveLucideIconName(name) ?? name
+    const Icon = (icons as unknown as Record<string, React.ComponentType<{ className?: string }>>)[resolved]
     if (!Icon) return null
     return <Icon className={className} />
 }
 
+// resolveLucideIconName — canonical PascalCase lucide name for a value that is
+// either already PascalCase ("CreditCard") or the kebab slug lucide documents
+// ("credit-card"). Returns null for anything that is not a real glyph: empty,
+// path-like strings (slash, dot, scheme), or the generic "Icon" base export.
+export function resolveLucideIconName(value: unknown): string | null {
+    if (typeof value !== 'string' || value === '' || value === 'Icon') return null
+    if (/[/\\.:\s]/.test(value)) return null
+    let name = value
+    if (/^[a-z0-9]+(-[a-z0-9]+)*$/.test(value)) {
+        name = value
+            .split('-')
+            .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+            .join('')
+    }
+    if (!/^[A-Z][A-Za-z0-9]*$/.test(name)) return null
+    return (icons as unknown as Record<string, unknown>)[name] ? name : null
+}
+
 // isLucideIconName — true when a string is a lucide-react icon name
-// ("Banknote", "CreditCard"). Lets image-ish renderers tell an icon name apart
-// from an image path/URL: addons declare icons by lucide slug (same convention
-// as OptionDef.icon), so a column inferred as `image` may carry one. Path-like
-// strings (slash, dot, scheme) are rejected before the registry lookup; "Icon"
-// itself is the generic base component, not a real glyph.
+// ("Banknote", "CreditCard", or the kebab slug "credit-card"). Lets image-ish
+// renderers tell an icon name apart from an image path/URL: addons declare
+// icons by lucide slug (same convention as OptionDef.icon), so a column
+// inferred as `image` may carry one. Path-like strings (slash, dot, scheme)
+// are rejected before the registry lookup; "Icon" itself is the generic base
+// component, not a real glyph.
 export function isLucideIconName(value: unknown): value is string {
-    if (typeof value !== 'string' || value === '' || value === 'Icon') return false
-    if (!/^[A-Z][A-Za-z0-9]*$/.test(value)) return false
-    return Boolean((icons as unknown as Record<string, unknown>)[value])
+    return resolveLucideIconName(value) !== null
 }

package/src/dynamic-select-field.tsx

@@ -37,7 +37,7 @@ import {
 } from '@asteby/metacore-ui/primitives'
 import { Check, ChevronsUpDown, Loader2, Plus } from 'lucide-react'
 import { resolveColorCss } from '@asteby/metacore-ui/lib'
-import { DynamicIcon } from './dynamic-icon'
+import { DynamicIcon, isLucideIconName } from './dynamic-icon'
 import { useOptionsResolver, type ResolvedOption } from './use-options-resolver'
 import { getDependsOn, getFieldRef, resolveOptionsSource } from './dynamic-form-schema'
 import type { ActionFieldDef } from './types'
@@ -71,6 +71,15 @@ export function OptionThumb({
     if (!image) {
         return <InitialsAvatar name={name} size={size} rounded="sm" tone="neutral" />
     }
+    // A lucide icon name stored where an image url/path is expected (the `icon`
+    // form widget's icon mode) → render the glyph instead of a broken <img>.
+    if (isLucideIconName(image)) {
+        return (
+            <span className="flex shrink-0 items-center justify-center rounded-sm bg-muted" style={box} aria-hidden>
+                <DynamicIcon name={image} className="size-4" />
+            </span>
+        )
+    }
     return (
         <img
             src={image}

package/src/dynamic-table.tsx

@@ -129,6 +129,32 @@ function writeTableDataCache(key: string, rows: any[], rowCount: number): void {
     }
 }
 
+// Chosen page size, persisted per table so a user's preferred density survives
+// reloads. localStorage ON PURPOSE (unlike the row-data cache above): a page
+// size is a UI preference, not org/user-scoped data, so outliving the tab is
+// desired. Keyed by model.
+const TBL_PAGE_SIZE_PREFIX = 'mc:tbl:pageSize:v1'
+
+function readStoredPageSize(model: string): number | null {
+    try {
+        const raw = localStorage.getItem(`${TBL_PAGE_SIZE_PREFIX}|${model}`)
+        if (!raw) return null
+        const n = parseInt(raw, 10)
+        return Number.isFinite(n) && n > 0 ? n : null
+    } catch {
+        return null
+    }
+}
+
+function writeStoredPageSize(model: string, size: number | null): void {
+    try {
+        if (size === null) localStorage.removeItem(`${TBL_PAGE_SIZE_PREFIX}|${model}`)
+        else localStorage.setItem(`${TBL_PAGE_SIZE_PREFIX}|${model}`, String(size))
+    } catch {
+        // quota / private mode — persistence is a nicety, never fatal
+    }
+}
+
 export interface DynamicTableProps {
     model: string
     endpoint?: string
@@ -166,11 +192,24 @@ export interface DynamicTableProps {
      */
     currency?: string
     /**
-     * Opt into infinite scroll: instead of the classic pager, rows accumulate as
-     * the user scrolls (a sentinel at the bottom fetches + appends the next
-     * page, deduped by id, respecting the active filters/search). Changing any
-     * filter/sort/search resets to page 1. Default false — existing hosts keep
-     * the classic pagination untouched.
+     * Pagination mode.
+     *   - 'pages' (default): classic pager footer (DataTablePagination — rows
+     *     per page selector, "página X de Y", first/prev/next/last). Each page
+     *     change fetches and REPLACES the visible rows (page/per_page against
+     *     the same server params the infinite mode uses; pageCount derives
+     *     from meta.total). The chosen page size persists per table in
+     *     localStorage (keyed by model). Changing any filter/sort/search
+     *     resets to page 1.
+     *   - 'infinite': rows accumulate as the user scrolls (a sentinel at the
+     *     bottom fetches + appends the next page, deduped by id, respecting
+     *     the active filters/search). Changing any filter/sort/search resets
+     *     to page 1.
+     */
+    pagination?: 'pages' | 'infinite'
+    /**
+     * @deprecated Use `pagination="infinite"`. Kept for back-compat: when the
+     * new `pagination` prop is not provided, `infiniteScroll` still selects the
+     * mode exactly as before.
      */
     infiniteScroll?: boolean
 }
@@ -188,8 +227,12 @@ export function DynamicTable({
     getDynamicColumns = defaultGetDynamicColumns,
     timeZone,
     currency,
-    infiniteScroll = false,
+    pagination: paginationMode,
+    infiniteScroll: infiniteScrollProp = false,
 }: DynamicTableProps) {
+    // The explicit `pagination` prop wins; the legacy `infiniteScroll` boolean
+    // still selects the mode when `pagination` is absent (back-compat).
+    const infiniteScroll = paginationMode ? paginationMode === 'infinite' : infiniteScrollProp
     const { t, i18n } = useTranslation()
     const api = useApi()
     const currentBranch = useCurrentBranch()
@@ -247,7 +290,17 @@ export function DynamicTable({
         return initial
     })
     const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])
-    const [pagination, setPagination] = useState<PaginationState>({ pageIndex: 0, pageSize: 10 })
+    // The user's persisted page-size preference for this table (pages mode).
+    // Read once at mount; a URL `per_page` still wins over it (deep-links stay
+    // exact), and it wins over the model's server default.
+    const storedPageSizeRef = useRef<number | null | undefined>(undefined)
+    if (storedPageSizeRef.current === undefined) {
+        storedPageSizeRef.current = readStoredPageSize(model)
+    }
+    const [pagination, setPagination] = useState<PaginationState>({
+        pageIndex: 0,
+        pageSize: storedPageSizeRef.current ?? 10,
+    })
     const [globalFilter, setGlobalFilter] = useState('')
     const [rowCount, setRowCount] = useState(bootData?.rowCount ?? 0)
 
@@ -507,7 +560,7 @@ export function DynamicTable({
             if (cached) {
                 setMetadata(cached)
                 defaultPerPage.current = cached.defaultPerPage || 10
-                if (!urlHadPerPage.current) setPagination((prev: PaginationState) => ({ ...prev, pageSize: cached.defaultPerPage || 10 }))
+                if (!urlHadPerPage.current && storedPageSizeRef.current == null) setPagination((prev: PaginationState) => ({ ...prev, pageSize: cached.defaultPerPage || 10 }))
                 setLoading(false)
             } else {
                 setLoading(true)
@@ -521,7 +574,7 @@ export function DynamicTable({
                     setMetadata(fresh)
                     cacheMetadata(model, fresh)
                     defaultPerPage.current = fresh.defaultPerPage || 10
-                    if (!urlHadPerPage.current) setPagination((prev: PaginationState) => ({ ...prev, pageSize: fresh.defaultPerPage || 10 }))
+                    if (!urlHadPerPage.current && storedPageSizeRef.current == null) setPagination((prev: PaginationState) => ({ ...prev, pageSize: fresh.defaultPerPage || 10 }))
                 }
             } catch (error) {
                 if (!cached) console.error('Error al cargar la configuración de la tabla', error)
@@ -738,6 +791,35 @@ export function DynamicTable({
         [buildFilterParams],
     )
 
+    // Pages mode: any filter/search/sort change snaps back to page 1 (same
+    // contract as the infinite reset above — a filtered set has its own page
+    // space). Ref-compared so paging itself never triggers it, and armed only
+    // AFTER the URL adoption has settled so a deep-linked `?page=3&sortBy=...`
+    // is not immediately reset by its own sort arriving.
+    const pagesSigArmed = useRef(false)
+    const pagesPrevSig = useRef<string | null>(null)
+    useEffect(() => {
+        if (infiniteScroll) return
+        if (enableUrlSync && !urlSynced) return
+        if (!pagesSigArmed.current) {
+            pagesSigArmed.current = true
+            pagesPrevSig.current = filterSignature
+            return
+        }
+        if (pagesPrevSig.current === filterSignature) return
+        pagesPrevSig.current = filterSignature
+        setPagination((p: PaginationState) => (p.pageIndex === 0 ? p : { ...p, pageIndex: 0 }))
+    }, [infiniteScroll, enableUrlSync, urlSynced, filterSignature])
+
+    // Persist the chosen page size per table (localStorage, keyed by model).
+    // The server default is stored as an explicit removal so a later backend
+    // change of `defaultPerPage` still propagates to users who never deviated.
+    useEffect(() => {
+        if (!metadata) return
+        const chosen = pagination.pageSize
+        writeStoredPageSize(model, chosen === defaultPerPage.current ? null : chosen)
+    }, [metadata, model, pagination.pageSize])
+
     const loadNextPage = useCallback(() => {
         if (loadingMore || loadingData || infExhausted) return
         if (data.length >= rowCount) return