@timbal-ai/timbal-react 1.4.0 → 1.6.0

package/dist/site.d.ts

@@ -0,0 +1,198 @@
+import * as React from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/** Entrance styles. `mask-up` clips the child and slides it in from below. */
+type RevealVariant = "fade" | "fade-up" | "fade-down" | "fade-left" | "fade-right" | "blur" | "scale" | "mask-up";
+interface RevealProps extends React.ComponentPropsWithoutRef<"div"> {
+    /** Entrance style. Default `fade-up`. */
+    variant?: RevealVariant;
+    /** Seconds before the animation starts. */
+    delay?: number;
+    /** Animation duration in seconds. Default {@link DURATION.base}. */
+    duration?: number;
+    /** Slide distance in px for the directional + mask variants. Default 28. */
+    distance?: number;
+    /**
+     * Fraction of the element that must be visible before it animates (0–1), or
+     * `"some"` / `"all"`. Default 0.3.
+     */
+    amount?: number | "some" | "all";
+    /** Replay every time the element re-enters the viewport. Default `false`. */
+    repeat?: boolean;
+    /** Render as a different intrinsic element (e.g. `"section"`, `"li"`). */
+    as?: keyof React.JSX.IntrinsicElements;
+    children?: React.ReactNode;
+}
+/**
+ * Reveal a block when it scrolls into view. Honours `prefers-reduced-motion`
+ * (renders immediately, no transform) and SSR (no layout shift — the element
+ * occupies its space from first paint).
+ *
+ * ```tsx
+ * <Reveal variant="fade-up" delay={0.1}>
+ *   <h2>Built for the long run</h2>
+ * </Reveal>
+ * ```
+ */
+declare const Reveal: React.ForwardRefExoticComponent<RevealProps & React.RefAttributes<HTMLDivElement>>;
+
+interface TextRevealProps extends Omit<React.ComponentPropsWithoutRef<"span">, "children"> {
+    /** The text to reveal. Plain string only (split into tokens internally). */
+    children: string;
+    /** Split granularity. `words` (default) animates word-by-word; `lines` splits on `\n`. */
+    splitBy?: "words" | "lines";
+    /** Seconds between each token's entrance. Default 0.06. */
+    stagger?: number;
+    /** Seconds before the first token animates. Default 0. */
+    delay?: number;
+    /** Per-token duration in seconds. Default {@link DURATION.base}. */
+    duration?: number;
+    /** Replay every time it re-enters the viewport. Default `false`. */
+    repeat?: boolean;
+    /** Visibility fraction before animating (0–1). Default 0.4. */
+    amount?: number;
+    /** Render the wrapper as a block-level heading element instead of an inline span. */
+    as?: "span" | "h1" | "h2" | "h3" | "h4" | "p";
+}
+/**
+ * Reveal text token-by-token with a masked slide-up — the signature
+ * editorial/luxury headline entrance. Each word (or line) rides up out of an
+ * `overflow-hidden` clip on a stagger. Collapses to static text under
+ * `prefers-reduced-motion`.
+ *
+ * ```tsx
+ * <TextReveal as="h1" className="text-6xl font-semibold" stagger={0.08}>
+ *   Every step forward
+ * </TextReveal>
+ * ```
+ */
+declare function TextReveal({ children, splitBy, stagger, delay, duration, repeat, amount, as, className, ...rest }: TextRevealProps): react_jsx_runtime.JSX.Element;
+
+interface ParallaxProps extends React.ComponentPropsWithoutRef<"div"> {
+    /**
+     * Parallax strength. Positive values drift the element *slower* than scroll
+     * (it lags behind); negative values push it ahead. Roughly the fraction of
+     * the element's travel to offset. Sensible range -0.6…0.6. Default 0.2.
+     */
+    speed?: number;
+    /** Axis to translate along. Default `"y"`. */
+    axis?: "x" | "y";
+    /** Smooth the motion with a spring (avoids jitter on fast scroll). Default `true`. */
+    smooth?: boolean;
+    children?: React.ReactNode;
+}
+/**
+ * Translate a layer relative to scroll for depth. Drives off the element's own
+ * position in the viewport (no global scroll listener), so multiple parallax
+ * layers compose cheaply. No-op under `prefers-reduced-motion`.
+ *
+ * ```tsx
+ * <Parallax speed={0.3}>
+ *   <img src={hero} alt="" className="h-full w-full object-cover" />
+ * </Parallax>
+ * ```
+ */
+declare const Parallax: React.ForwardRefExoticComponent<ParallaxProps & React.RefAttributes<HTMLDivElement>>;
+
+interface MarqueeProps extends React.ComponentPropsWithoutRef<"div"> {
+    /** Scroll speed in px/second. Default 60. */
+    speed?: number;
+    /** Travel direction. Default `"left"`. */
+    direction?: "left" | "right";
+    /** Pause while hovered. Default `true`. */
+    pauseOnHover?: boolean;
+    /** Gap between the repeated content groups (any CSS length). Default `"3rem"`. */
+    gap?: string;
+    children?: React.ReactNode;
+}
+/**
+ * Seamless infinite marquee. Duplicates its children and advances a single
+ * motion value per frame, wrapping at the content width so there is no visible
+ * seam. Frame-rate independent (uses elapsed delta). Renders a static,
+ * horizontally-scrollable row under `prefers-reduced-motion`.
+ *
+ * ```tsx
+ * <Marquee speed={40} className="py-6">
+ *   {logos.map((l) => <img key={l.id} src={l.src} alt={l.name} className="h-8" />)}
+ * </Marquee>
+ * ```
+ */
+declare const Marquee: React.ForwardRefExoticComponent<MarqueeProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Shared motion tokens for the expressive `/site` layer.
+ *
+ * These are deliberately *opinionated but restrained* — the defaults produce
+ * the kind of confident, weighted motion seen on award-tier marketing sites
+ * (slow-out cubic-bezier, ~0.7–1s durations) rather than the snappy 150ms
+ * micro-interactions the app kit favours. Override per-component when a brief
+ * calls for it.
+ */
+/** Cubic-bezier easings as `[x1, y1, x2, y2]` tuples (motion's `ease` format). */
+declare const EASE: {
+    /** Strong slow-out — the workhorse for entrances and reveals. */
+    readonly out: readonly [0.16, 1, 0.3, 1];
+    /** Symmetric in-out for loops and continuous motion. */
+    readonly inOut: readonly [0.65, 0, 0.35, 1];
+    /** Gentle in-out, good for parallax / large translations. */
+    readonly soft: readonly [0.4, 0, 0.2, 1];
+};
+/** Default durations (seconds) for the expressive layer. */
+declare const DURATION: {
+    readonly fast: 0.4;
+    readonly base: 0.7;
+    readonly slow: 1.1;
+};
+/** Spring presets for pointer-driven motion (Magnetic, etc.). */
+declare const SPRING: {
+    /** Tight, responsive follow. */
+    readonly snappy: {
+        readonly stiffness: 350;
+        readonly damping: 30;
+        readonly mass: 0.4;
+    };
+    /** Looser, more elastic follow. */
+    readonly smooth: {
+        readonly stiffness: 150;
+        readonly damping: 20;
+        readonly mass: 0.6;
+    };
+};
+
+interface MagneticProps extends React.ComponentPropsWithoutRef<"div"> {
+    /** How far the element follows the pointer, as a fraction of the cursor offset. Default 0.35. */
+    strength?: number;
+    /** Max travel in px in any direction (clamps `strength` on large elements). Default 24. */
+    max?: number;
+    /** Spring feel. Default `"snappy"`. */
+    spring?: keyof typeof SPRING;
+    children?: React.ReactNode;
+}
+/**
+ * Make a child element drift toward the cursor while hovered, springing back
+ * on leave — the classic "magnetic" CTA / nav affordance. Wrap a single
+ * interactive child (button, link). No-op under `prefers-reduced-motion`.
+ *
+ * ```tsx
+ * <Magnetic strength={0.4}>
+ *   <Button>Shop the drop</Button>
+ * </Magnetic>
+ * ```
+ */
+declare const Magnetic: React.ForwardRefExoticComponent<MagneticProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Copy-paste into a workforce agent system prompt (or codegen tool context) so
+ * the model knows which expressive `/site` motion primitives exist and how to
+ * dose them — without turning every page into a motion demo.
+ *
+ * @example
+ * ```ts
+ * import { SITE_AGENT_INSTRUCTIONS } from "@timbal-ai/timbal-react/site";
+ *
+ * const systemPrompt = `${basePrompt}\n\n${SITE_AGENT_INSTRUCTIONS}`;
+ * ```
+ */
+declare const SITE_AGENT_INSTRUCTIONS: string;
+
+export { DURATION, EASE, Magnetic, type MagneticProps, Marquee, type MarqueeProps, Parallax, type ParallaxProps, Reveal, type RevealProps, type RevealVariant, SITE_AGENT_INSTRUCTIONS, SPRING, TextReveal, type TextRevealProps };

package/dist/site.esm.js

@@ -0,0 +1,23 @@
+import {
+  DURATION,
+  EASE,
+  Magnetic,
+  Marquee,
+  Parallax,
+  Reveal,
+  SITE_AGENT_INSTRUCTIONS,
+  SPRING,
+  TextReveal
+} from "./chunk-JJOO4PR5.esm.js";
+import "./chunk-EDEKQYSU.esm.js";
+export {
+  DURATION,
+  EASE,
+  Magnetic,
+  Marquee,
+  Parallax,
+  Reveal,
+  SITE_AGENT_INSTRUCTIONS,
+  SPRING,
+  TextReveal
+};