@eifi1/ui-kit 0.10.0 → 0.12.0

package/src/components/error-boundary.tsx

@@ -0,0 +1,216 @@
+import { Component } from "react";
+import type { ErrorInfo, ReactNode } from "react";
+import { AlertTriangle } from "lucide-react";
+import { useKitLabels } from "../i18n/kit-labels";
+import { Button, EmptyState } from "./ui";
+import { Disclosure } from "./disclosure";
+
+/** The words of the default fallback. */
+export interface ErrorBoundaryLabels {
+  /** The fallback's heading. */
+  title: string;
+  /** The line under it. */
+  message: string;
+  /** The button that clears the error and renders the children again. */
+  retry: string;
+  /** The disclosure that opens the error's own text (`showDetails`). */
+  details: string;
+}
+
+export const DEFAULT_ERROR_BOUNDARY_LABELS: ErrorBoundaryLabels = {
+  title: "Something went wrong",
+  message: "This part of the page could not be shown. Try again, or reload the page.",
+  retry: "Try again",
+  details: "Error details",
+};
+
+/**
+ * What was thrown, as flat strings, read ONCE when it arrives.
+ *
+ * React stores whatever was thrown, hostile or not — `throw { get message() { throw … } }`,
+ * `throw { name: Symbol() }`, `throw undefined` — and reading one of those during the
+ * fallback's own render would throw INSIDE the boundary, escalating to the next one up
+ * (keksdose's error-boundary.tsx learned this as feedback #160: at the app level there is
+ * none, and the result is the white screen the boundary exists to prevent).
+ */
+export interface ErrorBoundaryDetails {
+  name: string;
+  message: string;
+  stack?: string;
+}
+
+function read(get: () => unknown): string | undefined {
+  try {
+    const v = get();
+    return typeof v === "string" ? v : v === undefined || v === null ? undefined : String(v);
+  } catch {
+    return undefined;
+  }
+}
+
+/** {@link ErrorBoundaryDetails} of any thrown value, without ever throwing. */
+export function describeThrown(error: unknown): ErrorBoundaryDetails {
+  if (typeof error === "object" && error !== null) {
+    const e = error as { name?: unknown; message?: unknown; stack?: unknown };
+    return {
+      name: read(() => e.name) ?? "Error",
+      message: read(() => e.message) ?? "",
+      stack: read(() => e.stack),
+    };
+  }
+  return { name: "Error", message: read(() => error) ?? "" };
+}
+
+/** What a render-prop `fallback` is handed. */
+export interface ErrorBoundaryFallbackProps {
+  /** The thrown value, as it was thrown. Read it with care — see {@link describeThrown}. */
+  error: unknown;
+  details: ErrorBoundaryDetails;
+  /** Clear the error and render the children again. */
+  reset: () => void;
+}
+
+export interface ErrorBoundaryProps {
+  children?: ReactNode;
+  /** Replaces the default fallback: a node, or a render function handed the error and
+   *  a `reset`. */
+  fallback?: ReactNode | ((props: ErrorBoundaryFallbackProps) => ReactNode);
+  /** Called once per caught error — log it, file a crash report. */
+  onError?: (error: unknown, info: ErrorInfo) => void;
+  /** Called when the error is cleared, by Retry, `reset` or a `resetKeys` change —
+   *  drop a cache, refetch. */
+  onReset?: () => void;
+  /**
+   * When any of these changes (compared with `Object.is`) AFTER an error was caught, the
+   * error is cleared and the children render again — a change in the same update that
+   * threw does not count (it is what the error was shown under) — pass the route path so leaving a broken page does not
+   * carry its fallback to the next one (keksdose's `resetKey`).
+   */
+  resetKeys?: ReadonlyArray<unknown>;
+  /** A disclosure under the message with the error's name, message and stack — for an
+   *  internal tool, or while developing. Off by default: a stack means nothing to a user. */
+  showDetails?: boolean;
+  /** The default fallback's heading level. Default `h2`: the fallback often IS the page. */
+  headingAs?: "h2" | "h3" | "h4" | "h5" | "h6";
+  /** Classes for the default fallback's box (`m-8 min-h-[400px]`, kastlan). */
+  className?: string;
+  labels?: Partial<ErrorBoundaryLabels>;
+}
+
+interface ErrorBoundaryState {
+  /** A flag of its own, so `throw undefined` is still an error shown. */
+  failed: boolean;
+  error: unknown;
+  details: ErrorBoundaryDetails | null;
+}
+
+const CLEAR: ErrorBoundaryState = { failed: false, error: null, details: null };
+
+function keysChanged(a: ReadonlyArray<unknown> | undefined, b: ReadonlyArray<unknown> | undefined): boolean {
+  if (a === b) return false;
+  if (!a || !b || a.length !== b.length) return true;
+  return a.some((v, i) => !Object.is(v, b[i]));
+}
+
+/**
+ * Catch a render error below it and show a fallback instead of an empty page.
+ *
+ * kastlan (shared/components/error-boundary.tsx) and keksdose (app/error-boundary.tsx)
+ * each built one on `EmptyState tone="danger"`: a warning glyph, a title, a line of
+ * explanation and a Retry. This is that fallback, translated through the provider
+ * (`errorBoundary.*`), with the hooks an app hangs its own behaviour on — `onError`
+ * for the crash report, `resetKeys` for the route change, `fallback` for anything else.
+ *
+ * The fallback is `role="alert"`: a page replaced by an error is news, and a reader
+ * that was on it is told.
+ */
+export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  state: ErrorBoundaryState = CLEAR;
+
+  static getDerivedStateFromError(error: unknown): Partial<ErrorBoundaryState> {
+    return { failed: true, error, details: describeThrown(error) };
+  }
+
+  componentDidCatch(error: unknown, info: ErrorInfo): void {
+    this.props.onError?.(error, info);
+  }
+
+  componentDidUpdate(prev: ErrorBoundaryProps, prevState: ErrorBoundaryState): void {
+    // Only a change AFTER the error was caught clears it (react-error-boundary's rule).
+    // `prevState.failed` is false in the update that caught it: that update may well be
+    // the one that changed the keys too — a navigation to a page that throws, with
+    // `resetKeys={[pathname]}` — and resetting then would fire `onReset` for nothing and
+    // render the failing child a second time. From then on `prev.resetKeys` are the
+    // keys the error was shown under, so any change clears it.
+    if (this.state.failed && prevState.failed && keysChanged(prev.resetKeys, this.props.resetKeys)) {
+      this.reset();
+    }
+  }
+
+  reset = (): void => {
+    this.props.onReset?.();
+    this.setState(CLEAR);
+  };
+
+  render(): ReactNode {
+    const { failed, error, details } = this.state;
+    if (!failed || !details) return this.props.children;
+    const { fallback } = this.props;
+    if (typeof fallback === "function") return fallback({ error, details, reset: this.reset });
+    if (fallback !== undefined) return fallback;
+    return (
+      <ErrorFallback
+        details={details}
+        reset={this.reset}
+        showDetails={this.props.showDetails ?? false}
+        headingAs={this.props.headingAs ?? "h2"}
+        className={this.props.className}
+        labels={this.props.labels}
+      />
+    );
+  }
+}
+
+function ErrorFallback({
+  details,
+  reset,
+  showDetails,
+  headingAs,
+  className,
+  labels,
+}: {
+  details: ErrorBoundaryDetails;
+  reset: () => void;
+  showDetails: boolean;
+  headingAs: NonNullable<ErrorBoundaryProps["headingAs"]>;
+  className?: string;
+  labels?: Partial<ErrorBoundaryLabels>;
+}) {
+  const text = useKitLabels("errorBoundary", DEFAULT_ERROR_BOUNDARY_LABELS, labels);
+  return (
+    <EmptyState
+      role="alert"
+      tone="danger"
+      headingAs={headingAs}
+      className={className}
+      icon={<AlertTriangle />}
+      title={text.title}
+      hint={text.message}
+      action={
+        <>
+          <Button variant="secondary" onClick={reset}>
+            {text.retry}
+          </Button>
+          {showDetails && (
+            <Disclosure variant="bare" title={text.details} className="basis-full text-start">
+              <pre className="max-h-60 overflow-auto whitespace-pre-wrap break-words text-xs text-[var(--text-secondary)]">
+                {details.message ? `${details.name}: ${details.message}` : details.name}
+                {details.stack ? `\n\n${details.stack}` : null}
+              </pre>
+            </Disclosure>
+          )}
+        </>
+      }
+    />
+  );
+}

package/src/components/field.tsx

@@ -0,0 +1,188 @@
+/**
+ * A field group with its label ABOVE the control: label, control, hint, error.
+ *
+ * ```tsx
+ * <Field label="IBAN" required hint="22 characters" error={errors.iban}>
+ *   {(ids) => <Input {...ids} value={iban} onChange={…} />}
+ * </Field>
+ * ```
+ *
+ * The kit's `Input` and `Select` float their label inside the field, and the pickers
+ * draw theirs the same way. That is the wrong shape for a control the kit did not
+ * render, a radio group, a range slider, or a form that sets its labels above the
+ * fields throughout — which is what kastlan's wizards are, and why it kept its own
+ * `WizardField` after the kit dropped the one it had never rendered. This is that
+ * group, with the wiring the old one left to the caller: the label names the control
+ * through `htmlFor`, and the control is described by the hint and the error that are
+ * actually on screen.
+ *
+ * ## Wiring
+ *
+ * Pass a function as `children` and it receives {@link FieldControlProps} — `id`,
+ * `aria-describedby`, `aria-invalid` and `aria-required` — to spread on the control.
+ * Plain children render as they are, for a control that wires itself (a checkbox that
+ * carries its own label, a group with `aria-labelledby`); `htmlFor` then points the
+ * label at the control's own id, and the hint and error are on screen but describe
+ * nothing — the same as the `WizardField` this replaces.
+ *
+ * ## Decoupled
+ *
+ * Deliberately knows neither the wizard nor react-hook-form: `error` is a plain
+ * value. Pass `wizard.fieldErrors.iban`, a step-local error, or
+ * `fieldState.error?.message` from a `FormField` render — the markup is the same
+ * whichever of them gates the step, so a step can move between them without its
+ * fields changing. (Inside a react-hook-form form, `FormItem` + `FormLabel` from
+ * `@eifi1/ui-kit/rhf` do the same job with the ids taken from the form.)
+ *
+ * The error is NOT `role="alert"`, for the reason the kit's `error` prop gives (see
+ * `useFieldError` in components/ui.tsx): it is read when focus reaches the control.
+ */
+import { useId, type ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { Label } from "./ui";
+
+/** What a `Field` hands its render-prop children, to spread on the control. */
+export interface FieldControlProps {
+  /** The id the label's `htmlFor` points at. */
+  id: string;
+  /** The ids of the hint and the error that are rendered, or `undefined` when
+   *  neither is. */
+  "aria-describedby": string | undefined;
+  /** `true` while the field has an error, `undefined` otherwise. */
+  "aria-invalid": true | undefined;
+  /** `true` when the field is `required`. The label's star is `aria-hidden`; this
+   *  is what a screen reader hears instead. */
+  "aria-required": true | undefined;
+}
+
+/**
+ * The second argument of a `Field`'s render-prop children: what a GROUP needs that
+ * a single control does not. `htmlFor` names an `<input>`, but a `<label>` pointing
+ * at a `role="radiogroup"` div names nothing — so a group (a {@link ToggleGroup})
+ * takes `aria-labelledby={labelId}` instead. Kept out of {@link FieldControlProps}
+ * so the spread every existing control takes is unchanged.
+ */
+export interface FieldRenderMeta {
+  /** The label element's id, or `undefined` when the field has no label. */
+  labelId: string | undefined;
+}
+
+/**
+ * Where the label is visible. `"visible"` (default); `"sr-only"`: never drawn, still
+ * the control's name; `"below-sm"` / `"below-md"` / `"below-lg"`: drawn only under
+ * that breakpoint and screen-reader-only from it up.
+ *
+ * For table-like editors — kastlan's journal entry lines
+ * (accounting/components/wizard/journal-entry-lines-step.tsx) — where a desktop
+ * row sits under column headers that already say "Account" and "Amount", but the
+ * phone layout stacks each line as a card and needs the labels back. The name stays
+ * on the control at every width; only the ink changes.
+ */
+export type FieldLabelVisibility = "visible" | "sr-only" | "below-sm" | "below-md" | "below-lg";
+
+// Literal class strings so Tailwind's scanner sees each one.
+const LABEL_VISIBILITY: Record<FieldLabelVisibility, string | undefined> = {
+  visible: undefined,
+  "sr-only": "sr-only",
+  "below-sm": "sm:sr-only",
+  "below-md": "md:sr-only",
+  "below-lg": "lg:sr-only",
+};
+
+export interface FieldProps {
+  /** The label above the control. Omit it for a group whose control is labelled
+   *  some other way; the hint and error still render. */
+  label?: ReactNode;
+  /** Draws the kit's required mark after the label, and sets `aria-required` on the
+   *  render-prop control. */
+  required?: boolean;
+  /** Muted helper text below the control. */
+  hint?: ReactNode;
+  /** The error below the control. `null`, `false` and `""` are no error — what a
+   *  `touched && errors.x` evaluates to on the happy path. */
+  error?: ReactNode;
+  /** The control's id. Defaults to a generated one; set it when the control carries
+   *  its own id (plain children). */
+  htmlFor?: string;
+  /** Dims the label with its control. */
+  disabled?: boolean;
+  /** The label's size: `sm` for a dense row, `md` otherwise. */
+  labelSize?: "sm" | "md";
+  /** See {@link FieldLabelVisibility}. */
+  labelVisibility?: FieldLabelVisibility;
+  /** Wrapper className. */
+  className?: string;
+  /** The control. A function receives {@link FieldControlProps} to spread on it, and
+   *  {@link FieldRenderMeta} (the label's id, for a group). */
+  children: ReactNode | ((control: FieldControlProps, meta: FieldRenderMeta) => ReactNode);
+}
+
+const isShown = (node: ReactNode) =>
+  node !== undefined && node !== null && node !== false && node !== "";
+
+export function Field({
+  label,
+  required,
+  hint,
+  error,
+  htmlFor,
+  disabled,
+  labelSize,
+  labelVisibility = "visible",
+  className,
+  children,
+}: FieldProps) {
+  const generated = useId();
+  const id = htmlFor ?? `${generated}-control`;
+  const hintId = `${generated}-hint`;
+  const errorId = `${generated}-error`;
+  const labelId = `${generated}-label`;
+  const hasHint = isShown(hint);
+  const hasError = isShown(error);
+  const describedBy = [hasHint && hintId, hasError && errorId].filter(Boolean).join(" ");
+  const control: FieldControlProps = {
+    id,
+    "aria-describedby": describedBy || undefined,
+    "aria-invalid": hasError || undefined,
+    "aria-required": required || undefined,
+  };
+  return (
+    <div
+      data-slot="field"
+      className={cn(
+        "grid gap-1.5",
+        // A hidden label is `position: absolute`; `relative` keeps its containing
+        // block here rather than the page's (see sr-only-containment.test).
+        labelVisibility !== "visible" && "relative",
+        className,
+      )}
+    >
+      {label !== undefined && (
+        <Label
+          id={labelId}
+          htmlFor={id}
+          required={required}
+          disabled={disabled}
+          size={labelSize}
+          data-error={hasError || undefined}
+          className={cn("data-[error=true]:text-[var(--danger)]", LABEL_VISIBILITY[labelVisibility])}
+        >
+          {label}
+        </Label>
+      )}
+      {typeof children === "function"
+        ? children(control, { labelId: label !== undefined ? labelId : undefined })
+        : children}
+      {hasHint && (
+        <p id={hintId} className="text-[11px] leading-tight text-[var(--text-muted)]">
+          {hint}
+        </p>
+      )}
+      {hasError && (
+        <p id={errorId} className="text-[11px] leading-tight text-[var(--danger)]">
+          {error}
+        </p>
+      )}
+    </div>
+  );
+}