@pablozaiden/webapp 0.6.0 → 0.6.2

package/src/web/settings/account-section.tsx

@@ -1,19 +1,44 @@
-import type { ThemePreference, WebAppConfigResponse } from "../../contracts";
+import { useState } from "react";
+import type { LogLevelName, WebAppConfigResponse } from "../../contracts";
 import { appJson } from "../api-client";
 import { Badge, Button, ErrorState, FormSection, LoadingState, SelectField } from "../components";
+import { useLogLevel } from "../log-level";
+import { isThemePreference, useTheme } from "../theme";
+
+const LOG_LEVEL_NAMES = ["trace", "debug", "info", "warn", "error"] as const satisfies readonly LogLevelName[];
+
+function isLogLevelName(value: string): value is LogLevelName {
+  return LOG_LEVEL_NAMES.some((level) => level === value);
+}
 
 export interface AccountSectionProps {
   config: WebAppConfigResponse;
-  theme: ThemePreference;
-  setTheme: (theme: ThemePreference) => void;
-  themeLoading: boolean;
-  themeLoadError?: Error;
-  retryThemeLoad: () => Promise<void>;
   refresh: () => Promise<void>;
   setError: (error: string | undefined) => void;
 }
 
-export function AccountSection({ config, theme, setTheme, themeLoading, themeLoadError, retryThemeLoad, refresh, setError }: AccountSectionProps) {
+export function AccountSection({ config, refresh, setError }: AccountSectionProps) {
+  const { preference, setPreference, loading, error, retry } = useTheme();
+  const logLevel = useLogLevel();
+  const [logLevelSaving, setLogLevelSaving] = useState(false);
+
+  async function updateLogLevel(value: string) {
+    if (!isLogLevelName(value)) {
+      setError(`Unknown log level: ${value}`);
+      return;
+    }
+    try {
+      setError(undefined);
+      setLogLevelSaving(true);
+      await appJson<unknown>("/api/preferences/log-level", { method: "PUT", body: JSON.stringify({ level: value }) });
+      await refresh();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setLogLevelSaving(false);
+    }
+  }
+
   return (
     <>
       {config.currentUser ? (
@@ -22,29 +47,47 @@ export function AccountSection({ config, theme, setTheme, themeLoading, themeLoa
         </FormSection>
       ) : null}
       <FormSection title="Display Settings">
-        <SelectField label="Theme" value={theme} onChange={(event) => {
-          const next = event.currentTarget.value as ThemePreference;
-          setTheme(next);
+        <SelectField label="Theme" value={preference} onChange={(event) => {
+          const next = event.currentTarget.value;
+          if (!isThemePreference(next)) {
+            setError(`Unknown theme preference: ${next}`);
+            return;
+          }
+          setPreference(next);
           void appJson("/api/preferences/theme", { method: "PUT", body: JSON.stringify({ theme: next }) }).catch((err) => setError(String(err)));
         }}>
           <option value="system">System</option>
           <option value="light">Light</option>
           <option value="dark">Dark</option>
         </SelectField>
-        {themeLoading ? <LoadingState title="Loading saved theme" /> : null}
-        {themeLoadError ? (
+        {loading ? <LoadingState title="Loading saved theme" /> : null}
+        {error ? (
           <ErrorState
-            description={themeLoadError.message}
-            action={<Button type="button" loading={themeLoading} onClick={() => void retryThemeLoad()}>Retry</Button>}
+            description={error.message}
+            action={<Button type="button" loading={loading} onClick={() => void retry()}>Retry</Button>}
           />
         ) : null}
       </FormSection>
 
       {config.currentUser?.isAdmin ? (
         <FormSection title="Developer Settings">
-          <SelectField label={config.logLevel.fromEnv ? `Log level (${config.logLevel.level}, controlled by env)` : "Log level"} value={config.logLevel.level} disabled={config.logLevel.fromEnv} onChange={(event) => void appJson("/api/preferences/log-level", { method: "PUT", body: JSON.stringify({ level: event.currentTarget.value }) }).then(refresh)}>
-            {["trace", "debug", "info", "warn", "error"].map((level) => <option key={level} value={level}>{level}</option>)}
-          </SelectField>
+          {logLevel.error ? (
+            <ErrorState
+              description={logLevel.error.message}
+              action={<Button type="button" loading={logLevel.loading} onClick={() => void logLevel.retry()}>Retry</Button>}
+            />
+          ) : null}
+          {logLevel.loading && logLevel.level === undefined ? <LoadingState title="Loading log level" /> : null}
+          {logLevel.level !== undefined ? (
+            <SelectField
+              label={logLevel.fromEnv ? `Log level (${logLevel.level}, controlled by env)` : "Log level"}
+              value={logLevel.level}
+              disabled={logLevel.fromEnv === true || logLevel.loading || logLevelSaving}
+              onChange={(event) => void updateLogLevel(event.currentTarget.value)}
+            >
+              {LOG_LEVEL_NAMES.map((level) => <option key={level} value={level}>{level}</option>)}
+            </SelectField>
+          ) : null}
         </FormSection>
       ) : null}
     </>

package/src/web/settings/settings-view.tsx

@@ -1,5 +1,5 @@
 import { useState, type ReactNode } from "react";
-import type { ThemePreference, WebAppConfigResponse } from "../../contracts";
+import type { WebAppConfigResponse } from "../../contracts";
 import { Button, DangerZone, FormSection } from "../components";
 import type { SettingsRow, SettingsScope, SettingsSection } from "../root-types";
 import { AccountSection } from "./account-section";
@@ -64,20 +64,15 @@ export interface SettingsViewProps {
   config: WebAppConfigResponse;
   refresh: () => Promise<void>;
   customSections: SettingsSection[];
-  theme: ThemePreference;
-  setTheme: (theme: ThemePreference) => void;
-  themeLoading: boolean;
-  themeLoadError?: Error;
-  retryThemeLoad: () => Promise<void>;
 }
 
-export function SettingsView({ config, refresh, customSections, theme, setTheme, themeLoading, themeLoadError, retryThemeLoad }: SettingsViewProps) {
+export function SettingsView({ config, refresh, customSections }: SettingsViewProps) {
   const [error, setError] = useState<string>();
 
   return (
     <div className="wapp-settings">
       {error ? <p className="wapp-error">{error}</p> : null}
-      <AccountSection config={config} theme={theme} setTheme={setTheme} themeLoading={themeLoading} themeLoadError={themeLoadError} retryThemeLoad={retryThemeLoad} refresh={refresh} setError={setError} />
+      <AccountSection config={config} refresh={refresh} setError={setError} />
       <FormSection title="Security">
         <SecuritySection config={config} refresh={refresh} setError={setError} />
         <SessionsSection config={config} setError={setError} />

package/src/web/styles.css

@@ -11,6 +11,18 @@
   --wapp-muted-2: #64748b;
   --wapp-danger: #991b1b;
   --wapp-danger-bg: #991b1b;
+  --wapp-toast-success: #166534;
+  --wapp-toast-success-surface: #f0fdf4;
+  --wapp-toast-success-border: #86efac;
+  --wapp-toast-error: #991b1b;
+  --wapp-toast-error-surface: #fef2f2;
+  --wapp-toast-error-border: #fca5a5;
+  --wapp-toast-warning: #92400e;
+  --wapp-toast-warning-surface: #fffbeb;
+  --wapp-toast-warning-border: #fcd34d;
+  --wapp-toast-info: #1e40af;
+  --wapp-toast-info-surface: #eff6ff;
+  --wapp-toast-info-border: #93c5fd;
   --wapp-primary: #111827;
   --wapp-shadow: 0 1px 2px 0 rgb(0 0 0 / 0.05);
   --wapp-overlay-bg: rgb(0 0 0 / 0.5);
@@ -49,6 +61,18 @@
   --wapp-muted-2: #71717a;
   --wapp-danger: #fca5a5;
   --wapp-danger-bg: #7f1d1d;
+  --wapp-toast-success: #bbf7d0;
+  --wapp-toast-success-surface: #14532d;
+  --wapp-toast-success-border: #166534;
+  --wapp-toast-error: #fecaca;
+  --wapp-toast-error-surface: #7f1d1d;
+  --wapp-toast-error-border: #991b1b;
+  --wapp-toast-warning: #fde68a;
+  --wapp-toast-warning-surface: #78350f;
+  --wapp-toast-warning-border: #92400e;
+  --wapp-toast-info: #bfdbfe;
+  --wapp-toast-info-surface: #1e3a8a;
+  --wapp-toast-info-border: #1e40af;
   --wapp-primary: #f9fafb;
   --wapp-shadow: none;
 }
@@ -1453,6 +1477,110 @@ textarea::placeholder {
   color: var(--wapp-danger);
 }
 
+.wapp-toast-viewport {
+  position: fixed;
+  right: max(1rem, var(--wapp-safe-area-right));
+  bottom: max(1rem, var(--wapp-safe-area-bottom));
+  z-index: 70;
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  gap: 0.5rem;
+  width: min(24rem, calc(100vw - 2rem));
+  max-height: calc(var(--wapp-viewport-height) - 2rem);
+  overflow-y: auto;
+  padding: 0.25rem;
+  pointer-events: none;
+}
+
+.wapp-toast {
+  display: flex;
+  align-items: flex-start;
+  gap: 0.75rem;
+  min-width: 0;
+  border: 1px solid var(--wapp-border);
+  border-radius: 0.75rem;
+  background: var(--wapp-surface);
+  color: var(--wapp-text);
+  padding: 0.75rem;
+  box-shadow: 0 8px 24px rgb(0 0 0 / 0.14);
+  pointer-events: auto;
+  animation: wapp-toast-enter 160ms ease-out;
+}
+
+.wapp-toast-success {
+  border-color: var(--wapp-toast-success-border);
+  background: var(--wapp-toast-success-surface);
+  color: var(--wapp-toast-success);
+}
+
+.wapp-toast-error {
+  border-color: var(--wapp-toast-error-border);
+  background: var(--wapp-toast-error-surface);
+  color: var(--wapp-toast-error);
+}
+
+.wapp-toast-warning {
+  border-color: var(--wapp-toast-warning-border);
+  background: var(--wapp-toast-warning-surface);
+  color: var(--wapp-toast-warning);
+}
+
+.wapp-toast-info {
+  border-color: var(--wapp-toast-info-border);
+  background: var(--wapp-toast-info-surface);
+  color: var(--wapp-toast-info);
+}
+
+.wapp-toast-message {
+  min-width: 0;
+  flex: 1 1 auto;
+  overflow-wrap: anywhere;
+  color: inherit;
+  font-size: 0.875rem;
+  line-height: 1.35;
+}
+
+.wapp-toast-dismiss {
+  display: inline-flex;
+  flex: 0 0 1.75rem;
+  align-items: center;
+  justify-content: center;
+  width: 1.75rem;
+  height: 1.75rem;
+  border: 0;
+  border-radius: 0.5rem;
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+  font-size: 1.25rem;
+  line-height: 1;
+}
+
+.wapp-toast-dismiss:hover,
+.wapp-toast-dismiss:focus-visible {
+  background: rgb(0 0 0 / 0.1);
+  outline: none;
+}
+
+@keyframes wapp-toast-enter {
+  from {
+    opacity: 0;
+    transform: translateY(0.5rem);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .wapp-toast {
+    animation: none;
+  }
+}
+
 .wapp-notice {
   color: var(--wapp-muted);
 }
@@ -1961,6 +2089,14 @@ textarea::placeholder {
   margin-top: 0.75rem;
 }
 
+:root[data-wapp-mobile] .wapp-toast-viewport {
+  right: max(0.75rem, var(--wapp-safe-area-right));
+  bottom: max(0.75rem, var(--wapp-safe-area-bottom));
+  left: max(0.75rem, var(--wapp-safe-area-left));
+  width: auto;
+  max-height: calc(var(--wapp-viewport-height) - 1.5rem);
+}
+
 @media (max-width: 640px) {
   .wapp-settings .wapp-list-row {
     display: grid;

package/src/web/theme.tsx

@@ -0,0 +1,147 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import type { ThemePreference } from "../contracts";
+import { appJson } from "./api-client";
+
+const THEME_STORAGE_KEY = "webapp.theme";
+const THEME_MEDIA_QUERY = "(prefers-color-scheme: dark)";
+
+export type ResolvedTheme = "light" | "dark";
+
+export interface WebAppThemeState {
+  preference: ThemePreference;
+  resolvedTheme: ResolvedTheme;
+  setPreference: (preference: ThemePreference) => void;
+  loading: boolean;
+  error?: Error;
+  retry: () => Promise<void>;
+}
+
+const ThemeContext = createContext<WebAppThemeState | null>(null);
+
+export function isThemePreference(value: unknown): value is ThemePreference {
+  return value === "system" || value === "light" || value === "dark";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readStoredPreference(): ThemePreference {
+  if (typeof window === "undefined") {
+    return "system";
+  }
+
+  const stored = window.localStorage.getItem(THEME_STORAGE_KEY);
+  return isThemePreference(stored) ? stored : "system";
+}
+
+function readSystemTheme(): ResolvedTheme {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return "light";
+  }
+  return window.matchMedia(THEME_MEDIA_QUERY).matches ? "dark" : "light";
+}
+
+function parseThemeResponse(value: unknown): ThemePreference {
+  if (!isRecord(value) || !isThemePreference(value.theme)) {
+    throw new Error("Theme preference response was invalid.");
+  }
+  return value.theme;
+}
+
+function toError(value: unknown): Error {
+  return value instanceof Error ? value : new Error(String(value));
+}
+
+export function useTheme(): WebAppThemeState {
+  const context = useContext(ThemeContext);
+  if (!context) {
+    throw new Error("useTheme must be used within the framework WebAppRoot.");
+  }
+  return context;
+}
+
+export function ThemeProvider({ userId, children }: { userId?: string; children: ReactNode }) {
+  const [preference, setPreferenceState] = useState<ThemePreference>(readStoredPreference);
+  const [systemTheme, setSystemTheme] = useState<ResolvedTheme>(readSystemTheme);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error>();
+  const requestIdRef = useRef(0);
+
+  useEffect(() => {
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+      return;
+    }
+
+    const query = window.matchMedia(THEME_MEDIA_QUERY);
+    const sync = () => setSystemTheme(query.matches ? "dark" : "light");
+    sync();
+    query.addEventListener("change", sync);
+    return () => query.removeEventListener("change", sync);
+  }, []);
+
+  const setPreference = useCallback((nextPreference: ThemePreference) => {
+    if (!isThemePreference(nextPreference)) {
+      throw new TypeError(`Unknown theme preference: ${String(nextPreference)}.`);
+    }
+    setPreferenceState(nextPreference);
+  }, []);
+
+  const resolvedTheme = preference === "system" ? systemTheme : preference;
+
+  useEffect(() => {
+    if (typeof document === "undefined") {
+      return;
+    }
+
+    const root = document.documentElement;
+    root.classList.toggle("dark", resolvedTheme === "dark");
+    root.style.colorScheme = resolvedTheme;
+    root.dataset.theme = preference;
+    root.dataset.resolvedTheme = resolvedTheme;
+    window.localStorage.setItem(THEME_STORAGE_KEY, preference);
+  }, [preference, resolvedTheme]);
+
+  const retry = useCallback(async () => {
+    const requestId = requestIdRef.current + 1;
+    requestIdRef.current = requestId;
+    if (!userId) {
+      setLoading(false);
+      setError(undefined);
+      return;
+    }
+
+    setLoading(true);
+    setError(undefined);
+    try {
+      const response = await appJson<unknown>("/api/preferences/theme");
+      if (requestId !== requestIdRef.current) {
+        return;
+      }
+      setPreference(parseThemeResponse(response));
+    } catch (value) {
+      if (requestId === requestIdRef.current) {
+        setError(toError(value));
+      }
+    } finally {
+      if (requestId === requestIdRef.current) {
+        setLoading(false);
+      }
+    }
+  }, [setPreference, userId]);
+
+  useEffect(() => {
+    void retry();
+  }, [retry]);
+
+  const state = useMemo<WebAppThemeState>(() => ({
+    preference,
+    resolvedTheme,
+    setPreference,
+    loading,
+    error,
+    retry,
+  }), [error, loading, preference, resolvedTheme, retry, setPreference]);
+
+  return <ThemeContext.Provider value={state}>{children}</ThemeContext.Provider>;
+}

package/src/web/toast.tsx

@@ -0,0 +1,218 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import { createPortal } from "react-dom";
+
+export type ToastVariant = "success" | "error" | "warning" | "info";
+export type ToastId = string;
+
+export interface Toast {
+  id: ToastId;
+  message: string;
+  variant: ToastVariant;
+  duration: number;
+}
+
+export interface ToastOptions {
+  id?: ToastId;
+  duration?: number;
+}
+
+export interface ToastShowOptions extends ToastOptions {
+  variant?: ToastVariant;
+}
+
+export interface ToastService {
+  toasts: readonly Toast[];
+  show: (message: string, options?: ToastShowOptions) => ToastId;
+  success: (message: string, options?: ToastOptions) => ToastId;
+  error: (message: string, options?: ToastOptions) => ToastId;
+  warning: (message: string, options?: ToastOptions) => ToastId;
+  info: (message: string, options?: ToastOptions) => ToastId;
+  dismiss: (id: ToastId) => void;
+  dismissAll: () => void;
+}
+
+const DEFAULT_TOAST_DURATION_MS = 8_000;
+const MAX_TOASTS = 5;
+
+const ToastContext = createContext<ToastService | null>(null);
+
+function isToastVariant(value: unknown): value is ToastVariant {
+  return value === "success" || value === "error" || value === "warning" || value === "info";
+}
+
+function normalizeMessage(message: string): string {
+  if (typeof message !== "string") {
+    throw new TypeError("Toast messages must be strings.");
+  }
+  return message;
+}
+
+function normalizeId(id: ToastId | undefined, nextId: () => ToastId): ToastId {
+  if (id === undefined) {
+    return nextId();
+  }
+  if (typeof id !== "string" || id.length === 0) {
+    throw new TypeError("Toast IDs must be non-empty strings.");
+  }
+  return id;
+}
+
+function normalizeDuration(duration: number | undefined): number {
+  if (duration === undefined) {
+    return DEFAULT_TOAST_DURATION_MS;
+  }
+  if (!Number.isFinite(duration) || duration < 0) {
+    throw new RangeError("Toast duration must be a finite, non-negative number.");
+  }
+  return duration;
+}
+
+function ToastViewport({ toasts, onDismiss }: { toasts: Toast[]; onDismiss: (id: ToastId) => void }) {
+  if (toasts.length === 0) {
+    return null;
+  }
+
+  return createPortal(
+    <div className="wapp-toast-viewport" role="region" aria-label="Notifications">
+      {toasts.map((toast) => {
+        const isError = toast.variant === "error";
+        return (
+          <div
+            key={toast.id}
+            className={`wapp-toast wapp-toast-${toast.variant}`}
+            data-toast-variant={toast.variant}
+            role={isError ? "alert" : "status"}
+            aria-live={isError ? "assertive" : "polite"}
+            aria-atomic="true"
+          >
+            <span className="wapp-toast-message">{toast.message}</span>
+            <button type="button" className="wapp-toast-dismiss" aria-label="Dismiss notification" onClick={() => onDismiss(toast.id)}>
+              ×
+            </button>
+          </div>
+        );
+      })}
+    </div>,
+    document.body,
+  );
+}
+
+export function useToast(): ToastService {
+  const context = useContext(ToastContext);
+  if (!context) {
+    throw new Error("useToast must be used within the framework webapp runtime.");
+  }
+  return context;
+}
+
+export function ToastProvider({ children }: { children: ReactNode }) {
+  const [toasts, setToasts] = useState<Toast[]>([]);
+  const timersRef = useRef(new Map<ToastId, ReturnType<typeof setTimeout>>());
+  const nextIdRef = useRef(0);
+
+  const nextId = useCallback((): ToastId => {
+    nextIdRef.current += 1;
+    return `toast-${nextIdRef.current}`;
+  }, []);
+
+  const clearTimer = useCallback((id: ToastId) => {
+    const timer = timersRef.current.get(id);
+    if (timer === undefined) {
+      return;
+    }
+    clearTimeout(timer);
+    timersRef.current.delete(id);
+  }, []);
+
+  const dismiss = useCallback((id: ToastId) => {
+    clearTimer(id);
+    setToasts((current) => current.filter((toast) => toast.id !== id));
+  }, [clearTimer]);
+
+  const dismissAll = useCallback(() => {
+    for (const id of Array.from(timersRef.current.keys())) {
+      clearTimer(id);
+    }
+    setToasts([]);
+  }, [clearTimer]);
+
+  const scheduleDismiss = useCallback((toast: Toast) => {
+    clearTimer(toast.id);
+    if (toast.duration === 0) {
+      return;
+    }
+
+    const timer = setTimeout(() => {
+      if (timersRef.current.get(toast.id) !== timer) {
+        return;
+      }
+      timersRef.current.delete(toast.id);
+      setToasts((current) => current.filter((item) => item.id !== toast.id));
+    }, toast.duration);
+    timersRef.current.set(toast.id, timer);
+  }, [clearTimer]);
+
+  const show = useCallback((message: string, options?: ToastShowOptions): ToastId => {
+    const normalizedMessage = normalizeMessage(message);
+    const variant = options?.variant ?? "info";
+    if (!isToastVariant(variant)) {
+      throw new TypeError(`Unknown toast variant: ${String(variant)}.`);
+    }
+    const id = normalizeId(options?.id, nextId);
+    const duration = normalizeDuration(options?.duration);
+    const toast: Toast = { id, message: normalizedMessage, variant, duration };
+
+    clearTimer(id);
+    setToasts((current) => {
+      const existingIndex = current.findIndex((item) => item.id === id);
+      if (existingIndex >= 0) {
+        const next = [...current];
+        next[existingIndex] = toast;
+        return next;
+      }
+      const next = [...current, toast];
+      return next.length > MAX_TOASTS ? next.slice(next.length - MAX_TOASTS) : next;
+    });
+    scheduleDismiss(toast);
+    return id;
+  }, [clearTimer, nextId, scheduleDismiss]);
+
+  useEffect(() => {
+    const activeIds = new Set(toasts.map((toast) => toast.id));
+    for (const id of timersRef.current.keys()) {
+      if (activeIds.has(id)) {
+        continue;
+      }
+      clearTimer(id);
+    }
+  }, [clearTimer, toasts]);
+
+  useEffect(() => () => {
+    for (const timer of timersRef.current.values()) {
+      clearTimeout(timer);
+    }
+    timersRef.current.clear();
+  }, []);
+
+  const success = useCallback((message: string, options?: ToastOptions) => show(message, { ...options, variant: "success" }), [show]);
+  const error = useCallback((message: string, options?: ToastOptions) => show(message, { ...options, variant: "error" }), [show]);
+  const warning = useCallback((message: string, options?: ToastOptions) => show(message, { ...options, variant: "warning" }), [show]);
+  const info = useCallback((message: string, options?: ToastOptions) => show(message, { ...options, variant: "info" }), [show]);
+  const service = useMemo<ToastService>(() => ({
+    toasts,
+    show,
+    success,
+    error,
+    warning,
+    info,
+    dismiss,
+    dismissAll,
+  }), [dismiss, dismissAll, error, info, show, success, toasts, warning]);
+
+  return (
+    <ToastContext.Provider value={service}>
+      {children}
+      <ToastViewport toasts={toasts} onDismiss={dismiss} />
+    </ToastContext.Provider>
+  );
+}