@nocobase/portal-template-default 1.0.16 → 1.0.17

package/src/extensions/nocobase-acl/demo/index.tsx

@@ -9,7 +9,13 @@ import {
   UserRoundCog,
   UsersRound,
 } from "lucide-react";
+import type { TreeMenuItem } from "@refinedev/core";
 
+import {
+  buildRouteResources,
+  defineAppRoutes,
+  RouteAccessGuard,
+} from "@/app/route-runtime";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
 import { CanAccess } from "@/components/access-control/can-access";
@@ -21,7 +27,11 @@ import {
   CardTitle,
 } from "@/components/ui/card";
 import { Input } from "@/components/ui/input";
-import type { RoleConstraint } from "@/lib/nocobase/acl";
+import {
+  filterMenuItemsByAcl,
+  type RoleConstraint,
+  useAclState,
+} from "@/lib/nocobase/acl";
 import { AclField, AclPage, AclRegion } from "../components/acl-boundary";
 import { AclPreviewProvider } from "./acl-preview-provider";
 import { AclBoundaryApi } from "./boundary-api";
@@ -58,6 +68,53 @@ const usersRouteRoles = {
   anyOf: ["admin"],
 } satisfies RoleConstraint;
 
+const navigationDemoRoutes = defineAppRoutes([
+  {
+    name: "dashboard",
+    path: "/dashboard",
+    resource: {
+      meta: {
+        label: "Dashboard",
+        icon: <LayoutPanelTop />,
+      },
+    },
+  },
+  {
+    name: "users",
+    path: "/users",
+    resource: {
+      meta: {
+        label: "Users",
+        icon: <UsersRound />,
+      },
+    },
+    access: {
+      roles: usersRouteRoles,
+    },
+  },
+  {
+    name: "roles",
+    path: "/roles",
+    resource: {
+      meta: {
+        label: "Roles",
+        icon: <UserRoundCog />,
+      },
+    },
+  },
+]);
+
+const navigationDemoResources = buildRouteResources(navigationDemoRoutes);
+const navigationDemoMenuItems: TreeMenuItem[] = navigationDemoResources.map(
+  (resource) => ({
+    key: resource.name,
+    name: resource.name,
+    route: typeof resource.list === "string" ? resource.list : undefined,
+    meta: resource.meta,
+    children: [],
+  })
+);
+
 const allowedRegionPermissions = {
   "users:list": {},
   "departments:list": {},
@@ -127,12 +184,12 @@ export function AclPatternsPage() {
           defaultScene: "User and role administration",
           defaultTarget:
             "Allow administrators to open Users, but remove it from navigation and block its direct URL for other roles.",
-          requirements: `- Put role constraints on the route resource through meta.acl.roles using anyOf, allOf, or noneOf.
-- Use meta.acl.type = "authenticated" when the route itself is role-controlled and its inner regions perform collection checks.
-- Let the Starter filter inaccessible sidebar items and choose the first accessible default route.
-- Wrap list, create, show, and edit routes with the Starter CanAccess and provide an AccessDenied fallback.
-- Mark non-collection utility pages as authenticated, snippet, route, or acl: false instead of treating them as collections.
-- If a parent route is denied but an accessible child remains, navigation must continue to the child route.`,
+          requirements: `- Define application-owned navigation once through defineAppRoutes in src/routes.tsx.
+- Put role constraints in the route access.roles field using anyOf, allOf, or noneOf.
+- Let the route runtime generate the Refine resource, filter the sidebar item, and wrap the direct route with CanAccess.
+- Do not repeat the same role list in Resource meta or a manually written route guard.
+- Keep resource/action, record, region, and field permissions in their dedicated ACL boundaries.
+- Let the Starter choose the first accessible route after inaccessible leaves and empty groups are removed.`,
         }}
       >
         <OutcomeComparison
@@ -343,21 +400,36 @@ function OutcomeComparison({
 }
 
 function NavigationPreview() {
+  const acl = useAclState();
+  const menuItems =
+    acl.status === "ready"
+      ? filterMenuItemsByAcl(navigationDemoMenuItems, acl.permissions)
+      : [];
+  const usersVisible = menuItems.some((item) => item.name === "users");
+  const usersRoute = navigationDemoRoutes.find(
+    (route) => route.name === "users"
+  );
+
   return (
     <div className="grid min-h-48 grid-cols-[150px_minmax(0,1fr)] overflow-hidden rounded-xl border bg-background">
       <aside className="border-r bg-muted/35 p-3">
         <div className="mb-3 text-xs font-semibold text-muted-foreground">
           Workspace
         </div>
-        <NavItem icon={<LayoutPanelTop />} label="Dashboard" />
-        <CanAccess roles={usersRouteRoles}>
-          <NavItem icon={<UsersRound />} label="Users" active />
-        </CanAccess>
-        <NavItem icon={<UserRoundCog />} label="Roles" />
+        {menuItems.map((item) => (
+          <NavItem
+            key={item.name}
+            icon={item.meta?.icon}
+            label={String(item.meta?.label ?? item.name)}
+            active={
+              usersVisible ? item.name === "users" : item.name === "dashboard"
+            }
+          />
+        ))}
       </aside>
       <div className="flex items-center justify-center p-5 text-center">
-        <CanAccess
-          roles={usersRouteRoles}
+        <RouteAccessGuard
+          access={usersRoute?.access}
           fallback={
             <div>
               <LayoutPanelTop className="mx-auto size-7 text-muted-foreground" />
@@ -375,7 +447,7 @@ function NavigationPreview() {
               Route is available
             </div>
           </div>
-        </CanAccess>
+        </RouteAccessGuard>
       </div>
     </div>
   );

package/src/extensions/nocobase-acl/demo/prompt-generator.tsx

@@ -45,6 +45,7 @@ Implementation contract
 - Use the Starter's built-in NocoBase accessControlProvider and ACL store.
 - NocoBase roles:check is the source of truth. Do not create a second permission store. Use configured role names only when the requirement explicitly includes a role constraint.
 - Import the Starter CanAccess from @/components/access-control/can-access. Use it with AclPage, AclRegion, and AclField for permission presentation. Do not copy their checks into local booleans or role comparisons.
+- For route-level role access, define the route once with defineAppRoutes in src/routes.tsx and put the constraint in access.roles. Let the route runtime control both its menu item and direct URL.
 - Use useGetRoles only when UI needs to display or pass through the current effective ACL roles; it is not a replacement permission evaluator.
 - Keep backend ACL enforcement in place; frontend checks only control presentation and navigation.
 - Import reusable components from the installed local entry point at @/extensions/nocobase-acl when page composition is needed.

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

@@ -0,0 +1,74 @@
+# NocoBase Mail
+
+Reusable mail inbox, compose, detail, and label components backed by the NocoBase mail API.
+
+After installation, import the components from `@/extensions/nocobase-mail`.
+
+- `MailInbox` full inbox with toolbar, table, detail panel, and compose.
+- `MailCompose` / `MailComposeForm` standalone compose dialog or embedded form,
+  with immediate and scheduled sending plus opt-in bulk mode, account-aware sender aliases,
+  server templates/signatures, recipient suggestions, reply/forward references, automatic draft
+  saving and recovery, and real attachment uploads.
+- `MailComposeAttachments` uploads files through `mail:messageAttachmentUpload`
+  with retry, removal, and the backend's 25 MB limit.
+- `MailFilters` folder, read-state, label, and todo-message filters.
+- `MailUnreadProvider` / `MailUnreadIndicator` / `MailUnreadIcon` reusable unread-count
+  display with interval, window-focus, and visibility refresh.
+- `MailDetail` threaded message detail with per-message Reply, conditional Reply all,
+  and Forward actions.
+- `MailSettingsDrawer` personal mailbox settings with Mailbox, Labels, Templates,
+  and Signature management tabs.
+- `MailMassTracking` bulk delivery tracking with recipient status, cancel, and resend.
+- `useMailMessages` hook for paginated message listing with search and filters.
+- `useMailCompose` hook to open compose from anywhere.
+- `MailLabelBadge` / `MailLabelsEditor` label display, assignment, and full CRUD.
+- `MailNoteEditor` per-message private notes.
+- `MailAttachmentList` attachment preview and download.
+- Message detail resolves authenticated `cid:` inline images and keeps those images out of the
+  regular attachment list.
+
+The mail API client (`mailApi`) uses the Starter's built-in `API_URL`, `getNocoBaseHeaders`, and `NOCOBASE_TOKEN_KEY` from `@/providers/constants`. A compatible NocoBase backend with the mail plugin enabled is required.
+
+## Send modes
+
+The standard compose form enables scheduled sending by default. Bulk sending is
+kept on the dedicated `/dev/mail/bulk` showcase page, where the bulk form and
+delivery jobs are visible together. Reusable compose forms can still opt into bulk mode:
+
+- **Schedule send** calls `mail:messageSend` with an ISO `scheduleSendAt` value.
+- **Bulk send** calls `mailMassMessages:send`, creates one separate message per
+  To recipient, and defaults to a 2-second interval between messages.
+
+```tsx
+<MailComposeForm
+  allowScheduleSend
+  allowBulkSend
+  defaultBulkIntervalMs={2000}
+/>
+```
+
+Bulk and scheduled sending are separate modes, matching the NocoBase email
+manager backend. Bulk sending requires at least two recipients and does not
+support a scheduled start time.
+
+Scheduled messages can be canceled back into drafts and edited or rescheduled.
+Opening a local draft enters compose mode with its uploaded attachments; local
+drafts can be updated or permanently deleted. Provider-backed drafts remain
+read-only and must be changed in the original mailbox so provider state and
+attachments are preserved. Trash actions are provider-backed: messages
+can be moved to trash, put back, or permanently deleted after confirmation.
+
+Templates are stored in `mailTemplates`; the backend model stores template
+content but no subject. Signatures are stored per mail account in
+`mailAccounts.config.signatures`, so changing the selected sender also changes
+the available/default signature. Use `recipientOptions` on the compose
+components to add application-specific record recipients alongside NocoBase
+users.
+
+Gmail aliases can be viewed and refreshed from Mail settings. Synced aliases are
+immediately available in the compose sender selector. Outlook does not expose
+sender aliases through this integration.
+
+Mailbox account creation, OAuth authorization, and provider settings are not
+part of this component package; they remain owned by the separate mail settings
+center.

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

@@ -0,0 +1,79 @@
+export * from "./types";
+export { mailApi } from "./mail-api";
+export { MailInbox } from "./mail-inbox";
+export type { MailInboxProps } from "./mail-inbox";
+export { MailToolbar } from "./mail-toolbar";
+export { MailTable } from "./mail-table";
+export { MailDetail } from "./mail-detail";
+export { MailCompose, MailComposeForm } from "./mail-compose";
+export type {
+  ComposeInitialValues,
+  ComposeReference,
+  ComposeMode,
+  ComposeVariant,
+  MailComposeFormProps,
+  MailComposeProps,
+} from "./mail-compose";
+export { MailSendActions } from "./mail-send-actions";
+export type { MailSendActionsProps } from "./mail-send-actions";
+export { MailRecipientInput } from "./mail-recipient-input";
+export type { MailRecipientInputProps } from "./mail-recipient-input";
+export { MailComposeAttachments } from "./mail-compose-attachments";
+export type { MailComposeAttachmentsProps } from "./mail-compose-attachments";
+export { getMailSenderCandidates, resolveMailSender } from "./mail-senders";
+export type { MailSenderCandidate } from "./mail-senders";
+export { MailRichEditor } from "./mail-rich-editor";
+export type { MailRichEditorProps } from "./mail-rich-editor";
+export { useMailSignatures } from "./use-mail-signatures";
+export type { MailSignatureValues } from "./use-mail-signatures";
+export { MailSignatureManager } from "./mail-signature-manager";
+export type { MailSignatureManagerProps } from "./mail-signature-manager";
+export { applySignature } from "./mail-signatures";
+export { useMailTemplates } from "./use-mail-templates";
+export type { MailTemplateValues } from "./use-mail-templates";
+export { MailTemplateManager } from "./mail-template-manager";
+export type { MailTemplateManagerProps } from "./mail-template-manager";
+export { useMailMessages } from "./use-mail-messages";
+export type {
+  UseMailMessagesOptions,
+  UseMailMessagesResult,
+} from "./use-mail-messages";
+export {
+  useMailCompose,
+  buildComposeInitial,
+  canReplyAll,
+} from "./use-mail-compose";
+export type { UseMailComposeOptions } from "./use-mail-compose";
+export { MailLabelBadge } from "./mail-label-badge";
+export { MailLabelsEditor } from "./mail-labels-editor";
+export { MailLabelManager } from "./mail-label-manager";
+export type { MailLabelManagerProps } from "./mail-label-manager";
+export { MailNoteEditor } from "./mail-note-editor";
+export { MailAttachmentList } from "./mail-attachment-list";
+export { createDebouncedDraftSaver } from "./mail-draft-autosave";
+export type { DebouncedDraftSaver } from "./mail-draft-autosave";
+export { serializeReplyQuote, splitReplyQuote } from "./mail-reply-quote";
+export type { MailReplyContent } from "./mail-reply-quote";
+export {
+  collectInlineContentIds,
+  filterInlineAttachments,
+  normalizeContentId,
+  replaceInlineImageSources,
+} from "./mail-inline-images";
+export { MailEmpty } from "./mail-empty";
+export {
+  MailUnreadIcon,
+  MailUnreadIndicator,
+  MailUnreadProvider,
+  useMailUnread,
+} from "./mail-unread";
+export type {
+  MailUnreadIndicatorProps,
+  MailUnreadProviderProps,
+} from "./mail-unread";
+export { MailSettingsDrawer } from "./mail-settings-drawer";
+export type { MailSettingsDrawerProps } from "./mail-settings-drawer";
+export { MailMassTracking } from "./mail-mass-tracking";
+export { useMailMassMessages } from "./use-mail-mass-messages";
+export { MailFilters } from "./mail-filters";
+export type { MailFilterValue, MailFiltersProps } from "./mail-filters";