@pablozaiden/webapp 0.2.3 → 0.3.0

package/docs/sidebar.md

@@ -30,15 +30,15 @@ Sidebar nodes support:
 | `route` | Hash route object used by `WebAppRoot` |
 | `children` | Collapsible nesting |
 | `action` | Single inline per-section/item action; use sparingly and prefer `actions` menus when possible |
-| `actions` | Context menu items shown on sidebar right-click |
+| `actions` | Entity action menu items shown on sidebar right-click and automatically in the active route title-bar menu |
 | `pinnable` | Enables framework Pin/Unpin actions |
 | `pinId` | Stable pin identity when it should differ from `id` |
-| `badge` | Status/count label |
+| `badge` | Status/count value; sidebar items render it as a compact status dot with accessible label/tooltip |
 | `defaultCollapsed` | Initial collapsed state |
 
 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.
 
-Use `actions` when an entity needs commands in the sidebar. The same `ActionMenuItem[]` should also be returned from `header.getActions` for that entity route so right-click actions and the title-bar three-line menu stay consistent:
+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
 const actions = projectActions(project);
@@ -56,9 +56,6 @@ return {
     pinning: { sectionTitle: "Pinned" },
     getNodes,
   }}
-  header={{
-    getActions: ({ route }) => route.view === "project" ? projectActionsForRoute(route) : [],
-  }}
 />
 ```
 

package/docs/ui-guidelines.md

@@ -18,9 +18,9 @@ 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 menus should usually be exposed through `WebAppRoot.header.getActions` so they render in the fixed title bar |
+| `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 |
 | `Button` / `IconButton` | Form submission and true inline controls; prefer action menus for entity/app commands |
-| `Badge` | Status/count labels |
+| `Badge` | Status/count labels; sidebar badges render as compact colored dots to preserve sidebar width |
 | `EntityHeader` | Main-content entity title/description/actions |
 | `DataList` / `DataListRow` | Lists with title, description, metadata, badge and actions |
 | `TextField`, `TextAreaField`, `SelectField` | Forms |
@@ -32,7 +32,7 @@ Use these first:
 | `EmptyState` | Empty or missing content |
 | `ConfirmDialog` | Destructive confirmation |
 
-For entity actions, prefer the framework title bar: define one `ActionMenuItem[]` builder, attach it to `SidebarNode.actions` for right-click, and return the same actions from `WebAppRoot.header.getActions` for the selected route.
+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.
 
 ## Visual validation captures
 
@@ -58,4 +58,8 @@ Use these captures as the manual visual baseline before changing shell, sidebar,
 
 All destructive delete actions must use the framework `ConfirmDialog` before calling the delete endpoint. Server lifecycle actions such as kill/reboot must also require confirmation and show the standard 15-second shutdown countdown progress bar after the request succeeds.
 
-Prefer the framework action-menu pattern for app commands. Actions such as New task, New note, New project, archive, delete, or state transitions should live in `SidebarNode.actions` and/or `WebAppRoot.header.getActions` so they appear behind the three-line title-bar/item action menus. Use discrete buttons mainly for form submission or inline controls that cannot reasonably live in an action menu.
+Framework dialogs and modal forms handle Enter as the primary/confirm action and Escape as cancel/close. Do not reimplement this keyboard behavior in app-local modal code.
+
+Prefer the framework action-menu pattern for app commands. Actions such as New task, New note, New project, archive, delete, or state transitions should live in `SidebarNode.actions` so they appear behind the three-line title-bar/item action menus. Destructive actions should be marked `destructive: true`; the framework also treats delete-labelled actions defensively, renders them red, and orders them last. Use discrete buttons mainly for form submission or inline controls that cannot reasonably live in an action menu.
+
+Headers and menus should be allowed to shrink safely: titles and subtitles truncate, while icon buttons and action buttons keep their shape and remain visible. Context menus are framework-positioned to stay inside the visible viewport.

package/package.json

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

package/src/server/auth/sqlite-store.ts

@@ -6,7 +6,6 @@ import type {
   AuditEventRecord,
   DeviceAuthRequestRecord,
   RefreshSessionRecord,
-  SigningKeyRecord,
   StoredPasskey,
   UserRecord,
   UserSetupLinkRecord,

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

@@ -63,6 +63,7 @@ export interface WebAppServerConfig<TEvent = unknown> {
   logLevel?: {
     onChange?: (level: LogLevelName) => void;
   };
+  configResponse?: (req: Request, base: Readonly<WebAppConfigResponse>) => Record<string, unknown>;
 }
 
 export const WEBAPP_SOCKET_HANDLER = "webappSocketHandler";
@@ -364,9 +365,9 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
     return { kind: "anonymous" };
   }
 
-  function configResponse(req: Request): WebAppConfigResponse {
+  function configResponse(req: Request): WebAppConfigResponse & Record<string, unknown> {
     const user = passkeysEnabled && config.passkeyDisabled ? disabledAuthOwner() : passkeysEnabled ? getPasskeySessionUser(req, store, config) : undefined;
-    return {
+    const base = {
       appName: config.appName,
       version,
       currentUser: user,
@@ -381,7 +382,8 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
       },
       apiKeys: { enabled: Boolean(apiKeysEnabled) },
       deviceAuth: { enabled: Boolean(deviceAuthEnabled) },
-    };
+    } satisfies WebAppConfigResponse;
+    return { ...(input.configResponse?.(req, base) ?? {}), ...base };
   }
 
   function setupUrl(req: Request, token: string): string {
@@ -427,6 +429,18 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
         const upgraded = server.upgrade(req, { data: { filters, userId: currentUser(auth)?.id } });
         return upgraded ? undefined : errorResponse(400, "websocket_upgrade_failed", "WebSocket upgrade failed");
       }
+      if (path === "/api/auth/status" && req.method === "GET") {
+        const auth = await authorize(req, true);
+        if (auth instanceof Response) return auth;
+        const user = currentUser(auth);
+        return jsonResponse({
+          authenticated: auth.kind !== "anonymous",
+          authKind: auth.kind,
+          subject: user?.id ?? null,
+          clientId: auth.kind === "bearer" ? auth.claims.clientId : null,
+          scope: auth.kind === "bearer" ? auth.claims.scope : null,
+        });
+      }
       if (path === "/api/passkey-auth/status" && req.method === "GET") {
         return jsonResponse(passkeyStatus(req, store, config, passkeysEnabled));
       }

package/src/server/route-catalog.ts

@@ -30,7 +30,7 @@ function defaultCliPath(path: string): string {
   return trimSlashes(path.startsWith("/api/") ? path.slice("/api/".length) : path);
 }
 
-function methodsFor(route: RouteDefinition): HttpMethod[] {
+function methodsFor<TEvent>(route: RouteDefinition<TEvent>): HttpMethod[] {
   return HTTP_METHODS.filter((method) => typeof route[method] === "function");
 }
 

package/src/server/routes.ts

@@ -10,6 +10,7 @@ export type UserOwnedResource = { userId: string };
 export type UserIdSelector<TResource> = (resource: TResource) => string | undefined;
 
 export interface UserScopedRealtimePublisher<TEvent = unknown> {
+  readonly _eventType?: TEvent;
   publishChanged<TPayload = unknown>(resource: string, options?: Omit<ResourceRealtimeEvent<TPayload>, "type" | "resource" | "action"> & { target?: RealtimeTarget }): void;
   publishEntityChanged<TPayload = unknown>(resource: string, id: string, options?: Omit<ResourceRealtimeEvent<TPayload>, "type" | "resource" | "action" | "id"> & { target?: RealtimeTarget }): void;
   publishDeleted<TPayload = unknown>(resource: string, id: string, options?: Omit<ResourceRealtimeEvent<TPayload>, "type" | "resource" | "action" | "id"> & { target?: RealtimeTarget }): void;
@@ -75,13 +76,19 @@ export function matchRoute<TEvent>(routes: RouteTable<TEvent>, pathname: string)
   const requestParts = splitPath(pathname);
   for (const [pattern, route] of Object.entries(routes)) {
     const patternParts = splitPath(pattern);
-    if (patternParts.length !== requestParts.length) {
+    const wildcardIndex = patternParts.indexOf("*");
+    const hasTrailingWildcard = wildcardIndex === patternParts.length - 1;
+    if ((!hasTrailingWildcard && patternParts.length !== requestParts.length) || (hasTrailingWildcard && requestParts.length < wildcardIndex)) {
       continue;
     }
     const params: Record<string, string> = {};
     let matched = true;
     for (let index = 0; index < patternParts.length; index += 1) {
       const patternPart = patternParts[index]!;
+      if (patternPart === "*" && index === patternParts.length - 1) {
+        params["*"] = requestParts.slice(index).map(decodeURIComponent).join("/");
+        break;
+      }
       const requestPart = requestParts[index]!;
       if (patternPart.startsWith(":")) {
         params[patternPart.slice(1)] = decodeURIComponent(requestPart);

package/src/web/WebAppRoot.tsx

@@ -51,8 +51,10 @@ export interface WebAppRootProps {
   routes: Record<string, ReactNode | ((route: WebAppRoute) => ReactNode)>;
   header?: {
     renderTitle?: (ctx: HeaderContext) => ReactNode;
+    renderActions?: (ctx: HeaderContext) => ReactNode;
     getActions?: (ctx: HeaderContext) => ActionMenuItem[];
   };
+  onRouteChange?: (route: WebAppRoute) => void;
   settings?: {
     sections?: SettingsSection[];
   };
@@ -203,7 +205,7 @@ function Icon({ name }: { name: "settings" | "sidebar" | "plus" | "home" | "sear
   if (name === "plus") return <svg {...common}><path d="M12 5v14M5 12h14" /></svg>;
   if (name === "bolt") return <svg {...common}><path d="m13 2-8 12h7l-1 8 8-12h-7l1-8Z" /></svg>;
   if (name === "chat") return <svg {...common}><path d="M21 15a4 4 0 0 1-4 4H8l-5 3V7a4 4 0 0 1 4-4h10a4 4 0 0 1 4 4Z" /><path d="M8 9h8M8 13h5" /></svg>;
-  if (name === "code") return <svg {...common}><path d="m16 18 6-6-6-6M8 6l-6 6 6 6" /></svg>;
+  if (name === "code") return <svg {...common}><path d="M8 8 4 12l4 4M16 8l4 4-4 4M14 4l-4 16" /></svg>;
   if (name === "refresh") return <svg {...common}><path d="M21 12a9 9 0 0 1-15.5 6.3L3 16M3 21v-5h5M3 12A9 9 0 0 1 18.5 5.7L21 8M21 3v5h-5" /></svg>;
   return <svg {...common}><path d="M4 10.5 12 4l8 6.5V20H5v-7h14" /></svg>;
 }
@@ -394,7 +396,18 @@ function DeviceVerificationScreen() {
   );
 }
 
-function SidebarTree({ nodes, route, navigate, level = 0 }: { nodes: SidebarNode[]; route: WebAppRoute; navigate: (route: WebAppRoute) => void; level?: number }) {
+type SidebarTreeParentKind = "root" | "section" | "item";
+
+function sidebarIndentStyle(level: number, parentKind: SidebarTreeParentKind): { marginLeft?: string } | undefined {
+  if (level <= 0) {
+    return undefined;
+  }
+  const baseIndentRem = level * 0.375;
+  const nestedSectionIndentRem = parentKind === "section" && level > 1 ? 0.875 : 0;
+  return { marginLeft: `${baseIndentRem + nestedSectionIndentRem}rem` };
+}
+
+function SidebarTree({ nodes, route, navigate, level = 0, parentKind = "root" }: { nodes: SidebarNode[]; route: WebAppRoute; navigate: (route: WebAppRoute) => void; level?: number; parentKind?: SidebarTreeParentKind }) {
   const [collapsed, setCollapsed] = useState<Record<string, boolean>>({});
   const [contextMenu, setContextMenu] = useState<{ position: ContextMenuPosition; items: ActionMenuItem[]; title: string } | null>(null);
   return (
@@ -404,21 +417,25 @@ function SidebarTree({ nodes, route, navigate, level = 0 }: { nodes: SidebarNode
         const isCollapsed = collapsed[node.id] ?? node.defaultCollapsed ?? false;
         if (node.type === "section") {
           return (
-            <section className="wapp-sidebar-section" key={node.id}>
-              <div className="wapp-sidebar-section-title" style={{ marginLeft: level ? `${level * 0.375}rem` : undefined }}>
-                <button type="button" aria-expanded={!isCollapsed} aria-label={`${isCollapsed ? "Expand" : "Collapse"} ${node.title}`} onClick={() => setCollapsed((current) => ({ ...current, [node.id]: !isCollapsed }))}>
-                  <span>{isCollapsed ? "▶" : "▼"}</span>{node.title}
-                </button>
-                {node.action ? <button type="button" className="wapp-sidebar-action" onClick={node.action.onAction ?? (() => node.action?.route && navigate(node.action.route))}>{node.action.label ?? "New"}</button> : null}
+            <section className={`wapp-sidebar-section ${level === 0 ? "top" : "nested"}`} key={node.id}>
+              <div className="wapp-sidebar-section-title" style={sidebarIndentStyle(level, parentKind)}>
+                {hasChildren ? (
+                  <button type="button" aria-expanded={!isCollapsed} aria-label={`${isCollapsed ? "Expand" : "Collapse"} ${node.title}`} onClick={() => setCollapsed((current) => ({ ...current, [node.id]: !isCollapsed }))}>
+                    <span>{isCollapsed ? "▶" : "▼"}</span>{node.title}
+                  </button>
+                ) : (
+                  <div className="wapp-sidebar-section-label">{node.title}</div>
+                )}
+                {node.action ? <button type="button" className="wapp-sidebar-action" title={node.action.title} aria-label={node.action.title} onClick={node.action.onAction ?? (() => node.action?.route && navigate(node.action.route))}>{node.action.label ?? "New"}</button> : null}
               </div>
-              {!isCollapsed && node.children ? <SidebarTree nodes={node.children} route={route} navigate={navigate} level={level + 1} /> : null}
-              {!isCollapsed && !node.children?.length ? <div className="wapp-sidebar-empty">No items.</div> : null}
+              {!isCollapsed && hasChildren ? <SidebarTree nodes={node.children ?? []} route={route} navigate={navigate} level={level + 1} parentKind="section" /> : null}
+              {!isCollapsed && !hasChildren && level === 0 ? <div className="wapp-sidebar-empty">No items.</div> : null}
             </section>
           );
         }
         const active = node.route?.view === route.view && Object.entries(node.route).every(([key, value]) => key === "view" || route[key] === value);
         return (
-          <div className={`wapp-sidebar-item-wrap ${hasChildren ? "has-toggle" : ""}`} key={node.id} style={{ marginLeft: level ? `${level * 0.375}rem` : undefined }}>
+          <div className={`wapp-sidebar-item-wrap ${hasChildren ? "has-toggle" : ""}`} key={node.id} style={sidebarIndentStyle(level, parentKind)}>
             {hasChildren ? <button type="button" className="wapp-tree-toggle" aria-expanded={!isCollapsed} aria-label={`${isCollapsed ? "Expand" : "Collapse"} ${node.title}`} onClick={() => setCollapsed((current) => ({ ...current, [node.id]: !isCollapsed }))}>{isCollapsed ? "▶" : "▼"}</button> : null}
             <button
               type="button"
@@ -434,9 +451,9 @@ function SidebarTree({ nodes, route, navigate, level = 0 }: { nodes: SidebarNode
                 <strong>{node.title}</strong>
                 {node.subtitle ? <small>{node.subtitle}</small> : null}
               </span>
-              {node.badge ? <Badge variant={node.badgeVariant}>{node.badge}</Badge> : null}
+              {node.badge ? <Badge variant={node.badgeVariant} className="wapp-sidebar-badge" title={node.badge} aria-label={node.badge}> </Badge> : null}
             </button>
-            {!isCollapsed && node.children ? <div className="wapp-sidebar-children"><SidebarTree nodes={node.children} route={route} navigate={navigate} level={level + 1} /></div> : null}
+            {!isCollapsed && node.children ? <div className="wapp-sidebar-children"><SidebarTree nodes={node.children} route={route} navigate={navigate} level={level + 1} parentKind="item" /></div> : null}
           </div>
         );
       })}
@@ -454,6 +471,10 @@ function renderSettingsActions(actions: SettingsRow["actions"]): ReactNode {
 }
 
 function StructuredSettingsSection({ section }: { section: SettingsSection }) {
+  if (!section.rows?.length && section.render) {
+    return <section className="wapp-custom-settings-section">{section.render()}</section>;
+  }
+
   return (
     <FormSection title={section.title} description={section.description}>
       {section.rows?.map((row) => {
@@ -870,7 +891,7 @@ function SettingsView({ config, refresh, customSections, theme, setTheme }: { co
   );
 }
 
-export function WebAppRoot({ appName, homeRoute, sidebar, routes, header, settings, version }: WebAppRootProps) {
+export function WebAppRoot({ appName, homeRoute, sidebar, routes, header, onRouteChange, settings, version }: WebAppRootProps) {
   const { config, error, refresh } = useConfig();
   const { route, navigate } = useRoute(homeRoute);
   const { theme, setTheme } = useTheme();
@@ -938,6 +959,10 @@ export function WebAppRoot({ appName, homeRoute, sidebar, routes, header, settin
       .catch(() => undefined);
   }, [config?.currentUser?.id, setTheme]);
 
+  useEffect(() => {
+    onRouteChange?.(route);
+  }, [onRouteChange, route]);
+
   if (error) {
     return <main className="wapp-auth-screen"><Panel title="Unable to load app" description={error} /></main>;
   }
@@ -968,13 +993,14 @@ export function WebAppRoot({ appName, homeRoute, sidebar, routes, header, settin
   const topActions = sidebar.topActions?.slice(0, 2) ?? [];
   const defaultTitle = route.view === "settings" ? "Settings" : route.view === homeRoute.view ? appName : route.view.replace(/-/g, " ");
   const headerContext = { route, defaultTitle };
-  const activePinnableNode = allPinnableItems.find((node) => routeMatches(node.route, route));
-  const activePinningAction = activePinnableNode ? pinningActionFor(activePinnableNode) : undefined;
+  const activeSidebarNode = flattenSidebarItems(nodes).find((node) => routeMatches(node.route, route));
+  const activeSidebarActions = activeSidebarNode?.actions ?? [];
   const headerActions = [
     ...(header?.getActions?.(headerContext) ?? []),
-    ...(activePinningAction ? [activePinningAction] : []),
+    ...activeSidebarActions,
   ];
   const headerTitle = header?.renderTitle?.(headerContext) ?? defaultTitle;
+  const primaryHeaderActions = header?.renderActions?.(headerContext);
   const headerActionLabel = typeof headerTitle === "string" ? headerTitle : defaultTitle;
 
   return (
@@ -992,8 +1018,8 @@ export function WebAppRoot({ appName, homeRoute, sidebar, routes, header, settin
         <div className="wapp-sidebar-scroll">
           {sidebarSearchEnabled ? <label className="wapp-search"><span className="sr-only">Search</span><input value={search} onChange={(event) => setSearch(event.target.value)} placeholder="Search" /></label> : null}
           <SidebarTree nodes={nodes} route={route} navigate={(next) => { navigate(next); setSidebarOpen(false); }} />
+          <div className="wapp-sidebar-footer">v{effectiveVersion}<button type="button" aria-label="Reload" onClick={() => window.location.reload()}><Icon name="refresh" /></button></div>
         </div>
-        <div className="wapp-sidebar-footer">v{effectiveVersion}<button type="button" aria-label="Reload" onClick={() => window.location.reload()}><Icon name="refresh" /></button></div>
       </aside>
       <section className="wapp-main">
         <header className="wapp-main-header">
@@ -1001,9 +1027,10 @@ export function WebAppRoot({ appName, homeRoute, sidebar, routes, header, settin
             {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>}
             <h1>{headerTitle}</h1>
           </div>
-          {headerActions.length ? (
+          {primaryHeaderActions || headerActions.length ? (
             <div className="wapp-main-header-actions">
-              <ActionMenu items={headerActions} ariaLabel={`Actions for ${headerActionLabel}`} />
+              {primaryHeaderActions}
+              {headerActions.length ? <ActionMenu items={headerActions} ariaLabel={`Actions for ${headerActionLabel}`} /> : null}
             </div>
           ) : null}
         </header>