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

package/tests/components/page-harness.test.tsx

@@ -0,0 +1,318 @@
+// The model to copy for a page test: a page that loads data through `useApiClient`, checks a permission with
+// `useCan`, formats with `useLocale`, raises a toast and opens a child-route `RouteDialog`. The page under test is
+// defined in this file so the template has one to run; in an application, import the real page and its child routes
+// instead and keep the setup below.
+import { ApiClientError, useApiClient, useToaster } from '@nocobase/app-client';
+import { useAuthentication } from '@nocobase/app-plugin-authentication/client';
+import { useCan } from '@nocobase/app-plugin-authorization/client';
+import { useLocale, useTranslation } from '@nocobase/i18n/client';
+import {
+  TestI18nProvider,
+  createTestI18nRuntime,
+} from '@nocobase/i18n/testing';
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { type ReactElement, type ReactNode, useEffect, useState } from 'react';
+import { createMemoryRouter, Link, Outlet, RouterProvider } from 'react-router';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { RouteDialog } from '#components/route-dialog';
+import { Button } from '#components/ui/button';
+import { useRouteOverlay } from '#components/use-route-overlay';
+
+import enUS from '../../client/locales/en-US.js';
+
+// `vi.mock` factories run before this file's imports and code, so everything a factory uses is created here.
+const { api, toaster, permission, refresh } = vi.hoisted(() => ({
+  // One object for the whole file: a new one per call would restart every effect that depends on `api`.
+  api: { request: vi.fn() },
+  // One toaster too, so a test asserts what `show` was called with rather than how Base UI renders it.
+  toaster: { show: vi.fn(), close: vi.fn() },
+  // What `useCan` returns; a test sets `can`, `isPending` or `error` before rendering.
+  permission: {
+    can: true,
+    isPending: false,
+    error: undefined as unknown,
+  },
+  refresh: vi.fn(),
+}));
+
+vi.mock('@nocobase/app-client', async (original) => ({
+  // Keep the real module, so `ApiClientError` stays the class the page checks with `instanceof`.
+  ...(await original<typeof import('@nocobase/app-client')>()),
+  useApiClient: () => api,
+  useToaster: () => toaster,
+}));
+vi.mock('@nocobase/app-plugin-authentication/client', () => ({
+  useAuthentication: () => ({ refresh }),
+}));
+vi.mock('@nocobase/app-plugin-authorization/client', () => ({
+  useCan: () => ({
+    can: permission.can,
+    isPending: permission.isPending,
+    error: permission.error,
+    retry: vi.fn(),
+  }),
+}));
+
+// The inline page's own copy. A real page finds its keys in `client/locales/`; this one brings them, merged over the
+// application's so the dialog's close button and the shared `status.*` keys resolve as they would there.
+const copy = {
+  'status.sessionExpired': 'Your session has ended.',
+  actions: { ...enUS.actions, create: 'Create', signInAgain: 'Sign in again' },
+  items: {
+    create: {
+      action: 'New item',
+      title: 'Create an item',
+      success: 'Created the item',
+    },
+    form: { description: 'Name the item.' },
+    error: {
+      forbidden: 'You cannot view items.',
+      failed: 'Items could not be loaded.',
+    },
+  },
+};
+
+// The real runtime, strict: a key the resources lack fails the test instead of rendering as text.
+const runtime = await createTestI18nRuntime({
+  application: {
+    namespace: '@nocobase/app-template-default',
+    resources: { ...enUS, ...copy },
+  },
+});
+
+function I18n({ children }: { readonly children: ReactNode }): ReactElement {
+  return <TestI18nProvider runtime={runtime}>{children}</TestI18nProvider>;
+}
+
+interface Item {
+  readonly id: number;
+  readonly name: string;
+  readonly updatedAt: string;
+}
+
+function ItemsPage(): ReactElement {
+  const { t } = useTranslation();
+  const { locale } = useLocale();
+  const client = useApiClient();
+  const { refresh: refreshSession } = useAuthentication();
+  const { can: canCreate } = useCan({
+    resource: { type: 'composite', id: 'items' },
+    action: 'create',
+  });
+  const [result, setResult] = useState<{
+    readonly items?: Item[];
+    readonly error?: unknown;
+  }>();
+
+  useEffect(() => {
+    const controller = new AbortController();
+    client
+      .request<{ data: Item[] }>({ path: 'items', signal: controller.signal })
+      .then(
+        ({ data }) => {
+          if (!controller.signal.aborted) setResult({ items: data });
+        },
+        (error: unknown) => {
+          if (!controller.signal.aborted) setResult({ error });
+        },
+      );
+    return () => controller.abort();
+  }, [client]);
+
+  const dateFormat = new Intl.DateTimeFormat(locale, { dateStyle: 'medium' });
+  let content: ReactElement;
+  const status =
+    result?.error instanceof ApiClientError ? result.error.status : undefined;
+  if (status === 401) {
+    // The session ended: no retry, only a way to sign in again (in an application, SessionExpiredAlert).
+    content = (
+      <p role='alert'>
+        {t('status.sessionExpired')}
+        <Button onClick={() => void refreshSession()}>
+          {t('actions.signInAgain')}
+        </Button>
+      </p>
+    );
+  } else if (result?.error) {
+    const forbidden = status === 403;
+    content = (
+      <p role='alert'>
+        {forbidden ? t('items.error.forbidden') : t('items.error.failed')}
+        {forbidden ? null : <Button>{t('status.retry')}</Button>}
+      </p>
+    );
+  } else if (!result?.items) {
+    content = <p role='status'>{t('status.loading')}</p>;
+  } else {
+    content = (
+      <ul>
+        {result.items.map((item) => (
+          <li key={item.id}>
+            {item.name} {dateFormat.format(new Date(item.updatedAt))}
+          </li>
+        ))}
+      </ul>
+    );
+  }
+
+  return (
+    <div>
+      {canCreate ? (
+        <Button nativeButton={false} render={<Link to='new' />}>
+          {t('items.create.action')}
+        </Button>
+      ) : null}
+      {content}
+      <Outlet />
+    </div>
+  );
+}
+
+function NewItemFooter(): ReactElement {
+  const { t } = useTranslation();
+  const { close } = useRouteOverlay();
+  const toaster = useToaster();
+  return (
+    <Button
+      onClick={() => {
+        toaster.show({ type: 'success', title: t('items.create.success') });
+        void close();
+      }}
+    >
+      {t('actions.create')}
+    </Button>
+  );
+}
+
+function NewItemPage(): ReactElement {
+  const { t } = useTranslation();
+  return (
+    <RouteDialog title={t('items.create.title')} footer={<NewItemFooter />}>
+      <p>{t('items.form.description')}</p>
+    </RouteDialog>
+  );
+}
+
+/** The page as the application routes it: the list at /items with the create dialog as its child route. */
+function renderAt(url: string) {
+  const router = createMemoryRouter(
+    [
+      {
+        path: '/items',
+        element: <ItemsPage />,
+        children: [{ path: 'new', element: <NewItemPage /> }],
+      },
+    ],
+    { initialEntries: [url] },
+  );
+  render(<RouterProvider router={router} />, { wrapper: I18n });
+  return router;
+}
+
+describe('page test harness', () => {
+  beforeEach(() => {
+    api.request.mockReset();
+    toaster.show.mockReset();
+    permission.can = true;
+    permission.isPending = false;
+    permission.error = undefined;
+    refresh.mockReset();
+  });
+
+  it('loads the list with the request the page is expected to send', async () => {
+    api.request.mockResolvedValue({
+      data: [{ id: 1, name: 'Alpha', updatedAt: '2026-01-02T00:00:00Z' }],
+    });
+    renderAt('/items');
+
+    expect(screen.getByRole('status')).toHaveTextContent(
+      enUS['status.loading'],
+    );
+    expect(await screen.findByText(/Alpha/)).toBeInTheDocument();
+    expect(api.request).toHaveBeenCalledWith(
+      expect.objectContaining({ path: 'items' }),
+    );
+  });
+
+  it('explains a 403 without offering a retry', async () => {
+    api.request.mockRejectedValue(
+      new ApiClientError('Forbidden', {
+        status: 403,
+        method: 'GET',
+        url: '/api/items',
+      }),
+    );
+    renderAt('/items');
+
+    expect(await screen.findByRole('alert')).toHaveTextContent(
+      copy.items.error.forbidden,
+    );
+    expect(
+      screen.queryByRole('button', { name: enUS['status.retry'] }),
+    ).not.toBeInTheDocument();
+  });
+
+  it('treats a 401 as an ended session, not as a failure to retry', async () => {
+    api.request.mockRejectedValue(
+      new ApiClientError('Unauthorized', {
+        status: 401,
+        method: 'GET',
+        url: '/api/items',
+      }),
+    );
+    renderAt('/items');
+
+    expect(await screen.findByRole('alert')).toHaveTextContent(
+      copy['status.sessionExpired'],
+    );
+    expect(
+      screen.queryByRole('button', { name: enUS['status.retry'] }),
+    ).not.toBeInTheDocument();
+    await userEvent.click(
+      screen.getByRole('button', { name: copy.actions.signInAgain }),
+    );
+    expect(refresh).toHaveBeenCalledTimes(1);
+  });
+
+  it('shows the create action only with permission', async () => {
+    api.request.mockResolvedValue({ data: [] });
+    renderAt('/items');
+
+    // A Button rendered as a Link (nativeButton={false}) is announced as a button, so query it by that role.
+    expect(
+      await screen.findByRole('button', { name: copy.items.create.action }),
+    ).toHaveAttribute('href', '/items/new');
+  });
+
+  it('hides the create action without permission', async () => {
+    permission.can = false;
+    api.request.mockResolvedValue({ data: [] });
+    renderAt('/items');
+
+    await waitFor(() => expect(screen.queryByRole('status')).toBeNull());
+    expect(
+      screen.queryByRole('button', { name: copy.items.create.action }),
+    ).not.toBeInTheDocument();
+  });
+
+  it('opens the create dialog from its URL and closes it back to the list', async () => {
+    api.request.mockResolvedValue({ data: [] });
+    const router = renderAt('/items/new');
+
+    expect(
+      await screen.findByRole('dialog', { name: copy.items.create.title }),
+    ).toBeInTheDocument();
+    await userEvent.click(
+      screen.getByRole('button', { name: copy.actions.create }),
+    );
+
+    expect(toaster.show).toHaveBeenCalledWith({
+      type: 'success',
+      title: copy.items.create.success,
+    });
+    await waitFor(() => expect(router.state.location.pathname).toBe('/items'));
+    await waitFor(() => expect(screen.queryByRole('dialog')).toBeNull());
+  });
+});

package/tests/components/primitive-labels.test.tsx

@@ -0,0 +1,80 @@
+import {
+  TestI18nProvider,
+  createTestI18nRuntime,
+} from '@nocobase/i18n/testing';
+import { act, render, screen } from '@testing-library/react';
+import type { ReactElement, ReactNode } from 'react';
+import { describe, expect, it } from 'vitest';
+
+import { Dialog, DialogContent, DialogTitle } from '#components/ui/dialog';
+import { Sheet, SheetContent, SheetTitle } from '#components/ui/sheet';
+import { Spinner } from '#components/ui/spinner';
+import { createToastManager, Toaster } from '#components/ui/toast';
+
+import zhCN from '../../client/locales/zh-CN.js';
+
+// Chinese, because the registry's built-in English and the application's English wording are both "Close": only a
+// label that goes through the application's locale reads 关闭.
+const runtime = await createTestI18nRuntime({
+  locale: 'zh-CN',
+  application: { namespace: '@nocobase/app-template-default', resources: zhCN },
+});
+
+function I18n({ children }: { readonly children: ReactNode }): ReactElement {
+  return <TestI18nProvider runtime={runtime}>{children}</TestI18nProvider>;
+}
+
+// These shipped primitives replace the English the registry builds into them with translation keys. Updating one
+// by overwriting it with the registry's file brings the English back, and the matching test fails.
+describe('labels built into the shipped primitives', () => {
+  it('names the Dialog close button through actions.close', () => {
+    render(
+      <Dialog open>
+        <DialogContent>
+          <DialogTitle>Panel</DialogTitle>
+        </DialogContent>
+      </Dialog>,
+      { wrapper: I18n },
+    );
+
+    expect(
+      screen.getByRole('button', { name: zhCN.actions.close }),
+    ).toBeInTheDocument();
+  });
+
+  it('names the Sheet close button through actions.close', () => {
+    render(
+      <Sheet open>
+        <SheetContent>
+          <SheetTitle>Panel</SheetTitle>
+        </SheetContent>
+      </Sheet>,
+      { wrapper: I18n },
+    );
+
+    expect(
+      screen.getByRole('button', { name: zhCN.actions.close }),
+    ).toBeInTheDocument();
+  });
+
+  it('names the toast close button through actions.close', async () => {
+    const manager = createToastManager();
+    render(<Toaster toastManager={manager} />, { wrapper: I18n });
+
+    act(() => {
+      manager.add({ title: 'Saved' });
+    });
+
+    // Base UI keeps the close button aria-hidden until the toast list is expanded, so find it by its label.
+    const [close] = await screen.findAllByLabelText(zhCN.actions.close);
+    expect(close).toHaveAttribute('data-slot', 'toast-close');
+  });
+
+  it('labels the Spinner through status.loading', () => {
+    render(<Spinner />, { wrapper: I18n });
+
+    expect(
+      screen.getByRole('status', { name: zhCN['status.loading'] }),
+    ).toBeInTheDocument();
+  });
+});

package/tests/components/sidebar-permissions.test.tsx

@@ -0,0 +1,110 @@
+import type { AppClientRegisteredRoute } from '@nocobase/app-client/plugins';
+import { act, render, screen, waitFor, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { MemoryRouter } from 'react-router';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  useRouteNavigation,
+  routeKey,
+} from '../../client/routing/route-navigation';
+import { NavigationMenu } from '../../client/layouts/components/navigation-menu';
+import { AppSidebarProvider } from '../../client/layouts/components/app-sidebar';
+
+const auth = vi.hoisted(() => ({ revision: 0, client: { can: vi.fn() } }));
+vi.mock('@nocobase/app-plugin-authorization/client', () => ({
+  useAuthorizationClient: () => auth.client,
+  useAuthorizationRevision: () => auth.revision,
+}));
+vi.mock('@nocobase/i18n/client', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+beforeEach(() => {
+  auth.revision = 0;
+  localStorage.clear();
+  vi.stubGlobal('matchMedia', () => ({
+    matches: false,
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+  }));
+});
+afterEach(() => vi.unstubAllGlobals());
+function page(name: string): AppClientRegisteredRoute {
+  return {
+    id: name,
+    name,
+    path: `/${name}`,
+    packageName: 'test',
+    source: 'application',
+    auth: 'required',
+    authz: { resource: { type: 'page', id: name }, action: 'access' },
+    navigation: { title: name },
+    componentLoader: async () => ({ default: () => null }),
+  };
+}
+const visible = page('Allowed');
+const hidden = page('Denied');
+const routes: AppClientRegisteredRoute[] = [
+  { ...page('Group'), componentLoader: undefined, children: [visible, hidden] },
+  { ...page('Empty'), componentLoader: undefined, children: [hidden] },
+];
+function Menu() {
+  const { items } = useRouteNavigation(routes);
+  return (
+    <NavigationMenu
+      items={items}
+      label='Navigation'
+      selectedKey={routeKey(visible)}
+    />
+  );
+}
+describe.each(['expanded', 'collapsed', 'mobile'])(
+  'permissions in %s navigation',
+  (mode) => {
+    it('hides pending and denied entries, removes empty groups, and refreshes open menus', async () => {
+      if (mode === 'mobile') vi.stubGlobal('innerWidth', 390);
+      if (mode === 'collapsed')
+        localStorage.setItem('nocobase:sidebar:collapsed', 'true');
+      const resolve: ((allowed: boolean) => void)[] = [];
+      auth.client.can.mockImplementation(
+        () => new Promise<boolean>((done) => resolve.push(done)),
+      );
+      const tree = () => (
+        <MemoryRouter>
+          <AppSidebarProvider>
+            <Menu />
+          </AppSidebarProvider>
+        </MemoryRouter>
+      );
+      const { rerender } = render(tree());
+      expect(screen.queryByText('Group')).not.toBeInTheDocument();
+      await act(async () => {
+        resolve.forEach((done, i) => done(i === 0));
+      });
+      const user = userEvent.setup();
+      if (mode === 'collapsed') {
+        await user.hover(await screen.findByRole('button', { name: 'Group' }));
+        expect(
+          within(await screen.findByRole('dialog')).getByRole('link', {
+            name: 'Allowed',
+          }),
+        ).toHaveAttribute('href', '/Allowed');
+      } else {
+        expect(
+          await screen.findByRole('link', { name: 'Allowed' }),
+        ).toBeVisible();
+      }
+      expect(screen.queryByText('Denied')).not.toBeInTheDocument();
+      expect(screen.queryByText('Empty')).not.toBeInTheDocument();
+      auth.client.can.mockResolvedValue(false);
+      auth.revision++;
+      rerender(tree());
+      await waitFor(() =>
+        expect(screen.queryByText('Group')).not.toBeInTheDocument(),
+      );
+      expect(
+        screen.queryByRole('link', { name: 'Allowed' }),
+      ).not.toBeInTheDocument();
+      expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+    });
+  },
+);

package/tests/components/sidebar-preference.test.tsx

@@ -0,0 +1,42 @@
+import { act, renderHook } from '@testing-library/react';
+import { beforeEach, describe, expect, it } from 'vitest';
+import { useSidebarPreference } from '../../client/layouts/use-sidebar-preference';
+
+const key = 'nocobase:sidebar:collapsed';
+
+describe('shared sidebar preference', () => {
+  beforeEach(() => localStorage.clear());
+
+  it('shares changes across layouts and restores them after remount', () => {
+    const first = renderHook(() => useSidebarPreference());
+    const second = renderHook(() => useSidebarPreference());
+    expect(first.result.current[0]).toBe(false);
+    act(() => first.result.current[1]((value) => !value));
+    expect(second.result.current[0]).toBe(true);
+    expect(localStorage.getItem(key)).toBe('true');
+    first.unmount();
+    second.unmount();
+    const restored = renderHook(() => useSidebarPreference());
+    expect(restored.result.current[0]).toBe(true);
+    act(() => restored.result.current[1](false));
+    expect(localStorage.getItem(key)).toBe('false');
+  });
+
+  it('reads saved state and follows storage changes from another tab', () => {
+    localStorage.setItem(key, 'true');
+    const { result } = renderHook(() => useSidebarPreference());
+    expect(result.current[0]).toBe(true);
+    act(() => {
+      localStorage.removeItem(key);
+      window.dispatchEvent(new StorageEvent('storage', { key }));
+    });
+    expect(result.current[0]).toBe(false);
+  });
+
+  it('defaults to expanded for an invalid stored value', () => {
+    localStorage.setItem(key, 'invalid');
+    expect(renderHook(() => useSidebarPreference()).result.current[0]).toBe(
+      false,
+    );
+  });
+});

package/tests/fixtures/theme-tokens.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Theme token verification</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./theme-tokens.tsx"></script>
+  </body>
+</html>

package/tests/fixtures/theme-tokens.tsx

@@ -0,0 +1,111 @@
+import { Refine } from '@refinedev/core';
+import { createRoot } from 'react-dom/client';
+import { MemoryRouter } from 'react-router';
+import { Button } from '../../client/components/ui/button';
+import { Input } from '../../client/components/ui/input';
+import {
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+  PopoverTitle,
+} from '../../client/components/ui/popover';
+import {
+  AppSidebar,
+  AppSidebarProvider,
+  AppSidebarToggle,
+} from '../../client/layouts/components/app-sidebar';
+import { AppThemeProvider, ThemeSettings } from '../../client/theme';
+import '../../client/styles.css';
+
+// A server-free browser fixture using the real shell, primitives and theme provider.
+// Run Vite and open /main/tests/fixtures/theme-tokens.html.
+export default function Fixture() {
+  return (
+    <MemoryRouter>
+      <AppThemeProvider>
+        <Refine options={{ disableTelemetry: true }}>
+          <AppSidebarProvider>
+            <AppSidebar label='Fixture sidebar'>
+              <div className='p-2'>
+                <Input aria-label='Sidebar content' />
+              </div>
+            </AppSidebar>
+            <main className='min-w-0 flex-1 space-y-6 overflow-y-auto p-6'>
+              <div className='flex flex-wrap gap-2'>
+                <ThemeSettings />
+                <AppSidebarToggle />
+              </div>
+              <h1 className='text-3xl'>Theme tokens · 主题样式</h1>
+              <p data-testid='body'>Body text · 中文内容与 English text</p>
+              <p className='font-serif'>Serif text</p>
+              <code>const theme = 'compact';</code>
+              <div className='flex flex-wrap gap-2'>
+                <Button>Default action</Button>
+                <Button size='sm'>Small action</Button>
+                <Button size='xs'>Extra small</Button>
+                <Button variant='destructive'>Delete</Button>
+              </div>
+              <Input
+                aria-label='Example input'
+                placeholder='输入内容 / Enter text'
+              />
+              <Popover>
+                <PopoverTrigger render={<Button variant='outline' />}>
+                  Open popover
+                </PopoverTrigger>
+                <PopoverContent>
+                  <PopoverTitle>Portal heading</PopoverTitle>
+                  <p>Portal body · 浮层内容</p>
+                </PopoverContent>
+              </Popover>
+              <section className='rounded-xl border bg-card p-4 text-card-foreground shadow-md ring-1 ring-ring'>
+                <h2 className='text-xl'>Card heading</h2>
+                <p className='text-sm'>
+                  A long description that wraps without clipping when fonts and
+                  spacing change. 长文本应该正常换行，不应被控件裁切。
+                </p>
+              </section>
+              <svg
+                aria-label='Chart palette'
+                viewBox='0 0 120 30'
+                className='h-8'
+              >
+                {[1, 2, 3, 4, 5].map((i) => (
+                  <rect
+                    key={i}
+                    x={(i - 1) * 24}
+                    width='20'
+                    height='30'
+                    fill={`var(--chart-${i})`}
+                  />
+                ))}
+              </svg>
+              <div className='flex flex-wrap gap-2'>
+                <div className='rounded-sm border p-2'>sm</div>
+                <div className='rounded-md border p-2'>md</div>
+                <div className='rounded-lg border p-2'>lg</div>
+                <div className='rounded-xl border p-2'>xl</div>
+                <div className='rounded-2xl border p-2'>2xl</div>
+                <div className='rounded-3xl border p-2'>3xl</div>
+                <div className='rounded-4xl border p-2'>4xl</div>
+              </div>
+              <div className='flex flex-wrap gap-4'>
+                <div className='shadow-2xs p-2'>2xs</div>
+                <div className='shadow-xs p-2'>xs</div>
+                <div className='shadow-sm p-2'>sm</div>
+                <div className='shadow-md p-2'>md</div>
+                <div className='shadow-lg p-2'>lg</div>
+                <div className='shadow-xl p-2'>xl</div>
+                <div className='shadow-2xl p-2'>2xl</div>
+              </div>
+            </main>
+          </AppSidebarProvider>
+        </Refine>
+      </AppThemeProvider>
+    </MemoryRouter>
+  );
+}
+
+const root = createRoot(document.getElementById('root')!);
+root.render(<Fixture />);
+import.meta.hot?.dispose(() => root.unmount());