gbs-add-block 1.2.12 → 1.2.14

package/README.md

@@ -1,23 +1,16 @@
-# GBS Building Blocks 2.0 (v1.2.12)
+# GBS Building Blocks 2.0 (v1.2.14)
 
 Latest and upgraded version of GBS building blocks with headless UI and removed dependencies.
 
 ## Documentation
 
-For detailed documentation on usage and props, Please visit: [Building Block Documentation v2.0](https://gramprokit.vercel.app)
+For detailed documentation on usage and props, Please visit: [Building Block Documentation](https://gramprokit.vercel.app)
 
 ## Beta Components
 
-DataGrid and Combobox use the redesigned core API and design system. Install them with the beta flag:
+New Beta Components are avilable for testing and feedback, Please visit: [Building Block Documentation v2.0.0 beta](https://gramprokit.vercel.app/2.0.0-beta)
 
-```bash
-npx gbs-add-block -a DataGrid -beta
-npx gbs-add-block -a Combobox -beta
-npx gbs-add-block -a DatePicker -beta
-npx gbs-add-block -a Toaster -beta
-```
-
-## What's New 🎉 (Ver 1.2.12)
+## What's New 🎉 (Ver 1.2.14)
 
 - Update Candidate for next major change 2.0.0
 

package/index.cjs

@@ -35,10 +35,20 @@ const CONFIG = {
     "UsePaginatedData",
     "UseUploader",
   ],
-  betaComponents: ["DataGrid", "Combobox", "DatePicker"],
+  betaComponents: [
+    "DataGrid",
+    "Combobox",
+    "DatePicker",
+    "Toaster",
+    "FileUploader",
+    "Dialog",
+    "Input",
+    "Modal",
+    "Textarea",
+  ],
   // Define component dependencies
   dependencies: {
-    FormRenderer: ["Select", "MultiSelect", "Input", "DatePicker", "toaster"],
+    FormRenderer: ["Select", "MultiSelect", "Input", "DatePicker"],
   },
   docs: "https://gramprokit.vercel.app/",
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gbs-add-block",
-  "version": "1.2.12",
+  "version": "1.2.14",
   "description": "React Component Library",
   "type": "module",
   "files": [

package/source/beta-components/dialog/README.md

@@ -0,0 +1,39 @@
+# Dialog
+
+Alert, confirm and prompt dialogs for React 19 that you can `await`, styled to
+match the rest of the library. No runtime dependencies besides React.
+
+## Setup
+
+```ts
+import { dialog, DialogHost } from "@/components/dialog";
+import "@/components/dialog/styles.css";
+```
+
+Mount `<DialogHost />` once near the root, then:
+
+```tsx
+if (await dialog.confirm({ title: "Delete 3 invoices?", intent: "danger", confirmLabel: "Delete" })) {
+  await deleteInvoices();
+}
+
+const name = await dialog.prompt({ title: "Rename", defaultValue: "report.pdf", required: true });
+await dialog.alert("Export finished");
+```
+
+- `alert` resolves when closed; `confirm` resolves `true`/`false`; `prompt` resolves the text or `null`.
+- `onConfirm` may be async: the dialog shows progress, and if it throws, shows the error and stays open.
+- Requests queue and show one at a time. Where there is no document (a server render) they resolve as canceled.
+- `<Dialog open onClose>` is the same dialog as a regular controlled component.
+
+## Options
+
+`title`, `description`, `intent` (`default` `info` `success` `warning` `danger`),
+`icon`, `confirmLabel`, `cancelLabel`, `dismissible`, `size` (`sm` `md`),
+`onConfirm`. Prompt adds `defaultValue`, `placeholder`, `inputLabel`, `inputType`,
+`required` and `validate`.
+
+## Headless use
+
+`createDialogStore()` and `createDialogApi(store)` build separate instances; pass
+the store to `<DialogHost store={store} />`. The core has no React imports.

package/source/beta-components/dialog/__tests__/core.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it, vi } from "vitest";
+import { createDialogApi } from "../core/api";
+import { dialog, dialogStore } from "../core/dialog";
+import { createDialogStore, resultFor } from "../core/store";
+
+describe("results", () => {
+  it("maps an answer to each kind's value", () => {
+    expect(resultFor("confirm", true)).toBe(true);
+    expect(resultFor("confirm", false)).toBe(false);
+    expect(resultFor("prompt", true, "Ada")).toBe("Ada");
+    expect(resultFor("prompt", true)).toBe("");
+    expect(resultFor("prompt", false, "ignored")).toBeNull();
+    expect(resultFor("alert", true)).toBeUndefined();
+  });
+});
+
+describe("queue", () => {
+  it("shows one dialog at a time, in order", async () => {
+    const store = createDialogStore();
+    const api = createDialogApi(store);
+
+    const first = api.confirm("Delete the file?");
+    const second = api.prompt({ title: "Rename", defaultValue: "report.pdf" });
+    const [a, b] = store.getSnapshot().queue;
+    expect(a).toMatchObject({ kind: "confirm", options: { title: "Delete the file?" } });
+    expect(b).toMatchObject({ kind: "prompt", options: { defaultValue: "report.pdf" } });
+
+    store.resolve(a.id, true);
+    expect(await first).toBe(true);
+    expect(store.getSnapshot().queue.map((item) => item.id)).toEqual([b.id]);
+
+    store.resolve(b.id, true, "summary.pdf");
+    expect(await second).toBe("summary.pdf");
+    expect(store.getSnapshot().queue).toHaveLength(0);
+  });
+
+  it("notifies subscribers and ignores unknown or repeated answers", async () => {
+    const store = createDialogStore();
+    const listener = vi.fn();
+    store.subscribe(listener);
+
+    const answer = store.open("alert", { title: "Saved" });
+    const [request] = store.getSnapshot().queue;
+    store.resolve("dialog-404", true);
+    store.resolve(request.id, true);
+    store.resolve(request.id, false);
+
+    expect(await answer).toBeUndefined();
+    expect(listener).toHaveBeenCalledTimes(2);
+  });
+
+  it("cancels everything with dismissAll", async () => {
+    const store = createDialogStore();
+    const api = createDialogApi(store);
+    const results = Promise.all([api.confirm("One?"), api.prompt("Two?"), api.alert("Three")]);
+
+    api.dismissAll();
+    expect(await results).toEqual([false, null, undefined]);
+    expect(store.getSnapshot().queue).toHaveLength(0);
+  });
+
+  it("keeps the snapshot object until something changes", () => {
+    const store = createDialogStore();
+    const before = store.getSnapshot();
+    expect(store.getSnapshot()).toBe(before);
+    void store.open("alert", { title: "Hi" });
+    expect(store.getSnapshot()).not.toBe(before);
+  });
+});
+
+describe("where nothing can be shown", () => {
+  it("answers as a cancel at once", async () => {
+    const store = createDialogStore();
+    const api = createDialogApi(store, () => false);
+    expect(await api.confirm("Sure?")).toBe(false);
+    expect(await api.prompt("Name?")).toBeNull();
+    expect(await api.alert("Hi")).toBeUndefined();
+    expect(store.getSnapshot().queue).toHaveLength(0);
+  });
+
+  it("does so for the default dialog on a server, where there is no document", async () => {
+    expect(typeof document).toBe("undefined");
+    expect(await dialog.confirm("Rendered on the server")).toBe(false);
+    expect(dialogStore.getSnapshot().queue).toHaveLength(0);
+  });
+});

package/source/beta-components/dialog/core/api.ts

@@ -0,0 +1,34 @@
+import type { DialogStore } from "./store";
+import type { AlertOptions, ConfirmOptions, PromptOptions } from "./types";
+
+export interface DialogApi {
+  /** Resolves when the user presses OK (or dismisses it). */
+  alert(options: AlertOptions | string): Promise<void>;
+  /** Resolves `true` on Confirm, `false` on Cancel, Escape or a backdrop click. */
+  confirm(options: ConfirmOptions | string): Promise<boolean>;
+  /** Resolves with the entered text, or `null` when canceled. */
+  prompt(options: PromptOptions | string): Promise<string | null>;
+  dismissAll(): void;
+}
+
+/**
+ * The `dialog` API for a store. `canShow` lets the default instance answer
+ * right away where nobody could see a dialog, such as during a server render.
+ */
+export function createDialogApi(store: DialogStore, canShow: () => boolean = () => true): DialogApi {
+  return {
+    alert(options) {
+      if (!canShow()) return Promise.resolve();
+      return store.open("alert", typeof options === "string" ? { title: options } : options);
+    },
+    confirm(options) {
+      if (!canShow()) return Promise.resolve(false);
+      return store.open("confirm", typeof options === "string" ? { title: options } : options);
+    },
+    prompt(options) {
+      if (!canShow()) return Promise.resolve(null);
+      return store.open("prompt", typeof options === "string" ? { title: options } : options);
+    },
+    dismissAll: () => store.dismissAll(),
+  };
+}

package/source/beta-components/dialog/core/dialog.ts

@@ -0,0 +1,11 @@
+import { createDialogApi } from "./api";
+import { createDialogStore } from "./store";
+
+/** The store behind `dialog`, and behind any `<DialogHost />` without a `store` prop. */
+export const dialogStore = createDialogStore();
+
+/**
+ * Ask the user something from anywhere and `await` the answer. Where there is
+ * no document (a server render), calls settle at once as a cancel.
+ */
+export const dialog = createDialogApi(dialogStore, () => typeof document !== "undefined");

package/source/beta-components/dialog/core/index.ts

@@ -0,0 +1,7 @@
+// Framework-free: the dialog queue and the promise API run without React.
+export { createDialogApi } from "./api";
+export type { DialogApi } from "./api";
+export { createDialogStore, resultFor } from "./store";
+export type { DialogStore } from "./store";
+export { dialog, dialogStore } from "./dialog";
+export type * from "./types";

package/source/beta-components/dialog/core/store.ts

@@ -0,0 +1,81 @@
+import type {
+  AlertOptions,
+  ConfirmOptions,
+  DialogKind,
+  DialogRequest,
+  DialogSnapshot,
+  PromptOptions,
+} from "./types";
+
+export interface DialogStore {
+  subscribe(listener: () => void): () => void;
+  getSnapshot(): DialogSnapshot;
+  getServerSnapshot(): DialogSnapshot;
+  open(kind: "alert", options: AlertOptions): Promise<void>;
+  open(kind: "confirm", options: ConfirmOptions): Promise<boolean>;
+  open(kind: "prompt", options: PromptOptions): Promise<string | null>;
+  /** Closes a request and settles its promise. */
+  resolve(id: string, confirmed: boolean, value?: string): void;
+  /** Cancels every open and waiting dialog. */
+  dismissAll(): void;
+}
+
+const EMPTY: DialogSnapshot = { queue: [] };
+
+/** What each kind's promise resolves with. */
+export function resultFor(kind: DialogKind, confirmed: boolean, value = ""): boolean | string | null | undefined {
+  if (kind === "confirm") return confirmed;
+  if (kind === "prompt") return confirmed ? value : null;
+  return undefined;
+}
+
+/**
+ * A queue of dialogs, one on screen at a time, with no React. Each request is a
+ * promise that settles when the user answers, so callers can simply `await` it.
+ */
+export function createDialogStore(): DialogStore {
+  let snapshot: DialogSnapshot = EMPTY;
+  let counter = 0;
+  const listeners = new Set<() => void>();
+  const settlers = new Map<string, (result: unknown) => void>();
+
+  function commit(queue: readonly DialogRequest[]) {
+    snapshot = { queue };
+    for (const listener of listeners) listener();
+  }
+
+  function open(kind: DialogKind, options: AlertOptions | ConfirmOptions | PromptOptions) {
+    const id = `dialog-${++counter}`;
+    return new Promise<unknown>((resolve) => {
+      settlers.set(id, resolve);
+      commit([...snapshot.queue, { id, kind, options } as DialogRequest]);
+    });
+  }
+
+  function resolve(id: string, confirmed: boolean, value?: string) {
+    const request = snapshot.queue.find((item) => item.id === id);
+    const settle = settlers.get(id);
+    if (!request || !settle) return;
+    settlers.delete(id);
+    commit(snapshot.queue.filter((item) => item.id !== id));
+    settle(resultFor(request.kind, confirmed, value));
+  }
+
+  function dismissAll() {
+    for (const request of snapshot.queue) resolve(request.id, false);
+  }
+
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    getSnapshot: () => snapshot,
+    getServerSnapshot: () => EMPTY,
+    open: open as DialogStore["open"],
+    resolve,
+    dismissAll,
+  };
+}

package/source/beta-components/dialog/core/types.ts

@@ -0,0 +1,59 @@
+import type { ReactNode } from "react";
+
+export type DialogKind = "alert" | "confirm" | "prompt";
+export type DialogIntent = "default" | "info" | "success" | "warning" | "danger";
+export type DialogSize = "sm" | "md";
+
+export interface DialogBaseOptions {
+  title: ReactNode;
+  description?: ReactNode;
+  /** Sets the icon and the confirm button's color. `danger` also focuses Cancel first. */
+  intent?: DialogIntent;
+  /** Replaces the intent's icon; `null` hides it. */
+  icon?: ReactNode;
+  confirmLabel?: ReactNode;
+  /** Escape and a backdrop click count as Cancel. Default true. */
+  dismissible?: boolean;
+  size?: DialogSize;
+}
+
+export interface AlertOptions extends DialogBaseOptions {
+  /** Runs on OK. The dialog waits while it runs and shows its error if it throws. */
+  onConfirm?(): void | Promise<void>;
+}
+
+export interface ConfirmOptions extends DialogBaseOptions {
+  cancelLabel?: ReactNode;
+  /** Runs on Confirm. The dialog waits while it runs and shows its error if it throws. */
+  onConfirm?(): void | Promise<void>;
+}
+
+export interface PromptOptions extends DialogBaseOptions {
+  cancelLabel?: ReactNode;
+  defaultValue?: string;
+  placeholder?: string;
+  inputLabel?: ReactNode;
+  inputType?: "text" | "email" | "password" | "number" | "url" | "tel";
+  required?: boolean;
+  /** Return a message to block confirming. */
+  validate?(value: string): string | null | undefined;
+  /** Runs with the value on Confirm. The dialog waits while it runs and shows its error if it throws. */
+  onConfirm?(value: string): void | Promise<void>;
+}
+
+export type DialogRequest =
+  | { id: string; kind: "alert"; options: AlertOptions }
+  | { id: string; kind: "confirm"; options: ConfirmOptions }
+  | { id: string; kind: "prompt"; options: PromptOptions };
+
+export interface DialogSnapshot {
+  /** The first request is on screen; the rest wait their turn. */
+  queue: readonly DialogRequest[];
+}
+
+export interface DialogLocaleText {
+  ok: string;
+  confirm: string;
+  cancel: string;
+  required: string;
+}

package/source/beta-components/dialog/index.ts

@@ -0,0 +1,7 @@
+export { Dialog } from "./react/Dialog";
+export type { DialogAction, DialogProps } from "./react/Dialog";
+export { DialogHost } from "./react/DialogHost";
+export type { DialogHostProps } from "./react/DialogHost";
+export { defaultDialogText } from "./react/locale";
+export type { DialogSlot } from "./react/props";
+export * from "./core";

package/source/beta-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>
+  );
+}