uigar 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vugar Safarzada
+
+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

@@ -0,0 +1,91 @@
+# uigar
+
+**uigar** is a simple and declarative JavaScript framework for building user interfaces, inspired by component-based architecture. It allows you to build a web application's UI using a declarative, function-based syntax.
+
+## Get Started
+
+The quickest way to start building with `uigar` is by creating a new project using our command-line tool.
+
+```bash
+npx uigar create my-uigar-app
+```
+
+This command will set up a new directory named `my-uigar-app` with a ready-to-go `uigar` project.
+
+Once the project is created, navigate into it and start the development server:
+
+```bash
+cd my-uigar-app
+npm install
+npm run start
+```
+
+## Usage as a Library
+
+You can also install `uigar` into an existing project.
+
+### Installation
+
+```bash
+npm install uigar
+```
+or
+```bash
+yarn add uigar
+```
+
+### Basic Component Example
+
+Here is a simple example of a `uigar` component that demonstrates state management:
+
+```typescript
+import { div, h1, p, button, Component, render } from 'uigar';
+
+interface CounterState {
+    count: number;
+}
+
+class CounterComponent extends Component<CounterState> {
+    constructor() {
+        super({ count: 0 });
+    }
+
+    render() {
+        return div(
+            h1('Counter App'),
+            p(`Count: ${this.state.count}`),
+            button('Increment')
+                .onClick(() => this.setState({ count: this.state.count + 1 }))
+                .style({ padding: '10px 20px', backgroundColor: '#007bff', color: 'white', border: 'none', borderRadius: '5px', cursor: 'pointer' })
+        );
+    }
+}
+
+// To render this component to the DOM:
+render('#app', new CounterComponent());
+```
+
+## Further Documentation
+
+For more detailed API references, advanced usage patterns, and tutorials, please visit our [documentation site](./docs/introduction.md).
+
+## Example Application
+
+This repository includes a full example application in the `/example` directory. It's a great way to explore various features of `uigar`.
+
+To run the example locally:
+
+1.  Navigate to the `example` directory:
+    ```bash
+    cd example
+    ```
+2.  Install dependencies:
+    ```bash
+    npm install
+    ```
+3.  Start the development server:
+    ```bash
+    npm run start
+    ```
+
+# uigar

package/cli.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+const args = process.argv.slice(2);
+const command = args[0];
+const projectName = args[1];
+
+if (command === "create") {
+  if (!projectName) {
+    console.error("Please provide a project name.");
+    process.exit(1);
+  }
+
+  const currentDir = process.cwd();
+  const projectDir = path.resolve(currentDir, projectName);
+  fs.mkdirSync(projectDir, { recursive: true });
+
+  const templateDir = path.resolve(__dirname, "template");
+  fs.cpSync(templateDir, projectDir, { recursive: true });
+
+  const projectPackageJsonPath = path.join(projectDir, "package.json");
+  let projectPackageJson = JSON.parse(
+    fs.readFileSync(projectPackageJsonPath, "utf8")
+  );
+
+  projectPackageJson.name = projectName;
+
+  fs.writeFileSync(
+    projectPackageJsonPath,
+    JSON.stringify(projectPackageJson, null, 2)
+  );
+
+  console.log("Success! Your new uigar project has been created.");
+  console.log(`To get started, run the following commands:`);
+  console.log(`cd ${projectName}`);
+  console.log(`npm install`);
+  console.log(`npm run start`);
+} else {
+  console.log("Unknown command. Did you mean:");
+  console.log("npx uigar create <project-name>");
+}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+declare class DomElement {
+    element: HTMLElement;
+    constructor(tagName: string, ...children: (DomElement | HTMLElement | string)[]);
+    private addChildren;
+    style(styles: Partial<CSSStyleDeclaration>): this;
+    settings(attributes: {
+        [key: string]: string;
+    }): this;
+    onClick(handler: (e: MouseEvent) => void): this;
+    on(event: string, handler: (e: Event) => void): this;
+    render(): HTMLElement;
+}
+type Child = DomElement | HTMLElement | string;
+export declare const div: (...children: Child[]) => DomElement;
+export declare const h1: (...children: Child[]) => DomElement;
+export declare const p: (...children: Child[]) => DomElement;
+export declare const a: (...children: Child[]) => DomElement;
+export declare const span: (...children: Child[]) => DomElement;
+export declare const img: () => DomElement;
+export declare const input: () => DomElement;
+export declare const button: (...children: Child[]) => DomElement;
+export declare abstract class Component<S extends object = {}> {
+    protected state: S;
+    private _mountedElement;
+    private _parentSelector;
+    constructor(initialState?: S);
+    abstract render(): DomElement;
+    protected setState(newState: Partial<S>): void;
+    private update;
+    _mount(selector: string): HTMLElement;
+}
+export declare function render(selector: string, component: Component): void;
+export {};

package/dist/index.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.render = exports.Component = exports.button = exports.input = exports.img = exports.span = exports.a = exports.p = exports.h1 = exports.div = void 0;
+// A simple DOM element wrapper
+class DomElement {
+    constructor(tagName, ...children) {
+        this.element = document.createElement(tagName);
+        this.addChildren(children);
+    }
+    addChildren(children) {
+        for (const child of children) {
+            if (typeof child === 'string') {
+                this.element.appendChild(document.createTextNode(child));
+            }
+            else if (child instanceof DomElement) {
+                this.element.appendChild(child.render());
+            }
+            else if (child instanceof HTMLElement) {
+                this.element.appendChild(child);
+            }
+        }
+    }
+    style(styles) {
+        for (const key in styles) {
+            if (Object.prototype.hasOwnProperty.call(styles, key)) {
+                const styleKey = key;
+                this.element.style[styleKey] = styles[styleKey];
+            }
+        }
+        return this;
+    }
+    settings(attributes) {
+        for (const key in attributes) {
+            if (Object.prototype.hasOwnProperty.call(attributes, key)) {
+                this.element.setAttribute(key, attributes[key]);
+            }
+        }
+        return this;
+    }
+    onClick(handler) {
+        this.element.onclick = handler;
+        return this;
+    }
+    on(event, handler) {
+        this.element.addEventListener(event, handler);
+        return this;
+    }
+    render() {
+        return this.element;
+    }
+}
+// Factory functions for creating elements
+const div = (...children) => new DomElement('div', ...children);
+exports.div = div;
+const h1 = (...children) => new DomElement('h1', ...children);
+exports.h1 = h1;
+const p = (...children) => new DomElement('p', ...children);
+exports.p = p;
+const a = (...children) => new DomElement('a', ...children);
+exports.a = a;
+const span = (...children) => new DomElement('span', ...children);
+exports.span = span;
+const img = () => new DomElement('img');
+exports.img = img;
+const input = () => new DomElement('input');
+exports.input = input;
+const button = (...children) => new DomElement('button', ...children);
+exports.button = button;
+// Base Component class for state management
+class Component {
+    constructor(initialState = {}) {
+        this._mountedElement = null;
+        this._parentSelector = null;
+        this.state = initialState;
+        this.update = this.update.bind(this); // Bind update for callbacks
+    }
+    setState(newState) {
+        this.state = Object.assign(Object.assign({}, this.state), newState);
+        this.update(); // Trigger re-render
+    }
+    update() {
+        if (this._mountedElement && this._parentSelector) {
+            // Re-render the component and replace the old element
+            const newElement = this.render().render();
+            const parent = document.querySelector(this._parentSelector);
+            if (parent) {
+                parent.replaceChild(newElement, this._mountedElement);
+                this._mountedElement = newElement; // Update reference to the new element
+            }
+        }
+    }
+    // Method called by the top-level render function
+    _mount(selector) {
+        this._parentSelector = selector;
+        this._mountedElement = this.render().render();
+        return this._mountedElement;
+    }
+}
+exports.Component = Component;
+// The top-level render function
+function render(selector, component) {
+    const app = document.querySelector(selector);
+    if (app) {
+        app.innerHTML = '';
+        app.appendChild(component._mount(selector));
+    }
+}
+exports.render = render;

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "uigar",
+  "version": "0.3.0",
+  "description": "A simple and declarative JavaScript framework for building user interfaces.",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "uigar": "./cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vugarsafarzada/uigar.git"
+  },
+  "homepage": "https://github.com/vugarsafarzada/uigar#readme",
+  "keywords": [
+    "framework",
+    "ui",
+    "declarative",
+    "frontend"
+  ],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "typescript": "^4.5.0"
+  },
+  "files": [
+    "dist",
+    "cli.js",
+    "template"
+  ]
+}

package/template/index.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <title>my-new-framework</title>
+    <link rel="stylesheet" href="./src/assets/styles/main.scss">
+</head>
+<body>
+    <div id="app"></div>
+    <script type="module" src="./src/index.ts"></script>
+</body>
+</html>

package/template/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "uigar-app",
+  "version": "0.2.0",
+  "description": "A new uigar application.",
+  "source": "index.html",
+  "scripts": {
+    "start": "parcel index.html",
+    "build": "parcel build index.html"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "module",
+  "dependencies": {
+    "uigar": "^0.1.0"
+  },
+  "devDependencies": {
+    "@parcel/transformer-sass": "^2.16.3",
+    "parcel": "latest"
+  }
+}

package/template/src/assets/styles/main.scss

@@ -0,0 +1,22 @@
+body {
+    background-color: #f0f0f0;
+    font-family: sans-serif;
+
+    h1 {
+        color: #333;
+    }
+}
+
+.btn {
+    padding: 10px 20px;
+    border: none;
+    border-radius: 5px;
+    background-color: #007bff;
+    color: white;
+    cursor: pointer;
+    font-size: 16px;
+
+    &:hover {
+        background-color: #0056b3;
+    }
+}

package/template/src/components/Button.ts

@@ -0,0 +1,7 @@
+import { button } from 'uigar';
+
+export function Button(text: string, onClick: () => void) {
+    return button(text)
+        .onClick(onClick)
+        .settings({ class: 'btn' });
+}

package/template/src/index.ts

@@ -0,0 +1,12 @@
+import { handleLocation, navigate } from './router';
+
+window.addEventListener('popstate', handleLocation);
+document.addEventListener('DOMContentLoaded', () => {
+    document.body.addEventListener('click', e => {
+        if (e.target && (e.target as HTMLElement).matches('[data-link]')) {
+            e.preventDefault();
+            navigate((e.target as HTMLAnchorElement).href);
+        }
+    });
+    handleLocation();
+});

package/template/src/pages/AboutPage.ts

@@ -0,0 +1,11 @@
+import { div, h1, p, a } from 'uigar';
+
+export function AboutPage() {
+    return div(
+        h1('About Us'),
+        p('This is the about page. Add your content here.'),
+        a('Go to Home Page')
+            .settings({ href: '/', 'data-link': '' })
+    )
+        .settings({ class: 'about-page' });
+}

package/template/src/pages/HomePage.ts

@@ -0,0 +1,14 @@
+import { div, h1, a } from 'uigar';
+import { Button } from '../components/Button';
+
+export function HomePage() {
+    return div(
+        h1('Welcome to the Home Page'),
+        Button('Click me!', () => {
+            alert('Button clicked!');
+        }),
+        a('Go to About Page')
+            .settings({ href: '/about', 'data-link': '' })
+    )
+        .settings({ class: 'home-page' });
+}

package/template/src/router.ts

@@ -0,0 +1,19 @@
+import { HomePage } from './pages/HomePage';
+import { AboutPage } from './pages/AboutPage';
+import { render } from 'uigar';
+
+const routes = {
+    '/': HomePage,
+    '/about': AboutPage,
+};
+
+export function handleLocation() {
+    const path = window.location.pathname;
+    const page = routes[path] || routes['/']; // Default to home page
+    render('#app', page());
+}
+
+export function navigate(path: string) {
+    window.history.pushState({}, '', path);
+    handleLocation();
+}