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

package/app/docs/components/copy.ts

@@ -0,0 +1,89 @@
+/**
+ * Clipboard and JSON-serialisation helpers shared by {@link CopyButton} and
+ * {@link JsonView}.
+ */
+
+/** How long a {@link CopyButton}'s "Copied" / "Copy failed" feedback shows, in ms. */
+export const COPY_FEEDBACK_MS = 1_500;
+
+/**
+ * Writes `text` to the clipboard. Resolves `false` instead of throwing when
+ * the Clipboard API is missing (an insecure origin, an old browser) or the
+ * write is refused (no permission, the document not focused).
+ */
+export async function copyText(text: string): Promise<boolean> {
+  try {
+    if (typeof navigator === "undefined" || !navigator.clipboard) {
+      return false;
+    }
+    await navigator.clipboard.writeText(text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** What {@link toJsonSafe} puts where a reference points back at an ancestor. */
+export const CIRCULAR_MARKER = "[Circular]";
+
+/**
+ * A JSON-safe copy of any value: circular references become
+ * {@link CIRCULAR_MARKER} (a shared, non-circular reference is kept), a
+ * `bigint` becomes its decimal string, `undefined` inside an array becomes
+ * `null` (as `JSON.stringify` would), functions and symbols are dropped from
+ * objects, and anything with `toJSON` (a `Date`) is serialised through it.
+ *
+ * The guard is a `WeakSet` of the objects on the current path: added on the
+ * way down, deleted on the way back up, so it flags cycles and nothing else.
+ */
+export function toJsonSafe(value: unknown): unknown {
+  const path = new WeakSet<object>();
+  const walk = (current: unknown): unknown => {
+    if (typeof current === "bigint") {
+      return current.toString();
+    }
+    if (typeof current === "function" || typeof current === "symbol") {
+      return undefined;
+    }
+    if (typeof current !== "object" || current === null) {
+      return current;
+    }
+    if (path.has(current)) {
+      return CIRCULAR_MARKER;
+    }
+    const withJson = current as { toJSON?: unknown };
+    if (typeof withJson.toJSON === "function") {
+      return walk((withJson.toJSON as () => unknown).call(current));
+    }
+    path.add(current);
+    try {
+      if (Array.isArray(current)) {
+        return current.map((item) => {
+          const safe = walk(item);
+          return safe === undefined ? null : safe;
+        });
+      }
+      const out: Record<string, unknown> = {};
+      for (const [key, item] of Object.entries(current)) {
+        const safe = walk(item);
+        if (safe !== undefined) {
+          out[key] = safe;
+        }
+      }
+      return out;
+    } finally {
+      path.delete(current);
+    }
+  };
+  return walk(value);
+}
+
+/**
+ * `JSON.stringify` that never throws: circular input and bigints are handled
+ * by {@link toJsonSafe}, and a bare `undefined` becomes the text `undefined`.
+ */
+export function safeStringify(value: unknown, indent = 2): string {
+  const text = JSON.stringify(toJsonSafe(value), null, indent) as
+    string | undefined;
+  return text ?? "undefined";
+}

package/app/docs/components/fieldContext.ts

@@ -0,0 +1,29 @@
+import { createContext, use } from "react";
+
+/** What a {@link Field} tells the control inside it. */
+export interface FieldControlProps {
+  /** The control's `id`; the field's `<label htmlFor>` points at it. */
+  id: string;
+  /** Ids of the hint and error (and any extra description), space separated; `undefined` when there are none. */
+  "aria-describedby": string | undefined;
+  /** `true` while the field shows an error. */
+  "aria-invalid": boolean | undefined;
+  /** Whether the field is marked required. */
+  required: boolean | undefined;
+}
+
+/** Carries the enclosing field's wiring; `null` outside a field. */
+export const FieldContext = createContext<FieldControlProps | null>(null);
+
+/** The enclosing {@link Field}'s wiring, or `null` when the control stands alone. */
+export function useField(): FieldControlProps | null {
+  return use(FieldContext);
+}
+
+/** Joins ids for `aria-describedby`, skipping empty ones; `undefined` when none are left. */
+export function joinIds(
+  ...ids: (string | false | null | undefined)[]
+): string | undefined {
+  const joined = ids.filter(Boolean).join(" ");
+  return joined === "" ? undefined : joined;
+}

package/app/docs/components/inputValues.ts

@@ -0,0 +1,142 @@
+import { MAX_DATE_MS } from "../api/contract";
+
+/**
+ * Value conversions of the kit's inputs, pure. The `datetime-local` value
+ * (`YYYY-MM-DDTHH:mm[:ss]`) is wall-clock time in the browser's own time
+ * zone.
+ */
+
+/** Parses an `<input type="number">` value: `""` (empty or unparsable) → `undefined`. */
+export function parseNumberInput(text: string): number | undefined {
+  if (text.trim() === "") {
+    return undefined;
+  }
+  const value = Number(text);
+  return Number.isFinite(value) ? value : undefined;
+}
+
+/** Pads to two digits. */
+function pad(value: number): string {
+  return String(value).padStart(2, "0");
+}
+
+/**
+ * Epoch ms → a `datetime-local` value in local time. Seconds are included
+ * when `withSeconds` is set; otherwise the value is truncated to the minute.
+ * `undefined`/`NaN` → `""`.
+ */
+export function toDateTimeLocal(
+  ms: number | undefined | null,
+  withSeconds = false,
+): string {
+  if (ms === undefined || ms === null || !Number.isFinite(ms)) {
+    return "";
+  }
+  const date = new Date(ms);
+  const day = `${String(date.getFullYear()).padStart(4, "0")}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+  const time = `${pad(date.getHours())}:${pad(date.getMinutes())}`;
+  return `${day}T${time}${withSeconds ? `:${pad(date.getSeconds())}` : ""}`;
+}
+
+/** The shape a `datetime-local` value takes. */
+const DATE_TIME_LOCAL =
+  /^(\d{4,})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?$/;
+
+/** A `datetime-local` value → epoch ms, read as local time; `undefined` when empty or malformed. */
+export function fromDateTimeLocal(text: string): number | undefined {
+  const match = DATE_TIME_LOCAL.exec(text.trim());
+  if (!match) {
+    return undefined;
+  }
+  const [, year, month, day, hours, minutes, seconds, fraction] = match;
+  const ms = new Date(
+    Number(year),
+    Number(month) - 1,
+    Number(day),
+    Number(hours),
+    Number(minutes),
+    Number(seconds ?? 0),
+    Number((fraction ?? "0").padEnd(3, "0")),
+  ).getTime();
+  return Number.isNaN(ms) ? undefined : ms;
+}
+
+/** Shown for a `datetime-local` value the browser could not read, or that is malformed. */
+export const DATE_TIME_UNREADABLE =
+  "Not a date and time this browser can read. Pick one again, or clear the field.";
+
+/**
+ * Shown for a time outside what the API accepts: epoch ms from 0 to
+ * `MAX_DATE_MS`, the last instant a `Date` holds (the API refuses anything
+ * else with 400 `VALIDATION` at the field).
+ */
+export const DATE_TIME_OUT_OF_RANGE =
+  "Pick a time from 1 January 1970 to 13 September 275760 (UTC): the API accepts no other.";
+
+/** What {@link readDateTimeLocal} found in a `datetime-local` value. */
+export type DateTimeReading =
+  /** Nothing: the field was cleared. */
+  | { kind: "empty" }
+  /** A time the API accepts, epoch ms. */
+  | { kind: "time"; ms: number }
+  /** Something unusable; `problem` says why, for the field's error. */
+  | { kind: "problem"; problem: string };
+
+/**
+ * Reads a `datetime-local` value the way the API will judge it. Empty is
+ * `empty` unless the browser flags a half-typed entry (`badInput`, for which
+ * it reports `""`). A malformed value, or one naming a day that does not
+ * exist, is {@link DATE_TIME_UNREADABLE}; a time before the epoch or after
+ * `MAX_DATE_MS` (which `Date` cannot even build) is
+ * {@link DATE_TIME_OUT_OF_RANGE}.
+ */
+export function readDateTimeLocal(
+  text: string,
+  badInput = false,
+): DateTimeReading {
+  const trimmed = text.trim();
+  if (trimmed === "") {
+    return badInput
+      ? { kind: "problem", problem: DATE_TIME_UNREADABLE }
+      : { kind: "empty" };
+  }
+  const match = DATE_TIME_LOCAL.exec(trimmed);
+  if (!match) {
+    return { kind: "problem", problem: DATE_TIME_UNREADABLE };
+  }
+  const [, year, month, day, hours, minutes, seconds] = match.map(Number);
+  if (
+    month < 1 ||
+    month > 12 ||
+    day < 1 ||
+    day > daysInMonth(year, month) ||
+    hours > 23 ||
+    minutes > 59 ||
+    (seconds ?? 0) > 59
+  ) {
+    return { kind: "problem", problem: DATE_TIME_UNREADABLE };
+  }
+  const ms = fromDateTimeLocal(trimmed);
+  if (ms === undefined || ms < 0 || ms > MAX_DATE_MS) {
+    return { kind: "problem", problem: DATE_TIME_OUT_OF_RANGE };
+  }
+  return { kind: "time", ms };
+}
+
+/** Days in a month (1-12) of a proleptic Gregorian year. */
+function daysInMonth(year: number, month: number): number {
+  if (month === 2) {
+    const leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+    return leap ? 29 : 28;
+  }
+  return [4, 6, 9, 11].includes(month) ? 30 : 31;
+}
+
+/** The browser's time zone name (e.g. `"Europe/London"`), or `"local time"` when unknown. */
+export function localTimeZone(): string {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || "local time";
+  } catch {
+    return "local time";
+  }
+}

package/app/docs/components/inputs.tsx

@@ -0,0 +1,387 @@
+import type {
+  ChangeEvent,
+  InputHTMLAttributes,
+  ReactNode,
+  Ref,
+  SelectHTMLAttributes,
+} from "react";
+import { useEffect, useId, useRef, useState } from "react";
+import { cx } from "./classNames";
+import { joinIds, useField } from "./fieldContext";
+import {
+  localTimeZone,
+  parseNumberInput,
+  readDateTimeLocal,
+  toDateTimeLocal,
+} from "./inputValues";
+
+/**
+ * The kit's form controls. Inside a {@link Field} each takes its id,
+ * `aria-describedby`, `aria-invalid` and `required` from it; explicit props
+ * win, and an explicit `aria-describedby` is added to the field's.
+ */
+
+/** Wiring props every control accepts. */
+interface ControlWiring {
+  /** The element id. Defaults to the enclosing field's. */
+  id?: string;
+  /** Extra description ids, added to the field's. */
+  "aria-describedby"?: string;
+  /** Invalid state. Defaults to the enclosing field's. */
+  "aria-invalid"?: boolean;
+  /** Required. Defaults to the enclosing field's. */
+  required?: boolean;
+}
+
+/** Resolves a control's wiring against the enclosing field. */
+function useWiring(props: ControlWiring) {
+  const field = useField();
+  return {
+    id: props.id ?? field?.id,
+    "aria-describedby": joinIds(
+      field?.["aria-describedby"],
+      props["aria-describedby"],
+    ),
+    "aria-invalid": props["aria-invalid"] ?? field?.["aria-invalid"],
+    required: props.required ?? field?.required,
+  };
+}
+
+/** Native input props the kit's inputs pass through (value and change are typed per control). */
+type PassThroughInputProps = Omit<
+  InputHTMLAttributes<HTMLInputElement>,
+  | "value"
+  | "defaultValue"
+  | "onChange"
+  | "type"
+  | "id"
+  | "aria-describedby"
+  | "aria-invalid"
+  | "required"
+  | "min"
+  | "max"
+  | "step"
+> & {
+  /** The underlying `<input>`, e.g. to focus it. */
+  ref?: Ref<HTMLInputElement>;
+};
+
+/** Props of {@link TextInput}. */
+export interface TextInputProps extends PassThroughInputProps, ControlWiring {
+  /** The text. */
+  value: string;
+  /** Called with the new text on each edit. */
+  onChange: (value: string, event: ChangeEvent<HTMLInputElement>) => void;
+  /** The input type. Defaults to `"text"`. */
+  type?: "text" | "search" | "email" | "url" | "password" | "tel";
+}
+
+/** A single-line text input. */
+export function TextInput({
+  value,
+  onChange,
+  type = "text",
+  className,
+  ...rest
+}: TextInputProps) {
+  const wiring = useWiring(rest);
+  return (
+    <input
+      {...rest}
+      {...wiring}
+      type={type}
+      className={cx("input", className)}
+      value={value}
+      onChange={(event) => onChange(event.target.value, event)}
+    />
+  );
+}
+
+/** Props of {@link NumberInput}. */
+export interface NumberInputProps extends PassThroughInputProps, ControlWiring {
+  /** The number, or `undefined` for empty. */
+  value: number | undefined;
+  /** Called with the new number, or `undefined` when the input is empty (or not a number). */
+  onChange: (
+    value: number | undefined,
+    event: ChangeEvent<HTMLInputElement>,
+  ) => void;
+  /** Smallest allowed value (native validation only; the value is not clamped). */
+  min?: number;
+  /** Largest allowed value (native validation only; the value is not clamped). */
+  max?: number;
+  /** Step. Defaults to `1`; pass `"any"` for decimals. */
+  step?: number | "any";
+}
+
+/** A number input where empty means `undefined`, never `0`. */
+export function NumberInput({
+  value,
+  onChange,
+  min,
+  max,
+  step = 1,
+  className,
+  ...rest
+}: NumberInputProps) {
+  const wiring = useWiring(rest);
+  return (
+    <input
+      inputMode={step === "any" ? "decimal" : "numeric"}
+      {...rest}
+      {...wiring}
+      type="number"
+      className={cx("input", "input-number", className)}
+      min={min}
+      max={max}
+      step={step}
+      value={value === undefined || Number.isNaN(value) ? "" : value}
+      onChange={(event) =>
+        onChange(parseNumberInput(event.target.value), event)
+      }
+    />
+  );
+}
+
+/** One option of a {@link Select}. */
+export interface SelectOption<V extends string> {
+  /** The value. */
+  value: V;
+  /** The text shown. Defaults to the value. */
+  label?: string;
+  /** Not selectable. */
+  disabled?: boolean;
+}
+
+/** Props of {@link Select}. */
+export interface SelectProps<V extends string>
+  extends
+    Omit<
+      SelectHTMLAttributes<HTMLSelectElement>,
+      | "value"
+      | "defaultValue"
+      | "onChange"
+      | "id"
+      | "aria-describedby"
+      | "aria-invalid"
+      | "required"
+      | "multiple"
+    >,
+    ControlWiring {
+  /** The choices. Include `{ value: "", label: "Any" }` (with `""` in `V`) for an "unset" choice. */
+  options: readonly SelectOption<V>[];
+  /** The selected value. */
+  value: V;
+  /** Called with the chosen value. */
+  onChange: (value: V, event: ChangeEvent<HTMLSelectElement>) => void;
+}
+
+/** A native `<select>` over a typed set of string values. */
+export function Select<V extends string>({
+  options,
+  value,
+  onChange,
+  className,
+  ...rest
+}: SelectProps<V>) {
+  const wiring = useWiring(rest);
+  return (
+    <select
+      {...rest}
+      {...wiring}
+      className={cx("input", "select", className)}
+      value={value}
+      onChange={(event) => {
+        const chosen = options.find(
+          (option) => option.value === event.target.value,
+        );
+        if (chosen) {
+          onChange(chosen.value, event);
+        }
+      }}
+    >
+      {options.map((option) => (
+        <option
+          key={option.value}
+          value={option.value}
+          disabled={option.disabled}
+        >
+          {option.label ?? option.value}
+        </option>
+      ))}
+    </select>
+  );
+}
+
+/** Props of {@link Checkbox}. */
+export interface CheckboxProps extends Omit<
+  PassThroughInputProps,
+  "checked" | "defaultChecked"
+> {
+  /** Whether it is ticked. */
+  checked: boolean;
+  /** Called with the new state. */
+  onChange: (checked: boolean, event: ChangeEvent<HTMLInputElement>) => void;
+  /** The label beside the box; clicking it toggles. */
+  label: ReactNode;
+  /** Help under the label; it describes the box. */
+  hint?: ReactNode;
+  /** The element id. Defaults to a generated one. */
+  id?: string;
+}
+
+/** A checkbox with its own label (it does not need a {@link Field}). */
+export function Checkbox({
+  checked,
+  onChange,
+  label,
+  hint,
+  id,
+  className,
+  ...rest
+}: CheckboxProps) {
+  const generatedId = useId();
+  const inputId = id ?? generatedId;
+  const hintId = `${inputId}-hint`;
+  return (
+    <div className={cx("checkbox", className)}>
+      <input
+        {...rest}
+        id={inputId}
+        type="checkbox"
+        checked={checked}
+        aria-describedby={hint ? hintId : undefined}
+        onChange={(event) => onChange(event.target.checked, event)}
+      />
+      <label htmlFor={inputId}>{label}</label>
+      {hint && (
+        <p
+          id={hintId}
+          className="field-hint checkbox-hint"
+        >
+          {hint}
+        </p>
+      )}
+    </div>
+  );
+}
+
+/** Props of {@link DateTimeInput}. */
+export interface DateTimeInputProps
+  extends Omit<PassThroughInputProps, "min" | "max">, ControlWiring {
+  /** The instant, epoch ms, or `undefined` for empty. */
+  value: number | undefined;
+  /**
+   * Called with the instant (epoch ms) the user picked, or `undefined` when
+   * cleared, or when the field holds something unusable (then `onProblem`
+   * says what).
+   */
+  onChange: (
+    value: number | undefined,
+    event: ChangeEvent<HTMLInputElement>,
+  ) => void;
+  /**
+   * Called with a message when the field holds something unusable — a time
+   * outside what the API accepts (0 to `MAX_DATE_MS`) or one the browser
+   * could not read — and with `undefined` once it holds a usable time, is
+   * cleared, or unmounts. Judged on each change and again on blur, since a
+   * half-typed entry into an empty field fires no change. The typed text is
+   * kept on screen meanwhile. Show the message as the field's error and hold
+   * the form back until it clears (`useFieldProblems`, in
+   * `hooks/useFieldProblems`).
+   */
+  onProblem?: (problem: string | undefined) => void;
+  /** Earliest allowed instant, epoch ms (native validation only). */
+  min?: number;
+  /** Latest allowed instant, epoch ms (native validation only). */
+  max?: number;
+  /** Let the user pick seconds. Defaults to `false` (minute precision). */
+  withSeconds?: boolean;
+  /** Show the browser's time zone beside the input. Defaults to `true`. */
+  showTimeZone?: boolean;
+}
+
+/**
+ * A `datetime-local` input speaking epoch ms. The wall-clock value is read
+ * in the browser's time zone, which is shown beside it (and part of its
+ * description), so "09:00" is never ambiguous.
+ */
+export function DateTimeInput({
+  value,
+  onChange,
+  onProblem,
+  min,
+  max,
+  withSeconds = false,
+  showTimeZone = true,
+  className,
+  onBlur,
+  ...rest
+}: DateTimeInputProps) {
+  const zoneId = useId();
+  const wiring = useWiring(rest);
+  // What the user typed, kept on screen while it is unusable (the value is
+  // then `undefined`, which would otherwise blank the field).
+  const [draft, setDraft] = useState<string | null>(null);
+  const onProblemRef = useRef(onProblem);
+  useEffect(() => {
+    onProblemRef.current = onProblem;
+  });
+  // A field that goes away takes its problem with it.
+  useEffect(() => () => onProblemRef.current?.(undefined), []);
+  return (
+    <span className="input-group">
+      <input
+        {...rest}
+        {...wiring}
+        aria-describedby={joinIds(
+          wiring["aria-describedby"],
+          showTimeZone && zoneId,
+        )}
+        type="datetime-local"
+        className={cx("input", "input-datetime", className)}
+        step={withSeconds ? 1 : 60}
+        min={min === undefined ? undefined : toDateTimeLocal(min, withSeconds)}
+        max={max === undefined ? undefined : toDateTimeLocal(max, withSeconds)}
+        value={
+          value === undefined
+            ? (draft ?? "")
+            : toDateTimeLocal(value, withSeconds)
+        }
+        onChange={(event) => {
+          const reading = readDateTimeLocal(
+            event.target.value,
+            event.target.validity.badInput,
+          );
+          if (reading.kind === "problem") {
+            setDraft(event.target.value);
+            onChange(undefined, event);
+            onProblem?.(reading.problem);
+            return;
+          }
+          setDraft(null);
+          onChange(reading.kind === "time" ? reading.ms : undefined, event);
+          onProblem?.(undefined);
+        }}
+        // A half-typed entry into an empty field fires no change (its value
+        // stays ""), so it is judged again on leaving the field.
+        onBlur={(event) => {
+          onBlur?.(event);
+          const reading = readDateTimeLocal(
+            event.target.value,
+            event.target.validity.badInput,
+          );
+          onProblem?.(reading.kind === "problem" ? reading.problem : undefined);
+        }}
+      />
+      {showTimeZone && (
+        <span
+          id={zoneId}
+          className="input-suffix"
+        >
+          {localTimeZone()}
+        </span>
+      )}
+    </span>
+  );
+}