app-studio 0.6.21 → 0.6.24

package/docs/Responsive.md

@@ -0,0 +1,135 @@
+# Responsive Design with App-Studio
+
+Creating a responsive design is an essential part of modern web development. In App-Studio, two primary features help you achieve this: `useResponsive` hook and the `media` prop. This document provides an overview and examples for both approaches.
+
+---
+
+## 1. Media Prop for Responsive Design
+
+The `media` prop is particularly useful for managing responsive design without causing your components to re-render. You can specify different styles for various devices or screen sizes.
+
+### Example
+
+Here's a quick example to demonstrate its usage:
+
+```jsx
+import React from 'react';
+import { ResponsiveProvider, View } from 'app-studio';
+
+const Example = () => {
+  return (
+    <View widthHeight={100} 
+     media={{
+        mobile: {
+          backgroundColor: 'color.green',
+        },
+        tablet: {
+          backgroundColor: 'color.yellow',
+        },
+        xl: {
+          backgroundColor: 'color.blue',
+        },
+      }}  
+      />
+  );
+};
+
+const App = () => (
+  <ResponsiveProvider 
+    breakpoints={{
+        xs: 0,
+        sm: 340,
+        md: 560,
+        lg: 1080,
+        xl: 1300,
+    }}
+    devices={{  
+        mobile: ['xs', 'sm'],
+        tablet: ['md', 'lg'],
+        desktop: ['lg', 'xl']
+    }}
+  >
+    <Example />
+  </ResponsiveProvider>
+);
+```
+
+The `media` prop receives an object, where each key corresponds to a device type or screen size, and its value is another object describing the CSS to apply for that specific device.
+
+---
+
+## 2. Using `useResponsive` Hook
+
+The `useResponsive` hook provides you with screen size and device type information based on your defined breakpoints and devices.
+
+### Example
+
+Here's how you can use `useResponsive`:
+
+```jsx
+import React from 'react';
+import { ResponsiveProvider, View, useResponsive } from 'app-studio';
+
+const Example = () => {
+  const { screen, on } = useResponsive();
+  
+  const responsive = {
+    xs: {
+      backgroundColor: 'red',
+    },
+    sm: {
+      backgroundColor: 'green',
+    },
+    md: {
+      backgroundColor: 'blue',
+    },
+    lg: {
+      backgroundColor: 'yellow',
+    },
+    xl: {
+      backgroundColor: 'red',
+    },
+  };
+
+  return (
+    <View widthHeight={100} 
+      {...responsive[screen]}       
+    >
+      {screen} -  mobile : {on('mobile') ? 'yes' : 'no'}
+    </View>
+  );
+};
+
+const App = () => (
+  <ResponsiveProvider 
+    breakpoints={{
+        xs: 0,
+        sm: 340,
+        md: 560,
+        lg: 1080,
+        xl: 1300,
+    }}
+    devices={{  
+        mobile: ['xs', 'sm'],
+        tablet: ['md', 'lg'],
+        desktop: ['lg', 'xl']
+    }}
+  >
+    <Example />
+  </ResponsiveProvider>
+);
+```
+
+In this example, `useResponsive` provides `screen` and `on`:
+- `screen`: Gives you the current screen size based on your breakpoints.
+- `on`: A function that returns `true` or `false` depending on whether the current screen size is included in the given device type.
+
+It's important to note that `useResponsive` causes re-renders when the screen size changes, as it relies on React state updates. In contrast, the `media` prop avoids re-renders because it applies styles directly through CSS media queries. Choose the method that best suits your performance needs and design requirements.
+
+
+These can then be used to dynamically apply styles to your components, as demonstrated with the `responsive` object.
+
+
+---
+
+By combining the `media` prop and `useResponsive`, you can create robust, efficient, and responsive designs with App-Studio.

package/docs/Theming.md

@@ -0,0 +1,200 @@
+# Theming with App-Studio
+
+Theming is an essential part of any application. It allows you to maintain a consistent look and feel across your app. With App-Studio, theming becomes effortless through its `ThemeProvider` component. This document shows you how to set up theming in App-Studio.
+
+## Setting up the Theme Object
+
+First, define a theme object that contains the properties you'd like to customize, such as colors and palettes. This object can be as simple or as complex as your needs require.
+
+Here's an example:
+
+```javascript
+const theme = {
+    main:{
+       primary: '#fff7ed'
+    },
+    components: {
+      button:{
+        background: '#fff7ed'
+      }
+    }
+};
+
+const colors = {
+    main:{
+       blue: '#94a3b8'
+    },
+    palette: {
+      blueGray: {
+        50: '#f8fafc',
+        100: '#f1f5f9',
+        200: '#e2e8f0',
+        300: '#cbd5e1',
+        400: '#94a3b8',
+        500: '#64748b',
+        600: '#475569',
+        700: '#334155',
+        800: '#1e293b',
+        900: '#0f172a'
+      }
+    }
+};
+```
+
+## Using `ThemeProvider`
+
+Wrap your application's root component with `ThemeProvider` and pass the theme object as a prop. This will make the theme available to all child components.
+
+```javascript
+import { ThemeProvider, View } from 'app-studio';
+
+// ...
+
+function App() {
+  return (
+    <ThemeProvider theme={theme} colors={colors}>
+      {/* The rest of your app */}
+    </ThemeProvider>
+  );
+}
+```
+
+## Using the Theme in Components
+
+Now that the theme is available, you can use it in your components. For example, any component that accepts `color` or `backgroundColor` props will use the values from the theme.
+
+Here's an example of how you might set the background color for a `View` and text color for a `Text` component:
+
+```javascript
+import { View, Text } from 'app-studio';
+import { Button } from '@app-studio/web';
+
+function Example() {
+  return (
+    <View backgroundColor="color.blue">
+       <View backgroundColor="color.blueGray.500">
+        <Text color="theme.primary">Hello</Text>
+       </View>
+       <Button backgroundColor="theme.button.background">Hello</Button>
+    </View>
+  );
+}
+```
+
+Notice how the `backgroundColor` and `color` props use values defined in the theme object.
+
+### Accessing Specific Theme Mode Colors
+
+You can directly access colors from a specific theme mode regardless of the current theme mode using the `light.` or `dark.` prefix:
+
+```javascript
+import { View, Text } from 'app-studio';
+
+function Example() {
+  return (
+    <View>
+      {/* Always use light mode white color regardless of current theme mode */}
+      <Text color="light.white">Always light mode white</Text>
+
+      {/* Always use dark mode red.200 color regardless of current theme mode */}
+      <View backgroundColor="dark.red.200">
+        <Text>Always dark mode red.200 background</Text>
+      </View>
+    </View>
+  );
+}
+```
+
+This is useful when you need to access a specific theme mode's color regardless of the current theme setting.
+
+### Direct Theme Color Access
+
+App-Studio allows you to directly call theme colors using a simple dot notation format. This makes your code more readable and maintainable:
+
+```javascript
+import { View, Text } from 'app-studio';
+
+function Example() {
+  return (
+    <View>
+      {/* Access light theme colors directly */}
+      <Text color="light.white">White text in light mode</Text>
+      <View backgroundColor="light.blue.500">
+        <Text>Light blue background</Text>
+      </View>
+
+      {/* Access dark theme colors directly */}
+      <Text color="dark.white">White text in dark mode</Text>
+      <View backgroundColor="dark.red.200">
+        <Text>Dark red background</Text>
+      </View>
+
+      {/* Mix and match in the same component */}
+      <View
+        backgroundColor="light.gray.100"
+        borderColor="dark.gray.800"
+        borderWidth={1}
+      >
+        <Text>Mixed theme colors</Text>
+      </View>
+    </View>
+  );
+}
+```
+
+This direct access syntax works with all color-related properties and can be used with both singleton colors (like `white`, `black`) and palette colors (like `red.200`, `blue.500`). It provides a convenient way to reference specific theme colors without having to use the `getColor` function from the `useTheme` hook.
+
+## Complete Example
+
+Here's a complete example that ties it all together:
+
+```javascript
+import React from 'react';
+import { ThemeProvider, View, Text, Button } from 'app-studio';
+
+const theme = {
+    main:{
+       primary: '#fff7ed'
+    },
+    components: {
+      button:{
+        background: '#fff7ed'
+      }
+    }
+};
+
+const colors = {
+    main:{
+       blue: '#94a3b8'
+    },
+    palette: {
+      blueGray: {
+        50: '#f8fafc',
+        100: '#f1f5f9',
+        200: '#e2e8f0',
+        300: '#cbd5e1',
+        400: '#94a3b8',
+        500: '#64748b',
+        600: '#475569',
+        700: '#334155',
+        800: '#1e293b',
+        900: '#0f172a'
+      }
+    }
+};
+
+function Example() {
+  return (
+    <ThemeProvider theme={theme} colors={colors}>
+      <View backgroundColor="color.blue">
+         <View backgroundColor="color.blueGray.500">
+            <Text color="theme.primary">Hello</Text>
+         </View>
+         <Button backgroundColor="theme.button.background">Hello</Button>
+      </View>
+    </ThemeProvider>
+  );
+}
+```
+
+By using the `ThemeProvider` and the theme object, you can now maintain a consistent and easily customizable UI across your application.

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.6.21",
+  "version": "0.6.24",
   "name": "app-studio",
   "description": "App Studio is a responsive and themeable framework to build cross platform applications",
   "repository": "git@github.com:rize-network/app-studio.git",
@@ -21,7 +21,8 @@
   ],
   "files": [
     "dist",
-    "codemod"
+    "codemod",
+    "docs"
   ],
   "engines": {
     "node": ">=10"