@zealamic/payload-auth-rbac-plugin 1.0.0-beta.9 → 1.0.1

package/docs/TRANSLATIONS.md

@@ -0,0 +1,469 @@
+# Translations guide
+
+Customize Admin labels, placeholders, select options, and permission-matrix UI text via the plugin `translations` option.
+
+```ts
+import type { RBACTranslations } from "@zealamic/payload-auth-rbac-plugin/types";
+import { payloadAuthRbacPlugin } from "@zealamic/payload-auth-rbac-plugin";
+
+export default buildConfig({
+  i18n: {
+    supportedLanguages: { en, vi },
+    fallbackLanguage: "en",
+  },
+  plugins: [
+    payloadAuthRbacPlugin({
+      translations: {
+        en: {
+          /* partial overrides OK */
+        },
+        vi: {
+          /* provide full strings for vi */
+        },
+      },
+    }),
+  ],
+});
+```
+
+---
+
+## How it works
+
+Translations are used in **two places**:
+
+| Layer                          | What it affects                                                                      |
+| ------------------------------ | ------------------------------------------------------------------------------------ |
+| **Collection config**          | Sidebar group, collection labels, field labels, placeholders, select option labels   |
+| **`config.i18n.translations`** | Permission matrix UI (`useTranslation` keys under `components.rolePermissionMatrix`) |
+
+**Merge order when the plugin loads:**
+
+```
+Plugin English defaults
+  → deep-merge your pluginOptions.translations
+    → deep-merge into existing config.i18n.translations
+```
+
+You only pass RBAC strings to **`payloadAuthRbacPlugin({ translations })`**. The plugin registers them into Payload i18n automatically — do **not** duplicate the same keys in `config.i18n.translations`.
+
+Your project's `config.i18n` still owns:
+
+- `supportedLanguages`
+- `fallbackLanguage`
+- Non-RBAC app strings (optional)
+
+### Locale merge behavior
+
+| Locale            | Behavior                                                                                                     |
+| ----------------- | ------------------------------------------------------------------------------------------------------------ |
+| `en`              | Partial overrides OK — missing keys inherit plugin English defaults                                          |
+| Other (e.g. `vi`) | **No** auto-fill from `en` — provide complete strings for that locale, or rely on Payload `fallbackLanguage` |
+
+### Serializable values only (Payload 3 / Next.js)
+
+Use **plain strings** (and nested objects of strings) only:
+
+```ts
+// ✅
+labels: { singular: "Role", plural: "Roles" }
+
+// ❌ functions, i18n library calls, class instances
+labels: { singular: () => "Role" }
+```
+
+---
+
+## Config shape
+
+Top-level keys = **locale codes** (`en`, `vi`, …). Must match `i18n.supportedLanguages`.
+
+```ts
+type RBACTranslations = {
+  [locale: string]: {
+    collections?: {
+      permissionActions?: CollectionTranslations;
+      permissionFeatures?: CollectionTranslations;
+      permissions?: CollectionTranslations;
+      roles?: CollectionTranslations;
+      rolesPermissions?: CollectionTranslations;
+      users?: UsersFieldTranslations; // fields only
+    };
+    components?: {
+      rolePermissionMatrix?: MatrixTranslations;
+    };
+  };
+};
+```
+
+### Collection config keys (camelCase)
+
+| Config key           | Collection slug                        |
+| -------------------- | -------------------------------------- |
+| `permissionActions`  | `permission-actions`                   |
+| `permissionFeatures` | `permission-features`                  |
+| `permissions`        | `permissions`                          |
+| `roles`              | `roles`                                |
+| `rolesPermissions`   | `roles-permissions`                    |
+| `users`              | Your auth collection (plugin-modified) |
+
+Every collection block supports:
+
+```ts
+{
+  labels?: { singular?: string; plural?: string };
+  admin?: { group?: string };
+  fields?: { [fieldName]: FieldTranslation };
+}
+```
+
+### Common field keys
+
+| Key           | Used on              |
+| ------------- | -------------------- |
+| `label`       | All fields           |
+| `placeholder` | Text, number, select |
+
+### Select option labels
+
+Pattern: **`{value}Label`** where `{value}` is the stored option value.
+
+```ts
+// status: active | inactive
+status: {
+  label: "Status",
+  placeholder: "Select status",
+  activeLabel: "Active",
+  inactiveLabel: "Inactive",
+}
+
+// permission-actions type: main | sub
+type: {
+  mainLabel: "Main",
+  subLabel: "Sub",
+}
+
+// roles dataScope: own | hierarchy | all
+dataScope: {
+  ownLabel: "Own",
+  hierarchyLabel: "Hierarchy",
+  allLabel: "All",
+}
+```
+
+---
+
+## Per-collection field keys
+
+All keys are optional. Defaults live in `src/collections/*/default-data.ts`.
+
+### `permissionActions`
+
+| Field       | Keys                                                   |
+| ----------- | ------------------------------------------------------ |
+| `code`      | `label`, `placeholder`                                 |
+| `type`      | `label`, `placeholder`, `mainLabel`, `subLabel`        |
+| `sortOrder` | `label`, `placeholder`                                 |
+| `status`    | `label`, `placeholder`, `activeLabel`, `inactiveLabel` |
+
+### `permissionFeatures`
+
+| Field       | Keys                                                   |
+| ----------- | ------------------------------------------------------ |
+| `code`      | `label`, `placeholder`                                 |
+| `sortOrder` | `label`, `placeholder`                                 |
+| `status`    | `label`, `placeholder`, `activeLabel`, `inactiveLabel` |
+
+### `permissions`
+
+| Field               | Keys                                                   |
+| ------------------- | ------------------------------------------------------ |
+| `name`              | `label`, `placeholder`                                 |
+| `permissionFeature` | `label`, `placeholder`                                 |
+| `permissionAction`  | `label`, `placeholder`                                 |
+| `sortOrder`         | `label`, `placeholder`                                 |
+| `status`            | `label`, `placeholder`, `activeLabel`, `inactiveLabel` |
+
+### `roles`
+
+| Field                         | Keys                                                                             |
+| ----------------------------- | -------------------------------------------------------------------------------- |
+| `code`, `name`, `description` | `label`, `placeholder`                                                           |
+| `status`                      | `label`, `placeholder`, `activeLabel`, `inactiveLabel`                           |
+| `dataScope`                   | `label`, `placeholder`, `ownLabel`, `hierarchyLabel`, `allLabel`                 |
+| `permissionMatrix`            | `label`, `placeholder` — **label only** for schema field `permissionMatrixDraft` |
+
+> **Field name vs translation key:** schema field = `permissionMatrixDraft`; translation key = `permissionMatrix`. For `collections.roles.fields` overrides, use schema name `permissionMatrixDraft`.
+
+### `rolesPermissions`
+
+| Field                | Keys                   |
+| -------------------- | ---------------------- |
+| `role`, `permission` | `label`, `placeholder` |
+| `enabled`            | `label`, `placeholder` |
+
+### `users` (fields only)
+
+| Field          | Keys                   |
+| -------------- | ---------------------- |
+| `isSuperAdmin` | `label`                |
+| `roles`        | `label`, `placeholder` |
+| `parent`       | `label`, `placeholder` |
+
+No collection `labels` — the users collection belongs to your app.
+
+---
+
+## Permission matrix UI
+
+**Config path:** `translations.<locale>.components.rolePermissionMatrix`
+
+Registered as Payload i18n keys: `components:rolePermissionMatrix:…`
+
+| Key                            | Description                                                     |
+| ------------------------------ | --------------------------------------------------------------- |
+| `title`                        | Matrix heading                                                  |
+| `viewInUpdateScreenOnly.label` | Shown on create screen                                          |
+| `loading.placeholder`          | Loading state                                                   |
+| `featuresLabel`                | Features column header                                          |
+| `features.{code}`              | Label for main feature with matching `permission-features.code` |
+| `actionsLabel`                 | Actions column header                                           |
+| `actions.{code}`               | Label for main action with matching `permission-actions.code`   |
+
+### Features (dynamic)
+
+The matrix resolves feature row labels via:
+
+```
+components:rolePermissionMatrix:features:{featureCode}
+```
+
+`{featureCode}` must match **`permission-features.code` exactly** (case-sensitive).
+
+Add one key per feature code under `translations.<locale>.components.rolePermissionMatrix.features`:
+
+```ts
+payloadAuthRbacPlugin({
+  translations: {
+    en: {
+      components: {
+        rolePermissionMatrix: {
+          // ... others
+          featuresLabel: "Features",
+          features: {
+            label: "Features",
+            users: "Users", // permission-features.code = "users" (plugin default)
+            posts: "Posts", // permission-features.code = "posts"
+          },
+        },
+      },
+    },
+  },
+});
+```
+
+If a key is missing, the UI falls back to `feature.id` (not `feature.code`).
+
+### Main action labels (dynamic)
+
+Main actions (`type: "main"`) resolve checkbox labels via:
+
+```
+components:rolePermissionMatrix:actions:{actionCode}
+```
+
+`{actionCode}` must match **`permission-actions.code` exactly**.
+
+```ts
+payloadAuthRbacPlugin({
+  translations: {
+    en: {
+      components: {
+        rolePermissionMatrix: {
+          // ... others
+          actionsLabel: "Actions",
+          actions: {
+            create: "Create", // permission-actions.code = "create" (plugin default)
+            read: "Read",
+            update: "Update",
+            delete: "Delete",
+            publish: "Publish", // permission-actions.code = "publish" (custom)
+          },
+        },
+      },
+    },
+  },
+});
+```
+
+If a key is missing, the UI falls back to `action.id` (not `action.code`).
+
+### Sub-action labels (limitation)
+
+Sub-actions (`type: "sub"`) **do not** use `useTranslation` — the UI shows raw `permission-actions.code`.
+
+**Workaround:** use readable codes when creating sub-actions (`approveDraft`, not `ad`).
+
+---
+
+## Examples
+
+### Partial English override
+
+```ts
+payloadAuthRbacPlugin({
+  translations: {
+    en: {
+      collections: {
+        permissionActions: {
+          admin: { group: "Access Control" },
+          fields: {
+            code: {
+              label: "Action Code",
+              placeholder: "e.g. create, read, update, delete",
+            },
+          },
+        },
+        roles: {
+          fields: {
+            permissionMatrix: { label: "Permission Matrix" },
+          },
+        },
+      },
+      components: {
+        rolePermissionMatrix: {
+          title: "Permission Matrix",
+        },
+      },
+    },
+  },
+});
+```
+
+### Bilingual (`en` + `vi`)
+
+```ts
+import { en } from "@payloadcms/translations/languages/en";
+import { vi } from "@payloadcms/translations/languages/vi";
+
+export default buildConfig({
+  i18n: {
+    supportedLanguages: { en, vi },
+    fallbackLanguage: "en",
+  },
+  plugins: [
+    payloadAuthRbacPlugin({
+      translations: {
+        en: {
+          collections: {
+            roles: { labels: { singular: "Role", plural: "Roles" } },
+          },
+        },
+        vi: {
+          collections: {
+            permissionActions: {
+              labels: { singular: "Quyền thao tác", plural: "Quyền thao tác" },
+              admin: { group: "Hệ thống" },
+              fields: {
+                code: { label: "Mã quyền thao tác" },
+                status: {
+                  activeLabel: "Hoạt động",
+                  inactiveLabel: "Ngừng hoạt động",
+                },
+              },
+            },
+            roles: {
+              labels: { singular: "Vai trò", plural: "Vai trò" },
+              fields: {
+                permissionMatrix: { label: "Ma trận quyền" },
+                dataScope: {
+                  ownLabel: "Của mình",
+                  hierarchyLabel: "Phân cấp",
+                  allLabel: "Tất cả",
+                },
+              },
+            },
+            users: {
+              fields: {
+                isSuperAdmin: { label: "Siêu quản trị" },
+                roles: { label: "Vai trò" },
+                parent: { label: "Quản lý trực tiếp" },
+              },
+            },
+          },
+          components: {
+            rolePermissionMatrix: {
+              title: "Ma trận quyền",
+              loading: { placeholder: "Đang tải..." },
+              featuresLabel: "Tính năng",
+              features: {
+                // Mã tính năng của permission-features
+              },
+              actionsLabel: "Hành động",
+              actions: {
+                create: "Tạo",
+                read: "Xem",
+                update: "Sửa",
+                delete: "Xóa",
+                // Mã hành đông của permission-features
+              },
+            },
+          },
+        },
+      },
+    }),
+  ],
+});
+```
+
+Working demo: `dev/rbac.ts`.
+
+---
+
+## TypeScript
+
+```ts
+import type { RBACTranslations } from "@zealamic/payload-auth-rbac-plugin/types";
+
+// Per-collection types (value for one locale):
+import type { RolesCollectionTranslations } from "@zealamic/payload-auth-rbac-plugin/types";
+import type { RolePermissionMatrixClientTranslations } from "@zealamic/payload-auth-rbac-plugin/types";
+```
+
+---
+
+## Default English strings
+
+Shipped defaults (override via `translations.en`):
+
+| Source file                                                    | Content               |
+| -------------------------------------------------------------- | --------------------- |
+| `src/collections/permission-actions/default-data.ts`           | Permission actions    |
+| `src/collections/permission-features/default-data.ts`          | Permission features   |
+| `src/collections/permissions/default-data.ts`                  | Permissions           |
+| `src/collections/roles/default-data.ts`                        | Roles + dataScope     |
+| `src/collections/roles-permissions/default-data.ts`            | Role permissions join |
+| `src/collections/users/default-data.ts`                        | User fields           |
+| `src/components/role-permission-matrix-client/default-data.ts` | Matrix UI             |
+
+---
+
+## Quick reference
+
+| Goal                     | Path                                                                        |
+| ------------------------ | --------------------------------------------------------------------------- |
+| Sidebar group            | `translations.<locale>.collections.<key>.admin.group`                       |
+| Collection name          | `…labels.singular` / `…labels.plural`                                       |
+| Field label              | `…fields.<fieldName>.label`                                                 |
+| Select option            | `…fields.<fieldName>.<value>Label`                                          |
+| Matrix title             | `…components.rolePermissionMatrix.title`                                    |
+| Matrix action column     | `…components.rolePermissionMatrix.actions.<code>`                           |
+| Override field in schema | Use **schema field name** (`permissionMatrixDraft`, not `permissionMatrix`) |
+
+---
+
+## Related docs
+
+- [README](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/README.md) — install and quick start
+- [COLLECTIONS](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/COLLECTIONS.md) — collection schemas and customization
+- [UTILS](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/UTILS.md) — access helpers

package/docs/UTILS.md

@@ -0,0 +1,226 @@
+# Utils reference
+
+This document lists only utilities that are currently exported.
+
+Export sources:
+
+- `@zealamic/payload-auth-rbac-plugin`
+- `@zealamic/payload-auth-rbac-plugin/utils`
+
+> Barrel file: `src/lib/utils/index.ts`
+
+---
+
+## Exported modules
+
+`src/lib/utils/index.ts` exports from:
+
+1. `access`
+2. `data`
+3. `fields`
+4. `localization`
+
+---
+
+## Access exports
+
+### `type DataScopeOptions`
+
+```ts
+type DataScopeOptions = {
+  createdByField?: string; // default: "createdBy"
+  usersCollectionSlug?: string; // default: "users"
+};
+```
+
+Use this to configure ownership field and users slug for hierarchy logic.
+
+### `getPermissionAccess({ featureCode, actionCode, mode?, collectionSlug?, options? })`
+
+Unified access helper for Payload `access` config.
+
+You can use one function for all common access cases:
+
+- permission-only (`create`, `readVersions`, `unlock`, ...)
+- read with data-scope filter
+- modify (`update` / `delete`) with per-document scope check
+
+Parameters:
+
+- `featureCode` (`string`): feature code in `permission-features.code`
+- `actionCode` (`string`): action code in `permission-actions.code`
+- `mode` (`"none" | "modify"`, optional):
+  - `"none"` (default) = permission check only
+  - `"modify"` = check one target document by `id`
+- `collectionSlug` (`string`, optional): required when `mode: "modify"`
+- `options` (`DataScopeOptions`, optional): data-scope config
+
+What it returns:
+
+- In permission-only mode: Payload access function returning `boolean`
+- In read-scope mode (`options` provided): Payload access function returning `boolean | Where`
+- In modify mode: Payload access function returning `boolean`
+
+```ts
+// 1) permission-only (best for create/readVersions/unlock/etc.)
+create: getPermissionAccess({
+  featureCode: "posts",
+  actionCode: "create",
+});
+
+// 2) read + scope (read mode inferred when options exists)
+read: getPermissionAccess({
+  featureCode: "posts",
+  actionCode: "read",
+  options: {
+    createdByField: "createdBy",
+    usersCollectionSlug: "users",
+  },
+});
+
+// 3) update/delete + document scope (requires mode + collectionSlug)
+update: getPermissionAccess({
+  featureCode: "posts",
+  actionCode: "update",
+  mode: "modify",
+  collectionSlug: "posts",
+  options: { createdByField: "createdBy" },
+});
+```
+
+How it works internally:
+
+1. deny when `req.user` is missing
+2. allow immediately for super admin
+3. check RBAC by `featureCode` + `actionCode`
+4. if read-scope mode: return scope filter (`true` or `Where`)
+5. if modify mode: load target document by `id`, then enforce data scope
+
+When to use each mode:
+
+- **Permission-only**: operations that do not depend on document ownership/hierarchy  
+  Example: `create`, `readVersions`, `unlock`
+- **Read-scope**: list/read access that must be filtered by owner/hierarchy/all
+- **Modify**: `update` and `delete` where permission depends on the specific document
+
+Common mistakes to avoid:
+
+- `mode: "modify"` without `collectionSlug` -> always denied
+- expecting read-scope behavior without passing `options`
+- `featureCode` / `actionCode` not matching values in your permission collections
+
+### `getSuperAdminAccess`
+
+Allow only super admins.
+
+### `getAuthenticatedOrSuperAdminAccess`
+
+Allow current document owner or super admin.
+
+### `resolveEffectiveDataScope(req, options?)`
+
+Resolve effective scope from roles: `own | hierarchy | all`.
+Widest scope wins: `all > hierarchy > own`.
+
+### `getHierarchyVisibleUserIds(req, options?)`
+
+Return visible user IDs in hierarchy scope (self + descendants).
+
+### `getDataScopeReadWhere(req, options?)`
+
+Build data-scope read filter as `Where | true`.
+
+### `isProtectedSuperAdminUserDoc(doc)`
+
+Guard helper for user docs with `isSuperAdmin: true`.
+
+### `canAccessDocumentByDataScope({ req, doc, featureCode, actionCode, collectionSlug, options? })`
+
+Low-level per-document RBAC + data-scope check.
+
+### `mergeDataScopeWhere(base, scopeWhere)`
+
+Merge existing `where` with scope constraints.
+
+```ts
+const scopeWhere = await getDataScopeReadWhere(req, {
+  createdByField: "createdBy",
+});
+const where = mergeDataScopeWhere(
+  { status: { equals: "published" } },
+  scopeWhere,
+);
+```
+
+---
+
+## Data exports
+
+### `toID(value)`
+
+Normalize relationship/id values to string id.
+
+```ts
+toID("507f1f77bcf86cd799439011"); // "507f1f77bcf86cd799439011"
+toID({ id: "507f1f77bcf86cd799439011" }); // "507f1f77bcf86cd799439011"
+toID(undefined); // ""
+```
+
+---
+
+## Fields exports
+
+### `getMergedFieldAffectingData({ fields, defaultField })`
+
+Merge one plugin default field with a user override by matching field name.
+
+### `getArrayOfMergedFieldAffectingData({ fields, defaultFields })`
+
+Build final fields list:
+
+- merge defaults by matching names
+- append unmatched custom fields
+
+---
+
+## Localization exports
+
+### `toLocaleRecord(locales, getValue)`
+
+Build `{ [locale]: string }` records from locale list.
+
+### `toSelectPlaceholder(locales, getValue)`
+
+Build serializable select placeholders (safe across Payload v3 server/client boundary).
+
+### `getMergedTranslations({ defaultTranslations, translations })`
+
+Deep-merge translation objects.
+
+### `getAllTranslationsOfSpecificObject({ translations, path, locales? })`
+
+Extract nested translation branch by path (example: `"collections.roles"`).
+
+---
+
+## Commonly paired constant export
+
+Not from `lib/utils`, but often used with access helpers:
+
+```ts
+import { CONSTANTS } from "@zealamic/payload-auth-rbac-plugin";
+
+CONSTANTS.ROLE.DATA_SCOPE;
+CONSTANTS.ROLE.STATUS;
+CONSTANTS.PERMISSION.STATUS;
+CONSTANTS.PERMISSION_ACTION.TYPE;
+CONSTANTS.USER.PARENT_PATH_SEPARATOR;
+```
+
+---
+
+## Related docs
+
+- [README](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/README.md) — install and quick start
+- [COLLECTIONS](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/COLLECTIONS.md) — collection schemas and customization
+- [TRANSLATIONS](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/TRANSLATIONS.md) — i18n keys