@nocobase/portal-template-default 1.0.3 → 1.0.5

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.`;
+}

package/registry/nocobase-route-surfaces/extension.tsx

@@ -0,0 +1,119 @@
+import type { AppExtension } from "@/app/extension";
+import { Layers3 } from "lucide-react";
+import { lazy } from "react";
+import { Route } from "react-router";
+import { LazyRouteSurfaceDemo } from "./demo/lazy-route";
+
+const DemoHome = lazy(() =>
+  import("./demo").then((module) => ({
+    default: module.RouteSurfacesDemoHome,
+  }))
+);
+const DemoDrawer = lazy(() =>
+  import("./demo").then((module) => ({ default: module.DemoDrawerRoute }))
+);
+const DemoSecondDrawer = lazy(() =>
+  import("./demo").then((module) => ({
+    default: module.DemoSecondDrawerRoute,
+  }))
+);
+const DemoDialog = lazy(() =>
+  import("./demo").then((module) => ({ default: module.DemoDialogRoute }))
+);
+const DemoPage = lazy(() =>
+  import("./demo").then((module) => ({ default: module.DemoPageRoute }))
+);
+const DemoPageDrawer = lazy(() =>
+  import("./demo").then((module) => ({
+    default: module.DemoPageDrawerRoute,
+  }))
+);
+const DemoPageDrawerDialog = lazy(() =>
+  import("./demo").then((module) => ({
+    default: module.DemoPageDrawerDialogRoute,
+  }))
+);
+
+const routeSurfacesExtension: AppExtension = {
+  id: "nocobase-route-surfaces",
+  resources: [
+    {
+      name: "route-surfaces",
+      list: "/route-surfaces",
+      meta: {
+        label: "Route surfaces",
+        icon: <Layers3 />,
+        description: "URL-backed drawer, dialog, page, and nested route patterns.",
+        acl: { type: "authenticated" },
+      },
+    },
+  ],
+  routes: (
+    <>
+      <Route
+        key="route-surfaces-overlays"
+        path="/route-surfaces"
+        element={
+          <LazyRouteSurfaceDemo>
+            <DemoHome />
+          </LazyRouteSurfaceDemo>
+        }
+      >
+        <Route
+          path="drawer"
+          element={
+            <LazyRouteSurfaceDemo>
+              <DemoDrawer />
+            </LazyRouteSurfaceDemo>
+          }
+        >
+          <Route
+            path="second"
+            element={
+              <LazyRouteSurfaceDemo>
+                <DemoSecondDrawer />
+              </LazyRouteSurfaceDemo>
+            }
+          />
+        </Route>
+        <Route
+          path="dialog"
+          element={
+            <LazyRouteSurfaceDemo>
+              <DemoDialog />
+            </LazyRouteSurfaceDemo>
+          }
+        />
+      </Route>
+      <Route
+        key="route-surfaces-page"
+        path="/route-surfaces/page"
+        element={
+          <LazyRouteSurfaceDemo>
+            <DemoPage />
+          </LazyRouteSurfaceDemo>
+        }
+      >
+        <Route
+          path="drawer"
+          element={
+            <LazyRouteSurfaceDemo>
+              <DemoPageDrawer />
+            </LazyRouteSurfaceDemo>
+          }
+        >
+          <Route
+            path="dialog"
+            element={
+              <LazyRouteSurfaceDemo>
+                <DemoPageDrawerDialog />
+              </LazyRouteSurfaceDemo>
+            }
+          />
+        </Route>
+      </Route>
+    </>
+  ),
+};
+
+export default routeSurfacesExtension;

package/registry/nocobase-route-surfaces/index.ts

@@ -0,0 +1,7 @@
+export * from "./route-dialog";
+export * from "./route-drawer";
+export * from "./route-page";
+export * from "./route-surface-context";
+export * from "./use-refine-unsaved-changes";
+export * from "./use-route-surface-close";
+export type { RouteSurfaceBeforeClose } from "./use-route-surface-state";

package/registry/nocobase-route-surfaces/route-dialog.tsx

@@ -0,0 +1,145 @@
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+import { X } from "lucide-react";
+import { type ReactNode, useCallback, useContext } from "react";
+
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+import {
+  RouteOverlayDepthContext,
+  RouteSurfaceContext,
+} from "./route-surface-context";
+import {
+  type RouteSurfaceBeforeClose,
+  useRouteSurfaceState,
+} from "./use-route-surface-state";
+
+export function RouteDialog({
+  title,
+  description,
+  actions,
+  children,
+  closeLabel,
+  closeTo,
+  beforeClose,
+  className,
+  nested,
+}: {
+  title: ReactNode;
+  description?: ReactNode;
+  actions?: ReactNode;
+  children: ReactNode;
+  closeLabel: string;
+  closeTo: string;
+  beforeClose?: RouteSurfaceBeforeClose;
+  className?: string;
+  nested?: ReactNode;
+}) {
+  const parentOverlayDepth = useContext(RouteOverlayDepthContext);
+  const isNestedOverlay = parentOverlayDepth > 0;
+  const { open, setOpen, close, navigateAfterClose } = useRouteSurfaceState({
+    closeTo,
+    beforeClose,
+    animated: true,
+  });
+  const handleOpenChange = useCallback(
+    (nextOpen: boolean, eventDetails: DialogPrimitive.Root.ChangeEventDetails) => {
+      if (nextOpen) {
+        setOpen(true);
+        return;
+      }
+
+      eventDetails.cancel();
+      void close();
+    },
+    [close, setOpen]
+  );
+
+  return (
+    <RouteSurfaceContext.Provider value={close}>
+      <RouteOverlayDepthContext.Provider value={parentOverlayDepth + 1}>
+        <DialogPrimitive.Root
+          open={open}
+          onOpenChange={handleOpenChange}
+          onOpenChangeComplete={(nextOpen) => {
+            if (!nextOpen) navigateAfterClose();
+          }}
+        >
+          <DialogPrimitive.Portal>
+            {isNestedOverlay ? (
+              <RouteDialogBackdrop open={open} onClose={close} />
+            ) : (
+              <DialogPrimitive.Backdrop
+                className="fixed inset-0 isolate z-50 bg-black/10 duration-150 supports-backdrop-filter:backdrop-blur-xs data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0"
+                onClick={(event) => {
+                  event.stopPropagation();
+                  void close();
+                }}
+              />
+            )}
+            <DialogPrimitive.Popup
+            className={cn(
+              "fixed top-1/2 left-1/2 z-50 flex max-h-[calc(100dvh-2rem)] w-full max-w-[calc(100%-2rem)] -translate-x-1/2 -translate-y-1/2 flex-col overflow-hidden rounded-xl bg-popover text-sm text-popover-foreground ring-1 ring-foreground/10 duration-150 outline-none sm:max-w-2xl data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+              className
+            )}
+          >
+            <header className="relative shrink-0 border-b px-5 py-4 pr-14 text-left">
+              <div className="flex items-start justify-between gap-4">
+                <div className="min-w-0 space-y-1">
+                  <DialogPrimitive.Title className="font-heading truncate text-lg font-medium">
+                    {title}
+                  </DialogPrimitive.Title>
+                  {description ? (
+                    <DialogPrimitive.Description className="text-sm text-muted-foreground">
+                      {description}
+                    </DialogPrimitive.Description>
+                  ) : null}
+                </div>
+                {actions ? (
+                  <div className="flex shrink-0 items-center gap-2">
+                    {actions}
+                  </div>
+                ) : null}
+              </div>
+              <Button
+                type="button"
+                variant="ghost"
+                size="icon-sm"
+                className="absolute top-3 right-3"
+                onClick={() => void close()}
+              >
+                <X />
+                <span className="sr-only">{closeLabel}</span>
+              </Button>
+            </header>
+            {children}
+            </DialogPrimitive.Popup>
+          </DialogPrimitive.Portal>
+          {nested}
+        </DialogPrimitive.Root>
+      </RouteOverlayDepthContext.Provider>
+    </RouteSurfaceContext.Provider>
+  );
+}
+
+function RouteDialogBackdrop({
+  open,
+  onClose,
+}: {
+  open: boolean;
+  onClose: () => Promise<boolean>;
+}) {
+  return (
+    <div
+      role="presentation"
+      aria-hidden="true"
+      className={cn(
+        "fixed inset-0 isolate z-50 bg-black/10 transition-opacity duration-150 supports-backdrop-filter:backdrop-blur-xs",
+        open ? "opacity-100" : "pointer-events-none opacity-0"
+      )}
+      onClick={(event) => {
+        event.stopPropagation();
+        void onClose();
+      }}
+    />
+  );
+}

package/registry/nocobase-route-surfaces/route-drawer.tsx

@@ -0,0 +1,186 @@
+import { Drawer as DrawerPrimitive } from "@base-ui/react/drawer";
+import { X } from "lucide-react";
+import {
+  type CSSProperties,
+  type ReactNode,
+  useCallback,
+  useContext,
+} from "react";
+
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+import {
+  RouteOverlayDepthContext,
+  RouteSurfaceContext,
+} from "./route-surface-context";
+import {
+  type RouteSurfaceBeforeClose,
+  useRouteSurfaceState,
+} from "./use-route-surface-state";
+
+export function RouteDrawer({
+  title,
+  description,
+  actions,
+  children,
+  closeLabel,
+  closeTo,
+  beforeClose,
+  className,
+  nested,
+  stackOffset = "4rem",
+}: {
+  title: ReactNode;
+  description?: ReactNode;
+  actions?: ReactNode;
+  children: ReactNode;
+  closeLabel: string;
+  closeTo: string;
+  beforeClose?: RouteSurfaceBeforeClose;
+  className?: string;
+  nested?: ReactNode;
+  stackOffset?: string;
+}) {
+  const parentOverlayDepth = useContext(RouteOverlayDepthContext);
+  const isNestedOverlay = parentOverlayDepth > 0;
+  const { open, setOpen, close, navigateAfterClose } = useRouteSurfaceState({
+    closeTo,
+    beforeClose,
+    animated: true,
+  });
+  const handleOpenChange = useCallback(
+    (nextOpen: boolean, eventDetails: DrawerPrimitive.Root.ChangeEventDetails) => {
+      if (nextOpen) {
+        setOpen(true);
+        return;
+      }
+
+      eventDetails.cancel();
+      void close();
+    },
+    [close, setOpen]
+  );
+  const stackStyle = {
+    "--peek": stackOffset,
+    "--stack-step": 0,
+    "--bleed": "0px",
+  } as CSSProperties;
+
+  return (
+    <RouteSurfaceContext.Provider value={close}>
+      <RouteOverlayDepthContext.Provider value={parentOverlayDepth + 1}>
+        <DrawerPrimitive.Root
+          open={open}
+          swipeDirection="right"
+          onOpenChange={handleOpenChange}
+          onOpenChangeComplete={(nextOpen) => {
+            if (!nextOpen) navigateAfterClose();
+          }}
+        >
+          <DrawerPrimitive.Portal>
+            {isNestedOverlay ? (
+              <RouteDrawerBackdrop open={open} onClose={close} />
+            ) : (
+              <DrawerPrimitive.Backdrop
+                className="fixed inset-0 z-50 min-h-dvh bg-black/10 opacity-[max(var(--drawer-overlay-min-opacity,0),calc(1-var(--drawer-swipe-progress)))] transition-opacity duration-450 ease-[cubic-bezier(0.32,0.72,0,1)] select-none data-ending-style:pointer-events-none data-ending-style:opacity-0 data-starting-style:opacity-0 data-swiping:duration-0 supports-backdrop-filter:backdrop-blur-xs"
+                onClick={(event) => {
+                  event.stopPropagation();
+                  void close();
+                }}
+              />
+            )}
+            <DrawerPrimitive.Viewport className="pointer-events-none fixed inset-0 z-50 select-none">
+            <DrawerPrimitive.Popup
+              style={stackStyle}
+              className={cn(
+                "group/route-drawer pointer-events-auto fixed inset-y-0 right-0 z-50 flex w-full transform-[translate3d(var(--translate-x,0px),0,0)] flex-row bg-popover text-sm text-popover-foreground shadow-xl transition-transform duration-450 ease-[cubic-bezier(0.22,1,0.36,1)] will-change-transform outline-none sm:w-full lg:w-[42vw] lg:min-w-[40rem]",
+                "[--stack-peek-offset:max(0px,calc((var(--nested-drawers)-var(--stack-progress))*var(--peek)))] [--stack-progress:clamp(0,var(--drawer-swipe-progress),1)]",
+                "[--closed-transform:translate3d(calc(100%+2px),0,0)] [--translate-x:calc(var(--drawer-swipe-movement-x)-var(--stack-peek-offset))]",
+                "data-ending-style:transform-(--closed-transform) data-ending-style:opacity-[0.9999] data-starting-style:transform-(--closed-transform) data-swiping:duration-0 data-nested-drawer-swiping:duration-0",
+                "data-nested-drawer-open:overflow-hidden",
+                className
+              )}
+            >
+              <div
+                aria-hidden="true"
+                className="pointer-events-none absolute inset-0 z-20 bg-black/10 opacity-0 transition-opacity duration-450 ease-[cubic-bezier(0.22,1,0.36,1)] group-data-nested-drawer-open/route-drawer:opacity-100 supports-backdrop-filter:backdrop-blur-xs"
+              />
+              <DrawerPrimitive.Content className="flex min-h-0 flex-1 flex-col overflow-hidden overscroll-contain select-text group-data-swiping/route-drawer:select-none">
+                <header className="relative shrink-0 border-b px-5 py-4 pr-14 text-left">
+                  <div className="flex items-start justify-between gap-4">
+                    <div className="min-w-0 space-y-1">
+                      <DrawerPrimitive.Title className="font-heading truncate text-lg font-medium text-foreground">
+                        {title}
+                      </DrawerPrimitive.Title>
+                      {description ? (
+                        <DrawerPrimitive.Description className="text-sm text-balance text-muted-foreground">
+                          {description}
+                        </DrawerPrimitive.Description>
+                      ) : null}
+                    </div>
+                    {actions ? (
+                      <div className="flex shrink-0 items-center gap-2">
+                        {actions}
+                      </div>
+                    ) : null}
+                  </div>
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="icon-sm"
+                    className="absolute top-3 right-3"
+                    onClick={() => void close()}
+                  >
+                    <X />
+                    <span className="sr-only">{closeLabel}</span>
+                  </Button>
+                </header>
+                {children}
+              </DrawerPrimitive.Content>
+            </DrawerPrimitive.Popup>
+            </DrawerPrimitive.Viewport>
+          </DrawerPrimitive.Portal>
+          {nested}
+        </DrawerPrimitive.Root>
+      </RouteOverlayDepthContext.Provider>
+    </RouteSurfaceContext.Provider>
+  );
+}
+
+function RouteDrawerBackdrop({
+  open,
+  onClose,
+}: {
+  open: boolean;
+  onClose: () => Promise<boolean>;
+}) {
+  return (
+    <div
+      role="presentation"
+      aria-hidden="true"
+      className={cn(
+        "fixed inset-0 z-50 min-h-dvh bg-black/10 transition-opacity duration-450 ease-[cubic-bezier(0.32,0.72,0,1)] select-none supports-backdrop-filter:backdrop-blur-xs",
+        open ? "opacity-100" : "pointer-events-none opacity-0"
+      )}
+      onClick={(event) => {
+        event.stopPropagation();
+        void onClose();
+      }}
+    />
+  );
+}
+
+export function RouteDrawerFooter({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      className={cn(
+        "mt-auto flex shrink-0 flex-col gap-2 border-t px-5 py-4",
+        className
+      )}
+      {...props}
+    />
+  );
+}

package/registry/nocobase-route-surfaces/route-page.tsx

@@ -0,0 +1,29 @@
+import { type ReactNode } from "react";
+
+import { RouteSurfaceContext } from "./route-surface-context";
+import {
+  type RouteSurfaceBeforeClose,
+  useRouteSurfaceState,
+} from "./use-route-surface-state";
+
+export function RoutePage({
+  children,
+  closeTo,
+  beforeClose,
+}: {
+  children: ReactNode;
+  closeTo: string;
+  beforeClose?: RouteSurfaceBeforeClose;
+}) {
+  const { close } = useRouteSurfaceState({
+    closeTo,
+    beforeClose,
+    animated: false,
+  });
+
+  return (
+    <RouteSurfaceContext.Provider value={close}>
+      {children}
+    </RouteSurfaceContext.Provider>
+  );
+}

package/registry/nocobase-route-surfaces/route-surface-context.ts

@@ -0,0 +1,13 @@
+import { createContext } from "react";
+
+export type RouteSurfaceCloseOptions = {
+  skipBeforeClose?: boolean;
+};
+
+export type RouteSurfaceClose = (
+  options?: RouteSurfaceCloseOptions
+) => Promise<boolean>;
+
+export const RouteSurfaceContext = createContext<RouteSurfaceClose | null>(null);
+
+export const RouteOverlayDepthContext = createContext(0);