@flamingo-stack/openframe-frontend-core 0.0.409 → 0.0.410-snapshot.20260711165901

package/src/components/navigation/index.ts

@@ -10,7 +10,7 @@ export type { ClientOnlyHeaderProps } from './client-only-header'
 export { HeaderSkeleton } from './header-skeleton'
 export type { HeaderSkeletonProps } from './header-skeleton'
 
-export { MobileNavPanel } from './mobile-nav-panel'
+export { MobileNavPanel, MOBILE_NAV_PANEL_ID } from './mobile-nav-panel'
 export type { MobileNavPanelProps } from './mobile-nav-panel'
 
 export { SlidingSidebar } from './sliding-sidebar'

package/src/components/navigation/mobile-burger-menu.tsx

@@ -1,8 +1,10 @@
 "use client"
 
-import React, { useCallback, useEffect } from 'react'
+import React, { useCallback, useRef } from 'react'
+import { usePreventScroll } from '@react-aria/overlays'
 import { NavigationSidebarConfig, NavigationSidebarItem } from '../../types/navigation'
 import { cn } from '../../utils'
+import { useFocusTrap } from '../../hooks/ui/use-focus-trap'
 import { Logout02Icon, PenEditIcon, UserSearchIcon } from '../icons-v2-generated'
 import { Button, SquareAvatar } from '../ui'
 import { OVERLAY_BACKDROP_CLASS } from '../ui/drawer'
@@ -47,32 +49,12 @@ export const MobileBurgerMenu = React.memo(function MobileBurgerMenu({
   onLogout,
   disabled = false,
 }: MobileBurgerMenuProps) {
-  // Prevent body scroll when menu is open
-  useEffect(() => {
-    if (isOpen) {
-      document.body.style.overflow = 'hidden'
-    } else {
-      document.body.style.overflow = 'unset'
-    }
-
-    return () => {
-      document.body.style.overflow = 'unset'
-    }
-  }, [isOpen])
+  const panelRef = useRef<HTMLDivElement>(null)
 
-  // Handle escape key
-  useEffect(() => {
-    const handleKeyDown = (e: KeyboardEvent) => {
-      if (e.key === 'Escape' && isOpen) {
-        onClose()
-      }
-    }
-
-    if (isOpen) {
-      document.addEventListener('keydown', handleKeyDown)
-      return () => document.removeEventListener('keydown', handleKeyDown)
-    }
-  }, [isOpen, onClose])
+  // Shared ref-counted, iOS-aware scroll lock (react-aria) while open.
+  usePreventScroll({ isDisabled: !isOpen })
+  // Initial focus, Tab containment, Escape-to-close, guarded focus restore.
+  useFocusTrap(panelRef, isOpen, { onEscape: onClose })
 
   const handleItemClick = useCallback((item: NavigationSidebarItem) => {
     if (item.onClick) {
@@ -165,7 +147,7 @@ export const MobileBurgerMenu = React.memo(function MobileBurgerMenu({
         className={cn(
           "absolute inset-0 z-[100] md:hidden",
           OVERLAY_BACKDROP_CLASS,
-          "transition-all duration-300",
+          "transition-all duration-300 motion-reduce:transition-none",
           isOpen ? "opacity-100" : "opacity-0 pointer-events-none"
         )}
         style={{ top: HEADER_HEIGHT }}
@@ -176,11 +158,12 @@ export const MobileBurgerMenu = React.memo(function MobileBurgerMenu({
       {/* Menu Panel - positioned below header with slide-down animation. `absolute`
           for the same reason as the backdrop above (anchors below the topBar). */}
       <div
+        ref={panelRef}
         className={cn(
           "absolute left-0 right-0 z-[101] md:hidden",
           "flex flex-col",
           "bg-ods-bg border-b border-ods-border",
-          "transition-all duration-300 ease-out",
+          "transition-all duration-300 ease-out motion-reduce:transition-none",
           "overflow-hidden",
           isOpen
             ? "opacity-100 translate-y-0"
@@ -193,9 +176,13 @@ export const MobileBurgerMenu = React.memo(function MobileBurgerMenu({
         role="dialog"
         aria-modal="true"
         aria-label="Mobile navigation menu"
+        tabIndex={-1}
+        // Stays mounted while hidden (opacity-0) — inert keeps its items out
+        // of the tab order when closed.
+        inert={!isOpen || undefined}
       >
         {/* Scrollable Content */}
-        <div className="flex-1 overflow-y-auto overflow-x-hidden p-4 flex flex-col gap-4">
+        <div className="flex-1 overflow-y-auto overflow-x-hidden overscroll-contain p-4 flex flex-col gap-4">
           {/* User Card */}
           {user && (
             <div

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

@@ -1,11 +1,18 @@
 "use client"
 
-import React, { useEffect, useRef } from 'react'
+import React, { useRef } from 'react'
+import { usePreventScroll } from '@react-aria/overlays'
 import { cn } from '../../utils'
 import { MobileNavConfig, NavigationItem } from '../../types/navigation'
 import { Button } from '../ui/button'
+import { OVERLAY_BACKDROP_CLASS } from '../ui/drawer'
+import { useFocusTrap } from '../../hooks/ui/use-focus-trap'
+import { useHeaderHeight } from '../../hooks/ui/use-header-height'
 import { X } from 'lucide-react'
 
+/** DOM id of the panel — referenced by the header hamburger's `aria-controls`. */
+export const MOBILE_NAV_PANEL_ID = 'mobile-nav-panel'
+
 export interface MobileNavPanelProps {
   isOpen: boolean
   config: MobileNavConfig
@@ -14,32 +21,13 @@ export interface MobileNavPanelProps {
 export function MobileNavPanel({ isOpen, config }: MobileNavPanelProps) {
   const panelRef = useRef<HTMLDivElement>(null)
 
-  // Prevent body scroll when menu is open - using the original working approach
-  useEffect(() => {
-    if (isOpen) {
-      document.body.style.overflow = 'hidden'
-    } else {
-      document.body.style.overflow = 'unset'
-    }
-
-    return () => {
-      document.body.style.overflow = 'unset'
-    }
-  }, [isOpen])
-
-  // Handle escape key
-  useEffect(() => {
-    const handleKeyDown = (e: KeyboardEvent) => {
-      if (e.key === 'Escape' && isOpen) {
-        config.onClose?.()
-      }
-    }
-
-    if (isOpen) {
-      document.addEventListener('keydown', handleKeyDown)
-      return () => document.removeEventListener('keydown', handleKeyDown)
-    }
-  }, [isOpen, config])
+  // Shared ref-counted, iOS-aware scroll lock (react-aria) — one counter with
+  // the modals and chat overlays, restores prior styles on release.
+  usePreventScroll({ isDisabled: !isOpen })
+  // Initial focus, Tab containment, Escape-to-close, guarded focus restore.
+  useFocusTrap(panelRef, isOpen, { onEscape: config.onClose })
+  // The panel is layout-mounted on every page — observers only while open.
+  const headerHeight = useHeaderHeight(64, { enabled: isOpen })
 
   if (!isOpen) return null
 
@@ -99,21 +87,30 @@ export function MobileNavPanel({ isOpen, config }: MobileNavPanelProps) {
     <>
       {/* Backdrop - closes nav when clicked outside */}
       <div
-        className="fixed inset-0 z-[9998] bg-black/50"
+        className={cn("fixed inset-0 z-[9998]", OVERLAY_BACKDROP_CLASS)}
         onClick={config.onClose}
       />
 
-      {/* Navigation Panel - modal style like the original working version */}
+      {/* Navigation Panel - top-anchored floating card */}
       <div
         ref={panelRef}
+        id={MOBILE_NAV_PANEL_ID}
+        role="dialog"
+        aria-modal="true"
+        aria-label="Navigation menu"
+        tabIndex={-1}
+        style={{ '--mobile-nav-top': `${headerHeight + 16}px` } as React.CSSProperties}
         className={cn(
           "fixed z-[9999] rounded-lg shadow-xl",
           config.className ? "" : "bg-ods-card border border-ods-border",
-          // Responsive positioning and sizing - matching original working version
+          // Responsive positioning and sizing
           "right-2 left-2 md:left-auto",
           "md:right-6 md:w-[400px] md:max-w-[calc(100vw-3rem)]",
-          // Height constraints with proper mobile spacing - increased top position
-          "top-20 max-h-[calc(100vh-130px)] md:max-h-[calc(100vh-88px)]",
+          // Small-viewport (svh) sizing anchored below the measured header —
+          // 100vh overflowed under mobile browser chrome, leaving the bottom
+          // entries and footer unreachable while the body was scroll-locked.
+          "top-[var(--mobile-nav-top)]",
+          "max-h-[calc(100svh-var(--mobile-nav-top)-50px)] md:max-h-[calc(100svh-var(--mobile-nav-top)-8px)]",
           "flex flex-col",
           config.className || ""
         )}
@@ -132,7 +129,7 @@ export function MobileNavPanel({ isOpen, config }: MobileNavPanelProps) {
         </div>
 
         {/* Scrollable content area */}
-        <div className="flex-1 overflow-y-auto overflow-x-hidden px-2 py-2">
+        <div className="flex-1 overflow-y-auto overflow-x-hidden overscroll-contain px-2 py-2">
           <div className="flex flex-col space-y-1">
             {config.sections.map((section, index) => (
               <div key={index}>
@@ -149,9 +146,9 @@ export function MobileNavPanel({ isOpen, config }: MobileNavPanelProps) {
           </div>
         </div>
 
-        {/* Footer with action button - fixed at bottom */}
+        {/* Footer with action button - fixed at bottom, clears the iOS home indicator */}
         {config.footer && (
-          <div className="border-t border-ods-border p-4 flex-shrink-0">
+          <div className="border-t border-ods-border p-4 pb-[max(1rem,env(safe-area-inset-bottom))] flex-shrink-0">
             {config.footer}
           </div>
         )}

package/src/components/navigation/sliding-sidebar.tsx

@@ -1,11 +1,14 @@
 "use client"
 
-import React, { useState, useEffect } from 'react'
-import { motion, AnimatePresence } from 'framer-motion'
+import React, { useState, useEffect, useRef } from 'react'
+import { motion, AnimatePresence, useReducedMotion } from 'framer-motion'
+import { usePreventScroll } from '@react-aria/overlays'
 import { cn } from '../../utils'
 import { useHeaderHeight } from '../../hooks/ui'
+import { useFocusTrap } from '../../hooks/ui/use-focus-trap'
 import { SlidingSidebarConfig, NavigationItem } from '../../types/navigation'
 import { Button } from '../ui/button'
+import { OVERLAY_BACKDROP_CLASS } from '../ui/drawer'
 
 export interface SlidingSidebarProps {
   config: SlidingSidebarConfig
@@ -15,6 +18,15 @@ export function SlidingSidebar({ config }: SlidingSidebarProps) {
   const [expandedItems, setExpandedItems] = useState<Set<string>>(new Set())
   const [mounted, setMounted] = useState(false)
   const headerHeight = useHeaderHeight()
+  const asideRef = useRef<HTMLElement>(null)
+  const prefersReducedMotion = useReducedMotion()
+
+  // Shared ref-counted scroll lock (react-aria) while the drawer is open.
+  usePreventScroll({ isDisabled: !config.isOpen })
+  // Escape + initial focus + guarded restore. `contain: false`: the z-50
+  // header stays visible and clickable ABOVE the open drawer (see the z-tier
+  // comment below), so this is a NON-modal dialog — Tab may leave freely.
+  useFocusTrap(asideRef, config.isOpen, { onEscape: config.onClose, contain: false })
 
   useEffect(() => { setMounted(true) }, [])
 
@@ -170,7 +182,7 @@ export function SlidingSidebar({ config }: SlidingSidebarProps) {
               duration: 0.3, 
               ease: [0.4, 0, 0.2, 1]
             }}
-            className="fixed inset-0 bg-black/50 z-[45]"
+            className={cn("fixed inset-0 z-[45]", OVERLAY_BACKDROP_CLASS)}
             onClick={() => config.onClose()}
           />
         )}
@@ -178,18 +190,26 @@ export function SlidingSidebar({ config }: SlidingSidebarProps) {
 
       {/* Sliding Sidebar */}
       <motion.aside
+        ref={asideRef}
         initial={false}
         animate={{
           x: config.isOpen ? 0 : (config.position === 'right' ? "100%" : "-100%")
         }}
-        transition={{ 
-          type: "spring", 
-          damping: 25, 
+        transition={prefersReducedMotion ? { duration: 0 } : {
+          type: "spring",
+          damping: 25,
           stiffness: 300,
           mass: 0.8,
           restDelta: 0.01,
           velocity: config.isOpen ? 5 : -5
         }}
+        tabIndex={-1}
+        // Stays mounted translated off-screen — inert keeps its items out of
+        // the tab order while "closed". Non-modal dialog: no aria-modal (the
+        // header above remains reachable by design).
+        inert={!config.isOpen || undefined}
+        role={config.isOpen ? 'dialog' : undefined}
+        aria-label={config.isOpen ? 'Navigation sidebar' : undefined}
         className={cn(
           "fixed top-0 bottom-0 z-[46] w-72 bg-ods-card border-ods-border flex flex-col shadow-xl",
           config.position === 'right' ? "right-0 border-l" : "left-0 border-r",
@@ -200,13 +220,13 @@ export function SlidingSidebar({ config }: SlidingSidebarProps) {
         <div className="flex-shrink-0" style={{ height: `${headerHeight}px` }} />
         
         {/* Navigation */}
-        <nav className="flex-1 p-4 space-y-2 overflow-y-auto">
+        <nav className="flex-1 p-4 space-y-2 overflow-y-auto overscroll-contain">
           {config.items.map(item => renderMenuItem(item))}
         </nav>
 
-        {/* Footer */}
+        {/* Footer - bottom padding clears the iOS home indicator */}
         {config.footer && (
-          <div className="p-4 border-t border-ods-border">
+          <div className="p-4 pb-[max(1rem,env(safe-area-inset-bottom))] border-t border-ods-border">
             {config.footer}
           </div>
         )}

package/src/components/ui/modal-v2.tsx

@@ -2,6 +2,7 @@
 
 import * as React from "react"
 import { useEffect, useState } from "react"
+import { usePreventScroll } from "@react-aria/overlays"
 import { XmarkIcon } from "../icons-v2-generated"
 import { cn } from "../../utils/cn"
 
@@ -52,6 +53,11 @@ const Modal = React.forwardRef<HTMLDivElement, ModalProps>(
       return () => clearTimeout(timeout)
     }, [isOpen])
 
+    // Shared ref-counted scroll lock (react-aria) — restores prior styles on
+    // release instead of clobbering to 'unset'.
+    usePreventScroll({ isDisabled: !isOpen })
+
+    // Escape key (document-level: top-of-stack semantics for modals)
     useEffect(() => {
       const handleKeyDown = (event: KeyboardEvent) => {
         if (event.key === 'Escape') {
@@ -60,13 +66,8 @@ const Modal = React.forwardRef<HTMLDivElement, ModalProps>(
       }
 
       if (isOpen) {
-        document.body.style.overflow = 'hidden'
         document.addEventListener('keydown', handleKeyDown)
-
-        return () => {
-          document.body.style.overflow = 'unset'
-          document.removeEventListener('keydown', handleKeyDown)
-        }
+        return () => document.removeEventListener('keydown', handleKeyDown)
       }
     }, [isOpen, onClose])
 

package/src/components/ui/modal.tsx

@@ -2,6 +2,7 @@
 
 import * as React from "react"
 import { useEffect } from "react"
+import { usePreventScroll } from "@react-aria/overlays"
 import { cn } from "../../utils/cn"
 
 interface ModalProps {
@@ -34,7 +35,11 @@ interface ModalFooterProps {
 /** @deprecated Use ModalV2 from './modal-v2' instead. */
 const Modal = React.forwardRef<HTMLDivElement, ModalProps>(
   ({ isOpen, onClose, children, className }, ref) => {
-    // Handle Escape key and scroll blocking
+    // Shared ref-counted scroll lock (react-aria) — restores prior styles on
+    // release instead of clobbering to 'unset'.
+    usePreventScroll({ isDisabled: !isOpen })
+
+    // Handle Escape key (document-level: top-of-stack semantics for modals)
     useEffect(() => {
       const handleKeyDown = (event: KeyboardEvent) => {
         if (event.key === 'Escape') {
@@ -43,15 +48,8 @@ const Modal = React.forwardRef<HTMLDivElement, ModalProps>(
       }
 
       if (isOpen) {
-        // Block background scrolling
-        document.body.style.overflow = 'hidden'
         document.addEventListener('keydown', handleKeyDown)
-        
-        return () => {
-          // Restore scrolling
-          document.body.style.overflow = 'unset'
-          document.removeEventListener('keydown', handleKeyDown)
-        }
+        return () => document.removeEventListener('keydown', handleKeyDown)
       }
     }, [isOpen, onClose])
 

package/src/hooks/ui/index.ts

@@ -2,6 +2,7 @@
 export * from './use-auto-limit-tags'
 export * from './use-debounce'
 export * from './use-deferred-error'
+export * from './use-focus-trap'
 export * from './use-header-height'
 export * from './use-horizontal-scrollbar'
 export * from './use-image-edge-color'
@@ -14,3 +15,8 @@ export * from './use-search'
 export * from './use-table-pagination'
 export * from './use-throttle'
 export * from './use-window-size'
+
+// Shared ref-counted, iOS-aware body scroll lock (react-aria). Re-exported so
+// hub/app consumers have one import path; lib internals may import the
+// package directly (npm dedupes to one module instance either way).
+export { usePreventScroll } from '@react-aria/overlays'

package/src/hooks/ui/use-focus-trap.ts

@@ -0,0 +1,110 @@
+'use client'
+
+import { useEffect, useRef, type RefObject } from 'react'
+
+const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'button:not([disabled])',
+  'input:not([disabled])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+].join(', ')
+
+export interface UseFocusTrapOptions {
+  /** Called when Escape is pressed while focus is inside the container.
+   *  When omitted, Escape passes through untouched so document-level
+   *  listeners still fire. */
+  onEscape?: () => void
+  /**
+   * When false, Tab/Shift+Tab are NOT cycled within the container — for
+   * non-modal dialogs (e.g. SlidingSidebar, whose z-50 header stays clickable
+   * above the open drawer). Escape / initial focus / guarded restore still apply.
+   * @default true
+   */
+  contain?: boolean
+}
+
+/**
+ * Focus management for overlay surfaces (mobile nav panel, sliding sidebar,
+ * burger menu, modals): initial focus on activate, container-scoped Tab
+ * cycling + Escape, and guarded focus restore on deactivate.
+ *
+ * CONTRACT: the container element MUST have `tabIndex={-1}`. After a
+ * click/tap on a non-focusable area inside the surface, browsers move focus
+ * to the nearest focusable ancestor — with the container script-focusable
+ * that ancestor is the container itself, so this keydown listener keeps
+ * hearing Escape/Tab. Without it, focus falls to `body` and the trap goes
+ * deaf.
+ *
+ * The listener being container-scoped makes it stacking-safe: it only fires
+ * while focus is inside the surface, so a modal open above never leaks its
+ * Escape into the surface below.
+ */
+export function useFocusTrap(
+  containerRef: RefObject<HTMLElement | null>,
+  active: boolean,
+  { onEscape, contain = true }: UseFocusTrapOptions = {}
+): void {
+  // Latest-ref so unstable inline callbacks never tear the trap down and
+  // re-yank focus — same stable-callback discipline as `useCloseOnNavigation`.
+  const onEscapeRef = useRef(onEscape)
+  onEscapeRef.current = onEscape
+
+  useEffect(() => {
+    if (!active) return
+    const container = containerRef.current
+    if (!container) return
+
+    const previouslyFocused = document.activeElement as HTMLElement | null
+
+    const focusables = () =>
+      Array.from(container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR))
+        .filter((el) => el.getClientRects().length > 0)
+
+    const first = focusables()[0]
+    ;(first ?? container).focus({ preventScroll: true })
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        // No preventDefault/stopPropagation — pass-through by design.
+        onEscapeRef.current?.()
+        return
+      }
+      if (e.key !== 'Tab' || !contain) return
+      const items = focusables()
+      if (items.length === 0) {
+        e.preventDefault()
+        container.focus({ preventScroll: true })
+        return
+      }
+      const firstEl = items[0]
+      const lastEl = items[items.length - 1]
+      const current = document.activeElement
+      if (e.shiftKey && (current === firstEl || current === container)) {
+        e.preventDefault()
+        lastEl.focus({ preventScroll: true })
+      } else if (!e.shiftKey && current === lastEl) {
+        e.preventDefault()
+        firstEl.focus({ preventScroll: true })
+      }
+    }
+
+    container.addEventListener('keydown', handleKeyDown)
+
+    return () => {
+      container.removeEventListener('keydown', handleKeyDown)
+      // Guarded restore: only when focus is still inside the surface (or fell
+      // to body because the surface unmounted) — never steal focus from a
+      // dialog that opened meanwhile (e.g. the nav-footer → SSO modal flow).
+      const current = document.activeElement
+      if (
+        previouslyFocused &&
+        previouslyFocused.isConnected &&
+        (current === null || current === document.body || container.contains(current))
+      ) {
+        previouslyFocused.focus({ preventScroll: true })
+      }
+    }
+  }, [containerRef, active, contain])
+}

package/src/hooks/ui/use-header-height.ts

@@ -8,10 +8,25 @@ import { useEffect, useState } from 'react'
  * Useful for offsetting fixed/absolute-positioned panels so they don't
  * overlap the header.
  */
-export function useHeaderHeight(defaultHeight = 64): number {
+export function useHeaderHeight(
+  defaultHeight = 64,
+  options: {
+    /**
+     * When false, no observers are attached and the default height is
+     * returned — for consumers that stay mounted on every page but only need
+     * the measurement while an overlay is open (avoids an always-on
+     * document-wide MutationObserver + forced reflow).
+     * @default true
+     */
+    enabled?: boolean
+  } = {}
+): number {
+  const { enabled = true } = options
   const [height, setHeight] = useState(defaultHeight)
 
   useEffect(() => {
+    if (!enabled) return
+
     const measure = () => {
       let total = 0
       const header = document.querySelector('header')
@@ -49,7 +64,7 @@ export function useHeaderHeight(defaultHeight = 64): number {
       resizeObserver.disconnect()
       mutationObserver.disconnect()
     }
-  }, [defaultHeight])
+  }, [defaultHeight, enabled])
 
   return height
 }