@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/progress/passport.json

@@ -0,0 +1,270 @@
+{
+  "passportVersion": "1.0.0",
+  "identity": {
+    "component": "Progress",
+    "folder": "progress",
+    "exports": [
+      "CircularProgress",
+      "Progress"
+    ]
+  },
+  "source": {
+    "libraryVersion": "2.4.0",
+    "files": [
+      "core/index.ts",
+      "core/progress.ts",
+      "core/types.ts",
+      "index.ts",
+      "react/CircularProgress.tsx",
+      "react/Progress.tsx",
+      "react/locale.ts",
+      "react/props.ts"
+    ],
+    "sourceHash": "sha256:40c85cf81b5ca8cc4f3332db2839f669c189b257bb1e660b4f6b67ade3bb6409"
+  },
+  "props": [
+    {
+      "name": "aria-describedby",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "aria-labelledby",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "children",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "classNames",
+      "type": "other",
+      "typeText": "Partial<Record<ProgressSlot, string>> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "hidden",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "id",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "label",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "Names the bar. Shown above it, and used as the accessible name.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "localeText",
+      "type": "other",
+      "typeText": "Partial<ProgressLocaleText> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "max",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "default": 100,
+      "origin": "derived",
+      "description": "What `value` is measured against. Default 100.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "ref",
+      "type": "other",
+      "typeText": "Ref<HTMLDivElement> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "showValue",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived",
+      "description": "Show the percentage beside the label.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "size",
+      "type": "enum",
+      "values": [
+        "lg",
+        "md",
+        "sm"
+      ],
+      "typeText": "ProgressSize | undefined",
+      "required": false,
+      "default": "md",
+      "origin": "derived",
+      "description": "Default `md`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "style",
+      "type": "other",
+      "typeText": "CSSProperties | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "tabIndex",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "thickness",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "default": 4,
+      "origin": "derived",
+      "description": "Ring thickness in pixels. Default 4.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "title",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "value",
+      "type": "number",
+      "typeText": "number | null | undefined",
+      "required": false,
+      "default": null,
+      "origin": "derived",
+      "description": "How far along. `null` means the length is not known yet.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "valueText",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "Replace what is shown and read, e.g. \"3.2 MB of 8 MB\".",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "variant",
+      "type": "enum",
+      "values": [
+        "accent",
+        "danger",
+        "success",
+        "warning"
+      ],
+      "typeText": "ProgressVariant | undefined",
+      "required": false,
+      "default": "accent",
+      "origin": "derived",
+      "description": "Default `accent`.",
+      "descriptionOrigin": "jsdoc"
+    }
+  ],
+  "inherits": [
+    {
+      "from": "HTMLAttributes<HTMLDivElement>",
+      "omitted": [
+        "role"
+      ],
+      "passthrough": true
+    }
+  ],
+  "events": [],
+  "slots": [
+    "root",
+    "header",
+    "label",
+    "value",
+    "track",
+    "bar",
+    "svg"
+  ],
+  "states": [
+    {
+      "attr": "data-indeterminate"
+    },
+    {
+      "attr": "data-size",
+      "values": [
+        "lg",
+        "sm"
+      ]
+    },
+    {
+      "attr": "data-theme",
+      "values": [
+        "dark",
+        "light"
+      ]
+    },
+    {
+      "attr": "data-variant",
+      "values": [
+        "danger",
+        "success",
+        "warning"
+      ]
+    }
+  ],
+  "accessibility": {
+    "supplied": [],
+    "required": []
+  },
+  "composition": {},
+  "operations": {},
+  "intentDomains": [],
+  "safeMutations": {},
+  "examples": [],
+  "coverage": {
+    "propsTotal": 21,
+    "propsDescribed": 8,
+    "describedPct": 38,
+    "authoredSections": [
+      "accessibility"
+    ]
+  }
+}

package/source/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/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/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/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/components/progress/styles.css

@@ -0,0 +1,200 @@
+/*
+ * 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 are unlayered: they beat a
+ * framework reset on specificity, and lose to anything you pass through
+ * `className`. With Tailwind v4, import this file after the framework and
+ * inside its components layer - see the README.
+ */
+
+.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;
+  }
+}