@nocobase/portal-template-default 1.0.1 → 1.0.3

package/src/components/resources/views/edit-view.tsx

@@ -1,16 +1,13 @@
 "use client";
 
 import { cn } from "@/lib/utils";
-import {
-  useBack,
-  useResourceParams,
-  useUserFriendlyName,
-} from "@refinedev/core";
+import { useBack, useResourceParams, useTranslate } from "@refinedev/core";
 import type { PropsWithChildren } from "react";
 import { Breadcrumb } from "@/components/app-shell/breadcrumb";
 import { Button } from "@/components/ui/button";
 import { RefreshButton } from "@/components/resources/buttons/refresh";
 import { ArrowLeftIcon } from "lucide-react";
+import { useResourceLabel } from "@/components/resources/resource-label";
 
 type EditViewProps = PropsWithChildren<{
   className?: string;
@@ -41,8 +38,7 @@ export const EditViewHeader = ({
   headerClassName,
 }: EditViewHeaderProps) => {
   const back = useBack();
-
-  const getUserFriendlyName = useUserFriendlyName();
+  const translate = useTranslate();
 
   const { resource, identifier } = useResourceParams({
     resource: resourceFromProps,
@@ -51,11 +47,19 @@ export const EditViewHeader = ({
 
   const resourceName = resource?.name ?? identifier;
 
-  const resourceTitle = getUserFriendlyName(
-    resource?.meta?.label ?? identifier ?? resource?.name,
-    "singular"
+  const resourceTitle = useResourceLabel(resource, "singular", identifier);
+  const title =
+    titleFromProps ??
+    translate(
+      "views.edit.title",
+      { resource: resourceTitle },
+      `Edit ${resourceTitle}`
+    );
+  const description = translate(
+    "views.edit.description",
+    { resource: resourceTitle.toLocaleLowerCase() },
+    `Update this ${resourceTitle.toLocaleLowerCase()} while NocoBase keeps the data consistent.`
   );
-  const title = titleFromProps ?? `Edit ${resourceTitle}`;
 
   return (
     <div className={cn("flex flex-col", "gap-3", wrapperClassName)}>
@@ -74,6 +78,7 @@ export const EditViewHeader = ({
             size="icon"
             className="mt-0.5 rounded-lg"
             onClick={back}
+            aria-label={translate("buttons.cancel", "Cancel")}
           >
             <ArrowLeftIcon className="h-4 w-4" />
           </Button>
@@ -81,10 +86,7 @@ export const EditViewHeader = ({
             <h2 className="text-3xl font-semibold tracking-[-0.035em]">
               {title}
             </h2>
-            <p className="mt-2 text-sm text-muted-foreground">
-              Update this {resourceTitle.toLowerCase()} while NocoBase keeps
-              the data consistent.
-            </p>
+            <p className="mt-2 text-sm text-muted-foreground">{description}</p>
           </div>
         </div>
 

package/src/components/resources/views/list-view.tsx

@@ -2,9 +2,11 @@
 
 import type { PropsWithChildren } from "react";
 
-import { useResourceParams, useUserFriendlyName } from "@refinedev/core";
+import { useResourceParams, useTranslate } from "@refinedev/core";
 import { Breadcrumb } from "@/components/app-shell/breadcrumb";
 import { CreateButton } from "@/components/resources/buttons/create";
+import { useResourceLabel } from "@/components/resources/resource-label";
+import { resolveTranslatableText, type TranslationOptions } from "@/lib/i18n";
 import { cn } from "@/lib/utils";
 
 type ListViewProps = PropsWithChildren<{
@@ -35,22 +37,30 @@ export const ListViewHeader = ({
   wrapperClassName,
   headerClassName,
 }: ListHeaderProps) => {
-  const getUserFriendlyName = useUserFriendlyName();
-
   const { resource, identifier } = useResourceParams({
     resource: resourceFromProps,
   });
+  const translate = useTranslate();
   const resourceName = identifier ?? resource?.name;
 
   const isCreateButtonVisible = canCreate ?? !!resource?.create;
 
-  const title =
-    titleFromProps ??
-    getUserFriendlyName(
-      resource?.meta?.label ?? identifier ?? resource?.name,
-      "plural"
-    );
-  const description = resource?.meta?.description as string | undefined;
+  const resourceTitle = useResourceLabel(resource, "plural", identifier);
+  const title = titleFromProps ?? resourceTitle;
+  const meta = resource?.meta as
+    | {
+        description?: string;
+        descriptionI18nKey?: string;
+        i18nOptions?: TranslationOptions;
+      }
+    | undefined;
+  const description = meta?.descriptionI18nKey
+    ? translate(
+        meta.descriptionI18nKey,
+        meta.i18nOptions,
+        meta.description ?? meta.descriptionI18nKey
+      )
+    : resolveTranslatableText(meta?.description);
 
   return (
     <div className={cn("flex flex-col", "gap-3", wrapperClassName)}>

package/src/components/resources/views/show-view.tsx

@@ -3,25 +3,29 @@
 import type { PropsWithChildren } from "react";
 
 import { ArrowLeftIcon } from "lucide-react";
-import {
-  useBack,
-  useResourceParams,
-  useUserFriendlyName,
-} from "@refinedev/core";
+import { useBack, useResourceParams, useTranslate } from "@refinedev/core";
 import { Breadcrumb } from "@/components/app-shell/breadcrumb";
 import { Button } from "@/components/ui/button";
 import { RefreshButton } from "@/components/resources/buttons/refresh";
 import { cn } from "@/lib/utils";
 import { EditButton } from "../buttons/edit";
+import { useResourceLabel } from "@/components/resources/resource-label";
 
 type ShowViewProps = PropsWithChildren<{
   className?: string;
+  resource?: string;
+  title?: string;
 }>;
 
-export function ShowView({ children, className }: ShowViewProps) {
+export function ShowView({
+  children,
+  className,
+  resource,
+  title,
+}: ShowViewProps) {
   return (
     <div className={cn("flex flex-col", "gap-6", className)}>
-      <ShowViewHeader />
+      <ShowViewHeader resource={resource} title={title} />
       {children}
     </div>
   );
@@ -41,8 +45,7 @@ export const ShowViewHeader = ({
   headerClassName,
 }: ShowViewHeaderProps) => {
   const back = useBack();
-
-  const getUserFriendlyName = useUserFriendlyName();
+  const translate = useTranslate();
 
   const { resource, identifier } = useResourceParams({
     resource: resourceFromProps,
@@ -51,12 +54,12 @@ export const ShowViewHeader = ({
 
   const resourceName = resource?.name ?? identifier;
 
-  const title =
-    titleFromProps ??
-    getUserFriendlyName(
-      resource?.meta?.label ?? identifier ?? resource?.name,
-      "singular"
-    );
+  const resourceTitle = useResourceLabel(resource, "singular", identifier);
+  const title = titleFromProps ?? resourceTitle;
+  const description = translate(
+    "views.show.description",
+    "Review the record and its NocoBase-managed data."
+  );
 
   return (
     <div className={cn("flex flex-col", "gap-3", wrapperClassName)}>
@@ -75,6 +78,7 @@ export const ShowViewHeader = ({
             size="icon"
             className="mt-0.5 rounded-lg"
             onClick={back}
+            aria-label={translate("buttons.cancel", "Cancel")}
           >
             <ArrowLeftIcon className="h-4 w-4" />
           </Button>
@@ -82,9 +86,7 @@ export const ShowViewHeader = ({
             <h2 className="text-3xl font-semibold tracking-[-0.035em]">
               {title}
             </h2>
-            <p className="mt-2 text-sm text-muted-foreground">
-              Review the record and its NocoBase-managed data.
-            </p>
+            <p className="mt-2 text-sm text-muted-foreground">{description}</p>
           </div>
         </div>
 

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

@@ -0,0 +1,19 @@
+# NocoBase ACL UI
+
+Reusable ACL composition components for the NocoBase Refine starter.
+
+After installation, import the components from `@/extensions/nocobase-acl`.
+
+- `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.
+
+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.

package/src/extensions/nocobase-acl/components/acl-boundary.tsx

@@ -0,0 +1,106 @@
+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";
+
+export type AclPermission = {
+  resource: string;
+  action: string;
+  id?: BaseKey;
+  field?: string;
+  dataSourceKey?: string;
+};
+
+export type AclPageProps = PropsWithChildren<{
+  anyOf?: AclPermission[];
+  allOf?: AclPermission[];
+  fallback?: ReactNode;
+}>;
+
+export type AclRegionProps = PropsWithChildren<
+  Omit<AclPermission, "field"> & {
+    fallback?: "hidden" | "forbidden" | ReactNode;
+  }
+>;
+
+export type AclFieldProps = PropsWithChildren<{
+  resource: string;
+  action: string;
+  field: string;
+  dataSourceKey?: string;
+  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,
+    },
+  });
+
+export function AclPage({
+  children,
+  anyOf,
+  allOf,
+  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));
+
+  return anyAllowed && allAllowed ? children : fallback;
+}
+
+export function AclRegion({
+  children,
+  resource,
+  action,
+  id,
+  dataSourceKey,
+  fallback = "hidden",
+}: AclRegionProps) {
+  const snapshot = useAclSnapshot();
+  const allowed = canAccess(snapshot, {
+    resource,
+    action,
+    id,
+    dataSourceKey,
+  });
+
+  if (allowed) return children;
+  if (fallback === "hidden") return null;
+  if (fallback === "forbidden") {
+    return <AccessDenied className="min-h-40" />;
+  }
+  return fallback;
+}
+
+export function AclField({
+  children,
+  resource,
+  action,
+  field,
+  dataSourceKey,
+  fallback = null,
+}: AclFieldProps) {
+  const snapshot = useAclSnapshot();
+  return canAccess(snapshot, {
+    resource,
+    action,
+    field,
+    dataSourceKey,
+  })
+    ? children
+    : fallback;
+}

package/src/extensions/nocobase-acl/components/index.ts

@@ -0,0 +1,3 @@
+export * from "./acl-boundary";
+export * from "./role-options";
+export * from "./role-switcher";

package/src/extensions/nocobase-acl/components/role-options.ts

@@ -0,0 +1,36 @@
+import type { Role, RoleMode } from "@/lib/nocobase/acl";
+import { resolveTranslatableText } from "@/lib/i18n";
+
+export const UNION_ROLE = "__union__";
+export const ANONYMOUS_ROLE = "anonymous";
+
+export function resolveRoleTitle(role?: Role) {
+  return resolveTranslatableText(role?.title || role?.name || "Role", {
+    ns: "starter",
+  });
+}
+
+export function getRoleOptions({
+  roles,
+  roleMode,
+  allowAnonymous = false,
+}: {
+  roles: Role[];
+  roleMode?: RoleMode;
+  allowAnonymous?: boolean;
+}) {
+  if (roleMode === "only-use-union") {
+    return [{ name: UNION_ROLE, title: "Full permissions" }];
+  }
+
+  const options = roles.filter(
+    (role) => role.name !== UNION_ROLE && role.name !== ANONYMOUS_ROLE
+  );
+  if (allowAnonymous) {
+    options.push({ name: ANONYMOUS_ROLE, title: "Anonymous" });
+  }
+  if (roleMode === "allow-use-union") {
+    options.unshift({ name: UNION_ROLE, title: "Full permissions" });
+  }
+  return options;
+}

package/src/extensions/nocobase-acl/components/role-switcher.tsx

@@ -0,0 +1,135 @@
+import { useGetIdentity } from "@refinedev/core";
+import { Loader2, ShieldCheck } from "lucide-react";
+import { useMemo, useState, type ReactNode } from "react";
+
+import { Badge } from "@/components/ui/badge";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import {
+  switchRole,
+  useAclSnapshot,
+  type AclIdentity,
+  type Role,
+} from "@/lib/nocobase/acl";
+import { cn } from "@/lib/utils";
+import { getRoleOptions, resolveRoleTitle, UNION_ROLE } from "./role-options";
+
+export type RoleSwitcherProps = {
+  className?: string;
+  triggerClassName?: string;
+  label?: ReactNode | false;
+  showWhenUnavailable?: boolean;
+};
+
+export function RoleSwitcher({
+  className,
+  triggerClassName,
+  label = "Switch role",
+  showWhenUnavailable = false,
+}: RoleSwitcherProps) {
+  const { data: identity, isLoading } = useGetIdentity<AclIdentity>();
+  const acl = useAclSnapshot();
+  const [switching, setSwitching] = useState(false);
+  const [error, setError] = useState<string>();
+
+  const roles = useMemo(
+    () =>
+      getRoleOptions({
+        roles: identity?.roles ?? [],
+        roleMode: acl.data.roleMode,
+        allowAnonymous: acl.data.allowAnonymous,
+      }),
+    [acl.data.allowAnonymous, acl.data.roleMode, identity?.roles]
+  );
+
+  const currentRole = acl.data.role ?? roles[0]?.name;
+  const canSwitch = roles.length > 1 && acl.data.roleMode !== "only-use-union";
+
+  if (isLoading) {
+    return <Loader2 className="size-4 animate-spin text-muted-foreground" />;
+  }
+  if (!canSwitch && !showWhenUnavailable) return null;
+
+  if (!canSwitch) {
+    return (
+      <div className={cn("flex items-center gap-2 text-sm", className)}>
+        <ShieldCheck className="size-4 text-muted-foreground" />
+        <span className="text-muted-foreground">Current role</span>
+        <Badge variant="secondary">{getRoleTitle(roles, currentRole)}</Badge>
+      </div>
+    );
+  }
+
+  return (
+    <div className={cn("space-y-2", className)}>
+      {label === false ? null : (
+        <p className="text-xs font-medium text-muted-foreground">{label}</p>
+      )}
+      <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);
+            });
+        }}
+      >
+        <SelectTrigger
+          className={cn("w-full min-w-52", triggerClassName)}
+          aria-label="Switch role"
+        >
+          {switching ? <Loader2 className="animate-spin" /> : <ShieldCheck />}
+          <SelectValue>{getRoleTitle(roles, currentRole)}</SelectValue>
+        </SelectTrigger>
+        <SelectContent>
+          {roles.map((role, index) => (
+            <RoleOption
+              key={role.name}
+              role={role}
+              showSeparator={index === 1 && roles[0]?.name === UNION_ROLE}
+            />
+          ))}
+        </SelectContent>
+      </Select>
+      {error ? <p className="text-xs text-destructive">{error}</p> : null}
+    </div>
+  );
+}
+
+function RoleOption({
+  role,
+  showSeparator,
+}: {
+  role: Role;
+  showSeparator: boolean;
+}) {
+  return (
+    <>
+      {showSeparator ? <SelectSeparator /> : null}
+      <SelectItem value={role.name}>{resolveRoleTitle(role)}</SelectItem>
+    </>
+  );
+}
+
+function getRoleTitle(roles: Role[], roleName?: string) {
+  return resolveRoleTitle(
+    roles.find((role) => role.name === roleName) ??
+      (roleName ? { name: roleName } : undefined)
+  );
+}

package/src/extensions/nocobase-acl/demo/boundary-api.tsx

@@ -0,0 +1,186 @@
+import { Card } from "@/components/ui/card";
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from "@/components/ui/table";
+
+type PropRow = [
+  name: string,
+  type: string,
+  defaultValue: string,
+  description: string
+];
+
+const pageProps: PropRow[] = [
+  [
+    "anyOf",
+    "AclPermission[]",
+    "undefined",
+    "Allows the page when any listed permission is available.",
+  ],
+  [
+    "allOf",
+    "AclPermission[]",
+    "undefined",
+    "Requires every listed permission before rendering the page.",
+  ],
+  [
+    "fallback",
+    "ReactNode",
+    "AccessDenied",
+    "Replaces the complete page when its permission test fails.",
+  ],
+  ["children", "ReactNode", "required", "The protected page content."],
+];
+
+const regionProps: PropRow[] = [
+  [
+    "resource",
+    "string",
+    "required",
+    "NocoBase collection or ACL resource name.",
+  ],
+  [
+    "action",
+    "string",
+    "required",
+    "Resource action such as list, show, create, edit, or delete.",
+  ],
+  [
+    "id",
+    "BaseKey",
+    "undefined",
+    "Optional record ID for record-scoped permission checks.",
+  ],
+  [
+    "dataSourceKey",
+    "string",
+    "undefined",
+    "Selects a non-main NocoBase data source.",
+  ],
+  [
+    "fallback",
+    '"hidden" | "forbidden" | ReactNode',
+    '"hidden"',
+    "Hides the region or replaces it with a local denied state.",
+  ],
+  ["children", "ReactNode", "required", "The protected page region."],
+];
+
+const fieldProps: PropRow[] = [
+  [
+    "resource",
+    "string",
+    "required",
+    "NocoBase collection containing the field.",
+  ],
+  [
+    "action",
+    "string",
+    "required",
+    "The action whose field whitelist should be checked.",
+  ],
+  ["field", "string", "required", "Exact NocoBase field name."],
+  [
+    "dataSourceKey",
+    "string",
+    "undefined",
+    "Selects a non-main NocoBase data source.",
+  ],
+  [
+    "fallback",
+    "ReactNode",
+    "null",
+    "Optional read-only replacement for a denied field.",
+  ],
+  ["children", "ReactNode", "required", "The protected field or field group."],
+];
+
+export function AclBoundaryApi() {
+  return (
+    <section className="space-y-5 border-t pt-8">
+      <div>
+        <p className="text-xs font-semibold uppercase tracking-[0.16em] text-muted-foreground">
+          Permission boundaries
+        </p>
+        <h2 className="mt-2 text-xl font-semibold tracking-tight">
+          Components behind the patterns
+        </h2>
+        <p className="mt-1.5 max-w-3xl text-sm leading-6 text-muted-foreground">
+          Use the smallest boundary that matches the intended user experience:
+          complete page, independent region, or individual field.
+        </p>
+      </div>
+      <div className="space-y-7">
+        <ComponentApi
+          title="AclPage"
+          description="Protects a complete route or business page. This corresponds to the Page permission pattern above."
+          rows={pageProps}
+        />
+        <ComponentApi
+          title="AclRegion"
+          description="Protects one independent area inside a larger page. This corresponds to the Region permission pattern."
+          rows={regionProps}
+        />
+        <ComponentApi
+          title="AclField"
+          description="Protects one field or field group. This corresponds to the Field permission pattern."
+          rows={fieldProps}
+        />
+      </div>
+    </section>
+  );
+}
+
+function ComponentApi({
+  title,
+  description,
+  rows,
+}: {
+  title: string;
+  description: string;
+  rows: PropRow[];
+}) {
+  return (
+    <div className="space-y-3">
+      <div>
+        <h3 className="font-semibold">{title}</h3>
+        <p className="mt-1 text-sm text-muted-foreground">{description}</p>
+      </div>
+      <Card className="gap-0 overflow-hidden py-0">
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead>Prop</TableHead>
+              <TableHead>Type</TableHead>
+              <TableHead>Default</TableHead>
+              <TableHead>Description</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {rows.map(([name, type, defaultValue, propDescription]) => (
+              <TableRow key={name}>
+                <TableCell className="font-mono text-xs font-medium">
+                  {name}
+                </TableCell>
+                <TableCell className="font-mono text-xs text-muted-foreground">
+                  {type}
+                </TableCell>
+                <TableCell className="font-mono text-xs text-muted-foreground">
+                  {defaultValue}
+                </TableCell>
+                <TableCell className="min-w-72 whitespace-normal text-muted-foreground">
+                  {propDescription}
+                </TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      </Card>
+    </div>
+  );
+}