gbs-add-block 1.2.18 → 1.3.0

package/source/beta-components/number-input/styles.css

@@ -0,0 +1,231 @@
+/*
+ * NumberInput styles.
+ *
+ * The field is a text input, so it looks and sizes exactly like the Input
+ * component; the spinner is two buttons the stylesheet owns rather than the
+ * browser's, which cannot be styled. 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 {
+  .nm-root {
+    --nm-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
+    --nm-muted: var(--gbs-muted, var(--dg-muted, light-dark(#71717a, #a1a1aa)));
+    --nm-border: var(--gbs-border, var(--dg-border, light-dark(#e4e4e7, #27272a)));
+    --nm-input-bg: var(--gbs-input-bg, var(--dg-input-bg, light-dark(#ffffff, #121216)));
+    --nm-readonly-bg: var(--gbs-readonly-bg, light-dark(#fafafa, #0e0e12));
+    --nm-hover: var(--gbs-hover, var(--dg-hover, light-dark(#f4f4f5, #1f1f23)));
+    --nm-accent: var(--gbs-accent, var(--dg-accent, light-dark(#2563eb, #60a5fa)));
+    --nm-focus: var(--gbs-focus, var(--dg-focus, light-dark(#2563eb, #60a5fa)));
+    --nm-danger: var(--gbs-danger, var(--dg-danger, light-dark(#dc2626, #f87171)));
+    --nm-radius: var(--gbs-radius, var(--dg-radius, 8px));
+    --nm-font-size: var(--gbs-font-size, var(--dg-font-size, 13px));
+    --nm-height: 36px;
+    --nm-px: 10px;
+
+    color-scheme: inherit;
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    min-width: 0;
+    font-size: var(--nm-font-size);
+    line-height: 1.4;
+    color: var(--nm-fg);
+  }
+
+  :where(.dark, [data-theme="dark"]) .nm-root {
+    color-scheme: dark;
+  }
+  :where(.light, [data-theme="light"]) .nm-root {
+    color-scheme: light;
+  }
+
+  :where(.nm-root) *,
+  :where(.nm-root) *::before,
+  :where(.nm-root) *::after {
+    box-sizing: border-box;
+  }
+
+  .nm-root[data-size="sm"] {
+    --nm-height: 30px;
+    --nm-px: 8px;
+    --nm-font-size: 12px;
+  }
+  .nm-root[data-size="lg"] {
+    --nm-height: 44px;
+    --nm-px: 12px;
+    --nm-font-size: 14px;
+  }
+
+  .nm-label {
+    font-weight: 500;
+  }
+  .nm-label[data-required]::after {
+    content: " *";
+    color: var(--nm-danger);
+  }
+
+  /* -------------------------------------------------------------- control */
+
+  .nm-control {
+    display: flex;
+    align-items: stretch;
+    gap: 6px;
+    min-width: 0;
+    height: var(--nm-height);
+    padding-inline-start: var(--nm-px);
+    border: 1px solid var(--nm-border);
+    border-radius: var(--nm-radius);
+    background: var(--nm-input-bg);
+    transition:
+      border-color 120ms ease,
+      box-shadow 120ms ease;
+  }
+  .nm-control:hover:not([data-disabled]) {
+    border-color: color-mix(in oklab, var(--nm-border) 60%, var(--nm-fg));
+  }
+  .nm-control:has(.nm-input:focus-visible) {
+    border-color: var(--nm-focus);
+    box-shadow: 0 0 0 1px var(--nm-focus);
+  }
+  .nm-control[data-invalid] {
+    border-color: var(--nm-danger);
+  }
+  .nm-control[data-invalid]:has(.nm-input:focus-visible) {
+    box-shadow: 0 0 0 1px var(--nm-danger);
+  }
+  .nm-control[data-disabled] {
+    opacity: 0.6;
+    cursor: not-allowed;
+  }
+  .nm-control[data-readonly] {
+    background: var(--nm-readonly-bg);
+  }
+
+  .nm-input {
+    flex: 1 1 auto;
+    min-width: 0;
+    padding: 0;
+    padding-inline-end: var(--nm-px);
+    border: 0;
+    background: none;
+    color: inherit;
+    font: inherit;
+    /* Figures of the same width, so a column of amounts lines up and the
+       number does not jitter as it is typed. */
+    font-variant-numeric: tabular-nums;
+    outline: none;
+  }
+  .nm-input::placeholder {
+    color: var(--nm-muted);
+  }
+  .nm-input:disabled {
+    cursor: not-allowed;
+  }
+
+  .nm-adornment {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    color: var(--nm-muted);
+    white-space: nowrap;
+  }
+  .nm-adornment[data-side="trailing"] {
+    padding-inline-end: 2px;
+  }
+
+  .nm-icon-button {
+    display: inline-flex;
+    flex: none;
+    align-self: center;
+    align-items: center;
+    justify-content: center;
+    width: 20px;
+    height: 20px;
+    padding: 0;
+    border: 0;
+    border-radius: 4px;
+    background: none;
+    color: var(--nm-muted);
+    cursor: pointer;
+  }
+  .nm-icon-button:hover {
+    background: var(--nm-hover);
+    color: var(--nm-fg);
+  }
+
+  /* -------------------------------------------------------------- stepper */
+
+  .nm-stepper {
+    display: flex;
+    flex: none;
+    flex-direction: column;
+    width: 22px;
+    border-inline-start: 1px solid var(--nm-border);
+  }
+
+  .nm-step {
+    display: flex;
+    flex: 1 1 50%;
+    align-items: center;
+    justify-content: center;
+    min-height: 0;
+    padding: 0;
+    border: 0;
+    background: none;
+    color: var(--nm-muted);
+    cursor: pointer;
+    /* The buttons repeat while held, so the browser must not read the hold as
+       a scroll gesture or a text selection. */
+    touch-action: none;
+    user-select: none;
+  }
+  .nm-step:first-child {
+    border-start-end-radius: calc(var(--nm-radius) - 1px);
+    border-block-end: 1px solid var(--nm-border);
+  }
+  .nm-step:last-child {
+    border-end-end-radius: calc(var(--nm-radius) - 1px);
+  }
+  .nm-step:hover:not(:disabled) {
+    background: var(--nm-hover);
+    color: var(--nm-fg);
+  }
+  .nm-step:active:not(:disabled) {
+    background: color-mix(in oklab, var(--nm-hover) 70%, var(--nm-accent));
+  }
+  .nm-step:disabled {
+    opacity: 0.4;
+    cursor: not-allowed;
+  }
+
+  /* ----------------------------------------------------------------- text */
+
+  .nm-description {
+    color: var(--nm-muted);
+    text-wrap: pretty;
+  }
+  .nm-error {
+    color: var(--nm-danger);
+    text-wrap: pretty;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .nm-control {
+      transition: none;
+    }
+  }
+
+  @media (forced-colors: active) {
+    .nm-control {
+      border: 1px solid CanvasText;
+    }
+    .nm-stepper,
+    .nm-step:first-child {
+      border-color: CanvasText;
+    }
+  }
+}

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";

package/source/beta-components/progress/react/CircularProgress.tsx

@@ -0,0 +1,106 @@
+"use client";
+
+import { useId, useMemo, type CSSProperties, type ReactNode, type Ref } from "react";
+import { describeProgress } from "../core/progress";
+import type { ProgressLocaleText, ProgressVariant } from "../core/types";
+import { defaultProgressText } from "./locale";
+import { cx, type CircularProgressSlot } from "./props";
+
+export interface CircularProgressProps {
+  value?: number | null;
+  max?: number;
+  /** Diameter in pixels. Default 44. */
+  size?: number;
+  /** Ring thickness in pixels. Default 4. */
+  thickness?: number;
+  variant?: ProgressVariant;
+  /** Names the ring for assistive technology. */
+  label?: string;
+  /** Print the percentage in the middle, or your own node. */
+  showValue?: boolean;
+  children?: ReactNode;
+  className?: string;
+  classNames?: Partial<Record<CircularProgressSlot, string>>;
+  style?: CSSProperties;
+  localeText?: Partial<ProgressLocaleText>;
+  ref?: Ref<HTMLDivElement>;
+}
+
+/**
+ * The same progress as a ring, for a tile or a table cell where a bar would be
+ * too wide.
+ *
+ * The arc is one circle with a dashed stroke: the dash is the whole
+ * circumference, and the gap moves it — no arc paths, no trigonometry, and it
+ * scales with `size` without redrawing anything.
+ */
+export function CircularProgress(props: CircularProgressProps) {
+  const {
+    ref,
+    value = null,
+    max = 100,
+    size = 44,
+    thickness = 4,
+    variant = "accent",
+    label,
+    showValue = false,
+    children,
+    className,
+    classNames,
+    style,
+    localeText,
+  } = props;
+
+  const id = useId();
+  const text = useMemo(() => ({ ...defaultProgressText, ...localeText }), [localeText]);
+  const state = describeProgress(value, max);
+
+  const radius = (size - thickness) / 2;
+  const circumference = 2 * Math.PI * radius;
+  // An indeterminate ring shows a quarter arc that spins; a determinate one
+  // shows its fraction.
+  const filled = state.indeterminate ? 0.25 : state.fraction;
+
+  return (
+    <div
+      ref={ref}
+      className={cx("pr-circle", classNames?.root, className)}
+      style={{ ...style, width: size, height: size }}
+      data-variant={variant}
+      data-indeterminate={state.indeterminate || undefined}
+      role="progressbar"
+      aria-valuenow={state.indeterminate ? undefined : state.value ?? undefined}
+      aria-valuemin={state.indeterminate ? undefined : 0}
+      aria-valuemax={state.indeterminate ? undefined : max}
+      aria-valuetext={state.indeterminate ? undefined : text.valueText(state.percent)}
+      aria-label={label ?? text.label}
+    >
+      <svg className={cx("pr-svg", classNames?.svg)} viewBox={`0 0 ${size} ${size}`} aria-hidden="true">
+        <circle
+          className={cx("pr-circle-track", classNames?.track)}
+          cx={size / 2}
+          cy={size / 2}
+          r={radius}
+          fill="none"
+          strokeWidth={thickness}
+        />
+        <circle
+          className={cx("pr-circle-bar", classNames?.bar)}
+          cx={size / 2}
+          cy={size / 2}
+          r={radius}
+          fill="none"
+          strokeWidth={thickness}
+          strokeLinecap="round"
+          strokeDasharray={circumference}
+          strokeDashoffset={circumference * (1 - filled)}
+        />
+      </svg>
+      {(showValue || children) && (
+        <span className={cx("pr-circle-label", classNames?.label)} aria-hidden="true" id={`${id}-label`}>
+          {children ?? (state.indeterminate ? "" : `${state.percent}%`)}
+        </span>
+      )}
+    </div>
+  );
+}

package/source/beta-components/progress/react/Progress.tsx

@@ -0,0 +1,113 @@
+"use client";
+
+import {
+  useId,
+  useMemo,
+  type CSSProperties,
+  type HTMLAttributes,
+  type ReactNode,
+  type Ref,
+} from "react";
+import { describeProgress } from "../core/progress";
+import type { ProgressLocaleText, ProgressSize, ProgressVariant } from "../core/types";
+import { defaultProgressText } from "./locale";
+import { cx, type ProgressSlot } from "./props";
+
+export interface ProgressProps extends Omit<HTMLAttributes<HTMLDivElement>, "role"> {
+  /** How far along. `null` means the length is not known yet. */
+  value?: number | null;
+  /** What `value` is measured against. Default 100. */
+  max?: number;
+  /** Names the bar. Shown above it, and used as the accessible name. */
+  label?: ReactNode;
+  /** Show the percentage beside the label. */
+  showValue?: boolean;
+  /** Replace what is shown and read, e.g. "3.2 MB of 8 MB". */
+  valueText?: ReactNode;
+  /** Default `accent`. */
+  variant?: ProgressVariant;
+  /** Default `md`. */
+  size?: ProgressSize;
+  classNames?: Partial<Record<ProgressSlot, string>>;
+  localeText?: Partial<ProgressLocaleText>;
+  ref?: Ref<HTMLDivElement>;
+}
+
+/**
+ * A bar for something with a known end: an upload, an import, a quota.
+ *
+ * Use a **Spinner** when there is nothing to measure and nothing to say about
+ * how long it will take. A progress bar that spends its life indeterminate is
+ * a spinner drawn as a promise it cannot keep.
+ */
+export function Progress(props: ProgressProps) {
+  const {
+    ref,
+    value = null,
+    max = 100,
+    label,
+    showValue = false,
+    valueText,
+    variant = "accent",
+    size = "md",
+    className,
+    classNames,
+    style,
+    localeText,
+    id: idProp,
+    "aria-label": ariaLabel,
+    ...rest
+  } = props;
+
+  const reactId = useId();
+  const id = idProp ?? reactId;
+  const text = useMemo(() => ({ ...defaultProgressText, ...localeText }), [localeText]);
+  const state = describeProgress(value, max);
+  const shown = valueText ?? (state.indeterminate ? text.working : text.valueText(state.percent));
+
+  return (
+    <div
+      {...rest}
+      ref={ref}
+      id={id}
+      className={cx("pr-root", classNames?.root, className)}
+      style={style}
+      data-variant={variant}
+      data-size={size}
+      data-indeterminate={state.indeterminate || undefined}
+    >
+      {(label || showValue) && (
+        <div className={cx("pr-header", classNames?.header)}>
+          {label && (
+            <span id={`${id}-label`} className={cx("pr-label", classNames?.label)}>
+              {label}
+            </span>
+          )}
+          {showValue && <span className={cx("pr-value", classNames?.value)}>{shown}</span>}
+        </div>
+      )}
+
+      <div
+        className={cx("pr-track", classNames?.track)}
+        role="progressbar"
+        // No aria-valuenow at all while the length is unknown: that is what
+        // tells a screen reader to say "busy" rather than to read out a zero.
+        aria-valuenow={state.indeterminate ? undefined : state.value ?? undefined}
+        aria-valuemin={state.indeterminate ? undefined : 0}
+        aria-valuemax={state.indeterminate ? undefined : max}
+        aria-valuetext={state.indeterminate ? undefined : typeof shown === "string" ? shown : undefined}
+        // The visible label names the bar when there is one, so the name and
+        // what is on screen can never drift apart.
+        aria-labelledby={label ? `${id}-label` : undefined}
+        aria-label={label ? undefined : (ariaLabel ?? text.label)}
+      >
+        <div
+          className={cx("pr-bar", classNames?.bar)}
+          // Drawn from the unrounded fraction, so the bar does not reach the
+          // end while the last of the work is still going.
+          style={{ "--pr-fraction": state.fraction } as CSSProperties}
+        />
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,7 @@
+import type { ProgressLocaleText } from "../core/types";
+
+export const defaultProgressText: ProgressLocaleText = {
+  label: "Progress",
+  valueText: (percent: number) => `${percent}%`,
+  working: "Working\u2026",
+};

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

@@ -0,0 +1,6 @@
+export type ProgressSlot = "root" | "header" | "label" | "value" | "track" | "bar";
+
+export type CircularProgressSlot = "root" | "svg" | "track" | "bar" | "label";
+
+// Shared with every other component, so class handling cannot drift.
+export { cx } from "../../shared/core/cx";