@carissa-io/components-counter 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# @carissa-io/components-counter
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A number that counts up to its value and ticks to a new one when the value changes. A React component, SCSS-themed, safe on
+the server. JavaScript drives the count (`requestAnimationFrame`); it stops while the tab is hidden, and with
+`trigger="view"` while the element is off-screen. It builds on `@carissa-io/components-animate` for the shared hooks
+(`use_reduced_motion`, `use_in_view`).
+
+```bash
+npm i @carissa-io/components-counter
+```
+
+## Use
+
+```jsx
+import { Counter } from '@carissa-io/components-counter'
+
+<Counter value={12840} locale="en-US" />
+
+// Starts when the reader scrolls to it
+<Counter value={99.5} decimals={1} suffix="%" trigger="view" duration={1800} on_complete={() => track('stat_seen')} />
+
+// Intl options or a function
+<Counter value={2400} locale="en-US" format={{ style: 'currency', currency: 'USD' }} />
+<Counter value={3} format={(n) => `${Math.round(n)} of 10`} />
+```
+
+Change `value` later and it ticks from the number on screen to the new one.
+
+| Prop | |
+|---|---|
+| `value` | the number to reach (default `0`). NaN, Infinity and anything that is not a number fall back to `0` |
+| `from` | where the first count starts (default `0`; same fallback) |
+| `duration` | milliseconds of one count. Without it the SCSS variable is used (`1.2s`) |
+| `delay` | milliseconds before the first frame (default `0`) |
+| `decimals` | digits after the point, integer 0 to 20 (default `0`). With `format` options, they own the digits unless `decimals` is given |
+| `locale` | BCP 47 tag, the visitor's by default; an invalid one falls back to it |
+| `format` | `Intl.NumberFormat` options (`{ style: 'percent' }`, ...) or a function `(value) => string`; invalid ones fall back to the plain number |
+| `prefix`, `suffix` | text around the number (strings or numbers) |
+| `trigger` | `load` (default, counts as soon as it mounts) or `view` (waits for the viewport, pauses off-screen); anything else falls back to `load` |
+| `on_complete` | `(value) => void`, called each time a count reaches its value |
+| `as` | the tag of the root, `span` by default |
+| `className`, `id`, ... | `className` is appended; unknown props go to the root |
+
+The component has no strings of its own: the digits are formatted from `value` and the app supplies any `prefix` or `suffix`.
+
+The root carries `data-state` (`counting` or `done`) and `data-motion="reduced"` under reduced motion.
+
+## Accessibility
+
+The final formatted value (prefix and suffix included) is the container's accessible text from the first render, in a
+visually hidden `c-counter__text` element. The animated digits (`c-counter__value`) are `aria-hidden`, so a screen reader
+never reads the frames and there is no live region. Do not put `aria-live` on it.
+
+## Reduced motion, hidden tab, server
+
+- `prefers-reduced-motion: reduce`: the final value at once, no frame is scheduled (it follows changes of the setting).
+- The count pauses while the tab is hidden and resumes where it stopped; with `trigger="view"` it also pauses off-screen.
+- Server rendering and the first paint show the final value, so nothing is wrong without JavaScript.
+
+## What the app does
+
+- Use it for one number worth noticing (one orchestrated moment per page), not for every figure.
+- It passes `locale` (or relies on the visitor's) and any currency; the component has no text of its own.
+
+## Style
+
+```scss
+@use '@carissa-io/components-counter/scss' with (
+    $c-counter-duration: 2s,
+    $c-counter-easing: in-out
+);
+```
+
+Classes: `c-counter`, `c-counter__text` (visually hidden final value) and `c-counter__value` (the animated digits).
+JavaScript reads the duration and the easing from the `--c-counter-duration` and `--c-counter-easing` custom properties.
+
+| Variable | Default |
+|---|---|
+| `$c-counter-duration` | `1.2s` (a CSS time; the `duration` prop of one instance wins) |
+| `$c-counter-easing` | `out` (`out`, `in-out` or `linear`) |
+| `$c-counter-font-variant-numeric` | `tabular-nums` |

package/dist/index.js

@@ -0,0 +1,177 @@
+// src/Counter.jsx
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { use_in_view, use_reduced_motion } from "@carissa-io/components-animate";
+import { jsx, jsxs } from "react/jsx-runtime";
+var TRIGGERS = ["load", "view"];
+var TAG = /^[a-z][a-z0-9-]*$/i;
+var DEFAULT_DURATION = 1200;
+var EASINGS = {
+  out: (p) => 1 - (1 - p) ** 3,
+  "in-out": (p) => p < 0.5 ? 4 * p ** 3 : 1 - (-2 * p + 2) ** 3 / 2,
+  linear: (p) => p
+};
+var join = (...parts) => parts.filter(Boolean).join(" ");
+var to_number = (value, fallback) => typeof value === "number" && Number.isFinite(value) ? value : fallback;
+var to_ms = (value, fallback) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : fallback;
+var to_text = (value) => typeof value === "string" || typeof value === "number" ? String(value) : "";
+function css_time(raw) {
+  const match = /^\s*(\d+(?:\.\d+)?)(ms|s)\s*$/.exec(raw ?? "");
+  if (!match) return void 0;
+  return match[2] === "s" ? Number(match[1]) * 1e3 : Number(match[1]);
+}
+var noop_subscribe = () => () => {
+};
+var on_client = () => true;
+var on_server = () => false;
+function subscribe_visibility(on_change) {
+  document.addEventListener("visibilitychange", on_change);
+  return () => document.removeEventListener("visibilitychange", on_change);
+}
+var tab_hidden = () => document.visibilityState === "hidden";
+function make_formatter(locale, decimals, options_key) {
+  const options = options_key ? JSON.parse(options_key) : {};
+  const fixed = decimals === void 0 ? {} : { minimumFractionDigits: decimals, maximumFractionDigits: decimals };
+  const plain = { minimumFractionDigits: decimals ?? 0, maximumFractionDigits: decimals ?? 0 };
+  const attempts = [
+    [locale, { ...options_key ? {} : plain, ...fixed, ...options }],
+    [locale, plain],
+    [void 0, plain]
+  ];
+  for (const [loc, opts] of attempts) {
+    try {
+      return new Intl.NumberFormat(loc, opts);
+    } catch {
+    }
+  }
+  return new Intl.NumberFormat();
+}
+function Counter({
+  value = 0,
+  from = 0,
+  duration,
+  delay = 0,
+  decimals,
+  locale,
+  format,
+  prefix,
+  suffix,
+  trigger = "load",
+  on_complete,
+  as = "span",
+  className = "",
+  ...rest
+}) {
+  const target = to_number(value, 0);
+  const start = to_number(from, 0);
+  const safe_trigger = TRIGGERS.includes(trigger) ? trigger : "load";
+  const Tag = typeof as === "string" && TAG.test(as) ? as : "span";
+  const digits = Number.isInteger(decimals) && decimals >= 0 && decimals <= 20 ? decimals : void 0;
+  const safe_locale = typeof locale === "string" && locale ? locale : void 0;
+  const format_fn = typeof format === "function" ? format : null;
+  let format_key = "";
+  if (!format_fn && format && typeof format === "object") {
+    try {
+      format_key = JSON.stringify(format);
+    } catch {
+      format_key = "";
+    }
+  }
+  const safe_duration = to_ms(duration, void 0);
+  const safe_delay = to_ms(delay, 0);
+  const reduced = use_reduced_motion();
+  const [set_view_node, in_view] = use_in_view();
+  const hidden = useSyncExternalStore(subscribe_visibility, tab_hidden, () => false);
+  const mounted = useSyncExternalStore(noop_subscribe, on_client, on_server);
+  const node_ref = useRef(null);
+  const ref = useCallback(
+    (node) => {
+      node_ref.current = node;
+      set_view_node(node);
+    },
+    [set_view_node]
+  );
+  const complete_ref = useRef(on_complete);
+  useEffect(() => {
+    complete_ref.current = on_complete;
+  });
+  const [shown, set_shown] = useState(null);
+  const current = useRef(null);
+  const run = useRef(null);
+  const can_run = !hidden && (safe_trigger === "load" || in_view);
+  useEffect(() => {
+    if (reduced || !can_run) return void 0;
+    const cur = current.current ?? start;
+    if (!run.current || run.current.to !== target) run.current = { to: target, origin: cur };
+    if (cur === target) return void 0;
+    const { origin } = run.current;
+    const node = node_ref.current;
+    const style = node ? getComputedStyle(node) : null;
+    const total = safe_duration ?? css_time(style?.getPropertyValue("--c-counter-duration")) ?? DEFAULT_DURATION;
+    const easing_name = style?.getPropertyValue("--c-counter-easing").trim();
+    const ease = EASINGS[easing_name] ?? EASINGS.out;
+    const span = Math.abs(target - origin);
+    const length = span === 0 ? 0 : total * (Math.abs(target - cur) / span);
+    const wait = cur === origin ? safe_delay : 0;
+    let frame = 0;
+    let timer = 0;
+    let t0 = null;
+    const tick = (now) => {
+      if (t0 === null) t0 = now;
+      const p = length <= 0 ? 1 : Math.min(1, (now - t0) / length);
+      const next = p >= 1 ? target : cur + (target - cur) * ease(p);
+      current.current = next;
+      set_shown(next);
+      if (p < 1) {
+        frame = requestAnimationFrame(tick);
+      } else {
+        run.current = null;
+        if (typeof complete_ref.current === "function") complete_ref.current(target);
+      }
+    };
+    const begin = () => {
+      frame = requestAnimationFrame(tick);
+    };
+    if (wait > 0) timer = setTimeout(begin, wait);
+    else begin();
+    return () => {
+      clearTimeout(timer);
+      cancelAnimationFrame(frame);
+    };
+  }, [reduced, can_run, target, start, safe_duration, safe_delay]);
+  const formatter = useMemo(
+    () => make_formatter(safe_locale, digits, format_key),
+    [safe_locale, digits, format_key]
+  );
+  const render_number = (n) => {
+    if (format_fn) {
+      try {
+        const out = format_fn(n);
+        if (typeof out === "string" || typeof out === "number") return String(out);
+      } catch {
+      }
+    }
+    return formatter.format(n);
+  };
+  const before = to_text(prefix);
+  const after = to_text(suffix);
+  const final_text = `${before}${render_number(target)}${after}`;
+  const on_screen = reduced || !mounted ? target : shown ?? start;
+  const visible_text = on_screen === target ? final_text : `${before}${render_number(on_screen)}${after}`;
+  return /* @__PURE__ */ jsxs(
+    Tag,
+    {
+      ...rest,
+      ref,
+      "data-state": reduced || !mounted || on_screen === target ? "done" : "counting",
+      "data-motion": reduced ? "reduced" : void 0,
+      className: join("c-counter", className),
+      children: [
+        /* @__PURE__ */ jsx("span", { className: "c-counter__text", children: final_text }),
+        /* @__PURE__ */ jsx("span", { className: "c-counter__value", "aria-hidden": "true", children: visible_text })
+      ]
+    }
+  );
+}
+export {
+  Counter
+};

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@carissa-io/components-counter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Carissa UI: counter as a React component with SCSS variables",
+  "type": "module",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "scss",
+    "THIRD-PARTY-NOTICES"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./scss": "./scss/index.scss",
+    "./scss/*": "./scss/*"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "esbuild src/index.js --bundle --packages=external --format=esm --jsx=automatic --outfile=dist/index.js",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "prepublishOnly": "node -e \"if (!process.env.GITHUB_ACTIONS) { console.error('Refusing to publish outside GitHub Actions CI: commit and push to main instead.'); process.exit(1); }\" && npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/carissa-io/components-counter.git"
+  },
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {
+    "@carissa-io/components-animate": "^0.1.1"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.7",
+    "@vitejs/plugin-react": "^6.1.1",
+    "esbuild": "^0.28.0",
+    "eslint": "^10.12.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "globals": "^17.13.0",
+    "jsdom": "^29.1.1",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "sass-embedded": "^1.105.1",
+    "vite": "^8.3.2",
+    "vitest": "^4.1.11"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}

package/scss/_counter.scss

@@ -0,0 +1,22 @@
+@use 'variables' as *;
+
+.c-counter {
+    --c-counter-duration: #{$c-counter-duration};
+    --c-counter-easing: #{$c-counter-easing};
+
+    position: relative;
+    font-variant-numeric: $c-counter-font-variant-numeric;
+}
+
+// The final value, visually hidden and still read by assistive technology (the animated digits are aria-hidden).
+.c-counter__text {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+    border: 0;
+}

package/scss/_variables.scss

@@ -0,0 +1,11 @@
+// Every value is `!default`: set it before the first @use / through `with (...)` and it wins.
+//
+//   @use '@carissa-io/components-counter/scss' with ($c-counter-duration: 2s, $c-counter-easing: in-out);
+//
+// The count is driven by JavaScript, which reads the duration and the easing from custom properties on the element, so a
+// theme sets the character of the motion here. The `duration` prop of one instance wins over the duration.
+// Under `prefers-reduced-motion: reduce` the component shows the final value at once.
+
+$c-counter-duration: 1.2s !default; // a CSS time (`1.2s`, `800ms`)
+$c-counter-easing: out !default; // `out` (decelerating), `in-out` or `linear`
+$c-counter-font-variant-numeric: tabular-nums !default; // equal-width digits, so the number does not jitter

package/scss/index.scss

@@ -0,0 +1,2 @@
+@forward 'variables';
+@use 'counter';