als-layout 2.0.0 → 2.2.0

package/build-readme.js

@@ -0,0 +1,8 @@
+const { readFileSync, writeFileSync, readdirSync } = require('fs')
+const { join } = require('path')
+
+const docsDir = join(__dirname, 'docs')
+const files = readdirSync(docsDir)
+const content = files.map(file => readFileSync(join(docsDir, file), 'utf-8')).join('\n');
+writeFileSync(join(__dirname, 'readme.md'), content, 'utf-8')
+

package/docs/#.md

@@ -0,0 +1,27 @@
+# als-layout Documentation
+
+## Library Description
+
+### 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.
+
+### 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.
+
+### 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')
+```

package/docs/0-change-log.md

@@ -0,0 +1,16 @@
+## Change Log 
+* 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

package/docs/1-basic-usage.md

@@ -0,0 +1,49 @@
+## 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 = new Layout()
+   .charset() // default UTF-8
+   .viewport() // default width=device-width, initial-scale=1.0
+   .title('Test title') // adding/updating title and meta[og:title]
+   .favicon('/favicon.png') // adding/updating link[rel=icon][type=image/x-icon] with new href
+   .keywords(['some', 'keyword']) // adding/updating meta[name=keywords]. not adding existing keywords
+   .image('/main-image.png', '1.5') // adding/updating meta - og:image, twitter:image, twitter:card
+   .description('Cool site') // adding/updating meta og:description, twitter:description, and description tag
+   .version('1.0.0') // adds version parameter to link, script.src, and image
+   .url('/some', 'http://site.com') // adding/updating meta[og:url] and link[rel="canonical"]
+   .style([{body:{m:0, bgc:'whitesmoke'}}]) // adding as simple-css styles to existing/new style tag
+   .style('body {margin:0; background-color:whitesmoke;}', true) // adding css styles to existing/new style tag. Second parameter is minified (default=false).
+   .link('/styles.css', '2.0') // adding link[rel=stylesheet] if such href not exists
+   .script({src:'/app.js'}, '', true, '3.0') // set script with src to head if such src not exists
+   .script({}, 'console.log("hello world")', false) // set script with script code to footer
+
+// 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)
+
+// Outputs
+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>`
+```

package/docs/2-cloning.md

@@ -0,0 +1,19 @@
+## 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.
+

package/docs/3-advanced-usage.md

@@ -0,0 +1,43 @@
+## 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('als-layout')
+
+// Starting with a basic HTML template and specifying the host for URL methods
+const raw = /*html*/`<html></html>`
+const host = 'http://example.com';
+const layout = new Layout(raw, host).lang('fr')
+console.log(layout.rawHtml) 
+// <!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.
+

package/docs/4-render.md

@@ -0,0 +1,71 @@
+## Rendering
+
+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:
+
+- `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,              // 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
+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')
+
+// 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: () => { $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>
+<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')
+```
+
+### Advanced Rendering Details
+- **Component Indexing:** Each component is assigned a `componentIndex` during rendering, providing a unique index within its parent component.
+- **Part Attribute:** Using the `part` attribute in a component prevents it from being added to `$App.components`, unless it is nested within another component.

package/lib/elements/script.js

@@ -9,7 +9,7 @@ function addScript(attrs = {}, innerHTML = '', head = true, version, layout) {
    if(Object.keys(attrs).length || innerHTML) {
       const script = new Node('script', attrs)
       if(innerHTML) script.innerHTML = innerHTML
-      if (head) layout.root.head.insert(2, script)
+      if (head) layout.head.insert(2, script)
       else layout.body.insert(3, script)
    }
    return layout

package/lib/layout.js

@@ -1,79 +1,44 @@
-const { cacheDoc } = require('als-document')
+const { Document } = require('als-document')
+const build$App = require('./render/build-app')
+const onload = require('./onload')
+const update = require('./render/update')
 const {
-   addKeywords, addStyle, addDescription, addTitle, addImage,
-   addUrl, addFavicon, addScript, addLink, charset, viewport
+   addKeywords, addStyle, addDescription, addTitle, addImage, 
+   addUrl, addFavicon, addScript,addLink,charset,viewport
 } = require('./elements/index')
-const build$App = require('./build-app')
-const buildRoot = require('./build-root')
 
-class Layout {
-   constructor(layout, options = {}) {
-      this.options = options
-      this.root = buildRoot(layout)
-      this.body; this.head;
+class Layout extends Document {
+   constructor(html,url) {
+      super(html,url)
       this.components = {}
       this.data = {}
       this.actions = {}
       this.utils = {}
+      this.root = this.html
+      this.update = update
    }
-
-   get html() {
-      const lang = this.options.lang || 'en'
-      if (!this.root.$('html')) this.root.insert(2, `<html></html>`)
-      const htmlElement = this.root.$('html')
-      if (lang && htmlElement.getAttribute('lang') !== lang) {
-         htmlElement.setAttribute('lang', lang)
-      }
-      return htmlElement
-   }
-   get body() {
-      if (!this.root.body) this.html.insert(2, `<body></body>`)
-      return this.root.body
-   }
-   get head() {
-      if (!this.root.head) this.html.insert(1, `<head></head>`)
-      return this.root.head
-   }
-
-   update(element, done = []) {
-      for (const componentName in this.components) {
-         const fn = this.components[componentName]
-         let components = element.getAttribute('component') === componentName
-            ? [element]
-            : [...element.querySelectorAll(`[component=${componentName}]`)]
-         components = components.filter(el => !done.includes(el))
-         components.forEach((element, i) => {
-            element.componentIndex = i
-            fn(element, this)
-            done.push(element)
-            this.update(element, done)
-         });
-      }
-   }
-
-   render() {
-      const done = []
-      this.update(this.root, done)
-      this.script({}, build$App(done,this),false)
-      return this.rawHtml
-   }
-
-   get rawHtml() { return this.root.innerHTML }
-   get cached() { return cacheDoc(this.root) }
-   get clone() { return new Layout(this.root, this.options) }
-
+   onload() {this.script({},onload); return this}
+   lang(lang) {this.html.setAttribute('lang',lang); return this}
    version(v) { this.v = v; return this; }
+   charset(newCharset = 'UTF-8') { return charset(newCharset, this) }
    keywords(keywords = []) { return addKeywords(keywords, this) }
    description(description) { return addDescription(description, this) }
    title(title) { return addTitle(title, this) }
    style(styles, minified) { return addStyle(styles, minified, this) }
    image(image, v = this.v) { return addImage(image, v, this) }
-   url(url, host = this.options.host) { return addUrl(url, host, this) }
+   url(url, host = this.URL) { return addUrl(url, host, this) }
    favicon(href) { return addFavicon(href, this) }
    script(attributes, innerHTML, head = true, v = this.v) { return addScript(attributes, innerHTML, head, v, this) }
    link(href, v = this.v) { return addLink(href, v, this) }
-   charset(newCharset = 'UTF-8') { return charset(newCharset, this) }
    viewport(newViewport = 'width=device-width, initial-scale=1.0') { return viewport(newViewport, this) }
+   get rawHtml() {return this.innerHTML}
+   get clone() {return new Layout(new Document(this),this.URL)}
+   render() {
+      const done = []
+      this.update(this.root, done)
+      this.script({}, build$App(done,this),false)
+      return this.rawHtml
+   }
 }
 
 module.exports = Layout

package/lib/onload.js

@@ -0,0 +1,9 @@
+module.exports = `document.addEventListener('DOMContentLoaded', function() {
+   const elements = document.querySelectorAll('[onload]');
+   elements.forEach(element => {
+       const onloadCode = element.getAttribute('onload');
+       const func = Function('"use strict"; return function() { ' + onloadCode + ' }');
+       func().call(element);
+       element.removeAttribute('onload');
+   });
+});`

package/lib/{build-app.js → render/build-app.js}

@@ -1,9 +1,13 @@
 const componentHierarchy = require('./component-hierarchy')
 module.exports = function(done=[],layout) {
-   const strComponents = 'components:{'+componentHierarchy(done).map(componentName => {
-      return `"${componentName}":${layout.components[componentName].toString()}`
-   }).join(',')+'}'
-   const updateFn = `update:function ${layout.update.toString()}`
+   let strComponents = 'components:{}', updateFn = 'update:()=>{}'
+   const components = componentHierarchy(done)
+   if(components.length) {
+      strComponents = 'components:{'+components.map(componentName => {
+         return `"${componentName}":${layout.components[componentName].toString()}`
+      }).join(',')+'}'
+      updateFn = `update:${layout.update.toString()}`
+   }
    const strData = 'data:'+JSON.stringify(layout.data)
    const $ = 'function $(selector,parent = document) {return parent.querySelector(selector)}'
    const $$ = 'function $$(selector,parent = document) {return [...parent.querySelectorAll(selector)]}'

package/lib/{component-hierarchy.js → render/component-hierarchy.js}

@@ -1,4 +1,5 @@
 function componentHierarchy(elements) {
+
    const entries = elements
       .map(el => ([el, el.getAttribute('component'), el.ancestors]))
       .sort((a, b) => a[2].length - b[2].length)
@@ -6,6 +7,13 @@ function componentHierarchy(elements) {
    const result = []
    while(entries.length > 0) {
       const [element, componentName, ancestors] = entries.shift()
+      if(element.getAttribute('part') !== null) {
+         element.removeAttribute('component')
+         element.removeAttribute('part')
+         continue
+      }
+      const partsInside = element.$$('[component][part]')
+      partsInside.forEach(element => { element.removeAttribute('part') });
       entries.forEach(entry => {
          if(entry[1] !== componentName) return
          if(entry[2].includes(element)) {

package/lib/render/update.js

@@ -0,0 +1,19 @@
+function update(element, done = []) {
+   for (const componentName in this.components) {
+      const fn = this.components[componentName]
+      let components = element.getAttribute('component') === componentName
+         ? [element]
+         : [...element.querySelectorAll(`[component=${componentName}]`)]
+      components = components.filter(el => !done.includes(el))
+      components.forEach((element, i) => {
+         element.componentIndex = i
+         const result = fn(element, this)
+         if(typeof result === 'string') element.innerHTML = result
+         done.push(element)
+         this.update(element, done)
+      });
+   }
+}
+
+
+module.exports = update

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "als-layout",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Html layout constructor",
   "main": "index.js",
   "directories": {
@@ -15,7 +15,7 @@
   "license": "ISC",
   "dependencies": {
     "als-css-parser": "^0.5.0",
-    "als-document": "^1.1.2",
+    "als-document": "^1.3.1",
     "als-simple-css": "^9.1.0"
   }
 }