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

package/README.md

@@ -1,3 +1,87 @@
-# Temporary Holding Version
+# @carissa-io/components-ticker
 
-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.
+Content that scrolls continuously (a ticker, a marquee): logos, headlines, announcements. A React component, SCSS-themed,
+safe on the server. The loop is CSS (a transform, no measuring), it has a real pause control, and under
+`prefers-reduced-motion: reduce` it becomes a static list.
+
+```bash
+npm i @carissa-io/components-ticker
+```
+
+It builds on `@carissa-io/components-animate` (the `use_reduced_motion` and `use_in_view` hooks).
+
+## Use
+
+```jsx
+import { Ticker } from '@carissa-io/components-ticker'
+
+<Ticker aria-label="Partners" pause_label="Pause scrolling" play_label="Resume scrolling" duration="40s">
+    <img src="/acme.svg" alt="Acme" />
+    <img src="/globex.svg" alt="Globex" />
+    <a href="/press/1">Carissa wins an award</a>
+</Ticker>
+```
+
+Every child becomes an item (`li`) of a list. The list is rendered twice and the track moves by exactly one list, so the
+loop has no seam. Add enough items for one list to fill the width (a short list is stretched to the viewport width).
+
+| Prop | |
+|---|---|
+| `children` | the items |
+| `duration` | time of one full loop: a CSS time (`30s`) or milliseconds; default `$c-ticker-duration`. The speed follows the width of the content (more items, faster for the same duration) |
+| `direction` | `left` (default), `right`, `up` or `down`; anything else falls back to `left`. The vertical ones need a height (`$c-ticker-height`) |
+| `gap` | space between items: pixels (`24`) or a CSS length (`1.5rem`); default `$c-ticker-gap` |
+| `pause_on_hover` | `true` by default: pause while the pointer is over the ticker |
+| `pause_label`, `play_label` | the accessible name of the control while it is playing / paused. Required in practice: the text comes from the app, nothing is built in |
+| `playing`, `default_playing`, `on_playing_change` | controlled / uncontrolled (default `true`) play state; `on_playing_change(playing)` is called when the control is used, also when controlled |
+| `as` | the tag of the root, `div` by default |
+| `className`, `id`, ... | `className` is appended; unknown props go to the root (give it an `aria-label` to name the region) |
+
+No text is built in: every label is a prop, and a button without its label prop has no accessible name. The app passes `pause_label` and `play_label` from its own translations, the same rule as `components-carousel`.
+
+The root carries `data-state`: `running`, `paused` (by the control), `idle` (off-screen or hidden tab) or `static`
+(reduced motion), and `data-direction`.
+
+## Accessibility
+
+- **Pause control:** a real `<button>` (`aria-label` is `pause_label` while playing and `play_label` while paused). Moving
+  content must be stoppable (WCAG 2.2.2).
+- **Read once:** the second copy that closes the loop is `aria-hidden` and `inert`, so screen readers and the keyboard see
+  the items only once. Links inside the ticker are reachable and the ticker pauses while focus is inside the list.
+- **Hover:** it pauses while the pointer is over it (`pause_on_hover`). Hover is not available on touch screens, so the
+  pause control is the way to stop it there.
+- **Pauses by itself** while it is off-screen or the tab is hidden.
+
+## Reduced motion
+
+Under `prefers-reduced-motion: reduce` it renders a static list: the items wrap, nothing scrolls, there is no second copy
+and no pause control (the hook and the CSS agree; the app does nothing).
+
+## Style
+
+```scss
+@use '@carissa-io/components-ticker/scss' with (
+    $c-ticker-duration: 45s,
+    $c-ticker-gap: 3rem
+);
+```
+
+Classes: `c-ticker`, `c-ticker--left|right|up|down`, `c-ticker--horizontal|vertical`, `c-ticker--pause-on-hover`,
+`c-ticker__viewport`, `__track`, `__list` (`--copy`), `__item`, `__toggle` (`--playing|paused`). Every variable is `!default`
+(see [scss/_variables.scss](scss/_variables.scss)); a theme sets the character of the motion with them.
+
+| Variable | Default |
+|---|---|
+| `$c-ticker-duration` | `30s` |
+| `$c-ticker-easing` | `linear` |
+| `$c-ticker-gap` | `2rem` |
+| `$c-ticker-height` | `12rem` (vertical) |
+| `$c-ticker-fade-size` | `0` (soft edges off) |
+| `$c-ticker-toggle-size` | `2rem` |
+| `$c-ticker-toggle-color` | `currentcolor` |
+| `$c-ticker-toggle-background` | `transparent` |
+| `$c-ticker-toggle-border-width` | `1px` |
+| `$c-ticker-toggle-border-color` | `currentcolor` |
+| `$c-ticker-toggle-radius` | `50%` |
+| `$c-ticker-toggle-icon-size` | `0.375rem` |
+| `$c-ticker-toggle-focus-outline` | `2px solid currentcolor` |

package/dist/index.js

@@ -0,0 +1,112 @@
+// src/Ticker.jsx
+import { Children, useState, useSyncExternalStore } from "react";
+import { use_in_view, use_reduced_motion } from "@carissa-io/components-animate";
+import { jsx, jsxs } from "react/jsx-runtime";
+var DIRECTIONS = ["left", "right", "up", "down"];
+var TAG = /^[a-z][a-z0-9-]*$/i;
+var TIME = /^\d+(\.\d+)?(ms|s)$/;
+var LENGTH = /^\d+(\.\d+)?(px|rem|em|%)$/;
+var join = (...parts) => parts.filter(Boolean).join(" ");
+function to_time(value) {
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) return `${value}ms`;
+  if (typeof value === "string" && TIME.test(value.trim()) && parseFloat(value) > 0) return value.trim();
+  return void 0;
+}
+function to_length(value) {
+  if (typeof value === "number" && Number.isFinite(value) && value >= 0) return `${value}px`;
+  if (typeof value === "string" && LENGTH.test(value.trim())) return value.trim();
+  return void 0;
+}
+function subscribe_visibility(on_change) {
+  if (typeof document === "undefined") return () => {
+  };
+  document.addEventListener("visibilitychange", on_change);
+  return () => document.removeEventListener("visibilitychange", on_change);
+}
+var tab_is_visible = () => typeof document === "undefined" || document.visibilityState !== "hidden";
+var make_inert = (node) => node?.setAttribute("inert", "");
+function Ticker({
+  direction = "left",
+  duration,
+  gap,
+  pause_on_hover = true,
+  pause_label,
+  play_label,
+  playing,
+  default_playing = true,
+  on_playing_change,
+  as = "div",
+  className = "",
+  style,
+  children,
+  ...rest
+}) {
+  const items = Children.toArray(children);
+  const safe_direction = DIRECTIONS.includes(direction) ? direction : "left";
+  const axis = safe_direction === "up" || safe_direction === "down" ? "vertical" : "horizontal";
+  const Tag = typeof as === "string" && TAG.test(as) ? as : "div";
+  const reduced = use_reduced_motion();
+  const [ref, in_view] = use_in_view();
+  const visible_tab = useSyncExternalStore(subscribe_visibility, tab_is_visible, () => true);
+  const [own_playing, set_own_playing] = useState(default_playing !== false);
+  const wants_play = playing === void 0 ? own_playing : playing !== false;
+  const running = wants_play && in_view && visible_tab;
+  let state = "running";
+  if (reduced) state = "static";
+  else if (!wants_play) state = "paused";
+  else if (!running) state = "idle";
+  const toggle = () => {
+    const next = !wants_play;
+    if (playing === void 0) set_own_playing(next);
+    on_playing_change?.(next);
+  };
+  const vars = {};
+  const safe_duration = to_time(duration);
+  const safe_gap = to_length(gap);
+  if (safe_duration) vars["--c-ticker-duration"] = safe_duration;
+  if (safe_gap) vars["--c-ticker-gap"] = safe_gap;
+  const list = (copy) => /* @__PURE__ */ jsx(
+    "ul",
+    {
+      className: join("c-ticker__list", copy && "c-ticker__list--copy"),
+      "aria-hidden": copy ? "true" : void 0,
+      ref: copy ? make_inert : void 0,
+      children: items.map((child, index) => /* @__PURE__ */ jsx("li", { className: "c-ticker__item", children: child }, index))
+    }
+  );
+  return /* @__PURE__ */ jsxs(
+    Tag,
+    {
+      ...rest,
+      ref,
+      "data-state": state,
+      "data-direction": safe_direction,
+      style: { ...vars, ...style },
+      className: join(
+        "c-ticker",
+        `c-ticker--${axis}`,
+        `c-ticker--${safe_direction}`,
+        pause_on_hover !== false && "c-ticker--pause-on-hover",
+        className
+      ),
+      children: [
+        /* @__PURE__ */ jsx("div", { className: "c-ticker__viewport", children: /* @__PURE__ */ jsxs("div", { className: "c-ticker__track", children: [
+          list(false),
+          reduced ? null : list(true)
+        ] }) }),
+        reduced ? null : /* @__PURE__ */ jsx(
+          "button",
+          {
+            type: "button",
+            className: join("c-ticker__toggle", wants_play ? "c-ticker__toggle--playing" : "c-ticker__toggle--paused"),
+            "aria-label": wants_play ? pause_label : play_label,
+            onClick: toggle
+          }
+        )
+      ]
+    }
+  );
+}
+export {
+  Ticker
+};

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@carissa-io/components-ticker",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Carissa UI: ticker 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-ticker.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/_ticker.scss

@@ -0,0 +1,180 @@
+@use 'variables' as *;
+
+@keyframes c-ticker-x {
+    from {
+        transform: translateX(0);
+    }
+
+    to {
+        transform: translateX(-50%);
+    }
+}
+
+@keyframes c-ticker-y {
+    from {
+        transform: translateY(0);
+    }
+
+    to {
+        transform: translateY(-50%);
+    }
+}
+
+.c-ticker {
+    position: relative;
+    display: flex;
+    align-items: center;
+    gap: $c-ticker-gap;
+}
+
+.c-ticker__viewport {
+    flex: 1;
+    min-width: 0;
+    overflow: hidden;
+
+    @if $c-ticker-fade-size != 0 {
+        mask-image: linear-gradient(to right, transparent, #000 $c-ticker-fade-size, #000 calc(100% - #{$c-ticker-fade-size}), transparent);
+    }
+}
+
+.c-ticker__track {
+    display: flex;
+    width: max-content;
+    animation-duration: var(--c-ticker-duration, #{$c-ticker-duration});
+    animation-timing-function: $c-ticker-easing;
+    animation-iteration-count: infinite;
+}
+
+// Each list is at least as wide as the viewport so a short list never leaves a hole; the padding closes the gap
+// between the end of one list and the start of the next, so the loop moves by exactly one list.
+.c-ticker__list {
+    display: flex;
+    flex: none;
+    gap: var(--c-ticker-gap, #{$c-ticker-gap});
+    min-width: 100vw;
+    padding: 0 var(--c-ticker-gap, #{$c-ticker-gap}) 0 0;
+    margin: 0;
+    list-style: none;
+}
+
+.c-ticker__item {
+    flex: none;
+}
+
+.c-ticker--horizontal .c-ticker__track {
+    animation-name: c-ticker-x;
+}
+
+.c-ticker--right .c-ticker__track,
+.c-ticker--down .c-ticker__track {
+    animation-direction: reverse;
+}
+
+.c-ticker--vertical {
+    .c-ticker__viewport {
+        height: $c-ticker-height;
+    }
+
+    .c-ticker__track {
+        flex-direction: column;
+        width: auto;
+        animation-name: c-ticker-y;
+    }
+
+    .c-ticker__list {
+        flex-direction: column;
+        min-width: 0;
+        min-height: $c-ticker-height;
+        padding: 0 0 var(--c-ticker-gap, #{$c-ticker-gap}) 0;
+    }
+}
+
+// Not playing: paused by the control, off-screen or in a hidden tab (and always while focus is inside the list)
+.c-ticker[data-state='paused'] .c-ticker__track,
+.c-ticker[data-state='idle'] .c-ticker__track,
+.c-ticker__viewport:focus-within .c-ticker__track,
+.c-ticker--pause-on-hover .c-ticker__viewport:hover .c-ticker__track {
+    animation-play-state: paused;
+}
+
+// Reduced motion (the component also renders the static form by itself): items wrap, nothing scrolls
+.c-ticker[data-state='static'] {
+    .c-ticker__track {
+        width: auto;
+        animation: none;
+    }
+
+    .c-ticker__list {
+        flex: 0 1 auto;
+        flex-wrap: wrap;
+        min-width: 0;
+        min-height: 0;
+        padding: 0;
+    }
+
+    .c-ticker__viewport {
+        height: auto;
+        mask-image: none;
+    }
+}
+
+.c-ticker__toggle {
+    position: relative;
+    box-sizing: border-box;
+    flex: none;
+    width: $c-ticker-toggle-size;
+    height: $c-ticker-toggle-size;
+    padding: 0;
+    color: $c-ticker-toggle-color;
+    cursor: pointer;
+    background: $c-ticker-toggle-background;
+    border: $c-ticker-toggle-border-width solid $c-ticker-toggle-border-color;
+    border-radius: $c-ticker-toggle-radius;
+
+    &::before {
+        position: absolute;
+        top: 50%;
+        left: 50%;
+        content: '';
+    }
+
+    &:focus-visible {
+        outline: $c-ticker-toggle-focus-outline;
+        outline-offset: 2px;
+    }
+}
+
+.c-ticker__toggle--playing::before {
+    width: $c-ticker-toggle-icon-size;
+    height: $c-ticker-toggle-icon-size * 1.5;
+    border-right: $c-ticker-toggle-icon-size * 0.375 solid currentcolor;
+    border-left: $c-ticker-toggle-icon-size * 0.375 solid currentcolor;
+    transform: translate(-50%, -50%);
+}
+
+.c-ticker__toggle--paused::before {
+    border-top: $c-ticker-toggle-icon-size * 0.75 solid transparent;
+    border-bottom: $c-ticker-toggle-icon-size * 0.75 solid transparent;
+    border-left: $c-ticker-toggle-icon-size * 1.25 solid currentcolor;
+    transform: translate(-35%, -50%);
+}
+
+@media (prefers-reduced-motion: reduce) {
+    .c-ticker__track {
+        width: auto;
+        animation: none;
+    }
+
+    .c-ticker__list--copy,
+    .c-ticker__toggle {
+        display: none;
+    }
+
+    .c-ticker__list {
+        flex: 0 1 auto;
+        flex-wrap: wrap;
+        min-width: 0;
+        min-height: 0;
+        padding: 0;
+    }
+}

package/scss/_variables.scss

@@ -0,0 +1,24 @@
+// Every value is `!default`: set it before the first @use / through `with (...)` and it wins.
+//
+//   @use '@carissa-io/components-ticker/scss' with ($c-ticker-duration: 45s, $c-ticker-gap: 3rem);
+//
+// The ticker scrolls by one list per loop, so `$c-ticker-duration` is the time of a full loop: a longer list moves
+// faster for the same duration. Under `prefers-reduced-motion: reduce` it is a static list that wraps.
+
+$c-ticker-duration: 30s !default; // one full loop; per instance: `duration` prop or `--c-ticker-duration`
+$c-ticker-easing: linear !default; // a marquee moves at a constant speed
+
+// Layout
+$c-ticker-gap: 2rem !default; // between items; per instance: `gap` prop or `--c-ticker-gap`
+$c-ticker-height: 12rem !default; // viewport height of the vertical directions (`up`, `down`)
+$c-ticker-fade-size: 0 !default; // soft edge at both ends of the viewport (a length, `0` is off)
+
+// Pause control
+$c-ticker-toggle-size: 2rem !default;
+$c-ticker-toggle-color: currentcolor !default;
+$c-ticker-toggle-background: transparent !default;
+$c-ticker-toggle-border-width: 1px !default;
+$c-ticker-toggle-border-color: currentcolor !default;
+$c-ticker-toggle-radius: 50% !default;
+$c-ticker-toggle-icon-size: 0.375rem !default;
+$c-ticker-toggle-focus-outline: 2px solid currentcolor !default;

package/scss/index.scss

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