@ossy/app 3.2.0 → 3.3.0

package/README.md

@@ -170,6 +170,22 @@ export default function ServiceForm() { … }
 
 See [`docs/component-primitive.md`](./docs/component-primitive.md) and [design-system/docs/SLOTS.md](../design-system/docs/SLOTS.md).
 
+## Compact / mobile shell
+
+Default and workspace layouts use `@ossy/app/shell` helpers for viewports ≤900px:
+
+- `useCompactShellLayout` / `COMPACT_SHELL_MEDIA_QUERY` — match Cloud theme compact typography
+- `ShellHeaderRow` + `MobileShellNav` — menu control + overlay drawer hosting `app:sidebar` with `presentation="drawer"`
+- `OpenMobileShellNav` / `CloseMobileShellNav` action POJOs on the menu/close controls (`data-action`) for flow coverage with `{ viewport }` / `{ press: 'Escape' }` / `{ press: 'Tab' }` / `{ press: 'Shift+Tab' }`
+- Header row stays when `app:header` is unset so sidebar-only pages keep primary nav
+- Drawer traps Tab focus via a `View` panel ref (flow asserts wrap with `Shift+Tab` / `Tab`), restores the menu trigger on close, and keeps menu/close hit areas ≥44px
+- While open, `[data-ossy-app-shell]` is `inert` + `aria-hidden`; body gets `data-ossy-mobile-shell-scroll-lock`; the drawer panel respects `env(safe-area-inset-*)`
+- Compact shells pad with the same safe-area insets (not zero) so the header menu clears notches; document head uses `viewport-fit=cover`
+- Compact header chrome (language / theme / auth) uses the same ≥44px hit areas via `compactShellControlStyle`
+- Tab-trap helpers live in `mobileShellFocus.js` (`listFocusable`, `resolveTabTrapTarget`, `compactShellControlStyle`, `compactAppShellStyle`, `setAppShellBackgroundInert`, `setMobileShellScrollLock`, `mobileShellDrawerSafeAreaStyle`) with unit coverage in `__tests__/mobileShellFocus.test.js`
+
+See [SHELL-SPEC §4.5](../../docs/concepts/SHELL-SPEC.md).
+
 ## Port configuration
 
 The server listens on port **3000** by default.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/app",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "",
   "source": "./src/index.js",
   "main": "./src/index.js",
@@ -50,19 +50,19 @@
     "@babel/preset-react": "^7.26.3",
     "@babel/register": "^7.25.9",
     "@ossy/authentication": "^3.2.0",
-    "@ossy/design-system": "^3.2.0",
+    "@ossy/design-system": "^3.3.0",
     "@ossy/locale": "^3.0.9",
     "@ossy/manifest": "^3.0.9",
     "@ossy/package-catalog": "^3.0.9",
     "@ossy/pages": "^3.0.9",
-    "@ossy/platform": "^3.2.0",
-    "@ossy/resources": "^3.2.0",
+    "@ossy/platform": "^3.3.0",
+    "@ossy/resources": "^3.3.0",
     "@ossy/router": "^3.0.9",
     "@ossy/router-react": "^3.0.9",
     "@ossy/schema": "^3.0.9",
-    "@ossy/sdk": "^3.2.0",
+    "@ossy/sdk": "^3.3.0",
     "@ossy/sdk-react": "^3.0.9",
-    "@ossy/themes": "^3.2.0",
+    "@ossy/themes": "^3.3.0",
     "@ossy/workspaces": "^3.2.0",
     "@rollup/plugin-alias": "^6.0.0",
     "@rollup/plugin-babel": "^7.1.0",
@@ -97,5 +97,5 @@
     "README.md",
     "tsconfig.json"
   ],
-  "gitHead": "b045f1fd7f2fe00c776b9ea96f76083b93fd8556"
+  "gitHead": "19e8bae4c1e9df79270218f28c0c9391f4f9871c"
 }

package/runtime/document-viewport.js

@@ -0,0 +1,7 @@
+/**
+ * Document viewport for mobile / iPad (and notched devices).
+ * `viewport-fit=cover` lets `env(safe-area-inset-*)` resolve so compact shell chrome
+ * and the mobile nav drawer can clear the status bar / home indicator.
+ */
+export const DOCUMENT_VIEWPORT_CONTENT =
+  'width=device-width, initial-scale=1, viewport-fit=cover'

package/runtime/page-runtime.js

@@ -3,6 +3,9 @@ import { pageIdToDocumentTitleKey, resolveMessage } from '@ossy/locale'
 import { Slot } from '@ossy/design-system'
 import { App } from '../src/shell/App.jsx'
 import { resolvePageSlots, CONTENT_SLOT_NAME } from './resolve-app-slots.js'
+import { DOCUMENT_VIEWPORT_CONTENT } from './document-viewport.js'
+
+export { DOCUMENT_VIEWPORT_CONTENT } from './document-viewport.js'
 
 /**
  * Dynamically imports each component bundle listed in `entries` and returns a
@@ -93,6 +96,7 @@ function buildTree ({ Layout, metadata, props }) {
       'head',
       null,
       createElement('meta', { charSet: 'utf-8' }),
+      createElement('meta', { name: 'viewport', content: DOCUMENT_VIEWPORT_CONTENT }),
       createElement('title', null, resolveDocumentTitle(metadata, props)),
     ),
     createElement('body', { style: { height: '100%', margin: 0 } }, createElement(App, props, contentEl)),

package/src/en.translations.json

@@ -4,5 +4,8 @@
   "app.shell.header.languagePicker": "Language",
   "app.shell.footer.languages": "Languages",
   "app.shell.header.themeSwitch": "{theme} theme. Switch theme.",
-  "app.shell.header.profile": "Profile"
+  "app.shell.header.profile": "Profile",
+  "app.shell.header.openNav": "Open navigation",
+  "app.shell.header.closeNav": "Close navigation",
+  "app.shell.header.nav": "Primary navigation"
 }

package/src/shell/HeaderAuthActions.jsx

@@ -3,6 +3,7 @@ import { Button, useLocale } from '@ossy/design-system'
 import { useRouter } from '@ossy/router-react'
 import { OpenSignIn, OpenSignUp } from '@ossy/authentication'
 import { useApp } from './AppContext.js'
+import { compactShellControlStyle } from './mobileShellFocus.js'
 
 /**
  * Profile link when authenticated; sign-in / sign-up when not.
@@ -11,6 +12,9 @@ export function HeaderAuthActions ({ compact = false }) {
   const app = useApp()
   const router = useRouter()
   const { t } = useLocale()
+  const controlStyle = compact
+    ? compactShellControlStyle()
+    : { flexShrink: 0 }
 
   if (app?.isAuthenticated) {
     return (
@@ -19,7 +23,7 @@ export function HeaderAuthActions ({ compact = false }) {
         suffix="profile"
         href={router.getHref('@profile')}
         aria-label={t('app.shell.header.profile') || 'Profile'}
-        style={{ flexShrink: 0 }}
+        style={controlStyle}
       >
         {compact ? null : (t('app.shell.header.profile') || 'Profile')}
       </Button>
@@ -34,7 +38,7 @@ export function HeaderAuthActions ({ compact = false }) {
         href={router.getHref('@sign-in')}
         label={compact ? undefined : OpenSignIn.label}
         aria-label={t(OpenSignIn.label)}
-        style={{ flexShrink: 0 }}
+        style={controlStyle}
       />
       <Button
         variant="cta"
@@ -42,7 +46,7 @@ export function HeaderAuthActions ({ compact = false }) {
         href={router.getHref('@sign-up')}
         label={compact ? undefined : OpenSignUp.label}
         aria-label={t(OpenSignUp.label)}
-        style={{ flexShrink: 0 }}
+        style={controlStyle}
       />
     </>
   )

package/src/shell/LanguageSelect.jsx

@@ -8,14 +8,18 @@ import {
 } from '@ossy/design-system'
 import { useRouter } from '@ossy/router-react'
 import { languageCode } from './languageCode.js'
+import { compactShellControlStyle } from './mobileShellFocus.js'
 
 /**
  * Language switcher for app shell header — cycle when two locales, dropdown when more.
  */
-export function LanguageSelect () {
+export function LanguageSelect ({ compact = false }) {
   const router = useRouter()
   const { t } = useLocale()
   const { language, supportedLanguages, getHref } = router
+  const controlStyle = compact
+    ? compactShellControlStyle()
+    : { flexShrink: 0 }
 
   if (!supportedLanguages?.length || supportedLanguages.length <= 1) {
     return null
@@ -32,7 +36,7 @@ export function LanguageSelect () {
         prefix="select"
         href={getHref({ language: other })}
         aria-label={pickerLabel}
-        style={{ flexShrink: 0 }}
+        style={controlStyle}
       >
         {languageCode(language)}
       </Button>
@@ -46,7 +50,7 @@ export function LanguageSelect () {
           prefix="select"
           variant="link"
           aria-label={pickerLabel}
-          style={{ flexShrink: 0 }}
+          style={controlStyle}
         >
           {languageCode(language)}
         </Button>

package/src/shell/MobileShellNav.jsx

@@ -0,0 +1,180 @@
+import React, { useEffect, useId, useRef } from 'react'
+import { Button, Overlay, Slot, useLocale, View } from '@ossy/design-system'
+import { useRouter } from '@ossy/router-react'
+import { metadata as OpenMobileShellNav } from '../shell-registry/open-mobile-shell-nav.action.js'
+import { metadata as CloseMobileShellNav } from '../shell-registry/close-mobile-shell-nav.action.js'
+import {
+  TAB_TRAP_FALLBACK,
+  compactShellControlStyle,
+  listFocusable,
+  mobileShellDrawerSafeAreaStyle,
+  resolveTabTrapTarget,
+  setAppShellBackgroundInert,
+  setMobileShellScrollLock,
+} from './mobileShellFocus.js'
+
+/**
+ * Compact-viewport primary nav: menu control + left drawer hosting `app:sidebar`.
+ * Layouts own open state so custom header slots still get a working mobile navbar.
+ */
+export function MobileShellNav ({
+  open = false,
+  onOpenChange = () => {},
+}) {
+  const router = useRouter()
+  const { t } = useLocale()
+  const panelId = useId()
+  const triggerRef = useRef(null)
+  const closeRef = useRef(null)
+  const panelRef = useRef(null)
+  const wasOpenRef = useRef(false)
+
+  useEffect(() => {
+    onOpenChange(false)
+  }, [router.href, onOpenChange])
+
+  useEffect(() => {
+    if (!open) return undefined
+    const onKeyDown = (event) => {
+      if (event.key === 'Escape') {
+        onOpenChange(false)
+        return
+      }
+      if (event.key !== 'Tab') return
+
+      const panel = panelRef.current
+      const focusable = listFocusable(panel)
+      const next = resolveTabTrapTarget({
+        focusable,
+        activeElement: document.activeElement,
+        containsActive: Boolean(panel?.contains?.(document.activeElement)),
+        shiftKey: event.shiftKey,
+      })
+
+      if (next === TAB_TRAP_FALLBACK) {
+        event.preventDefault()
+        closeRef.current?.focus?.()
+        return
+      }
+
+      if (next) {
+        event.preventDefault()
+        next.focus?.()
+      }
+    }
+    window.addEventListener('keydown', onKeyDown)
+    return () => window.removeEventListener('keydown', onKeyDown)
+  }, [open, onOpenChange])
+
+  useEffect(() => {
+    if (!open || typeof document === 'undefined') return undefined
+    const lock = setMobileShellScrollLock(document, true)
+    setAppShellBackgroundInert(document, true)
+    return () => {
+      setMobileShellScrollLock(document, false, {
+        previousOverflow: lock?.previousOverflow ?? '',
+      })
+      setAppShellBackgroundInert(document, false)
+    }
+  }, [open])
+
+  // Move focus into the drawer on open; restore it to the menu control on close.
+  useEffect(() => {
+    if (open) {
+      wasOpenRef.current = true
+      closeRef.current?.focus?.()
+      return undefined
+    }
+    if (wasOpenRef.current) {
+      wasOpenRef.current = false
+      // Shell inert is cleared in the scroll-lock effect cleanup before this runs.
+      triggerRef.current?.focus?.()
+    }
+    return undefined
+  }, [open])
+
+  const openLabel = t('app.shell.header.openNav') || 'Open navigation'
+  const closeLabel = t('app.shell.header.closeNav') || 'Close navigation'
+  const navLabel = t('app.shell.header.nav') || 'Primary navigation'
+  const touchTargetStyle = compactShellControlStyle()
+
+  return (
+    <>
+      <Button
+        {...OpenMobileShellNav}
+        ref={triggerRef}
+        type="button"
+        variant="link"
+        label={undefined}
+        prefix={OpenMobileShellNav.prefix ?? 'menu'}
+        aria-label={open ? closeLabel : openLabel}
+        aria-expanded={open}
+        aria-haspopup="dialog"
+        aria-controls={panelId}
+        data-ossy-mobile-shell-nav-trigger
+        onClick={() => onOpenChange(!open)}
+        style={touchTargetStyle}
+      />
+      <Overlay
+        isVisible={open}
+        onClose={() => onOpenChange(false)}
+        data-ossy-mobile-shell-nav-overlay
+      >
+        <View
+          ref={panelRef}
+          id={panelId}
+          role="dialog"
+          aria-modal="true"
+          aria-label={navLabel}
+          data-ossy-mobile-shell-nav
+          surface="primary"
+          style={mobileShellDrawerSafeAreaStyle({
+            position: 'absolute',
+            top: 0,
+            left: 0,
+            bottom: 0,
+            width: 'min(20rem, 86vw)',
+            maxWidth: '100%',
+            height: '100%',
+            boxSizing: 'border-box',
+            overflow: 'auto',
+            boxShadow: '4px 0 24px color-mix(in srgb, var(--text-default-color, #000) 22%, transparent)',
+            display: 'flex',
+            flexDirection: 'column',
+            // Theme primary is glass; over Overlay's dark scrim it reads as a muddy top bar.
+            // Use solid color.primary so drawer chrome stays opaque and readable.
+            background: 'var(--color-primary)',
+            backdropFilter: 'none',
+            WebkitBackdropFilter: 'none',
+          })}
+        >
+          <View
+            layout="row"
+            style={{
+              justifyContent: 'flex-end',
+              alignItems: 'center',
+              flexShrink: 0,
+              padding: 'var(--space-s)',
+            }}
+          >
+            <Button
+              {...CloseMobileShellNav}
+              ref={closeRef}
+              type="button"
+              variant="link"
+              label={undefined}
+              prefix={CloseMobileShellNav.prefix ?? 'close'}
+              aria-label={closeLabel}
+              data-ossy-mobile-shell-nav-close
+              onClick={() => onOpenChange(false)}
+              style={touchTargetStyle}
+            />
+          </View>
+          <View style={{ flex: '1 1 auto', minHeight: 0, overflow: 'auto' }}>
+            <Slot view="app:sidebar" presentation="drawer" />
+          </View>
+        </View>
+      </Overlay>
+    </>
+  )
+}

package/src/shell/ShellHeaderRow.jsx

@@ -0,0 +1,49 @@
+import React from 'react'
+import { View, Slot } from '@ossy/design-system'
+import { MobileShellNav } from './MobileShellNav.jsx'
+import {
+  shouldShowMobileShellNav,
+  shouldShowShellHeaderRow,
+} from './shellChrome.js'
+
+/**
+ * Shared header chrome for default/workspace layouts.
+ * Owns the compact mobile navbar so custom `app:header` slots still get a menu.
+ */
+export function ShellHeaderRow ({
+  compact = false,
+  showSidebar = false,
+  showHeader = false,
+  mobileNavOpen = false,
+  onMobileNavOpenChange = () => {},
+}) {
+  if (!shouldShowShellHeaderRow({ compact, showSidebar, showHeader })) {
+    return null
+  }
+
+  const showMobileNav = shouldShowMobileShellNav({ compact, showSidebar })
+
+  return (
+    <View
+      data-region="header"
+      layout="row"
+      style={{
+        alignItems: 'center',
+        gap: compact ? 'var(--space-xs)' : 'var(--space-s)',
+        minWidth: 0,
+      }}
+    >
+      {showMobileNav && (
+        <MobileShellNav
+          open={mobileNavOpen}
+          onOpenChange={onMobileNavOpenChange}
+        />
+      )}
+      {showHeader && (
+        <View style={{ flex: '1 1 auto', minWidth: 0 }}>
+          <Slot view="app:header" />
+        </View>
+      )}
+    </View>
+  )
+}

package/src/shell/ThemeSelect.jsx

@@ -8,6 +8,7 @@ import {
   useTheme,
 } from '@ossy/design-system'
 import { patchUserAppSettings } from './patchUserAppSettings.js'
+import { compactShellControlStyle } from './mobileShellFocus.js'
 
 const THEME_ICON_BY_NAME = {
   light: 'sun',
@@ -36,6 +37,9 @@ function themeIcon (name) {
 export function ThemeSelect ({ compact = false }) {
   const { themes, activeTheme, setTheme } = useTheme()
   const { t } = useLocale()
+  const controlStyle = compact
+    ? compactShellControlStyle()
+    : { flexShrink: 0 }
 
   const saveTheme = useCallback((themeName) => {
     setTheme(themeName)
@@ -63,7 +67,7 @@ export function ThemeSelect ({ compact = false }) {
         prefix={themeIcon(activeTheme)}
         onClick={cycleTheme}
         aria-label={ariaLabel}
-        style={{ flexShrink: 0 }}
+        style={controlStyle}
       >
         {compact ? null : activeLabel}
       </Button>
@@ -77,7 +81,7 @@ export function ThemeSelect ({ compact = false }) {
           prefix={compact ? themeIcon(activeTheme) : 'select'}
           variant="link"
           aria-label={ariaLabel}
-          style={{ flexShrink: 0 }}
+          style={controlStyle}
         >
           {compact ? null : activeLabel}
         </Button>

package/src/shell/index.js

@@ -7,7 +7,33 @@ export { useShellWorkspace } from './useShellWorkspace.js'
 export { WorkspaceAppSettingsSync } from './WorkspaceAppSettingsSync.jsx'
 export { resolveEndpoints } from './resolveEndpoints.js'
 export { resolveWorkspaceServices } from './resolveWorkspaceServices.js'
-export { useCompactShellLayout } from './useCompactShellLayout.js'
+export {
+  useCompactShellLayout,
+  COMPACT_SHELL_MEDIA_QUERY,
+} from './useCompactShellLayout.js'
+export {
+  shouldShowMobileShellNav,
+  shouldShowShellHeaderRow,
+} from './shellChrome.js'
+export {
+  isDrawerPresentation,
+  resolveSidebarBorderRadius,
+  resolveSidebarSmall,
+  shouldShowSidebarCollapseControl,
+} from './sidebarChrome.js'
+export { MobileShellNav } from './MobileShellNav.jsx'
+export { ShellHeaderRow } from './ShellHeaderRow.jsx'
+export {
+  compactAppShellStyle,
+  mobileShellSafeAreaStyle,
+  mobileShellDrawerSafeAreaStyle,
+  compactShellControlStyle,
+  setAppShellBackgroundInert,
+  setMobileShellScrollLock,
+  MOBILE_SHELL_SCROLL_LOCK_ATTR,
+} from './mobileShellFocus.js'
+export { metadata as OpenMobileShellNav } from '../shell-registry/open-mobile-shell-nav.action.js'
+export { metadata as CloseMobileShellNav } from '../shell-registry/close-mobile-shell-nav.action.js'
 export { buildSidebarNav } from './buildSidebarNav.js'
 export { resolvePackageHomePageId } from './resolvePackageHomePageId.js'
 export { shellSlotUnset, shellSlotViewId, coerceShellSlotSpec } from '../../runtime/merge-shell-slots.js'

package/src/shell/mobileShellFocus.js

@@ -0,0 +1,196 @@
+/** Minimum touch target for compact menu / close controls (WCAG 2.5.5). */
+export const MOBILE_SHELL_TOUCH_TARGET_PX = 44
+
+/** Selector for the layout shell that sits behind the mobile nav drawer portal. */
+export const APP_SHELL_SELECTOR = '[data-ossy-app-shell]'
+
+/** Body attribute while the compact drawer locks document scroll (flow hook). */
+export const MOBILE_SHELL_SCROLL_LOCK_ATTR = 'data-ossy-mobile-shell-scroll-lock'
+
+/**
+ * Notches / home-indicator insets via `env(safe-area-inset-*)`.
+ * Requires document viewport `viewport-fit=cover` (see `DOCUMENT_VIEWPORT_CONTENT`).
+ *
+ * @param {Record<string, unknown>} [extra]
+ * @returns {Record<string, unknown>}
+ */
+export function mobileShellSafeAreaStyle (extra = {}) {
+  return {
+    paddingTop: 'env(safe-area-inset-top, 0px)',
+    paddingRight: 'env(safe-area-inset-right, 0px)',
+    paddingBottom: 'env(safe-area-inset-bottom, 0px)',
+    paddingLeft: 'env(safe-area-inset-left, 0px)',
+    ...extra,
+  }
+}
+
+/**
+ * Notches / home-indicator insets for the compact nav drawer panel.
+ * Applied on the dialog root so close + sidebar content clear the safe area.
+ *
+ * @param {Record<string, unknown>} [extra]
+ * @returns {Record<string, unknown>}
+ */
+export function mobileShellDrawerSafeAreaStyle (extra = {}) {
+  return mobileShellSafeAreaStyle(extra)
+}
+
+/**
+ * Outer padding for compact default/workspace shells (edge-to-edge except safe area).
+ * Desktop shells keep `var(--space-m)`; compact uses safe-area insets only.
+ *
+ * @param {Record<string, unknown>} [extra]
+ * @returns {Record<string, unknown>}
+ */
+export function compactAppShellStyle (extra = {}) {
+  return mobileShellSafeAreaStyle({
+    boxSizing: 'border-box',
+    height: '100%',
+    minWidth: 0,
+    ...extra,
+  })
+}
+
+/**
+ * Inline style for compact shell icon/link controls (menu, close, header chrome).
+ * Keeps hit areas ≥ {@link MOBILE_SHELL_TOUCH_TARGET_PX}.
+ *
+ * @param {Record<string, unknown>} [extra]
+ * @returns {Record<string, unknown>}
+ */
+export function compactShellControlStyle (extra = {}) {
+  return {
+    flexShrink: 0,
+    minWidth: MOBILE_SHELL_TOUCH_TARGET_PX,
+    minHeight: MOBILE_SHELL_TOUCH_TARGET_PX,
+    boxSizing: 'border-box',
+    ...extra,
+  }
+}
+
+/**
+ * Mark (or clear) the app shell behind an open mobile drawer so AT / Tab ignore it.
+ * The drawer itself is portaled outside the shell (`Overlay`), so inert + aria-hidden
+ * on `[data-ossy-app-shell]` does not hide the dialog.
+ *
+ * @param {ParentNode | null | undefined} root Document or test container
+ * @param {boolean} enabled
+ * @returns {Element | null} The shell element when found
+ */
+export function setAppShellBackgroundInert (root, enabled) {
+  const shell = root?.querySelector?.(APP_SHELL_SELECTOR) ?? null
+  if (!shell) return null
+
+  if (enabled) {
+    shell.setAttribute('aria-hidden', 'true')
+    if ('inert' in shell) {
+      shell.inert = true
+    } else {
+      shell.setAttribute('inert', '')
+    }
+  } else {
+    shell.removeAttribute('aria-hidden')
+    if ('inert' in shell) {
+      shell.inert = false
+    }
+    shell.removeAttribute('inert')
+  }
+
+  return shell
+}
+
+/**
+ * Lock (or restore) document body scroll while the compact mobile drawer is open.
+ * Sets {@link MOBILE_SHELL_SCROLL_LOCK_ATTR} so flows can assert scroll-lock without
+ * reading computed styles.
+ *
+ * @param {Document | { body?: HTMLElement | null } | null | undefined} doc
+ * @param {boolean} enabled
+ * @param {{ previousOverflow?: string }} [opts] Pass the overflow returned when enabling
+ *   so cleanup restores the prior inline value.
+ * @returns {{ body: HTMLElement, previousOverflow: string } | null}
+ */
+export function setMobileShellScrollLock (doc, enabled, opts = {}) {
+  const body = doc?.body ?? null
+  if (!body) return null
+
+  if (enabled) {
+    const previousOverflow = body.style?.overflow ?? ''
+    if (body.style) body.style.overflow = 'hidden'
+    body.setAttribute?.(MOBILE_SHELL_SCROLL_LOCK_ATTR, '')
+    return { body, previousOverflow }
+  }
+
+  if (body.style) {
+    body.style.overflow = opts.previousOverflow ?? ''
+  }
+  body.removeAttribute?.(MOBILE_SHELL_SCROLL_LOCK_ATTR)
+  return { body, previousOverflow: opts.previousOverflow ?? '' }
+}
+
+export const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'button:not([disabled])',
+  'input:not([disabled]):not([type="hidden"])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+].join(',')
+
+/** Sentinel: trap has no focusable nodes; caller should focus its fallback control. */
+export const TAB_TRAP_FALLBACK = Object.freeze({ fallback: true })
+
+/**
+ * List Tab-reachable elements inside a drawer root.
+ * Skips `aria-hidden` nodes and elements that are not visible.
+ *
+ * @param {{ querySelectorAll?: Function } | null | undefined} root
+ * @returns {Element[]}
+ */
+export function listFocusable (root) {
+  if (!root?.querySelectorAll) return []
+  return [...root.querySelectorAll(FOCUSABLE_SELECTOR)].filter((el) => {
+    if (el.getAttribute?.('aria-hidden') === 'true') return false
+    if (typeof el.checkVisibility === 'function') {
+      return el.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true })
+    }
+    const active = typeof document !== 'undefined' ? document.activeElement : null
+    return el.offsetParent !== null || el === active
+  })
+}
+
+/**
+ * Resolve the next focus target for Tab / Shift+Tab inside an open drawer.
+ *
+ * @param {{
+ *   focusable: unknown[],
+ *   activeElement: unknown,
+ *   containsActive: boolean,
+ *   shiftKey: boolean,
+ * }} opts
+ * @returns {null | typeof TAB_TRAP_FALLBACK | unknown}
+ *   - `TAB_TRAP_FALLBACK` when there are no focusable nodes
+ *   - an element to focus (and preventDefault) when wrapping
+ *   - `null` to leave default Tab behavior alone
+ */
+export function resolveTabTrapTarget ({
+  focusable,
+  activeElement,
+  containsActive,
+  shiftKey,
+}) {
+  if (!Array.isArray(focusable) || focusable.length === 0) {
+    return TAB_TRAP_FALLBACK
+  }
+
+  const first = focusable[0]
+  const last = focusable[focusable.length - 1]
+
+  if (shiftKey) {
+    if (!containsActive || activeElement === first) return last
+    return null
+  }
+
+  if (!containsActive || activeElement === last) return first
+  return null
+}

package/src/shell/shellChrome.js

@@ -0,0 +1,24 @@
+/** Matches Cloud theme compact typography (`theme.media['(max-width: 900px)']`). */
+export const COMPACT_SHELL_MEDIA_QUERY = '(max-width: 900px)'
+
+/**
+ * Whether layouts should render the header row on the current viewport.
+ * Compact chrome hides the in-grid sidebar, so a menu control must remain
+ * reachable even when the `app:header` slot is intentionally unset.
+ *
+ * @param {{ compact: boolean, showSidebar: boolean, showHeader: boolean }} opts
+ * @returns {boolean}
+ */
+export function shouldShowShellHeaderRow ({ compact, showSidebar, showHeader }) {
+  return Boolean(showHeader || (compact && showSidebar))
+}
+
+/**
+ * Whether the mobile navbar (menu + drawer) should render.
+ *
+ * @param {{ compact: boolean, showSidebar: boolean }} opts
+ * @returns {boolean}
+ */
+export function shouldShowMobileShellNav ({ compact, showSidebar }) {
+  return Boolean(compact && showSidebar)
+}

package/src/shell/sidebarChrome.js

@@ -0,0 +1,60 @@
+/**
+ * Pure chrome rules for default / primary sidebars when hosted in-grid vs
+ * inside the compact mobile nav drawer (`presentation="drawer"`).
+ */
+
+/**
+ * @param {unknown} presentation
+ * @returns {boolean}
+ */
+export function isDrawerPresentation (presentation) {
+  return presentation === 'drawer'
+}
+
+/**
+ * Drawer chrome must stay expanded (labeled); otherwise honor compact /
+ * collapsed / explicit `small`.
+ *
+ * @param {{
+ *   presentation?: unknown,
+ *   compactViewport?: boolean,
+ *   sidebarCollapsed?: boolean,
+ *   smallProp?: boolean,
+ * }} opts
+ * @returns {boolean}
+ */
+export function resolveSidebarSmall ({
+  presentation,
+  compactViewport = false,
+  sidebarCollapsed = false,
+  smallProp = false,
+}) {
+  if (isDrawerPresentation(presentation)) return false
+  return Boolean(compactViewport || sidebarCollapsed || smallProp)
+}
+
+/**
+ * Collapse control is desktop in-grid only — never in the mobile drawer or
+ * on compact viewports (drawer owns open/close).
+ *
+ * @param {{ presentation?: unknown, compactViewport?: boolean }} opts
+ * @returns {boolean}
+ */
+export function shouldShowSidebarCollapseControl ({
+  presentation,
+  compactViewport = false,
+}) {
+  return !isDrawerPresentation(presentation) && !compactViewport
+}
+
+/**
+ * Square panel in the drawer; rounded rail when in-grid.
+ *
+ * @param {unknown} presentation
+ * @returns {0 | string}
+ */
+export function resolveSidebarBorderRadius (presentation) {
+  return isDrawerPresentation(presentation)
+    ? 0
+    : 'var(--space-l) var(--space-s) var(--space-s) var(--space-l)'
+}

package/src/shell/useCompactShellLayout.js

@@ -1,18 +1,18 @@
 import { useSyncExternalStore } from 'react'
+import { COMPACT_SHELL_MEDIA_QUERY } from './shellChrome.js'
 
-/** Viewports at or below this width use compact chrome (icon rail, tighter padding). */
-const COMPACT_MEDIA_QUERY = '(max-width: 900px)'
+export { COMPACT_SHELL_MEDIA_QUERY }
 
 function subscribe (onStoreChange) {
   if (typeof window === 'undefined') return () => {}
-  const mq = window.matchMedia(COMPACT_MEDIA_QUERY)
+  const mq = window.matchMedia(COMPACT_SHELL_MEDIA_QUERY)
   mq.addEventListener('change', onStoreChange)
   return () => mq.removeEventListener('change', onStoreChange)
 }
 
 function getSnapshot () {
   if (typeof window === 'undefined') return false
-  return window.matchMedia(COMPACT_MEDIA_QUERY).matches
+  return window.matchMedia(COMPACT_SHELL_MEDIA_QUERY).matches
 }
 
 function getServerSnapshot () {

package/src/shell-registry/close-mobile-shell-nav.action.js

@@ -0,0 +1,6 @@
+export const metadata = {
+  id: '@ossy/app/actions/close-mobile-shell-nav',
+  access: 'public',
+  prefix: 'close',
+  label: 'app.shell.header.closeNav',
+}

package/src/shell-registry/default.layout.jsx

@@ -1,10 +1,15 @@
-import React from 'react'
+import React, { useEffect, useState } from 'react'
 import {
   PageSection,
   View,
   Slot,
 } from '@ossy/design-system'
-import { useCompactShellLayout, shellSlotUnset } from '@ossy/app/shell'
+import {
+  useCompactShellLayout,
+  shellSlotUnset,
+  ShellHeaderRow,
+  compactAppShellStyle,
+} from '@ossy/app/shell'
 
 export const metadata = { id: '@ossy/app/layout/default' }
 
@@ -20,6 +25,13 @@ export default function DefaultLayout ({
   maxWidth = 'xl',
 }) {
   const compact = useCompactShellLayout()
+  const [mobileNavOpen, setMobileNavOpen] = useState(false)
+  const showSidebar = !shellSlotUnset(shellSlots['app:sidebar'])
+  const showHeader = !shellSlotUnset(shellSlots['app:header'])
+
+  useEffect(() => {
+    if (!compact) setMobileNavOpen(false)
+  }, [compact])
 
   return (
     <>
@@ -27,12 +39,14 @@ export default function DefaultLayout ({
       <View
         surface="base"
         data-ossy-app-shell
-        style={{
-          boxSizing: 'border-box',
-          height: '100%',
-          minWidth: 0,
-          padding: compact ? 0 : 'var(--space-m)',
-        }}
+        style={compact
+          ? compactAppShellStyle()
+          : {
+              boxSizing: 'border-box',
+              height: '100%',
+              minWidth: 0,
+              padding: 'var(--space-m)',
+            }}
       >
         <PageSection
           maxWidth={maxWidth}
@@ -55,13 +69,17 @@ export default function DefaultLayout ({
               ...(compact ? { gap: '4px' } : {}),
             }}
           >
-            {!shellSlotUnset(shellSlots['app:sidebar']) && (
+            {showSidebar && !compact && (
               <Slot region="sidebar-primary" view="app:sidebar" />
             )}
 
-            {!shellSlotUnset(shellSlots['app:header']) && (
-              <Slot region="header" view="app:header" />
-            )}
+            <ShellHeaderRow
+              compact={compact}
+              showSidebar={showSidebar}
+              showHeader={showHeader}
+              mobileNavOpen={mobileNavOpen}
+              onMobileNavOpenChange={setMobileNavOpen}
+            />
 
             <View
               data-region="content"

package/src/shell-registry/header-default.component.jsx

@@ -40,7 +40,7 @@ export default function DefaultHeader ({
             gap: compact ? 'var(--space-xs)' : 'var(--space-s)',
           }}
         >
-          <LanguageSelect />
+          <LanguageSelect compact={compact} />
           <ThemeSelect compact={compact} />
           <HeaderAuthActions compact={compact} />
         </View>

package/src/shell-registry/open-mobile-shell-nav.action.js

@@ -0,0 +1,6 @@
+export const metadata = {
+  id: '@ossy/app/actions/open-mobile-shell-nav',
+  access: 'public',
+  prefix: 'menu',
+  label: 'app.shell.header.openNav',
+}

package/src/shell-registry/sidebar-default.component.jsx

@@ -2,6 +2,12 @@ import React, { useState, useMemo, useRef, useEffect, useCallback } from 'react'
 import { Button, View, Slot, useLocale } from '@ossy/design-system'
 import { useRouter } from '@ossy/router-react'
 import { useApp, buildSidebarNav, patchUserAppSettings, useCompactShellLayout, useShellWorkspace } from '@ossy/app/shell'
+import {
+  isDrawerPresentation,
+  resolveSidebarBorderRadius,
+  resolveSidebarSmall,
+  shouldShowSidebarCollapseControl,
+} from '../shell/sidebarChrome.js'
 
 export const metadata = { id: '@ossy/app/component/sidebar/default' }
 
@@ -47,6 +53,7 @@ function navLabelForItem (item, showLabels, t) {
 
 export default function DefaultSidebar ({
   small: smallProp = false,
+  presentation,
   ...rest
 }) {
   const [hoverRailExpanded, setHoverRailExpanded] = useState(false)
@@ -56,6 +63,7 @@ export default function DefaultSidebar ({
   const compactViewport = useCompactShellLayout()
   const initialSidebarCollapsed = app?.sidebarPrimaryCollapsed === true
   const [sidebarCollapsed, setSidebarCollapsed] = useState(initialSidebarCollapsed)
+  const isDrawer = isDrawerPresentation(presentation)
 
   const onToggleCollapsed = useCallback(() => {
     setSidebarCollapsed((collapsed) => {
@@ -65,16 +73,25 @@ export default function DefaultSidebar ({
     })
   }, [])
 
-  const small = compactViewport || sidebarCollapsed || smallProp
+  const small = resolveSidebarSmall({
+    presentation,
+    compactViewport,
+    sidebarCollapsed,
+    smallProp,
+  })
   const { workspace } = useShellWorkspace()
   const router = useRouter()
   const { t } = useLocale()
 
-  const desktopHoverRail = small && !compactViewport
+  const desktopHoverRail = small && !compactViewport && !isDrawer
   const showLabels = !small || (desktopHoverRail && hoverRailExpanded)
   const iconOnly = !showLabels
   const hoverExpandedDesktop = desktopHoverRail && hoverRailExpanded
   const narrowChrome = small
+  const showCollapseControl = shouldShowSidebarCollapseControl({
+    presentation,
+    compactViewport,
+  })
 
   const { shellItems, packageItems } = useMemo(
     () => buildSidebarNav({
@@ -186,6 +203,7 @@ export default function DefaultSidebar ({
       prefix={item.prefix}
       title={item.title}
       aria-current={item.selected ? 'page' : undefined}
+      data-ossy-sidebar-nav-item={item.key ?? item.href}
       style={{
         justifyContent: iconOnly ? 'center' : 'flex-start',
         padding: hoverExpandedDesktop ? '8px 24px' : (narrowChrome ? 'var(--space-s)' : '8px 24px'),
@@ -200,17 +218,18 @@ export default function DefaultSidebar ({
       {...(!desktopHoverRail ? rest : {})}
       surface="primary"
       gap={narrowChrome ? 's' : 'm'}
+      data-ossy-sidebar-presentation={isDrawer ? 'drawer' : undefined}
       style={{
         height: '100%',
-        width: desktopHoverRail ? '100%' : 'auto',
+        width: isDrawer || desktopHoverRail ? '100%' : 'auto',
         minWidth: small ? 0 : undefined,
-        maxHeight: small ? '100%' : undefined,
+        maxHeight: small || isDrawer ? '100%' : undefined,
         padding: hoverExpandedDesktop
           ? 'var(--space-m) var(--space-l) var(--space-m) var(--space-m)'
           : narrowChrome
           ? 'var(--space-s) var(--space-xs)'
           : 'var(--space-m) var(--space-l) var(--space-m) var(--space-m)',
-        borderRadius: 'var(--space-l) var(--space-s) var(--space-s) var(--space-l)',
+        borderRadius: resolveSidebarBorderRadius(presentation),
         flexShrink: 0,
         boxSizing: 'border-box',
       }}
@@ -233,7 +252,7 @@ export default function DefaultSidebar ({
         {menuNear.map(renderButton)}
       </View>
 
-      {onToggleCollapsed && !compactViewport && (
+      {onToggleCollapsed && showCollapseControl && (
         <View style={{ flexShrink: 0, marginTop: 'var(--space-s)' }}>
           <Button
             variant="link"

package/src/shell-registry/workspace.layout.jsx

@@ -1,10 +1,15 @@
-import React from 'react'
+import React, { useEffect, useState } from 'react'
 import {
   PageSection,
   View,
   Slot,
 } from '@ossy/design-system'
-import { useCompactShellLayout, shellSlotUnset } from '@ossy/app/shell'
+import {
+  useCompactShellLayout,
+  shellSlotUnset,
+  ShellHeaderRow,
+  compactAppShellStyle,
+} from '@ossy/app/shell'
 
 export const metadata = { id: '@ossy/app/layout/workspace' }
 
@@ -23,6 +28,13 @@ export default function WorkspaceLayout ({
   maxWidth = 'xl',
 }) {
   const compact = useCompactShellLayout()
+  const [mobileNavOpen, setMobileNavOpen] = useState(false)
+  const showSidebar = !shellSlotUnset(shellSlots['app:sidebar'])
+  const showHeader = !shellSlotUnset(shellSlots['app:header'])
+
+  useEffect(() => {
+    if (!compact) setMobileNavOpen(false)
+  }, [compact])
 
   return (
     <>
@@ -30,12 +42,14 @@ export default function WorkspaceLayout ({
       <View
         surface="base"
         data-ossy-app-shell
-        style={{
-          boxSizing: 'border-box',
-          height: '100%',
-          minWidth: 0,
-          padding: compact ? 0 : 'var(--space-m)',
-        }}
+        style={compact
+          ? compactAppShellStyle()
+          : {
+              boxSizing: 'border-box',
+              height: '100%',
+              minWidth: 0,
+              padding: 'var(--space-m)',
+            }}
       >
         <PageSection
           maxWidth={maxWidth}
@@ -58,13 +72,17 @@ export default function WorkspaceLayout ({
               ...(compact ? { gap: '4px' } : {}),
             }}
           >
-            {!shellSlotUnset(shellSlots['app:sidebar']) && (
+            {showSidebar && !compact && (
               <Slot region="sidebar-primary" view="app:sidebar" />
             )}
 
-            {!shellSlotUnset(shellSlots['app:header']) && (
-              <Slot region="header" view="app:header" />
-            )}
+            <ShellHeaderRow
+              compact={compact}
+              showSidebar={showSidebar}
+              showHeader={showHeader}
+              mobileNavOpen={mobileNavOpen}
+              onMobileNavOpenChange={setMobileNavOpen}
+            />
 
             <View
               data-region="content"

package/src/sv.translations.json

@@ -4,5 +4,8 @@
   "app.shell.header.languagePicker": "Språk",
   "app.shell.footer.languages": "Språk",
   "app.shell.header.themeSwitch": "{theme}-tema. Byt tema.",
-  "app.shell.header.profile": "Profil"
+  "app.shell.header.profile": "Profil",
+  "app.shell.header.openNav": "Öppna navigation",
+  "app.shell.header.closeNav": "Stäng navigation",
+  "app.shell.header.nav": "Huvudnavigation"
 }