@pablozaiden/webapp 0.3.1 → 0.3.3

package/docs/getting-started.md

@@ -57,11 +57,15 @@ See `docs/cli.md` for framework CLI helpers and generic API command support.
 Frontend entrypoints should use `renderWebApp` so Bun/browser hot reload reuses the existing React root instead of calling `createRoot()` twice. Import the framework CSS explicitly so Bun hot reload observes style changes:
 
 ```tsx
-import { WebAppRoot, renderWebApp } from "@pablozaiden/webapp/web";
+import { Page, Panel, WebAppRoot, renderWebApp } from "@pablozaiden/webapp/web";
 import "@pablozaiden/webapp/web/styles.css";
 
 function Home() {
-  return <main className="wapp-main-content">Hello</main>;
+  return (
+    <Page>
+      <Panel>Hello</Panel>
+    </Page>
+  );
 }
 
 renderWebApp(
@@ -75,6 +79,7 @@ renderWebApp(
 ```
 
 `renderWebApp` renders into `#root` by default and reuses the existing React root across hot reloads. Pass a custom element id or `Element` only when the app uses a different mount point.
+`WebAppRoot` owns the shell and `.wapp-main-content`; each route component should return a `Page` wrapper so standard content margins, mobile padding and scroll behavior stay consistent.
 
 Recommended dev script:
 

package/docs/ui-guidelines.md

@@ -9,6 +9,7 @@ The framework intentionally provides a consistent base UI:
 - Settings and collapse controls are framework-owned.
 - Version is always visible at the bottom of the sidebar.
 - Main content should prefer panels, toolbars, badges and simple forms over custom one-off layouts.
+- `WebAppRoot` owns the fixed main title bar and `.wapp-main-content`; app routes should not render or style those shell elements directly.
 
 ## Main content primitives
 
@@ -16,6 +17,7 @@ Use these first:
 
 | Component | Use |
 | --- | --- |
+| `Page` | Required top-level wrapper for route content rendered by `WebAppRoot.routes`; provides standard margins/padding and mobile spacing |
 | `Toolbar` | Page title/actions inside main content |
 | `Panel` | Cards/sections; use `actions` for a top-right menu/action area |
 | `ActionMenu` | Three-line action menu for secondary surfaces; entity-level shell menus should usually come from `SidebarNode.actions` so the framework renders them in the sidebar context menu and fixed title bar |
@@ -34,6 +36,8 @@ Use these first:
 
 For entity actions, prefer the framework title bar: define one `ActionMenuItem[]` builder and attach it to `SidebarNode.actions` for the route-backed node. The framework reuses those actions for both sidebar right-click and the active route title-bar menu. Use `WebAppRoot.header.getActions` only for additional actions not owned by a sidebar node.
 
+Every route component rendered by `WebAppRoot.routes` should return `Page` at the top level, including loading/error/empty states. Do not render a `Panel`, `DataList`, `EmptyState` or custom div directly into `WebAppRoot`; that skips the standard content margins and recreates the visual bug where cards touch the main content edge. Use `EntityHeader` only when the page needs a content-specific heading distinct from the fixed framework title bar; do not duplicate the active route title immediately below the header.
+
 ## Visual validation captures
 
 Generated screenshots live in `artifacts/screenshots`:

package/package.json

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

package/src/web/WebAppRoot.tsx

@@ -102,6 +102,87 @@ function useRoute(defaultRoute: WebAppRoute) {
   return { route, navigate };
 }
 
+function useMobileViewportHeight() {
+  useEffect(() => {
+    if (typeof window === "undefined") {
+      return;
+    }
+
+    const root = document.documentElement;
+    const mobileQuery = window.matchMedia("(max-width: 900px)");
+    const viewport = window.visualViewport;
+    const timers = new Set<number>();
+    let frame = 0;
+
+    const clearViewportHeight = () => {
+      root.style.removeProperty("--wapp-viewport-height");
+    };
+
+    const sync = () => {
+      frame = 0;
+      if (!mobileQuery.matches) {
+        clearViewportHeight();
+        return;
+      }
+
+      const height = Math.round(viewport?.height ?? window.innerHeight);
+      if (height > 0) {
+        root.style.setProperty("--wapp-viewport-height", `${height}px`);
+      }
+
+      const scrollingElement = document.scrollingElement;
+      if (scrollingElement && scrollingElement.scrollTop !== 0) {
+        scrollingElement.scrollTop = 0;
+      }
+    };
+
+    const scheduleSync = () => {
+      if (frame) {
+        return;
+      }
+      frame = requestAnimationFrame(sync);
+    };
+
+    const scheduleDelayedSync = (delay: number) => {
+      const timer = window.setTimeout(() => {
+        timers.delete(timer);
+        scheduleSync();
+      }, delay);
+      timers.add(timer);
+    };
+
+    const handleKeyboardBoundary = () => {
+      scheduleSync();
+      scheduleDelayedSync(120);
+      scheduleDelayedSync(320);
+    };
+
+    scheduleSync();
+    viewport?.addEventListener("resize", scheduleSync);
+    viewport?.addEventListener("scroll", scheduleSync);
+    window.addEventListener("resize", scheduleSync);
+    mobileQuery.addEventListener("change", scheduleSync);
+    document.addEventListener("focusin", handleKeyboardBoundary);
+    document.addEventListener("focusout", handleKeyboardBoundary);
+
+    return () => {
+      if (frame) {
+        cancelAnimationFrame(frame);
+      }
+      for (const timer of timers) {
+        clearTimeout(timer);
+      }
+      viewport?.removeEventListener("resize", scheduleSync);
+      viewport?.removeEventListener("scroll", scheduleSync);
+      window.removeEventListener("resize", scheduleSync);
+      mobileQuery.removeEventListener("change", scheduleSync);
+      document.removeEventListener("focusin", handleKeyboardBoundary);
+      document.removeEventListener("focusout", handleKeyboardBoundary);
+      clearViewportHeight();
+    };
+  }, []);
+}
+
 async function json<T>(path: string, init: RequestInit = {}): Promise<T> {
   const response = await fetch(path, {
     ...init,
@@ -892,6 +973,7 @@ function SettingsView({ config, refresh, customSections, theme, setTheme }: { co
 }
 
 export function WebAppRoot({ appName, homeRoute, sidebar, routes, header, onRouteChange, settings, version }: WebAppRootProps) {
+  useMobileViewportHeight();
   const { config, error, refresh } = useConfig();
   const { route, navigate } = useRoute(homeRoute);
   const { theme, setTheme } = useTheme();
@@ -1002,16 +1084,28 @@ export function WebAppRoot({ appName, homeRoute, sidebar, routes, header, onRout
   const headerTitle = header?.renderTitle?.(headerContext) ?? defaultTitle;
   const primaryHeaderActions = header?.renderActions?.(headerContext);
   const headerActionLabel = typeof headerTitle === "string" ? headerTitle : defaultTitle;
+  const navigateFromSidebarHeader = (nextRoute: WebAppRoute) => {
+    navigate(nextRoute);
+    setSidebarOpen(false);
+  };
+  const runSidebarHeaderAction = (action: SidebarAction) => {
+    if (action.onAction) {
+      action.onAction();
+    } else if (action.route) {
+      navigate(action.route);
+    }
+    setSidebarOpen(false);
+  };
 
   return (
     <main className={`wapp-shell ${sidebarCollapsed ? "sidebar-collapsed" : ""} ${sidebarOpen ? "sidebar-open" : ""}`}>
       <div className="wapp-mobile-backdrop" onClick={() => setSidebarOpen(false)} />
       <aside className="wapp-sidebar">
         <div className="wapp-sidebar-header">
-          <button type="button" className="wapp-brand" onClick={() => navigate(homeRoute)}>{appName}</button>
+          <button type="button" className="wapp-brand" onClick={() => navigateFromSidebarHeader(homeRoute)}>{appName}</button>
           <div className="wapp-sidebar-actions">
-            {topActions.map((action) => <IconButton key={action.id} className="wapp-sidebar-top-button" title={action.title} aria-label={action.title} onClick={action.onAction ?? (() => action.route && navigate(action.route))}><ActionIcon icon={action.icon} /></IconButton>)}
-            <IconButton className="wapp-sidebar-top-button" title="Settings" aria-label="Open settings" active={route.view === "settings"} onClick={() => navigate({ view: "settings" })}><Icon name="settings" /></IconButton>
+            {topActions.map((action) => <IconButton key={action.id} className="wapp-sidebar-top-button" title={action.title} aria-label={action.title} onClick={() => runSidebarHeaderAction(action)}><ActionIcon icon={action.icon} /></IconButton>)}
+            <IconButton className="wapp-sidebar-top-button" title="Settings" aria-label="Open settings" active={route.view === "settings"} onClick={() => navigateFromSidebarHeader({ view: "settings" })}><Icon name="settings" /></IconButton>
             <IconButton className="wapp-sidebar-top-button" title="Collapse sidebar" aria-label="Collapse sidebar" onClick={() => { setSidebarCollapsed(true); setSidebarOpen(false); }}><Icon name="sidebar" /></IconButton>
           </div>
         </div>

package/src/web/styles.css

@@ -13,9 +13,27 @@
   --wapp-danger-bg: #991b1b;
   --wapp-primary: #111827;
   --wapp-shadow: 0 1px 2px 0 rgb(0 0 0 / 0.05);
+  --wapp-safe-area-top: env(safe-area-inset-top, 0px);
+  --wapp-safe-area-bottom: env(safe-area-inset-bottom, 0px);
+  --wapp-safe-area-left: env(safe-area-inset-left, 0px);
+  --wapp-safe-area-right: env(safe-area-inset-right, 0px);
+  --wapp-mobile-bottom-clearance: max(var(--wapp-safe-area-bottom), 0.75rem);
+  --wapp-viewport-height: 100vh;
   font-family: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
 }
 
+@supports (height: 100svh) {
+  :root {
+    --wapp-viewport-height: 100svh;
+  }
+}
+
+@supports (height: 100dvh) {
+  :root {
+    --wapp-viewport-height: 100dvh;
+  }
+}
+
 :root.dark {
   color-scheme: dark;
   --wapp-bg: var(--wapp-shell-bg);
@@ -41,6 +59,7 @@ html,
 body,
 #root {
   height: 100%;
+  min-height: 100%;
 }
 
 body {
@@ -84,8 +103,8 @@ textarea::placeholder {
 
 .wapp-shell {
   display: flex;
-  height: 100vh;
-  min-height: 100vh;
+  height: var(--wapp-viewport-height);
+  min-height: var(--wapp-viewport-height);
   overflow: hidden;
   background: var(--wapp-bg);
 }
@@ -94,7 +113,7 @@ textarea::placeholder {
   width: 20rem;
   min-width: 20rem;
   min-height: 0;
-  height: 100vh;
+  height: var(--wapp-viewport-height);
   display: flex;
   flex-direction: column;
   overflow: hidden;
@@ -258,6 +277,7 @@ textarea::placeholder {
   overflow-y: auto;
   overflow-x: hidden;
   padding: 1rem 0.75rem;
+  scroll-padding-bottom: var(--wapp-mobile-bottom-clearance);
 }
 
 .wapp-search input {
@@ -501,7 +521,7 @@ textarea::placeholder {
   align-items: center;
   justify-content: space-between;
   min-height: 2rem;
-  padding: 0.25rem 0.25rem 0;
+  padding: 0.25rem 0.25rem var(--wapp-safe-area-bottom);
   color: var(--wapp-muted-2);
   font-size: 0.75rem;
 }
@@ -527,7 +547,7 @@ textarea::placeholder {
   flex: 1;
   min-width: 0;
   min-height: 0;
-  height: 100vh;
+  height: var(--wapp-viewport-height);
   display: flex;
   flex-direction: column;
 }
@@ -551,12 +571,53 @@ textarea::placeholder {
   overflow: auto;
   overflow-x: hidden;
   padding: 0;
+  scroll-padding-bottom: var(--wapp-mobile-bottom-clearance);
 }
 
 .wapp-page {
   width: 100%;
   min-width: 0;
-  padding: 1.5rem 2rem 2rem;
+  max-width: 100%;
+  padding: 1.5rem 2rem max(2rem, var(--wapp-mobile-bottom-clearance));
+}
+
+.wapp-page,
+.wapp-panel,
+.wapp-modal-body {
+  overflow-wrap: anywhere;
+}
+
+.wapp-page :where(*):not(table, thead, tbody, tfoot, tr, th, td),
+.wapp-panel :where(*):not(table, thead, tbody, tfoot, tr, th, td),
+.wapp-modal-body :where(*):not(table, thead, tbody, tfoot, tr, th, td) {
+  min-width: 0;
+}
+
+.wapp-page :where(img, video, canvas, iframe, svg),
+.wapp-panel :where(img, video, canvas, iframe, svg),
+.wapp-modal-body :where(img, video, canvas, iframe, svg) {
+  max-width: 100%;
+}
+
+.wapp-page :where(pre),
+.wapp-panel :where(pre),
+.wapp-modal-body :where(pre) {
+  max-width: 100%;
+  overflow-x: auto;
+}
+
+.wapp-page :where(table),
+.wapp-panel :where(table),
+.wapp-modal-body :where(table) {
+  display: block;
+  max-width: 100%;
+  overflow-x: auto;
+}
+
+.wapp-page :where(code, kbd, samp),
+.wapp-panel :where(code, kbd, samp),
+.wapp-modal-body :where(code, kbd, samp) {
+  overflow-wrap: anywhere;
 }
 
 .wapp-panel {
@@ -1599,7 +1660,7 @@ textarea::placeholder {
   flex-direction: column;
   width: 100%;
   min-width: 0;
-  max-height: calc(100dvh - 1.5rem);
+  max-height: calc(var(--wapp-viewport-height) - 1.5rem - var(--wapp-safe-area-bottom));
   overflow: hidden;
   border: 1px solid var(--wapp-border);
   border-radius: 0.5rem;
@@ -1682,6 +1743,7 @@ textarea::placeholder {
   overflow-x: hidden;
   overflow-y: auto;
   padding: 0.75rem 1rem;
+  scroll-padding-bottom: var(--wapp-mobile-bottom-clearance);
 }
 
 .wapp-modal-footer {
@@ -1692,7 +1754,7 @@ textarea::placeholder {
   justify-content: flex-end;
   gap: 0.5rem;
   border-top: 1px solid var(--wapp-border);
-  padding: 0.75rem 1rem;
+  padding: 0.75rem 1rem max(0.75rem, var(--wapp-mobile-bottom-clearance));
 }
 
 @media (min-width: 640px) {
@@ -1701,7 +1763,7 @@ textarea::placeholder {
   }
 
   .wapp-modal {
-    max-height: calc(100dvh - 2.5rem);
+    max-height: calc(var(--wapp-viewport-height) - 2.5rem - var(--wapp-safe-area-bottom));
   }
 
   .wapp-modal-header {
@@ -1776,7 +1838,7 @@ textarea::placeholder {
   }
 
   .wapp-page {
-    padding: 1rem;
+    padding: 1rem 1rem max(1rem, var(--wapp-mobile-bottom-clearance));
   }
 
   .wapp-panel-header,