@asteby/metacore-runtime-react 49.9.0 → 49.10.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 && (

package/src/index.ts

@@ -259,12 +259,15 @@ export {
     PermissionsProvider,
     useCan,
     usePermissionsActive,
+    useRoleGate,
+    isActionAllowedForRoles,
     makeCan,
     capabilityForActionKey,
     modelCapability,
     gateTableMetadata,
     resolveRowActions,
     type CanFn,
+    type RoleGate,
     type PermissionsProviderProps,
 } from './permissions-context'
 export {
@@ -423,6 +426,7 @@ export type {
     ColumnFilterConfig,
     FilterOption as DynamicColumnFilterOption,
     GetDynamicColumns,
+    RowActionPredicate,
     DynamicIconComponent,
 } from './dynamic-columns-shim'
 export {
@@ -430,6 +434,7 @@ export {
     makeDefaultGetDynamicColumns,
     relationKeyFor,
     resolveAvatarSrc,
+    resolveImageSrc,
     resolveMissingActorLabel,
     resolveActorDisplayName,
     resolveRelationLabel,

package/src/permissions-context.tsx

@@ -35,9 +35,44 @@ export interface PermissionsProviderProps {
     permissions: string[]
     /** Superrole bypass — admins/owners see everything, no filtering at all. */
     isAdmin: boolean
+    /**
+     * Roles of the current user (e.g. `['doctor']`), used ONLY to honour the
+     * per-action `allowedRoles` declared in table metadata. Opt-in: while this
+     * is `undefined` (and `loading` is not set) role filtering is OFF and
+     * `allowedRoles` is ignored, exactly as before this prop existed. Once the
+     * host passes an array (even `[]` = "resolved, no roles") the filter is
+     * fail-closed: an action with a non-empty `allowedRoles` that shares no
+     * role with the user is hidden.
+     *
+     * Pass a referentially stable array (`useMemo`, or a value straight from a
+     * store): the table rebuilds its columns when `roles` / `superRoles` change
+     * identity, so an inline `roles={[role]}` recreates them on every render.
+     */
+    roles?: string[]
+    /**
+     * Roles that bypass `allowedRoles` entirely (the host's superroles, e.g.
+     * `['admin', 'super_admin']`). Default `[]` = no role bypasses. `isAdmin`
+     * also bypasses. Same stable-reference advice as `roles`.
+     */
+    superRoles?: string[]
+    /**
+     * The host is still hydrating the session roles. While true no action is
+     * hidden by `allowedRoles` (avoids a flash of missing actions); set it back
+     * to false once `roles` is resolved.
+     */
+    rolesLoading?: boolean
     children: React.ReactNode
 }
 
+/** Resolved role-gating state shared with the table surfaces. */
+export interface RoleGate {
+    /** User roles; `undefined` while unresolved. */
+    roles?: string[]
+    superRoles: string[]
+    loading: boolean
+    isAdmin: boolean
+}
+
 // ---------------------------------------------------------------------------
 // Core
 // ---------------------------------------------------------------------------
@@ -56,10 +91,64 @@ export function makeCan(permissions: string[], isAdmin: boolean): CanFn {
 const ALWAYS_ALLOW: CanFn = () => true
 
 const PermissionsContext = createContext<CanFn | null>(null)
+const RoleGateContext = createContext<RoleGate | null>(null)
+
+const NO_ROLES: string[] = []
 
-export function PermissionsProvider({ permissions, isAdmin, children }: PermissionsProviderProps) {
+export function PermissionsProvider({
+    permissions,
+    isAdmin,
+    roles,
+    superRoles = NO_ROLES,
+    rolesLoading = false,
+    children,
+}: PermissionsProviderProps) {
     const can = useMemo(() => makeCan(permissions, isAdmin), [permissions, isAdmin])
-    return <PermissionsContext.Provider value={can}>{children}</PermissionsContext.Provider>
+    const roleGate = useMemo<RoleGate>(
+        () => ({ roles, superRoles, loading: rolesLoading, isAdmin }),
+        [roles, superRoles, rolesLoading, isAdmin],
+    )
+    return (
+        <PermissionsContext.Provider value={can}>
+            <RoleGateContext.Provider value={roleGate}>{children}</RoleGateContext.Provider>
+        </PermissionsContext.Provider>
+    )
+}
+
+/**
+ * Role-gating state of the nearest <PermissionsProvider>, or `null` when none
+ * is mounted (no provider → no role filtering, legacy behaviour).
+ */
+export function useRoleGate(): RoleGate | null {
+    return useContext(RoleGateContext)
+}
+
+/**
+ * Whether `action` is visible for the user under `gate`. Pure.
+ *
+ * UX ONLY: this hides buttons, it does not authorize anything. The backend
+ * remains the authority and must enforce the same `allowedRoles` on execution.
+ *
+ * Rules:
+ *   - no gate (no provider) → visible (unchanged behaviour).
+ *   - action without `allowedRoles` (or empty) → visible. Reads both the
+ *     camelCase `allowedRoles` and the snake_case `allowed_roles` wire forms.
+ *   - `gate.loading` → visible (don't flash-hide while the session hydrates).
+ *   - `gate.roles === undefined` and not loading → the host did not opt in to
+ *     role gating → visible.
+ *   - `gate.isAdmin` or any user role in `gate.superRoles` → visible.
+ *   - otherwise visible only if the user shares a role with `allowedRoles`
+ *     (fail-closed: `roles: []` sees none of the restricted actions).
+ */
+export function isActionAllowedForRoles(action: ActionDefinition, gate: RoleGate | null): boolean {
+    if (!gate) return true
+    const declared = action.allowedRoles ?? action.allowed_roles
+    if (!declared || declared.length === 0) return true
+    if (gate.loading || gate.roles === undefined) return true
+    if (gate.isAdmin) return true
+    const userRoles = gate.roles
+    if (userRoles.some((r) => gate.superRoles.includes(r))) return true
+    return userRoles.some((r) => declared.includes(r))
 }
 
 /**
@@ -113,6 +202,10 @@ const DEFAULT_TRIO: { key: string; i18nKey: string; fallback: string; icon: stri
  *     actions so individual entries can be dropped; `tx` resolves their labels
  *     (defaults to the Spanish fallbacks used by the column factory).
  *
+ * When `roleGate` is given, actions declaring `allowedRoles` are also dropped
+ * for users outside those roles (see `isActionAllowedForRoles`; UX only, the
+ * backend stays the authority).
+ *
  * Pure + idempotent. Callers should only invoke it when a provider is active
  * (`usePermissionsActive()`), otherwise pass the metadata through untouched.
  */
@@ -121,6 +214,7 @@ export function gateTableMetadata(
     model: string,
     can: CanFn,
     tx: (i18nKey: string, fallback: string) => string = (_k, fallback) => fallback,
+    roleGate: RoleGate | null = null,
 ): TableMetadata {
     const allowed = (key: string) => can(modelCapability(model, key))
 
@@ -139,7 +233,7 @@ export function gateTableMetadata(
                     }) as ActionDefinition,
             )
           : []
-    const actions = base.filter((a) => allowed(a.key))
+    const actions = base.filter((a) => allowed(a.key) && isActionAllowedForRoles(a, roleGate))
 
     return {
         ...metadata,
@@ -176,8 +270,9 @@ export function resolveRowActions(
     can: CanFn,
     permissionsActive: boolean,
     tx: (i18nKey: string, fallback: string) => string = (_k, fallback) => fallback,
+    roleGate: RoleGate | null = null,
 ): ActionDefinition[] {
-    const gated = permissionsActive ? gateTableMetadata(metadata, model, can, tx) : metadata
+    const gated = permissionsActive ? gateTableMetadata(metadata, model, can, tx, roleGate) : metadata
     const explicit = gated.actions ?? []
     const hasExplicit = (gated.hasActions ?? explicit.length > 0) && explicit.length > 0
     const base: ActionDefinition[] = hasExplicit

package/src/types.ts

@@ -905,6 +905,14 @@ export interface ActionDefinition {
     /** Multi-step wizard form; when present the dispatcher renders a wizard. */
     steps?: ActionStep[]
     requiresState?: string[]
+    /**
+     * Roles allowed to see/run this action. Empty/absent = unrestricted. Only
+     * filters the UI when the host mounts <PermissionsProvider roles={...}>
+     * (see `isActionAllowedForRoles`); the backend remains the authority.
+     */
+    allowedRoles?: string[]
+    /** snake_case wire form of `allowedRoles`, read as a fallback. */
+    allowed_roles?: string[]
     /**
      * Manifest `supervisor_policy`: the action needs the on-the-spot
      * authorization of a supervisor for that policy (`general.approve_<policy>`).