app-studio 0.6.21 → 0.6.22

package/docs/Animation.md

@@ -0,0 +1,197 @@
+# Animation
+
+## 1. Introduction
+
+App-Studio provides a powerful animation system through the `Animation` object. This system allows you to easily add dynamic and engaging animations to any component that extends from `Element`. The animations are based on CSS animations and can be customized with various properties.
+
+## 2. Usage
+
+### Basic Usage
+
+```jsx
+import { View, Animation } from 'app-studio';
+
+// Simple animation
+<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', 'ease-in-out'
+  iterationCount?: string | number; // e.g., '1', 'infinite'
+}
+```
+
+## 3. Animation Types
+
+### Transition Animations
+
+Animations that involve changes in opacity or position:
+
+```jsx
+// Fade animations (change opacity)
+Animation.fadeIn()
+Animation.fadeOut()
+
+// Slide animations (move elements)
+Animation.slideInLeft()
+Animation.slideInRight()
+Animation.slideOutLeft()
+Animation.slideOutRight()
+Animation.slideInUp()
+Animation.slideOutDown()
+```
+
+### Transform Animations
+
+Animations that modify the element's transformation:
+
+```jsx
+// Rotate
+Animation.rotate()
+
+// Scale
+Animation.scale()
+
+// Translate
+Animation.translate()
+```
+
+### Effect Animations
+
+Animations that create special effects:
+
+```jsx
+// Attention seekers
+Animation.bounce()
+Animation.pulse()
+Animation.shake()
+Animation.flash()
+
+// Special effects
+Animation.flip()
+Animation.rubberBand()
+Animation.heartBeat()
+```
+
+## 4. Event-Based Animations
+
+Animations can be triggered by various events using the `on` prop:
+
+```jsx
+<View
+  on={{
+    // Animation on hover
+    hover: {
+      backgroundColor: 'lightblue', // Example: change background color on hover
+      animate: Animation.pulse({
+        duration: "1s",
+        iterationCount: "infinite",
+      }),
+    },
+    
+    // Animation on click
+    click: {
+      animate: Animation.flash({ duration: '0.5s' })
+    }
+  }}
+/>
+```
+
+## 5. Responsive Animations
+
+You can define different animations for different screen sizes using the `media` prop:
+
+```jsx
+<View
+  media={{
+    mobile: {
+      animate: Animation.fadeIn({ duration: '1s' })
+    },
+    tablet: {
+      animate: Animation.slideInLeft({ duration: '0.5s' })
+    },
+    desktop: {
+      animate: Animation.bounce({ duration: '2s' })
+    }
+  }}
+/>
+```
+
+## 6. Custom Animation Sequences
+
+You can create complex animation sequences by defining an array of animation states. Each state in the sequence is an object with `from` and `to` properties that define the CSS styles at the start and end of that animation segment.
+
+Here's a simple example:
+
+```jsx
+const simpleSequence = [
+  {
+    from: { opacity: 0 }, // Start fully transparent
+    to: { opacity: 1 }, // End fully opaque
+    duration: "1s",
+    timingFunction: "ease-in",
+  },
+];
+
+<View animate={simpleSequence} />
+```
+
+And here's a more complex example:
+
+```jsx
+const complexSequence = [
+  {
+    from: { opacity: 0, transform: "translateY(-100px)" },
+    to: { opacity: 1, transform: "translateY(0)" },
+    duration: "2s",
+    timingFunction: "ease-in",
+  },
+  {
+    from: { opacity: 1, transform: "translateY(100px)" },
+    to: { opacity: 0, transform: "translateY(0)" },
+    duration: "2s",
+    timingFunction: "ease-out",
+  },
+];
+
+<View animate={complexSequence} />
+```
+
+## 7. Best Practices
+
+1. **Performance**
+   - Use animations sparingly and purposefully
+   - Prefer transform and opacity animations for better performance
+   - Avoid animating too many properties simultaneously
+
+2. **User Experience**
+   - Keep animations short and subtle
+   - Use appropriate timing functions for natural movement
+   - Consider reducing motion for accessibility
+
+3. **Code Organization**
+   - Define reusable animation configurations
+   - Use meaningful names for custom sequences
+   - Keep animation logic separate from component logic. For example, you can create separate configuration objects for your animations:
+     ```jsx
+     const myAnimation = Animation.fadeIn({ duration: '1s' });
+
+     <View animate={myAnimation} />
+     ```
+
+4. **Responsive Design**
+   - Adjust animation duration for different screen sizes
+   - Consider disabling complex animations on mobile devices
+   - Test animations on *real devices* in addition to browser developer tools, as performance can vary.

package/docs/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/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.