app-studio 0.7.1 → 0.7.2

package/dist/stories/ScrollAnimation.stories.d.ts

@@ -1,19 +1,51 @@
 import React from 'react';
 import { ComponentStory } from '@storybook/react';
 import { View } from '../src/index';
-declare const FillTextDemo: React.FC;
-declare const _default: import("@storybook/types").ComponentAnnotations<import("@storybook/react/dist/types-0fc72a6d").R, {
-    children?: React.ReactNode;
-}>;
+declare const _default: import("@storybook/types").ComponentAnnotations<import("@storybook/react/dist/types-0fc72a6d").R, import("../src").ElementProps & React.RefAttributes<HTMLElement> & import("../src").ViewProps>;
 export default _default;
-export declare const FillTextScrollStory: ComponentStory<typeof FillTextDemo>;
+/**
+ * Demonstrates the useScrollAnimation hook with various configurations.
+ * This hook uses IntersectionObserver to track element visibility and progress.
+ */
+export declare const UseScrollAnimationHook: ComponentStory<typeof View>;
+/**
+ * Demonstrates the useScroll hook for tracking scroll position and progress.
+ */
+export declare const UseScrollHook: ComponentStory<typeof View>;
+/**
+ * Demonstrates the useScrollDirection hook.
+ */
+export declare const UseScrollDirectionHook: ComponentStory<typeof View>;
+/**
+ * Demonstrates the useSmoothScroll hook for programmatic smooth scrolling.
+ */
+export declare const UseSmoothScrollHook: ComponentStory<typeof View>;
 /**
  * CSS View Timeline Animations - Pure CSS, no JavaScript state!
- * These animations now work by default with animate prop (animateOn="Both" is default).
  */
-export declare const ViewTimelineAnimations: ComponentStory<typeof View>;
+export declare const CSSViewTimelineAnimations: ComponentStory<typeof View>;
 /**
  * Entry + Exit animations combined
  */
 export declare const EntryExitAnimations: ComponentStory<typeof View>;
-export declare const AnimatedComponent: React.FC;
+/**
+ * Scroll-driven text fill animation
+ */
+export declare const ScrollDrivenTextFill: ComponentStory<typeof View>;
+/**
+ * FillText Examples - Using App-Studio's Theming System
+ *
+ * This story demonstrates FillText scroll animations integrated with App-Studio's
+ * color system. Colors use CSS variables for theme-awareness:
+ *
+ * - Palette colors: var(--color-blue-500), var(--color-emerald-500)
+ * - Alpha transparency: color-mix(in srgb, var(--color-blue-500) 20%, transparent)
+ * - Background colors: color.slate.900, color.emerald.950, etc.
+ *
+ * See docs/Theming.md for the complete color reference.
+ */
+export declare const FillTextExamples: ComponentStory<typeof View>;
+/**
+ * All scroll-driven animation presets
+ */
+export declare const ScrollDrivenAnimationPresets: ComponentStory<typeof View>;

package/docs/Animation.md

@@ -189,6 +189,294 @@ These animations are linked to the scroll position associated with a timeline (u
 <View animate={Animation.fadeInScroll()} />
 ```
 
+### Custom Scroll Timeline with `animate.timeline`
+
+For fine-grained control over scroll-driven animations, use the `animate` prop with `timeline` and `keyframes`:
+
+```jsx
+import { View, Vertical, Text } from 'app-studio';
+
+function ScrollProgressBar() {
+  return (
+    <Vertical gap={20} padding={20} height="100vh">
+      <Text fontSize={24} fontWeight="bold">
+        Scroll Timeline Animation
+      </Text>
+      <Text>Scroll down to see the progress bar animate.</Text>
+
+      {/* Scroll container */}
+      <View
+        height={300}
+        overflow="auto"
+        border="1px solid #ccc"
+        padding={20}
+        position="relative"
+      >
+        {/* Progress Bar - sticks to top of container */}
+        <View
+          position="sticky"
+          top={0}
+          width="100%"
+          height={8}
+          backgroundColor="#ddd"
+          zIndex={10}
+        >
+          {/* Animated progress fill */}
+          <View
+            height="100%"
+            backgroundColor="color.blue.500"
+            width="0%"
+            animate={{
+              timeline: 'scroll()',
+              keyframes: {
+                from: { width: '0%' },
+                to: { width: '100%' },
+              },
+            }}
+          />
+        </View>
+
+        {/* Scrollable content */}
+        <Vertical gap={50} paddingVertical={50}>
+          {[1, 2, 3, 4, 5].map((i) => (
+            <View key={i} padding={20} backgroundColor="#f5f5f5" borderRadius={8}>
+              Item {i}
+            </View>
+          ))}
+        </Vertical>
+      </View>
+    </Vertical>
+  );
+}
+```
+
+**Timeline Options:**
+
+| Timeline | Description |
+|----------|-------------|
+| `scroll()` | Links animation to the nearest scrollable ancestor's scroll progress |
+| `scroll(root)` | Links to the root (viewport) scroll progress |
+| `view()` | Links to element's visibility in the viewport (entry/exit) |
+
+**Keyframe Properties:**
+
+You can animate any CSS property between `from` and `to` states, or use percentage keyframes for more control:
+
+```jsx
+animate={{
+  timeline: 'scroll()',
+  keyframes: {
+    '0%': { opacity: 0, transform: 'translateY(20px)' },
+    '50%': { opacity: 1, transform: 'translateY(0)' },
+    '100%': { opacity: 0.5, transform: 'translateY(-10px)' },
+  },
+}}
+```
+
+See the [ScrollTimeline Story](../stories/ScrollTimeline.stories.tsx) for a complete example.
+
+### FillText Scroll Animation with Theming
+
+The `fillTextScroll()` animation creates a text reveal effect that fills as the user scrolls. It integrates with App-Studio's theming system using CSS variables.
+
+#### Basic Usage
+
+```jsx
+import { View, Animation } from 'app-studio';
+
+<View
+  as="span"
+  fontSize={48}
+  fontWeight="bold"
+  color="color.gray.500"
+  backgroundClip="text"
+  animate={Animation.fillTextScroll({
+    duration: '1s',
+    timingFunction: 'linear',
+    timeline: '--section',
+    range: 'entry 100% cover 55%',
+  })}
+>
+  Text that fills as you scroll
+</View>
+```
+
+#### Theme-Aware FillText with CSS Variables
+
+For full theme integration, use CSS variables from the theming system. This ensures colors adapt to light/dark mode:
+
+```jsx
+import { View, Text } from 'app-studio';
+import { Animation } from 'app-studio';
+
+function ThemedFillText({ children, color = 'blue' }) {
+  // Map palette names to CSS variables
+  const colors = {
+    blue: {
+      fill: 'var(--color-blue-500)',
+      accent: 'var(--color-blue-400)',
+      base: 'color-mix(in srgb, var(--color-blue-500) 15%, transparent)',
+      underline: 'color-mix(in srgb, var(--color-blue-500) 20%, transparent)',
+    },
+    emerald: {
+      fill: 'var(--color-emerald-500)',
+      accent: 'var(--color-emerald-400)',
+      base: 'color-mix(in srgb, var(--color-emerald-500) 12%, transparent)',
+      underline: 'color-mix(in srgb, var(--color-emerald-500) 20%, transparent)',
+    },
+    violet: {
+      fill: 'var(--color-violet-500)',
+      accent: 'var(--color-violet-400)',
+      base: 'color-mix(in srgb, var(--color-violet-500) 10%, transparent)',
+      underline: 'color-mix(in srgb, var(--color-violet-500) 20%, transparent)',
+    },
+  };
+
+  const { fill, accent, base, underline } = colors[color] || colors.blue;
+
+  return (
+    <View
+      as="span"
+      fontSize={48}
+      fontWeight="bold"
+      css={`
+        color: ${base};
+        --fill-color: ${fill};
+        --accent: ${accent};
+        --underline-color: ${underline};
+        --underline-block-width: 200vmax;
+        --underline-width: 100%;
+      `}
+      backgroundImage={`
+        linear-gradient(90deg, transparent calc(100% - 1ch), var(--accent) calc(100% - 1ch)),
+        linear-gradient(90deg, var(--fill-color), var(--fill-color)),
+        linear-gradient(90deg, var(--underline-color), var(--underline-color))`}
+      backgroundSize={`
+        var(--underline-block-width) var(--underline-width),
+        var(--underline-block-width) var(--underline-width),
+        100% var(--underline-width)`}
+      backgroundRepeat="no-repeat"
+      backgroundPositionX="0"
+      backgroundPositionY="100%"
+      backgroundClip="text"
+      animate={Animation.fillTextScroll({
+        duration: '1s',
+        timingFunction: 'linear',
+      })}
+    >
+      {children}
+    </View>
+  );
+}
+
+// Usage with different color palettes
+<ThemedFillText color="blue">Blue themed text</ThemedFillText>
+<ThemedFillText color="emerald">Emerald themed text</ThemedFillText>
+<ThemedFillText color="violet">Violet themed text</ThemedFillText>
+```
+
+#### Using Color Palettes
+
+All App-Studio color palettes work with FillText. Reference them via CSS variables:
+
+| Palette | Fill Variable | Accent Variable |
+|---------|--------------|-----------------|
+| Blue | `var(--color-blue-500)` | `var(--color-blue-400)` |
+| Emerald | `var(--color-emerald-500)` | `var(--color-emerald-400)` |
+| Violet | `var(--color-violet-500)` | `var(--color-violet-400)` |
+| Amber | `var(--color-amber-500)` | `var(--color-amber-400)` |
+| Rose | `var(--color-rose-500)` | `var(--color-rose-400)` |
+| Cyan | `var(--color-cyan-500)` | `var(--color-cyan-400)` |
+| Gray (light bg) | `var(--color-gray-800)` | `var(--color-gray-900)` |
+
+#### Alpha Transparency with `color-mix()`
+
+For semi-transparent colors that remain theme-aware, use `color-mix()`:
+
+```jsx
+// 15% opacity blue
+baseColor="color-mix(in srgb, var(--color-blue-500) 15%, transparent)"
+
+// 20% opacity emerald
+underlineColor="color-mix(in srgb, var(--color-emerald-500) 20%, transparent)"
+
+// 70% opacity white
+fillColor="color-mix(in srgb, var(--color-white) 70%, transparent)"
+```
+
+#### Complete Section Example
+
+Here's a complete FillText section with view-timeline:
+
+```jsx
+function FillTextSection() {
+  return (
+    <View
+      css={`
+        @supports (animation-timeline: scroll()) {
+          @media (prefers-reduced-motion: no-preference) {
+            view-timeline-name: --hero-section;
+          }
+        }
+      `}
+      backgroundColor="color.slate.900"
+    >
+      <View height="50vh" />
+      <View as="main" height="200vh">
+        <View
+          as="section"
+          position="sticky"
+          top="0"
+          height="100vh"
+          display="grid"
+          placeItems="center"
+        >
+          <View padding="5ch" textAlign="center" maxWidth={1200}>
+            <View
+              as="span"
+              fontSize={56}
+              fontWeight="bold"
+              css={`
+                color: color-mix(in srgb, var(--color-blue-500) 15%, transparent);
+                --fill-color: var(--color-blue-500);
+                --accent: var(--color-blue-400);
+                --underline-color: color-mix(in srgb, var(--color-blue-500) 20%, transparent);
+                --underline-block-width: 200vmax;
+                --underline-width: 100%;
+              `}
+              backgroundImage={`
+                linear-gradient(90deg, transparent calc(100% - 1ch), var(--accent) calc(100% - 1ch)),
+                linear-gradient(90deg, var(--fill-color), var(--fill-color)),
+                linear-gradient(90deg, var(--underline-color), var(--underline-color))`}
+              backgroundSize={`
+                var(--underline-block-width) var(--underline-width),
+                var(--underline-block-width) var(--underline-width),
+                100% var(--underline-width)`}
+              backgroundRepeat="no-repeat"
+              backgroundPositionX="0"
+              backgroundPositionY="100%"
+              backgroundClip="text"
+              animate={Animation.fillTextScroll({
+                duration: '1s',
+                timingFunction: 'linear',
+                timeline: '--hero-section',
+                range: 'entry 100% cover 55%, cover 50% exit 0%',
+              })}
+            >
+              Build beautiful scroll-driven animations with pure CSS.
+            </View>
+          </View>
+        </View>
+      </View>
+    </View>
+  );
+}
+```
+
+See [docs/Theming.md](./Theming.md) for the complete color palette reference.
+
+See the [FillText Examples Story](../stories/ScrollAnimation.stories.tsx) for interactive demos with all color themes.
+
 ## 7. Event-Based Animations
 
 You can trigger animations on interactions like hover, click, or focus using the `on` prop or underscore props (`_hover`, `_active`).

package/docs/Hooks.md

@@ -2,11 +2,19 @@
 
 App-Studio provides a comprehensive set of React hooks to help you build interactive and responsive applications. This guide covers all the available hooks and their usage.
 
+## Iframe Support
+
+Many hooks in App-Studio support working inside iframes for micro-frontend architectures, preview environments, and embedded widgets.
+
+**Supported hooks:** `useScroll`, `useScrollAnimation`, `useScrollDirection`, `useSmoothScroll`, `useClickOutside`, plus `ResponsiveProvider` and `WindowSizeProvider`.
+
+See the dedicated [Iframe Support Guide](./IframeSupport.md) for complete documentation and examples.
+
 ## Scroll Hooks
 
 ### useScroll
 
-A hook that tracks scroll position and progress for a container or window.
+A hook that tracks scroll position and progress for a container or window. Supports tracking scroll inside iframes.
 
 ```tsx
 import { useScroll } from 'app-studio';
@@ -27,17 +35,57 @@ function MyComponent() {
 }
 ```
 
+#### Tracking Scroll Inside an Iframe
+
+When you pass an `HTMLIFrameElement` reference to the `container` option, `useScroll` automatically detects the iframe context and tracks scroll within the iframe's window:
+
+```tsx
+import { useScroll } from 'app-studio';
+
+function IframeScrollTracker() {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+
+  // Pass the iframe ref - useScroll will track the iframe's scroll position
+  const scrollPosition = useScroll({
+    container: iframeRef,
+    throttleMs: 50
+  });
+
+  return (
+    <div>
+      <p>Iframe Scroll Y: {Math.round(scrollPosition.y)}px</p>
+      <p>Iframe Scroll Progress: {Math.round(scrollPosition.yProgress * 100)}%</p>
+      <iframe
+        ref={iframeRef}
+        src="/your-iframe-content"
+        style={{ width: '100%', height: '400px' }}
+      />
+    </div>
+  );
+}
+```
+
 **Options:**
 
-- `container`: Reference to the scrollable container (optional, defaults to window)
-- `target`: Reference to the target element (optional)
-- `offset`: X and Y offset values (optional, defaults to [0, 0])
-- `throttleMs`: Throttle interval in milliseconds (optional, defaults to 100)
-- `disabled`: Whether to disable the hook (optional, defaults to false)
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `container` | `RefObject<HTMLElement>` | window | Reference to the scrollable container. If an `HTMLIFrameElement` is passed, tracks the iframe's content scroll. |
+| `offset` | `[number, number]` | `[0, 0]` | X and Y offset values to add to scroll position |
+| `throttleMs` | `number` | `100` | Throttle interval in milliseconds for performance |
+| `disabled` | `boolean` | `false` | Whether to disable scroll tracking |
+
+**Returns:** `ScrollPosition`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `x` | `number` | Horizontal scroll position in pixels |
+| `y` | `number` | Vertical scroll position in pixels |
+| `xProgress` | `number` | Horizontal scroll progress (0 to 1) |
+| `yProgress` | `number` | Vertical scroll progress (0 to 1) |
 
 ### useScrollDirection
 
-A hook that detects scroll direction.
+A hook that detects scroll direction. Supports tracking direction inside iframes via the `targetWindow` parameter.
 
 ```tsx
 import { useScrollDirection } from 'app-studio';
@@ -53,13 +101,35 @@ function ScrollDirectionComponent() {
 }
 ```
 
+#### With Iframe Support
+
+```tsx
+import { useScrollDirection } from 'app-studio';
+
+function IframeScrollDirection({ iframeWindow }: { iframeWindow: Window }) {
+  // Track scroll direction inside an iframe
+  const scrollDirection = useScrollDirection(5, iframeWindow);
+
+  return (
+    <div>
+      Iframe scroll direction: {scrollDirection}
+    </div>
+  );
+}
+```
+
 **Parameters:**
 
-- `threshold`: Minimum scroll distance in pixels before direction change is detected (optional, defaults to 0)
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `threshold` | `number` | `5` | Minimum scroll distance in pixels before direction change is detected |
+| `targetWindow` | `Window` | `window` | Target window to track (use `iframe.contentWindow` for iframe support) |
+
+**Returns:** `'up' | 'down'`
 
 ### useSmoothScroll
 
-A hook that provides smooth scrolling functionality to elements.
+A hook that provides smooth scrolling functionality to elements. Supports scrolling inside iframes via the `targetWindow` parameter.
 
 ```tsx
 import { useSmoothScroll } from 'app-studio';
@@ -79,9 +149,42 @@ function SmoothScrollComponent() {
 }
 ```
 
+#### With Iframe Support
+
+```tsx
+import { useSmoothScroll } from 'app-studio';
+
+function IframeSmoothScroll({ iframeWindow }: { iframeWindow: Window }) {
+  // Smooth scroll inside an iframe
+  const scrollTo = useSmoothScroll(iframeWindow);
+  const targetRef = useRef<HTMLDivElement>(null);
+
+  return (
+    <>
+      <button onClick={() => scrollTo(targetRef.current, 80)}>
+        Scroll to Section in Iframe
+      </button>
+      <div ref={targetRef}>Target Section</div>
+    </>
+  );
+}
+```
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `targetWindow` | `Window` | `window` | Target window to scroll (use `iframe.contentWindow` for iframe support) |
+
+**Returns:** `(element: HTMLElement | null, offset?: number) => void`
+
+The returned function accepts:
+- `element`: The element to scroll to
+- `offset`: Optional offset from the top in pixels (default: 0)
+
 ### useScrollAnimation
 
-A hook for creating scroll-linked animations using Intersection Observer.
+A hook for creating scroll-linked animations using Intersection Observer. Supports automatic iframe detection and explicit `targetWindow` for cross-window observation.
 
 ```tsx
 import { useScrollAnimation } from 'app-studio';
@@ -101,6 +204,98 @@ function ScrollAnimationComponent() {
 }
 ```
 
+#### With Multiple Thresholds
+
+Use an array of thresholds to get granular progress updates:
+
+```tsx
+import { useScrollAnimation } from 'app-studio';
+
+function AnimatedSection({ index }: { index: number }) {
+  const sectionRef = useRef<HTMLDivElement>(null);
+
+  const { isInView, progress } = useScrollAnimation(sectionRef, {
+    threshold: [0, 0.25, 0.5, 0.75, 1], // Fire at each 25% visibility
+  });
+
+  return (
+    <div
+      ref={sectionRef}
+      style={{
+        opacity: 0.3 + progress * 0.7,
+        transform: `scale(${0.85 + progress * 0.15})`,
+        transition: 'opacity 0.4s, transform 0.4s',
+      }}
+    >
+      <span>{isInView ? '✓ In View' : '○ Out of View'}</span>
+      <span>Progress: {(progress * 100).toFixed(0)}%</span>
+    </div>
+  );
+}
+```
+
+#### With Iframe Support
+
+The hook automatically detects when elements are inside an iframe and uses the correct `IntersectionObserver`. You can also explicitly pass `targetWindow`:
+
+```tsx
+import { useScrollAnimation } from 'app-studio';
+
+function IframeAnimatedSection({ targetWindow }: { targetWindow?: Window }) {
+  const sectionRef = useRef<HTMLDivElement>(null);
+
+  // Auto-detect iframe context or use explicit targetWindow
+  const { isInView, progress } = useScrollAnimation(sectionRef, {
+    threshold: [0, 0.25, 0.5, 0.75, 1],
+    targetWindow, // Optional: explicitly set the iframe's window
+  });
+
+  return (
+    <div
+      ref={sectionRef}
+      style={{
+        opacity: 0.3 + progress * 0.7,
+        background: isInView ? '#e8f5e9' : '#f5f5f5',
+      }}
+    >
+      Progress: {(progress * 100).toFixed(0)}%
+    </div>
+  );
+}
+```
+
+#### With Callback
+
+Use the `onIntersectionChange` callback for custom logic:
+
+```tsx
+const { isInView, progress } = useScrollAnimation(ref, {
+  threshold: 0.5,
+  onIntersectionChange: (isIntersecting, ratio) => {
+    if (isIntersecting) {
+      analytics.track('section_viewed', { visibility: ratio });
+    }
+  },
+});
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `threshold` | `number \| number[]` | `0` | Visibility threshold(s) to trigger updates (0-1) |
+| `rootMargin` | `string` | `'0px'` | Margin around the root for intersection calculation |
+| `root` | `Element \| null` | `null` | Custom root element for intersection |
+| `targetWindow` | `Window \| null` | auto-detected | Target window for iframe support. Auto-detects from element's `ownerDocument` if not specified. |
+| `onIntersectionChange` | `(isIntersecting: boolean, ratio: number) => void` | - | Callback fired on intersection changes |
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isInView` | `boolean` | Whether the element is currently in view |
+| `progress` | `number` | Intersection ratio (0 to 1) based on threshold |
+
 ### useInfiniteScroll
 
 A hook for implementing infinite scroll functionality.