npm - als-layout - Versions diffs - 7.0.1 → 7.1.0 - Mend

als-layout 7.0.1 → 7.1.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 (17) hide show

package/index.mjs +89 -81
package/layout.js +89 -81
package/package.json +15 -3
package/readme.md +186 -163
package/src/layout.js +93 -85
package/build.js +0 -8
package/tests/constructor.test.js +0 -28
package/tests/description.test.js +0 -33
package/tests/favicon.test.js +0 -36
package/tests/image.test.js +0 -25
package/tests/integrative.test.js +0 -83
package/tests/keywords.test.js +0 -47
package/tests/link.test.js +0 -33
package/tests/script.test.js +0 -42
package/tests/style.test.js +0 -34
package/tests/url.test.js +0 -42
package/tests/viewport.test.js +0 -41

package/readme.md CHANGED Viewed

@@ -1,163 +1,186 @@
-# als-layout Documentation
-`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.
-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.
----
-## Installation and Import
-Install via npm:
-```bash
-npm i als-layout
-```
-### Node (CommonJS)
-```js
-const Layout = require('als-layout')
-```
-### ESM (Module)
-```js
-import Layout from 'als-layout'
-```
-### Browser (with bundle)
-```html
-<script src="layout.js"></script>
-<script>
-   const layout = new Layout()
-</script>
-```
----
-## Change Log for V7
-**⚠ Breaking changes: not backward compatible.**
-### Removed
-- `uglify js and css`
-- `status` method
-- `end` method
-- `minified` attribute
-- `propsToClone`
-### Changed
-- All code is merged into a single file
-- Added **ESM module build** (`index.mjs`)
-- Added **browser bundle** (`layout.js`) that includes `als-document` and exposes a global `Layout`
----
-## Basic Usage
-### Initialization
-```js
-const layout = new Layout();
-```
-### Adding Elements
-```js
-const layout = new Layout()
-   .viewport() // default: width=device-width, initial-scale=1.0
-   .title('Test title') // sets <title> and meta[og:title]
-   .favicon('/favicon.png') // adds/updates favicon link
-   .keywords(['some', 'keyword']) // updates meta[name=keywords]
-   .image('/main-image.png') // sets og:image, twitter:image, twitter:card
-   .description('Cool site') // sets meta description tags
-   .url('/some', 'http://site.com') // sets canonical + og:url
-   .style('body {margin:0; background-color:whitesmoke;}') // appends CSS to style tag
-   .link('/styles.css') // adds stylesheet link if not already present
-   .script({src:'/app.js'}) // external script
-   .script({}, 'console.log("hello world")', false) // inline script in body
-// Accessors
-layout.body // getter for <body>
-layout.head // getter for <head>
-layout.html // getter for <html>
-// Outputs
-layout.rawHtml // raw HTML string
-layout.clone   // cloned Layout instance
-```
----
-## Cloning
-### Why Clone?
-Cloning creates a complete, independent copy of a `Layout` instance. Useful when generating multiple pages from a base template.
-### Example
-```js
-const newLayout = layout.clone;
-newLayout.title('Cloned page');
-```
-- **Efficiency** – avoids rebuilding from scratch
-- **Isolation** – modifications to clones don’t affect the original
-- **Performance** – fast even for larger layouts
----
-## Advanced Usage
-```js
-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></head><body></body></html>
-const homePage = layout.clone;
-homePage.title('Home page');
-homePage.body.innerHTML = `<h1>Home page</h1>`;
-console.log(homePage.rawHtml);
-const autoReload = layout.clone;
-autoReload.script({}, 'setTimeout(() => window.location.reload(), 60000);', false);
-```
----
-## API
-### Constructor
-```js
-new Layout(html?: string, host?: string)
-```
-- **html**: optional HTML string
-- **host**: base host for resolving relative URLs
-### Properties
-- `layout.rawHtml` – returns the current document as HTML string
-- `layout.clone` – returns a cloned instance
-### Methods
-- `lang(lang: string)` – sets `<html lang>`
-- `title(title: string)` – sets document `<title>` and Open Graph title
-- `description(description: string)` – sets description meta tags
-- `favicon(href: string)` – sets or updates favicon
-- `meta(props: object)` – sets or updates a `<meta>` tag
-- `keywords(keywords: string[])` – sets or appends to `meta[name=keywords]`
-- `viewport(viewport: string = 'width=device-width, initial-scale=1.0')` – sets viewport meta
-- `image(image: string)` – sets OG and Twitter image meta tags
-- `style(styles: string)` – appends CSS styles into `<style>`
-- `url(url: string, host?: string)` – sets canonical + og:url
-- `script(attrs: object = {}, innerHTML: string = '', head: boolean = true)` – adds `<script>` tag
-- `link(href: string, attributes: object = { rel: "stylesheet", type: "text/css" })` – adds stylesheet link
----
-## Notes
-- Version 7 removed **status**, **end**, **minified**, and **propsToClone**.
-- Use `clone` for creating independent layouts instead of extending clone properties.
-- Use `layout.js` in the browser for quick setup (exposes global `Layout`).
+# als-layout
+`als-layout` is a small, dependency‑light library for building and manipulating an HTML
+document in memory — title, meta tags, Open Graph / Twitter cards, styles, scripts, links,
+favicon and viewport — with a fluent, chainable API. It works the same in Node (SSR /
+static generation) and in the browser.
+It is built on top of [`als-document`](https://www.npmjs.com/package/als-document) and is a
+pure **document** builder: it has no global state and no site‑level concerns (collections,
+sitemaps, robots). For multi‑page sites built on top of it, see
+[`als-site`](https://www.npmjs.com/package/als-site).
+---
+## What's new in 7.1
+- **`toDocument()`** — render a layout into the live DOM on the client (no‑op in Node).
+- **`urlObj`** — `url()` now exposes the parsed `URL`.
+- **Packaging** — ESM resolves to the named `Layout` export, CommonJS to the class (`exports` map).
+- **Fix** — `twitter:description` uses `name=` (was `property=`), per the Twitter Cards spec.
+- **Fix** — `clone` preserves the document URL/host.
+- **Change** — `url()` keeps the canonical trailing slash (`URL.href`) and stores `urlObj`.
+See the full [Changelog](#changelog) below.
+---
+## Installation
+```bash
+npm i als-layout
+```
+### ESM (named export)
+```js
+import { Layout } from 'als-layout'
+```
+### Node (CommonJS)
+```js
+const Layout = require('als-layout')
+```
+### Browser bundle (global `Layout`, `als-document` inlined)
+```html
+<script src="layout.js"></script>
+<script>const layout = new Layout()</script>
+```
+---
+## Quick start
+```js
+import { Layout } from 'als-layout'
+const layout = new Layout(undefined, 'https://example.com')
+   .lang('en')
+   .viewport()                                   // width=device-width, initial-scale=1.0
+   .title('Home')                                // <title> + og:title
+   .description('A cool site')                   // description + og/twitter description
+   .keywords(['stats', 'sheets'])
+   .favicon('/favicon.png')
+   .image('/cover.png')                          // og:image, twitter:image, twitter:card
+   .link('/styles.css')                          // <link rel=stylesheet> (deduped)
+   .style('body{margin:0}')                      // appends to <style>
+   .script({ src: '/app.js' })                   // <script> in <head>
+   .script({}, 'console.log("hi")', false)       // inline <script> in <body>
+   .url('/')                                      // canonical + og:url, resolved vs host
+layout.body.innerHTML = '<h1>Home</h1>'
+console.log(layout.rawHtml)                       // full HTML string
+```
+---
+## A Layout is an offline DOM
+This is the core idea: a `Layout` extends an `als-document` document, so the instance is a
+real, in‑memory **DOM tree** you can query and mutate almost exactly like the browser DOM —
+no `jsdom`, no browser, works in plain Node. The chainable `title()/meta()/link()/…` helpers
+are just convenience on top of it; for anything else you manipulate nodes directly.
+```js
+const layout = new Layout(/*html*/`<html><head></head><body><main></main></body></html>`)
+// Query like the DOM ($ / $$ are aliases for querySelector / querySelectorAll)
+const main = layout.$('main')              // === layout.querySelector('main')
+const items = layout.$$('.item')           // === querySelectorAll, returns an array
+// Build and insert nodes
+main.innerHTML = '<h1>Hello</h1>'
+main.insert(2, '<p class="lead">Intro</p>')          // append parsed HTML
+main.insertAdjacentHTML('beforeend', '<hr>')
+// Mutate elements with the familiar API
+const h1 = layout.$('h1')
+h1.setAttribute('id', 'top')
+h1.classList.add('title')
+h1.dataset.role = 'heading'
+h1.textContent = 'Welcome'
+console.log(h1.outerHTML)                   // <h1 id="top" class="title" data-role="heading">Welcome</h1>
+// Traverse
+h1.parent          // parent node
+h1.nextElementSibling
+layout.body.children
+// Remove
+layout.$('hr').remove()
+```
+Supported on nodes: `querySelector`/`$`, `querySelectorAll`/`$$`, `getElementById`,
+`getAttribute`/`setAttribute`/`removeAttribute`, `classList`, `dataset`, `style`,
+`innerHTML`/`outerHTML`/`textContent`, `append`/`insert`/`insertAdjacentHTML`/`remove`,
+plus traversal (`parent`, `children`, `prev`/`next`, …). See
+[`als-document`](https://www.npmjs.com/package/als-document) for the full node API.
+On the client, `toDocument()` flushes this offline DOM into the live `document`.
+---
+## Cloning
+`layout.clone` returns a deep, independent copy — ideal as a template for many pages.
+Changes to a clone never affect the original.
+```js
+const base = new Layout(template, 'https://example.com').link('/styles.css')
+const about = base.clone.title('About').url('/about')
+```
+---
+## API
+### Constructor
+```js
+new Layout(html?: string, host?: string)
+```
+- **html** — optional HTML string to start from.
+- **host** — base URL used to resolve relative URLs in `url()`.
+### Properties
+- `rawHtml` — current document as an HTML string.
+- `clone` — a deep, independent copy.
+- `urlObj` — the parsed `URL` of the last `url()` call (set after `url()`).
+- `head` / `body` / `html` — element accessors (from `als-document`).
+### Methods (all chainable, return `this`)
+- `lang(lang)` — sets `<html lang>`.
+- `title(title)` — sets `<title>` and `og:title`.
+- `description(text)` — sets `description`, `og:description`, `twitter:description`.
+- `keywords(list)` — sets/merges `meta[name=keywords]`.
+- `meta(props)` — sets/updates a `<meta>` tag (keyed by its first attribute).
+- `image(src)` — sets `og:image`, `twitter:image`, `twitter:card`.
+- `favicon(href)` — sets/updates the favicon link.
+- `viewport(content?)` — sets the viewport meta.
+- `link(href, attributes?)` — adds a stylesheet `<link>` (skipped if already present).
+- `style(css)` — appends CSS to a `<style>` element.
+- `script(attrs?, innerHTML?, head = true)` — adds a `<script>` (head or body; `src` deduped).
+- `url(url, host = this.URL)` — sets canonical + `og:url`, stores `urlObj`.
+- `toDocument()` — in the browser, renders this layout into the live `document` (no‑op in Node); returns `this`.
+---
+## Changelog
+### 7.1.0
+- **Added** `toDocument()` — render a layout into the live DOM on the client.
+- **Added** `urlObj` — `url()` now exposes the parsed `URL`.
+- **Added** `exports` map — ESM resolves to the named `Layout` export, CommonJS to the class.
+- **Fixed** `twitter:description` now uses `name=` (was `property=`), per the Twitter Cards spec.
+- **Fixed** `clone` preserves the document URL/host.
+- **Changed** `url()` keeps the canonical trailing slash (`URL.href`), and stores `urlObj`.
+### 7.0.0 (breaking)
+- Merged into a single source file; added ESM build (`index.mjs`) and browser bundle (`layout.js`).
+- Removed `status`, `end`, `minified`, `propsToClone`, and JS/CSS uglification.
+---
+## Notes
+- Pure document builder — no global state, no file I/O.
+- `index.mjs` and the browser `layout.js` are generated from `src/layout.js` by `node build.js`.
+- Use `clone` to derive page variants from a base template.

package/src/layout.js CHANGED Viewed

@@ -1,85 +1,93 @@
-const { Document, SingleNode, Node } = require('als-document');
-class Layout extends Document {
-   constructor(html, host) { super(html, host); this.root = this.html; }
-   get rawHtml() { return this.innerHTML }
-   get clone() { return new this.constructor(new Document(this, this.URL), this.host) }
-   lang(lang) { this.html.setAttribute('lang', lang); return this }
-   link(href, attributes = { rel: "stylesheet", type: "text/css" }) {
-      if (!href || typeof href !== 'string') throw new Error(`href attribute must be a string`)
-      if (!this.root.querySelector(`link[rel=stylesheet][href^="${href}"]`))
-         this.head.insert(2, new SingleNode('link', { href, ...attributes }))
-      return this
-   }
-   keywords(keywords = []) {
-      let el = this.root.$('meta[name=keywords]') || new SingleNode('meta', { name: 'keywords' })
-      keywords = new Set([...(el.getAttribute('content') || '').split(','),...keywords.map(k => k.trim())].filter(Boolean))
-      if (keywords.size) el.setAttribute('content', Array.from(keywords).join(','))
-      if(keywords.size && !el.parent) this.head.insert(2, el)
-      return this
-   }
-   style(styles) {
-      if (typeof styles !== 'string') throw 'styles parameter should be string';
-      let el = this.root.$('style') || this.head.insert(2, new Node('style'))
-      el.innerHTML = el.innerHTML + '\n' + styles;
-      return this
-   }
-   url(url, host = this.URL) {
-      try {
-         url = (host ? new URL(url, host) : new URL(url)).href.replace(/\/$/, '')
-         this.meta({ property: 'og:url', content: url })
-         const el = this.root.$('link[rel="canonical"]') || this.head.insert(2, new SingleNode('link', { rel: 'canonical', href: url }))
-         el.setAttribute('href', url)
-      } catch (error) { error.info = `url "${url}" with host "${host}" is not valid url`; throw error; }
-      return this
-   }
-   meta(props) {
-      const entries = Object.entries(props)
-      const [name, value] = entries[0]
-      const metaElement = this.root.querySelector(`meta[${name}="${value}"]`) || this.head.insert(2, new SingleNode('meta', props))
-      entries.forEach(([name, v]) => metaElement.setAttribute(name, props[name]))
-      return this
-   }
-   script(attrs = {}, innerHTML = '', head = true) {
-      if (typeof attrs !== 'object' || attrs === null || Array.isArray(attrs)) attrs = {}
-      if (attrs.src && this.root.querySelector(`script[src="${attrs.src}"]`)) return this
-      if (Object.keys(attrs).length || innerHTML) {
-         const script = new Node('script', attrs)
-         if (innerHTML) script.innerHTML = innerHTML
-         if (head) this.head.insert(2, script)
-         else this.html.insert(2, script)
-      }
-      return this
-   }
-   description(description) {
-      this.meta({ name: 'description', content: description })
-      this.meta({ property: 'og:description', content: description })
-      this.meta({ property: 'twitter:description', content: description })
-      return this
-   }
-   favicon(href) {
-      const el = this.root.$('link[rel=icon][type=image/x-icon]')
-      if (el) el.setAttribute('href', href)
-      else this.head.insert(2, new SingleNode('link', { rel: 'icon', href, type: 'image/x-icon' }))
-      return this
-   }
-   viewport(viewport = 'width=device-width, initial-scale=1.0') {
-      const el = this.root.$('meta[name="viewport"]')
-      if (el) el.setAttribute('content', viewport)
-      else this.head.insert(2, new SingleNode('meta', { name: 'viewport', content: viewport }))
-      return this
-   }
-   image(image) {
-      this.meta({ property: 'og:image', content: image })
-      this.meta({ name: 'twitter:image', content: image })
-      this.meta({ name: 'twitter:card', content: 'summary_large_image' })
-      return this
-   }
-   title(title) {
-      super.title // create title tag if not exists
-      super.title = title
-      this.meta({ property: 'og:title', content: title })
-      return this
-   }
-}
-module.exports = Layout
+const { Document, SingleNode, Node } = require('als-document');
+class Layout extends Document {
+   constructor(html, host) { super(html, host); this.root = this.html; }
+   get rawHtml() { return this.innerHTML }
+   get clone() { return new this.constructor(new Document(this, this.URL), this.URL) }
+   lang(lang) { this.html.setAttribute('lang', lang); return this }
+   link(href, attributes = { rel: "stylesheet", type: "text/css" }) {
+      if (!href || typeof href !== 'string') throw new Error(`href attribute must be a string`)
+      if (!this.root.querySelector(`link[rel=stylesheet][href^="${href}"]`))
+         this.head.insert(2, new SingleNode('link', { href, ...attributes }))
+      return this
+   }
+   keywords(keywords = []) {
+      let el = this.root.$('meta[name=keywords]') || new SingleNode('meta', { name: 'keywords' })
+      keywords = new Set([...(el.getAttribute('content') || '').split(','),...keywords.map(k => k.trim())].filter(Boolean))
+      if (keywords.size) el.setAttribute('content', Array.from(keywords).join(','))
+      if(keywords.size && !el.parent) this.head.insert(2, el)
+      return this
+   }
+   style(styles) {
+      if (typeof styles !== 'string') throw 'styles parameter should be string';
+      let el = this.root.$('style') || this.head.insert(2, new Node('style'))
+      el.innerHTML = el.innerHTML + '\n' + styles;
+      return this
+   }
+   url(url, host = this.URL) {
+      try {
+         this.urlObj = (host ? new URL(url, host) : new URL(url))
+         url = this.urlObj.href
+         this.meta({ property: 'og:url', content: url })
+         const el = this.root.$('link[rel="canonical"]') || this.head.insert(2, new SingleNode('link', { rel: 'canonical', href: url }))
+         el.setAttribute('href', url)
+      } catch (error) { error.info = `url "${url}" with host "${host}" is not valid url`; throw error; }
+      return this
+   }
+   meta(props) {
+      const entries = Object.entries(props)
+      const [name, value] = entries[0]
+      const metaElement = this.root.querySelector(`meta[${name}="${value}"]`) || this.head.insert(2, new SingleNode('meta', props))
+      entries.forEach(([name, v]) => metaElement.setAttribute(name, props[name]))
+      return this
+   }
+   script(attrs = {}, innerHTML = '', head = true) {
+      if (typeof attrs !== 'object' || attrs === null || Array.isArray(attrs)) attrs = {}
+      if (attrs.src && this.root.querySelector(`script[src="${attrs.src}"]`)) return this
+      if (Object.keys(attrs).length || innerHTML) {
+         const script = new Node('script', attrs)
+         if (innerHTML) script.innerHTML = innerHTML
+         if (head) this.head.insert(2, script)
+         else this.html.insert(2, script)
+      }
+      return this
+   }
+   description(description) {
+      this.meta({ name: 'description', content: description })
+      this.meta({ property: 'og:description', content: description })
+      this.meta({ name: 'twitter:description', content: description })
+      return this
+   }
+   favicon(href) {
+      const el = this.root.$('link[rel=icon][type=image/x-icon]')
+      if (el) el.setAttribute('href', href)
+      else this.head.insert(2, new SingleNode('link', { rel: 'icon', href, type: 'image/x-icon' }))
+      return this
+   }
+   viewport(viewport = 'width=device-width, initial-scale=1.0') {
+      const el = this.root.$('meta[name="viewport"]')
+      if (el) el.setAttribute('content', viewport)
+      else this.head.insert(2, new SingleNode('meta', { name: 'viewport', content: viewport }))
+      return this
+   }
+   image(image) {
+      this.meta({ property: 'og:image', content: image })
+      this.meta({ name: 'twitter:image', content: image })
+      this.meta({ name: 'twitter:card', content: 'summary_large_image' })
+      return this
+   }
+   title(title) {
+      super.title // create title tag if not exists
+      super.title = title
+      this.meta({ property: 'og:title', content: title })
+      return this
+   }
+   toDocument() {
+      if (typeof window === 'undefined' || typeof document === 'undefined') return this
+      document.querySelector('title')?.remove()
+      document.head.innerHTML = this.head.innerHTML
+      document.body.outerHTML = this.body.outerHTML
+      return this
+   }
+}
+module.exports = Layout

package/build.js DELETED Viewed

@@ -1,8 +0,0 @@
-const { writeFileSync, readFileSync } = require('fs')
-const Layout = require('./src/layout.js');
-const content = Layout.toString()
-writeFileSync('index.mjs',`import { Document, SingleNode, Node } from 'als-document';\n`+'export '+content,'utf8' )
-const document = readFileSync('./node_modules/als-document/document.js','utf8')
-writeFileSync('layout.js',[document,`const { Document, SingleNode, Node } = alsDocument`,content].join('\n'))

package/tests/constructor.test.js DELETED Viewed

@@ -1,28 +0,0 @@
-const assert = require('assert');
-const { describe, it } = require('node:test')
-const Layout = require('../src/layout.js');
-describe('Layout Initialization', () => {
-    it('should create an instance of Layout', () => {
-        const layout = new Layout();
-        assert(layout instanceof Layout, 'layout is not an instance of Layout');
-    });
-    it('should initialize default language as "en"', () => {
-        const layout = new Layout();
-        assert(layout.html.getAttribute('lang') === 'en', 'default language is not "en"');
-    });
-    it('should allow setting a custom language', () => {
-        const customLang = 'fr';
-        const layout = new Layout(undefined).lang(customLang);
-        layout.lang(customLang)
-        assert(layout.html.getAttribute('lang') === customLang, `language is not set to ${customLang}`);
-    });
-    it('should allow setting a custom host', () => {
-        const customHost = 'http://localhost';
-        const layout = new Layout(undefined,customHost);
-        assert.strictEqual(layout.URL, customHost, `host is not set to ${customHost}`);
-    });
-});

package/tests/description.test.js DELETED Viewed

@@ -1,33 +0,0 @@
-const assert = require('assert');
-const { describe, it,beforeEach } = require('node:test')
-const Layout = require('../src/layout.js');
-describe('description and title', () => {
-   let layout;
-   beforeEach(() => layout = new Layout());
-   it('should add description correctly', () => {
-      const description = 'Test Description';
-      layout.description(description);
-      assert.strictEqual(layout.root.$('meta[name="description"]').getAttribute('content'), description, 'Description not set correctly');
-      assert.strictEqual(layout.root.$('meta[property="og:description"]').getAttribute('content'), description, 'Description not set correctly');
-      assert.strictEqual(layout.root.$('meta[property="twitter:description"]').getAttribute('content'), description, 'Description not set correctly');
-   });
-   it('should add title correctly', () => {
-      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');
-   });
-   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');
-   });
-});