npm - pawajs - Versions diffs - 1.3.0 - Mend

pawajs 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (23) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Allisboy
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,354 @@
+# pawajs
+pawajs - power the web (reactivity and html runtime)
+# PawaJS
+**A lightweight and reactive JavaScript library for building modern web interfaces with a simple, declarative syntax.**
+PawaJS is a JavaScript library designed for building dynamic user interfaces. It combines a component-based architecture and progressive enhancement with a powerful reactivity system no v-dom. Its intuitive, directive-based templating feels familiar and makes it easy to create interactive applications, from simple widgets to complex single-page apps. With built-in support for server-side rendering, PawaJS is equipped for performance and scalability.
+---
+## Features
+-   **Declarative Rendering:** Use a clean, HTML-based template syntax with powerful directives (`if`, `for`, `on-event`, etc.) to describe your UI.
+-   **Reactive State Management:** Effortlessly create reactive state that automatically updates the DOM when it changes using the `$state` utility.
+-   **Component-Based Architecture:** Build encapsulated components that manage their own state, making your code more reusable and maintainable.
+-   **Async Components:** First-class support for asynchronous components, allowing you to fetch data directly within your component definition.
+-   **Efficient List Rendering:** Render lists of data with the `for` directive, including support for keyed updates for optimal performance.
+-   **Lifecycle Hooks:** Tap into a component's lifecycle with `mount` and `unmount` directives, or the `runEffect` hook for more complex side effects.
+-   **Context API:** Pass data through the component tree without having to pass props down manually at every level.
+-   **Server-Side Rendering (SSR) Isomorphic architecture:** PawaJS is built with SSR in mind, featuring a "resuming" mechanism to efficiently continue server-rendered HTML on the client.
+-   **Plugin System:** Extend PawaJS's core functionality with custom directives and lifecycle behaviors.
+---
+## Installation
+Install PawaJS into your project using npm:
+```bash
+npm install pawajs
+```
+CDN
+```html
+    <head>
+        <script type="module" href="https://cdn.jsdelivr.net/npm/pawajs@1.2.0/cdn/index.js"></script>
+    </head>
+    <body>
+        <div id="app"></div>
+        <script type="module">
+            window.$pawa.pawaStartApp(document.getElementById('app'));
+        </script>
+    </body>
+```
+OR
+Then, you can import it into your application: through npm
+```javascript
+import { pawaStartApp, $state, RegisterComponent, html } from 'pawajs';
+```
+---
+## Getting Started: A Simple Counter
+Here's a basic example to show you how PawaJS works.
+**`index.html`**
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <title>PawaJS Counter</title>
+</head>
+<body>
+    <div id="app">
+        <h1 state-name="'PAWAJS'">@{name.value}</h1>
+        <!-- The component will be rendered here -->
+        <counter-app></counter-app>
+    </div>
+    <script type="module" src="app.js"></script>
+</body>
+</html>
+```
+**`app.js`**
+```javascript
+import { pawaStartApp, $state, useInsert, RegisterComponent, html } from './pawajs/index.js';
+// 1. Define a component
+const CounterApp = () => {
+    // 2. Create reactive state
+    const count = $state(0);
+    // 3. Define methods to modify the state
+    const increment = () => {
+        count.value++;
+    };
+    const decrement = () => {
+        count.value--;
+    };
+    // 4. Expose state and methods to the template
+    useInsert({ count, increment, decrement });
+    // 5. Return the component's template
+    return html`
+        <div>
+            <h1>PawaJS Counter</h1>
+            <p>Current count: <strong>@{count.value}</strong></p>
+            <button on-click="increment()">Increment +</button>
+            <button on-click="decrement()">Decrement -</button>
+        </div>
+    `;
+}
+// 6. Register the component
+// PawaJS converts PascalCase component names to kebab-case for use in HTML.
+RegisterComponent(CounterApp);
+// 7. Start the PawaJS application
+const appElement = document.getElementById('app');
+pawaStartApp(appElement);
+```
+---
+## Core Concepts
+### State Management with `$state`
+The `$state` function is the heart of PawaJS's reactivity. It creates a reactive object whose `value` property can be read and written to. Any changes to `.value` will automatically trigger updates in the parts of your application that depend on it (fine-granded) no component re-rendering or diffing. `$state` can be global when used outside a component. Also inline state in the html or template `state-*="any js types"`
+```html
+    <!--- number-->
+    <div state-count="0">@{count.value}<div>
+    <!--- string-->
+    <div state-name="'PAWAJS'">@{name.value}<div>
+    <!--- object-->
+    <div state-object="{name:'pawajs'}">@{object.value.name}<div>
+    <!--- boolean-->
+    <div state-login="false">@{login.value? 'Welcome back!':'Please login'}<div>
+    <!--- array-->
+    <span state-splitname="['P','A','W','A','J','S']" for="item in splitname.value">@{item}<div>
+```
+```javascript
+// Create a simple state
+const name = $state('Pawa');
+console.log(name.value); // "Pawa"
+name.value = 'PawaJS'; // The UI will update automatically
+// State can hold any data type
+const user = $state({ name: 'Alex', loggedIn: false });
+user.value.loggedIn = true; // This is also reactive
+// Persist state to localStorage
+// The state will be saved under the key 'session' and reloaded on page refresh.
+const session = $state({ id: null }, 'session');
+// Compute state - must be used inside a component
+// when ever count changes the state update
+const doubleCount=$state(()=>count.value * 2,[count])
+//AutoCompute
+// Any function that uses any reactive state for reactive bindings or direcives becomes computed function
+const doubleCount=()=>count.value * 2
+```
+### Components
+Components are the building blocks of your application. In PawaJS, a component is a JavaScript function that returns an HTML template string or not.
+-   **Defining:** Create a function that returns a template or not.
+-   **Registering:** Use `RegisterComponent(MyComponent)` to make it available globally. In HTML, you can then use it as `<my-component>`.
+-   **`useInsert`:** To make variables, state, and functions from your component's setup available in its template, pass them in an object to `useInsert()`.
+### Asynchronous Components
+PawaJS supports async components ( `useAsync()` hook) out of the box. You can define a component as an `async` function, allowing you to perform asynchronous operations (like fetching data) before the component renders.
+wrap any pawajs hook with $async after any await call
+```javascript
+const UserProfile = async () => {
+    // Async hook store the current component instance for $async to use
+    const {$async}=useAsync()
+    // The component will wait for this promise to resolve before rendering
+    const data = await fetch('/api/user').then(res => res.json());
+    const user = $async(()=>$state(data);)
+    $async(()=>useInsert({user}))
+    return html`
+        <div class="profile">
+            <h1>@{user.value.name}</h1>
+        </div>
+    `;
+}
+```
+### Templating
+PawaJS uses a simple `@{...}` syntax to embed dynamic JavaScript expressions directly into your HTML.
+```html
+<!-- Bind to text content -->
+<p>@{user.name}</p>
+<!-- Bind to attributes -->
+<div class="user-card @{user.value.isActive ? 'active' : 'inactive'}">
+    <input value="@{user.value.name}" on-input="user.value.name = e.target.value">
+</div>
+```
+### Directives
+Directives are special attributes that apply reactive behavior to DOM elements.
+#### `state-*`
+create inline state for the element and children
+```html
+    <div state-count="0">
+        <button on-click="count.value++">@{count.value}</button>
+    </div>
+```
+#### `if` / `else` / `else-if`
+For conditional rendering.
+```html
+<div if="user.value.loggedIn">
+    Welcome back, @{user.name.value}!
+</div>
+<div else-if="user.value.isGuest">
+    You are browsing as a guest.
+</div>
+<div else>
+    Please log in to continue.
+</div>
+```
+#### `switch` / `case` / `default`
+switch conditional rendering.
+```html
+<div switch="user.value.type" case="'admin'">
+    Welcome back, @{user.name.value}!
+</div>
+<div case="'guest">
+    You are browsing as a guest.
+</div>
+<div default>
+    Please log in to continue.
+</div>
+```
+#### `key`
+re-renders the element/component when the reactivity changes
+```html
+<user-component key="user.value.type"></user-component>
+```
+#### `is-exit`
+makes pawajs engine to wait before removing the element until the animation/transition is done.
+```html
+<div if="user.value.loggedIn" class="user-card @{user.value.isActive ? 'active' : 'inactive'}" is-exit>
+    <input value="@{user.value.name}" on-input="user.value.value = e.target.value">
+</div>
+```
+#### `for`
+For rendering lists from an array. Use `for-key` to give each element a unique identity, which helps PawaJS optimize rendering.
+```html
+<ul>
+    <li for="todo, i in todos.value" for-key="{{todo.id}}">
+        <span>@{i + 1}. @{todo.text}</span>
+    </li>
+</ul>
+```
+#### `on-<event>`
+For handling DOM events.
+```html
+<button on-click="addTodo()">Add Todo</button>
+<input on-input="newTodoText.value = e.target.value" />
+```
+### Component Props
+You can pass data from a parent component to a child component using props. To declare a prop, prefix the attribute with a colon (`:`).
+Children are passed by default in pawajs, they are not functional prop.
+For rest props pass `--` to the element that needs the attributes.
+**Parent Component (`app.js`)**
+```javascript
+// ...
+const message = $state('This is a message from the parent!');
+useInsert({ message });
+return html`
+    <todo-list :title="'My Todo List'" :message="message.value" class="to the rest prop">Children in here</todo-list>
+`;
+```
+**Child Component (`todo-list.js`)**
+```javascript
+export const TodoList = ({ title, message,children }) => {
+    // Props are passed as functions that return the reactive value
+    useInsert({ title, message });
+    return html`
+        <div -->
+            <h2>@{title()}</h2>
+            <p>@{message()}</p>
+            ${children}
+        </div>
+    `;
+}
+// You can also validate props
+useValidateComponent(TodoList, {
+    title: {
+        type: String,
+        strict: true // This prop is required
+    },
+    message: {
+        type: String,
+        default: 'Default message'
+    }
+});
+```
+---
+## API Reference
+### Core Functions
+-   `pawaStartApp(rootElement, initialContext)`: Initializes the PawaJS application on a given root DOM element.
+-   `RegisterComponent(...components)`: Registers one or more components to be used in templates.
+-   `$state(initialValue, localStorageKey?)`: Creates a new reactive state object.
+-   `html`: A tagged template literal for syntax highlighting and potential future optimizations.
+### Component Hooks
+-   `useInsert(object)`: Exposes data and functions from a component's setup to its template.
+-   `runEffect(callback, dependencies?)`: Runs a side effect after or before the component renders, and re-runs it when its dependencies change .
+-   `useContext(contextObject)` & `setContext()`: A mechanism for providing and consuming data throughout a component tree.
+-   `useRef()`: Creates a reference object that can be attached to a DOM element using the `ref` directive.
+-   `useValidateComponent(Component, rules)`: Defines validation rules for a component's props.
+---
+## Contributing
+Contributions are welcome! If you have a feature request, bug report, or want to contribute to the code, please feel free to open an issue or pull request on the GitHub repository.
+## License
+This project is licensed under the MIT License.

package/cdn/index.js ADDED Viewed

@@ -0,0 +1,5 @@
+import Pawa from '../index.js'
+// this is for cdn file
+window.$pawa=Pawa

package/index.d.ts ADDED Viewed

@@ -0,0 +1,291 @@
+export interface PawaElement extends HTMLElement {
+    _running: boolean;
+    _context: any;
+    _staticContext: any[];
+    _resetEffects: Set<Function>;
+    _avoidPawaRender: boolean;
+    _el: HTMLElement;
+    _out: boolean;
+    _terminateEffects: Set<Function>;
+    _deleteEffects: () => void;
+    _slots: DocumentFragment;
+    _mainAttribute: Record<string, any>;
+    _preRenderAvoid: string[];
+    _lazy: boolean;
+    _await: boolean;
+    _hasForOrIf: () => boolean;
+    _elementContent: string | null;
+    _textContent: Record<string, string>;
+    _attributes: ({ name: string; value: string } | Attr)[];
+    _template: string;
+    _exitAnimation: (() => Promise<void>) | null;
+    _component: any;
+    _unMountFunctions: Function[];
+    _MountFunctions: Function[];
+    _elementType: string;
+    _getNode: () => Element | null;
+    _componentOrTemplate: boolean;
+    _props: Record<string, any>;
+    _isView: any;
+    _isElementComponent: boolean;
+    _pawaAttribute: Record<string, string>;
+    _setUnMount: (func: Function) => void;
+    _componentName: string;
+    _attrElement: (attrName: string) => HTMLElement;
+    _attr: Record<string, string>;
+    _checkStatic: () => void;
+    _callMount: () => void;
+    _callUnMOunt: () => Promise<void>;
+    _remove: (callback?: Function) => Promise<any>;
+    _componentChildren: string;
+    _pawaElementComponent: any;
+    _componentTerminate: Function | null;
+    _cacheSetUp: boolean;
+    _effectsCache: HTMLElement | null;
+    _effectsCarrier: any;
+    _pawaElementComponentName: string;
+    _reCallEffect: () => void;
+    _ElementEffects: Map<any, any>;
+    _deCompositionElement: boolean;
+    _restProps: Record<string, any>;
+    _kill: Function | null;
+    _isKill: boolean;
+    _scriptFetching: boolean;
+    _scriptDone: boolean;
+    _underControl: any;
+    _reactiveProps: Record<string, any>;
+    getChildrenTree(): Element[];
+    reCallEffect(): void;
+    setPawaAttr(): void;
+    findPawaAttribute(): void;
+    setUnMounts(func: Function): void;
+    isPawaElementComponent(): void;
+    getNode(): Element | null;
+    terminateEffects(): void;
+    getNewElementByRemovingAttr(attrName: string): HTMLElement;
+    setAttri(): void;
+    hasForOrIf(): boolean;
+    cache(): void;
+    effectsCache(): HTMLElement | null;
+    reCheckStaticContext(): void;
+    remove(callback?: Function): Promise<any>;
+    unMount(): Promise<void>;
+    mount(): void;
+    elementType(): void;
+    setProps(): void;
+}
+export interface AttriPlugin {
+    startsWith?: string;
+    fullName?: string;
+    mode?: null | 'client' | 'server';
+    dependency?: string[];
+    plugin: (el: HTMLElement | PawaElement, attr: { name: string; value: string }, stateContext?: any, notRender?: any, stopResume?: any) => void;
+}
+export interface PluginObject {
+    attribute?: {
+        register: AttriPlugin[];
+    };
+    component?: {
+        beforeCall?: (stateContext: any, app: any) => void;
+        afterCall?: (stateContext: any, el: HTMLElement) => void;
+    };
+    renderSystem?: {
+        beforePawa?: (el: HTMLElement, context: any) => void;
+        afterPawa?: (el: PawaElement) => void;
+        beforeChildRender?: (el: PawaElement) => void;
+    };
+}
+export type StateInput<T> = T | (() => T) | (() => Promise<T>);
+export interface State<T> {
+    value: T;
+    readonly id: string;
+    async?: boolean;
+    failed?: boolean;
+    retry?: () => void;
+}
+export function setErrorCALLER(callback: (message: any) => void): void;
+export function pluginsMap(): {
+    compoAfterCall: Set<Function>;
+    compoBeforeCall: Set<Function>;
+    renderAfterPawa: Set<Function>;
+    renderBeforePawa: Set<Function>;
+    renderBeforeChild: Set<Function>;
+    startsWithSet: Set<string>;
+    fullNamePlugin: Set<string>;
+    externalPlugin: Record<string, Function>;
+    externalPluginMap: Map<string, string[]>;
+};
+export const escapePawaAttribute: Set<string>;
+export const dependentPawaAttribute: Set<string>;
+/**
+ * Removes a plugin by name.
+ * @param {...string} pluginName - Names of plugins to remove.
+ */
+export function removePlugin(...pluginName: string[]): void;
+/**
+ * Registers plugins to extend PawaJS capabilities.
+ * @param {...(() => PluginObject)} func - Functions returning plugin definitions.
+ */
+export function PluginSystem(...func: (() => PluginObject)[]): void;
+export function keepContext(context: any): void;
+export const components: Map<string, Function>;
+export function getCurrentContext(): any;
+export function setPawaAttributes(...attr: string[]): void;
+export function getDependentAttribute(): Set<string>;
+export function getPawaAttributes(): Set<string>;
+export function setError(params: { error: any }): void;
+/**
+ * Registers components for use in templates.
+ * @param {...(string | Function)} args - Component functions or (name, function - done by pawajs-vite-plugin automaticly) pairs.
+ */
+export function RegisterComponent(...args: (string | Function)[]): void;
+/**
+ * Runs a side effect or lifecycle hook.
+ * @param {() => void | (() => void)} callback - Effect function, optionally returning cleanup.
+ * @param {any[] | object | number | null} [deps] - Dependencies or hook type (null=mount).
+ */
+export function runEffect(callback: () => void | (() => void), deps?: any[] | object | number | null): void;
+export interface PropValidation {
+    strict?: boolean;
+    err?: string;
+    default?: any;
+    type?: Function | Function[];
+}
+export function useValidateComponent(component: Function, object: Record<string, PropValidation>): void;
+export interface ContextHandle<T = any> {
+    id: string;
+    setValue: (val?: T) => void;
+}
+/**
+ * Creates a context provider handle.
+ * @template T
+ * @returns {ContextHandle<T>} Handle to set context values.
+ */
+export function setContext<T = any>(): ContextHandle<T>;
+/**
+ * Consumes a context value.
+ * @template T
+ * @param {ContextHandle<T>} context - The context handle.
+ * @returns {T} The context value.
+ */
+export function useContext<T = any>(context: ContextHandle<T>): T;
+/**
+ * Gets the context from the parent Element
+ * @template T
+ * @returns {T}
+ */
+export function useInnerContext<T=any>(): T;
+/**
+ * Tells pawa-ssr to serialize the children prop.
+ * Then pawajs adds it into the component unpon re-execution
+ * @returns {()=>void}
+ */
+export function accessChild(): (()=>void);
+/**
+ * Tells pawa-ssr to serialized data from useInsert.
+ * Then pawajs continuity model de-serializes it and adds to the rendering context
+ * @returns {void}
+ * Note: meant for server-only component
+ */
+export function useServer(): (() => void) | undefined;
+/**
+ * Stores the component instance into the returned $async hook.
+ * Used in async component.
+ * Must be called before any await call
+ */
+export function useAsync(): { $async: <T>(callback: () => T) => T };
+/**
+ * Returns TRUE when pawajs is in continous rendering mode from ssr
+ */
+export function isResume(): boolean;
+/**
+ * Exposes variables to the template scope.
+ * @param {Record<string, any>} [obj] - Variables to expose.
+ */
+export function useInsert(obj?: Record<string, any>): void;
+export function setStateContext(context: any): any;
+/**
+ * Creates a reactive state.
+ * @template T
+ * @param {StateInput<T>} initialValue - Initial value or generator function.
+ * @param {string | null | string[]} [section] - Persistence key or dependency array.
+ * @returns {State<T>} Reactive state object.
+ */
+export function $state<T>(initialValue: StateInput<T>, section?: string | null | string[]): State<T>;
+export function restoreContext(state_context: any): void;
+/**
+ * Creates a reference object.
+ * @template T
+ * @returns {{ value: T | null }} Ref object.
+ */
+export function useRef<T = any>(): { value: T | null };
+/**
+ * Renders a component or element.
+ * @param {HTMLElement} el - Target element.
+ * @param {object} [contexts] - Context.
+ * @param {any} [notRender] - Internal.
+ * @param {boolean} [isName] - Internal.
+ */
+export function render(el: HTMLElement, contexts?: object, notRender?: any, isName?: boolean): void;
+/**
+ * Initializes and starts the Pawa application.
+ * @param {HTMLElement} app - Root element.
+ * @param {Record<string, any>} [context] - Initial context.
+ */
+export function pawaStartApp(app: HTMLElement, context?: Record<string, any>): void;
+/**
+ * Tagged template literal for HTML strings. Enables syntax highlighting in compatible editors.
+ * @param {TemplateStringsArray} strings
+ * @param {...any} values
+ */
+export function html(strings: TemplateStringsArray, ...values: any[]): string;
+declare const Pawa: {
+    useInsert: typeof useInsert;
+    useContext: typeof useContext;
+    useValidateComponent: typeof useValidateComponent;
+    setPawaAttributes: typeof setPawaAttributes;
+    setContext: typeof setContext;
+    $state: typeof $state;
+    pawaStartApp: typeof pawaStartApp;
+    RegisterComponent: typeof RegisterComponent;
+    runEffect: typeof runEffect;
+    html: typeof html;
+};
+export default Pawa;