@nocobase/app-template-default 0.0.0-stage → 1.0.0-beta.57

package/client/routing/client-route.tsx

@@ -0,0 +1,129 @@
+import { useTranslation } from '@nocobase/i18n/client';
+import type {
+  AppClientRegisteredRoute,
+  AppClientRouteComponentModule,
+} from '@nocobase/app-client/plugins';
+import { useCan } from '@nocobase/app-plugin-authorization/client';
+import { NamespaceScope } from '@nocobase/i18n/client';
+import { type ReactElement, useEffect, useState } from 'react';
+import { ErrorBoundary } from 'react-error-boundary';
+
+import { Loading } from '#components/loading';
+import { Button } from '#components/ui/button';
+
+export interface ClientRouteProps {
+  readonly route: AppClientRegisteredRoute;
+}
+
+export function ClientRoute({ route }: ClientRouteProps): ReactElement {
+  const { authz, componentLoader } = route;
+  const checkAccess = authz !== 'skip';
+  const { can: allowed, isPending: accessLoading } = useCan(
+    authz === 'skip' ? undefined : authz,
+  );
+  const [componentModule, setComponentModule] =
+    useState<AppClientRouteComponentModule>();
+  const [loadError, setLoadError] = useState<unknown>();
+
+  useEffect(() => {
+    if (checkAccess && !allowed) return;
+    let active = true;
+
+    componentLoader!().then(
+      (module) => {
+        if (active) {
+          setComponentModule(module);
+          setLoadError(undefined);
+        }
+      },
+      (error: unknown) => {
+        if (active) {
+          setLoadError(error);
+        }
+      },
+    );
+
+    return () => {
+      active = false;
+    };
+  }, [allowed, checkAccess, componentLoader]);
+
+  if (loadError) {
+    return <ClientPageError route={route} />;
+  }
+
+  if (checkAccess && accessLoading) return <ClientPageLoading />;
+  if (checkAccess && !allowed) return <ClientPageDenied route={route} />;
+
+  if (!componentModule) {
+    return <ClientPageLoading />;
+  }
+
+  const Component = componentModule.default;
+
+  return (
+    <ErrorBoundary fallback={<ClientPageError route={route} />}>
+      {/* The owning package is the page's namespace, so a plugin page translates with a bare useTranslation(). */}
+      <NamespaceScope ns={route.packageName}>
+        <Component />
+      </NamespaceScope>
+    </ErrorBoundary>
+  );
+}
+
+function ClientPageDenied(inputProps: ClientRouteProps): ReactElement {
+  const { t } = useTranslation();
+  const { route } = inputProps;
+
+  return (
+    <section className='grid min-h-[calc(100svh-4rem)] place-items-center px-6'>
+      <section className='w-full max-w-lg space-y-3 text-center'>
+        <h1 className='text-xl font-semibold'>
+          {t('status.denied', { defaultValue: 'Access denied' })}
+        </h1>
+        <p className='text-sm text-muted-foreground'>
+          {t('status.deniedDescription', {
+            label: route.name,
+            defaultValue: `You do not have permission to access ${route.name}.`,
+          })}
+        </p>
+      </section>
+    </section>
+  );
+}
+
+function ClientPageLoading(): ReactElement {
+  const { t } = useTranslation();
+
+  return (
+    <Loading
+      className='min-h-[calc(100svh-4rem)]'
+      label={t('status.loadingPage', { defaultValue: 'Loading page' })}
+    />
+  );
+}
+
+function ClientPageError(inputProps: ClientRouteProps): ReactElement {
+  const { t } = useTranslation();
+  const { route } = inputProps;
+
+  return (
+    <section className='grid min-h-[calc(100svh-4rem)] place-items-center px-6'>
+      <section className='w-full max-w-lg space-y-4 text-center'>
+        <h1 className='text-xl font-semibold'>
+          {t('status.pageFailed', { defaultValue: 'Unable to load page' })}
+        </h1>
+        <p className='text-sm text-muted-foreground'>
+          {t('status.routeFailedDescription', {
+            label: route.name,
+            packageName: route.packageName,
+            defaultValue: `Route ${route.name} from ${route.packageName} could not be loaded.`,
+          })}
+        </p>
+        <Button onClick={() => window.location.reload()}>
+          {t('status.retry', { defaultValue: 'Retry' })}
+        </Button>
+      </section>
+    </section>
+  );
+}

package/client/routing/route-context.tsx

@@ -0,0 +1,85 @@
+import type { AppClientRegisteredRoute } from '@nocobase/app-client/plugins';
+import { useLocation } from 'react-router';
+import {
+  createContext,
+  useContext,
+  useMemo,
+  type PropsWithChildren,
+  type ReactElement,
+} from 'react';
+
+import { EMPTY_ARRAY } from '#lib/constants';
+
+import { matchRouteTree } from './route-navigation.js';
+
+/* eslint-disable react-refresh/only-export-components -- provider and hooks are intentionally colocated */
+
+/**
+ * One level of the trail leading to the current page.
+ *
+ * `pathname` is the resolved URL rather than the registered pattern, so a level such as `/orders/:id` links to
+ * where the user actually is. The route names itself: a level with no `breadcrumb` is structure rather than a
+ * destination — a tab, an overlay, or a layer that exists only to share a layout — and consumers skip it.
+ */
+export interface RouteTrailEntry {
+  readonly route: AppClientRegisteredRoute;
+  readonly pathname: string;
+}
+
+const RouteTreeContext = createContext<readonly AppClientRegisteredRoute[]>([]);
+export interface RouteTreeProviderProps extends PropsWithChildren {
+  readonly routes: readonly AppClientRegisteredRoute[];
+}
+
+/**
+ * Publishes the routes a page may be reached through, so anything below can work out where it is.
+ *
+ * It carries the tree rather than a trail derived from it: deriving is `useRouteTrail`'s job, which keeps the
+ * derivation and the memo that guards it in one place. `routes` still has to keep its identity between renders,
+ * since a new array re-renders every consumer; callers pass a memoised one.
+ */
+export function RouteTreeProvider({
+  children,
+  routes,
+}: RouteTreeProviderProps): ReactElement {
+  return (
+    <RouteTreeContext.Provider value={routes}>
+      {children}
+    </RouteTreeContext.Provider>
+  );
+}
+
+/**
+ * The trail of route levels leading to the current location.
+ *
+ * Every level the location matches is returned, structure included; whether a level is named, and what it is
+ * called, is its route's own `breadcrumb`, which a consumer reads. A breadcrumb title states what kind of page a
+ * level is rather than which record it is showing, so it is known before the page loads anything and the trail
+ * never changes while the user waits.
+ */
+export function useRouteTrail(): readonly RouteTrailEntry[] {
+  const routes = useContext(RouteTreeContext);
+  const { pathname } = useLocation();
+
+  return useMemo(
+    () =>
+      matchRouteTree(routes, pathname)?.map(
+        ({ route, pathname: resolvedPathname }) => ({
+          route,
+          // matchRoutes decodes path segments (but keeps encoded slashes). Use only
+          // its matched depth, taking the actual segments from the original URL.
+          pathname:
+            pathname
+              .split('/')
+              .slice(
+                0,
+                resolvedPathname === '/'
+                  ? 1
+                  : resolvedPathname.split('/').length,
+              )
+              .join('/') || '/',
+        }),
+      ) ?? EMPTY_ARRAY,
+    [pathname, routes],
+  );
+}

package/client/routing/route-navigation.ts

@@ -0,0 +1,153 @@
+import type { AppClientRegisteredRoute } from '@nocobase/app-client/plugins';
+import {
+  useAuthorizationRevision,
+  useAuthorizationClient,
+  type AuthorizationRequirement,
+} from '@nocobase/app-plugin-authorization/client';
+import { useEffect, useMemo, useState } from 'react';
+import { matchPath, matchRoutes, type RouteObject } from 'react-router';
+
+import { EMPTY_ARRAY } from '#lib/constants';
+
+export interface RouteNavigationItem {
+  readonly route: AppClientRegisteredRoute;
+  readonly children: readonly RouteNavigationItem[];
+}
+
+export function buildRouteNavigation(
+  routes: readonly AppClientRegisteredRoute[],
+  denied: ReadonlySet<string>,
+): RouteNavigationItem[] {
+  return routes.flatMap((route) => {
+    if (denied.has(routeKey(route))) return [];
+    const children = buildRouteNavigation(
+      route.children ?? EMPTY_ARRAY,
+      denied,
+    );
+    return route.navigation && (route.componentLoader || children.length)
+      ? [{ route, children }]
+      : children;
+  });
+}
+
+export function selectedNavigationId(
+  routes: readonly AppClientRegisteredRoute[],
+  pathname: string,
+  denied: ReadonlySet<string> = new Set(),
+): string | undefined {
+  const matches = matchRouteTree(routes, pathname);
+  const pages = navigationPages(buildRouteNavigation(routes, denied));
+  const visible = new Set(pages.map(routeKey));
+  const selected =
+    matches
+      ?.map(({ route }) => route)
+      .reverse()
+      .find(
+        (route) =>
+          route.componentLoader &&
+          route.navigation &&
+          visible.has(routeKey(route)),
+      ) ??
+    (matches
+      ? undefined
+      : pages
+          .filter((route) =>
+            matchPath({ path: route.path, end: false }, pathname),
+          )
+          .sort((a, b) => b.path.length - a.path.length)[0]);
+  return selected ? routeKey(selected) : undefined;
+}
+
+export function navigationPages(
+  items: readonly RouteNavigationItem[],
+): AppClientRegisteredRoute[] {
+  return items.flatMap(({ route, children }) => [
+    ...(route.componentLoader ? [route] : []),
+    ...navigationPages(children),
+  ]);
+}
+
+export function useRouteNavigation(
+  routes: readonly AppClientRegisteredRoute[],
+) {
+  const client = useAuthorizationClient();
+  // Recheck mounted menus after session or realtime permission invalidation.
+  const revision = useAuthorizationRevision();
+  const guards = useMemo(() => {
+    const collect = (
+      nodes: readonly AppClientRegisteredRoute[],
+    ): { id: string; check: AuthorizationRequirement }[] =>
+      // `unrestricted` pages are checked like any other: hidden unless the snapshot is unrestricted.
+      nodes.flatMap((route) => [
+        ...(route.componentLoader && route.authz !== 'skip'
+          ? [{ id: routeKey(route), check: route.authz }]
+          : []),
+        ...collect(route.children ?? EMPTY_ARRAY),
+      ]);
+    return collect(routes);
+  }, [routes]);
+  const [result, setResult] = useState<{
+    client: typeof client;
+    guards: typeof guards;
+    revision: number;
+    denied: ReadonlySet<string>;
+  }>();
+  useEffect(() => {
+    if (!guards.length) return;
+    let active = true;
+    void Promise.all(
+      guards.map(async ({ id, check }) => {
+        try {
+          return (await client.can(check)) ? undefined : id;
+        } catch {
+          return id;
+        }
+      }),
+    ).then((ids) => {
+      if (active)
+        setResult({
+          client,
+          guards,
+          revision,
+          denied: new Set(ids.filter((id) => id !== undefined)),
+        });
+    });
+    return () => {
+      active = false;
+    };
+  }, [client, guards, revision]);
+  const loading = Boolean(
+    guards.length &&
+    (result?.client !== client ||
+      result.guards !== guards ||
+      result.revision !== revision),
+  );
+  const denied = guards.length
+    ? (result?.denied ?? new Set<string>())
+    : new Set<string>();
+  return {
+    loading,
+    items: loading ? [] : buildRouteNavigation(routes, denied),
+    denied,
+  };
+}
+
+export function matchRouteTree(
+  routes: readonly AppClientRegisteredRoute[],
+  pathname: string,
+) {
+  const toMatch = (nodes: readonly AppClientRegisteredRoute[]): RouteObject[] =>
+    nodes.map((route) => ({
+      path: route.path,
+      handle: route,
+      children: toMatch(route.children ?? EMPTY_ARRAY),
+    }));
+  return matchRoutes(toMatch(routes), pathname)?.map((match) => ({
+    ...match,
+    route: match.route.handle as AppClientRegisteredRoute,
+  }));
+}
+
+export function routeKey(route: AppClientRegisteredRoute): string {
+  return `${route.packageName}:${route.path}:${route.id}`;
+}

package/client/routing/route-tree.tsx

@@ -0,0 +1,42 @@
+import type { AppClientRegisteredRoute } from '@nocobase/app-client/plugins';
+import type { ReactElement } from 'react';
+import { Outlet, Route } from 'react-router';
+
+import { EMPTY_ARRAY } from '#lib/constants';
+
+import { routeKey } from './route-navigation.js';
+import { ClientRoute } from './client-route.js';
+
+/** Groups pass children through; pages deliberately own their Outlet placement. */
+export function renderRouteTree(
+  routes: readonly AppClientRegisteredRoute[],
+  parentPath = '',
+): ReactElement[] {
+  return routes.map((route) => (
+    <Route
+      key={routeKey(route)}
+      path={
+        parentPath
+          ? route.path === parentPath ||
+            parentPath.startsWith(`${route.path.replace(/\/$/, '')}/`)
+            ? ''
+            : route.path.slice(parentPath === '/' ? 1 : parentPath.length + 1)
+          : route.path
+      }
+      element={
+        route.componentLoader ? (
+          <ClientRoute key={routeKey(route)} route={route} />
+        ) : (
+          <Outlet />
+        )
+      }
+    >
+      {renderRouteTree(
+        route.children ?? EMPTY_ARRAY,
+        parentPath.startsWith(`${route.path.replace(/\/$/, '')}/`)
+          ? parentPath
+          : route.path,
+      )}
+    </Route>
+  ));
+}

package/client/routing/standalone-page-layout.tsx

@@ -0,0 +1,15 @@
+import type { ReactElement } from 'react';
+import { Outlet } from 'react-router';
+
+import { ThemeSettings } from '../theme/index.js';
+
+export function StandalonePageLayout(): ReactElement {
+  return (
+    <div className='relative min-h-svh'>
+      <div className='fixed top-4 right-4 z-50'>
+        <ThemeSettings />
+      </div>
+      <Outlet />
+    </div>
+  );
+}

package/client/runtime.ts

@@ -0,0 +1,26 @@
+import defaultConfigs from './config/index.js';
+import { createAppClientConfig } from '@nocobase/app-client';
+import { defineAppRuntime } from '@nocobase/app-client/runtime';
+
+import locales from './locales/index.js';
+import plugins from './plugins.js';
+import reactProviders from './react-providers.js';
+import routeComponentOverrides from './route-overrides.js';
+import routes from './routes.js';
+import serviceProviders from './service-provider.js';
+import sourceExtensions from './source-extensions.js';
+
+const appRuntime = defineAppRuntime({
+  packageName: '@nocobase/app-template-default',
+  createAppConfig: createAppClientConfig,
+  defaultConfigs,
+  serviceProviders,
+  locales,
+  reactProviders,
+  routes,
+  plugins,
+  routeComponentOverrides,
+  sourceExtensions,
+});
+
+export default appRuntime;

package/client/service-provider.ts

@@ -0,0 +1,40 @@
+import { ClientApplication, toasterToken } from '@nocobase/app-client';
+import type { ClientServiceProviderConstructor } from '@nocobase/app-client/plugins';
+import { ServiceProvider } from '@nocobase/service-provider';
+
+import { createToaster } from './lib/toaster.js';
+
+export class DefaultClientServiceProvider extends ServiceProvider<ClientApplication> {
+  public readonly name: string = '@nocobase/app-template-default/client';
+  private previousDocumentTitle: string | undefined;
+
+  public override register(): void {
+    // What plugins and pages report through useToaster() reaches the Toaster in client/react-providers.ts from here.
+    this.app.container.instance(toasterToken, createToaster());
+  }
+
+  public override boot(): Promise<void> {
+    const configuredTitle = this.app.config.get<unknown>('app.title');
+    const title =
+      typeof configuredTitle === 'string' && configuredTitle.trim()
+        ? configuredTitle.trim()
+        : 'NocoBase';
+    this.app.refine.setOptions({ title: { text: title } });
+    this.previousDocumentTitle = document.title;
+    document.title = title;
+    return Promise.resolve();
+  }
+
+  public override shutdown(): Promise<void> {
+    if (this.previousDocumentTitle !== undefined) {
+      document.title = this.previousDocumentTitle;
+    }
+    return Promise.resolve();
+  }
+}
+
+const serviceProviders: readonly ClientServiceProviderConstructor[] = [
+  DefaultClientServiceProvider,
+];
+
+export default serviceProviders;

package/client/source-extensions.ts

@@ -0,0 +1,19 @@
+import type { AppClientSourceExtension } from '@nocobase/app-client/plugins';
+
+interface AppClientSourceExtensionModule {
+  readonly default: AppClientSourceExtension;
+}
+
+const extensionModules = import.meta.glob<AppClientSourceExtensionModule>(
+  './extensions/*/extension.ts',
+  { eager: true },
+);
+
+export const sourceExtensions: readonly AppClientSourceExtension[] =
+  Object.freeze(
+    Object.entries(extensionModules)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([, module]) => module.default),
+  );
+
+export default sourceExtensions;

package/client/startup.tsx

@@ -0,0 +1,22 @@
+import type { ReactElement } from 'react';
+
+import { Button } from '#components/ui/button';
+
+export interface AppStartupErrorProps {
+  error: unknown;
+}
+
+export function AppStartupError({ error }: AppStartupErrorProps): ReactElement {
+  const message =
+    error instanceof Error ? error.message : 'Unknown startup error.';
+
+  return (
+    <main className='grid min-h-svh place-items-center px-6'>
+      <section className='w-full max-w-lg space-y-4 text-center'>
+        <h1 className='text-xl font-semibold'>Unable to start application</h1>
+        <p className='text-sm text-muted-foreground'>{message}</p>
+        <Button onClick={() => window.location.reload()}>Retry</Button>
+      </section>
+    </main>
+  );
+}

package/client/styles.css

@@ -0,0 +1,122 @@
+@import 'tailwindcss';
+@config "../tailwind.config.mjs";
+@import 'tw-animate-css';
+@import 'shadcn/tailwind.css';
+@import './theme/themes/default.css';
+@import './theme/themes/compact.css';
+@source "./components/ui";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme {
+  --font-heading: var(--font-sans);
+  /* These names are implemented below as runtime-variable utilities. */
+  --shadow-2xs: initial;
+  --shadow-xs: initial;
+  --shadow-sm: initial;
+  --shadow-md: initial;
+  --shadow-lg: initial;
+  --shadow-xl: initial;
+  --shadow-2xl: initial;
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --radius-sm: calc(var(--radius) * 0.6);
+  --radius-md: calc(var(--radius) * 0.8);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) * 1.4);
+  --radius-2xl: calc(var(--radius) * 1.8);
+  --radius-3xl: calc(var(--radius) * 2.2);
+  --radius-4xl: calc(var(--radius) * 2.6);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+
+  body {
+    @apply min-h-svh bg-background font-sans text-base text-foreground antialiased;
+    margin: 0;
+  }
+
+  /* Keep semantic text in application and plugin content on the same typography. */
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6 {
+    @apply font-heading;
+  }
+
+  code,
+  pre,
+  kbd,
+  samp {
+    @apply font-mono;
+  }
+}
+
+/* Named shadows normally compile to literal values. Arbitrary-value utilities
+   preserve the runtime token and Tailwind's ring/shadow composition. */
+@utility shadow-2xs {
+  @apply shadow-(--shadow-2xs);
+}
+@utility shadow-xs {
+  @apply shadow-(--shadow-xs);
+}
+@utility shadow-sm {
+  @apply shadow-(--shadow-sm);
+}
+@utility shadow-md {
+  @apply shadow-(--shadow-md);
+}
+@utility shadow-lg {
+  @apply shadow-(--shadow-lg);
+}
+@utility shadow-xl {
+  @apply shadow-(--shadow-xl);
+}
+@utility shadow-2xl {
+  @apply shadow-(--shadow-2xl);
+}
+
+/* The application's one toaster mounts before any dialog opens, and every
+   overlay shares z-50, so a dialog portaled later would paint over its toasts.
+   Lift the viewport here rather than in the generated component; left outside
+   any layer so it outranks the component's z-50 utility. */
+[data-slot='toast-viewport'] {
+  z-index: 100;
+}

package/client/theme/index.ts

@@ -0,0 +1,4 @@
+export { useTheme } from 'next-themes';
+
+export { AppThemeProvider } from './theme-provider';
+export { ThemeSettings } from './theme-settings';

package/client/theme/theme-context.ts

@@ -0,0 +1,12 @@
+import { createContext, useContext } from 'react';
+import type { ThemePresetId } from './theme-presets';
+
+export const PresetContext = createContext<{
+  preset: ThemePresetId;
+  setPreset: (value: ThemePresetId) => void;
+} | null>(null);
+export function useThemePreset() {
+  const value = useContext(PresetContext);
+  if (!value) throw new Error('ThemeSettings requires AppThemeProvider');
+  return value;
+}