@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/dialog/passport.json

@@ -0,0 +1,344 @@
+{
+  "passportVersion": "1.0.0",
+  "identity": {
+    "component": "Dialog",
+    "folder": "dialog",
+    "exports": [
+      "Dialog",
+      "DialogHost"
+    ]
+  },
+  "source": {
+    "libraryVersion": "2.4.0",
+    "files": [
+      "core/api.ts",
+      "core/dialog.ts",
+      "core/index.ts",
+      "core/store.ts",
+      "core/types.ts",
+      "index.ts",
+      "react/Dialog.tsx",
+      "react/DialogHost.tsx",
+      "react/icons.tsx",
+      "react/locale.ts",
+      "react/props.ts"
+    ],
+    "sourceHash": "sha256:054631ef8ddc464b32edabedea2cf26e4aa7e57a18d596dc6a65081e790283b1"
+  },
+  "props": [
+    {
+      "name": "cancelLabel",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "classNames",
+      "type": "other",
+      "typeText": "Partial<Record<DialogSlot, string>> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "confirmLabel",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "defaultValue",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "default": "",
+      "origin": "derived"
+    },
+    {
+      "name": "description",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "dismissible",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": true,
+      "origin": "derived",
+      "description": "Escape and a backdrop click count as Cancel. Default true.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "icon",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "Replaces the intent's icon; `null` hides it.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "id",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "inputLabel",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "inputType",
+      "type": "enum",
+      "values": [
+        "email",
+        "number",
+        "password",
+        "tel",
+        "text",
+        "url"
+      ],
+      "typeText": "'number' | 'email' | 'tel' | 'text' | 'url' | 'password' | undefined",
+      "required": false,
+      "default": "text",
+      "origin": "derived"
+    },
+    {
+      "name": "intent",
+      "type": "enum",
+      "values": [
+        "danger",
+        "default",
+        "info",
+        "success",
+        "warning"
+      ],
+      "typeText": "DialogIntent | undefined",
+      "required": false,
+      "default": "default",
+      "origin": "derived",
+      "description": "Sets the icon and the confirm button's color. `danger` also focuses Cancel first.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "kind",
+      "type": "enum",
+      "values": [
+        "alert",
+        "confirm",
+        "prompt"
+      ],
+      "typeText": "DialogKind | undefined",
+      "required": false,
+      "default": "confirm",
+      "origin": "derived",
+      "description": "`alert` has one button, `confirm` two, `prompt` adds a text field. Default `confirm`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "localeText",
+      "type": "other",
+      "typeText": "Partial<DialogLocaleText> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "onClose",
+      "type": "function",
+      "signature": "((action: DialogAction, value: string) => void) | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "The user answered. Set `open` to false here.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "onConfirm",
+      "type": "function",
+      "signature": "((value: string) => void | Promise<void>) | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Runs on Confirm, with the prompt's value. While its promise is pending the\nbuttons show progress; if it throws, the error message is shown and the\ndialog stays open.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "onExited",
+      "type": "function",
+      "signature": "(() => void) | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "The exit animation finished.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "open",
+      "type": "boolean",
+      "typeText": "boolean",
+      "required": true,
+      "origin": "derived"
+    },
+    {
+      "name": "placeholder",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "required",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived"
+    },
+    {
+      "name": "size",
+      "type": "enum",
+      "values": [
+        "md",
+        "sm"
+      ],
+      "typeText": "DialogSize | undefined",
+      "required": false,
+      "default": "sm",
+      "origin": "derived"
+    },
+    {
+      "name": "store",
+      "type": "other",
+      "typeText": "DialogStore | undefined",
+      "required": false,
+      "default": "dialogStore",
+      "origin": "derived",
+      "description": "A store from `createDialogStore()`. Defaults to the one behind `dialog`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "style",
+      "type": "other",
+      "typeText": "CSSProperties | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "title",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": true,
+      "origin": "derived"
+    },
+    {
+      "name": "validate",
+      "type": "function",
+      "signature": "((value: string) => string | null | undefined) | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Return a message to block confirming.",
+      "descriptionOrigin": "jsdoc"
+    }
+  ],
+  "inherits": [
+    {
+      "from": "PromptOptions",
+      "omitted": [
+        "onConfirm"
+      ],
+      "passthrough": true
+    }
+  ],
+  "events": [
+    {
+      "name": "onClose",
+      "signature": "((action: DialogAction, value: string) => void) | undefined"
+    },
+    {
+      "name": "onConfirm",
+      "signature": "((value: string) => void | Promise<void>) | undefined"
+    },
+    {
+      "name": "onExited",
+      "signature": "(() => void) | undefined"
+    }
+  ],
+  "slots": [
+    "root",
+    "body",
+    "icon",
+    "title",
+    "description",
+    "input",
+    "actions",
+    "confirm",
+    "cancel"
+  ],
+  "states": [
+    {
+      "attr": "data-autofocus"
+    },
+    {
+      "attr": "data-intent",
+      "values": [
+        "danger",
+        "info",
+        "success",
+        "warning"
+      ]
+    },
+    {
+      "attr": "data-size",
+      "values": [
+        "md"
+      ]
+    },
+    {
+      "attr": "data-state"
+    },
+    {
+      "attr": "data-theme",
+      "values": [
+        "dark",
+        "light"
+      ]
+    },
+    {
+      "attr": "data-variant",
+      "values": [
+        "danger",
+        "primary",
+        "secondary"
+      ]
+    }
+  ],
+  "accessibility": {
+    "supplied": [],
+    "required": []
+  },
+  "composition": {},
+  "operations": {},
+  "intentDomains": [],
+  "safeMutations": {},
+  "examples": [],
+  "coverage": {
+    "propsTotal": 25,
+    "propsDescribed": 9,
+    "describedPct": 36,
+    "authoredSections": [
+      "accessibility"
+    ]
+  }
+}

package/source/components/dialog/react/Dialog.tsx

@@ -0,0 +1,279 @@
+"use client";
+
+import {
+  useEffect,
+  useEffectEvent,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+  type MouseEvent,
+  type ReactNode,
+} from "react";
+import type {
+  DialogIntent,
+  DialogKind,
+  DialogLocaleText,
+  PromptOptions,
+} from "../core/types";
+import { DangerIcon, InfoIcon, SpinnerIcon, SuccessIcon, WarningIcon } from "./icons";
+import { defaultDialogText } from "./locale";
+import { cx, type DialogSlot } from "./props";
+
+/** Matches the CSS transition, so content stays mounted while the dialog animates out. */
+const EXIT_DURATION = 200;
+
+const INTENT_ICONS: Record<DialogIntent, ReactNode> = {
+  default: null,
+  info: <InfoIcon />,
+  success: <SuccessIcon />,
+  warning: <WarningIcon />,
+  danger: <DangerIcon />,
+};
+
+export type DialogAction = "confirm" | "cancel";
+
+export interface DialogProps extends Omit<PromptOptions, "onConfirm"> {
+  open: boolean;
+  /** `alert` has one button, `confirm` two, `prompt` adds a text field. Default `confirm`. */
+  kind?: DialogKind;
+  /**
+   * Runs on Confirm, with the prompt's value. While its promise is pending the
+   * buttons show progress; if it throws, the error message is shown and the
+   * dialog stays open.
+   */
+  onConfirm?(value: string): void | Promise<void>;
+  /** The user answered. Set `open` to false here. */
+  onClose?(action: DialogAction, value: string): void;
+  /** The exit animation finished. */
+  onExited?(): void;
+  id?: string;
+  className?: string;
+  classNames?: Partial<Record<DialogSlot, string>>;
+  style?: CSSProperties;
+  localeText?: Partial<DialogLocaleText>;
+}
+
+const outside = (event: MouseEvent<HTMLDialogElement>) => {
+  if (event.target !== event.currentTarget) return false;
+  const rect = event.currentTarget.getBoundingClientRect();
+  const { clientX: x, clientY: y } = event;
+  return x < rect.left || x > rect.right || y < rect.top || y > rect.bottom;
+};
+
+/** An alert, confirm or prompt dialog. For the promise API, mount `<DialogHost />` and call `dialog.confirm()`. */
+export function Dialog(props: DialogProps) {
+  const {
+    open,
+    kind = "confirm",
+    title,
+    description,
+    intent = "default",
+    icon,
+    confirmLabel,
+    cancelLabel,
+    dismissible = true,
+    size = "sm",
+    defaultValue = "",
+    placeholder,
+    inputLabel,
+    inputType = "text",
+    required = false,
+    validate,
+    onConfirm,
+    onClose,
+    onExited,
+    id: idProp,
+    className,
+    classNames,
+    style,
+    localeText,
+  } = props;
+
+  const reactId = useId();
+  const id = idProp ?? reactId;
+  const text = useMemo(() => ({ ...defaultDialogText, ...localeText }), [localeText]);
+  const dialogRef = useRef<HTMLDialogElement>(null);
+  const pressStartedOutside = useRef(false);
+
+  const [value, setValue] = useState(defaultValue);
+  const [error, setError] = useState<string | null>(null);
+  const [pending, setPending] = useState(false);
+
+  // Reset each time it opens, and keep content mounted through the exit transition.
+  const [previousOpen, setPreviousOpen] = useState(open);
+  const [closing, setClosing] = useState(false);
+  if (previousOpen !== open) {
+    setPreviousOpen(open);
+    setClosing(!open);
+    if (open) {
+      setValue(defaultValue);
+      setError(null);
+      setPending(false);
+    }
+  }
+
+  const exited = useEffectEvent(() => onExited?.());
+  useEffect(() => {
+    if (!closing) return;
+    const timer = setTimeout(() => {
+      setClosing(false);
+      exited();
+    }, EXIT_DURATION);
+    return () => clearTimeout(timer);
+  }, [closing]);
+
+  useEffect(() => {
+    const element = dialogRef.current;
+    if (!element) return;
+    if (open && !element.open) {
+      element.showModal();
+      element.querySelector<HTMLElement>("[data-autofocus]")?.focus();
+    } else if (!open && element.open) {
+      element.close();
+    }
+  }, [open]);
+
+  const confirm = async () => {
+    if (pending || !open) return;
+    if (kind === "prompt") {
+      const message = required && !value.trim() ? text.required : validate?.(value);
+      if (message) {
+        setError(message);
+        return;
+      }
+    }
+    if (onConfirm) {
+      setPending(true);
+      setError(null);
+      try {
+        await onConfirm(value);
+      } catch (reason) {
+        setError(reason instanceof Error ? reason.message : String(reason));
+        setPending(false);
+        return;
+      }
+      setPending(false);
+    }
+    onClose?.("confirm", value);
+  };
+
+  const cancel = () => {
+    if (pending || !open) return;
+    onClose?.("cancel", value);
+  };
+
+  const mounted = open || closing;
+  const resolvedIcon = icon !== undefined ? icon : INTENT_ICONS[intent];
+  // A destructive confirm starts on Cancel, so a stray Enter doesn't delete anything.
+  const focusCancel = kind === "confirm" && intent === "danger";
+  const errorId = `${id}-error`;
+
+  return (
+    <dialog
+      ref={dialogRef}
+      id={id}
+      role="alertdialog"
+      aria-labelledby={`${id}-title`}
+      aria-describedby={description ? `${id}-description` : undefined}
+      className={cx("dl-root", classNames?.root, className)}
+      style={style}
+      data-intent={intent}
+      data-size={size}
+      data-state={open ? "open" : "closed"}
+      onCancel={(event) => {
+        event.preventDefault();
+        if (dismissible) cancel();
+      }}
+      onPointerDown={(event) => {
+        pressStartedOutside.current = outside(event);
+      }}
+      onClick={(event) => {
+        if (dismissible && pressStartedOutside.current && outside(event)) cancel();
+        pressStartedOutside.current = false;
+      }}
+    >
+      {mounted && (
+        <form
+          className="dl-form"
+          noValidate
+          onSubmit={(event) => {
+            event.preventDefault();
+            void confirm();
+          }}
+        >
+          <div className={cx("dl-body", classNames?.body)}>
+            {resolvedIcon != null && (
+              <span className={cx("dl-icon", classNames?.icon)} aria-hidden="true">
+                {resolvedIcon}
+              </span>
+            )}
+            <div className="dl-text">
+              <h2 id={`${id}-title`} className={cx("dl-title", classNames?.title)}>
+                {title}
+              </h2>
+              {description && (
+                <div id={`${id}-description`} className={cx("dl-description", classNames?.description)}>
+                  {description}
+                </div>
+              )}
+              {kind === "prompt" && (
+                <label className="dl-field">
+                  {inputLabel && <span className="dl-label">{inputLabel}</span>}
+                  <input
+                    className={cx("dl-input", classNames?.input)}
+                    type={inputType}
+                    value={value}
+                    placeholder={placeholder}
+                    required={required}
+                    readOnly={pending}
+                    data-autofocus=""
+                    aria-invalid={error ? true : undefined}
+                    aria-describedby={error ? errorId : undefined}
+                    onChange={(event) => {
+                      setValue(event.target.value);
+                      if (error) setError(null);
+                    }}
+                  />
+                </label>
+              )}
+              {error && (
+                <p id={errorId} className="dl-error" role="alert">
+                  {error}
+                </p>
+              )}
+            </div>
+          </div>
+
+          <div className={cx("dl-actions", classNames?.actions)}>
+            {kind !== "alert" && (
+              <button
+                type="button"
+                className={cx("dl-button", classNames?.cancel)}
+                data-variant="secondary"
+                data-autofocus={focusCancel ? "" : undefined}
+                aria-disabled={pending || undefined}
+                onClick={cancel}
+              >
+                {cancelLabel ?? text.cancel}
+              </button>
+            )}
+            <button
+              type="submit"
+              className={cx("dl-button", classNames?.confirm)}
+              data-variant={intent === "danger" ? "danger" : "primary"}
+              data-autofocus={!focusCancel && kind !== "prompt" ? "" : undefined}
+              // aria-disabled rather than disabled, so focus stays on the button while it works.
+              aria-disabled={pending || undefined}
+              aria-busy={pending || undefined}
+            >
+              {pending && <SpinnerIcon />}
+              {confirmLabel ?? (kind === "alert" ? text.ok : text.confirm)}
+            </button>
+          </div>
+        </form>
+      )}
+    </dialog>
+  );
+}

package/source/components/dialog/react/DialogHost.tsx

@@ -0,0 +1,45 @@
+"use client";
+
+import { useState, useSyncExternalStore, type CSSProperties } from "react";
+import { dialogStore } from "../core/dialog";
+import type { DialogStore } from "../core/store";
+import type { DialogLocaleText, DialogRequest } from "../core/types";
+import { Dialog } from "./Dialog";
+import type { DialogSlot } from "./props";
+
+export interface DialogHostProps {
+  /** A store from `createDialogStore()`. Defaults to the one behind `dialog`. */
+  store?: DialogStore;
+  /** Applied to every dialog this host shows. */
+  className?: string;
+  classNames?: Partial<Record<DialogSlot, string>>;
+  style?: CSSProperties;
+  localeText?: Partial<DialogLocaleText>;
+}
+
+/** Mount once. Shows the dialogs requested through `dialog.alert/confirm/prompt`, one at a time. */
+export function DialogHost({ store = dialogStore, ...shared }: DialogHostProps) {
+  const { queue } = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getServerSnapshot);
+  const current = queue[0];
+
+  // Keep the last dialog rendered while it animates out.
+  const [shown, setShown] = useState<DialogRequest | undefined>(current);
+  if (current && current !== shown) setShown(current);
+
+  if (!shown) return null;
+
+  return (
+    <Dialog
+      key={shown.id}
+      {...shown.options}
+      {...shared}
+      open={shown === current}
+      kind={shown.kind}
+      onConfirm={shown.options.onConfirm}
+      onClose={(action, value) => store.resolve(shown.id, action === "confirm", value)}
+      onExited={() => {
+        if (store.getSnapshot().queue.length === 0) setShown(undefined);
+      }}
+    />
+  );
+}

package/source/components/dialog/react/icons.tsx

@@ -0,0 +1,20 @@
+import {
+  AlertCircleIcon,
+  InfoIcon as SharedInfo,
+  SpinnerIcon as SharedSpinner,
+  SuccessIcon as SharedSuccess,
+  WarningIcon as SharedWarning,
+  type IconProps,
+} from "../../shared/react/icons";
+
+/*
+ * The dialog draws its status icon at 20px, beside the title.
+ */
+export const InfoIcon = (p: IconProps) => <SharedInfo width={20} height={20} {...p} />;
+export const SuccessIcon = (p: IconProps) => <SharedSuccess width={20} height={20} {...p} />;
+export const WarningIcon = (p: IconProps) => <SharedWarning width={20} height={20} {...p} />;
+export const DangerIcon = (p: IconProps) => <AlertCircleIcon width={20} height={20} {...p} />;
+
+export const SpinnerIcon = (p: IconProps) => (
+  <SharedSpinner width={14} height={14} {...p} className="dl-spinner" />
+);

package/source/components/dialog/react/locale.ts

@@ -0,0 +1,8 @@
+import type { DialogLocaleText } from "../core/types";
+
+export const defaultDialogText: DialogLocaleText = {
+  ok: "OK",
+  confirm: "Confirm",
+  cancel: "Cancel",
+  required: "Please fill in this field",
+};