@flamingo-stack/openframe-frontend-core 0.0.704 → 0.0.705-snapshot.20261006160157

package/src/components/navigation/mingo-ai-button.tsx

@@ -1,104 +1,180 @@
 'use client';
 
 import type React from 'react';
+import { useEffect } from 'react';
+import { useVisitorOs } from '../../hooks/ui/use-visitor-os';
 import { cn } from '../../utils';
+import { shortcutLabel, usesCommandKey } from '../../utils/visitor-os';
 import { MingoIcon } from '../icons';
+import { Button } from '../ui/button';
 
 export interface MingoAiButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
   source?: string;
-  /** The platform's Mingo identity glyph — pass the SAME server-configured
+  /** The platform's Mingo identity glyph: pass the SAME server-configured
    *  icon the chat panel renders (host-side: `EntityIcon` fed by the admin
    *  `assistantIcon`), so the launcher and the panel can never diverge.
    *  Falls back to the packaged Mingo mark when the server has none. */
   icon?: React.ReactNode;
-  /** The launcher's wordmark + aria-label — pass the server-configured
+  /** The launcher's wordmark + aria-label: pass the server-configured
    *  assistant name (same `assistantName` the chat panel shows) so the
    *  launcher never hardcodes an identity the admin has renamed. */
   label?: string;
+  /** Bind Cmd+K (Ctrl+K off Apple platforms) to open the chat, and show the
+   *  key cap beside the label. Default false. */
+  shortcutHint?: boolean;
+  /** `inline` (default): the header launcher, the height and type of the menu
+   *  items beside it. `field`: the full-width row that opens the mobile menu
+   *  (the name reads as the field's prompt). ONE component, so every Mingo
+   *  launcher carries the same identity, ring and event. */
+  variant?: 'inline' | 'field';
+}
+
+const MINGO_ACCENT = 'var(--ods-flamingo-cyan-base)';
+
+/** The event the mounted chat panel (`EmbeddableChat`) opens on. */
+export const ASK_AI_OPEN_EVENT = 'ask-ai:open';
+
+/**
+ * Open the chat of `source`. Coalesced to '' so a source-less call still
+ * matches the panel's own `runtime.source ?? ''` comparison (undefined !== ''
+ * would make the panel silently ignore the event).
+ */
+export function openAskAi(source?: string): void {
+  window.dispatchEvent(new CustomEvent(ASK_AI_OPEN_EVENT, { detail: { source: source ?? '' } }));
 }
 
 /**
- * Marketing-header Mingo AI launcher: the flush, full-height button rendered
- * at the far right edge of the public `Header` (`config.mingo`). Stateless:
- * clicking dispatches an `ask-ai:open` CustomEvent (source-filtered) that the
- * mounted `EmbeddableChat` panel listens for.
+ * THE Mingo AI launcher, in the site header's right cluster and at the top of
+ * the mobile menu (`variant="field"`): the round identity glyph, the
+ * assistant's name and an optional shortcut hint, sized like the menu items
+ * beside it. Stateless: clicking dispatches an `ask-ai:open`
+ * CustomEvent (source-filtered) that the mounted `EmbeddableChat` panel
+ * listens for.
+ *
+ * It carries the AI edge light (`.mingo-edge-frame` / `.mingo-edge` in
+ * `styles/chat-animations.css`): an accent arc travelling around its outline,
+ * with a one-shot shimmer on hover. Static under reduced motion.
  *
  * Distinct from `header-mingo-button.tsx` (`HeaderMingoButton`), the
  * dashboard/AppHeader controlled toggle; different surface and contract, do
  * not merge them.
  *
- * Deliberately a raw `<button>` rather than the ui-kit `Button`: it needs
- * full-height flush cell layout, an absolutely-positioned animated ring, and
- * icon-only collapse that `Button` cannot express (same precedent as
- * `header-mingo-button.tsx`).
+ * It is the lib `Button` (`transparent`, or `glyph` for the menu row, at the
+ * `wrap` size): the launcher's own box, ring and collapse are classes on it.
  */
-const MINGO_ACCENT = 'var(--ods-flamingo-cyan-base)';
+export function MingoAiButton({
+  source,
+  icon,
+  label = 'Mingo AI',
+  shortcutHint = false,
+  variant = 'inline',
+  className,
+  onClick,
+  ...props
+}: MingoAiButtonProps) {
+  // Known after hydration only: until then the hint keeps its space, empty.
+  const visitor = useVisitorOs();
+  const field = variant === 'field';
+
+  const commandKey = visitor.known && usesCommandKey(visitor.os);
+
+  // The shortcut the key cap shows opens the same chat the click opens.
+  useEffect(() => {
+    if (!shortcutHint) return undefined;
+    const onKeyDown = (event: KeyboardEvent) => {
+      // Something on the page already took the shortcut (an editor's link shortcut): leave it alone.
+      if (event.defaultPrevented || event.altKey || event.shiftKey) return;
+      // The modifier the key cap shows, and only that one: on a Mac Ctrl+K is
+      // the text fields' own "delete to the end of the line".
+      const modifier = commandKey ? event.metaKey && !event.ctrlKey : event.ctrlKey && !event.metaKey;
+      if (event.key.toLowerCase() !== 'k' || !modifier) return;
+      event.preventDefault();
+      openAskAi(source);
+    };
+    window.addEventListener('keydown', onKeyDown);
+    return () => window.removeEventListener('keydown', onKeyDown);
+  }, [shortcutHint, source, commandKey]);
 
-export function MingoAiButton({ source, icon, label = 'Mingo AI', className, onClick, ...props }: MingoAiButtonProps) {
   return (
-    <button
+    <Button
       {...props}
       type="button"
+      variant={field ? 'glyph' : 'transparent'}
+      size="wrap"
+      font="regular"
       aria-label={label}
+      aria-keyshortcuts={shortcutHint && visitor.known ? (commandKey ? 'Meta+K' : 'Control+K') : undefined}
       onClick={e => {
-        // Coalesce to '' so a source-less mount still matches EmbeddableChat's
-        // own `runtime.source ?? ''` comparison (undefined !== '' would make
-        // the panel silently ignore the event).
-        window.dispatchEvent(new CustomEvent('ask-ai:open', { detail: { source: source ?? '' } }));
+        openAskAi(source);
         onClick?.(e);
       }}
       className={cn(
-        // Unified ODS top-navigation cell (Figma 2797-6808 desktop /
-        // 2797-7275 mobile): full-height cell with a leading divider,
-        // transparent at rest so it inherits the bar's background.
-        // No hover background on the cell: the animated ring + shimmer are
-        // the ONLY hover treatment (a bg flip on top read as a double
-        // animation).
-        'group/mingo relative flex h-full shrink-0 items-center border-l border-ods-border bg-transparent px-[var(--spacing-system-m)] focus:outline-none focus-visible:ring-2 focus-visible:ring-ods-accent',
+        'group/mingo flex shrink-0 justify-start focus-visible:ring-ods-accent',
+        field
+          ? // A row of the mobile menu like the groups under it: same height,
+            // type and divider, no surface and no ring of its own.
+            'min-h-14 w-full gap-[var(--spacing-system-sf)] rounded-none border-b border-ods-border text-left text-h4 [&_svg]:h-6 [&_svg]:w-6'
+          : // Transparent at rest so it inherits the bar's background; the hover
+            // wash is the menu items' own.
+            'h-10 gap-[var(--spacing-system-xsf)] rounded-md pl-[var(--spacing-system-xsf)] pr-2.5 text-ods-text-secondary hover:text-ods-text-primary',
         className,
       )}
     >
-      {/* Inner box = 1:1 twin of the DEFAULT-size Button geometry (rounded-md,
-          h-11 md:h-12, px-m) — the same footprint as the header's "Try for
-          Free" CTA — so the animated ring traces exactly where a full button
-          border would sit inside the 72px bar. */}
-      <span className="relative flex h-11 items-center gap-[var(--spacing-system-xsf)] rounded-md px-[var(--spacing-system-m)] md:h-12">
-        {/* AI edge light (Apple-Intelligence-style): a rotating accent-
-            gradient arc clipped to a 3px ring on the box outline via CSS
-            mask (.mingo-edge-frame) — NO opaque cover, so the launcher
-            inherits whatever background sits behind it. Platform-tinted via
-            the accent token. */}
-        <span aria-hidden="true" className="mingo-edge-frame pointer-events-none absolute inset-0 rounded-md">
-          <span className="mingo-edge" />
-        </span>
-        {/* One-shot light-streak shimmer on hover, clipped to the box. */}
-        <span aria-hidden="true" className="pointer-events-none absolute inset-0 overflow-hidden rounded-md">
-          <span
-            className="mingo-shimmer absolute inset-y-0 left-0 w-1/2"
-            style={{
-              background:
-                'linear-gradient(105deg, transparent, color-mix(in srgb, var(--ods-system-greys-white) 12%, transparent), transparent)',
-            }}
-          />
+      {!field && (
+        <>
+          {/* AI edge light (Apple-Intelligence-style): a rotating accent-gradient
+          arc clipped to a hairline ring on the outline via CSS mask
+          (.mingo-edge-frame). NO opaque cover, so the launcher inherits
+          whatever background sits behind it. Platform-tinted via the accent
+          token. */}
+          <span aria-hidden="true" className="mingo-edge-frame pointer-events-none absolute inset-0 rounded-md">
+            <span className="mingo-edge" />
+          </span>
+          {/* One-shot light-streak shimmer on hover, clipped to the outline. */}
+          <span aria-hidden="true" className="pointer-events-none absolute inset-0 overflow-hidden rounded-md">
+            <span
+              className="mingo-shimmer absolute inset-y-0 left-0 w-1/2"
+              style={{
+                background:
+                  'linear-gradient(105deg, transparent, color-mix(in srgb, var(--ods-system-greys-white) 12%, transparent), transparent)',
+              }}
+            />
+          </span>
+        </>
+      )}
+      {icon ? (
+        <span
+          className={cn(
+            'relative inline-flex shrink-0 items-center justify-center overflow-hidden rounded-full',
+            field ? 'size-6' : 'size-5',
+          )}
+        >
+          {icon}
         </span>
-        {icon ? (
-          <span className="relative inline-flex size-6 shrink-0 items-center justify-center">{icon}</span>
-        ) : (
-          <MingoIcon
-            color="currentColor"
-            eyesColor={MINGO_ACCENT}
-            cornerColor={MINGO_ACCENT}
-            className="relative h-6 w-6 shrink-0 text-ods-text-primary"
-          />
-        )}
-        {/* Wordmark collapses below md — the mobile cell is icon-only per
-            spec. h3 bold, matching the default-size CTA label next to it
-            (Figma 2936-6825). */}
-        {/* Bare `text-h3` — the exact composite the default-size Button label
-            uses (bold 700 and -0.02em tracking are built into the utility). */}
-        <span className="relative hidden whitespace-nowrap text-ods-text-primary text-h3 md:inline">{label}</span>
+      ) : (
+        <MingoIcon
+          color="currentColor"
+          eyesColor={MINGO_ACCENT}
+          cornerColor={MINGO_ACCENT}
+          className={cn('relative shrink-0 text-ods-text-primary', field ? 'size-6' : 'size-5')}
+        />
+      )}
+      {/* In the header the name collapses below lg, with the menus: on a phone
+          the launcher is its glyph alone (the name stays the accessible name). */}
+      <span
+        className={cn('relative whitespace-nowrap', field ? 'min-w-0 flex-1 truncate' : 'hidden text-h6 lg:inline')}
+      >
+        {label}
       </span>
-    </button>
+      {shortcutHint && !field && (
+        // A key cap in the label's own type (never smaller: a hint nobody can
+        // read is decoration) and the label's colour, which clears 4.5:1 on
+        // the bar. It keeps its width before the platform is known.
+        <kbd className="relative hidden h-6 min-w-9 items-center justify-center rounded border border-ods-border px-[var(--spacing-system-xxs)] text-h6 lg:inline-flex">
+          {visitor.known ? shortcutLabel(visitor.os, 'K') : ''}
+        </kbd>
+      )}
+    </Button>
   );
 }
 

package/src/components/navigation/mobile-nav-sheet-id.ts

@@ -0,0 +1,2 @@
+/** DOM id of the mobile navigation sheet, referenced by the header burger's `aria-controls`. */
+export const MOBILE_NAV_SHEET_ID = 'mobile-nav-sheet';

package/src/components/navigation/mobile-nav-sheet.tsx

@@ -0,0 +1,241 @@
+'use client';
+
+import { usePreventScroll } from '@react-aria/overlays';
+import type React from 'react';
+import { useRef, useState } from 'react';
+import { resolveActiveSection } from '../../hooks/ui/use-active-section';
+import { useFocusTrap } from '../../hooks/ui/use-focus-trap';
+import type { NavLink, NavMenu, SiteNav } from '../../types/navigation';
+import { cn } from '../../utils/cn';
+import { Chevron02DownIcon } from '../icons-v2-generated/arrows/chevron-02-down-icon';
+import { Chevron02RightIcon } from '../icons-v2-generated/arrows/chevron-02-right-icon';
+import { XmarkIcon } from '../icons-v2-generated/signs-and-symbols/xmark-icon';
+import { Button } from '../ui/button';
+import { MingoAiButton } from './mingo-ai-button';
+import { MOBILE_NAV_SHEET_ID } from './mobile-nav-sheet-id';
+import { NavItemRow } from './nav-item-row';
+import { defaultRenderSiteNavLink, NAV_FOCUS_CLASS, type SiteNavLinkRenderer } from './site-nav-link';
+
+export { MOBILE_NAV_SHEET_ID } from './mobile-nav-sheet-id';
+
+export interface MobileNavSheetProps {
+  nav: SiteNav;
+  isOpen: boolean;
+  onClose: () => void;
+  /** The host router's pathname: the group holding the current page starts open. */
+  pathname: string;
+  logo: React.ReactNode;
+  renderLink?: SiteNavLinkRenderer;
+  /** The primary CTA node when `nav.primaryCta` is `'trial'` or `'waitlist'`. */
+  cta?: React.ReactNode;
+  /** Host nodes shown above the pinned CTA (a sign-up button). */
+  actions?: React.ReactNode;
+  /** The Mingo row at the top (`MingoAiButton variant="field"`): the assistant's
+   *  name and icon; `source` scopes the `ask-ai:open` event. Omitted: no row. */
+  askAI?: { source?: string; icon?: React.ReactNode; label?: string };
+  /** Host-added groups after the site's own (Profile, Admin). */
+  extraMenus?: NavMenu[];
+  /** Values for `NavLink.badgeKey`. */
+  badges?: Record<string, number>;
+  /** Rendered under the links of a menu with `showSocial`. */
+  social?: React.ReactNode;
+  /** Opaque ODS background class. Default `bg-ods-bg`. */
+  backgroundClassName?: string;
+}
+
+/**
+ * Would the sheet list anything from this navigation? The header's menu button
+ * and the sheet read this one answer (plus whatever the host adds: a profile
+ * entry, a sign-up button), so a button never opens an empty sheet.
+ */
+export function siteNavHasMobileMenus(nav: Pick<SiteNav, 'menus' | 'mobileMenus'>): boolean {
+  return (nav.mobileMenus ?? nav.menus).length > 0;
+}
+
+const GROUP_ROW_CLASS =
+  'flex min-h-14 w-full items-center justify-between gap-[var(--spacing-system-sf)] text-left text-ods-text-primary text-h4';
+
+const menuLinks = (menu: NavMenu): NavLink[] => [
+  ...(menu.columns ?? []).flatMap(group => group.links),
+  ...(menu.sideLinks ?? []),
+];
+
+/**
+ * The site navigation below `lg`: a full-screen sheet drawn from the same
+ * `SiteNav` as the header. Each menu with links is an accordion that expands
+ * in place; the primary CTA and Sign in stay pinned at the bottom while the
+ * body scrolls.
+ *
+ * Unmounted while closed (the header's panels are what crawlers read).
+ */
+export function MobileNavSheet(props: MobileNavSheetProps) {
+  // The open groups are seeded from the page the sheet opens on, so the body
+  // mounts with the sheet: every open starts from the current section.
+  if (!props.isOpen) return null;
+  return <MobileNavSheetBody {...props} />;
+}
+
+function MobileNavSheetBody({
+  nav,
+  onClose,
+  pathname,
+  logo,
+  renderLink = defaultRenderSiteNavLink,
+  cta,
+  actions,
+  askAI,
+  extraMenus,
+  badges,
+  social,
+  backgroundClassName,
+}: MobileNavSheetProps) {
+  const sheetRef = useRef<HTMLDivElement>(null);
+  const menus = [...(nav.mobileMenus ?? nav.menus), ...(extraMenus ?? [])];
+
+  // Shared ref-counted, iOS-aware scroll lock (react-aria): one counter with
+  // the modals and chat overlays, restores prior styles on release.
+  usePreventScroll();
+  // Initial focus, Tab containment, Escape-to-close, guarded focus restore.
+  useFocusTrap(sheetRef, true, { onEscape: onClose });
+
+  const [openGroups, setOpenGroups] = useState<Record<string, boolean>>(() => {
+    const active = resolveActiveSection(menus, pathname);
+    return active ? { [active]: true } : {};
+  });
+
+  const primaryCta =
+    typeof nav.primaryCta === 'object' ? (
+      <Button variant="accent" href={nav.primaryCta.href} onClick={onClose} className="w-full">
+        {nav.primaryCta.label}
+      </Button>
+    ) : nav.primaryCta === 'none' ? null : (
+      (cta ?? null)
+    );
+  const hasFooter = !!actions || !!primaryCta || !!nav.signIn;
+
+  return (
+    <div
+      ref={sheetRef}
+      id={MOBILE_NAV_SHEET_ID}
+      role="dialog"
+      aria-modal="true"
+      aria-label="Navigation menu"
+      tabIndex={-1}
+      // Small-viewport height: 100vh overflowed under mobile browser chrome,
+      // leaving the pinned CTA unreachable while the body was scroll-locked.
+      className={cn(
+        'fixed inset-0 z-[9999] flex h-[100svh] flex-col text-ods-text-primary outline-none',
+        backgroundClassName ?? 'bg-ods-bg',
+      )}
+    >
+      <div className="flex h-14 shrink-0 items-center justify-between border-b border-ods-border pl-5 pr-[var(--spacing-system-xsf)]">
+        <div className="flex min-w-0 items-center">{logo}</div>
+        <Button
+          type="button"
+          variant="transparent"
+          size="icon"
+          aria-label="Close menu"
+          onClick={onClose}
+          className={cn('h-11 w-11 shrink-0 md:h-11 md:w-11', NAV_FOCUS_CLASS)}
+        >
+          <XmarkIcon aria-hidden="true" className="!h-6 !w-6" />
+        </Button>
+      </div>
+
+      <div className="min-h-0 flex-1 overflow-y-auto overflow-x-hidden overscroll-contain px-5">
+        {askAI && (
+          <MingoAiButton
+            variant="field"
+            source={askAI.source}
+            icon={askAI.icon}
+            label={askAI.label}
+            onClick={onClose}
+          />
+        )}
+
+        <nav aria-label="Main">
+          {menus.map(menu => {
+            const links = menuLinks(menu);
+            if (links.length === 0) {
+              if (!menu.href) return null;
+              return (
+                <div key={menu.id} className="border-b border-ods-border">
+                  {renderLink({
+                    link: { href: menu.href },
+                    className: cn(GROUP_ROW_CLASS, NAV_FOCUS_CLASS),
+                    onClick: onClose,
+                    children: (
+                      <>
+                        {menu.label}
+                        <Chevron02RightIcon aria-hidden="true" className="h-5 w-5 shrink-0 text-ods-text-muted" />
+                      </>
+                    ),
+                  })}
+                </div>
+              );
+            }
+
+            const open = !!openGroups[menu.id];
+            const listId = `${MOBILE_NAV_SHEET_ID}-${menu.id}`;
+            return (
+              <div key={menu.id} className="border-b border-ods-border">
+                <Button
+                  type="button"
+                  variant="glyph"
+                  size="wrap"
+                  font="regular"
+                  aria-expanded={open}
+                  aria-controls={open ? listId : undefined}
+                  onClick={() => setOpenGroups(prev => ({ ...prev, [menu.id]: !prev[menu.id] }))}
+                  className={cn(GROUP_ROW_CLASS, NAV_FOCUS_CLASS)}
+                >
+                  {menu.label}
+                  <Chevron02DownIcon
+                    aria-hidden="true"
+                    className={cn(
+                      'h-5 w-5 shrink-0 text-ods-text-muted transition-transform duration-150',
+                      open && 'rotate-180',
+                    )}
+                  />
+                </Button>
+                {open && (
+                  <div id={listId} className="flex flex-col pb-[var(--spacing-system-sf)]">
+                    {links.map(link => (
+                      <NavItemRow
+                        key={link.id}
+                        link={link}
+                        variant="sheet"
+                        renderLink={renderLink}
+                        badge={link.badgeKey ? badges?.[link.badgeKey] : undefined}
+                        onNavigate={onClose}
+                      />
+                    ))}
+                    {menu.showSocial && social && <div className="pt-[var(--spacing-system-xsf)]">{social}</div>}
+                  </div>
+                )}
+              </div>
+            );
+          })}
+        </nav>
+      </div>
+
+      {/* Pinned: stays visible while the body scrolls, clears the iOS home indicator. */}
+      {hasFooter && (
+        <div className="flex shrink-0 flex-col gap-[var(--spacing-system-xxs)] border-t border-ods-border px-5 pb-[max(1.75rem,env(safe-area-inset-bottom))] pt-[var(--spacing-system-mf)] [&_a]:w-full [&_button]:w-full">
+          {actions}
+          {primaryCta}
+          {nav.signIn &&
+            renderLink({
+              link: nav.signIn,
+              className: cn(
+                'flex h-12 items-center justify-center rounded-md text-ods-text-primary text-h4',
+                NAV_FOCUS_CLASS,
+              ),
+              onClick: onClose,
+              children: nav.signIn.label,
+            })}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/navigation/nav-item-row.tsx

@@ -0,0 +1,129 @@
+'use client';
+
+import type React from 'react';
+import type { NavLink } from '../../types/navigation';
+import { cn } from '../../utils/cn';
+import { EntityIcon } from '../icon-display';
+import { defaultRenderSiteNavLink, NAV_FOCUS_CLASS, navLinkLabel, type SiteNavLinkRenderer } from './site-nav-link';
+import { UnreadCountBadge } from './unread-dot';
+
+export type NavItemRowVariant = 'panel' | 'sheet' | 'side' | 'label';
+
+export interface NavItemRowProps {
+  link: NavLink;
+  /**
+   * - `panel` (default): a desktop menu row, 36px icon tile, label, description.
+   * - `sheet`: the mobile sheet's row, 32px tile, at least 52px tall.
+   * - `side`: a mega menu's side list, a small bare icon and the label.
+   * - `label`: the label only (footer columns).
+   */
+  variant?: NavItemRowVariant;
+  renderLink?: SiteNavLinkRenderer;
+  /** The live counter for `link.badgeKey`; nothing renders at 0 or undefined. */
+  badge?: number;
+  /** Called on activation, so the menu or sheet holding the row can close. */
+  onNavigate?: () => void;
+  className?: string;
+}
+
+// Box and colour per variant; every text step is an ODS composite.
+const ROW_CLASSES: Record<NavItemRowVariant, string> = {
+  panel:
+    'flex items-start gap-[var(--spacing-system-sf)] rounded-lg p-[var(--spacing-system-sf)] text-ods-text-primary transition-colors hover:bg-ods-bg-hover',
+  sheet: 'flex min-h-[52px] items-center gap-[var(--spacing-system-sf)] py-1.5 text-ods-text-primary',
+  side: 'flex items-center gap-[var(--spacing-system-xsf)] rounded-md px-[var(--spacing-system-sf)] py-2.5 text-ods-text-secondary transition-colors text-h6 hover:bg-ods-bg-hover hover:text-ods-text-primary',
+  label:
+    'inline-flex items-center gap-[var(--spacing-system-xsf)] text-ods-text-secondary transition-colors text-h6 hover:text-ods-text-primary',
+};
+
+function RowGlyph({ link, box, glyph }: { link: NavLink; box: string; glyph: number }) {
+  // A server-configured icon (an agent's avatar) is drawn round and whole.
+  if (link.icon) {
+    return (
+      <span
+        aria-hidden="true"
+        className={cn('flex shrink-0 items-center justify-center overflow-hidden rounded-full', box)}
+      >
+        <EntityIcon icon={link.icon} className="h-full w-full" />
+      </span>
+    );
+  }
+  if (!link.iconName) return null;
+  return (
+    <span
+      aria-hidden="true"
+      className={cn(
+        'flex shrink-0 items-center justify-center rounded-lg border border-ods-border bg-ods-bg text-ods-text-primary',
+        box,
+      )}
+    >
+      <EntityIcon icon={{ name: link.iconName }} size={glyph} />
+    </span>
+  );
+}
+
+/**
+ * One navigation row, shared by the desktop panels, the mobile sheet and the
+ * footer columns: icon tile or agent avatar, label, description, the
+ * "Built on ..." line and an optional live counter.
+ */
+export function NavItemRow({
+  link,
+  variant = 'panel',
+  renderLink = defaultRenderSiteNavLink,
+  badge,
+  onNavigate,
+  className,
+}: NavItemRowProps) {
+  const label = navLinkLabel(link);
+  const counter = badge ? <UnreadCountBadge count={badge} className="static shrink-0" /> : null;
+  // A row with one line of text centres it on its icon; with a description or
+  // a "Built on" line the label stays level with the icon's top.
+  const singleLine = !link.description && !link.builtOn;
+  const rowClassName = cn(
+    ROW_CLASSES[variant],
+    variant === 'panel' && singleLine && 'items-center',
+    NAV_FOCUS_CLASS,
+    className,
+  );
+  const onClick = onNavigate ? () => onNavigate() : undefined;
+
+  let children: React.ReactNode;
+  if (variant === 'label') {
+    children = (
+      <>
+        {label}
+        {counter}
+      </>
+    );
+  } else if (variant === 'side') {
+    children = (
+      <>
+        {link.iconName && (
+          <span aria-hidden="true" className="flex shrink-0">
+            <EntityIcon icon={{ name: link.iconName }} size={18} />
+          </span>
+        )}
+        <span className="min-w-0 flex-1">{label}</span>
+        {counter}
+      </>
+    );
+  } else {
+    const sheet = variant === 'sheet';
+    children = (
+      <>
+        <RowGlyph link={link} box={sheet ? 'h-8 w-8' : 'h-9 w-9'} glyph={sheet ? 18 : 20} />
+        <span className="flex min-w-0 flex-1 flex-col">
+          <span className="flex items-center gap-[var(--spacing-system-xsf)] text-h6">
+            <span className="min-w-0">{label}</span>
+            {counter}
+          </span>
+          {link.description && <span className="text-ods-text-muted text-h6">{link.description}</span>}
+          {link.builtOn && <span className="text-ods-text-muted text-h6">Built on {link.builtOn}</span>}
+        </span>
+      </>
+    );
+  }
+
+  return <>{renderLink({ link, className: rowClassName, children, onClick })}</>;
+}