pict-section-form 1.1.0 → 1.1.2

package/docs/examples/richtext_form/README.md

@@ -0,0 +1,132 @@
+# RichText Form Input
+
+<!-- docuserve:example-launch:start -->
+> **[Launch the live app](examples/richtext%5Fform/index.html)** - runs in your browser, opens in a new tab.
+<!-- docuserve:example-launch:end -->
+
+**RichText Form Input** is the smallest demonstration of the new
+`RichText` InputType: a pict-section-form with one field whose provider
+pairs this module's markdown editor (edit mode) with rendered markdown
+(view mode). Boots in view mode — no CodeMirror loaded until the first
+toggle. Demonstrates the pluggable image-uploader hook in two flavors.
+
+The `RichText` InputType + its provider class live in **pict-section-form**
+(see [the Input Type doc](https://fable-retold.github.io/pict-section-form/#/page/input%5Fproviders/014-rich-text)).
+The provider lazy-requires this module on the first edit toggle — that's why
+the heavy CodeMirror bundle isn't fetched at boot.
+
+For the same InputType inside a richer character-sheet form alongside
+stock inputs and a Diagram, see
+[Superhero Studio](../superhero%5Fstudio/README.md)
+in the pict-section-excalidraw sister module.
+
+## What it demonstrates
+
+| Capability | Where you see it |
+|------------|------------------|
+| `Pict-Input-RichText` provider registration | One `pict.addProvider(...)` call wires the InputType into the form |
+| Per-field runtime mode toggle | `provider.toggleMode('Body', cb)` flips view ↔ edit; the editor bundle lazy-loads on the first edit |
+| View-mode rendered markdown | `pict-section-content` renders headings, lists, code blocks, blockquotes into the slot — no editor present |
+| `AllowImages: false` rejection | The checkbox toggles this off live; pasting an image surfaces a rejection rather than inserting a half-baked data URI |
+| Pluggable `ImageUploader` | Pasting with the uploader on calls `pict.PictApplication.uploadImage(file, descriptor, cb)`; turning it off falls through to default base64 inline |
+
+## Key files
+
+- `RichTextForm-Example-Application.js` — the app. Registers the RichText input provider, defines a one-field form manifest, stubs `uploadImage`, and exposes the mode-toggle + AllowImages-toggle controls.
+- `html/index.html` — page chrome: the Edit/Done toggle, two checkboxes (`AllowImages` and `Use ImageUploader stub`), and the form container.
+
+## The form descriptor
+
+```javascript
+'Body': {
+    Name:     'Body',
+    Hash:     'Body',
+    DataType: 'String',
+    PictForm:
+    {
+        Section:   'Article',
+        Row:       1,
+        Width:     12,
+        InputType: 'RichText',
+        RichText:
+        {
+            AllowImages:   true,
+            ImageUploader: 'uploadImage',  // method name on pict.PictApplication
+            Height:        '320px'
+        }
+    }
+}
+```
+
+The provider auto-injects its templates into pict-section-form's `DynamicTemplates` registry on construction, so the form's render path finds `*-Template-Input-InputType-RichText` and emits the standard hidden input + display slot.
+
+## Feature 1 — View-by-default with lazy editor mount
+
+On page load, the field's value is parsed as markdown and written into the slot — that's it. Inspect the DevTools Network tab: no `vendor`-side or `codemirror`-side requests fire.
+
+The first time the user clicks Edit, `provider.setMode('Body', 'edit', cb)` runs:
+
+1. Tear down view-mode DOM (clear the slot).
+2. Instantiate a subclass of `Pict-Section-MarkdownEditor` with `TargetElementAddress` pointing at the slot.
+3. Seed it with the value the provider was last holding for this hash.
+4. Wire `onContentChange(segmentIndex, content)` so every keystroke writes through to the form's hidden `<input>` (and dispatches a `change` event so Informary updates AppData).
+
+Clicking Done calls `setMode('Body', 'view', cb)`: the editor is destroyed, the slot is re-rendered from the latest value. The hidden input keeps the user's content across the toggle.
+
+## Feature 2 — `AllowImages: false` rejection
+
+The provider subclass overrides `onImageUpload(file, segmentIndex, cb)`:
+
+```javascript
+onImageUpload(pFile, pSegmentIndex, fImgCallback)
+{
+    if (!tmpRichTextOpts.AllowImages)
+    {
+        fImgCallback('Image uploads are disabled for this field.');
+        return true;   // claim the upload so the editor doesn't fall through
+    }
+    // ... uploader dispatch below
+}
+```
+
+Returning `true` and calling `fCallback(errMessage)` tells the editor "I handled this — and I refused it." No half-baked data URI ends up in the markdown. Toggle the page checkbox to see the live difference.
+
+## Feature 3 — Pluggable `ImageUploader`
+
+When `AllowImages: true` AND `ImageUploader` is set, the provider dispatches the file to `pict.PictApplication[name](pFile, pInputDescriptor, fCallback)`:
+
+```javascript
+uploadImage(pFile, pInputDescriptor, fCallback)
+{
+    setTimeout(() =>
+    {
+        let tmpFakeURL = '/uploads/' + Date.now() + '-' + pFile.name.replace(/[^A-Za-z0-9._-]/g, '_');
+        fCallback(null, tmpFakeURL);
+    }, 600);
+    return true;
+}
+```
+
+The 600 ms `setTimeout` mimics a real upload round-trip. A production app would POST the file to its storage endpoint and call back with the permanent URL. With the page checkbox set to "off", the stub returns `false`, which tells the underlying editor "fall through to default" — and the default is `FileReader` → base64 data URI inline. Toggle and confirm.
+
+## Running the example
+
+```sh
+cd modules/pict/pict-section-form/example_applications/richtext_form
+npm install
+npx quack build && npx quack copy
+open dist/index.html
+```
+
+## Takeaways
+
+1. **The provider is the only registration step.** Once it's added to the Pict instance, every form on the instance can use `InputType: 'RichText'`.
+2. **Image handling is the host's contract.** Three knobs cover the realistic cases: forbid (`AllowImages: false`), accept and embed (`AllowImages: true`, no uploader), accept and store remotely (`AllowImages: true`, `ImageUploader: '<name>'`).
+3. **View-mode performance is free.** A form full of read-only RichText fields never touches CodeMirror until the user starts editing.
+
+## Related documentation
+
+- [pict-section-markdowneditor API Reference ↗](https://fable-retold.github.io/pict-section-markdowneditor/#/page/api) — the markdown editor's public surface, on which the input provider depends.
+- [pict-section-markdowneditor / Image Upload ↗](https://fable-retold.github.io/pict-section-markdowneditor/#/page/image%5Fupload) — the full `onImageUpload` contract (this is what `ImageUploader` proxies through).
+- [Server Upload ↗](https://fable-retold.github.io/pict-section-markdowneditor/#/page/examples/server%5Fupload/README) — the editor's `onImageUpload` hook wired to a real Orator backend; useful when you want to build a real `ImageUploader` for the form provider.
+- [Superhero Studio](../superhero%5Fstudio/README.md) — the RichText InputType inside a fuller form, alongside a Diagram InputType.

package/docs/examples/richtext_form/index.html

@@ -0,0 +1,82 @@
+<!doctype html>
+<html lang="en">
+<head>
+	<meta charset="utf-8">
+	<meta name="viewport" content="width=device-width, initial-scale=1">
+	<title>RichText Form Input — Pict Example</title>
+
+	<style id="PICT-CSS"></style>
+	<style>
+		*, *::before, *::after { box-sizing: border-box; }
+		body { margin: 0; padding: 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; background: #FAF8F4; color: #2A2520; }
+
+		.pict-example-header { display: flex; align-items: stretch; background: #264653; border-bottom: 3px solid #E76F51; }
+		.pict-example-badge { background: #E76F51; color: #FAEDCD; padding: 0.6rem 1rem; font-size: 0.72rem; font-weight: 800; text-transform: uppercase; letter-spacing: 0.1em; }
+		.pict-example-app-name { padding: 0.6rem 1rem; color: #FAEDCD; font-size: 1.1rem; font-weight: 600; }
+		.pict-example-module { margin-left: auto; padding: 0.6rem 1rem; color: #D4A373; font-size: 0.75rem; letter-spacing: 0.03em; align-self: center; }
+
+		.page-content { padding: 2rem; max-width: 920px; margin: 0 auto; }
+		.intro { color: #5A4A3C; font-size: 0.9rem; line-height: 1.6; margin-bottom: 24px; }
+		.intro code { background: #F0E8DA; padding: 1px 6px; border-radius: 3px; font-family: 'SFMono-Regular', Menlo, monospace; font-size: 0.85em; }
+
+		.controls { background: #FFFFFF; border: 1px solid #D4C4A8; border-radius: 6px; padding: 14px 16px; margin-bottom: 20px; display: flex; flex-wrap: wrap; gap: 16px; align-items: center; font-size: 0.85rem; }
+		.controls label { display: flex; align-items: center; gap: 6px; cursor: pointer; }
+		.controls button { padding: 6px 14px; font-size: 0.85rem; font-weight: 600; color: #FAEDCD; background: #264653; border: none; border-radius: 4px; cursor: pointer; }
+		.controls button:hover { background: #E76F51; }
+
+		#Pict-Form-Container { background: #FFFFFF; border: 1px solid #D4C4A8; border-radius: 6px; padding: 20px; }
+
+		/* The form has one section + one input. */
+		.notes { margin-top: 24px; padding: 14px 16px; background: #FFF8E7; border-left: 3px solid #E9C46A; border-radius: 3px; font-size: 0.82rem; color: #5A4A3C; }
+		.notes strong { color: #2A2520; }
+	</style>
+</head>
+<body>
+	<header class="pict-example-header">
+		<span class="pict-example-badge">Pict Example</span>
+		<span class="pict-example-app-name">RichText Form Input</span>
+		<span class="pict-example-module">pict-section-markdowneditor</span>
+	</header>
+
+	<main class="page-content">
+		<p class="intro">
+			A pict-section-form field whose <code>InputType</code> is <code>RichText</code>. Boots in
+			<strong>view</strong> mode — just rendered markdown, no CodeMirror loaded. Click <em>Edit</em>
+			to flip into the editor (lazy-loads the markdown editor bundle on first toggle).
+		</p>
+
+		<div class="controls">
+			<button id="toggle-Body" onclick="_Pict.PictApplication.demo_toggleMode('Body')">Edit</button>
+
+			<label>
+				<input type="checkbox" id="allow-images" checked onchange="_Pict.PictApplication.demo_setAllowImages('Body', this.checked)">
+				Allow image paste
+			</label>
+
+			<label>
+				<input type="checkbox" id="use-uploader" checked onchange="_Pict.PictApplication.demo_setUploaderEnabled(this.checked)">
+				Use ImageUploader stub
+				<span style="color:#8A7F72; margin-left:6px; font-size:0.75rem;">(off = base64 inline)</span>
+			</label>
+		</div>
+
+		<div id="Pict-Form-Container"></div>
+
+		<div class="notes">
+			<strong>Verifying:</strong>
+			Open DevTools → Network. With <em>Edit</em> never clicked, no CodeMirror request fires. Click <em>Edit</em>
+			once and the markdown-editor bundle loads. Click <em>Done</em> to return to view mode — the editor view
+			is torn down, but its content lives in the field's hidden form input.
+		</div>
+	</main>
+
+	<script src="https://cdn.jsdelivr.net/npm/pict@1/dist/pict.min.js"></script>
+	<script src="./richtext_form_example.min.js"></script>
+	<script>
+		Pict.safeOnDocumentReady(() =>
+		{
+			Pict.safeLoadPictApplication(window.RichtextFormExample || window.RichTextFormExample, 1);
+		});
+	</script>
+</body>
+</html>