@djangocfg/layouts 2.1.608 → 2.1.610

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.1.608",
+  "version": "2.1.610",
   "description": "Simple, straightforward layout components for Next.js - import and use with props",
   "keywords": [
     "layouts",
@@ -91,11 +91,11 @@
     "test": "vitest run"
   },
   "peerDependencies": {
-    "@djangocfg/analytics": "^2.1.608",
-    "@djangocfg/api": "^2.1.608",
-    "@djangocfg/devtools": "^2.1.608",
-    "@djangocfg/i18n": "^2.1.608",
-    "@djangocfg/ui-core": "^2.1.608",
+    "@djangocfg/analytics": "^2.1.610",
+    "@djangocfg/api": "^2.1.610",
+    "@djangocfg/devtools": "^2.1.610",
+    "@djangocfg/i18n": "^2.1.610",
+    "@djangocfg/ui-core": "^2.1.610",
     "@hookform/resolvers": "^5.2.2",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
@@ -125,12 +125,12 @@
     "uuid": "^11.1.1"
   },
   "devDependencies": {
-    "@djangocfg/analytics": "^2.1.608",
-    "@djangocfg/api": "^2.1.608",
-    "@djangocfg/devtools": "^2.1.608",
-    "@djangocfg/i18n": "^2.1.608",
-    "@djangocfg/typescript-config": "^2.1.608",
-    "@djangocfg/ui-core": "^2.1.608",
+    "@djangocfg/analytics": "^2.1.610",
+    "@djangocfg/api": "^2.1.610",
+    "@djangocfg/devtools": "^2.1.610",
+    "@djangocfg/i18n": "^2.1.610",
+    "@djangocfg/typescript-config": "^2.1.610",
+    "@djangocfg/ui-core": "^2.1.610",
     "@storybook/react-vite": "^10.5.0",
     "@types/node": "^25.9.5",
     "@types/react": "19.2.15",

package/src/layouts/AppLayout/BaseApp.tsx

@@ -62,6 +62,7 @@ import { AuthDialog } from '../../snippets/AuthDialog';
 import type { BaseLayoutProps } from '../types/layout.types';
 import { LayoutI18nProvider } from '../../shared/LayoutI18nProvider';
 import { ProjectNameProvider } from '../../shared/ProjectContext';
+import { PwaMetaGuard } from './pwaMeta';
 
 import React from 'react';
 
@@ -105,6 +106,7 @@ export function BaseApp({
   swr,
   devtools: devtoolsConfig,
   i18n,
+  pwaMeta = true,
 }: BaseAppProps) {
   // auth=false disables AuthProvider entirely (public apps with no login)
   const authEnabled = auth !== false;
@@ -122,6 +124,8 @@ export function BaseApp({
   };
 
   const content = (
+    <>
+    {pwaMeta && <PwaMetaGuard />}
     <ThemeProvider
       defaultTheme={theme?.defaultTheme || 'system'}
       storageKey={theme?.storageKey}
@@ -192,6 +196,7 @@ export function BaseApp({
       </NextLinkProvider>
       </NextRouterAdapter>
     </ThemeProvider>
+    </>
   );
 
   // The error boundary is now UiProviders' built-in one (fed our i18n fallback

package/src/layouts/AppLayout/pwaMeta.test.ts

@@ -0,0 +1,36 @@
+// @vitest-environment jsdom
+import { beforeEach, describe, expect, it } from 'vitest';
+
+import { PWA_META_SCRIPT } from './pwaMeta';
+
+const meta = (n: string) => document.head.querySelector(`meta[name="${n}"]`)?.getAttribute('content');
+const run = () => new Function(PWA_META_SCRIPT)();
+
+describe('PWA_META_SCRIPT', () => {
+  beforeEach(() => {
+    document.head.innerHTML = '';
+  });
+
+  it('adds viewport-fit=cover to an existing viewport and the iOS app tags', () => {
+    document.head.innerHTML = '<meta name="viewport" content="width=device-width, initial-scale=1">';
+    run();
+    expect(meta('viewport')).toBe('width=device-width, initial-scale=1, viewport-fit=cover');
+    expect(meta('apple-mobile-web-app-capable')).toBe('yes');
+    expect(meta('mobile-web-app-capable')).toBe('yes');
+    expect(meta('apple-mobile-web-app-status-bar-style')).toBe('black-translucent');
+  });
+
+  it('creates a viewport when none exists', () => {
+    run();
+    expect(meta('viewport')).toContain('viewport-fit=cover');
+  });
+
+  it('never overrides what the app set', () => {
+    document.head.innerHTML =
+      '<meta name="viewport" content="width=device-width, viewport-fit=contain">' +
+      '<meta name="apple-mobile-web-app-status-bar-style" content="default">';
+    run();
+    expect(meta('viewport')).toBe('width=device-width, viewport-fit=contain');
+    expect(meta('apple-mobile-web-app-status-bar-style')).toBe('default');
+  });
+});

package/src/layouts/AppLayout/pwaMeta.tsx

@@ -0,0 +1,40 @@
+/**
+ * Installed-app `<meta>` tags, applied by `BaseApp` so an app does not have to remember them.
+ *
+ * Next's App Router builds `<head>` from the server `viewport` / `metadata` exports; a client component such as
+ * `BaseApp` cannot contribute to them, and a second `<meta name="viewport">` would fight Next's own. So this is a tiny
+ * inline script (it runs while the HTML is parsed, before first paint) that completes what is missing in `<head>`:
+ *
+ *   viewport                              + `viewport-fit=cover` (without it every `--safe-*` inset is 0 and the
+ *                                           installed iOS app letterboxes)
+ *   apple-mobile-web-app-capable          yes   (Next 16 only emits `mobile-web-app-capable`; iOS < 26 needs the apple tag)
+ *   mobile-web-app-capable                yes
+ *   apple-mobile-web-app-status-bar-style black-translucent
+ *
+ * Existing tags are never overridden (an app's own `appleWebApp.statusBarStyle` wins); only `viewport-fit` is added to
+ * an existing viewport that lacks it. A MutationObserver re-applies it if a client navigation rewrites the viewport tag.
+ * Prefer exporting `viewport = createViewport(...)` (default `viewportFit: 'cover'`): that puts it in the server HTML;
+ * this is the safety net for apps that forgot.
+ */
+
+import * as React from 'react';
+
+export const PWA_META_SCRIPT = `(function(){try{
+var d=document,h=d.head;if(!h)return;
+function q(n){return h.querySelector('meta[name="'+n+'"]')}
+function ensure(n,c){if(!q(n)){var m=d.createElement('meta');m.name=n;m.content=c;h.appendChild(m)}}
+function fit(){var v=q('viewport');
+if(!v){v=d.createElement('meta');v.name='viewport';v.content='width=device-width, initial-scale=1, viewport-fit=cover';h.appendChild(v);return}
+var c=v.getAttribute('content')||'';
+if(!/viewport-fit\\s*=/.test(c))v.setAttribute('content',(c?c+', ':'')+'viewport-fit=cover')}
+fit();
+ensure('apple-mobile-web-app-capable','yes');
+ensure('mobile-web-app-capable','yes');
+ensure('apple-mobile-web-app-status-bar-style','black-translucent');
+if(window.MutationObserver){new MutationObserver(function(){var v=q('viewport');if(!v||!/viewport-fit\\s*=\\s*cover/.test(v.getAttribute('content')||''))fit()}).observe(h,{subtree:true,childList:true,attributes:true,attributeFilter:['content']})}
+}catch(e){}})();`;
+
+/** Renders the inline script. Server-rendered into the HTML; React does not re-run it on hydration. */
+export function PwaMetaGuard() {
+  return <script dangerouslySetInnerHTML={{ __html: PWA_META_SCRIPT }} suppressHydrationWarning />;
+}

package/src/layouts/PrivateLayout/components/ForbiddenState.tsx

@@ -36,7 +36,7 @@ export function ForbiddenState({
   return (
     <div
       role="alert"
-      className="flex min-h-svh flex-col items-center justify-center gap-4 p-6 text-center"
+      className="flex min-h-[var(--app-height,100svh)] flex-col items-center justify-center gap-4 p-6 text-center"
     >
       <div className="flex size-12 items-center justify-center rounded-full bg-destructive/10">
         <ShieldAlert className="size-6 text-destructive" />

package/src/layouts/PrivateLayout/hooks/useLayoutVisual.ts

@@ -71,10 +71,10 @@ const BOXED_BG_CLASS: Record<NonNullable<LayoutVisualConfig['background']>, stri
 export function resolveProviderClassName(
   visual: LayoutVisualConfig | undefined,
 ): string | undefined {
-  // h-svh + overflow-hidden: lock the shell to exactly one viewport height so
+  // h-[var(--app-height)] + overflow-hidden: lock the shell to exactly one viewport height so
   // the inner scroll-area (PrivateContent) is the only scroll surface. Without
   // this, SidebarProvider grows via min-h-svh and the whole page scrolls.
-  const base = 'h-svh overflow-hidden';
+  const base = 'h-[var(--app-height,100svh)] overflow-hidden';
   if ((visual?.variant ?? 'full-bleed') !== 'boxed') return base;
   // `max-md:!bg-background` neutralises shadcn-sidebar's built-in
   // `has-[[data-variant=inset]]:bg-sidebar` below md so the mobile Drawer shell

package/src/layouts/types/layout.types.ts

@@ -72,6 +72,13 @@ export interface BaseLayoutProps {
    * UserMenu, LocaleSwitcher) reads from there via `useLayoutI18n()`.
    */
   i18n?: I18nLayoutConfig;
+
+  /**
+   * Installed-app meta tags (`viewport-fit=cover`, `apple-mobile-web-app-capable`, `mobile-web-app-capable`,
+   * translucent status bar), added to `<head>` when the app's own `viewport`/`metadata` lack them. On by default;
+   * pass `false` to opt out.
+   */
+  pwaMeta?: boolean;
 }
 
 /** Devtools config for BaseApp — the `<Devtools>` props minus children. */