olova 2.0.3 → 2.0.4

package/README.md

@@ -1,54 +1,258 @@
-# Olova JavaScript Framework
+# 🚀 Olova Framework Documentation
 
-Olova is a lightweight and reactive JavaScript framework that simplifies UI
-development with a clean, intuitive syntax. It provides a reactivity system and
-hooks to manage state and side effects, allowing developers to build modern web
-applications with ease.
+> A lightweight JavaScript framework for building web applications with JSX
 
-## Features
+## What is Olova?
 
-- **State Management**: Use the `State` hook to manage reactive state in your
-  components.
-- **Side Effects**: Use the `Effect` hook to run side effects in response to
-  state changes.
-- **JSX-style Syntax**: Write UI components using a simple, declarative
-  JSX-style syntax.
-- **Reactivity**: Automatically re-render components when state changes.
+Olova is a simple yet powerful JavaScript framework that lets you build web
+applications using JSX. It directly manipulates the DOM without a Virtual DOM,
+making it lightweight and straightforward to use.
 
-## Installation
+## ⚡ Quick Start
 
-To get started with Olova, first install the core library via npm or yarn.
+### Installation
+
+Get started with a single command:
 
 ```bash
-npm install olova
+npm create vilo@latest
 ```
 
-or
+This command will set up a new Olova project, similar to how Vite works. You can
+use it to create an Olova template or install Olova in an existing project.
+
+Alternatively, you can install Olova directly:
 
 ```bash
-yarn add olova
+npm install olova
+```
+
+### Your First Olova App
+
+```jsx
+import Olova from "olova";
+
+const App = () => {
+  return (
+    <>
+      <h1>Welcome to Olova! 🎉</h1>
+      <p>Building web apps made simple.</p>
+    </>
+  );
+};
+```
+
+## 🎯 Core Concepts
+
+### Built-in Hooks
+
+Olova provides several essential hooks for building dynamic applications:
+
+```jsx
+import {
+  $signal, // Manage component state
+  $effect, // Handle side effects
+  $memo, // Memoize values
+  $ref, // Reference DOM elements
+  $context, // Share data between components
+  $callback, // Memoize functions
+} from "olova";
+```
+
+### Default Exports
+
+Olova comes with two built-in utilities:
+
+```jsx
+import Olova, { h, Fragment } from "olova";
+
+// h: Element generator (automatically used for JSX transformation)
+// Fragment: Wrapper for multiple elements, can be used as <></> or <Fragment></Fragment>
 ```
 
-## Example Usage
+## 💫 Using Hooks
 
-Here is an example of a basic component in Olova:
+### State Management
 
-```js
-import Olova, { State, Effect } from "olova";
+```jsx
+import Olova, { $signal } from "olova";
 
-export default function Home() {
+const Counter = () => {
   const [count, setCount] = State(0);
 
+  return <button onClick={() => setCount(count + 1)}>Count: {count}</button>;
+};
+```
+
+### Side Effects
+
+```jsx
+import Olova, { $effect, $signal } from "olova";
+
+const DataFetcher = () => {
+  const [data, setData] = State(null);
+
   Effect(() => {
-    console.log("Home is rendered");
-    console.log(count);
-  }, [count]);
+    fetch("/api/data")
+      .then((res) => res.json())
+      .then(setData);
+  }, []); // Empty array means run once on mount
 
-  return (
-    <>
-      <h1>{count}</h1>
-      <button onClick={() => setCount(count + 1)}>Increment</button>
-    </>
-  );
-}
+  return <div>{data ? "Data loaded!" : "Loading..."}</div>;
+};
+```
+
+### Using References
+
+```jsx
+import Olova, { $ref } from "olova";
+
+const FocusInput = () => {
+  const inputRef = $ref(null);
+
+  return <input ref={inputRef} onFocus={() => console.log("Input focused!")} />;
+};
+```
+
+### Memoization
+
+```jsx
+import Olova, { $memo, $signal } from "olova";
+
+const ExpensiveComponent = ({ data }) => {
+  const processedData = Memo(() => {
+    // Expensive computation here
+    return data.map((item) => item * 2);
+  }, [data]);
+
+  return <div>{processedData.join(", ")}</div>;
+};
+```
+
+## 🎨 Styling in Olova
+
+Olova supports all standard CSS approaches:
+
+### CSS Imports
+
+```jsx
+import "./styles.css";
+
+const StyledComponent = () => (
+  <div className="my-component">Styled content</div>
+);
+```
+
+### CSS Modules
+
+```jsx
+import styles from "./Component.module.css";
+
+const ModuleStyledComponent = () => (
+  <div className={styles.container}>Module styled content</div>
+);
+```
+
+### Inline Styles
+
+```jsx
+const InlineStyledComponent = () => (
+  <div style={{ padding: "20px", color: "blue" }}>Inline styled content</div>
+);
 ```
+
+## 🔮 How Olova Works
+
+1. **Direct DOM Manipulation**
+
+1. Olova directly updates the DOM without a Virtual DOM
+1. Efficient updates when state changes
+1. Lightweight and fast performance
+
+1. **JSX Transformation**
+
+1. Uses the `h` function to transform JSX into DOM elements
+1. Handles event binding automatically
+1. Manages component lifecycle efficiently
+
+## 📚 Best Practices
+
+### Component Structure
+
+```jsx
+// Good: Single responsibility component
+const UserProfile = ({ user }) => (
+  <div className="profile">
+    <img src={user.avatar || "/placeholder.svg"} alt={user.name} />
+    <h2>{user.name}</h2>
+  </div>
+);
+
+// Better: Using Fragment for multiple elements
+const UserCard = ({ user }) => (
+  <>
+    <UserProfile user={user} />
+    <UserStats stats={user.stats} />
+  </>
+);
+```
+
+### Hook Usage
+
+```jsx
+// Effective use of multiple hooks
+const UserDashboard = () => {
+  const [user, setUser] = State(null);
+  const userCache = $ref({});
+
+  Effect(() => {
+    // Side effect cleanup example
+    return () => {
+      userCache.current = {};
+    };
+  }, []);
+
+  return <div>Dashboard Content</div>;
+};
+```
+
+## 🚀 Coming Soon
+
+- More built-in hooks
+- Enhanced development tools
+- Additional utility functions
+- Performance optimizations
+
+## 🤝 Contributing
+
+We welcome contributions! Whether it's:
+
+- Bug reports
+- Feature requests
+- Documentation improvements
+- Pull requests
+
+## 📖 Examples
+
+Find more examples in our [GitHub repository](https://github.com/olovajs/olova).
+
+## 🛠 Using Vilo
+
+Vilo is a project creation tool for Olova, similar to Vite. You can use it to
+quickly set up new Olova projects or add Olova to existing projects.
+
+To create a new Olova project:
+
+```bash
+npm create vilo@latest my-olova-app
+cd my-olova-app
+npm install
+npm run dev
+```
+
+This will set up a new Olova project with a basic template, ready for you to
+start developing.
+
+---
+
+Made with simplicity in mind 🌟

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "olova",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "A lightweight JavaScript framework for building reactive applications.",
   "main": "dist/olova.js",
   "keywords": [