@pablozaiden/webapp 1.2.0 → 1.3.0

package/README.md

@@ -28,6 +28,25 @@ Each application package must declare `react` and `react-dom`; they are peer dep
 | `@pablozaiden/webapp/cli` | One-binary command helpers, device/environment auth credentials and generic API CLI caller |
 | `@pablozaiden/webapp/build` | Bun single-binary compile helper |
 
+## Motion primitives
+
+The web export includes `Presence`, `Collapsible`, `AsyncState`, `AnimatedList`,
+`Tabs`, `TabPanels`, and `TabPanel`. Use stable React keys with `AnimatedList`;
+it preserves removed keyed children for the exit duration and marks them
+inaccessible while they leave. The primitives honor
+`prefers-reduced-motion` and skip visual movement when it is enabled.
+
+```tsx
+<AnimatedList>
+  {records.map((record) => (
+    <DataListRow key={record.id} title={record.title} />
+  ))}
+</AnimatedList>
+```
+
+Use `layout="contents"` when animated children should participate directly in
+the surrounding layout rather than through the list wrapper.
+
 See `docs/getting-started.md` for the minimum app shape and `examples/notes-todo` for a realistic app. Use `docs/github-actions.md` when adding CI, Docker and release workflows to an app built with the framework. Release/publishing details for this package are in `docs/release.md`.
 
 CLI API callers can use a stored device session or the stateless

package/docs/ui-guidelines.md

@@ -43,6 +43,7 @@ Use these first:
 | `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 |
+| `FloatingPanel` | Anchored arbitrary popup content; use it instead of app-owned portals when the content is not a simple `ActionMenu` |
 | `Button` / `IconButton` | Form submission and true inline controls; prefer action menus for entity/app commands |
 | `Badge` | Generic status/count labels; preserves the supplied text casing |
 | `StatusBadge` | Status labels with the shared uppercase and letter-spacing treatment |

package/package.json

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

package/src/web/WebAppRoot.tsx

@@ -4,7 +4,7 @@ import { AppShell } from "./app-shell";
 import { DeviceVerificationScreen, PasskeyAuthScreen, UserSetupScreen } from "./auth-screens";
 import { EmptyState, Panel } from "./components";
 import { useMobileBreakpoint, useMobileSidebarSwipe, useMobileViewportHeight } from "./mobile-hooks";
-import { useRoute } from "./routing";
+import { routeToHash, supportsViewTransitions, useRoute } from "./routing";
 import { flattenSidebarItems, toStoredPin, useSidebarCollapsedState, useSidebarPins } from "./sidebar-state";
 import { SettingsView } from "./settings/settings-view";
 import type { HeaderContext, WebAppRootProps } from "./root-types";
@@ -12,6 +12,7 @@ import type { ActionMenuItem, SidebarNode, WebAppRoute } from "./sidebar/types";
 import { ThemeProvider } from "./theme";
 import { WebAppConfigProvider, useWebAppConfig } from "./webapp-config";
 import { setLogLevel } from "./logger";
+import { useReducedMotion } from "./motion";
 
 export { replaceHashRoute, replaceWebAppRoute, routeToHash } from "./routing";
 export type {
@@ -48,6 +49,7 @@ function WebAppRootContent({
   refresh: () => Promise<void>;
 }) {
   const isMobile = useMobileBreakpoint();
+  const reducedMotion = useReducedMotion();
   useMobileViewportHeight(isMobile);
   const { route, navigate } = useRoute(homeRoute);
   const [search, setSearch] = useState("");
@@ -189,6 +191,8 @@ function WebAppRootContent({
       headerActionLabel={headerActionLabel}
       primaryHeaderActions={primaryHeaderActions}
       headerActions={headerActions}
+      routeKey={routeToHash(route)}
+      nativeRouteTransitions={supportsViewTransitions() && !reducedMotion}
       view={view}
     />
   );

package/src/web/app-shell.tsx

@@ -1,5 +1,6 @@
 import { useEffect, type ReactNode, type RefObject } from "react";
 import { ActionMenu, IconButton } from "./components";
+import { Presence } from "./motion";
 import { SidebarTree } from "./sidebar-tree";
 import type { SidebarCollapsedState } from "./sidebar-state";
 import type { ActionMenuItem, SidebarAction, SidebarNode, WebAppRoute } from "./sidebar/types";
@@ -61,6 +62,8 @@ export interface AppShellProps {
   headerActionLabel: string;
   primaryHeaderActions?: ReactNode;
   headerActions: ActionMenuItem[];
+  routeKey: string;
+  nativeRouteTransitions?: boolean;
   view: ReactNode;
 }
 
@@ -88,6 +91,8 @@ export function AppShell({
   headerActionLabel,
   primaryHeaderActions,
   headerActions,
+  routeKey,
+  nativeRouteTransitions = false,
   view,
 }: AppShellProps) {
   useEffect(() => {
@@ -129,20 +134,25 @@ export function AppShell({
   };
 
   return (
-    <main className={`wapp-shell ${sidebarCollapsed ? "sidebar-collapsed" : ""} ${sidebarOpen ? "sidebar-open" : ""}`}>
-      <div
-        className="wapp-mobile-backdrop"
-        role="button"
-        tabIndex={0}
-        aria-label="Close sidebar"
-        onClick={closeSidebar}
-        onKeyDown={(event) => {
-          if (event.key === "Enter" || event.key === " ") {
-            event.preventDefault();
-            closeSidebar();
-          }
-        }}
-      />
+    <main className={`wapp-shell ${sidebarCollapsed ? "sidebar-collapsed" : ""} ${sidebarOpen ? "sidebar-open" : ""} ${nativeRouteTransitions ? "wapp-native-route-transitions" : ""}`.trim()}>
+      <Presence present={sidebarOpen}>
+        {(state) => (
+          <div
+            className={`wapp-mobile-backdrop wapp-motion-${state}`}
+            role="button"
+            tabIndex={0}
+            aria-label="Close sidebar"
+            aria-hidden={state === "exit" ? true : undefined}
+            onClick={closeSidebar}
+            onKeyDown={(event) => {
+              if (event.key === "Enter" || event.key === " ") {
+                event.preventDefault();
+                closeSidebar();
+              }
+            }}
+          />
+        )}
+      </Presence>
       <aside id="wapp-sidebar" className="wapp-sidebar">
         <div className="wapp-sidebar-header">
           <button type="button" className="wapp-brand" onClick={() => navigateFromSidebarHeader(homeRoute)}>{appName}</button>
@@ -182,16 +192,20 @@ export function AppShell({
         <header className="wapp-main-header">
           <div className="wapp-main-header-title">
             {sidebarCollapsed ? <IconButton className="wapp-sidebar-top-button" aria-label={sidebarToggleLabel} title={sidebarToggleLabel} aria-expanded={!sidebarCollapsed} aria-controls="wapp-sidebar" onClick={toggleSidebarCollapsed}><Icon name="sidebar" /></IconButton> : <IconButton className="wapp-mobile-only wapp-sidebar-top-button" aria-label="Show sidebar" title="Show sidebar" aria-expanded={sidebarOpen} aria-controls="wapp-sidebar" onClick={() => setSidebarOpen(true)}><Icon name="sidebar" /></IconButton>}
-            <h1>{headerTitle}</h1>
+            <h1 key={routeKey} className="wapp-route-fade">{headerTitle}</h1>
           </div>
           {primaryHeaderActions || headerActions.length ? (
-            <div className="wapp-main-header-actions">
+            <div key={routeKey} className="wapp-main-header-actions wapp-route-fade">
               {primaryHeaderActions}
               {headerActions.length ? <ActionMenu items={headerActions} ariaLabel={`Actions for ${headerActionLabel}`} /> : null}
             </div>
           ) : null}
         </header>
-        <div className="wapp-main-content">{view}</div>
+        <div className="wapp-main-content">
+          <div key={routeKey} className="wapp-route-view">
+            {view}
+          </div>
+        </div>
       </section>
     </main>
   );