@salemaljebaly/payload-plugin-rbac-ui 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Salem Aljebaly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# @salemaljebaly/payload-plugin-rbac-ui
+
+Reusable RBAC permissions matrix UI for Payload CMS.
+
+## Features
+
+- Adds a grouped checkbox matrix UI for role permissions in Admin.
+- Validates role permissions against a strict allowed list.
+- Keeps role permission UI and server-side validation in sync.
+- Works by enhancing an existing roles collection.
+
+## Install
+
+```bash
+pnpm add @salemaljebaly/payload-plugin-rbac-ui
+```
+
+## Usage
+
+```ts
+import { buildConfig } from 'payload'
+import { rbacUIPlugin, type PermissionGroup } from '@salemaljebaly/payload-plugin-rbac-ui'
+
+const permissionGroups: PermissionGroup[] = [
+  {
+    label: 'Posts',
+    permissions: [
+      { action: 'Create', description: 'Create posts', permission: 'Create:Post' },
+      { action: 'Read', description: 'Read posts', permission: 'Read:Post' },
+      { action: 'Update', description: 'Update posts', permission: 'Update:Post' },
+      { action: 'Delete', description: 'Delete posts', permission: 'Delete:Post' },
+    ],
+  },
+]
+
+export default buildConfig({
+  collections: [/* users, roles, etc */],
+  plugins: [
+    rbacUIPlugin({
+      rolesCollectionSlug: 'roles',
+      permissionsFieldName: 'permissions',
+      permissionGroups,
+    }),
+  ],
+})
+```
+
+## Options
+
+- `rolesCollectionSlug`: roles collection slug. Default: `roles`
+- `permissionsFieldName`: permissions field name. Default: `permissions`
+- `permissionGroups`: grouped permission model used by the UI and validator.
+- `rolesFieldDescription`: custom field description text.
+- `ensurePermissionsField`: if `true`, inserts field when missing. Default: `true`
+- `customFieldPath`: override the client component path.
+- `onConfigureRolesCollection`: final roles collection mutator.
+
+## Best Practices
+
+- Keep permission strings stable (`Action:Resource`).
+- Use one shared permission registry for UI, role seeds, and access helpers.
+- Use `overrideAccess: false` whenever you pass `user` in Local API calls.
+- Keep access checks server-side; UI is only convenience.
+
+## Publishing / Official Discovery
+
+To make the plugin discoverable in the Payload ecosystem:
+
+1. Publish to npm.
+2. Add topic `payload-plugin` to the GitHub repository.
+
+Payload docs reference the `payload-plugin` topic for plugin discovery.
+
+## Development
+
+```bash
+pnpm test
+```

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@salemaljebaly/payload-plugin-rbac-ui",
+  "version": "0.1.0",
+  "description": "Reusable RBAC permissions UI and helpers for Payload CMS",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./client": "./src/components/PermissionsMatrixField.tsx",
+    "./types": "./src/types.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "payload": "^3.76.1",
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "25.2.3",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "payload": "3.76.1",
+    "typescript": "5.9.3",
+    "vitest": "4.0.18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "payload",
+    "payloadcms",
+    "payload-plugin",
+    "rbac",
+    "permissions"
+  ],
+  "scripts": {
+    "test": "vitest run --config ./vitest.config.mts",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/components/PermissionsMatrixField.tsx

@@ -0,0 +1,193 @@
+'use client'
+
+import React, { useCallback, useMemo } from 'react'
+import type { JSONFieldClientComponent } from 'payload'
+import { useField } from '@payloadcms/ui'
+import type { PermissionGroup } from '../types'
+import { coerceStringArray } from '../lib/permissions'
+
+type FieldAdminConfig = {
+  custom?: {
+    rbac?: {
+      permissionGroups?: PermissionGroup[]
+    }
+  }
+}
+
+const readPermissionGroups = (props: unknown): PermissionGroup[] => {
+  const typedProps = props as { field?: { admin?: FieldAdminConfig } }
+  const admin = typedProps.field?.admin
+  return admin?.custom?.rbac?.permissionGroups ?? []
+}
+
+export const PermissionsMatrixField: JSONFieldClientComponent = (props) => {
+  const { path } = props
+  const groups = readPermissionGroups(props)
+  const { value, setValue } = useField<unknown>({ path })
+
+  const safeValue = useMemo(() => coerceStringArray(value), [value])
+  const currentPermissions = useMemo(() => new Set(safeValue), [safeValue])
+
+  const handleTogglePermission = useCallback(
+    (permission: string) => {
+      const nextValue = currentPermissions.has(permission)
+        ? safeValue.filter((p) => p !== permission)
+        : [...safeValue, permission]
+
+      setValue(nextValue)
+    },
+    [currentPermissions, safeValue, setValue],
+  )
+
+  const handleToggleGroup = useCallback(
+    (group: PermissionGroup) => {
+      const groupPermissions = group.permissions.map((item) => item.permission)
+      const allSelected = groupPermissions.every((permission) => currentPermissions.has(permission))
+
+      const nextValue = allSelected
+        ? safeValue.filter((p) => !groupPermissions.includes(p))
+        : [...new Set([...safeValue, ...groupPermissions])]
+
+      setValue(nextValue)
+    },
+    [currentPermissions, safeValue, setValue],
+  )
+
+  return (
+    <div className="field-type permissions-field" style={{ marginTop: 'var(--base)' }}>
+      <div
+        style={{
+          marginBottom: 'var(--base)',
+          padding: 'var(--base)',
+          backgroundColor: 'var(--theme-success-50)',
+          border: '1px solid var(--theme-success-200)',
+          borderRadius: 'var(--base-radius)',
+        }}
+      >
+        <strong>Selected: {currentPermissions.size} permissions</strong>
+      </div>
+
+      {groups.map((group) => {
+        const groupPermissions = group.permissions.map((item) => item.permission)
+        const selectedCount = groupPermissions.filter((permission) => currentPermissions.has(permission)).length
+        const allSelected = selectedCount === groupPermissions.length
+        const someSelected = selectedCount > 0 && !allSelected
+
+        return (
+          <div
+            key={group.label}
+            style={{
+              marginBottom: 'calc(var(--base) * 1.5)',
+              border: '1px solid var(--theme-elevation-150)',
+              borderRadius: 'var(--base-radius)',
+              overflow: 'hidden',
+              backgroundColor: 'var(--theme-bg)',
+            }}
+          >
+            <div
+              style={{
+                padding: 'var(--base)',
+                backgroundColor: allSelected
+                  ? 'var(--theme-success-100)'
+                  : someSelected
+                    ? 'var(--theme-warning-100)'
+                    : 'var(--theme-elevation-50)',
+                borderBottom: '1px solid var(--theme-elevation-150)',
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'space-between',
+              }}
+            >
+              <div style={{ display: 'flex', alignItems: 'center', gap: 'calc(var(--base) * 0.75)' }}>
+                <input
+                  type="checkbox"
+                  checked={allSelected}
+                  ref={(input) => {
+                    if (input) input.indeterminate = someSelected
+                  }}
+                  onChange={() => handleToggleGroup(group)}
+                  style={{ cursor: 'pointer' }}
+                />
+                <strong style={{ fontSize: '1.125rem' }}>{group.label}</strong>
+                {selectedCount > 0 && (
+                  <span
+                    style={{
+                      fontSize: '0.875rem',
+                      color: 'var(--theme-elevation-500)',
+                      backgroundColor: 'var(--theme-elevation-100)',
+                      padding: '0.125rem 0.5rem',
+                      borderRadius: '9999px',
+                    }}
+                  >
+                    {selectedCount}/{groupPermissions.length}
+                  </span>
+                )}
+              </div>
+              <button
+                type="button"
+                onClick={() => handleToggleGroup(group)}
+                className="btn"
+                style={{
+                  padding: '0.5rem 1rem',
+                  fontSize: '0.875rem',
+                  backgroundColor: allSelected ? 'var(--theme-error-500)' : 'var(--theme-success-500)',
+                  color: 'white',
+                  border: 'none',
+                  borderRadius: 'var(--base-radius)',
+                  cursor: 'pointer',
+                }}
+              >
+                {allSelected ? 'Deselect All' : 'Select All'}
+              </button>
+            </div>
+
+            <div
+              style={{
+                padding: 'var(--base)',
+                display: 'grid',
+                gridTemplateColumns: 'repeat(auto-fill, minmax(280px, 1fr))',
+                gap: 'calc(var(--base) * 0.75)',
+              }}
+            >
+              {group.permissions.map((item) => {
+                const isSelected = currentPermissions.has(item.permission)
+
+                return (
+                  <label
+                    key={item.permission}
+                    style={{
+                      display: 'flex',
+                      alignItems: 'flex-start',
+                      gap: '0.5rem',
+                      padding: 'calc(var(--base) * 0.75)',
+                      border: `2px solid ${isSelected ? 'var(--theme-success-500)' : 'var(--theme-elevation-150)'}`,
+                      borderRadius: 'var(--base-radius)',
+                      backgroundColor: isSelected ? 'var(--theme-success-50)' : 'var(--theme-bg)',
+                      cursor: 'pointer',
+                      transition: 'all 0.2s',
+                    }}
+                  >
+                    <input
+                      type="checkbox"
+                      checked={isSelected}
+                      onChange={() => handleTogglePermission(item.permission)}
+                      style={{ marginTop: '0.125rem', cursor: 'pointer' }}
+                    />
+                    <div>
+                      <div style={{ fontWeight: '600', fontSize: '0.875rem', marginBottom: '0.125rem' }}>
+                        {item.action}
+                      </div>
+                      <div style={{ fontSize: '0.75rem', color: 'var(--theme-elevation-600)' }}>
+                        {item.description}
+                      </div>
+                    </div>
+                  </label>
+                )
+              })}
+            </div>
+          </div>
+        )
+      })}
+    </div>
+  )
+}

package/src/index.ts

@@ -0,0 +1,107 @@
+import type { CollectionConfig, Config, Plugin } from 'payload'
+import type { PermissionGroup, RBACUIPluginOptions } from './types'
+import { flattenPermissionGroups, validatePermissionArray } from './lib/permissions'
+
+const DEFAULT_ROLES_COLLECTION = 'roles'
+const DEFAULT_PERMISSIONS_FIELD = 'permissions'
+const DEFAULT_COMPONENT_PATH = '@salemaljebaly/payload-plugin-rbac-ui/client#PermissionsMatrixField'
+
+const resolveDescription = (
+  description: RBACUIPluginOptions['rolesFieldDescription'],
+): string | Record<string, string> => {
+  if (!description) return 'Select permissions for this role'
+  return description
+}
+
+const configureRolesCollection = ({
+  collection,
+  options,
+  allowedPermissions,
+}: {
+  collection: CollectionConfig
+  options: RBACUIPluginOptions
+  allowedPermissions: string[]
+}): CollectionConfig => {
+  const permissionsFieldName = options.permissionsFieldName ?? DEFAULT_PERMISSIONS_FIELD
+  const componentPath = options.customFieldPath ?? DEFAULT_COMPONENT_PATH
+  const permissionGroups = options.permissionGroups
+  const fieldDescription = resolveDescription(options.rolesFieldDescription)
+
+  const fields = [...(collection.fields ?? [])]
+  const permissionsFieldIndex = fields.findIndex(
+    (field) => 'name' in field && field.name === permissionsFieldName,
+  )
+
+  const fieldPatch = {
+    type: 'json' as const,
+    name: permissionsFieldName,
+    admin: {
+      description: fieldDescription,
+      custom: {
+        rbac: {
+          permissionGroups,
+        },
+      },
+      components: {
+        Field: componentPath,
+      },
+    },
+    validate: (value: unknown) => validatePermissionArray(value, allowedPermissions),
+  }
+
+  if (permissionsFieldIndex === -1) {
+    if (options.ensurePermissionsField === false) return collection
+    fields.push(fieldPatch)
+  } else {
+    const existingField = fields[permissionsFieldIndex]
+    fields[permissionsFieldIndex] = {
+      ...(existingField as object),
+      ...fieldPatch,
+      admin: {
+        ...((existingField as { admin?: object }).admin ?? {}),
+        ...fieldPatch.admin,
+      },
+    }
+  }
+
+  const updated = {
+    ...collection,
+    fields,
+  }
+
+  return options.onConfigureRolesCollection ? options.onConfigureRolesCollection(updated) : updated
+}
+
+export const rbacUIPlugin = (options: RBACUIPluginOptions): Plugin => {
+  if (!options.permissionGroups || options.permissionGroups.length === 0) {
+    throw new Error('rbacUIPlugin requires at least one permission group.')
+  }
+
+  const rolesCollectionSlug = options.rolesCollectionSlug ?? DEFAULT_ROLES_COLLECTION
+  const allowedPermissions = flattenPermissionGroups(options.permissionGroups)
+
+  return (incomingConfig: Config): Config => {
+    const collections = incomingConfig.collections ?? []
+
+    const hasRolesCollection = collections.some((collection) => collection.slug === rolesCollectionSlug)
+    if (!hasRolesCollection) {
+      throw new Error(`rbacUIPlugin could not find roles collection: "${rolesCollectionSlug}"`)
+    }
+
+    return {
+      ...incomingConfig,
+      collections: collections.map((collection) => {
+        if (collection.slug !== rolesCollectionSlug) return collection
+
+        return configureRolesCollection({
+          collection,
+          options,
+          allowedPermissions,
+        })
+      }),
+    }
+  }
+}
+
+export type { PermissionGroup, PermissionItem, RBACUIPluginOptions } from './types'
+export { flattenPermissionGroups, validatePermissionArray } from './lib/permissions'

package/src/lib/permissions.ts

@@ -0,0 +1,36 @@
+import type { PermissionGroup } from '../types'
+
+export const flattenPermissionGroups = (groups: PermissionGroup[]): string[] => {
+  const unique = new Set<string>()
+
+  for (const group of groups) {
+    for (const item of group.permissions) {
+      unique.add(item.permission)
+    }
+  }
+
+  return [...unique]
+}
+
+export const validatePermissionArray = (
+  value: unknown,
+  allowedPermissions: readonly string[],
+): true | string => {
+  if (value === null || value === undefined) return true
+  if (!Array.isArray(value)) return 'Permissions must be an array of strings.'
+
+  const invalid = value.filter(
+    (item) => typeof item !== 'string' || !allowedPermissions.includes(item),
+  )
+
+  if (invalid.length > 0) {
+    return `Invalid permissions found: ${invalid.join(', ')}`
+  }
+
+  return true
+}
+
+export const coerceStringArray = (value: unknown): string[] => {
+  if (!Array.isArray(value)) return []
+  return value.filter((v): v is string => typeof v === 'string')
+}

package/src/types.ts

@@ -0,0 +1,22 @@
+import type { CollectionConfig } from 'payload'
+
+export type PermissionItem = {
+  action: string
+  description: string
+  permission: string
+}
+
+export type PermissionGroup = {
+  label: string
+  permissions: PermissionItem[]
+}
+
+export type RBACUIPluginOptions = {
+  rolesCollectionSlug?: string
+  permissionsFieldName?: string
+  permissionGroups: PermissionGroup[]
+  rolesFieldDescription?: string | Record<string, string>
+  ensurePermissionsField?: boolean
+  customFieldPath?: string
+  onConfigureRolesCollection?: (collection: CollectionConfig) => CollectionConfig
+}