gbs-add-block 1.2.14 → 1.2.16

package/source/beta-components/breadcrumb/react/Breadcrumb.tsx

@@ -0,0 +1,177 @@
+"use client";
+
+import {
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type HTMLAttributes,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import { collapseItems, toBreadcrumbJsonLd } from "../core/trail";
+import type { BreadcrumbItem, BreadcrumbLocaleText } from "../core/types";
+import { defaultBreadcrumbText } from "./locale";
+import { cx, type BreadcrumbLinkProps, type BreadcrumbSlot } from "./props";
+
+export interface BreadcrumbProps extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+  /** From the top level to the current page. The last item is the current page. */
+  items: readonly BreadcrumbItem[];
+  /** Between crumbs. Default a chevron. */
+  separator?: ReactNode;
+  /** Collapse the middle of the trail when it has more crumbs than this. */
+  maxItems?: number;
+  /** Crumbs kept before the collapsed part. Default 1. */
+  itemsBeforeCollapse?: number;
+  /** Crumbs kept after the collapsed part. Default 1. */
+  itemsAfterCollapse?: number;
+  /** Draw links with your router, e.g. `(props) => <Link {...props} />`. */
+  renderLink?(props: BreadcrumbLinkProps): ReactElement;
+  /**
+   * Add schema.org `BreadcrumbList` JSON-LD for search engines. Pass
+   * `{ baseUrl }` so relative links become absolute, as search engines require.
+   */
+  structuredData?: boolean | { baseUrl: string };
+  size?: "sm" | "md" | "lg";
+  classNames?: Partial<Record<BreadcrumbSlot, string>>;
+  localeText?: Partial<BreadcrumbLocaleText>;
+}
+
+const Chevron = () => (
+  <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" focusable="false">
+    <path d="m9 18 6-6-6-6" />
+  </svg>
+);
+
+/** Where the current page sits in the site's hierarchy. */
+export function Breadcrumb(props: BreadcrumbProps) {
+  const {
+    items,
+    separator,
+    maxItems,
+    itemsBeforeCollapse = 1,
+    itemsAfterCollapse = 1,
+    renderLink,
+    structuredData = false,
+    size = "md",
+    className,
+    classNames,
+    localeText,
+    "aria-label": ariaLabel,
+    ...rest
+  } = props;
+
+  const text = useMemo(() => ({ ...defaultBreadcrumbText, ...localeText }), [localeText]);
+  const listRef = useRef<HTMLOListElement>(null);
+  const [expanded, setExpanded] = useState(false);
+  const [revealFrom, setRevealFrom] = useState<number | null>(null);
+
+  // After expanding, move focus to the first crumb that was hidden, not to <body>.
+  useEffect(() => {
+    if (revealFrom === null) return;
+    listRef.current?.querySelector<HTMLElement>(`[data-index="${revealFrom}"] :is(a, button, [tabindex])`)?.focus();
+  }, [revealFrom]);
+
+  const slots = expanded
+    ? collapseItems(items.length)
+    : collapseItems(items.length, maxItems, itemsBeforeCollapse, itemsAfterCollapse);
+  const lastIndex = items.length - 1;
+
+  const renderItem = (item: BreadcrumbItem, index: number) => {
+    const content = (
+      <>
+        {item.icon && (
+          <span className="bc-icon" aria-hidden="true">
+            {item.icon}
+          </span>
+        )}
+        <span className="bc-text" title={typeof item.label === "string" ? item.label : undefined}>
+          {item.label}
+        </span>
+      </>
+    );
+
+    if (index === lastIndex || (!item.href && !item.onClick)) {
+      return (
+        <span
+          className={cx("bc-current", classNames?.current)}
+          aria-current={index === lastIndex ? "page" : undefined}
+        >
+          {content}
+        </span>
+      );
+    }
+    if (item.href) {
+      const linkProps: BreadcrumbLinkProps = {
+        href: item.href,
+        className: cx("bc-link", classNames?.link),
+        children: content,
+        onClick: item.onClick ? () => item.onClick?.() : undefined,
+      };
+      return renderLink ? renderLink(linkProps) : <a {...linkProps} />;
+    }
+    return (
+      <button type="button" className={cx("bc-link", classNames?.link)} onClick={item.onClick}>
+        {content}
+      </button>
+    );
+  };
+
+  const jsonLd = structuredData
+    ? toBreadcrumbJsonLd(
+        items.map((item) => ({
+          name: item.name ?? (typeof item.label === "string" ? item.label : ""),
+          href: item.href,
+        })),
+        typeof structuredData === "object" ? structuredData.baseUrl : undefined,
+      )
+    : null;
+
+  return (
+    <nav
+      {...rest}
+      aria-label={ariaLabel ?? text.label}
+      className={cx("bc-root", classNames?.root, className)}
+      data-size={size}
+    >
+      <ol ref={listRef} className={cx("bc-list", classNames?.list)}>
+        {slots.map((slot, position) => (
+          <li
+            key={slot.kind === "item" ? slot.index : "ellipsis"}
+            className={cx("bc-item", classNames?.item)}
+            data-index={slot.kind === "item" ? slot.index : undefined}
+          >
+            {position > 0 && (
+              <span className={cx("bc-separator", classNames?.separator)} aria-hidden="true">
+                {separator ?? <Chevron />}
+              </span>
+            )}
+            {slot.kind === "item" ? (
+              renderItem(items[slot.index], slot.index)
+            ) : (
+              <button
+                type="button"
+                className={cx("bc-ellipsis", classNames?.ellipsis)}
+                aria-label={text.showMore(String(slot.hidden.length))}
+                title={text.showMore(String(slot.hidden.length))}
+                onClick={() => {
+                  setExpanded(true);
+                  setRevealFrom(slot.hidden[0]);
+                }}
+              >
+                …
+              </button>
+            )}
+          </li>
+        ))}
+      </ol>
+      {jsonLd && (
+        <script
+          type="application/ld+json"
+          // `<` is escaped so a crumb's name can never close the script tag.
+          dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd).replace(/</g, "\\u003c") }}
+        />
+      )}
+    </nav>
+  );
+}

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

@@ -0,0 +1,6 @@
+import type { BreadcrumbLocaleText } from "../core/types";
+
+export const defaultBreadcrumbText: BreadcrumbLocaleText = {
+  label: "Breadcrumb",
+  showMore: (count) => `Show ${count} more`,
+};

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

@@ -0,0 +1,14 @@
+import type { MouseEventHandler, ReactNode } from "react";
+
+export type BreadcrumbSlot = "root" | "list" | "item" | "link" | "current" | "separator" | "ellipsis";
+
+/** Handed to `renderLink`, to draw a crumb with your router's link component. */
+export interface BreadcrumbLinkProps {
+  href: string;
+  className: string;
+  children: ReactNode;
+  onClick?: MouseEventHandler<HTMLAnchorElement>;
+}
+
+// Shared with every other component, so class handling cannot drift.
+export { cx } from "../../shared/core/cx";

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

@@ -0,0 +1,139 @@
+/*
+ * Breadcrumb styles.
+ *
+ * Tokens read the shared --gbs-* variables when they are set on an ancestor
+ * (set them on :root to theme every component at once) and fall back to the
+ * same default palette otherwise. Rules live in the `components` layer, so utility classes passed
+ * through `className` / `classNames` override them.
+ */
+@layer theme, base, components, utilities;
+
+@layer components {
+  .bc-root {
+    --bc-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
+    --bc-muted: var(--gbs-muted, var(--dg-muted, light-dark(#71717a, #a1a1aa)));
+    --bc-hover: var(--gbs-hover, var(--dg-hover, light-dark(#f4f4f5, #1f1f23)));
+    --bc-focus: var(--gbs-focus, var(--dg-focus, light-dark(#2563eb, #60a5fa)));
+    --bc-font-size: var(--gbs-font-size, var(--dg-font-size, 13px));
+    /* Long labels are cut with an ellipsis; the full text is in the tooltip. */
+    --bc-max-label: 24ch;
+
+    color-scheme: inherit;
+    font-size: var(--bc-font-size);
+    line-height: 1.4;
+    color: var(--bc-muted);
+  }
+
+  :where(.dark, [data-theme="dark"]) .bc-root {
+    color-scheme: dark;
+  }
+  :where(.light, [data-theme="light"]) .bc-root {
+    color-scheme: light;
+  }
+
+  :where(.bc-root) *,
+  :where(.bc-root) *::before,
+  :where(.bc-root) *::after {
+    box-sizing: border-box;
+  }
+
+  .bc-root[data-size="sm"] {
+    --bc-font-size: 12px;
+  }
+  .bc-root[data-size="lg"] {
+    --bc-font-size: 14px;
+  }
+
+  .bc-list {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 4px 6px;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+  .bc-item {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    min-width: 0;
+  }
+
+  .bc-link,
+  .bc-current {
+    display: inline-flex;
+    align-items: center;
+    gap: 5px;
+    min-width: 0;
+  }
+  .bc-link {
+    margin: -2px -4px;
+    padding: 2px 4px;
+    border: 0;
+    border-radius: 4px;
+    background: none;
+    color: inherit;
+    font: inherit;
+    text-decoration: none;
+    cursor: pointer;
+  }
+  .bc-link:hover {
+    color: var(--bc-fg);
+    text-decoration: underline;
+    text-underline-offset: 3px;
+  }
+  .bc-link:focus-visible,
+  .bc-ellipsis:focus-visible {
+    outline: 2px solid var(--bc-focus);
+    outline-offset: 1px;
+  }
+  .bc-current {
+    color: var(--bc-fg);
+    font-weight: 500;
+  }
+
+  .bc-text {
+    max-width: var(--bc-max-label);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  .bc-icon {
+    display: inline-flex;
+    flex: none;
+  }
+  .bc-icon > svg {
+    width: 1.1em;
+    height: 1.1em;
+  }
+
+  .bc-separator {
+    display: inline-flex;
+    flex: none;
+    opacity: 0.7;
+  }
+  /* A chevron points the reading direction. */
+  .bc-separator > svg:dir(rtl) {
+    transform: scaleX(-1);
+  }
+
+  .bc-ellipsis {
+    display: inline-grid;
+    place-items: center;
+    min-width: 24px;
+    height: 22px;
+    padding: 0 4px;
+    border: 0;
+    border-radius: 4px;
+    background: transparent;
+    color: inherit;
+    font: inherit;
+    letter-spacing: 1px;
+    cursor: pointer;
+  }
+  .bc-ellipsis:hover {
+    background: var(--bc-hover);
+    color: var(--bc-fg);
+  }
+}

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

@@ -0,0 +1,32 @@
+# Button
+
+A button for React 19 with variants, sizes, icons and a loading state that
+manages itself, styled to match the rest of the library. No runtime
+dependencies besides React.
+
+```ts
+import { Button } from "@/components/button";
+import "@/components/button/styles.css";
+```
+
+```tsx
+<Button onClick={async () => await save()}>Save</Button>          {/* spinner while the promise runs */}
+<Button type="submit">Create</Button>                            {/* spinner while the form's Server Action runs */}
+<Button variant="outline" leading={<PlusIcon />}>New invoice</Button>
+<Button variant="ghost" icon={<TrashIcon />} aria-label="Delete" />
+<Button render={(props) => <Link href="/billing" {...props} />}>Billing</Button>
+```
+
+| Prop | Default | Description |
+| --- | --- | --- |
+| `variant` | `primary` | `primary`, `secondary`, `outline`, `ghost`, `danger`, `link`. |
+| `size` | `md` | `sm` 30 · `md` 36 · `lg` 44 px. |
+| `type` | `button` | Not `submit`, so buttons inside forms don't submit by accident. |
+| `loading` / `loadingText` | `false` / — | Busy state; stays focusable and keeps its width. |
+| `leading`, `trailing`, `icon` | — | Icons; `icon` alone makes an icon-only button (add `aria-label`). |
+| `fullWidth` | `false` | Fill the container. |
+| `onClick` | — | Return a promise to show loading until it settles. |
+| `render` | — | Render another element (e.g. a router link) with the button's look. |
+| `className`, `classNames`, `localeText`, `ref` | — | Slots: `root`, `content`, `spinner`, `icon`. |
+
+Every other `<button>` attribute passes through.

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

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import { buttonState, isPromiseLike } from "../core/state";
+
+describe("button state", () => {
+  it("is active by default", () => {
+    expect(buttonState({})).toEqual({ busy: false, inactive: false, nativeDisabled: false });
+  });
+
+  it("stays focusable while busy", () => {
+    expect(buttonState({ loading: true })).toEqual({ busy: true, inactive: true, nativeDisabled: false });
+    expect(buttonState({ pending: true })).toEqual({ busy: true, inactive: true, nativeDisabled: false });
+  });
+
+  it("uses native disabled, and shows no spinner, when disabled", () => {
+    expect(buttonState({ disabled: true, loading: true })).toEqual({
+      busy: false,
+      inactive: true,
+      nativeDisabled: true,
+    });
+  });
+});
+
+describe("promise detection", () => {
+  it("recognizes promises and thenables only", () => {
+    expect(isPromiseLike(Promise.resolve())).toBe(true);
+    expect(isPromiseLike({ then: () => {} })).toBe(true);
+    expect(isPromiseLike(undefined)).toBe(false);
+    expect(isPromiseLike({ then: 1 })).toBe(false);
+    expect(isPromiseLike(() => {})).toBe(false);
+  });
+});

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

@@ -0,0 +1,3 @@
+// Framework-free: the button's state rules.
+export { buttonState, isPromiseLike } from "./state";
+export type * from "./types";

package/source/beta-components/button/core/state.ts

@@ -0,0 +1,16 @@
+import type { ButtonState, ButtonStateInput } from "./types";
+
+/** An async click handler's return value: anything with a `then`. */
+export function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { then?: unknown }).then === "function"
+  );
+}
+
+/** How a button behaves for its combination of flags. */
+export function buttonState({ disabled = false, loading = false, pending = false }: ButtonStateInput): ButtonState {
+  const busy = !disabled && (loading || pending);
+  return { busy, inactive: disabled || busy, nativeDisabled: disabled };
+}

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

@@ -0,0 +1,28 @@
+export type ButtonVariant = "primary" | "secondary" | "outline" | "ghost" | "danger" | "link";
+
+export type ButtonSize = "sm" | "md" | "lg";
+
+export interface ButtonStateInput {
+  disabled?: boolean;
+  /** Set by you. */
+  loading?: boolean;
+  /** Set by the button itself: an async `onClick` or a pending form action. */
+  pending?: boolean;
+}
+
+export interface ButtonState {
+  /** Show the spinner and `aria-busy`. */
+  busy: boolean;
+  /** Ignore activation. */
+  inactive: boolean;
+  /**
+   * Use the native `disabled` attribute. A busy button stays focusable and uses
+   * `aria-disabled` instead, so keyboard focus isn't thrown away mid-action.
+   */
+  nativeDisabled: boolean;
+}
+
+export interface ButtonLocaleText {
+  /** Announced while the button is busy. */
+  loading: string;
+}

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

@@ -0,0 +1,5 @@
+export { Button } from "./react/Button";
+export type { ButtonProps } from "./react/Button";
+export { defaultButtonText } from "./react/locale";
+export type { ButtonRenderProps, ButtonSlot } from "./react/props";
+export * from "./core";

package/source/beta-components/button/react/Button.tsx

@@ -0,0 +1,173 @@
+"use client";
+
+import {
+  useMemo,
+  useState,
+  type ButtonHTMLAttributes,
+  type MouseEvent,
+  type ReactElement,
+  type ReactNode,
+  type Ref,
+} from "react";
+import { useFormStatus } from "react-dom";
+import { buttonState, isPromiseLike } from "../core/state";
+import type { ButtonLocaleText, ButtonSize, ButtonVariant } from "../core/types";
+import { defaultButtonText } from "./locale";
+import { cx, type ButtonRenderProps, type ButtonSlot } from "./props";
+
+export interface ButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onClick"> {
+  /** Default `primary`. */
+  variant?: ButtonVariant;
+  /** Default `md`. */
+  size?: ButtonSize;
+  /** Show a spinner and ignore clicks, while keeping focus and the button's width. */
+  loading?: boolean;
+  /** Text shown next to the spinner while busy, instead of keeping the label. */
+  loadingText?: ReactNode;
+  /** Icon before the label. */
+  leading?: ReactNode;
+  /** Icon after the label. */
+  trailing?: ReactNode;
+  /** An icon-only button. Give it an `aria-label`. */
+  icon?: ReactNode;
+  fullWidth?: boolean;
+  /** Return a promise to show the loading state until it settles. */
+  onClick?(event: MouseEvent<HTMLElement>): unknown;
+  /**
+   * Render another element with the button's look and behavior, e.g. a router
+   * link: `render={(props) => <Link href="/billing" {...props} />}`.
+   */
+  render?(props: ButtonRenderProps): ReactElement;
+  classNames?: Partial<Record<ButtonSlot, string>>;
+  localeText?: Partial<ButtonLocaleText>;
+  ref?: Ref<HTMLButtonElement>;
+}
+
+/** Attributes that only mean something on a `<button>`, left off a `render`ed element. */
+const BUTTON_ONLY = new Set(["form", "formAction", "formEncType", "formMethod", "formNoValidate", "formTarget", "name", "value", "type"]);
+
+const Spinner = () => (
+  <svg className="bt-spinner-ring" viewBox="0 0 24 24" aria-hidden="true" focusable="false">
+    <circle cx="12" cy="12" r="9" pathLength={100} />
+  </svg>
+);
+
+/**
+ * A button with variants, sizes, icons and a loading state. An async `onClick`
+ * shows progress by itself, and a submit button shows progress while its form's
+ * Server Action runs.
+ */
+export function Button(props: ButtonProps) {
+  const {
+    ref,
+    variant = "primary",
+    size = "md",
+    type = "button",
+    loading = false,
+    loadingText,
+    leading,
+    trailing,
+    icon,
+    fullWidth = false,
+    disabled = false,
+    onClick,
+    render,
+    className,
+    classNames,
+    localeText,
+    children,
+    ...rest
+  } = props;
+
+  const text = useMemo(() => ({ ...defaultButtonText, ...localeText }), [localeText]);
+  // Pending while the surrounding <form action={…}> is submitting (React 19).
+  const { pending: formPending } = useFormStatus();
+  const [clickPending, setClickPending] = useState(false);
+  const state = buttonState({
+    disabled,
+    loading,
+    pending: clickPending || (type === "submit" && formPending),
+  });
+  const iconOnly = icon !== undefined && (children === undefined || children === null);
+
+  const handleClick = (event: MouseEvent<HTMLElement>) => {
+    // aria-disabled doesn't stop a click or a form submit on its own.
+    if (state.inactive) {
+      event.preventDefault();
+      return;
+    }
+    const result = onClick?.(event);
+    if (!isPromiseLike(result)) return;
+    setClickPending(true);
+    const done = () => setClickPending(false);
+    Promise.resolve(result).then(done, (error: unknown) => {
+      done();
+      // Keep the failure visible instead of swallowing it.
+      throw error;
+    });
+  };
+
+  const content = (
+    <>
+      <span
+        className={cx("bt-content", classNames?.content)}
+        // Hidden, not removed, so the button keeps its width while busy.
+        data-hidden={state.busy ? "" : undefined}
+      >
+        {leading && (
+          <span className={cx("bt-icon", classNames?.icon)} aria-hidden="true">
+            {leading}
+          </span>
+        )}
+        {iconOnly ? <span className={cx("bt-icon", classNames?.icon)}>{icon}</span> : children}
+        {trailing && (
+          <span className={cx("bt-icon", classNames?.icon)} aria-hidden="true">
+            {trailing}
+          </span>
+        )}
+      </span>
+      {state.busy && (
+        <span className={cx("bt-spinner", classNames?.spinner)}>
+          <Spinner />
+          {loadingText ?? <span className="bt-sr-only">{text.loading}</span>}
+        </span>
+      )}
+    </>
+  );
+
+  const shared = {
+    className: cx("bt-root", classNames?.root, className),
+    "data-variant": variant,
+    "data-size": size,
+    "data-busy": state.busy ? ("" as const) : undefined,
+    "data-icon-only": iconOnly ? ("" as const) : undefined,
+    "data-full-width": fullWidth ? ("" as const) : undefined,
+    "data-loading-text": state.busy && loadingText ? "" : undefined,
+    "aria-busy": state.busy || undefined,
+  };
+
+  if (render) {
+    const attributes = Object.fromEntries(Object.entries(rest).filter(([key]) => !BUTTON_ONLY.has(key)));
+    return render({
+      ...attributes,
+      ...shared,
+      "aria-disabled": state.inactive || undefined,
+      onClick: handleClick,
+      children: content,
+    });
+  }
+
+  return (
+    <button
+      {...rest}
+      {...shared}
+      ref={ref}
+      type={type}
+      disabled={state.nativeDisabled}
+      aria-disabled={state.inactive && !state.nativeDisabled ? true : undefined}
+      onClick={handleClick}
+    >
+      {content}
+    </button>
+  );
+}

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

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

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

@@ -0,0 +1,23 @@
+import type { CSSProperties, MouseEvent, ReactNode } from "react";
+import type { ButtonSize, ButtonVariant } from "../core/types";
+
+export type ButtonSlot = "root" | "content" | "spinner" | "icon";
+
+/** Handed to `render`, to put the button's look and behavior on another element. */
+export interface ButtonRenderProps {
+  className: string;
+  style?: CSSProperties;
+  children: ReactNode;
+  onClick(event: MouseEvent<HTMLElement>): void;
+  "data-variant": ButtonVariant;
+  "data-size": ButtonSize;
+  "data-busy"?: "";
+  "data-icon-only"?: "";
+  "data-full-width"?: "";
+  "aria-busy"?: boolean;
+  "aria-disabled"?: boolean;
+  [attribute: string]: unknown;
+}
+
+// Shared with every other component, so class handling cannot drift.
+export { cx } from "../../shared/core/cx";