@carissa-io/components-stagger-list 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# @carissa-io/components-stagger-list
 
-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 list whose rows enter one after another. The rows stay real list items (`li` inside `ul` / `ol`), so the list keeps its
+semantics. A React component, SCSS-themed, safe on the server. The motion is CSS: it reuses the presets of
+`@carissa-io/components-animate` and the inherited `--c-animate-delay` custom property (the pattern `Sequence` uses), and
+it depends on that package only.
+
+```bash
+npm i @carissa-io/components-stagger-list
+```
+
+Load the styles of both packages: the pace between rows is set here, the motion itself (duration, distance, easing) in
+`@carissa-io/components-animate`.
+
+## Use
+
+```jsx
+import { StaggerList } from '@carissa-io/components-stagger-list'
+
+<StaggerList effect="rise" trigger="view" stagger={100} aria-label="Steps">
+    <span>Create an account</span>
+    <span>Pick a plan</span>
+    <span>Invite your team</span>
+</StaggerList>
+
+// or from data
+<StaggerList as="ol" items={steps.map((step) => <Step key={step.id} {...step} />)} />
+```
+
+Pass the content of each row; a child that is already an `li` is used as the row itself (its props are kept).
+
+| Prop | |
+|---|---|
+| `children`, `items` | the rows: the children first, then the entries of `items` |
+| `effect` | `fade`, `rise` (default) or `scale`; anything else falls back to `rise` |
+| `trigger` | `load` (default, plays on first paint, no script needed) or `view` (when the list enters the viewport); anything else falls back to `load` |
+| `stagger` | gap between one row and the next, milliseconds or a CSS time; default `$c-stagger-list-stagger` |
+| `delay` | wait before the first row; default `$c-stagger-list-delay` |
+| `duration` | entrance time of one row (sets `--c-animate-duration`) |
+| `once` | `true` by default: plays only the first time; `false` plays again each time the list re-enters the viewport (`trigger="view"`) |
+| `as` | `ul` (default), `ol` or `div` (rows are then `div`s); anything else falls back to `ul` |
+| `className`, `id`, ... | `className` is appended; unknown props go to the root |
+
+The component has no strings of its own: the rows come from the app.
+
+Invalid times are ignored. The root carries `data-state` (`idle`, `active` or `static`) and each row
+`--c-stagger-list-index`; row N waits `delay + N * stagger`.
+
+## Accessibility and reduced motion
+
+- The list is a real `ul` / `ol` with `li` rows, so assistive tech announces it as a list with its item count.
+- Rows are in the DOM from the start; with `trigger="view"` they are only transparent until the list is seen, so do not use
+  it for content the page cannot do without when JavaScript fails. `trigger="load"` plays without a script.
+- Under `prefers-reduced-motion: reduce` every row is shown at once with no animation (the component and the CSS agree; the
+  app does nothing).
+
+## Style
+
+```scss
+@use '@carissa-io/components-animate/scss';
+@use '@carissa-io/components-stagger-list/scss' with (
+    $c-stagger-list-stagger: 0.15s,
+    $c-stagger-list-gap: 0.5rem
+);
+```
+
+Classes: `c-stagger-list`, `c-stagger-list__item` (plus animate's `c-animate c-animate--rise|fade|scale c-animate--entrance`
+on each row). Every variable is `!default` (see [scss/_variables.scss](scss/_variables.scss)).
+
+| Variable | Default |
+|---|---|
+| `$c-stagger-list-stagger` | `0.08s` |
+| `$c-stagger-list-delay` | `0s` |
+| `$c-stagger-list-gap` | `0` |
+| `$c-stagger-list-direction` | `column` |

package/dist/index.js

@@ -0,0 +1,74 @@
+// src/StaggerList.jsx
+import { Children, cloneElement, isValidElement } from "react";
+import { use_in_view, use_reduced_motion } from "@carissa-io/components-animate";
+import { jsx } from "react/jsx-runtime";
+var EFFECTS = ["fade", "rise", "scale"];
+var TRIGGERS = ["load", "view"];
+var TAGS = ["ul", "ol", "div"];
+var TIME = /^\d+(\.\d+)?(ms|s)$/;
+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())) return value.trim();
+  return void 0;
+}
+function StaggerList({
+  items,
+  effect = "rise",
+  trigger = "load",
+  stagger,
+  delay,
+  duration,
+  once = true,
+  as = "ul",
+  className = "",
+  style,
+  children,
+  ...rest
+}) {
+  const rows = [...Children.toArray(children), ...Array.isArray(items) ? items : []];
+  const safe_effect = EFFECTS.includes(effect) ? effect : "rise";
+  const safe_trigger = TRIGGERS.includes(trigger) ? trigger : "load";
+  const Tag = TAGS.includes(as) ? as : "ul";
+  const Row = Tag === "div" ? "div" : "li";
+  const reduced = use_reduced_motion();
+  const [ref, in_view] = use_in_view({ once: once !== false });
+  const active = safe_trigger === "load" || in_view;
+  const state = reduced ? void 0 : active ? "active" : "idle";
+  const vars = {};
+  const safe_stagger = to_time(stagger);
+  const safe_delay = to_time(delay);
+  const safe_duration = to_time(duration);
+  if (safe_stagger) vars["--c-stagger-list-stagger"] = safe_stagger;
+  if (safe_delay) vars["--c-stagger-list-delay"] = safe_delay;
+  if (safe_duration) vars["--c-animate-duration"] = safe_duration;
+  const row_classes = join("c-stagger-list__item", "c-animate", `c-animate--${safe_effect}`, "c-animate--entrance");
+  return /* @__PURE__ */ jsx(
+    Tag,
+    {
+      ...rest,
+      ref,
+      "data-state": reduced ? "static" : active ? "active" : "idle",
+      style: { ...vars, ...style },
+      className: join("c-stagger-list", className),
+      children: rows.map((row, index) => {
+        const props = {
+          "data-state": state,
+          style: { "--c-stagger-list-index": index }
+        };
+        if (Row === "li" && isValidElement(row) && row.type === "li") {
+          return cloneElement(row, {
+            ...props,
+            key: row.key ?? index,
+            className: join(row_classes, row.props.className),
+            style: { ...props.style, ...row.props.style }
+          });
+        }
+        return /* @__PURE__ */ jsx(Row, { className: row_classes, ...props, children: row }, isValidElement(row) && row.key != null ? row.key : index);
+      })
+    }
+  );
+}
+export {
+  StaggerList
+};

package/package.json

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

@@ -0,0 +1,26 @@
+@use 'variables' as *;
+
+.c-stagger-list {
+    display: flex;
+    flex-direction: $c-stagger-list-direction;
+    gap: $c-stagger-list-gap;
+    padding: 0;
+    margin: 0;
+    list-style: none;
+}
+
+// Each row inherits the animation of `.c-animate--*` (the preset) and takes its place in the order as a delay
+.c-stagger-list__item {
+    --c-animate-delay: calc(
+        var(--c-stagger-list-delay, #{$c-stagger-list-delay}) + var(--c-stagger-list-index, 0) *
+            var(--c-stagger-list-stagger, #{$c-stagger-list-stagger})
+    );
+}
+
+@media (prefers-reduced-motion: reduce) {
+    .c-stagger-list__item {
+        opacity: 1;
+        transform: none;
+        animation: none;
+    }
+}

package/scss/_variables.scss

@@ -0,0 +1,14 @@
+// Every value is `!default`: set it before the first @use / through `with (...)` and it wins.
+//
+//   @use '@carissa-io/components-stagger-list/scss' with ($c-stagger-list-stagger: 0.15s, $c-stagger-list-gap: 0.5rem);
+//
+// The rows enter with the presets of `@carissa-io/components-animate`: load that package's styles too, since the motion
+// itself (duration, distance, easing) is configured there. Here you set the pace between rows.
+// Under `prefers-reduced-motion: reduce` every row shows at once.
+
+$c-stagger-list-stagger: 0.08s !default; // gap between one row and the next; per instance: `stagger` prop or `--c-stagger-list-stagger`
+$c-stagger-list-delay: 0s !default; // wait before the first row; per instance: `delay` prop or `--c-stagger-list-delay`
+
+// Layout of the rows (neutral: stacked, no marker, no gap)
+$c-stagger-list-gap: 0 !default;
+$c-stagger-list-direction: column !default;

package/scss/index.scss

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