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

package/client/components/breadcrumbs.tsx

@@ -0,0 +1,167 @@
+import { usePageBreadcrumbLevels } from '@nocobase/app-client';
+import type { PageBreadcrumbLevel } from '@nocobase/app-client';
+import { useTranslation } from '@nocobase/i18n/client';
+import { Fragment, type ReactElement } from 'react';
+import { Link } from 'react-router';
+
+import {
+  Breadcrumb,
+  BreadcrumbEllipsis,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from '#components/ui/breadcrumb';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '#components/ui/dropdown-menu';
+import { cn } from 'cn';
+
+import {
+  useRouteTrail,
+  type RouteTrailEntry,
+} from '../routing/route-context.js';
+import { routeKey } from '../routing/route-navigation.js';
+
+export interface BreadcrumbsProps {
+  readonly className?: string;
+  /** Route keys the viewer may not open (`useRouteNavigation`): the trail names none of them. */
+  readonly denied?: ReadonlySet<string>;
+}
+
+/**
+ * The trail of destinations leading to the current page, which the layout renders in its header after the sidebar
+ * toggle. Pages do not place it.
+ *
+ * By default it is the route trail: a route earns a level by declaring `breadcrumb`, or by being a menu page
+ * (`navigation` with a component), and structure that only owns a path segment — a tab, an overlay, a group with
+ * neither — is skipped. A page whose trail names records, or does not follow its URL, declares the whole trail with
+ * `usePageBreadcrumb` from `@nocobase/app-client`. Earlier levels link where a page sits behind them; the last is the
+ * current page.
+ *
+ * On a phone only the last level shows, beside the brand; on a medium screen a trail of three or more levels keeps its
+ * first and last and folds the middle into a menu.
+ */
+export function Breadcrumbs({
+  className,
+  denied,
+}: BreadcrumbsProps = {}): ReactElement | null {
+  const trail = useRouteTrail();
+  const declared = usePageBreadcrumbLevels();
+  const { t } = useTranslation();
+  const trailLevels =
+    declared ??
+    trail.flatMap((entry): PageBreadcrumbLevel[] => {
+      const title = routeLevelTitle(entry);
+      if (title === undefined || denied?.has(routeKey(entry.route))) return [];
+      return [
+        {
+          label: t(title, {
+            ns: entry.route.packageName,
+            defaultValue: title,
+          }),
+          ...(entry.route.componentLoader ? { to: entry.pathname } : {}),
+        },
+      ];
+    });
+
+  if (trailLevels.length === 0) return null;
+  // A level is told apart by its depth and label; two levels may share either alone.
+  const levels = trailLevels.map((level, depth) => ({
+    ...level,
+    key: `${depth}:${level.label}`,
+  }));
+  const last = levels.length - 1;
+  const folded = levels.slice(1, last);
+
+  return (
+    <Breadcrumb
+      aria-label={t('navigation.breadcrumb', { defaultValue: 'Breadcrumb' })}
+      className={cn('min-w-0', className)}
+    >
+      <BreadcrumbList className='flex-nowrap'>
+        {levels.map((level, index) => (
+          <Fragment key={level.key}>
+            {index === 1 && folded.length > 0 ? (
+              <>
+                <BreadcrumbItem className='hidden md:inline-flex lg:hidden'>
+                  <DropdownMenu>
+                    <DropdownMenuTrigger
+                      aria-label={t('navigation.breadcrumbMore', {
+                        defaultValue: 'Show the levels in between',
+                      })}
+                      className='rounded-sm transition-colors hover:text-foreground'
+                    >
+                      <BreadcrumbEllipsis />
+                    </DropdownMenuTrigger>
+                    <DropdownMenuContent align='start'>
+                      {folded.map((middle) =>
+                        middle.to ? (
+                          <DropdownMenuItem
+                            key={middle.key}
+                            render={<Link to={middle.to} />}
+                          >
+                            {middle.label}
+                          </DropdownMenuItem>
+                        ) : (
+                          <DropdownMenuItem key={middle.key} disabled>
+                            {middle.label}
+                          </DropdownMenuItem>
+                        ),
+                      )}
+                    </DropdownMenuContent>
+                  </DropdownMenu>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator className='hidden md:block lg:hidden' />
+              </>
+            ) : null}
+            <BreadcrumbItem
+              className={cn(
+                'min-w-0',
+                index === last
+                  ? undefined
+                  : index === 0
+                    ? 'hidden shrink-0 md:inline-flex'
+                    : 'hidden shrink-0 lg:inline-flex',
+              )}
+            >
+              {index === last ? (
+                <BreadcrumbPage className='truncate font-medium'>
+                  {level.label}
+                </BreadcrumbPage>
+              ) : level.to ? (
+                <BreadcrumbLink
+                  className='max-w-48 truncate'
+                  render={<Link to={level.to} />}
+                >
+                  {level.label}
+                </BreadcrumbLink>
+              ) : (
+                <span className='max-w-48 truncate'>{level.label}</span>
+              )}
+            </BreadcrumbItem>
+            {index < last ? (
+              <BreadcrumbSeparator
+                className={index === 0 ? 'hidden md:block' : 'hidden lg:block'}
+              />
+            ) : null}
+          </Fragment>
+        ))}
+      </BreadcrumbList>
+    </Breadcrumb>
+  );
+}
+
+/** A route's level title: its `breadcrumb`, else the menu title of a page; `undefined` for structure. */
+function routeLevelTitle(entry: RouteTrailEntry): string | undefined {
+  const { route } = entry;
+  if (route.breadcrumb) return route.breadcrumb.title;
+  if (route.navigation && route.componentLoader) return route.navigation.title;
+  return undefined;
+}
+
+Breadcrumbs.displayName = 'Breadcrumbs';

package/client/components/inbox-badge.ts

@@ -0,0 +1,49 @@
+import { useEffect } from 'react';
+
+/**
+ * What the inbox button shows: the count of what waits on the viewer (`decisions`), or, with none waiting, the count
+ * of unread items; nothing otherwise.
+ *
+ * What waits wins outright rather than adding up with the unread items. The two overlap: a waiting decision is also an
+ * unread item until opened, so a sum would count it twice. And a sum would blur what the badge means: amber says
+ * "needs you", which an unread notification does not.
+ */
+export type InboxBadge = {
+  readonly kind: 'decisions' | 'unread';
+  readonly count: number;
+  readonly text: string;
+} | null;
+
+/** The badge's text for `count`: "99+" above 99 so the badge keeps its size, none at zero. */
+export function inboxBadgeText(count: number): string | null {
+  if (!Number.isFinite(count) || count <= 0) return null;
+  return count > 99 ? '99+' : String(count);
+}
+
+export function inboxBadge(decisions: number, unread: number): InboxBadge {
+  const pending = inboxBadgeText(decisions);
+  if (pending) return { kind: 'decisions', count: decisions, text: pending };
+  const text = inboxBadgeText(unread);
+  return text ? { kind: 'unread', count: unread, text } : null;
+}
+
+const TITLE_COUNT = /^\(\d+\+?\) /;
+
+/**
+ * The browser tab title with the badge text in front (`(3) Inbox`), or without it when `text` is null. Any earlier
+ * count prefix is replaced, so applying it again never stacks prefixes.
+ */
+export function inboxTitle(title: string, text: string | null): string {
+  const base = title.replace(TITLE_COUNT, '');
+  return text ? `(${text}) ${base}` : base;
+}
+
+/** Puts the badge text in front of the browser tab title while mounted, and takes it off again. */
+export function useDocumentTitleBadge(text: string | null): void {
+  useEffect(() => {
+    document.title = inboxTitle(document.title, text);
+    return () => {
+      document.title = inboxTitle(document.title, null);
+    };
+  }, [text]);
+}

package/client/components/inbox-button.tsx

@@ -0,0 +1,132 @@
+import { useTranslation } from '@nocobase/i18n/client';
+import { InboxIcon } from 'lucide-react';
+import type { ReactElement } from 'react';
+import { Link, useLocation } from 'react-router';
+
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '#components/ui/tooltip';
+import { cn } from 'cn';
+
+import type { InboxBadge } from './inbox-badge.js';
+
+/** Other words for the button, in place of its `inboxButton.*` translations. */
+export interface InboxButtonLabels {
+  readonly title?: string;
+  readonly pending?: (count: number) => string;
+  readonly unread?: (count: number) => string;
+  readonly pendingHint?: (count: number) => string;
+  readonly unreadHint?: (count: number) => string;
+}
+
+export interface InboxButtonProps {
+  /** Where the inbox is. */
+  readonly to?: string;
+  /** What the badge shows (`inboxBadge`); none when null. */
+  readonly badge: InboxBadge;
+  /** Marks the button current; on `to` and below it when left out. */
+  readonly active?: boolean;
+  readonly labels?: InboxButtonLabels;
+  /** The prefix of its test ids: `<prefix>-button` and `<prefix>-badge`. */
+  readonly idPrefix?: string;
+  readonly className?: string;
+}
+
+/**
+ * A header button linking to the inbox, with a badge: amber with the count of what waits on the viewer, or in the
+ * primary color with the unread count when nothing waits. The label and the tooltip say which count it is.
+ */
+export function InboxButton({
+  to = '/inbox',
+  badge,
+  active,
+  labels,
+  idPrefix = 'nocobase-inbox',
+  className,
+}: InboxButtonProps): ReactElement {
+  const { t } = useTranslation();
+  const { pathname } = useLocation();
+  const current = active ?? (pathname === to || pathname.startsWith(`${to}/`));
+  const title =
+    labels?.title ?? t('inboxButton.title', { defaultValue: 'Inbox' });
+  const label = !badge
+    ? title
+    : badge.kind === 'decisions'
+      ? (labels?.pending?.(badge.count) ??
+        t('inboxButton.pending', {
+          count: badge.count,
+          defaultValue: 'Inbox, {{count}} waiting',
+        }))
+      : (labels?.unread?.(badge.count) ??
+        t('inboxButton.unread', {
+          count: badge.count,
+          defaultValue: 'Inbox, {{count}} unread',
+        }));
+
+  return (
+    <Tooltip>
+      <TooltipTrigger
+        render={
+          <Link
+            to={to}
+            aria-current={current ? 'page' : undefined}
+            className={cn(
+              'relative inline-flex size-9 shrink-0 items-center justify-center rounded-lg border transition-colors focus-visible:outline-none focus-visible:ring-3 focus-visible:ring-ring/50',
+              // On the inbox itself: filled and outlined in the text color, apart from the plain buttons beside it.
+              current
+                ? 'border-foreground/40 bg-accent text-foreground hover:bg-accent'
+                : 'border-border/70 bg-background/60 text-foreground hover:bg-muted',
+              className,
+            )}
+            data-testid={`${idPrefix}-button`}
+          />
+        }
+        aria-label={label}
+      >
+        <InboxIcon className='size-4.5' aria-hidden='true' />
+        {/* Amber means "needs you"; the primary color (the brand's, in a themed application) only that something is
+            unread. Ringed in the header's color so it stays apart from the border. */}
+        {badge ? (
+          <span
+            className={cn(
+              // Anchored to the corner and pushed a third of its size out, whatever its width.
+              'absolute top-0 right-0 flex h-4.5 min-w-4.5 translate-x-1/3 -translate-y-1/3 items-center justify-center rounded-full px-1 leading-none font-semibold tabular-nums ring-2 ring-background',
+              // "99+" in smaller type, so the badge stays a pill rather than covering the icon.
+              badge.text.length > 2 ? 'text-[9px]' : 'text-[11px]',
+              badge.kind === 'decisions'
+                ? 'bg-amber-500 text-white'
+                : 'bg-primary text-primary-foreground',
+            )}
+            data-testid={`${idPrefix}-badge`}
+            data-kind={badge.kind}
+            aria-hidden='true'
+          >
+            {badge.text}
+          </span>
+        ) : null}
+      </TooltipTrigger>
+      <TooltipContent side='bottom' className='max-w-64 flex-col items-start'>
+        <span>{title}</span>
+        {badge ? (
+          <span className='opacity-80'>
+            {badge.kind === 'decisions'
+              ? (labels?.pendingHint?.(badge.count) ??
+                t('inboxButton.pendingHint', {
+                  count: badge.count,
+                  defaultValue:
+                    '{{count}} waiting for you; it goes down once they are handled.',
+                }))
+              : (labels?.unreadHint?.(badge.count) ??
+                t('inboxButton.unreadHint', {
+                  count: badge.count,
+                  defaultValue:
+                    '{{count}} unread; it goes down as you read them.',
+                }))}
+          </span>
+        ) : null}
+      </TooltipContent>
+    </Tooltip>
+  );
+}

package/client/components/inbox-header-button.tsx

@@ -0,0 +1,25 @@
+import { useAuthentication } from '@nocobase/app-plugin-authentication/client';
+import {
+  useInboxRefresh,
+  useInboxUnreadCount,
+} from '@nocobase/app-plugin-notification-in-app/client/inbox';
+import type { ReactElement } from 'react';
+
+import { inboxBadge, useDocumentTitleBadge } from '#components/inbox-badge';
+import { InboxButton } from '#components/inbox-button';
+
+/** The header's link to `/inbox` with the unread count, for a signed-in person only. */
+export function InboxHeaderButton(): ReactElement | null {
+  const { session, isPending } = useAuthentication();
+  if (isPending || !session?.user) return null;
+  return <SignedInInboxButton key={session.user.id} />;
+}
+
+function SignedInInboxButton(): ReactElement {
+  useInboxRefresh();
+  const unread = useInboxUnreadCount();
+  // Nothing in this application asks the viewer to decide, so the badge counts what is unread.
+  const badge = inboxBadge(0, unread.data ?? 0);
+  useDocumentTitleBadge(badge?.text ?? null);
+  return <InboxButton badge={badge} />;
+}

package/client/components/loading.tsx

@@ -0,0 +1,35 @@
+import { useTranslation } from '@nocobase/i18n/client';
+import type { ComponentPropsWithoutRef, ReactElement } from 'react';
+
+import { Spinner } from '#components/ui/spinner';
+import { cn } from 'cn';
+
+export interface LoadingProps extends ComponentPropsWithoutRef<'div'> {
+  readonly fullscreen?: boolean;
+  readonly label?: string;
+}
+
+export function Loading(inputProps: LoadingProps): ReactElement {
+  const { t } = useTranslation();
+  const {
+    className,
+    fullscreen = false,
+    label = t('status.loading', { defaultValue: 'Loading' }),
+    ...props
+  } = inputProps;
+
+  return (
+    <div
+      aria-label={label}
+      className={cn(
+        'flex items-center justify-center',
+        fullscreen && 'min-h-svh w-full bg-background',
+        className,
+      )}
+      role='status'
+      {...props}
+    >
+      <Spinner aria-hidden='true' role={undefined} />
+    </div>
+  );
+}

package/client/components/page-container.tsx

@@ -0,0 +1,24 @@
+import type { ComponentProps, ReactElement } from 'react';
+
+import { cn } from 'cn';
+
+export type PageContainerProps = ComponentProps<'section'>;
+
+/**
+ * The frame of a page: the full width, the responsive padding, and the spacing between its sections.
+ *
+ * A page renders one. Content that renders inside another page — an inline child route, a tab panel — already sits in
+ * that page's container and adds none of its own, while a covering `RouteChildPage` is a surface of its own and
+ * places one inside it.
+ */
+export function PageContainer({
+  className,
+  ...props
+}: PageContainerProps): ReactElement {
+  return (
+    <section
+      className={cn('w-full space-y-6 p-6 md:p-8', className)}
+      {...props}
+    />
+  );
+}

package/client/components/page-header.tsx

@@ -0,0 +1,33 @@
+import type { ReactElement, ReactNode } from 'react';
+
+export interface PageHeaderProps {
+  readonly title: ReactNode;
+  readonly description?: ReactNode;
+  /** Page-level actions, aligned to the right of the title from the `sm` breakpoint up. */
+  readonly actions?: ReactNode;
+}
+
+/** The heading of a page: its only `h1`, an optional description, and the actions that apply to the whole page. */
+export function PageHeader({
+  actions,
+  description,
+  title,
+}: PageHeaderProps): ReactElement {
+  return (
+    <header className='flex flex-col gap-4 sm:flex-row sm:items-end sm:justify-between'>
+      <div className='min-w-0'>
+        <h1 className='font-heading text-3xl font-semibold tracking-[-0.035em]'>
+          {title}
+        </h1>
+        {description ? (
+          <p className='mt-2 max-w-2xl text-sm leading-6 text-muted-foreground'>
+            {description}
+          </p>
+        ) : null}
+      </div>
+      {actions ? (
+        <div className='flex shrink-0 items-center gap-2'>{actions}</div>
+      ) : null}
+    </header>
+  );
+}

package/client/components/route-child-page.tsx

@@ -0,0 +1,121 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useRef,
+  type ReactElement,
+  type ReactNode,
+  type RefObject,
+} from 'react';
+
+import { cn } from 'cn';
+
+export interface RouteChildPageProps {
+  readonly children?: ReactNode;
+  readonly className?: string;
+}
+
+// The scrolling element of the layer a child page is rendered inside, when it is rendered inside one.
+const EnclosingLayerContext =
+  createContext<RefObject<HTMLDivElement | null> | null>(null);
+
+/**
+ * A child page, laid over the page that opened it.
+ *
+ * It is the third way a child route can present itself, beside `RouteDialog` and `RouteDrawer`: those float in the
+ * middle or at the side, this one covers the content area. Because it covers rather than replaces, the page beneath
+ * keeps its DOM — a draft being typed, a scroll position — and gets it back when this layer closes.
+ *
+ * Unlike the other two it is deliberately **not** modal. It does not portal out of the content area or trap focus,
+ * because the user is still on a page of the application and must be able to reach the sidebar. What closes it is
+ * the header's breadcrumb or the `BackButton` above its heading, or the browser's back button — not an X or Escape.
+ *
+ * It is two elements, the way the layout's content area is: the outer one positions and never scrolls, the inner one
+ * scrolls. A deeper layer rendered beside this component anchors to the content area, as this one does, which is
+ * where a page's own outlet belongs. One rendered inside it — a child page of a tab, which can only render through
+ * the tab's outlet — anchors to the outer element: it covers this layer whole instead of scrolling out of sight with
+ * the content once the user has scrolled this page.
+ */
+export function RouteChildPage({
+  children,
+  className,
+}: RouteChildPageProps): ReactElement {
+  const enclosingScrollerRef = useContext(EnclosingLayerContext);
+  const layerRef = useRef<HTMLDivElement>(null);
+  const scrollerRef = useRef<HTMLDivElement>(null);
+
+  // Covering a page is not the same as closing it: the siblings underneath keep their DOM, and with it their place
+  // in the tab order and the accessibility tree. Left alone they are reachable behind opaque paint — a keyboard
+  // user tabs through controls nothing on screen shows, and focusing one scrolls the covered page into view while
+  // the layer, anchored to the content area, does not move. `inert` switches off exactly what this layer covers.
+  // The sidebar and the header are outside the content area and so outside this list, which is what keeps the
+  // component non-modal. A sibling already marked belongs to the layer below and is left for it to restore.
+  //
+  // Inside another layer, what this one covers also surrounds it: the enclosing page's header and tab bar, up to that
+  // layer's scrolling element. That element stays live, since it holds this layer; everything else in it is covered.
+  // At this layer's own level only the siblings before it are covered: the ones after it are deeper layers.
+  useEffect(() => {
+    const layer = layerRef.current;
+    const boundary = enclosingScrollerRef?.current;
+    const covered: Element[] = [];
+    const cover = (element: Element): void => {
+      if (element.hasAttribute('inert')) return;
+      element.setAttribute('inert', '');
+      covered.push(element);
+    };
+    for (
+      let sibling = layer?.previousElementSibling ?? null;
+      sibling;
+      sibling = sibling.previousElementSibling
+    ) {
+      cover(sibling);
+    }
+    if (layer && boundary?.contains(layer)) {
+      for (
+        let ancestor = layer.parentElement;
+        ancestor && ancestor !== boundary;
+        ancestor = ancestor.parentElement
+      ) {
+        for (
+          let sibling = ancestor.previousElementSibling;
+          sibling;
+          sibling = sibling.previousElementSibling
+        ) {
+          cover(sibling);
+        }
+        for (
+          let sibling = ancestor.nextElementSibling;
+          sibling;
+          sibling = sibling.nextElementSibling
+        ) {
+          cover(sibling);
+        }
+      }
+    }
+    return () => {
+      for (const element of covered) element.removeAttribute('inert');
+    };
+  });
+
+  return (
+    <div
+      className={cn(
+        'absolute inset-0 z-10 overflow-hidden bg-background',
+        className,
+      )}
+      data-slot='route-child-page'
+      ref={layerRef}
+    >
+      {/* Scrolling stops at this layer rather than carrying on into the page it covers, which keeps that page's
+          scroll position for when this layer closes. */}
+      <div
+        className='h-full overflow-y-auto overscroll-contain'
+        ref={scrollerRef}
+      >
+        <EnclosingLayerContext.Provider value={scrollerRef}>
+          {children}
+        </EnclosingLayerContext.Provider>
+      </div>
+    </div>
+  );
+}

package/client/components/route-dialog.tsx

@@ -0,0 +1,10 @@
+import type { ReactElement } from 'react';
+
+import { RouteOverlay, type RouteOverlayProps } from './route-overlay.js';
+
+export type RouteDialogProps = RouteOverlayProps;
+
+/** A child route presented as a centered modal dialog. */
+export function RouteDialog(props: RouteDialogProps): ReactElement {
+  return <RouteOverlay {...props} />;
+}

package/client/components/route-drawer.tsx

@@ -0,0 +1,10 @@
+import type { ReactElement } from 'react';
+
+import { RouteOverlay, type RouteOverlayProps } from './route-overlay.js';
+
+export type RouteDrawerProps = RouteOverlayProps;
+
+/** A child route presented as a modal panel docked to the right edge of the viewport. */
+export function RouteDrawer(props: RouteDrawerProps): ReactElement {
+  return <RouteOverlay {...props} drawer />;
+}