@kingsleyweb/bun-ui 0.0.0-stage → 3.0.0-rc.2

package/app/docs/styles/tokens.css

@@ -0,0 +1,143 @@
+/*
+ * Design tokens. Light is the default; dark applies when the OS prefers it
+ * and no theme is forced (`data-theme` absent = "system"), or when
+ * `data-theme="dark"` forces it. `data-theme="light"` forces light.
+ *
+ * Every text/background and control/background pair the app uses is checked
+ * for WCAG AA contrast, in both themes, by `__tests__/app/a11y/contrast.test.ts`
+ * (parsed from this file): change a colour and that test says whether it
+ * still reads.
+ */
+:root {
+  color-scheme: light;
+
+  --font-sans:
+    system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial,
+    sans-serif;
+  --font-mono:
+    ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace;
+
+  --space-1: 4px;
+  --space-2: 8px;
+  --space-3: 12px;
+  --space-4: 16px;
+  --space-5: 24px;
+  --space-6: 32px;
+
+  --radius-sm: 4px;
+  --radius: 8px;
+  --radius-pill: 999px;
+
+  --text-xs: 0.75rem;
+  --text-sm: 0.8125rem;
+  --text-md: 0.9375rem;
+  --text-lg: 1.125rem;
+  --text-xl: 1.5rem;
+
+  --bg: #f6f7f9;
+  --surface: #ffffff;
+  --surface-2: #f0f2f5;
+  --border: #d9dde3;
+  /* A control's outline (inputs): 3:1 against the surfaces, WCAG 1.4.11. */
+  --border-strong: #838c99;
+  --text: #1b1f24;
+  --text-muted: #5b6573;
+  --accent: #2957c7;
+  --accent-contrast: #ffffff;
+  --focus: #2957c7;
+  --danger: #b42318;
+  --danger-contrast: #ffffff;
+  --warning-bg: #fff4d6;
+  --warning-text: #7a4b00;
+  --info-bg: #e3ecff;
+  --info-text: #1f3f8f;
+  --success-bg: #ddf5e6;
+  --success-text: #13603a;
+  --danger-bg: #fde5e3;
+  --danger-text: #92211a;
+  --neutral-bg: #eceff3;
+  --neutral-text: #3b4450;
+
+  /* Job states: a line/dot colour each. */
+  --state-waiting: #2f6fdb;
+  --state-delayed: #7a4fcf;
+  --state-active: #0f8a8a;
+  --state-completed: #238a4a;
+  --state-failed: #d4541a;
+  --state-dead: #b42318;
+  --state-waiting-children: #7a6a1f;
+
+  --shadow: 0 1px 2px rgb(16 24 40 / 6%), 0 1px 3px rgb(16 24 40 / 8%);
+  --header-height: 56px;
+  --nav-width: 200px;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    color-scheme: dark;
+    --bg: #0f1216;
+    --surface: #171b21;
+    --surface-2: #1e232b;
+    --border: #2d343e;
+    --border-strong: #65717f;
+    --text: #e6e9ee;
+    --text-muted: #9aa4b2;
+    --accent: #7ea2ff;
+    --accent-contrast: #0b1020;
+    --focus: #7ea2ff;
+    --danger: #ff7b70;
+    --danger-contrast: #1a0806;
+    --warning-bg: #3a2c0a;
+    --warning-text: #ffd27a;
+    --info-bg: #182646;
+    --info-text: #b7caff;
+    --success-bg: #11301f;
+    --success-text: #8fe0ad;
+    --danger-bg: #3d1512;
+    --danger-text: #ffb4ad;
+    --neutral-bg: #242a33;
+    --neutral-text: #c9d0da;
+    --state-waiting: #6f9ef0;
+    --state-delayed: #b08cf0;
+    --state-active: #3cc4c4;
+    --state-completed: #52c47f;
+    --state-failed: #f08a52;
+    --state-dead: #ff7b70;
+    --state-waiting-children: #cdb64a;
+    --shadow: 0 1px 2px rgb(0 0 0 / 40%);
+  }
+}
+
+:root[data-theme="dark"] {
+  color-scheme: dark;
+  --bg: #0f1216;
+  --surface: #171b21;
+  --surface-2: #1e232b;
+  --border: #2d343e;
+  --border-strong: #65717f;
+  --text: #e6e9ee;
+  --text-muted: #9aa4b2;
+  --accent: #7ea2ff;
+  --accent-contrast: #0b1020;
+  --focus: #7ea2ff;
+  --danger: #ff7b70;
+  --danger-contrast: #1a0806;
+  --warning-bg: #3a2c0a;
+  --warning-text: #ffd27a;
+  --info-bg: #182646;
+  --info-text: #b7caff;
+  --success-bg: #11301f;
+  --success-text: #8fe0ad;
+  --danger-bg: #3d1512;
+  --danger-text: #ffb4ad;
+  --neutral-bg: #242a33;
+  --neutral-text: #c9d0da;
+  --state-waiting: #6f9ef0;
+  --state-delayed: #b08cf0;
+  --state-active: #3cc4c4;
+  --state-completed: #52c47f;
+  --state-failed: #f08a52;
+  --state-dead: #ff7b70;
+  --state-waiting-children: #cdb64a;
+  --shadow: 0 1px 2px rgb(0 0 0 / 40%);
+}

package/app/docs/theme.ts

@@ -0,0 +1,56 @@
+import type { DocsUiTheme } from "../../lib/docs/browser/config.ts";
+
+/** `localStorage` key the chosen theme is remembered under. */
+export const THEME_STORAGE_KEY = "bun-api-docs-ui:theme";
+
+/** Every theme, in the order the toggle cycles through them. */
+export const THEMES: readonly DocsUiTheme[] = ["system", "light", "dark"];
+
+/** Whether a value is a theme. */
+export function isTheme(value: unknown): value is DocsUiTheme {
+  return THEMES.includes(value as DocsUiTheme);
+}
+
+/** The theme after `theme` in the toggle's cycle. */
+export function nextTheme(theme: DocsUiTheme): DocsUiTheme {
+  return THEMES[(THEMES.indexOf(theme) + 1) % THEMES.length];
+}
+
+/** The remembered theme, or `null`. Storage can be absent or throw (private mode, blocked site data). */
+export function readStoredTheme(): DocsUiTheme | null {
+  try {
+    const value = globalThis.localStorage?.getItem(THEME_STORAGE_KEY);
+    return isTheme(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Remembers a theme; a storage failure only means it is not remembered. */
+export function storeTheme(theme: DocsUiTheme): void {
+  try {
+    globalThis.localStorage?.setItem(THEME_STORAGE_KEY, theme);
+  } catch {
+    // Not remembered; the page still works.
+  }
+}
+
+/** The theme to start in: the remembered choice, else the mount's default. */
+export function initialTheme(configured: DocsUiTheme): DocsUiTheme {
+  return readStoredTheme() ?? configured;
+}
+
+/**
+ * Applies a theme to the document: `data-theme="light"|"dark"` forces one,
+ * no attribute follows `prefers-color-scheme` (see `styles/tokens.css`).
+ */
+export function applyTheme(
+  theme: DocsUiTheme,
+  root: HTMLElement = document.documentElement,
+): void {
+  if (theme === "system") {
+    delete root.dataset.theme;
+  } else {
+    root.dataset.theme = theme;
+  }
+}

package/app/kit/unauthorized.ts

@@ -0,0 +1,222 @@
+import type { QueryClient } from "@tanstack/react-query";
+import type { UiUnauthorized } from "../../lib/kit/browser/unauthorized.ts";
+import { createContext, use } from "react";
+import { unauthorizedRedirectUrl } from "../../lib/kit/browser/unauthorized.ts";
+
+/**
+ * `unauthorized` in the browser: the one place an authorization failure
+ * becomes a navigation, once per page load. Shared by the docs viewer and
+ * the jobs UI (as `@kingsleyweb/bun-ui/docs/embed/unauthorized`).
+ *
+ * Sources report here: the query and mutation caches through
+ * {@link watchAuthFailures} (any failed call, whichever client made it: the
+ * viewer's document read; every jobs UI API call), the jobs UI's live
+ * socket (`LiveClient`'s `onAuthFailure`), and the jobs UI's crashed screens
+ * (through {@link UnauthorizedRedirect.probe}: a lazy screen's chunk the
+ * shell's `authorize` refused fails with no status to read). No screen knows
+ * about it; a failure that is not redirected shows its message as before.
+ *
+ * One per page: the app that owns the page creates it. The embedded docs
+ * screens never do, so the jobs UI's docs section redirects through
+ * the jobs UI's alone.
+ */
+
+/** The parts of `window.location` the redirect reads and calls. */
+export interface RedirectLocation {
+  /** The page's URL, to resolve the target and compare origins. */
+  readonly href: string;
+  /** Sends the browser to a URL. */
+  assign: (url: string) => void;
+}
+
+/** A mount's redirect, made by {@link createUnauthorizedRedirect}. */
+export interface UnauthorizedRedirect {
+  /** Whether `unauthorized` is configured at all. */
+  readonly enabled: boolean;
+  /** Whether a report has sent the browser away (later reports do nothing). */
+  readonly redirected: boolean;
+  /**
+   * Reports a failure's status. One the mount lists sends the browser to the
+   * target, once: the first such report navigates, every later one returns
+   * `true` without navigating again. Returns whether the browser was (or
+   * already had been) sent away.
+   */
+  report: (status: number) => boolean;
+  /** {@link UnauthorizedRedirect.report} for an error from any client: reads its numeric `status`, if it has one. */
+  reportError: (error: unknown) => boolean;
+  /**
+   * Asks the server whether this page may still be loaded, for a failure
+   * that carries no status: a `HEAD` of the shell (`basePath`), whose status
+   * is reported. A screen whose chunk failed to load is the case: the
+   * shell's `authorize` guards the bundle files, and a failed dynamic import
+   * never says why. Resolves what {@link UnauthorizedRedirect.report} returned, or
+   * `false` when the probe itself failed.
+   */
+  probe: () => Promise<boolean>;
+}
+
+/** Options of {@link createUnauthorizedRedirect}; tests replace both. */
+export interface UnauthorizedRedirectOptions {
+  /** Where to read the page's URL and navigate. Defaults to `globalThis.location`, looked up per report. */
+  location?: () => RedirectLocation | undefined;
+  /** The `fetch` {@link UnauthorizedRedirect.probe} calls. Defaults to `globalThis.fetch`, looked up per probe. */
+  fetch?: () => typeof fetch;
+}
+
+/** The status an error carries, if any: `ApiError`'s, bun-client's `HttpError`'s, anything with a numeric `status`. */
+export function statusOf(error: unknown): number | undefined {
+  if (typeof error !== "object" || error === null || !("status" in error)) {
+    return undefined;
+  }
+  const { status } = error;
+  return typeof status === "number" ? status : undefined;
+}
+
+/** Whether `path` is `base` or lies under it, segment-wise. */
+function isWithin(path: string, base: string): boolean {
+  return path === base || path.startsWith(`${base}/`);
+}
+
+/** The pathname as the router compares it: decoded where it can be, lower-cased, no trailing `/`. */
+function comparablePath(pathname: string): string {
+  let decoded = pathname;
+  try {
+    decoded = decodeURIComponent(pathname);
+  } catch {
+    // A malformed escape: compare it as written.
+  }
+  return decoded.replace(/\/+$/, "").toLowerCase();
+}
+
+/** A redirect that never navigates: `unauthorized` is off. */
+export const NO_UNAUTHORIZED_REDIRECT: UnauthorizedRedirect = Object.freeze({
+  enabled: false,
+  redirected: false,
+  report: () => false,
+  reportError: () => false,
+  probe: () => Promise.resolve(false),
+});
+
+/**
+ * Creates the redirect for one page load. `null` gives {@link NO_UNAUTHORIZED_REDIRECT}.
+ *
+ * The target carries `returnParam` set to the page the user is on (path,
+ * query and fragment). A target that resolves into this UI on this origin is
+ * never followed (an absolute URL `jobsUi()` could not check, since it does
+ * not know its own origin): it would load the UI, fail again and loop, so
+ * the screens show their messages instead.
+ *
+ * @param redirect The UI config's `unauthorized` (`JobsUiConfig`, `DocsUiConfig`).
+ * @param basePath The UI config's `basePath`.
+ * @param options Where to navigate and what to fetch with; see {@link UnauthorizedRedirectOptions}.
+ */
+export function createUnauthorizedRedirect(
+  redirect: UiUnauthorized | null,
+  basePath: string,
+  options: UnauthorizedRedirectOptions = {},
+): UnauthorizedRedirect {
+  const getLocation = options.location ?? (() => globalThis.location);
+  const getFetch = options.fetch ?? (() => globalThis.fetch);
+  if (redirect === null) {
+    return NO_UNAUTHORIZED_REDIRECT;
+  }
+  const statuses = new Set<number>(redirect.statuses);
+  const base = basePath.toLowerCase();
+  let redirected = false;
+
+  const report = (status: number): boolean => {
+    if (redirected) {
+      return true;
+    }
+    if (!statuses.has(status)) {
+      return false;
+    }
+    const location = getLocation();
+    if (location === undefined) {
+      return false;
+    }
+    const here = new URL(location.href);
+    const target = unauthorizedRedirectUrl(
+      redirect,
+      `${here.pathname}${here.search}${here.hash}`,
+    );
+    const resolved = new URL(target, here);
+    if (
+      resolved.origin === here.origin &&
+      isWithin(comparablePath(resolved.pathname), base)
+    ) {
+      return false;
+    }
+    redirected = true;
+    location.assign(target);
+    return true;
+  };
+
+  return {
+    enabled: true,
+    get redirected() {
+      return redirected;
+    },
+    report,
+    reportError: (error) => {
+      const status = statusOf(error);
+      return status === undefined ? false : report(status);
+    },
+    probe: async () => {
+      if (redirected) {
+        return true;
+      }
+      let status: number;
+      try {
+        const response = await getFetch()(basePath, {
+          method: "HEAD",
+          credentials: "same-origin",
+          cache: "no-store",
+        });
+        status = response.status;
+      } catch {
+        return false;
+      }
+      return report(status);
+    },
+  };
+}
+
+/**
+ * Reports every failed query and mutation of `queryClient` to `redirect`:
+ * the cache-level hook, so every API call is covered whichever client made it
+ * and no screen needs code of its own. Returns the unsubscribe. Subscribes to
+ * nothing when the redirect is off.
+ */
+export function watchAuthFailures(
+  queryClient: QueryClient,
+  redirect: UnauthorizedRedirect,
+): () => void {
+  if (!redirect.enabled) {
+    return () => {};
+  }
+  const offQueries = queryClient.getQueryCache().subscribe((event) => {
+    if (event.type === "updated" && event.action.type === "error") {
+      redirect.reportError(event.action.error);
+    }
+  });
+  const offMutations = queryClient.getMutationCache().subscribe((event) => {
+    if (event.type === "updated" && event.action.type === "error") {
+      redirect.reportError(event.action.error);
+    }
+  });
+  return () => {
+    offQueries();
+    offMutations();
+  };
+}
+
+/** Carries the page's {@link UnauthorizedRedirect}; {@link NO_UNAUTHORIZED_REDIRECT} outside `AppProviders`. */
+export const UnauthorizedRedirectContext = createContext<UnauthorizedRedirect>(
+  NO_UNAUTHORIZED_REDIRECT,
+);
+
+/** The page's {@link UnauthorizedRedirect}. */
+export function useUnauthorizedRedirect(): UnauthorizedRedirect {
+  return use(UnauthorizedRedirectContext);
+}