@webiny/app-admin 0.0.0-unstable.eb196ccd2f → 0.0.0-unstable.f6dc066313

package/permissions/PermissionValueContext.js

@@ -0,0 +1,23 @@
+import React, { useContext } from "react";
+const PermissionValueContext = /*#__PURE__*/React.createContext(null);
+export const PermissionValueProvider = ({
+  value,
+  onChange,
+  children
+}) => {
+  return /*#__PURE__*/React.createElement(PermissionValueContext.Provider, {
+    value: {
+      value,
+      onChange
+    }
+  }, children);
+};
+export function usePermissionValue() {
+  const ctx = useContext(PermissionValueContext);
+  if (!ctx) {
+    throw new Error("usePermissionValue must be used within a PermissionValueProvider");
+  }
+  return ctx;
+}
+
+//# sourceMappingURL=PermissionValueContext.js.map

package/permissions/PermissionValueContext.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["React","useContext","PermissionValueContext","createContext","PermissionValueProvider","value","onChange","children","createElement","Provider","usePermissionValue","ctx","Error"],"sources":["PermissionValueContext.tsx"],"sourcesContent":["import React, { useContext } from \"react\";\nimport type { Permission } from \"./types.js\";\n\ninterface PermissionValueContextValue {\n    value: Permission[];\n    onChange: (value: Permission[]) => void;\n}\n\nconst PermissionValueContext = React.createContext<PermissionValueContextValue | null>(null);\n\nexport const PermissionValueProvider = ({\n    value,\n    onChange,\n    children\n}: PermissionValueContextValue & { children: React.ReactNode }) => {\n    return (\n        <PermissionValueContext.Provider value={{ value, onChange }}>\n            {children}\n        </PermissionValueContext.Provider>\n    );\n};\n\nexport function usePermissionValue(): PermissionValueContextValue {\n    const ctx = useContext(PermissionValueContext);\n    if (!ctx) {\n        throw new Error(\"usePermissionValue must be used within a PermissionValueProvider\");\n    }\n    return ctx;\n}\n"],"mappings":"AAAA,OAAOA,KAAK,IAAIC,UAAU,QAAQ,OAAO;AAQzC,MAAMC,sBAAsB,gBAAGF,KAAK,CAACG,aAAa,CAAqC,IAAI,CAAC;AAE5F,OAAO,MAAMC,uBAAuB,GAAGA,CAAC;EACpCC,KAAK;EACLC,QAAQ;EACRC;AACyD,CAAC,KAAK;EAC/D,oBACIP,KAAA,CAAAQ,aAAA,CAACN,sBAAsB,CAACO,QAAQ;IAACJ,KAAK,EAAE;MAAEA,KAAK;MAAEC;IAAS;EAAE,GACvDC,QAC4B,CAAC;AAE1C,CAAC;AAED,OAAO,SAASG,kBAAkBA,CAAA,EAAgC;EAC9D,MAAMC,GAAG,GAAGV,UAAU,CAACC,sBAAsB,CAAC;EAC9C,IAAI,CAACS,GAAG,EAAE;IACN,MAAM,IAAIC,KAAK,CAAC,kEAAkE,CAAC;EACvF;EACA,OAAOD,GAAG;AACd","ignoreList":[]}

package/permissions/createHasPermission.d.ts

@@ -0,0 +1,3 @@
+import React from "react";
+import type { PermissionSchemaConfig, HasPermissionProps } from "./types.js";
+export declare function createHasPermission<const S extends PermissionSchemaConfig>(schema: S): React.FC<HasPermissionProps<S>>;

package/permissions/createHasPermission.js

@@ -0,0 +1,36 @@
+import React from "react";
+import { createUsePermissions } from "./usePermissions.js";
+const BUILT_IN_ACTIONS = {
+  read: "canRead",
+  create: "canCreate",
+  edit: "canEdit",
+  delete: "canDelete",
+  publish: "canPublish",
+  unpublish: "canUnpublish"
+};
+export function createHasPermission(schema) {
+  const usePermissions = createUsePermissions(schema);
+  return function HasPermission({
+    children,
+    ...props
+  }) {
+    const permissions = usePermissions();
+    const action = props.action;
+    const entities = props.entity ? [props.entity] : props.any ?? props.all ?? [];
+    const requireAll = !!props.all;
+    const check = entityId => {
+      if (!action) {
+        return permissions.canAccess(entityId);
+      }
+      const method = BUILT_IN_ACTIONS[action];
+      if (method) {
+        return permissions[method](entityId);
+      }
+      return permissions.canAction(action, entityId);
+    };
+    const allowed = requireAll ? entities.every(check) : entities.some(check);
+    return allowed ? /*#__PURE__*/React.createElement(React.Fragment, null, children) : null;
+  };
+}
+
+//# sourceMappingURL=createHasPermission.js.map

package/permissions/createHasPermission.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["React","createUsePermissions","BUILT_IN_ACTIONS","read","create","edit","delete","publish","unpublish","createHasPermission","schema","usePermissions","HasPermission","children","props","permissions","action","entities","entity","any","all","requireAll","check","entityId","canAccess","method","canAction","allowed","every","some","createElement","Fragment"],"sources":["createHasPermission.tsx"],"sourcesContent":["import React from \"react\";\nimport { createUsePermissions } from \"./usePermissions.js\";\nimport type { PermissionSchemaConfig, HasPermissionProps } from \"./types.js\";\n\nconst BUILT_IN_ACTIONS: Record<string, string> = {\n    read: \"canRead\",\n    create: \"canCreate\",\n    edit: \"canEdit\",\n    delete: \"canDelete\",\n    publish: \"canPublish\",\n    unpublish: \"canUnpublish\"\n};\n\nexport function createHasPermission<const S extends PermissionSchemaConfig>(\n    schema: S\n): React.FC<HasPermissionProps<S>> {\n    const usePermissions = createUsePermissions(schema);\n\n    return function HasPermission({ children, ...props }) {\n        const permissions = usePermissions();\n\n        const action = props.action as string | undefined;\n        const entities: string[] = props.entity ? [props.entity] : (props.any ?? props.all ?? []);\n        const requireAll = !!props.all;\n\n        const check = (entityId: string): boolean => {\n            if (!action) {\n                return permissions.canAccess(entityId as any);\n            }\n            const method = BUILT_IN_ACTIONS[action];\n            if (method) {\n                return (permissions as any)[method](entityId);\n            }\n            return permissions.canAction(action as any, entityId as any);\n        };\n\n        const allowed = requireAll ? entities.every(check) : entities.some(check);\n\n        return allowed ? <>{children}</> : null;\n    };\n}\n"],"mappings":"AAAA,OAAOA,KAAK,MAAM,OAAO;AACzB,SAASC,oBAAoB;AAG7B,MAAMC,gBAAwC,GAAG;EAC7CC,IAAI,EAAE,SAAS;EACfC,MAAM,EAAE,WAAW;EACnBC,IAAI,EAAE,SAAS;EACfC,MAAM,EAAE,WAAW;EACnBC,OAAO,EAAE,YAAY;EACrBC,SAAS,EAAE;AACf,CAAC;AAED,OAAO,SAASC,mBAAmBA,CAC/BC,MAAS,EACsB;EAC/B,MAAMC,cAAc,GAAGV,oBAAoB,CAACS,MAAM,CAAC;EAEnD,OAAO,SAASE,aAAaA,CAAC;IAAEC,QAAQ;IAAE,GAAGC;EAAM,CAAC,EAAE;IAClD,MAAMC,WAAW,GAAGJ,cAAc,CAAC,CAAC;IAEpC,MAAMK,MAAM,GAAGF,KAAK,CAACE,MAA4B;IACjD,MAAMC,QAAkB,GAAGH,KAAK,CAACI,MAAM,GAAG,CAACJ,KAAK,CAACI,MAAM,CAAC,GAAIJ,KAAK,CAACK,GAAG,IAAIL,KAAK,CAACM,GAAG,IAAI,EAAG;IACzF,MAAMC,UAAU,GAAG,CAAC,CAACP,KAAK,CAACM,GAAG;IAE9B,MAAME,KAAK,GAAIC,QAAgB,IAAc;MACzC,IAAI,CAACP,MAAM,EAAE;QACT,OAAOD,WAAW,CAACS,SAAS,CAACD,QAAe,CAAC;MACjD;MACA,MAAME,MAAM,GAAGvB,gBAAgB,CAACc,MAAM,CAAC;MACvC,IAAIS,MAAM,EAAE;QACR,OAAQV,WAAW,CAASU,MAAM,CAAC,CAACF,QAAQ,CAAC;MACjD;MACA,OAAOR,WAAW,CAACW,SAAS,CAACV,MAAM,EAASO,QAAe,CAAC;IAChE,CAAC;IAED,MAAMI,OAAO,GAAGN,UAAU,GAAGJ,QAAQ,CAACW,KAAK,CAACN,KAAK,CAAC,GAAGL,QAAQ,CAACY,IAAI,CAACP,KAAK,CAAC;IAEzE,OAAOK,OAAO,gBAAG3B,KAAA,CAAA8B,aAAA,CAAA9B,KAAA,CAAA+B,QAAA,QAAGlB,QAAW,CAAC,GAAG,IAAI;EAC3C,CAAC;AACL","ignoreList":[]}

package/permissions/createPermissionSchema.d.ts

@@ -0,0 +1,2 @@
+import type { PermissionSchemaConfig } from "./types.js";
+export declare function createPermissionSchema<const T extends PermissionSchemaConfig>(config: T): T;

package/permissions/createPermissionSchema.js

@@ -0,0 +1,8 @@
+export function createPermissionSchema(config) {
+  return {
+    ...config,
+    entities: config.entities ?? []
+  };
+}
+
+//# sourceMappingURL=createPermissionSchema.js.map

package/permissions/createPermissionSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createPermissionSchema","config","entities"],"sources":["createPermissionSchema.ts"],"sourcesContent":["import type { PermissionSchemaConfig } from \"./types.js\";\n\nexport function createPermissionSchema<const T extends PermissionSchemaConfig>(config: T): T {\n    return {\n        ...config,\n        entities: config.entities ?? []\n    };\n}\n"],"mappings":"AAEA,OAAO,SAASA,sBAAsBA,CAAyCC,MAAS,EAAK;EACzF,OAAO;IACH,GAAGA,MAAM;IACTC,QAAQ,EAAED,MAAM,CAACC,QAAQ,IAAI;EACjC,CAAC;AACL","ignoreList":[]}

package/permissions/index.d.ts

@@ -0,0 +1,8 @@
+export { createPermissionSchema } from "./createPermissionSchema.js";
+export { createUsePermissions } from "./usePermissions.js";
+export { usePermissionForm, deserializePermissions, serializePermissions } from "./usePermissionForm.js";
+export { PermissionRenderer } from "./PermissionRenderer.js";
+export type { PermissionRendererProps } from "./PermissionRenderer.js";
+export { usePermissionValue, PermissionValueProvider } from "./PermissionValueContext.js";
+export { createHasPermission } from "./createHasPermission.js";
+export type { Permission, ActionDefinition, EntityDefinition, OwnableItem, PermissionSchemaConfig, PermissionSchema, UsePermissionFormOptions, UsePermissionFormResult, UsePermissionsResult, PermissionRendererConfig, HasPermissionAction, HasPermissionProps } from "./types.js";

package/permissions/index.js

@@ -0,0 +1,8 @@
+export { createPermissionSchema } from "./createPermissionSchema.js";
+export { createUsePermissions } from "./usePermissions.js";
+export { usePermissionForm, deserializePermissions, serializePermissions } from "./usePermissionForm.js";
+export { PermissionRenderer } from "./PermissionRenderer.js";
+export { usePermissionValue, PermissionValueProvider } from "./PermissionValueContext.js";
+export { createHasPermission } from "./createHasPermission.js";
+
+//# sourceMappingURL=index.js.map

package/permissions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createPermissionSchema","createUsePermissions","usePermissionForm","deserializePermissions","serializePermissions","PermissionRenderer","usePermissionValue","PermissionValueProvider","createHasPermission"],"sources":["index.ts"],"sourcesContent":["export { createPermissionSchema } from \"./createPermissionSchema.js\";\nexport { createUsePermissions } from \"./usePermissions.js\";\nexport {\n    usePermissionForm,\n    deserializePermissions,\n    serializePermissions\n} from \"./usePermissionForm.js\";\nexport { PermissionRenderer } from \"./PermissionRenderer.js\";\nexport type { PermissionRendererProps } from \"./PermissionRenderer.js\";\nexport { usePermissionValue, PermissionValueProvider } from \"./PermissionValueContext.js\";\nexport { createHasPermission } from \"./createHasPermission.js\";\nexport type {\n    Permission,\n    ActionDefinition,\n    EntityDefinition,\n    OwnableItem,\n    PermissionSchemaConfig,\n    PermissionSchema,\n    UsePermissionFormOptions,\n    UsePermissionFormResult,\n    UsePermissionsResult,\n    PermissionRendererConfig,\n    HasPermissionAction,\n    HasPermissionProps\n} from \"./types.js\";\n"],"mappings":"AAAA,SAASA,sBAAsB;AAC/B,SAASC,oBAAoB;AAC7B,SACIC,iBAAiB,EACjBC,sBAAsB,EACtBC,oBAAoB;AAExB,SAASC,kBAAkB;AAE3B,SAASC,kBAAkB,EAAEC,uBAAuB;AACpD,SAASC,mBAAmB","ignoreList":[]}

package/permissions/types.d.ts

@@ -0,0 +1,242 @@
+import type React from "react";
+/**
+ * A single permission object from the API.
+ */
+export interface Permission {
+    name: string;
+    [key: string]: any;
+}
+/**
+ * An action definition on an entity.
+ *
+ * Built-in actions:
+ * - `{ name: "rwd" }` — read/write/delete single-select (serialized as joined string, e.g. "rw")
+ * - `{ name: "pw" }` — publish/unpublish multi-select (serialized as joined string, e.g. "pu")
+ *
+ * Custom actions:
+ * - `{ name: "install", label: "Install" }` — boolean flag (serialized as `install: true`)
+ */
+export interface ActionDefinition {
+    /** Key on the permission object (e.g. "rwd", "pw", "install") */
+    name: string;
+    /** Display label for the UI. Required for custom actions; ignored for built-in "rwd"/"pw". */
+    label?: string;
+}
+/**
+ * Defines an entity within a permission schema.
+ */
+export interface EntityDefinition {
+    /** Unique ID, used for form field naming: ${id}AccessScope, ${id}RWD, etc. */
+    id: string;
+    /** Display title for the UI renderer (e.g. "Files", "Settings") */
+    title?: string;
+    /** Permission name emitted for this entity (e.g. "fm.file") */
+    permission: string;
+    /** Available access scopes */
+    scopes: ("full" | "own")[];
+    /** Action definitions for this entity */
+    actions?: ActionDefinition[];
+    /** Dependency on another entity */
+    dependsOn?: {
+        /** ID of parent entity */
+        entity: string;
+        /** Required action character (e.g. "r") */
+        requires: string;
+    };
+}
+/**
+ * Configuration for creating a permission schema.
+ */
+export interface PermissionSchemaConfig {
+    /** Permission prefix — used to filter permissions from the array */
+    prefix: string;
+    /**
+     * Full access configuration.
+     * - `true` — emits `{ name: "${prefix}.*" }`.
+     * - `{ ...extras }` — emits `{ name: "${prefix}.*", ...extras }`.
+     */
+    fullAccess: boolean | {
+        [key: string]: any;
+    };
+    /**
+     * Read-only access configuration. When defined, the schema supports a read-only tier.
+     * - `true` — emits `{ name: "${prefix}.*", rwd: "r" }`.
+     * - `Permission[]` — emits the array as-is.
+     */
+    readOnlyAccess?: boolean | Permission[];
+    /** Entity definitions (optional — simple apps have none) */
+    entities?: EntityDefinition[];
+}
+/**
+ * A compiled permission schema returned by `createPermissionSchema`.
+ */
+export interface PermissionSchema {
+    prefix: string;
+    /**
+     * Full access configuration.
+     * - `true` — emits `{ name: "${prefix}.*" }`.
+     * - `{ ...extras }` — emits `{ name: "${prefix}.*", ...extras }`.
+     */
+    fullAccess: boolean | {
+        [key: string]: any;
+    };
+    /**
+     * Read-only access configuration. When defined, the schema supports a read-only tier.
+     * - `true` — emits `{ name: "${prefix}.*", rwd: "r" }`.
+     * - `Permission[]` — emits the array as-is.
+     */
+    readOnlyAccess?: boolean | Permission[];
+    entities?: EntityDefinition[];
+}
+/**
+ * Options passed to the `usePermissionForm` hook.
+ */
+export interface UsePermissionFormOptions {
+    value: Permission[];
+    onChange: (value: Permission[]) => void;
+    /** Merge extra fields into deserialized form data (for CMS endpoints, resource scopes, etc.) */
+    deserialize?: (permissions: Permission[]) => Record<string, any>;
+    /** Transform or extend the core-serialized permissions (for CMS endpoints, resource scopes, etc.) */
+    serialize?: (formData: Record<string, any>, corePermissions: Permission[]) => Permission[];
+}
+/**
+ * Return value of `usePermissionForm`.
+ */
+export interface UsePermissionFormResult {
+    formData: Record<string, any>;
+    onFormChange: (data: Record<string, any>) => void;
+}
+/**
+ * Configuration for a permission renderer registered via AdminConfig.
+ *
+ * Either `schema` or `element` must be provided:
+ * - `schema`: uses the built-in PermissionRenderer for auto-generated UI.
+ * - `element`: uses a custom React element for full control.
+ */
+export type PermissionRendererConfig = PermissionRendererConfigBase & ({
+    schema: PermissionSchema;
+    element?: never;
+} | {
+    schema?: never;
+    element: React.ReactElement;
+});
+interface PermissionRendererConfigBase {
+    name: string;
+    title: string;
+    description?: string;
+    icon?: React.ReactElement;
+    system?: boolean;
+}
+/**
+ * Item that may have an owner (used for own-scope permission checks).
+ */
+export interface OwnableItem {
+    createdBy?: {
+        id: string;
+    } | null;
+}
+/**
+ * Extract the union of entity definitions from a schema config type.
+ */
+type EntitiesOf<S extends PermissionSchemaConfig> = S extends {
+    entities: ReadonlyArray<infer E extends EntityDefinition>;
+} ? E : never;
+/**
+ * Extract entity IDs whose actions array contains an action with the given name.
+ */
+type EntityIdWithAction<S extends PermissionSchemaConfig, A extends string> = {
+    [K in EntitiesOf<S> as K extends {
+        actions: ReadonlyArray<infer Act>;
+    } ? Act extends {
+        name: A;
+    } ? K["id"] : never : never]: never;
+} extends infer M ? keyof M & string : never;
+/**
+ * Entity IDs that have the "rwd" action.
+ */
+export type RwdEntityId<S extends PermissionSchemaConfig> = EntityIdWithAction<S, "rwd">;
+/**
+ * Entity IDs that have the "pw" action.
+ */
+export type PwEntityId<S extends PermissionSchemaConfig> = EntityIdWithAction<S, "pw">;
+/**
+ * All entity IDs in the schema.
+ */
+export type AllEntityIds<S extends PermissionSchemaConfig> = EntitiesOf<S>["id"];
+/**
+ * Custom (non-builtin) action names across all entities.
+ */
+export type CustomActionNames<S extends PermissionSchemaConfig> = Exclude<EntitiesOf<S> extends {
+    actions: ReadonlyArray<infer Act extends ActionDefinition>;
+} ? Act["name"] : never, "rwd" | "pw">;
+/**
+ * The return type of `usePermissions(schema)`.
+ *
+ * When the schema has literal entity types, methods are narrowed to only accept valid entity IDs.
+ * When the schema is dynamically typed, all methods accept `string`.
+ */
+export type UsePermissionsResult<S extends PermissionSchemaConfig> = string extends AllEntityIds<S> ? UsePermissionsResultUntyped : UsePermissionsResultTyped<S>;
+export interface UsePermissionsResultUntyped {
+    canAccess: (entityId: string) => boolean;
+    canRead: (entityId: string) => boolean;
+    canCreate: (entityId: string) => boolean;
+    canEdit: (entityId: string, item?: OwnableItem) => boolean;
+    canDelete: (entityId: string, item?: OwnableItem) => boolean;
+    canPublish: (entityId: string) => boolean;
+    canUnpublish: (entityId: string) => boolean;
+    canAction: (action: string, entityId: string) => boolean;
+}
+/**
+ * Action values accepted by `HasPermission`.
+ *
+ * Built-in actions are always available; custom action names from the schema are inferred automatically.
+ */
+export type HasPermissionAction<S extends PermissionSchemaConfig> = "read" | "create" | "edit" | "delete" | "publish" | "unpublish" | CustomActionNames<S>;
+/**
+ * Props for a schema-bound `HasPermission` component created via `createHasPermission`.
+ *
+ * Exactly one of `entity`, `any`, or `all` must be provided.
+ */
+export type HasPermissionProps<S extends PermissionSchemaConfig> = SingleEntityProps<S> | AnyEntitiesProps<S> | AllEntitiesProps<S>;
+interface SingleEntityProps<S extends PermissionSchemaConfig> {
+    entity: AllEntityIds<S>;
+    any?: never;
+    all?: never;
+    action?: HasPermissionAction<S>;
+    children: React.ReactNode;
+}
+interface AnyEntitiesProps<S extends PermissionSchemaConfig> {
+    entity?: never;
+    any: AllEntityIds<S>[];
+    all?: never;
+    action?: HasPermissionAction<S>;
+    children: React.ReactNode;
+}
+interface AllEntitiesProps<S extends PermissionSchemaConfig> {
+    entity?: never;
+    any?: never;
+    all: AllEntityIds<S>[];
+    action?: HasPermissionAction<S>;
+    children: React.ReactNode;
+}
+type UsePermissionsResultTyped<S extends PermissionSchemaConfig> = {
+    canAccess: (entityId: AllEntityIds<S>) => boolean;
+    canAction: (action: CustomActionNames<S> extends never ? string : CustomActionNames<S>, entityId: AllEntityIds<S>) => boolean;
+} & ([RwdEntityId<S>] extends [never] ? {
+    canRead: (entityId: string) => boolean;
+    canCreate: (entityId: string) => boolean;
+    canEdit: (entityId: string, item?: OwnableItem) => boolean;
+    canDelete: (entityId: string, item?: OwnableItem) => boolean;
+} : {
+    canRead: (entityId: RwdEntityId<S>) => boolean;
+    canCreate: (entityId: RwdEntityId<S>) => boolean;
+    canEdit: (entityId: RwdEntityId<S>, item?: OwnableItem) => boolean;
+    canDelete: (entityId: RwdEntityId<S>, item?: OwnableItem) => boolean;
+}) & ([PwEntityId<S>] extends [never] ? {
+    canPublish: (entityId: string) => boolean;
+    canUnpublish: (entityId: string) => boolean;
+} : {
+    canPublish: (entityId: PwEntityId<S>) => boolean;
+    canUnpublish: (entityId: PwEntityId<S>) => boolean;
+});
+export {};

package/permissions/types.js

@@ -0,0 +1,3 @@
+export {};
+
+//# sourceMappingURL=types.js.map

package/permissions/types.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sources":["types.ts"],"sourcesContent":["import type React from \"react\";\n\n/**\n * A single permission object from the API.\n */\nexport interface Permission {\n    name: string;\n    [key: string]: any;\n}\n\n/**\n * An action definition on an entity.\n *\n * Built-in actions:\n * - `{ name: \"rwd\" }` — read/write/delete single-select (serialized as joined string, e.g. \"rw\")\n * - `{ name: \"pw\" }` — publish/unpublish multi-select (serialized as joined string, e.g. \"pu\")\n *\n * Custom actions:\n * - `{ name: \"install\", label: \"Install\" }` — boolean flag (serialized as `install: true`)\n */\nexport interface ActionDefinition {\n    /** Key on the permission object (e.g. \"rwd\", \"pw\", \"install\") */\n    name: string;\n    /** Display label for the UI. Required for custom actions; ignored for built-in \"rwd\"/\"pw\". */\n    label?: string;\n}\n\n/**\n * Defines an entity within a permission schema.\n */\nexport interface EntityDefinition {\n    /** Unique ID, used for form field naming: ${id}AccessScope, ${id}RWD, etc. */\n    id: string;\n    /** Display title for the UI renderer (e.g. \"Files\", \"Settings\") */\n    title?: string;\n    /** Permission name emitted for this entity (e.g. \"fm.file\") */\n    permission: string;\n    /** Available access scopes */\n    scopes: (\"full\" | \"own\")[];\n    /** Action definitions for this entity */\n    actions?: ActionDefinition[];\n    /** Dependency on another entity */\n    dependsOn?: {\n        /** ID of parent entity */\n        entity: string;\n        /** Required action character (e.g. \"r\") */\n        requires: string;\n    };\n}\n\n/**\n * Configuration for creating a permission schema.\n */\nexport interface PermissionSchemaConfig {\n    /** Permission prefix — used to filter permissions from the array */\n    prefix: string;\n    /**\n     * Full access configuration.\n     * - `true` — emits `{ name: \"${prefix}.*\" }`.\n     * - `{ ...extras }` — emits `{ name: \"${prefix}.*\", ...extras }`.\n     */\n    fullAccess: boolean | { [key: string]: any };\n    /**\n     * Read-only access configuration. When defined, the schema supports a read-only tier.\n     * - `true` — emits `{ name: \"${prefix}.*\", rwd: \"r\" }`.\n     * - `Permission[]` — emits the array as-is.\n     */\n    readOnlyAccess?: boolean | Permission[];\n    /** Entity definitions (optional — simple apps have none) */\n    entities?: EntityDefinition[];\n}\n\n/**\n * A compiled permission schema returned by `createPermissionSchema`.\n */\nexport interface PermissionSchema {\n    prefix: string;\n    /**\n     * Full access configuration.\n     * - `true` — emits `{ name: \"${prefix}.*\" }`.\n     * - `{ ...extras }` — emits `{ name: \"${prefix}.*\", ...extras }`.\n     */\n    fullAccess: boolean | { [key: string]: any };\n    /**\n     * Read-only access configuration. When defined, the schema supports a read-only tier.\n     * - `true` — emits `{ name: \"${prefix}.*\", rwd: \"r\" }`.\n     * - `Permission[]` — emits the array as-is.\n     */\n    readOnlyAccess?: boolean | Permission[];\n    entities?: EntityDefinition[];\n}\n\n/**\n * Options passed to the `usePermissionForm` hook.\n */\nexport interface UsePermissionFormOptions {\n    value: Permission[];\n    onChange: (value: Permission[]) => void;\n    /** Merge extra fields into deserialized form data (for CMS endpoints, resource scopes, etc.) */\n    deserialize?: (permissions: Permission[]) => Record<string, any>;\n    /** Transform or extend the core-serialized permissions (for CMS endpoints, resource scopes, etc.) */\n    serialize?: (formData: Record<string, any>, corePermissions: Permission[]) => Permission[];\n}\n\n/**\n * Return value of `usePermissionForm`.\n */\nexport interface UsePermissionFormResult {\n    formData: Record<string, any>;\n    onFormChange: (data: Record<string, any>) => void;\n}\n\n/**\n * Configuration for a permission renderer registered via AdminConfig.\n *\n * Either `schema` or `element` must be provided:\n * - `schema`: uses the built-in PermissionRenderer for auto-generated UI.\n * - `element`: uses a custom React element for full control.\n */\nexport type PermissionRendererConfig = PermissionRendererConfigBase &\n    (\n        | { schema: PermissionSchema; element?: never }\n        | { schema?: never; element: React.ReactElement }\n    );\n\ninterface PermissionRendererConfigBase {\n    name: string;\n    title: string;\n    description?: string;\n    icon?: React.ReactElement;\n    system?: boolean;\n}\n\n/**\n * Item that may have an owner (used for own-scope permission checks).\n */\nexport interface OwnableItem {\n    createdBy?: { id: string } | null;\n}\n\n/**\n * Extract the union of entity definitions from a schema config type.\n */\ntype EntitiesOf<S extends PermissionSchemaConfig> = S extends {\n    entities: ReadonlyArray<infer E extends EntityDefinition>;\n}\n    ? E\n    : never;\n\n/**\n * Extract entity IDs whose actions array contains an action with the given name.\n */\ntype EntityIdWithAction<S extends PermissionSchemaConfig, A extends string> = {\n    [K in EntitiesOf<S> as K extends { actions: ReadonlyArray<infer Act> }\n        ? Act extends { name: A }\n            ? K[\"id\"]\n            : never\n        : never]: never;\n} extends infer M\n    ? keyof M & string\n    : never;\n\n/**\n * Entity IDs that have the \"rwd\" action.\n */\nexport type RwdEntityId<S extends PermissionSchemaConfig> = EntityIdWithAction<S, \"rwd\">;\n\n/**\n * Entity IDs that have the \"pw\" action.\n */\nexport type PwEntityId<S extends PermissionSchemaConfig> = EntityIdWithAction<S, \"pw\">;\n\n/**\n * All entity IDs in the schema.\n */\nexport type AllEntityIds<S extends PermissionSchemaConfig> = EntitiesOf<S>[\"id\"];\n\n/**\n * Custom (non-builtin) action names across all entities.\n */\nexport type CustomActionNames<S extends PermissionSchemaConfig> = Exclude<\n    EntitiesOf<S> extends { actions: ReadonlyArray<infer Act extends ActionDefinition> }\n        ? Act[\"name\"]\n        : never,\n    \"rwd\" | \"pw\"\n>;\n\n/**\n * The return type of `usePermissions(schema)`.\n *\n * When the schema has literal entity types, methods are narrowed to only accept valid entity IDs.\n * When the schema is dynamically typed, all methods accept `string`.\n */\nexport type UsePermissionsResult<S extends PermissionSchemaConfig> =\n    string extends AllEntityIds<S> ? UsePermissionsResultUntyped : UsePermissionsResultTyped<S>;\n\nexport interface UsePermissionsResultUntyped {\n    canAccess: (entityId: string) => boolean;\n    canRead: (entityId: string) => boolean;\n    canCreate: (entityId: string) => boolean;\n    canEdit: (entityId: string, item?: OwnableItem) => boolean;\n    canDelete: (entityId: string, item?: OwnableItem) => boolean;\n    canPublish: (entityId: string) => boolean;\n    canUnpublish: (entityId: string) => boolean;\n    canAction: (action: string, entityId: string) => boolean;\n}\n\n/**\n * Action values accepted by `HasPermission`.\n *\n * Built-in actions are always available; custom action names from the schema are inferred automatically.\n */\nexport type HasPermissionAction<S extends PermissionSchemaConfig> =\n    | \"read\"\n    | \"create\"\n    | \"edit\"\n    | \"delete\"\n    | \"publish\"\n    | \"unpublish\"\n    | CustomActionNames<S>;\n\n/**\n * Props for a schema-bound `HasPermission` component created via `createHasPermission`.\n *\n * Exactly one of `entity`, `any`, or `all` must be provided.\n */\nexport type HasPermissionProps<S extends PermissionSchemaConfig> =\n    | SingleEntityProps<S>\n    | AnyEntitiesProps<S>\n    | AllEntitiesProps<S>;\n\ninterface SingleEntityProps<S extends PermissionSchemaConfig> {\n    entity: AllEntityIds<S>;\n    any?: never;\n    all?: never;\n    action?: HasPermissionAction<S>;\n    children: React.ReactNode;\n}\n\ninterface AnyEntitiesProps<S extends PermissionSchemaConfig> {\n    entity?: never;\n    any: AllEntityIds<S>[];\n    all?: never;\n    action?: HasPermissionAction<S>;\n    children: React.ReactNode;\n}\n\ninterface AllEntitiesProps<S extends PermissionSchemaConfig> {\n    entity?: never;\n    any?: never;\n    all: AllEntityIds<S>[];\n    action?: HasPermissionAction<S>;\n    children: React.ReactNode;\n}\n\ntype UsePermissionsResultTyped<S extends PermissionSchemaConfig> = {\n    canAccess: (entityId: AllEntityIds<S>) => boolean;\n    canAction: (\n        action: CustomActionNames<S> extends never ? string : CustomActionNames<S>,\n        entityId: AllEntityIds<S>\n    ) => boolean;\n} & ([RwdEntityId<S>] extends [never]\n    ? {\n          canRead: (entityId: string) => boolean;\n          canCreate: (entityId: string) => boolean;\n          canEdit: (entityId: string, item?: OwnableItem) => boolean;\n          canDelete: (entityId: string, item?: OwnableItem) => boolean;\n      }\n    : {\n          canRead: (entityId: RwdEntityId<S>) => boolean;\n          canCreate: (entityId: RwdEntityId<S>) => boolean;\n          canEdit: (entityId: RwdEntityId<S>, item?: OwnableItem) => boolean;\n          canDelete: (entityId: RwdEntityId<S>, item?: OwnableItem) => boolean;\n      }) &\n    ([PwEntityId<S>] extends [never]\n        ? {\n              canPublish: (entityId: string) => boolean;\n              canUnpublish: (entityId: string) => boolean;\n          }\n        : {\n              canPublish: (entityId: PwEntityId<S>) => boolean;\n              canUnpublish: (entityId: PwEntityId<S>) => boolean;\n          });\n"],"mappings":"","ignoreList":[]}

package/permissions/usePermissionForm.d.ts

@@ -0,0 +1,17 @@
+import type { Permission, PermissionSchema, UsePermissionFormOptions, UsePermissionFormResult } from "./types.js";
+/**
+ * Deserialize Permission[] into form data based on the schema.
+ */
+declare function deserializePermissions(schema: PermissionSchema, value: Permission[]): Record<string, any>;
+/**
+ * Serialize form data into Permission[] based on the schema.
+ */
+declare function serializePermissions(schema: PermissionSchema, formData: Record<string, any>, currentValue: Permission[]): Permission[];
+/**
+ * Hook that bridges a permission schema with a Form component.
+ *
+ * Handles bidirectional transformation between Permission[] and form data,
+ * with optional custom serialize/deserialize callbacks for app-specific needs.
+ */
+export declare function usePermissionForm(schema: PermissionSchema, options: UsePermissionFormOptions): UsePermissionFormResult;
+export { deserializePermissions, serializePermissions };

package/permissions/usePermissionForm.js

@@ -0,0 +1,256 @@
+import { useMemo, useCallback } from "react";
+function hasAction(entity, name) {
+  return entity.actions?.some(a => a.name === name) ?? false;
+}
+
+/** Resolve fullAccess config into a concrete Permission object. */
+function resolveFullAccess(schema) {
+  const name = `${schema.prefix}.*`;
+  if (schema.fullAccess === true) {
+    return {
+      name
+    };
+  }
+  return {
+    name,
+    ...schema.fullAccess
+  };
+}
+
+/** Resolve readOnlyAccess config into a concrete Permission[]. */
+function resolveReadOnlyAccess(schema) {
+  if (!schema.readOnlyAccess) {
+    return undefined;
+  }
+  if (schema.readOnlyAccess === true) {
+    return [{
+      name: `${schema.prefix}.*`,
+      rwd: "r"
+    }];
+  }
+  return schema.readOnlyAccess;
+}
+
+/**
+ * Deserialize Permission[] into form data based on the schema.
+ */
+function deserializePermissions(schema, value) {
+  if (!Array.isArray(value)) {
+    return {
+      accessLevel: "no"
+    };
+  }
+
+  // Check for read-only access by looking for the synthetic marker permission.
+  if (value.some(p => p.name === `$${schema.prefix}.readonly`)) {
+    return {
+      accessLevel: "read-only"
+    };
+  }
+
+  // Check for full access: either wildcard or the schema's fullAccess permission.
+  const fullAccessName = `${schema.prefix}.*`;
+  const hasFullAccess = value.some(p => p.name === "*" || p.name === fullAccessName);
+  if (hasFullAccess) {
+    return {
+      accessLevel: "full"
+    };
+  }
+
+  // Filter permissions that belong to this schema's prefix.
+  const ownPermissions = value.filter(p => p.name.startsWith(schema.prefix));
+  if (ownPermissions.length === 0) {
+    return {
+      accessLevel: "no"
+    };
+  }
+
+  // Custom access level — extract per-entity form fields.
+  const data = {
+    accessLevel: "custom"
+  };
+  const entities = schema.entities || [];
+  for (const entity of entities) {
+    const perm = ownPermissions.find(p => p.name === entity.permission);
+    if (!perm) {
+      continue;
+    }
+
+    // Access scope: "own" if perm.own === true, else "full".
+    if (perm.own === true) {
+      data[`${entity.id}AccessScope`] = "own";
+    } else {
+      data[`${entity.id}AccessScope`] = "full";
+    }
+
+    // Process actions.
+    for (const action of entity.actions ?? []) {
+      if (action.name === "rwd") {
+        data[`${entity.id}RWD`] = perm.rwd || "r";
+      } else if (action.name === "pw") {
+        data[`${entity.id}PW`] = perm.pw ? perm.pw.split("") : [];
+      } else {
+        // Custom boolean action.
+        data[`${entity.id}Action_${action.name}`] = perm[action.name] === true;
+      }
+    }
+  }
+  return data;
+}
+
+/**
+ * Serialize form data into Permission[] based on the schema.
+ */
+function serializePermissions(schema, formData, currentValue) {
+  // Start by filtering out all permissions belonging to this schema's prefix.
+  const filtered = Array.isArray(currentValue) ? currentValue.filter(p => !p.name.startsWith(schema.prefix) && !p.name.startsWith(`$${schema.prefix}`)) : [];
+  if (formData.accessLevel === "no" || !formData.accessLevel) {
+    return filtered;
+  }
+  if (formData.accessLevel === "full") {
+    return [...filtered, resolveFullAccess(schema)];
+  }
+  const readOnlyPermissions = resolveReadOnlyAccess(schema);
+  if (formData.accessLevel === "read-only" && readOnlyPermissions) {
+    return [...filtered, {
+      name: `$${schema.prefix}.readonly`
+    }, ...readOnlyPermissions];
+  }
+  const entities = schema.entities || [];
+
+  // Custom access — build entity permissions.
+  // First, build a map of entity definitions by ID for dependency lookups.
+  const entityMap = new Map();
+  for (const entity of entities) {
+    entityMap.set(entity.id, entity);
+  }
+
+  // Resolve cascading "own" scopes: if a parent is "own", children must be "own" too.
+  const resolvedScopes = new Map();
+  for (const entity of entities) {
+    const scope = formData[`${entity.id}AccessScope`];
+    if (!scope || scope === "no") {
+      continue;
+    }
+    let resolvedScope = scope;
+
+    // If this entity depends on a parent and the parent scope is "own",
+    // force this entity's scope to "own" as well.
+    if (entity.dependsOn) {
+      const parentScope = resolvedScopes.get(entity.dependsOn.entity);
+      if (parentScope === "own") {
+        resolvedScope = "own";
+      }
+    }
+    resolvedScopes.set(entity.id, resolvedScope);
+  }
+
+  // Prune resolved scopes based on dependencies (must run before building permissions
+  // so that transitive dependencies are properly pruned).
+  for (const entity of entities) {
+    if (!entity.dependsOn || !resolvedScopes.has(entity.id)) {
+      continue;
+    }
+    const parentScope = resolvedScopes.get(entity.dependsOn.entity);
+    if (!parentScope) {
+      // Parent entity is not enabled — prune child.
+      resolvedScopes.delete(entity.id);
+      continue;
+    }
+    const parentEntity = entityMap.get(entity.dependsOn.entity);
+    if (parentEntity && hasAction(parentEntity, "rwd")) {
+      const parentRwd = parentScope === "own" ? "rwd" : formData[`${entity.dependsOn.entity}RWD`] || "r";
+      if (!parentRwd.includes(entity.dependsOn.requires)) {
+        // Parent doesn't have the required action — prune child.
+        resolvedScopes.delete(entity.id);
+      }
+    }
+  }
+
+  // Build permissions from the pruned resolved scopes.
+  const permissions = [];
+  for (const entity of entities) {
+    const scope = resolvedScopes.get(entity.id);
+    if (!scope) {
+      continue;
+    }
+    const perm = {
+      name: entity.permission
+    };
+    if (scope === "own") {
+      perm.own = true;
+      if (hasAction(entity, "rwd")) {
+        perm.rwd = "rwd";
+      }
+    } else if (hasAction(entity, "rwd")) {
+      perm.rwd = formData[`${entity.id}RWD`] || "r";
+    }
+
+    // Process non-rwd actions.
+    for (const action of entity.actions ?? []) {
+      if (action.name === "rwd") {
+        continue; // Already handled above.
+      }
+      if (action.name === "pw") {
+        const pw = formData[`${entity.id}PW`] || [];
+        if (pw.length > 0) {
+          perm.pw = pw.join("");
+        }
+      } else {
+        // Custom boolean action.
+        if (formData[`${entity.id}Action_${action.name}`]) {
+          perm[action.name] = true;
+        }
+      }
+    }
+    permissions.push(perm);
+  }
+  return [...filtered, ...permissions];
+}
+
+/**
+ * Hook that bridges a permission schema with a Form component.
+ *
+ * Handles bidirectional transformation between Permission[] and form data,
+ * with optional custom serialize/deserialize callbacks for app-specific needs.
+ */
+export function usePermissionForm(schema, options) {
+  const {
+    value,
+    onChange
+  } = options;
+  const formData = useMemo(() => {
+    let data = deserializePermissions(schema, value);
+
+    // Merge custom deserialized data if provided.
+    if (options.deserialize) {
+      const extra = options.deserialize(Array.isArray(value) ? value : []);
+      data = {
+        ...data,
+        ...extra
+      };
+    }
+    return data;
+  }, []);
+  const onFormChange = useCallback(data => {
+    let result = serializePermissions(schema, data, value);
+
+    // Apply custom serializer if provided.
+    if (options.serialize) {
+      result = options.serialize(data, result.filter(p => p.name.startsWith(schema.prefix)));
+      // Re-add non-schema permissions that were filtered out.
+      const nonSchemaPermissions = Array.isArray(value) ? value.filter(p => !p.name.startsWith(schema.prefix) && !p.name.startsWith(`$${schema.prefix}`)) : [];
+      result = [...nonSchemaPermissions, ...result];
+    }
+    onChange(result);
+  }, [value]);
+  return {
+    formData,
+    onFormChange
+  };
+}
+
+// Export the pure functions for unit testing.
+export { deserializePermissions, serializePermissions };
+
+//# sourceMappingURL=usePermissionForm.js.map