gbs-add-block 1.2.19 → 2.0.0

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

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import { formatCount, showCount } from "../core/count";
+
+describe("formatCount", () => {
+  it("prints the number while it fits", () => {
+    expect(formatCount(0)).toEqual({ text: "0" });
+    expect(formatCount(99)).toEqual({ text: "99" });
+  });
+
+  it("caps it, and says aloud what the cap means", () => {
+    // "99+" read out as "ninety-nine plus" is a guess at a number.
+    expect(formatCount(100)).toEqual({ text: "99+", spoken: "more than 99" });
+    expect(formatCount(4821, 999)).toEqual({ text: "999+", spoken: "more than 999" });
+  });
+
+  it("takes a formatter, for grouped or localized numbers", () => {
+    const format = new Intl.NumberFormat("de-DE").format;
+    expect(formatCount(1234, 9999, format).text).toBe("1.234");
+    expect(formatCount(20000, 9999, format)).toEqual({
+      text: "9.999+",
+      spoken: "more than 9.999",
+    });
+  });
+
+  it("drops the fraction of a number that should not have one", () => {
+    expect(formatCount(3.7).text).toBe("3");
+  });
+
+  it("has nothing to print for a number that is not one", () => {
+    expect(formatCount(Number.NaN).text).toBe("");
+    expect(formatCount(Number.POSITIVE_INFINITY).text).toBe("");
+  });
+});
+
+describe("showCount", () => {
+  it("leaves a zero off the page unless it is asked for", () => {
+    expect(showCount(0)).toBe(false);
+    expect(showCount(0, true)).toBe(true);
+    expect(showCount(1)).toBe(true);
+  });
+
+  it("never shows a negative or a non-number", () => {
+    expect(showCount(-1)).toBe(false);
+    expect(showCount(Number.NaN, true)).toBe(false);
+  });
+});

package/source/beta-components/badge/core/count.ts

@@ -0,0 +1,37 @@
+/**
+ * The label a counter shows, and the one a screen reader hears.
+ *
+ * A badge is small, so a number that keeps growing has to stop somewhere —
+ * but "99+" read aloud as "ninety-nine plus" is a guess, not a count, which is
+ * why the two strings are computed together and the spoken one says what it
+ * means.
+ */
+export interface CountLabel {
+  /** What is printed in the badge. */
+  text: string;
+  /** What assistive technology reads instead, when the two differ. */
+  spoken?: string;
+}
+
+export function formatCount(
+  count: number,
+  max = 99,
+  format?: (value: number) => string,
+): CountLabel {
+  const show = (value: number) => (format ? format(value) : String(value));
+  if (!Number.isFinite(count)) return { text: "" };
+  const whole = Math.trunc(count);
+  if (whole <= max) return { text: show(whole) };
+  return { text: `${show(max)}+`, spoken: `more than ${show(max)}` };
+}
+
+/**
+ * Whether a counter should be on the page at all.
+ *
+ * Zero is the interesting case: a badge reading "0" is noise on a page and a
+ * spurious announcement in a screen reader, so it is left off unless the caller
+ * asks for it — but a caller sometimes does, when the number sits in a table of
+ * numbers and a gap would read as missing data.
+ */
+export const showCount = (count: number, showZero = false): boolean =>
+  Number.isFinite(count) && (count > 0 || (showZero && count === 0));

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

@@ -0,0 +1,2 @@
+export { formatCount, showCount, type CountLabel } from "./count";
+export type * from "./types";

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

@@ -0,0 +1,11 @@
+export type BadgeVariant = "neutral" | "accent" | "success" | "warning" | "danger" | "info";
+
+/** `soft` is a tint, `solid` a filled block, `outline` a border only. */
+export type BadgeAppearance = "soft" | "solid" | "outline";
+
+export type BadgeSize = "sm" | "md";
+
+export interface BadgeLocaleText {
+  /** The remove button on a Tag. `label` is the tag's own text. */
+  remove(label: string): string;
+}

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

@@ -0,0 +1,7 @@
+export { Badge } from "./react/Badge";
+export type { BadgeProps } from "./react/Badge";
+export { Tag } from "./react/Tag";
+export type { TagProps } from "./react/Tag";
+export { defaultBadgeText } from "./react/locale";
+export type { BadgeSlot, TagSlot } from "./react/props";
+export * from "./core";

package/source/beta-components/badge/react/Badge.tsx

@@ -0,0 +1,89 @@
+"use client";
+
+import type { HTMLAttributes, ReactNode, Ref } from "react";
+import { formatCount, showCount } from "../core/count";
+import type { BadgeAppearance, BadgeSize, BadgeVariant } from "../core/types";
+import { cx, type BadgeSlot } from "./props";
+
+export interface BadgeProps extends Omit<HTMLAttributes<HTMLSpanElement>, "children"> {
+  children?: ReactNode;
+  /** Default `neutral`. */
+  variant?: BadgeVariant;
+  /** Default `soft`. */
+  appearance?: BadgeAppearance;
+  /** Default `md`. */
+  size?: BadgeSize;
+  /** A number instead of children. Above `max` it reads "99+". */
+  count?: number;
+  /** Where the count stops. Default 99. */
+  max?: number;
+  /** Show a count of zero. Default false: an empty counter is noise. */
+  showZero?: boolean;
+  /** Format the number, e.g. with `Intl.NumberFormat`. */
+  formatValue?(value: number): string;
+  /** A small filled circle before the label, for a status. */
+  dot?: boolean;
+  icon?: ReactNode;
+  classNames?: Partial<Record<BadgeSlot, string>>;
+  ref?: Ref<HTMLSpanElement>;
+}
+
+/**
+ * A short, static label: a status, a category, a count.
+ *
+ * It is text, not a control — nothing here is clickable or removable. Use
+ * **Tag** for something the user can take off, and a **Button** for something
+ * they can press.
+ */
+export function Badge(props: BadgeProps) {
+  const {
+    ref,
+    children,
+    variant = "neutral",
+    appearance = "soft",
+    size = "md",
+    count,
+    max = 99,
+    showZero = false,
+    formatValue,
+    dot = false,
+    icon,
+    className,
+    classNames,
+    ...rest
+  } = props;
+
+  const counted = count !== undefined;
+  if (counted && !showCount(count, showZero)) return null;
+  const label = counted ? formatCount(count, max, formatValue) : null;
+
+  return (
+    <span
+      {...rest}
+      ref={ref}
+      className={cx("bd-root", classNames?.root, className)}
+      data-variant={variant}
+      data-appearance={appearance}
+      data-size={size}
+      data-count={counted || undefined}
+    >
+      {dot && <span className={cx("bd-dot", classNames?.dot)} aria-hidden="true" />}
+      {icon && (
+        <span className={cx("bd-icon", classNames?.icon)} aria-hidden="true">
+          {icon}
+        </span>
+      )}
+      <span className={cx("bd-label", classNames?.label)}>
+        {label ? (
+          <>
+            <span aria-hidden={label.spoken ? "true" : undefined}>{label.text}</span>
+            {/* "99+" read aloud is a guess at a number; this says what it means. */}
+            {label.spoken && <span className="bd-sr-only">{label.spoken}</span>}
+          </>
+        ) : (
+          children
+        )}
+      </span>
+    </span>
+  );
+}

package/source/beta-components/badge/react/Tag.tsx

@@ -0,0 +1,82 @@
+"use client";
+
+import { useMemo, type HTMLAttributes, type ReactNode, type Ref } from "react";
+import { XIcon } from "../../shared/react/icons";
+import type { BadgeAppearance, BadgeLocaleText, BadgeSize, BadgeVariant } from "../core/types";
+import { defaultBadgeText } from "./locale";
+import { cx, type TagSlot } from "./props";
+
+export interface TagProps extends Omit<HTMLAttributes<HTMLSpanElement>, "onRemove"> {
+  children?: ReactNode;
+  variant?: BadgeVariant;
+  appearance?: BadgeAppearance;
+  size?: BadgeSize;
+  icon?: ReactNode;
+  /** Show a remove button. Without it a Tag is a Badge with a bit more padding. */
+  onRemove?(): void;
+  /** Names the remove button when the tag's own text is not a plain string. */
+  label?: string;
+  disabled?: boolean;
+  classNames?: Partial<Record<TagSlot, string>>;
+  localeText?: Partial<BadgeLocaleText>;
+  ref?: Ref<HTMLSpanElement>;
+}
+
+/**
+ * A chip the user can take off: a filter, a recipient, a selected value.
+ *
+ * The remove button carries the tag's own text in its name, so a screen reader
+ * says "Remove Berlin" rather than announcing a row of identical "Remove"
+ * buttons with no way to tell them apart.
+ */
+export function Tag(props: TagProps) {
+  const {
+    ref,
+    children,
+    variant = "neutral",
+    appearance = "soft",
+    size = "md",
+    icon,
+    onRemove,
+    label,
+    disabled = false,
+    className,
+    classNames,
+    localeText,
+    ...rest
+  } = props;
+
+  const text = useMemo(() => ({ ...defaultBadgeText, ...localeText }), [localeText]);
+  const name = label ?? (typeof children === "string" ? children : "");
+
+  return (
+    <span
+      {...rest}
+      ref={ref}
+      className={cx("bd-tag", classNames?.root, className)}
+      data-variant={variant}
+      data-appearance={appearance}
+      data-size={size}
+      data-disabled={disabled || undefined}
+    >
+      {icon && (
+        <span className={cx("bd-icon", classNames?.icon)} aria-hidden="true">
+          {icon}
+        </span>
+      )}
+      <span className={cx("bd-label", classNames?.label)}>{children}</span>
+      {onRemove && (
+        <button
+          type="button"
+          className={cx("bd-remove", classNames?.remove)}
+          aria-label={text.remove(name)}
+          title={text.remove(name)}
+          disabled={disabled}
+          onClick={onRemove}
+        >
+          <XIcon width={12} height={12} />
+        </button>
+      )}
+    </span>
+  );
+}

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

@@ -0,0 +1,5 @@
+import type { BadgeLocaleText } from "../core/types";
+
+export const defaultBadgeText: BadgeLocaleText = {
+  remove: (label: string) => `Remove ${label}`,
+};

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

@@ -0,0 +1,6 @@
+export type BadgeSlot = "root" | "dot" | "icon" | "label";
+
+export type TagSlot = "root" | "icon" | "label" | "remove";
+
+// Shared with every other component, so class handling cannot drift.
+export { cx } from "../../shared/core/cx";

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

@@ -0,0 +1,204 @@
+/*
+ * Badge and Tag styles.
+ *
+ * One tinted pill in six variants and three appearances; the variant only ever
+ * sets --bd-accent, so adding one is a single rule. Tokens read the shared
+ * --gbs-* variables when they are set on an ancestor (set them on :root to
+ * theme every component at once). Rules live in the `components` layer, so
+ * utility classes passed through `className` / `classNames` override them.
+ */
+@layer theme, base, components, utilities;
+
+@layer components {
+  .bd-root,
+  .bd-tag {
+    --bd-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
+    --bd-muted: var(--gbs-muted, var(--dg-muted, light-dark(#71717a, #a1a1aa)));
+    --bd-bg: var(--gbs-bg, var(--dg-bg, light-dark(#ffffff, #0b0b0e)));
+    --bd-border: var(--gbs-border, var(--dg-border, light-dark(#e4e4e7, #27272a)));
+    --bd-on-accent: var(--gbs-accent-fg, var(--dg-accent-fg, light-dark(#ffffff, #0b1220)));
+    --bd-focus: var(--gbs-focus, var(--dg-focus, light-dark(#2563eb, #60a5fa)));
+    --bd-accent-color: var(--gbs-accent, var(--dg-accent, light-dark(#2563eb, #60a5fa)));
+    --bd-success: var(--gbs-success, light-dark(#15803d, #4ade80));
+    --bd-warning: var(--gbs-warning, light-dark(#b45309, #fbbf24));
+    --bd-danger: var(--gbs-danger, var(--dg-danger, light-dark(#dc2626, #f87171)));
+    --bd-info: var(--gbs-info, var(--bd-accent-color));
+    --bd-font-size: calc(var(--gbs-font-size, var(--dg-font-size, 13px)) - 1px);
+    --bd-radius: 999px;
+    --bd-height: 20px;
+    --bd-px: 8px;
+    /* Neutral is the text colour rather than a hue, so it reads as "no state". */
+    --bd-accent: var(--bd-fg);
+
+    color-scheme: inherit;
+    display: inline-flex;
+    align-items: center;
+    gap: 4px;
+    max-width: 100%;
+    height: var(--bd-height);
+    padding: 0 var(--bd-px);
+    border: 1px solid transparent;
+    border-radius: var(--bd-radius);
+    font-size: var(--bd-font-size);
+    font-weight: 500;
+    line-height: 1;
+    white-space: nowrap;
+    vertical-align: middle;
+  }
+
+  :where(.dark, [data-theme="dark"]) :is(.bd-root, .bd-tag) {
+    color-scheme: dark;
+  }
+  :where(.light, [data-theme="light"]) :is(.bd-root, .bd-tag) {
+    color-scheme: light;
+  }
+
+  :where(.bd-root, .bd-tag) *,
+  :where(.bd-root, .bd-tag) *::before,
+  :where(.bd-root, .bd-tag) *::after {
+    box-sizing: border-box;
+  }
+
+  .bd-root[data-variant="accent"],
+  .bd-tag[data-variant="accent"] {
+    --bd-accent: var(--bd-accent-color);
+  }
+  .bd-root[data-variant="success"],
+  .bd-tag[data-variant="success"] {
+    --bd-accent: var(--bd-success);
+  }
+  .bd-root[data-variant="warning"],
+  .bd-tag[data-variant="warning"] {
+    --bd-accent: var(--bd-warning);
+  }
+  .bd-root[data-variant="danger"],
+  .bd-tag[data-variant="danger"] {
+    --bd-accent: var(--bd-danger);
+  }
+  .bd-root[data-variant="info"],
+  .bd-tag[data-variant="info"] {
+    --bd-accent: var(--bd-info);
+  }
+
+  /* --------------------------------------------------------- appearances */
+
+  .bd-root[data-appearance="soft"],
+  .bd-tag[data-appearance="soft"] {
+    background: color-mix(in oklab, var(--bd-accent) 12%, var(--bd-bg));
+    color: color-mix(in oklab, var(--bd-accent) 85%, var(--bd-fg));
+  }
+  .bd-root[data-appearance="solid"],
+  .bd-tag[data-appearance="solid"] {
+    background: var(--bd-accent);
+    color: var(--bd-on-accent);
+  }
+  /* Neutral solid would be black on near-black text; invert it instead. */
+  .bd-root[data-variant="neutral"][data-appearance="solid"],
+  .bd-tag[data-variant="neutral"][data-appearance="solid"] {
+    background: var(--bd-fg);
+    color: var(--bd-bg);
+  }
+  .bd-root[data-appearance="outline"],
+  .bd-tag[data-appearance="outline"] {
+    border-color: color-mix(in oklab, var(--bd-accent) 40%, var(--bd-border));
+    color: color-mix(in oklab, var(--bd-accent) 85%, var(--bd-fg));
+  }
+
+  .bd-root[data-size="sm"],
+  .bd-tag[data-size="sm"] {
+    --bd-height: 17px;
+    --bd-px: 6px;
+    --bd-font-size: 11px;
+  }
+
+  /* A counter is a circle until it needs to be a pill. */
+  .bd-root[data-count] {
+    justify-content: center;
+    min-width: var(--bd-height);
+    padding: 0 5px;
+    font-variant-numeric: tabular-nums;
+  }
+
+  .bd-dot {
+    width: 6px;
+    height: 6px;
+    border-radius: 50%;
+    background: currentColor;
+  }
+  .bd-icon {
+    display: inline-flex;
+    flex: none;
+  }
+  .bd-icon > svg {
+    width: 12px;
+    height: 12px;
+  }
+  .bd-label {
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+
+  /* ------------------------------------------------------------------ tag */
+
+  .bd-tag {
+    --bd-px: 8px;
+    padding-inline-end: 4px;
+  }
+  .bd-tag:not(:has(.bd-remove)) {
+    padding-inline-end: var(--bd-px);
+  }
+
+  .bd-remove {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    width: 16px;
+    height: 16px;
+    padding: 0;
+    border: 0;
+    border-radius: 50%;
+    background: none;
+    color: inherit;
+    opacity: 0.7;
+    cursor: pointer;
+  }
+  .bd-remove:hover:not(:disabled) {
+    background: color-mix(in oklab, currentColor 18%, transparent);
+    opacity: 1;
+  }
+  .bd-remove:focus-visible {
+    outline: 2px solid var(--bd-focus);
+    outline-offset: 1px;
+  }
+  .bd-remove:disabled {
+    cursor: not-allowed;
+  }
+  .bd-tag[data-disabled] {
+    opacity: 0.6;
+  }
+
+  .bd-sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    margin: -1px;
+    padding: 0;
+    border: 0;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+
+  @media (forced-colors: active) {
+    .bd-root,
+    .bd-tag {
+      border-color: CanvasText;
+    }
+    .bd-root[data-appearance="solid"],
+    .bd-tag[data-appearance="solid"] {
+      background: Highlight;
+      color: HighlightText;
+    }
+  }
+}

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

@@ -0,0 +1,38 @@
+# Progress and CircularProgress
+
+A bar, or a ring, for something with a known end: an upload, an import, a
+quota. For React 19, styled to match the rest of the library. No runtime
+dependencies besides React.
+
+```ts
+import { CircularProgress, Progress } from "@/components/progress";
+import "@/components/progress/styles.css";
+```
+
+```tsx
+<Progress label="Uploading report.pdf" value={62} showValue />
+<Progress value={null} label="Preparing export" />            {/* length unknown */}
+<Progress value={92} max={100} variant="warning" label="Storage" size="sm" />
+
+<CircularProgress value={62} size={56} showValue />
+```
+
+**Progress:** `value` (`number | null`), `max`, `label`, `showValue`,
+`valueText`, `variant` (`accent` `success` `warning` `danger`), `size` (`sm`
+`md` `lg`), `classNames` (`root` `header` `label` `value` `track` `bar`),
+`localeText`, `ref`, and every `<div>` attribute.
+
+**CircularProgress:** the same value props, plus `size` (pixels), `thickness`,
+`showValue` or `children` for the middle.
+
+`value={null}` means the length is not known yet, which is a different thing
+from zero: the bar sweeps, and `aria-valuenow` is left off entirely, which is
+what makes a screen reader say "busy" instead of reading out a zero.
+
+Use a **Spinner** when there is nothing to measure at all. A progress bar that
+spends its life indeterminate is a spinner drawn as a promise it cannot keep.
+
+`describeProgress` and `stepFraction` are exported from the framework-free
+`core`. `describeProgress` is where a `max` of zero stops being a division by
+zero, and where the drawn fraction stays unrounded so a 99.6% bar does not
+reach the end early.

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

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import { describeProgress, stepFraction } from "../core/progress";
+
+describe("describeProgress", () => {
+  it("measures a value against its max", () => {
+    expect(describeProgress(25)).toMatchObject({ fraction: 0.25, percent: 25, value: 25 });
+    expect(describeProgress(3, 8)).toMatchObject({ fraction: 0.375, percent: 38 });
+  });
+
+  it("treats no value as unknown, not as zero", () => {
+    // The difference decides whether a screen reader says "busy" or "0 percent".
+    for (const value of [null, undefined, Number.NaN]) {
+      expect(describeProgress(value)).toEqual({
+        indeterminate: true,
+        value: null,
+        fraction: 0,
+        percent: 0,
+      });
+    }
+  });
+
+  it("clamps into range rather than drawing past the end", () => {
+    expect(describeProgress(140).percent).toBe(100);
+    expect(describeProgress(-20).percent).toBe(0);
+  });
+
+  it("survives a task with nothing in it", () => {
+    // 0 of 0 files: without the guard this is NaN% and an empty bar drawn at
+    // Infinity.
+    const state = describeProgress(0, 0);
+    expect(state.fraction).toBe(0);
+    expect(Number.isNaN(state.percent)).toBe(false);
+  });
+
+  it("keeps the drawn fraction unrounded", () => {
+    // 99.6% must not snap the bar to full while bytes are still moving.
+    const state = describeProgress(99.6);
+    expect(state.percent).toBe(100);
+    expect(state.fraction).toBeCloseTo(0.996);
+  });
+});
+
+describe("stepFraction", () => {
+  it("counts a step as done, not as started", () => {
+    // "Step 2 of 5" is two fifths finished.
+    expect(stepFraction(2, 5)).toBe(0.4);
+    expect(stepFraction(0, 5)).toBe(0);
+    expect(stepFraction(5, 5)).toBe(1);
+  });
+
+  it("stays inside the wizard", () => {
+    expect(stepFraction(9, 5)).toBe(1);
+    expect(stepFraction(-1, 5)).toBe(0);
+    expect(stepFraction(1, 0)).toBe(0);
+  });
+});

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

@@ -0,0 +1,2 @@
+export { describeProgress, stepFraction } from "./progress";
+export type * from "./types";

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

@@ -0,0 +1,40 @@
+import type { ProgressState } from "./types";
+
+/**
+ * What a progress bar knows about itself.
+ *
+ * Kept apart from the component because the two interesting cases are easy to
+ * get wrong and invisible when you do: a value of `null` is *unknown*, not
+ * zero, and a `max` of zero is a task with nothing in it, which must not become
+ * a division by zero shown as `NaN%`.
+ */
+export function describeProgress(
+  value: number | null | undefined,
+  max = 100,
+): ProgressState {
+  if (value === null || value === undefined || !Number.isFinite(value)) {
+    return { indeterminate: true, value: null, fraction: 0, percent: 0 };
+  }
+  const top = Number.isFinite(max) && max > 0 ? max : 0;
+  const clamped = Math.min(Math.max(value, 0), top || value);
+  const fraction = top === 0 ? 0 : clamped / top;
+  return {
+    indeterminate: false,
+    value: clamped,
+    fraction,
+    // Rounded for display only; the bar itself is drawn from `fraction`, so a
+    // 99.6% bar does not snap to full while the last bytes are still moving.
+    percent: Math.round(fraction * 100),
+  };
+}
+
+/**
+ * A step counter's fraction: "step 2 of 5" is 40%, not 20%.
+ *
+ * Off-by-one here is the classic wizard bug — the first step showing an empty
+ * bar, or the last showing one still short of full.
+ */
+export function stepFraction(step: number, total: number): number {
+  if (!Number.isFinite(step) || !Number.isFinite(total) || total <= 0) return 0;
+  return Math.min(Math.max(step, 0), total) / total;
+}

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

@@ -0,0 +1,23 @@
+export type ProgressVariant = "accent" | "success" | "warning" | "danger";
+
+export type ProgressSize = "sm" | "md" | "lg";
+
+export interface ProgressState {
+  /** The task is running but its length is unknown. */
+  indeterminate: boolean;
+  /** Clamped into range, or null when indeterminate. */
+  value: number | null;
+  /** 0 to 1, for drawing. */
+  fraction: number;
+  /** 0 to 100, rounded, for reading. */
+  percent: number;
+}
+
+export interface ProgressLocaleText {
+  /** The accessible name when none is given. */
+  label: string;
+  /** What a screen reader reads instead of the raw number. */
+  valueText(percent: number): string;
+  /** Announced while the length is unknown. */
+  working: string;
+}

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

@@ -0,0 +1,7 @@
+export { Progress } from "./react/Progress";
+export type { ProgressProps } from "./react/Progress";
+export { CircularProgress } from "./react/CircularProgress";
+export type { CircularProgressProps } from "./react/CircularProgress";
+export { defaultProgressText } from "./react/locale";
+export type { CircularProgressSlot, ProgressSlot } from "./react/props";
+export * from "./core";