@prenta/admin 2.6.1 → 2.7.0

package/src/layout/nav-config.tsx

@@ -0,0 +1,425 @@
+import {
+  BookOpen,
+  Briefcase,
+  Clipboard,
+  ClipboardList,
+  Code,
+  Cpu,
+  Download,
+  File,
+  FileText,
+  FolderOpen,
+  HelpCircle,
+  Image,
+  Inbox,
+  Key,
+  Layers,
+  LayoutGrid,
+  ListChecks,
+  ListTree,
+  Lock,
+  Mail,
+  Menu as MenuIcon,
+  Newspaper,
+  Palette,
+  PanelBottom,
+  PanelTop,
+  PanelsTopLeft,
+  Plug,
+  Search as SearchIcon,
+  Settings,
+  ShieldX,
+  TextAlignStart,
+  Trash2,
+  Users,
+  Webhook,
+} from 'lucide-react'
+import type { LucideIcon } from 'lucide-react'
+import type { ReactElement } from 'react'
+import type { FormsSidebarCount } from '../lib/forms-service.js'
+
+/**
+ * The admin's single nav config (SHELL.md §2 "Nav order (exact)", TRACKING
+ * P-02). It ports the kit's base NAV plus `nav-patches.js`: `forms()` (Forms
+ * children with per-form unread counts, nested as `cms-layouts.js` does),
+ * `appearance()` (a group above where Templates would be) and `jobs()` (above
+ * Settings, opening SETTINGS).
+ *
+ * Kit order:
+ *   Dashboard · Pages › · Posts › · Appearance ›
+ *   ── CONTENT ── Media · Forms › · SEO · Script Tags · <collections, plugins>
+ *   <config collection groups, each under its own label>
+ *   ── SETTINGS ── Jobs · Settings
+ *
+ * Templates is left out until its screen exists (CONFLICTS.md §2: never link
+ * to a redirect).
+ */
+
+export interface NavItem {
+  path: string
+  label: string
+  icon: LucideIcon | NavIconComponent
+  /**
+   * Section label. Consecutive items sharing a `group` render under one
+   * header, shown when the group changes. Items without one render unlabelled.
+   */
+  group?: string
+  /** Children, shown as a sub-group (expanded sidebar) or a flyout (rail). */
+  children?: NavItem[]
+  /** Unread count. Zero or undefined renders nothing. */
+  badge?: number
+  /**
+   * Contributed by the config or a plugin rather than the kit. The mobile tab
+   * bar leaves these to the "More" drawer.
+   */
+  extra?: boolean
+  /** Icon size in px. Kit: 16 for top-level rows, 14 for patched children. */
+  iconSize?: number
+}
+
+type NavIconComponent = (props: {
+  className?: string
+  size?: number
+  strokeWidth?: number
+}) => ReactElement
+
+/** Per-form row marker: the kit's 12px dot (`circle r=2.5`). */
+function FormDot({
+  className,
+  size = 12,
+  strokeWidth = 1.75,
+}: {
+  className?: string
+  size?: number
+  strokeWidth?: number
+}) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={strokeWidth}
+      className={className}
+      aria-hidden
+    >
+      <circle cx="12" cy="12" r="2.5" />
+    </svg>
+  )
+}
+
+const ICON_MAP: Record<string, LucideIcon> = {
+  file: File,
+  'file-text': FileText,
+  briefcase: Briefcase,
+  folder: FolderOpen,
+  book: BookOpen,
+  help: HelpCircle,
+  newspaper: Newspaper,
+  navigation: ListTree,
+  menu: MenuIcon,
+  'list-tree': ListTree,
+  PanelTop: PanelTop,
+  PanelBottom: PanelBottom,
+  Layers: Layers,
+}
+
+const PAGES_CHILDREN: NavItem[] = [
+  { path: '/pages', label: 'All Pages', icon: PanelsTopLeft },
+  { path: '/pages/trash', label: 'Trash', icon: Trash2 },
+]
+
+/**
+ * Post Types are reached through the `/posts/types` cards page, not listed
+ * one per type, so the shape is the same however many types exist.
+ */
+const POSTS_CHILDREN: NavItem[] = [
+  { path: '/posts', label: 'All Posts', icon: File },
+  { path: '/posts/types', label: 'Post Types', icon: Clipboard },
+  { path: '/posts/trash', label: 'Trash', icon: Trash2 },
+]
+
+/**
+ * Appearance → Menus opens plugin-navigation's `navigations` collection: its
+ * list and NavBuilder editor are the working menu editor.
+ */
+const MENUS_SLUG = 'navigations'
+const MENUS_PATH = `/${MENUS_SLUG}`
+
+/** Without the navigation plugin there are no menus, so Menus would 404. */
+function appearanceItem(hasMenus: boolean): NavItem {
+  const children: NavItem[] = [
+    ...(hasMenus ? [{ path: MENUS_PATH, label: 'Menus', icon: TextAlignStart, iconSize: 14 }] : []),
+    { path: '/appearance/header', label: 'Header & Footer', icon: PanelsTopLeft, iconSize: 14 },
+    { path: '/appearance/widgets', label: 'Widgets', icon: LayoutGrid, iconSize: 14 },
+  ]
+  // No Appearance landing screen exists, so the parent opens its first child.
+  return { path: children[0]!.path, label: 'Appearance', icon: Palette, children }
+}
+
+const DASHBOARD: NavItem = { path: '/', label: 'Dashboard', icon: LayoutGrid }
+const PAGES: NavItem = {
+  path: '/pages',
+  label: 'Pages',
+  icon: PanelsTopLeft,
+  children: PAGES_CHILDREN,
+}
+const POSTS: NavItem = { path: '/posts', label: 'Posts', icon: File, children: POSTS_CHILDREN }
+
+const CONTENT_STATIC: NavItem[] = [
+  { path: '/media', label: 'Media', icon: Image, group: 'Content' },
+  { path: '/forms', label: 'Forms', icon: Clipboard, group: 'Content' },
+  { path: '/seo', label: 'SEO', icon: SearchIcon, group: 'Content' },
+  { path: '/script-tags', label: 'Script Tags', icon: Code, group: 'Content' },
+]
+
+const SETTINGS_ITEMS: NavItem[] = [
+  { path: '/jobs', label: 'Jobs', icon: ListChecks, group: 'Settings' },
+  { path: '/settings', label: 'Settings', icon: Settings, group: 'Settings' },
+]
+
+function resolveIcon(collection: any): LucideIcon {
+  const mapped = collection.admin?.icon ? ICON_MAP[collection.admin.icon] : undefined
+  if (mapped) return mapped
+  return collection.type === 'page' ? File : FileText
+}
+
+/**
+ * Build the nav tree from the CMS config. A config-less install gets the
+ * kit's default tree (no navigations collection, so no Menus).
+ *
+ * Repo-only destinations follow CONFLICTS.md §2: the `pages` collection is
+ * the kit's Pages item; other collections and plugin nav links continue the
+ * CONTENT block after Script Tags; collections with their own `admin.group`
+ * follow under their own labels; Users and API Keys live in Settings tabs.
+ */
+export function buildNavItems(config: any): NavItem[] {
+  if (!config?.collections) {
+    return [DASHBOARD, PAGES, POSTS, appearanceItem(false), ...CONTENT_STATIC, ...SETTINGS_ITEMS]
+  }
+
+  const raw = config.collections
+  const collectionsList: any[] = Array.isArray(raw) ? raw : Object.values(raw)
+  // Appearance → Menus reaches the navigations collection, so neither it nor
+  // the plugin's own nav link to it is listed again.
+  const hasMenus = collectionsList.some((c) => c.slug === MENUS_SLUG)
+  const visible = collectionsList.filter((c) => !c.admin?.hidden && c.slug !== MENUS_SLUG)
+
+  // `admin.group: 'Posts'` (case-insensitive) is a synonym for `type: 'post'`.
+  const isPostsGroup = (c: any) =>
+    typeof c.admin?.group === 'string' && c.admin.group.toLowerCase() === 'posts'
+  const hasPages = visible.some((c) => c.slug === 'pages')
+  const hasPosts = visible.some((c) => c.type === 'post' || isPostsGroup(c))
+  // Every other ungrouped collection continues CONTENT after Script Tags.
+  const ungrouped = visible.filter(
+    (c) => c.slug !== 'pages' && c.type !== 'post' && !isPostsGroup(c) && !c.admin?.group,
+  )
+  const grouped = visible.filter((c) => c.admin?.group && !isPostsGroup(c) && c.type !== 'post')
+
+  const items: NavItem[] = [DASHBOARD]
+  if (hasPages) items.push(PAGES)
+  if (hasPosts) items.push(POSTS)
+  items.push(appearanceItem(hasMenus), ...CONTENT_STATIC)
+
+  const taken = (path: string) =>
+    items.some((n) => n.path === path || n.children?.some((c) => c.path === path))
+
+  for (const collection of ungrouped) {
+    const path = `/${collection.slug}`
+    if (taken(path)) continue
+    items.push({
+      label: collection.labels?.plural ?? collection.slug,
+      path,
+      icon: resolveIcon(collection),
+      group: 'Content',
+      extra: true,
+    })
+  }
+
+  // Plugin-contributed nav links (PluginDefinition.adminNavItems, collected
+  // onto `_pluginNavItems` by cms-core's applyPlugins), deduped by path so a
+  // plugin can't double a built-in destination or one of its own collections.
+  const pluginNav: Array<{ label?: string; icon?: string; path?: string }> = Array.isArray(
+    config?._pluginNavItems,
+  )
+    ? config._pluginNavItems
+    : []
+  for (const item of pluginNav) {
+    if (!item?.path || (hasMenus && item.path === MENUS_PATH) || taken(item.path)) continue
+    items.push({
+      label: item.label ?? item.path,
+      path: item.path,
+      icon: (item.icon && ICON_MAP[item.icon]) || FileText,
+      group: 'Content',
+      extra: true,
+    })
+  }
+
+  // Config collection groups, each under its own label. A grouped collection
+  // whose path a built-in already provides is skipped: plugin-forms' `forms`
+  // (admin.group 'Forms', path `/forms`) would otherwise double Forms.
+  const groupBuckets = new Map<string, NavItem[]>()
+  for (const col of grouped) {
+    const path = `/${col.slug}`
+    if (taken(path)) continue
+    const group = col.admin.group as string
+    const bucket = groupBuckets.get(group) ?? []
+    bucket.push({
+      label: col.labels?.plural ?? col.slug,
+      path,
+      icon: resolveIcon(col),
+      group,
+      extra: true,
+    })
+    groupBuckets.set(group, bucket)
+  }
+  for (const bucket of groupBuckets.values()) items.push(...bucket)
+
+  items.push(...SETTINGS_ITEMS)
+  return items
+}
+
+/**
+ * Forms children as in the kit: All Entries and All Forms each open a third
+ * level with one row per form (`cms-layouts.js` "3rd-level nav nesting"),
+ * followed by Spam, SMTP Log and Form Settings. The parent and All Entries
+ * carry the total unread count; each form's entries row carries its own.
+ *
+ * `forms` comes from `/forms/sidebar-counts`, which returns active forms only,
+ * so drafts aren't listed under All Forms yet and Spam has no count.
+ */
+export function applyFormsNav(items: NavItem[], forms: FormsSidebarCount[]): NavItem[] {
+  const totalUnread = forms.reduce((sum, f) => sum + (f.unread ?? 0), 0)
+  return items.map((item) => {
+    if (item.path !== '/forms') return item
+    const children: NavItem[] = [
+      {
+        path: '/forms/entries',
+        label: 'All Entries',
+        icon: Inbox,
+        badge: totalUnread,
+        iconSize: 14,
+        children: forms.map((f) => ({
+          path: `/forms/${f.formId}/submissions`,
+          label: f.name,
+          icon: FormDot,
+          iconSize: 12,
+          badge: f.unread,
+        })),
+      },
+      {
+        path: '/forms',
+        label: 'All Forms',
+        icon: ClipboardList,
+        iconSize: 14,
+        children: forms.map((f) => ({
+          path: `/forms/${f.formId}/edit`,
+          label: f.name,
+          icon: FormDot,
+          iconSize: 12,
+        })),
+      },
+      { path: '/forms/spam', label: 'Spam', icon: ShieldX, iconSize: 14 },
+      { path: '/forms/deliveries', label: 'SMTP Log', icon: Mail, iconSize: 14 },
+      { path: '/forms/settings', label: 'Form Settings', icon: Settings, iconSize: 14 },
+    ]
+    return { ...item, badge: totalUnread > 0 ? totalUnread : undefined, children }
+  })
+}
+
+/**
+ * The Settings tabs in strip order: Settings.html `TABS` with its 15px icons,
+ * plus the repo's Layout and Webhooks. One list for the Settings tab strip and
+ * the mobile drawer, so each tab reads the same in both. `layout` exists only
+ * when the site defines layout regions.
+ */
+export const SETTINGS_TABS: ReadonlyArray<{ id: string; label: string; icon: LucideIcon }> = [
+  { id: 'general', label: 'General', icon: Settings },
+  { id: 'appearance', label: 'Admin appearance', icon: Palette },
+  { id: 'layout', label: 'Layout', icon: Layers },
+  { id: 'security', label: 'Security', icon: Lock },
+  { id: 'users', label: 'Users', icon: Users },
+  { id: 'mcp', label: 'MCP', icon: Plug },
+  { id: 'api-keys', label: 'API Keys', icon: Key },
+  { id: 'seo', label: 'SEO', icon: SearchIcon },
+  { id: 'email', label: 'Email (SMTP)', icon: Mail },
+  { id: 'webhooks', label: 'Webhooks', icon: Webhook },
+  { id: 'ai', label: 'AI', icon: Cpu },
+  { id: 'updates', label: 'Updates', icon: Download },
+]
+
+/**
+ * The mobile drawer (behind the tab bar's More) also lists the Settings tabs
+ * (CONFLICTS.md §2, DECIDED mobile nav), which don't fit in the bar. Layout
+ * only applies this below 769px; the desktop sidebar keeps Settings a leaf.
+ */
+export function withSettingsTabs(
+  items: NavItem[],
+  config: { layout?: { regions?: Record<string, unknown> } } | null | undefined,
+): NavItem[] {
+  const hasLayout = Object.keys(config?.layout?.regions ?? {}).length > 0
+  const tab = (id: string, label: string, icon: LucideIcon): NavItem => ({
+    path: `/settings?tab=${id}`,
+    label,
+    icon,
+    iconSize: 14,
+  })
+  const children: NavItem[] = SETTINGS_TABS.filter(
+    (settingsTab) => settingsTab.id !== 'layout' || hasLayout,
+  ).map((settingsTab) => tab(settingsTab.id, settingsTab.label, settingsTab.icon))
+  return items.map((item) => (item.path === '/settings' ? { ...item, children } : item))
+}
+
+/**
+ * Whether `itemPath` is the current page. Query and hash are ignored so
+ * state-bearing routes (`/seo?tab=audit`) still match.
+ */
+export function isPathActive(currentPath: string, itemPath: string): boolean {
+  const path = currentPath.split('?')[0]!.split('#')[0]!
+  // A query in the item path (Settings tabs, `/settings?tab=security`) must
+  // match too; Settings without `?tab=` shows General.
+  if (itemPath.includes('?')) {
+    const [itemPathname, itemQuery] = itemPath.split('?') as [string, string]
+    if (path !== itemPathname) return false
+    const current = new URLSearchParams(currentPath.split('#')[0]!.split('?')[1] ?? '')
+    const wanted = new URLSearchParams(itemQuery)
+    for (const [key, value] of wanted) {
+      const have = current.get(key) ?? (key === 'tab' ? 'general' : null)
+      if (have !== value) return false
+    }
+    return true
+  }
+  if (itemPath === '/') return path === '/'
+  // `/posts` is a prefix of `/posts/types`; All Posts is exact-only.
+  if (itemPath === '/posts') return path === '/posts' || path === '/posts/new'
+  return path === itemPath || path.startsWith(itemPath + '/')
+}
+
+/**
+ * The row that owns the current page, searching every level below: the
+ * longest matching path wins, so All Pages (`/pages`) yields to Trash on
+ * `/pages/trash` and All Forms (`/forms`) to All Entries on `/forms/entries`.
+ */
+export function activeChildPath(children: NavItem[], currentPath: string): string | undefined {
+  let best: string | undefined
+  const visit = (items: NavItem[]) => {
+    for (const child of items) {
+      if (isPathActive(currentPath, child.path) && (!best || child.path.length > best.length)) {
+        best = child.path
+      }
+      if (child.children) visit(child.children)
+    }
+  }
+  visit(children)
+  return best
+}
+
+/** True when the current page is one of `items` or anything nested below them. */
+export function hasActiveDescendant(items: NavItem[], currentPath: string): boolean {
+  return items.some(
+    (item) =>
+      isPathActive(currentPath, item.path) ||
+      (!!item.children && hasActiveDescendant(item.children, currentPath)),
+  )
+}

package/src/layout/primitives/AdminShell.tsx

@@ -1,5 +1,6 @@
-import { useEffect, useState } from 'react'
+import { useEffect, useRef, useState, type KeyboardEvent as ReactKeyboardEvent } from 'react'
 import type { ReactNode } from 'react'
+import { X } from 'lucide-react'
 
 export interface AdminShellProps {
   /** Sidebar/navigation slot. Rendered in the left column on desktop. */
@@ -10,10 +11,16 @@ export interface AdminShellProps {
   breadcrumbs?: ReactNode
   /** Main content. Scrolls independently of the sidebar. */
   children: ReactNode
+  /**
+   * Mobile bottom tab bar, rendered below `desktopBreakpoint` only. The main
+   * area reserves `--tabbar-h` at the bottom so content isn't hidden behind it.
+   */
+  tabBar?: ReactNode
   /**
    * Whether the mobile sidebar overlay is currently open. Controlled.
    * AdminShell renders the backdrop + slide transform; the consumer owns
-   * the open state and the hamburger button that toggles it.
+   * the open state and the control that toggles it (the admin's tab bar
+   * More).
    */
   mobileSidebarOpen?: boolean
   onMobileSidebarClose?: () => void
@@ -24,6 +31,27 @@ export interface AdminShellProps {
   desktopBreakpoint?: number
 }
 
+/** The mobile drawer's id, for an opener's `aria-controls`. */
+export const DRAWER_ID = 'prenta-nav-drawer'
+
+const FOCUSABLE =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+
+function setInert(el: HTMLElement | null, inert: boolean) {
+  if (el) (el as HTMLElement & { inert?: boolean }).inert = inert
+}
+
+/**
+ * The drawer's Tab stops: rendered (a `display: none` ancestor leaves no
+ * client rects, like the sidebar's collapse footer below 1025px) and not
+ * inert.
+ */
+function tabStops(root: HTMLElement): HTMLElement[] {
+  return Array.from(root.querySelectorAll<HTMLElement>(FOCUSABLE)).filter(
+    (el) => el.getClientRects().length > 0 && !el.closest('[inert]'),
+  )
+}
+
 /**
  * The canonical admin chrome. Owns the entire viewport, splits into
  * `sidebar | (header + breadcrumbs + content)`, and handles the mobile
@@ -47,11 +75,17 @@ export function AdminShell({
   header,
   breadcrumbs,
   children,
+  tabBar,
   mobileSidebarOpen = false,
   onMobileSidebarClose,
   desktopBreakpoint = 768,
 }: AdminShellProps) {
   const [isDesktop, setIsDesktop] = useState(false)
+  const sidebarRef = useRef<HTMLDivElement>(null)
+  const contentRef = useRef<HTMLDivElement>(null)
+  const tabBarRef = useRef<HTMLDivElement>(null)
+  const skipRef = useRef<HTMLAnchorElement>(null)
+  const drawerOpen = !isDesktop && mobileSidebarOpen
 
   useEffect(() => {
     if (typeof window === 'undefined') return
@@ -62,6 +96,74 @@ export function AdminShell({
     return () => mq.removeEventListener('change', handler)
   }, [desktopBreakpoint])
 
+  // The closed mobile drawer is off-screen: keep it out of the tab order and
+  // the accessibility tree. Set on the element because React 18 has no
+  // `inert` prop.
+  useEffect(() => {
+    setInert(sidebarRef.current, !isDesktop && !mobileSidebarOpen)
+  }, [isDesktop, mobileSidebarOpen])
+
+  // The drawer only exists below the breakpoint: close it on the way out, or
+  // it would reopen by itself when the window narrows again.
+  useEffect(() => {
+    if (isDesktop && mobileSidebarOpen) onMobileSidebarClose?.()
+  }, [isDesktop, mobileSidebarOpen, onMobileSidebarClose])
+
+  // The open drawer is modal: the skip link, the content and the tab bar go
+  // inert, focus moves in (to its close button), and on close it returns to
+  // the opener (the tab bar's More, or a custom header's menu button). One effect so the
+  // opener is read before it goes inert and un-inerted before it takes focus
+  // back.
+  useEffect(() => {
+    if (!drawerOpen) return
+    const opener = document.activeElement as HTMLElement | null
+    const behind = [skipRef.current, contentRef.current, tabBarRef.current]
+    for (const el of behind) setInert(el, true)
+    const drawer = sidebarRef.current
+    if (drawer) (tabStops(drawer)[0] ?? drawer).focus()
+    // App shortcuts listening on `document` would open UI in the inert column
+    // (the command palette's Ctrl/Cmd+K); a modal ignores them.
+    const blockShortcuts = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'k') {
+        e.stopPropagation()
+        // Also keep the browser's own Ctrl+K (focus the address bar) from
+        // firing; Shift combos (e.g. Edge's Duplicate tab) are left alone.
+        if (!e.shiftKey) e.preventDefault()
+      }
+    }
+    document.addEventListener('keydown', blockShortcuts, true)
+    return () => {
+      document.removeEventListener('keydown', blockShortcuts, true)
+      for (const el of behind) setInert(el, false)
+      if (opener && opener !== document.body && document.contains(opener)) opener.focus()
+    }
+  }, [drawerOpen])
+
+  // Esc closes the drawer; Tab and Shift+Tab stay inside it. Keys from
+  // portals rendered in the drawer's React tree (a Radix menu's Esc) bubble
+  // here too; they belong to that layer.
+  const onDrawerKeyDown = (e: ReactKeyboardEvent<HTMLDivElement>) => {
+    if (!drawerOpen || e.defaultPrevented) return
+    if (!e.currentTarget.contains(e.target as Node)) return
+    if (e.key === 'Escape') {
+      e.stopPropagation()
+      onMobileSidebarClose?.()
+      return
+    }
+    if (e.key !== 'Tab') return
+    const items = tabStops(e.currentTarget)
+    if (items.length === 0) return
+    const first = items[0]!
+    const last = items[items.length - 1]!
+    if (e.shiftKey && document.activeElement === first) {
+      e.preventDefault()
+      last.focus()
+    } else if (!e.shiftKey && document.activeElement === last) {
+      e.preventDefault()
+      first.focus()
+    }
+  }
+
   return (
     <div
       className="bg-background text-foreground h-screen overflow-hidden"
@@ -77,7 +179,7 @@ export function AdminShell({
        * focused; styling lives in `responsive.css` because it has to survive
        * a consumer whose Tailwind build does not scan this file.
        */}
-      <a className="prenta-skip-link" href="#prenta-main">
+      <a ref={skipRef} className="prenta-skip-link" href="#prenta-main">
         Skip to content
       </a>
 
@@ -90,7 +192,17 @@ export function AdminShell({
       )}
 
       <div
-        className="z-50"
+        ref={sidebarRef}
+        id={DRAWER_ID}
+        // Below the desktop breakpoint the open sidebar is a modal drawer.
+        role={drawerOpen ? 'dialog' : undefined}
+        aria-modal={drawerOpen ? true : undefined}
+        aria-label={drawerOpen ? 'Navigation' : undefined}
+        tabIndex={drawerOpen ? -1 : undefined}
+        onKeyDown={onDrawerKeyDown}
+        // A class, not an inline transition, so the in-app Reduce motion
+        // setting (and prefers-reduced-motion) can stop the slide.
+        className={`z-50 outline-none ${isDesktop ? '' : 'motion-safe:transition-transform motion-safe:duration-300 motion-safe:ease-out'}`}
         style={
           isDesktop
             ? {
@@ -104,14 +216,27 @@ export function AdminShell({
                 bottom: 0,
                 left: 0,
                 transform: mobileSidebarOpen ? 'translateX(0)' : 'translateX(-100%)',
-                transition: 'transform 300ms ease',
               }
         }
       >
+        {/* The drawer's own dismiss: the scrim is pointer-only, and its
+            opener is inert behind the modal. First in the drawer, so it takes
+            focus on open. */}
+        {!isDesktop && onMobileSidebarClose ? (
+          <button
+            type="button"
+            onClick={onMobileSidebarClose}
+            aria-label="Close navigation"
+            className="rounded-7 text-sub hover:bg-acc-l hover:text-acc prenta-touch-target absolute top-2.5 right-2.5 z-[1] flex h-9 w-9 cursor-pointer items-center justify-center border-0 bg-transparent p-0"
+          >
+            <X className="h-4 w-4" strokeWidth={1.75} aria-hidden />
+          </button>
+        ) : null}
         {sidebar}
       </div>
 
       <div
+        ref={contentRef}
         className="flex flex-col overflow-hidden"
         style={
           isDesktop
@@ -121,10 +246,33 @@ export function AdminShell({
       >
         {header}
         {breadcrumbs}
-        <main id="prenta-main" className="min-h-0 flex-1 overflow-y-auto">
+        {/* scroll-padding-bottom keeps a focused field clear of the floating
+            unsaved bar (52px, 16px up) when focus scrolls it into view
+            (WCAG 2.4.11); on mobile the fixed tab bar covers another
+            --tabbar-h, which the content also reserves at its end.
+            `relative`: visually hidden text (`sr-only`, absolutely positioned)
+            with no positioned ancestor otherwise sized the fixed admin root,
+            and on long pages the whole shell scrolled. */}
+        <main
+          id="prenta-main"
+          className="relative min-h-0 flex-1 scroll-pb-[84px] overflow-x-hidden overflow-y-auto"
+          style={
+            !isDesktop && tabBar
+              ? {
+                  // --fab-clear: room for a floating action button
+                  // (responsive.css sets it while the page has one).
+                  paddingBottom:
+                    'calc(var(--tabbar-h) + env(safe-area-inset-bottom) + var(--fab-clear, 0px))',
+                  scrollPaddingBottom: 'calc(84px + var(--tabbar-h) + env(safe-area-inset-bottom))',
+                }
+              : undefined
+          }
+        >
           {children}
         </main>
       </div>
+
+      {!isDesktop && tabBar ? <div ref={tabBarRef}>{tabBar}</div> : null}
     </div>
   )
 }

package/src/layout/topbar-classes.ts

@@ -0,0 +1,8 @@
+/**
+ * The kit's topbar icon button (`.icbtn`, SHELL.md §3): 34×34, radius 8,
+ * `--sub`, hover `--acc-l` / `--acc`; 44×44 below 769px (cms-layouts.css) and
+ * at least 44px on touch screens (`.prenta-touch-target`). `relative` so the
+ * bell's unread dot can sit in its corner.
+ */
+export const TOPBAR_ICON_BUTTON =
+  'rounded-8 text-sub hover:bg-acc-l hover:text-acc prenta-touch-target relative flex h-[34px] w-[34px] shrink-0 cursor-pointer items-center justify-center border-0 bg-transparent p-0 mobile:h-11 mobile:w-11'