App-Studio is a React library designed to streamline the development of modern web applications. It provides a comprehensive suite of reusable components, hooks, utilities, and built-in systems for theming, responsive design, animation, and analytics. Built upon a flexible Element base component, App-Studio empowers developers to build high-quality, efficient, and scalable projects faster.

• Core Element Component: A versatile base for all UI elements, offering extensive styling via props, including responsive (media) and state-based (on) styles.
• Rich Component Library: Includes components for layout (View, Horizontal, Vertical, etc.), text (Text), images (Image, ImageBackground), forms (Form, Input, Button), and loading states (Skeleton).
• Powerful Styling: Utilizes a utility-prop system for direct styling, alongside support for standard CSS and the css prop.
• Integrated Theming: ThemeProvider and useTheme hook for managing light/dark modes, custom color palettes, and consistent design tokens.
• Responsive Design: ResponsiveProvider and useResponsive hook provide tools to adapt layouts and styles based on screen size and orientation.
• Animation System: A declarative Animation object for easily applying and sequencing CSS animations and transitions, including scroll-driven effects.
• Helpful Hooks: A collection of hooks for managing state, detecting interactions (useHover, useActive, useFocus), tracking viewport status (useInView, useOnScreen), handling events (useClickOutside, useKeyPress), and more.
• Analytics Integration: AnalyticsProvider to easily integrate event tracking.
• TypeScript Support: Fully typed for a better development experience.

Get started with App-Studio by installing it via npm and setting up the necessary providers in your application root.

Prerequisites

• Node.js (>= 14.x recommended)
• React (>= 17.x recommended)

Installation Steps

1. Install the package using npm or yarn:

   npm install --save app-studio
   # or
   yarn add app-studio

2. Wrap your application with the core providers. Typically, you'll need ThemeProvider, ResponsiveProvider, and potentially AnalyticsProvider and WindowSizeProvider.

   import React from 'react';
   import {
     ThemeProvider,
     ResponsiveProvider,
     AnalyticsProvider,
     WindowSizeProvider
   } from 'app-studio';
   
   // Example analytics tracking function
   const trackMyAppEvent = ({ type, target, ...event }) => {
     console.log('Tracking Event:', { type, target, ...event });
     // Replace with your actual analytics service call, e.g.,
     // YourAnalyticsService.track(`${type}_${target || 'element'}`, event);
   };
   
   function App() {
     return (
       <ThemeProvider> {/* Manages theming (colors, modes) */}
         <ResponsiveProvider> {/* Manages responsive breakpoints and device info */}
           <WindowSizeProvider> {/* Tracks window dimensions */}
             <AnalyticsProvider trackEvent={trackMyAppEvent}> {/* Optional: Enables analytics tracking */}
               {/* Your application components go here */}
               {/* e.g., <YourMainAppComponent /> */}
             </AnalyticsProvider>
           </WindowSizeProvider>
         </ResponsiveProvider>
       </ThemeProvider>
     );
   }
   
   export default App;

The Element component is the cornerstone of App-Studio. Most other components extend Element. It acts as a highly configurable primitive that renders an HTML tag (defaulting to div, configurable via the as prop) and accepts a wide range of props for styling.

• Direct Styling Props: Apply CSS styles directly (e.g., backgroundColor="blue", padding={10}).
• Responsive Styles: Use the media prop to define styles for specific breakpoints (e.g., media={{ mobile: { padding: 8 }, desktop: { padding: 16 } }}).
• State-Based Styles: Use the on prop to apply styles based on interaction states like hover, focus, or active (e.g., on={{ hover: { backgroundColor: 'lightgray' } }}).
• Animation: Integrates with the animation system via the animate prop.
• Theming: Automatically resolves theme colors (e.g., color="theme.primary").

App-Studio generates CSS utility classes based on the props you provide to Element and its derived components. This approach keeps styles co-located with the component logic and optimizes performance by reusing generated classes.

Use ThemeProvider to define global theme settings, including light/dark mode colors and custom theme tokens (e.g., primary, secondary). The useTheme hook provides access to the current theme mode (themeMode), theme configuration (theme), a function to switch modes (setThemeMode), and the essential getColor function to resolve color strings (like color.blue.500 or theme.primary) into actual CSS color values for the current mode.

You can also directly access specific theme mode colors using the light. or dark. prefix (e.g., light.white or dark.red.200), which will always use that specific theme mode's color regardless of the current theme setting.

Wrap your app in ResponsiveProvider (optionally configuring custom breakpoints and devices). Use the useResponsive hook to access the current breakpoint (screen), device type (currentDevice), orientation, and helper functions (on, is) to conditionally render components or apply styles. You can also use the media prop on Element components for responsive styling.

App-Studio includes a powerful animation system accessible via the Animation object. Apply pre-defined animations (Animation.fadeIn, Animation.slideInLeft, etc.) or create custom keyframe animations using the animate prop on any Element-based component. Animations can be sequenced, triggered by events (on prop), or applied responsively (media prop).

App-Studio provides a set of reusable components built on the Element base.

The fundamental building block. Renders as a specified HTML tag (as prop, defaults to div) and accepts extensive styling props.

Key Props:

Example:

import { Element } from 'app-studio';

function MyStyledElement() {
  return (
    <Element
      as="section"
      padding={16}
      backgroundColor="color.blue.500"
      borderRadius={8}
      color="color.white"
      on={{ hover: { backgroundColor: 'color.blue.600' } }}
      media={{ mobile: { padding: 8 } }}
    >
      This is a styled section.
    </Element>
  );
}

In addition to global theming via ThemeProvider, the Element component offers granular control through the themeMode, colors, and theme props. When specified, these props locally override the context provided by ThemeProvider for this specific element instance and how its style props (like backgroundColor="theme.primary" or color="color.blue.500") resolve color values. themeMode forces 'light' or 'dark' mode resolution, colors provides a custom { main, palette } object, and theme supplies custom token mappings (e.g., { primary: 'color.purple.500' }). This allows creating distinctly styled sections or components without altering the global theme, useful for sidebars, specific UI states, or component variations.

Example (Local Theme Override):

import { Element, Text } from 'app-studio';

function LocallyThemedSection() {
  // Assume the global theme is currently 'light' mode.

  // Define a local override theme and colors for this specific section
  const localThemeOverride = { primary: 'color.orange.500', secondary: 'color.teal.300' };
  const localDarkColorsOverride = {
    main: {
      white: '#EEE'
    }
  }; // Using defaults for demonstration

  return (
    <Element
      padding={20}
      marginVertical={10}
      // Force dark mode and provide specific theme/color definitions JUST for this Element
      themeMode="dark"
      theme={localThemeOverride}
      colors={localDarkColorsOverride}
      // Styles below will resolve using the LOCAL dark theme override defined above:
      backgroundColor="theme.secondary" // Resolves to 'color.teal.300' via localThemeOverride in dark mode
      borderRadius={8}
    >
      <Text color="color.white"
      colors={localDarkColorsOverride}> {/* 'color.white' from localDarkColorsOverride.main */}
        This section forces dark mode with an orange primary, even if the app is light.
      </Text>
      <Element marginTop={8} padding={10} backgroundColor="color.gray.700"> {/* Uses local dark palette */}
         <Text color="theme.primary">Nested Primary (Orange)</Text> {/* Still uses local override */}
      </Element>
    </Element>
  );
}

A versatile container component extending Element, primarily used for layout. Defaults to div.

Key Features:

• Inherits all Element props.
• Ideal for structuring UI and applying layout styles (Flexbox, Grid).

Variants:

• Horizontal: A View with display: flex, flexDirection: row.
• Vertical: A View with display: flex, flexDirection: column.
• HorizontalResponsive: Switches from row to column on mobile.
• VerticalResponsive: Switches from column to row on mobile.
• Scroll: Basic scrollable view (might need explicit overflow styles).
• SafeArea: A view with overflow: auto.
• Div, Span: Aliases for Element rendering div and span respectively.

Example:

import { View, Horizontal, Text } from 'app-studio';

function MyLayout() {
  return (
    <View padding={16} backgroundColor="color.gray.100">
      <Horizontal gap={8} alignItems="center">
        <View width={50} height={50} backgroundColor="color.red.500" borderRadius="50%" />
        <Text fontSize="lg" fontWeight="bold">Item Title</Text>
      </Horizontal>
    </View>
  );
}

A component for rendering text content, extending Element. Defaults to span.

Key Features:

• Inherits all Element props.
• Applies typography styles easily (fontSize, fontWeight, lineHeight, textAlign, etc.).
• Supports toUpperCase prop.

Key Props (in addition to Element props):

Example:

import { Text } from 'app-studio';

function MyText() {
  return (
    <Text
      fontSize="xl"
      fontWeight="bold"
      color="theme.primary"
      textAlign="center"
      toUpperCase
    >
      Important Heading
    </Text>
  );
}

An optimized image component extending Element. Renders an <img> tag.

Key Features:

• Inherits Element props relevant to images.
• Supports standard src, alt attributes.
• Potentially supports features like lazy loading or fallbacks (verify implementation specifics if needed).

Key Props (in addition to relevant Element props):

Variant:

• ImageBackground: Renders an Element (div) with the image applied as a backgroundImage (covers and no-repeat). Takes src prop.

Example:

import { Image, ImageBackground, Text } from 'app-studio';

function MyImage() {
  return (
    <>
      <Image src="logo.png" alt="Company Logo" width={100} height={50} objectFit="contain" />

      <ImageBackground src="hero.jpg" height={200} width="100%" display="flex" alignItems="center" justifyContent="center">
        <Text color="color.white" fontSize="2xl">Overlay Text</Text>
      </ImageBackground>
    </>
  );
}

Simplifies form creation and handling. Extends Element and renders a <form> tag.

Key Features:

• Inherits Element props.
• Handles form submission via onSubmit.
• Includes styled sub-components Form.Input and Form.Button.

Sub-components:

• Input: Extends Element, renders an <input> tag. Accepts standard input attributes (name, type, placeholder, value, onChange, etc.) and styling props.
• Button: Extends Element, renders a <button> tag. Accepts standard button attributes (type, disabled, etc.) and styling props. Handles onClick.

Key Props (Form):

Example:

import { Form, Input, Button } from 'app-studio';

function MyForm() {
  const handleSubmit = (event) => {
    event.preventDefault();
    const formData = new FormData(event.target);
    const data = Object.fromEntries(formData.entries());
    console.log('Form Data:', data);
  };

  return (
    <Form onSubmit={handleSubmit} display="flex" flexDirection="column" gap={12}>
      <Input name="username" placeholder="Username" padding={8} borderRadius={4} border="1px solid color.gray.300" />
      <Input name="password" type="password" placeholder="Password" padding={8} borderRadius={4} border="1px solid color.gray.300" />
      <Button type="submit" backgroundColor="color.blue.500" color="color.white" padding={10} borderRadius={4} cursor="pointer">
        Log In
      </Button>
    </Form>
  );
}

Displays a placeholder loading state, often with a shimmer animation. Extends View.

Key Props (in addition to View props):

Example:

import { Skeleton } from 'app-studio';

function UserProfileLoading() {
  return (
    <View display="flex" alignItems="center" gap={12}>
      <Skeleton width={50} height={50} borderRadius="50%" />
      <View flex={1} display="flex" flexDirection="column" gap={8}>
        <Skeleton height={20} width="60%" />
        <Skeleton height={16} width="80%" />
      </View>
    </View>
  );
}

App-Studio provides a powerful and declarative way to add animations using the Animation object and the animate prop on Element-based components.

Basic Usage

Import the Animation object and pass animation configurations to the animate prop.

import { View, Animation } from 'app-studio';

function AnimatedComponent() {
  return (
    <View
      animate={Animation.fadeIn({ duration: '0.5s' })}
      padding={20}
      backgroundColor="color.blue.200"
    >
      Fades In
    </View>
  );
}

Event-Based Animations

Trigger animations on interaction states using the on prop.

import { Button, Animation } from 'app-studio';

function HoverButton() {
  return (
    <Button
      padding={10}
      on={{
        hover: {
          animate: Animation.pulse({ duration: '1s', iterationCount: 'infinite' })
        }
      }}
    >
      Hover Over Me
    </Button>
  );
}

Animation Sequences

Pass an array of animation configurations to the animate prop to create sequences. Delays are automatically calculated based on previous animation durations and delays.

import { View, Animation } from 'app-studio';

function SequencedAnimation() {
  const sequence = [
    Animation.fadeIn({ duration: '1s' }), // Fades in over 1s
    Animation.slideInRight({ duration: '0.5s', delay: '0.2s' }) // Slides in 0.2s after fade-in finishes
  ];

  return (
    <View
      animate={sequence}
      padding={20}
      backgroundColor="color.green.200"
    >
      Sequence
    </View>
  );
}

Available Animations (Animation.*)

A wide range of pre-defined animations are available (check element/Animation.tsx for the full list and options):

• Fades: fadeIn, fadeOut, fadeInDown, fadeInUp, etc.
• Slides: slideInLeft, slideInRight, slideOutLeft, slideOutRight, etc.
• Zooms: zoomIn, zoomOut, zoomInDown, etc.
• Bounces: bounce, bounceIn, bounceOut.
• Rotations: rotate, flip, flipInX, flipInY.
• Attention Seekers: pulse, shake, swing, tada, jello, heartBeat, headShake, wobble, flash.
• Special Effects: shimmer, lightSpeedIn, lightSpeedOut, hinge, jackInTheBox, rollIn, rollOut.
• Scroll-Driven: fadeInScroll, slideInLeftScroll, scaleDownScroll, etc. (These often require specific CSS setups like animation-timeline).

Animation Properties

Each animation function accepts an options object:

interface AnimationProps {
  from?: CSSProperties | any; // Starting styles (for keyframes)
  to?: CSSProperties | any;   // Ending styles (for keyframes)
  '0%'?: CSSProperties | any; // Specific keyframe styles
  // ... other percentage keys like '50%'
  duration?: string;        // e.g., '1s', '500ms'
  timingFunction?: string;  // e.g., 'ease', 'linear', 'ease-in-out', 'steps(N)'
  delay?: string;           // e.g., '0.2s', '100ms'
  iterationCount?: string | number; // e.g., '1', 'infinite'
  direction?: 'normal' | 'reverse' | 'alternate' | 'alternate-reverse';
  fillMode?: 'none' | 'forwards' | 'backwards' | 'both';
  playState?: 'running' | 'paused';
  timeline?: string;        // For scroll-driven animations (e.g., 'scroll()', 'view()', '--custom-timeline')
  range?: string;           // For scroll-driven animations (e.g., 'cover 0% cover 50%', 'entry', 'exit')
}

Responsive Animations

Combine animate with the media prop for different animations on different screen sizes.

import { View, Animation } from 'app-studio';

function ResponsiveAnimation() {
  return (
    <View
      padding={20}
      backgroundColor="color.purple.200"
      media={{
        mobile: {
          animate: Animation.fadeIn({ duration: '1s' })
        },
        tablet: {
          animate: Animation.slideInLeft({ duration: '0.8s' })
        }
      }}
    >
      Responsive Animation
    </View>
  );
}

App-Studio provides hooks for common UI logic and state management needs.

(Note: Descriptions below are based on the provided code structure. Verify specific usage details.)

Examples:

// useHover Example
import { useHover } from 'app-studio';
import { View } from './components/View'; // Assuming View component path

function HoverComponent() {
  const [hoverRef, isHovered] = useHover();
  return (
    <View ref={hoverRef} padding={20} backgroundColor={isHovered ? 'color.gray.200' : 'color.white'}>
      Hover over me!
    </View>
  );
}

// useResponsive Example
import { useResponsive } from 'app-studio';
import { View, Text } from './components/Components'; // Assuming component paths

function ResponsiveComponent() {
  const { screen, orientation, on } = useResponsive();
  return (
    <View>
      <Text>Current Screen: {screen}, Orientation: {orientation}</Text>
      {on('mobile') && <Text color="color.red.500">This only shows on mobile!</Text>}
      {on('desktop') && <Text color="color.blue.500">This only shows on desktop!</Text>}
      {/* Check specific breakpoint */}
      {on('md') && <Text>Medium screen size detected.</Text>}
    </View>
  );
}

// useInView Example
import { useInView } from 'app-studio';
import { View, Animation } from './components/Components'; // Assuming component paths

function LazyLoadComponent() {
  const { ref, inView } = useInView({ triggerOnce: true, threshold: 0.1 });

  return (
    <View ref={ref} height={200} backgroundColor="color.gray.100">
      {inView ? (
        <View animate={Animation.fadeIn()}>Content loaded!</View>
      ) : (
        'Waiting to scroll into view...'
      )}
    </View>
  );
}

Providers wrap parts of your application to offer context and global state.

Manages the application's theme, including color palettes, light/dark modes, and theme tokens.

Props:

Context Values (via useTheme)

• getColor(colorName, mode?): Resolves a color string (e.g., color.blue.500, theme.primary, blackAlpha.500) to its CSS value for the specified or current theme mode.
• theme: The merged theme configuration object.
• themeMode: The current mode ('light' or 'dark').
• setThemeMode(mode): Function to change the theme mode.

Provides context about the current screen size, orientation, and device type based on configured breakpoints.

Props:

Context Values (via useResponsive)

• breakpoints: The configured breakpoints object.
• devices: The configured devices object.
• mediaQueries: Generated media query strings for each breakpoint.
• currentWidth: Current window width.
• currentHeight: Current window height.
• currentBreakpoint: The name of the currently active breakpoint (e.g., 'sm', 'lg').
• currentDevice: The name of the currently inferred device type (e.g., 'mobile', 'desktop').
• orientation: Current screen orientation ('landscape' or 'portrait').
• on(name) / is(name): Function to check if the current screen matches a breakpoint or device name.

Enables event tracking throughout the application. Components like Element automatically track click events if onClick is provided and this provider is used.

Props:

Example Usage (Provider Setup):

See the Installation section.

Provides the current dimensions of the browser window via the useWindowSize hook.

Props: None.

Context Values (via useWindowSize)

• width: Current window width in pixels.
• height: Current window height in pixels.

App-Studio exports utility objects and functions.

Defines the default color palettes (defaultLightPalette, defaultDarkPalette) and singleton colors (defaultLightColors, defaultDarkColors) used by ThemeProvider. You can import these if needed for custom theme configurations. Colors are accessed within components primarily via the getColor function from useTheme.

Accessing Colors:

import { useTheme } from 'app-studio';
import { View } from './components/View';

function ThemedComponent() {
  const { getColor } = useTheme();

  return (
    <View
      backgroundColor={getColor('theme.primary')} // Get theme color
      color={getColor('color.white')}            // Get singleton color
      borderColor={getColor('color.blue.300')}     // Get palette color
      padding={10}
    >
      My Themed Content
    </View>
  );
}

Exports the Typography object containing pre-defined scales for letterSpacings, lineHeights, fontWeights, and fontSizes. These are typically used internally or can be referenced when customizing themes.

Exports the Shadows object, which maps numbers (0-9) to box-shadow configurations used by the shadow prop on Element.

May export various constants used within the library (e.g., internal configuration keys). Check the file for specifics if needed.

import { View, Text, useResponsive } from 'app-studio';

function ResponsiveCard() {
  const { on } = useResponsive();

  return (
    <View
      flexDirection={on('mobile') ? 'column' : 'row'} // Stack on mobile, row otherwise
      padding={16}
      backgroundColor="color.white"
      borderRadius={8}
      shadow={2} // Apply shadow level 2
      gap={on('mobile') ? 12 : 20}
    >
      <View flex={1}> {/* Use flex for layout control */}
        <Text fontWeight="bold" fontSize="lg">Card Title</Text>
        <Text color="color.gray.600">Some descriptive content here.</Text>
      </View>
      <View width={on('mobile') ? '100%' : 100} height={100} backgroundColor="color.blue.100" borderRadius={4}>
        {/* Image or placeholder */}
      </View>
    </View>
  );
}

import { Button, Animation } from 'app-studio';

function AnimatedButton() {
  return (
    <Button
      paddingHorizontal={20}
      paddingVertical={10}
      backgroundColor="color.green.500"
      color="color.white"
      borderRadius={5}
      fontWeight="bold"
      animate={Animation.fadeIn({ duration: '0.5s' })}
      on={{
        hover: {
          backgroundColor: 'color.green.600',
          animate: Animation.pulse({ duration: '0.8s', iterationCount: 2 })
        },
        active: {
          transform: 'scale(0.95)' // Simple transform on active
        }
      }}
    >
      Click Me
    </Button>
  );
}

Explore our comprehensive documentation to learn more about App-Studio:

• Getting Started - Quick start guide and core concepts
• Components - Detailed documentation of all available components
• Hooks - Guide to the React hooks provided by App-Studio
• Theming - How to customize the look and feel of your app
• Animation - Creating animations with App-Studio
• Responsive Design - Building responsive layouts
• Design System - Understanding the design system
• Event Handling - Working with events and interactions
• Providers - Context providers for global state
• Migration Guide - Migrating to App-Studio

• Core: Element
• Components: View, Horizontal, Vertical, HorizontalResponsive, VerticalResponsive, Scroll, SafeArea, Div, Span, Text, Image, ImageBackground, Form, Input, Button, Skeleton.
• Animation: Animation object with functions like fadeIn, slideInLeft, pulse, etc.
• Hooks: useActive, useClickOutside, useFocus, useHover, useInView, useKeyPress, useMount, useOnScreen, useResponsive, useScroll, useWindowSize.
• Providers: ThemeProvider, ResponsiveProvider, AnalyticsProvider, WindowSizeProvider.
• Context Hooks: useTheme, useResponsiveContext, useAnalytics, useWindowSize.
• Utilities: colors, Typography, Shadows.

Contributions are welcome! Please follow standard procedures:

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/your-feature-name).
3. Make your changes.
4. Add tests for your changes.
5. Commit your changes (git commit -m 'Add some feature').
6. Push to the branch (git push origin feature/your-feature-name).
7. Open a Pull Request.

(Maintain a log of versions and changes here)

• vX.Y.Z (Date):
  • Description of changes.
• v1.0.0 (Initial Release):
  • Core Element component.
  • Basic components: View, Text, Image, Form, Skeleton.
  • Hooks for interactions, viewport, and responsiveness.
  • Providers for Theme, Responsiveness, Analytics, WindowSize.
  • Animation system via Animation object.