ladrillosjs 1.0.0-rc.8 → 1.0.0

package/README.md

@@ -6,168 +6,466 @@ A lightweight, zero-dependency web component framework for building modular web
 
 "I designed this framework to empower developers with the ability to componentize their code efficiently and effectively, without the need for a full-scale framework. By focusing on simplicity and leveraging core web fundamentals, my goal was to create a lightweight and accessible solution that enhances development while staying true to the basics."
 
-## Getting Starting with samples
+## Table of Contents
+
+- [Features](#features)
+- [Getting Started](#getting-started)
+- [Installation](#installation)
+- [Your First Component](#your-first-component)
+- [Core Concepts](#core-concepts)
+  - [Component Registration](#component-registration)
+  - [State Management](#state-management)
+  - [Event Handling](#event-handling)
+  - [Data Binding](#data-binding)
+  - [Conditional Rendering](#conditional-rendering)
+  - [Slots](#slots)
+- [Advanced Features](#advanced-features)
+  - [External Scripts](#external-scripts)
+  - [Global State Stores](#global-state-stores)
+  - [Shadow DOM](#shadow-dom)
+- [API Reference](#api-reference)
+- [Examples](#examples)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+- 🚀 **Zero Dependencies** - Pure JavaScript, no build tools required
+- 📦 **Single-File Components** - HTML, CSS, and JavaScript in one file
+- ⚡ **Reactive State** - Automatic re-rendering on state changes
+- 🎯 **Event System** - Built-in event emission and listening
+- 🔄 **Two-Way Data Binding** - For form inputs and contenteditable elements
+- 🎨 **Scoped Styles** - Component styles with optional Shadow DOM
+- 🏪 **State Management** - Simple store implementation for shared state
+- 🔌 **Slots Support** - Content projection with named and default slots
+- 📝 **TypeScript Support** - Includes type definitions
+
+## Getting Started
+
+The repository includes several example applications that demonstrate various features:
+
+- **[Todo App](samples/apps/todo)** - Classic todo list with component composition
+- **[Notes App](samples/apps/notes)** - Multi-component app with global state management
+- **[Markdown Editor](samples/apps/markdown)** - Real-time markdown preview
+- **[API Example](samples/apps/api)** - Fetching and displaying external data
+- **[Business Card](samples/apps/biz)** - Editable form with two-way data binding
+- **[Button Game](samples/apps/button-game)** - Interactive game with component events
+- **[Slideshow](samples/apps/slideshow)** - Multi-slide presentation system
+- **[Docs](samples/apps/docs)** - Documentation viewer with syntax highlighting
+
+To run the examples:
 
-1. `npm install`
-2. `npm run dev`
+```bash
+# Clone the repository
+git clone https://github.com/drubiodev/LadrillosJS.git
+cd LadrillosJS
+
+# Install dependencies (for dev server only)
+npm install
 
-## Usage
+# Start the development server
+npm run dev
+```
 
-### Install & import
+## Installation
+
+### NPM
 
 ```bash
 npm install ladrillosjs
 ```
 
-This will spin up Vite with the `samples` folder as the web root.
-
-### cdn
+### CDN
 
-```js
+```html
 <script defer src="https://cdn.jsdelivr.net/npm/ladrillosjs"></script>
 ```
 
-## First Component
+## Your First Component
 
-A component in LadrillosJS is a reusable custom HTML element that bundles its own template, logic (bindings) and styles into a single file.
+A component in LadrillosJS is a reusable custom HTML element that bundles its own template, logic, and styles into a single file.
 
-To create your first component, follow these steps:
+### 1. Create a Component File
 
-1. Create an HTML file that defines your component’s template, script bindings and CSS. For example:
+Create `hello-world.html`:
 
-   ```html
-   <!-- hello.html -->
+```html
+<!-- hello-world.html -->
+<div class="greeting">
+  <h1>{title}</h1>
+  <p>Hello, {name}!</p>
+  <button onclick="greet">Click me ({count})</button>
+</div>
 
-   <p>Hello, LadrillosJS!</p>
-   <button onclick="increment">Clicked {count} times</button>
+<script>
+  // Component state
+  let title = "Welcome to LadrillosJS";
+  let name = "World";
+  let count = 0;
+
+  // Event handler
+  const greet = () => {
+    count++;
+    name = prompt("What's your name?") || "World";
+  };
+</script>
 
-   <script>
-     // declare a bound variable
-     let count = 0;
+<style>
+  .greeting {
+    text-align: center;
+    padding: 2rem;
+    background: #f0f0f0;
+    border-radius: 8px;
+  }
+
+  button {
+    padding: 0.5rem 1rem;
+    font-size: 1rem;
+    cursor: pointer;
+  }
+</style>
+```
 
-     // declare a handler for the button click
-     const increment = () => {
-       count++;
-       // update component state and re-render
-       this.setState({ count });
-     };
-   </script>
+### 2. Register and Use the Component
 
-   <style>
-     /* component‐scoped CSS */
-     p {
-       font-size: 1.25rem;
-       color: #1a73e8;
-     }
-     button {
-       margin-top: 0.5rem;
-       padding: 0.5rem 1rem;
-     }
-   </style>
-   ```
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>My App</title>
+  </head>
+  <body>
+    <!-- Use your component -->
+    <hello-world></hello-world>
+
+    <!-- Register component -->
+    <script type="module">
+      import { registerComponent } from "ladrillosjs";
+      registerComponent("hello-world", "./hello-world.html");
+    </script>
+  </body>
+</html>
+```
 
-2. Import and register your component in the page where you want to use it:
+## Core Concepts
 
-   ```html
-   <!-- import -->
-   <script type="module">
-     import { registerComponent } from "ladrillosjs";
+### Component Registration
 
-     registerComponent("hello-world", "hello-world.html");
-   </script>
+Register single or multiple components:
 
-   <!-- CDN -->
-   <script type="module">
-     ladrillosjs.registerComponent("hello-world", "hello-world.html");
-   </script>
-   ```
+```javascript
+// Single component
+import { registerComponent } from "ladrillosjs";
+registerComponent("my-component", "./my-component.html");
 
-   ```html
-   <!-- then use it in markup -->
-   <hello-world></hello-world>
-   ```
+// Multiple components with concurrency control
+import { registerComponents } from "ladrillosjs";
+await registerComponents(
+  [
+    { name: "app-header", path: "./components/header.html" },
+    { name: "app-footer", path: "./components/footer.html" },
+    { name: "user-card", path: "./components/user-card.html" },
+  ],
+  10
+); // Max 10 parallel fetches (default: 5)
 
-Under the hood, LadrillosJS will fetch, parse and cache hello.html, then define a `<hello-world>`.
+// Using CDN
+ladrillosjs.registerComponent("my-component", "./my-component.html");
+```
 
-- Template placeholders `{…}` automatically bind to this.state.
-- Top‐level `let/const/function` in your `<script>` block are hoisted and initialized into `this.state` if they appear in a template or event.
-- Event attributes like `onclick="increment"` register listeners under the hood.
+### State Management
 
-## Binding Variables & Events
+Components have reactive state that automatically triggers re-renders:
 
-- To bind data into your markup, wrap state keys in `{}`
+```html
+<div>
+  <h2>User: {user.name}</h2>
+  <p>Score: {score}</p>
+  <button onclick="updateScore">Add Point</button>
+</div>
+
+<script>
+  const date = new Date(Date.now());
+  const formattedDate = date.toLocaleDateString("en-US"); // Format: MM/DD/YYYY
+  // Initial state
+  let score = 0;
+  let user = {
+    name: "Player 1",
+  };
+
+  const updateScore = () => {
+    // Update state and trigger re-render
+    score++;
+  };
+</script>
+```
+
+### Event Handling
+
+Multiple ways to handle events:
 
 ```html
-<span>{user.name}</span>
+<!-- Method reference -->
+<button onclick="handleClick">Click me: {count}</button>
+
+<!-- Function with arguments -->
+<button onclick="addItem('Hello', 123)">Add Item</button>
+
+<!-- Inline arrow function -->
+<button onclick="(e) => console.log(e.target)">Log Target</button>
+
+<script>
+  const count = 0;
+  this.setState({ items: [] });
+
+  const handleClick = (event) => {
+    console.log("Clicked!", event);
+    count++;
+  };
+
+  const addItem = (name, value) => {
+    this.setState({ items: [...this.state.items, { name, value }] });
+  };
+</script>
+<div>
+  <h1>Shopping Cart ({items.length} items)</h1>
+
+  <div data-if="items.length === 0">
+    <p>Your cart is empty</p>
+  </div>
+
+  <div data-else-if="items.length < 3">
+    <p>You have a few items</p>
+  </div>
+
+  <div data-else>
+    <p>You have many items!</p>
+  </div>
+
+  <button data-if="!isLoggedIn" onclick="login">Login</button>
+  <button data-else onclick="logout">Logout</button>
+</div>
+<script>
+  const items = ["apple", "banana", "orange"];
+  const isLoggedIn = false;
+
+  function login() {
+    isLoggedIn = true;
+  }
+
+  function logout() {
+    isLoggedIn = false;
+  }
+</script>
 ```
 
-- To bind an event, prefix an attribute with `on`:
+### Slots
+
+Content projection using slots:
 
 ```html
-<button onclick="doSomething">Do it</button>
+<!-- card.html -->
+<div class="card">
+  <div class="card-header">
+    <slot name="header">Default Header</slot>
+  </div>
+  <div class="card-body">
+    <slot></slot>
+    <!-- Default slot -->
+  </div>
+  <div class="card-footer">
+    <slot name="footer"></slot>
+  </div>
+</div>
+
+<!-- Usage -->
+<my-card>
+  <h2 slot="header">User Profile</h2>
+  <p>This goes in the default slot</p>
+  <button slot="footer">Save</button>
+</my-card>
 ```
 
-## Initializing from Attributes
+## Advanced Features
 
-Component attributes sync to `this.state` automatically and can be reference by using `this.state["some-prop"]` in your template or code.
+### External Scripts
 
-## Internal vs. External Scripts
+Load external JavaScript with components:
 
-- Inline scripts (no src) are parsed, top‑level bindings registered, then executed in component context.
-- External scripts with `bind` attribute are fetched, and processed exactly like inline scripts.
+```html
+<!-- With 'bind' attribute for component context -->
+<script src="./helpers.js" bind></script>
+
+<!-- ES modules with bind -->
+<script src="./component-logic.js" type="module" bind></script>
 
-```js
-<script src="path_to_file.js" bind></script>
+<!-- Regular external script -->
+<script src="https://cdn.example.com/library.js"></script>
 ```
 
-- External scripts without bind are injected via a `<script>` tag (for non‑module, or third‑party scripts).
-- `type="module"` scripts (inline or external) are added to the shadow/root as real modules.
+For modules with `bind`, export a default function:
+
+```javascript
+// component-logic.js
+export default function () {
+  // 'this' refers to the component instance
+  this.formatDate = (date) => {
+    return new Intl.DateTimeFormat("en-US").format(date);
+  };
+
+  this.init = () => {
+    console.log("Component initialized");
+  };
 
-## Managing State
+  // Called automatically if defined
+  this.init();
+}
+```
 
-To manage state in LadrillosJS, you can use the `this.setState()` method to update the component's state. The `this.state` object holds the component's state variables, and you can modify them as needed.
+### Global State Stores
 
-When you call `this.setState({ key: value, … })`, LadrillosJS will automatically re-render the component with the updated state.
+Share state across components:
 
-## Emitting
+```javascript
+// stores/userStore.js
+import { createStore } from "ladrillosjs";
 
-To emit events from your component, you can use the `this.emit()` method. This allows you to trigger custom events that can be listened to by parent components or other parts of your application. If you don't pass a second argument, the event will be emitted with the component's state as the data.
+export const userStore = createStore({
+  user: null,
+  isAuthenticated: false,
+});
 
-```js
-this.emit("event-name", { some: "data" });
+export function login(userData) {
+  userStore.setState({
+    user: userData,
+    isAuthenticated: true,
+  });
+}
+
+export function logout() {
+  userStore.setState({
+    user: null,
+    isAuthenticated: false,
+  });
+}
 ```
 
-To listen to emitted events, you can use the `this.listen()` method on the component instance:
+```html
+<!-- header.html -->
+<header>
+  <span data-if="isAuthenticated">Welcome, {user.name}!</span>
+  <button data-else onclick="showLogin">Login</button>
+</header>
 
-```js
-this.listen("event-name", (payload) => {
-  console.log(payload); // Access the emitted data
-});
+<script type="module" src="./header-logic.js" bind></script>
+```
+
+```javascript
+// header-logic.js
+import { userStore } from "../stores/userStore.js";
+
+export default function () {
+  // Subscribe to store changes
+  userStore.subscribe((state) => {
+    this.setState({
+      user: state.user,
+      isAuthenticated: state.isAuthenticated,
+    });
+  });
+
+  this.showLogin = () => {
+    this.emit("show-login");
+  };
+}
 ```
 
-## Two‑Way Binding
+### Shadow DOM
 
-LadrillosJS provides built‑in two‑way data binding for form controls and contenteditable elements via the `data-bind` attribute.  
-When a component is initialized, any element with `data-bind="key"` will:
+Components use Shadow DOM by default for style encapsulation. To disable:
 
-- Push its initial value/content into `this.state.key`.
-- Listen for user input (e.g. `input` or `change` events) and update `this.state.key` automatically.
-- Re-render whenever you call `this.setState({ key: newValue })`, updating the element’s value or innerText.
+```javascript
+// Disable Shadow DOM for a component
+registerComponent("my-component", "./my-component.html", false);
 
-Usage example:
+// Multiple components
+registerComponents([
+  { name: "global-styles", path: "./global.html", useShadowDOM: false },
+  { name: "isolated-widget", path: "./widget.html", useShadowDOM: true },
+]);
+```
+
+## API Reference
+
+### Component Methods
+
+| Method                            | Description                                  |
+| --------------------------------- | -------------------------------------------- |
+| `this.setState(partial)`          | Update component state and trigger re-render |
+| `this.emit(eventName, data?)`     | Dispatch a custom event                      |
+| `this.listen(eventName, handler)` | Listen for custom events                     |
+| `this.querySelector(selector)`    | Query element within component               |
+| `this.querySelectorAll(selector)` | Query all elements within component          |
+
+### Store Methods
+
+| Method                      | Description                |
+| --------------------------- | -------------------------- |
+| `createStore(initialState)` | Create a new store         |
+| `store.getState()`          | Get current store state    |
+| `store.setState(partial)`   | Update store state         |
+| `store.subscribe(callback)` | Subscribe to state changes |
+| `store.reset()`             | Reset to initial state     |
+
+## Examples
+
+### Component Communication
 
 ```html
-<!-- In your component HTML -->
-<input type="text" placeholder="Username" data-bind="username" />
-<div contenteditable="true" placeholder="About you…" data-bind="bio"></div>
-<button onclick="submit">Submit</button>
+<!-- parent.html -->
+<div>
+  <child-component data-message="Hello"></child-component>
+</div>
+
+<script>
+  this.listen("child-event", (data) => {
+    console.log("Received from child:", data);
+  });
+</script>
+
+<!-- child.html -->
+<button onclick="sendMessage">{data-message}</button>
 
 <script>
-  const submit = () => {
-    console.log("Username:", this.state.username);
-    console.log("Bio:", this.state.bio);
-    // reset state
-    this.setState({ username: "", bio: "" });
+  const sendMessage = () => {
+    this.emit("child-event", {
+      message: this.state["data-message"],
+      timestamp: Date.now(),
+    });
   };
 </script>
 ```
+
+### Dynamic Component Creation
+
+```javascript
+// Create components programmatically
+const createCard = (userData) => {
+  const card = document.createElement("user-card");
+  card.setAttribute("user-id", userData.id);
+  card.setAttribute("name", userData.name);
+  document.querySelector("#user-list").appendChild(card);
+};
+
+// Fetch and create
+fetch("/api/users")
+  .then((res) => res.json())
+  .then((users) => users.forEach(createCard));
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.

package/dist/core/main.d.ts

@@ -0,0 +1,31 @@
+export const ladrillos: Ladrillos;
+export type LadrillosComponent = import("../types/LadrilloTypes").LadrillosComponent;
+/** @typedef {import('../types/LadrilloTypes').LadrillosComponent} LadrillosComponent */
+declare class Ladrillos {
+    static "__#2@#safeFetch"(url: any): Promise<string>;
+    /** @type {Record<string, LadrillosComponent>} */
+    components: Record<string, LadrillosComponent>;
+    /**
+     * Registers a web‐component by fetching its HTML, scripts, and styles.
+     * @param {string} name
+     * @param {string} path
+     * @param {boolean} [useShadowDOM=true]
+     */
+    registerComponent(name: string, path: string, useShadowDOM?: boolean): Promise<void>;
+    /**
+     * Registers multiple components with optional concurrency throttling.
+     * @param {{name: string, path: string,useShadowDOM:boolean}[]} components
+     * @param {number} [concurrency=5] max simultaneous registrations
+     */
+    registerComponents(components: {
+        name: string;
+        path: string;
+        useShadowDOM: boolean;
+    }[], concurrency?: number): Promise<any>;
+    /** @private */
+    private _runWithConcurrency;
+    /** @private */
+    private _defineWebComponent;
+    #private;
+}
+export {};

package/dist/core/store.d.ts

@@ -0,0 +1,6 @@
+export function createStore(initialState?: {}): {
+    getState(): {};
+    setState(partial: any): void;
+    subscribe(fn: any): () => boolean;
+    reset(): void;
+};

package/dist/core/webcomponent.d.ts

@@ -0,0 +1,2 @@
+export function defineWebComponent(component: LadrillosComponent, useShadowDOM: boolean): void;
+export type LadrillosComponent = import("../types/LadrilloTypes").LadrillosComponent;