coralite 0.7.1 → 0.8.0

package/bin/coralite.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node --experimental-vm-modules
+#!/usr/bin/env node --experimental-vm-modules --experimental-import-meta-resolve
 
 import { getSubDirectory, getPkg, coralite } from '#lib'
 import { Command } from 'commander'

package/changelog.md

@@ -1,12 +1,66 @@
+# 🎁 Release notes (`v0.8.0`)
+
+## Changes
+- 25c4669 (HEAD -> main, tag: v0.8.0, origin/main) feat(aggregate): add pagination support - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 1268e3c fix(aggregate): handle non-array metadata values correctly - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 42c3ae0 fix(aggregate): handle string and non-array limit values correctly - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 0538a80 fix(aggregate): Handle offset parsing robustly for numeric conversion - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 4d2fe56 feat(aggregate): Add metadata-based page filtering using options.filter - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 176c7f3 feat(lib/html-module): add support for custom sort function in aggregate - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 3acfb99 feat(lib/html-module): add pagination support with token validation - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 41b0e10 refactor(lib): integrate htmlparser2 and dom-serializer for improved HTML parsing - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 0c7fb5e refactor(html-module): update aggregate to use component element children and return Aggregation object - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 6bb83d3 refactor: restructure document rendering logic and add HTMLData type support - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 8d4b43c refactor: move coralite rendering logic to new renderDocument function - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- c81786e types: add pagination configuration to CoraliteAggregate - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- c8ddec4 feat(metadata): Update metadata token prefix to '$' - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- ee57e18 feat: add parsePagination function for handling pagination templates - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 4471482 types: add Aggregation typedef and update imports - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 2772969 docs: Improve JSDoc clarity for parseHTMLDocument function - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 37e79db refactor: restructure html file path properties - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- dab3a61 refactor: Export createTextNode function - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- c538186 fix: handle custom element creation with proper tag validation - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 58d101d refactor: update addMetadata to support non-array values as array of objects - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- d0fa67c docs: update parseHTMLMeta parameters and example documentation - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- de8035e fix: correct path calculation in parseScript function - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- b9c94ee refactor(parse): use scriptResult.values instead of computedValues when merging values - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 7b0be0c fix: correct script parsing path resolution and module identifier - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 803aa3e refactor(parse): refactor aggregate method to use helper and collect documents - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 2c77b44 fix: add warning when component is not found - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 885fd6c refactor(parseModule): remove html parameter and introduce lineOffset property - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 84c8a74 types: allow string or CoraliteToken[] as meta value types - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 0b9ce81 refactor: merge html.path into path object in parseHTMLDocument - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 1964a60 types: update JSDoc types for aggregate callbacks - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 2205c1a types: Refactor types to introduce CoraliteFilePath and improve module interface definitions - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- c37fa7c docs: add CoraliteComponent import - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 281e07e refactor: rename getHTML to getHtmlFiles and add getHtmlFile function - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- f91251a types: Update return type of createComponent to CoraliteComponent - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- d6fab1e refactor: use cleanKeys for consistent naming conventions - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- dfe3b06 docs: update aggregate comments - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 6a495f3 feat: add document data to  component - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 17afeb4 feat: require experimental-import-meta-resolve for dynamic imports - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 34ccd76 feat: dynamic module linker - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 828bcaa feat: add console to script context - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 47ab7db chore: version bump - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 4c7f361 fix kleur dependencies - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 2f88f2d chore: update changelong - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- aedf75f chore: version bump - (*[Thomas David](https://codeberg.org/tjdavid)*)
+
+## Metadata
+```
+This version -------- v0.8.0
+Previous version ---- v0.7.0
+Total commits ------- 44
+```
 # 🎁 Release notes (`v0.7.0`)
 
 ## Changes
-- d7b183d (HEAD -> main, tag: v0.7.0, origin/main) fix: use type helper to confirm child is a node - (*Thomas David*)
-- b574569 feat: check if slot is a node - (*Thomas David*)
-- de05e38 feat: type helper functions - (*Thomas David*)
-- 24f3935 test: cover nested components attributes - (*Thomas David*)
-- 8dc8f5d fix: apply nested custom component attribute values - (*Thomas David*)
-- 3fa3eb5 chore: version bump - (*Thomas David*)
+- d7b183d (HEAD -> main, tag: v0.7.0, origin/main) fix: use type helper to confirm child is a node - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- b574569 feat: check if slot is a node - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- de05e38 feat: type helper functions - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 24f3935 test: cover nested components attributes - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 8dc8f5d fix: apply nested custom component attribute values - (*[Thomas David](https://codeberg.org/tjdavid)*)
+- 3fa3eb5 chore: version bump - (*[Thomas David](https://codeberg.org/tjdavid)*)
 
 ## Metadata
 ```

package/lib/coralite.js

@@ -1,4 +1,4 @@
-import { createComponent, parseHTMLDocument, parseModule, getHTML } from '#lib'
+import { createComponent, parseHTMLDocument, parseModule, getHtmlFiles } from '#lib'
 import render from 'dom-serializer'
 
 /**
@@ -8,8 +8,9 @@ import render from 'dom-serializer'
  *  CoraliteAnyNode,
  *  CoraliteModule,
  *  CoraliteResult,
- *  CoraliteAggregate
- * } from '#types'
+ *  CoraliteAggregate,
+ *  IgnoreByAttribute,
+ *  HTMLData } from '#types'
  */
 
 /**
@@ -86,69 +87,128 @@ export async function coralite ({
   ignoreByAttribute
 }) {
   const startTime = performance.now()
-  const htmlTemplates = await getHTML({
+  const htmlTemplates = await getHtmlFiles({
     path: templates,
     recursive: true
   })
-  const htmlPages = await getHTML({
+  const htmlPages = await getHtmlFiles({
     path: pages,
     recursive: true
   })
 
   /** @type {Object.<string, CoraliteModule>} */
-  const coraliteModules = {}
-  /** @type {CoraliteResult[]} */
-  const documents = []
+  const components = {}
 
   // create templates
   for (let i = 0; i < htmlTemplates.length; i++) {
     const html = htmlTemplates[i]
-    const coraliteModule = parseModule(html.content, ignoreByAttribute)
+    const component = parseModule(html.content, {
+      ignoreByAttribute
+    })
 
-    coraliteModules[coraliteModule.id] = coraliteModule
+    components[component.id] = {
+      ...component,
+      path: html.path
+    }
   }
 
+  /** @type {CoraliteResult[]} */
+  const documents = []
+
   for (let i = 0; i < htmlPages.length; i++) {
     const html = htmlPages[i]
-    const document = parseHTMLDocument(html, {
+    await renderDocument({
+      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
-      }
+      templates,
+      ignoreByAttribute,
+      components,
+      startTime,
+      documents
+    })
+  }
+
+  return documents
+}
+
+/**
+ * Renders an HTML document using the provided configuration and components.
+ *
+ * @param {Object} param
+ * @param {HTMLData} param.html - The raw HTML content to render.
+ * @param {string} param.pages - Path to the root pages directory.
+ * @param {string} param.templates - Path to the root templates directory.
+ * @param {IgnoreByAttribute} param.ignoreByAttribute - An array of attribute names and values to ignore by element type.
+ * @param {Object} param.components - Components configuration used during rendering.
+ * @param {number} param.startTime - Timestamp when rendering started (for performance tracking).
+ * @param {CoraliteResult[]} [param.documents=[]] - Array of rendered documents to accumulate results.
+ * @param {boolean} [param.isHead=true] - Whether this is the head section (controls recursive rendering behavior).
+ *
+ * @returns {Promise<CoraliteResult[]>} A promise that resolves to an array of rendered document results.
+ */
+async function renderDocument ({
+  html,
+  pages,
+  templates,
+  ignoreByAttribute,
+  components,
+  startTime,
+  documents = [],
+  isHead = true
+}) {
+  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,
+      document
+    })
 
-      for (let i = 0; i < component.children.length; i++) {
-      // update component parent
-        component.children[i].parent = customElement.parent
+    if (component) {
+      const element = component.element
+      for (let i = 0; i < element.children.length; i++) {
+        // update component parent
+        element.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)
+      customElement.parent.children.splice(index, 1, ...element.children)
+
+      if (isHead && component.documents) {
+        for (let i = 0; i < component.documents.length; i++) {
+          const html = component.documents[i]
+          await renderDocument({
+            html,
+            pages,
+            templates,
+            ignoreByAttribute,
+            components,
+            startTime,
+            documents,
+            isHead: false
+          })
+        }
+      }
     }
+  }
 
-    // render document
-    // @ts-ignore
-    const result = render(document.root)
+  // render document
+  // @ts-ignore
+  const result = render(document.root)
 
-    documents.push({
-      item: document,
-      html: result,
-      duration: performance.now() - startTime
-    })
-  }
+  documents.push({
+    item: document,
+    html: result,
+    duration: performance.now() - startTime
+  })
 
   return documents
 }

package/lib/get-html.js

@@ -15,13 +15,13 @@ import { readdir, readFile } from 'node:fs/promises'
  *
  * @example
  * // Example usage:
- * const htmlFiles = await getHTML({
+ * const htmlFiles = await getHtmlFiles({
  *  path: 'src',
  *  recursive: true,
  *  exclude: ['index.html', 'subdir/file2.html']
  * })
  */
-export default function getHTML ({ path, recursive = false, exclude = [] }) {
+export function getHtmlFiles ({ path, recursive = false, exclude = [] }) {
   return new Promise((resolve, reject) => {
     const html = []
 
@@ -39,10 +39,17 @@ export default function getHTML ({ path, recursive = false, exclude = [] }) {
             && !exclude.includes(file.name)
           ) {
             const parentPath = file.parentPath || file.path
+            const dirname = parentPath.replace(path, '')
+            const name = file.name
 
             html.push({
-              parentPath,
-              name: file.name
+              path: {
+                pathname: join(dirname, name),
+                filename: name,
+                dirname,
+                page: parentPath,
+                pageName: join(parentPath, name)
+              }
             })
 
             promises.push(readFile(join(parentPath, file.name), { encoding: 'utf8' }))
@@ -62,3 +69,24 @@ export default function getHTML ({ path, recursive = false, exclude = [] }) {
       .catch(error => reject(error))
   })
 }
+
+/**
+ * Reads an HTML file and returns its content as a string.
+ * @param {string} filename - The path to the HTML file.
+ * @returns {Promise<string>} A promise that resolves with the HTML content.
+ * @throws {Error} If the file cannot be read.
+ */
+export async function getHtmlFile (filename) {
+  try {
+    const extension = extname(filename).toLowerCase()
+
+    if (extension === '.html') {
+      const data = await readFile(filename, 'utf8')
+      return data
+    }
+
+    throw new Error('Unexpected filename extension "' + extension +'"')
+  } catch (err) {
+    throw err
+  }
+}