pict-section-inlinedocumentation 0.0.1

package/example_applications/basic/docs/README.md

@@ -0,0 +1,40 @@
+# Inline Documentation Example
+
+Welcome to the inline documentation browser example. This demonstrates embedding a documentation viewer inside a Pict application.
+
+## Features
+
+- **Markdown Rendering** — Full markdown support including code blocks, tables, and blockquotes
+- **Sidebar Navigation** — Hierarchical document navigation loaded from `_sidebar.md`
+- **Topic Filtering** — Scope navigation to specific topics for contextual help
+- **Internal Links** — Click links to navigate between documents without leaving the page
+
+## Getting Started
+
+See the [Getting Started](getting-started.md) guide for setup instructions.
+
+## Architecture
+
+The inline documentation provider manages all views and state. You interact with it through a simple API:
+
+```javascript
+let tmpProvider = pict.providers['Pict-InlineDocumentation'];
+tmpProvider.loadDocument('getting-started.md');
+```
+
+## Code Example
+
+Here is a simple code block:
+
+```javascript
+const libPict = require('pict');
+const libInlineDoc = require('pict-section-inlinedocumentation');
+
+let tmpPict = new libPict({ Product: 'MyApp' });
+
+tmpPict.addProvider('Pict-InlineDocumentation',
+	libInlineDoc.default_configuration,
+	libInlineDoc);
+```
+
+> This is a blockquote demonstrating the markdown rendering capabilities.

package/example_applications/basic/docs/_sidebar.md

@@ -0,0 +1,4 @@
+- [Home](README.md)
+- Guide
+  - [Getting Started](getting-started.md)
+  - [Advanced Topics](advanced-topics.md)

package/example_applications/basic/docs/_topics.json

@@ -0,0 +1,10 @@
+{
+	"getting-started": {
+		"Name": "Getting Started",
+		"Documents": ["README.md", "getting-started.md"]
+	},
+	"advanced": {
+		"Name": "Advanced Usage",
+		"Documents": ["advanced-topics.md"]
+	}
+}

package/example_applications/basic/docs/advanced-topics.md

@@ -0,0 +1,47 @@
+# Advanced Topics
+
+This page covers advanced usage of the inline documentation system.
+
+## Custom Container
+
+By default the layout renders into an element with id `InlineDoc-Container`. You can override this:
+
+```javascript
+tmpDocProvider.initializeDocumentation({
+	DocsBaseURL: 'docs/',
+	ContainerAddress: '#my-custom-container'
+});
+```
+
+## Programmatic Navigation
+
+The navigation sidebar is loaded from `_sidebar.md`, but you can also set it programmatically via AppData:
+
+```javascript
+pict.AppData.InlineDocumentation.SidebarGroups = [
+	{
+		Name: 'Guide',
+		Key: 'guide',
+		Path: 'README.md',
+		Items: [
+			{ Name: 'Getting Started', Path: 'getting-started.md' },
+			{ Name: 'Advanced', Path: 'advanced-topics.md' }
+		]
+	}
+];
+```
+
+## Content Caching
+
+Documents are cached after first load. To clear the cache (e.g. after docs are updated), change the base URL or create a new provider instance.
+
+## Upcoming Features
+
+These features are planned for future releases:
+
+- **Edit Mode** — In-place markdown editing
+- **Tooltips** — Hover documentation for terms and concepts
+- **Localization** — Multi-language document support
+- **Search** — Full-text search across documents
+- **AI Integration** — Contextual AI assistance
+- **Advanced Docking** — Resizable, detachable documentation panels

package/example_applications/basic/docs/getting-started.md

@@ -0,0 +1,70 @@
+# Getting Started
+
+This guide walks you through embedding the inline documentation browser in your application.
+
+## Installation
+
+```bash
+npm install pict-section-inlinedocumentation
+```
+
+## Basic Setup
+
+1. Add the provider to your Pict instance
+2. Call `initializeDocumentation()` with your docs base URL
+3. Load a document
+
+```javascript
+const libPict = require('pict');
+const libInlineDoc = require('pict-section-inlinedocumentation');
+
+let tmpPict = new libPict({ Product: 'MyApp' });
+
+// Add the inline documentation provider
+let tmpDocProvider = tmpPict.addProvider(
+	'Pict-InlineDocumentation',
+	libInlineDoc.default_configuration,
+	libInlineDoc);
+
+// Initialize with your docs folder URL
+tmpDocProvider.initializeDocumentation(
+	{ DocsBaseURL: 'docs/' },
+	() =>
+	{
+		// Load the first document
+		tmpDocProvider.loadDocument('README.md');
+	});
+```
+
+## Topics
+
+Topics let you scope the navigation sidebar to a subset of documents. Define topics in a `_topics.json` file:
+
+```json
+{
+	"getting-started": {
+		"Name": "Getting Started",
+		"Documents": ["README.md", "getting-started.md"]
+	}
+}
+```
+
+Then activate a topic:
+
+```javascript
+tmpDocProvider.setTopic('getting-started');
+```
+
+## API Reference
+
+| Method | Description |
+|--------|-------------|
+| `initializeDocumentation(options, callback)` | Initialize the documentation system |
+| `loadDocument(path, callback)` | Load and display a document |
+| `setTopic(topicKey)` | Filter navigation to a topic |
+| `clearTopic()` | Show all navigation |
+| `navigateBack(callback)` | Go to previous document |
+| `setDocsBaseURL(url)` | Change the docs root URL |
+| `getNavigationHistory()` | Get visited document paths |
+
+Back to [Home](README.md).

package/example_applications/basic/index.html

@@ -0,0 +1,100 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+	<meta charset="UTF-8">
+	<meta name="viewport" content="width=device-width, initial-scale=1.0">
+	<title>Inline Documentation Example</title>
+	<style>
+		* { margin: 0; padding: 0; box-sizing: border-box; }
+		body {
+			font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+			background: #F5F3EE;
+			color: #3D3229;
+			padding: 2em;
+		}
+		h1 {
+			margin-bottom: 0.5em;
+			font-size: 1.5em;
+		}
+		.controls {
+			margin-bottom: 1em;
+			display: flex;
+			gap: 0.5em;
+			flex-wrap: wrap;
+		}
+		.controls button {
+			padding: 0.4em 0.8em;
+			border: 1px solid #C4BAA8;
+			border-radius: 4px;
+			background: #fff;
+			color: #3D3229;
+			cursor: pointer;
+			font-size: 0.9em;
+		}
+		.controls button:hover {
+			background: #F0ECE4;
+		}
+		.controls button.active {
+			background: #2E7D74;
+			color: #fff;
+			border-color: #2E7D74;
+		}
+		#InlineDoc-Container {
+			height: 600px;
+		}
+	</style>
+</head>
+<body>
+	<h1>Inline Documentation Browser</h1>
+	<div class="controls">
+		<button onclick="loadDoc('README.md')">Home</button>
+		<button onclick="loadDoc('getting-started.md')">Getting Started</button>
+		<button onclick="loadDoc('advanced-topics.md')">Advanced Topics</button>
+		<button onclick="setTopic('getting-started')">Topic: Getting Started</button>
+		<button onclick="setTopic('advanced')">Topic: Advanced</button>
+		<button onclick="clearTopic()">Clear Topic</button>
+		<button onclick="goBack()">Back</button>
+	</div>
+	<div id="InlineDoc-Container"></div>
+
+	<script src="../../dist/pict-section-inlinedocumentation.js"></script>
+	<script src="https://cdn.jsdelivr.net/npm/pict@1/dist/pict.min.js"></script>
+	<script>
+		var _Pict = new Pict({ Product: 'InlineDocExample' });
+
+		var InlineDocProvider = require('pict-section-inlinedocumentation');
+
+		var _DocProvider = _Pict.addProvider(
+			'Pict-InlineDocumentation',
+			InlineDocProvider.default_configuration,
+			InlineDocProvider);
+
+		_DocProvider.initializeDocumentation(
+			{ DocsBaseURL: 'docs/' },
+			function ()
+			{
+				_DocProvider.loadDocument('README.md');
+			});
+
+		function loadDoc(pPath)
+		{
+			_DocProvider.loadDocument(pPath);
+		}
+
+		function setTopic(pKey)
+		{
+			_DocProvider.setTopic(pKey);
+		}
+
+		function clearTopic()
+		{
+			_DocProvider.clearTopic();
+		}
+
+		function goBack()
+		{
+			_DocProvider.navigateBack();
+		}
+	</script>
+</body>
+</html>

package/example_applications/bookshop/.quackage.json

@@ -0,0 +1,10 @@
+{
+	"build":
+	[
+		{
+			"Type": "Browserify",
+			"Entry": "./Pict-Application-Bookshop.js",
+			"OutputFileName": "bookshop_example"
+		}
+	]
+}

package/example_applications/bookshop/Pict-Application-Bookshop-Configuration.json

@@ -0,0 +1,15 @@
+{
+	"Name": "Bookshop",
+	"Hash": "Bookshop",
+
+	"MainViewportViewIdentifier": "Bookshop-BookList",
+
+	"AutoSolveAfterInitialize": true,
+	"AutoRenderMainViewportViewAfterInitialize": false,
+	"AutoRenderViewsAfterInitialize": false,
+
+	"pict_configuration":
+		{
+			"Product": "Bookshop-Pict-Application"
+		}
+}

package/example_applications/bookshop/Pict-Application-Bookshop.js

@@ -0,0 +1,218 @@
+const libPictApplication = require('pict-application');
+
+const libInlineDocumentation = require('../../source/Pict-Section-InlineDocumentation.js');
+
+const libViewBookList = require('./views/PictView-Bookshop-BookList.js');
+const libViewStore = require('./views/PictView-Bookshop-Store.js');
+const libViewHelpToggle = require('./views/PictView-Bookshop-HelpToggle.js');
+
+const _BookshopData = require('./data/BookshopData.json');
+const _TopicsData = require('./data/pict_documentation_topics.json');
+
+class BookshopApplication extends libPictApplication
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		// Add the inline documentation provider
+		this.pict.addProvider('Pict-InlineDocumentation', libInlineDocumentation.default_configuration, libInlineDocumentation);
+
+		// Add application views
+		this.pict.addView('Bookshop-BookList', libViewBookList.default_configuration, libViewBookList);
+		this.pict.addView('Bookshop-Store', libViewStore.default_configuration, libViewStore);
+		this.pict.addView('Bookshop-HelpToggle', libViewHelpToggle.default_configuration, libViewHelpToggle);
+	}
+
+	onAfterInitializeAsync(fCallback)
+	{
+		// Initialize application state
+		this.pict.AppData.Bookshop =
+		{
+			Books: _BookshopData.Books,
+			CurrentBook: null,
+			CurrentView: 'BookList',
+			GenreFilter: '',
+			HelpVisible: false,
+			HelpTopicCode: 'BOOKSHOP-WELCOME'
+		};
+
+		// Pre-load topics into the inline documentation state
+		if (!this.pict.AppData.InlineDocumentation)
+		{
+			this.pict.AppData.InlineDocumentation = {};
+		}
+		this.pict.AppData.InlineDocumentation.Topics = _TopicsData;
+
+		// Initialize inline documentation
+		let tmpDocProvider = this.pict.providers['Pict-InlineDocumentation'];
+		tmpDocProvider.initializeDocumentation(
+			{
+				DocsBaseURL: 'docs/',
+				onSave: (pSaveData, fSaveCallback) =>
+				{
+					// Demo save handler — log to console
+					this.log.info(`Bookshop: Saving document [${pSaveData.Path}] (${pSaveData.Content.length} chars)`);
+					// In a real app, this would PUT to an API
+					return fSaveCallback(null);
+				},
+				onTopicsSave: (pTopics, fSaveCallback) =>
+				{
+					// Demo topics save handler — log to console
+					this.log.info(`Bookshop: Saving topics (${Object.keys(pTopics).length} topics)`);
+					// In a real app, this would PUT to an API
+					return fSaveCallback(null);
+				},
+				onImageUpload: (pFile, pDocumentPath, fCallback) =>
+				{
+					// Demo image upload handler — log to console
+					this.log.info(`Bookshop: Image upload [${pFile.name}] (${pFile.size} bytes) for document [${pDocumentPath}]`);
+					// In a real app, this would POST the file to a server
+					// and return a relative URL for the markdown reference.
+					// For the demo, fall back to base64 by returning an error.
+					return fCallback('Demo mode: no upload server configured');
+				}
+			},
+			() =>
+			{
+				// Enable edit mode for demo
+				tmpDocProvider.setEditEnabled(true);
+
+				// Render the main book list
+				this.pict.views['Bookshop-BookList'].render();
+
+				// Load help for the initial route
+				tmpDocProvider.navigateToRoute('/books');
+
+				// Set up F1 keyboard listener
+				this._setupKeyboardShortcuts();
+
+				return super.onAfterInitializeAsync(fCallback);
+			});
+	}
+
+	/**
+	 * Set up the F1 keyboard shortcut for toggling help.
+	 */
+	_setupKeyboardShortcuts()
+	{
+		if (typeof document === 'undefined')
+		{
+			return;
+		}
+
+		document.addEventListener('keydown', (pEvent) =>
+		{
+			if (pEvent.key === 'F1')
+			{
+				pEvent.preventDefault();
+				this.toggleHelp();
+			}
+		});
+	}
+
+	/**
+	 * Toggle the help panel visibility.
+	 */
+	toggleHelp()
+	{
+		let tmpState = this.pict.AppData.Bookshop;
+		tmpState.HelpVisible = !tmpState.HelpVisible;
+
+		let tmpHelpPanel = document.getElementById('Bookshop-Help-Panel');
+		let tmpContentArea = document.getElementById('Bookshop-Content-Area');
+
+		if (tmpState.HelpVisible)
+		{
+			if (tmpHelpPanel) { tmpHelpPanel.classList.add('visible'); }
+			if (tmpContentArea) { tmpContentArea.classList.add('help-open'); }
+		}
+		else
+		{
+			if (tmpHelpPanel) { tmpHelpPanel.classList.remove('visible'); }
+			if (tmpContentArea) { tmpContentArea.classList.remove('help-open'); }
+		}
+	}
+
+	/**
+	 * Show contextual help for a specific topic code.
+	 *
+	 * @param {string} pTopicCode - The TopicCode from pict_documentation_topics.json
+	 */
+	showHelp(pTopicCode)
+	{
+		let tmpState = this.pict.AppData.Bookshop;
+		let tmpDocProvider = this.pict.providers['Pict-InlineDocumentation'];
+
+		tmpState.HelpTopicCode = pTopicCode;
+
+		// Ensure help panel is visible
+		if (!tmpState.HelpVisible)
+		{
+			tmpState.HelpVisible = true;
+			let tmpHelpPanel = document.getElementById('Bookshop-Help-Panel');
+			let tmpContentArea = document.getElementById('Bookshop-Content-Area');
+			if (tmpHelpPanel) { tmpHelpPanel.classList.add('visible'); }
+			if (tmpContentArea) { tmpContentArea.classList.add('help-open'); }
+		}
+
+		// Load the topic document
+		tmpDocProvider.loadTopicDocument(pTopicCode);
+	}
+
+	/**
+	 * Navigate to a specific book's store page.
+	 *
+	 * @param {number} pBookID - The book ID
+	 */
+	showBook(pBookID)
+	{
+		let tmpState = this.pict.AppData.Bookshop;
+		let tmpDocProvider = this.pict.providers['Pict-InlineDocumentation'];
+
+		for (let i = 0; i < tmpState.Books.length; i++)
+		{
+			if (tmpState.Books[i].IDBook === pBookID)
+			{
+				tmpState.CurrentBook = tmpState.Books[i];
+				tmpState.CurrentView = 'Store';
+				this.pict.views['Bookshop-Store'].render();
+
+				// Update help for the store route
+				tmpDocProvider.navigateToRoute('/books/store/' + pBookID);
+				return;
+			}
+		}
+	}
+
+	/**
+	 * Navigate back to the book list.
+	 */
+	showBookList()
+	{
+		let tmpState = this.pict.AppData.Bookshop;
+		let tmpDocProvider = this.pict.providers['Pict-InlineDocumentation'];
+
+		tmpState.CurrentBook = null;
+		tmpState.CurrentView = 'BookList';
+		this.pict.views['Bookshop-BookList'].render();
+
+		// Update help for the book list route
+		tmpDocProvider.navigateToRoute('/books');
+	}
+
+	/**
+	 * Filter books by genre.
+	 *
+	 * @param {string} pGenre - The genre to filter by (empty for all)
+	 */
+	filterByGenre(pGenre)
+	{
+		this.pict.AppData.Bookshop.GenreFilter = pGenre || '';
+		this.pict.views['Bookshop-BookList'].render();
+	}
+}
+
+module.exports = BookshopApplication;
+
+module.exports.default_configuration = require('./Pict-Application-Bookshop-Configuration.json');

package/example_applications/bookshop/data/BookshopData.json

@@ -0,0 +1,65 @@
+{
+	"Books":
+	[
+		{
+			"IDBook": 1,
+			"Title": "The Pragmatic Programmer",
+			"Author": "David Thomas & Andrew Hunt",
+			"Price": 49.99,
+			"Genre": "Software Engineering",
+			"Cover": "https://picsum.photos/seed/pragprog/120/180",
+			"Description": "A classic guide to software craftsmanship covering topics from personal responsibility to architectural techniques.",
+			"InStock": true
+		},
+		{
+			"IDBook": 2,
+			"Title": "Designing Data-Intensive Applications",
+			"Author": "Martin Kleppmann",
+			"Price": 44.99,
+			"Genre": "Distributed Systems",
+			"Cover": "https://picsum.photos/seed/dataintensive/120/180",
+			"Description": "The big ideas behind reliable, scalable, and maintainable systems, with detailed analysis of the algorithms and protocols.",
+			"InStock": true
+		},
+		{
+			"IDBook": 3,
+			"Title": "Structure and Interpretation of Computer Programs",
+			"Author": "Harold Abelson & Gerald Jay Sussman",
+			"Price": 39.99,
+			"Genre": "Computer Science",
+			"Cover": "https://picsum.photos/seed/sicp/120/180",
+			"Description": "The legendary MIT textbook introducing core concepts of computation through Scheme.",
+			"InStock": false
+		},
+		{
+			"IDBook": 4,
+			"Title": "Clean Code",
+			"Author": "Robert C. Martin",
+			"Price": 37.99,
+			"Genre": "Software Engineering",
+			"Cover": "https://picsum.photos/seed/cleancode/120/180",
+			"Description": "A handbook of agile software craftsmanship with practical advice for writing better code.",
+			"InStock": true
+		},
+		{
+			"IDBook": 5,
+			"Title": "The Art of Computer Programming",
+			"Author": "Donald E. Knuth",
+			"Price": 79.99,
+			"Genre": "Computer Science",
+			"Cover": "https://picsum.photos/seed/taocp/120/180",
+			"Description": "Knuth's monumental multi-volume work covering fundamental algorithms and data structures.",
+			"InStock": true
+		},
+		{
+			"IDBook": 6,
+			"Title": "Refactoring",
+			"Author": "Martin Fowler",
+			"Price": 42.99,
+			"Genre": "Software Engineering",
+			"Cover": "https://picsum.photos/seed/refactoring/120/180",
+			"Description": "Improving the design of existing code through systematic transformations with catalog of refactoring patterns.",
+			"InStock": true
+		}
+	]
+}

package/example_applications/bookshop/data/pict_documentation_topics.json

@@ -0,0 +1,46 @@
+{
+	"BOOKSHOP-WELCOME": {
+		"TopicCode": "BOOKSHOP-WELCOME",
+		"TopicHelpFilePath": "welcome.md",
+		"TopicTitle": "Welcome to the Bookshop",
+		"Routes": ["/"]
+	},
+	"BOOKSHOP-BOOKLIST": {
+		"TopicCode": "BOOKSHOP-BOOKLIST",
+		"TopicHelpFilePath": "book-list.md",
+		"TopicTitle": "Browsing the Book Catalog",
+		"Routes": ["/books", "/books/catalog"],
+		"Tooltips": {
+			"catalog-title": { "Content": "Browse our full collection of books. Click any book to view details and purchase.\n\nSee [Book Catalog Help](help:book-list.md) for the full guide." },
+			"catalog-info": { "Content": "**Tip:** Use the genre filter to narrow results, or click a book card to visit its store page.\n\nLearn more: [Searching & Filtering](help:search-filter.md)" },
+			"genre-filter": { "Content": "Filter the catalog by literary genre. Select **All Genres** to see everything.\n\nFor advanced filtering tips, see [Search & Filter Guide](help:search-filter.md)." },
+			"book-price": { "Content": "All prices are in **USD** and include tax.\n\nSee [Store Page Help → Pricing](help:store.md#pricing) for details." },
+			"stock-status": { "Content": "**In Stock** means the book is available for immediate purchase. **Out of Stock** items cannot be added to cart.\n\nMore info: [Store Help → Availability](help:store.md#availability)" }
+		}
+	},
+	"BOOKSHOP-BOOKDETAIL": {
+		"TopicCode": "BOOKSHOP-BOOKDETAIL",
+		"TopicHelpFilePath": "book-detail.md",
+		"TopicTitle": "Book Details & Purchasing",
+		"Routes": ["/books/detail/*"]
+	},
+	"BOOKSHOP-STORE": {
+		"TopicCode": "BOOKSHOP-STORE",
+		"TopicHelpFilePath": "store.md",
+		"TopicTitle": "The Store Page",
+		"Routes": ["/books/store/*"],
+		"Tooltips": {
+			"genre-badge": { "Content": "Books are categorized by genre to help you find similar titles.\n\nSee the [full catalog](help:book-list.md) to browse by genre." },
+			"store-price": { "Content": "The listed price is the final price in **USD**, tax included.\n\n[Pricing details](help:store.md#pricing)" },
+			"store-stock": { "Content": "Real-time availability. Out of stock items may be restocked — check back later.\n\n[Availability info](help:store.md#availability)" },
+			"add-to-cart": { "Content": "Adds this book to your shopping cart. You can review your cart before checkout.\n\nSee [Store Help](help:store.md) for the full purchasing guide." },
+			"cart-info": { "Content": "**Shopping Cart:** Items stay in your cart until you complete checkout or remove them.\n\nFor help: [Store Guide](help:store.md) | [Book Details](help:book-detail.md)" }
+		}
+	},
+	"BOOKSHOP-SEARCH": {
+		"TopicCode": "BOOKSHOP-SEARCH",
+		"TopicHelpFilePath": "search-filter.md",
+		"TopicTitle": "Searching & Filtering",
+		"Routes": ["/books/search", "/books/filter"]
+	}
+}

package/example_applications/bookshop/docs/_sidebar.md

@@ -0,0 +1,6 @@
+- [Welcome](welcome.md)
+- Using the Bookshop
+  - [Book Catalog](book-list.md)
+  - [Book Details](book-detail.md)
+  - [Store Page](store.md)
+  - [Search & Filter](search-filter.md)

package/example_applications/bookshop/docs/book-detail.md

@@ -0,0 +1,21 @@
+# Book Details & Purchasing
+
+When you click on a book in the catalog, you are taken to the store page which shows the full details for that book.
+
+## Detail View
+
+The detail view shows:
+
+- **Large cover image** on the left
+- **Full title and author** on the right
+- **Genre badge** indicating the book's category
+- **Description** — A summary of the book's content
+- **Price** displayed prominently
+- **Stock status** — Whether the book is available
+
+## Actions
+
+- **Back to Catalog** — Returns you to the full book list
+- **Add to Cart** — Adds the book to your shopping cart (available for in-stock items)
+
+> This is a demo application. The "Add to Cart" button simulates the action but does not process a real transaction.

package/example_applications/bookshop/docs/book-list.md

@@ -0,0 +1,21 @@
+# Browsing the Book Catalog
+
+The book catalog displays all available titles in a card layout. Each card shows the book's cover, title, author, genre, price, and availability.
+
+## Card Information
+
+- **Cover Image** — A thumbnail of the book cover
+- **Title & Author** — The book's title and author(s)
+- **Genre** — The category the book belongs to
+- **Price** — The current retail price
+- **Availability** — Whether the book is currently in stock
+
+## Interacting with Books
+
+Click on any book card to navigate to the **Store** page where you can see full details about the book and add it to your cart.
+
+> Books that are out of stock will show a red "Out of Stock" badge. You can still view their details but purchasing may be unavailable.
+
+## Filtering
+
+Use the genre filter dropdown above the book list to narrow the catalog to a specific genre. Select "All Genres" to see the full catalog again.