gbs-add-block 1.2.13 → 1.2.15

package/source/beta-components/spinner/react/Spinner.tsx

@@ -0,0 +1,96 @@
+"use client";
+
+import { useMemo, type CSSProperties, type HTMLAttributes, type ReactNode } from "react";
+import { spinnerPixels } from "../core/visibility";
+import type { SpinnerLocaleText, SpinnerSize, SpinnerVariant } from "../core/types";
+import { defaultSpinnerText } from "./locale";
+import { cx, type SpinnerSlot } from "./props";
+import { useDelayedLoading } from "./useDelayedLoading";
+
+export interface SpinnerProps extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+  /** Default true. With `children`, the spinner covers them while this is true. */
+  loading?: boolean;
+  /** Default `md` (24 px); a number is pixels. */
+  size?: SpinnerSize | number;
+  /** Default `ring`. */
+  variant?: SpinnerVariant;
+  /** What screen readers announce. Default "Loading". */
+  label?: string;
+  /** Show the label next to the spinner. */
+  showLabel?: boolean;
+  /** Milliseconds to wait before showing, so fast work doesn't flash. Default 0. */
+  delay?: number;
+  /** Once shown, stay at least this many milliseconds. Default 0. */
+  minDuration?: number;
+  /** Content to cover while loading. It becomes inert, so it can't be clicked or focused. */
+  children?: ReactNode;
+  classNames?: Partial<Record<SpinnerSlot, string>>;
+  localeText?: Partial<SpinnerLocaleText>;
+}
+
+/** A loading indicator, on its own or covering content that is busy. */
+export function Spinner(props: SpinnerProps) {
+  const {
+    loading = true,
+    size = "md",
+    variant = "ring",
+    label,
+    showLabel = false,
+    delay = 0,
+    minDuration = 0,
+    children,
+    className,
+    classNames,
+    style,
+    localeText,
+    ...rest
+  } = props;
+
+  const text = useMemo(() => ({ ...defaultSpinnerText, ...localeText }), [localeText]);
+  const visible = useDelayedLoading(loading, { delay, minDuration });
+  const sized = { "--sp-size": `${spinnerPixels(size)}px`, ...style } as CSSProperties;
+
+  const status = (
+    <span role="status" className={cx("sp-status", classNames?.status)}>
+      <span className={cx("sp-indicator", classNames?.indicator)} data-variant={variant} aria-hidden="true">
+        {variant === "dots" ? (
+          <>
+            <span className="sp-dot" />
+            <span className="sp-dot" />
+            <span className="sp-dot" />
+          </>
+        ) : (
+          <svg className="sp-ring" viewBox="0 0 24 24" focusable="false">
+            <circle className="sp-track" cx="12" cy="12" r="9.5" />
+            <circle className="sp-arc" cx="12" cy="12" r="9.5" pathLength={100} />
+          </svg>
+        )}
+      </span>
+      <span className={showLabel ? cx("sp-label", classNames?.label) : "sp-sr-only"}>{label ?? text.loading}</span>
+    </span>
+  );
+
+  if (children === undefined) {
+    if (!visible) return null;
+    return (
+      <span {...rest} className={cx("sp-root", classNames?.root, className)} style={sized} data-variant={variant}>
+        {status}
+      </span>
+    );
+  }
+
+  return (
+    <div
+      {...rest}
+      className={cx("sp-container", classNames?.root, className)}
+      style={sized}
+      aria-busy={visible || undefined}
+      data-loading={visible || undefined}
+    >
+      <div className={cx("sp-content", classNames?.content)} inert={visible}>
+        {children}
+      </div>
+      {visible && <div className={cx("sp-overlay", classNames?.overlay)}>{status}</div>}
+    </div>
+  );
+}

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

@@ -0,0 +1,5 @@
+import type { SpinnerLocaleText } from "../core/types";
+
+export const defaultSpinnerText: SpinnerLocaleText = {
+  loading: "Loading",
+};

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

@@ -0,0 +1,4 @@
+export type SpinnerSlot = "root" | "status" | "indicator" | "label" | "content" | "overlay";
+
+export const cx = (...names: (string | false | null | undefined)[]) =>
+  names.filter(Boolean).join(" ");

package/source/beta-components/spinner/react/useDelayedLoading.ts

@@ -0,0 +1,39 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { stepVisibility } from "../core/visibility";
+import type { VisibilityMarks, VisibilityOptions } from "../core/types";
+
+/**
+ * `loading`, smoothed for display: true only after `delay` has passed, and then
+ * for at least `minDuration`. Use it for any loading UI, not just the Spinner.
+ */
+export function useDelayedLoading(loading: boolean, options: VisibilityOptions = {}): boolean {
+  const { delay = 0, minDuration = 0 } = options;
+  const immediate = delay <= 0 && minDuration <= 0;
+  const [visible, setVisible] = useState(() => loading && delay <= 0);
+  const marks = useRef<VisibilityMarks>({ visible: loading && delay <= 0, loadingSince: null, visibleSince: null });
+
+  useEffect(() => {
+    if (immediate) return;
+    const current = marks.current;
+    const now = Date.now();
+    current.loadingSince = loading ? (current.loadingSince ?? now) : null;
+    if (current.visible) current.visibleSince ??= now;
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const evaluate = () => {
+      const step = stepVisibility(loading, current, Date.now(), { delay, minDuration });
+      if (step.visible !== current.visible) {
+        current.visible = step.visible;
+        current.visibleSince = step.visible ? Date.now() : null;
+        setVisible(step.visible);
+      }
+      if (step.recheckIn !== null) timer = setTimeout(evaluate, step.recheckIn);
+    };
+    timer = setTimeout(evaluate, 0);
+    return () => clearTimeout(timer);
+  }, [loading, delay, minDuration, immediate]);
+
+  return immediate ? loading : visible;
+}

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

@@ -0,0 +1,167 @@
+/*
+ * Spinner styles.
+ *
+ * The indicator draws in `currentColor`, so it takes the color of its
+ * surroundings. Tokens read the DataGrid's --dg-* variables when they are set on
+ * an ancestor. Rules live in the `components` layer, so utility classes passed
+ * through `className` / `classNames` override them.
+ */
+@layer theme, base, components, utilities;
+
+@layer components {
+  .sp-root,
+  .sp-container {
+    --sp-size: 24px;
+    --sp-color: currentColor;
+    --sp-track: color-mix(in oklab, currentColor 18%, transparent);
+    --sp-duration: 0.8s;
+    --sp-overlay-bg: color-mix(in oklab, var(--dg-bg, light-dark(#ffffff, #0b0b0e)) 72%, transparent);
+    --sp-overlay-color: var(--dg-accent, light-dark(#2563eb, #60a5fa));
+    --sp-font-size: var(--dg-font-size, 13px);
+
+    color-scheme: inherit;
+  }
+
+  :where(.sp-root, .sp-container) *,
+  :where(.sp-root, .sp-container) *::before,
+  :where(.sp-root, .sp-container) *::after {
+    box-sizing: border-box;
+  }
+
+  .sp-root {
+    display: inline-flex;
+    align-items: center;
+    vertical-align: middle;
+    color: var(--sp-color);
+    font-size: var(--sp-font-size);
+  }
+
+  .sp-status {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+  }
+  .sp-label {
+    line-height: 1.4;
+  }
+
+  .sp-indicator {
+    display: inline-grid;
+    flex: none;
+    place-items: center;
+    width: var(--sp-size);
+    height: var(--sp-size);
+  }
+
+  /* ---------------------------------------------------------------- ring */
+
+  .sp-ring {
+    width: 100%;
+    height: 100%;
+    animation: sp-rotate var(--sp-duration) linear infinite;
+  }
+  .sp-track,
+  .sp-arc {
+    fill: none;
+    stroke-width: 2.5;
+  }
+  .sp-track {
+    stroke: var(--sp-track);
+  }
+  .sp-arc {
+    stroke: currentColor;
+    stroke-linecap: round;
+    stroke-dasharray: 28 100;
+  }
+  @keyframes sp-rotate {
+    to {
+      transform: rotate(360deg);
+    }
+  }
+
+  /* ---------------------------------------------------------------- dots */
+
+  .sp-indicator[data-variant="dots"] {
+    grid-auto-flow: column;
+    gap: calc(var(--sp-size) * 0.1);
+  }
+  .sp-dot {
+    width: calc(var(--sp-size) * 0.22);
+    aspect-ratio: 1;
+    border-radius: 50%;
+    background: currentColor;
+    animation: sp-pulse calc(var(--sp-duration) * 1.4) ease-in-out infinite;
+  }
+  .sp-dot:nth-child(2) {
+    animation-delay: calc(var(--sp-duration) * 0.18);
+  }
+  .sp-dot:nth-child(3) {
+    animation-delay: calc(var(--sp-duration) * 0.36);
+  }
+  @keyframes sp-pulse {
+    0%,
+    80%,
+    100% {
+      opacity: 0.25;
+      scale: 0.7;
+    }
+    40% {
+      opacity: 1;
+      scale: 1;
+    }
+  }
+
+  /* ----------------------------------------------------------- container */
+
+  .sp-container {
+    position: relative;
+  }
+  .sp-overlay {
+    position: absolute;
+    inset: 0;
+    z-index: 1;
+    display: grid;
+    place-items: center;
+    border-radius: inherit;
+    background: var(--sp-overlay-bg);
+    color: var(--sp-overlay-color);
+    font-size: var(--sp-font-size);
+    animation: sp-fade 150ms ease both;
+  }
+  @keyframes sp-fade {
+    from {
+      opacity: 0;
+    }
+  }
+
+  .sp-sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    margin: -1px;
+    padding: 0;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+    border: 0;
+  }
+
+  /* Slower, not stopped: a frozen spinner reads as a hang. */
+  @media (prefers-reduced-motion: reduce) {
+    .sp-root,
+    .sp-container {
+      --sp-duration: 2.4s;
+    }
+    .sp-overlay {
+      animation: none;
+    }
+  }
+
+  @media (forced-colors: active) {
+    .sp-arc,
+    .sp-dot {
+      stroke: CanvasText;
+      background: CanvasText;
+    }
+  }
+}

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

@@ -0,0 +1,32 @@
+# Tabs
+
+Accessible tabs for React 19 following the WAI-ARIA tabs pattern, styled to
+match the rest of the library. No runtime dependencies besides React.
+
+```ts
+import { Tab, TabList, TabPanel, Tabs } from "@/components/tabs";
+import "@/components/tabs/styles.css";
+```
+
+```tsx
+<Tabs defaultValue="overview">
+  <TabList aria-label="Project">
+    <Tab value="overview">Overview</Tab>
+    <Tab value="activity" badge={3}>Activity</Tab>
+    <Tab value="billing" disabled>Billing</Tab>
+  </TabList>
+  <TabPanel value="overview">…</TabPanel>
+  <TabPanel value="activity">…</TabPanel>
+</Tabs>
+```
+
+**Tabs:** `value` / `defaultValue` / `onValueChange`, `orientation`
+(`horizontal` `vertical`), `activation` (`automatic` `manual`), `variant` (`line`
+`pills` `enclosed`), `size`, `keepMounted`.
+**Tab:** `value`, `disabled`, `icon`, `badge`.
+**TabPanel:** `value`, `keepMounted`.
+
+Arrow keys move between tabs (swapped in right-to-left layouts), Home and End
+jump, and disabled tabs are skipped. `keepMounted` keeps hidden panels' state
+using React's `<Activity>`. `nextTab` and `tabDomId` are exported from the
+framework-free `core`.

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

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import { nextTab, tabDomId } from "../core/navigation";
+
+const tabs = [{}, { disabled: true }, {}, {}];
+
+describe("keyboard movement", () => {
+  it("moves with the arrows, skipping disabled tabs", () => {
+    expect(nextTab(tabs, 0, "ArrowRight")).toBe(2);
+    expect(nextTab(tabs, 2, "ArrowLeft")).toBe(0);
+  });
+
+  it("wraps around by default, or stops at the ends", () => {
+    expect(nextTab(tabs, 3, "ArrowRight")).toBe(0);
+    expect(nextTab(tabs, 0, "ArrowLeft")).toBe(3);
+    expect(nextTab(tabs, 3, "ArrowRight", { loop: false })).toBeNull();
+    expect(nextTab(tabs, 0, "ArrowLeft", { loop: false })).toBeNull();
+  });
+
+  it("jumps with Home and End", () => {
+    expect(nextTab(tabs, 2, "Home")).toBe(0);
+    expect(nextTab(tabs, 0, "End")).toBe(3);
+    expect(nextTab([{ disabled: true }, {}, { disabled: true }], 1, "End")).toBe(1);
+  });
+
+  it("uses up and down when vertical, and ignores the other axis", () => {
+    expect(nextTab(tabs, 0, "ArrowDown", { orientation: "vertical" })).toBe(2);
+    expect(nextTab(tabs, 2, "ArrowUp", { orientation: "vertical" })).toBe(0);
+    expect(nextTab(tabs, 0, "ArrowRight", { orientation: "vertical" })).toBeNull();
+    expect(nextTab(tabs, 0, "ArrowDown")).toBeNull();
+  });
+
+  it("swaps left and right in right-to-left layouts", () => {
+    expect(nextTab(tabs, 0, "ArrowLeft", { rtl: true })).toBe(2);
+    expect(nextTab(tabs, 2, "ArrowRight", { rtl: true })).toBe(0);
+  });
+
+  it("returns null when nothing can take focus", () => {
+    expect(nextTab([], 0, "ArrowRight")).toBeNull();
+    expect(nextTab([{ disabled: true }], 0, "ArrowRight")).toBeNull();
+    expect(nextTab(tabs, 0, "Enter")).toBeNull();
+  });
+});
+
+describe("ids", () => {
+  it("makes safe, distinct ids from any value", () => {
+    expect(tabDomId("t1", "tab", "overview")).toBe("t1-tab-overview");
+    expect(tabDomId("t1", "panel", "billing & plans")).toBe("t1-panel-billing_20_26_20plans");
+    expect(tabDomId("t1", "tab", "a b")).not.toBe(tabDomId("t1", "tab", "a_b"));
+    expect(tabDomId("t1", "tab", "v1.2")).toMatch(/^[\w-]+$/);
+  });
+});

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

@@ -0,0 +1,3 @@
+// Framework-free: keyboard movement and ids for the tabs pattern.
+export { nextTab, tabDomId } from "./navigation";
+export type * from "./types";

package/source/beta-components/tabs/core/navigation.ts

@@ -0,0 +1,54 @@
+import type { NavigationOptions } from "./types";
+
+/**
+ * The tab a key moves to, skipping disabled tabs, or null when the key isn't a
+ * tab key (or there is nowhere to go). Follows the WAI-ARIA tabs pattern.
+ */
+export function nextTab(
+  tabs: readonly { disabled?: boolean }[],
+  current: number,
+  key: string,
+  options: NavigationOptions = {},
+): number | null {
+  const { orientation = "horizontal", rtl = false, loop = true } = options;
+  const count = tabs.length;
+  if (count === 0) return null;
+
+  const horizontal = orientation === "horizontal";
+  const previousKey = horizontal ? (rtl ? "ArrowRight" : "ArrowLeft") : "ArrowUp";
+  const nextKey = horizontal ? (rtl ? "ArrowLeft" : "ArrowRight") : "ArrowDown";
+
+  const scan = (start: number, step: 1 | -1): number | null => {
+    let index = start;
+    for (let visited = 0; visited < count; visited++) {
+      if (index < 0 || index >= count) {
+        if (!loop) return null;
+        index = (index + count) % count;
+      }
+      if (!tabs[index].disabled) return index;
+      index += step;
+    }
+    return null;
+  };
+
+  switch (key) {
+    case nextKey:
+      return scan(current + 1, 1);
+    case previousKey:
+      return scan(current - 1, -1);
+    case "Home":
+      return scan(0, 1);
+    case "End":
+      return scan(count - 1, -1);
+    default:
+      return null;
+  }
+}
+
+/**
+ * A DOM id for a tab or panel. Values may contain spaces or symbols, so they are
+ * percent-encoded with `_` in place of `%`, which keeps different values distinct.
+ */
+export function tabDomId(base: string, part: "tab" | "panel", value: string): string {
+  return `${base}-${part}-${encodeURIComponent(value).replace(/[%.!~*'()]/g, "_")}`;
+}

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

@@ -0,0 +1,16 @@
+export type TabsOrientation = "horizontal" | "vertical";
+
+/** `automatic` selects a tab as soon as it gets focus; `manual` waits for Enter or Space. */
+export type TabsActivation = "automatic" | "manual";
+
+export type TabsVariant = "line" | "pills" | "enclosed";
+
+export type TabsSize = "sm" | "md" | "lg";
+
+export interface NavigationOptions {
+  orientation?: TabsOrientation;
+  /** Right-to-left: the horizontal arrow keys swap. */
+  rtl?: boolean;
+  /** Wrap from the last tab to the first. Default true. */
+  loop?: boolean;
+}

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

@@ -0,0 +1,5 @@
+export { Tab, TabList, TabPanel, Tabs } from "./react/Tabs";
+export type { TabListProps, TabPanelProps, TabProps, TabsProps } from "./react/Tabs";
+export { TabsContext, useTabsContext } from "./react/context";
+export type { TabsContextValue } from "./react/context";
+export * from "./core";