pict-section-inlinedocumentation 0.0.1

package/README.md

@@ -0,0 +1,107 @@
+# pict-section-inlinedocumentation
+
+> Embed context-aware documentation and tooltip help directly inside any Pict application.
+
+A Pict section that turns a folder of Markdown files into in-app help. Ships four progressively deeper embedding modes: a drop-in sidebar with a table of contents, route-mapped reading panes, hand-authored tooltips on specific controls, and auto-generated tooltips for every Manyfest-managed control in your app -- editable live when a content owner is signed in.
+
+Part of the [Retold](https://github.com/stevenvelozo/retold) suite.
+
+## Install
+
+```bash
+npm install pict-section-inlinedocumentation
+```
+
+## Quick Usage
+
+```js
+const libPict = require('pict');
+const libInlineDocs = require('pict-section-inlinedocumentation');
+
+const _Pict = new libPict({ Product: 'My 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();
+};
+```
+
+Add a container to your HTML and you're done:
+
+```html
+<aside id="AppHelpSidebar"></aside>
+```
+
+## Four Levels of Embeddedness
+
+```mermaid
+flowchart LR
+    L1[1. Sidebar + ToC] --> L2[2. Route-Mapped]
+    L2 --> L3[3. Hand-Authored Tooltips]
+    L3 --> L4[4. Auto-Generated Tooltips]
+```
+
+| Level | What you get | Effort |
+|---|---|---|
+| 1 | Sidebar with a ToC of every topic | A few lines of config |
+| 2 | Help pane tracks the current route | Add a route map |
+| 3 | Tooltips on specific controls | `data-help` per control |
+| 4 | Tooltips on **every** Manyfest control, editable in-app | One call per form |
+
+Each level is a strict superset of the one below it.
+
+## Highlights
+
+- Built on `pict-view`, integrates with `pict-router`
+- Consumes `retold-catalog.json` + `retold-keyword-index.json` from `pict-docuserve`
+- Safe Markdown renderer with Mermaid, code highlighting, and KaTeX
+- MutationObserver keeps tooltips bound as the DOM changes
+- Edit mode: content editors can rewrite topics from the running app and POST them back
+- Emits lifecycle events for analytics and audit
+
+## Scripts
+
+| Script | What it does |
+|---|---|
+| `npm test` | Run Mocha TDD test suite |
+| `npm run coverage` | Code coverage via nyc/Istanbul |
+| `npx quack build` | Build the browser bundle |
+
+## Documentation
+
+Full documentation lives in [`docs/`](./docs/) and is published via [pict-docuserve](https://github.com/stevenvelozo/pict-docuserve):
+
+- [Overview](./docs/overview.md)
+- [Quickstart](./docs/quickstart.md)
+- [Architecture](./docs/architecture.md)
+- [Implementation Reference](./docs/reference.md)
+- [API Reference](./docs/api-reference.md)
+- Embedding: [Level 1](./docs/embedding-level1-sidebar.md) · [Level 2](./docs/embedding-level2-routes.md) · [Level 3](./docs/embedding-level3-tooltips.md) · [Level 4](./docs/embedding-level4-autogen.md)
+
+Regenerate the catalog and keyword index after editing any Markdown file:
+
+```bash
+npx quack prepare-docs
+```
+
+## Relationship to Other Retold Modules
+
+| Module | Role |
+|---|---|
+| [pict](https://github.com/stevenvelozo/pict) | Application framework |
+| [pict-view](https://github.com/stevenvelozo/pict-view) | Base view class |
+| [pict-router](https://github.com/stevenvelozo/pict-router) | Route change source for Level 2 |
+| [pict-docuserve](https://github.com/stevenvelozo/pict-docuserve) | Catalog + keyword index producer |
+| [manyfest](https://github.com/stevenvelozo/manyfest) | Descriptors walked for Level 4 |
+
+## License
+
+[MIT](./LICENSE) -- same as the rest of the Retold suite.

package/docs/README.md

@@ -0,0 +1,83 @@
+# pict-section-inlinedocumentation
+
+> Embed context-aware documentation and tooltip help directly inside any Pict application.
+
+`pict-section-inlinedocumentation` is a Pict section that turns a folder of Markdown topics into in-app help. It spans the full spectrum from "a sidebar with a table of contents" to "every editable control on every screen has a live, editable tooltip" -- and you pick the level that matches your product.
+
+Part of the [Retold](https://github.com/stevenvelozo/retold) suite. Uses [`pict-view`](/pict/pict-view/) as its base, optionally consumes catalogs from [`pict-docuserve`](/pict/pict-docuserve/), and at the deepest level pairs with [`manyfest`](/utility/manyfest/) to auto-generate tooltips for every descriptor in your model.
+
+## Four Levels of Embeddedness
+
+```mermaid
+flowchart LR
+    L1[1. Sidebar + ToC] --> L2[2. Route-Mapped Content]
+    L2 --> L3[3. Hand-Authored Tooltips]
+    L3 --> L4[4. Auto-Generated Tooltips]
+
+    style L1 fill:#e3f2fd,stroke:#42a5f5,color:#333
+    style L2 fill:#e8f5e9,stroke:#66bb6a,color:#333
+    style L3 fill:#fff3e0,stroke:#ffa726,color:#333
+    style L4 fill:#fce4ec,stroke:#ef5350,color:#333
+```
+
+Each level is a strict superset of the one before it.
+
+## Documentation
+
+Published with [`pict-docuserve`](/pict/pict-docuserve/). Open `docs/index.html` locally, or browse the source Markdown:
+
+- **[Overview](overview.md)** -- what it does and why
+- **[Quickstart](quickstart.md)** -- sidebar running in five minutes
+- **[Architecture](architecture.md)** -- services, views, lifecycle, with a Mermaid diagram
+- **[Implementation Reference](reference.md)** -- source tree tour
+- **[API Reference](api-reference.md)** -- every exposed function with a runnable snippet
+
+### Embedding Guides
+
+- **[Level 1 -- Sidebar + ToC](embedding-level1-sidebar.md)** -- least embedded
+- **[Level 2 -- Route-Mapped Content](embedding-level2-routes.md)** -- more embedded
+- **[Level 3 -- Hand-Authored Tooltips](embedding-level3-tooltips.md)** -- somewhat embedded
+- **[Level 4 -- Auto-Generated Tooltips](embedding-level4-autogen.md)** -- most embedded
+
+## Installation
+
+```bash
+npm install pict-section-inlinedocumentation
+```
+
+## Tiny Example
+
+```js
+const libPict = require('pict');
+const libInlineDocs = require('pict-section-inlinedocumentation');
+
+const _Pict = new libPict({ Product: 'My 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();
+};
+```
+
+## Relationship to Other Modules
+
+| Module | Role |
+|---|---|
+| [pict](/pict/pict/) | Application framework |
+| [pict-view](/pict/pict-view/) | Base view class |
+| [pict-router](/pict/pict-router/) | Source of route change events for Level 2 |
+| [pict-docuserve](/pict/pict-docuserve/) | Produces the catalog and keyword index consumed by this section |
+| [pict-template-markdown](/pict/pict-template-markdown/) | Markdown -> HTML renderer |
+| [manyfest](/utility/manyfest/) | Descriptors walked by Level 4 auto-generation |
+
+## License
+
+MIT -- same as the rest of the Retold suite.

package/docs/_cover.md

@@ -0,0 +1,15 @@
+# pict-section-inlinedocumentation
+
+> Embed context-aware documentation and tooltip help directly inside any Pict application.
+
+A Pict section that turns Markdown documentation into in-app help -- from a simple sidebar ToC all the way to auto-generated tooltips for every editable control in your application. Four levels of embeddedness, one tiny API.
+
+- **Level 1** -- Sidebar + ToC drop-in
+- **Level 2** -- Route-pattern-mapped content
+- **Level 3** -- Hand-authored tooltip topics
+- **Level 4** -- Auto-generated tooltips for every manifest-managed control
+
+[Get Started](#/page/quickstart.md)
+[Architecture](#/page/architecture.md)
+[API Reference](#/page/api-reference.md)
+[GitHub](https://github.com/stevenvelozo/retold)

package/docs/_sidebar.md

@@ -0,0 +1,24 @@
+- Introduction
+
+  - [Overview](#/page/overview.md)
+  - [Quickstart](#/page/quickstart.md)
+
+- Design
+
+  - [Architecture](#/page/architecture.md)
+  - [Implementation Reference](#/page/reference.md)
+  - [API Reference](#/page/api-reference.md)
+
+- Embedding Levels
+
+  - [1. Sidebar + ToC](#/page/embedding-level1-sidebar.md)
+  - [2. Route-Mapped Content](#/page/embedding-level2-routes.md)
+  - [3. Hand-Authored Tooltips](#/page/embedding-level3-tooltips.md)
+  - [4. Auto-Generated Tooltips](#/page/embedding-level4-autogen.md)
+
+- Ecosystem
+
+  - [pict](/pict/pict/)
+  - [pict-view](/pict/pict-view/)
+  - [pict-docuserve](/pict/pict-docuserve/)
+  - [manyfest](/utility/manyfest/)

package/docs/_topbar.md

@@ -0,0 +1,8 @@
+# pict-section-inlinedocumentation
+
+- [Overview](#/page/overview.md)
+- [Quickstart](#/page/quickstart.md)
+- [Architecture](#/page/architecture.md)
+- [API](#/page/api-reference.md)
+- [Embedding](#/page/embedding-level1-sidebar.md)
+- [GitHub](https://github.com/stevenvelozo/retold)

package/docs/_version.json

@@ -0,0 +1,7 @@
+{
+	"Name": "pict-section-inlinedocumentation",
+	"Version": "0.0.1",
+	"Description": "Pict embeddable inline documentation browser with topic support",
+	"GeneratedAt": "2026-04-10T17:25:27.594Z",
+	"GitCommit": "530ff7d"
+}

package/docs/api-reference.md

@@ -0,0 +1,185 @@
+# API Reference
+
+Every function a developer is expected to call, with a working snippet for each.
+
+The section is reached via `_Pict.views.InlineDocumentation` after it has been registered with `_Pict.addSection('InlineDocumentation', libInlineDocs, config)`.
+
+---
+
+## `renderAsync()`
+
+Renders the sidebar and reading pane into their configured containers. Call once after the Pict application has initialized.
+
+```js
+await _Pict.views.InlineDocumentation.renderAsync();
+```
+
+---
+
+## `loadTopicAsync(pTopicKey)`
+
+Loads a single topic by key and renders it into the reading pane. Returns the parsed topic object.
+
+```js
+const tmpTopic = await _Pict.views.InlineDocumentation.loadTopicAsync('records/editing');
+console.log(tmpTopic.Title, tmpTopic.Category);
+```
+
+---
+
+## `getTopicAsync(pTopicKey)`
+
+Returns the parsed topic without touching the DOM. Useful when you want the HTML for your own rendering.
+
+```js
+const tmpTopic = await _Pict.views.InlineDocumentation.getTopicAsync('customers/email-field');
+document.getElementById('MyCustomPane').innerHTML = tmpTopic.HTML;
+```
+
+---
+
+## `setDefaultTopic(pTopicKey)`
+
+Changes the topic rendered when nothing else is selected.
+
+```js
+_Pict.views.InlineDocumentation.setDefaultTopic('getting-started');
+```
+
+---
+
+## `setRouteMap(pRouteMap)`
+
+Replaces the route map at runtime. Entries are matched top-down; the first match wins.
+
+```js
+_Pict.views.InlineDocumentation.setRouteMap(
+[
+    { Pattern: '/records/:entity',          Topic: 'records/browsing' },
+    { Pattern: '/records/:entity/:id/edit', Topic: 'records/editing' },
+    { Pattern: '/settings/*',                Topic: 'settings' }
+]);
+```
+
+---
+
+## `attachRouter(pRouter)`
+
+Subscribes to a `pict-router` instance so that route changes drive the reading pane.
+
+```js
+_Pict.views.InlineDocumentation.attachRouter(_Pict.providers.Router);
+```
+
+---
+
+## `bindTooltipsAsync(pScopeSelector)`
+
+Finds every element with a `data-help` attribute under the given selector and wires a tooltip to it. Safe to call multiple times; already-bound elements are skipped.
+
+```js
+await _Pict.views.InlineDocumentation.bindTooltipsAsync('#CustomerForm');
+```
+
+---
+
+## `unbindTooltips(pScopeSelector)`
+
+Removes tooltip wiring for a scope. Use before destroying a view to avoid leaked listeners.
+
+```js
+_Pict.views.InlineDocumentation.unbindTooltips('#CustomerForm');
+```
+
+---
+
+## `showTooltip(pElement, pTopicKey)`
+
+Imperatively shows a tooltip -- handy for validation errors that carry a topic reference.
+
+```js
+const tmpInput = document.getElementById('CustomerEmail');
+_Pict.views.InlineDocumentation.showTooltip(tmpInput, 'customers/email-invalid');
+```
+
+---
+
+## `hideTooltip()`
+
+Hides any currently visible tooltip.
+
+```js
+_Pict.views.InlineDocumentation.hideTooltip();
+```
+
+---
+
+## `autoGenerateTooltipsAsync(pOptions)`
+
+Walks a Manyfest descriptor, creates topic keys for every hash, and binds tooltips to the matching DOM controls. In `EditMode`, stub topics are created for missing keys and can be edited from the app.
+
+```js
+await _Pict.views.InlineDocumentation.autoGenerateTooltipsAsync(
+{
+    Manyfest: _Pict.providers.CustomerManyfest,
+    Scope: '#CustomerForm',
+    TopicPrefix: 'customers/',
+    EditMode: _Pict.providers.Auth.userHasRole('docs-editor')
+});
+```
+
+---
+
+## `registerTopicStub(pTopicKey, pStub)`
+
+Adds a stub topic in memory. Useful for testing or for supplying fallback content when the corpus is incomplete.
+
+```js
+_Pict.views.InlineDocumentation.registerTopicStub('customers/email-field',
+{
+    Title: 'Customer Email',
+    Markdown: 'The primary email address used for all customer correspondence.'
+});
+```
+
+---
+
+## `searchAsync(pQuery)`
+
+Runs a keyword search against the loaded corpus. Returns an array of `{ TopicKey, Title, Score, Snippet }`.
+
+```js
+const tmpResults = await _Pict.views.InlineDocumentation.searchAsync('password reset');
+tmpResults.forEach(r => console.log(r.Score.toFixed(2), r.TopicKey, r.Title));
+```
+
+---
+
+## `exportEditedTopicsAsync()`
+
+In edit mode, returns every topic that has been modified in the running session so you can persist them or PR them back into the docs repo.
+
+```js
+const tmpEdits = await _Pict.views.InlineDocumentation.exportEditedTopicsAsync();
+await fetch('/api/docs/batch', { method: 'POST', body: JSON.stringify(tmpEdits) });
+```
+
+---
+
+## `on(pEventName, pHandler)` / `off(pEventName, pHandler)`
+
+Emits lifecycle events:
+
+- `topic-loaded` -- `{ TopicKey, Topic }`
+- `topic-rendered` -- `{ TopicKey, Container }`
+- `tooltip-shown` -- `{ Element, TopicKey }`
+- `tooltip-hidden` -- `{ Element }`
+- `catalog-loaded` -- `{ Catalog }`
+- `topic-edited` -- `{ TopicKey, Topic }` (edit mode only)
+
+```js
+_Pict.views.InlineDocumentation.on('topic-rendered', ({ TopicKey }) =>
+{
+    _Pict.providers.Analytics.track('help:viewed', { topic: TopicKey });
+});
+```

package/docs/architecture.md

@@ -0,0 +1,103 @@
+# Architecture
+
+`pict-section-inlinedocumentation` is a Pict section that wraps three collaborating services: a **topic store**, a **renderer**, and a **binder**. The section itself is thin -- it owns configuration and lifecycle; the services do the work.
+
+## Core Concepts
+
+- **Topic** -- a single Markdown file with frontmatter. Addressed by a slash-separated key such as `records/editing` or `customers/email-field`.
+- **Catalog** -- a JSON index of topics, either shipped with the app or produced by `pict-docuserve prepare-docs`.
+- **Route Map** -- a list of `{ Pattern, Topic }` entries that associates application routes with topic keys.
+- **Binding** -- a runtime link between a DOM element and a topic, expressed via `data-help="<key>"` or via a Manyfest hash.
+
+## Component Diagram
+
+```mermaid
+flowchart TB
+    subgraph Host["Host Pict Application"]
+        ROUTER[pict-router]
+        MANYFEST[Manyfest Descriptor]
+        DOM[DOM Controls]
+    end
+
+    subgraph Section["pict-section-inlinedocumentation"]
+        direction TB
+        CONFIG[Section Config]
+        STORE[TopicStore]
+        RENDER[TopicRenderer]
+        BINDER[TooltipBinder]
+        AUTOGEN[AutoTooltipGenerator]
+        SIDEBAR[SidebarView]
+        PANE[ReadingPaneView]
+        TOOLTIP[TooltipView]
+        CONFIG --> STORE
+        STORE --> RENDER
+        RENDER --> PANE
+        RENDER --> SIDEBAR
+        RENDER --> TOOLTIP
+        BINDER --> TOOLTIP
+        AUTOGEN --> BINDER
+    end
+
+    subgraph Sources["Content Sources"]
+        MD[(Markdown Files)]
+        CATALOG[(retold-catalog.json)]
+        KWIDX[(keyword-index.json)]
+    end
+
+    STORE -- fetch --> MD
+    STORE -- load --> CATALOG
+    STORE -- search --> KWIDX
+    ROUTER -- route change --> RENDER
+    MANYFEST -- hashes --> AUTOGEN
+    DOM -- data-help --> BINDER
+    BINDER -- hover/focus --> TOOLTIP
+    SIDEBAR --> DOM
+    PANE --> DOM
+    TOOLTIP --> DOM
+```
+
+## Services
+
+### TopicStore
+
+Owns the corpus. Responsible for:
+
+- Fetching the catalog on boot (or walking a folder if no catalog is provided).
+- Lazy-loading individual topic Markdown on demand, with an LRU cache.
+- Resolving aliases and redirects declared in topic frontmatter.
+- Providing a keyword search API when `retold-keyword-index.json` is present.
+
+### TopicRenderer
+
+Transforms topic Markdown into HTML and injects it into the reading pane or tooltip view. Supports:
+
+- Frontmatter-driven title, category, and related-topic metadata.
+- Mermaid, code-highlighting, and KaTeX passes (same as `pict-docuserve`).
+- Template substitution for dynamic fields (e.g. the current entity name).
+
+### TooltipBinder
+
+Manages the relationship between DOM elements and topics. It observes the document for elements with `data-help` attributes, attaches hover/focus listeners, and shows a small popover tooltip driven by `TopicRenderer`. Uses the Pict MutationObserver wrapper so dynamically added elements get picked up automatically.
+
+### AutoTooltipGenerator
+
+Given a Manyfest descriptor, walks every hash in the descriptor and creates a synthetic topic key like `<manyfest-scope>/<hash>`. If a topic already exists, it is used as-is. If not, a stub is created in memory and -- in edit mode -- persisted back to the content service so an editor can fill it in from the running app.
+
+## Lifecycle
+
+1. **Bootstrap** -- The section registers with Pict and receives its config.
+2. **Catalog load** -- `TopicStore` fetches the catalog (or enumerates files).
+3. **Sidebar render** -- `SidebarView` renders the ToC from the catalog.
+4. **Route hook** -- If a route map is configured, the section subscribes to `pict-router` change events and asks `TopicRenderer` to render the current topic.
+5. **Tooltip binding** -- If `bindTooltipsAsync` has been called, every element in scope with `data-help` gets a tooltip.
+6. **Auto-generation** -- If `autoGenerateTooltipsAsync` has been called, the Manyfest hashes are walked and bindings applied.
+
+## Pict Content Assignment
+
+The section honors the Pict `Pict-Content-Assignment` override pattern: rendering goes through the section's assigned content target, so it works in the browser, in blessed/terminal Pict apps via `pict-terminalui`, and in unit tests via `Pict-Environment-Log`.
+
+## Security
+
+- Markdown is rendered with a safe allowlist; script tags and `javascript:` URLs are stripped.
+- Topic keys are validated against `^[a-z0-9][a-z0-9/-]*$` before being used as URL paths.
+- The optional edit-mode persistence path requires an explicit `EditEndpoint` and a bearer token; it will refuse to POST without both.