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

package/app/docs/components/KeyValue.tsx

@@ -0,0 +1,63 @@
+import type { ReactNode } from "react";
+import { cx } from "./classNames";
+
+/** One row of a {@link KeyValue}. */
+export interface KeyValueItem {
+  /** The term, e.g. "Attempts". */
+  label: ReactNode;
+  /** The value: text or any node. `null`, `undefined` and `""` render the `empty` placeholder. */
+  value: ReactNode;
+  /** A stable React key; defaults to the label when it is a string, else the index. */
+  key?: string;
+  /** A short note under the value, e.g. "of 5 allowed". */
+  hint?: ReactNode;
+}
+
+/** Props of {@link KeyValue}. */
+export interface KeyValueProps {
+  /** The rows, in order. Falsy entries are skipped, so rows can be conditional inline. */
+  items: readonly (KeyValueItem | false | null | undefined)[];
+  /** `"grid"` puts label and value side by side; `"stacked"` puts the label above. Defaults to `"grid"`. */
+  layout?: "grid" | "stacked";
+  /** What a missing value shows. Defaults to `"—"`. */
+  empty?: ReactNode;
+  /** Extra class names on the `<dl>`. */
+  className?: string;
+}
+
+/** A summary as a definition list: label/value rows (a job's timings, a queue's settings). */
+export function KeyValue({
+  items,
+  layout = "grid",
+  empty = "—",
+  className,
+}: KeyValueProps) {
+  return (
+    <dl className={cx("kv", `kv-${layout}`, className)}>
+      {items.map((item, index) => {
+        if (!item) {
+          return null;
+        }
+        const missing =
+          item.value === null || item.value === undefined || item.value === "";
+        // The index is only the fallback for a row with neither a key nor a
+        // string label.
+        const rowKey =
+          item.key ??
+          (typeof item.label === "string" ? item.label : `row-${index}`);
+        return (
+          <div
+            key={rowKey}
+            className="kv-row"
+          >
+            <dt className="kv-label">{item.label}</dt>
+            <dd className={cx("kv-value", missing && "muted")}>
+              {missing ? empty : item.value}
+              {item.hint && <span className="kv-hint">{item.hint}</span>}
+            </dd>
+          </div>
+        );
+      })}
+    </dl>
+  );
+}

package/app/docs/components/ProblemBanner.tsx

@@ -0,0 +1,116 @@
+import { isApiError } from "../api/errors";
+import { Button } from "./Button";
+import { cx } from "./classNames";
+
+/** Props of {@link ProblemBanner}. */
+export interface ProblemBannerProps {
+  /** What failed: an `ApiError` shows its title, code, detail, context and issues; anything else its message. */
+  error: unknown;
+  /** A heading override, e.g. "Could not save limits". Defaults to the problem's title. */
+  title?: string;
+  /** Offers a Retry button when given. */
+  onRetry?: () => void;
+  /** Offers a Dismiss button when given. */
+  onDismiss?: () => void;
+  /** Extra class names. */
+  className?: string;
+}
+
+/** Formats one context value for the banner: strings as-is, the rest as JSON. */
+function contextText(value: unknown): string {
+  if (typeof value === "string") {
+    return value;
+  }
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
+/**
+ * A compact, inline error for a panel or a dialog: one line of title and
+ * code, the detail, the problem's `context` as `key=value` chips, and any
+ * validation issues. {@link ErrorView} is the full-size version for a screen.
+ */
+export function ProblemBanner({
+  error,
+  title,
+  onRetry,
+  onDismiss,
+  className,
+}: ProblemBannerProps) {
+  const api = isApiError(error) ? error : null;
+  const heading = title ?? api?.title ?? "Something went wrong";
+  const detail =
+    api?.detail ?? (error instanceof Error ? error.message : String(error));
+  const context = api ? Object.entries(api.context) : [];
+  return (
+    <div
+      className={cx("problem-banner", className)}
+      role="alert"
+    >
+      <div className="problem-banner-main">
+        <p className="problem-banner-title">
+          <strong>{heading}</strong>
+          {api && (
+            <code className="problem-banner-code">
+              {api.code}
+              {api.status > 0 ? ` · ${api.status}` : ""}
+            </code>
+          )}
+        </p>
+        {detail && detail !== heading && (
+          <p className="problem-banner-detail">{detail}</p>
+        )}
+        {context.length > 0 && (
+          <ul
+            className="problem-banner-context"
+            aria-label="Context"
+          >
+            {context.map(([key, value]) => (
+              <li key={key}>
+                <span className="problem-banner-key">{key}</span>=
+                <code>{contextText(value)}</code>
+              </li>
+            ))}
+          </ul>
+        )}
+        {api && api.issues.length > 0 && (
+          <ul className="problem-banner-issues">
+            {api.issues.map((issue) => (
+              <li key={`${issue.target}:${issue.path}:${issue.message}`}>
+                <code>
+                  {issue.target}
+                  {issue.path ? `.${issue.path}` : ""}
+                </code>{" "}
+                {issue.message}
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+      {(onRetry || onDismiss) && (
+        <div className="problem-banner-actions">
+          {onRetry && (
+            <Button
+              size="sm"
+              onClick={onRetry}
+            >
+              Retry
+            </Button>
+          )}
+          {onDismiss && (
+            <Button
+              size="sm"
+              variant="ghost"
+              onClick={onDismiss}
+            >
+              Dismiss
+            </Button>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

package/app/docs/components/ScreenErrorBoundary.tsx

@@ -0,0 +1,141 @@
+import type { QueryClient } from "@tanstack/react-query";
+import type { ErrorInfo, ReactNode } from "react";
+import { QueryClientContext } from "@tanstack/react-query";
+import { Component } from "react";
+import { resetScreenQueries } from "../queryClient";
+import { Button } from "./Button";
+
+/** Props of {@link ScreenErrorBoundary}. */
+export interface ScreenErrorBoundaryProps {
+  /** The screen. */
+  children: ReactNode;
+  /** When this changes (the location), a failed screen is tried again: navigating away from a crash recovers without a click. */
+  resetKey?: string;
+  /** Called with each crash, e.g. to log it. Defaults to nothing (React already reports it in development). */
+  onError?: (error: unknown, info: ErrorInfo) => void;
+}
+
+/** State of {@link ScreenErrorBoundary}. */
+interface ScreenErrorBoundaryState {
+  /** What the screen threw while rendering, or `null` while it renders fine. */
+  error: unknown;
+  /** Whether {@link ScreenErrorBoundaryState.error} is set (an error may be any value, `null` included). */
+  failed: boolean;
+  /** Bumped by "Reload this screen", remounting the screen with fresh state. */
+  attempt: number;
+  /** The `resetKey` the failure happened under. */
+  failedKey: string | undefined;
+}
+
+/**
+ * Catches a routed screen's render crash so the app around it survives: the
+ * header, nav and live status stay, and the screen's place shows what
+ * failed with a "Reload this screen" button that mounts it afresh and
+ * re-reads its data: the cached answers it read are reset first (see
+ * {@link resetScreenQueries}; `/meta` and the permissions are kept), so a
+ * crash caused by a bad answer recovers once the host answers well. A lazy
+ * screen whose chunk failed to load is retried the same way (see
+ * `screens/lazy.tsx`).
+ *
+ * The app's queries do not throw into it (no `throwOnError`, no suspense
+ * queries: a failed read renders the screen's own error view), so there is
+ * no `QueryErrorResetBoundary` to reset.
+ */
+export class ScreenErrorBoundary extends Component<
+  ScreenErrorBoundaryProps,
+  ScreenErrorBoundaryState
+> {
+  static override contextType = QueryClientContext;
+
+  /** The app's query client, when a `QueryClientProvider` is above (none in some tests). */
+  declare context: QueryClient | undefined;
+
+  override state: ScreenErrorBoundaryState = {
+    error: null,
+    failed: false,
+    attempt: 0,
+    failedKey: undefined,
+  };
+
+  static getDerivedStateFromError(
+    error: unknown,
+  ): Partial<ScreenErrorBoundaryState> {
+    return { error, failed: true };
+  }
+
+  static getDerivedStateFromProps(
+    props: ScreenErrorBoundaryProps,
+    state: ScreenErrorBoundaryState,
+  ): Partial<ScreenErrorBoundaryState> | null {
+    // Remember where it failed; a new location clears the failure.
+    if (state.failed && state.failedKey === undefined) {
+      return { failedKey: props.resetKey ?? "" };
+    }
+    if (state.failed && state.failedKey !== (props.resetKey ?? "")) {
+      return {
+        error: null,
+        failed: false,
+        failedKey: undefined,
+        attempt: state.attempt + 1,
+      };
+    }
+    return null;
+  }
+
+  override componentDidCatch(error: unknown, info: ErrorInfo): void {
+    this.props.onError?.(error, info);
+  }
+
+  /** Resets the screen's cached answers, then mounts it again. */
+  private readonly reload = () => {
+    if (this.context) {
+      void resetScreenQueries(this.context);
+    }
+    this.setState((state) => ({
+      error: null,
+      failed: false,
+      failedKey: undefined,
+      attempt: state.attempt + 1,
+    }));
+  };
+
+  override render(): ReactNode {
+    const { error, failed, attempt } = this.state;
+    if (!failed) {
+      return <ScreenAttempt key={attempt}>{this.props.children}</ScreenAttempt>;
+    }
+    const message =
+      error instanceof Error ? error.message : String(error ?? "Unknown error");
+    return (
+      <div
+        className="screen screen-error"
+        data-testid="screen-error"
+      >
+        <div
+          className="error-view"
+          role="alert"
+        >
+          <h1 className="error-view-title">This screen failed to show</h1>
+          <p className="error-view-detail">
+            Something went wrong while drawing it. The rest of the app still
+            works: reload the screen, or pick another one.
+          </p>
+          <p className="error-view-meta">
+            <code>{message}</code>
+          </p>
+          <Button
+            variant="primary"
+            onClick={this.reload}
+          >
+            Reload this screen
+          </Button>
+        </div>
+      </div>
+    );
+  }
+}
+
+/** A keyed wrapper: a new key remounts the screen with fresh state. */
+function ScreenAttempt({ children }: { children: ReactNode }) {
+  return <>{children}</>;
+}

package/app/docs/components/Spinner.tsx

@@ -0,0 +1,33 @@
+import { cx } from "./classNames";
+
+/** Props of {@link Spinner}. */
+export interface SpinnerProps {
+  /** What is loading; read by screen readers. Defaults to `"Loading"`. */
+  label?: string;
+  /** Show the label next to the spinner. Defaults to `false` (screen readers only). */
+  showLabel?: boolean;
+  /** Extra class names. */
+  className?: string;
+}
+
+/** A loading indicator with a live `status` role. */
+export function Spinner({
+  label = "Loading",
+  showLabel = false,
+  className,
+}: SpinnerProps) {
+  return (
+    <span
+      className={cx("spinner-wrap", className)}
+      role="status"
+    >
+      <span
+        className="spinner"
+        aria-hidden="true"
+      />
+      <span className={showLabel ? "spinner-label" : "visually-hidden"}>
+        {label}
+      </span>
+    </span>
+  );
+}

package/app/docs/components/Table.tsx

@@ -0,0 +1,33 @@
+import type { ReactNode } from "react";
+import { cx } from "./classNames";
+
+/** Props of {@link Table}. */
+export interface TableProps {
+  /** Accessible name of the table (rendered as a visually hidden caption). */
+  label: string;
+  /** Extra class names on the `<table>`. */
+  className?: string;
+  /** `<thead>` / `<tbody>`. */
+  children: ReactNode;
+}
+
+/**
+ * A table in a scrollable, focusable region with a sticky header. Keyboard
+ * users can scroll a wide table because the region is tabbable.
+ */
+export function Table({ label, className, children }: TableProps) {
+  return (
+    <div
+      className="table-wrap"
+      role="region"
+      aria-label={label}
+      // A scrollable region must be reachable by keyboard.
+      tabIndex={0}
+    >
+      <table className={cx("table", className)}>
+        <caption className="visually-hidden">{label}</caption>
+        {children}
+      </table>
+    </div>
+  );
+}

package/app/docs/components/Tabs.tsx

@@ -0,0 +1,226 @@
+import type { KeyboardEvent, ReactNode } from "react";
+import { useCallback, useId, useRef } from "react";
+import { useUrlTab } from "../hooks/useUrlTab";
+import { useRouter } from "../routing";
+import { cx } from "./classNames";
+
+/** One tab of {@link Tabs}. */
+export interface TabItem<V extends string> {
+  /** The tab's value, e.g. a job state. */
+  value: V;
+  /** The text on the tab. */
+  label: ReactNode;
+  /** A count shown as a badge beside the label; omitted when `undefined`. */
+  count?: number;
+  /** Not selectable. */
+  disabled?: boolean;
+  /** A tooltip on the tab (its `title`), e.g. what a state's label means. Omitted when `undefined`. */
+  title?: string;
+}
+
+/** Props of {@link Tabs}. */
+export interface TabsProps<V extends string> {
+  /** The tabs, in order. */
+  tabs: readonly TabItem<V>[];
+  /** The selected tab's value. */
+  value: V;
+  /** Called with the tab the user picked. */
+  onChange: (value: V) => void;
+  /** Accessible name of the tab list, e.g. "Job states". */
+  label: string;
+  /** The selected tab's content, rendered in the single tab panel. Omit to render only the tab list. */
+  children?: ReactNode;
+  /** `"auto"` selects on arrow-key focus; `"manual"` waits for Enter/Space. Defaults to `"auto"`. */
+  activation?: "auto" | "manual";
+  /** Extra class names on the wrapper. */
+  className?: string;
+}
+
+/** Formats a tab count compactly: `1234` → `1.2K`. */
+const countFormat = new Intl.NumberFormat(undefined, { notation: "compact" });
+
+/**
+ * Controlled tabs following the WAI-ARIA tabs pattern: `tablist`/`tab`/
+ * `tabpanel`, one tab in the tab order (roving `tabIndex`), Left/Right to
+ * move (wrapping), Home/End to jump. Disabled tabs are skipped.
+ */
+export function Tabs<V extends string>({
+  tabs,
+  value,
+  onChange,
+  label,
+  children,
+  activation = "auto",
+  className,
+}: TabsProps<V>) {
+  const baseId = useId();
+  const listRef = useRef<HTMLDivElement>(null);
+  const tabId = (index: number) => `${baseId}-tab-${index}`;
+  const panelId = `${baseId}-panel`;
+  const selectedIndex = tabs.findIndex((tab) => tab.value === value);
+
+  const onKeyDown = (event: KeyboardEvent<HTMLButtonElement>) => {
+    const enabled = tabs
+      .map((tab, index) => ({ tab, index }))
+      .filter(({ tab }) => !tab.disabled);
+    if (enabled.length === 0) {
+      return;
+    }
+    const current = enabled.findIndex(
+      ({ index }) => tabId(index) === event.currentTarget.id,
+    );
+    let next: number | null = null;
+    switch (event.key) {
+      case "ArrowRight":
+        next = (current + 1) % enabled.length;
+        break;
+      case "ArrowLeft":
+        next = (current - 1 + enabled.length) % enabled.length;
+        break;
+      case "Home":
+        next = 0;
+        break;
+      case "End":
+        next = enabled.length - 1;
+        break;
+      default:
+        return;
+    }
+    event.preventDefault();
+    const target = enabled[next];
+    listRef.current?.ownerDocument.getElementById(tabId(target.index))?.focus();
+    if (activation === "auto") {
+      onChange(target.tab.value);
+    }
+  };
+
+  return (
+    <div className={cx("tabs", className)}>
+      <div
+        ref={listRef}
+        className="tabs-list"
+        role="tablist"
+        aria-label={label}
+      >
+        {tabs.map((tab, index) => {
+          const selected = index === selectedIndex;
+          // With nothing selected, the first enabled tab takes the tab stop.
+          const tabStop =
+            selected ||
+            (selectedIndex === -1 &&
+              index === tabs.findIndex((item) => !item.disabled));
+          return (
+            <button
+              key={tab.value}
+              id={tabId(index)}
+              type="button"
+              role="tab"
+              className="tab"
+              aria-selected={selected}
+              aria-controls={children !== undefined ? panelId : undefined}
+              tabIndex={tabStop ? 0 : -1}
+              disabled={tab.disabled}
+              title={tab.title}
+              onClick={() => onChange(tab.value)}
+              onKeyDown={onKeyDown}
+            >
+              <span className="tab-label">{tab.label}</span>
+              {tab.count !== undefined && (
+                <span
+                  className="tab-count"
+                  title={String(tab.count)}
+                >
+                  {countFormat.format(tab.count)}
+                </span>
+              )}
+            </button>
+          );
+        })}
+      </div>
+      {children !== undefined && (
+        <div
+          id={panelId}
+          className="tabs-panel"
+          role="tabpanel"
+          aria-labelledby={
+            selectedIndex >= 0 ? tabId(selectedIndex) : undefined
+          }
+          tabIndex={0}
+        >
+          {children}
+        </div>
+      )}
+    </div>
+  );
+}
+
+/** Props of {@link UrlTabs}. */
+export interface UrlTabsProps<V extends string> extends Omit<
+  TabsProps<V>,
+  "value" | "onChange"
+> {
+  /** The query parameter holding the tab, e.g. `"state"`. */
+  param: string;
+  /** The tab when the parameter is absent or not one of `tabs`; selecting it removes the parameter. */
+  defaultValue: V;
+  /** Query parameters to remove when the tab changes, e.g. `["offset"]` so paging restarts. */
+  resetParams?: readonly string[];
+  /** Called after the URL changed. */
+  onChange?: (value: V) => void;
+}
+
+/**
+ * {@link Tabs} whose selection lives in the query string (`?state=failed`),
+ * so it survives reload and can be linked. Changes replace the history entry
+ * (the router's `navigate(…, { replace: true })`), keep every other
+ * parameter, and drop the `resetParams`.
+ */
+export function UrlTabs<V extends string>({
+  param,
+  defaultValue,
+  resetParams = [],
+  onChange,
+  tabs,
+  ...rest
+}: UrlTabsProps<V>) {
+  const { location, navigate } = useRouter();
+  const value = useUrlTab(param, tabs, defaultValue);
+  const select = useCallback(
+    (next: V) => {
+      const params = new URLSearchParams(location.search);
+      if (next === defaultValue) {
+        params.delete(param);
+      } else {
+        params.set(param, next);
+      }
+      if (next !== value) {
+        for (const key of resetParams) {
+          params.delete(key);
+        }
+      }
+      const query = params.toString();
+      navigate(`${location.path ?? "/"}${query ? `?${query}` : ""}`, {
+        replace: true,
+      });
+      onChange?.(next);
+    },
+    [
+      location.search,
+      location.path,
+      defaultValue,
+      param,
+      value,
+      resetParams,
+      navigate,
+      onChange,
+    ],
+  );
+  return (
+    <Tabs
+      {...rest}
+      tabs={tabs}
+      value={value}
+      onChange={select}
+    />
+  );
+}

package/app/docs/components/classNames.ts

@@ -0,0 +1,4 @@
+/** Joins class names, skipping falsy ones. */
+export function cx(...names: (string | false | null | undefined)[]): string {
+  return names.filter(Boolean).join(" ");
+}