app-studio 0.4.6 → 0.5.0

package/README.md

@@ -1,94 +1,218 @@
-# App Studio
+# App-Studio Documentation
+
+## Table of Contents
+- [App-Studio Documentation](#app-studio-documentation)
+  - [Table of Contents](#table-of-contents)
+  - [1. Introduction](#1-introduction)
+    - [Features](#features)
+  - [2. Installation](#2-installation)
+  - [3. Core Components](#3-core-components)
+    - [Element](#element)
+      - [Usage](#usage)
+      - [Key Properties](#key-properties)
+    - [View](#view)
+      - [Usage](#usage-1)
+    - [Text](#text)
+      - [Usage](#usage-2)
+    - [Form](#form)
+      - [Usage](#usage-3)
+    - [Image](#image)
+      - [Usage](#usage-4)
+  - [4. Responsive Design](#4-responsive-design)
+    - [Media Prop](#media-prop)
+      - [Example](#example)
+    - [useResponsive Hook](#useresponsive-hook)
+      - [Example](#example-1)
+  - [5. Event Management](#5-event-management)
+      - [Example](#example-2)
+  - [6. Theming](#6-theming)
+      - [Setting up the Theme](#setting-up-the-theme)
+      - [Using ThemeProvider](#using-themeprovider)
+      - [Applying Theme in Components](#applying-theme-in-components)
+  - [7. Custom Hooks](#7-custom-hooks)
+    - [useMount](#usemount)
+      - [Usage](#usage-5)
+  - [8. Design Props](#8-design-props)
+    - [Example](#example-3)
+    - [Shadow Prop](#shadow-prop)
+  - [9. Animations](#9-animations)
+    - [Basic Usage](#basic-usage)
+    - [Available Animations](#available-animations)
+    - [Customizing Animations](#customizing-animations)
+    - [Creating Custom Animations](#creating-custom-animations)
+    - [Combining Animations](#combining-animations)
+    - [Animation Events](#animation-events)
+  - [10. Advanced Usage](#10-advanced-usage)
+  - [10. Contributing](#10-contributing)
+  - [11. License](#11-license)
+
+## 1. Introduction
+
+App-Studio is a powerful React-based library designed to simplify the process of building responsive, interactive, and visually consistent web applications. It provides CSS design props for layout, spacing, sizing, shadows, event management, and theming.
+
+### Features
+
+- 🌈 Add styled props to your application
+- 📦 A set of simple and powerful React components
+- 🌍 Internationalization support for dozens of languages
+- 🎨 Powerful theme customization in every detail
+
+## 2. Installation
+
+To install App-Studio, run the following command:
 
-[![npm version](https://img.shields.io/npm/v/app-studio.svg?style=for-the-badge)](https://www.npmjs.com/package/app-studio)
-[![npm](https://img.shields.io/npm/dt/app-studio.svg?style=for-the-badge)](https://www.npmjs.com/package/app-studio)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
-[![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg?style=for-the-badge)](https://github.com/prettier/prettier)
+```bash
+npm install app-studio  --save
+```
 
+## 3. Core Components
 
-[npm-image]: http://img.shields.io/npm/v/app-studio.svg?style=flat-square
-[npm-url]: http://npmjs.org/package/app-studio
-[github-action-image]: https://github.com/rize-network/app-studio/workflows/%E2%9C%85%20test/badge.svg
-[github-action-url]: https://github.com/rize-network/app-studio/actions?query=workflow%3A%22%E2%9C%85+test%22
+### Element
 
-[download-image]: https://img.shields.io/npm/dm/app-studio.svg?style=flat-square
-[download-url]: https://npmjs.org/package/app-studio
+The `Element` component is the foundation of App-Studio. It handles a large part of the styling for other components, including responsiveness, shadow, margins, and padding.
 
-[help-wanted-image]: https://flat.badgen.net/github/label-issues/rize-network/app-studio/help%20wanted/open
-[help-wanted-url]: https://github.com/rize-network/app-studio/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22
+#### Usage
+
+```jsx
+<Element backgroundColor="color.blue" padding={10}>
+  This is an element
+</Element>
+```
 
-[discussions-image]: https://img.shields.io/badge/discussions-on%20github-blue?style=flat-square
-[discussions-url]: https://github.com/rize-network/app-studio/discussions
+#### Key Properties
 
-[issues-helper-image]: https://img.shields.io/badge/using-issues--helper-orange?style=flat-square
-[issues-helper-url]: https://github.com/actions-cool/issues-helper
+- `size`: Sets equal width and height
+- `on`: Defines styles for different CSS events
+- `media`: Defines styles for different media queries
+- `shadow`: Adds shadow to an element (boolean, number, or `Shadow` object)
 
+### View
 
+The `View` component is a versatile layout component that extends the basic HTML `div` tag with additional styling properties.
 
-`App-studio` provides CSS design props for layout, spacing, sizing, shadows with the 'shadow' prop, event management through the `on` prop, and theming. Components include `Element` for fundamental design, `View` based on the `div`, `Text` for text styles, `Form` for form-related designs, and `Image` based on the `img` tag.
+#### Usage
 
-Supported events: `hover`, `active`, `focus`, and `disabled`.
+```jsx
+<View backgroundColor="color.red" color="color.white" padding={20}>
+  This is a view
+</View>
+```
 
-## ✨ Features
+### Text
 
-- 🌈 Add styled props to your application.
-- 📦 A set of Simple and powerful React components.
-- 🌍 Internationalization support for dozens of languages.
-- 🎨 Powerful theme customization in every detail.
+The `Text` component extends the HTML `div` tag with additional text styling properties.
 
-## 📦 Install
+#### Usage
 
-```bash
-npm install app-studio --save
+```jsx
+<Text color="color.blue">This is a text</Text>
 ```
 
-## 🔨 Usage
+### Form
 
-The `<View>` component supports all of the default [CSSProperties](https://developer.mozilla.org/fr/docs/Web/CSS/CSS_Properties_Reference) as props. The styles are transformed.
+The `Form` component extends the HTML `form` tag and provides `Button` and `Input` subcomponents.
 
-1. Add Responsive and Theme Provider to your application root:
+#### Usage
 
 ```jsx
-import React from 'react';
-import { ResponsiveProvider, ThemeProvider } from 'app-studio';
+<Form>
+  <Input placeholder="Enter your name" />
+  <Button>Submit</Button>
+</Form>
+```
 
-const Root = () => {
-    return (
-        <ResponsiveProvider>
-            <ThemeProvider>
-                <App />
-            </ThemeProvider>
-        </ResponsiveProvider>
-    );
-};
+### Image
+
+The `Image` component extends the HTML `img` tag with additional properties like `shadow`, `media`, and `on`.
+
+#### Usage
+
+```jsx
+<Image src="url_to_image" alt="description" />
 ```
 
-2. Use components in your application:
+## 4. Responsive Design
+
+App-Studio offers two primary methods for implementing responsive design: the `media` prop and the `useResponsive` hook.
+
+### Media Prop
+
+The `media` prop allows you to specify different styles for various devices or screen sizes without causing component re-renders.
+
+#### Example
 
 ```jsx
-import React from 'react';
-import { View } from 'app-studio';
+<View size={100} 
+  media={{
+  mobile: { backgroundColor: 'color.green' },
+  tablet: { backgroundColor: 'color.yellow' },
+  xl: { backgroundColor: 'color.blue' },
+  }}  
+/>
+```
 
-function Example() {
-    return (
-        <View 
-            backgroundColor="color.grey" 
-            padding={20}
-            on={{ hover: { backgroundColor: 'color.blue.100' } }}
-        >
-            Hello
-        </View>
-    );
-}
+### useResponsive Hook
+
+The `useResponsive` hook provides information about the current screen size and device type based on defined breakpoints and devices.
+
+#### Example
+
+```jsx
+const { screen, on } = useResponsive();
+
+return (
+  <View size={100} backgroundColor={responsive[screen]}>
+  {screen} - mobile: {on('mobile') ? 'yes' : 'no'}
+  </View>
+);
 ```
 
-You can use View for a `<div>` tag. You can also use Div, Span, Form, Input, and Image components if you need another tag.
+To use these responsive features, wrap your app with `ResponsiveProvider`:
 
-## Advanced Example
+```jsx
+<ResponsiveProvider 
+  breakpoints={{
+  xs: 0,
+  sm: 340,
+  md: 560,
+  lg: 1080,
+  xl: 1300,
+  }}
+  devices={{  
+  mobile: ['xs', 'sm'],
+  tablet: ['md', 'lg'],
+  desktop: ['lg', 'xl']
+  }}
+>
+  <App />
+</ResponsiveProvider>
+```
+
+## 5. Event Management
+
+App-Studio provides an intuitive way to manage CSS events through the `on` prop. This feature allows you to style elements based on various interactive states.
+
+#### Example
 
 ```jsx
-import { ThemeProvider, ResponsiveProvider, View, Span, Text, Button } from 'app-studio';
+<View 
+  backgroundColor="grey" 
+  padding={20}
+  on={{ hover: { backgroundColor: 'blue.100' } }}
+>
+  Hover over me
+</View>
+```
+
+Supported events include `hover`, `active`, `focus`, and `disabled`.
+
+## 6. Theming
 
+App-Studio's theming system allows you to maintain a consistent look across your application using the `ThemeProvider` component.
+
+#### Setting up the Theme
+
+```javascript
 const theme = {
   main: { primary: '#fff7ed' },
   components: { button: { background: '#fff7ed' } }
@@ -96,86 +220,274 @@ const theme = {
 
 const colors = {
   main: { blue: '#94a3b8' },
-  palette: { blueGray: { 500: '#64748b' } }
+  palette: {
+  blueGray: {
+    50: '#f8fafc',
+    // ... other shades
+    900: '#0f172a'
+  }
+  }
+};
+```
+
+#### Using ThemeProvider
+
+```jsx
+<ThemeProvider theme={theme} colors={colors}>
+  <App />
+</ThemeProvider>
+```
+
+#### Applying Theme in Components
+
+```jsx
+<View backgroundColor="color.blue">
+  <Text color="theme.primary">Hello</Text>
+  <Button backgroundColor="theme.button.background">Click me</Button>
+</View>
+```
+
+## 7. Custom Hooks
+
+### useMount
+
+The `useMount` hook executes logic when a component first mounts.
+
+#### Usage
+
+```jsx
+import { useMount } from '@your-org/app-studio';
+
+const MyComponent = () => {
+  useMount(() => {
+  console.log('MyComponent mounted');
+  });
+
+  return <div>MyComponent</div>;
 };
+```
+
+## 8. Design Props
+
+App-Studio provides additional props to better manage design integration in CSS. These props offer more control over the styling of components, including layout, spacing, and sizing.
+
+### Example
+
+```jsx
+<View 
+  backgroundColor="theme.primary" 
+  padding={20}
+  margin={10}
+  width={200}
+  height={100}
+>
+  I am a View component with custom styling
+</View>
+```
+
+### Shadow Prop
+
+The `shadow` prop is used to manage shadows in CSS. It takes a number or a string as a value, which defines the shadow effect to apply to the component.
+
+```jsx
+<View 
+  backgroundColor="theme.primary" 
+  padding={20}
+  shadow={6}
+>
+  I have a shadow
+</View>
+```
+
+## 9. Animations
+
+App-Studio provides a powerful and flexible animation system that allows you to easily add dynamic effects to your components. The animation system is based on CSS animations and can be applied using the `animate` prop.
+
+### Basic Usage
+
+To apply an animation to a component, use the `animate` prop with an animation object:
+
+```jsx
+import { View, Animation } from 'app-studio';
 
 function Example() {
   return (
-    <ResponsiveProvider>
-        <ThemeProvider theme={theme} colors={colors}>
-          <Span
-            backgroundColor="color.blue"
-            padding={10}
-            media={{
-                mobile: {
-                  padding: 20
-                }
-            }}
-          >
-            Base element
-          </Span>
-          <View 
-            backgroundColor="theme.primary" 
-            margin={10}
-            width={200}
-            on={{ hover: { backgroundColor: 'color.blueGray.500' } }}
-          >
-            Hover to change color
-          </View>
-          <Button backgroundColor="theme.button.background">Click here</Button>
-          <Text color="theme.primary">Hello</Text>
-        </ThemeProvider>
-    </ResponsiveProvider>
+    <View
+      animate={Animation.fadeIn()}
+      backgroundColor="theme.primary"
+      padding={20}
+    >
+      This view will fade in
+    </View>
   );
 }
 ```
 
-## Transform JavaScript/TypeScript JSX
+### Available Animations
 
-To transform your existing JavaScript/TypeScript JSX code to use App-Studio:
+App-Studio comes with a set of pre-defined animations that you can use out of the box:
 
-1. Install the codemod tool:
+- `fadeIn` / `fadeOut`
+- `slideInLeft` / `slideInRight` / `slideInUp` / `slideInDown`
+- `zoomIn` / `zoomOut`
+- `bounce`
+- `rotate`
+- `pulse`
+- `flash`
+- `shake`
+- `swing`
+- `rubberBand`
+- `wobble`
+- `flip`
+- `heartBeat`
+- `rollIn` / `rollOut`
+- `lightSpeedIn` / `lightSpeedOut`
+- `hinge`
+- `jackInTheBox`
 
-```bash
-npm install -g @app-studio/codemod
+Each animation function accepts parameters to customize the duration, timing function, and other properties.
+
+### Customizing Animations
+
+You can customize animations by passing parameters to the animation functions:
+
+```jsx
+<View
+  animate={Animation.fadeIn('2s', 'ease-in-out')}
+  backgroundColor="theme.primary"
+  padding={20}
+>
+  This view will fade in slowly
+</View>
 ```
 
-2. Run the transformation:
+### Creating Custom Animations
 
-```bash
-app-studio-codemod to-app-studio <path_to_your_js_or_tsx_files> --assetsDir=src/assets --assetsUrl=/assets
+You can also create custom animations by defining your own keyframes:
+
+```jsx
+const customAnimation = {
+  from: { opacity: 0, transform: 'translateY(-50px)' },
+  to: { opacity: 1, transform: 'translateY(0)' },
+  duration: '1s',
+  timingFunction: 'ease-out'
+};
+
+<View
+  animate={customAnimation}
+  backgroundColor="theme.primary"
+  padding={20}
+>
+  This view will have a custom animation
+</View>
+```
+
+### Combining Animations
+
+You can combine multiple animations by using the `Animation.compose` function:
+
+```jsx
+const combinedAnimation = Animation.compose(
+  Animation.fadeIn(),
+  Animation.slideInUp()
+);
+
+<View
+  animate={combinedAnimation}
+  backgroundColor="theme.primary"
+  padding={20}
+>
+  This view will fade in and slide up simultaneously
+</View>
 ```
 
-Replace `<path_to_your_js_or_tsx_files>` with the actual path to your JavaScript/TypeScript files.
+### Animation Events
 
-## 🔗 Links
-- [Change Log](CHANGELOG.md)
-- [Versioning Release Note](https://github.com/rize-network/app-studio/wiki/)
-- [How to Apply for Being A Collaborator](https://github.com/rize-network/app-studio/wiki/Collaborators#how-to-apply-for-being-a-collaborator)
+You can also listen to animation events using the `onAnimationStart`, `onAnimationEnd`, and `onAnimationIteration` props:
 
-## 🤝 Contributing [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
+```jsx
+<View
+  animate={Animation.bounce()}
+  onAnimationStart={() => console.log('Animation started')}
+  onAnimationEnd={() => console.log('Animation ended')}
+  backgroundColor="theme.primary"
+  padding={20}
+>
+  This view will bounce
+</View>
+```
 
-Read our [contributing guide](https://ant.design/docs/react/contributing) and let's build a better rize-network together.
+By leveraging these animation capabilities, you can create rich, interactive user interfaces with App-Studio.
 
-We welcome all contributions. Please read our [CONTRIBUTING.md](https://github.com/rize-network/app-studio/blob/master/.github/CONTRIBUTING.md) first. You can submit any ideas as [pull requests](https://github.com/rize-network/app-studio/pulls) or as [GitHub issues](https://github.com/rize-network/app-studio/issues). If you'd like to improve code, check out the [Development Instructions](https://github.com/rize-network/app-studio/wiki/Development) and have a good time! :)
+## 10. Advanced Usage
 
-If you are a collaborator, please follow our [Pull Request principle](https://github.com/rize-network/app-studio/wiki/PR-principle) to create a Pull Request with [collaborator template](https://github.com/rize-network/app-studio/compare?expand=1&template=collaborator.md).
+Here's an advanced example showcasing various features of App-Studio, including animations:
+
+```jsx
+import { ThemeProvider, ResponsiveProvider, View, Span, Text, Button, Animation } from 'app-studio';
+
+const theme = {
+  main: { primary: '#fff7ed' },
+  components: { button: { background: '#fff7ed' } }
+};
+
+const colors = {
+  main: { blue: '#94a3b8' },
+  palette: { blueGray: { 500: '#64748b' } }
+};
 
-[![Let's fund issues in this repository](https://issuehunt.io/static/embed/issuehunt-button-v1.svg)](https://issuehunt.io/o/rize-network)
+function Example() {
+  return (
+    <ResponsiveProvider>
+      <ThemeProvider theme={theme} colors={colors}>
+        <Span
+          animate={Animation.fadeIn('1s', 'ease-out')}
+          backgroundColor="color.blue"
+          padding={10}
+          media={{
+            mobile: {
+              padding: 20
+            }
+          }}
+        >
+          Base element
+        </Span>
+        <View 
+          animate={Animation.slideInRight()}
+          backgroundColor="theme.primary" 
+          margin={10}
+          width={200}
+          on={{ hover: { backgroundColor: 'color.blueGray.500' } }}
+        >
+          Hover to change color
+        </View>
+        <Button 
+          animate={Animation.pulse('infinite')}
+          backgroundColor="theme.button.background"
+        >
+          Click here
+        </Button>
+        <Text 
+          animate={Animation.typewriter('Hello', 100)}
+          color="theme.primary"
+        />
+      </ThemeProvider>
+    </ResponsiveProvider>
+  );
+}
+```
 
-## Roadmap 
 
-- Integrate React Native 
+## 10. Contributing
 
-## Author
+We welcome all contributions to App-Studio. Please read our [contributing guide](https://ant.design/docs/react/contributing) and let's build a better App-Studio together.
 
-SteedMonteiro, steed@rize.network
+For more detailed information on contributing, including how to apply for being a collaborator, please refer to our [GitHub repository](https://github.com/rize-network/app-studio).
 
-## ❤️ Sponsors and Backers [![](https://opencollective.com/rize/tiers/sponsors/badge.svg?label=Sponsors&color=brightgreen)](https://opencollective.com/rize#support) [![](https://opencollective.com/rize/tiers/backers/badge.svg?label=Backers&color=brightgreen)](https://opencollective.com/rize#support)
+## 11. License
 
-[![](https://opencollective.com/rize/tiers/sponsors.svg?avatarHeight=36)](https://opencollective.com/rize#support)
-[![](https://opencollective.com/rize/tiers/backers.svg?avatarHeight=36)](https://opencollective.com/rize#support)
+App-Studio is available under the MIT license. See the LICENSE file for more info.
 
-## License
+---
 
-App Studio is available under the MIT license. See the LICENSE file for more info.
+For the latest updates, changelog, and more detailed information, please visit our [GitHub repository](https://github.com/rize-network/app-studio).