@nocobase/portal-template-default 1.0.8 → 1.0.10

package/src/components/auth/auto-redirect-provider.tsx

@@ -3,6 +3,7 @@ import { useLocation } from "react-router";
 
 import { LoadingState } from "@/components/app-shell/loading-state";
 import { nocobaseClient } from "@/lib/nocobase/client";
+import { resolvePortalUrl } from "@/providers/runtime-config";
 
 type AutoRedirectResponse = {
   success?: boolean;
@@ -32,7 +33,7 @@ export function AuthAutoRedirectProvider({
 }: AuthAutoRedirectProviderProps) {
   const { pathname, search } = useLocation();
   const attemptedRef = useRef(false);
-  const redirect = `${pathname}${search}`;
+  const redirect = resolvePortalUrl(`${pathname}${search}`);
   const shouldCheck =
     enabled &&
     !nocobaseClient.getToken() &&

package/src/extensions/nocobase-acl/README.md

@@ -0,0 +1,74 @@
+# NocoBase ACL UI
+
+Reusable ACL composition components for the NocoBase Refine starter.
+
+After installation, import the components from `@/extensions/nocobase-acl`.
+
+- The Starter's `CanAccess` supports role, resource, record, and field checks.
+- `AclPage` combines page-level permissions.
+- `AclRegion` hides or replaces individual data regions.
+- `AclField` applies NocoBase field whitelists.
+- `RoleSwitcher` can be placed in any application surface. It supports
+  normal roles, Anonymous when enabled, and Full permissions through the
+  `__union__` role when the system role mode allows it.
+
+Route resource metadata and `AclPage` accept a `roles` constraint with `anyOf`,
+`allOf`, and `noneOf`. Role constraints use the roles in the current effective
+ACL context. In union mode this is the set of roles participating in the union;
+in single-role mode it is only the selected role. Regions, fields, and actions
+continue to use resource permissions.
+
+Use the Starter's `useGetRoles()` hook when application UI needs the same
+effective role names. Its result follows the familiar Refine query shape with
+`data`, `isLoading`, `isPending`, `isError`, and `error`. `data` is the active
+ACL role set, not every role assigned to the signed-in user.
+
+```tsx
+import { useGetRoles } from "@/lib/nocobase/acl";
+
+function CurrentAccessContext() {
+  const { data: roles, isLoading } = useGetRoles();
+
+  if (isLoading) return null;
+  return <span>Effective roles: {roles?.join(", ")}</span>;
+}
+```
+
+```tsx
+const adminRoute = {
+  name: "administration",
+  meta: {
+    acl: {
+      type: "authenticated",
+      roles: { anyOf: ["admin"] },
+    },
+  },
+};
+
+function AuditLogsRoute() {
+  return (
+    <AclPage roles={{ anyOf: ["admin", "auditor"] }}>
+      <AclRegion resource="auditLogs" action="list">
+        <AuditLogTable />
+      </AclRegion>
+    </AclPage>
+  );
+}
+```
+
+Mark non-collection resources with `meta.acl.type = "authenticated"`, or use
+the `collection`, `snippet`, and `route` ACL metadata variants when the resource
+should participate in NocoBase permission checks.
+
+The underlying `accessControlProvider`, `roles:check` cache, record permissions,
+and Refine integration are provided by the compatible Starter.
+
+The Demo uses the real `CanAccess`, `AclPage`, `AclRegion`, and `AclField`
+components. A local `AclPreviewProvider` supplies a static in-memory ACL store
+so both allowed and restricted outcomes remain visible without changing the
+current user's real roles. It does not replace Refine's access-control context.
+Applications use the Starter's root `AclStoreProvider` and production `aclStore`.
+
+Global ACL permissions remain fixed for one page session. Switching roles saves
+the selected role and reloads the page so navigation, routes, data access, and
+Refine permission queries all start from the same `roles:check` result.

package/{registry → src/extensions}/nocobase-acl/components/acl-boundary.tsx

@@ -2,10 +2,8 @@ import type { BaseKey } from "@refinedev/core";
 import type { PropsWithChildren, ReactNode } from "react";
 
 import { AccessDenied } from "@/components/access-control/access-denied";
-import {
-  canAccessWithSnapshot,
-  useAclSnapshot,
-} from "@/lib/nocobase/acl";
+import { useAclEvaluator } from "@/lib/nocobase/acl";
+import type { RoleConstraint } from "@/lib/nocobase/acl";
 
 export type AclPermission = {
   resource: string;
@@ -18,6 +16,7 @@ export type AclPermission = {
 export type AclPageProps = PropsWithChildren<{
   anyOf?: AclPermission[];
   allOf?: AclPermission[];
+  roles?: RoleConstraint;
   fallback?: ReactNode;
 }>;
 
@@ -35,31 +34,29 @@ export type AclFieldProps = PropsWithChildren<{
   fallback?: ReactNode;
 }>;
 
-const canAccess = (
-  snapshot: ReturnType<typeof useAclSnapshot>,
-  permission: AclPermission
-) =>
-  canAccessWithSnapshot(snapshot, {
-    resource: permission.resource,
-    action: permission.action,
-    params: {
-      id: permission.id,
-      field: permission.field,
-      dataSourceKey: permission.dataSourceKey,
-    },
-  });
+const toAccessRequest = (permission: AclPermission) => ({
+  resource: permission.resource,
+  action: permission.action,
+  id: permission.id,
+  field: permission.field,
+  dataSourceKey: permission.dataSourceKey,
+});
 
 export function AclPage({
   children,
   anyOf,
   allOf,
+  roles,
   fallback = <AccessDenied />,
 }: AclPageProps) {
-  const snapshot = useAclSnapshot();
-  const anyAllowed = !anyOf?.length || anyOf.some((item) => canAccess(snapshot, item));
-  const allAllowed = !allOf?.length || allOf.every((item) => canAccess(snapshot, item));
+  const canAccess = useAclEvaluator();
+  const anyAllowed =
+    !anyOf?.length || anyOf.some((item) => canAccess(toAccessRequest(item)));
+  const allAllowed =
+    !allOf?.length || allOf.every((item) => canAccess(toAccessRequest(item)));
+  const roleAllowed = canAccess({ roles });
 
-  return anyAllowed && allAllowed ? children : fallback;
+  return roleAllowed && anyAllowed && allAllowed ? children : fallback;
 }
 
 export function AclRegion({
@@ -70,8 +67,8 @@ export function AclRegion({
   dataSourceKey,
   fallback = "hidden",
 }: AclRegionProps) {
-  const snapshot = useAclSnapshot();
-  const allowed = canAccess(snapshot, {
+  const canAccess = useAclEvaluator();
+  const allowed = canAccess({
     resource,
     action,
     id,
@@ -94,8 +91,8 @@ export function AclField({
   dataSourceKey,
   fallback = null,
 }: AclFieldProps) {
-  const snapshot = useAclSnapshot();
-  return canAccess(snapshot, {
+  const canAccess = useAclEvaluator();
+  return canAccess({
     resource,
     action,
     field,

package/{registry → src/extensions}/nocobase-acl/components/role-switcher.tsx

@@ -13,7 +13,7 @@ import {
 } from "@/components/ui/select";
 import {
   switchRole,
-  useAclSnapshot,
+  useAclState,
   type AclIdentity,
   type Role,
 } from "@/lib/nocobase/acl";
@@ -34,24 +34,41 @@ export function RoleSwitcher({
   showWhenUnavailable = false,
 }: RoleSwitcherProps) {
   const { data: identity, isLoading } = useGetIdentity<AclIdentity>();
-  const acl = useAclSnapshot();
+  const acl = useAclState();
   const [switching, setSwitching] = useState(false);
   const [error, setError] = useState<string>();
+  const permissions = acl.status === "ready" ? acl.permissions : undefined;
 
   const roles = useMemo(
     () =>
       getRoleOptions({
         roles: identity?.roles ?? [],
-        roleMode: acl.data.roleMode,
-        allowAnonymous: acl.data.allowAnonymous,
+        roleMode: permissions?.roleMode,
+        allowAnonymous: permissions?.allowAnonymous,
       }),
-    [acl.data.allowAnonymous, acl.data.roleMode, identity?.roles]
+    [identity?.roles, permissions?.allowAnonymous, permissions?.roleMode]
   );
 
-  const currentRole = acl.data.role ?? roles[0]?.name;
-  const canSwitch = roles.length > 1 && acl.data.roleMode !== "only-use-union";
+  const currentRole = permissions?.currentRole ?? roles[0]?.name;
+  const canSwitch =
+    roles.length > 1 && permissions?.roleMode !== "only-use-union";
 
-  if (isLoading) {
+  const handleRoleChange = async (value: string | null) => {
+    if (!value || value === currentRole) return;
+    setSwitching(true);
+    setError(undefined);
+    try {
+      await switchRole(value);
+      window.location.reload();
+    } catch (reason) {
+      setError(
+        reason instanceof Error ? reason.message : "Unable to switch role"
+      );
+      setSwitching(false);
+    }
+  };
+
+  if (isLoading || acl.status === "idle" || acl.status === "loading") {
     return <Loader2 className="size-4 animate-spin text-muted-foreground" />;
   }
   if (!canSwitch && !showWhenUnavailable) return null;
@@ -74,21 +91,7 @@ export function RoleSwitcher({
       <Select
         value={currentRole}
         disabled={switching}
-        onValueChange={(value) => {
-          if (!value || value === currentRole) return;
-          setSwitching(true);
-          setError(undefined);
-          void switchRole(value, { reloadAcl: false })
-            .then(() => window.location.reload())
-            .catch((reason) => {
-              setError(
-                reason instanceof Error
-                  ? reason.message
-                  : "Unable to switch role"
-              );
-              setSwitching(false);
-            });
-        }}
+        onValueChange={handleRoleChange}
       >
         <SelectTrigger
           className={cn("w-full min-w-52", triggerClassName)}

package/src/extensions/nocobase-acl/demo/acl-preview-provider.tsx

@@ -0,0 +1,81 @@
+import { useMemo, type PropsWithChildren } from "react";
+
+import {
+  AclStoreProvider,
+  type AclActionParams,
+  type AclState,
+  type AclStore,
+} from "@/lib/nocobase/acl";
+
+type PreviewRecordPermission = {
+  dataSourceKey?: string;
+  resource: string;
+  action: string;
+  id: string | number;
+  allowed: boolean;
+};
+
+export type AclPreviewProviderProps = PropsWithChildren<{
+  roles: string[];
+  permissions?: Record<string, AclActionParams>;
+  recordPermissions?: PreviewRecordPermission[];
+}>;
+
+export function AclPreviewProvider({
+  children,
+  roles,
+  permissions = {},
+  recordPermissions = [],
+}: AclPreviewProviderProps) {
+  const store = useMemo<AclStore>(() => {
+    const resources = Array.from(
+      new Set(
+        Object.keys(permissions).map((permission) =>
+          permission.slice(0, permission.lastIndexOf(":"))
+        )
+      )
+    );
+    const state: AclState = {
+      status: "ready",
+      permissions: {
+        currentRole: roles.length > 1 ? "__union__" : roles[0],
+        roles,
+        roleMode: roles.length > 1 ? "allow-use-union" : "default",
+        resources,
+        actions: permissions,
+        actionAlias: {
+          list: "list",
+          get: "get",
+          create: "create",
+          update: "update",
+          destroy: "destroy",
+        },
+        snippets: [],
+      },
+    };
+    const recordState = new Map(
+      recordPermissions.map((permission) => [
+        `${permission.dataSourceKey ?? "main"}:${permission.resource}:${
+          permission.action
+        }:${permission.id}`,
+        permission.allowed,
+      ])
+    );
+
+    return {
+      getState: () => state,
+      subscribe: () => () => undefined,
+      load: async () => state,
+      retry: async () => state,
+      clear: () => undefined,
+      recordPermissions: {
+        getState: () => recordState,
+        subscribe: () => () => undefined,
+        getPermission: ({ dataSourceKey = "main", resource, action, id }) =>
+          recordState.get(`${dataSourceKey}:${resource}:${action}:${id}`),
+      },
+    };
+  }, [permissions, recordPermissions, roles]);
+
+  return <AclStoreProvider store={store}>{children}</AclStoreProvider>;
+}

package/{registry → src/extensions}/nocobase-acl/demo/boundary-api.tsx

@@ -15,6 +15,33 @@ type PropRow = [
   description: string
 ];
 
+const canAccessProps: PropRow[] = [
+  [
+    "roles",
+    "RoleConstraint",
+    "undefined",
+    "Checks the current effective roles with anyOf, allOf, and noneOf.",
+  ],
+  [
+    "resource / action",
+    "string",
+    "undefined",
+    "Checks a NocoBase resource action. When roles are also present, both checks must pass.",
+  ],
+  [
+    "id / field",
+    "BaseKey / string",
+    "undefined",
+    "Optionally narrows the decision to one record or field.",
+  ],
+  [
+    "fallback",
+    "ReactNode",
+    "null",
+    "Renders when the access request is denied.",
+  ],
+];
+
 const pageProps: PropRow[] = [
   [
     "anyOf",
@@ -28,6 +55,12 @@ const pageProps: PropRow[] = [
     "undefined",
     "Requires every listed permission before rendering the page.",
   ],
+  [
+    "roles",
+    "RoleConstraint",
+    "undefined",
+    "Requires the current effective roles to match anyOf, allOf, and noneOf constraints.",
+  ],
   [
     "fallback",
     "ReactNode",
@@ -100,6 +133,21 @@ const fieldProps: PropRow[] = [
   ["children", "ReactNode", "required", "The protected field or field group."],
 ];
 
+const runtimeApis: PropRow[] = [
+  [
+    "AclStoreProvider",
+    "{ store, children }",
+    "required",
+    "Connects React ACL hooks and components to the application aclStore. The Starter mounts it at the application root.",
+  ],
+  [
+    "useGetRoles",
+    "() => QueryResult<string[]>",
+    "-",
+    "Returns the current effective ACL role names, including all participating roles in union mode.",
+  ],
+];
+
 export function AclBoundaryApi() {
   return (
     <section className="space-y-5 border-t pt-8">
@@ -116,6 +164,11 @@ export function AclBoundaryApi() {
         </p>
       </div>
       <div className="space-y-7">
+        <ComponentApi
+          title="CanAccess"
+          description="The Starter access boundary for role-only, resource-only, or combined permission checks."
+          rows={canAccessProps}
+        />
         <ComponentApi
           title="AclPage"
           description="Protects a complete route or business page. This corresponds to the Page permission pattern above."
@@ -131,6 +184,11 @@ export function AclBoundaryApi() {
           description="Protects one field or field group. This corresponds to the Field permission pattern."
           rows={fieldProps}
         />
+        <ComponentApi
+          title="ACL context APIs"
+          description="Read the active role context from the application ACL store. Demo previews use an isolated in-memory store with the same evaluator."
+          rows={runtimeApis}
+        />
       </div>
     </section>
   );