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

package/app/docs/router.tsx

@@ -0,0 +1,194 @@
+import type { AnchorHTMLAttributes, MouseEvent, ReactNode } from "react";
+import type { NavigateOptions, RouteDef } from "./routing";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { ScreenErrorBoundary } from "./components/ScreenErrorBoundary";
+import {
+  matchPath,
+  normalizeBasePath,
+  ParamsContext,
+  readLocation,
+  RouterContext,
+  useLocation,
+  useNavigate,
+  useRouter,
+} from "./routing";
+
+/**
+ * The router's components: the provider, route matching, redirects and
+ * links. The pure path functions and the hooks live in `routing.ts`.
+ */
+
+/** Props of {@link RouterProvider}. */
+export interface RouterProviderProps {
+  /** The mount path (`DocsUiConfig.basePath`). */
+  basePath: string;
+  /** The app. */
+  children: ReactNode;
+}
+
+/** Provides routing under `basePath`, following `window.history`. */
+export function RouterProvider({ basePath, children }: RouterProviderProps) {
+  const base = normalizeBasePath(basePath);
+  const [location, setLocation] = useState(() => readLocation(base));
+
+  useEffect(() => {
+    const onPopState = () => setLocation(readLocation(base));
+    window.addEventListener("popstate", onPopState);
+    return () => window.removeEventListener("popstate", onPopState);
+  }, [base]);
+
+  const href = useCallback(
+    (to: string) => {
+      const target = to.startsWith("/") ? to : `/${to}`;
+      if (base === "") {
+        return target;
+      }
+      // `/` is the mount itself; keep the query attached without a slash.
+      return target === "/" || target.startsWith("/?")
+        ? `${base}${target.slice(1)}`
+        : `${base}${target}`;
+    },
+    [base],
+  );
+
+  const navigate = useCallback(
+    (to: string, options: NavigateOptions = {}) => {
+      const url = href(to);
+      if (options.replace) {
+        window.history.replaceState(null, "", url);
+      } else {
+        window.history.pushState(null, "", url);
+      }
+      setLocation(readLocation(base));
+    },
+    [base, href],
+  );
+
+  const value = useMemo(
+    () => ({ basePath: base, location, navigate, href }),
+    [base, location, navigate, href],
+  );
+  return <RouterContext value={value}>{children}</RouterContext>;
+}
+
+/** Props of {@link Routes}. */
+export interface RoutesProps {
+  /** Routes, tried in order; the first match wins. */
+  routes: readonly RouteDef[];
+  /** Rendered when nothing matches (including a URL outside `basePath`). */
+  notFound: ReactNode;
+}
+
+/**
+ * Renders the first route matching the current location, inside a
+ * {@link ScreenErrorBoundary}: a screen that crashes while rendering shows a
+ * recoverable panel in its place instead of blanking the app, and moving to
+ * another location tries again.
+ */
+export function Routes({ routes, notFound }: RoutesProps) {
+  const { path } = useLocation();
+  return (
+    <ScreenErrorBoundary resetKey={path ?? ""}>
+      <MatchedRoute
+        routes={routes}
+        notFound={notFound}
+        path={path}
+      />
+    </ScreenErrorBoundary>
+  );
+}
+
+/** The first route matching `path`, or `notFound`. */
+function MatchedRoute({
+  routes,
+  notFound,
+  path,
+}: RoutesProps & { path: string | null }) {
+  if (path !== null) {
+    for (const route of routes) {
+      const params = matchPath(route.path, path);
+      if (params) {
+        return (
+          <ParamsContext
+            key={route.path}
+            value={params}
+          >
+            {route.element}
+          </ParamsContext>
+        );
+      }
+    }
+  }
+  return <>{notFound}</>;
+}
+
+/** Props of {@link Navigate}. */
+export interface NavigateProps {
+  /** App path to go to. */
+  to: string;
+  /** Replace the history entry. Defaults to `true`: a redirect should not be a back-button stop. */
+  replace?: boolean;
+}
+
+/** Redirects on render. */
+export function Navigate({ to, replace = true }: NavigateProps) {
+  const navigate = useNavigate();
+  useEffect(() => {
+    navigate(to, { replace });
+  }, [navigate, to, replace]);
+  return null;
+}
+
+/** Props of {@link Link}. */
+export interface LinkProps extends Omit<
+  AnchorHTMLAttributes<HTMLAnchorElement>,
+  "href"
+> {
+  /** App path (relative to `basePath`), may carry `?query`. */
+  to: string;
+  /** Mark the link `aria-current="page"` when the location matches: `"exact"`, or `"prefix"` for a section. Defaults to none. */
+  activeMatch?: "exact" | "prefix";
+}
+
+/** Whether a click should be left to the browser (new tab, download, modified). */
+function isModifiedClick(event: MouseEvent<HTMLAnchorElement>): boolean {
+  return (
+    event.button !== 0 ||
+    event.metaKey ||
+    event.altKey ||
+    event.ctrlKey ||
+    event.shiftKey ||
+    event.defaultPrevented
+  );
+}
+
+/** An `<a>` that navigates in-app on a plain left-click. */
+export function Link({ to, activeMatch, onClick, target, ...rest }: LinkProps) {
+  const { navigate, href, location } = useRouter();
+  const toPath = to.split("?")[0] || "/";
+  const active =
+    location.path !== null &&
+    (activeMatch === "exact"
+      ? location.path === toPath
+      : activeMatch === "prefix"
+        ? toPath === "/"
+          ? location.path === "/"
+          : location.path === toPath || location.path.startsWith(`${toPath}/`)
+        : false);
+  return (
+    <a
+      {...rest}
+      target={target}
+      href={href(to)}
+      aria-current={active ? "page" : undefined}
+      onClick={(event) => {
+        onClick?.(event);
+        if (isModifiedClick(event) || (target && target !== "_self")) {
+          return;
+        }
+        event.preventDefault();
+        navigate(to);
+      }}
+    />
+  );
+}

package/app/docs/routing.ts

@@ -0,0 +1,194 @@
+import type { ReactNode } from "react";
+import { createContext, use, useCallback, useMemo } from "react";
+
+/**
+ * A small history router scoped under the mount's `basePath`.
+ *
+ * The app's routes are flat and few, so this replaces a router library: it
+ * tracks `location.pathname`/`search` relative to `basePath`, intercepts
+ * plain left-clicks on its {@link Link}s, matches `:param` and trailing `*`
+ * patterns, and keeps URL-addressable state in the query string. A path
+ * outside `basePath` matches nothing and renders the 404.
+ */
+
+/** Where the app is, relative to `basePath`. */
+export interface AppLocation {
+  /** Path under `basePath`, always starting with `/`; `null` when the URL is outside `basePath`. */
+  path: string | null;
+  /** The query string, with its leading `?` (or `""`). */
+  search: string;
+}
+
+/** Options of a navigation. */
+export interface NavigateOptions {
+  /** Replace the current history entry instead of pushing one. Defaults to `false`. */
+  replace?: boolean;
+}
+
+/** What the router provides. */
+export interface RouterContextValue {
+  /** The mount path, no trailing slash (`""` when mounted at the root). */
+  basePath: string;
+  /** The current location. */
+  location: AppLocation;
+  /** Navigates to an app path (relative to `basePath`, may carry `?query`). */
+  navigate: (to: string, options?: NavigateOptions) => void;
+  /** The full URL path for an app path. */
+  href: (to: string) => string;
+}
+
+/** Carries the router. */
+export const RouterContext = createContext<RouterContextValue | null>(null);
+/** Carries the params the matched route bound. */
+export const ParamsContext = createContext<Readonly<Record<string, string>>>(
+  {},
+);
+
+/** Normalises a base path: leading `/`, no trailing `/`, `/` itself becomes `""`. */
+export function normalizeBasePath(basePath: string): string {
+  const trimmed = basePath.replace(/\/+$/, "");
+  if (trimmed === "") {
+    return "";
+  }
+  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+
+/**
+ * The path under `basePath`, or `null` when `pathname` is outside it.
+ * `/jobs` and `/jobs/` are both `/`; `/jobsx` is outside `/jobs`.
+ */
+export function stripBasePath(
+  pathname: string,
+  basePath: string,
+): string | null {
+  const base = normalizeBasePath(basePath);
+  if (base !== "" && pathname !== base && !pathname.startsWith(`${base}/`)) {
+    return null;
+  }
+  const rest = pathname.slice(base.length);
+  if (rest === "" || rest === "/") {
+    return "/";
+  }
+  return rest.length > 1 && rest.endsWith("/") ? rest.slice(0, -1) : rest;
+}
+
+/**
+ * Matches an app path against a pattern: `/queues/:queue` binds `queue`
+ * (percent-decoded), a trailing `/*` binds the rest as `*`. Returns the
+ * params, or `null` when it does not match.
+ */
+export function matchPath(
+  pattern: string,
+  path: string,
+): Record<string, string> | null {
+  const patternParts = pattern.split("/").filter(Boolean);
+  const pathParts = path.split("/").filter(Boolean);
+  const params: Record<string, string> = {};
+  for (let index = 0; index < patternParts.length; index++) {
+    const part = patternParts[index];
+    if (part === "*" && index === patternParts.length - 1) {
+      params["*"] = pathParts.slice(index).map(safeDecode).join("/");
+      return params;
+    }
+    const actual = pathParts[index];
+    if (actual === undefined) {
+      return null;
+    }
+    if (part.startsWith(":")) {
+      params[part.slice(1)] = safeDecode(actual);
+    } else if (part !== actual) {
+      return null;
+    }
+  }
+  return pathParts.length === patternParts.length ? params : null;
+}
+
+/** `decodeURIComponent`, keeping a malformed segment as it is. */
+function safeDecode(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+/** Reads the current location from `window.location`. */
+export function readLocation(basePath: string): AppLocation {
+  return {
+    path: stripBasePath(window.location.pathname, basePath),
+    search: window.location.search,
+  };
+}
+
+/** The router, or a clear error outside a {@link RouterProvider}. */
+export function useRouter(): RouterContextValue {
+  const router = use(RouterContext);
+  if (!router) {
+    throw new Error("useRouter must be used inside a <RouterProvider>");
+  }
+  return router;
+}
+
+/** The current location. */
+export function useLocation(): AppLocation {
+  return useRouter().location;
+}
+
+/** A function that navigates to an app path. */
+export function useNavigate(): RouterContextValue["navigate"] {
+  return useRouter().navigate;
+}
+
+/** A function that turns an app path into a full URL path. */
+export function useHref(): RouterContextValue["href"] {
+  return useRouter().href;
+}
+
+/** The params the matched route bound. */
+export function useParams<
+  T extends Record<string, string> = Record<string, string>,
+>(): Readonly<T> {
+  return use(ParamsContext) as Readonly<T>;
+}
+
+/** The current query string, parsed. */
+export function useSearchParams(): URLSearchParams {
+  const { search } = useLocation();
+  return useMemo(() => new URLSearchParams(search), [search]);
+}
+
+/**
+ * One query-string value as state: `[value, setValue]`. Setting `""` or
+ * `null` removes the key. Updates replace the history entry, so typing in a
+ * filter does not flood the back button.
+ */
+export function useQueryParam(
+  key: string,
+): [string, (value: string | null) => void] {
+  const { location, navigate } = useRouter();
+  const value = new URLSearchParams(location.search).get(key) ?? "";
+  const setValue = useCallback(
+    (next: string | null) => {
+      const params = new URLSearchParams(window.location.search);
+      if (next === null || next === "") {
+        params.delete(key);
+      } else {
+        params.set(key, next);
+      }
+      const query = params.toString();
+      navigate(`${location.path ?? "/"}${query ? `?${query}` : ""}`, {
+        replace: true,
+      });
+    },
+    [key, location.path, navigate],
+  );
+  return [value, setValue];
+}
+
+/** One route: a pattern and what it renders. */
+export interface RouteDef {
+  /** Pattern relative to `basePath`: `/`, `/queues/:queue`, `/docs/*`. */
+  path: string;
+  /** What the route renders; params are available through {@link useParams}. */
+  element: ReactNode;
+}

package/app/docs/screens/docs/document.ts

@@ -0,0 +1,27 @@
+/**
+ * The loaded document, shared by the viewer's routes: its context and hook,
+ * kept apart from `viewer.tsx` so that file exports components only (fast
+ * refresh, `react/only-export-components`).
+ */
+import type { DocumentKind, SpecDocument } from "../../api/docs";
+import { createContext, use } from "react";
+
+/** What the loaded document is. */
+export interface LoadedDocument {
+  /** The document. */
+  doc: SpecDocument;
+  /** Its kind. */
+  kind: DocumentKind;
+}
+
+/** Carries the loaded document. */
+export const DocumentContext = createContext<LoadedDocument | null>(null);
+
+/** The loaded document, or a clear error outside `<DocsViewer>`. */
+export function useDocument(): LoadedDocument {
+  const loaded = use(DocumentContext);
+  if (!loaded) {
+    throw new Error("useDocument must be used inside <DocsViewer>");
+  }
+  return loaded;
+}