com-angel-authorization 1.0.0

package/dist/react/index.cjs

@@ -0,0 +1,156 @@
+"use client";
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/react/index.ts
+var react_exports = {};
+__export(react_exports, {
+  Can: () => Can,
+  PermissionProvider: () => PermissionProvider,
+  PermissionStore: () => import_core2.PermissionStore,
+  createPermissionStore: () => import_core2.createPermissionStore,
+  useHasPermission: () => useHasPermission,
+  useHasRole: () => useHasRole,
+  usePermission: () => usePermission
+});
+module.exports = __toCommonJS(react_exports);
+
+// src/react/context.tsx
+var import_react = require("react");
+var import_core = require("../core");
+var PermissionContext = (0, import_react.createContext)(null);
+function PermissionProvider({
+  children,
+  store: externalStore,
+  initialState
+}) {
+  const store = (0, import_react.useMemo)(
+    () => externalStore ?? (0, import_core.createPermissionStore)(initialState),
+    // store identity is intentional; initialState only applies on first create
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [externalStore]
+  );
+  return (0, import_react.createElement)(PermissionContext.Provider, { value: store }, children);
+}
+function useStore() {
+  const store = (0, import_react.useContext)(PermissionContext);
+  if (!store) {
+    throw new Error(
+      "[com-angel-authorization/react] usePermission* hooks must be used within <PermissionProvider>."
+    );
+  }
+  return store;
+}
+function usePermissionSnapshot(store) {
+  const [state, setState] = (0, import_react.useState)(() => store.getState());
+  (0, import_react.useEffect)(() => {
+    setState(store.getState());
+    return store.subscribe(setState);
+  }, [store]);
+  return state;
+}
+function usePermission() {
+  const store = useStore();
+  const state = usePermissionSnapshot(store);
+  const hasPermission = (0, import_react.useCallback)(
+    (codes, options) => store.hasPermission(codes, options),
+    [store]
+  );
+  const hasRole = (0, import_react.useCallback)(
+    (codes, options) => store.hasRole(codes, options),
+    [store]
+  );
+  const can = (0, import_react.useCallback)(
+    (codes, options) => store.can(codes, options),
+    [store]
+  );
+  return {
+    permissions: state.permissions,
+    roles: state.roles,
+    isSuperAdmin: Boolean(state.isSuperAdmin),
+    hasPermission,
+    hasRole,
+    can,
+    setPermissions: store.setPermissions.bind(store),
+    setRoles: store.setRoles.bind(store),
+    setSuperAdmin: store.setSuperAdmin.bind(store),
+    hydrate: store.hydrate.bind(store),
+    clear: store.clear.bind(store),
+    store
+  };
+}
+function useHasPermission(codes, options) {
+  const { hasPermission, permissions, isSuperAdmin } = usePermission();
+  void permissions;
+  void isSuperAdmin;
+  return hasPermission(codes, options);
+}
+function useHasRole(codes, options) {
+  const { hasRole, roles, isSuperAdmin } = usePermission();
+  void roles;
+  void isSuperAdmin;
+  return hasRole(codes, options);
+}
+
+// src/react/Can.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+function evaluateAccess(hasPermission, hasRole, props) {
+  const { permission, role, mode, combine = "and" } = props;
+  const options = { mode };
+  const hasPermCheck = permission !== void 0;
+  const hasRoleCheck = role !== void 0;
+  if (!hasPermCheck && !hasRoleCheck) return true;
+  const permOk = hasPermCheck ? hasPermission(permission, options) : true;
+  const roleOk = hasRoleCheck ? hasRole(role, options) : true;
+  if (hasPermCheck && hasRoleCheck) {
+    return combine === "or" ? permOk || roleOk : permOk && roleOk;
+  }
+  return hasPermCheck ? permOk : roleOk;
+}
+function Can({
+  permission,
+  role,
+  mode,
+  combine,
+  children,
+  fallback = null
+}) {
+  const { hasPermission, hasRole } = usePermission();
+  const allowed = evaluateAccess(hasPermission, hasRole, {
+    permission,
+    role,
+    mode,
+    combine
+  });
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children: allowed ? children : fallback });
+}
+
+// src/react/index.ts
+var import_core2 = require("../core");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Can,
+  PermissionProvider,
+  PermissionStore,
+  createPermissionStore,
+  useHasPermission,
+  useHasRole,
+  usePermission
+});
+//# sourceMappingURL=index.cjs.map

package/dist/react/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/react/index.ts","../../src/react/context.tsx","../../src/react/Can.tsx"],"sourcesContent":["export { PermissionProvider, usePermission, useHasPermission, useHasRole } from './context';\nexport type { PermissionProviderProps, UsePermissionResult } from './context';\n\nexport { Can } from './Can';\nexport type { CanProps } from './Can';\n\nexport type {\n  CheckOptions,\n  MatchMode,\n  PermissionChecker,\n  PermissionCode,\n  PermissionListener,\n  PermissionState,\n  RoleCode,\n} from '../core';\n\nexport { PermissionStore, createPermissionStore } from '../core';\n","import {\n  createContext,\n  createElement,\n  useCallback,\n  useContext,\n  useEffect,\n  useMemo,\n  useState,\n  type ReactNode,\n} from 'react';\nimport {\n  createPermissionStore,\n  type CheckOptions,\n  type PermissionCode,\n  type PermissionState,\n  type PermissionStore,\n  type RoleCode,\n} from '../core';\n\nconst PermissionContext = createContext<PermissionStore | null>(null);\n\nexport interface PermissionProviderProps {\n  children: ReactNode;\n  /** Pass an existing store to share across trees, or omit to create one. */\n  store?: PermissionStore;\n  /** Initial state when the provider creates its own store. */\n  initialState?: Partial<PermissionState>;\n}\n\nexport function PermissionProvider({\n  children,\n  store: externalStore,\n  initialState,\n}: PermissionProviderProps) {\n  const store = useMemo(\n    () => externalStore ?? createPermissionStore(initialState),\n    // store identity is intentional; initialState only applies on first create\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    [externalStore],\n  );\n\n  return createElement(PermissionContext.Provider, { value: store }, children);\n}\n\nfunction useStore(): PermissionStore {\n  const store = useContext(PermissionContext);\n  if (!store) {\n    throw new Error(\n      '[com-angel-authorization/react] usePermission* hooks must be used within <PermissionProvider>.',\n    );\n  }\n  return store;\n}\n\nfunction usePermissionSnapshot(store: PermissionStore): PermissionState {\n  const [state, setState] = useState(() => store.getState());\n\n  useEffect(() => {\n    setState(store.getState());\n    return store.subscribe(setState);\n  }, [store]);\n\n  return state;\n}\n\nexport interface UsePermissionResult {\n  permissions: PermissionCode[];\n  roles: RoleCode[];\n  isSuperAdmin: boolean;\n  hasPermission: (codes: PermissionCode | PermissionCode[], options?: CheckOptions) => boolean;\n  hasRole: (codes: RoleCode | RoleCode[], options?: CheckOptions) => boolean;\n  can: (codes: PermissionCode | PermissionCode[], options?: CheckOptions) => boolean;\n  setPermissions: (permissions: PermissionCode[]) => void;\n  setRoles: (roles: RoleCode[]) => void;\n  setSuperAdmin: (isSuperAdmin: boolean) => void;\n  hydrate: (payload: Partial<PermissionState>) => void;\n  clear: () => void;\n  store: PermissionStore;\n}\n\nexport function usePermission(): UsePermissionResult {\n  const store = useStore();\n  const state = usePermissionSnapshot(store);\n\n  const hasPermission = useCallback(\n    (codes: PermissionCode | PermissionCode[], options?: CheckOptions) =>\n      store.hasPermission(codes, options),\n    [store],\n  );\n\n  const hasRole = useCallback(\n    (codes: RoleCode | RoleCode[], options?: CheckOptions) => store.hasRole(codes, options),\n    [store],\n  );\n\n  const can = useCallback(\n    (codes: PermissionCode | PermissionCode[], options?: CheckOptions) => store.can(codes, options),\n    [store],\n  );\n\n  return {\n    permissions: state.permissions,\n    roles: state.roles,\n    isSuperAdmin: Boolean(state.isSuperAdmin),\n    hasPermission,\n    hasRole,\n    can,\n    setPermissions: store.setPermissions.bind(store),\n    setRoles: store.setRoles.bind(store),\n    setSuperAdmin: store.setSuperAdmin.bind(store),\n    hydrate: store.hydrate.bind(store),\n    clear: store.clear.bind(store),\n    store,\n  };\n}\n\n/** Returns whether the current user has the given permission(s). */\nexport function useHasPermission(\n  codes: PermissionCode | PermissionCode[],\n  options?: CheckOptions,\n): boolean {\n  const { hasPermission, permissions, isSuperAdmin } = usePermission();\n  // re-compute when permission list / super-admin changes\n  void permissions;\n  void isSuperAdmin;\n  return hasPermission(codes, options);\n}\n\n/** Returns whether the current user has the given role(s). */\nexport function useHasRole(\n  codes: RoleCode | RoleCode[],\n  options?: CheckOptions,\n): boolean {\n  const { hasRole, roles, isSuperAdmin } = usePermission();\n  void roles;\n  void isSuperAdmin;\n  return hasRole(codes, options);\n}\n","import type { ReactNode } from 'react';\nimport type { CheckOptions, PermissionCode, RoleCode } from '../core';\nimport { usePermission } from './context';\n\nexport interface CanProps {\n  /** Permission codes to check. */\n  permission?: PermissionCode | PermissionCode[];\n  /** Role codes to check. */\n  role?: RoleCode | RoleCode[];\n  /**\n   * `any` — pass when at least one code matches (default)\n   * `all` — pass only when every code matches\n   */\n  mode?: CheckOptions['mode'];\n  /**\n   * How permission and role conditions combine when both are provided.\n   * Default: `and` (must satisfy both).\n   */\n  combine?: 'and' | 'or';\n  children: ReactNode;\n  /** Fallback when access is denied. */\n  fallback?: ReactNode;\n}\n\nfunction evaluateAccess(\n  hasPermission: (c: PermissionCode | PermissionCode[], o?: CheckOptions) => boolean,\n  hasRole: (c: RoleCode | RoleCode[], o?: CheckOptions) => boolean,\n  props: Pick<CanProps, 'permission' | 'role' | 'mode' | 'combine'>,\n): boolean {\n  const { permission, role, mode, combine = 'and' } = props;\n  const options: CheckOptions = { mode };\n\n  const hasPermCheck = permission !== undefined;\n  const hasRoleCheck = role !== undefined;\n\n  if (!hasPermCheck && !hasRoleCheck) return true;\n\n  const permOk = hasPermCheck ? hasPermission(permission!, options) : true;\n  const roleOk = hasRoleCheck ? hasRole(role!, options) : true;\n\n  if (hasPermCheck && hasRoleCheck) {\n    return combine === 'or' ? permOk || roleOk : permOk && roleOk;\n  }\n\n  return hasPermCheck ? permOk : roleOk;\n}\n\n/**\n * Conditionally render children based on permission / role.\n *\n * @example\n * <Can permission=\"user:edit\">\n *   <button>Edit</button>\n * </Can>\n *\n * <Can permission={['user:edit', 'user:delete']} mode=\"all\" fallback={null}>\n *   <AdminPanel />\n * </Can>\n */\nexport function Can({\n  permission,\n  role,\n  mode,\n  combine,\n  children,\n  fallback = null,\n}: CanProps) {\n  const { hasPermission, hasRole } = usePermission();\n  const allowed = evaluateAccess(hasPermission, hasRole, {\n    permission,\n    role,\n    mode,\n    combine,\n  });\n\n  return <>{allowed ? children : fallback}</>;\n}\n"],"mappings":"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","names":["import_core"]}

package/dist/react/index.d.cts

@@ -0,0 +1,119 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+type PermissionCode = string;
+type RoleCode = string;
+interface PermissionState {
+    /** Permission codes owned by the current user */
+    permissions: PermissionCode[];
+    /** Roles owned by the current user */
+    roles: RoleCode[];
+    /** Super admin bypasses all checks when true */
+    isSuperAdmin?: boolean;
+}
+type MatchMode = 'all' | 'any';
+interface CheckOptions {
+    /**
+     * `any` — pass when at least one code matches (default)
+     * `all` — pass only when every code matches
+     */
+    mode?: MatchMode;
+}
+type PermissionListener = (state: PermissionState) => void;
+interface PermissionChecker {
+    hasPermission(codes: PermissionCode | PermissionCode[], options?: CheckOptions): boolean;
+    hasRole(codes: RoleCode | RoleCode[], options?: CheckOptions): boolean;
+    can(codes: PermissionCode | PermissionCode[], options?: CheckOptions): boolean;
+    getState(): PermissionState;
+}
+
+/**
+ * Mutable permission store shared by React / Vue adapters.
+ * Framework-agnostic — safe to use in Node, browser, or any UI lib.
+ */
+declare class PermissionStore implements PermissionChecker {
+    private state;
+    private permissionSet;
+    private roleSet;
+    private listeners;
+    constructor(initial?: Partial<PermissionState>);
+    getState(): PermissionState;
+    setState(next: Partial<PermissionState>): void;
+    setPermissions(permissions: PermissionCode[]): void;
+    setRoles(roles: RoleCode[]): void;
+    setSuperAdmin(isSuperAdmin: boolean): void;
+    /** Replace permissions, roles and super-admin flag in one shot (typical after login). */
+    hydrate(payload: Partial<PermissionState>): void;
+    /** Clear all authz data (typical after logout). */
+    clear(): void;
+    hasPermission(codes: PermissionCode | PermissionCode[], options?: CheckOptions): boolean;
+    hasRole(codes: RoleCode | RoleCode[], options?: CheckOptions): boolean;
+    /** Alias of `hasPermission` for template-friendly APIs. */
+    can(codes: PermissionCode | PermissionCode[], options?: CheckOptions): boolean;
+    subscribe(listener: PermissionListener): () => void;
+    private emit;
+}
+declare function createPermissionStore(initial?: Partial<PermissionState>): PermissionStore;
+
+interface PermissionProviderProps {
+    children: ReactNode;
+    /** Pass an existing store to share across trees, or omit to create one. */
+    store?: PermissionStore;
+    /** Initial state when the provider creates its own store. */
+    initialState?: Partial<PermissionState>;
+}
+declare function PermissionProvider({ children, store: externalStore, initialState, }: PermissionProviderProps): react.FunctionComponentElement<react.ProviderProps<PermissionStore | null>>;
+interface UsePermissionResult {
+    permissions: PermissionCode[];
+    roles: RoleCode[];
+    isSuperAdmin: boolean;
+    hasPermission: (codes: PermissionCode | PermissionCode[], options?: CheckOptions) => boolean;
+    hasRole: (codes: RoleCode | RoleCode[], options?: CheckOptions) => boolean;
+    can: (codes: PermissionCode | PermissionCode[], options?: CheckOptions) => boolean;
+    setPermissions: (permissions: PermissionCode[]) => void;
+    setRoles: (roles: RoleCode[]) => void;
+    setSuperAdmin: (isSuperAdmin: boolean) => void;
+    hydrate: (payload: Partial<PermissionState>) => void;
+    clear: () => void;
+    store: PermissionStore;
+}
+declare function usePermission(): UsePermissionResult;
+/** Returns whether the current user has the given permission(s). */
+declare function useHasPermission(codes: PermissionCode | PermissionCode[], options?: CheckOptions): boolean;
+/** Returns whether the current user has the given role(s). */
+declare function useHasRole(codes: RoleCode | RoleCode[], options?: CheckOptions): boolean;
+
+interface CanProps {
+    /** Permission codes to check. */
+    permission?: PermissionCode | PermissionCode[];
+    /** Role codes to check. */
+    role?: RoleCode | RoleCode[];
+    /**
+     * `any` — pass when at least one code matches (default)
+     * `all` — pass only when every code matches
+     */
+    mode?: CheckOptions['mode'];
+    /**
+     * How permission and role conditions combine when both are provided.
+     * Default: `and` (must satisfy both).
+     */
+    combine?: 'and' | 'or';
+    children: ReactNode;
+    /** Fallback when access is denied. */
+    fallback?: ReactNode;
+}
+/**
+ * Conditionally render children based on permission / role.
+ *
+ * @example
+ * <Can permission="user:edit">
+ *   <button>Edit</button>
+ * </Can>
+ *
+ * <Can permission={['user:edit', 'user:delete']} mode="all" fallback={null}>
+ *   <AdminPanel />
+ * </Can>
+ */
+declare function Can({ permission, role, mode, combine, children, fallback, }: CanProps): react.JSX.Element;
+
+export { Can, type CanProps, type CheckOptions, type MatchMode, type PermissionChecker, type PermissionCode, type PermissionListener, PermissionProvider, type PermissionProviderProps, type PermissionState, PermissionStore, type RoleCode, type UsePermissionResult, createPermissionStore, useHasPermission, useHasRole, usePermission };

package/dist/react/index.d.ts

@@ -0,0 +1,119 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+type PermissionCode = string;
+type RoleCode = string;
+interface PermissionState {
+    /** Permission codes owned by the current user */
+    permissions: PermissionCode[];
+    /** Roles owned by the current user */
+    roles: RoleCode[];
+    /** Super admin bypasses all checks when true */
+    isSuperAdmin?: boolean;
+}
+type MatchMode = 'all' | 'any';
+interface CheckOptions {
+    /**
+     * `any` — pass when at least one code matches (default)
+     * `all` — pass only when every code matches
+     */
+    mode?: MatchMode;
+}
+type PermissionListener = (state: PermissionState) => void;
+interface PermissionChecker {
+    hasPermission(codes: PermissionCode | PermissionCode[], options?: CheckOptions): boolean;
+    hasRole(codes: RoleCode | RoleCode[], options?: CheckOptions): boolean;
+    can(codes: PermissionCode | PermissionCode[], options?: CheckOptions): boolean;
+    getState(): PermissionState;
+}
+
+/**
+ * Mutable permission store shared by React / Vue adapters.
+ * Framework-agnostic — safe to use in Node, browser, or any UI lib.
+ */
+declare class PermissionStore implements PermissionChecker {
+    private state;
+    private permissionSet;
+    private roleSet;
+    private listeners;
+    constructor(initial?: Partial<PermissionState>);
+    getState(): PermissionState;
+    setState(next: Partial<PermissionState>): void;
+    setPermissions(permissions: PermissionCode[]): void;
+    setRoles(roles: RoleCode[]): void;
+    setSuperAdmin(isSuperAdmin: boolean): void;
+    /** Replace permissions, roles and super-admin flag in one shot (typical after login). */
+    hydrate(payload: Partial<PermissionState>): void;
+    /** Clear all authz data (typical after logout). */
+    clear(): void;
+    hasPermission(codes: PermissionCode | PermissionCode[], options?: CheckOptions): boolean;
+    hasRole(codes: RoleCode | RoleCode[], options?: CheckOptions): boolean;
+    /** Alias of `hasPermission` for template-friendly APIs. */
+    can(codes: PermissionCode | PermissionCode[], options?: CheckOptions): boolean;
+    subscribe(listener: PermissionListener): () => void;
+    private emit;
+}
+declare function createPermissionStore(initial?: Partial<PermissionState>): PermissionStore;
+
+interface PermissionProviderProps {
+    children: ReactNode;
+    /** Pass an existing store to share across trees, or omit to create one. */
+    store?: PermissionStore;
+    /** Initial state when the provider creates its own store. */
+    initialState?: Partial<PermissionState>;
+}
+declare function PermissionProvider({ children, store: externalStore, initialState, }: PermissionProviderProps): react.FunctionComponentElement<react.ProviderProps<PermissionStore | null>>;
+interface UsePermissionResult {
+    permissions: PermissionCode[];
+    roles: RoleCode[];
+    isSuperAdmin: boolean;
+    hasPermission: (codes: PermissionCode | PermissionCode[], options?: CheckOptions) => boolean;
+    hasRole: (codes: RoleCode | RoleCode[], options?: CheckOptions) => boolean;
+    can: (codes: PermissionCode | PermissionCode[], options?: CheckOptions) => boolean;
+    setPermissions: (permissions: PermissionCode[]) => void;
+    setRoles: (roles: RoleCode[]) => void;
+    setSuperAdmin: (isSuperAdmin: boolean) => void;
+    hydrate: (payload: Partial<PermissionState>) => void;
+    clear: () => void;
+    store: PermissionStore;
+}
+declare function usePermission(): UsePermissionResult;
+/** Returns whether the current user has the given permission(s). */
+declare function useHasPermission(codes: PermissionCode | PermissionCode[], options?: CheckOptions): boolean;
+/** Returns whether the current user has the given role(s). */
+declare function useHasRole(codes: RoleCode | RoleCode[], options?: CheckOptions): boolean;
+
+interface CanProps {
+    /** Permission codes to check. */
+    permission?: PermissionCode | PermissionCode[];
+    /** Role codes to check. */
+    role?: RoleCode | RoleCode[];
+    /**
+     * `any` — pass when at least one code matches (default)
+     * `all` — pass only when every code matches
+     */
+    mode?: CheckOptions['mode'];
+    /**
+     * How permission and role conditions combine when both are provided.
+     * Default: `and` (must satisfy both).
+     */
+    combine?: 'and' | 'or';
+    children: ReactNode;
+    /** Fallback when access is denied. */
+    fallback?: ReactNode;
+}
+/**
+ * Conditionally render children based on permission / role.
+ *
+ * @example
+ * <Can permission="user:edit">
+ *   <button>Edit</button>
+ * </Can>
+ *
+ * <Can permission={['user:edit', 'user:delete']} mode="all" fallback={null}>
+ *   <AdminPanel />
+ * </Can>
+ */
+declare function Can({ permission, role, mode, combine, children, fallback, }: CanProps): react.JSX.Element;
+
+export { Can, type CanProps, type CheckOptions, type MatchMode, type PermissionChecker, type PermissionCode, type PermissionListener, PermissionProvider, type PermissionProviderProps, type PermissionState, PermissionStore, type RoleCode, type UsePermissionResult, createPermissionStore, useHasPermission, useHasRole, usePermission };

package/dist/react/index.js

@@ -0,0 +1,134 @@
+"use client";
+
+// src/react/context.tsx
+import {
+  createContext,
+  createElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState
+} from "react";
+import {
+  createPermissionStore
+} from "../core";
+var PermissionContext = createContext(null);
+function PermissionProvider({
+  children,
+  store: externalStore,
+  initialState
+}) {
+  const store = useMemo(
+    () => externalStore ?? createPermissionStore(initialState),
+    // store identity is intentional; initialState only applies on first create
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [externalStore]
+  );
+  return createElement(PermissionContext.Provider, { value: store }, children);
+}
+function useStore() {
+  const store = useContext(PermissionContext);
+  if (!store) {
+    throw new Error(
+      "[com-angel-authorization/react] usePermission* hooks must be used within <PermissionProvider>."
+    );
+  }
+  return store;
+}
+function usePermissionSnapshot(store) {
+  const [state, setState] = useState(() => store.getState());
+  useEffect(() => {
+    setState(store.getState());
+    return store.subscribe(setState);
+  }, [store]);
+  return state;
+}
+function usePermission() {
+  const store = useStore();
+  const state = usePermissionSnapshot(store);
+  const hasPermission = useCallback(
+    (codes, options) => store.hasPermission(codes, options),
+    [store]
+  );
+  const hasRole = useCallback(
+    (codes, options) => store.hasRole(codes, options),
+    [store]
+  );
+  const can = useCallback(
+    (codes, options) => store.can(codes, options),
+    [store]
+  );
+  return {
+    permissions: state.permissions,
+    roles: state.roles,
+    isSuperAdmin: Boolean(state.isSuperAdmin),
+    hasPermission,
+    hasRole,
+    can,
+    setPermissions: store.setPermissions.bind(store),
+    setRoles: store.setRoles.bind(store),
+    setSuperAdmin: store.setSuperAdmin.bind(store),
+    hydrate: store.hydrate.bind(store),
+    clear: store.clear.bind(store),
+    store
+  };
+}
+function useHasPermission(codes, options) {
+  const { hasPermission, permissions, isSuperAdmin } = usePermission();
+  void permissions;
+  void isSuperAdmin;
+  return hasPermission(codes, options);
+}
+function useHasRole(codes, options) {
+  const { hasRole, roles, isSuperAdmin } = usePermission();
+  void roles;
+  void isSuperAdmin;
+  return hasRole(codes, options);
+}
+
+// src/react/Can.tsx
+import { Fragment, jsx } from "react/jsx-runtime";
+function evaluateAccess(hasPermission, hasRole, props) {
+  const { permission, role, mode, combine = "and" } = props;
+  const options = { mode };
+  const hasPermCheck = permission !== void 0;
+  const hasRoleCheck = role !== void 0;
+  if (!hasPermCheck && !hasRoleCheck) return true;
+  const permOk = hasPermCheck ? hasPermission(permission, options) : true;
+  const roleOk = hasRoleCheck ? hasRole(role, options) : true;
+  if (hasPermCheck && hasRoleCheck) {
+    return combine === "or" ? permOk || roleOk : permOk && roleOk;
+  }
+  return hasPermCheck ? permOk : roleOk;
+}
+function Can({
+  permission,
+  role,
+  mode,
+  combine,
+  children,
+  fallback = null
+}) {
+  const { hasPermission, hasRole } = usePermission();
+  const allowed = evaluateAccess(hasPermission, hasRole, {
+    permission,
+    role,
+    mode,
+    combine
+  });
+  return /* @__PURE__ */ jsx(Fragment, { children: allowed ? children : fallback });
+}
+
+// src/react/index.ts
+import { PermissionStore, createPermissionStore as createPermissionStore2 } from "../core";
+export {
+  Can,
+  PermissionProvider,
+  PermissionStore,
+  createPermissionStore2 as createPermissionStore,
+  useHasPermission,
+  useHasRole,
+  usePermission
+};
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/react/context.tsx","../../src/react/Can.tsx","../../src/react/index.ts"],"sourcesContent":["import {\n  createContext,\n  createElement,\n  useCallback,\n  useContext,\n  useEffect,\n  useMemo,\n  useState,\n  type ReactNode,\n} from 'react';\nimport {\n  createPermissionStore,\n  type CheckOptions,\n  type PermissionCode,\n  type PermissionState,\n  type PermissionStore,\n  type RoleCode,\n} from '../core';\n\nconst PermissionContext = createContext<PermissionStore | null>(null);\n\nexport interface PermissionProviderProps {\n  children: ReactNode;\n  /** Pass an existing store to share across trees, or omit to create one. */\n  store?: PermissionStore;\n  /** Initial state when the provider creates its own store. */\n  initialState?: Partial<PermissionState>;\n}\n\nexport function PermissionProvider({\n  children,\n  store: externalStore,\n  initialState,\n}: PermissionProviderProps) {\n  const store = useMemo(\n    () => externalStore ?? createPermissionStore(initialState),\n    // store identity is intentional; initialState only applies on first create\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    [externalStore],\n  );\n\n  return createElement(PermissionContext.Provider, { value: store }, children);\n}\n\nfunction useStore(): PermissionStore {\n  const store = useContext(PermissionContext);\n  if (!store) {\n    throw new Error(\n      '[com-angel-authorization/react] usePermission* hooks must be used within <PermissionProvider>.',\n    );\n  }\n  return store;\n}\n\nfunction usePermissionSnapshot(store: PermissionStore): PermissionState {\n  const [state, setState] = useState(() => store.getState());\n\n  useEffect(() => {\n    setState(store.getState());\n    return store.subscribe(setState);\n  }, [store]);\n\n  return state;\n}\n\nexport interface UsePermissionResult {\n  permissions: PermissionCode[];\n  roles: RoleCode[];\n  isSuperAdmin: boolean;\n  hasPermission: (codes: PermissionCode | PermissionCode[], options?: CheckOptions) => boolean;\n  hasRole: (codes: RoleCode | RoleCode[], options?: CheckOptions) => boolean;\n  can: (codes: PermissionCode | PermissionCode[], options?: CheckOptions) => boolean;\n  setPermissions: (permissions: PermissionCode[]) => void;\n  setRoles: (roles: RoleCode[]) => void;\n  setSuperAdmin: (isSuperAdmin: boolean) => void;\n  hydrate: (payload: Partial<PermissionState>) => void;\n  clear: () => void;\n  store: PermissionStore;\n}\n\nexport function usePermission(): UsePermissionResult {\n  const store = useStore();\n  const state = usePermissionSnapshot(store);\n\n  const hasPermission = useCallback(\n    (codes: PermissionCode | PermissionCode[], options?: CheckOptions) =>\n      store.hasPermission(codes, options),\n    [store],\n  );\n\n  const hasRole = useCallback(\n    (codes: RoleCode | RoleCode[], options?: CheckOptions) => store.hasRole(codes, options),\n    [store],\n  );\n\n  const can = useCallback(\n    (codes: PermissionCode | PermissionCode[], options?: CheckOptions) => store.can(codes, options),\n    [store],\n  );\n\n  return {\n    permissions: state.permissions,\n    roles: state.roles,\n    isSuperAdmin: Boolean(state.isSuperAdmin),\n    hasPermission,\n    hasRole,\n    can,\n    setPermissions: store.setPermissions.bind(store),\n    setRoles: store.setRoles.bind(store),\n    setSuperAdmin: store.setSuperAdmin.bind(store),\n    hydrate: store.hydrate.bind(store),\n    clear: store.clear.bind(store),\n    store,\n  };\n}\n\n/** Returns whether the current user has the given permission(s). */\nexport function useHasPermission(\n  codes: PermissionCode | PermissionCode[],\n  options?: CheckOptions,\n): boolean {\n  const { hasPermission, permissions, isSuperAdmin } = usePermission();\n  // re-compute when permission list / super-admin changes\n  void permissions;\n  void isSuperAdmin;\n  return hasPermission(codes, options);\n}\n\n/** Returns whether the current user has the given role(s). */\nexport function useHasRole(\n  codes: RoleCode | RoleCode[],\n  options?: CheckOptions,\n): boolean {\n  const { hasRole, roles, isSuperAdmin } = usePermission();\n  void roles;\n  void isSuperAdmin;\n  return hasRole(codes, options);\n}\n","import type { ReactNode } from 'react';\nimport type { CheckOptions, PermissionCode, RoleCode } from '../core';\nimport { usePermission } from './context';\n\nexport interface CanProps {\n  /** Permission codes to check. */\n  permission?: PermissionCode | PermissionCode[];\n  /** Role codes to check. */\n  role?: RoleCode | RoleCode[];\n  /**\n   * `any` — pass when at least one code matches (default)\n   * `all` — pass only when every code matches\n   */\n  mode?: CheckOptions['mode'];\n  /**\n   * How permission and role conditions combine when both are provided.\n   * Default: `and` (must satisfy both).\n   */\n  combine?: 'and' | 'or';\n  children: ReactNode;\n  /** Fallback when access is denied. */\n  fallback?: ReactNode;\n}\n\nfunction evaluateAccess(\n  hasPermission: (c: PermissionCode | PermissionCode[], o?: CheckOptions) => boolean,\n  hasRole: (c: RoleCode | RoleCode[], o?: CheckOptions) => boolean,\n  props: Pick<CanProps, 'permission' | 'role' | 'mode' | 'combine'>,\n): boolean {\n  const { permission, role, mode, combine = 'and' } = props;\n  const options: CheckOptions = { mode };\n\n  const hasPermCheck = permission !== undefined;\n  const hasRoleCheck = role !== undefined;\n\n  if (!hasPermCheck && !hasRoleCheck) return true;\n\n  const permOk = hasPermCheck ? hasPermission(permission!, options) : true;\n  const roleOk = hasRoleCheck ? hasRole(role!, options) : true;\n\n  if (hasPermCheck && hasRoleCheck) {\n    return combine === 'or' ? permOk || roleOk : permOk && roleOk;\n  }\n\n  return hasPermCheck ? permOk : roleOk;\n}\n\n/**\n * Conditionally render children based on permission / role.\n *\n * @example\n * <Can permission=\"user:edit\">\n *   <button>Edit</button>\n * </Can>\n *\n * <Can permission={['user:edit', 'user:delete']} mode=\"all\" fallback={null}>\n *   <AdminPanel />\n * </Can>\n */\nexport function Can({\n  permission,\n  role,\n  mode,\n  combine,\n  children,\n  fallback = null,\n}: CanProps) {\n  const { hasPermission, hasRole } = usePermission();\n  const allowed = evaluateAccess(hasPermission, hasRole, {\n    permission,\n    role,\n    mode,\n    combine,\n  });\n\n  return <>{allowed ? children : fallback}</>;\n}\n","export { PermissionProvider, usePermission, useHasPermission, useHasRole } from './context';\nexport type { PermissionProviderProps, UsePermissionResult } from './context';\n\nexport { Can } from './Can';\nexport type { CanProps } from './Can';\n\nexport type {\n  CheckOptions,\n  MatchMode,\n  PermissionChecker,\n  PermissionCode,\n  PermissionListener,\n  PermissionState,\n  RoleCode,\n} from '../core';\n\nexport { PermissionStore, createPermissionStore } from '../core';\n"],"mappings":"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","names":["createPermissionStore"]}