pict-section-content 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Steven Velozo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# Pict Section Content
+
+A reusable content rendering section for the Pict ecosystem. Parses markdown to HTML with support for fenced code blocks, Mermaid diagrams, KaTeX math equations, GFM tables, and more. Provides a styled content view with post-render hooks for Mermaid and KaTeX integration.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Features
+
+- **Markdown Parsing** -- Headings, paragraphs, lists, blockquotes, horizontal rules, fenced code blocks (with nested fence support), GFM tables, and inline formatting
+- **Mermaid Diagrams** -- Code blocks tagged `mermaid` render as diagrams when the Mermaid library is present
+- **KaTeX Math** -- Inline (`$...$`) and display (`$$...$$`) math equations render when KaTeX is loaded
+- **Link Resolver** -- Pluggable callback for custom link resolution, enabling consumers to map links to application-specific routes
+- **Content View** -- Styled view with CSS for all rendered elements, post-render hooks for Mermaid and KaTeX, and a loading indicator
+- **Extensible** -- Extend the view class to use custom container IDs, override styling, or add post-render behavior
+- **Service Provider Pattern** -- Both the provider and view register with a Pict instance via dependency injection
+
+## Installation
+
+```bash
+npm install pict-section-content
+```
+
+## Quick Start
+
+### Parsing Markdown (Provider)
+
+```javascript
+const libPict = require('pict');
+const libPictSectionContent = require('pict-section-content');
+const PictContentProvider = libPictSectionContent.PictContentProvider;
+
+let tmpPict = new libPict();
+let tmpProvider = tmpPict.addProvider('Content',
+	PictContentProvider.default_configuration, PictContentProvider);
+
+let tmpHTML = tmpProvider.parseMarkdown('# Hello World\n\nThis is **bold** text.');
+// <h1 id="hello-world">Hello World</h1>
+// <p>This is <strong>bold</strong> text.</p>
+```
+
+### Displaying Content (View)
+
+```javascript
+const libPictSectionContent = require('pict-section-content');
+
+// Register the view with your Pict application
+let tmpView = tmpPict.addView('Content',
+	libPictSectionContent.default_configuration, libPictSectionContent);
+
+// Render the container, then display parsed HTML
+tmpView.render();
+tmpView.displayContent(tmpHTML);
+```
+
+### Custom Link Resolution
+
+```javascript
+let tmpResolver = (pHref, pLinkText) =>
+{
+	if (pHref.match(/\.md$/))
+	{
+		return { href: '#/page/' + pHref.replace(/\.md$/, '') };
+	}
+	return null; // fall back to default behavior
+};
+
+let tmpHTML = tmpProvider.parseMarkdown(markdown, tmpResolver);
+```
+
+## Supported Markdown
+
+| Feature | Syntax |
+|---------|--------|
+| Headings | `# H1` through `###### H6` |
+| Bold | `**text**` or `__text__` |
+| Italic | `*text*` or `_text_` |
+| Inline code | `` `code` `` |
+| Links | `[text](url)` |
+| Images | `![alt](src)` |
+| Code blocks | ```` ``` ```` with optional language tag |
+| Mermaid | ```` ```mermaid ```` |
+| Tables | GFM pipe syntax |
+| Lists | `- item` or `1. item` |
+| Blockquotes | `> text` |
+| Horizontal rules | `---`, `***`, or `___` |
+| Inline math | `$equation$` |
+| Display math | `$$...$$` |
+
+## Module Exports
+
+```javascript
+const libPictSectionContent = require('pict-section-content');
+
+// Primary export: the content view class
+libPictSectionContent                  // PictContentView (extends pict-view)
+libPictSectionContent.default_configuration  // View configuration with CSS and templates
+
+// Named export: the content provider class
+libPictSectionContent.PictContentProvider                  // PictContentProvider (extends pict-provider)
+libPictSectionContent.PictContentProvider.default_configuration  // Provider configuration
+```
+
+## External Dependencies
+
+For full rendering, load these libraries in the browser:
+
+- **Mermaid** -- Renders diagram blocks (optional, detected at runtime)
+- **KaTeX** -- Renders math equations (optional, detected at runtime)
+
+Content renders without them; diagrams and equations appear as raw text.
+
+## Part of the Retold Framework
+
+- [pict](https://github.com/stevenvelozo/pict) -- UI framework
+- [pict-view](https://github.com/stevenvelozo/pict-view) -- View base class
+- [pict-provider](https://github.com/stevenvelozo/pict-provider) -- Provider base class
+- [pict-docuserve](https://github.com/stevenvelozo/pict-docuserve) -- Documentation server (uses this module)
+- [fable](https://github.com/stevenvelozo/fable) -- Application services framework
+
+## Testing
+
+```bash
+npm test
+```
+
+```bash
+npm run coverage
+```
+
+## License
+
+MIT - See [LICENSE](LICENSE) for details.
+
+## Author
+
+Steven Velozo - [steven@velozo.com](mailto:steven@velozo.com)

package/docs/README.md

@@ -0,0 +1,130 @@
+# Pict Section Content
+
+A reusable content rendering section for the Pict ecosystem. Provides a markdown-to-HTML parser (the provider) and a styled content display view with post-render hooks for Mermaid diagrams and KaTeX math equations.
+
+## Quick Start
+
+```bash
+npm install pict-section-content
+```
+
+### Parsing Markdown
+
+The content provider parses markdown into HTML. Create a provider instance via Pict's `addProvider` method:
+
+```javascript
+const libPict = require('pict');
+const libPictSectionContent = require('pict-section-content');
+const PictContentProvider = libPictSectionContent.PictContentProvider;
+
+let tmpPict = new libPict();
+let tmpProvider = tmpPict.addProvider('Content',
+	PictContentProvider.default_configuration, PictContentProvider);
+
+let tmpHTML = tmpProvider.parseMarkdown('# Hello World\n\nThis is **bold** text.');
+```
+
+The parser handles headings, paragraphs, lists, blockquotes, horizontal rules, fenced code blocks (with nested fence support), GFM tables, Mermaid diagram blocks, KaTeX math (inline and display), and all standard inline formatting (bold, italic, code, links, images).
+
+### Displaying Content
+
+The content view renders parsed HTML into a styled container and triggers post-render hooks for Mermaid and KaTeX:
+
+```javascript
+const libPictSectionContent = require('pict-section-content');
+
+// Register the view
+let tmpView = tmpPict.addView('Content',
+	libPictSectionContent.default_configuration, libPictSectionContent);
+
+// Render the container, then display content
+tmpView.render();
+tmpView.displayContent(tmpHTML);
+```
+
+The view provides CSS for all rendered elements and automatically initializes Mermaid diagrams and KaTeX equations after content is assigned.
+
+### Custom Link Resolution
+
+By default, external links (`https://...`) open in a new tab with `rel="noopener"` and relative links render as-is. To customize link handling, pass a resolver callback:
+
+```javascript
+let tmpResolver = (pHref, pLinkText) =>
+{
+	// Convert .md links to hash routes
+	if (pHref.match(/\.md$/))
+	{
+		return { href: '#/page/' + pHref.replace(/\.md$/, '') };
+	}
+	// Return null to use default behavior
+	return null;
+};
+
+let tmpHTML = tmpProvider.parseMarkdown(markdown, tmpResolver);
+```
+
+See [Link Resolver](link-resolver.md) for the full pattern documentation.
+
+## Module Structure
+
+```
+pict-section-content/
+  source/
+    Pict-Section-Content.js         # Entry point
+    providers/
+      Pict-Provider-Content.js      # Markdown parser (extends pict-provider)
+    views/
+      Pict-View-Content.js          # Content display (extends pict-view)
+```
+
+The primary export is the view class. The provider is available as a named export:
+
+```javascript
+const PictContentView = require('pict-section-content');
+const PictContentProvider = require('pict-section-content').PictContentProvider;
+```
+
+## Supported Markdown
+
+### Block Elements
+
+| Feature | Syntax | Output |
+|---------|--------|--------|
+| Headings | `# H1` through `###### H6` | `<h1>` through `<h6>` with auto-generated `id` |
+| Paragraphs | Plain text | `<p>` |
+| Code blocks | ```` ``` ```` with optional language | `<pre><code class="language-...">` |
+| Mermaid | ```` ```mermaid ```` | `<pre class="mermaid">` |
+| Unordered lists | `- item` or `* item` | `<ul><li>` |
+| Ordered lists | `1. item` | `<ol><li>` |
+| Blockquotes | `> text` | `<blockquote>` (recursive) |
+| Tables | GFM pipe syntax | `<table>` with `<thead>` and `<tbody>` |
+| Horizontal rules | `---`, `***`, or `___` | `<hr>` |
+| Display math | `$$...$$` | `<div class="pict-content-katex-display">` |
+
+### Inline Elements
+
+| Feature | Syntax | Output |
+|---------|--------|--------|
+| Bold | `**text**` or `__text__` | `<strong>` |
+| Italic | `*text*` or `_text_` | `<em>` |
+| Inline code | `` `code` `` | `<code>` |
+| Links | `[text](url)` | `<a>` |
+| Images | `![alt](src)` | `<img>` |
+| Inline math | `$equation$` | `<span class="pict-content-katex-inline">` |
+
+## External Dependencies
+
+For full rendering in the browser, load these libraries:
+
+- **Mermaid** -- Renders `<pre class="mermaid">` elements into diagrams
+- **KaTeX** -- Renders `.pict-content-katex-inline` and `.pict-content-katex-display` elements
+
+Both are detected at runtime. Without them, content renders normally but diagrams and equations appear as raw text.
+
+## Learn More
+
+- [API Reference](api.md) -- Complete method and property documentation
+- [Link Resolver](link-resolver.md) -- Custom link resolution pattern
+- [Extending the View](extending.md) -- Using pict-section-content as a base class
+- [Pict View](/pict/pict-view/) -- View base class documentation
+- [Pict Provider](/pict/pict-provider/) -- Provider base class documentation

package/docs/_sidebar.md

@@ -0,0 +1,19 @@
+- Getting Started
+
+  - [Overview](README.md)
+  - [Link Resolver](link-resolver.md)
+  - [Extending the View](extending.md)
+
+- Reference
+
+  - [API Reference](api.md)
+
+- Retold Ecosystem
+
+  - [Pict](/pict/pict/)
+  - [Pict Application](/pict/pict-application/)
+  - [Pict View](/pict/pict-view/)
+  - [Pict Provider](/pict/pict-provider/)
+  - [Pict Docuserve](/pict/pict-docuserve/)
+  - [Fable](/fable/fable/)
+  - [Fable Service Base](/fable/fable-serviceproviderbase/)

package/docs/_topbar.md

@@ -0,0 +1,7 @@
+# Pict Section Content
+
+- [Overview](README.md)
+- [API Reference](api.md)
+- [Link Resolver](link-resolver.md)
+- [Extending](extending.md)
+- [GitHub](https://github.com/stevenvelozo/pict-section-content)

package/docs/api.md

@@ -0,0 +1,323 @@
+# API Reference
+
+## PictContentProvider
+
+Extends `pict-provider`. Service type: `'PictProvider'`.
+
+The content provider parses markdown into HTML. It handles block-level elements (headings, code blocks, lists, tables, blockquotes, math blocks) and inline elements (bold, italic, code, links, images, inline math).
+
+### Constructor
+
+```javascript
+new PictContentProvider(pFable, pOptions, pServiceHash)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pFable` | object | A Fable or Pict instance |
+| `pOptions` | object | Configuration options (merged with defaults) |
+| `pServiceHash` | string | Service identifier for the provider registry |
+
+### Default Configuration
+
+```javascript
+{
+	ProviderIdentifier: "Pict-Content",
+	AutoInitialize: true,
+	AutoInitializeOrdinal: 0
+}
+```
+
+---
+
+### parseMarkdown(pMarkdown, pLinkResolver)
+
+Parse a markdown string into HTML. Processes block-level elements line by line, delegating inline formatting to `parseInline`. The optional `pLinkResolver` callback is threaded through to inline parsing and into recursive calls (for blockquotes).
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pMarkdown` | string | The raw markdown text |
+| `pLinkResolver` | function | Optional link resolver callback (see [Link Resolver](link-resolver.md)) |
+
+**Returns:** `string` -- The parsed HTML
+
+**Block elements handled:**
+
+| Element | Detection | Output |
+|---------|-----------|--------|
+| Headings | `# ` through `###### ` | `<h1 id="...">` through `<h6 id="...">` |
+| Code blocks | ```` ``` ```` with optional language | `<pre><code class="language-...">` |
+| Mermaid blocks | ```` ```mermaid ```` | `<pre class="mermaid">` |
+| Unordered lists | `- `, `* `, `+ ` | `<ul><li>` |
+| Ordered lists | `1. ` | `<ol><li>` |
+| Blockquotes | `> ` | `<blockquote>` (recursive markdown parsing) |
+| Tables | `| ... |` with separator row | `<table>` with `<thead>` and `<tbody>` |
+| Horizontal rules | `---`, `***`, `___` | `<hr>` |
+| Display math | `$$` delimiters | `<div class="pict-content-katex-display">` |
+| Paragraphs | Any other non-empty line | `<p>` |
+
+**Code block nesting:** The parser tracks fence length (number of backticks). A closing fence must have at least as many backticks as the opening fence. This allows ```` ```` ```` to contain ```` ``` ```` blocks as content.
+
+**Example:**
+
+```javascript
+let tmpProvider = tmpPict.addProvider('Content',
+	PictContentProvider.default_configuration, PictContentProvider);
+
+let tmpHTML = tmpProvider.parseMarkdown(
+	'# Heading\n\n'
+	+ 'A paragraph with **bold** text.\n\n'
+	+ '- Item one\n'
+	+ '- Item two\n\n'
+	+ '```javascript\nlet x = 1;\n```'
+);
+```
+
+---
+
+### parseInline(pText, pLinkResolver)
+
+Parse inline markdown elements within a single line of text. Called by `parseMarkdown` for each line that contains inline content (headings, paragraphs, list items, table cells).
+
+Processing order:
+1. Inline code (backticks)
+2. Inline LaTeX (`$...$`)
+3. Images (`![alt](src)`)
+4. Links (`[text](url)`) -- with optional resolver
+5. Bold (`**text**` and `__text__`)
+6. Italic (`*text*` and `_text_`)
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pText` | string | The text to parse |
+| `pLinkResolver` | function | Optional link resolver callback |
+
+**Returns:** `string` -- HTML with inline elements
+
+**Link behavior without resolver:**
+- External links (`https://...` or `http://...`) get `target="_blank" rel="noopener"`
+- All other links render as plain `<a href="...">` tags
+
+**Example:**
+
+```javascript
+tmpProvider.parseInline('**bold** and *italic* and `code`');
+// '<strong>bold</strong> and <em>italic</em> and <code>code</code>'
+
+tmpProvider.parseInline('[GitHub](https://github.com)');
+// '<a href="https://github.com" target="_blank" rel="noopener">GitHub</a>'
+
+tmpProvider.parseInline('[Guide](guide.md)');
+// '<a href="guide.md">Guide</a>'
+```
+
+---
+
+### escapeHTML(pText)
+
+Escape HTML special characters to prevent XSS and ensure safe rendering inside HTML contexts. Used internally for code block content.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pText` | string | The text to escape |
+
+**Returns:** `string` -- The escaped text
+
+**Characters escaped:**
+
+| Character | Replacement |
+|-----------|-------------|
+| `&` | `&amp;` |
+| `<` | `&lt;` |
+| `>` | `&gt;` |
+| `"` | `&quot;` |
+| `'` | `&#39;` |
+
+**Example:**
+
+```javascript
+tmpProvider.escapeHTML('<script>alert("xss")</script>');
+// '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'
+```
+
+---
+
+## PictContentView
+
+Extends `pict-view`. Provides a styled content container with post-render hooks for Mermaid diagrams and KaTeX math equations.
+
+### Constructor
+
+```javascript
+new PictContentView(pFable, pOptions, pServiceHash)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pFable` | object | A Fable or Pict instance |
+| `pOptions` | object | Configuration options (merged with defaults) |
+| `pServiceHash` | string | Service identifier for the view registry |
+
+### Default Configuration
+
+```javascript
+{
+	ViewIdentifier: "Pict-Content",
+	DefaultRenderable: "Pict-Content-Display",
+	DefaultDestinationAddress: "#Pict-Content-Container",
+	AutoRender: false,
+
+	CSS: /* content styles */,
+
+	Templates:
+	[
+		{
+			Hash: "Pict-Content-Template",
+			Template: '<div class="pict-content" id="Pict-Content-Body">...</div>'
+		}
+	],
+
+	Renderables:
+	[
+		{
+			RenderableHash: "Pict-Content-Display",
+			TemplateHash: "Pict-Content-Template",
+			DestinationAddress: "#Pict-Content-Container",
+			RenderMethod: "replace"
+		}
+	]
+}
+```
+
+The view's `AutoRender` is `false` by default. Call `render()` explicitly to insert the content container into the DOM.
+
+---
+
+### displayContent(pHTMLContent, pContainerID)
+
+Assign HTML content to the container element, scroll to the top, and trigger post-render hooks for Mermaid and KaTeX.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `pHTMLContent` | string | | The HTML to display |
+| `pContainerID` | string | `'Pict-Content-Body'` | The container element ID |
+
+**Sequence:**
+1. Assigns content via `pict.ContentAssignment.assignContent`
+2. Scrolls the container's parent to the top
+3. Calls `renderMermaidDiagrams(pContainerID)`
+4. Calls `renderKaTeXEquations(pContainerID)`
+
+---
+
+### renderMermaidDiagrams(pContainerID)
+
+Find all `<pre class="mermaid">` elements in the container and render them using the Mermaid library. If `mermaid` is not defined globally, this method returns immediately.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `pContainerID` | string | `'Pict-Content-Body'` | The container element ID |
+
+---
+
+### renderKaTeXEquations(pContainerID)
+
+Find all `.pict-content-katex-inline` and `.pict-content-katex-display` elements in the container and render them using the KaTeX library. If `katex` is not defined globally, this method returns immediately.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `pContainerID` | string | `'Pict-Content-Body'` | The container element ID |
+
+**Element types:**
+- `.pict-content-katex-inline` -- Rendered with `displayMode: false`
+- `.pict-content-katex-display` -- Rendered with `displayMode: true`
+
+Both use `throwOnError: false` to prevent rendering failures from propagating.
+
+---
+
+### showLoading(pMessage, pContainerID)
+
+Display a loading indicator inside the content container.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `pMessage` | string | `'Loading content...'` | The loading message |
+| `pContainerID` | string | `'Pict-Content-Body'` | The container element ID |
+
+---
+
+## CSS Classes
+
+The view registers CSS styles for the `.pict-content` container and all rendered elements within it.
+
+### Layout
+
+| Class | Description |
+|-------|-------------|
+| `.pict-content` | Main content wrapper. Max width 900px, centered, padded. |
+| `.pict-content-loading` | Loading indicator. Centered, minimum height 200px. |
+
+### Typography
+
+| Selector | Description |
+|----------|-------------|
+| `.pict-content h1` | Primary heading. Bottom border, no top margin. |
+| `.pict-content h2` | Section heading. Light bottom border. |
+| `.pict-content h3` | Subsection heading. |
+| `.pict-content h4, h5, h6` | Minor headings. |
+| `.pict-content p` | Paragraph. Line height 1.7. |
+| `.pict-content a` | Links. Teal color, underline on hover. |
+
+### Code
+
+| Selector | Description |
+|----------|-------------|
+| `.pict-content pre` | Code block. Dark background, rounded corners. |
+| `.pict-content code` | Inline code. Light background, warm accent color. |
+| `.pict-content pre code` | Code inside pre block. Inherits pre styling. |
+
+### Lists and Quotes
+
+| Selector | Description |
+|----------|-------------|
+| `.pict-content ul, ol` | List containers. Left padding, line height 1.8. |
+| `.pict-content li` | List items. |
+| `.pict-content blockquote` | Block quote. Left border, light background. |
+
+### Tables
+
+| Selector | Description |
+|----------|-------------|
+| `.pict-content table` | Full width, collapsed borders. |
+| `.pict-content table th` | Header cells. Warm background, bold. |
+| `.pict-content table td` | Body cells. |
+| `.pict-content table tr:nth-child(even)` | Alternating row background. |
+
+### Special Elements
+
+| Selector | Description |
+|----------|-------------|
+| `.pict-content img` | Images. Max width 100%, auto height. |
+| `.pict-content hr` | Horizontal rule. Light border. |
+| `.pict-content pre.mermaid` | Mermaid diagram container. White background, centered. |
+| `.pict-content .pict-content-katex-display` | Display math. Centered, padded. |
+| `.pict-content .pict-content-katex-inline` | Inline math. |
+
+---
+
+## Inherited from pict-view
+
+PictContentView inherits the full view interface. Key inherited members:
+
+| Member | Description |
+|--------|-------------|
+| `render()` | Render the view's template to the DOM |
+| `pict` | The Pict instance |
+| `AppData` | Shared application state |
+| `log` | Logger instance |
+| `options` | Merged configuration |
+| `UUID` | Unique service identifier |
+| `Hash` | Service registry hash |
+
+See [Pict View](/pict/pict-view/) for the complete view API.

package/docs/cover.md

@@ -0,0 +1,15 @@
+# Pict Section Content
+
+> Markdown parsing and content rendering for the Pict ecosystem
+
+Parse markdown to HTML with support for code blocks, Mermaid diagrams, KaTeX math, GFM tables, and customizable link resolution. Display content with a styled view that handles post-render initialization of diagrams and equations.
+
+- **Markdown Parser** -- Full block and inline markdown support with HTML escaping
+- **Mermaid & KaTeX** -- Post-render hooks for diagram and math rendering
+- **Link Resolver** -- Pluggable callback for application-specific link handling
+- **Extensible View** -- Inherit and customize container IDs, styling, and behavior
+
+[Quick Start](README.md)
+[API Reference](api.md)
+[Link Resolver](link-resolver.md)
+[GitHub](https://github.com/stevenvelozo/pict-section-content)