@timbal-ai/timbal-react 1.4.0 → 1.6.0

package/dist/chunk-JJOO4PR5.esm.js

@@ -0,0 +1,391 @@
+import {
+  cn
+} from "./chunk-EDEKQYSU.esm.js";
+
+// src/site/easing.ts
+var EASE = {
+  /** Strong slow-out — the workhorse for entrances and reveals. */
+  out: [0.16, 1, 0.3, 1],
+  /** Symmetric in-out for loops and continuous motion. */
+  inOut: [0.65, 0, 0.35, 1],
+  /** Gentle in-out, good for parallax / large translations. */
+  soft: [0.4, 0, 0.2, 1]
+};
+var DURATION = {
+  fast: 0.4,
+  base: 0.7,
+  slow: 1.1
+};
+var SPRING = {
+  /** Tight, responsive follow. */
+  snappy: { stiffness: 350, damping: 30, mass: 0.4 },
+  /** Looser, more elastic follow. */
+  smooth: { stiffness: 150, damping: 20, mass: 0.6 }
+};
+
+// src/site/Reveal.tsx
+import * as React from "react";
+import { motion, useReducedMotion } from "motion/react";
+import { jsx } from "react/jsx-runtime";
+function hidden(variant, distance) {
+  switch (variant) {
+    case "fade":
+      return { opacity: 0 };
+    case "fade-up":
+      return { opacity: 0, y: distance };
+    case "fade-down":
+      return { opacity: 0, y: -distance };
+    case "fade-left":
+      return { opacity: 0, x: distance };
+    case "fade-right":
+      return { opacity: 0, x: -distance };
+    case "blur":
+      return { opacity: 0, filter: "blur(12px)" };
+    case "scale":
+      return { opacity: 0, scale: 0.94 };
+    case "mask-up":
+      return { y: "110%" };
+  }
+}
+function shown(variant) {
+  if (variant === "mask-up") return { y: "0%" };
+  if (variant === "blur") return { opacity: 1, filter: "blur(0px)" };
+  if (variant === "scale") return { opacity: 1, scale: 1 };
+  return { opacity: 1, x: 0, y: 0 };
+}
+var Reveal = React.forwardRef(function Reveal2({
+  variant = "fade-up",
+  delay = 0,
+  duration = DURATION.base,
+  distance = 28,
+  amount = 0.3,
+  repeat = false,
+  as = "div",
+  className,
+  children,
+  ...rest
+}, ref) {
+  const reduce = useReducedMotion();
+  const isMask = variant === "mask-up";
+  if (reduce) {
+    const Tag = as;
+    return /* @__PURE__ */ jsx(Tag, { ref, className: cn(isMask && "overflow-hidden", className), ...rest, children });
+  }
+  const variants = {
+    hidden: hidden(variant, distance),
+    shown: shown(variant)
+  };
+  const MotionTag = motion[as] ?? motion.div;
+  const inner = /* @__PURE__ */ jsx(
+    MotionTag,
+    {
+      ref,
+      className,
+      variants,
+      initial: "hidden",
+      whileInView: "shown",
+      viewport: { once: !repeat, amount },
+      transition: { duration, delay, ease: EASE.out },
+      ...rest,
+      children
+    }
+  );
+  if (isMask) {
+    return /* @__PURE__ */ jsx("span", { className: "block overflow-hidden", children: inner });
+  }
+  return inner;
+});
+
+// src/site/TextReveal.tsx
+import * as React2 from "react";
+import { motion as motion2, useReducedMotion as useReducedMotion2 } from "motion/react";
+import { jsx as jsx2 } from "react/jsx-runtime";
+var tokenVariants = {
+  hidden: { y: "115%" },
+  shown: { y: "0%" }
+};
+function TextReveal({
+  children,
+  splitBy = "words",
+  stagger = 0.06,
+  delay = 0,
+  duration = DURATION.base,
+  repeat = false,
+  amount = 0.4,
+  as = "span",
+  className,
+  ...rest
+}) {
+  const reduce = useReducedMotion2();
+  const Tag = as;
+  const tokens = React2.useMemo(() => {
+    if (splitBy === "lines") return children.split("\n");
+    return children.split(/(\s+)/).filter((t) => t.length > 0);
+  }, [children, splitBy]);
+  if (reduce) {
+    return /* @__PURE__ */ jsx2(Tag, { className, ...rest, children });
+  }
+  const containerVariants = {
+    hidden: {},
+    shown: { transition: { staggerChildren: stagger, delayChildren: delay } }
+  };
+  return /* @__PURE__ */ jsx2(
+    motion2.span,
+    {
+      variants: containerVariants,
+      initial: "hidden",
+      whileInView: "shown",
+      viewport: { once: !repeat, amount },
+      className: cn(as === "span" ? "inline" : "block", className),
+      ...rest,
+      children: /* @__PURE__ */ jsx2(Tag, { className: as === "span" ? "inline" : "block", children: tokens.map(
+        (token, i) => /^\s+$/.test(token) && splitBy === "words" ? /* @__PURE__ */ jsx2("span", { children: " " }, i) : /* @__PURE__ */ jsx2(
+          "span",
+          {
+            className: cn(
+              "overflow-hidden",
+              splitBy === "lines" ? "block" : "inline-block align-bottom"
+            ),
+            children: /* @__PURE__ */ jsx2(
+              motion2.span,
+              {
+                className: "inline-block",
+                variants: tokenVariants,
+                transition: { duration, ease: EASE.out },
+                children: token
+              }
+            )
+          },
+          i
+        )
+      ) })
+    }
+  );
+}
+
+// src/site/Parallax.tsx
+import * as React3 from "react";
+import {
+  motion as motion3,
+  useReducedMotion as useReducedMotion3,
+  useScroll,
+  useSpring,
+  useTransform
+} from "motion/react";
+import { jsx as jsx3 } from "react/jsx-runtime";
+var Parallax = React3.forwardRef(function Parallax2({ speed = 0.2, axis = "y", smooth = true, className, children, style, ...rest }, forwardedRef) {
+  const reduce = useReducedMotion3();
+  const innerRef = React3.useRef(null);
+  React3.useImperativeHandle(forwardedRef, () => innerRef.current);
+  const { scrollYProgress } = useScroll({
+    target: innerRef,
+    offset: ["start end", "end start"]
+  });
+  const range = 100 * speed;
+  const raw = useTransform(scrollYProgress, [0, 1], [range, -range]);
+  const smoothed = useSpring(raw, { stiffness: 120, damping: 30, mass: 0.4 });
+  const value = smooth ? smoothed : raw;
+  if (reduce) {
+    return /* @__PURE__ */ jsx3("div", { ref: innerRef, className, style, ...rest, children });
+  }
+  return /* @__PURE__ */ jsx3(
+    motion3.div,
+    {
+      ref: innerRef,
+      className: cn("will-change-transform", className),
+      style: { ...style, [axis]: value },
+      ...rest,
+      children
+    }
+  );
+});
+
+// src/site/Marquee.tsx
+import * as React4 from "react";
+import {
+  motion as motion4,
+  useAnimationFrame,
+  useMotionValue,
+  useReducedMotion as useReducedMotion4
+} from "motion/react";
+import { jsx as jsx4, jsxs } from "react/jsx-runtime";
+var Marquee = React4.forwardRef(function Marquee2({ speed = 60, direction = "left", pauseOnHover = true, gap = "3rem", className, children, ...rest }, ref) {
+  const reduce = useReducedMotion4();
+  const x = useMotionValue(0);
+  const setWidthRef = React4.useRef(0);
+  const groupRef = React4.useRef(null);
+  const [paused, setPaused] = React4.useState(false);
+  React4.useEffect(() => {
+    const el = groupRef.current;
+    if (!el) return;
+    const measure = () => {
+      const gapPx = parseFloat(getComputedStyle(el.parentElement).columnGap || "0") || 0;
+      setWidthRef.current = el.offsetWidth + gapPx;
+    };
+    measure();
+    const ro = new ResizeObserver(measure);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+  useAnimationFrame((_, delta) => {
+    if (reduce || paused || setWidthRef.current === 0) return;
+    const dir = direction === "left" ? -1 : 1;
+    const moveBy = speed * delta / 1e3;
+    let next = x.get() + dir * moveBy;
+    const w = setWidthRef.current;
+    if (next <= -w) next += w;
+    else if (next >= w) next -= w;
+    x.set(next);
+  });
+  if (reduce) {
+    return /* @__PURE__ */ jsx4(
+      "div",
+      {
+        ref,
+        className: cn("flex w-full items-center overflow-x-auto", className),
+        style: { columnGap: gap },
+        ...rest,
+        children
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx4(
+    "div",
+    {
+      ref,
+      className: cn("w-full overflow-hidden", className),
+      onMouseEnter: pauseOnHover ? () => setPaused(true) : void 0,
+      onMouseLeave: pauseOnHover ? () => setPaused(false) : void 0,
+      ...rest,
+      children: /* @__PURE__ */ jsxs(motion4.div, { className: "flex w-max flex-nowrap items-center", style: { x, columnGap: gap }, children: [
+        /* @__PURE__ */ jsx4("div", { ref: groupRef, className: "flex flex-nowrap items-center", style: { columnGap: gap }, children }),
+        /* @__PURE__ */ jsx4("div", { className: "flex flex-nowrap items-center", style: { columnGap: gap }, "aria-hidden": true, children })
+      ] })
+    }
+  );
+});
+
+// src/site/Magnetic.tsx
+import * as React5 from "react";
+import { motion as motion5, useMotionValue as useMotionValue2, useReducedMotion as useReducedMotion5, useSpring as useSpring2 } from "motion/react";
+import { jsx as jsx5 } from "react/jsx-runtime";
+var Magnetic = React5.forwardRef(function Magnetic2({ strength = 0.35, max = 24, spring = "snappy", className, children, ...rest }, forwardedRef) {
+  const reduce = useReducedMotion5();
+  const innerRef = React5.useRef(null);
+  React5.useImperativeHandle(forwardedRef, () => innerRef.current);
+  const mvx = useMotionValue2(0);
+  const mvy = useMotionValue2(0);
+  const x = useSpring2(mvx, SPRING[spring]);
+  const y = useSpring2(mvy, SPRING[spring]);
+  const clamp = (v) => Math.max(-max, Math.min(max, v));
+  function handleMove(e) {
+    if (reduce) return;
+    const el = innerRef.current;
+    if (!el) return;
+    const rect = el.getBoundingClientRect();
+    const cx = rect.left + rect.width / 2;
+    const cy = rect.top + rect.height / 2;
+    mvx.set(clamp((e.clientX - cx) * strength));
+    mvy.set(clamp((e.clientY - cy) * strength));
+  }
+  function reset() {
+    mvx.set(0);
+    mvy.set(0);
+  }
+  if (reduce) {
+    return /* @__PURE__ */ jsx5("div", { ref: innerRef, className: cn("inline-block", className), ...rest, children });
+  }
+  return /* @__PURE__ */ jsx5(
+    motion5.div,
+    {
+      ref: innerRef,
+      className: cn("inline-block", className),
+      style: { x, y },
+      onMouseMove: handleMove,
+      onMouseLeave: reset,
+      ...rest,
+      children
+    }
+  );
+});
+
+// src/site/agent-instructions.ts
+var SITE_AGENT_INSTRUCTIONS = `
+## Site kit (@timbal-ai/timbal-react/site)
+
+Expressive **motion & interaction primitives** for marketing, brand, landing, and editorial pages \u2014 the counterpart to \`/app\` (which is for dashboards and operations UIs). Import from \`@timbal-ai/timbal-react/site\` (or the package root).
+
+These are **mechanics, not art direction**: they animate whatever you put inside them. Compose them under a chosen aesthetic; they do not impose colors, type, or layout.
+
+### When to use \`/site\` (and when not to)
+
+- **Do** use \`/site\` for landing pages, hero sections, feature walkthroughs, logo walls, pricing pages, and editorial/brand storytelling.
+- **Do not** use \`/site\` inside dashboards, settings, tables, or in-thread chat artifacts \u2014 those stay on \`/app\` and \`/artifacts\`. Animated dashboard chrome reads as slop.
+- Every primitive is **reduced-motion-aware** (collapses to static, no-transform output under \`prefers-reduced-motion\`) and **SSR-safe** (no layout shift \u2014 elements occupy their space from first paint). You never need to guard them yourself.
+- Built on the \`motion\` engine the package already bundles \u2014 **no extra dependencies**.
+
+### Dosing (anti-overuse \u2014 read this)
+
+The failure mode is animating *everything*. Restraint is the brand signal.
+
+- Pick **one** signature motion per section (e.g. a \`TextReveal\` headline **or** a \`Parallax\` hero image, not both stacked).
+- Stagger entrances down the page; do not fire ten reveals at once on first paint.
+- Reserve \`Magnetic\` for **primary** CTAs / nav, not every button.
+- Keep \`Parallax\` \`speed\` subtle (\`0.15\`\u2013\`0.35\`); large values look gimmicky.
+- Default durations are intentionally slow and weighted (\`DURATION.base\` = 0.7s) \u2014 that confident pacing is the point. Don't speed everything up to app-kit's 150ms.
+
+### Component menu
+
+| Component | Use for | Key props |
+|-----------|---------|-----------|
+| \`Reveal\` | Fade/slide a block in as it scrolls into view (headings, cards, images, list items). | \`variant\` (\`fade\` \\| \`fade-up\` \\| \`fade-down\` \\| \`fade-left\` \\| \`fade-right\` \\| \`blur\` \\| \`scale\` \\| \`mask-up\`, default \`fade-up\`), \`delay\`, \`duration\`, \`distance\` (px, default 28), \`amount\` (visibility fraction 0\u20131 / \`"some"\` / \`"all"\`, default 0.3), \`repeat\` (replay on re-enter), \`as\` (render element, e.g. \`"section"\`/\`"li"\`). |
+| \`TextReveal\` | Signature editorial headline entrance \u2014 text rides up token-by-token from a clip on a stagger. | \`children\` (**plain string only**), \`splitBy\` (\`words\` default \\| \`lines\`), \`stagger\` (default 0.06), \`delay\`, \`duration\`, \`amount\` (default 0.4), \`repeat\`, \`as\` (\`span\` default \\| \`h1\`\u2013\`h4\` \\| \`p\`). |
+| \`Parallax\` | Depth \u2014 translate a layer relative to scroll (hero images, background art). | \`speed\` (-0.6\u20260.6, positive = lags behind scroll, default 0.2), \`axis\` (\`y\` default \\| \`x\`), \`smooth\` (spring-damped, default true). |
+| \`Marquee\` | Seamless infinite scrolling row (logo walls, testimonials, ticker). Duplicates children internally \u2014 no visible seam. | \`speed\` (px/s, default 60), \`direction\` (\`left\` default \\| \`right\`), \`pauseOnHover\` (default true), \`gap\` (CSS length, default \`"3rem"\`). |
+| \`Magnetic\` | Pointer-following "magnetic" affordance for a **single** interactive child (primary CTA, nav link). | \`strength\` (fraction of cursor offset, default 0.35), \`max\` (px clamp, default 24), \`spring\` (\`"snappy"\` default \\| \`"smooth"\`). Wrap one button/link. |
+
+### Motion tokens
+
+\`EASE\` (cubic-bezier tuples: \`out\` / \`inOut\` / \`soft\`), \`DURATION\` (\`fast\` 0.4s / \`base\` 0.7s / \`slow\` 1.1s), and \`SPRING\` (\`snappy\` / \`smooth\`) are exported for custom \`motion\` work that should match the kit's feel. Prefer the component defaults; reach for tokens only when hand-rolling a bespoke animation.
+
+### Example imports
+
+\`\`\`tsx
+import { Reveal, TextReveal, Parallax, Marquee, Magnetic } from "@timbal-ai/timbal-react/site";
+\`\`\`
+
+\`\`\`tsx
+<Reveal variant="fade-up" delay={0.1}>
+  <TextReveal as="h1" className="text-6xl font-semibold">
+    Built for the long run
+  </TextReveal>
+</Reveal>
+
+<Parallax speed={0.3}>
+  <img src={hero} alt="" className="h-full w-full object-cover" />
+</Parallax>
+
+<Magnetic strength={0.4}>
+  <Button>Get started</Button>
+</Magnetic>
+\`\`\`
+
+### Rules
+
+- \`/site\` is for the **marketing/brand surface**, not the product app shell (\`/app\`) or in-chat widgets (\`/artifacts\`).
+- \`TextReveal\` takes a **string** child only \u2014 it splits internally; do not pass JSX.
+- \`Magnetic\` wraps a **single** interactive child; don't wrap whole layouts.
+- Trust the reduced-motion / SSR handling \u2014 never add your own \`prefers-reduced-motion\` guards around these.
+`.trim();
+
+export {
+  EASE,
+  DURATION,
+  SPRING,
+  Reveal,
+  TextReveal,
+  Parallax,
+  Marquee,
+  Magnetic,
+  SITE_AGENT_INSTRUCTIONS
+};