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

package/app/docs/components/EmptyState.tsx

@@ -0,0 +1,34 @@
+import type { ReactNode } from "react";
+
+/** Props of {@link EmptyState}. */
+export interface EmptyStateProps {
+  /** The headline, e.g. "No queues yet". */
+  title: string;
+  /** A sentence of explanation. */
+  description?: ReactNode;
+  /** A follow-up control. */
+  action?: ReactNode;
+  /**
+   * Render the headline as a heading of this level instead of a paragraph.
+   * Use `1` when the empty state IS the screen (a not-found or hidden screen
+   * has no other `h1`). Defaults to none (a paragraph).
+   */
+  headingLevel?: 1 | 2 | 3;
+}
+
+/** What a list or screen shows when there is nothing to show. */
+export function EmptyState({
+  title,
+  description,
+  action,
+  headingLevel,
+}: EmptyStateProps) {
+  const Title = headingLevel ? (`h${headingLevel}` as const) : "p";
+  return (
+    <div className="empty-state">
+      <Title className="empty-state-title">{title}</Title>
+      {description && <p className="empty-state-description">{description}</p>}
+      {action && <div className="empty-state-action">{action}</div>}
+    </div>
+  );
+}

package/app/docs/components/ErrorView.tsx

@@ -0,0 +1,70 @@
+import { isApiError } from "../api/errors";
+import { Button } from "./Button";
+
+/** Props of {@link ErrorView}. */
+export interface ErrorViewProps {
+  /** What failed: an `ApiError` renders its problem fields, anything else a generic message. */
+  error: unknown;
+  /** A heading override, e.g. "Could not load queues". */
+  title?: string;
+  /** Offers a retry button when given. */
+  onRetry?: () => void;
+  /**
+   * Render the heading as a heading of this level instead of a paragraph.
+   * Use `1` when the error replaces the whole screen, so it still has its
+   * `h1`. Defaults to none (a paragraph).
+   */
+  headingLevel?: 1 | 2 | 3;
+}
+
+/** Renders a failed request: title, detail, code/status, and validation issues. */
+export function ErrorView({
+  error,
+  title,
+  onRetry,
+  headingLevel,
+}: ErrorViewProps) {
+  const Title = headingLevel ? (`h${headingLevel}` as const) : "p";
+  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));
+  return (
+    <div
+      className="error-view"
+      role="alert"
+    >
+      <Title className="error-view-title">{heading}</Title>
+      {detail && detail !== heading && (
+        <p className="error-view-detail">{detail}</p>
+      )}
+      {api && (
+        <p className="error-view-meta">
+          <code>{api.code}</code>
+          {api.status > 0 && <span> · HTTP {api.status}</span>}
+        </p>
+      )}
+      {api && api.issues.length > 0 && (
+        <ul className="error-view-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>
+      )}
+      {onRetry && (
+        <Button
+          variant="secondary"
+          onClick={onRetry}
+        >
+          Retry
+        </Button>
+      )}
+    </div>
+  );
+}

package/app/docs/components/Field.tsx

@@ -0,0 +1,93 @@
+import type { ReactNode } from "react";
+import type { FieldControlProps } from "./fieldContext";
+import { useId, useMemo } from "react";
+import { cx } from "./classNames";
+import { FieldContext, joinIds } from "./fieldContext";
+
+/** Props of {@link Field}. */
+export interface FieldProps {
+  /** The visible label, a `<label>` for the control. */
+  label: ReactNode;
+  /** Help under the control; it describes the control (`aria-describedby`). */
+  hint?: ReactNode;
+  /** An error under the control; it describes the control and sets `aria-invalid`. Falsy means valid. */
+  error?: ReactNode;
+  /** Show a required marker and mark the control required. Defaults to `false`. */
+  required?: boolean;
+  /** The control's id. Defaults to a generated one. */
+  id?: string;
+  /** Extra class names on the wrapper. */
+  className?: string;
+  /** The control: one of this kit's inputs (they read the wiring from context), or a render function receiving it for anything else. */
+  children: ReactNode | ((control: FieldControlProps) => ReactNode);
+}
+
+/**
+ * A labelled form row: label, control, hint and error. The kit's inputs
+ * ({@link TextInput}, {@link NumberInput}, {@link Select},
+ * {@link DateTimeInput}, `JsonEditor`) pick up the id, `aria-describedby`,
+ * `aria-invalid` and `required` from it; a plain element can take them from
+ * the render-function form of `children`.
+ */
+export function Field({
+  label,
+  hint,
+  error,
+  required = false,
+  id,
+  className,
+  children,
+}: FieldProps) {
+  const generatedId = useId();
+  const controlId = id ?? generatedId;
+  const hintId = `${controlId}-hint`;
+  const errorId = `${controlId}-error`;
+  const hasError = Boolean(error);
+  const control = useMemo<FieldControlProps>(
+    () => ({
+      id: controlId,
+      "aria-describedby": joinIds(hint ? hintId : null, hasError && errorId),
+      "aria-invalid": hasError || undefined,
+      required: required || undefined,
+    }),
+    [controlId, hint, hintId, hasError, errorId, required],
+  );
+  return (
+    <div className={cx("field", hasError && "field-invalid", className)}>
+      <label
+        className="field-label"
+        htmlFor={controlId}
+      >
+        {label}
+        {required && (
+          <span
+            className="field-required"
+            aria-hidden="true"
+          >
+            {" "}
+            *
+          </span>
+        )}
+      </label>
+      <FieldContext value={control}>
+        {typeof children === "function" ? children(control) : children}
+      </FieldContext>
+      {hint && (
+        <p
+          id={hintId}
+          className="field-hint"
+        >
+          {hint}
+        </p>
+      )}
+      {hasError && (
+        <p
+          id={errorId}
+          className="field-error"
+        >
+          {error}
+        </p>
+      )}
+    </div>
+  );
+}

package/app/docs/components/JsonEditor.tsx

@@ -0,0 +1,151 @@
+import type { JsonEditorState, JsonEditorStateOptions } from "./jsonParse";
+import { useId, useMemo } from "react";
+import { Button } from "./Button";
+import { cx } from "./classNames";
+import { joinIds, useField } from "./fieldContext";
+import { formatBytes, jsonEditorState } from "./jsonParse";
+
+/** Props of {@link JsonEditor}. */
+export interface JsonEditorProps extends JsonEditorStateOptions {
+  /** The text (controlled). Seed it with `JSON.stringify(value, null, 2)`. */
+  value: string;
+  /** Called on every edit, format and minify with the new state. */
+  onChange: (state: JsonEditorState) => void;
+  /** Visible rows. Defaults to `10`. */
+  rows?: number;
+  /** Accessible name when not inside a `Field`. */
+  "aria-label"?: string;
+  /** The textarea's id. Defaults to the enclosing field's, or a generated one. */
+  id?: string;
+  /** Read-only: no editing, no format/minify. */
+  readOnly?: boolean;
+  /** Disabled. */
+  disabled?: boolean;
+  /** Placeholder text. */
+  placeholder?: string;
+  /** Extra class names on the wrapper. */
+  className?: string;
+}
+
+/**
+ * A plain-textarea JSON editor: the parse error with line and column, a
+ * UTF-8 size meter against `maxBytes` (turning red over it), and Format /
+ * Minify. Inside a `Field` it takes the field's id and description.
+ */
+export function JsonEditor({
+  value: text,
+  onChange,
+  maxBytes,
+  allowEmpty = false,
+  rows = 10,
+  "aria-label": ariaLabel,
+  id,
+  readOnly = false,
+  disabled = false,
+  placeholder,
+  className,
+}: JsonEditorProps) {
+  const field = useField();
+  const generatedId = useId();
+  const inputId = id ?? field?.id ?? generatedId;
+  const errorId = `${inputId}-json-error`;
+  const sizeId = `${inputId}-json-size`;
+  const state = useMemo(
+    () => jsonEditorState(text, { maxBytes, allowEmpty }),
+    [text, maxBytes, allowEmpty],
+  );
+  const emit = (next: string) =>
+    onChange(jsonEditorState(next, { maxBytes, allowEmpty }));
+  const reformat = (indent: number | undefined) => {
+    if (state.error === null && state.value !== undefined) {
+      emit(JSON.stringify(state.value, null, indent));
+    }
+  };
+  const canFormat =
+    !readOnly && !disabled && state.error === null && state.value !== undefined;
+
+  return (
+    <div
+      className={cx(
+        "json-editor",
+        !state.valid && "json-editor-invalid",
+        className,
+      )}
+    >
+      <textarea
+        id={inputId}
+        className="input json-editor-text"
+        rows={rows}
+        value={text}
+        placeholder={placeholder}
+        readOnly={readOnly}
+        disabled={disabled}
+        spellCheck={false}
+        autoCapitalize="off"
+        autoComplete="off"
+        aria-label={ariaLabel}
+        aria-invalid={!state.valid || field?.["aria-invalid"] || undefined}
+        aria-required={field?.required}
+        aria-describedby={joinIds(
+          field?.["aria-describedby"],
+          state.error && errorId,
+          sizeId,
+        )}
+        onChange={(event) => emit(event.target.value)}
+      />
+      <div className="json-editor-bar">
+        {state.error ? (
+          <p
+            id={errorId}
+            className="json-editor-error"
+          >
+            Line {state.error.line}, column {state.error.column}:{" "}
+            {state.error.message}
+          </p>
+        ) : (
+          <p className="json-editor-ok muted">Valid JSON</p>
+        )}
+        <span
+          id={sizeId}
+          className={cx("json-editor-size", state.overLimit && "is-over")}
+        >
+          {maxBytes !== undefined && (
+            <meter
+              className="json-editor-meter"
+              min={0}
+              max={maxBytes}
+              low={maxBytes * 0.8}
+              high={maxBytes}
+              optimum={0}
+              value={Math.min(state.bytes, maxBytes)}
+              aria-hidden="true"
+            />
+          )}
+          {maxBytes === undefined
+            ? formatBytes(state.bytes)
+            : state.overLimit
+              ? `${formatBytes(state.bytes)} of ${formatBytes(maxBytes)}: over the limit by ${formatBytes(state.bytes - maxBytes)}`
+              : `${formatBytes(state.bytes)} of ${formatBytes(maxBytes)}`}
+        </span>
+        {!readOnly && (
+          <span className="json-editor-actions">
+            <Button
+              size="sm"
+              disabled={!canFormat}
+              onClick={() => reformat(2)}
+            >
+              Format
+            </Button>
+            <Button
+              size="sm"
+              disabled={!canFormat}
+              onClick={() => reformat(undefined)}
+            >
+              Minify
+            </Button>
+          </span>
+        )}
+      </div>
+    </div>
+  );
+}

package/app/docs/components/JsonView.tsx

@@ -0,0 +1,338 @@
+import type { ReactNode } from "react";
+import { useState } from "react";
+import { cx } from "./classNames";
+import { safeStringify } from "./copy";
+import { CopyButton } from "./CopyButton";
+
+/** Limits of a {@link JsonView}. */
+interface ViewLimits {
+  /** Levels expanded on first render. */
+  expandDepth: number;
+  /** Characters of a string shown before "show more". */
+  maxStringLength: number;
+  /** Children rendered per expand (and per "show more"). */
+  maxChildren: number;
+}
+
+/** Props of {@link JsonView}. */
+export interface JsonViewProps {
+  /** Any value: JSON, `undefined`, a `Date`, a `bigint`, even a circular object. */
+  value: unknown;
+  /** Accessible name of the tree, e.g. "Job data". Defaults to `"JSON"`. */
+  label?: string;
+  /** Levels expanded on first render; `0` starts collapsed. Defaults to `1`. */
+  expandDepth?: number;
+  /** Characters of a string shown before a "show more" control. Defaults to `200`. */
+  maxStringLength?: number;
+  /** Array items / object keys rendered per expand; "show more" renders the next batch. Defaults to `100`. */
+  maxChildren?: number;
+  /** Show a Copy button for the whole value (serialised on click, circular-safe). Defaults to `true`. */
+  copyable?: boolean;
+  /** Extra class names. */
+  className?: string;
+}
+
+/** What a value looks like to the viewer. */
+type Kind =
+  | "object"
+  | "array"
+  | "string"
+  | "number"
+  | "boolean"
+  | "null"
+  | "undefined"
+  | "other";
+
+/** Classifies a value for rendering. */
+function kindOf(value: unknown): Kind {
+  if (value === null) {
+    return "null";
+  }
+  if (Array.isArray(value)) {
+    return "array";
+  }
+  switch (typeof value) {
+    case "object":
+      return value instanceof Date ? "other" : "object";
+    case "string":
+      return "string";
+    case "number":
+    case "bigint":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "undefined":
+      return "undefined";
+    default:
+      return "other";
+  }
+}
+
+/** A primitive's (or opaque value's) text. */
+function scalarText(value: unknown): string {
+  if (typeof value === "bigint") {
+    return `${value}n`;
+  }
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? "Invalid Date" : value.toISOString();
+  }
+  if (typeof value === "symbol" || typeof value === "function") {
+    return value.toString();
+  }
+  return String(value);
+}
+
+/** The first `limit` entries of a container, arrays keyed by index; never touches the rest. */
+function entriesOf(value: object, limit: number): [string, unknown][] {
+  if (Array.isArray(value)) {
+    return value
+      .slice(0, limit)
+      .map((item: unknown, index) => [String(index), item]);
+  }
+  const record = value as Record<string, unknown>;
+  return Object.keys(record)
+    .slice(0, limit)
+    .map((key) => [key, record[key]]);
+}
+
+/**
+ * A read-only, collapsible tree of any value. Built for job payloads of any
+ * size: levels past `expandDepth` start collapsed, each expand renders at
+ * most `maxChildren` children (with "show more"), long strings are cut at
+ * `maxStringLength`, and a reference back to an ancestor renders as
+ * `[Circular]` instead of recursing.
+ */
+export function JsonView({
+  value,
+  label = "JSON",
+  expandDepth = 1,
+  maxStringLength = 200,
+  maxChildren = 100,
+  copyable = true,
+  className,
+}: JsonViewProps) {
+  const limits: ViewLimits = { expandDepth, maxStringLength, maxChildren };
+  return (
+    <div className={cx("json-view", className)}>
+      {copyable && (
+        <div className="json-view-toolbar">
+          <CopyButton
+            text={() => safeStringify(value, 2)}
+            ariaLabel={`Copy ${label}`}
+          />
+        </div>
+      )}
+      <ul
+        className="json-tree"
+        aria-label={label}
+      >
+        <JsonNode
+          name={null}
+          value={value}
+          depth={0}
+          ancestors={[]}
+          limits={limits}
+        />
+      </ul>
+    </div>
+  );
+}
+
+/** Props of {@link JsonNode}. */
+interface JsonNodeProps {
+  /** The key or index, or `null` at the root. */
+  name: string | null;
+  /** The value at this node. */
+  value: unknown;
+  /** Nesting level, root = 0. */
+  depth: number;
+  /** The containers above this node, for the circular check. */
+  ancestors: readonly object[];
+  /** Rendering limits. */
+  limits: ViewLimits;
+}
+
+/** One key/value row, expandable when the value is a non-empty container. */
+function JsonNode({ name, value, depth, ancestors, limits }: JsonNodeProps) {
+  const kind = kindOf(value);
+  const key = name === null ? null : <span className="json-key">{name}: </span>;
+
+  if (kind !== "object" && kind !== "array") {
+    return (
+      <li className="json-row">
+        {key}
+        <JsonScalar
+          value={value}
+          kind={kind}
+          maxLength={limits.maxStringLength}
+        />
+      </li>
+    );
+  }
+
+  const container = value as object;
+  if (ancestors.includes(container)) {
+    return (
+      <li className="json-row">
+        {key}
+        <span className="json-circular">[Circular]</span>
+      </li>
+    );
+  }
+  return (
+    <JsonContainer
+      nameNode={key}
+      value={container}
+      isArray={kind === "array"}
+      depth={depth}
+      ancestors={ancestors}
+      limits={limits}
+    />
+  );
+}
+
+/** Props of {@link JsonContainer}. */
+interface JsonContainerProps {
+  /** The rendered key, or `null` at the root. */
+  nameNode: ReactNode;
+  /** The object or array. */
+  value: object;
+  /** Whether it is an array. */
+  isArray: boolean;
+  /** Nesting level. */
+  depth: number;
+  /** The containers above it. */
+  ancestors: readonly object[];
+  /** Rendering limits. */
+  limits: ViewLimits;
+}
+
+/** An object or array: a disclosure button, and its children once expanded. */
+function JsonContainer({
+  nameNode,
+  value,
+  isArray,
+  depth,
+  ancestors,
+  limits,
+}: JsonContainerProps) {
+  const [expanded, setExpanded] = useState(depth < limits.expandDepth);
+  const [shown, setShown] = useState(limits.maxChildren);
+  // Object.keys is O(n) but cheap next to rendering; children are only
+  // materialised while expanded.
+  const size = isArray
+    ? (value as unknown[]).length
+    : Object.keys(value).length;
+  const open = isArray ? "[" : "{";
+  const close = isArray ? "]" : "}";
+  const summary = isArray
+    ? `${size} ${size === 1 ? "item" : "items"}`
+    : `${size} ${size === 1 ? "key" : "keys"}`;
+
+  if (size === 0) {
+    return (
+      <li className="json-row">
+        {nameNode}
+        <span className="json-punct">
+          {open}
+          {close}
+        </span>
+      </li>
+    );
+  }
+
+  const children = expanded ? entriesOf(value, shown) : [];
+  const nextAncestors = expanded ? [...ancestors, value] : ancestors;
+  return (
+    <li className="json-row json-container">
+      <button
+        type="button"
+        className="json-toggle"
+        aria-expanded={expanded}
+        onClick={() => setExpanded((current) => !current)}
+      >
+        <span
+          className="json-caret"
+          aria-hidden="true"
+        />
+        {nameNode}
+        <span className="json-punct">{open}</span>
+        {!expanded && (
+          <>
+            <span className="json-summary">{summary}</span>
+            <span className="json-punct">{close}</span>
+          </>
+        )}
+      </button>
+      {expanded && (
+        <>
+          <ul className="json-children">
+            {children.map(([key, item]) => (
+              <JsonNode
+                key={key}
+                name={key}
+                value={item}
+                depth={depth + 1}
+                ancestors={nextAncestors}
+                limits={limits}
+              />
+            ))}
+            {size > shown && (
+              <li className="json-row">
+                <button
+                  type="button"
+                  className="json-more"
+                  onClick={() =>
+                    setShown((current) => current + limits.maxChildren)
+                  }
+                >
+                  Show {Math.min(limits.maxChildren, size - shown)} more (
+                  {size - shown} hidden)
+                </button>
+              </li>
+            )}
+          </ul>
+          <span className="json-punct">{close}</span>
+        </>
+      )}
+    </li>
+  );
+}
+
+/** Props of {@link JsonScalar}. */
+interface JsonScalarProps {
+  /** The value. */
+  value: unknown;
+  /** Its kind. */
+  kind: Kind;
+  /** String length before truncation. */
+  maxLength: number;
+}
+
+/** A leaf value, colour-coded; long strings truncate with "show more". */
+function JsonScalar({ value, kind, maxLength }: JsonScalarProps) {
+  const [full, setFull] = useState(false);
+  if (kind === "string") {
+    const text = value as string;
+    const cut = !full && text.length > maxLength;
+    return (
+      <>
+        <span className="json-string">
+          &quot;{cut ? text.slice(0, maxLength) : text}
+          {cut ? "…" : ""}&quot;
+        </span>
+        {text.length > maxLength && (
+          <button
+            type="button"
+            className="json-more"
+            aria-expanded={full}
+            onClick={() => setFull((current) => !current)}
+          >
+            {full ? "Show less" : `Show more (${text.length} chars)`}
+          </button>
+        )}
+      </>
+    );
+  }
+  return <span className={`json-${kind}`}>{scalarText(value)}</span>;
+}