gbs-add-block 1.2.18 → 1.3.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/number-input/README.md

@@ -0,0 +1,53 @@
+# NumberInput
+
+A numeric field for React 19 that reads and writes numbers the way the locale
+does, styled to match the Input component. No runtime dependencies besides
+React.
+
+```ts
+import { NumberInput } from "@/components/number-input";
+import "@/components/number-input/styles.css";
+```
+
+```tsx
+<NumberInput label="Quantity" min={1} max={99} value={qty} onValueChange={setQty} />
+
+<NumberInput label="Amount" format="currency" currency="USD" decimals={2} locale="en-US" />
+
+{/* 45% in the field is 0.45 in the value, as Intl and CSS both have it. */}
+<NumberInput label="Discount" format="percent" step={0.01} min={0} max={1} />
+```
+
+**Why not `<input type="number">`:** the wheel silently edits it while the page
+scrolls; an entry it considers invalid reports itself as the empty string, so
+"nothing" and "not a number yet" cannot be told apart and what was typed is
+gone; it understands one notation, so `1.234,56` is not a number to it; and its
+spin buttons cannot be styled. This field is a text input with
+`role="spinbutton"`, which has none of those problems and the same
+announcements.
+
+**Props:** `value` / `defaultValue` / `onValueChange` (`number | null`), `min`,
+`max`, `step`, `largeStep`, `snapToStep`, `decimals`, `locale`, `format`
+(`decimal` `currency` `percent`), `currency`, `useGrouping`, `clampBehavior`
+(`blur` `strict` `none`), `stepper`, `wheel`, `selectOnFocus`, `clearable`,
+`label`, `description`, `error`, `size`, `leading`, `trailing`, `disabled`,
+`readOnly`, `required`, `classNames` (`root` `label` `control` `input`
+`stepper` `description` `error`), `localeText`, `ref` (the `<input>`), and
+every `<input>` attribute.
+
+**Keyboard:** **↑** / **↓** step, **Page Up** / **Page Down** step by
+`largeStep`, **Home** / **End** jump to `min` / `max` where there is one, and
+**Escape** puts back the last committed number.
+
+The field shows a grouped, formatted number at rest and the plain number while
+it has focus, so separators never appear under the caret. An entry that cannot
+be read falls back to the last good value on blur rather than being discarded.
+
+`parseNumber`, `formatNumber`, `toEditText`, `localeParts`, `stepBy`,
+`snapToStep`, `clamp`, `round` and `decimalsOf` are exported from the
+framework-free `core` — the same parsing a server can reuse to accept what the
+field sends.
+
+**`wheel` is off by default.** Turning it on lets the wheel change a focused
+field, which is exactly the behaviour that makes `<input type="number">`
+dangerous in a long form.