@pablozaiden/webapp 0.3.2 → 0.3.4

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.2",
+  "version": "0.3.4",
   "description": "Opinionated Bun + React webapp framework for single-server apps",
   "license": "MIT",
   "type": "module",

package/src/web/WebAppRoot.tsx

@@ -70,6 +70,18 @@ type StoredSidebarPin = {
   route: WebAppRoute;
 };
 
+function isSidebarShortcutEditableTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) {
+    return false;
+  }
+  if (target.isContentEditable || target.closest("[contenteditable=''], [contenteditable='true']")) {
+    return true;
+  }
+  return target instanceof HTMLInputElement
+    || target instanceof HTMLTextAreaElement
+    || target instanceof HTMLSelectElement;
+}
+
 function routeToHash(route: WebAppRoute): string {
   const params = new URLSearchParams();
   for (const [key, value] of Object.entries(route)) {
@@ -102,6 +114,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,12 +985,20 @@ 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();
   const [search, setSearch] = useState("");
   const [sidebarOpen, setSidebarOpen] = useState(false);
   const [sidebarCollapsed, setSidebarCollapsed] = useState(false);
+  const toggleSidebarCollapsed = useCallback(() => {
+    setSidebarCollapsed((current) => {
+      const nextCollapsed = !current;
+      setSidebarOpen(!nextCollapsed);
+      return nextCollapsed;
+    });
+  }, []);
   const sidebarSearchEnabled = sidebar.search !== false;
   const pinningEnabled = sidebar.pinning !== false;
   const sidebarPins = useSidebarPins(appName, sidebar.pinning ? sidebar.pinning.storageKey : undefined);
@@ -959,6 +1060,28 @@ export function WebAppRoot({ appName, homeRoute, sidebar, routes, header, onRout
       .catch(() => undefined);
   }, [config?.currentUser?.id, setTheme]);
 
+  useEffect(() => {
+    function handleSidebarShortcut(event: KeyboardEvent) {
+      if (
+        event.key.toLowerCase() !== "b"
+        || event.altKey
+        || event.shiftKey
+        || event.ctrlKey === event.metaKey
+        || event.isComposing
+        || event.repeat
+        || isSidebarShortcutEditableTarget(event.target)
+      ) {
+        return;
+      }
+
+      event.preventDefault();
+      toggleSidebarCollapsed();
+    }
+
+    document.addEventListener("keydown", handleSidebarShortcut);
+    return () => document.removeEventListener("keydown", handleSidebarShortcut);
+  }, [toggleSidebarCollapsed]);
+
   useEffect(() => {
     onRouteChange?.(route);
   }, [onRouteChange, route]);
@@ -1002,6 +1125,7 @@ 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 sidebarToggleLabel = sidebarCollapsed ? "Show sidebar" : "Collapse sidebar";
   const navigateFromSidebarHeader = (nextRoute: WebAppRoute) => {
     navigate(nextRoute);
     setSidebarOpen(false);
@@ -1024,7 +1148,7 @@ export function WebAppRoot({ appName, homeRoute, sidebar, routes, header, onRout
           <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={() => 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>
+            <IconButton className="wapp-sidebar-top-button" title={sidebarToggleLabel} aria-label={sidebarToggleLabel} onClick={toggleSidebarCollapsed}><Icon name="sidebar" /></IconButton>
           </div>
         </div>
         <div className="wapp-sidebar-scroll">
@@ -1036,7 +1160,7 @@ export function WebAppRoot({ appName, homeRoute, sidebar, routes, header, onRout
       <section className="wapp-main">
         <header className="wapp-main-header">
           <div className="wapp-main-header-title">
-            {sidebarCollapsed ? <IconButton className="wapp-sidebar-top-button" aria-label="Show sidebar" title="Show sidebar" onClick={() => { setSidebarCollapsed(false); setSidebarOpen(true); }}><Icon name="sidebar" /></IconButton> : <IconButton className="wapp-mobile-only wapp-sidebar-top-button" aria-label="Show sidebar" title="Show sidebar" onClick={() => setSidebarOpen(true)}><Icon name="sidebar" /></IconButton>}
+            {sidebarCollapsed ? <IconButton className="wapp-sidebar-top-button" aria-label={sidebarToggleLabel} title={sidebarToggleLabel} onClick={toggleSidebarCollapsed}><Icon name="sidebar" /></IconButton> : <IconButton className="wapp-mobile-only wapp-sidebar-top-button" aria-label="Show sidebar" title="Show sidebar" onClick={() => setSidebarOpen(true)}><Icon name="sidebar" /></IconButton>}
             <h1>{headerTitle}</h1>
           </div>
           {primaryHeaderActions || headerActions.length ? (

package/src/web/styles.css

@@ -13,9 +13,29 @@
   --wapp-danger-bg: #991b1b;
   --wapp-primary: #111827;
   --wapp-shadow: 0 1px 2px 0 rgb(0 0 0 / 0.05);
+  --wapp-overlay-bg: rgb(0 0 0 / 0.5);
+  --wapp-overlay-blur: blur(4px);
+  --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 +61,7 @@ html,
 body,
 #root {
   height: 100%;
+  min-height: 100%;
 }
 
 body {
@@ -84,8 +105,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 +115,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 +279,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 +523,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 +549,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 +573,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 {
@@ -1488,7 +1551,8 @@ textarea::placeholder {
 .wapp-mobile-backdrop {
   position: fixed;
   inset: 0;
-  background: rgb(15 23 42 / 0.36);
+  background: var(--wapp-overlay-bg);
+  backdrop-filter: var(--wapp-overlay-blur);
   z-index: 50;
 }
 
@@ -1589,8 +1653,8 @@ textarea::placeholder {
 .wapp-modal-overlay {
   position: absolute;
   inset: 0;
-  background: rgb(0 0 0 / 0.5);
-  backdrop-filter: blur(4px);
+  background: var(--wapp-overlay-bg);
+  backdrop-filter: var(--wapp-overlay-blur);
 }
 
 .wapp-modal {
@@ -1599,7 +1663,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 +1746,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 +1757,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 +1766,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 +1841,7 @@ textarea::placeholder {
   }
 
   .wapp-page {
-    padding: 1rem;
+    padding: 1rem 1rem max(1rem, var(--wapp-mobile-bottom-clearance));
   }
 
   .wapp-panel-header,