@webiny/app-admin 0.0.0-unstable.6f45466a1d → 0.0.0-unstable.7be00a75a9

package/permissions/createPermissions.test.js

@@ -0,0 +1,209 @@
+import { describe, expect, it } from "vitest";
+import { Container } from "@webiny/di";
+import { createPermissionsAbstraction, createPermissionsFeature } from "./createPermissions.js";
+import { createPermissionSchema } from "./createPermissionSchema.js";
+import { IdentityContext } from "../features/security/IdentityContext/abstractions.js";
+import { IdentityContext as IdentityContext_js_IdentityContext } from "../features/security/IdentityContext/IdentityContext.js";
+import { Identity } from "../domain/Identity.js";
+const TEST_SCHEMA = createPermissionSchema({
+    prefix: "test",
+    fullAccess: true,
+    entities: [
+        {
+            id: "page",
+            title: "Page",
+            permission: "test.page",
+            scopes: [
+                "full",
+                "own"
+            ],
+            actions: [
+                {
+                    name: "rwd"
+                },
+                {
+                    name: "pw"
+                }
+            ]
+        }
+    ]
+});
+const TestPermissions = createPermissionsAbstraction(TEST_SCHEMA);
+const TestPermissionsFeature = createPermissionsFeature(TEST_SCHEMA, TestPermissions);
+function resolve(permissions) {
+    const container = new Container();
+    container.register(IdentityContext_js_IdentityContext).inSingletonScope();
+    TestPermissionsFeature.register(container);
+    const identityContext = container.resolve(IdentityContext);
+    identityContext.setIdentity(Identity.createAuthenticated({
+        id: "test-user",
+        displayName: "Test User",
+        type: "admin",
+        roles: [],
+        teams: [],
+        permissions,
+        profile: {
+            external: false
+        },
+        currentTenant: {
+            id: "root",
+            name: "Root"
+        },
+        defaultTenant: {
+            id: "root",
+            name: "Root"
+        }
+    }));
+    return container.resolve(TestPermissions);
+}
+describe("SchemaPermissions", ()=>{
+    describe("full access", ()=>{
+        it("grants everything with unrestricted wildcard", ()=>{
+            const p = resolve([
+                {
+                    name: "test.*"
+                }
+            ]);
+            expect(p.canAccess("page")).toBe(true);
+            expect(p.canRead("page")).toBe(true);
+            expect(p.canCreate("page")).toBe(true);
+            expect(p.canEdit("page")).toBe(true);
+            expect(p.canDelete("page")).toBe(true);
+            expect(p.canPublish("page")).toBe(true);
+            expect(p.canUnpublish("page")).toBe(true);
+        });
+        it("rejects wildcard with rwd restriction as non-full access", ()=>{
+            const p = resolve([
+                {
+                    name: "test.*",
+                    rwd: "r"
+                }
+            ]);
+            expect(p.canCreate("page")).toBe(false);
+            expect(p.canDelete("page")).toBe(false);
+        });
+    });
+    describe("entity-level access", ()=>{
+        it("grants access when entity permission exists", ()=>{
+            const p = resolve([
+                {
+                    name: "test.page"
+                }
+            ]);
+            expect(p.canAccess("page")).toBe(true);
+        });
+        it("denies access when no permission exists", ()=>{
+            const p = resolve([]);
+            expect(p.canAccess("page")).toBe(false);
+        });
+    });
+    describe("rwd actions", ()=>{
+        it("respects read permission", ()=>{
+            const p = resolve([
+                {
+                    name: "test.page",
+                    rwd: "r"
+                }
+            ]);
+            expect(p.canRead("page")).toBe(true);
+            expect(p.canCreate("page")).toBe(false);
+            expect(p.canDelete("page")).toBe(false);
+        });
+        it("respects write permission", ()=>{
+            const p = resolve([
+                {
+                    name: "test.page",
+                    rwd: "rw"
+                }
+            ]);
+            expect(p.canRead("page")).toBe(true);
+            expect(p.canCreate("page")).toBe(true);
+            expect(p.canEdit("page")).toBe(true);
+            expect(p.canDelete("page")).toBe(false);
+        });
+        it("respects delete permission", ()=>{
+            const p = resolve([
+                {
+                    name: "test.page",
+                    rwd: "d"
+                }
+            ]);
+            expect(p.canDelete("page")).toBe(true);
+            expect(p.canRead("page")).toBe(false);
+        });
+    });
+    describe("publish/unpublish actions", ()=>{
+        it("grants publish when pw includes p", ()=>{
+            const p = resolve([
+                {
+                    name: "test.page",
+                    pw: "p"
+                }
+            ]);
+            expect(p.canPublish("page")).toBe(true);
+            expect(p.canUnpublish("page")).toBe(false);
+        });
+        it("grants both when pw includes pu", ()=>{
+            const p = resolve([
+                {
+                    name: "test.page",
+                    pw: "pu"
+                }
+            ]);
+            expect(p.canPublish("page")).toBe(true);
+            expect(p.canUnpublish("page")).toBe(true);
+        });
+    });
+    describe("own scope", ()=>{
+        it("allows edit when item is owned by the user", ()=>{
+            const p = resolve([
+                {
+                    name: "test.page",
+                    own: true
+                }
+            ]);
+            expect(p.canEdit("page", {
+                createdBy: {
+                    id: "test-user"
+                }
+            })).toBe(true);
+        });
+        it("denies edit when item is owned by someone else", ()=>{
+            const p = resolve([
+                {
+                    name: "test.page",
+                    own: true
+                }
+            ]);
+            expect(p.canEdit("page", {
+                createdBy: {
+                    id: "other-user"
+                }
+            })).toBe(false);
+        });
+        it("allows edit when no item is provided (optimistic)", ()=>{
+            const p = resolve([
+                {
+                    name: "test.page",
+                    own: true
+                }
+            ]);
+            expect(p.canEdit("page")).toBe(true);
+        });
+        it("denies delete when item is owned by someone else", ()=>{
+            const p = resolve([
+                {
+                    name: "test.page",
+                    own: true
+                }
+            ]);
+            expect(p.canDelete("page", {
+                createdBy: {
+                    id: "other-user"
+                }
+            })).toBe(false);
+        });
+    });
+});
+
+//# sourceMappingURL=createPermissions.test.js.map

package/permissions/createPermissions.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions/createPermissions.test.js","sources":["../../src/permissions/createPermissions.test.ts"],"sourcesContent":["import { describe, it, expect } from \"vitest\";\nimport { Container } from \"@webiny/di\";\nimport { createPermissionsAbstraction, createPermissionsFeature } from \"./createPermissions.js\";\nimport { createPermissionSchema } from \"./createPermissionSchema.js\";\nimport { IdentityContext } from \"~/features/security/IdentityContext/abstractions.js\";\nimport { IdentityContext as IdentityContextImpl } from \"~/features/security/IdentityContext/IdentityContext.js\";\nimport { Identity } from \"~/domain/Identity.js\";\n\nconst TEST_SCHEMA = createPermissionSchema({\n    prefix: \"test\",\n    fullAccess: true,\n    entities: [\n        {\n            id: \"page\",\n            title: \"Page\",\n            permission: \"test.page\",\n            scopes: [\"full\", \"own\"],\n            actions: [{ name: \"rwd\" }, { name: \"pw\" }]\n        }\n    ]\n} as const);\n\nconst TestPermissions = createPermissionsAbstraction(TEST_SCHEMA);\nconst TestPermissionsFeature = createPermissionsFeature(TEST_SCHEMA, TestPermissions);\n\nfunction resolve(permissions: Array<{ name: string; [key: string]: any }>) {\n    const container = new Container();\n    container.register(IdentityContextImpl).inSingletonScope();\n    TestPermissionsFeature.register(container);\n\n    const identityContext = container.resolve(IdentityContext);\n    identityContext.setIdentity(\n        Identity.createAuthenticated({\n            id: \"test-user\",\n            displayName: \"Test User\",\n            type: \"admin\",\n            roles: [],\n            teams: [],\n            permissions,\n            profile: { external: false },\n            currentTenant: { id: \"root\", name: \"Root\" },\n            defaultTenant: { id: \"root\", name: \"Root\" }\n        })\n    );\n\n    return container.resolve(TestPermissions);\n}\n\ndescribe(\"SchemaPermissions\", () => {\n    describe(\"full access\", () => {\n        it(\"grants everything with unrestricted wildcard\", () => {\n            const p = resolve([{ name: \"test.*\" }]);\n            expect(p.canAccess(\"page\")).toBe(true);\n            expect(p.canRead(\"page\")).toBe(true);\n            expect(p.canCreate(\"page\")).toBe(true);\n            expect(p.canEdit(\"page\")).toBe(true);\n            expect(p.canDelete(\"page\")).toBe(true);\n            expect(p.canPublish(\"page\")).toBe(true);\n            expect(p.canUnpublish(\"page\")).toBe(true);\n        });\n\n        it(\"rejects wildcard with rwd restriction as non-full access\", () => {\n            const p = resolve([{ name: \"test.*\", rwd: \"r\" }]);\n            expect(p.canCreate(\"page\")).toBe(false);\n            expect(p.canDelete(\"page\")).toBe(false);\n        });\n    });\n\n    describe(\"entity-level access\", () => {\n        it(\"grants access when entity permission exists\", () => {\n            const p = resolve([{ name: \"test.page\" }]);\n            expect(p.canAccess(\"page\")).toBe(true);\n        });\n\n        it(\"denies access when no permission exists\", () => {\n            const p = resolve([]);\n            expect(p.canAccess(\"page\")).toBe(false);\n        });\n    });\n\n    describe(\"rwd actions\", () => {\n        it(\"respects read permission\", () => {\n            const p = resolve([{ name: \"test.page\", rwd: \"r\" }]);\n            expect(p.canRead(\"page\")).toBe(true);\n            expect(p.canCreate(\"page\")).toBe(false);\n            expect(p.canDelete(\"page\")).toBe(false);\n        });\n\n        it(\"respects write permission\", () => {\n            const p = resolve([{ name: \"test.page\", rwd: \"rw\" }]);\n            expect(p.canRead(\"page\")).toBe(true);\n            expect(p.canCreate(\"page\")).toBe(true);\n            expect(p.canEdit(\"page\")).toBe(true);\n            expect(p.canDelete(\"page\")).toBe(false);\n        });\n\n        it(\"respects delete permission\", () => {\n            const p = resolve([{ name: \"test.page\", rwd: \"d\" }]);\n            expect(p.canDelete(\"page\")).toBe(true);\n            expect(p.canRead(\"page\")).toBe(false);\n        });\n    });\n\n    describe(\"publish/unpublish actions\", () => {\n        it(\"grants publish when pw includes p\", () => {\n            const p = resolve([{ name: \"test.page\", pw: \"p\" }]);\n            expect(p.canPublish(\"page\")).toBe(true);\n            expect(p.canUnpublish(\"page\")).toBe(false);\n        });\n\n        it(\"grants both when pw includes pu\", () => {\n            const p = resolve([{ name: \"test.page\", pw: \"pu\" }]);\n            expect(p.canPublish(\"page\")).toBe(true);\n            expect(p.canUnpublish(\"page\")).toBe(true);\n        });\n    });\n\n    describe(\"own scope\", () => {\n        it(\"allows edit when item is owned by the user\", () => {\n            const p = resolve([{ name: \"test.page\", own: true }]);\n            expect(p.canEdit(\"page\", { createdBy: { id: \"test-user\" } })).toBe(true);\n        });\n\n        it(\"denies edit when item is owned by someone else\", () => {\n            const p = resolve([{ name: \"test.page\", own: true }]);\n            expect(p.canEdit(\"page\", { createdBy: { id: \"other-user\" } })).toBe(false);\n        });\n\n        it(\"allows edit when no item is provided (optimistic)\", () => {\n            const p = resolve([{ name: \"test.page\", own: true }]);\n            expect(p.canEdit(\"page\")).toBe(true);\n        });\n\n        it(\"denies delete when item is owned by someone else\", () => {\n            const p = resolve([{ name: \"test.page\", own: true }]);\n            expect(p.canDelete(\"page\", { createdBy: { id: \"other-user\" } })).toBe(false);\n        });\n    });\n});\n"],"names":["TEST_SCHEMA","createPermissionSchema","TestPermissions","createPermissionsAbstraction","TestPermissionsFeature","createPermissionsFeature","resolve","permissions","container","Container","IdentityContextImpl","identityContext","IdentityContext","Identity","describe","it","p","expect"],"mappings":"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"}

package/permissions/index.d.ts

@@ -0,0 +1,9 @@
+export { createPermissionSchema } from "./createPermissionSchema.js";
+export { createPermissionsAbstraction, createPermissionsFeature } from "./createPermissions.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,7 @@
+export { createPermissionSchema } from "./createPermissionSchema.js";
+export { createPermissionsAbstraction, createPermissionsFeature } from "./createPermissions.js";
+export { createUsePermissions } from "./usePermissions.js";
+export { deserializePermissions, serializePermissions, usePermissionForm } from "./usePermissionForm.js";
+export { PermissionRenderer } from "./PermissionRenderer.js";
+export { PermissionValueProvider, usePermissionValue } from "./PermissionValueContext.js";
+export { createHasPermission } from "./createHasPermission.js";

package/permissions/types.d.ts

@@ -0,0 +1,267 @@
+import type React from "react";
+import type { NonEmptyArray } from "@webiny/app/types.js";
+/**
+ * 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>;
+/**
+ * Canonical type for DI-resolved permissions.
+ * Same underlying type as `UsePermissionsResult<S>`.
+ */
+export type Permissions<S extends PermissionSchemaConfig> = UsePermissionsResult<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>;
+/**
+ * Action constraint for `HasPermission`.
+ *
+ * Exactly one of `action`, `someActions`, or `allActions` may be provided:
+ * - `action` — single action; grants access if it passes.
+ * - `someActions` — array; grants access if ANY action passes (OR).
+ * - `allActions` — array; grants access only if ALL actions pass (AND).
+ */
+type ActionConstraint<S extends PermissionSchemaConfig> = {
+    action?: HasPermissionAction<S>;
+    someActions?: never;
+    allActions?: never;
+} | {
+    action?: never;
+    someActions: NonEmptyArray<HasPermissionAction<S>>;
+    allActions?: never;
+} | {
+    action?: never;
+    someActions?: never;
+    allActions: NonEmptyArray<HasPermissionAction<S>>;
+};
+/**
+ * Props for a schema-bound `HasPermission` component created via `createHasPermission`.
+ *
+ * Exactly one of `entity`, `any`, or `all` must be provided.
+ * Optionally combine with `action`, `someActions`, or `allActions`.
+ */
+export type HasPermissionProps<S extends PermissionSchemaConfig> = (SingleEntityProps<S> | AnyEntitiesProps<S> | AllEntitiesProps<S>) & ActionConstraint<S>;
+interface SingleEntityProps<S extends PermissionSchemaConfig> {
+    entity: AllEntityIds<S>;
+    any?: never;
+    all?: never;
+    children: React.ReactNode;
+}
+interface AnyEntitiesProps<S extends PermissionSchemaConfig> {
+    entity?: never;
+    any: AllEntityIds<S>[];
+    all?: never;
+    children: React.ReactNode;
+}
+interface AllEntitiesProps<S extends PermissionSchemaConfig> {
+    entity?: never;
+    any?: never;
+    all: AllEntityIds<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/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 };