@pablozaiden/webapp 1.1.1 → 1.3.0

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>
   );

package/src/web/components/index.tsx

@@ -1,6 +1,7 @@
-import { useCallback, useEffect, useId, useLayoutEffect, useRef, useState, type ButtonHTMLAttributes, type CSSProperties, type HTMLAttributes, type InputHTMLAttributes, type MouseEvent as ReactMouseEvent, type ReactNode, type RefObject, type SelectHTMLAttributes, type TextareaHTMLAttributes } from "react";
+import { useCallback, useEffect, useId, useLayoutEffect, useRef, useState, type ButtonHTMLAttributes, type CSSProperties, type HTMLAttributes, type InputHTMLAttributes, type KeyboardEvent as ReactKeyboardEvent, type MouseEvent as ReactMouseEvent, type ReactNode, type RefObject, type SelectHTMLAttributes, type TextareaHTMLAttributes } from "react";
 import { createPortal } from "react-dom";
 import type { ActionMenuItem, BadgeVariant } from "../sidebar/types";
+import { AnimatedList, MOTION_FAST_MS, usePresence } from "../motion";
 
 export type ButtonVariant = "default" | "primary" | "danger" | "ghost";
 export type ButtonSize = "xs" | "sm" | "md" | "lg";
@@ -167,7 +168,7 @@ export function DataList({
   empty?: ReactNode;
   variant?: DataListVariant;
 }) {
-  return <div className={`wapp-data-list wapp-data-list-${variant}`}>{children ?? empty ?? null}</div>;
+  return <AnimatedList className={`wapp-data-list wapp-data-list-${variant}`}>{children ?? empty ?? null}</AnimatedList>;
 }
 
 export function DataListRow({
@@ -276,6 +277,148 @@ export function SegmentedControl<T extends string>({ value, options, onChange, l
   );
 }
 
+export interface TabOption {
+  id: string;
+  label: ReactNode;
+  disabled?: boolean;
+}
+
+export function Tabs({
+  tabs,
+  value,
+  onChange,
+  ariaLabel = "Tabs",
+  panelIdPrefix = "wapp-tab-panel",
+  className = "",
+}: {
+  tabs: TabOption[];
+  value: string;
+  onChange: (id: string) => void;
+  ariaLabel?: string;
+  panelIdPrefix?: string;
+  className?: string;
+}) {
+  const tabRefs = useRef(new Map<string, HTMLButtonElement>());
+
+  const handleKeyDown = (event: ReactKeyboardEvent<HTMLButtonElement>, tabId: string) => {
+    const enabledTabs = tabs.filter((tab) => !tab.disabled);
+    const currentIndex = enabledTabs.findIndex((tab) => tab.id === tabId);
+    if (currentIndex < 0 || enabledTabs.length < 2) {
+      return;
+    }
+
+    let nextIndex = currentIndex;
+    if (event.key === "ArrowRight" || event.key === "ArrowDown") {
+      nextIndex = (currentIndex + 1) % enabledTabs.length;
+    } else if (event.key === "ArrowLeft" || event.key === "ArrowUp") {
+      nextIndex = (currentIndex - 1 + enabledTabs.length) % enabledTabs.length;
+    } else if (event.key === "Home") {
+      nextIndex = 0;
+    } else if (event.key === "End") {
+      nextIndex = enabledTabs.length - 1;
+    } else {
+      return;
+    }
+
+    event.preventDefault();
+    const nextTab = enabledTabs[nextIndex];
+    if (nextTab) {
+      onChange(nextTab.id);
+      const nextElement = tabRefs.current.get(nextTab.id);
+      if (nextElement) {
+        nextElement.focus();
+      }
+    }
+  };
+
+  return (
+    <div className={`wapp-tabs ${className}`.trim()} role="tablist" aria-label={ariaLabel}>
+      {tabs.map((tab) => (
+        <button
+          type="button"
+          key={tab.id}
+          className={`wapp-tab ${value === tab.id ? "active" : ""}`}
+          role="tab"
+          aria-selected={value === tab.id}
+          aria-controls={`${panelIdPrefix}-${tab.id}`}
+          tabIndex={value === tab.id ? 0 : -1}
+          disabled={tab.disabled}
+          ref={(element) => {
+            if (element) {
+              tabRefs.current.set(tab.id, element);
+            } else {
+              tabRefs.current.delete(tab.id);
+            }
+          }}
+          onClick={() => onChange(tab.id)}
+          onKeyDown={(event) => handleKeyDown(event, tab.id)}
+        >
+          {tab.label}
+        </button>
+      ))}
+    </div>
+  );
+}
+
+export function TabPanels({ children, className = "" }: { children: ReactNode; className?: string }) {
+  return <div className={`wapp-tab-panels ${className}`.trim()}>{children}</div>;
+}
+
+export function TabPanel({
+  id,
+  active,
+  labelledBy,
+  children,
+  keepMounted = false,
+  duration = MOTION_FAST_MS,
+  className = "",
+}: {
+  id: string;
+  active: boolean;
+  labelledBy?: string;
+  children: ReactNode;
+  keepMounted?: boolean;
+  duration?: number;
+  className?: string;
+}) {
+  const presence = usePresence(active, { duration });
+  const [keepMountedHidden, setKeepMountedHidden] = useState(!active);
+
+  useEffect(() => {
+    if (!keepMounted || active) {
+      if (active) {
+        setKeepMountedHidden(false);
+      }
+      return;
+    }
+
+    if (presence.reducedMotion || duration <= 0) {
+      setKeepMountedHidden(true);
+      return;
+    }
+
+    const timer = setTimeout(() => setKeepMountedHidden(true), duration);
+    return () => clearTimeout(timer);
+  }, [active, duration, keepMounted, presence.reducedMotion]);
+
+  if (!keepMounted && !presence.mounted) {
+    return null;
+  }
+
+  return (
+    <div
+      id={id}
+      className={`wapp-tab-panel wapp-motion-${presence.state} ${className}`.trim()}
+      role="tabpanel"
+      aria-labelledby={labelledBy}
+      aria-hidden={active ? undefined : true}
+      hidden={keepMounted && keepMountedHidden && !active}
+    >
+      {children}
+    </div>
+  );
+}
+
 export function FormSection({ title, description, children }: { title: string; description?: string; children: ReactNode }) {
   return (
     <section className="wapp-form-section">
@@ -501,6 +644,7 @@ export function Modal({
   closeOnOverlayClick = true,
   className = "",
 }: ModalProps) {
+  const presence = usePresence(isOpen);
   const modalRef = useRef<HTMLDivElement>(null);
   const previousFocusRef = useRef<Element | null>(null);
   const titleId = useId();
@@ -509,7 +653,7 @@ export function Modal({
 
   useDialogKeyboardShortcuts({
     dialogRef: modalRef,
-    enabled: isOpen,
+    enabled: isOpen && presence.mounted,
     onCancel: () => onCloseRef.current(),
   });
 
@@ -560,14 +704,14 @@ export function Modal({
         previousFocusRef.current.focus();
       }
     };
-  }, [handleFocusTrap, isOpen]);
+  }, [handleFocusTrap, isOpen, presence.mounted]);
 
-  if (!isOpen) {
+  if (!presence.mounted) {
     return null;
   }
 
   return createPortal(
-    <div className="wapp-modal-layer">
+    <div className={`wapp-modal-layer wapp-motion-${presence.state}`} aria-hidden={isOpen ? undefined : true}>
       <div
         className="wapp-modal-overlay"
         onClick={closeOnOverlayClick ? onClose : undefined}
@@ -576,7 +720,7 @@ export function Modal({
       <div
         ref={modalRef}
         tabIndex={-1}
-        className={`wapp-modal wapp-modal-${size} ${className}`}
+        className={`wapp-modal wapp-modal-${size} wapp-motion-${presence.state} ${className}`}
         role="dialog"
         aria-modal="true"
         aria-labelledby={titleId}
@@ -660,6 +804,7 @@ export function Dialog({
   children,
   actions,
   onClose,
+  keyboardShortcutsEnabled = true,
   className = "",
 }: {
   title: string;
@@ -667,10 +812,11 @@ export function Dialog({
   children?: ReactNode;
   actions?: ReactNode;
   onClose?: () => void;
+  keyboardShortcutsEnabled?: boolean;
   className?: string;
 }) {
   const dialogRef = useRef<HTMLDivElement>(null);
-  useDialogKeyboardShortcuts({ dialogRef, onCancel: onClose });
+  useDialogKeyboardShortcuts({ dialogRef, enabled: keyboardShortcutsEnabled, onCancel: onClose });
 
   return (
     <div ref={dialogRef} className={`wapp-dialog ${className}`} role="dialog" aria-modal="true" aria-label={title}>
@@ -708,12 +854,15 @@ export function ConfirmDialog({
   onCancel: () => void;
   onConfirm: () => void;
 }) {
-  if (!open) return null;
+  const presence = usePresence(open);
+  if (!presence.mounted) return null;
   return createPortal(
-    <div className="wapp-dialog-backdrop" role="presentation">
+    <div className={`wapp-dialog-backdrop wapp-motion-${presence.state}`} role="presentation" aria-hidden={open ? undefined : true}>
       <Dialog
         title={title}
         onClose={onCancel}
+        keyboardShortcutsEnabled={open && presence.mounted}
+        className={`wapp-motion-${presence.state}`}
         actions={(
           <>
           <Button type="button" variant="ghost" onClick={onCancel}>Cancel</Button>
@@ -762,6 +911,210 @@ function getViewportBounds(): ViewportBounds {
   };
 }
 
+export type FloatingPanelPlacement = "top-start" | "top-end" | "bottom-start" | "bottom-end";
+
+export interface FloatingPanelProps {
+  open: boolean;
+  anchorRef: RefObject<HTMLElement | null>;
+  onClose: () => void;
+  children: ReactNode;
+  ariaLabel?: string;
+  role?: "dialog" | "group" | "menu" | "region";
+  id?: string;
+  placement?: FloatingPanelPlacement;
+  offset?: number;
+  className?: string;
+  style?: CSSProperties;
+  focusSelector?: string;
+  restoreFocusOnClose?: boolean;
+}
+
+function floatingPanelStyle(
+  panel: HTMLDivElement,
+  anchor: HTMLElement,
+  placement: FloatingPanelPlacement,
+  offset: number,
+): CSSProperties {
+  const margin = 8;
+  const viewport = getViewportBounds();
+  const panelRect = panel.getBoundingClientRect();
+  const anchorRect = anchor.getBoundingClientRect();
+  const panelWidth = panelRect.width;
+  const panelHeight = panelRect.height;
+  const maxHeight = Math.max(80, viewport.height - margin * 2);
+  const canPlaceTop = anchorRect.top - panelHeight - offset >= viewport.top + margin;
+  const canPlaceBottom = anchorRect.bottom + panelHeight + offset <= viewport.bottom - margin;
+  const prefersTop = placement.startsWith("top");
+  const placeTop = prefersTop ? (canPlaceTop || !canPlaceBottom) : (!canPlaceBottom && canPlaceTop);
+  const preferredLeft = placement.endsWith("start")
+    ? anchorRect.left
+    : anchorRect.right - panelWidth;
+  const left = Math.max(viewport.left + margin, Math.min(preferredLeft, viewport.right - panelWidth - margin));
+  const preferredTop = placeTop
+    ? anchorRect.top - panelHeight - offset
+    : anchorRect.bottom + offset;
+  const top = Math.max(viewport.top + margin, Math.min(preferredTop, viewport.bottom - panelHeight - margin));
+
+  return {
+    position: "fixed",
+    left,
+    top,
+    maxHeight,
+    overflowY: "auto",
+    visibility: "visible",
+  };
+}
+
+export function FloatingPanel({
+  open,
+  anchorRef,
+  onClose,
+  children,
+  ariaLabel = "Floating panel",
+  role = "dialog",
+  id,
+  placement = "bottom-start",
+  offset = 8,
+  className = "",
+  style,
+  focusSelector,
+  restoreFocusOnClose = false,
+}: FloatingPanelProps) {
+  const presence = usePresence(open);
+  const panelRef = useRef<HTMLDivElement>(null);
+  const positionFrameRef = useRef<number | null>(null);
+  const [panelStyle, setPanelStyle] = useState<CSSProperties | null>(null);
+  const wasOpenRef = useRef(open);
+
+  const updatePosition = useCallback(() => {
+    const panel = panelRef.current;
+    const anchor = anchorRef.current;
+    if (!panel || !anchor) {
+      return;
+    }
+    setPanelStyle(floatingPanelStyle(panel, anchor, placement, offset));
+  }, [anchorRef, offset, placement]);
+
+  const schedulePositionUpdate = useCallback(() => {
+    if (positionFrameRef.current !== null) {
+      return;
+    }
+    positionFrameRef.current = window.requestAnimationFrame(() => {
+      positionFrameRef.current = null;
+      updatePosition();
+    });
+  }, [updatePosition]);
+
+  useLayoutEffect(() => {
+    if (!open || !presence.mounted) {
+      return;
+    }
+
+    updatePosition();
+    schedulePositionUpdate();
+    return () => {
+      if (positionFrameRef.current !== null) {
+        window.cancelAnimationFrame(positionFrameRef.current);
+        positionFrameRef.current = null;
+      }
+    };
+  }, [open, presence.mounted, schedulePositionUpdate, updatePosition]);
+
+  useEffect(() => {
+    if (!presence.mounted) {
+      setPanelStyle(null);
+    }
+  }, [presence.mounted]);
+
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") {
+        event.preventDefault();
+        onClose();
+      }
+    };
+    const handlePointerDown = (event: PointerEvent) => {
+      const panel = panelRef.current;
+      const anchor = anchorRef.current;
+      const path = event.composedPath();
+      if ((panel && path.includes(panel)) || (anchor && path.includes(anchor))) {
+        return;
+      }
+      onClose();
+    };
+    const handleViewportChange = () => schedulePositionUpdate();
+
+    document.addEventListener("keydown", handleKeyDown);
+    document.addEventListener("pointerdown", handlePointerDown);
+    window.addEventListener("resize", handleViewportChange);
+    window.addEventListener("scroll", handleViewportChange, true);
+    window.visualViewport?.addEventListener("resize", handleViewportChange);
+    return () => {
+      document.removeEventListener("keydown", handleKeyDown);
+      document.removeEventListener("pointerdown", handlePointerDown);
+      window.removeEventListener("resize", handleViewportChange);
+      window.removeEventListener("scroll", handleViewportChange, true);
+      window.visualViewport?.removeEventListener("resize", handleViewportChange);
+    };
+  }, [anchorRef, onClose, open, schedulePositionUpdate]);
+
+  useEffect(() => {
+    if (open) {
+      wasOpenRef.current = true;
+      return;
+    }
+    if (!wasOpenRef.current) {
+      return;
+    }
+    wasOpenRef.current = false;
+    if (!restoreFocusOnClose) {
+      return;
+    }
+    const frameId = window.requestAnimationFrame(() => anchorRef.current?.focus());
+    return () => window.cancelAnimationFrame(frameId);
+  }, [anchorRef, open, restoreFocusOnClose]);
+
+  useEffect(() => {
+    if (!open || !presence.mounted || !focusSelector) {
+      return;
+    }
+    const frameId = window.requestAnimationFrame(() => {
+      panelRef.current?.querySelector<HTMLElement>(focusSelector)?.focus();
+    });
+    return () => window.cancelAnimationFrame(frameId);
+  }, [focusSelector, open, presence.mounted]);
+
+  if (!presence.mounted) {
+    return null;
+  }
+
+  const resolvedPanelStyle = panelStyle ?? {
+    position: "fixed" as const,
+    top: -9999,
+    left: -9999,
+    visibility: "hidden" as const,
+  };
+
+  return createPortal(
+    <div
+      ref={panelRef}
+      id={id}
+      className={`wapp-floating-panel wapp-motion-${presence.state} ${className}`.trim()}
+      role={role}
+      aria-label={ariaLabel}
+      aria-hidden={open ? undefined : true}
+      style={{ ...resolvedPanelStyle, ...style }}
+    >
+      {children}
+    </div>,
+    document.body,
+  );
+}
+
 function MenuIcon() {
   return (
     <svg aria-hidden="true" viewBox="0 0 24 24" className="wapp-svg">
@@ -841,6 +1194,7 @@ export function ActionMenu({
   triggerSize?: "default" | "compact";
 }) {
   const [open, setOpen] = useState(false);
+  const presence = usePresence(open);
   const triggerRef = useRef<HTMLButtonElement>(null);
   const menuRef = useRef<HTMLDivElement>(null);
   const [style, setStyle] = useState<CSSProperties>({ position: "fixed", top: -9999, left: -9999 });
@@ -873,7 +1227,7 @@ export function ActionMenu({
         y: triggerRect.bottom + 4,
       }),
     });
-  }, [open]);
+  }, [open, presence.mounted]);
 
   function handleItemClick(item: ActionMenuItem) {
     if (item.disabled) return;
@@ -899,8 +1253,8 @@ export function ActionMenu({
       >
         {trigger ?? <MenuIcon />}
       </button>
-      {open ? createPortal(
-        <div ref={menuRef} className="wapp-action-menu" role="menu" aria-label={ariaLabel} style={style}>
+      {presence.mounted ? createPortal(
+        <div ref={menuRef} className={`wapp-action-menu wapp-motion-${presence.state}`} role="menu" aria-label={ariaLabel} aria-hidden={open ? undefined : true} style={style}>
           <ActionMenuItems items={items} onItemClick={handleItemClick} />
         </div>,
         document.body,
@@ -921,20 +1275,28 @@ export function ContextMenu({
   ariaLabel?: string;
 }) {
   const menuRef = useRef<HTMLDivElement>(null);
+  const presence = usePresence(Boolean(position));
+  const [renderPosition, setRenderPosition] = useState(position);
   const [menuStyle, setMenuStyle] = useState<CSSProperties | null>(position ? hiddenMenuStyle(position) : null);
 
+  useEffect(() => {
+    if (position) {
+      setRenderPosition(position);
+    }
+  }, [position]);
+
   useLayoutEffect(() => {
-    if (!position) {
+    if (!renderPosition) {
       setMenuStyle(null);
       return;
     }
 
     let frameId: number | null = null;
     const updatePosition = () => {
-      setMenuStyle(boundedMenuStyle(menuRef.current, position));
+      setMenuStyle(boundedMenuStyle(menuRef.current, renderPosition));
     };
 
-    setMenuStyle(hiddenMenuStyle(position));
+    setMenuStyle(hiddenMenuStyle(renderPosition));
     updatePosition();
     frameId = window.requestAnimationFrame(updatePosition);
 
@@ -943,7 +1305,7 @@ export function ContextMenu({
         window.cancelAnimationFrame(frameId);
       }
     };
-  }, [items, position]);
+  }, [items, renderPosition]);
 
   useEffect(() => {
     if (!position) return;
@@ -974,7 +1336,7 @@ export function ContextMenu({
     };
   }, [onClose, position]);
 
-  if (!position || !menuStyle) return null;
+  if (!presence.mounted || !renderPosition || !menuStyle) return null;
 
   function handleItemClick(item: ActionMenuItem) {
     if (item.disabled) return;
@@ -985,9 +1347,10 @@ export function ContextMenu({
   return createPortal(
     <div
       ref={menuRef}
-      className="wapp-action-menu"
+      className={`wapp-action-menu wapp-motion-${presence.state}`}
       role="menu"
       aria-label={ariaLabel}
+      aria-hidden={position ? undefined : true}
       style={menuStyle}
       onContextMenu={(event: ReactMouseEvent<HTMLDivElement>) => {
         event.preventDefault();

package/src/web/index.ts

@@ -1,6 +1,8 @@
 export * from "./WebAppRoot";
 export * from "./components";
 export * from "./render";
+export * from "./motion";
+export { supportsViewTransitions } from "./routing";
 export * from "./api-client";
 export * from "./sidebar/types";
 export * from "./realtime/useRealtime";
@@ -11,5 +13,6 @@ export { useTheme } from "./theme";
 export type { ResolvedTheme, WebAppThemeState } from "./theme";
 export { useLogLevel } from "./log-level";
 export type { WebAppLogLevelState } from "./log-level";
+export { createLogger, getLogLevel, log } from "./logger";
 export { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 export type { ThemePreference } from "../contracts";

package/src/web/logger.ts

@@ -0,0 +1,44 @@
+import { Logger, type ILogObj } from "tslog";
+import {
+  DEFAULT_LOG_LEVEL,
+  LOG_LEVEL_NAMES,
+  LOG_LEVELS,
+  VALID_LOG_LEVELS,
+  type LogLevelName,
+} from "../contracts";
+
+const subLoggers = new Map<string, Logger<ILogObj>>();
+
+function isLogLevelName(value: unknown): value is LogLevelName {
+  return typeof value === "string" && VALID_LOG_LEVELS.includes(value as LogLevelName);
+}
+
+export const log = new Logger<ILogObj>({
+  name: "webapp",
+  minLevel: LOG_LEVELS[DEFAULT_LOG_LEVEL],
+});
+
+export function createLogger(scope: string): Logger<ILogObj> {
+  const existing = subLoggers.get(scope);
+  if (existing) {
+    return existing;
+  }
+  const logger = log.getSubLogger({ name: scope });
+  subLoggers.set(scope, logger);
+  return logger;
+}
+
+export function setLogLevel(level: LogLevelName): void {
+  if (!isLogLevelName(level)) {
+    throw new Error(`Invalid log level: ${String(level)}`);
+  }
+  const numericLevel = LOG_LEVELS[level];
+  log.settings.minLevel = numericLevel;
+  for (const subLogger of subLoggers.values()) {
+    subLogger.settings.minLevel = numericLevel;
+  }
+}
+
+export function getLogLevel(): LogLevelName {
+  return LOG_LEVEL_NAMES[log.settings.minLevel] ?? DEFAULT_LOG_LEVEL;
+}