coralite 0.5.0 → 0.6.0

package/bin/coralite.js

@@ -1,17 +1,12 @@
 #!/usr/bin/env node
 
-import { render } from 'dom-serializer'
-import { getHTML, parseHTMLDocument, parseModule, createComponent, getSubDirectory } from '#lib'
+import { getSubDirectory, getPkg, coralite } from '#lib'
 import { Command } from 'commander'
 import { join } from 'node:path'
-import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs'
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import kleur from 'kleur'
 
-/**
- * @import { CoraliteModule } from '#types'
- */
-
-const pkgPath = new URL('../package.json', import.meta.url)
-const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+const pkg = await getPkg()
 const program = new Command()
 
 program
@@ -21,7 +16,8 @@ program
   .requiredOption('-t, --templates <path>', 'Path to templates directory')
   .requiredOption('-p, --pages <path>', 'Path to pages directory')
   .requiredOption('-o, --output <path>', 'Output directory for the generated site')
-  .option('-d, --dry', 'Run in dry-run mode')
+  .option('-i, --ignore-attribute <key=value...>', 'Ignore elements by attribute name value pair', [])
+  .option('-d, --dry-run', 'Run in dry-run mode')
 
 program.parse(process.argv)
 program.on('error', (err) => {
@@ -29,81 +25,52 @@ program.on('error', (err) => {
 })
 
 const options = program.opts()
-const templatesPath = options.templates
-const pagesPath = options.pages
-const outputDir = options.output
-const dryRun = options.dry
-
-const htmlTemplates = await getHTML({
-  path: templatesPath,
-  recursive: true
-})
-const htmlPages = await getHTML({
-  path: pagesPath,
-  recursive: true
-})
+const pages = options.pages
+const output = options.output
+const ignoreByAttribute = []
 
-/** @type {Object.<string, CoraliteModule>} */
-const coraliteModules = {}
+for (let i = 0; i < options.ignoreAttribute.length; i++) {
+  const pair = options.ignoreAttribute[i].split('=')
 
-// create templates
-for (let i = 0; i < htmlTemplates.length; i++) {
-  const html = htmlTemplates[i]
-  const coraliteModule = parseModule(html.content)
+  if (pair.length !== 2) {
+    throw new Error('Ignore attribute "' + pair[0] + '" expected a value but found none')
+  }
 
-  coraliteModules[coraliteModule.id] = coraliteModule
+  ignoreByAttribute.push(pair)
 }
 
-for (let i = 0; i < htmlPages.length; i++) {
-  const html = htmlPages[i]
-  const document = parseHTMLDocument(html, {
-    pages: pagesPath,
-    templates: templatesPath
-  })
-
-  for (let i = 0; i < document.customElements.length; i++) {
-    const customElement = document.customElements[i]
-    const component = await createComponent({
-      id: customElement.name,
-      values: customElement.attribs,
-      element: customElement,
-      components: coraliteModules,
-      document
-    })
+const documents = await coralite({
+  templates: options.templates,
+  pages,
+  ignoreByAttribute
+})
 
-    for (let i = 0; i < component.children.length; i++) {
-      // update component parent
-      component.children[i].parent = customElement.parent
-    }
-    const index = customElement.parent.children.indexOf(customElement, customElement.parentChildIndex)
-    // replace custom element with template
-    customElement.parent.children.splice(index, 1, ...component.children)
-  }
+if (options.dryRun) {
+  const PAD = '  '
+  const border = '─'.repeat(Math.min(process.stdout.columns, 36) / 2)
 
-  // render document
-  // @ts-ignore
-  const content = render(document.root)
+  for (let i = 0; i < documents.length; i++) {
+    const document = documents[i]
 
-  if (!dryRun) {
+    process.stdout.write('\n' + PAD + kleur.green('Document is ready!\n\n'))
+    process.stdout.write(PAD + `${kleur.bold('- Path:')}      ${join(document.item.parentPath, document.item.name)}\n`)
+    process.stdout.write(PAD + `${kleur.bold('- Built in:')}      ${Math.floor(document.duration)}ms\n\n`)
+    process.stdout.write(border + kleur.inverse(' Content start ') + border + '\n\n')
+    process.stdout.write(document.html)
+    process.stdout.write('\n\n' + border + kleur.inverse(' Content end ') + border + '\n')
+  }
+} else {
+  for (let i = 0; i < documents.length; i++) {
+    const document = documents[i]
     // get pages sub directory
-    const subDir = getSubDirectory(pagesPath, html.parentPath)
-    const dir = join(outputDir, subDir)
-
-    try {
-      if (!existsSync(dir)) {
-        // create directory
-        mkdirSync(dir)
-      }
+    const subDir = getSubDirectory(pages, document.item.parentPath)
+    const dir = join(output, subDir)
 
-      writeFileSync(join(dir, html.name), content)
-      // file written successfully
-    } catch (err) {
-      console.error(err)
+    if (!existsSync(dir)) {
+    // create directory
+      mkdirSync(dir)
     }
-  } else {
-    console.log('Document')
-    console.log('Path: ' + join(html.parentPath, html.name))
-    console.log('Content')
-    console.log(content)
+
+    writeFileSync(join(dir, document.item.name), document.html)
   }
 }

package/eslint.config.js

@@ -110,7 +110,8 @@ export default [
   {
     ignores: [
       '**/dist/',
-      '**/.history/'
+      '**/.history/',
+      '**/playwright-report/'
     ]
   }
 ]

package/lib/coralite.js

@@ -1,5 +1,13 @@
+import { createComponent, parseHTMLDocument, parseModule, getHTML } from '#lib'
+import render from 'dom-serializer'
+
 /**
- * @import { CoraliteElement, CoraliteTextNode } from '#types'
+ * @import {
+ *  CoraliteElement,
+ *  CoraliteTextNode,
+ *  CoraliteAggregateTemplate,
+ *  CoraliteAnyNode,
+ *  CoraliteModule } from '#types'
  */
 
 /**
@@ -7,6 +15,11 @@
  * The HTML module code is run in the `parseScript` function in parse.js
  */
 
+/**
+ * @callback DefineComponentSlot
+ * @param {CoraliteAnyNode[]} nodes
+ */
+
 /**
  * @type {Object.<string, string>}
  */
@@ -17,8 +30,8 @@ export const tokens = {}
  *
  * @param {Object} options
  * @param {string} [options.id] - Optional component id, if not defined, the id will be extracted from the first top level element with the id attribute
- * @param {Object.<string, (string | Function)>} options.tokens - Token names and values are either strings or functions representing the corresponding tokens' content or behavior.
- * @param {Object.<string, Function>} options.slots - Middleware for slot content
+ * @param {Object.<string, (string | Function)>} [options.tokens] - Token names and values are either strings or functions representing the corresponding tokens' content or behavior.
+ * @param {Object.<string, DefineComponentSlot>} [options.slots] - Middleware for slot content
  * @returns {Promise<Object.<string, string>>}
  */
 export async function defineComponent (options) {
@@ -30,10 +43,90 @@ export async function defineComponent (options) {
  * Aggregates HTML content from specified paths into a single collection of components.
  *
  * @param {Object} options - Configuration object for the aggregation process
- * @param {string} options.componentId - Unique identifier for the component used for each document
+ * @param {CoraliteAggregateTemplate | string} options.template - Templates used to display the result
  * @param {string} options.path - The path to aggregate, relative to pages directory
  * @returns {Promise<(CoraliteElement | CoraliteTextNode)[]>}
  */
 export async function aggregate (options) {
   return []
 }
+
+/**
+ * @param {Object} options
+ * @param {string} options.templates
+ * @param {string} options.pages
+ * @param {Array<string[]>} [options.ignoreByAttribute]
+ */
+export async function coralite ({
+  templates,
+  pages,
+  ignoreByAttribute
+}) {
+  const startTime = performance.now()
+  const htmlTemplates = await getHTML({
+    path: templates,
+    recursive: true
+  })
+  const htmlPages = await getHTML({
+    path: pages,
+    recursive: true
+  })
+
+  /** @type {Object.<string, CoraliteModule>} */
+  const coraliteModules = {}
+  const documents = []
+
+  // create templates
+  for (let i = 0; i < htmlTemplates.length; i++) {
+    const html = htmlTemplates[i]
+    const coraliteModule = parseModule(html.content)
+
+    coraliteModules[coraliteModule.id] = coraliteModule
+  }
+
+  for (let i = 0; i < htmlPages.length; i++) {
+    const html = htmlPages[i]
+    const document = parseHTMLDocument(html, {
+      pages,
+      templates
+    }, ignoreByAttribute)
+
+    for (let i = 0; i < document.customElements.length; i++) {
+      const customElement = document.customElements[i]
+      const component = await createComponent({
+        id: customElement.name,
+        values: customElement.attribs,
+        element: customElement,
+        components: coraliteModules,
+        document
+      })
+
+      if (!component) {
+      // skip if no component
+        continue
+      }
+
+      for (let i = 0; i < component.children.length; i++) {
+      // update component parent
+        component.children[i].parent = customElement.parent
+      }
+      const index = customElement.parent.children.indexOf(customElement, customElement.parentChildIndex)
+      // replace custom element with template
+      customElement.parent.children.splice(index, 1, ...component.children)
+    }
+
+    // render document
+    // @ts-ignore
+    const result = render(document.root)
+
+    documents.push({
+      item: document,
+      html: result,
+      duration: performance.now() - startTime
+    })
+  }
+
+  return documents
+}
+
+export default coralite

package/lib/get-pkg.js

@@ -0,0 +1,22 @@
+import { readFile } from 'node:fs/promises'
+
+/**
+ * @typedef {Object} PackageJson
+ * @property {string} name
+ * @property {string} description
+ * @property {string} version
+ */
+
+/**
+ * Get package.json
+ * @return {Promise<PackageJson>}
+ */
+export async function getPkg () {
+  try {
+    const pkgPath = await readFile(new URL('../package.json', import.meta.url), { encoding: 'utf8' })
+
+    return JSON.parse(pkgPath)
+  } catch (err) {
+    console.error(err.message)
+  }
+}

package/lib/html-module.js

@@ -11,7 +11,8 @@ import { createComponent, parseHTMLMeta } from './parse.js'
  *
  * @param {Object} options - Configuration object for the aggregation process
  * @param {string} options.path - The path to aggregate, relative to pages directory
- * @param {string} options.componentId - Unique identifier for the component
+ * @param {Object} options.template - Templates used to display the result
+ * @param {string} options.template.item - Unique identifier for the component used for each document
  * @param {boolean} [options.recursive] - Whether to recursively search subdirectories
  * @param {CoraliteTokenOptions} [options.tokens] - Token configuration options
  * @param {CoraliteModuleValues} values - Default token values
@@ -24,7 +25,7 @@ import { createComponent, parseHTMLMeta } from './parse.js'
  * aggregate({
  *   path: 'button',
  *   recursive: true,
- *   componentId: 'my-component'
+ *   template: { item: 'my-component' }
  * }, {
  *   className: 'btn'
  * }, components, document);
@@ -62,7 +63,7 @@ export async function aggregate (options, values, components, document) {
     }
 
     const component = await createComponent({
-      id: options.componentId,
+      id: options.template.item,
       values: pageValues,
       components,
       document

package/lib/index.js

@@ -1,8 +1,11 @@
 import getHTML from './get-html.js'
+import coralite from './coralite.js'
 
 export * from './parse.js'
 export * from './path-utils.js'
+export * from './get-pkg.js'
 
 export {
-  getHTML
+  getHTML,
+  coralite
 }

package/lib/parse.js

@@ -18,6 +18,7 @@ import { invalidCustomTags, validTags } from './tags.js'
  *  CoraliteDocumentRoot,
  *  CoraliteContentNode,
  *  CoraliteModuleValues,
+ *  CoraliteAggregateTemplate
  * } from '#types'
  */
 
@@ -30,6 +31,7 @@ const customElementTagTokenRegExp = /^[^-].*[-._a-z0-9\u00B7\u00C0-\u00D6\u00D8-
  *
  * @param {HTMLData} html - The HTML data containing the content to parse
  * @param {CoralitePath} path - The path object containing the file path information
+ * @param {Array<string[]>} [ignoreByAttribute] - Ignore element with attribute name value pair
  * @returns {CoraliteDocument} An object representing the parsed document structure
  *
  * @example
@@ -50,13 +52,14 @@ const customElementTagTokenRegExp = /^[^-].*[-._a-z0-9\u00B7\u00C0-\u00D6\u00D8-
  * // document.root will contain parsed elements and text nodes
  * ```
  */
-export function parseHTMLDocument (html, path) {
+export function parseHTMLDocument (html, path, ignoreByAttribute) {
   // root element reference
   /** @type {CoraliteDocumentRoot} */
   const root = {
     type: 'root',
     children: []
   }
+
   // stack to keep track of current element hierarchy
   /** @type {CoraliteContentNode[]} */
   const stack = [root]
@@ -74,6 +77,16 @@ export function parseHTMLDocument (html, path) {
       const parent = stack[stack.length - 1]
       const element = createElement(originalName, attributes, customElements, parent)
 
+      if (ignoreByAttribute) {
+        for (let i = 0; i < ignoreByAttribute.length; i++) {
+          const [key, value] = ignoreByAttribute[i]
+
+          if (attributes[key] && attributes[key].includes(value)) {
+            element.remove = true
+          }
+        }
+      }
+
       // push element to stack as it may have children
       stack.push(element)
     },
@@ -83,6 +96,15 @@ export function parseHTMLDocument (html, path) {
       createTextNode(text, parent)
     },
     onclosetag () {
+      const element = stack[stack.length - 1]
+
+      // @ts-ignore
+      if (element.remove) {
+        // remove element from tree
+        // @ts-ignore
+        element.parent.children.pop()
+      }
+
       // remove current element from stack as we're done with its children
       stack.pop()
     },
@@ -399,7 +421,7 @@ export function parseModule (string) {
  * @param {Object.<string, CoraliteModule>} options.components - Mapping of component IDs to their module definitions
  * @param {CoraliteElement} [options.element] - Mapping of component IDs to their module definitions
  * @param {CoraliteDocument} options.document - Current document being processed
- * @returns {Promise<CoraliteElement>}
+ * @returns {Promise<CoraliteElement | void>}
  *
  * @example
  * ```
@@ -431,7 +453,7 @@ export async function createComponent ({
   let component = components[id]
 
   if (!component) {
-    throw new Error('Could not find component: "' + id +'"')
+    return console.warn('Could not find component "' + id +'" used in document "' + document.parentPath + '/' + document.name + '"')
   }
 
   component = structuredClone(component)
@@ -625,6 +647,7 @@ export async function createComponent ({
  */
 export async function parseScript (component, values, element, components, document) {
   const contextifiedObject = vm.createContext({
+    crypto,
     coralite: {
       tokens: values,
       /**
@@ -692,15 +715,31 @@ export async function parseScript (component, values, element, components, docum
         return values
       },
       /**
+       * @overload
        * @param {Object} options
-       * @param {string} options.componentId
+       * @param {string} options.template - Templates used to display the result
+       * @param {string} options.path
+       */
+
+      /**
+       * @param {Object} options
+       * @param {CoraliteAggregateTemplate} options.template - Templates used to display the result
        * @param {string} options.path
        */
       async aggregate (options) {
-        const component = components[options.componentId]
+        /** @type {string} */
+        let templateId
+
+        if (typeof options.template === 'string') {
+          templateId = options.template
+        } else {
+          templateId = options.template.item
+        }
+
+        const component = components[templateId]
 
         if (!component) {
-          throw new Error('Aggregate: no component found by the id: ' + options.componentId)
+          throw new Error('Aggregate: no template found by the id: ' + templateId)
         }
 
         return await aggregate(options, values, components, document)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coralite",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "HTML modules static site generator",
   "main": "./lib/coralite.js",
   "type": "module",
@@ -31,7 +31,7 @@
     "test-e2e": "playwright test",
     "test-e2e-report": "playwright show-report",
     "test-e2e-ui": "playwright test --ui",
-    "html": "node --experimental-vm-modules bin/coralite.js -t tests/fixtures/templates -p tests/fixtures/pages -o dist",
+    "html": "node --experimental-vm-modules bin/coralite.js -t tests/fixtures/templates -p tests/fixtures/pages -o dist -i 'data-dev=true'",
     "server": "sirv dist --dev --port 3000"
   },
   "bin": "bin/coralite.js",
@@ -40,8 +40,14 @@
     "#types": "./types/index.js"
   },
   "exports": {
-    "default": "./lib/coralite.js",
-    "types": "./types/index.js"
+    ".": {
+      "default": "./lib/coralite.js",
+      "types": "./types/index.js"
+    },
+    "./utils": {
+      "default": "./lib/index.js",
+      "types": "./types/index.js"
+    }
   },
   "devDependencies": {
     "@commitlint/cli": "^19.6.1",
@@ -50,6 +56,7 @@
     "@stylistic/eslint-plugin-js": "^2.12.1",
     "@stylistic/eslint-plugin-plus": "^2.12.1",
     "@types/node": "^22.10.5",
+    "kleur": "^4.1.5",
     "sirv-cli": "^3.0.0"
   },
   "engines": {

package/types/index.js

@@ -72,6 +72,7 @@
  * @property {CoraliteContentNode} parent - Parent element
  * @property {number} [parentChildIndex] - Position in parent's child list
  * @property {Object[]} [slots]
+ * @property {boolean} [remove] - Mark element to be removed from stack
  */
 
 
@@ -123,3 +124,8 @@
  * @property {CoraliteElement[]} customElements - Custom elements defined in the document
  * @property {CoralitePath} path - Document's file path
  */
+
+/**
+ * @typedef {Object} CoraliteAggregateTemplate - Templates used to display the result
+ * @property {string} item - Unique identifier for the component used for each document
+ */