@nocobase/portal-template-default 1.0.0 → 1.0.2

package/registry/nocobase-acl/demo/role-switcher-prompt-generator.tsx

@@ -0,0 +1,198 @@
+import { Check, Copy } from "lucide-react";
+import { useMemo, useState } from "react";
+
+import { Button } from "@/components/ui/button";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { Textarea } from "@/components/ui/textarea";
+
+type Placement = "header" | "user-menu" | "settings" | "custom";
+type UnavailableState = "hide" | "current-role";
+
+const placementLabels: Record<Placement, string> = {
+  header: "Application header",
+  "user-menu": "User menu",
+  settings: "Account settings",
+  custom: "Custom surface",
+};
+
+const unavailableStateLabels: Record<UnavailableState, string> = {
+  "current-role": "Show current role",
+  hide: "Hide component",
+};
+
+const placementInstructions: Record<Placement, string> = {
+  header:
+    "Place it in the application header beside the existing account controls. Keep the trigger compact and preserve the responsive user menu.",
+  "user-menu":
+    "Place it inside the existing user/account popover as a full-width menu section, separated from profile and sign-out actions.",
+  settings:
+    "Place it in an account settings section with a field label and short explanation of how the active role changes visible data and actions.",
+  custom:
+    "Place it in the application surface described below, matching the surrounding layout and spacing.",
+};
+
+export function RoleSwitcherPromptGenerator() {
+  const [placement, setPlacement] = useState<Placement>("user-menu");
+  const [label, setLabel] = useState("Working as");
+  const [unavailableState, setUnavailableState] =
+    useState<UnavailableState>("current-role");
+  const [surface, setSurface] = useState(
+    "Use the Starter's existing account controls and visual language. Do not create a separate demo page."
+  );
+  const [copied, setCopied] = useState(false);
+  const [copyError, setCopyError] = useState(false);
+
+  const prompt = useMemo(
+    () => `Integrate the RoleSwitcher into the existing NocoBase Admin Starter.
+
+Target placement
+- Placement: ${placementLabels[placement]}
+- ${placementInstructions[placement]}
+- Application context: ${surface}
+
+Component presentation
+- Label: ${label.trim() ? label : "No label; pass label={false}."}
+- When role switching is unavailable: ${
+      unavailableState === "current-role"
+        ? "Keep the current identity visible by passing showWhenUnavailable."
+        : "Hide the component by keeping showWhenUnavailable false."
+    }
+- Use className and triggerClassName only to fit the existing surface; do not fork or restyle the internal Select implementation.
+
+Integration requirements
+- Import and reuse RoleSwitcher from the installed local entry point at @/extensions/nocobase-acl.
+- Update the existing application surface instead of creating an isolated example page.
+- Do not fetch, hard-code, or pass a duplicate role list. The component reads roles from the signed-in identity.
+- Do not reimplement Full permissions, Anonymous, or role-mode logic. The component derives these options from the Starter ACL store.
+- Do not add a separate role-switch mutation. The component already calls users:setDefaultRole and reloads the application after a successful switch.
+- Preserve existing account, responsive navigation, and sign-out behavior.
+- Return the complete updated component for the target surface and mention any imports that were added.`,
+    [label, placement, surface, unavailableState]
+  );
+
+  return (
+    <div className="grid items-start gap-5 xl:grid-cols-[360px_minmax(0,1fr)]">
+      <Card className="gap-0 py-0">
+        <CardHeader className="border-b py-4">
+          <CardTitle className="text-base">Placement settings</CardTitle>
+          <CardDescription>
+            Choose where the shared role switcher belongs and how its compact
+            state should appear.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-5 py-5">
+          <div className="space-y-2">
+            <Label>Placement</Label>
+            <Select
+              value={placement}
+              onValueChange={(value) =>
+                value && setPlacement(value as Placement)
+              }
+            >
+              <SelectTrigger className="w-full">
+                <SelectValue>{placementLabels[placement]}</SelectValue>
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="header">Application header</SelectItem>
+                <SelectItem value="user-menu">User menu</SelectItem>
+                <SelectItem value="settings">Account settings</SelectItem>
+                <SelectItem value="custom">Custom surface</SelectItem>
+              </SelectContent>
+            </Select>
+          </div>
+          <div className="space-y-2">
+            <Label htmlFor="role-switcher-label">Label</Label>
+            <Input
+              id="role-switcher-label"
+              value={label}
+              onChange={(event) => setLabel(event.target.value)}
+              placeholder="Leave empty for no label"
+            />
+          </div>
+          <div className="space-y-2">
+            <Label>Single-role behavior</Label>
+            <Select
+              value={unavailableState}
+              onValueChange={(value) =>
+                value && setUnavailableState(value as UnavailableState)
+              }
+            >
+              <SelectTrigger className="w-full">
+                <SelectValue>
+                  {unavailableStateLabels[unavailableState]}
+                </SelectValue>
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="current-role">Show current role</SelectItem>
+                <SelectItem value="hide">Hide component</SelectItem>
+              </SelectContent>
+            </Select>
+          </div>
+          <div className="space-y-2">
+            <Label htmlFor="role-switcher-surface">Application context</Label>
+            <Textarea
+              id="role-switcher-surface"
+              value={surface}
+              onChange={(event) => setSurface(event.target.value)}
+              className="min-h-28"
+            />
+          </div>
+        </CardContent>
+      </Card>
+
+      <Card className="gap-0 overflow-hidden py-0">
+        <div className="flex items-center justify-between gap-3 border-b px-4 py-3">
+          <div>
+            <div className="text-sm font-medium">
+              Generated integration prompt
+            </div>
+            <div className="text-xs text-muted-foreground">
+              Updates as you change placement and presentation settings.
+            </div>
+          </div>
+          <Button
+            size="sm"
+            onClick={async () => {
+              try {
+                await navigator.clipboard.writeText(prompt);
+                setCopyError(false);
+                setCopied(true);
+                window.setTimeout(() => setCopied(false), 1500);
+              } catch {
+                setCopyError(true);
+              }
+            }}
+          >
+            {copied ? <Check /> : <Copy />}
+            {copied ? "Copied" : "Copy prompt"}
+          </Button>
+        </div>
+        {copyError ? (
+          <p className="border-b px-4 py-2 text-xs text-destructive">
+            Clipboard access failed. Select the prompt and copy it manually.
+          </p>
+        ) : null}
+        <CardContent className="p-0">
+          <pre className="max-h-[560px] overflow-auto whitespace-pre-wrap bg-muted/25 p-5 font-mono text-xs leading-5 text-muted-foreground">
+            {prompt}
+          </pre>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

package/registry/nocobase-acl/demo/scenario-section.tsx

@@ -0,0 +1,37 @@
+import type { ReactNode } from "react";
+
+import { Badge } from "@/components/ui/badge";
+import {
+  AclScenarioPromptGenerator,
+  type AclPromptGeneratorConfig,
+} from "./prompt-generator";
+
+export function AclScenarioSection({
+  eyebrow,
+  title,
+  description,
+  children,
+  prompt,
+}: {
+  eyebrow: string;
+  title: string;
+  description: string;
+  children: ReactNode;
+  prompt: AclPromptGeneratorConfig;
+}) {
+  return (
+    <section className="space-y-5 border-t pt-8">
+      <div>
+        <Badge variant="outline">{eyebrow}</Badge>
+        <h2 className="mt-3 text-2xl font-semibold tracking-[-0.025em]">
+          {title}
+        </h2>
+        <p className="mt-2 max-w-3xl text-sm leading-6 text-muted-foreground">
+          {description}
+        </p>
+      </div>
+      {children}
+      <AclScenarioPromptGenerator config={prompt} />
+    </section>
+  );
+}

package/registry/nocobase-acl/extension.tsx

@@ -0,0 +1,71 @@
+import type { AppExtension } from "@/app/extension";
+import { Blocks, PanelsTopLeft, ShieldCheck } from "lucide-react";
+import { lazy } from "react";
+import { Outlet, Route } from "react-router";
+import { LazyAclRoute } from "./demo/lazy-route";
+
+const AclComponentsPage = lazy(() =>
+  import("./demo/components").then((module) => ({
+    default: module.AclComponentsPage,
+  }))
+);
+const AclPatternsPage = lazy(() =>
+  import("./demo").then((module) => ({ default: module.AclPatternsPage }))
+);
+
+const nocobaseAclExtension: AppExtension = {
+  id: "nocobase-acl",
+  resources: [
+    {
+      name: "acl-integration",
+      meta: {
+        label: "Access control",
+        icon: <ShieldCheck />,
+        description: "NocoBase ACL integration for admin applications.",
+        acl: { type: "authenticated" },
+      },
+    },
+    {
+      name: "acl-components",
+      list: "/acl",
+      meta: {
+        parent: "acl-integration",
+        label: "Role switcher",
+        icon: <Blocks />,
+        acl: { type: "authenticated" },
+      },
+    },
+    {
+      name: "acl-patterns",
+      list: "/acl/patterns",
+      meta: {
+        parent: "acl-integration",
+        label: "Permission patterns",
+        icon: <PanelsTopLeft />,
+        acl: { type: "authenticated" },
+      },
+    },
+  ],
+  routes: (
+    <Route key="nocobase-acl" path="/acl" element={<Outlet />}>
+      <Route
+        index
+        element={
+          <LazyAclRoute>
+            <AclComponentsPage />
+          </LazyAclRoute>
+        }
+      />
+      <Route
+        path="patterns"
+        element={
+          <LazyAclRoute>
+            <AclPatternsPage />
+          </LazyAclRoute>
+        }
+      />
+    </Route>
+  ),
+};
+
+export default nocobaseAclExtension;

package/registry/nocobase-acl/index.ts

@@ -0,0 +1 @@
+export * from "./components";

package/registry/nocobase-acl/tests/acl-regression.mjs

@@ -0,0 +1,314 @@
+import assert from "node:assert/strict";
+import { createServer } from "vite";
+
+const server = await createServer({
+  appType: "custom",
+  logLevel: "silent",
+  server: { middlewareMode: true },
+});
+
+try {
+  const {
+    canAccessWithSnapshot,
+    getAclDataForDataSource,
+    resolveActionPermission,
+  } = await server.ssrLoadModule("/src/lib/nocobase/acl/action.ts");
+  const { resolveAclDataSourceKey } = await server.ssrLoadModule(
+    "/src/lib/nocobase/acl/data-source.ts"
+  );
+  const { filterMenuItemsByAcl, findFirstAccessibleRoute } =
+    await server.ssrLoadModule("/src/lib/nocobase/acl/menu.ts");
+  const {
+    clearRecordPermissions,
+    getRecordActionPermission,
+    updateRecordPermissions,
+  } = await server.ssrLoadModule("/src/lib/nocobase/acl/record-permissions.ts");
+  const { RoleSwitcher } = await server.ssrLoadModule(
+    "/registry/nocobase-acl/components/role-switcher.tsx"
+  );
+  const { getRoleOptions, resolveRoleTitle } = await server.ssrLoadModule(
+    "/registry/nocobase-acl/components/role-options.ts"
+  );
+
+  const snapshot = {
+    status: "ready",
+    version: 1,
+    data: {
+      role: "editor",
+      roleMode: "allow-use-union",
+      resources: ["blog_posts"],
+      actionAlias: {
+        list: "view",
+        get: "view",
+      },
+      actions: {
+        "blog_posts:view": { fields: ["id", "title"] },
+        "blog_posts:update": { fields: ["title"] },
+      },
+      strategy: {
+        actions: ["view:all"],
+      },
+      snippets: ["pm.*"],
+    },
+    meta: {},
+  };
+
+  assert.deepEqual(
+    resolveActionPermission({
+      snapshot,
+      resource: "blog_posts",
+      action: "list",
+    }),
+    { fields: ["id", "title"] }
+  );
+  assert.equal(
+    canAccessWithSnapshot(snapshot, {
+      resource: "blog_posts",
+      action: "create",
+    }),
+    false
+  );
+
+  const externalSnapshot = {
+    ...snapshot,
+    data: {
+      ...snapshot.data,
+      allowAll: true,
+      actionAlias: { list: "view" },
+    },
+    meta: {
+      dataSources: {
+        analytics: {
+          allowAll: false,
+          resources: ["orders"],
+          actionAlias: { list: "read" },
+          actions: { "orders:read": {} },
+        },
+      },
+    },
+  };
+  assert.deepEqual(getAclDataForDataSource(externalSnapshot, "analytics"), {
+    ...externalSnapshot.data,
+    allowAll: false,
+    resources: ["orders"],
+    actionAlias: { list: "read" },
+    actions: { "orders:read": {} },
+    snippets: externalSnapshot.data.snippets,
+  });
+  assert.equal(
+    canAccessWithSnapshot(externalSnapshot, {
+      resource: "orders",
+      action: "list",
+      params: { meta: { dataSourceKey: "analytics" } },
+    }),
+    true
+  );
+  assert.equal(
+    resolveAclDataSourceKey({
+      acl: {
+        type: "collection",
+        dataSourceKey: "analytics",
+      },
+    }),
+    "analytics"
+  );
+  assert.equal(
+    resolveAclDataSourceKey(
+      { dataSourceKey: "reporting" },
+      {
+        acl: {
+          type: "collection",
+          dataSourceKey: "analytics",
+        },
+      }
+    ),
+    "reporting"
+  );
+  assert.equal(
+    getRecordActionPermission({
+      resource: "blog_posts",
+      action: "update",
+      id: 3,
+    }),
+    undefined
+  );
+  assert.equal(
+    canAccessWithSnapshot(snapshot, {
+      resource: "categories",
+      action: "list",
+    }),
+    true
+  );
+  assert.equal(
+    canAccessWithSnapshot(snapshot, {
+      resource: "settings",
+      action: "list",
+      params: {
+        resource: {
+          name: "settings",
+          meta: { acl: { type: "snippet", name: "*" } },
+        },
+      },
+    }),
+    true
+  );
+  assert.equal(
+    canAccessWithSnapshot(
+      {
+        ...snapshot,
+        data: {
+          ...snapshot.data,
+          snippets: ["pm", "pm.*", "!pm.data-source-manager*"],
+        },
+      },
+      {
+        resource: "settings",
+        action: "list",
+        params: {
+          resource: {
+            name: "settings",
+            meta: {
+              acl: { type: "snippet", name: "pm.data-source-manager" },
+            },
+          },
+        },
+      }
+    ),
+    false
+  );
+  assert.equal(
+    updateRecordPermissions({
+      resource: "blog_posts",
+      recordIds: [4],
+      allowedActions: { update: [] },
+    }),
+    true
+  );
+  assert.equal(
+    getRecordActionPermission({
+      resource: "blog_posts",
+      action: "update",
+      id: 4,
+    }),
+    false
+  );
+  assert.equal(
+    canAccessWithSnapshot(snapshot, {
+      resource: "settings",
+      action: "list",
+      params: {
+        resource: {
+          name: "settings",
+          meta: { acl: { type: "snippet", name: "pm.acl" } },
+        },
+      },
+    }),
+    true
+  );
+  assert.equal(
+    canAccessWithSnapshot(snapshot, {
+      resource: "blog_posts",
+      action: "edit",
+      params: { field: "title" },
+    }),
+    true
+  );
+  assert.equal(
+    canAccessWithSnapshot(snapshot, {
+      resource: "blog_posts",
+      action: "edit",
+      params: { field: "status" },
+    }),
+    false
+  );
+
+  clearRecordPermissions();
+  updateRecordPermissions({
+    resource: "blog_posts",
+    recordIds: [1, 2],
+    allowedActions: {
+      view: [1, 2],
+      update: [1],
+      destroy: [],
+    },
+  });
+  assert.equal(
+    canAccessWithSnapshot(snapshot, {
+      resource: "blog_posts",
+      action: "edit",
+      params: { id: 1 },
+    }),
+    true
+  );
+  assert.equal(
+    canAccessWithSnapshot(snapshot, {
+      resource: "blog_posts",
+      action: "edit",
+      params: { id: 2 },
+    }),
+    false
+  );
+  assert.equal(
+    updateRecordPermissions({
+      resource: "blog_posts",
+      recordIds: [1, 2],
+      allowedActions: {
+        view: [1, 2],
+        update: [1],
+        destroy: [],
+      },
+    }),
+    false
+  );
+
+  const filteredMenu = filterMenuItemsByAcl(
+    [
+      {
+        key: "restricted-parent",
+        name: "restricted-parent",
+        route: "/restricted-parent",
+        children: [
+          {
+            key: "public-child",
+            name: "public-child",
+            route: "/public-child",
+            meta: { acl: { type: "authenticated" } },
+            children: [],
+          },
+        ],
+      },
+    ],
+    {
+      ...snapshot,
+      data: { ...snapshot.data, strategy: { actions: [] } },
+    }
+  );
+  assert.equal(filteredMenu[0].route, undefined);
+  assert.equal(findFirstAccessibleRoute(filteredMenu), "/public-child");
+
+  assert.deepEqual(
+    getRoleOptions({
+      roles: [
+        { name: "admin", title: "Administrator" },
+        { name: "member", title: "Member" },
+      ],
+      roleMode: "allow-use-union",
+      allowAnonymous: true,
+    }),
+    [
+      { name: "__union__", title: "Full permissions" },
+      { name: "admin", title: "Administrator" },
+      { name: "member", title: "Member" },
+      { name: "anonymous", title: "Anonymous" },
+    ]
+  );
+  assert.equal(
+    resolveRoleTitle({ name: "admin", title: '{{t("Admin")}}' }),
+    "Admin"
+  );
+
+  assert.equal(typeof RoleSwitcher, "function");
+  console.log("NocoBase ACL regression tests passed");
+} finally {
+  await server.close();
+}

package/registry/nocobase-ai/README.md

@@ -0,0 +1,70 @@
+# NocoBase AI Registry
+
+The Registry is split by capability so applications only install the code and dependencies they use.
+
+These entries target the compatible NocoBase admin starter family. The host must
+provide the `@` source alias, `@/lib/nocobase/client`, the standard shadcn UI
+components, and (for `@nocobase/ai`) the `@/app/extension` discovery contract.
+Applications with a different host can still reuse the providers and components,
+but should supply their own `AIService` adapter and integration entry.
+
+- `@nocobase/ai-runtime`: NocoBase service adapter, chat state, streaming transport, conversation history, Tool execution, and page-context registries.
+- `@nocobase/ai-chat`: Chat windows, containers, triggers, page-element APIs, built-in Tool cards, and the high-level `NocoBaseAIRootProvider`.
+- `@nocobase/ai-react-hook-form`: Optional React Hook Form adapter for the built-in Form filler.
+- `@nocobase/ai`: The complete Demo extension and routes.
+
+## Recommended provider
+
+Use one root provider around every chat surface and page element that should participate in AI interactions:
+
+```tsx
+<NocoBaseAIRootProvider service={service}>
+  <YourApplication />
+</NocoBaseAIRootProvider>
+```
+
+It installs the AI runtime, built-in Tool renderers, Form registry, frontend Tool registry, and page-context resolver in the required order. The lower-level providers remain available for advanced integrations.
+
+## Page context
+
+Prefer `useAIPageElementHandle` when a page element is both registered and referenced by a task or scope:
+
+```tsx
+const customer = useAIPageElementHandle({
+  id: "customer-detail",
+  title: "Customer detail",
+  getContext: () => customerRecord,
+});
+
+return (
+  <AIPageContextScope context={customer.context}>
+    <section ref={customer.ref}>...</section>
+  </AIPageContextScope>
+);
+```
+
+Context is resolved again immediately before sending, so the model receives the latest page values. Resolution failures block the request by default. Set `contextFailurePolicy="omit"` on `NocoBaseAIRootProvider` only when sending without unavailable context is an intentional product decision.
+
+Nested scopes replace the parent scope by default. Use `mode="append"` to compose parent and child context.
+
+## Form filler
+
+Register forms with `useAIForm`. Sending a registered form Context automatically enables the fixed `formFiller` Tool; tasks do not need to add it to `skillSettings.tools`.
+
+The runtime applies only declared, editable, type-compatible fields. It never submits or saves the form. React Hook Form users can install `@nocobase/ai-react-hook-form` and import `applyReactHookFormValues` from `src/extensions/nocobase-ai/adapters/react-hook-form`.
+
+## Frontend Tools
+
+Frontend Tools are page-local browser actions and remain separate from Form filler. Use `defineAIFrontendTool` for typed registration, provide a JSON input schema, and choose `ASK` or `ALLOW`. Runtime permission controls approval; prompts should not simulate approval behavior.
+
+## Tool cards
+
+Pass application-specific message renderers through `NocoBaseAIRootProvider.toolRenderers`. Built-in renderers remain available automatically. A custom renderer receives the Tool part, disabled state, edit/approve/reject actions, and a composer-focus callback.
+
+## Local Registry development
+
+- `pnpm registry:build` regenerates `registry.json` and the static shadcn Registry output.
+- `pnpm registry:install` installs the Registry source only when the target directory is missing.
+- `pnpm registry:preview` intentionally replaces the local installed preview with the authoritative source.
+
+Normal install and `postinstall` never overwrite an existing `src/extensions/nocobase-ai` directory, so downstream applications can edit and commit installed source.