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

package/app/docs/components/jsonParse.ts

@@ -0,0 +1,338 @@
+/**
+ * JSON parsing that says *where* it failed. `JSON.parse` does the parsing;
+ * only when it throws does a small scanner walk the text to find the
+ * offending position, because engines disagree on whether (and how) their
+ * messages carry one — JavaScriptCore's carry none at all.
+ */
+
+/** Where and why a JSON text failed to parse. */
+export interface JsonParseError {
+  /** What is wrong, e.g. "Expected ',' or '}'". */
+  message: string;
+  /** 1-based line. */
+  line: number;
+  /** 1-based column (in UTF-16 code units). */
+  column: number;
+  /** 0-based offset into the text. */
+  offset: number;
+}
+
+/** The outcome of {@link parseJsonText}. */
+export type JsonParseResult =
+  | {
+      /** It parsed. */
+      ok: true;
+      /** The parsed value. */
+      value: unknown;
+    }
+  | {
+      /** It did not parse. */
+      ok: false;
+      /** Where and why. */
+      error: JsonParseError;
+    };
+
+/** Thrown inside the scanner with the failing offset. */
+class ScanError extends Error {
+  /** 0-based offset. */
+  readonly offset: number;
+
+  constructor(message: string, offset: number) {
+    super(message);
+    this.offset = offset;
+  }
+}
+
+/** Describes the character at `index` for a message. */
+function describe(text: string, index: number): string {
+  return index >= text.length
+    ? "end of input"
+    : `'${text[index] === "\n" ? "\\n" : text[index]}'`;
+}
+
+/**
+ * Walks `text` as JSON (RFC 8259) and throws a {@link ScanError} at the
+ * first position that is not valid. Returns normally for valid JSON.
+ */
+function scan(text: string): void {
+  let index = 0;
+
+  const skipWhitespace = () => {
+    while (
+      index < text.length &&
+      (text[index] === " " ||
+        text[index] === "\t" ||
+        text[index] === "\n" ||
+        text[index] === "\r")
+    ) {
+      index++;
+    }
+  };
+
+  const fail = (expected: string): never => {
+    throw new ScanError(
+      `Expected ${expected} but found ${describe(text, index)}`,
+      index,
+    );
+  };
+
+  const literal = (word: string) => {
+    for (let i = 0; i < word.length; i++) {
+      if (text[index] !== word[i]) {
+        fail(`'${word}'`);
+      }
+      index++;
+    }
+  };
+
+  const string = () => {
+    index++; // opening quote
+    while (index < text.length) {
+      const char = text[index];
+      if (char === '"') {
+        index++;
+        return;
+      }
+      if (char === "\\") {
+        const next = text[index + 1];
+        if (next === "u") {
+          if (!/^[0-9a-f]{4}$/i.test(text.slice(index + 2, index + 6))) {
+            index += 2;
+            fail("four hex digits after \\u");
+          }
+          index += 6;
+          continue;
+        }
+        if (next === undefined || !'"\\/bfnrt'.includes(next)) {
+          index++;
+          fail("a valid escape");
+        }
+        index += 2;
+        continue;
+      }
+      if (char < " ") {
+        throw new ScanError(
+          "Control characters must be escaped in strings",
+          index,
+        );
+      }
+      index++;
+    }
+    throw new ScanError("Unterminated string", index);
+  };
+
+  const number = () => {
+    const match = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:e[+-]?\d+)?/i.exec(
+      text.slice(index, index + 400),
+    );
+    if (!match) {
+      fail("a number");
+    }
+    index += match![0].length;
+  };
+
+  const value = (): void => {
+    skipWhitespace();
+    const char = text[index];
+    if (char === "{") {
+      index++;
+      skipWhitespace();
+      if (text[index] === "}") {
+        index++;
+        return;
+      }
+      for (;;) {
+        skipWhitespace();
+        if (text[index] !== '"') {
+          fail("a property name in double quotes");
+        }
+        string();
+        skipWhitespace();
+        if (text[index] !== ":") {
+          fail("':'");
+        }
+        index++;
+        value();
+        skipWhitespace();
+        if (text[index] === ",") {
+          index++;
+          continue;
+        }
+        if (text[index] === "}") {
+          index++;
+          return;
+        }
+        fail("',' or '}'");
+      }
+    }
+    if (char === "[") {
+      index++;
+      skipWhitespace();
+      if (text[index] === "]") {
+        index++;
+        return;
+      }
+      for (;;) {
+        value();
+        skipWhitespace();
+        if (text[index] === ",") {
+          index++;
+          continue;
+        }
+        if (text[index] === "]") {
+          index++;
+          return;
+        }
+        fail("',' or ']'");
+      }
+    }
+    if (char === '"') {
+      string();
+      return;
+    }
+    if (char === "t") {
+      literal("true");
+      return;
+    }
+    if (char === "f") {
+      literal("false");
+      return;
+    }
+    if (char === "n") {
+      literal("null");
+      return;
+    }
+    if (char === "-" || (char !== undefined && char >= "0" && char <= "9")) {
+      number();
+      return;
+    }
+    fail("a value");
+  };
+
+  value();
+  skipWhitespace();
+  if (index < text.length) {
+    fail("end of input");
+  }
+}
+
+/** 1-based line and column of an offset. */
+export function lineColumn(
+  text: string,
+  offset: number,
+): { line: number; column: number } {
+  let line = 1;
+  let lineStart = 0;
+  const end = Math.min(offset, text.length);
+  for (let i = 0; i < end; i++) {
+    if (text.charCodeAt(i) === 10) {
+      line++;
+      lineStart = i + 1;
+    }
+  }
+  return { line, column: end - lineStart + 1 };
+}
+
+/** Parses JSON; on failure, reports the message with its line and column. */
+export function parseJsonText(text: string): JsonParseResult {
+  try {
+    return { ok: true, value: JSON.parse(text) as unknown };
+  } catch (caught) {
+    let message = caught instanceof Error ? caught.message : String(caught);
+    let offset = 0;
+    try {
+      scan(text);
+      // The scanner accepted what JSON.parse refused (should not happen);
+      // keep the engine's message without a position.
+    } catch (scanned) {
+      if (scanned instanceof ScanError) {
+        message = scanned.message;
+        offset = scanned.offset;
+      }
+    }
+    return {
+      ok: false,
+      error: { message, offset, ...lineColumn(text, offset) },
+    };
+  }
+}
+
+/** The UTF-8 size of a text, in bytes (what the API measures against its limits). */
+export function byteLength(text: string): number {
+  return new TextEncoder().encode(text).byteLength;
+}
+
+/** Formats a byte count: `512 B`, `1.5 KiB`, `2.0 MiB`. */
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  if (bytes < 1024 * 1024) {
+    return `${(bytes / 1024).toFixed(1)} KiB`;
+  }
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+}
+
+/** The editor's state, as `JsonEditor` reports it on every change. */
+export interface JsonEditorState {
+  /** The raw text. */
+  text: string;
+  /** The parsed value; `undefined` when the text does not parse (or is empty). */
+  value: unknown;
+  /** Whether the text parses (or is empty and `allowEmpty`) and fits `maxBytes`. The one flag a submit button needs. */
+  valid: boolean;
+  /** The parse error with its line and column, or `null`. */
+  error: JsonParseError | null;
+  /** The text's UTF-8 size. */
+  bytes: number;
+  /** Whether `bytes` exceeds `maxBytes`. */
+  overLimit: boolean;
+}
+
+/** Options of {@link jsonEditorState}. */
+export interface JsonEditorStateOptions {
+  /** The size limit, bytes. */
+  maxBytes?: number;
+  /** Whether empty (whitespace-only) text is valid, as `undefined`. Defaults to `false`. */
+  allowEmpty?: boolean;
+}
+
+/**
+ * Works out a {@link JsonEditorState} from text, e.g. to seed a form's
+ * validity before the first edit.
+ */
+export function jsonEditorState(
+  text: string,
+  { maxBytes, allowEmpty = false }: JsonEditorStateOptions = {},
+): JsonEditorState {
+  const bytes = byteLength(text);
+  const overLimit = maxBytes !== undefined && bytes > maxBytes;
+  if (allowEmpty && text.trim() === "") {
+    return {
+      text,
+      value: undefined,
+      valid: !overLimit,
+      error: null,
+      bytes,
+      overLimit,
+    };
+  }
+  const parsed = parseJsonText(text);
+  return parsed.ok
+    ? {
+        text,
+        value: parsed.value,
+        valid: !overLimit,
+        error: null,
+        bytes,
+        overLimit,
+      }
+    : {
+        text,
+        value: undefined,
+        valid: false,
+        error: parsed.error,
+        bytes,
+        overLimit,
+      };
+}

package/app/docs/components/listKeys.ts

@@ -0,0 +1,30 @@
+/**
+ * Arrow-key movement through a vertical list of links (the API docs
+ * sidebars): Down/Up to the next/previous item, stopping at the ends,
+ * Home/End to the first/last. Each item stays a Tab stop too, so this adds
+ * speed without hiding anything from Tab.
+ */
+
+/** The item a key moves focus to from `active`, or `null` when the key is not a movement key (or the list is empty). */
+export function arrowTarget<T extends Element>(
+  key: string,
+  items: readonly T[],
+  active: Element | null,
+): T | null {
+  if (items.length === 0) {
+    return null;
+  }
+  const index = active ? items.indexOf(active as T) : -1;
+  switch (key) {
+    case "ArrowDown":
+      return items[index < 0 ? 0 : Math.min(index + 1, items.length - 1)];
+    case "ArrowUp":
+      return items[index <= 0 ? 0 : index - 1];
+    case "Home":
+      return items[0];
+    case "End":
+      return items[items.length - 1];
+    default:
+      return null;
+  }
+}

package/app/docs/config.ts

@@ -0,0 +1,86 @@
+import type { DocsUiConfig } from "../../lib/docs/browser/config.ts";
+import { DOCS_UI_CONFIG_ELEMENT_ID } from "../../lib/docs/browser/config.ts";
+import { isUiUnauthorized } from "../../lib/kit/browser/unauthorized.ts";
+
+/** The injected configuration was missing or malformed. */
+export class DocsUiConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "DocsUiConfigError";
+  }
+}
+
+/** Whether a value is a plain object. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Checks the fields the viewer relies on before its first request. It does
+ * not re-validate everything the server resolved — only enough that a stale
+ * or hand-edited shell fails with a message instead of a blank page.
+ */
+export function parseDocsUiConfig(value: unknown): DocsUiConfig {
+  if (!isRecord(value)) {
+    throw new DocsUiConfigError("The UI configuration is not an object.");
+  }
+  if (value.version !== 1) {
+    throw new DocsUiConfigError(
+      `Unsupported UI configuration version ${JSON.stringify(value.version)} (expected 1).`,
+    );
+  }
+  for (const key of [
+    "title",
+    "basePath",
+    "assetsPath",
+    "documentUrl",
+  ] as const) {
+    if (typeof value[key] !== "string") {
+      throw new DocsUiConfigError(
+        `The UI configuration's "${key}" is not a string.`,
+      );
+    }
+  }
+  if (value.csrfHeader !== null && typeof value.csrfHeader !== "string") {
+    throw new DocsUiConfigError(
+      `The UI configuration's "csrfHeader" must be a string or null.`,
+    );
+  }
+  if (
+    !Array.isArray(value.extensions) ||
+    !value.extensions.every((prefix) => typeof prefix === "string")
+  ) {
+    throw new DocsUiConfigError(
+      `The UI configuration's "extensions" must be an array of strings.`,
+    );
+  }
+  if (!["system", "light", "dark"].includes(String(value.theme))) {
+    throw new DocsUiConfigError(`The UI configuration's "theme" is not valid.`);
+  }
+  // Missing in a shell from before the option existed, or from a host that
+  // mirrors the config (bun-common's docsRouter): off.
+  const unauthorized = value.unauthorized ?? null;
+  if (unauthorized !== null && !isUiUnauthorized(unauthorized)) {
+    throw new DocsUiConfigError(
+      `The UI configuration's "unauthorized" must be null or { redirectTo, returnParam, statuses }.`,
+    );
+  }
+  return { ...value, unauthorized } as unknown as DocsUiConfig;
+}
+
+/** Reads the {@link DocsUiConfig} the server inlined as `<script type="application/json" id="bun-api-docs-ui-config">`. */
+export function readDocsUiConfig(doc: Document = document): DocsUiConfig {
+  const element = doc.getElementById(DOCS_UI_CONFIG_ELEMENT_ID);
+  if (!element) {
+    throw new DocsUiConfigError(
+      `The page has no #${DOCS_UI_CONFIG_ELEMENT_ID} element: it was not served by docsUi().`,
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(element.textContent ?? "");
+  } catch {
+    throw new DocsUiConfigError("The UI configuration is not valid JSON.");
+  }
+  return parseDocsUiConfig(parsed);
+}

package/app/docs/context.ts

@@ -0,0 +1,33 @@
+import type { DocsUiConfig } from "../../lib/docs/browser/config.ts";
+import type { DocsClient, FetchLike } from "./api/client";
+import { createContext, use } from "react";
+
+/** Carries the injected {@link DocsUiConfig}. */
+export const DocsUiConfigContext = createContext<DocsUiConfig | null>(null);
+/** Carries the try-it panel's client (built on the document's resolved server). */
+export const DocsClientContext = createContext<DocsClient | null>(null);
+/** Carries the `fetch` every client uses; tests inject one. Defaults to `globalThis.fetch`. */
+export const DocsFetchContext = createContext<FetchLike | null>(null);
+
+/** The resolved {@link DocsUiConfig} the server injected. */
+export function useDocsUiConfig(): DocsUiConfig {
+  const config = use(DocsUiConfigContext);
+  if (!config) {
+    throw new Error("useDocsUiConfig must be used inside <DocsUiProviders>");
+  }
+  return config;
+}
+
+/** The try-it panel's client. */
+export function useDocsClient(): DocsClient {
+  const client = use(DocsClientContext);
+  if (!client) {
+    throw new Error("useDocsClient must be used inside <DocsClientContext>");
+  }
+  return client;
+}
+
+/** The `fetch` the clients use, or `undefined` for `globalThis.fetch`. */
+export function useDocsFetch(): FetchLike | undefined {
+  return use(DocsFetchContext) ?? undefined;
+}

package/app/docs/embed.ts

@@ -0,0 +1,74 @@
+/**
+ * The embedding surface (`@kingsleyweb/bun-ui/docs/embed`): the viewer's
+ * screens and models for a host app to render inside its own shell, with the
+ * host's router, client, permissions and console injected through the seam
+ * props. The jobs UI's docs section is built from these.
+ *
+ * This is browser code (React, TSX, CSS side-effect imports): it is for a host
+ * that bundles it (Bun.build does), never for a Node consumer, and it ships as
+ * source — there are no declarations, the types ARE the source. It is covered
+ * in-repo (the jobs app imports it by this name); the package's
+ * consumer check covers the server-side `lib/` surface.
+ *
+ * The two models come out as namespaces: both name a `filterGroups`, and the
+ * WebSocket one a `refName` that is not the schema's.
+ */
+
+// The shared JSON Schema renderer.
+export * from "./screens/docs/schema";
+
+// The HTTP reference (OpenAPI 3.1).
+export * as httpModel from "./screens/docs/http/model";
+export * as httpTryIt from "./screens/docs/http/tryIt";
+export { HttpReference } from "./screens/docs/http/index";
+export type { HttpReferenceProps } from "./screens/docs/http/index";
+
+// The WebSocket reference (AsyncAPI 3.0).
+export * as wsModel from "./screens/docs/ws/model";
+export * as wsFormat from "./screens/docs/ws/format";
+export { InlineText } from "./screens/docs/ws/InlineText";
+export { PayloadSchema } from "./screens/docs/ws/PayloadSchema";
+export type { PayloadSchemaProps } from "./screens/docs/ws/PayloadSchema";
+export { PermissionMarker } from "./screens/docs/ws/items";
+export { WsReference } from "./screens/docs/ws/index";
+export type { WsConsole, WsPaneOptions } from "./screens/docs/ws/items";
+export type { WsReferenceProps } from "./screens/docs/ws/index";
+
+// The seams.
+export type { PermissionProbe } from "./screens/docs/permissions";
+export type { WsAddressOptions } from "./screens/docs/ws/model";
+export type { LimitInfo } from "./screens/docs/ws/format";
+
+// The host provides the config and the try-it client through these.
+export {
+  DocsClientContext,
+  DocsFetchContext,
+  DocsUiConfigContext,
+} from "./context";
+
+// The host's app shares the router's contexts by re-exporting these.
+export * from "./routing";
+export { Link, Navigate, RouterProvider } from "./router";
+export type { LinkProps, RouterProviderProps } from "./router";
+
+// The client and the document type, for the host's adapters, and the error
+// class (the host re-homes its own errors into it for the try-it's banner).
+export { ApiError, isApiError } from "./api/errors";
+export type {
+  ApiErrorInit,
+  ApiErrorKind,
+  ProblemDto,
+  ProblemIssueDto,
+} from "./api/errors";
+export { createDocsClient } from "./api/client";
+export type {
+  DocsClient,
+  FetchLike,
+  HttpMethod,
+  QueryParams,
+  QueryScalar,
+  QueryValue,
+  RawResponse,
+  RequestOptions,
+} from "./api/client";
+export type { SpecDocument } from "./api/docs";

package/app/docs/env.d.ts

@@ -0,0 +1,2 @@
+// Stylesheets are imported for their side effect; Bun.build emits them as CSS.
+declare module "*.css";

package/app/docs/format.ts

@@ -0,0 +1,9 @@
+/** One shared integer formatter in the browser's locale. */
+const integerFormat = new Intl.NumberFormat(undefined, {
+  maximumFractionDigits: 0,
+});
+
+/** Formats a count, e.g. `12,345`. */
+export function formatNumber(value: number): string {
+  return integerFormat.format(value);
+}

package/app/docs/hooks/useUrlTab.ts

@@ -0,0 +1,16 @@
+import { useRouter } from "../routing";
+
+/**
+ * The selected tab of a `UrlTabs`, read from the URL: the value of
+ * `param` when it is one of `tabs`, else `defaultValue`. Use it in the
+ * screen to pick the data for the panel.
+ */
+export function useUrlTab<V extends string>(
+  param: string,
+  tabs: readonly { value: V }[],
+  defaultValue: V,
+): V {
+  const { location } = useRouter();
+  const raw = new URLSearchParams(location.search).get(param);
+  return tabs.find((tab) => tab.value === raw)?.value ?? defaultValue;
+}

package/app/docs/main.tsx

@@ -0,0 +1,11 @@
+import { boot } from "./boot";
+/**
+ * The browser entry point `Bun.build` bundles: the stylesheets (emitted as
+ * CSS files) and the viewer. Everything else lives in `boot.tsx`, so tests
+ * can start the app without this module's import-time side effect.
+ */
+import "./styles/tokens.css";
+import "./styles/base.css";
+import "./components/components.css";
+
+boot();

package/app/docs/queryClient.ts

@@ -0,0 +1,54 @@
+import { QueryClient } from "@tanstack/react-query";
+import { isApiError } from "./api/errors";
+
+/** Most retries of a failed read. */
+const MAX_RETRIES = 2;
+
+/**
+ * Retries network failures and 5xx, never a 4xx: a 401/403/404/400 will not
+ * change by asking again, and retrying a 401 delays the sign-in message.
+ * Nor a malformed response (kind `parse`): the host answered, and answering
+ * the same again would only hold the error back for the retries' backoff.
+ */
+export function shouldRetry(failureCount: number, error: unknown): boolean {
+  if (
+    isApiError(error) &&
+    (error.kind === "parse" || (error.status >= 400 && error.status < 500))
+  ) {
+    return false;
+  }
+  return failureCount < MAX_RETRIES;
+}
+
+/** Options of {@link createQueryClient}. */
+export interface CreateQueryClientOptions {
+  /** Retry failed reads (see {@link shouldRetry}). Defaults to `true`; tests pass `false`. */
+  retry?: boolean;
+}
+
+/** The viewer's TanStack Query client. */
+export function createQueryClient(
+  options: CreateQueryClientOptions = {},
+): QueryClient {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: options.retry === false ? false : shouldRetry,
+        staleTime: 2_000,
+        refetchOnWindowFocus: true,
+      },
+      mutations: { retry: false },
+    },
+  });
+}
+
+/**
+ * Before "Reload this screen" (`ScreenErrorBoundary`) remounts a crashed
+ * screen, drops the cached answers the screen read, so it reads them again:
+ * a crash caused by the DATA would otherwise render the same cached answer
+ * and crash again at once. Only inactive queries are reset; the crashed
+ * screen's are inactive by then.
+ */
+export function resetScreenQueries(queryClient: QueryClient): Promise<void> {
+  return queryClient.resetQueries({ type: "inactive" });
+}