@dreamtree-org/twreact-ui 2.1.2 → 2.2.0

package/README.md

@@ -124,23 +124,27 @@ Server Component to these Client Components. You also cannot dot into a client e
 In Vite, Rollup can log `Module level directives cause errors when bundled, "use client" … was ignored`.
 This message is harmless. To hide it, filter `MODULE_LEVEL_DIRECTIVE` in `build.rollupOptions.onwarn`.
 
-### Optional entry points: charts and rich text
+### Optional entry points: charts, rich text and motion
 
 Charts and the rich-text editor wrap third-party libraries, so they live on their own entry points
-and use **optional peer dependencies**. If you never import them you install nothing extra, and
-nothing changes in your bundle — the root `@dreamtree-org/twreact-ui` import never touches them.
+and use **optional peer dependencies**. The motion (scroll-storytelling) components need no
+dependency at all but are kept off the root so app bundles never carry them. If you never import
+these entry points you install nothing extra, and nothing changes in your bundle — the root
+`@dreamtree-org/twreact-ui` import never touches them.
 
 | Entry point | Exports | Install first |
 |---|---|---|
 | `@dreamtree-org/twreact-ui/charts` | `LineChart`, `BarChart`, `AreaChart`, `DonutChart`, `Sparkline`, `ScatterChart` | `npm install recharts` (recharts 2.15+ or 3.x; React 18 apps also `npm install react-is@18`) |
 | `@dreamtree-org/twreact-ui/rich-text` | `RichTextEditor` | `npm install @tiptap/react @tiptap/pm @tiptap/starter-kit` (Tiptap 3) |
+| `@dreamtree-org/twreact-ui/motion` | `ScrollStage`, `Reveal`, `RevealGroup`, `LogoMarquee`, `CountUp`, `StatStrip`, `StackedCards`, `DeviceFrame`, `DeviceMorphHero`, `BentoExpandGrid`, `TestimonialSpotlight`, `PhotoCollage`, `RotatingBadge`, `SmoothScrollProvider`, `useScrollProgress`, `useSmoothScroll` | Nothing. Optional: `npm install lenis` for `SmoothScrollProvider` |
 
 ```jsx
 import { LineChart, DonutChart } from '@dreamtree-org/twreact-ui/charts';
 import { RichTextEditor } from '@dreamtree-org/twreact-ui/rich-text';
+import { StackedCards, LogoMarquee } from '@dreamtree-org/twreact-ui/motion';
 ```
 
-Both ship ESM (with `'use client'`), CommonJS and TypeScript declarations, and resolve under every
+All three ship ESM (with `'use client'`), CommonJS and TypeScript declarations, and resolve under every
 TypeScript `moduleResolution` (`bundler`, `node16`/`nodenext` and legacy `node`). Their styles are
 already in `dist/index.css`. Rich-text output is HTML from the user — **sanitize it on the server**
 before you store or render it (see [doc/RichTextEditor.md](doc/RichTextEditor.md#security-sanitize-the-html-on-the-server)).
@@ -858,6 +862,45 @@ import { RichTextEditor } from '@dreamtree-org/twreact-ui/rich-text';
 > The HTML comes from the user. Sanitize it on the server (e.g. DOMPurify / `sanitize-html`) before
 > storing or rendering it; this library ships no sanitizer.
 
+### Motion: scroll storytelling (optional entry point)
+
+Import from `@dreamtree-org/twreact-ui/motion` — landing-page sections that tell a story as the
+page scrolls (overview: [`doc/Motion.md`](doc/Motion.md)). One shared `requestAnimationFrame` +
+`IntersectionObserver` engine drives them by writing CSS variables (`--dt-p`, 0–1), so React does
+not re-render per frame and only on-screen sections do any work. No animation library is bundled;
+the entry is gated at **12 KB gzipped** (`npm run motion:size`).
+
+| Component | Use for |
+|---|---|
+| [`ScrollStage`](doc/ScrollStage.md) | A pinned scene: content sticks while the page scrolls `length` vh (default 300, 150 below `md`); progress in `--dt-p`, `children(progress)` and `onProgress` |
+| [`useScrollProgress`](doc/useScrollProgress.md) | The hook under it: `useScrollProgress(ref, { mode: 'view' \| 'pin', start, end, onChange })` → `{ get, subscribe }` |
+| [`Reveal`](doc/Reveal.md) / [`RevealGroup`](doc/RevealGroup.md) | Entrances on scroll (`fade-up`, `fade`, `scale`, `clip`, `split-words`), with `delay` / `stagger` |
+| [`LogoMarquee`](doc/LogoMarquee.md) | Endless client strip (`speed` px/s, `rows`, `fadeEdges`); the loop copy is `aria-hidden` |
+| [`CountUp`](doc/CountUp.md) / [`StatStrip`](doc/StatStrip.md) | Numbers that count up on view (`en-IN` grouping by default); the server renders the real value |
+| [`StackedCards`](doc/StackedCards.md) | Sticky cards that stack, shrink and dim, with an alternating tilt |
+| [`DeviceFrame`](doc/DeviceFrame.md) | CSS-only phone / tablet / laptop / browser mock-up |
+| [`DeviceMorphHero`](doc/DeviceMorphHero.md) | Full-bleed media that shrinks into a device, which slides aside as the copy fades in |
+| [`BentoExpandGrid`](doc/BentoExpandGrid.md) | Photo grid whose hovered or focused tile grows; a snap scroller on phones |
+| [`TestimonialSpotlight`](doc/TestimonialSpotlight.md) | Quotes beside a logo tile grid; tab-list dots, pausable autoplay |
+| [`PhotoCollage`](doc/PhotoCollage.md) / [`RotatingBadge`](doc/RotatingBadge.md) | Overlapping photos with parallax and stat chips; a turning circular text badge |
+| [`SmoothScrollProvider`](doc/SmoothScrollProvider.md) / [`useSmoothScroll`](doc/useSmoothScroll.md) | Opt-in Lenis smooth scroll (`npm install lenis`, pass `lenis={Lenis}`); `scrollTo` works either way |
+
+```jsx
+import { DeviceMorphHero, LogoMarquee, StatStrip, StackedCards } from '@dreamtree-org/twreact-ui/motion';
+
+<DeviceMorphHero media={{ video: '/intro.mp4', poster: '/intro.jpg', alt: 'Product tour' }} device="phone" content={<HeroCopy />} />
+<LogoMarquee items={['Schoo360', 'TradeOS', { src: '/acme.svg', alt: 'Acme' }]} speed={40} />
+<StatStrip items={[{ value: 500, suffix: '+', label: 'Projects' }, { value: 14, label: 'Years' }]} />
+<StackedCards items={pillars} stickyTop={80} tilt={1} scaleBack={0.95} />
+```
+
+**Server rendering and reduced motion.** The server renders every component in its final state —
+real numbers, visible text, the device beside the copy — and motion only starts after hydration.
+With `prefers-reduced-motion: reduce`, pins become normal flow, counters show the final number,
+marquees become a static wrapped row, and tilt and parallax drop to 0. Content already on screen at
+load is never hidden by `Reveal`. Scroll defaults come from the new `scroll` tokens
+(`scroll.stickyTop` 80px, `scroll.sceneLength` 300vh, `scroll.sceneLengthMobile` 150vh).
+
 ### Page blocks
 
 Page-level patterns extracted from the Dreamtree products. Build pages from these before composing layouts by hand.

package/ai-skills/dreamtree-ui.md

@@ -36,6 +36,8 @@ is not yet supported.
 npm install recharts            # React 18 apps also: npm install react-is@18
 # rich text: @dreamtree-org/twreact-ui/rich-text
 npm install @tiptap/react @tiptap/pm @tiptap/starter-kit
+# motion (scroll storytelling): @dreamtree-org/twreact-ui/motion — needs nothing;
+npm install lenis                # only for SmoothScrollProvider (optional)
 ```
 
 Apps that don't import these subpaths install and bundle nothing extra.
@@ -135,6 +137,7 @@ The library exports four kinds of things from `@dreamtree-org/twreact-ui`:
 | **Blocks**      | `AppShell`, `PageHeader`, `StatCard`, `StatusPill`, `EmptyState`, `ErrorState`, `LoadingState`, `ConfirmDialog`, `BottomActionBar` (+ `BottomActionBar.Spacer`), `ProductCard` (storefront product tile) — page-level patterns; build pages from these before composing layouts by hand |
 | **Charts** (`@dreamtree-org/twreact-ui/charts`, peer `recharts`) | `LineChart`, `BarChart`, `AreaChart`, `DonutChart`, `Sparkline`, `ScatterChart` — NOT exported from the root |
 | **Rich text** (`@dreamtree-org/twreact-ui/rich-text`, peers `@tiptap/react @tiptap/pm @tiptap/starter-kit`) | `RichTextEditor` — NOT exported from the root |
+| **Motion** (`@dreamtree-org/twreact-ui/motion`, optional peer `lenis`) | `ScrollStage`, `Reveal`, `RevealGroup`, `LogoMarquee`, `CountUp`, `StatStrip`, `StackedCards`, `DeviceFrame`, `DeviceMorphHero`, `BentoExpandGrid`, `TestimonialSpotlight`, `PhotoCollage`, `RotatingBadge`, `SmoothScrollProvider`, hooks `useScrollProgress`, `useSmoothScroll` — scroll-storytelling sections for landing pages; NOT exported from the root |
 
 ### Hooks
 
@@ -241,6 +244,7 @@ When suggesting a component or new variant value, use this exact vocabulary.
 - Haptics are opt-in: `haptics` on `Switch` / `Checkbox` (selection tick), `Sheet` (tick on a new snap point) and `ConfirmDialog` (warning on destructive open, success on confirm). Default `false`; never the only signal. For custom cues use `useHaptics().trigger('success')`.
 - Charts (`/charts`) — `<LineChart data={rows} index="month" categories={['revenue', 'costs']} />`; same shape for `BarChart` (`stacked`, `horizontal`) and `AreaChart` (`stacked`); `DonutChart` takes `index` (name key) + `category` (value key) + `centerLabel`; `Sparkline` takes `category` + `color`; `ScatterChart` takes `x` + `y` (numeric keys) plus optional `index` (entity name) and `category` (series), e.g. `<ScatterChart data={projects} x="health" y="variance" index="project" category="department" />`. Colours are tokens (`colors={['primary', 'success-600']}`), never hex. Always pass `title` (accessible name) and, for key charts, a `description` with the takeaway. `valueFormatter` formats tooltip/axis/table values.
 - `RichTextEditor` (`/rich-text`) — `label`/`error`/`helperText` like `Input`; `value` + `onChange(html)` (or `outputFormat="json"`); `toolbar={['bold', 'italic', 'link']}` to trim. Tell the user to **sanitize the HTML server-side**; never render it with `dangerouslySetInnerHTML` unsanitized.
+- Motion (`/motion`) — landing-page storytelling. `ScrollStage length={300}` pins its child while the page scrolls (CSS reads `var(--dt-p, 1)`, always with the `1` fallback = final state); `useScrollProgress(ref, { mode: 'view' | 'pin' })` for custom scenes. `Reveal effect="fade-up|fade|scale|clip|split-words"` / `RevealGroup stagger={80}` for entrances. `LogoMarquee items={['Acme', { src, alt }]} speed={40}`; `StatStrip items={[{ value: 500, suffix: '+', label: 'Projects' }]}` (or one `CountUp value`); `StackedCards items={[{ kicker, title, body, bullets, metric: { value, label }, cta, media: { src, alt } }]} tilt={1}`; `DeviceMorphHero media={{ video, poster, alt }} device="phone" content={<Copy />}`; `DeviceFrame device="browser" url="…"` for a static mock-up; `BentoExpandGrid items={[{ media: { src, alt }, title, tag, client, href }]}`; `TestimonialSpotlight items={[{ quote, name, role, logo }]}`; `PhotoCollage images chips badge={<RotatingBadge text="BRAND • SINCE 2012 • " />}`. Smooth scroll is opt-in: `import Lenis from 'lenis'` and wrap the page in `<SmoothScrollProvider lenis={Lenis}>`; `useSmoothScroll().scrollTo('#id')` works with or without it. Everything renders its final state on the server and under reduced motion — don't add your own `prefers-reduced-motion` handling, and never fake counters with "0" in the markup.
 - `Tour` — onboarding coach marks: `steps=[{ target: '[data-tour="x"]', title, content, placement }]`, `open`, `onClose(reason)`; a missing target falls back to a centred card.
 
 **Tokens:** colours are CSS variables (`--dt-primary-600`, `--dt-surface`, …) generated from
@@ -424,6 +428,18 @@ import { RichTextEditor } from '@dreamtree-org/twreact-ui/rich-text';
 <RichTextEditor label="Description" placeholder="Describe the task…" value={html} onChange={setHtml} maxHeight={320} />
 ```
 
+### Motion (optional entry point)
+
+```jsx
+import { DeviceMorphHero, LogoMarquee, StatStrip, StackedCards, Reveal } from '@dreamtree-org/twreact-ui/motion';
+
+<DeviceMorphHero media={{ video: '/intro.mp4', poster: '/intro.jpg', alt: 'Product tour' }} device="phone" content={<HeroCopy />} />
+<LogoMarquee items={clients} speed={40} />
+<StatStrip items={[{ value: 500, suffix: '+', label: 'Projects' }, { value: 14, label: 'Years' }]} />
+<Reveal as="h2" effect="split-words" className="text-page-title">What we do</Reveal>
+<StackedCards items={pillars} stickyTop={80} tilt={1} />
+```
+
 ### cn
 
 ```jsx
@@ -457,10 +473,11 @@ import { cn } from '@dreamtree-org/twreact-ui';
    `tailwind.config.js` `content[]` includes
    `./node_modules/@dreamtree-org/twreact-ui/dist/**/*.{js,mjs}`.
 6. **Don't deep-import.** The public modules are `@dreamtree-org/twreact-ui`
-   plus the two optional entry points `@dreamtree-org/twreact-ui/charts` and
-   `@dreamtree-org/twreact-ui/rich-text` (each needs its peer installed).
+   plus the optional entry points `@dreamtree-org/twreact-ui/charts`,
+   `@dreamtree-org/twreact-ui/rich-text` (each needs its peer installed) and
+   `@dreamtree-org/twreact-ui/motion` (no peer; `lenis` only for smooth scroll).
    Don't suggest `@dreamtree-org/twreact-ui/src/components/core/Button`, and
-   never import charts or `RichTextEditor` from the root.
+   never import charts, `RichTextEditor` or the motion components from the root.
 7. **React 18 only.** If the user is on React 19, warn them: this
    library has not yet been verified on React 19.
 8. **Accessibility-first.** Icon-only buttons need `aria-label`.

package/dist/_shared/{cn-DPPQUJu1.js → cn-TMJ-_w1a.js}

@@ -36,7 +36,10 @@ function _iterableToArrayLimit(r, l) {
       f = true,
       o = false;
     try {
-      if (i = (t = t.call(r)).next, 0 === l) ; else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0);
+      if (i = (t = t.call(r)).next, 0 === l) {
+        if (Object(t) !== t) return;
+        f = !1;
+      } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0);
     } catch (r) {
       o = true, n = r;
     } finally {
@@ -116,6 +119,15 @@ function _toPropertyKey(t) {
   var i = _toPrimitive(t, "string");
   return "symbol" == typeof i ? i : i + "";
 }
+function _typeof(o) {
+  "@babel/helpers - typeof";
+
+  return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) {
+    return typeof o;
+  } : function (o) {
+    return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o;
+  }, _typeof(o);
+}
 function _unsupportedIterableToArray(r, a) {
   if (r) {
     if ("string" == typeof r) return _arrayLikeToArray(r, a);
@@ -135,4 +147,5 @@ exports._objectSpread2 = _objectSpread2;
 exports._objectWithoutProperties = _objectWithoutProperties;
 exports._slicedToArray = _slicedToArray;
 exports._toConsumableArray = _toConsumableArray;
+exports._typeof = _typeof;
 exports.cn = cn;

package/dist/_shared/useLatestRef-CdtlnPUz.js

@@ -0,0 +1,21 @@
+'use strict';
+
+var React = require('react');
+
+// useLayoutEffect warns during SSR; fall back to useEffect on the server.
+var useIsomorphicLayoutEffect = typeof window !== "undefined" ? React.useLayoutEffect : React.useEffect;
+/**
+ * Internal (not exported from the package): a ref that always holds the latest
+ * `value`. Lets an effect call the newest consumer callback (e.g. `onChange`)
+ * without listing it as a dependency, so a parent passing an inline function
+ * does not re-run the effect on every render.
+ */
+function useLatestRef(value) {
+  var ref = React.useRef(value);
+  useIsomorphicLayoutEffect(function () {
+    ref.current = value;
+  });
+  return ref;
+}
+
+exports.useLatestRef = useLatestRef;

package/dist/_shared/useReducedMotion-B_PMM5ER.js

@@ -0,0 +1,77 @@
+'use strict';
+
+var React = require('react');
+
+// Internal (not exported). SSR-safe media-query subscription.
+function getMediaQueryList(query) {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return null;
+  return window.matchMedia(query) || null;
+}
+/**
+ * Subscribes `onChange` to a MediaQueryList's change events. Uses
+ * `addEventListener` where available and falls back to the deprecated
+ * `addListener` (Safari < 14). Returns the unsubscribe function.
+ */
+function subscribeMediaQuery(query, onChange) {
+  var mql = getMediaQueryList(query);
+  if (!mql) return function () {};
+  if (typeof mql.addEventListener === "function") {
+    mql.addEventListener("change", onChange);
+    return function () {
+      var _mql$removeEventListe;
+      return (_mql$removeEventListe = mql.removeEventListener) === null || _mql$removeEventListe === void 0 ? void 0 : _mql$removeEventListe.call(mql, "change", onChange);
+    };
+  }
+  if (typeof mql.addListener === "function") {
+    mql.addListener(onChange);
+    return function () {
+      var _mql$removeListener;
+      return (_mql$removeListener = mql.removeListener) === null || _mql$removeListener === void 0 ? void 0 : _mql$removeListener.call(mql, onChange);
+    };
+  }
+  return function () {};
+}
+/**
+ * `true` while `query` matches; follows changes live.
+ *
+ * On the server (and while hydrating) it returns `defaultValue`, so server and
+ * client markup agree; the real value is applied right after hydration. Without
+ * `window.matchMedia` it always returns `defaultValue`.
+ *
+ * @param {string} query - a CSS media query, e.g. "(max-width: 639px)".
+ * @param {{ defaultValue?: boolean }} [options]
+ * @returns {boolean}
+ */
+function useMediaQuery(query) {
+  var _ref = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {},
+    _ref$defaultValue = _ref.defaultValue,
+    defaultValue = _ref$defaultValue === void 0 ? false : _ref$defaultValue;
+  var subscribe = React.useCallback(function (onChange) {
+    return subscribeMediaQuery(query, onChange);
+  }, [query]);
+  var getSnapshot = function getSnapshot() {
+    var mql = getMediaQueryList(query);
+    return mql ? Boolean(mql.matches) : defaultValue;
+  };
+  var getServerSnapshot = function getServerSnapshot() {
+    return defaultValue;
+  };
+  return React.useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+
+// Internal (not exported). Shared by the charts and the overlay primitives.
+var REDUCED_MOTION_QUERY = "(prefers-reduced-motion: reduce)";
+/**
+ * `true` while the user asks the OS for reduced motion; follows changes live.
+ * `false` on the server and while hydrating, so the first render matches.
+ *
+ * @returns {boolean}
+ */
+function useReducedMotion() {
+  return useMediaQuery(REDUCED_MOTION_QUERY, {
+    defaultValue: false
+  });
+}
+
+exports.useMediaQuery = useMediaQuery;
+exports.useReducedMotion = useReducedMotion;