@grampro/kit 0.0.0-stage → 2.4.1

package/source/components/toaster/passport.json

@@ -0,0 +1,221 @@
+{
+  "passportVersion": "1.0.0",
+  "identity": {
+    "component": "Toaster",
+    "folder": "toaster",
+    "exports": [
+      "DEFAULT_DURATION",
+      "DEFAULT_LIMIT",
+      "EXIT_DURATION",
+      "Toaster"
+    ]
+  },
+  "source": {
+    "libraryVersion": "2.4.1",
+    "files": [
+      "core/api.ts",
+      "core/index.ts",
+      "core/store.ts",
+      "core/toast.ts",
+      "core/types.ts",
+      "index.ts",
+      "react/ToastItem.tsx",
+      "react/Toaster.tsx",
+      "react/icons.tsx",
+      "react/locale.ts",
+      "react/props.ts",
+      "react/useToasts.ts"
+    ],
+    "sourceHash": "sha256:29756fca7fc33de05f42257fbb145017a6c507565eecb99ce06814ba404262ef"
+  },
+  "props": [
+    {
+      "name": "className",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "classNames",
+      "type": "other",
+      "typeText": "Partial<Record<ToasterSlot, string>> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "closeButton",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": true,
+      "origin": "derived",
+      "description": "Show a close button on dismissible toasts. Default true.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "dir",
+      "type": "enum",
+      "values": [
+        "auto",
+        "ltr",
+        "rtl"
+      ],
+      "typeText": "'ltr' | 'rtl' | 'auto' | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "duration",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Default auto-close delay in milliseconds. Default 5000.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "hotkey",
+      "type": "other",
+      "typeText": "readonly string[] | undefined",
+      "required": false,
+      "default": "DEFAULT_HOTKEY",
+      "origin": "derived",
+      "description": "Keys that move focus to the notifications: `KeyboardEvent` modifier names\nplus a `code`. Default `[\"altKey\", \"KeyT\"]`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "icons",
+      "type": "other",
+      "typeText": "Partial<Record<ToastType, ReactNode>> | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Replace the icon per type; `null` hides it.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "limit",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Open toasts on screen at once; the rest wait their turn. Default 3.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "localeText",
+      "type": "other",
+      "typeText": "Partial<ToasterLocaleText> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "position",
+      "type": "enum",
+      "values": [
+        "bottom-center",
+        "bottom-left",
+        "bottom-right",
+        "top-center",
+        "top-left",
+        "top-right"
+      ],
+      "typeText": "ToastPosition | undefined",
+      "required": false,
+      "default": "top-right",
+      "origin": "derived",
+      "description": "Default `\"top-right\"`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "store",
+      "type": "other",
+      "typeText": "ToastStore | undefined",
+      "required": false,
+      "default": "toastStore",
+      "origin": "derived",
+      "description": "A store from `createToastStore()`. Defaults to the one behind `toast()`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "style",
+      "type": "other",
+      "typeText": "CSSProperties | undefined",
+      "required": false,
+      "origin": "derived"
+    }
+  ],
+  "events": [],
+  "slots": [
+    "region",
+    "list",
+    "toast",
+    "icon",
+    "content",
+    "title",
+    "description",
+    "actions",
+    "action",
+    "cancel",
+    "close"
+  ],
+  "states": [
+    {
+      "attr": "data-custom"
+    },
+    {
+      "attr": "data-position"
+    },
+    {
+      "attr": "data-state",
+      "values": [
+        "closing"
+      ]
+    },
+    {
+      "attr": "data-swiping"
+    },
+    {
+      "attr": "data-theme",
+      "values": [
+        "dark",
+        "light"
+      ]
+    },
+    {
+      "attr": "data-type",
+      "values": [
+        "default",
+        "error",
+        "info",
+        "loading",
+        "success",
+        "warning"
+      ]
+    },
+    {
+      "attr": "data-variant",
+      "values": [
+        "action",
+        "cancel"
+      ]
+    }
+  ],
+  "accessibility": {
+    "supplied": [],
+    "required": []
+  },
+  "composition": {},
+  "operations": {},
+  "intentDomains": [],
+  "safeMutations": {},
+  "examples": [],
+  "coverage": {
+    "propsTotal": 12,
+    "propsDescribed": 7,
+    "describedPct": 58,
+    "authoredSections": [
+      "accessibility"
+    ]
+  }
+}

package/source/components/toaster/react/ToastItem.tsx

@@ -0,0 +1,164 @@
+"use client";
+
+import {
+  useRef,
+  useState,
+  type CSSProperties,
+  type KeyboardEvent,
+  type MouseEvent,
+  type PointerEvent,
+  type ReactNode,
+} from "react";
+import type { ToastStore } from "../core/store";
+import type { ToastAction, ToasterLocaleText, ToastRecord, ToastType } from "../core/types";
+import { ErrorIcon, InfoIcon, SpinnerIcon, SuccessIcon, WarningIcon, XIcon } from "./icons";
+import { cx, type ToasterSlot } from "./props";
+
+/** Horizontal drag, in pixels, that dismisses a toast. */
+const SWIPE_DISMISS = 64;
+
+const DEFAULT_ICONS: Record<ToastType, ReactNode> = {
+  default: null,
+  success: <SuccessIcon />,
+  error: <ErrorIcon />,
+  warning: <WarningIcon />,
+  info: <InfoIcon />,
+  loading: <SpinnerIcon />,
+};
+
+interface ToastItemProps {
+  toast: ToastRecord;
+  store: ToastStore;
+  closeButton: boolean;
+  icons?: Partial<Record<ToastType, ReactNode>>;
+  classNames?: Partial<Record<ToasterSlot, string>>;
+  text: ToasterLocaleText;
+}
+
+export function ToastItem({ toast, store, closeButton, icons, classNames, text }: ToastItemProps) {
+  const [swipe, setSwipe] = useState(0);
+  const drag = useRef<{ pointerId: number; startX: number } | null>(null);
+  const { action, cancel, render } = toast;
+  const closing = toast.state === "closing";
+
+  const dismiss = () => store.dismiss(toast.id);
+
+  // `null` from the toast or the Toaster hides the icon; `undefined` means "use the default".
+  const icon =
+    toast.icon !== undefined
+      ? toast.icon
+      : icons !== undefined && Object.hasOwn(icons, toast.type)
+        ? icons[toast.type]
+        : DEFAULT_ICONS[toast.type];
+
+  const runAction = (item: ToastAction, event: MouseEvent<HTMLButtonElement>) => {
+    item.onClick(event);
+    if (!event.defaultPrevented) dismiss();
+  };
+
+  const onKeyDown = (event: KeyboardEvent<HTMLLIElement>) => {
+    if (event.key !== "Escape" || !toast.dismissible) return;
+    event.preventDefault();
+    // Keep focus in the notification region instead of dropping it on <body>.
+    event.currentTarget.closest<HTMLElement>(".ts-list")?.focus();
+    dismiss();
+  };
+
+  const onPointerDown = (event: PointerEvent<HTMLLIElement>) => {
+    if (!toast.dismissible || closing || event.button !== 0) return;
+    if ((event.target as Element).closest("button, a, input, select, textarea")) return;
+    drag.current = { pointerId: event.pointerId, startX: event.clientX };
+    event.currentTarget.setPointerCapture(event.pointerId);
+  };
+
+  const onPointerMove = (event: PointerEvent<HTMLLIElement>) => {
+    const start = drag.current;
+    if (start?.pointerId === event.pointerId) setSwipe(event.clientX - start.startX);
+  };
+
+  const endSwipe = (event: PointerEvent<HTMLLIElement>) => {
+    const start = drag.current;
+    if (start?.pointerId !== event.pointerId) return;
+    drag.current = null;
+    const far = Math.abs(event.clientX - start.startX) >= SWIPE_DISMISS;
+    if (event.type === "pointerup" && far) dismiss();
+    else setSwipe(0);
+  };
+
+  return (
+    <li
+      className={cx("ts-toast", classNames?.toast, toast.className)}
+      // The list is a polite live region; errors interrupt.
+      role={toast.type === "error" ? "alert" : undefined}
+      aria-atomic="true"
+      tabIndex={0}
+      data-type={toast.type}
+      data-state={toast.state}
+      data-custom={render ? "" : undefined}
+      data-swiping={swipe !== 0 ? "" : undefined}
+      style={{ "--ts-swipe": `${swipe}px` } as CSSProperties}
+      onKeyDown={onKeyDown}
+      onPointerDown={onPointerDown}
+      onPointerMove={onPointerMove}
+      onPointerUp={endSwipe}
+      onPointerCancel={endSwipe}
+    >
+      {!render && icon != null && (
+        <span className={cx("ts-icon", classNames?.icon)} aria-hidden="true">
+          {icon}
+        </span>
+      )}
+
+      <div className={cx("ts-content", classNames?.content)}>
+        {render ? (
+          render({ id: toast.id, dismiss })
+        ) : (
+          <>
+            <div className={cx("ts-title", classNames?.title)}>{toast.title}</div>
+            {toast.description != null && (
+              <div className={cx("ts-description", classNames?.description)}>
+                {toast.description}
+              </div>
+            )}
+          </>
+        )}
+      </div>
+
+      {!render && (action || cancel) && (
+        <div className={cx("ts-actions", classNames?.actions)}>
+          {cancel && (
+            <button
+              type="button"
+              className={cx("ts-button", classNames?.cancel)}
+              data-variant="cancel"
+              onClick={(event) => runAction(cancel, event)}
+            >
+              {cancel.label}
+            </button>
+          )}
+          {action && (
+            <button
+              type="button"
+              className={cx("ts-button", classNames?.action)}
+              data-variant="action"
+              onClick={(event) => runAction(action, event)}
+            >
+              {action.label}
+            </button>
+          )}
+        </div>
+      )}
+
+      {closeButton && toast.dismissible && (
+        <button
+          type="button"
+          className={cx("ts-close", classNames?.close)}
+          aria-label={text.close}
+          onClick={dismiss}
+        >
+          <XIcon />
+        </button>
+      )}
+    </li>
+  );
+}

package/source/components/toaster/react/Toaster.tsx

@@ -0,0 +1,187 @@
+"use client";
+
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useSyncExternalStore,
+  type CSSProperties,
+  type ReactNode,
+} from "react";
+import { createPortal } from "react-dom";
+import { visibleToasts, type ToastStore } from "../core/store";
+import { toastStore } from "../core/toast";
+import type { ToasterLocaleText, ToastPosition, ToastType } from "../core/types";
+import { defaultToasterText } from "./locale";
+import { cx, type ToasterSlot } from "./props";
+import { ToastItem } from "./ToastItem";
+import { useToasts } from "./useToasts";
+
+export interface ToasterProps {
+  /** Default `"top-right"`. */
+  position?: ToastPosition;
+  /** Open toasts on screen at once; the rest wait their turn. Default 3. */
+  limit?: number;
+  /** Default auto-close delay in milliseconds. Default 5000. */
+  duration?: number;
+  /** Show a close button on dismissible toasts. Default true. */
+  closeButton?: boolean;
+  /**
+   * Keys that move focus to the notifications: `KeyboardEvent` modifier names
+   * plus a `code`. Default `["altKey", "KeyT"]`.
+   */
+  hotkey?: readonly string[];
+  /** Replace the icon per type; `null` hides it. */
+  icons?: Partial<Record<ToastType, ReactNode>>;
+  /** A store from `createToastStore()`. Defaults to the one behind `toast()`. */
+  store?: ToastStore;
+  dir?: "ltr" | "rtl" | "auto";
+  className?: string;
+  classNames?: Partial<Record<ToasterSlot, string>>;
+  style?: CSSProperties;
+  localeText?: Partial<ToasterLocaleText>;
+}
+
+type Modifier = "altKey" | "ctrlKey" | "metaKey" | "shiftKey";
+
+const MODIFIER_LABELS: Record<Modifier, string> = {
+  altKey: "Alt",
+  ctrlKey: "Ctrl",
+  metaKey: "Meta",
+  shiftKey: "Shift",
+};
+
+const DEFAULT_HOTKEY: readonly string[] = ["altKey", "KeyT"];
+
+const isModifier = (key: string): key is Modifier => Object.hasOwn(MODIFIER_LABELS, key);
+
+const hotkeyLabel = (keys: readonly string[]) =>
+  keys
+    .map((key) => (isModifier(key) ? MODIFIER_LABELS[key] : key.replace(/^(Key|Digit)/, "")))
+    .join("+");
+
+const subscribeNothing = () => () => {};
+
+/**
+ * Mount once, anywhere in the app. Toasts come from `toast()` and render in a
+ * portal on `<body>`, so no parent's overflow, transform or z-index can hide them.
+ */
+export function Toaster(props: ToasterProps) {
+  const {
+    position = "top-right",
+    limit,
+    duration,
+    closeButton = true,
+    hotkey = DEFAULT_HOTKEY,
+    icons,
+    store = toastStore,
+    dir,
+    className,
+    classNames,
+    style,
+    localeText,
+  } = props;
+
+  const snapshot = useToasts(store);
+  // False during a server render and hydration, so the portal never causes a mismatch.
+  const mounted = useSyncExternalStore(
+    subscribeNothing,
+    () => true,
+    () => false,
+  );
+  const text = useMemo(() => ({ ...defaultToasterText, ...localeText }), [localeText]);
+
+  const listRef = useRef<HTMLOListElement>(null);
+  const pointerInside = useRef(false);
+  const focusInside = useRef(false);
+
+  useEffect(() => {
+    store.configure({ limit, duration });
+  }, [store, limit, duration]);
+
+  /** Timers hold while someone is reading: pointer over, focus inside, or tab hidden. */
+  const syncPause = useCallback(() => {
+    const hold =
+      pointerInside.current || focusInside.current || document.visibilityState === "hidden";
+    if (hold) store.pause();
+    else store.resume();
+  }, [store]);
+
+  useEffect(() => {
+    document.addEventListener("visibilitychange", syncPause);
+    return () => document.removeEventListener("visibilitychange", syncPause);
+  }, [syncPause]);
+
+  const empty = snapshot.toasts.length === 0;
+  useEffect(() => {
+    if (!empty) return;
+    // A toast that disappears under the pointer never fires pointerleave.
+    pointerInside.current = false;
+    focusInside.current = false;
+    syncPause();
+  }, [empty, syncPause]);
+
+  useEffect(() => {
+    if (hotkey.length === 0) return;
+    const onKeyDown = (event: KeyboardEvent) => {
+      const pressed = hotkey.every((key) => (isModifier(key) ? event[key] : event.code === key));
+      if (!pressed) return;
+      event.preventDefault();
+      listRef.current?.focus();
+    };
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [hotkey]);
+
+  if (!mounted) return null;
+
+  return createPortal(
+    <section
+      className={cx("ts-region", classNames?.region, className)}
+      style={style}
+      dir={dir}
+      data-position={position}
+      aria-label={text.regionLabel(hotkeyLabel(hotkey))}
+      onPointerEnter={() => {
+        pointerInside.current = true;
+        syncPause();
+      }}
+      onPointerLeave={() => {
+        pointerInside.current = false;
+        syncPause();
+      }}
+      onFocus={() => {
+        focusInside.current = true;
+        syncPause();
+      }}
+      onBlur={(event) => {
+        if (event.currentTarget.contains(event.relatedTarget)) return;
+        focusInside.current = false;
+        syncPause();
+      }}
+    >
+      {/* Always mounted, even when empty, so screen readers announce the first toast. */}
+      <ol
+        ref={listRef}
+        tabIndex={-1}
+        className={cx("ts-list", classNames?.list)}
+        aria-live="polite"
+        aria-relevant="additions text"
+      >
+        {visibleToasts(snapshot).map((item) => (
+          <ToastItem
+            key={item.id}
+            toast={item}
+            store={store}
+            closeButton={closeButton}
+            icons={icons}
+            classNames={classNames}
+            text={text}
+          />
+        ))}
+      </ol>
+    </section>,
+    document.body,
+  );
+}

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

@@ -0,0 +1,23 @@
+import {
+  AlertCircleIcon,
+  InfoIcon as SharedInfo,
+  SpinnerIcon as SharedSpinner,
+  SuccessIcon as SharedSuccess,
+  WarningIcon as SharedWarning,
+  XIcon as SharedX,
+  type IconProps,
+} from "../../shared/react/icons";
+import { cx } from "./props";
+
+/*
+ * A toast draws its status icon at 18px and its close button at 14px.
+ */
+export const SuccessIcon = (p: IconProps) => <SharedSuccess width={18} height={18} {...p} />;
+export const ErrorIcon = (p: IconProps) => <AlertCircleIcon width={18} height={18} {...p} />;
+export const WarningIcon = (p: IconProps) => <SharedWarning width={18} height={18} {...p} />;
+export const InfoIcon = (p: IconProps) => <SharedInfo width={18} height={18} {...p} />;
+export const XIcon = (p: IconProps) => <SharedX width={14} height={14} {...p} />;
+
+export const SpinnerIcon = (p: IconProps) => (
+  <SharedSpinner width={18} height={18} {...p} className={cx("ts-spinner", p.className)} />
+);

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

@@ -0,0 +1,6 @@
+import type { ToasterLocaleText } from "../core/types";
+
+export const defaultToasterText: ToasterLocaleText = {
+  regionLabel: (hotkey) => `Notifications (${hotkey})`,
+  close: "Close notification",
+};

package/source/components/toaster/react/props.ts

@@ -0,0 +1,15 @@
+export type ToasterSlot =
+  | "region"
+  | "list"
+  | "toast"
+  | "icon"
+  | "content"
+  | "title"
+  | "description"
+  | "actions"
+  | "action"
+  | "cancel"
+  | "close";
+
+// Shared with every other component, so class handling cannot drift.
+export { cx } from "../../shared/core/cx";

package/source/components/toaster/react/useToasts.ts

@@ -0,0 +1,11 @@
+"use client";
+
+import { useSyncExternalStore } from "react";
+import type { ToastStore } from "../core/store";
+import { toastStore } from "../core/toast";
+import type { ToastSnapshot } from "../core/types";
+
+/** The live toast list, for building your own notification UI on the same store. */
+export function useToasts(store: ToastStore = toastStore): ToastSnapshot {
+  return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getServerSnapshot);
+}