@pablozaiden/webapp 0.5.8 → 0.6.1

package/src/web/root-types.ts

@@ -0,0 +1,61 @@
+import type { ReactNode } from "react";
+import type { ActionMenuItem, SidebarAction, SidebarBuildContext, SidebarNode, WebAppRoute } from "./sidebar/types";
+
+export type SettingsScope = "user" | "admin" | "owner";
+
+export type SettingsAction = {
+  id: string;
+  label: string;
+  variant?: "default" | "primary" | "danger" | "ghost";
+  disabled?: boolean;
+  onAction: () => void;
+};
+
+export type SettingsRow = {
+  id: string;
+  title: string;
+  description?: string;
+  scope?: SettingsScope;
+  content?: ReactNode;
+  actions?: ReactNode | SettingsAction[];
+  danger?: boolean;
+};
+
+export type SettingsSection = {
+  id: string;
+  title: string;
+  description?: string;
+  scope?: SettingsScope;
+  rows?: SettingsRow[];
+  render?: () => ReactNode;
+};
+
+export type HeaderContext = {
+  route: WebAppRoute;
+  defaultTitle: string;
+};
+
+export interface WebAppRootProps {
+  appName: string;
+  homeRoute: WebAppRoute;
+  sidebar: {
+    search?: boolean;
+    topActions?: SidebarAction[];
+    pinning?: false | {
+      sectionTitle?: string;
+      storageKey?: string;
+    };
+    getNodes: (ctx: SidebarBuildContext) => SidebarNode[];
+  };
+  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[];
+  };
+  version?: string;
+}

package/src/web/routing.ts

@@ -0,0 +1,61 @@
+import { useCallback, useEffect, useState } from "react";
+import type { WebAppRoute } from "./sidebar/types";
+
+export function routeToHash(route: WebAppRoute): string {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(route)) {
+    if (key !== "view" && value !== undefined) {
+      params.set(key, String(value));
+    }
+  }
+  return `#/${route.view}${params.size ? `?${params.toString()}` : ""}`;
+}
+
+export function replaceHashRoute(hash: string): boolean {
+  const normalizedHash = hash.startsWith("#") ? hash : `#${hash}`;
+  if (window.location.hash === normalizedHash) {
+    return false;
+  }
+
+  const previousUrl = window.location.href;
+  let hashChangeEmitted = false;
+  const markHashChangeEmitted = () => {
+    hashChangeEmitted = true;
+  };
+  window.addEventListener("hashchange", markHashChangeEmitted, { once: true });
+  window.history.replaceState(window.history.state, "", normalizedHash);
+  window.removeEventListener("hashchange", markHashChangeEmitted);
+  if (!hashChangeEmitted) {
+    window.dispatchEvent(new HashChangeEvent("hashchange", { oldURL: previousUrl, newURL: window.location.href }));
+  }
+  return true;
+}
+
+export function replaceWebAppRoute(route: WebAppRoute): boolean {
+  return replaceHashRoute(routeToHash(route));
+}
+
+function parseRoute(defaultRoute: WebAppRoute): WebAppRoute {
+  const hash = window.location.hash.replace(/^#\/?/, "");
+  if (!hash) {
+    return defaultRoute;
+  }
+  const [view = defaultRoute.view, query = ""] = hash.split("?", 2);
+  const params = Object.fromEntries(new URLSearchParams(query).entries());
+  return { view: view.replace(/^\//, ""), ...params };
+}
+
+export function useRoute(defaultRoute: WebAppRoute) {
+  const [route, setRoute] = useState(() => parseRoute(defaultRoute));
+  useEffect(() => {
+    const listener = () => setRoute(parseRoute(defaultRoute));
+    window.addEventListener("hashchange", listener);
+    return () => window.removeEventListener("hashchange", listener);
+  }, [defaultRoute]);
+  const navigate = useCallback((next: WebAppRoute) => {
+    if (replaceWebAppRoute(next)) {
+      setRoute(next);
+    }
+  }, []);
+  return { route, navigate };
+}

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

@@ -0,0 +1,52 @@
+import type { ThemePreference, WebAppConfigResponse } from "../../contracts";
+import { appJson } from "../api-client";
+import { Badge, Button, ErrorState, FormSection, LoadingState, SelectField } from "../components";
+
+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) {
+  return (
+    <>
+      {config.currentUser ? (
+        <FormSection title="Account">
+          <p>Signed in as <strong>{config.currentUser.username}</strong> <Badge variant={config.currentUser.isAdmin ? "success" : "disabled"}>{config.currentUser.role}</Badge></p>
+        </FormSection>
+      ) : null}
+      <FormSection title="Display Settings">
+        <SelectField label="Theme" value={theme} onChange={(event) => {
+          const next = event.currentTarget.value as ThemePreference;
+          setTheme(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 ? (
+          <ErrorState
+            description={themeLoadError.message}
+            action={<Button type="button" loading={themeLoading} onClick={() => void retryThemeLoad()}>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>
+        </FormSection>
+      ) : null}
+    </>
+  );
+}

package/src/web/settings/resource-state.tsx

@@ -0,0 +1,17 @@
+import type { ReactNode } from "react";
+import { Button, ErrorState, LoadingState } from "../components";
+
+export function ResourceState({ loading, error, hasData, refresh }: { loading: boolean; error?: Error; hasData: boolean; refresh: () => Promise<void> }): ReactNode {
+  if (!hasData && loading) {
+    return <LoadingState />;
+  }
+  if (!error) {
+    return null;
+  }
+  return (
+    <ErrorState
+      description={error.message}
+      action={<Button type="button" loading={loading} onClick={() => void refresh()}>Retry</Button>}
+    />
+  );
+}

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

@@ -0,0 +1,119 @@
+import { startRegistration } from "@simplewebauthn/browser";
+import { useCallback, useState } from "react";
+import type { ApiKeySummary, CreatedApiKeyResponse, WebAppConfigResponse } from "../../contracts";
+import { appJson } from "../api-client";
+import { Button, ConfirmDialog, EmptyState } from "../components";
+import { useLiveQuery } from "../realtime/useRealtime";
+import { ResourceState } from "./resource-state";
+
+export interface SecuritySectionProps {
+  config: WebAppConfigResponse;
+  refresh: () => Promise<void>;
+  setError: (error: string | undefined) => void;
+}
+
+export function SecuritySection({ config, refresh, setError }: SecuritySectionProps) {
+  const [createdToken, setCreatedToken] = useState<string>();
+  const [apiKeyToDelete, setApiKeyToDelete] = useState<ApiKeySummary>();
+  const [confirmDeletePasskey, setConfirmDeletePasskey] = useState(false);
+
+  const loadApiKeys = useCallback(
+    () => config.apiKeys.enabled
+      ? appJson<ApiKeySummary[]>("/api/api-keys")
+      : Promise.resolve<ApiKeySummary[]>([]),
+    [config.apiKeys.enabled],
+  );
+  const { data: apiKeys, error: apiKeysLoadError, loading: apiKeysLoading, refresh: refreshApiKeys } = useLiveQuery<ApiKeySummary[]>({ load: loadApiKeys, realtime: false });
+
+  async function createKey() {
+    const result = await appJson<CreatedApiKeyResponse>("/api/api-keys", { method: "POST", body: JSON.stringify({ name: "Browser key", scopes: ["*"] }) });
+    setCreatedToken(result.token);
+    await refreshApiKeys();
+  }
+
+  async function deleteKey(id: string) {
+    try {
+      setError(undefined);
+      await appJson(`/api/api-keys/${encodeURIComponent(id)}`, { method: "DELETE" });
+      setApiKeyToDelete(undefined);
+      await refreshApiKeys();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  async function setupPasskey() {
+    try {
+      setError(undefined);
+      const options = await appJson<PublicKeyCredentialCreationOptionsJSON>("/api/passkey-auth/owner-setup/options", { method: "POST", body: "{}" });
+      const credential = await startRegistration({ optionsJSON: options as never });
+      await appJson("/api/passkey-auth/owner-setup/verify", { method: "POST", body: JSON.stringify(credential) });
+      await refresh();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  async function logout() {
+    await appJson("/api/passkey-auth/logout", { method: "POST", body: "{}" });
+    await refresh();
+  }
+
+  async function deleteConfiguredPasskey() {
+    await appJson("/api/passkey-auth/passkey", { method: "DELETE" });
+    setConfirmDeletePasskey(false);
+    await refresh();
+  }
+
+  return (
+    <>
+      <div className="wapp-settings-row">
+        <div>
+          <strong>Passkey</strong>
+          <p>{config.passkeyAuth.passkeyConfigured ? "Your passkey protects this account." : "No passkey configured yet."}</p>
+        </div>
+        <div className="wapp-row-actions">
+          {config.passkeyAuth.passkeyConfigured ? (
+            <>
+              <Button type="button" onClick={() => void logout()}>Logout</Button>
+              <Button type="button" variant="danger" onClick={() => setConfirmDeletePasskey(true)}>Delete passkey</Button>
+            </>
+          ) : (
+            config.currentUser?.isOwner ? <Button type="button" variant="primary" onClick={() => void setupPasskey()}>Set up passkey</Button> : null
+          )}
+        </div>
+      </div>
+      {config.apiKeys.enabled ? (
+        <div className="wapp-settings-row stacked">
+          <div>
+            <strong>API keys</strong>
+            <p>Create bearer tokens for scripts and agents.</p>
+          </div>
+          <div className="wapp-row-actions"><Button type="button" onClick={() => void createKey().catch((err) => setError(String(err)))}>Create API key</Button></div>
+          {createdToken ? <code className="wapp-token">{createdToken}</code> : null}
+          <ResourceState loading={apiKeysLoading} error={apiKeysLoadError} hasData={apiKeys !== undefined} refresh={refreshApiKeys} />
+          {apiKeys?.length ? (
+            <div className="wapp-list">
+              {apiKeys.map((key) => (
+                <div className="wapp-list-row" key={key.id}>
+                  <span><strong>{key.name}</strong><small>{key.scopes.join(", ")} · {key.createdAt}</small></span>
+                  <Button type="button" variant="danger" onClick={() => setApiKeyToDelete(key)}>Delete</Button>
+                </div>
+              ))}
+            </div>
+          ) : apiKeys !== undefined && !apiKeysLoadError ? <EmptyState title="No API keys" /> : null}
+        </div>
+      ) : null}
+      <ConfirmDialog
+        open={Boolean(apiKeyToDelete)}
+        title="Delete API key?"
+        message={apiKeyToDelete ? `This permanently deletes "${apiKeyToDelete.name}". Scripts and agents using this token will stop working.` : ""}
+        confirmLabel="Delete API key"
+        danger
+        onCancel={() => setApiKeyToDelete(undefined)}
+        onConfirm={() => apiKeyToDelete && void deleteKey(apiKeyToDelete.id)}
+      />
+      <ConfirmDialog open={confirmDeletePasskey} title="Delete passkey?" message="This removes the configured passkey and invalidates browser sessions." confirmLabel="Delete passkey" danger onCancel={() => setConfirmDeletePasskey(false)} onConfirm={() => void deleteConfiguredPasskey()} />
+    </>
+  );
+}

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

@@ -0,0 +1,66 @@
+import { useCallback, useState } from "react";
+import type { AuthSessionSummary, WebAppConfigResponse } from "../../contracts";
+import { appJson } from "../api-client";
+import { Button, ConfirmDialog, EmptyState } from "../components";
+import { useLiveQuery } from "../realtime/useRealtime";
+import { ResourceState } from "./resource-state";
+
+export interface SessionsSectionProps {
+  config: WebAppConfigResponse;
+  setError: (error: string | undefined) => void;
+}
+
+export function SessionsSection({ config, setError }: SessionsSectionProps) {
+  const [authSessionToRevoke, setAuthSessionToRevoke] = useState<AuthSessionSummary>();
+
+  const loadAuthSessions = useCallback(
+    () => config.deviceAuth.enabled
+      ? appJson<AuthSessionSummary[]>("/api/auth/sessions")
+      : Promise.resolve<AuthSessionSummary[]>([]),
+    [config.deviceAuth.enabled],
+  );
+  const { data: authSessions, error: authSessionsLoadError, loading: authSessionsLoading, refresh: refreshAuthSessions } = useLiveQuery<AuthSessionSummary[]>({ load: loadAuthSessions, realtime: false });
+
+  async function revokeAuthSession(session: AuthSessionSummary) {
+    try {
+      setError(undefined);
+      await appJson(`/api/auth/sessions/${session.id}`, { method: "DELETE" });
+      setAuthSessionToRevoke(undefined);
+      await refreshAuthSessions();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  if (!config.deviceAuth.enabled) {
+    return null;
+  }
+  return (
+    <>
+      <div className="wapp-settings-row stacked">
+        <div>
+          <strong>Device auth sessions</strong>
+          <p>Refresh-token sessions created through the device flow.</p>
+        </div>
+        <ResourceState loading={authSessionsLoading} error={authSessionsLoadError} hasData={authSessions !== undefined} refresh={refreshAuthSessions} />
+        <div className="wapp-list">
+          {authSessions?.length ? authSessions.map((session) => (
+            <div className="wapp-list-row" key={session.id}>
+              <span><strong>{session.clientId}</strong><small>{session.scope} · {session.updatedAt}</small></span>
+              <Button type="button" variant="danger" onClick={() => setAuthSessionToRevoke(session)}>Revoke</Button>
+            </div>
+          )) : authSessions !== undefined && !authSessionsLoadError ? <EmptyState title="No device sessions" /> : null}
+        </div>
+      </div>
+      <ConfirmDialog
+        open={Boolean(authSessionToRevoke)}
+        title="Revoke device session?"
+        message={authSessionToRevoke ? `This revokes the active "${authSessionToRevoke.clientId}" refresh-token session.` : ""}
+        confirmLabel="Revoke session"
+        danger
+        onCancel={() => setAuthSessionToRevoke(undefined)}
+        onConfirm={() => authSessionToRevoke && void revokeAuthSession(authSessionToRevoke)}
+      />
+    </>
+  );
+}

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

@@ -0,0 +1,96 @@
+import { useState, type ReactNode } from "react";
+import type { ThemePreference, WebAppConfigResponse } from "../../contracts";
+import { Button, DangerZone, FormSection } from "../components";
+import type { SettingsRow, SettingsScope, SettingsSection } from "../root-types";
+import { AccountSection } from "./account-section";
+import { SecuritySection } from "./security-section";
+import { SessionsSection } from "./sessions-section";
+import { ShutdownSection } from "./shutdown-section";
+import { UserManagement } from "./user-management";
+
+export type { SettingsAction, SettingsRow, SettingsSection } from "../root-types";
+
+function renderSettingsActions(actions: SettingsRow["actions"]): ReactNode {
+  if (!actions) {
+    return null;
+  }
+  if (!Array.isArray(actions)) {
+    return actions;
+  }
+  return actions.map((action) => (
+    <Button key={action.id} type="button" variant={action.variant} disabled={action.disabled} onClick={action.onAction}>{action.label}</Button>
+  ));
+}
+
+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) => {
+        const actions = renderSettingsActions(row.actions);
+        if (row.danger) {
+          return <DangerZone key={row.id} title={row.title} description={row.description} actions={actions} />;
+        }
+        return (
+          <div className="wapp-settings-row" key={row.id}>
+            <div>
+              <strong>{row.title}</strong>
+              {row.description ? <p>{row.description}</p> : null}
+              {row.content ? <div className="wapp-settings-row-content">{row.content}</div> : null}
+            </div>
+            {actions ? <div className="wapp-row-actions">{actions}</div> : null}
+          </div>
+        );
+      })}
+      {section.render?.()}
+    </FormSection>
+  );
+}
+
+function isScopeVisible(scope: SettingsScope | undefined, config: WebAppConfigResponse): boolean {
+  if (!scope || scope === "user") {
+    return Boolean(config.currentUser);
+  }
+  if (scope === "admin") {
+    return Boolean(config.currentUser?.isAdmin);
+  }
+  return Boolean(config.currentUser?.isOwner);
+}
+
+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) {
+  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} />
+      <FormSection title="Security">
+        <SecuritySection config={config} refresh={refresh} setError={setError} />
+        <SessionsSection config={config} setError={setError} />
+      </FormSection>
+      <UserManagement config={config} />
+      <ShutdownSection config={config} setError={setError} />
+      {customSections.filter((section) => isScopeVisible(section.scope, config)).map((section) => ({
+        ...section,
+        rows: section.rows?.filter((row) => isScopeVisible(row.scope, config)),
+      })).map((section) => <StructuredSettingsSection key={section.id} section={section} />)}
+      <FormSection title="About">
+        <p>{config.appName} {config.version}</p>
+      </FormSection>
+    </div>
+  );
+}

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

@@ -0,0 +1,95 @@
+import { useCallback, useEffect, useState } from "react";
+import type { WebAppConfigResponse } from "../../contracts";
+import { appFetch } from "../api-client";
+import { Button, ConfirmDialog, FormSection } from "../components";
+
+const KILL_SERVER_COUNTDOWN_SECONDS = 15;
+
+function computeProgressPercent(countdown: number, total: number): number {
+  return total <= 0 ? 0 : (countdown / total) * 100;
+}
+
+function useCountdownReload(active: boolean, onComplete: () => void, durationSeconds = KILL_SERVER_COUNTDOWN_SECONDS): { countdown: number; progressPercent: number } {
+  const [countdown, setCountdown] = useState(durationSeconds);
+
+  useEffect(() => {
+    if (!active) {
+      setCountdown(durationSeconds);
+      return;
+    }
+
+    setCountdown(durationSeconds);
+    const interval = window.setInterval(() => {
+      setCountdown((previous) => {
+        const next = previous - 1;
+        if (next <= 0) {
+          window.clearInterval(interval);
+          onComplete();
+          return 0;
+        }
+        return next;
+      });
+    }, 1000);
+
+    return () => window.clearInterval(interval);
+  }, [active, durationSeconds, onComplete]);
+
+  return {
+    countdown,
+    progressPercent: computeProgressPercent(countdown, durationSeconds),
+  };
+}
+
+export function ShutdownSection({ config, setError }: { config: WebAppConfigResponse; setError: (error: string | undefined) => void }) {
+  const [confirmKillServer, setConfirmKillServer] = useState(false);
+  const [killRequested, setKillRequested] = useState(false);
+  const reloadPage = useCallback(() => window.location.reload(), []);
+  const { countdown, progressPercent } = useCountdownReload(killRequested, reloadPage);
+
+  async function killServer() {
+    try {
+      setError(undefined);
+      setConfirmKillServer(false);
+      await appFetch("/api/server/kill", { method: "POST" });
+      setKillRequested(true);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  if (!config.currentUser?.isAdmin) {
+    return null;
+  }
+  return (
+    <>
+      <FormSection title="Server operations">
+        <div className="wapp-settings-row">
+          <div>
+            <strong>Kill server</strong>
+            <p>Stop the server process. If your deployment restarts it automatically, the app will come back after a moment.</p>
+            {killRequested ? (
+              <div className="wapp-shutdown-countdown" aria-live="polite">
+                <div className="wapp-shutdown-message">Server is shutting down... Reloading in {countdown}s</div>
+                <div className="wapp-shutdown-progress" aria-hidden="true">
+                  <div className="wapp-shutdown-progress-bar" style={{ width: `${progressPercent}%` }} />
+                </div>
+              </div>
+            ) : null}
+          </div>
+          <div className="wapp-row-actions">
+            <Button type="button" variant="danger" disabled={killRequested} onClick={() => setConfirmKillServer(true)}>Kill server</Button>
+          </div>
+        </div>
+      </FormSection>
+      <ConfirmDialog
+        open={confirmKillServer}
+        title="Kill server?"
+        message="Are you sure you want to kill the server?"
+        confirmLabel="Kill server"
+        danger
+        onCancel={() => setConfirmKillServer(false)}
+        onConfirm={() => void killServer()}
+      />
+    </>
+  );
+}