@asteby/metacore-runtime-react 49.9.1 → 49.10.0

package/src/__tests__/permissions-allowed-roles.test.tsx

@@ -0,0 +1,104 @@
+// @vitest-environment happy-dom
+//
+// `allowedRoles` por acción: oculta según los roles que provee el host vía
+// <PermissionsProvider roles superRoles>. Solo UX; el backend es la autoridad.
+import { describe, expect, it } from 'vitest'
+import { renderHook } from '@testing-library/react'
+import React from 'react'
+
+import {
+    gateTableMetadata,
+    isActionAllowedForRoles,
+    makeCan,
+    PermissionsProvider,
+    resolveRowActions,
+    useRoleGate,
+    type RoleGate,
+} from '../permissions-context'
+import type { TableMetadata, ActionDefinition } from '../types'
+
+function meta(actions: ActionDefinition[]): TableMetadata {
+    return {
+        title: 'Doctores',
+        endpoint: '/dynamic/doctors',
+        columns: [],
+        actions,
+        perPageOptions: [10],
+        defaultPerPage: 10,
+        searchPlaceholder: 'Buscar...',
+        enableCRUDActions: false,
+        hasActions: actions.length > 0,
+    } as TableMetadata
+}
+
+const act = (key: string, extra: Record<string, unknown> = {}): ActionDefinition =>
+    ({ key, name: key, label: key, icon: 'Zap', ...extra }) as ActionDefinition
+
+const can = makeCan(['*'], false)
+const gate = (over: Partial<RoleGate> = {}): RoleGate => ({
+    roles: ['doctor'],
+    superRoles: [],
+    loading: false,
+    isAdmin: false,
+    ...over,
+})
+const keys = (m: TableMetadata) => m.actions.map((a) => a.key)
+
+describe('allowedRoles por acción', () => {
+    const m = meta([act('free'), act('onlyAdmin', { allowedRoles: ['admin'] }), act('docs', { allowedRoles: ['doctor', 'nurse'] })])
+
+    it('oculta/muestra según el rol del usuario', () => {
+        expect(keys(gateTableMetadata(m, 'doctors', can, undefined, gate()))).toEqual(['free', 'docs'])
+        expect(keys(gateTableMetadata(m, 'doctors', can, undefined, gate({ roles: ['admin'] })))).toEqual(['free', 'onlyAdmin'])
+    })
+
+    it('superRoles hace bypass; sin superRoles no hay bypass', () => {
+        const g = gate({ roles: ['super_admin'], superRoles: ['admin', 'super_admin'] })
+        expect(keys(gateTableMetadata(m, 'doctors', can, undefined, g))).toEqual(['free', 'onlyAdmin', 'docs'])
+        expect(keys(gateTableMetadata(m, 'doctors', can, undefined, gate({ roles: ['super_admin'] })))).toEqual(['free'])
+    })
+
+    it('isAdmin hace bypass', () => {
+        expect(keys(gateTableMetadata(m, 'doctors', can, undefined, gate({ isAdmin: true })))).toHaveLength(3)
+    })
+
+    it('sin allowedRoles (o vacío) todo igual', () => {
+        const plain = meta([act('a'), act('b', { allowedRoles: [] })])
+        expect(keys(gateTableMetadata(plain, 'doctors', can, undefined, gate({ roles: [] })))).toEqual(['a', 'b'])
+    })
+
+    it('sin provider (gate null) todo igual', () => {
+        expect(keys(gateTableMetadata(m, 'doctors', can))).toEqual(['free', 'onlyAdmin', 'docs'])
+        expect(isActionAllowedForRoles(act('x', { allowedRoles: ['admin'] }), null)).toBe(true)
+    })
+
+    it('acepta snake_case allowed_roles', () => {
+        const s = meta([act('x', { allowed_roles: ['admin'] })])
+        expect(keys(gateTableMetadata(s, 'doctors', can, undefined, gate()))).toEqual([])
+        expect(keys(gateTableMetadata(s, 'doctors', can, undefined, gate({ roles: ['admin'] })))).toEqual(['x'])
+    })
+
+    it('loading y roles sin resolver no filtran; roles [] es fail-closed', () => {
+        const a = act('x', { allowedRoles: ['admin'] })
+        expect(isActionAllowedForRoles(a, gate({ roles: undefined, loading: true }))).toBe(true)
+        expect(isActionAllowedForRoles(a, gate({ roles: ['patient'], loading: true }))).toBe(true)
+        expect(isActionAllowedForRoles(a, gate({ roles: undefined }))).toBe(true)
+        expect(isActionAllowedForRoles(a, gate({ roles: [] }))).toBe(false)
+    })
+
+    it('resolveRowActions (kanban) aplica el mismo filtro', () => {
+        const rows = resolveRowActions(m, 'doctors', can, true, undefined, gate())
+        expect(rows.map((a) => a.key)).toEqual(['free', 'docs'])
+    })
+
+    it('PermissionsProvider expone el gate y sin provider es null', () => {
+        expect(renderHook(() => useRoleGate()).result.current).toBeNull()
+        const wrapper = ({ children }: { children: React.ReactNode }) => (
+            <PermissionsProvider permissions={['*']} isAdmin={false} roles={['doctor']} superRoles={['admin']}>
+                {children}
+            </PermissionsProvider>
+        )
+        const { result } = renderHook(() => useRoleGate(), { wrapper })
+        expect(result.current).toMatchObject({ roles: ['doctor'], superRoles: ['admin'], loading: false })
+    })
+})

package/src/__tests__/row-action-predicate.test.tsx

@@ -0,0 +1,172 @@
+// @vitest-environment happy-dom
+//
+// `isRowActionVisible` (consumer predicate) en DynamicTable y DynamicKanban:
+//   1. Función pura: AND con requiresState/condition, fail-closed si lanza,
+//      sin predicado = comportamiento previo.
+//   2. DynamicTable: el menú «…» de una fila desaparece cuando el predicado
+//      oculta todas sus acciones; sin predicado aparece en todas.
+//   3. DynamicKanban: igual para el menú de la tarjeta.
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen, waitFor } from '@testing-library/react'
+
+vi.mock('@tanstack/react-router', () => ({
+    useNavigate: () => () => {},
+}))
+const I18N_T = (_k: string, o?: { defaultValue?: string }) => o?.defaultValue ?? _k
+const USE_TRANSLATION = { t: I18N_T, i18n: { language: 'es' } }
+vi.mock('react-i18next', () => ({ useTranslation: () => USE_TRANSLATION }))
+
+import { isRowActionVisible } from '../dynamic-columns'
+import { DynamicTable } from '../dynamic-table'
+import { DynamicKanban } from '../dynamic-kanban'
+import { ApiProvider, type ApiClient } from '../api-context'
+import { useMetadataCache } from '../metadata-cache'
+import type { ActionDefinition, TableMetadata } from '../types'
+import type { RowActionPredicate } from '../dynamic-columns-shim'
+
+afterEach(() => {
+    cleanup()
+    vi.restoreAllMocks()
+})
+
+const act = (over: Record<string, unknown> = {}): ActionDefinition =>
+    ({ key: 'pagar', name: 'pagar', label: 'Pagar', icon: 'Zap', ...over }) as ActionDefinition
+
+describe('isRowActionVisible (puro)', () => {
+    it('sin predicado = comportamiento previo (requiresState + condition)', () => {
+        const a = act({ requiresState: ['open'] })
+        expect(isRowActionVisible(a, { status: 'open' })).toBe(true)
+        expect(isRowActionVisible(a, { status: 'closed' })).toBe(false)
+    })
+
+    it('muestra u oculta por fila según el predicado y recibe (action, row)', () => {
+        const spy = vi.fn<RowActionPredicate>((_a, row) => row.id !== 2)
+        const a = act()
+        expect(isRowActionVisible(a, { id: 1 }, undefined, spy)).toBe(true)
+        expect(isRowActionVisible(a, { id: 2 }, undefined, spy)).toBe(false)
+        expect(spy).toHaveBeenCalledWith(a, { id: 2 })
+    })
+
+    it('es AND: un predicado true no revela lo que la metadata oculta', () => {
+        const a = act({ requiresState: ['open'] })
+        expect(isRowActionVisible(a, { status: 'closed' }, undefined, () => true)).toBe(false)
+        expect(isRowActionVisible(a, { status: 'open' }, undefined, () => false)).toBe(false)
+        expect(isRowActionVisible(a, { status: 'open' }, undefined, () => true)).toBe(true)
+    })
+
+    it('si el predicado lanza, oculta la acción y registra el error', () => {
+        const err = vi.spyOn(console, 'error').mockImplementation(() => {})
+        const boom: RowActionPredicate = () => {
+            throw new Error('boom')
+        }
+        expect(isRowActionVisible(act(), { id: 1 }, undefined, boom)).toBe(false)
+        expect(err).toHaveBeenCalled()
+    })
+})
+
+function meta(over: Partial<TableMetadata> = {}): TableMetadata {
+    return {
+        title: 'Issues',
+        endpoint: '/data/issue',
+        columns: [{ key: 'title', label: 'Title', type: 'text', sortable: false, filterable: false, searchable: true }],
+        actions: [act()],
+        perPageOptions: [10],
+        defaultPerPage: 10,
+        searchPlaceholder: 'Buscar...',
+        enableCRUDActions: false,
+        hasActions: true,
+        ...over,
+    }
+}
+
+const ROWS = [
+    { id: 1, title: 'Uno', stage: 'a' },
+    { id: 2, title: 'Dos', stage: 'a' },
+    { id: 3, title: 'Tres', stage: 'a' },
+]
+
+function fakeApi(m: TableMetadata): ApiClient {
+    const ok = (data: unknown) => ({ data: { success: true, data, meta: { total: ROWS.length } } })
+    return {
+        get: vi.fn(async (url: string) => {
+            if (url.startsWith('/metadata/table/')) return ok(m)
+            if (url.endsWith('/facets')) return ok([])
+            return ok(ROWS)
+        }),
+        post: vi.fn(async () => ok(null)),
+        put: vi.fn(async () => ok(null)),
+        delete: vi.fn(async () => ok(null)),
+    }
+}
+
+const hideRow2: RowActionPredicate = (_a, row) => row.id !== 2
+
+// La tabla pinta el layout de escritorio y el de tarjetas móviles a la vez en
+// el DOM (el CSS elige uno), así que cada fila cuenta dos veces.
+const LAYOUTS = 2
+
+describe('DynamicTable isRowActionVisible', () => {
+    const mount = (predicate?: RowActionPredicate) => {
+        const m = meta()
+        useMetadataCache.getState().setMetadata('issue', m)
+        return render(
+            <ApiProvider client={fakeApi(m)}>
+                <DynamicTable model="issue" enableUrlSync={false} isRowActionVisible={predicate} />
+            </ApiProvider>,
+        )
+    }
+
+    it('sin predicado todas las filas muestran el menú', async () => {
+        mount()
+        await screen.findAllByText('Dos')
+        expect(screen.getAllByText('Abrir menú')).toHaveLength(3 * LAYOUTS)
+    })
+
+    it('con predicado oculta el menú solo en la fila filtrada', async () => {
+        mount(hideRow2)
+        await screen.findAllByText('Dos')
+        await waitFor(() => expect(screen.getAllByText('Abrir menú')).toHaveLength(2 * LAYOUTS))
+    })
+
+    it('un predicado que lanza no rompe la tabla: oculta las acciones', async () => {
+        vi.spyOn(console, 'error').mockImplementation(() => {})
+        mount(() => {
+            throw new Error('boom')
+        })
+        await screen.findAllByText('Dos')
+        expect(screen.queryAllByText('Abrir menú')).toHaveLength(0)
+    })
+})
+
+describe('DynamicKanban isRowActionVisible', () => {
+    const mount = (predicate?: RowActionPredicate) => {
+        const m = meta({
+            view_type: 'kanban',
+            group_by: 'stage',
+            stages: [{ key: 'a', label: 'Etapa A', color: 'slate', order: 0 }],
+            columns: [
+                { key: 'title', label: 'Title', type: 'text', sortable: false, filterable: false, searchable: true },
+                { key: 'stage', label: 'Stage', type: 'status', sortable: false, filterable: false, options: [{ value: 'a', label: 'Etapa A', color: 'slate' }] },
+            ],
+        })
+        useMetadataCache.getState().setMetadata('issue', m)
+        return render(
+            <ApiProvider client={fakeApi(m)}>
+                <DynamicKanban model="issue" isRowActionVisible={predicate} />
+            </ApiProvider>,
+        )
+    }
+    const menus = (c: HTMLElement) => c.querySelectorAll('button[aria-haspopup="menu"]').length
+
+    it('sin predicado cada tarjeta tiene su menú', async () => {
+        const { container } = mount()
+        await screen.findAllByText('Dos')
+        expect(menus(container)).toBe(3)
+    })
+
+    it('con predicado la tarjeta filtrada pierde el menú', async () => {
+        const { container } = mount(hideRow2)
+        await screen.findAllByText('Dos')
+        await waitFor(() => expect(menus(container)).toBe(2))
+    })
+})

package/src/dynamic-columns-shim.ts

@@ -4,7 +4,7 @@
 // shadcn theme). Hosts pass their implementation into <DynamicTable> via the
 // `getDynamicColumns` prop.
 import type { ColumnDef } from '@tanstack/react-table'
-import type { TableMetadata } from './types'
+import type { ActionDefinition, TableMetadata } from './types'
 
 export interface FilterOption {
     label: string
@@ -31,6 +31,20 @@ export interface ColumnFilterConfig {
     loadOptions?: (q?: string) => Promise<FilterOption[]>
 }
 
+/**
+ * Consumer-side, per-row gate for row actions. Receives the full action
+ * definition and the row; return `false` to hide the action for that row. It
+ * is AND-ed with the metadata gates (`requiresState` + `condition`), so it can
+ * only hide more, never reveal an action the metadata already hides. A throwing
+ * predicate hides the action (fail-closed) and logs via `console.error`.
+ *
+ * Pass a stable reference (module-level function or `useCallback`): a new
+ * identity on every render rebuilds the table columns.
+ *
+ * Adapting a `(actionKey, row)` predicate: `(a, row) => legacy(a.key, row)`.
+ */
+export type RowActionPredicate = (action: ActionDefinition, row: Record<string, unknown>) => boolean
+
 /** Signature for the host-provided `getDynamicColumns` factory. */
 export type GetDynamicColumns = (
     metadata: TableMetadata,
@@ -40,6 +54,8 @@ export type GetDynamicColumns = (
     columnFilterConfigs: Map<string, ColumnFilterConfig>,
     timeZone?: string,
     currency?: string,
+    /** Consumer row-action predicate (`DynamicTable.isRowActionVisible`). Custom factories may ignore it. */
+    rowActionPredicate?: RowActionPredicate,
 ) => ColumnDef<any>[]
 
 /** Signature for the host-provided `DynamicIcon` renderer. */

package/src/dynamic-columns.tsx

@@ -59,6 +59,7 @@ import { isColumnVisibleInTable } from './column-visibility'
 import type {
     ColumnFilterConfig,
     GetDynamicColumns,
+    RowActionPredicate,
 } from './dynamic-columns-shim'
 
 /** Host-supplied helpers consumed by avatar/image cell renderers. */
@@ -75,6 +76,13 @@ export interface DynamicColumnsHelpers {
      * `import.meta.env.VITE_API_URL.replace('/api', '')`.
      */
     apiBaseUrl?: string
+    /**
+     * Optional host hook applied to the raw value of `type: 'image'` columns
+     * BEFORE it is resolved (absolute URL / rooted path / bare filename +
+     * basePath). Lets a host map its own storage convention (e.g. rewrite a
+     * legacy prefix) without the SDK hardcoding it. Omitted = no-op.
+     */
+    normalizeImagePath?: (raw: string, col: ColumnDefinition) => string
 }
 
 const defaultGetImageUrl = (path: string) => path
@@ -320,8 +328,22 @@ export const isActionConditionMet = (action: any, row: any): boolean => {
  * (`requiresState`) AND the declarative `condition` must pass. Shared by the
  * table's action column and the kanban card menu so they hide/show identically.
  */
-export const isRowActionVisible = (action: any, row: any, stageField?: string): boolean =>
-    isActionAllowedForRowState(action, row, stageField) && isActionConditionMet(action, row)
+export const isRowActionVisible = (
+    action: any,
+    row: any,
+    stageField?: string,
+    predicate?: RowActionPredicate,
+): boolean => {
+    if (!(isActionAllowedForRowState(action, row, stageField) && isActionConditionMet(action, row))) return false
+    if (!predicate) return true
+    // Consumer predicate: AND-ed with the metadata gates; fail-closed on throw.
+    try {
+        return !!predicate(action, row)
+    } catch (err) {
+        console.error('[metacore] isRowActionVisible predicate threw; hiding action', action?.key, err)
+        return false
+    }
+}
 
 /**
  * The column a model's `requiresState` gates read: the served `stage_field`
@@ -649,6 +671,26 @@ export const resolveAvatarSrc = (
     return `${apiBaseUrl}${basePath}${raw}`
 }
 
+/**
+ * Resolves the source of a `type: 'image'` cell with the same contract as
+ * `resolveAvatarSrc`: absolute `http(s)` URL and rooted `/path` are untouched;
+ * a bare filename gets `apiBaseUrl + basePath` only when the column declares a
+ * basePath (`styleConfig.base_path` / `col.basePath`), otherwise it is left
+ * as-is (previous behaviour). `normalizeImagePath` runs first. Exported for tests.
+ */
+export const resolveImageSrc = (
+    col: ColumnDefinition,
+    raw: string,
+    apiBaseUrl = '',
+    normalizeImagePath?: (raw: string, col: ColumnDefinition) => string,
+): string => {
+    const value = normalizeImagePath ? normalizeImagePath(raw, col) : raw
+    if (value.startsWith('http') || value.startsWith('/')) return value
+    const basePath = styleCfg(col, 'base_path', 'basePath') ?? col.basePath ?? ''
+    if (!basePath) return value
+    return `${apiBaseUrl}${basePath}${value}`
+}
+
 /**
  * Reads a secondary identifier the backend stamps on a resolved FK sibling — a
  * product's SKU, a user's email — projected as `subtitle`/`description` (the
@@ -880,6 +922,7 @@ export function makeDefaultGetDynamicColumns(
 ): GetDynamicColumns {
     const getImageUrl = helpers.getImageUrl ?? defaultGetImageUrl
     const apiBaseUrl = helpers.apiBaseUrl ?? ''
+    const normalizeImagePath = helpers.normalizeImagePath
 
     return function defaultGetDynamicColumns(
         metadata: TableMetadata,
@@ -889,6 +932,7 @@ export function makeDefaultGetDynamicColumns(
         filterConfigs?: Map<string, ColumnFilterConfig>,
         timeZone?: string,
         currency?: string,
+        rowActionPredicate?: RowActionPredicate,
     ): ColumnDef<any>[] {
         const dateLocale = currentLanguage === 'en' ? enUS : es
         const columns: ColumnDef<any>[] = [
@@ -1431,7 +1475,11 @@ export function makeDefaultGetDynamicColumns(
                                 (Array.isArray(row.original.media)
                                     ? row.original.media.find((m: any) => m.type === 'image')?.url
                                     : null)
-                            return <ImageCell value={imageValue} getImageUrl={getImageUrl} />
+                            const imageSrc =
+                                imageValue && !isLucideIconName(imageValue)
+                                    ? resolveImageSrc(col, String(imageValue), apiBaseUrl, normalizeImagePath)
+                                    : imageValue
+                            return <ImageCell value={imageSrc} getImageUrl={getImageUrl} />
                         }
 
                         case 'image_stack': {
@@ -1545,7 +1593,7 @@ export function makeDefaultGetDynamicColumns(
                     // secundarias (compartir/imprimir/correo/chat + las que
                     // aporten addons instalados). Ver row-actions-menu.tsx.
                     <RowActionsMenu
-                        actions={resolvedActions.filter((action) => isRowActionVisible(action, row.original, lifecycleStageField(metadata)))}
+                        actions={resolvedActions.filter((action) => isRowActionVisible(action, row.original, lifecycleStageField(metadata), rowActionPredicate))}
                         row={row.original}
                         onAction={onAction}
                     />

package/src/dynamic-kanban.tsx

@@ -161,6 +161,7 @@ import { useOptionsResolver } from './use-options-resolver'
 import { ActivityValueRenderer } from './activity-value-renderer'
 import { DynamicIcon } from './dynamic-icon'
 import { isColumnVisibleInTable } from './column-visibility'
+import type { RowActionPredicate } from './dynamic-columns-shim'
 import {
     aggregateOf,
     formatAggregateTotal,
@@ -169,7 +170,7 @@ import {
     relationKeyFor,
     RowActionMenuItem,
 } from './dynamic-columns'
-import { useCan, usePermissionsActive, resolveRowActions } from './permissions-context'
+import { useCan, usePermissionsActive, useRoleGate, resolveRowActions } from './permissions-context'
 import { useDynamicRowActions } from './dynamic-row-actions'
 import { useStageLayout } from './stage-layout'
 import type {
@@ -844,6 +845,15 @@ export interface DynamicKanbanProps {
      * record dialog. `delete`/link/custom actions are always handled in-SDK.
      */
     onAction?: (action: string, row: any) => void
+    /**
+     * Consumer-side per-row gate for row actions, AND-ed with the metadata
+     * gates (`requiresState` + `condition`): it can only hide more. Receives the
+     * full action definition (adapt an `(actionKey, row)` predicate with
+     * `(a, row) => legacy(a.key, row)`). A throw hides the action (fail-closed,
+     * `console.error`). Memoize it (module-level fn or `useCallback`).
+     * Omitted → behaviour unchanged. Not a substitute for backend authorization.
+     */
+    isRowActionVisible?: RowActionPredicate
     /**
      * Size of the INITIAL board page (one request, grouped into lanes). Each
      * lane then tops up incrementally on scroll (see `lanePageSize`). Defaults
@@ -931,6 +941,7 @@ function DynamicKanbanBoard({
     realtime: realtimeProp,
     onCardClick,
     onAction,
+    isRowActionVisible: rowActionPredicate,
     pageSize = 50,
     lanePageSize = 25,
     timeZone: timeZoneProp,
@@ -1607,14 +1618,20 @@ function DynamicKanbanBoard({
     // user lacks permission for never appears.
     const can = useCan()
     const permissionsActive = usePermissionsActive()
+    const roleGate = useRoleGate()
     const rowActions = useMemo(
         () =>
             metadata
-                ? resolveRowActions(metadata, model, can, permissionsActive, (k, fb) =>
-                      t(k, { defaultValue: fb }),
+                ? resolveRowActions(
+                      metadata,
+                      model,
+                      can,
+                      permissionsActive,
+                      (k, fb) => t(k, { defaultValue: fb }),
+                      roleGate,
                   )
                 : [],
-        [metadata, model, can, permissionsActive, t],
+        [metadata, model, can, permissionsActive, t, roleGate],
     )
 
     // Shared row-action dispatch + dialogs — view/edit/delete/link/custom behave
@@ -2142,6 +2159,7 @@ function DynamicKanbanBoard({
                             showAllFields={explicitCard}
                             actions={rowActions}
                             stageField={lifecycleStageField(metadata)}
+                            rowActionPredicate={rowActionPredicate}
                             locale={i18n.language}
                             timeZone={timeZone}
                             currency={currency}
@@ -2175,6 +2193,7 @@ function DynamicKanbanBoard({
                 showAllFields={explicitCard}
                 actions={rowActions}
                 stageField={lifecycleStageField(metadata)}
+                rowActionPredicate={rowActionPredicate}
                 locale={i18n.language}
                 timeZone={timeZone}
                 currency={currency}
@@ -3209,6 +3228,8 @@ interface KanbanCardProps {
     actions: ActionDefinition[]
     /** Column the actions' requiresState reads (the model's stage_field). */
     stageField?: string
+    /** Consumer row-action predicate (`DynamicKanban.isRowActionVisible`). */
+    rowActionPredicate?: RowActionPredicate
     locale: string
     timeZone?: string
     currency?: string
@@ -3287,6 +3308,7 @@ function KanbanCard({
     showAllFields,
     actions,
     stageField,
+    rowActionPredicate,
     locale,
     timeZone,
     currency,
@@ -3301,7 +3323,7 @@ function KanbanCard({
         disabled: !draggable,
     })
 
-    const visibleActions = actions.filter((a) => isRowActionVisible(a, card, stageField))
+    const visibleActions = actions.filter((a) => isRowActionVisible(a, card, stageField, rowActionPredicate))
 
     const menu =
         visibleActions.length > 0 ? (

package/src/dynamic-table.tsx

@@ -69,7 +69,7 @@ import { useMetadataCache } from './metadata-cache'
 import { useRecordMutationTick } from './use-record-mutation-tick'
 import { useApi, useCurrentBranch } from './api-context'
 import { useReasonPrompt } from './reason-prompt'
-import type { ColumnFilterConfig, GetDynamicColumns } from './dynamic-columns-shim'
+import type { ColumnFilterConfig, GetDynamicColumns, RowActionPredicate } from './dynamic-columns-shim'
 import { defaultGetDynamicColumns, DATE_CELL_TYPES, aggregateOf, formatAggregateTotal } from './dynamic-columns'
 import { useFacetLoaders, isLongTextColumn } from './use-facet-loaders'
 import { translateOptionLabels } from './filter-chips'
@@ -81,11 +81,11 @@ import {
 } from './table-virtualization'
 import { OptionsContext } from './options-context'
 import { RowActionsModelContext } from './row-actions-menu'
-import type { TableMetadata, ApiResponse, ColumnDefinition } from './types'
+import type { TableMetadata, ApiResponse, ColumnDefinition, ActionDefinition } from './types'
 import { getSearchableColumnKeys } from './column-visibility'
 import { visibleRelationInclude } from './list-include'
 import { useDebouncedValue } from './use-debounced-value'
-import { useCan, usePermissionsActive, gateTableMetadata } from './permissions-context'
+import { useCan, usePermissionsActive, useRoleGate, gateTableMetadata, modelCapability } from './permissions-context'
 import { useDynamicRowActions } from './dynamic-row-actions'
 import { ExportDialog } from './dialogs/export'
 import { ImportDialog } from './dialogs/import'
@@ -184,6 +184,13 @@ export interface DynamicTableProps {
      */
     mutationEndpoint?: string
     enableUrlSync?: boolean
+    /**
+     * Initial sort applied when there is no user/URL sorting yet. It seeds the
+     * `sorting` state, so a `?sortBy=` deep-link wins over it (when
+     * `enableUrlSync`), and the user can still change or clear the sort via
+     * the column headers. Only read on mount.
+     */
+    defaultSort?: { id: string; desc?: boolean }
     /**
      * Hide the import action on THIS view even when the model supports it.
      * A role-scoped view (e.g. a rep seeing only their own records) usually
@@ -213,6 +220,15 @@ export interface DynamicTableProps {
      * clickable and the behaviour is unchanged.
      */
     onRowClick?: (row: any) => void
+    /**
+     * Consumer-side per-row gate for row actions, AND-ed with the metadata
+     * gates (`requiresState` + `condition`): it can only hide more. Receives the
+     * full action definition (adapt an `(actionKey, row)` predicate with
+     * `(a, row) => legacy(a.key, row)`). A throw hides the action (fail-closed,
+     * `console.error`). Memoize it (module-level fn or `useCallback`).
+     * Omitted → behaviour unchanged. Not a substitute for backend authorization.
+     */
+    isRowActionVisible?: RowActionPredicate
     refreshTrigger?: any
     defaultFilters?: Record<string, any>
     extraColumns?: ColumnDef<any>[]
@@ -294,6 +310,10 @@ export interface DynamicTableBulkContext {
     selectedIds: Array<string | number>
     clearSelection: () => void
     refresh: () => void
+    /** Metadata actions visible to the current user (capability-gated when a PermissionsProvider is mounted). */
+    actions: ActionDefinition[]
+    /** `true` when the user may run `actionKey` on this model; always `true` without a PermissionsProvider. */
+    can: (actionKey: string) => boolean
 }
 
 /** True when an api-client error is an HTTP 403 (axios-style or fetch-style). */
@@ -307,12 +327,14 @@ export function DynamicTable({
     endpoint,
     mutationEndpoint,
     enableUrlSync = true,
+    defaultSort,
     hideImport,
     hideExport,
     hiddenColumns = [],
     allowedActionKeys,
     onAction,
     onRowClick,
+    isRowActionVisible: rowActionPredicate,
     refreshTrigger,
     defaultFilters,
     extraColumns = [],
@@ -395,7 +417,12 @@ export function DynamicTable({
     const [bulkDeleteTotal, setBulkDeleteTotal] = useState(0)
 
     const [rowSelection, setRowSelection] = useState({})
-    const [sorting, setSorting] = useState<SortingState>([])
+    const [sorting, setSorting] = useState<SortingState>(() => {
+        if (!defaultSort) return []
+        // A deep-linked ?sortBy= wins; skip the default so no request goes out with it first.
+        if (enableUrlSync && typeof window !== 'undefined' && new URLSearchParams(window.location.search).get('sortBy')) return []
+        return [{ id: defaultSort.id, desc: defaultSort.desc ?? false }]
+    })
     const [columnVisibility, setColumnVisibility] = useState<VisibilityState>(() => {
         const initial: VisibilityState = {}
         hiddenColumns.forEach(col => { initial[col] = false })
@@ -799,10 +826,11 @@ export function DynamicTable({
     // filtered by `can(lowercase(model).<action>)`.
     const can = useCan()
     const permissionsActive = usePermissionsActive()
+    const roleGate = useRoleGate()
     const viewMetadata = useMemo(() => {
         if (!metadata || !permissionsActive) return metadata
-        return gateTableMetadata(metadata, model, can, (key, fallback) => t(key, { defaultValue: fallback }))
-    }, [metadata, permissionsActive, can, model, t])
+        return gateTableMetadata(metadata, model, can, (key, fallback) => t(key, { defaultValue: fallback }), roleGate)
+    }, [metadata, permissionsActive, can, model, t, roleGate])
 
     // Row-action menus mount their icons on open: load them with the
     // metadata so the first open draws every glyph at once.
@@ -1396,12 +1424,12 @@ export function DynamicTable({
             }
             return actions === viewMetadata.actions ? viewMetadata : { ...viewMetadata, actions }
         })()
-        const baseColumns = getDynamicColumns(rowMetadata, handleInternalAction, t, i18n.language, columnFilterConfigs, timeZone, currency)
+        const baseColumns = getDynamicColumns(rowMetadata, handleInternalAction, t, i18n.language, columnFilterConfigs, timeZone, currency, rowActionPredicate)
         const filteredBase = baseColumns.filter((col: ColumnDef<any>) => !effectiveHiddenColumns.includes(col.id as string))
         const actionsCol = filteredBase.find((c: ColumnDef<any>) => c.id === 'actions')
         const otherCols = filteredBase.filter((c: ColumnDef<any>) => c.id !== 'actions')
         return [...otherCols, ...extraColumns, ...(actionsCol ? [actionsCol] : [])]
-    }, [viewMetadata, handleInternalAction, effectiveHiddenColumns, allowedActionKeys, extraColumns, t, i18n.language, columnFilterConfigs, getDynamicColumns, timeZone, currency])
+    }, [viewMetadata, handleInternalAction, effectiveHiddenColumns, allowedActionKeys, extraColumns, t, i18n.language, columnFilterConfigs, getDynamicColumns, timeZone, currency, rowActionPredicate])
 
     const filters = useMemo(() => [], [])
 
@@ -1979,6 +2007,8 @@ export function DynamicTable({
                         selectedIds: bulkSelectedRows.map((r) => r.id).filter((id) => id != null),
                         clearSelection: () => table.resetRowSelection(),
                         refresh: handleRefresh,
+                        actions: viewMetadata?.actions ?? [],
+                        can: (actionKey: string) => !permissionsActive || can(modelCapability(model, actionKey)),
                     })
                     : extraBulkActions}
                 {!hideBulkDelete && (