@grampro/kit 0.0.0-stage → 2.4.1

package/source/components/spinner/README.md

@@ -0,0 +1,29 @@
+# Spinner
+
+A loading indicator for React 19, on its own or covering busy content, styled to
+match the rest of the library. No runtime dependencies besides React.
+
+```ts
+import { Spinner, useDelayedLoading } from "@/components/spinner";
+import "@/components/spinner/styles.css";
+```
+
+```tsx
+<Spinner />                                   {/* 24 px ring in the current text color */}
+<Spinner size="sm" showLabel label="Saving…" />
+<Spinner loading={isPending} delay={250} minDuration={600}>
+  <Chart />                                   {/* covered and inert while loading */}
+</Spinner>
+```
+
+| Prop | Default | Description |
+| --- | --- | --- |
+| `loading` | `true` | With children, covers them while true. |
+| `size` | `md` | `xs` 12 · `sm` 16 · `md` 24 · `lg` 32 · `xl` 48, or pixels. |
+| `variant` | `ring` | `ring` or `dots`. |
+| `label` / `showLabel` | "Loading" / `false` | Announced text; optionally shown. |
+| `delay` / `minDuration` | `0` / `0` | Wait before showing; stay at least this long once shown. |
+| `className`, `classNames`, `style`, `localeText` | — | Slots: `root`, `status`, `indicator`, `label`, `content`, `overlay`. |
+
+`useDelayedLoading(loading, { delay, minDuration })` applies the same timing to
+any loading UI. `stepVisibility` is the framework-free rule behind it.

package/source/components/spinner/core/index.ts

@@ -0,0 +1,3 @@
+// Framework-free: when a spinner shows, and how big it is.
+export { spinnerPixels, stepVisibility } from "./visibility";
+export type * from "./types";

package/source/components/spinner/core/types.ts

@@ -0,0 +1,28 @@
+export type SpinnerSize = "xs" | "sm" | "md" | "lg" | "xl";
+
+export type SpinnerVariant = "ring" | "dots";
+
+export interface VisibilityOptions {
+  /** Wait this long before showing, so fast work never flashes a spinner. Default 0. */
+  delay?: number;
+  /** Once shown, stay at least this long, so it doesn't blink off. Default 0. */
+  minDuration?: number;
+}
+
+export interface VisibilityMarks {
+  visible: boolean;
+  /** When `loading` last turned true, or null while not loading. */
+  loadingSince: number | null;
+  /** When the spinner last appeared, or null while hidden. */
+  visibleSince: number | null;
+}
+
+export interface VisibilityStep {
+  visible: boolean;
+  /** Milliseconds until the answer can change, or null when it won't on its own. */
+  recheckIn: number | null;
+}
+
+export interface SpinnerLocaleText {
+  loading: string;
+}

package/source/components/spinner/core/visibility.ts

@@ -0,0 +1,34 @@
+import type { SpinnerSize, VisibilityMarks, VisibilityOptions, VisibilityStep } from "./types";
+
+/**
+ * Whether a spinner should be on screen right now. A short `delay` hides work
+ * that finishes quickly; a `minDuration` keeps a spinner that did appear from
+ * vanishing a moment later. Both avoid the flicker of a spinner that blinks.
+ */
+export function stepVisibility(
+  loading: boolean,
+  marks: VisibilityMarks,
+  now: number,
+  options: VisibilityOptions = {},
+): VisibilityStep {
+  const delay = Math.max(0, options.delay ?? 0);
+  const minDuration = Math.max(0, options.minDuration ?? 0);
+
+  if (loading && !marks.visible) {
+    const waited = now - (marks.loadingSince ?? now);
+    return waited >= delay ? { visible: true, recheckIn: null } : { visible: false, recheckIn: delay - waited };
+  }
+  if (!loading && marks.visible) {
+    const shown = now - (marks.visibleSince ?? now);
+    return shown >= minDuration
+      ? { visible: false, recheckIn: null }
+      : { visible: true, recheckIn: minDuration - shown };
+  }
+  return { visible: marks.visible, recheckIn: null };
+}
+
+const SIZES: Record<SpinnerSize, number> = { xs: 12, sm: 16, md: 24, lg: 32, xl: 48 };
+
+/** Pixel size for a named size; numbers pass through. */
+export const spinnerPixels = (size: SpinnerSize | number = "md") =>
+  typeof size === "number" ? Math.max(1, size) : SIZES[size];

package/source/components/spinner/index.ts

@@ -0,0 +1,6 @@
+export { Spinner } from "./react/Spinner";
+export type { SpinnerProps } from "./react/Spinner";
+export { useDelayedLoading } from "./react/useDelayedLoading";
+export { defaultSpinnerText } from "./react/locale";
+export type { SpinnerSlot } from "./react/props";
+export * from "./core";

package/source/components/spinner/passport.json

@@ -0,0 +1,245 @@
+{
+  "passportVersion": "1.0.0",
+  "identity": {
+    "component": "Spinner",
+    "folder": "spinner",
+    "exports": [
+      "Spinner"
+    ]
+  },
+  "source": {
+    "libraryVersion": "2.4.1",
+    "files": [
+      "core/index.ts",
+      "core/types.ts",
+      "core/visibility.ts",
+      "index.ts",
+      "react/Spinner.tsx",
+      "react/locale.ts",
+      "react/props.ts",
+      "react/useDelayedLoading.ts"
+    ],
+    "sourceHash": "sha256:2b6b8fa25750f5a491b73f37711de1beed2b1bcf9e38e2cf1b1f419d763b6c2e"
+  },
+  "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",
+      "description": "Content to cover while loading. It becomes inert, so it can't be clicked or focused.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "classNames",
+      "type": "other",
+      "typeText": "Partial<Record<SpinnerSlot, string>> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "delay",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "default": 0,
+      "origin": "derived",
+      "description": "Milliseconds to wait before showing, so fast work doesn't flash. Default 0.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "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": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "What screen readers announce. Default \"Loading\".",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "loading",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": true,
+      "origin": "derived",
+      "description": "Default true. With `children`, the spinner covers them while this is true.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "localeText",
+      "type": "other",
+      "typeText": "Partial<SpinnerLocaleText> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "minDuration",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "default": 0,
+      "origin": "derived",
+      "description": "Once shown, stay at least this many milliseconds. Default 0.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "role",
+      "type": "other",
+      "typeText": "AriaRole | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "showLabel",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived",
+      "description": "Show the label next to the spinner.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "size",
+      "type": "other",
+      "typeText": "number | SpinnerSize | undefined",
+      "required": false,
+      "default": "md",
+      "origin": "derived",
+      "description": "Default `md` (24 px); a number is pixels.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "style",
+      "type": "other",
+      "typeText": "CSSProperties | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "tabIndex",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "title",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "variant",
+      "type": "enum",
+      "values": [
+        "dots",
+        "ring"
+      ],
+      "typeText": "SpinnerVariant | undefined",
+      "required": false,
+      "default": "ring",
+      "origin": "derived",
+      "description": "Default `ring`.",
+      "descriptionOrigin": "jsdoc"
+    }
+  ],
+  "inherits": [
+    {
+      "from": "HTMLAttributes<HTMLElement>",
+      "omitted": [
+        "children"
+      ],
+      "passthrough": true
+    }
+  ],
+  "events": [],
+  "slots": [
+    "root",
+    "status",
+    "indicator",
+    "label",
+    "content",
+    "overlay"
+  ],
+  "states": [
+    {
+      "attr": "data-loading"
+    },
+    {
+      "attr": "data-theme",
+      "values": [
+        "dark",
+        "light"
+      ]
+    },
+    {
+      "attr": "data-variant",
+      "values": [
+        "dots"
+      ]
+    }
+  ],
+  "accessibility": {
+    "supplied": [],
+    "required": []
+  },
+  "composition": {},
+  "operations": {},
+  "intentDomains": [],
+  "safeMutations": {},
+  "examples": [],
+  "coverage": {
+    "propsTotal": 20,
+    "propsDescribed": 8,
+    "describedPct": 40,
+    "authoredSections": [
+      "accessibility"
+    ]
+  }
+}

package/source/components/spinner/react/Spinner.tsx

@@ -0,0 +1,96 @@
+"use client";
+
+import { useMemo, type CSSProperties, type HTMLAttributes, type ReactNode } from "react";
+import { spinnerPixels } from "../core/visibility";
+import type { SpinnerLocaleText, SpinnerSize, SpinnerVariant } from "../core/types";
+import { defaultSpinnerText } from "./locale";
+import { cx, type SpinnerSlot } from "./props";
+import { useDelayedLoading } from "./useDelayedLoading";
+
+export interface SpinnerProps extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+  /** Default true. With `children`, the spinner covers them while this is true. */
+  loading?: boolean;
+  /** Default `md` (24 px); a number is pixels. */
+  size?: SpinnerSize | number;
+  /** Default `ring`. */
+  variant?: SpinnerVariant;
+  /** What screen readers announce. Default "Loading". */
+  label?: string;
+  /** Show the label next to the spinner. */
+  showLabel?: boolean;
+  /** Milliseconds to wait before showing, so fast work doesn't flash. Default 0. */
+  delay?: number;
+  /** Once shown, stay at least this many milliseconds. Default 0. */
+  minDuration?: number;
+  /** Content to cover while loading. It becomes inert, so it can't be clicked or focused. */
+  children?: ReactNode;
+  classNames?: Partial<Record<SpinnerSlot, string>>;
+  localeText?: Partial<SpinnerLocaleText>;
+}
+
+/** A loading indicator, on its own or covering content that is busy. */
+export function Spinner(props: SpinnerProps) {
+  const {
+    loading = true,
+    size = "md",
+    variant = "ring",
+    label,
+    showLabel = false,
+    delay = 0,
+    minDuration = 0,
+    children,
+    className,
+    classNames,
+    style,
+    localeText,
+    ...rest
+  } = props;
+
+  const text = useMemo(() => ({ ...defaultSpinnerText, ...localeText }), [localeText]);
+  const visible = useDelayedLoading(loading, { delay, minDuration });
+  const sized = { "--sp-size": `${spinnerPixels(size)}px`, ...style } as CSSProperties;
+
+  const status = (
+    <span role="status" className={cx("sp-status", classNames?.status)}>
+      <span className={cx("sp-indicator", classNames?.indicator)} data-variant={variant} aria-hidden="true">
+        {variant === "dots" ? (
+          <>
+            <span className="sp-dot" />
+            <span className="sp-dot" />
+            <span className="sp-dot" />
+          </>
+        ) : (
+          <svg className="sp-ring" viewBox="0 0 24 24" focusable="false">
+            <circle className="sp-track" cx="12" cy="12" r="9.5" />
+            <circle className="sp-arc" cx="12" cy="12" r="9.5" pathLength={100} />
+          </svg>
+        )}
+      </span>
+      <span className={showLabel ? cx("sp-label", classNames?.label) : "sp-sr-only"}>{label ?? text.loading}</span>
+    </span>
+  );
+
+  if (children === undefined) {
+    if (!visible) return null;
+    return (
+      <span {...rest} className={cx("sp-root", classNames?.root, className)} style={sized} data-variant={variant}>
+        {status}
+      </span>
+    );
+  }
+
+  return (
+    <div
+      {...rest}
+      className={cx("sp-container", classNames?.root, className)}
+      style={sized}
+      aria-busy={visible || undefined}
+      data-loading={visible || undefined}
+    >
+      <div className={cx("sp-content", classNames?.content)} inert={visible}>
+        {children}
+      </div>
+      {visible && <div className={cx("sp-overlay", classNames?.overlay)}>{status}</div>}
+    </div>
+  );
+}

package/source/components/spinner/react/locale.ts

@@ -0,0 +1,5 @@
+import type { SpinnerLocaleText } from "../core/types";
+
+export const defaultSpinnerText: SpinnerLocaleText = {
+  loading: "Loading",
+};

package/source/components/spinner/react/props.ts

@@ -0,0 +1,4 @@
+export type SpinnerSlot = "root" | "status" | "indicator" | "label" | "content" | "overlay";
+
+// Shared with every other component, so class handling cannot drift.
+export { cx } from "../../shared/core/cx";

package/source/components/spinner/react/useDelayedLoading.ts

@@ -0,0 +1,39 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { stepVisibility } from "../core/visibility";
+import type { VisibilityMarks, VisibilityOptions } from "../core/types";
+
+/**
+ * `loading`, smoothed for display: true only after `delay` has passed, and then
+ * for at least `minDuration`. Use it for any loading UI, not just the Spinner.
+ */
+export function useDelayedLoading(loading: boolean, options: VisibilityOptions = {}): boolean {
+  const { delay = 0, minDuration = 0 } = options;
+  const immediate = delay <= 0 && minDuration <= 0;
+  const [visible, setVisible] = useState(() => loading && delay <= 0);
+  const marks = useRef<VisibilityMarks>({ visible: loading && delay <= 0, loadingSince: null, visibleSince: null });
+
+  useEffect(() => {
+    if (immediate) return;
+    const current = marks.current;
+    const now = Date.now();
+    current.loadingSince = loading ? (current.loadingSince ?? now) : null;
+    if (current.visible) current.visibleSince ??= now;
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const evaluate = () => {
+      const step = stepVisibility(loading, current, Date.now(), { delay, minDuration });
+      if (step.visible !== current.visible) {
+        current.visible = step.visible;
+        current.visibleSince = step.visible ? Date.now() : null;
+        setVisible(step.visible);
+      }
+      if (step.recheckIn !== null) timer = setTimeout(evaluate, step.recheckIn);
+    };
+    timer = setTimeout(evaluate, 0);
+    return () => clearTimeout(timer);
+  }, [loading, delay, minDuration, immediate]);
+
+  return immediate ? loading : visible;
+}

package/source/components/spinner/styles.css

@@ -0,0 +1,173 @@
+/*
+ * Spinner styles.
+ *
+ * The indicator draws in `currentColor`, so it takes the color of its
+ * surroundings. Tokens read the shared --gbs-* variables when they are set on
+ * an ancestor. 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.
+ */
+
+.sp-root,
+.sp-container {
+  --sp-size: 24px;
+  --sp-color: currentColor;
+  --sp-track: color-mix(in oklab, currentColor 18%, transparent);
+  --sp-duration: 0.8s;
+  --sp-overlay-bg: color-mix(in oklab, var(--gbs-bg, var(--dg-bg, light-dark(#ffffff, #0b0b0e))) 72%, transparent);
+  --sp-overlay-color: var(--gbs-accent, var(--dg-accent, light-dark(#2563eb, #60a5fa)));
+  --sp-font-size: var(--gbs-font-size, var(--dg-font-size, 13px));
+
+  color-scheme: inherit;
+}
+
+:where(.dark, [data-theme="dark"]) .sp-root {
+  color-scheme: dark;
+}
+:where(.light, [data-theme="light"]) .sp-root {
+  color-scheme: light;
+}
+
+:where(.sp-root, .sp-container) *,
+:where(.sp-root, .sp-container) *::before,
+:where(.sp-root, .sp-container) *::after {
+  box-sizing: border-box;
+}
+
+.sp-root {
+  display: inline-flex;
+  align-items: center;
+  vertical-align: middle;
+  color: var(--sp-color);
+  font-size: var(--sp-font-size);
+}
+
+.sp-status {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+}
+.sp-label {
+  line-height: 1.4;
+}
+
+.sp-indicator {
+  display: inline-grid;
+  flex: none;
+  place-items: center;
+  width: var(--sp-size);
+  height: var(--sp-size);
+}
+
+/* ---------------------------------------------------------------- ring */
+
+.sp-ring {
+  width: 100%;
+  height: 100%;
+  animation: sp-rotate var(--sp-duration) linear infinite;
+}
+.sp-track,
+.sp-arc {
+  fill: none;
+  stroke-width: 2.5;
+}
+.sp-track {
+  stroke: var(--sp-track);
+}
+.sp-arc {
+  stroke: currentColor;
+  stroke-linecap: round;
+  stroke-dasharray: 28 100;
+}
+@keyframes sp-rotate {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+/* ---------------------------------------------------------------- dots */
+
+.sp-indicator[data-variant="dots"] {
+  grid-auto-flow: column;
+  gap: calc(var(--sp-size) * 0.1);
+}
+.sp-dot {
+  width: calc(var(--sp-size) * 0.22);
+  aspect-ratio: 1;
+  border-radius: 50%;
+  background: currentColor;
+  animation: sp-pulse calc(var(--sp-duration) * 1.4) ease-in-out infinite;
+}
+.sp-dot:nth-child(2) {
+  animation-delay: calc(var(--sp-duration) * 0.18);
+}
+.sp-dot:nth-child(3) {
+  animation-delay: calc(var(--sp-duration) * 0.36);
+}
+@keyframes sp-pulse {
+  0%,
+  80%,
+  100% {
+    opacity: 0.25;
+    scale: 0.7;
+  }
+  40% {
+    opacity: 1;
+    scale: 1;
+  }
+}
+
+/* ----------------------------------------------------------- container */
+
+.sp-container {
+  position: relative;
+}
+.sp-overlay {
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+  display: grid;
+  place-items: center;
+  border-radius: inherit;
+  background: var(--sp-overlay-bg);
+  color: var(--sp-overlay-color);
+  font-size: var(--sp-font-size);
+  animation: sp-fade 150ms ease both;
+}
+@keyframes sp-fade {
+  from {
+    opacity: 0;
+  }
+}
+
+.sp-sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+/* Slower, not stopped: a frozen spinner reads as a hang. */
+@media (prefers-reduced-motion: reduce) {
+  .sp-root,
+  .sp-container {
+    --sp-duration: 2.4s;
+  }
+  .sp-overlay {
+    animation: none;
+  }
+}
+
+@media (forced-colors: active) {
+  .sp-arc,
+  .sp-dot {
+    stroke: CanvasText;
+    background: CanvasText;
+  }
+}