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

package/app/docs/screens/docs/viewer.tsx

@@ -0,0 +1,154 @@
+/**
+ * The viewer: loads the one document the mount is configured with
+ * (`config.documentUrl`), reads from it whether it is an OpenAPI 3.1 or an
+ * AsyncAPI 3.0 document, and routes to the matching reference — `/http[…]`
+ * or `/ws[…]`, with `/` redirecting to it.
+ */
+import type { ReactNode } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { useMemo } from "react";
+import { createDocsClient } from "../../api/client";
+import { documentKind, docsKeys, getDocument } from "../../api/docs";
+import { Card } from "../../components/Card";
+import { EmptyState } from "../../components/EmptyState";
+import { ErrorView } from "../../components/ErrorView";
+import { Spinner } from "../../components/Spinner";
+import { useDocsFetch, useDocsUiConfig } from "../../context";
+import { Navigate, Link, Routes } from "../../router";
+import type { RouteDef } from "../../routing";
+import { DocumentContext, useDocument } from "./document";
+import { HttpReference } from "./http";
+import { WsReference } from "./ws";
+
+export type { LoadedDocument } from "./document";
+
+/** `/http[…]` for an OpenAPI document; anything else is told there is none. */
+function HttpRoute() {
+  const { doc, kind } = useDocument();
+  if (kind !== "openapi") {
+    return (
+      <div className="screen">
+        <EmptyState
+          headingLevel={1}
+          title="No HTTP documentation"
+          description="This document is not an OpenAPI document."
+        />
+      </div>
+    );
+  }
+  return <HttpReference doc={doc} />;
+}
+
+/** `/ws[…]` for an AsyncAPI document; anything else is told there is none. */
+function WsRoute() {
+  const { doc, kind } = useDocument();
+  if (kind !== "asyncapi") {
+    return (
+      <div className="screen">
+        <EmptyState
+          headingLevel={1}
+          title="No WebSocket documentation"
+          description="This document is not an AsyncAPI document."
+        />
+      </div>
+    );
+  }
+  return <WsReference document={doc} />;
+}
+
+/** `/`: straight to the one reference this viewer has. */
+function Home() {
+  const { kind } = useDocument();
+  return <Navigate to={kind === "asyncapi" ? "/ws" : "/http"} />;
+}
+
+/** The route table: the reference's own pages under the mount. */
+const ROUTES: readonly RouteDef[] = [
+  { path: "/", element: <Home /> },
+  { path: "/http", element: <HttpRoute /> },
+  { path: "/http/:operationId", element: <HttpRoute /> },
+  { path: "/ws", element: <WsRoute /> },
+  { path: "/ws/:item", element: <WsRoute /> },
+];
+
+/** The viewer, once the document has loaded. */
+export function DocsViewer({ children }: { children?: ReactNode }) {
+  const config = useDocsUiConfig();
+  const fetcher = useDocsFetch();
+  // The document URL is absolute or same-origin; the client sends it as it is.
+  const client = useMemo(
+    () =>
+      createDocsClient({
+        base: "",
+        csrfHeader: config.csrfHeader,
+        fetch: fetcher,
+      }),
+    [config.csrfHeader, fetcher],
+  );
+  const spec = useQuery({
+    queryKey: docsKeys.document(config.documentUrl),
+    queryFn: ({ signal }) => getDocument(client, config.documentUrl, signal),
+    staleTime: Infinity,
+  });
+
+  if (spec.isPending) {
+    return (
+      <div className="screen">
+        <Spinner
+          label="Loading the API document"
+          showLabel
+        />
+      </div>
+    );
+  }
+  if (spec.isError) {
+    return (
+      <div className="screen">
+        <ErrorView
+          headingLevel={1}
+          error={spec.error}
+          title="Could not load the API document"
+          onRetry={() => void spec.refetch()}
+        />
+      </div>
+    );
+  }
+  const kind = documentKind(spec.data);
+  if (kind === null) {
+    return (
+      <div className="screen">
+        <EmptyState
+          headingLevel={1}
+          title="Not a document this viewer can show"
+          description="The document carries neither an `openapi` nor an `asyncapi` field. This viewer shows an OpenAPI 3.1 or an AsyncAPI 3.0 document."
+        />
+      </div>
+    );
+  }
+  return (
+    <DocumentContext value={{ doc: spec.data, kind }}>
+      {children ?? (
+        <Routes
+          routes={ROUTES}
+          notFound={<DocsNotFound />}
+        />
+      )}
+    </DocumentContext>
+  );
+}
+
+/** The 404 for a client route the viewer does not have. */
+export function DocsNotFound() {
+  return (
+    <div className="screen">
+      <Card>
+        <EmptyState
+          headingLevel={1}
+          title="Page not found"
+          description="This page is not part of the API documentation."
+          action={<Link to="/">Back to the documentation</Link>}
+        />
+      </Card>
+    </div>
+  );
+}

package/app/docs/screens/docs/ws/InlineText.tsx

@@ -0,0 +1,25 @@
+/** Props of {@link InlineText}. */
+export interface InlineTextProps {
+  /** One line of spec text, whose backtick spans are code. */
+  text: string;
+}
+
+/**
+ * One line of spec text with its `` `code` `` spans as `<code>`: the inline
+ * half of the shared `Prose`, which does not export it. No HTML is injected.
+ */
+export function InlineText({ text }: InlineTextProps) {
+  const parts = text.split(/(`[^`]+`)/);
+  return (
+    <>
+      {parts.map((part, index) =>
+        part.length > 2 && part.startsWith("`") && part.endsWith("`") ? (
+          // eslint-disable-next-line react/no-array-index-key -- the split is fixed for a given text
+          <code key={index}>{part.slice(1, -1)}</code>
+        ) : (
+          part
+        ),
+      )}
+    </>
+  );
+}

package/app/docs/screens/docs/ws/PayloadSchema.tsx

@@ -0,0 +1,39 @@
+import type { SpecDocument } from "../../../api/docs";
+import { SchemaTree } from "../schema";
+
+/** Props of {@link PayloadSchema}. */
+export interface PayloadSchemaProps {
+  /** The schema, as the document writes it (often a `$ref`). */
+  schema: unknown;
+  /** The whole document, for resolving `$ref`s. */
+  root: SpecDocument;
+  /** The tree's accessible name. */
+  label: string;
+  /** Levels open at first. Defaults to 2. */
+  depth?: number;
+}
+
+/**
+ * A message's payload schema, `$ref`s resolved, drawn by the docs' shared
+ * schema tree. The one place the WebSocket reference renders a schema.
+ */
+export function PayloadSchema({
+  schema,
+  root,
+  label,
+  depth = 2,
+}: PayloadSchemaProps) {
+  return (
+    <div
+      className="ws-schema"
+      data-testid="ws-schema"
+    >
+      <SchemaTree
+        schema={schema}
+        root={root}
+        depth={depth}
+        label={label}
+      />
+    </div>
+  );
+}

package/app/docs/screens/docs/ws/format.ts

@@ -0,0 +1,82 @@
+import { formatNumber } from "../../../format";
+
+/**
+ * How the limits panel reads each `<prefix>-limits` entry. A limit's unit is
+ * read from its name's suffix (`…Bytes`, `…Ms`, `…PerSecond`); a viewer
+ * embedding this reference can pass a {@link LimitInfo} per name for a label
+ * and a meaning instead (the jobs UI does, for its own vocabulary).
+ */
+
+/** A limit's unit. */
+export type LimitUnit = "bytes" | "ms" | "count" | "per-second";
+
+/** How one limit reads. */
+export interface LimitInfo {
+  /** Its label. */
+  label: string;
+  /** What it means. */
+  meaning: string;
+  /** Its unit. */
+  unit: LimitUnit;
+}
+
+/** A limit's unit from its name: `maxMessageBytes` → bytes, `heartbeatMs` → ms, `messagesPerSecond` → per-second, anything else a count. */
+export function limitUnit(name: string): LimitUnit {
+  if (/bytes$/i.test(name)) {
+    return "bytes";
+  }
+  if (/ms$/i.test(name)) {
+    return "ms";
+  }
+  if (/persecond$/i.test(name)) {
+    return "per-second";
+  }
+  return "count";
+}
+
+/** `1,048,576 bytes (1 MiB)`. */
+export function formatBytes(value: number): string {
+  const units = ["KiB", "MiB", "GiB"];
+  let scaled = value;
+  let unit = "";
+  for (const next of units) {
+    if (scaled < 1024 || scaled % 1024 !== 0) {
+      break;
+    }
+    scaled /= 1024;
+    unit = next;
+  }
+  return unit === ""
+    ? `${formatNumber(value)} bytes`
+    : `${formatNumber(value)} bytes (${formatNumber(scaled)} ${unit})`;
+}
+
+/** `25,000 ms (25 s)`, `300,000 ms (5 min)`. */
+export function formatMs(value: number): string {
+  const plain = `${formatNumber(value)} ms`;
+  if (value >= 60_000 && value % 60_000 === 0) {
+    return `${plain} (${formatNumber(value / 60_000)} min)`;
+  }
+  if (value >= 1000 && value % 1000 === 0) {
+    return `${plain} (${formatNumber(value / 1000)} s)`;
+  }
+  return plain;
+}
+
+/** A limit's value in its unit: `info`'s when given, else the name's suffix. */
+export function formatLimit(
+  name: string,
+  value: number,
+  info?: LimitInfo,
+): string {
+  switch (info?.unit ?? limitUnit(name)) {
+    case "bytes":
+      return formatBytes(value);
+    case "ms":
+      return formatMs(value);
+    case "per-second":
+      return `${formatNumber(value)} / s`;
+    default:
+      return formatNumber(value);
+  }
+}

package/app/docs/screens/docs/ws/index.tsx

@@ -0,0 +1,286 @@
+/**
+ * The WebSocket API reference (AsyncAPI 3.0): `/ws` and `/ws/:item` under the
+ * mount. The document is loaded by the viewer (`../viewer.tsx`); the pure
+ * reading of it is in `model.ts`, the per-item panes in `items.tsx`, the
+ * extension panels in `panels.tsx`.
+ */
+import type { KeyboardEvent } from "react";
+import type { SpecDocument } from "../../../api/docs";
+import type { PermissionProbe } from "../permissions";
+import type { LimitInfo } from "./format";
+import type { WsConsole, WsPaneOptions } from "./items";
+import type { WsAddressOptions, WsNavGroup } from "./model";
+import { useMemo, useRef } from "react";
+import { EmptyState } from "../../../components/EmptyState";
+import { Field } from "../../../components/Field";
+import { TextInput } from "../../../components/inputs";
+import { arrowTarget } from "../../../components/listKeys";
+import { Link } from "../../../router";
+import { useParams, useQueryParam } from "../../../routing";
+import { SEARCH_SHORTCUT } from "../../../shortcuts";
+import { ChannelPane, MessagePane, OperationPane } from "./items";
+import {
+  filterGroups,
+  itemPath,
+  navGroups,
+  readWsDoc,
+  selectItem,
+} from "./model";
+import {
+  CloseCodesPanel,
+  DocHeader,
+  LimitsPanel,
+  RefusalsPanel,
+  SecurityPanel,
+  ServerPanel,
+} from "./panels";
+import "./ws.css";
+
+/** Props of {@link WsSidebar}. */
+interface WsSidebarProps {
+  /** The groups, before searching. */
+  groups: readonly WsNavGroup[];
+  /** The selected slug. */
+  selected: string;
+  /** The search (`?q=`). */
+  query: string;
+  /** Sets the search. */
+  onQuery: (query: string) => void;
+  /** The docs section's path within the host app ("" for a standalone viewer). */
+  pathBase: string;
+}
+
+/** The sidebar: a search box, then the connection's panels, channels, operations and messages. */
+function WsSidebar({
+  groups,
+  selected,
+  query,
+  onQuery,
+  pathBase,
+}: WsSidebarProps) {
+  const shown = filterGroups(groups, query);
+  const navRef = useRef<HTMLElement>(null);
+  const links = () =>
+    Array.from(
+      navRef.current?.querySelectorAll<HTMLAnchorElement>("a.ws-nav-link") ??
+        [],
+    );
+  // Arrow keys move between the links (Home/End to the ends), and ArrowDown
+  // from the search goes to the first; each link stays a Tab stop too.
+  const onListKey = (event: KeyboardEvent<HTMLDivElement>) => {
+    const target = arrowTarget(event.key, links(), document.activeElement);
+    if (target) {
+      event.preventDefault();
+      target.focus();
+    }
+  };
+  return (
+    <nav
+      ref={navRef}
+      className="ws-sidebar"
+      aria-label="WebSocket reference"
+    >
+      <Field label="Search">
+        <TextInput
+          type="search"
+          value={query}
+          onChange={onQuery}
+          onKeyDown={(event) => {
+            const first = links()[0];
+            if (event.key === "ArrowDown" && first) {
+              event.preventDefault();
+              first.focus();
+            }
+          }}
+          placeholder="Channel, message, code…"
+          {...SEARCH_SHORTCUT}
+          autoComplete="off"
+          spellCheck={false}
+        />
+      </Field>
+      {shown.length === 0 && (
+        <p
+          className="muted"
+          data-testid="ws-search-empty"
+        >
+          Nothing matches “{query}”.
+        </p>
+      )}
+      <div
+        className="ws-sidebar-list"
+        onKeyDown={onListKey}
+      >
+        {shown.map((group) => (
+          <section
+            key={group.title}
+            className="ws-group"
+            data-testid={`ws-group-${group.title}`}
+          >
+            <h2 className="ws-group-title">{group.title}</h2>
+            <ul>
+              {group.items.map((item) => (
+                <li key={item.slug}>
+                  <Link
+                    to={itemPath(item.slug, query, pathBase)}
+                    className="ws-nav-link"
+                    activeMatch="exact"
+                    data-selected={item.slug === selected ? "true" : undefined}
+                    data-testid={`ws-nav-${item.slug}`}
+                  >
+                    <span className="ws-nav-label">{item.label}</span>
+                    {item.hint && (
+                      <span className="ws-nav-hint">{item.hint}</span>
+                    )}
+                  </Link>
+                </li>
+              ))}
+            </ul>
+          </section>
+        ))}
+      </div>
+    </nav>
+  );
+}
+
+/** Props of {@link WsReference}. */
+export interface WsReferenceProps {
+  /** The AsyncAPI document. */
+  document: SpecDocument;
+  /** The extension prefixes to read; defaults to the configured ones. */
+  extensions?: readonly string[];
+  /** The subprotocol shown when the document states none. */
+  defaultSubprotocol?: string;
+  /** Labels and meanings for the limits, when the embedding viewer knows them. */
+  limitsInfo?: Readonly<Record<string, LimitInfo>>;
+  /** The console the try-it cards open (the jobs UI's Events console), when the host has one. */
+  console?: WsConsole;
+  /** Answers "does the caller hold this permission" (the have/lack markers). */
+  probe?: PermissionProbe;
+  /** The host's contract for the try-it's address fields. */
+  address?: WsAddressOptions;
+  /** The docs section's path within the host app ("" for a standalone viewer). */
+  pathBase?: string;
+}
+
+/** The reference for a loaded document. */
+export function WsReference({
+  document: spec,
+  extensions,
+  defaultSubprotocol,
+  limitsInfo,
+  console: consoleOptions,
+  probe,
+  address,
+  pathBase = "",
+}: WsReferenceProps) {
+  const paneOptions: WsPaneOptions = {
+    console: consoleOptions,
+    probe,
+    address,
+    pathBase,
+  };
+  const doc = useMemo(
+    () => readWsDoc(spec, { extensions, defaultSubprotocol }),
+    [spec, extensions, defaultSubprotocol],
+  );
+  const groups = useMemo(() => navGroups(doc), [doc]);
+  const { item } = useParams<{ item?: string }>();
+  const [query, setQuery] = useQueryParam("q");
+
+  const connection = doc.channels.find((channel) => channel.isConnection);
+  const slug = item ?? connection?.slug ?? doc.channels[0]?.slug ?? "";
+  const selection = selectItem(doc, slug);
+
+  let pane;
+  if (selection === null) {
+    pane = (
+      <EmptyState
+        title="No such item"
+        description={
+          <>
+            This document has nothing called <code>{slug}</code>.{" "}
+            <Link to={`${pathBase}/ws`}>Back to the connection</Link>.
+          </>
+        }
+      />
+    );
+  } else {
+    switch (selection.kind) {
+      case "channel":
+        pane = (
+          <ChannelPane
+            doc={doc}
+            root={spec}
+            channel={selection.channel}
+            limitsInfo={limitsInfo}
+            {...paneOptions}
+          />
+        );
+        break;
+      case "operation":
+        pane = (
+          <OperationPane
+            doc={doc}
+            operation={selection.operation}
+            {...paneOptions}
+          />
+        );
+        break;
+      case "message":
+        pane = (
+          <MessagePane
+            doc={doc}
+            root={spec}
+            message={selection.message}
+            {...paneOptions}
+          />
+        );
+        break;
+      case "limits":
+        pane = doc.limits && (
+          <LimitsPanel
+            limits={doc.limits}
+            extensionKey={doc.extensionKeys.limits}
+            limitsInfo={limitsInfo}
+          />
+        );
+        break;
+      case "close-codes":
+        pane = <CloseCodesPanel doc={doc} />;
+        break;
+      case "upgrade-refusals":
+        pane = <RefusalsPanel doc={doc} />;
+        break;
+    }
+  }
+
+  return (
+    <div
+      className="screen ws-docs"
+      data-testid="ws-docs"
+    >
+      <DocHeader doc={doc} />
+      <div className="ws-overview">
+        <ServerPanel doc={doc} />
+        <SecurityPanel doc={doc} />
+      </div>
+      <div className="ws-layout">
+        <WsSidebar
+          groups={groups}
+          selected={selection ? slug : ""}
+          query={query}
+          onQuery={setQuery}
+          pathBase={pathBase}
+        />
+        <section
+          className="ws-main"
+          aria-label="Selected item"
+          data-testid="ws-main"
+          data-selected={selection ? slug : ""}
+        >
+          {pane}
+        </section>
+      </div>
+    </div>
+  );
+}