npm - @ui-doc/html-renderer - Versions diffs - 0.4.0 → 1.0.0 - Mend

@ui-doc/html-renderer 0.4.0 → 1.0.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 (34) hide show

package/README.md +586 -151
package/dist/HtmlRenderer.d.ts +3 -3
package/dist/InlineReader.d.ts +1 -1
package/dist/Lexer.types.d.ts +5 -4
package/dist/NodeParser.d.ts +2 -2
package/dist/Parser.types.d.ts +6 -6
package/dist/Primitive.types.d.ts +1 -1
package/dist/Reader.types.d.ts +8 -6
package/dist/Renderer.types.d.ts +7 -7
package/dist/assets/services/expand.d.ts +4 -2
package/dist/assets/ui-doc.cjs +24 -13
package/dist/assets/ui-doc.cjs.map +1 -1
package/dist/assets/ui-doc.min.js +1 -1
package/dist/assets/ui-doc.mjs +24 -13
package/dist/assets/ui-doc.mjs.map +1 -1
package/dist/assets/utils/delay.d.ts +1 -1
package/dist/assets/utils/dom.d.ts +6 -3
package/dist/index.cjs +146 -114
package/dist/index.cjs.map +1 -1
package/dist/index.mjs +145 -114
package/dist/index.mjs.map +1 -1
package/dist/nodes/CommentNode.d.ts +2 -1
package/dist/nodes/TemplateNode.d.ts +2 -1
package/dist/nodes/index.d.ts +4 -2
package/dist/nodes/tags/for.d.ts +2 -2
package/dist/nodes/tags/if.d.ts +3 -3
package/dist/utils/index.d.ts +1 -1
package/package.json +32 -29
package/scripts/services/example.ts +3 -3
package/scripts/services/expand.ts +19 -12
package/scripts/services/sidebar.ts +4 -3
package/scripts/utils/delay.ts +2 -2
package/scripts/utils/dom.ts +9 -5
package/LICENSE.md +0 -9

package/README.md CHANGED Viewed

@@ -1,251 +1,686 @@
-# UI-Doc HTML Renderer
+# @ui-doc/html-renderer
-Simple and light HTML Rendering Engine. Its purpose is to create HTML from a Context Object by using a simple template syntax and have no dependencies. This project should not be used for complexer projects, because of it's simplicity.
+HTML renderer for UI-Doc that converts UI-Doc context objects into interactive HTML documentation pages. It implements the `Renderer` interface from `@ui-doc/core` and includes a built-in template engine with zero dependencies.
-## Tags
+## Overview
-Tags are used to get a bit of functionality into the html generation process.
+The HTML renderer provides:
-### var
+- **Template Engine** - A lightweight, dependency-free template system with custom syntax
+- **Built-in Templates** - Ready-to-use layouts, pages, and partials for documentation
+- **Asset Management** - Pre-built CSS and JavaScript for documentation styling
+- **Extensibility** - Custom templates and styling support
-Output value of a variable.
+## Installation
+```bash
+npm install @ui-doc/html-renderer @ui-doc/core
 ```
-<h1>{{var:title}}</h1>
+## Quick Start
+### Basic Usage
+```ts
+import { HtmlRenderer, NodeParser } from '@ui-doc/html-renderer'
+// Create a renderer instance
+const renderer = new HtmlRenderer(NodeParser.init())
+// Add templates
+renderer.addLayout('default', {
+  source: 'inline',
+  content: `
+    <html>
+      <head>
+        <title>{{var:title}}</title>
+      </head>
+      <body>
+        {{page:default}}
+      </body>
+    </html>
+  `,
+})
+renderer.addPage('default', {
+  source: 'inline',
+  content: `
+    <h1>{{var:title}}</h1>
+    <div>{{var:content}}</div>
+  `,
+})
+// Generate HTML from context
+const html = renderer.generate({
+  title: 'My Documentation',
+  page: {
+    title: 'Welcome',
+    content: '<p>Documentation content here</p>',
+  },
+  assets: [],
+})
 ```
-To escape the variable use `{{var:title escape}}`.
+### Integration with UI-Doc
-### if
+```ts
+import { UIDoc } from '@ui-doc/core'
+import { HtmlRenderer, NodeParser, TemplateLoader } from '@ui-doc/html-renderer'
+import { NodeFileSystem } from '@ui-doc/node'
-Use a if condition to decide when our when not to render something. Please not that currently there is no `else` or `ifelse`
+const fileSystem = new NodeFileSystem()
+const renderer = new HtmlRenderer(NodeParser.init())
-```
-{{if:show}}
-<p>Show this if show inside the context is a true statement</p>
-{{/if}}
-```
+// Load built-in templates
+const templatePath = await fileSystem.assetLoader().packagePath(
+  TemplateLoader.TEMPLATES_PACKAGE,
+)
+await TemplateLoader.load({ renderer, fileSystem, templatePath })
+// Create UI-Doc instance
+const uidoc = new UIDoc({ renderer })
-#### Conditions
+// Process source files
+uidoc.sourceCreate('path/to/source.css', await fileSystem.fileRead('path/to/source.css'))
-You can use conditions
+// Output documentation
+await uidoc.output(async (file, content) => {
+  await fileSystem.fileWrite(`./dist/${file}`, content)
+})
+// Copy required assets
+const assetLoader = fileSystem.assetLoader()
+await assetLoader.copy('@ui-doc/html-renderer/ui-doc.min.css', './dist/ui-doc.css')
+await assetLoader.copy('@ui-doc/html-renderer/ui-doc.min.js', './dist/ui-doc.js')
 ```
-{{if:title === "foo"}}
-{{if:show === true}}
-{{if:page.number === 3}}
+## Template Syntax
+The template engine uses double curly braces `{{...}}` for directives.
+### Variables
+Output values from the context:
+```html
+<h1>{{var:title}}</h1>
+<p>{{var:description}}</p>
+<!-- Access nested properties with dot notation -->
+<div>{{var:page.content}}</div>
+<!-- Escape HTML output -->
+<div>{{var:userInput escape}}</div>
 ```
-**Operators:**
+### Conditionals
-- `===`
-- `==`
-- `!==`
-- `!=`
-- `<`
-- `<=`
-- `>`
-- `>=`
+Render content conditionally:
-### for
+```html
+{{if:showContent}}
+  <p>This is visible when showContent is truthy</p>
+{{/if}}
+```
-Use for to loop over objects and arrays. Please not that a loop will change the context to help you access inside your loop target and give you loop specific context like index and object keys.
+Supported comparison operators: `===`, `==`, `!==`, `!=`, `<`, `<=`, `>`, `>=`
-#### array loop
+```html
+{{if:status === "active"}}
+  <span>Active</span>
+{{/if}}
+{{if:count > 5}}
+  <span>More than 5 items</span>
+{{/if}}
 ```
-<!-- context: {"list": ["foo", "bar", "baz"]} -->
+### Loops
+#### Array Loops
+```html
+<!-- Context: {"items": ["apple", "banana", "cherry"]} -->
 <ul>
-  {{for:list}}
-  <li>{{var:_loop.value}}, index: {{var:_loop.index}}</li>
+  {{for:items}}
+    <li>{{var:_loop.value}} (index: {{var:_loop.index}})</li>
   {{/for}}
 </ul>
 <!-- Output: -->
 <ul>
-  <li>foo, index: 0</li>
-  <li>bar, index: 1</li>
-  <li>baz, index: 2</li>
+  <li>apple (index: 0)</li>
+  <li>banana (index: 1)</li>
+  <li>cherry (index: 2)</li>
 </ul>
 ```
-#### object loop
+#### Object Loops
-```
-<!-- context: {"list": {"foo": "FOO", "bar": "BAR", "baz": "BAZ"}} -->
+```html
+<!-- Context: {"colors": {"red": "#f00", "green": "#0f0", "blue": "#00f"}} -->
 <ul>
-  {{for:list}}
-  <li>{{var:_loop.value}}, key: {{var:_loop.key}}, index: {{var:_loop.index}}</li>
+  {{for:colors}}
+    <li>{{var:_loop.key}}: {{var:_loop.value}}</li>
   {{/for}}
 </ul>
 <!-- Output: -->
 <ul>
-  <li>FOO, key: foo, index: 0</li>
-  <li>BAR, key: bar, index: 1</li>
-  <li>BAZ, key: baz, index: 2</li>
+  <li>red: #f00</li>
+  <li>green: #0f0</li>
+  <li>blue: #00f</li>
 </ul>
 ```
-#### loop items as objects
+#### Looping Over Object Arrays
-You can loop over an array or object of objects. The object items will directly be accessible inside the for context.
+```html
+<!-- Context: {"sections": [{"title": "Intro", "content": "..."}, {"title": "Details", "content": "..."}]} -->
+{{for:sections}}
+  <section>
+    <h2>{{var:title}}</h2>
+    <div>{{var:content}}</div>
+  </section>
+{{/for}}
+```
+Loop variables available in `_loop`:
+- `_loop.value` - Current item value
+- `_loop.index` - Current iteration index (0-based)
+- `_loop.key` - Current key (for object loops)
+### Pages
+Render registered page templates with optional context switching:
+```html
+<!-- Use the default page template -->
+{{page}}
+<!-- Use a specific page template -->
+{{page:default}}
+<!-- Use a page template with different context -->
+{{page:default page}}
 ```
-<!-- context: {"sections": [{"title": "Section 1", content: "<p>Section 1 content</p>"}, {"title": "Section 2", content: "<p>Section 2 content</p>"}]} -->
-{{for:sections}}
-<section>
-  <h2>{{var::title}}</h2>
-  {{var:content}}
-</section>
-{{/for}}
+### Partials
-<!-- Output: -->
-<section>
-  <h2>Section 1</h2>
-  <p>Section 1 content</p>
-</section>
-<section>
-  <h2>Section 2</h2>
-  <p>Section 2 content</p>
-</section>
+Include reusable template fragments:
+```html
+<!-- Include a partial -->
+{{partial:nav-main}}
+<!-- Include a partial with different context -->
+{{partial:section currentSection}}
 ```
-### page
+### Debug
+Output context as JSON for debugging:
-Use page to output registered page templates (see Templates > Page). `{{page:foo}}` this will try to render the `foo` page. If no page with this name is registered the system will fallback to the `default` page. If you want to use the default page you can also just use `{{page}}`. As second parameter you can give a context if you like to change the context `{{page:layout newContext}}`.
+```html
+<!-- Output entire context -->
+{{debug}}
+<!-- Output specific context property -->
+{{debug:page}}
 ```
-<!-- context: {"title": "Document Title", "page": {"title": "Page title", "content": "Page content"}} -->
-<html>
-<head>
-  <title>{{var:title}}</title>
-</head>
-<body>
-  <!-- using default layout with new context `page` -->
-  {{page:default page}}
-</body>
-</html>
+## Template Types
-<!-- default page template with change context -->
-<!-- context: {"title": "Page title", "content": "Page content"} -->
+### Layouts
-<main>
-  <h1>{{var:title}}</h1>
-  <p>{{var:content}}</p>
-</main>
+Define the overall HTML structure. A layout typically includes the `<html>`, `<head>`, and `<body>` tags.
+```ts
+renderer.addLayout('default', {
+  source: 'my-layout.html',
+  content: `
+    <!doctype html>
+    <html lang="en">
+      <head>
+        <meta charset="utf-8" />
+        <title>{{var:title}}</title>
+        {{var:styles}}
+      </head>
+      <body>
+        {{page:default}}
+        {{var:scripts}}
+      </body>
+    </html>
+  `,
+})
+```
-<!-- Output: -->
-<html>
-<head>
-  <title>Document Title</title>
-</head>
-<body>
-<main>
-  <h1>Page title</h1>
-  <p>Page content</p>
-</main>
-</body>
-</html>
+### Pages
+Define page-specific content structures:
+```ts
+renderer.addPage('default', {
+  source: 'my-page.html',
+  content: `
+    <header>
+      <h1>{{var:title}}</h1>
+      {{if:description}}
+        <p>{{var:description}}</p>
+      {{/if}}
+    </header>
+    <main>
+      {{for:sections}}
+        {{partial:section}}
+      {{/for}}
+    </main>
+  `,
+})
+```
+### Partials
+Create reusable template components:
+```ts
+renderer.addPartial('section', {
+  source: 'section.html',
+  content: `
+    <section id="{{var:id}}">
+      <h2>{{var:title}}</h2>
+      <div>{{var:content}}</div>
+    </section>
+  `,
+})
 ```
-### partial
+## Loading Templates
+### From Files
+Use `TemplateLoader` to load templates from the file system:
+```ts
+import { TemplateLoader } from '@ui-doc/html-renderer'
+import { NodeFileSystem } from '@ui-doc/node'
+const fileSystem = new NodeFileSystem()
-Use partial to render registered partial templates (see Templates > Partial). If the given partial name was not found nothing will be generated
+// Load templates from a directory
+await TemplateLoader.load({
+  renderer,
+  fileSystem,
+  templatePath: './my-templates',
+})
+```
+The loader expects this directory structure:
+```text
+my-templates/
+  layouts/
+    default.html
+    custom.html
+  pages/
+    default.html
+    index.html
+  partials/
+    nav.html
+    section.html
 ```
-{{partial:foo}} > output foo partial
+### Using Built-in Templates
+The package includes ready-to-use templates:
+```ts
+const templatePath = await fileSystem.assetLoader().packagePath(
+  TemplateLoader.TEMPLATES_PACKAGE,
+)
+await TemplateLoader.load({ renderer, fileSystem, templatePath })
 ```
-As second parameter you can give a context definition to change the context
+## Built-in Assets
+The package provides pre-built CSS and JavaScript for documentation styling.
+### CSS
+```bash
+# Full CSS
+@ui-doc/html-renderer/ui-doc.css
+# Minified CSS
+@ui-doc/html-renderer/ui-doc.min.css
 ```
-{{partial:foo bar}} > output foo partial using bar of the current context as new context
+### JavaScript
+```bash
+# Full JavaScript
+@ui-doc/html-renderer/ui-doc.js
+# Minified JavaScript (for use in browsers)
+@ui-doc/html-renderer/ui-doc.min.js
 ```
-### debug
+### Copying Assets
-Use debug to output the current context or parts of the context. The context will be outputted as JSON.
+```ts
+const assetLoader = fileSystem.assetLoader()
+await assetLoader.copy(
+  '@ui-doc/html-renderer/ui-doc.min.css',
+  './dist/ui-doc.css',
+)
+await assetLoader.copy(
+  '@ui-doc/html-renderer/ui-doc.min.js',
+  './dist/ui-doc.js',
+)
 ```
-<!-- context: {"title": "Document Title", "page": {"title": "Page title", "content": "Page content"}} -->
-{{debug}}
-<!-- Output: -->
-{"title": "Document Title", "page": {"title": "Page title", "content": "Page content"}}
+### Syntax Highlighting
-{{debug:page}}
-<!-- Output: -->
-{"title": "Page title", "content": "Page content"}
+The built-in templates use highlight.js for code syntax highlighting. Include it in your output:
+```ts
+await assetLoader.copy(
+  '@highlightjs/cdn-assets/styles/default.min.css',
+  './dist/highlight.css',
+)
+await assetLoader.copy(
+  '@highlightjs/cdn-assets/highlight.min.js',
+  './dist/highlight.js',
+)
 ```
-## Templates
+## API Reference
-You can register different template parts to the renderer these templates can then be reused wile generation.
+### HtmlRenderer
-### Layouts
+The main renderer class implementing the `Renderer` interface.
+#### Constructor
+```text
+new HtmlRenderer(parser: Parser)
+```
+- `parser` - A `Parser` instance (typically `NodeParser.init()`)
+#### Methods
-Define the HTML basic structure.
+##### addLayout(name, layout)
-### Page
+Register a layout template.
-Define a page specific template. You can use the `{{page:your-page-template-name}}` tag to render a specific page template. Page templates are not necessary but they help to keep layouts smaller and easier to read.
+```text
+renderer.addLayout(name: string, layout: SourceInput): HtmlRenderer
+```
+- `name` - Unique identifier for the layout
+- `layout` - Template source (object with `source` and `content` properties, or a `Reader` instance)
+- Returns the renderer instance for chaining
+##### addPage(name, page)
+Register a page template.
+```text
+renderer.addPage(name: string, page: SourceInput): HtmlRenderer
+```
+- `name` - Unique identifier for the page
+- `page` - Template source
+- Returns the renderer instance for chaining
+##### addPartial(name, partial)
+Register a partial template.
+```text
+renderer.addPartial(name: string, partial: SourceInput): HtmlRenderer
+```
+- `name` - Unique identifier for the partial
+- `partial` - Template source
+- Returns the renderer instance for chaining
+##### generate(context, layout?)
+Generate HTML from a context object.
+```text
+renderer.generate(context: GenerateContext, layout?: string): string
+```
+- `context` - The UI-Doc context object to render
+- `layout` - Optional layout name (defaults to `'default'`)
+- Returns the generated HTML string
+The `GenerateContext` includes:
+- `title` - Document title
+- `page` - Page context object
+- `assets` - Array of asset objects with `type`, `src`, and optional `attrs`
+- Additional properties from your UI-Doc configuration
+##### page(name, context)
+Render a specific page template with context.
+```text
+renderer.page(name: string, context: RenderContext): string
+```
+- `name` - Page template name (falls back to `'default'` if not found)
+- `context` - Context object for rendering
+- Returns the rendered HTML string
+##### partial(name, context?)
+Render a specific partial template with optional context.
+```text
+renderer.partial(name: string, context?: RenderContext): string
+```
+- `name` - Partial template name (falls back to `'default'` if not found)
+- `context` - Optional context object (defaults to empty object)
+- Returns the rendered HTML string
+### NodeParser
+Parser for the template syntax.
+#### Static Methods
+##### init()
+Create and initialize a parser with all built-in tags.
+```text
+NodeParser.init(): NodeParser
+```
+Returns a configured `NodeParser` instance.
+#### Methods
+##### registerTagParser(tag)
+Register a custom tag parser.
+```text
+parser.registerTagParser(tag: TagNodeParse): NodeParser
+```
-### Partial
+- `tag` - Tag parser definition
+- Returns the parser instance for chaining
-Define a partial that can be reused, to get the same output inside layouts, pages and even in other partials. You can use the `{{partial:your-partial-name}}` tag to render the partial.
+### TemplateLoader
-## Usage
+Utility for loading templates from the file system.
+#### Static Properties
+##### TEMPLATES_PACKAGE
+```text
+static readonly TEMPLATES_PACKAGE: string
 ```
-import { HtmlRenderer } from '@ui-doc/html-renderer'
-const layout = `
-<html>
+Package identifier for built-in templates: `'@ui-doc/html-renderer/templates'`
+#### Static Methods
+##### load(options)
+Load templates from a directory.
+```text
+static async load(options: {
+  renderer: HtmlRenderer
+  fileSystem: FileSystem
+  templatePath: string
+}): Promise<void>
+```
+- `options.renderer` - The renderer to load templates into
+- `options.fileSystem` - File system instance (typically `NodeFileSystem`)
+- `options.templatePath` - Path to the templates directory
+## Error Handling
+The renderer throws specific errors for better debugging:
+### HTMLRendererError
+Thrown when a required template is not found.
+```ts
+try {
+  renderer.generate(context, 'nonexistent-layout')
+} catch (error) {
+  if (error instanceof HTMLRendererError) {
+    console.error(`Template error: ${error.message}`)
+  }
+}
+```
+### HTMLRendererSyntaxError
+Thrown when template syntax is invalid.
+```ts
+import { HTMLRendererSyntaxError } from '@ui-doc/html-renderer'
+try {
+  renderer.addLayout('bad', {
+    source: 'inline',
+    content: '{{invalid:syntax',
+  })
+} catch (error) {
+  if (error instanceof HTMLRendererSyntaxError) {
+    console.error(`Syntax error at line ${error.line}, column ${error.column}`)
+    console.error(error.message)
+  }
+}
+```
+Properties:
+- `message` - Error description
+- `source` - Source identifier
+- `line` - Line number where error occurred
+- `column` - Column number where error occurred
+- `code` - The problematic code snippet
+## Custom Templates
+You can create custom templates to match your design requirements.
+### Example Custom Layout
+```html
+<!doctype html>
+<html lang="en">
   <head>
-    <meta charset="utf-8">
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>{{var:title}}</title>
+    {{var:styles}}
+    <link rel="stylesheet" href="custom-styles.css" />
   </head>
-  <body>
-    {{page:default}}
-  </body>
-</html>`
+  <body class="custom-theme">
+    <header class="site-header">
+      <nav>{{partial:main-nav}}</nav>
+    </header>
-const page = `
-<h1>{{var:title}}</h1>
+    <main class="site-content">
+      {{page:page.id page}}
+    </main>
-{{if:excerpt}}
-<div>{{var:excerpt}}</div>
-{{/if}}
+    <footer class="site-footer">
+      <p>&copy; 2024 {{var:name}}</p>
+    </footer>
-{{for:sections}}
-{{partial:section}}
-{{/for}}`
+    {{var:scripts}}
+    <script src="custom-scripts.js"></script>
+  </body>
+</html>
+```
-const section = `
-<h2>{{var:title}}</h2>
+### Example Custom Page
+```html
+<article class="documentation-page">
+  <header class="page-header">
+    <h1>{{var:title}}</h1>
+    {{if:description}}
+      <div class="page-description">{{var:description}}</div>
+    {{/if}}
+  </header>
+  {{if:sections}}
+    <div class="page-sections">
+      {{for:sections}}
+        {{partial:custom-section}}
+      {{/for}}
+    </div>
+  {{/if}}
+</article>
+```
-{{var:content}}
-`
+## Integration with Build Tools
-const renderer = new HtmlRenderer()
+While you can use the HTML renderer directly, it's typically used through build tool plugins:
-renderer.addLayout('default', layout)
-renderer.addPage('default', page)
-renderer.addPartial('section', section)
+- **Rollup** - Use [`@ui-doc/rollup`](../rollup/README.md)
+- **Vite** - Use [`@ui-doc/vite`](../vite/README.md)
-renderer.generate({
-  title: 'Example',
-  page: {
-    title: 'Example Page Title',
-    sections: [
-      {; content: "<p>Section 1 content</p>" },
-      {; title: "Section 2"; content: "<p>Section 2 content</p>" },
-    ],
-  },
-})
+These plugins handle template loading, asset copying, and file watching automatically.
+## TypeScript Support
+The package includes full TypeScript definitions. All exported types are available for import:
+```ts
+import type {
+  Parser,
+  RenderContext,
+  Renderer,
+  SourceInput,
+  TagNodeParse,
+} from '@ui-doc/html-renderer'
 ```
+## Requirements
+- Node.js >= 16.0.0
+- `@ui-doc/core` (peer dependency)
+## License
+See [LICENSE.md](../../LICENSE.md) for license information.