@pablozaiden/webapp 0.5.6 → 0.5.8

package/docs/getting-started.md

@@ -41,7 +41,7 @@ const app = createWebAppServer({
 await app.runFromCli();
 ```
 
-The framework generates the HTML document, React mount point, viewport metadata, PWA manifest, default SVG icons, and the theme prepaint script. By default it uses `./web/main.tsx` relative to the Bun entry file as the frontend entrypoint, so apps only need to create that file. Override document defaults only when the app needs different metadata:
+The framework generates the HTML document, React mount point, fixed-scale viewport metadata, PWA manifest, default SVG icons, and the theme prepaint script. On iPhone, iPad, and other mobile browsers that honor viewport scaling tokens, the generated viewport prevents pinch-to-zoom while preserving normal scrolling; clients that ignore those tokens are unaffected. By default it uses `./web/main.tsx` relative to the Bun entry file as the frontend entrypoint, so apps only need to create that file. Override document defaults only when the app needs different metadata:
 
 ```ts
 createWebAppServer({
@@ -67,6 +67,8 @@ createWebAppServer({
 });
 ```
 
+Do not create an app-owned `index.html` or add global touch handlers to control zoom. The framework owns the viewport policy so the same metadata is emitted for development, compiled clients, and installed PWAs without disabling scrolling.
+
 PWA support is on by default, with generated initials icons unless the app provides `web.icons`. Icon paths are relative to the app package root; production apps should provide at least 192x192 and 512x512 PNG manifest icons plus an Apple touch icon. Set `web.pwa: false` only for apps that deliberately should not be installable. The standard theme preference key is `webapp.theme`; apps should not use app-specific theme storage keys.
 
 Apps should stay one app and one binary. Use subcommands for different modes:

package/docs/server.md

@@ -96,7 +96,9 @@ Built-in endpoints include:
 
 ## Framework-owned web document and PWA metadata
 
-`createWebAppServer` owns the browser document. Apps do not provide `index.html`; the framework generates a Bun `HTMLBundle` internally so Bun hot reload and asset rewriting keep working. By default the frontend entrypoint is `./web/main.tsx` relative to the Bun entry file.
+`createWebAppServer` owns the browser document. Apps do not provide `index.html`; the framework generates a Bun `HTMLBundle` internally so Bun hot reload and asset rewriting keep working. By default the frontend entrypoint is `./web/main.tsx` relative to the Bun entry file. The generated viewport keeps the app at `initial-scale=1` with `maximum-scale=1` and `user-scalable=no`; clients and mobile browsers that honor those viewport scaling tokens, including iPhone and iPad, cannot change the app scale with pinch-to-zoom while normal scrolling remains enabled. Clients that ignore the tokens are unaffected.
+
+Do not replace this behavior with global touch event handlers, `preventDefault()` calls, or `touch-action: none`: those approaches can disable scrolling and other touch interactions. Applications should keep the document framework-owned rather than adding an app-owned `index.html`.
 
 ```ts
 createWebAppServer({

package/docs/sidebar.md

@@ -38,6 +38,8 @@ Sidebar nodes support:
 
 Search is intentionally app-defined: `getNodes({ search })` receives raw search text and returns the tree that should be rendered. Set `sidebar.search: false` when an app has a small fixed navigation tree and should not show the sidebar search box.
 
+On mobile widths, the drawer can be opened with a horizontal swipe starting within the first 24px of the viewport, in addition to the header button. The gesture must move at least 64px to the right, stay within 48px of vertical displacement, and remain more horizontal than vertical.
+
 Use `actions` when an entity needs commands in the sidebar. `WebAppRoot` finds the active route-backed sidebar node and automatically renders its `ActionMenuItem[]` in the title-bar three-line menu, so the sidebar right-click menu and header menu stay consistent from one source of truth. Use `header.getActions` only for extra route-level actions that are not represented by the active sidebar node.
 
 ```tsx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pablozaiden/webapp",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "description": "Opinionated Bun + React webapp framework for single-server apps",
   "license": "MIT",
   "type": "module",

package/src/server/create-web-app-server.ts

@@ -510,7 +510,7 @@ function generatedHtml(
 <html lang="${escapeAttribute(web.lang ?? "en")}">
   <head>
     <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no, viewport-fit=cover" />
 ${themeMetaTag}\
 ${manifestTags}    <title>${title}</title>
     <script>${themeBootScript(themeColor)}</script>

package/src/web/WebAppRoot.tsx

@@ -190,7 +190,7 @@ function useMobileViewportHeight() {
       timers.add(timer);
     };
 
-    const handleKeyboardBoundary = () => {
+    const handleViewportTransition = () => {
       scheduleSync();
       scheduleDelayedSync(120);
       scheduleDelayedSync(320);
@@ -200,9 +200,10 @@ function useMobileViewportHeight() {
     viewport?.addEventListener("resize", scheduleSync);
     viewport?.addEventListener("scroll", scheduleSync);
     window.addEventListener("resize", scheduleSync);
+    window.addEventListener("orientationchange", handleViewportTransition);
     mobileQuery.addEventListener("change", scheduleSync);
-    document.addEventListener("focusin", handleKeyboardBoundary);
-    document.addEventListener("focusout", handleKeyboardBoundary);
+    document.addEventListener("focusin", handleViewportTransition);
+    document.addEventListener("focusout", handleViewportTransition);
 
     return () => {
       if (frame) {
@@ -214,14 +215,94 @@ function useMobileViewportHeight() {
       viewport?.removeEventListener("resize", scheduleSync);
       viewport?.removeEventListener("scroll", scheduleSync);
       window.removeEventListener("resize", scheduleSync);
+      window.removeEventListener("orientationchange", handleViewportTransition);
       mobileQuery.removeEventListener("change", scheduleSync);
-      document.removeEventListener("focusin", handleKeyboardBoundary);
-      document.removeEventListener("focusout", handleKeyboardBoundary);
+      document.removeEventListener("focusin", handleViewportTransition);
+      document.removeEventListener("focusout", handleViewportTransition);
       clearViewportHeight();
     };
   }, []);
 }
 
+const MOBILE_SIDEBAR_BREAKPOINT = 900;
+const SIDEBAR_SWIPE_EDGE_WIDTH = 24;
+const SIDEBAR_SWIPE_DISTANCE = 64;
+const SIDEBAR_SWIPE_VERTICAL_TOLERANCE = 48;
+
+function useMobileSidebarSwipe(sidebarOpen: boolean, setSidebarOpen: (open: boolean) => void) {
+  useEffect(() => {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+      return;
+    }
+
+    let tracking = false;
+    let startX = 0;
+    let startY = 0;
+
+    const reset = () => {
+      tracking = false;
+    };
+
+    const handleTouchStart = (event: TouchEvent) => {
+      if (sidebarOpen || window.innerWidth > MOBILE_SIDEBAR_BREAKPOINT || event.touches.length !== 1) {
+        reset();
+        return;
+      }
+
+      const touch = event.touches[0];
+      if (!touch || touch.clientX > SIDEBAR_SWIPE_EDGE_WIDTH) {
+        reset();
+        return;
+      }
+
+      tracking = true;
+      startX = touch.clientX;
+      startY = touch.clientY;
+    };
+
+    const handleTouchMove = (event: TouchEvent) => {
+      if (!tracking) {
+        return;
+      }
+      if (event.touches.length !== 1) {
+        reset();
+        return;
+      }
+
+      const touch = event.touches[0];
+      if (!touch) {
+        reset();
+        return;
+      }
+
+      const deltaX = touch.clientX - startX;
+      const deltaY = Math.abs(touch.clientY - startY);
+      if (deltaX <= 0 || deltaY > SIDEBAR_SWIPE_VERTICAL_TOLERANCE || deltaY > deltaX) {
+        reset();
+        return;
+      }
+      if (deltaX < SIDEBAR_SWIPE_DISTANCE) {
+        return;
+      }
+
+      event.preventDefault();
+      setSidebarOpen(true);
+      reset();
+    };
+
+    document.addEventListener("touchstart", handleTouchStart, { passive: true });
+    document.addEventListener("touchmove", handleTouchMove, { passive: false });
+    document.addEventListener("touchend", reset);
+    document.addEventListener("touchcancel", reset);
+    return () => {
+      document.removeEventListener("touchstart", handleTouchStart);
+      document.removeEventListener("touchmove", handleTouchMove);
+      document.removeEventListener("touchend", reset);
+      document.removeEventListener("touchcancel", reset);
+    };
+  }, [setSidebarOpen, sidebarOpen]);
+}
+
 async function json<T>(path: string, init: RequestInit = {}): Promise<T> {
   const response = await fetch(path, {
     ...init,
@@ -1077,6 +1158,7 @@ export function WebAppRoot({ appName, homeRoute, sidebar, routes, header, onRout
   const [sidebarOpen, setSidebarOpen] = useState(false);
   const [sidebarCollapsed, setSidebarCollapsed] = useState(false);
   const sidebarTreeState = useSidebarCollapsedState(appName);
+  useMobileSidebarSwipe(sidebarOpen, setSidebarOpen);
   const toggleSidebarCollapsed = useCallback(() => {
     setSidebarCollapsed((current) => {
       const nextCollapsed = !current;

package/src/web/styles.css

@@ -108,6 +108,7 @@ textarea::placeholder {
   height: var(--wapp-viewport-height);
   min-height: var(--wapp-viewport-height);
   overflow: hidden;
+  overscroll-behavior-x: none;
   background: var(--wapp-bg);
 }
 
@@ -1896,6 +1897,10 @@ textarea::placeholder {
     padding: 0.875rem 1rem;
   }
 
+  .wapp-main {
+    touch-action: pan-y;
+  }
+
   .wapp-main-content {
     overflow: auto;
     overflow-x: hidden;