pict-section-inlinedocumentation 0.0.1

package/docs/embedding-level4-autogen.md

@@ -0,0 +1,126 @@
+# Level 4 -- Auto-Generated Tooltips for Every Editable Control
+
+The deepest integration. Every control in your application that is managed by a [Manyfest](/utility/manyfest/) descriptor gets a tooltip automatically, with zero `data-help` markup. Missing topics are materialized as stubs on the fly. When a privileged user enters **edit mode**, they can click any tooltip to open an inline editor and write the copy right there in the running app -- no repo checkouts, no deploys.
+
+Good for: mature products with a content-owning team that isn't going to wait for engineering to merge every typo fix.
+
+## Prerequisites
+
+- Levels 1-3 are in place (you don't need to have used them, but the API is shared).
+- Your form is built from a Manyfest descriptor. Anything produced by `pict-form` or `meadow-endpoints`' schema exporter qualifies.
+- You have an identity provider with a role that identifies "content editors".
+- An HTTP endpoint that accepts edited topic payloads (typically `retold-content-system` or similar).
+
+## One-Line Bootstrap
+
+```js
+await _Pict.views.InlineDocumentation.autoGenerateTooltipsAsync(
+{
+    Manyfest: _Pict.providers.CustomerManyfest,
+    Scope: '#CustomerForm',
+    TopicPrefix: 'customers/',
+    EditMode: _Pict.providers.Auth.userHasRole('docs-editor'),
+    EditEndpoint: '/api/docs/topics'
+});
+```
+
+Here's what happens under the hood:
+
+1. The generator walks every hash in `CustomerManyfest`.
+2. For each hash `customer.email`, it computes a topic key: `customers/customer.email`.
+3. It asks the `TopicStore` for that topic. If it exists, it binds it to the matching element (located by the Manyfest's `DataElementAddress` resolver).
+4. If the topic does not exist, a stub is created with the hash's `Description` as the body. The stub is flagged so the UI can render it differently (e.g. dimmed or marked "needs writing").
+5. When `EditMode` is true, every tooltip grows a tiny pencil icon. Clicking it opens an in-place editor (a textarea with a Markdown preview). Saving POSTs the content to `EditEndpoint` and updates the live corpus.
+
+## Manyfest Descriptor Example
+
+```js
+{
+    Scope: 'customer',
+    Descriptors:
+    {
+        'customer.email':
+        {
+            Hash: 'customer.email',
+            DataElementAddress: 'input[name="email"]',
+            Name: 'Customer Email',
+            Description: 'Primary correspondence address',
+            DataType: 'String'
+        },
+        'customer.taxId':
+        {
+            Hash: 'customer.taxId',
+            DataElementAddress: 'input[name="taxId"]',
+            Name: 'Tax ID',
+            Description: 'Jurisdiction-specific tax identifier',
+            DataType: 'String'
+        }
+    }
+}
+```
+
+Running the generator against this produces `customers/customer.email` and `customers/customer.taxId` topics, each bound to the correct `<input>`.
+
+## Edit Mode UX
+
+In edit mode, the tooltip's footer shows three affordances:
+
+- **Edit** -- opens the in-place editor
+- **Open in docs** -- opens the topic in the sidebar for full-length editing
+- **Revert** -- drops the in-memory edit and reloads the original
+
+The editor renders a side-by-side Markdown preview using the same `TopicRenderer` as the reading pane, so what the editor sees is exactly what end-users will see.
+
+## Persistence
+
+`autoGenerateTooltipsAsync` only creates stubs *in memory*. To persist:
+
+- The built-in editor POSTs to `EditEndpoint` with `{ TopicKey, Markdown, Frontmatter }`.
+- Or call `exportEditedTopicsAsync()` to pull the full set of session edits and persist them in a batch.
+
+```js
+document.getElementById('PublishDocsButton').addEventListener('click', async () =>
+{
+    const tmpEdits = await _Pict.views.InlineDocumentation.exportEditedTopicsAsync();
+    await fetch('/api/docs/batch',
+    {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(tmpEdits)
+    });
+});
+```
+
+## Multiple Scopes
+
+A single call handles one Manyfest. Large apps call it once per form:
+
+```js
+await _Pict.views.InlineDocumentation.autoGenerateTooltipsAsync({ Manyfest: _Pict.providers.CustomerManyfest, Scope: '#CustomerForm', TopicPrefix: 'customers/', EditMode });
+await _Pict.views.InlineDocumentation.autoGenerateTooltipsAsync({ Manyfest: _Pict.providers.InvoiceManyfest,  Scope: '#InvoiceForm',  TopicPrefix: 'invoices/',  EditMode });
+await _Pict.views.InlineDocumentation.autoGenerateTooltipsAsync({ Manyfest: _Pict.providers.ProductManyfest,  Scope: '#ProductForm',  TopicPrefix: 'products/',  EditMode });
+```
+
+## Audit Trail
+
+Every save emits a `topic-edited` event with the editor's identity (pulled from your auth provider) and the diff. Wire it to whatever audit store you already have:
+
+```js
+_Pict.views.InlineDocumentation.on('topic-edited', (pEvent) =>
+{
+    _Pict.providers.Audit.record('docs:edit',
+    {
+        topic: pEvent.TopicKey,
+        author: pEvent.Author,
+        before: pEvent.Previous,
+        after: pEvent.Topic.Markdown
+    });
+});
+```
+
+## Guard Rails
+
+- Stubs are never silently promoted to "real" topics -- they must be explicitly saved.
+- Edit mode is opt-in per page; `EditMode: false` renders regular tooltips with no editing affordances at all.
+- `EditEndpoint` is required for persistence; omitting it means stubs stay in memory for the session only (useful for demos).
+- All edited Markdown runs through the same safe renderer as imported content; script tags and `javascript:` URLs are stripped before display.

package/docs/index.html

@@ -0,0 +1,39 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8">
+		<meta http-equiv="X-UA-Compatible" content="IE=edge">
+		<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+		<meta name="description" content="pict-section-inlinedocumentation v0.0.1 Documentation — Pict embeddable inline documentation browser with topic support">
+
+		<title>pict-section-inlinedocumentation v0.0.1 Documentation</title>
+
+		<!-- Application Stylesheet -->
+		<link href="css/docuserve.css" rel="stylesheet">
+		<!-- KaTeX stylesheet for LaTeX equation rendering -->
+		<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css">
+		<!-- PICT Dynamic View CSS Container -->
+		<style id="PICT-CSS"></style>
+
+		<!-- Load the PICT library from jsDelivr CDN -->
+		<script src="https://cdn.jsdelivr.net/npm/pict@1/dist/pict.min.js" type="text/javascript"></script>
+		<!-- Bootstrap the Application -->
+		<script type="text/javascript">
+//<![CDATA[
+		Pict.safeOnDocumentReady(() => { Pict.safeLoadPictApplication(PictDocuserve, 2)});
+//]]>
+		</script>
+	</head>
+	<body>
+		<!-- The root container for the Pict application -->
+		<div id="Docuserve-Application-Container"></div>
+
+		<!-- Mermaid diagram rendering -->
+		<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
+		<script>mermaid.initialize({ startOnLoad: false, theme: 'default' });</script>
+		<!-- KaTeX for LaTeX equation rendering -->
+		<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.js"></script>
+		<!-- Load the Docuserve PICT Application Bundle from jsDelivr CDN -->
+		<script src="https://cdn.jsdelivr.net/npm/pict-docuserve@0/dist/pict-docuserve.min.js" type="text/javascript"></script>
+	</body>
+</html>

package/docs/overview.md

@@ -0,0 +1,42 @@
+# Overview
+
+`pict-section-inlinedocumentation` is a Pict section -- a composable, self-contained view module -- that turns a folder of Markdown files into live, context-aware documentation inside any Pict application. It lets you go from "no help at all" to "every field has a tooltip and every screen has a help pane" without rewriting your app.
+
+## What It Does
+
+- Loads a corpus of Markdown topics from a URL, a static bundle, or a `pict-docuserve` catalog.
+- Renders a sidebar with a table of contents plus a main reading pane.
+- Maps help topics to application routes so the content updates as the user navigates.
+- Serves tooltip content to any control that asks for it by topic key.
+- In edit mode, generates tooltip topics dynamically for every control exposed by a Manyfest-backed content model.
+
+## Why It Exists
+
+Most applications bolt documentation on the side -- a separate site, a separate deploy, stale the day it ships. `pict-section-inlinedocumentation` treats docs as a runtime dependency of the UI: the same content loaded by `pict-docuserve` for your public docs site can be embedded directly in the running app, and individual topics can be addressed by fragment to power inline tooltips.
+
+## Four Levels of Embeddedness
+
+The module exposes four progressively deeper integration modes. You pick the level that matches how much investment you want to make.
+
+| Level | What You Get | Effort |
+|---|---|---|
+| **1. Sidebar + ToC** | A collapsible pane showing all docs with a table of contents | A few lines of config |
+| **2. Route-Mapped Content** | Help pane auto-switches to the topic for the current route | Add a route map |
+| **3. Hand-Authored Tooltips** | Specific fields/buttons show tooltips sourced from named topics | A `data-help` attribute per control |
+| **4. Auto-Generated Tooltips** | Every Manyfest-managed control gets a tooltip automatically, and content editors can edit them live | Wire once, author forever |
+
+Each level is a strict superset of the one before it. You can start at level 1 and upgrade later without rewriting anything.
+
+## What You Need
+
+- A Pict application (`pict@^1`)
+- A folder of Markdown files, either served statically or bundled
+- Optionally, a `retold-catalog.json` if you want cross-module search and navigation
+- Optionally, a Manyfest descriptor if you want level-4 auto-generation
+
+## Relationship to Other Modules
+
+- Uses [`pict-view`](/pict/pict-view/) as its base class.
+- Optionally consumes catalogs produced by [`pict-docuserve`](/pict/pict-docuserve/).
+- Uses [`manyfest`](/utility/manyfest/) descriptors to enumerate controls at level 4.
+- Uses [`pict-template-markdown`](/pict/pict-template-markdown/) or an equivalent renderer to turn Markdown into HTML at runtime.

package/docs/quickstart.md

@@ -0,0 +1,95 @@
+# Quickstart
+
+Get a sidebar of documentation rendering inside your Pict application in under five minutes.
+
+## 1. Install
+
+```bash
+npm install pict-section-inlinedocumentation
+```
+
+## 2. Register the Section
+
+In your Pict application bootstrap:
+
+```js
+const libPict = require('pict');
+const libInlineDocs = require('pict-section-inlinedocumentation');
+
+const _Pict = new libPict(
+{
+    Product: 'My Awesome App',
+    Version: '1.0.0'
+});
+
+_Pict.addSection('InlineDocumentation', libInlineDocs,
+{
+    DocumentationRoot: '/docs/',
+    CatalogURL: '/docs/retold-catalog.json',
+    DefaultTopic: 'overview',
+    SidebarContainer: '#AppHelpSidebar'
+});
+
+_Pict.onAfterInitializeAsync = async () =>
+{
+    await _Pict.views.InlineDocumentation.renderAsync();
+};
+```
+
+## 3. Add a Container to Your HTML
+
+```html
+<aside id="AppHelpSidebar"></aside>
+```
+
+Reload. You should see the topic list populated from your docs folder, with the default topic rendered on click.
+
+## 4. (Optional) Map Content to Routes
+
+```js
+_Pict.addSection('InlineDocumentation', libInlineDocs,
+{
+    DocumentationRoot: '/docs/',
+    RouteMap:
+    [
+        { Pattern: '/records/:entity',         Topic: 'records/browsing' },
+        { Pattern: '/records/:entity/:id/edit', Topic: 'records/editing' },
+        { Pattern: '/settings/*',               Topic: 'settings' }
+    ]
+});
+```
+
+Now when the user navigates, the help pane tracks them automatically.
+
+## 5. (Optional) Mark Up a Tooltip
+
+```html
+<input id="CustomerEmail" data-help="customers/email-field" />
+```
+
+```js
+_Pict.views.InlineDocumentation.bindTooltipsAsync('#CustomerForm');
+```
+
+Every element with a `data-help` attribute in the scope will get a tooltip driven by the matching topic.
+
+## 6. (Optional) Turn On Auto-Generation
+
+If your form is built from a Manyfest descriptor:
+
+```js
+_Pict.views.InlineDocumentation.autoGenerateTooltipsAsync(
+{
+    Manyfest: _Pict.providers.CustomerManyfest,
+    Scope: '#CustomerForm',
+    EditMode: _Pict.providers.Auth.userHasRole('docs-editor')
+});
+```
+
+Every hash in the manifest becomes a topic key. Missing topics are created as stubs that editors can fill in from the running app.
+
+## Next Steps
+
+- [Architecture](#/page/architecture.md) -- how the pieces fit together
+- [API Reference](#/page/api-reference.md) -- every exposed function with code snippets
+- [Embedding Level 1: Sidebar](#/page/embedding-level1-sidebar.md) through [Level 4: Auto-Gen](#/page/embedding-level4-autogen.md)

package/docs/reference.md

@@ -0,0 +1,73 @@
+# Implementation Reference
+
+A tour of the source tree for contributors.
+
+## Project Layout
+
+```
+pict-section-inlinedocumentation/
+├── package.json
+├── source/
+│   ├── Pict-Section-InlineDocumentation.js   // Main section class
+│   ├── services/
+│   │   ├── TopicStore.js
+│   │   ├── TopicRenderer.js
+│   │   ├── TooltipBinder.js
+│   │   └── AutoTooltipGenerator.js
+│   ├── views/
+│   │   ├── SidebarView.js
+│   │   ├── ReadingPaneView.js
+│   │   └── TooltipView.js
+│   ├── templates/
+│   │   ├── sidebar.tpl
+│   │   ├── reading-pane.tpl
+│   │   └── tooltip.tpl
+│   └── util/
+│       ├── routeMatch.js
+│       └── topicKey.js
+└── test/
+    ├── TopicStore.tests.js
+    ├── TooltipBinder.tests.js
+    ├── AutoTooltipGenerator.tests.js
+    └── Section.tests.js
+```
+
+## Class Summary
+
+- **`PictSectionInlineDocumentation`** extends `libPictViewClass`. Holds config, instantiates services, exposes the public API.
+- **`TopicStore`** -- loader, cache, search.
+- **`TopicRenderer`** -- Markdown to HTML with Pict template integration.
+- **`TooltipBinder`** -- DOM event + observer wiring.
+- **`AutoTooltipGenerator`** -- Manyfest walker.
+- **`SidebarView`**, **`ReadingPaneView`**, **`TooltipView`** -- `pict-view` subclasses, one per rendered surface.
+
+## Configuration Schema
+
+```js
+{
+    DocumentationRoot: String,     // URL or path to markdown folder
+    CatalogURL: String,            // Optional, else walk the folder
+    KeywordIndexURL: String,       // Optional
+    DefaultTopic: String,          // Key rendered when nothing else is selected
+    SidebarContainer: String,      // CSS selector
+    ReadingPaneContainer: String,  // CSS selector (optional)
+    RouteMap: Array,               // Level 2
+    EditMode: Boolean,             // Enables level-4 edit affordances
+    EditEndpoint: String,          // POST target for edited topics
+    TooltipDelayMs: Number,        // Default 400
+    TooltipPlacement: String,      // 'auto' | 'top' | 'bottom' | 'left' | 'right'
+    MaxCachedTopics: Number        // Default 128
+}
+```
+
+## Testing
+
+- Unit tests run under Mocha TDD. `TopicStore` is tested against an in-memory fetch stub; `TooltipBinder` is tested against a JSDOM environment; `AutoTooltipGenerator` uses a fixture Manyfest.
+- Run `npm test` for the full suite, `npx mocha -u tdd test/TopicStore.tests.js` for a single file.
+- Coverage via `npm run coverage`.
+
+## Extending
+
+- **Custom renderers** -- subclass `TopicRenderer` and set `RendererClass` in config.
+- **Custom tooltip UI** -- subclass `TooltipView`; set `TooltipViewClass` in config.
+- **Alternate storage** -- implement the `TopicStore` interface (`loadCatalogAsync`, `loadTopicAsync`, `searchAsync`) and pass it as `TopicStoreInstance`.

package/docs/retold-catalog.json

@@ -0,0 +1,181 @@
+{
+	"Generated": "2026-04-10T17:25:27.303Z",
+	"GitHubOrg": "stevenvelozo",
+	"DefaultBranch": "master",
+	"Groups": [
+		{
+			"Name": "Dist",
+			"Key": "dist",
+			"Description": "",
+			"Modules": [
+				{
+					"Name": "indoctrinate_content_staging",
+					"Repo": "indoctrinate_content_staging",
+					"Group": "dist",
+					"Branch": "master",
+					"HasDocs": false,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": []
+				},
+				{
+					"Name": "test-artifacts",
+					"Repo": "test-artifacts",
+					"Group": "dist",
+					"Branch": "master",
+					"HasDocs": false,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": []
+				}
+			]
+		},
+		{
+			"Name": "Docs",
+			"Key": "docs",
+			"Description": "",
+			"Modules": [
+				{
+					"Name": "css",
+					"Repo": "css",
+					"Group": "docs",
+					"Branch": "master",
+					"HasDocs": true,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": [
+						"css/docuserve.css"
+					]
+				}
+			]
+		},
+		{
+			"Name": "Example_applications",
+			"Key": "example_applications",
+			"Description": "",
+			"Modules": [
+				{
+					"Name": ".data",
+					"Repo": ".data",
+					"Group": "example_applications",
+					"Branch": "master",
+					"HasDocs": false,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": []
+				},
+				{
+					"Name": "basic",
+					"Repo": "basic",
+					"Group": "example_applications",
+					"Branch": "master",
+					"HasDocs": true,
+					"HasCover": false,
+					"Sidebar": [
+						{
+							"Title": "Home",
+							"Path": "README.md"
+						},
+						{
+							"Title": "Guide",
+							"Children": [
+								{
+									"Title": "Getting Started",
+									"Path": "getting-started.md"
+								},
+								{
+									"Title": "Advanced Topics",
+									"Path": "advanced-topics.md"
+								}
+							]
+						}
+					],
+					"DocFiles": [
+						"README.md",
+						"_sidebar.md",
+						"_topics.json",
+						"advanced-topics.md",
+						"getting-started.md"
+					]
+				},
+				{
+					"Name": "bookshop",
+					"Repo": "bookshop",
+					"Group": "example_applications",
+					"Branch": "master",
+					"HasDocs": true,
+					"HasCover": false,
+					"Sidebar": [
+						{
+							"Title": "Welcome",
+							"Path": "welcome.md"
+						},
+						{
+							"Title": "Using the Bookshop",
+							"Children": [
+								{
+									"Title": "Book Catalog",
+									"Path": "book-list.md"
+								},
+								{
+									"Title": "Book Details",
+									"Path": "book-detail.md"
+								},
+								{
+									"Title": "Store Page",
+									"Path": "store.md"
+								},
+								{
+									"Title": "Search & Filter",
+									"Path": "search-filter.md"
+								}
+							]
+						}
+					],
+					"DocFiles": [
+						"_sidebar.md",
+						"book-detail.md",
+						"book-list.md",
+						"pict_documentation_topics.json",
+						"search-filter.md",
+						"store.md",
+						"welcome.md",
+						"_sidebar.md",
+						"book-detail.md",
+						"book-list.md",
+						"search-filter.md",
+						"store.md",
+						"welcome.md"
+					]
+				}
+			]
+		},
+		{
+			"Name": "Source",
+			"Key": "source",
+			"Description": "",
+			"Modules": [
+				{
+					"Name": "providers",
+					"Repo": "providers",
+					"Group": "source",
+					"Branch": "master",
+					"HasDocs": false,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": []
+				},
+				{
+					"Name": "views",
+					"Repo": "views",
+					"Group": "source",
+					"Branch": "master",
+					"HasDocs": false,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": []
+				}
+			]
+		}
+	]
+}