gbs-add-block 1.2.13 → 1.2.15

package/source/beta-components/modal/react/Modal.tsx

@@ -0,0 +1,238 @@
+"use client";
+
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+  type MouseEvent,
+  type ReactNode,
+  type Ref,
+  type RefObject,
+} from "react";
+import { canDismiss, confirmClose, isOutside } from "../core/dismiss";
+import type {
+  CloseReason,
+  ModalLocaleText,
+  ModalPlacement,
+  ModalSize,
+} from "../core/types";
+import { XIcon } from "./icons";
+import { defaultModalText } from "./locale";
+import { cx, type ModalHandle, type ModalRenderProps, type ModalSlot } from "./props";
+
+/** Matches the CSS transition, so content stays mounted while the modal animates out. */
+const EXIT_DURATION = 200;
+
+type Renderable = ReactNode | ((props: ModalRenderProps) => ReactNode);
+
+export interface ModalProps {
+  /** Controlled open state. */
+  open?: boolean;
+  defaultOpen?: boolean;
+  /** `reason` says what closed it; it is undefined when opening. */
+  onOpenChange?(open: boolean, reason?: CloseReason): void;
+  title?: ReactNode;
+  description?: ReactNode;
+  /** Accessible name when there is no `title`. */
+  "aria-label"?: string;
+  children?: Renderable;
+  footer?: Renderable;
+  /** Width for dialogs; for drawers, the width (left/right) or height (bottom). Default `md`. */
+  size?: ModalSize;
+  /** Default `center`. */
+  placement?: ModalPlacement;
+  /** Show the × button. Default true. */
+  closeButton?: boolean;
+  /** Default true. */
+  closeOnEscape?: boolean;
+  /** Default true. */
+  closeOnBackdrop?: boolean;
+  /** Return `false` (or a promise of it) to keep the modal open, e.g. for unsaved changes. */
+  onBeforeClose?(reason: CloseReason): boolean | Promise<boolean>;
+  /** Focused on open. Otherwise the first `[data-autofocus]` element, then the first focusable one. */
+  initialFocus?: RefObject<HTMLElement | null>;
+  /** Keep the content mounted while closed, preserving its state. Default false. */
+  keepMounted?: boolean;
+  id?: string;
+  className?: string;
+  classNames?: Partial<Record<ModalSlot, string>>;
+  style?: CSSProperties;
+  localeText?: Partial<ModalLocaleText>;
+  ref?: Ref<ModalHandle>;
+}
+
+const outside = (event: MouseEvent<HTMLDialogElement>) =>
+  event.target === event.currentTarget &&
+  isOutside(event.currentTarget.getBoundingClientRect(), event.clientX, event.clientY);
+
+/**
+ * A modal built on the native `<dialog>` element. The browser provides the top
+ * layer, the inert background, the focus trap and focus return; the component
+ * adds controlled state, dismiss rules, drawers and animation.
+ */
+export function Modal(props: ModalProps) {
+  const {
+    ref,
+    open: openProp,
+    defaultOpen = false,
+    onOpenChange,
+    title,
+    description,
+    "aria-label": ariaLabel,
+    children,
+    footer,
+    size = "md",
+    placement = "center",
+    closeButton = true,
+    closeOnEscape = true,
+    closeOnBackdrop = true,
+    onBeforeClose,
+    initialFocus,
+    keepMounted = false,
+    id: idProp,
+    className,
+    classNames,
+    style,
+    localeText,
+  } = props;
+
+  const reactId = useId();
+  const id = idProp ?? reactId;
+  const text = useMemo(() => ({ ...defaultModalText, ...localeText }), [localeText]);
+  const dialogRef = useRef<HTMLDialogElement>(null);
+  const pressStartedOutside = useRef(false);
+
+  const [internalOpen, setInternalOpen] = useState(defaultOpen);
+  const open = openProp ?? internalOpen;
+
+  // Keep the content mounted through the exit transition. Adjusting state while
+  // rendering avoids an extra render with the content already gone.
+  const [previousOpen, setPreviousOpen] = useState(open);
+  const [closing, setClosing] = useState(false);
+  if (previousOpen !== open) {
+    setPreviousOpen(open);
+    setClosing(!open);
+  }
+
+  useEffect(() => {
+    if (!closing) return;
+    const timer = setTimeout(() => setClosing(false), EXIT_DURATION);
+    return () => clearTimeout(timer);
+  }, [closing]);
+
+  const setOpen = useCallback(
+    (next: boolean, reason?: CloseReason) => {
+      if (openProp === undefined) setInternalOpen(next);
+      onOpenChange?.(next, reason);
+    },
+    [openProp, onOpenChange],
+  );
+
+  const requestClose = useCallback(
+    (reason: CloseReason) => {
+      if (!canDismiss(reason, { closeOnEscape, closeOnBackdrop })) return;
+      void confirmClose(onBeforeClose, reason).then((allowed) => {
+        if (allowed) setOpen(false, reason);
+      });
+    },
+    [closeOnEscape, closeOnBackdrop, onBeforeClose, setOpen],
+  );
+
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    if (open && !dialog.open) {
+      dialog.showModal();
+      const target =
+        initialFocus?.current ?? dialog.querySelector<HTMLElement>("[data-autofocus]");
+      target?.focus();
+    } else if (!open && dialog.open) {
+      dialog.close();
+    }
+  }, [open, initialFocus]);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      open: () => setOpen(true),
+      close: () => requestClose("api"),
+      getElement: () => dialogRef.current,
+    }),
+    [setOpen, requestClose],
+  );
+
+  const renderProps: ModalRenderProps = { close: () => requestClose("api") };
+  const render = (node: Renderable) => (typeof node === "function" ? node(renderProps) : node);
+  const mounted = open || closing || keepMounted;
+
+  return (
+    <dialog
+      ref={dialogRef}
+      id={id}
+      className={cx("md-root", classNames?.root, className)}
+      style={style}
+      data-size={size}
+      data-placement={placement}
+      data-state={open ? "open" : "closed"}
+      aria-labelledby={title ? `${id}-title` : undefined}
+      aria-describedby={description ? `${id}-description` : undefined}
+      aria-label={title ? undefined : ariaLabel}
+      // Escape: keep the browser from closing it, and decide ourselves.
+      onCancel={(event) => {
+        event.preventDefault();
+        requestClose("escape");
+      }}
+      // Closed some other way, e.g. by a `<form method="dialog">` inside.
+      onClose={() => {
+        if (open) setOpen(false, "api");
+      }}
+      // A drag that starts inside and ends on the backdrop must not close it.
+      onPointerDown={(event) => {
+        pressStartedOutside.current = outside(event);
+      }}
+      onClick={(event) => {
+        if (pressStartedOutside.current && outside(event)) requestClose("backdrop");
+        pressStartedOutside.current = false;
+      }}
+    >
+      {mounted && (
+        <>
+          {(title || description || closeButton) && (
+            <header className={cx("md-header", classNames?.header)}>
+              <div className="md-heading">
+                {title && (
+                  <h2 id={`${id}-title`} className={cx("md-title", classNames?.title)}>
+                    {title}
+                  </h2>
+                )}
+                {description && (
+                  <p id={`${id}-description`} className={cx("md-description", classNames?.description)}>
+                    {description}
+                  </p>
+                )}
+              </div>
+              {closeButton && (
+                <button
+                  type="button"
+                  className={cx("md-close", classNames?.close)}
+                  aria-label={text.close}
+                  title={text.close}
+                  onClick={() => requestClose("close-button")}
+                >
+                  <XIcon />
+                </button>
+              )}
+            </header>
+          )}
+          <div className={cx("md-body", classNames?.body)}>{render(children)}</div>
+          {footer && <footer className={cx("md-footer", classNames?.footer)}>{render(footer)}</footer>}
+        </>
+      )}
+    </dialog>
+  );
+}

package/source/beta-components/modal/react/icons.tsx

@@ -0,0 +1,19 @@
+import type { SVGProps } from "react";
+
+export const XIcon = (props: SVGProps<SVGSVGElement>) => (
+  <svg
+    width="16"
+    height="16"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    aria-hidden="true"
+    focusable="false"
+    {...props}
+  >
+    <path d="M18 6 6 18M6 6l12 12" />
+  </svg>
+);

package/source/beta-components/modal/react/locale.ts

@@ -0,0 +1,5 @@
+import type { ModalLocaleText } from "../core/types";
+
+export const defaultModalText: ModalLocaleText = {
+  close: "Close",
+};

package/source/beta-components/modal/react/props.ts

@@ -0,0 +1,17 @@
+export type ModalSlot = "root" | "header" | "title" | "description" | "close" | "body" | "footer";
+
+export interface ModalHandle {
+  open(): void;
+  /** Asks to close; `onBeforeClose` still gets a say. */
+  close(): void;
+  getElement(): HTMLDialogElement | null;
+}
+
+/** Passed to `children` and `footer` when they are functions. */
+export interface ModalRenderProps {
+  /** Closes through `onBeforeClose`, like the close button. */
+  close(): void;
+}
+
+export const cx = (...names: (string | false | null | undefined)[]) =>
+  names.filter(Boolean).join(" ");

package/source/beta-components/modal/styles.css

@@ -0,0 +1,235 @@
+/*
+ * Modal styles.
+ *
+ * Tokens read the DataGrid's --dg-* variables when they are set on an ancestor
+ * (set them on :root to share one theme) and fall back to the same palette
+ * otherwise. Rules live in the `components` layer, so utility classes passed
+ * through `className` / `classNames` override them.
+ */
+@layer theme, base, components, utilities;
+
+@layer components {
+  .md-root {
+    --md-bg: var(--dg-bg, light-dark(#ffffff, #0b0b0e));
+    --md-fg: var(--dg-fg, light-dark(#18181b, #f4f4f5));
+    --md-muted: var(--dg-muted, light-dark(#71717a, #a1a1aa));
+    --md-border: var(--dg-border, light-dark(#e4e4e7, #27272a));
+    --md-hover: var(--dg-hover, light-dark(#f4f4f5, #1f1f23));
+    --md-footer-bg: var(--dg-header-bg, light-dark(#fafafa, #111114));
+    --md-focus: var(--dg-focus, light-dark(#2563eb, #60a5fa));
+    --md-shadow: 0 24px 64px -16px light-dark(rgb(0 0 0 / 0.3), rgb(0 0 0 / 0.8));
+    --md-backdrop: light-dark(rgb(9 9 11 / 0.45), rgb(0 0 0 / 0.65));
+    --md-radius: var(--dg-radius, 12px);
+    --md-font-size: var(--dg-font-size, 13px);
+    --md-width: 520px;
+    --md-gutter: 16px;
+    --md-px: 20px;
+    --md-duration: 200ms;
+    --md-enter: 0 8px;
+
+    color-scheme: inherit;
+    box-sizing: border-box;
+    width: min(var(--md-width), 100vw - 2 * var(--md-gutter));
+    max-width: none;
+    max-height: calc(100dvh - 2 * var(--md-gutter));
+    margin: auto;
+    padding: 0;
+    overflow: hidden;
+    border: 1px solid var(--md-border);
+    border-radius: var(--md-radius);
+    background: var(--md-bg);
+    color: var(--md-fg);
+    box-shadow: var(--md-shadow);
+    font-size: var(--md-font-size);
+    line-height: 1.5;
+    opacity: 0;
+    translate: var(--md-enter);
+    transition:
+      opacity var(--md-duration) ease,
+      translate var(--md-duration) ease,
+      overlay var(--md-duration) allow-discrete,
+      display var(--md-duration) allow-discrete;
+  }
+  .md-root[open] {
+    display: flex;
+    flex-direction: column;
+    opacity: 1;
+    translate: 0 0;
+  }
+  @starting-style {
+    .md-root[open] {
+      opacity: 0;
+      translate: var(--md-enter);
+    }
+  }
+
+  .md-root::backdrop {
+    background: var(--md-backdrop, rgb(9 9 11 / 0.45));
+    opacity: 0;
+    transition:
+      opacity var(--md-duration) ease,
+      overlay var(--md-duration) allow-discrete,
+      display var(--md-duration) allow-discrete;
+  }
+  .md-root[open]::backdrop {
+    opacity: 1;
+  }
+  @starting-style {
+    .md-root[open]::backdrop {
+      opacity: 0;
+    }
+  }
+
+  :where(.dark, [data-theme="dark"]) .md-root {
+    color-scheme: dark;
+  }
+  :where(.light, [data-theme="light"]) .md-root {
+    color-scheme: light;
+  }
+
+  :where(.md-root) *,
+  :where(.md-root) *::before,
+  :where(.md-root) *::after {
+    box-sizing: border-box;
+  }
+
+  /* The page behind an open modal doesn't scroll. */
+  :root:has(.md-root[open]) {
+    overflow: hidden;
+  }
+
+  /* --------------------------------------------------------------- sizes */
+
+  .md-root[data-size="sm"] {
+    --md-width: 400px;
+  }
+  .md-root[data-size="lg"] {
+    --md-width: 720px;
+  }
+  .md-root[data-size="xl"] {
+    --md-width: 960px;
+  }
+  .md-root[data-size="full"] {
+    --md-width: 100vw;
+    --md-gutter: 0px;
+    height: 100dvh;
+    max-height: 100dvh;
+    border: 0;
+    border-radius: 0;
+  }
+
+  /* ----------------------------------------------------------- placement */
+
+  .md-root[data-placement="top"] {
+    margin-top: min(10vh, 80px);
+  }
+
+  .md-root:is([data-placement="left"], [data-placement="right"]) {
+    --md-gutter: 0px;
+    height: 100dvh;
+    max-height: 100dvh;
+    border-block: 0;
+    border-radius: 0;
+  }
+  .md-root[data-placement="left"] {
+    --md-enter: -100% 0;
+    margin: 0 auto 0 0;
+    border-inline-start: 0;
+  }
+  .md-root[data-placement="right"] {
+    --md-enter: 100% 0;
+    margin: 0 0 0 auto;
+    border-inline-end: 0;
+  }
+  .md-root[data-placement="bottom"] {
+    --md-enter: 0 100%;
+    width: 100vw;
+    max-height: min(var(--md-width), 90dvh);
+    margin: auto 0 0;
+    border-bottom: 0;
+    border-radius: var(--md-radius) var(--md-radius) 0 0;
+  }
+
+  /* -------------------------------------------------------------- layout */
+
+  .md-header {
+    display: flex;
+    flex: none;
+    align-items: flex-start;
+    gap: 12px;
+    padding: 16px 12px 12px var(--md-px);
+  }
+  .md-heading {
+    flex: 1 1 auto;
+    min-width: 0;
+  }
+  .md-title {
+    margin: 0;
+    font-size: 1.15em;
+    font-weight: 600;
+    line-height: 1.35;
+  }
+  .md-description {
+    margin: 4px 0 0;
+    color: var(--md-muted);
+  }
+  .md-close {
+    display: inline-grid;
+    flex: none;
+    place-items: center;
+    width: 30px;
+    height: 30px;
+    margin-top: -4px;
+    padding: 0;
+    border: 0;
+    border-radius: 6px;
+    background: transparent;
+    color: var(--md-muted);
+    cursor: pointer;
+  }
+  .md-close:hover {
+    background: var(--md-hover);
+    color: var(--md-fg);
+  }
+  .md-close:focus-visible {
+    outline: 2px solid var(--md-focus);
+    outline-offset: 1px;
+  }
+
+  .md-body {
+    flex: 1 1 auto;
+    min-height: 0;
+    padding: 0 var(--md-px) 20px;
+    overflow: auto;
+    overscroll-behavior: contain;
+  }
+  .md-body:first-child {
+    padding-top: 20px;
+  }
+
+  .md-footer {
+    display: flex;
+    flex: none;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: flex-end;
+    gap: 8px;
+    padding: 12px var(--md-px);
+    border-top: 1px solid var(--md-border);
+    background: var(--md-footer-bg);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .md-root,
+    .md-root::backdrop {
+      --md-enter: 0 0;
+      transition-duration: 0s;
+    }
+  }
+
+  @media (forced-colors: active) {
+    .md-root {
+      border: 1px solid CanvasText;
+    }
+  }
+}

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

@@ -0,0 +1,29 @@
+# Spinner
+
+A loading indicator for React 19, on its own or covering busy content, styled to
+match the rest of the library. No runtime dependencies besides React.
+
+```ts
+import { Spinner, useDelayedLoading } from "@/components/spinner";
+import "@/components/spinner/styles.css";
+```
+
+```tsx
+<Spinner />                                   {/* 24 px ring in the current text color */}
+<Spinner size="sm" showLabel label="Saving…" />
+<Spinner loading={isPending} delay={250} minDuration={600}>
+  <Chart />                                   {/* covered and inert while loading */}
+</Spinner>
+```
+
+| Prop | Default | Description |
+| --- | --- | --- |
+| `loading` | `true` | With children, covers them while true. |
+| `size` | `md` | `xs` 12 · `sm` 16 · `md` 24 · `lg` 32 · `xl` 48, or pixels. |
+| `variant` | `ring` | `ring` or `dots`. |
+| `label` / `showLabel` | "Loading" / `false` | Announced text; optionally shown. |
+| `delay` / `minDuration` | `0` / `0` | Wait before showing; stay at least this long once shown. |
+| `className`, `classNames`, `style`, `localeText` | — | Slots: `root`, `status`, `indicator`, `label`, `content`, `overlay`. |
+
+`useDelayedLoading(loading, { delay, minDuration })` applies the same timing to
+any loading UI. `stepVisibility` is the framework-free rule behind it.

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

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { spinnerPixels, stepVisibility } from "../core/visibility";
+
+const hidden = { visible: false, loadingSince: null, visibleSince: null };
+
+describe("visibility", () => {
+  it("shows at once without a delay", () => {
+    expect(stepVisibility(true, { ...hidden, loadingSince: 1000 }, 1000)).toEqual({ visible: true, recheckIn: null });
+  });
+
+  it("waits out the delay, then shows", () => {
+    const marks = { ...hidden, loadingSince: 1000 };
+    expect(stepVisibility(true, marks, 1100, { delay: 300 })).toEqual({ visible: false, recheckIn: 200 });
+    expect(stepVisibility(true, marks, 1300, { delay: 300 })).toEqual({ visible: true, recheckIn: null });
+  });
+
+  it("never shows for work that ends within the delay", () => {
+    expect(stepVisibility(false, hidden, 1200, { delay: 300 })).toEqual({ visible: false, recheckIn: null });
+  });
+
+  it("stays for the minimum duration once shown", () => {
+    const shown = { visible: true, loadingSince: null, visibleSince: 2000 };
+    expect(stepVisibility(false, shown, 2100, { minDuration: 500 })).toEqual({ visible: true, recheckIn: 400 });
+    expect(stepVisibility(false, shown, 2500, { minDuration: 500 })).toEqual({ visible: false, recheckIn: null });
+  });
+
+  it("keeps showing while loading continues", () => {
+    const shown = { visible: true, loadingSince: 1000, visibleSince: 1300 };
+    expect(stepVisibility(true, shown, 9000, { delay: 300, minDuration: 500 })).toEqual({
+      visible: true,
+      recheckIn: null,
+    });
+  });
+
+  it("treats negative options as zero", () => {
+    expect(stepVisibility(true, { ...hidden, loadingSince: 0 }, 0, { delay: -50 }).visible).toBe(true);
+  });
+});
+
+describe("size", () => {
+  it("maps names to pixels and passes numbers through", () => {
+    expect(spinnerPixels()).toBe(24);
+    expect(spinnerPixels("xs")).toBe(12);
+    expect(spinnerPixels("xl")).toBe(48);
+    expect(spinnerPixels(20)).toBe(20);
+    expect(spinnerPixels(0)).toBe(1);
+  });
+});

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

@@ -0,0 +1,3 @@
+// Framework-free: when a spinner shows, and how big it is.
+export { spinnerPixels, stepVisibility } from "./visibility";
+export type * from "./types";

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

@@ -0,0 +1,28 @@
+export type SpinnerSize = "xs" | "sm" | "md" | "lg" | "xl";
+
+export type SpinnerVariant = "ring" | "dots";
+
+export interface VisibilityOptions {
+  /** Wait this long before showing, so fast work never flashes a spinner. Default 0. */
+  delay?: number;
+  /** Once shown, stay at least this long, so it doesn't blink off. Default 0. */
+  minDuration?: number;
+}
+
+export interface VisibilityMarks {
+  visible: boolean;
+  /** When `loading` last turned true, or null while not loading. */
+  loadingSince: number | null;
+  /** When the spinner last appeared, or null while hidden. */
+  visibleSince: number | null;
+}
+
+export interface VisibilityStep {
+  visible: boolean;
+  /** Milliseconds until the answer can change, or null when it won't on its own. */
+  recheckIn: number | null;
+}
+
+export interface SpinnerLocaleText {
+  loading: string;
+}

package/source/beta-components/spinner/core/visibility.ts

@@ -0,0 +1,34 @@
+import type { SpinnerSize, VisibilityMarks, VisibilityOptions, VisibilityStep } from "./types";
+
+/**
+ * Whether a spinner should be on screen right now. A short `delay` hides work
+ * that finishes quickly; a `minDuration` keeps a spinner that did appear from
+ * vanishing a moment later. Both avoid the flicker of a spinner that blinks.
+ */
+export function stepVisibility(
+  loading: boolean,
+  marks: VisibilityMarks,
+  now: number,
+  options: VisibilityOptions = {},
+): VisibilityStep {
+  const delay = Math.max(0, options.delay ?? 0);
+  const minDuration = Math.max(0, options.minDuration ?? 0);
+
+  if (loading && !marks.visible) {
+    const waited = now - (marks.loadingSince ?? now);
+    return waited >= delay ? { visible: true, recheckIn: null } : { visible: false, recheckIn: delay - waited };
+  }
+  if (!loading && marks.visible) {
+    const shown = now - (marks.visibleSince ?? now);
+    return shown >= minDuration
+      ? { visible: false, recheckIn: null }
+      : { visible: true, recheckIn: minDuration - shown };
+  }
+  return { visible: marks.visible, recheckIn: null };
+}
+
+const SIZES: Record<SpinnerSize, number> = { xs: 12, sm: 16, md: 24, lg: 32, xl: 48 };
+
+/** Pixel size for a named size; numbers pass through. */
+export const spinnerPixels = (size: SpinnerSize | number = "md") =>
+  typeof size === "number" ? Math.max(1, size) : SIZES[size];

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

@@ -0,0 +1,6 @@
+export { Spinner } from "./react/Spinner";
+export type { SpinnerProps } from "./react/Spinner";
+export { useDelayedLoading } from "./react/useDelayedLoading";
+export { defaultSpinnerText } from "./react/locale";
+export type { SpinnerSlot } from "./react/props";
+export * from "./core";