@flamingo-stack/openframe-frontend-core 0.0.705 → 0.0.706-snapshot.20261006190707

package/src/components/navigation/site-header.tsx

@@ -0,0 +1,339 @@
+'use client';
+
+import type React from 'react';
+import { useEffect, useRef, useState } from 'react';
+import Link from '../../embed-shims/next-link';
+import { useActiveSection } from '../../hooks/ui/use-active-section';
+import { useNavMenus } from '../../hooks/ui/use-nav-menus';
+import type { NavMenu, SiteNav } from '../../types/navigation';
+import { cn } from '../../utils/cn';
+import { EntityIcon } from '../icon-display';
+import { Chevron02DownIcon } from '../icons-v2-generated/arrows/chevron-02-down-icon';
+import { Menu01Icon } from '../icons-v2-generated/interface/menu-01-icon';
+import { XmarkIcon } from '../icons-v2-generated/signs-and-symbols/xmark-icon';
+import { Button } from '../ui/button';
+import { HeaderButton } from './header-button';
+import { MingoAiButton } from './mingo-ai-button';
+import { MOBILE_NAV_SHEET_ID } from './mobile-nav-sheet-id';
+import { isMegaMenu, NavPanel, type NavPanelMotion } from './nav-panel';
+import { defaultRenderSiteNavLink, NAV_FOCUS_CLASS, type SiteNavLinkRenderer } from './site-nav-link';
+import { TopNavigation } from './top-navigation';
+
+export interface SiteHeaderProps {
+  nav: SiteNav;
+  /** The host router's pathname: marks the active section and closes menus on navigation. */
+  pathname: string;
+  logo: React.ReactNode;
+  /** Omitted: the logo is not a link. */
+  logoHref?: string;
+  /** The host's link (Next `Link`, unified navigation). Default: `<a>`. */
+  renderLink?: SiteNavLinkRenderer;
+  /** Leading cells (admin sidebar toggle). Each cell owns its divider. */
+  leading?: React.ReactNode;
+  /** Host actions at the right (profile button, custom buttons). Shown at every width. */
+  actions?: React.ReactNode;
+  /** The primary CTA node when `nav.primaryCta` is `'trial'` or `'waitlist'`. */
+  cta?: React.ReactNode;
+  /** Trailing cells (ticket alerts). Each cell owns its divider. */
+  sideActions?: React.ReactNode;
+  /**
+   * The Mingo AI launcher, first in the right cluster (before Sign in).
+   * Omitted: no launcher. `icon` and `label` are the server-configured
+   * assistant identity (the same ones the chat panel shows); `source` scopes
+   * the `ask-ai:open` event the launcher dispatches.
+   */
+  mingo?: { source?: string; icon?: React.ReactNode; label?: string; shortcutHint?: boolean };
+  /** Omitted: no burger. */
+  mobile?: { isOpen: boolean; onToggle: () => void; controlsId?: string };
+  /** Values for `NavLink.badgeKey`. */
+  badges?: Record<string, number>;
+  /** Rendered under a menu with `showSocial`. */
+  social?: React.ReactNode;
+  autoHide?: boolean;
+  /** Opaque ODS background class. */
+  backgroundClassName?: string;
+  className?: string;
+  style?: React.CSSProperties;
+  /** The id the "Skip to content" link targets. Default `main-content`. */
+  skipToContentId?: string;
+}
+
+// A top-level item (prototype `.nv-l`): 40px tall, quiet until hovered, open
+// or current.
+const TOP_ITEM_CLASS =
+  'relative inline-flex h-10 items-center gap-1.5 whitespace-nowrap rounded-md px-3.5 text-ods-text-secondary transition-colors text-h6 hover:bg-ods-bg-hover hover:text-ods-text-primary';
+// The current section: a 2px accent underline and an accent wash.
+const TOP_ITEM_CURRENT_CLASS =
+  'rounded-b-none bg-gradient-to-b from-transparent to-ods-accent/10 text-ods-text-primary after:absolute after:inset-x-0 after:bottom-0 after:h-0.5 after:bg-ods-accent';
+
+/** A top-level item's optional glyph (`NavMenu.iconName`), before its label. */
+const menuIcon = (menu: NavMenu) =>
+  menu.iconName ? <EntityIcon icon={{ name: menu.iconName }} size={20} className="size-5 shrink-0" /> : null;
+
+/**
+ * The site header of every platform, drawn from one `SiteNav`: logo, the
+ * menus left-aligned after it, then the Mingo AI launcher, Sign in, the host's
+ * actions, the primary CTA (the only button) and the trailing cells. A
+ * platform differs only in the data and the slots it passes.
+ *
+ * Below `lg` the menus and Sign in leave the bar (they live in
+ * `MobileNavSheet`); the host's actions, the CTA and the launcher stay.
+ */
+export function SiteHeader({
+  nav,
+  pathname,
+  logo,
+  logoHref,
+  renderLink = defaultRenderSiteNavLink,
+  leading,
+  actions,
+  cta,
+  sideActions,
+  mingo,
+  mobile,
+  badges,
+  social,
+  autoHide = false,
+  backgroundClassName,
+  className,
+  style,
+  skipToContentId = 'main-content',
+}: SiteHeaderProps) {
+  const [show, setShow] = useState(true);
+  // Not state: nothing renders the previous offset, and as `useState` it
+  // re-rendered the whole header on every scroll event just to store a number.
+  const lastScrollY = useRef(0);
+
+  const activeId = useActiveSection(nav.menus, pathname);
+  const { openId, close, getTriggerProps, getPanelProps } = useNavMenus({ pathname });
+
+  // The menu that was open before this one, kept during render (no effect, no
+  // late frame): it tells an opening mega menu which side its content comes from.
+  const [trail, setTrail] = useState<{ id: string | null; from: string | null }>({ id: null, from: null });
+  if (trail.id !== openId) setTrail({ id: openId, from: trail.id });
+  const previousId = trail.id === openId ? trail.from : trail.id;
+  const megaIds = nav.menus.filter(isMegaMenu).map(menu => menu.id);
+  const openMegaIndex = openId === null ? -1 : megaIds.indexOf(openId);
+  const previousMegaIndex = previousId === null ? -1 : megaIds.indexOf(previousId);
+  const megaMotion: NavPanelMotion =
+    openMegaIndex < 0 || previousMegaIndex < 0 ? 'open' : openMegaIndex > previousMegaIndex ? 'from-end' : 'from-start';
+
+  useEffect(() => {
+    // Only add the scroll listener while auto-hide is on. Nothing to reset
+    // here: `show` is masked by `autoHide` where it is read (`headerShown`), so
+    // turning auto-hide off can never leave the header stuck off-screen.
+    if (!autoHide) return undefined;
+
+    const handleScroll = () => {
+      const currentScrollY = window.scrollY;
+      const prevScrollY = lastScrollY.current;
+      lastScrollY.current = currentScrollY;
+
+      if (currentScrollY > prevScrollY && currentScrollY > 50) setShow(false);
+      else if (currentScrollY < prevScrollY || currentScrollY <= 10) setShow(true);
+    };
+
+    window.addEventListener('scroll', handleScroll, { passive: true });
+    return () => window.removeEventListener('scroll', handleScroll);
+  }, [autoHide]);
+
+  // An open menu holds the header in place: hiding the bar would take the
+  // panel the visitor is reading with it.
+  const headerShown = !autoHide || show || openId !== null;
+
+  const renderMenu = (menu: NavMenu) => {
+    const current = menu.id === activeId;
+    const hasPanel = !!menu.columns?.length || !!menu.features?.length || !!menu.sideLinks?.length;
+
+    if (!hasPanel) {
+      if (!menu.href) return null;
+      return (
+        <div key={menu.id} className="flex">
+          <Button
+            asChild
+            variant="transparent"
+            size="wrap"
+            font="regular"
+            className={cn(TOP_ITEM_CLASS, NAV_FOCUS_CLASS, current && TOP_ITEM_CURRENT_CLASS)}
+          >
+            {renderLink({
+              link: { href: menu.href },
+              'aria-current': current ? 'page' : undefined,
+              children: (
+                <>
+                  {menuIcon(menu)}
+                  {menu.label}
+                </>
+              ),
+            })}
+          </Button>
+        </div>
+      );
+    }
+
+    const open = openId === menu.id;
+    return (
+      // A dropdown is anchored to its trigger (`relative`); a mega menu to the
+      // bar itself, so its wrapper stays unpositioned.
+      <div key={menu.id} className={cn('flex', !isMegaMenu(menu) && 'relative')}>
+        <Button
+          type="button"
+          variant="transparent"
+          size="wrap"
+          font="regular"
+          {...getTriggerProps(menu.id)}
+          aria-current={current ? 'page' : undefined}
+          className={cn(
+            TOP_ITEM_CLASS,
+            NAV_FOCUS_CLASS,
+            open && 'bg-ods-bg-hover text-ods-text-primary',
+            current && TOP_ITEM_CURRENT_CLASS,
+          )}
+        >
+          {menuIcon(menu)}
+          {menu.label}
+          <Chevron02DownIcon
+            aria-hidden="true"
+            // `!`: the Button sizes every glyph inside it at 20px; the chevron is 16.
+            className={cn('!h-4 !w-4 transition-transform duration-150', open && 'rotate-180')}
+          />
+        </Button>
+        <NavPanel
+          {...getPanelProps(menu.id)}
+          menu={menu}
+          open={open}
+          motion={open ? megaMotion : undefined}
+          handoff={openMegaIndex >= 0}
+          renderLink={renderLink}
+          badges={badges}
+          social={social}
+          onNavigate={close}
+        />
+      </div>
+    );
+  };
+
+  const primaryCta =
+    typeof nav.primaryCta === 'object' ? (
+      <Button variant="accent" href={nav.primaryCta.href}>
+        {nav.primaryCta.label}
+      </Button>
+    ) : nav.primaryCta === 'none' ? null : (
+      (cta ?? null)
+    );
+  const hasRight = !!mingo || !!nav.signIn || !!actions || !!primaryCta;
+
+  return (
+    <div
+      // Hook point for page-scoped header CSS (a full-screen deck hides the bar).
+      data-site-header=""
+      className="sticky top-0 z-[50] w-full transition-transform duration-300 ease-in-out"
+      style={{ transform: headerShown ? 'translateY(0)' : 'translateY(-100%)' }}
+    >
+      {/* First tab stop of the page; visible only while focused. */}
+      <Link
+        href={`#${skipToContentId}`}
+        className={cn(
+          'sr-only left-[var(--spacing-system-lf)] top-3 z-[70] rounded-md bg-ods-text-primary px-[var(--spacing-system-mf)] py-[var(--spacing-system-xsf)] text-ods-bg text-h6 focus:not-sr-only focus:absolute',
+          NAV_FOCUS_CLASS,
+        )}
+      >
+        Skip to content
+      </Link>
+      {/* Unified ODS top-navigation shell (Figma 2797-5978), cell model with
+          per-cell dividers. NOTE: no `backdrop-blur` anywhere in this bar.
+          Every platform ships an OPAQUE header background, so a
+          backdrop-filter would blur a backdrop that is then fully painted
+          over: zero visual effect, but the browser still re-rasterizes the
+          strip behind this sticky bar every scroll frame and content flickers
+          as it passes under the header. A translucent "glass" header needs
+          the blur and a translucent `backgroundClassName` together. */}
+      <TopNavigation
+        // `relative` anchors a mega menu to the bar: it opens full width
+        // right under it.
+        className={cn('relative', className)}
+        style={style}
+        backgroundClassName={backgroundClassName}
+        centerBreakpoint="lg"
+        size="big"
+        leading={
+          <>
+            {leading}
+            {/* Menu toggle: a leading cell, banded with the menus' breakpoint
+                (`lg`) so the desktop menus and the toggle never co-show. */}
+            {mobile && (
+              <HeaderButton
+                className="border-r border-ods-border lg:hidden"
+                onClick={mobile.onToggle}
+                isActive={mobile.isOpen}
+                aria-label={mobile.isOpen ? 'Close menu' : 'Open menu'}
+                aria-expanded={mobile.isOpen}
+                // Conditional: the sheet unmounts when closed, so an
+                // unconditional reference would dangle (axe aria-valid-attr-value).
+                aria-controls={mobile.isOpen ? (mobile.controlsId ?? MOBILE_NAV_SHEET_ID) : undefined}
+                icon={mobile.isOpen ? <XmarkIcon className="h-6 w-6" /> : <Menu01Icon className="h-6 w-6" />}
+              />
+            )}
+          </>
+        }
+        logo={
+          logoHref
+            ? renderLink({
+                link: { href: logoHref },
+                className: cn(
+                  'flex min-w-0 items-center rounded-md transition-opacity duration-200 hover:opacity-80',
+                  NAV_FOCUS_CLASS,
+                ),
+                'aria-label': nav.brand.name,
+                children: logo,
+              })
+            : logo
+        }
+        // Big-bar rule (Figma 2936-6812): a fixed 24px left inset on the logo
+        // zone at every breakpoint, which also reads as the gap between a
+        // leading cell and the logo. `shrink` lets the logo, never the CTA,
+        // give way on the narrowest phones.
+        logoClassName="shrink pl-[var(--spacing-system-lf)] md:pl-[var(--spacing-system-lf)] lg:pl-[var(--spacing-system-lf)]"
+        center={
+          nav.menus.length > 0 ? (
+            <nav aria-label="Main" className="flex items-center gap-[var(--spacing-system-xxs)]">
+              {nav.menus.map(renderMenu)}
+            </nav>
+          ) : undefined
+        }
+        centerClassName="justify-start pl-[var(--spacing-system-xlf)]"
+        cta={
+          hasRight ? (
+            <>
+              {mingo && (
+                <MingoAiButton
+                  source={mingo.source}
+                  icon={mingo.icon}
+                  label={mingo.label}
+                  shortcutHint={mingo.shortcutHint}
+                />
+              )}
+              {nav.signIn && (
+                <div className="hidden lg:flex">
+                  <Button
+                    asChild
+                    variant="transparent"
+                    size="wrap"
+                    font="regular"
+                    className={cn(TOP_ITEM_CLASS, NAV_FOCUS_CLASS)}
+                  >
+                    {renderLink({ link: nav.signIn, children: nav.signIn.label })}
+                  </Button>
+                </div>
+              )}
+              {actions}
+              {primaryCta}
+            </>
+          ) : undefined
+        }
+        ctaClassName="gap-[var(--spacing-system-xsf)]"
+        sideActions={sideActions}
+      />
+    </div>
+  );
+}

package/src/components/navigation/site-nav-link.tsx

@@ -0,0 +1,41 @@
+import type React from 'react';
+import Link from '../../embed-shims/next-link';
+import type { NavLink } from '../../types/navigation';
+
+/**
+ * How a host renders one navigation link (Next `Link`, a unified-navigation
+ * anchor). Every site navigation component takes one; omitted, links go
+ * through {@link defaultRenderSiteNavLink}.
+ */
+export type SiteNavLinkRenderer = (props: {
+  link: Pick<NavLink, 'href' | 'external'>;
+  className?: string;
+  children: React.ReactNode;
+  onClick?: (e: React.MouseEvent) => void;
+  'aria-current'?: 'page';
+  'aria-label'?: string;
+}) => React.ReactNode;
+
+/**
+ * The default link: the library's `Link` shim (a plain `<a>`, or the host's
+ * registered router link, so internal links soft-navigate), opened in a new
+ * tab for a link that leaves the site.
+ */
+export const defaultRenderSiteNavLink: SiteNavLinkRenderer = ({ link, children, ...rest }) =>
+  link.external ? (
+    <Link href={link.href} target="_blank" rel="noopener noreferrer" {...rest}>
+      {children}
+    </Link>
+  ) : (
+    <Link href={link.href} {...rest}>
+      {children}
+    </Link>
+  );
+
+/** A link's label, with its `{count}` token filled from `link.count`. */
+export function navLinkLabel(link: Pick<NavLink, 'label' | 'count'>): string {
+  return link.count === undefined ? link.label : link.label.replace('{count}', String(link.count));
+}
+
+/** Focus ring shared by every navigation link and trigger. */
+export const NAV_FOCUS_CLASS = 'outline-none focus-visible:ring-2 focus-visible:ring-ods-accent';

package/src/components/navigation/ticket-alerts-button.tsx

@@ -2,8 +2,8 @@
 
 /**
  * TicketAlertsButton — the unified header affordance for support-ticket
- * unread indication. Mounted by BOTH header shells (hub `Header` via
- * `HeaderConfig.tickets`, console `AppHeader` via `showTicketAlerts`).
+ * unread indication. Mounted by BOTH header shells (the `SiteHeader` through its
+ * `sideActions` slot, console `AppHeader` via `showTicketAlerts`).
  *
  * ATTENTION-ONLY element, deliberately unlike the always-on header cells:
  *   - renders NOTHING unless there are unread support replies (and a

package/src/components/navigation/top-navigation.tsx

@@ -59,7 +59,7 @@ export interface TopNavigationProps extends React.HTMLAttributes<HTMLElement> {
   sideActions?: React.ReactNode;
   /** Opaque ODS background class. Defaults to `bg-ods-card`. Keep it opaque —
    *  translucent backgrounds under a sticky bar need a deliberate
-   *  backdrop-blur treatment (see the note in `header.tsx`). */
+   *  backdrop-blur treatment (see the note in `site-header.tsx`). */
   backgroundClassName?: string;
   /** Top border on mobile (the ODS spec bar shows it below md). Default true. */
   mobileTopBorder?: boolean;
@@ -73,7 +73,7 @@ const hasContent = (node: React.ReactNode): boolean => node !== null && node !==
 /**
  * Unified ODS top-navigation bar (Figma `[UPD] top-navigation`, node
  * 2797-5978): the single 48px/56px (mobile / md+) cell-based header shell
- * shared by the console `AppHeader` and the marketing `Header` across all
+ * shared by the console `AppHeader` and the `SiteHeader` across all
  * platforms.
  *
  * The shell owns the bar geometry only — height, borders, background, and the

package/src/components/platform/ToolBadge.tsx

@@ -9,6 +9,7 @@ import type React from 'react';
 import type { ToolType } from '../../types/tool.types';
 import { cn } from '../../utils/cn';
 import { getToolLabel } from '../../utils/tool-utils';
+import { NavLinkAnchorViaRuntime } from '../chat/nav-link-anchor-via-runtime';
 import { ToolIcon } from '../tool-icon';
 
 export type { ToolType } from '../../types/tool.types';
@@ -31,6 +32,12 @@ export interface ToolBadgeProps {
    * link that opens it in a new tab; without it the badge is plain text.
    */
   href?: string | null;
+  /**
+   * The platform `href` is on, by name, when it is one of the host's own
+   * platforms. The badge then opens through the shared navigation rule (the
+   * one chat cards use); the host must mount the chat runtime.
+   */
+  targetPlatform?: string | null;
   /** Additional CSS classes */
   className?: string;
   iconClassName?: string;
@@ -47,6 +54,7 @@ export const ToolBadge: React.FC<ToolBadgeProps> = ({
   icon,
   variant = 'inline',
   href,
+  targetPlatform,
   className,
   iconClassName,
 }) => {
@@ -55,7 +63,16 @@ export const ToolBadge: React.FC<ToolBadgeProps> = ({
 
   // One rule for both variants: with an `href` the badge is a link.
   const linked = (node: React.ReactElement, linkClassName: string) =>
-    href ? (
+    href && targetPlatform ? (
+      <NavLinkAnchorViaRuntime
+        href={href}
+        targetPlatform={targetPlatform}
+        title={text || undefined}
+        className={linkClassName}
+      >
+        {node}
+      </NavLinkAnchorViaRuntime>
+    ) : href ? (
       <a href={href} target="_blank" rel="noopener noreferrer" title={text || undefined} className={linkClassName}>
         {node}
       </a>

package/src/components/ui/brand-association-card.tsx

@@ -2,6 +2,7 @@
 
 import { ExternalLink } from 'lucide-react';
 import React from 'react';
+import { useNavLinkViaRuntime } from '../chat/nav-link-anchor-via-runtime';
 import { Button } from './button';
 
 export interface BrandAssociationItem {
@@ -10,6 +11,13 @@ export interface BrandAssociationItem {
   description: string;
   buttonText: string;
   link: string;
+  /**
+   * The platform `link` leads to, by name, when it is another of the host's
+   * own platforms. The button then opens it through the shared navigation rule
+   * (the one chat cards use); the host must mount the chat runtime. Omitted, it
+   * is a plain outside link in a new tab.
+   */
+  targetPlatform?: string | null;
 }
 
 export interface BrandAssociationCardProps {
@@ -17,6 +25,16 @@ export interface BrandAssociationCardProps {
   className?: string;
 }
 
+/** The button to a NAMED platform: the shared navigation rule decides how it opens. */
+function PlatformBrowseButton({ item }: { item: BrandAssociationItem }) {
+  const linkProps = useNavLinkViaRuntime({ href: item.link, targetPlatform: item.targetPlatform });
+  return (
+    <Button variant="outline" linkProps={linkProps} rightIcon={<ExternalLink className="h-4 w-4" />}>
+      Browse {item.buttonText}
+    </Button>
+  );
+}
+
 export function BrandAssociationCard({ item, className = '' }: BrandAssociationCardProps) {
   // Helper function to render icon - handle both React elements and components
   const renderIcon = () => {
@@ -43,9 +61,13 @@ export function BrandAssociationCard({ item, className = '' }: BrandAssociationC
         <p className="text-ods-text-secondary text-h6">{item.description}</p>
 
         {/* Browse Button */}
-        <Button variant="outline" href={item.link} openInNewTab rightIcon={<ExternalLink className="h-4 w-4" />}>
-          Browse {item.buttonText}
-        </Button>
+        {item.targetPlatform ? (
+          <PlatformBrowseButton item={item} />
+        ) : (
+          <Button variant="outline" href={item.link} openInNewTab rightIcon={<ExternalLink className="h-4 w-4" />}>
+            Browse {item.buttonText}
+          </Button>
+        )}
       </div>
     </div>
   );

package/src/hooks/index.ts

@@ -39,6 +39,7 @@ export * from './use-claude-mirror-src';
 // Deep-link "scroll to URL hash" after data loads. Pairs with URL
 // composers that emit `?<filter>=<id>#<prefix>-<id>` — the filter
 // narrows the list, the hash scrolls the matching DOM id.
+export * from './use-location-hash';
 export * from './use-scroll-to-hash';
 
 // Invisible bot-protection client primitive (honeypot ref + submit-timing).

package/src/hooks/ui/index.ts

@@ -31,3 +31,6 @@ export { usePreventScroll } from '@react-aria/overlays';
 export * from './use-prefers-reduced-motion';
 export * from './use-in-view';
 export * from './use-autoplay';
+export * from './use-active-section';
+export * from './use-nav-menus';
+export * from './use-visitor-os';

package/src/hooks/ui/use-active-section.ts

@@ -0,0 +1,44 @@
+'use client';
+
+import { useMemo } from 'react';
+import type { NavMenu } from '../../types/navigation';
+
+/** The path of an internal href, without its query or `#anchor`. `null` for an
+ *  absolute URL: another site is never the current section. */
+function pathOf(href: string | undefined): string | null {
+  if (!href || !href.startsWith('/') || href.startsWith('//')) return null;
+  const path = href.split(/[?#]/)[0];
+  return path.length > 1 ? path.replace(/\/+$/, '') : '/';
+}
+
+/** Boundary-aware prefix test: `/pricing` holds `/pricing` and `/pricing/x`,
+ *  never `/pricing-old`; `/` holds only `/`. */
+function prefixHolds(prefix: string, pathname: string): boolean {
+  if (prefix === '/') return pathname === '/';
+  return pathname === prefix || pathname.startsWith(`${prefix}/`);
+}
+
+/**
+ * Pure rule behind {@link useActiveSection}: the id of the menu whose `match`
+ * prefixes (else its `href`) hold the pathname. The longest prefix wins, the
+ * first menu on a tie; `null` when none holds it.
+ */
+export function resolveActiveSection(menus: readonly NavMenu[], pathname: string | null | undefined): string | null {
+  const current = pathOf(pathname ?? undefined);
+  if (!current) return null;
+  let best: { id: string; length: number } | null = null;
+  for (const menu of menus) {
+    const prefixes = menu.match?.length ? menu.match : [menu.href];
+    for (const raw of prefixes) {
+      const prefix = pathOf(raw);
+      if (!prefix || !prefixHolds(prefix, current)) continue;
+      if (!best || prefix.length > best.length) best = { id: menu.id, length: prefix.length };
+    }
+  }
+  return best?.id ?? null;
+}
+
+/** The id of the top-level menu the current page belongs to, or `null`. */
+export function useActiveSection(menus: readonly NavMenu[], pathname: string | null | undefined): string | null {
+  return useMemo(() => resolveActiveSection(menus, pathname), [menus, pathname]);
+}