@nocobase/portal-template-default 1.0.0 → 1.0.2

package/README.MD

@@ -14,7 +14,15 @@ NOCOBASE_API_URL=https://develop.v2.test.nocobase.com/nocobase/api/__app/cms
 
 In development, the app auto-detects the proxy target from `NOCOBASE_API_URL` when that value is an absolute URL. The configured API URL can stay on the original sub-app path such as `/nocobase/api/__app/cms`.
 
-Refine resource names must match NocoBase collection names. For example, the supplied Swagger document exposes `collectionCategories`, so use that name when registering a corresponding Refine resource.
+Application resource names must match NocoBase collection names. The included
+Users example targets the default `users` collection, so it works without a
+project-specific business collection.
+
+Application-owned React translations live in `src/locales`. The entry registers
+an `app` namespace for business pages and augments the default `starter`
+namespace for shared controls. Feature-specific Registry translations remain
+inside their own extension namespace and are not mixed into application locale
+files.
 
 ## Available Scripts
 
@@ -30,6 +38,87 @@ pnpm dev
 pnpm build
 ```
 
+### Extensions and the NocoBase Shadcn Registry
+
+The starter separates framework-owned extension support from installed Registry
+source:
+
+- `src/app/extension.ts` defines the generic extension contract.
+- `src/app/extensions.tsx` discovers `src/extensions/*/extension.tsx` and adds
+  its providers, Refine resources, and routes to the app.
+- `registry/<name>` contains the canonical authoring source for a Registry
+  package while it is developed in this repository.
+- `src/extensions/<name>` contains installed, application-owned source.
+  Downstream applications can commit this directory like any other source code.
+
+`registry.config.json` is the only authoring manifest. In addition to standard
+Shadcn Registry item fields, each item has a local `source` mapping used to
+generate its standard `files` array. The same mapping lets the starter's
+`postinstall` hook copy a locally authored extension only when its target is
+missing. Existing installed source is never compared, updated, or overwritten.
+Optional entries can set `source.install` to `false`; they remain available to
+Registry builds and local previews but are not added by `postinstall`.
+
+You can run the same missing-only installation explicitly with:
+
+```bash
+pnpm registry:install
+```
+
+This repository authors optional NocoBase integration entries. Internationalization
+is delivered as one cohesive Registry entry:
+
+- `i18n` provides frontend-owned UI resources, selected server-generated
+  namespaces such as `lm-collections`, the application translation provider,
+  locale persistence, `X-Locale` synchronization, legacy `{{t(...)}}`
+  compatibility, the language switcher, and the lazy-loaded showcase with its
+  prompt generator.
+
+The AI integration is available through four incremental entries:
+
+- `ai-runtime` provides AI services, providers, transports, and
+  controllers. Its NocoBase requests use the starter's shared
+  `src/lib/nocobase/client.ts` client.
+- `ai-chat` adds the reusable chat components and depends on the
+  runtime entry.
+- `ai-react-hook-form` adds the optional React Hook Form adapter for the fixed
+  Form filler Tool.
+- `ai` adds the application extension integration and Demo pages and depends on the
+  chat entry.
+
+To refresh the local preview from the canonical Registry source, run:
+
+```bash
+pnpm registry:preview
+```
+
+This is the only command that intentionally replaces the local preview at
+`src/extensions/nocobase-ai`. Normal `pnpm dev`, `pnpm install`, and
+`pnpm registry:install` do not overwrite an installed extension.
+
+Build the standard Shadcn Registry JSON files into `public/r` with:
+
+```bash
+pnpm registry:build
+```
+
+With the development server running, a compatible starter can also add the
+complete item through Shadcn:
+
+```bash
+pnpm dlx shadcn@latest add @nocobase/ai
+```
+
+Shadcn does not keep a Registry item lock or merge local changes. Re-running
+`add` downloads the current item, skips identical files, and asks before
+replacing different files. Use `--diff` to inspect an update and `--overwrite`
+to accept the Registry version explicitly.
+
+The Registry alias is configured in `components.json` and resolves to
+`http://localhost:5173/r/{name}.json` during local development. The same generic
+extension host and Registry source mapping can be reused for future Registry
+packages without adding package-specific logic to `App.tsx` or the installer.
+
 ### Running the production server.
 
 ```bash

package/components.json

@@ -21,5 +21,7 @@
   },
   "menuColor": "default",
   "menuAccent": "subtle",
-  "registries": {}
+  "registries": {
+    "@nocobase": "http://localhost:5173/r/{name}.json"
+  }
 }

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@nocobase/portal-template-default",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "type": "module",
-  "dependencies": {
+  "devDependencies": {
+    "@ai-sdk/react": "2.0.0",
     "@base-ui/react": "^1.6.0",
+    "@dicebear/core": "^9.4.3",
     "@fontsource-variable/geist": "^5.3.0",
     "@hookform/resolvers": "^5.0.1",
+    "@nocobase/ai-employee-avatars": "^1.0.2",
     "@refinedev/cli": "^2.16.48",
     "@refinedev/core": "^5.0.8",
     "@refinedev/devtools": "^2.0.1",
@@ -15,12 +18,18 @@
     "@refinedev/rest": "^2.1.0",
     "@refinedev/simple-rest": "^6.0.0",
     "@tailwindcss/vite": "^4.1.8",
+    "@tanstack/react-query": "^5.81.5",
     "@tanstack/react-table": "^8.2.6",
+    "ai": "5.0.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "date-fns": "^4.1.0",
     "dayjs": "^1.10.7",
+    "echarts": "^5.5.0",
+    "echarts-for-react": "3.0.2",
     "embla-carousel-react": "^8.6.0",
+    "eventsource-parser": "3.1.0",
+    "ignore": "^7.0.6",
     "input-otp": "^1.4.2",
     "lucide-react": "^0.487.0",
     "next-themes": "^0.4.6",
@@ -29,16 +38,16 @@
     "react-day-picker": "10.0.1",
     "react-dom": "19.1.0",
     "react-hook-form": "^7.57.0",
+    "react-markdown": "^10.1.0",
     "react-resizable-panels": "^4.12.2",
     "react-router": "^7.0.2",
     "recharts": "^3.8.0",
+    "remark-gfm": "^4.0.1",
     "shadcn": "^4.13.1",
     "sonner": "^2.0.3",
     "tailwind-merge": "^3.2.0",
     "tw-animate-css": "^1.2.5",
-    "zod": "^3.24.3"
-  },
-  "devDependencies": {
+    "zod": "^3.24.3",
     "@eslint/js": "^9.25.0",
     "@tailwindcss/postcss": "^4.1.4",
     "@types/node": "^20",
@@ -51,6 +60,7 @@
     "eslint-plugin-react-hooks": "^5.2.0",
     "eslint-plugin-react-refresh": "^0.4.19",
     "globals": "^16.0.0",
+    "i18next": "^25.3.2",
     "tailwindcss": "^4.1.4",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.30.1",
@@ -64,8 +74,14 @@
     "url": "git+https://github.com/nocobase/portal-template-default.git"
   },
   "scripts": {
+    "postinstall": "node ./scripts/registry.mjs install-missing",
     "dev": "vite",
     "build": "tsc && refine build",
+    "registry:install": "node ./scripts/registry.mjs install-missing",
+    "registry:preview": "node ./scripts/registry.mjs preview",
+    "registry:build": "node ./scripts/registry.mjs build && shadcn build ./registry.json -o ./public/r",
+    "test:acl": "node registry/nocobase-acl/tests/acl-regression.mjs",
+    "test:i18n": "node registry/nocobase-i18n/tests/i18n-regression.mjs",
     "start": "refine start",
     "refine": "refine"
   },

package/registry/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/registry/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/registry/nocobase-acl/components/index.ts

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

package/registry/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/registry/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/registry/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>
+  );
+}