@nocobase/portal-template-default 1.0.3 → 1.0.4

package/registry/nocobase-i18n/provider.tsx

@@ -1,18 +1,30 @@
 import { useEffect, useState, type PropsWithChildren } from "react";
 
 import { LoadingState } from "@/components/app-shell/loading-state";
-import { setTranslationResolver } from "@/lib/i18n";
+import { nocobaseClient } from "@/lib/nocobase/client";
+import { setLocalePersistence } from "@/providers/i18n";
+import { useSystemSettings } from "@/providers/system-settings";
 import { loadServerLocaleResources } from "./server-resources";
-import { translate } from "./runtime";
 
-export function LocalePreferenceProvider({ children }: PropsWithChildren) {
+export function NocoBaseI18nBootstrap({ children }: PropsWithChildren) {
+  const { settings } = useSystemSettings();
   const [ready, setReady] = useState(false);
 
-  useEffect(() => setTranslationResolver(translate), []);
+  useEffect(
+    () =>
+      setLocalePersistence(async (locale) => {
+        if (!nocobaseClient.getToken()) return;
+        await nocobaseClient.action("users", "updateLang", {
+          method: "POST",
+          body: { appLang: locale },
+        });
+      }),
+    []
+  );
 
   useEffect(() => {
     let active = true;
-    void loadServerLocaleResources()
+    void loadServerLocaleResources(settings)
       .catch((error) => {
         console.warn("Unable to load NocoBase locale resources", error);
       })
@@ -22,7 +34,7 @@ export function LocalePreferenceProvider({ children }: PropsWithChildren) {
     return () => {
       active = false;
     };
-  }, []);
+  }, [settings]);
 
   if (!ready) {
     return <LoadingState className="min-h-80" />;

package/registry/nocobase-i18n/server-resources.ts

@@ -1,20 +1,18 @@
 import { nocobaseClient } from "@/lib/nocobase/client";
 import {
-  getLocaleDefinitions,
+  type LocaleSystemSettings,
+  applyDocumentLocale,
+  getCurrentLocale,
+  i18n,
   registerLocale,
   setEnabledLocales,
-} from "./locale-store";
-import { applyDocumentLocale, getCurrentLocale, i18n } from "./runtime";
+} from "@/providers/i18n";
 
 type ServerLanguagePayload = {
   lang?: string;
   resources?: Record<string, Record<string, string>>;
 };
 
-type SystemSettingsPayload = {
-  enabledLanguages?: string[];
-};
-
 const serverResourceNamespaces = new Set(["lm-collections"]);
 const loadedServerResourceNamespaces = new Set<string>();
 const namespaceLoadPromises = new Map<string, Promise<void>>();
@@ -119,37 +117,23 @@ export function getServerResourceNamespaces() {
   return [...serverResourceNamespaces];
 }
 
-export function loadServerLocaleResources() {
+export function loadServerLocaleResources(settings?: LocaleSystemSettings) {
   if (serverResourcesPromise) return serverResourcesPromise;
 
   bootstrapStarted = true;
   const requestedLocale = nocobaseClient.getStoredLocale();
   const initialNamespaces = [...serverResourceNamespaces];
-  const systemSettingsPromise = nocobaseClient
-    .action<SystemSettingsPayload>("systemSettings", "get", {
-      method: "GET",
-      includeRole: false,
-      withAclMeta: false,
-    })
-    .catch((error) => {
-      console.warn("Unable to load enabled NocoBase languages", error);
-      return undefined;
-    })
-    .then((systemSettings) => {
-      const configuredLocales = Array.isArray(systemSettings?.enabledLanguages)
-        ? systemSettings.enabledLanguages
-        : [];
-      if (configuredLocales.length) setEnabledLocales(configuredLocales);
-      return systemSettings;
-    });
+  const configuredLocales = Array.isArray(settings?.enabledLanguages)
+    ? settings.enabledLanguages
+    : [];
+  if (configuredLocales.length) setEnabledLocales(configuredLocales);
   const languagePromise = requestServerResources(
     initialNamespaces,
     requestedLocale
   );
 
-  serverResourcesPromise = Promise.all([systemSettingsPromise, languagePromise])
-    .then(async ([systemSettings, payload]) => {
-      const configuredLocales = systemSettings?.enabledLanguages ?? [];
+  serverResourcesPromise = languagePromise
+    .then(async (payload) => {
       const serverLocale = payload.lang;
 
       if (!configuredLocales.length && serverLocale) {
@@ -173,9 +157,7 @@ export function loadServerLocaleResources() {
     })
     .catch((error) => {
       bootstrapComplete = true;
-      if (!getLocaleDefinitions().length) {
-        setEnabledLocales([getCurrentLocale()]);
-      }
+      if (!configuredLocales.length) setEnabledLocales([getCurrentLocale()]);
       serverResourcesPromise = undefined;
       throw error;
     });

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

@@ -9,13 +9,16 @@ const server = await createServer({
 
 try {
   await server.ssrLoadModule("/src/locales/index.ts");
-  const { i18n, registerLocaleResources, translate } =
-    await server.ssrLoadModule("/registry/nocobase-i18n/runtime.ts");
-  const { resolveTranslatableText, setTranslationResolver } =
+  const {
+    applySystemLocale,
+    getCurrentLocale,
+    i18n,
+    registerLocaleResources,
+    translate,
+  } = await server.ssrLoadModule("/src/providers/i18n/runtime.ts");
+  const { resolveTranslatableText } =
     await server.ssrLoadModule("/src/lib/i18n.ts");
 
-  setTranslationResolver(translate);
-
   await i18n.changeLanguage("en-US");
   assert.equal(translate("resources.users", { ns: "app" }, "Users"), "Users");
 
@@ -36,6 +39,12 @@ try {
     "示例"
   );
 
+  await applySystemLocale({
+    appLang: "en-US",
+    enabledLanguages: ["en-US", "zh-CN"],
+  });
+  assert.equal(getCurrentLocale(), "en-US");
+
   console.log("NocoBase i18n regression tests passed");
 } finally {
   await server.close();

package/registry/nocobase-route-surfaces/README.md

@@ -0,0 +1,21 @@
+# Route surfaces
+
+Route surfaces keep URL navigation separate from visual presentation. The same
+business content can be hosted by a routed drawer, dialog, or full page.
+
+The Registry also installs a lazy-loaded Demo route at `/route-surfaces` with
+live drawer, dialog, child-page, nested-drawer, and mixed page/drawer/dialog
+scenarios plus a Prompt generator.
+
+## Components
+
+- `RouteDrawer` supports URL-backed nested drawers and push-style stacking.
+- `RouteDialog` provides the same close contract for modal routes.
+- `RoutePage` provides the close context without an overlay.
+- `useRouteSurfaceClose` lets content request a close without knowing how it is
+  presented.
+- `useRefineUnsavedChangesGuard` adapts Refine's unsaved-change state to the
+  route surface close lifecycle and renders a shadcn Alert Dialog confirmation.
+
+Route definitions, ACL guards, resource data fetching, and application-specific
+paths remain application concerns.

package/registry/nocobase-route-surfaces/demo/index.tsx

@@ -0,0 +1,266 @@
+import { ArrowLeft, ArrowRight, Layers3 } from "lucide-react";
+import { useOutlet, useNavigate } from "react-router";
+
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import {
+  RouteDialog,
+  RouteDrawer,
+  RoutePage,
+  useRouteSurfaceClose,
+} from "../index";
+import { RouteSurfacePromptGenerator } from "./prompt-generator";
+import { routeSurfaceScenarios } from "./scenarios";
+
+const demoBase = "/route-surfaces";
+
+export function RouteSurfacesDemoHome() {
+  const navigate = useNavigate();
+  const overlay = useOutlet();
+
+  return (
+    <>
+      <div className="space-y-6">
+        <div className="space-y-2">
+          <Badge variant="secondary">Route surfaces</Badge>
+          <h1 className="font-heading text-3xl font-semibold tracking-tight">
+            URL-backed pages and overlays
+          </h1>
+          <p className="max-w-3xl text-muted-foreground">
+            Keep business content independent from whether it appears as a page,
+            drawer, dialog, or nested combination. Every preview below supports a
+            direct URL and browser history.
+          </p>
+        </div>
+
+        <div className="grid gap-4 lg:grid-cols-2 xl:grid-cols-3">
+          {routeSurfaceScenarios.map((scenario) => (
+            <Card key={scenario.id} className="flex flex-col">
+              <CardHeader>
+                <div className="flex items-center justify-between gap-3">
+                  <Badge variant="outline">Scenario {scenario.number}</Badge>
+                  <span className="text-xs text-muted-foreground">
+                    {scenario.routeShape}
+                  </span>
+                </div>
+                <CardTitle>{scenario.title}</CardTitle>
+                <CardDescription>{scenario.description}</CardDescription>
+              </CardHeader>
+              <CardContent className="mt-auto">
+                <Button
+                  type="button"
+                  variant="outline"
+                  className="w-full"
+                  onClick={() => navigate(scenario.path)}
+                >
+                  Open preview
+                  <ArrowRight />
+                </Button>
+              </CardContent>
+            </Card>
+          ))}
+        </div>
+
+        <RouteSurfacePromptGenerator />
+      </div>
+      {overlay}
+    </>
+  );
+}
+
+export function DemoDrawerRoute() {
+  const navigate = useNavigate();
+  const nested = useOutlet();
+
+  return (
+    <RouteDrawer
+      title="Customer details"
+      description="A routed drawer keeps the scenario page mounted behind it."
+      closeLabel="Close"
+      closeTo={demoBase}
+      nested={nested}
+    >
+      <DemoSurfaceBody
+        label="Drawer"
+        title="Northwind renewal"
+        description="Business content does not know that it is rendered inside a drawer."
+      >
+        <Button onClick={() => navigate("second")}>
+          Open second-level drawer
+          <ArrowRight />
+        </Button>
+      </DemoSurfaceBody>
+    </RouteDrawer>
+  );
+}
+
+export function DemoSecondDrawerRoute() {
+  return (
+    <RouteDrawer
+      title="Renewal activity"
+      description="The lower drawer is pushed outward and remains behind the layer mask."
+      closeLabel="Close"
+      closeTo={`${demoBase}/drawer`}
+    >
+      <DemoSurfaceBody
+        label="Second-level drawer"
+        title="Latest review"
+        description="Clicking this layer's backdrop closes only the top drawer."
+      />
+    </RouteDrawer>
+  );
+}
+
+export function DemoDialogRoute() {
+  return (
+    <RouteDialog
+      title="Approve renewal"
+      description="A modal route for a focused decision."
+      closeLabel="Close"
+      closeTo={demoBase}
+    >
+      <DemoSurfaceBody
+        label="Dialog"
+        title="Approval required"
+        description="The page stays mounted while the URL represents the active dialog."
+      />
+    </RouteDialog>
+  );
+}
+
+export function DemoPageRoute() {
+  const nested = useOutlet();
+
+  return (
+    <RoutePage closeTo={demoBase}>
+      <DemoPageContent nested={nested} />
+    </RoutePage>
+  );
+}
+
+function DemoPageContent({ nested }: { nested: React.ReactNode }) {
+  const close = useRouteSurfaceClose();
+  const navigate = useNavigate();
+
+  return (
+    <>
+      <div className="space-y-6">
+        <div className="flex flex-wrap items-start justify-between gap-4">
+          <div className="space-y-2">
+            <Badge variant="secondary">Child page</Badge>
+            <h1 className="font-heading text-3xl font-semibold tracking-tight">
+              Customer workspace
+            </h1>
+            <p className="text-muted-foreground">
+              This route replaces the Demo home instead of rendering inside its Outlet.
+            </p>
+          </div>
+          <Button variant="outline" onClick={() => void close()}>
+            <ArrowLeft />
+            Back to scenarios
+          </Button>
+        </div>
+
+        <Card>
+          <CardHeader>
+            <div className="flex items-center gap-2">
+              <Layers3 className="size-5 text-primary" />
+              <CardTitle>Page-owned workflow</CardTitle>
+            </div>
+            <CardDescription>
+              A page can still host routed overlays without becoming coupled to their content.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Button onClick={() => navigate("drawer")}>Open page drawer</Button>
+          </CardContent>
+        </Card>
+      </div>
+      {nested}
+    </>
+  );
+}
+
+export function DemoPageDrawerRoute() {
+  const navigate = useNavigate();
+  const nested = useOutlet();
+
+  return (
+    <RouteDrawer
+      title="Customer activity"
+      description="This drawer belongs to the child page route."
+      closeLabel="Close"
+      closeTo={`${demoBase}/page`}
+      nested={nested}
+    >
+      <DemoSurfaceBody
+        label="Page drawer"
+        title="Renewal conversation"
+        description="Open a dialog above this drawer to test mixed presentation types."
+      >
+        <Button onClick={() => navigate("dialog")}>
+          Open confirmation dialog
+          <ArrowRight />
+        </Button>
+      </DemoSurfaceBody>
+    </RouteDrawer>
+  );
+}
+
+export function DemoPageDrawerDialogRoute() {
+  return (
+    <RouteDialog
+      title="Confirm follow-up"
+      description="The dialog is nested in the drawer route subtree."
+      closeLabel="Close"
+      closeTo={`${demoBase}/page/drawer`}
+    >
+      <DemoSurfaceBody
+        label="Nested dialog"
+        title="Schedule a follow-up?"
+        description="Closing returns to the drawer; closing the drawer then returns to the page."
+      />
+    </RouteDialog>
+  );
+}
+
+function DemoSurfaceBody({
+  label,
+  title,
+  description,
+  children,
+}: {
+  label: string;
+  title: string;
+  description: string;
+  children?: React.ReactNode;
+}) {
+  return (
+    <div className="min-h-0 flex-1 overflow-y-auto px-5 py-5">
+      <div className="space-y-5">
+        <Badge variant="outline">{label}</Badge>
+        <div className="space-y-2">
+          <h2 className="text-xl font-semibold">{title}</h2>
+          <p className="text-muted-foreground">{description}</p>
+        </div>
+        <div className="grid gap-3 rounded-lg border bg-muted/30 p-4 sm:grid-cols-2">
+          <DemoField label="Owner" value="Ada Lovelace" />
+          <DemoField label="Status" value="In review" />
+          <DemoField label="Value" value="$48,000" />
+          <DemoField label="Renewal" value="September 30" />
+        </div>
+        {children ? <div>{children}</div> : null}
+      </div>
+    </div>
+  );
+}
+
+function DemoField({ label, value }: { label: string; value: string }) {
+  return (
+    <div className="space-y-1">
+      <div className="text-xs text-muted-foreground">{label}</div>
+      <div className="font-medium">{value}</div>
+    </div>
+  );
+}

package/{src/extensions/nocobase-acl → registry/nocobase-route-surfaces}/demo/lazy-route.tsx

@@ -1,7 +1,8 @@
 import { Suspense, type ReactNode } from "react";
+
 import { LoadingState } from "@/components/app-shell/loading-state";
 
-export function LazyAclRoute({ children }: { children: ReactNode }) {
+export function LazyRouteSurfaceDemo({ children }: { children: ReactNode }) {
   return (
     <Suspense fallback={<LoadingState className="min-h-80" />}>
       {children}

package/registry/nocobase-route-surfaces/demo/prompt-generator.tsx

@@ -0,0 +1,90 @@
+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";
+import {
+  getRouteSurfacePrompt,
+  routeSurfaceScenarios,
+  type RouteSurfaceScenarioId,
+} from "./scenarios";
+
+export function RouteSurfacePromptGenerator() {
+  const [scenarioId, setScenarioId] =
+    useState<RouteSurfaceScenarioId>("drawer");
+  const [target, setTarget] = useState("a customer detail workflow");
+  const [copied, setCopied] = useState(false);
+  const scenario =
+    routeSurfaceScenarios.find((item) => item.id === scenarioId) ??
+    routeSurfaceScenarios[0];
+  const prompt = useMemo(
+    () => getRouteSurfacePrompt(scenario, target),
+    [scenario, target]
+  );
+
+  const copyPrompt = async () => {
+    await navigator.clipboard.writeText(prompt);
+    setCopied(true);
+    window.setTimeout(() => setCopied(false), 1500);
+  };
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Prompt generator</CardTitle>
+        <CardDescription>
+          Generate a complete routing scenario, not just an isolated overlay component.
+        </CardDescription>
+      </CardHeader>
+      <CardContent className="space-y-4">
+        <div className="grid gap-4 md:grid-cols-2">
+          <div className="space-y-2">
+            <Label htmlFor="route-surface-scenario">Scenario</Label>
+            <Select
+              value={scenarioId}
+              onValueChange={(value) =>
+                setScenarioId(value as RouteSurfaceScenarioId)
+              }
+            >
+              <SelectTrigger id="route-surface-scenario" className="w-full">
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                {routeSurfaceScenarios.map((item) => (
+                  <SelectItem key={item.id} value={item.id}>
+                    {item.number}. {item.title}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          </div>
+          <div className="space-y-2">
+            <Label htmlFor="route-surface-target">Business target</Label>
+            <Input
+              id="route-surface-target"
+              value={target}
+              onChange={(event) => setTarget(event.target.value)}
+            />
+          </div>
+        </div>
+        <Textarea value={prompt} readOnly className="min-h-80 font-mono text-xs" />
+        <div className="flex justify-end">
+          <Button type="button" onClick={() => void copyPrompt()}>
+            {copied ? <Check /> : <Copy />}
+            {copied ? "Copied" : "Copy prompt"}
+          </Button>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}

package/registry/nocobase-route-surfaces/demo/scenarios.ts

@@ -0,0 +1,95 @@
+export type RouteSurfaceScenarioId =
+  | "drawer"
+  | "dialog"
+  | "page"
+  | "nested-drawers"
+  | "page-drawer-dialog";
+
+export type RouteSurfaceScenario = {
+  id: RouteSurfaceScenarioId;
+  number: string;
+  title: string;
+  description: string;
+  path: string;
+  routeShape: string;
+};
+
+export const routeSurfaceScenarios: RouteSurfaceScenario[] = [
+  {
+    id: "drawer",
+    number: "1",
+    title: "Drawer route",
+    description: "Keep the current page mounted and open one URL-backed drawer.",
+    path: "/route-surfaces/drawer",
+    routeShape: "Page → Drawer",
+  },
+  {
+    id: "dialog",
+    number: "2",
+    title: "Dialog route",
+    description: "Open focused content in a modal while preserving the page URL history.",
+    path: "/route-surfaces/dialog",
+    routeShape: "Page → Dialog",
+  },
+  {
+    id: "page",
+    number: "3",
+    title: "Child page",
+    description: "Replace the current page instead of rendering the child inside an overlay.",
+    path: "/route-surfaces/page",
+    routeShape: "Page → Child page",
+  },
+  {
+    id: "nested-drawers",
+    number: "4",
+    title: "Second-level drawer",
+    description: "Push the lower drawer outward and keep the top drawer at a stable size.",
+    path: "/route-surfaces/drawer/second",
+    routeShape: "Page → Drawer → Drawer",
+  },
+  {
+    id: "page-drawer-dialog",
+    number: "5",
+    title: "Page, drawer, and dialog",
+    description: "Compose different presentation types without coupling business content to them.",
+    path: "/route-surfaces/page/drawer/dialog",
+    routeShape: "Child page → Drawer → Dialog",
+  },
+];
+
+export function getRouteSurfacePrompt(
+  scenario: RouteSurfaceScenario,
+  target: string
+) {
+  const presentation = {
+    drawer:
+      "Keep the current page mounted and open the target content with RouteDrawer. Closing the drawer returns to the page route.",
+    dialog:
+      "Keep the current page mounted and open the target content with RouteDialog. The dialog route must be directly addressable and dismissible through the shared close lifecycle.",
+    page:
+      "Render the target content as a real child page with RoutePage. Register it as a page route branch rather than placing it inside a drawer outlet.",
+    "nested-drawers":
+      "Create a parent RouteDrawer with an Outlet and pass the rendered child outlet through its nested prop. The second RouteDrawer must push the lower drawer outward, keep equal widths, and close back to the parent route.",
+    "page-drawer-dialog":
+      "Render a RoutePage first, place a RouteDrawer route inside that page, then render a RouteDialog as the drawer's nested route. Closing each layer must return to the immediately lower URL.",
+  }[scenario.id];
+
+  return `Build ${target || "the requested workflow"} with the installed NocoBase route surfaces.
+
+Scenario:
+- ${scenario.routeShape}
+- ${presentation}
+
+Implementation requirements:
+- Import RouteDrawer, RouteDialog, RoutePage, and useRouteSurfaceClose from @/extensions/nocobase-route-surfaces as needed.
+- Keep data loading, forms, ACL guards, route paths, and business copy in application-owned files.
+- Keep business content independent from its presentation container so the same content can move between a drawer, dialog, or page.
+- Every surface must have an explicit closeTo URL.
+- Use nested React Router routes and Outlet only when the visual layer is genuinely nested.
+- A full child page must be a page route branch, not an Outlet rendered inside a drawer.
+- For editable forms, use useRefineUnsavedChangesGuard, pass its beforeClose callback to the surface, render its confirmation node, and use useRouteSurfaceClose for Cancel and successful submission.
+- Direct URL entry, refresh, browser back/forward, Escape, the close button, and backdrop dismissal must all restore the correct layer stack.
+- Apply ResourceAccessGuard to each business resource/action independently; do not rely on a parent list permission for unrelated child pages.
+
+Deliver the complete route definitions and React components using the application's existing design system.`;
+}