als-layout 2.1.0 → 2.3.0

package/readme.md

@@ -1,24 +1,69 @@
-# Als-layout
+# als-layout Documentation
 
-`Als-layout` is an HTML layout constructor for Node.js that allows you to manage HTML elements, styles, and scripts through JavaScript. It's perfect for server-side HTML generation or dynamic page modifications before delivery to the client.
+## Library Description
 
-## What's New in 2.1.0
+### What is it?
+`als-layout` is a JavaScript library designed to simplify and enhance the process of constructing and managing web page layouts. It provides a comprehensive API for modifying HTML documents dynamically, allowing developers to add, update, and manipulate various elements such as meta tags, styles, scripts, and more.
 
-* updated als-document version
-* [part] attribute for static components
-* onload() method
-* bugs fixed
+### Why is it needed?
+Managing HTML document structures and their contents can often become repetitive and error-prone when done manually. `als-modular` offers a structured and reusable approach, reducing development time and improving code maintainability.
 
-## Install
+### What can you do with it and where can it be used?
+The `als-layout` library is versatile, suitable for:
+- Building dynamic web pages that require frequent updates to their metadata, styles, or scripts.
+- Creating templating systems where multiple page layouts share similar structures but differ in content or styling.
+- Developing web applications that need to dynamically adjust their UI based on user interactions or data changes.
+This library is particularly useful in environments where rapid development and modular design are prioritized.
+
+## Installation and Adding
+To use the `als-layout` library in your project, you can install it via npm and then include it in your JavaScript files:
 
 ```bash
 npm i als-layout
 ```
 
+```js
+const Layout = require('als-layout')
+```
+
+## Change Log 
+* V2.3.0
+  * Default, component will not be included in $App, if not [publish] attribute
+  * When cloning, components and other staff cloned too
+    * Reference does not change
+
+* V2.2.0
+  * fixed empty update function if no components for $App
+  * if component function return string, it will element.innerHTML = string
+  * Now each Layout extends Document (als-document)
+  * layout.$ and layout.$$
+    * Also $App.$ and $App.$$ on backend too
+  * no langs validation any more
+    * lang method instead
+  * no layout.cached
+  * charset meta tag allready exists by default
+
+* V2.1.0
+  * updated als-document version
+  * [part] attribute for static components
+  * onload() method
+  * bugs fixed
+
+
 ## Basic Usage
 
+### Initialization
+To start using `als-layout`, you first need to create a new instance of `Layout`. This instance will serve as the foundation for building and modifying your web page.
+
+```js
+const Layout = require('als-layout');
+const layout = new Layout();
+```
+
+### Adding Different Elements
+Once you have your `Layout` instance, you can easily add or modify various elements of your web page. Here are some examples of how you can use the library to customize your layout:
+
 ```js
-const Layout = require('als-layout')
 const layout = new Layout()
    .charset() // default UTF-8
    .viewport() // default width=device-width, initial-scale=1.0
@@ -38,108 +83,154 @@ const layout = new Layout()
 // Accessors for document parts
 layout.body // getter for body element (if not exists, created)
 layout.head // getter for head element (if not exists, created)
-layout.html // getter for html element (if not exists, created)
+layout.html // getter for html Element (if not exists, created)
 
 // Outputs
-layout.rawHtml // raw html
-layout.cached // cached DOM
-layout.clone // new layout object clone for current object
+layout.rawHtml // raw HTML of the document
+layout.clone // creates a new layout object clone for current object
 ```
 
+### onload
+
+By adding onload attribute, you can run scripts for each element after dom content has loaded. 
+
+Example how it works:
+```js
+const layout = new Layout().charset().viewport().title('On load').onload()
+layout.body.innerHTML = /*html*/`<div onload="this.innerHTML = 'new content'">original content</div>`
+```
+## Cloning Functionality
+
+### What is Cloning and Why is it Necessary?
+Cloning in the `als-layout` library refers to creating a complete, independent copy of the existing `Layout` instance. This functionality is crucial when you need to generate multiple pages or versions of a page from a single base layout without affecting the original setup.
+
+### How to Use Cloning
+To clone a `Layout` instance, simply use the `clone` method. This method creates a new `Layout` instance with the same properties and settings as the original, allowing for independent modifications without interference.
+
+```js
+const newLayout = layout.clone;
+```
+
+### Benefits of Cloning
+- **Efficiency:** Cloning is highly efficient, especially for creating pages with similar structures but different content or styles. It avoids the overhead of reinitializing and reconfiguring a new `Layout` instance from scratch.
+- **Speed:** Cloning is fast, typically taking less than 20ms even for large pages. This makes it ideal for high-performance web applications that need to dynamically generate content.
+- **Isolation:** Changes made to a cloned `Layout` do not affect the original, ensuring that each instance can be modified independently based on specific requirements.
+
+Cloning is particularly useful in scenarios where templates or base layouts are used repeatedly with slight variations, providing a robust and scalable solution for web page generation.
+
+
 ## Advanced Usage
 
+The `als-layout` library allows for sophisticated manipulation of web page layouts, providing robust tools for creating dynamic and complex web pages. Below is an advanced example demonstrating various capabilities of the library:
+
 ```js
-const Layout = require('./lib/layout')
+const Layout = require('als-layout')
 
+// Starting with a basic HTML template and specifying the host for URL methods
 const raw = /*html*/`<html></html>`
-const options = {
-  host:'http://example.com', // host for url method
-  lang:'fr' // for <html lang="fr"></html>
-}
-const layout = new Layout(raw, options)
+const host = 'http://example.com';
+const layout = new Layout(raw, host).lang('fr')
 console.log(layout.rawHtml) 
-// <!DOCTYPE html><html lang="fr"><head></head><body></body></html>
+// <!DOCTYPE html><html lang="fr"><head></p></head><body></body></html>
 
+// Cloning the initial layout to create a specialized page
 const homePage = layout.clone
+homeAutoReload = layout.clone
 homePage.title('Home page')
 homePage.body.innerHTML = /*html*/`<h1>Home page</h1>`
 console.log(homePage.rawHtml)
 // <!DOCTYPE html><html lang="fr"><head><title>Home page</title><meta property="og:title" content="Home page"></head><body><h1>Home page</h1></body></html>
+
+// Adding script that reloads the page every minute
+homeAutoReload.script({}, 'setTimeout(function() { window.location.reload(); }, 60000);', false)
+console.log(homeAutoReload.rawHtml)
+// <!DOCTYPE html><html lang="fr"><head><title>Automatic Reload Page</title><meta property="og:title" content="Automatic Reload Page"></head><body><script>setTimeout(function() { window.location.reload(); }, 60000);</script></body></html>
+
+// Demonstrating dynamic stylesheet linkage with versioning
+const styleVersion = '1.1';
+homePage.link('/css/main.css', styleVersion)
+console.log(homePage.rawHtml)
+// Includes link to the stylesheet with version parameter to ensure fresh cache
 ```
 
+In this example:
+- We start with a basic HTML template and use the `lang` method to set the language.
+- We use the `clone` method to create two versions of the base layout: one for the home page and another that automatically reloads every minute.
+- We manipulate the `body` of the `homePage` to include custom HTML.
+- We add a script to `homeAutoReload` that sets up an automatic page reload, showcasing how to insert JavaScript dynamically.
+- We dynamically add a versioned link to a stylesheet in the `homePage`, demonstrating control over caching and resource management.
+
+This advanced example illustrates how `als-layout` can be used to handle complex scenarios and requirements in web development, enhancing the flexibility and power at your disposal.
+
+
 ## Rendering
 
-Each layout instance has a render method and the following objects:
-```js
-layout.data
-layout.components
-layout.utils
-layout.actions
-```
+Each instance of `Layout` comes equipped with a `render` method that compiles the HTML structure and embeds a JavaScript object to manage the page dynamically. This object, known as `window.$App`, allows for real-time interaction and updates within the page.
+
+### Structure
+The layout object houses several key properties that facilitate dynamic content management:
 
-The render method returns raw HTML after building elements with the attribute component. It will create HTML raw which will include a `window.$App` object with the following:
+- `layout.data`: Stores the data that can be used across the page, such as state variables or configuration settings.
+- `layout.components`: Holds functions that define the behavior and rendering logic for components identified by specific attributes in the HTML.
+- `layout.utils`: Contains utility functions that can be used throughout the page for common tasks.
+- `layout.actions`: Methods that can be triggered by user interaction, often modifying `layout.data` and updating the page accordingly.
+
+### The Render Method
+The `render` method processes all elements with a `component` attribute, dynamically generating their content and behavior based on the defined components. After rendering, the page includes the `window.$App` JavaScript object, which provides methods and properties to interact with the page elements and data:
 
 ```js
 window.$App = {
-   data,
-   components,
-   utils,
-   actions,
-   $(selector, parent=document), // querySelector
-   $$(selector, parent=document), // querySelectorAll
-   update(element), // update element if it has component attribute
+   data,              // Access to the layout data object
+   components,        // Access to components functions
+   utils,             // Access to utility functions
+   actions,           // Access to action functions
+   $(selector, parent = document),   // Equivalent to querySelector
+   $$(selector, parent = document),  // Equivalent to querySelectorAll
+   update(element) {  // Updates the element if it has a component attribute
+       // Update logic here
+   }
 }
 ```
 
-
-## Counter Example
+### Counter Example
+To demonstrate dynamic interaction, consider a counter that can be increased or decreased through user input:
 
 ```js
 const fs = require('fs')
 const Layout = require('als-layout')
 
-const layout = new Layout().charset().viewport().title('Counter')
-layout.data.counter = 0
+// Create and configure the layout
+const layout = new Layout().title('Counter')
+layout.data.counter = 0  // Initialize counter data
+
+// Define a component for displaying the counter
 layout.components.counter = function(element, $App) {
    element.innerHTML = `${$App.data.counter}`
 }
 
+// Define actions for increasing and decreasing the counter
 layout.actions = {
-   increase: () => { $App.data.counter++; $App.update($App.$('[component=counter]')) },
-   decrease: () => { $App.data.counter--; $App.update($App.$('[component=counter]')) }
+   increase: () => { $App.data.counter++; $App.update($App.$('[component=counter]')); },
+   decrease: () => { $We render the html page to measure and write to a document.app.data.counter--; $Page updates are shown in real-time on the rendered HTML.$App.update($App.$('[component=counter]')); }
 }
 
+// Add buttons and the counter display to the body
 layout.body.innerHTML = /*html*/`
 <button onclick="$App.actions.increase()">Increase</button>
-<span component="counter"></span>
+<span component="counter" publish></span>
 <button onclick="$App.actions.decrease()">Decrease</button>
 `
+
+// Measure render time and generate HTML
 const time1 = performance.now()
 const rawHtml = layout.render()
 const time2 = performance.now()
 console.log(`${time2 - time1}ms`) // e.g., 1.0649ms
 
+// Write the output to a file
 fs.writeFileSync('counter.html', rawHtml, 'utf-8')
 ```
 
-Each component gets a `componentIndex` which is available inside the component function.
-```js
-element.componentIndex
-```
-
-
-### parts
-
-By default render method adds all used components to `$App.components`. 
-By adding `part` attribute component will not be added, except cases, the component is part of another component. 
-
-
-## onload
-
-By adding onload attribute, you can run scripts for each element after dom content has loaded. 
-
-Example how it works:
-```js
-const layout = new Layout().charset().viewport().title('On load').onload()
-layout.body.innerHTML = /*html*/`<div onload="this.innerHTML = 'new content'">original content</div>`
-```
+### Advanced Rendering Details
+- **Component Indexing:** Each component is assigned a `componentIndex` during rendering, providing a unique index within its parent component.
+- **Publish Attribute:** Using the `publish` attribute in a component make it being added to `$App.components`, unless it is nested within another component.

package/tests/build-app.test.js

@@ -17,13 +17,13 @@ describe('build-$App Functionality', () => {
       const called = []
       const done = [
          { 
-            getAttribute: (attr) => attr === 'component' ? 'comp1' : null,
+            getAttribute: (attr) => attr === 'component' ? 'comp1' : attr === 'publish' ? '' : null,
             removeAttribute(att) {called.push(att)},
             $$(){return []},
             ancestors:2 
          },
          { 
-            getAttribute: (attr) => attr === 'component' ? 'comp2' : null,
+            getAttribute: (attr) => attr === 'component' ? 'comp2' : attr === 'publish' ? '' : null,
             removeAttribute(att) {called.push(att)},
             $$(){return []},
             ancestors:2 

package/tests/component-hierarchy.test.js

@@ -13,7 +13,7 @@ function shuffleArray(array) {
 
 describe('Basic tests', () => {
    it('should build correct hierarchy', () => {
-      const root = parseHTML(/*html*/`<div component="some">
+      const root = parseHTML(/*html*/`<div component="some" publish>
          <div>
             <div component="some1"></div>
             <div>

package/tests/constructor.test.js

@@ -17,7 +17,8 @@ describe('Layout Initialization', () => {
     it('should allow setting a custom language', () => {
         const customLang = 'fr';
         const layout = new Layout(undefined, { lang: customLang });
-        assert(layout.options.lang === customLang, `language is not set to ${customLang}`);
+        layout.lang(customLang)
+        assert(layout.html.getAttribute('lang') === customLang, `language is not set to ${customLang}`);
     });
 
     it('should initialize development mode as undefined or false', () => {
@@ -32,16 +33,8 @@ describe('Layout Initialization', () => {
 
     it('should allow setting a custom host', () => {
         const customHost = 'http://localhost';
-        const layout = new Layout(undefined, { host: customHost });
-        assert.strictEqual(layout.options.host, customHost, `host is not set to ${customHost}`);
+        const layout = new Layout(undefined,customHost);
+        console.log(layout.URL)
+        assert.strictEqual(layout.URL, customHost, `host is not set to ${customHost}`);
     });
-
-    it('check method',() => {
-        const cached = cacheDoc(new Root())
-        const layout = new Layout(cached)
-        const root = layout.root
-        assert(root.$('html') !== null)
-        assert(root.$('head') !== null)
-        assert(root.$('body') !== null)
-    })
 });

package/tests/elements.test.js

@@ -20,7 +20,7 @@ describe('Charset tests', () => {
    it('should insert charset at second position if not present', () => {
       const charset = 'UTF-8';
       layout.charset(charset);
-      assert.strictEqual(layout.head.childNodes[0].tagName, 'meta', 'Meta should be at second position');
+      assert.strictEqual(layout.head.childNodes[0].tagName, 'META', 'Meta should be at second position');
       assert.strictEqual(layout.head.childNodes[0].getAttribute('charset'), charset, 'Charset not set correctly');
    });
 
@@ -50,7 +50,7 @@ describe('Favicon tests', () => {
    it('should insert favicon at second position if not present', () => {
       const faviconHref = 'favicon.ico';
       layout.favicon(faviconHref);
-      assert.strictEqual(layout.head.childNodes[0].tagName, 'link', 'Favicon link should be at second position');
+      assert.strictEqual(layout.head.childNodes[0].tagName, 'LINK', 'Favicon link should be at second position');
       assert.strictEqual(layout.head.childNodes[0].getAttribute('href'), faviconHref, 'Favicon href not set correctly');
    });
 
@@ -265,7 +265,7 @@ describe('Scripts', () => {
    it('should add script after body when head is false', () => {
       const scriptContent = 'console.log("Script in body");';
       layout.script({ src: 'scriptbody.js' }, scriptContent, false);
-      assert.strictEqual(layout.body.next.$('script').innerHTML, scriptContent, 'Script should be added to body');
+      assert.strictEqual(layout.body.next.innerHTML, scriptContent, 'Script should be added to body');
    });
 
    it('should append version parameter correctly when src already has parameters', () => {
@@ -328,7 +328,6 @@ describe('Url', () => {
       layout.url('not-a-url', 'aa');
       assert.strictEqual(layout.root.$('link[rel="canonical"]'), null, 'Canonical URL should not be added for invalid URLs');
    });
-
    
    it('should add url correctly', () => {
       const url = 'http://localhost';
@@ -426,4 +425,12 @@ describe('description and title', () => {
       assert(layout.root.$('[property="og:title"]').getAttribute('content') === title, 'Title not set correctly');
    });
 
+   it('should add title if no title tag', () => {
+      layout.$('title').remove()
+      const title = 'Test Title';
+      layout.title(title);
+      assert(layout.root.$('title').innerHTML === title, 'Title not set correctly');
+      assert(layout.root.$('[property="og:title"]').getAttribute('content') === title, 'Title not set correctly');
+   });
+
 });

package/tests/layout.test.js

@@ -47,7 +47,7 @@ describe('HTML Structure Initialization', () => {
    });
 
    it('should initialize html element correctly', () => {
-      assert.strictEqual(layout.html.tagName, 'html', 'HTML element should be initialized');
+      assert.strictEqual(layout.html.tagName, 'HTML', 'HTML element should be initialized');
    });
 
    it('should not recreate html element if it already exists', () => {
@@ -56,7 +56,7 @@ describe('HTML Structure Initialization', () => {
    });
 
    it('should initialize body element correctly', () => {
-      assert.strictEqual(layout.body.tagName, 'body', 'Body element should be initialized');
+      assert.strictEqual(layout.body.tagName, 'BODY', 'Body element should be initialized');
    });
 
    it('should not recreate body element if it already exists', () => {
@@ -65,7 +65,7 @@ describe('HTML Structure Initialization', () => {
    });
 
    it('should initialize head element correctly', () => {
-      assert.strictEqual(layout.head.tagName, 'head', 'Head element should be initialized');
+      assert.strictEqual(layout.head.tagName, 'HEAD', 'Head element should be initialized');
    });
 
    it('should not recreate head element if it already exists', () => {
@@ -111,7 +111,7 @@ describe('Component Updating', () => {
          element.insert(2, 'test1 success')
       }
       layout.data.test = 'hello'
-      layout.body.innerHTML = /*html*/`<div component="test1">
+      layout.body.innerHTML = /*html*/`<div component="test1" publish>
          <div component="test2">failed</div>
       </div>`
 
@@ -132,8 +132,8 @@ describe('Component Updating', () => {
 
    it('should add part to $App if it is component`s descendant', () => {
       layout.body.innerHTML = /*html*/`
-         <div component="parent">
-            <div component="child" part></div>
+         <div component="parent" publish>
+            <div component="child"></div>
          </div>`;
       layout.components.parent = (element, $App) => {};
       layout.components.child = (element, $App) => {};
@@ -151,8 +151,8 @@ describe('Component Updating', () => {
 
    it('should not add part to $App if it has no component ancestor', () => {
       layout.body.innerHTML = /*html*/`
-      <div component="comp1"></div>
-      <div component="comp2" part></div>
+      <div component="comp1" publish></div>
+      <div component="comp2"></div>
       `;
       layout.components.comp1 = (element, $App) => {};
       layout.components.comp2 = (element, $App) => {};
@@ -175,20 +175,15 @@ describe('Component Updating', () => {
 
 });
 
-describe('Cache and Clone Testing', () => {
+describe('Clone Testing', () => {
    let layout;
    beforeEach(() => {
       layout = new Layout();
    });
 
-   it('should retrieve cached version of the layout', () => {
-      const cachedVersion = layout.cached;
-      assert.doesNotThrow(() => JSON.stringify(cachedVersion)) // should be object without recursions
-      assert(buildFromCache(cachedVersion).innerHTML === layout.rawHtml)
-   });
-
    it('should clone the layout correctly', () => {
       const clone = layout.clone;
+      console.log(clone.constructor.name)
       assert(clone instanceof Layout, 'Clone should be an instance of Layout');
       assert.notStrictEqual(clone, layout, 'Clone should not be the same instance as the original');
    });

package/lib/build-root.js

@@ -1,16 +0,0 @@
-const { buildFromCache, Root, parseHTML, cacheDoc, Document } = require('als-document')
-
-function buildRoot(item) {
-   const root = 
-   (item instanceof Root) ? buildFromCache(cacheDoc(item))
-   : (typeof item === 'string') ? parseHTML(item) 
-   : (typeof item === 'object' && item.tagName) ? buildFromCache(item) 
-   : new Root()
-   
-   const firstNode = root.childNodes[0]
-   if(!firstNode || firstNode.tagName !== '!DOCTYPE') {root.insert(1,/*html*/`<!DOCTYPE html>`)}
-
-   return root
-}
-
-module.exports = buildRoot