coralite 0.14.2 → 0.16.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 (46) hide show
  1. package/README.md +1 -1
  2. package/dist/about.html +20 -0
  3. package/dist/cast.html +13 -0
  4. package/dist/code.html +42 -0
  5. package/dist/index.html +24 -0
  6. package/dist/nested-components.html +54 -0
  7. package/docs/basic-templating.md +121 -0
  8. package/docs/coralite-cli.md +68 -0
  9. package/docs/coralite.md +130 -0
  10. package/docs/images/intro.gif +0 -0
  11. package/docs/images/logo.png +0 -0
  12. package/docs/types.md +360 -0
  13. package/lib/collection.js +61 -6
  14. package/lib/config.js +10 -0
  15. package/lib/coralite.js +123 -19
  16. package/lib/html.js +2 -1
  17. package/lib/index.js +1 -0
  18. package/lib/parse.js +10 -1
  19. package/lib/tags.js +9 -9
  20. package/package.json +13 -16
  21. package/playwright-report/index.html +76 -0
  22. package/plugins/define-component.js +19 -0
  23. package/plugins/index.js +1 -0
  24. package/plugins/refs.js +30 -0
  25. package/scripts/changelog.sh +128 -0
  26. package/test-results/.last-run.json +4 -0
  27. package/tests/e2e/index.spec.js +69 -0
  28. package/tests/fixtures/data/names.json +6 -0
  29. package/tests/fixtures/pages/about.html +14 -0
  30. package/tests/fixtures/pages/cast.html +11 -0
  31. package/tests/fixtures/pages/code.html +22 -0
  32. package/tests/fixtures/pages/index.html +20 -0
  33. package/tests/fixtures/pages/nested-components.html +19 -0
  34. package/tests/fixtures/templates/components/author.html +24 -0
  35. package/tests/fixtures/templates/components/badge-icon.html +5 -0
  36. package/tests/fixtures/templates/components/badge.html +5 -0
  37. package/tests/fixtures/templates/components/code-highlight.html +60 -0
  38. package/tests/fixtures/templates/components/code.html +203 -0
  39. package/tests/fixtures/templates/components/head.html +15 -0
  40. package/tests/fixtures/templates/components/header.html +7 -0
  41. package/tests/fixtures/templates/components/names.html +16 -0
  42. package/tests/fixtures/templates/components/title.html +3 -0
  43. package/tests/fixtures/templates/layouts/basic.html +7 -0
  44. package/types/index.js +36 -4
  45. package/eslint.config.js +0 -117
  46. package/jsconfig.json +0 -8
package/README.md CHANGED
@@ -4,7 +4,7 @@ coralite is a static site generator library built around the emerging [HTML modu
4
4
 
5
5
  <p style="text-align:center;">
6
6
  <a href="https://youtu.be/wUWwH9QZUTs" target="_blank">
7
- <img src="https://codeberg.org/tjdavid/coralite/media/branch/main/docs/images/intro.gif" alt="How to build a website using Coralite" style="max-width: 100%; width: auto;filter: drop-shadow(rgba(0,0,0,0.2) 0px 0px 0.75rem)">
7
+ <img src="https://codeberg.org/tjdavid/coralite/media/branch/main/packages/coralite/docs/images/intro.gif" alt="How to build a website using Coralite" style="max-width: 100%; width: auto;filter: drop-shadow(rgba(0,0,0,0.2) 0px 0px 0.75rem)">
8
8
  </a>
9
9
  <div>Watch the full video on <a href="https://youtu.be/wUWwH9QZUTs" target="_blank">how to build a website using Coralite.</a></div>
10
10
  </p>
package/dist/about.html ADDED
@@ -0,0 +1,20 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta name="title" content="About">
5
+ <title>About</title>
6
+ </head>
7
+ <body>
8
+
9
+ <div>
10
+ <h1>Title</h1>
11
+
12
+
13
+
14
+ test
15
+
16
+ <footer>Footer</footer>
17
+ </div>
18
+
19
+ </body>
20
+ </html>
package/dist/cast.html ADDED
@@ -0,0 +1,13 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>Nemo Cast</title>
7
+ </head>
8
+ <body>
9
+
10
+ Nemo,Squirt,Dory,Crush
11
+
12
+ </body>
13
+ </html>
package/dist/code.html ADDED
@@ -0,0 +1,42 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta name="title" content="code">
5
+ <title>Code</title>
6
+ </head>
7
+ <body>
8
+
9
+ <div class="code">
10
+ <div class="code-toolbar">
11
+ <span class="code-language">javascript</span>
12
+ <button popovertarget="copy-8ea8555fbb7f2" type="button" class="button button-icon" onclick="navigator.clipboard.writeText(this.parentElement.parentElement.children[1].children[0].textContent)">
13
+ Copy to clipboard
14
+ </button>
15
+ <div id="copy-8ea8555fbb7f2" popover>Code copied!</div>
16
+ </div>
17
+ <pre class="code-body"><code>
18
+ <span class="hljs-keyword">const</span> hello = <span class="hljs-string">&apos;world&apos;</span>
19
+ </code></pre>
20
+ </div>
21
+
22
+
23
+
24
+ <div class="code">
25
+ <div class="code-toolbar">
26
+ <span class="code-language">HTML</span>
27
+ <button popovertarget="copy-6c12813491646" type="button" class="button button-icon" onclick="navigator.clipboard.writeText(this.parentElement.parentElement.children[1].children[0].textContent)">
28
+ Copy to clipboard
29
+ </button>
30
+ <div id="copy-6c12813491646" popover>Code copied!</div>
31
+ </div>
32
+ <pre class="code-body"><code><span class="code-token html-tag"><span class="code-token html-tag-text">&lt;</span><span class="code-token html-tag-name">div</span><span class="code-token html-tag-text">&gt;</span></span>
33
+ <span class="code-token html-comment"><span class="code-token html-comment">&lt;!--</span><span class="code-token html-comment">
34
+ Multiline
35
+ Comments
36
+ </span><span class="code-token html-comment">--&gt;</span></span>
37
+ <span class="code-token html-tag"><span class="code-token html-tag-text">&lt;</span><span class="code-token html-tag-name">h1</span><span class="code-token html-tag-text">&gt;</span></span>code<span class="code-token html-tag-text">&lt;/</span><span class="code-token html-tag-name">h1</span><span class="code-token html-tag-text">&gt;</span>
38
+ <span class="code-token html-tag-text">&lt;/</span><span class="code-token html-tag-name">div</span><span class="code-token html-tag-text">&gt;</span></code></pre>
39
+ </div>
40
+
41
+ </body>
42
+ </html>
package/dist/index.html ADDED
@@ -0,0 +1,24 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+
7
+ <title>Home page</title>
8
+ </head>
9
+ <body>
10
+ Hello
11
+
12
+
13
+ <header>
14
+ This is the mighty header
15
+
16
+
17
+ </header>
18
+
19
+
20
+ world
21
+
22
+
23
+ </body>
24
+ </html>
package/dist/nested-components.html ADDED
@@ -0,0 +1,54 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+
7
+ <title>Home page</title>
8
+ </head>
9
+ <body>
10
+
11
+ <header>
12
+ This is the mighty header
13
+
14
+
15
+
16
+ <header>
17
+ This is the mighty header
18
+
19
+
20
+ </header>
21
+
22
+
23
+ </header>
24
+
25
+
26
+
27
+
28
+ <span class="badge">
29
+
30
+ <span class="icon icon--circle">circle</span>
31
+
32
+ </span>
33
+
34
+
35
+
36
+
37
+ <span class="badge">
38
+
39
+ <span class="icon icon--square">square</span>
40
+
41
+ </span>
42
+
43
+
44
+
45
+
46
+
47
+ <header>
48
+ This is the mighty header
49
+
50
+ <h1>Nested title</h1>
51
+ </header>
52
+
53
+ </body>
54
+ </html>
package/docs/basic-templating.md ADDED
@@ -0,0 +1,121 @@
1
+ # Getting Started: Basic templating
2
+
3
+ This guide will walk you through creating your first page using Coralite, a static site generator built around HTML modules.
4
+
5
+ ## Project Structure
6
+
7
+ Create a new project directory with the following structure:
8
+
9
+ ```
10
+ my-coralite-site/
11
+ ├── src/
12
+ │ ├── templates/
13
+ │ │ ├── header.html
14
+ │ │ └── footer.html
15
+ │ └── pages/
16
+ │ └── index.html
17
+ └── dist/
18
+ ```
19
+
20
+ ## Creating Templates
21
+
22
+ Before creating the template files, there are few things to take note of:
23
+
24
+ 1. Every template must have an `id` attribute that matches its usage in pages:
25
+ ```html
26
+ <template id="coralite-header">
27
+ ```
28
+
29
+ 2. Custom element names in pages must match template IDs:
30
+ ```html
31
+ <coralite-header title="My Title">
32
+ ```
33
+
34
+ 3. Data can be passed via attributes and accessed using double curly bracket syntax:
35
+ ```html
36
+ <!-- In your page -->
37
+ <coralite-header title="Hello World">
38
+
39
+ <!-- In your template -->
40
+ <h1>{{ title }}</h1>
41
+ ```
42
+
43
+ 4. Templates can pass nested elements via `slots`
44
+
45
+ Let's create two basic templates:
46
+
47
+ ### 1. Header Template (src/templates/header.html)
48
+
49
+ ```html
50
+ <template id="coralite-header">
51
+ <h1>{{ title }}</h1>
52
+ <slot name="subtitle"></slot>
53
+ <slot></slot>
54
+ </template>
55
+ ```
56
+
57
+ ### 2. Footer Template (src/templates/footer.html)
58
+
59
+ ```html
60
+ <template id="coralite-footer">
61
+ <footer>
62
+ Just keep swimming.
63
+ </footer>
64
+ </template>
65
+ ```
66
+
67
+ ## Building Your First Page
68
+
69
+ Create your main page in `src/pages/index.html`:
70
+
71
+ ```html
72
+ <!DOCTYPE html>
73
+ <html lang="en">
74
+ <head>
75
+ <meta charset="UTF-8">
76
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
77
+ <title>My First Coralite Page</title>
78
+ </head>
79
+ <body>
80
+ <coralite-header title="Welcome to My Site">
81
+ <span slot="subtitle">A Coralite Creation</span>
82
+ <p>This is my first page built with Coralite!</p>
83
+ </coralite-header>
84
+
85
+ <coralite-footer></coralite-footer>
86
+ </body>
87
+ </html>
88
+ ```
89
+
90
+ ## Building Your Site
91
+
92
+ Generate your site using the Coralite CLI:
93
+
94
+ ```bash
95
+ coralite --templates path/to/templates --pages path/to/pages --output dist
96
+ ```
97
+
98
+ To preview changes without generating files, use the dry-run mode:
99
+
100
+ ```bash
101
+ coralite --templates path/to/templates --pages path/to/pages --output dist --dry-run
102
+ ```
103
+
104
+ ## Next Steps
105
+
106
+ - Try creating more complex templates with multiple slots
107
+ - Explore nested components by using one component inside another
108
+ - Use the dry-run mode to debug template issues
109
+ - Check the [full documentation](https://codeberg.org/tjdavid/coralite/src/branch/main/docs) for advanced features
110
+
111
+ ## Common Issues
112
+
113
+ 1. If your templates aren't rendering, ensure:
114
+ - Template IDs match the component names in your pages
115
+ - All required attributes are provided
116
+ - The Node.js `--experimental-vm-modules` and `--experimental-import-meta-resolve` flag is enabled
117
+
118
+ 2. Missing content might indicate:
119
+ - Incorrect slot names
120
+ - Missing slot definitions in templates
121
+ - Malformed template syntax
package/docs/coralite-cli.md ADDED
@@ -0,0 +1,68 @@
1
+ # Coralite CLI
2
+
3
+ This technical documentation provides an in-depth overview of the Coralite CLI, its command-line options, and usage examples.
4
+
5
+ ## Installation
6
+
7
+ Before using the Coralite CLI, ensure you have Node.js installed on your system. Then, install Coralite globally via npm:
8
+
9
+ ```bash
10
+ npm install -g coralite
11
+ ```
12
+
13
+ ## Command Structure
14
+
15
+ The basic command structure for the Coralite CLI is as follows:
16
+
17
+ ```bash
18
+ coralite [options]
19
+ ```
20
+
21
+ ## Options
22
+
23
+ The Coralite CLI accepts several options to configure its behavior. Here's a detailed list of available options:
24
+
25
+ - **`-t, --templates <path>`** (required)
26
+ - Description: The file system path to the directory containing Coralite templates.
27
+ - Example: `--templates ./path/to/templates`
28
+
29
+ - **`-p, --pages <path>`** (required)
30
+ - Description: The file system path to the directory containing pages that will be rendered using the provided templates.
31
+ - Example: `--pages ./path/to/pages`
32
+
33
+ - **`-o, --output <path>`** (required)
34
+ - Description: The output directory for the generated site. If the specified directory does not exist, it will be created.
35
+ - Example: `--output ./dist`
36
+
37
+ - **`-i, --ignore-attribute <key=value...>`** (optional)
38
+ - Description: Ignore elements by attribute name-value pair during parsing. Multiple pairs can be provided separated by spaces.
39
+ - Examples:
40
+ - Ignore `<div data-ignore="true">` elements: `--ignore-attribute data-ignore=true`
41
+ - Ignore multiple elements: `--ignore-attribute data-ignore=true class=test-only`
42
+
43
+ - **`-d, --dry-run`** (optional)
44
+ - Description: Run the CLI in dry-run mode. This displays information about generated documents and their content without actually writing files to the output directory.
45
+ - Example: `coralite -t ./path/to/templates -p ./path/to/pages -o ./dist --dry-run`
46
+
47
+ ## Examples
48
+
49
+ 1. **Generate a site with default options:**
50
+
51
+ ```bash
52
+ coralite -t path/to/templates -p path/to/pages -o dist
53
+ ```
54
+
55
+ 2. **Ignore specific elements during parsing and run in dry-run mode:**
56
+
57
+ ```bash
58
+ coralite -t path/to/templates -p path/to/pages -o dist --ignore-attribute data-ignore=true --dry-run
59
+ ```
60
+
61
+ ## Technical Details
62
+
63
+ Under the hood, the Coralite CLI does the following:
64
+
65
+ 1. Parses command-line options using the `commander` library.
66
+ 2. Validates and processes provided options (e.g., splits ignore attribute key-value pairs).
67
+ 3. Calls the core `coralite` function with the parsed options.
68
+ 4. Based on the `--dry-run` option, either displays generated document information or writes rendered HTML files to the specified output directory.
package/docs/coralite.md ADDED
@@ -0,0 +1,130 @@
1
+ # Coralite library documentation
2
+
3
+ Coralite is designed to work with a structured project layout containing `templates` (reusable components) and `pages` (content to be rendered). Below are typical directory structures and file examples that illustrate how Coralite processes HTML files.
4
+
5
+ ---
6
+
7
+ ## 📁 Project Structure Example
8
+
9
+ A basic Coralite project might look like this:
10
+
11
+ ```
12
+ my-coralite-project/
13
+ │
14
+ ├── src/
15
+ │ ├── templates/ // ✅ Templates used for rendering
16
+ │ │ ├── header.html // Reusable template component
17
+ │ │ └── layout.html // Base layout template
18
+ │ │
19
+ │ └── pages/ // ✅ Pages to be rendered using templates
20
+ │ ├── index.html // Main page with dynamic content
21
+ │ └── about.html // Another page that uses templates
22
+ │
23
+ ├── assets/ // 📁 Optional: static files (CSS, images)
24
+ │ └── styles.css // CSS file referenced by pages or templates
25
+ │
26
+ └── package.json // Project metadata and dependencies
27
+ ```
28
+
29
+ ---
30
+
31
+ ## 📄 Template File Example (`src/templates/header.html`)
32
+
33
+ ```html
34
+ <!-- header.html - A reusable template component -->
35
+ <template id="coralite-header">
36
+ <header>
37
+ <h1>{{ title }}</h1> <!-- Dynamic token placeholder -->
38
+ <nav>
39
+ <ul>
40
+ <li><a href="/">Home</a></li>
41
+ <li><a href="/about">About</a></li>
42
+ </ul>
43
+ </nav>
44
+ </header>
45
+ </template>
46
+ ```
47
+
48
+ This template defines a reusable header component with a dynamic `{{ title }}` token that will be replaced during rendering.
49
+
50
+ ---
51
+
52
+ ## 📄 Page File Example (`src/pages/index.html`)
53
+
54
+ ```html
55
+ <!-- index.html - A page to be rendered using templates -->
56
+ <!DOCTYPE html>
57
+ <html lang="en">
58
+ <head>
59
+ <title>Homepage</title>
60
+ </head>
61
+ <article data-page="home">
62
+ <!-- Custom element - the attributes will be available as tokens in the template -->
63
+ <coralite-module title="Hello world"></coralite-module>
64
+
65
+ <section>
66
+ <h2>Welcome</h2>
67
+ <p>This is the homepage content.</p>
68
+ </section>
69
+ </article>
70
+ </body>
71
+ </html>
72
+ ```
73
+
74
+ This page includes a `coralite-header` element that references the `header.html` template and defines its own content.
75
+
76
+ ---
77
+
78
+ ## 📌 Ignored Element Example
79
+
80
+ If you want to exclude certain elements during rendering, use the `ignoreByAttribute` option:
81
+
82
+ ```html
83
+ <!-- ignored-element.html -->
84
+ <div data-dev="true">This element will be ignored by Coralite.</div>
85
+ ```
86
+
87
+ Then include it in your configuration:
88
+
89
+ ```javascript
90
+ new Coralite({
91
+ templates: 'src/templates',
92
+ pages: 'src/pages',
93
+ ignoreByAttribute: [{
94
+ name: 'data-dev',
95
+ value: 'true'
96
+ }]
97
+ })
98
+ ```
99
+
100
+ ---
101
+
102
+ ## 📁 Recursive Template Example
103
+
104
+ Coralite can also process nested directories if enabled via the `recursive` option in advanced configurations. For example:
105
+
106
+ ```
107
+ src/
108
+ ├── templates/
109
+ │ └── components/
110
+ │ ├── button.html
111
+ │ └── card.html
112
+ └── pages/
113
+ └── blog/
114
+ └── post-1.html
115
+ ```
116
+
117
+ Coralite will process all HTML files in `templates` and `pages`, including subdirectories.
118
+
119
+ ---
120
+
121
+ ## Parameters Table
122
+
123
+ | **Name** | **Type** | **Description** | **Example** |
124
+ |--------------------|--------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|--------------------------------------------------|
125
+ | `templates` | String | Path to the directory containing Coralite templates. | `'path/to/templates'` |
126
+ | `pages` | String | Path to the directory containing pages that will be rendered using the provided templates. | `'path/to/pages'` |
127
+ | `plugins` | Array of plugin objects (optional, defaults to empty array) | Array of plugin modules for extending functionality. Each plugin must implement specific methods. | `[myPlugin]` |
128
+ | `ignoreByAttribute`| Array of attribute name-value pairs (optional) | Elements to ignore based on exact attribute name-value matches. | `[{ name: 'data-ignore', value: 'true' }]` |
129
+
130
+ ---
package/docs/images/intro.gif ADDED
Binary file
package/docs/images/logo.png ADDED
Binary file