gbs-add-block 1.2.19 → 2.0.0

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

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

@@ -0,0 +1,202 @@
+/*
+ * Progress and CircularProgress styles.
+ *
+ * The bar is drawn from --pr-fraction (0 to 1) rather than a width in percent,
+ * so the same number drives the bar, the ring and any transition. 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 {
+  .pr-root,
+  .pr-circle {
+    --pr-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
+    --pr-muted: var(--gbs-muted, var(--dg-muted, light-dark(#71717a, #a1a1aa)));
+    --pr-track: var(--gbs-subtle, light-dark(#e4e4e7, #27272a));
+    --pr-accent: var(--gbs-accent, var(--dg-accent, light-dark(#2563eb, #60a5fa)));
+    --pr-success: var(--gbs-success, light-dark(#15803d, #4ade80));
+    --pr-warning: var(--gbs-warning, light-dark(#b45309, #fbbf24));
+    --pr-danger: var(--gbs-danger, var(--dg-danger, light-dark(#dc2626, #f87171)));
+    --pr-font-size: var(--gbs-font-size, var(--dg-font-size, 13px));
+    --pr-height: 8px;
+    --pr-duration: 240ms;
+    --pr-bar: var(--pr-accent);
+
+    color-scheme: inherit;
+    font-size: var(--pr-font-size);
+    color: var(--pr-fg);
+  }
+
+  :where(.dark, [data-theme="dark"]) :is(.pr-root, .pr-circle) {
+    color-scheme: dark;
+  }
+  :where(.light, [data-theme="light"]) :is(.pr-root, .pr-circle) {
+    color-scheme: light;
+  }
+
+  :where(.pr-root, .pr-circle) *,
+  :where(.pr-root, .pr-circle) *::before,
+  :where(.pr-root, .pr-circle) *::after {
+    box-sizing: border-box;
+  }
+
+  .pr-root[data-variant="success"],
+  .pr-circle[data-variant="success"] {
+    --pr-bar: var(--pr-success);
+  }
+  .pr-root[data-variant="warning"],
+  .pr-circle[data-variant="warning"] {
+    --pr-bar: var(--pr-warning);
+  }
+  .pr-root[data-variant="danger"],
+  .pr-circle[data-variant="danger"] {
+    --pr-bar: var(--pr-danger);
+  }
+
+  /* ------------------------------------------------------------------ bar */
+
+  .pr-root {
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
+    min-width: 0;
+  }
+  .pr-root[data-size="sm"] {
+    --pr-height: 4px;
+    --pr-font-size: 12px;
+  }
+  .pr-root[data-size="lg"] {
+    --pr-height: 12px;
+  }
+
+  .pr-header {
+    display: flex;
+    align-items: baseline;
+    justify-content: space-between;
+    gap: 12px;
+    min-width: 0;
+  }
+  .pr-label {
+    overflow: hidden;
+    font-weight: 500;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  .pr-value {
+    flex: none;
+    color: var(--pr-muted);
+    font-variant-numeric: tabular-nums;
+  }
+
+  .pr-track {
+    position: relative;
+    width: 100%;
+    height: var(--pr-height);
+    border-radius: 999px;
+    background: var(--pr-track);
+    overflow: hidden;
+  }
+
+  .pr-bar {
+    width: 100%;
+    height: 100%;
+    border-radius: inherit;
+    background: var(--pr-bar);
+    /* `scaleX` from the origin: the compositor handles it, so a bar that ticks
+       up every few milliseconds costs nothing in layout. */
+    transform-origin: left center;
+    scale: var(--pr-fraction, 0) 1;
+    transition: scale var(--pr-duration) ease;
+  }
+  .pr-root:dir(rtl) .pr-bar {
+    transform-origin: right center;
+  }
+
+  /* With no length to show, a short bar sweeps the track instead. */
+  .pr-root[data-indeterminate] .pr-bar {
+    width: 35%;
+    scale: 1 1;
+    animation: pr-sweep 1.3s ease-in-out infinite;
+  }
+  @keyframes pr-sweep {
+    from {
+      translate: -100%;
+    }
+    to {
+      translate: 300%;
+    }
+  }
+
+  /* ----------------------------------------------------------------- ring */
+
+  .pr-circle {
+    position: relative;
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    vertical-align: middle;
+  }
+  .pr-svg {
+    width: 100%;
+    height: 100%;
+    /* Zero is at three o'clock in SVG; a progress ring starts at the top. */
+    rotate: -90deg;
+  }
+  .pr-circle-track {
+    stroke: var(--pr-track);
+  }
+  .pr-circle-bar {
+    stroke: var(--pr-bar);
+    transition: stroke-dashoffset var(--pr-duration) ease;
+  }
+  .pr-circle[data-indeterminate] .pr-svg {
+    animation: pr-spin 1s linear infinite;
+  }
+  @keyframes pr-spin {
+    from {
+      rotate: -90deg;
+    }
+    to {
+      rotate: 270deg;
+    }
+  }
+
+  .pr-circle-label {
+    position: absolute;
+    font-size: calc(var(--pr-font-size) - 1px);
+    font-variant-numeric: tabular-nums;
+    font-weight: 600;
+    line-height: 1;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .pr-bar,
+    .pr-circle-bar {
+      transition: none;
+    }
+    /* Movement that repeats forever is what reduced motion is about, but a
+       stopped indeterminate bar would look broken — so it slows instead. */
+    .pr-root[data-indeterminate] .pr-bar {
+      animation-duration: 3s;
+    }
+    .pr-circle[data-indeterminate] .pr-svg {
+      animation-duration: 2.5s;
+    }
+  }
+
+  @media (forced-colors: active) {
+    .pr-track {
+      border: 1px solid CanvasText;
+    }
+    .pr-bar {
+      background: Highlight;
+    }
+    .pr-circle-bar {
+      stroke: Highlight;
+    }
+  }
+}