@app-studio/web 0.9.57 → 0.9.59

package/docs/app-studio/Animation.md

@@ -0,0 +1,241 @@
+# Animation
+
+## 1. Introduction
+
+App-Studio provides a powerful animation system through the `Animation` object and the `Element` component. This system allows you to easily add dynamic and engaging animations, including:
+
+- **Standard CSS Animations**: Immediate animations on mount or loop.
+- **Scroll-Triggered Animations** (`view()`): Animations that play when elements enter the viewport.
+- **Scroll-Linked Animations** (`scroll()`): Animations driven by the scroll progress (e.g., parallax, reading progress).
+- **Interactive Animations**: Triggered by events like hover, click, or focus.
+
+## 2. Basic Usage
+
+### Standard Animations
+
+Use the `Animation` object to access standard animation presets.
+
+```jsx
+import { View, Animation } from 'app-studio';
+
+// Simple animation running immediately on mount
+<View 
+  animate={Animation.fadeIn({
+    duration: '1s',
+    timingFunction: 'ease',
+    iterationCount: '1'
+  })}
+/>
+```
+
+### Animation Properties
+
+Each animation function accepts an options object with these properties:
+
+```typescript
+type AnimationOptions = {
+  duration?: string;          // e.g., '1s', '500ms'
+  timingFunction?: string;    // e.g., 'ease', 'linear', 'cubic-bezier(...)'
+  iterationCount?: string | number; // e.g., '1', 'infinite'
+  delay?: string;             // e.g., '0.5s'
+  direction?: string;         // e.g., 'normal', 'reverse', 'alternate'
+  fillMode?: string;          // e.g., 'forwards', 'both'
+  playState?: string;         // e.g., 'running', 'paused'
+}
+```
+
+## 3. Element Props for Animation
+
+The `Element` component (and components extending it like `View`, `Text`, `Image`) supports several props to control animations:
+
+### `animate`
+The main property to apply animations. Accepts a single animation object or an array of animations.
+
+```jsx
+<View animate={Animation.bounce()} />
+<View animate={[Animation.fadeIn(), Animation.slideInUp()]} />
+```
+
+### `animateIn` & `animateOut`
+Useful for mounting and unmounting transitions, or conditional rendering effects.
+- `animateIn`: Applied when the component mounts or becomes visible (if `IntersectionObserver` is used internally).
+- `animateOut`: Applied during unmount cleanup (requires immediate re-render or external handling to be visible).
+
+### `animateOn`
+Controls *when* the animation defined in `animate` starts.
+
+- `'Mount'` (default): Animation starts immediately when the component is added to the DOM.
+- `'View'`: Animation is converted to a CSS `view()` timeline animation. It plays as the element enters the viewport. **No JavaScript required.**
+- `'Both'`: Technically same as Mount for most cases, ensuring visibility.
+
+```jsx
+// Trigger animation only when user scrolls it into view
+<View animate={Animation.slideInUp()} animateOn="View" />
+```
+
+## 4. Animation Presets
+
+App-Studio comes with a comprehensive library of ready-to-use animations available under the `Animation` namespace.
+
+### Fades
+- `Animation.fadeIn()`
+- `Animation.fadeOut()`
+- `Animation.fadeInDown()`
+- `Animation.fadeInUp()`
+- `Animation.fadeInScroll()` - Scroll-progress driven fade
+
+### Slides
+- `Animation.slideInLeft()`
+- `Animation.slideInRight()`
+- `Animation.slideInDown()`
+- `Animation.slideInUp()`
+- `Animation.slideOutLeft()`
+- `Animation.slideOutRight()`
+- `Animation.slideInLeftScroll()` - Scroll-progress driven slide
+
+### Zooms & Scales
+- `Animation.zoomIn()`
+- `Animation.zoomOut()`
+- `Animation.zoomInDown()`
+- `Animation.zoomOutUp()`
+- `Animation.scale()` - Pulse scale effect
+- `Animation.scaleDownScroll()`
+- `Animation.listItemScaleScroll()`
+
+### Bounces
+- `Animation.bounce()`
+- `Animation.bounceIn()`
+- `Animation.bounceOut()`
+
+### Flips & Rotations
+- `Animation.rotate()`
+- `Animation.flip()`
+- `Animation.flipInX()`
+- `Animation.flipInY()`
+- `Animation.rollIn()`
+- `Animation.rollOut()`
+- `Animation.swing()`
+
+### Attention Seekers & Effects
+- `Animation.pulse()`
+- `Animation.flash()`
+- `Animation.shake()`
+- `Animation.headShake()`
+- `Animation.rubberBand()`
+- `Animation.wobble()`
+- `Animation.heartBeat()`
+- `Animation.tada()`
+- `Animation.jello()`
+
+### Extrances & Exits
+- `Animation.lightSpeedIn()`
+- `Animation.lightSpeedOut()`
+- `Animation.jackInTheBox()`
+- `Animation.hinge()`
+- `Animation.backInDown()`
+- `Animation.backOutUp()`
+
+### Special / Scroll-Driven
+- `Animation.shimmer()` - Loading shimmer effect
+- `Animation.typewriter()` - Typing effect
+- `Animation.blinkCursor()`
+- `Animation.handWaveScroll()`
+- `Animation.ctaCollapseScroll()`
+- `Animation.fillTextScroll()`
+
+## 5. View Timeline Animations (Scroll-Driven)
+
+There are two ways to create animations that trigger on scroll into view:
+
+### 1. Using `animateOn="View"`
+This works with any standard animation.
+
+```jsx
+<View animate={Animation.fadeIn()} animateOn="View" />
+```
+
+### 2. Using `*OnView` Helper Functions
+These are performant, pure CSS animations explicitly designed for entry/exit effects. Imported directly from `app-studio`.
+
+```jsx
+import { 
+  fadeInOnView, 
+  slideUpOnView, 
+  scaleUpOnView,
+  blurInOnView,
+  rotateInOnView,
+  revealOnView,
+  flipXOnView,
+  flipYOnView
+} from 'app-studio';
+
+<View animate={fadeInOnView()} />
+<View animate={slideUpOnView({ distance: '50px' })} />
+<View animate={revealOnView()} /> // Clip-path reveal
+```
+
+## 6. Scroll Progress Animations
+
+These animations are linked to the scroll position associated with a timeline (usually the nearest scroller). As you scroll active range, the animation progresses.
+
+```jsx
+// Text that fills efficiently as you scroll (requires CSS variable support)
+<View animate={Animation.fillTextScroll()} />
+
+// Image that unclips/expands as you scroll
+<View animate={Animation.unclipScroll()} />
+
+// Item that fades in based on scroll progress
+<View animate={Animation.fadeInScroll()} />
+```
+
+## 7. Event-Based Animations
+
+You can trigger animations on interactions like hover, click, or focus using the `on` prop or underscore props (`_hover`, `_active`).
+
+```jsx
+<View
+  _hover={{
+    // Pulse animation while hovering
+    animate: Animation.pulse({ duration: '0.5s' }),
+    scale: 1.05
+  }}
+  
+  on={{
+    click: {
+      animate: Animation.flash()
+    }
+  }}
+>
+  <Text>Hover or Click Me</Text>
+</View>
+```
+
+## 8. Custom Animation Sequences
+
+You can create complex animation sequences by configuring keyframes directly.
+
+```jsx
+const customTwist = {
+  from: { transform: 'rotate(0deg) scale(1)' },
+  '50%': { transform: 'rotate(180deg) scale(1.5)' },
+  to: { transform: 'rotate(360deg) scale(1)' },
+  duration: '2s',
+  iterationCount: 'infinite'
+};
+
+<View animate={customTwist} />
+```
+
+## 9. Best Practices
+
+1.  **Performance**: Prefer standard transforms (`translate`, `scale`, `rotate`) and `opacity`. Avoid animating layout properties like `width` or `margin`.
+2.  **Scroll Animations**: Use `animateOn="View"` or `*OnView` helpers for "reveal" effects, as they run on the compositor thread and don't require JavaScript listeners.
+3.  **Accessibility**: Respect user motion preferences.
+4.  **Composability**: You can mix standard styles with animations.
+    ```jsx
+    <View 
+      style={{ opacity: 0 }} // Initial state
+      animate={Animation.fadeIn({ delay: '0.5s', fillMode: 'forwards' })} 
+    />
+    ```

package/docs/app-studio/Components.md

@@ -0,0 +1,192 @@
+# Components
+
+App-Studio provides a comprehensive set of components built on the `Element` base component. This guide covers all the available components and their usage.
+
+## Element
+
+The `Element` component is the foundation of App-Studio. It is responsible for handling a large part of the styles of the other components. It takes care of responsiveness, shadow, margins, and padding among other properties.
+
+### Usage
+
+```jsx
+<Element backgroundColor="color.blue" padding={10}>This is an element</Element>
+```
+
+It is the base component for all other components in the library. It adds additional properties to help manage design:
+
+- `widthHeight`: Sets both `width` and `height` to the same value. Accepts a number (in pixels) or a string (e.g., '50%', 'auto').
+- `on`: An object to define styles that apply on different CSS pseudo-class events (like `hover`, `focus`, `active`). Refer to the Events documentation for details.
+- `media`: An object to define responsive styles for different media queries (breakpoints) or devices. Refer to the Responsive Design documentation for details.
+- `shadow`: Applies a shadow effect to the element. Can be a boolean (default shadow), a number (referencing predefined shadow levels), or a `Shadow` object for custom shadow properties.
+
+## Layout Components
+
+### View
+The basic building block for layouts. Extends the basic `div` HTML element.
+
+```tsx
+import { View } from 'app-studio';
+
+<View
+  widthHeight={100}
+  backgroundColor="color.white"
+  marginTop={20}
+>
+  {/* Content */}
+</View>
+```
+
+### Vertical & Horizontal
+For stack and row layouts.
+
+```tsx
+import { Vertical, Horizontal } from 'app-studio';
+
+// Vertical stack
+<Vertical spacing={20}>
+  <View />
+  <View />
+</Vertical>
+
+// Horizontal row
+<Horizontal spacing={10}>
+  <View />
+  <View />
+</Horizontal>
+```
+
+## Text Components
+
+### Text
+For displaying text content with theme support. Extends the basic `span` HTML element.
+
+```tsx
+import { Text } from 'app-studio';
+
+<Text
+  color="color.black"
+  marginRight={10}
+>
+  Content
+</Text>
+
+// With theme mode
+<Text
+  color="color.red"
+  themeMode="dark"
+>
+  Dark mode text
+</Text>
+```
+
+## Media Components
+
+### Image
+Extends the basic `img` HTML element with additional properties like `shadow`, `media`, and `on`.
+
+```tsx
+import { Image } from 'app-studio';
+
+// Basic usage
+<Image
+  widthHeight={100}
+  shadow={9}
+  src="https://picsum.photos/200"
+/>
+
+// Responsive image (mobile only)
+<Image
+  widthHeight={100}
+  src="https://picsum.photos/200"
+  only={['mobile']}
+/>
+```
+
+## Form Components
+
+### Form
+Extends the basic `form` HTML element. It's used for creating forms and provides nested `Form.Button` and `Form.Input` components for form elements.
+
+```jsx
+<Form>
+  <Input placeholder="Enter your name" />
+  <Button>Submit</Button>
+</Form>
+```
+
+### Input
+Extends the basic `input` HTML element with additional styling properties.
+
+```tsx
+import { Input } from 'app-studio';
+
+// Basic usage
+<Input width={100} />
+
+// With hover state
+<Input
+  width={100}
+  shadow={9}
+  on={{
+    hover: {
+      backgroundColor: 'color.red'
+    }
+  }}
+/>
+```
+
+### Button
+Interactive button component with built-in states and animations.
+
+```tsx
+import { Button } from 'app-studio';
+
+<Button
+  paddingHorizontal={20}
+  paddingVertical={10}
+  backgroundColor="color.green.500"
+  color="color.white"
+  borderRadius={5}
+  fontWeight="bold"
+  on={{
+    hover: { backgroundColor: 'color.green.600' },
+    active: { transform: 'scale(0.95)' }
+  }}
+>
+  Click Me
+</Button>
+```
+
+## Feedback Components
+
+### Skeleton
+Used for loading states and content placeholders. Extends `View`.
+
+```tsx
+import { Skeleton, View } from 'app-studio';
+
+// Basic usage
+<View>
+  <Skeleton widthHeight={100} />
+</View>
+
+// With background comparison
+<View>
+  <View widthHeight={100} backgroundColor="red" />
+  <Skeleton widthHeight={100} />
+</View>
+```
+
+## Component Props
+
+All components extend the base `Element` props:
+
+- `as`: HTML element to render as
+- `media`: Responsive styles object
+- `on`: Interactive state styles
+- `animate`: Animation configuration
+- `themeMode`: Override theme mode
+- `colors`: Custom color palette
+- `theme`: Custom theme tokens
+
+Additional component-specific props are documented in their respective sections above.

package/docs/app-studio/Design.md

@@ -0,0 +1,121 @@
+
+# Design Props and Styling
+
+
+The `app-studio` library provides a set of design props that simplify styling and enhance design integration. These props offer a more streamlined and efficient way to manage styling compared to using inline styles or CSS classes directly. They are particularly beneficial for implementing responsive and theme-aware styling, allowing you to easily adapt your components to different screen sizes and themes.
+
+Here is an example:
+
+```jsx
+<View
+  backgroundColor="theme.primary"
+  padding={20}
+  margin={10}
+  width={200}
+  height={100}
+>
+  I am a View component with custom styling
+</View>
+```
+
+In this example, the View component is styled with custom background color, padding, margin, width, and height.
+
+The `shadow` prop allows you to apply shadow effects to components. It can accept a boolean, a number, or a `Shadow` object. A boolean value applies a default shadow, while a number references predefined shadow levels (e.g., `shadow={6}` might correspond to a specific shadow intensity defined in your theme). For more granular control, you can use a `Shadow` object to customize the shadow's properties.
+
+Here is an example:
+
+```jsx
+<View backgroundColor="theme.primary" padding={20} shadow={6}>
+  I have a shadow
+</View>
+```
+
+In this example, the `shadow={6}` applies the 6th predefined shadow level from your theme to the `View` component.
+
+## CSS Custom Properties (Variables)
+
+App-Studio supports CSS custom properties (CSS variables) that start with `--`. You can define and use these variables in your components for more flexible styling:
+
+```jsx
+<View
+  style={{
+    '--primary-color': 'blue',
+    '--primary-bg': 'lightblue',
+    '--spacing': '15px',
+  }}
+  backgroundColor="var(--primary-bg)"
+  color="var(--primary-color)"
+  padding="var(--spacing)"
+>
+  This component uses CSS variables
+</View>
+```
+
+You can also define CSS variables using the `css` prop:
+
+```jsx
+<View
+  css={{
+    '--secondary-color': 'green',
+    '--secondary-bg': 'lightgreen',
+    '--border-radius': '8px',
+  }}
+  backgroundColor="var(--secondary-bg)"
+  borderRadius="var(--border-radius)"
+>
+  <Text color="var(--secondary-color)">
+    This text uses a CSS variable for its color
+  </Text>
+</View>
+```
+
+CSS variables are particularly useful for:
+- Creating theme variations within components
+- Sharing values between different CSS properties
+- Enabling dynamic styling through JavaScript
+
+## Vendor-Prefixed Properties
+
+App-Studio handles vendor-prefixed CSS properties to ensure cross-browser compatibility. You can use both camelCase and lowercase formats for vendor prefixes:
+
+### Camel Case Format (Recommended)
+
+```jsx
+<View
+  WebkitUserSelect="none"
+  MozUserSelect="none"
+  msFlexAlign="center"
+>
+  This element has vendor-prefixed properties
+</View>
+```
+
+### Lowercase Format
+
+```jsx
+<View
+  webkitBackgroundClip="text"
+  webkitTextFillColor="transparent"
+  background="linear-gradient(45deg, #ff0000, #0000ff)"
+>
+  This text should have a gradient effect
+</View>
+```
+
+You can also use the `css` prop for more complex vendor-prefixed styles:
+
+```jsx
+<View
+  css={{
+    background: "linear-gradient(45deg, #ff0000, #00ff00, #0000ff)",
+    webkitBackgroundClip: "text",
+    color: "transparent",
+    fontSize: "24px",
+    fontWeight: "bold"
+  }}
+>
+  This text should have a gradient background
+</View>
+```
+
+App-Studio automatically converts JavaScript-style vendor-prefixed properties (like `webkitBackgroundClip`) to their CSS equivalents with hyphens (e.g., `-webkit-background-clip`), ensuring proper rendering across different browsers.