pict-section-form 1.1.0 → 1.1.2

package/example_applications/superhero_studio/SuperheroStudio-Example-Application.js

@@ -0,0 +1,313 @@
+/**
+ * SuperheroStudio-Example-Application.js
+ *
+ * The "Superhero Studio" — a pict-section-form showcase that exercises both
+ * new complex InputTypes in one place:
+ *
+ *   - RichText (origin story)   — markdown editor / rendered markdown
+ *   - Diagram  (portrait)       — Excalidraw / inline themed SVG
+ *
+ * Plus a bunch of stock inputs (Text, Number, Select, TextArea) so the form
+ * feels like a real character-sheet UI.
+ *
+ * A dropdown at the top loads one of five pre-baked superheroes — their
+ * stats, portraits, and origin stories all flow into the form via
+ * marshalDataFromAppDataToDynamicViews(). Try toggling the portrait or origin into
+ * edit mode and editing them — the rest of the form keeps working.
+ */
+
+const libPictApplication = require('pict-application');
+const libPictSectionForm = require('../../source/Pict-Section-Form.js');
+
+const libSuperheroes = require('./superheroes/Superheroes.js');
+
+// ----- Form manifest -------------------------------------------------------
+
+const _PowerOptions =
+[
+	{ id: 'Telepathy',           text: 'Telepathy'              },
+	{ id: 'Manifestation',       text: 'Manifestation'          },
+	{ id: 'Syntax Highlighting', text: 'Syntax Highlighting'    },
+	{ id: 'Z-Index Manipulation',text: 'Z-Index Manipulation'   },
+	{ id: 'Snap to Grid',        text: 'Snap to Grid'           },
+	{ id: 'Flight',              text: 'Flight'                 },
+	{ id: 'Super Strength',      text: 'Super Strength'         },
+	{ id: 'Invisibility',        text: 'Invisibility'           },
+	{ id: 'Time Travel',         text: 'Time Travel'            },
+	{ id: 'Pyrokinesis',         text: 'Pyrokinesis'            }
+];
+
+const _ColorOptions =
+[
+	{ id: 'Red',    text: 'Red'    },
+	{ id: 'Blue',   text: 'Blue'   },
+	{ id: 'Green',  text: 'Green'  },
+	{ id: 'Black',  text: 'Black'  },
+	{ id: 'Yellow', text: 'Yellow' },
+	{ id: 'Purple', text: 'Purple' }
+];
+
+const _Descriptors =
+{
+	// ---- Identity ----
+	'Name': {
+		Name: 'Name', Hash: 'Name', DataType: 'String',
+		PictForm: { Section: 'Identity', Row: 1, Width: 6, InputType: 'Text' }
+	},
+	'AlterEgo': {
+		Name: 'Alter Ego', Hash: 'AlterEgo', DataType: 'String',
+		PictForm: { Section: 'Identity', Row: 1, Width: 6, InputType: 'Text' }
+	},
+	'ShoeSize': {
+		Name: 'Shoe Size (US)', Hash: 'ShoeSize', DataType: 'Number',
+		PictForm: { Section: 'Identity', Row: 2, Width: 3, InputType: 'Number', Min: 1, Max: 22, Step: 0.5 }
+	},
+	'OriginYear': {
+		Name: 'Year of Origin', Hash: 'OriginYear', DataType: 'Number',
+		PictForm: { Section: 'Identity', Row: 2, Width: 3, InputType: 'Number', Min: 1900, Max: 2099 }
+	},
+	'CoffeeCupsPerDay': {
+		Name: 'Coffee Cups / Day', Hash: 'CoffeeCupsPerDay', DataType: 'Number',
+		PictForm: { Section: 'Identity', Row: 2, Width: 3, InputType: 'Number', Min: 0, Max: 99 }
+	},
+	'NumberOfSidekicks': {
+		Name: 'Active Sidekicks', Hash: 'NumberOfSidekicks', DataType: 'Number',
+		PictForm: { Section: 'Identity', Row: 2, Width: 3, InputType: 'Number', Min: 0, Max: 99 }
+	},
+
+	// ---- Powers ----
+	'PowerLevel': {
+		Name: 'Power Level (1–10)', Hash: 'PowerLevel', DataType: 'Number',
+		PictForm: { Section: 'Powers', Row: 1, Width: 3, InputType: 'Number', Min: 1, Max: 10 }
+	},
+	'PrimaryPower': {
+		Name: 'Primary Power', Hash: 'PrimaryPower', DataType: 'String',
+		PictForm: { Section: 'Powers', Row: 1, Width: 5, InputType: 'Option', SelectOptions: _PowerOptions }
+	},
+	'ThemeColor': {
+		Name: 'Theme Color', Hash: 'ThemeColor', DataType: 'String',
+		PictForm: { Section: 'Powers', Row: 1, Width: 4, InputType: 'Option', SelectOptions: _ColorOptions }
+	},
+	'Weakness': {
+		Name: 'Known Weakness', Hash: 'Weakness', DataType: 'String',
+		PictForm: { Section: 'Powers', Row: 2, Width: 6, InputType: 'Text' }
+	},
+	'FavoriteSnack': {
+		Name: 'Favorite Snack', Hash: 'FavoriteSnack', DataType: 'String',
+		PictForm: { Section: 'Powers', Row: 2, Width: 6, InputType: 'Text' }
+	},
+	'Catchphrase': {
+		Name: 'Signature Catchphrase', Hash: 'Catchphrase', DataType: 'String',
+		PictForm: { Section: 'Powers', Row: 3, Width: 12, InputType: 'TextArea', TextAreaRows: 2 }
+	},
+
+	// ---- Portrait (Diagram InputType) ----
+	'Portrait': {
+		Name: 'Portrait', Hash: 'Portrait', DataType: 'String',
+		PictForm:
+		{
+			Section: 'Portrait', Row: 1, Width: 12,
+			InputType: 'Diagram',
+			Diagram:
+			{
+				ThemeColors:          true,
+				Height:               '320px',
+				EditorImplementation: 'react'
+			}
+		}
+	},
+
+	// ---- Origin Story (RichText InputType) ----
+	'OriginStory': {
+		Name: 'Origin Story', Hash: 'OriginStory', DataType: 'String',
+		PictForm:
+		{
+			Section: 'OriginStory', Row: 1, Width: 12,
+			InputType: 'RichText',
+			RichText:
+			{
+				AllowImages:   true,
+				ImageUploader: 'uploadImage',
+				Height:        '380px'
+			}
+		}
+	}
+};
+
+const _FormManifest =
+{
+	Scope: 'SuperheroForm',
+	Sections:
+	[
+		{ Hash: 'Identity',    Name: 'Identity'      },
+		{ Hash: 'Powers',      Name: 'Powers & Loadout' },
+		{ Hash: 'Portrait',    Name: 'Portrait'      },
+		{ Hash: 'OriginStory', Name: 'Origin Story'  }
+	],
+	Descriptors: _Descriptors
+};
+
+// ----- Application ---------------------------------------------------------
+
+class SuperheroStudioApplication extends libPictSectionForm.PictFormApplication
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		// Register the RichText input provider (from pict-section-markdowneditor).
+		// Both complex InputType providers live in pict-section-form. The heavy
+		// editor deps (markdowneditor → CodeMirror, excalidraw → vendor bundle)
+		// lazy-load on the first setMode('edit'), so this view-by-default form
+		// pays for neither editor at boot.
+		let libRichTextInput = libPictSectionForm.RichTextInput;
+		this.pict.addProvider(
+			libRichTextInput.default_configuration.ProviderIdentifier,
+			libRichTextInput.default_configuration,
+			libRichTextInput);
+
+		let libDiagramInput = libPictSectionForm.DiagramInput;
+		this.pict.addProvider(
+			libDiagramInput.default_configuration.ProviderIdentifier,
+			libDiagramInput.default_configuration,
+			libDiagramInput);
+
+		// Seed with the first hero so the form has data on load.
+		this._currentHeroSlug = 'captain-verbose';
+		this.pict.AppData.SuperheroForm =
+			JSON.parse(JSON.stringify(libSuperheroes[this._currentHeroSlug]));
+	}
+
+	onAfterInitializeAsync(fCallback)
+	{
+		// Point the form metacontroller at our AppData branch BEFORE super so
+		// the initial render reads from the right place.
+		if (this.pict.views.PictFormMetacontroller)
+		{
+			this.pict.views.PictFormMetacontroller.viewMarshalDestination = 'AppData.SuperheroForm';
+		}
+		super.onAfterInitializeAsync(() =>
+		{
+			try { this.marshalDataFromAppDataToDynamicViews(); }
+			catch (pErr) { if (this.log) this.log.warn('[superhero_studio] initial marshal failed', { error: pErr.message }); }
+			return fCallback();
+		});
+	}
+
+	// -----------------------------------------------------------------
+	// Dropdown / page handlers (called from index.html inline onclick)
+	// -----------------------------------------------------------------
+
+	demo_loadHero(pSlug)
+	{
+		let tmpHero = libSuperheroes[pSlug];
+		if (!tmpHero) return;
+		this._currentHeroSlug = pSlug;
+
+		// Tear down any currently-open editor instances so the swap doesn't
+		// leave a stale CodeMirror/Excalidraw painting yesterday's hero.
+		this._foldAllEditors();
+
+		// Replace the form's source-of-truth record.
+		this.pict.AppData.SuperheroForm = JSON.parse(JSON.stringify(tmpHero));
+
+		// Push the new record into the rendered form.
+		try { this.marshalDataFromAppDataToDynamicViews(); }
+		catch (pErr) { if (this.log) this.log.warn('[superhero_studio] marshal failed', { error: pErr.message }); }
+
+		this._refreshToggleLabels();
+	}
+
+	demo_toggleMode(pInputHash)
+	{
+		let tmpProvider = this._providerForInput(pInputHash);
+		if (!tmpProvider) return;
+		tmpProvider.toggleMode(pInputHash, (pErr) =>
+		{
+			if (pErr && this.log) this.log.warn('[superhero_studio] toggleMode error',
+				{ error: pErr.message, inputHash: pInputHash });
+			this._refreshToggleLabels();
+		});
+	}
+
+	/**
+	 * Demo image uploader for the RichText origin-story field. In a real app
+	 * this would POST to your image-storage endpoint and call back with the
+	 * permanent URL. Here we mint a fake CDN URL after a brief delay.
+	 */
+	uploadImage(pFile, pInputDescriptor, fCallback)
+	{
+		setTimeout(() =>
+		{
+			let tmpFakeURL = '/uploads/heroes/' + Date.now() + '-' +
+				(pFile.name || 'image.png').replace(/[^A-Za-z0-9._-]/g, '_');
+			fCallback(null, tmpFakeURL);
+			if (this.log) this.log.info('[superhero_studio] uploadImage resolved', { url: tmpFakeURL });
+		}, 600);
+		return true;
+	}
+
+	// -----------------------------------------------------------------
+	// Internals
+	// -----------------------------------------------------------------
+
+	_providerForInput(pInputHash)
+	{
+		let tmpDescriptor = _Descriptors[pInputHash];
+		if (!tmpDescriptor) return null;
+		let tmpType = tmpDescriptor.PictForm && tmpDescriptor.PictForm.InputType;
+		if (tmpType === 'RichText') return this.pict.providers['Pict-Input-RichText'];
+		if (tmpType === 'Diagram')  return this.pict.providers['Pict-Input-Diagram'];
+		return null;
+	}
+
+	_foldAllEditors()
+	{
+		let tmpHashes = ['Portrait', 'OriginStory'];
+		for (let i = 0; i < tmpHashes.length; i++)
+		{
+			let tmpProvider = this._providerForInput(tmpHashes[i]);
+			if (tmpProvider && tmpProvider.getMode(tmpHashes[i]) === 'edit')
+			{
+				try { tmpProvider.setMode(tmpHashes[i], 'view', () => {}); }
+				catch (pErr) { /* swallow — happens if not yet mounted */ }
+			}
+		}
+	}
+
+	_refreshToggleLabels()
+	{
+		if (typeof document === 'undefined') return;
+		let tmpHashes = ['Portrait', 'OriginStory'];
+		for (let i = 0; i < tmpHashes.length; i++)
+		{
+			let tmpHash = tmpHashes[i];
+			let tmpProvider = this._providerForInput(tmpHash);
+			let tmpBtn = document.getElementById('toggle-' + tmpHash);
+			if (!tmpBtn) continue;
+			let tmpMode = tmpProvider ? tmpProvider.getMode(tmpHash) : null;
+			tmpBtn.textContent = (tmpMode === 'edit') ? 'Done' : 'Edit';
+		}
+	}
+}
+
+module.exports = SuperheroStudioApplication;
+
+// Extend the parent's default_configuration so MainViewportViewIdentifier
+// (= "PictFormMetacontroller") survives — without it the form has no
+// auto-render target and the page comes up blank.
+module.exports.default_configuration = Object.assign({},
+	libPictSectionForm.PictFormApplication.default_configuration,
+	{
+		Name: 'Superhero Studio',
+		Hash: 'SuperheroStudio',
+		pict_configuration:
+		{
+			Product: 'SuperheroStudio-Example',
+			DefaultFormManifest: _FormManifest
+		}
+	});
+
+// Expose the slug list so the HTML dropdown can render its options dynamically.
+module.exports.HeroSlugs = Object.keys(libSuperheroes);
+module.exports.Heroes    = libSuperheroes;

package/example_applications/superhero_studio/html/index.html

@@ -0,0 +1,166 @@
+<!doctype html>
+<html lang="en">
+<head>
+	<meta charset="utf-8">
+	<meta name="viewport" content="width=device-width, initial-scale=1">
+	<title>Superhero Studio — Pict Example</title>
+
+	<style id="PICT-CSS"></style>
+	<style id="diagram-theme">
+		:root
+		{
+			--diagram-ink:        #1B1F23;
+			--diagram-paper:      #FDFCF7;
+			--diagram-accent:     #E66C2C;
+			--diagram-highlight:  #FFD966;
+			--diagram-deemphasis: #A0A0A0;
+			--diagram-link:       #2E7D74;
+		}
+	</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: #F4F1ED; 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: 1.6rem 2rem 4rem; max-width: 1080px; margin: 0 auto; }
+
+		.hero-bar
+		{
+			background: #FFFFFF; border: 1px solid #D4C4A8; border-radius: 8px;
+			padding: 16px 20px; margin-bottom: 22px;
+			display: flex; flex-wrap: wrap; gap: 14px; align-items: center;
+			box-shadow: 0 1px 3px rgba(0,0,0,0.04);
+		}
+		.hero-bar label { font-size: 0.78rem; text-transform: uppercase; letter-spacing: 0.08em; color: #5A4A3C; font-weight: 600; }
+		.hero-bar select
+		{
+			padding: 6px 12px; border: 1px solid #D4C4A8; border-radius: 4px;
+			background: #FBF7EE; font-size: 0.95rem; min-width: 220px;
+		}
+		.hero-bar .theme-group { margin-left: auto; display: flex; gap: 8px; align-items: center; }
+		.hero-bar .swatch
+		{
+			width: 22px; height: 22px; border-radius: 4px; cursor: pointer;
+			border: 2px solid rgba(0,0,0,0.1); transition: transform 0.08s ease;
+		}
+		.hero-bar .swatch:hover { transform: scale(1.1); border-color: #2E7D74; }
+
+		.field-action-bar
+		{
+			display: flex; align-items: center; gap: 10px;
+			margin-top: -8px; margin-bottom: 12px; padding: 0 4px;
+		}
+		.field-action-bar button
+		{
+			padding: 4px 12px; font-size: 0.78rem; font-weight: 600;
+			color: #FAEDCD; background: #264653; border: none; border-radius: 4px;
+			cursor: pointer;
+		}
+		.field-action-bar button:hover { background: #E76F51; }
+		.field-action-bar .hint { font-size: 0.72rem; color: #8A7F72; }
+
+		#Pict-Form-Container
+		{
+			background: #FFFFFF; border: 1px solid #D4C4A8; border-radius: 8px;
+			padding: 24px 26px; box-shadow: 0 1px 3px rgba(0,0,0,0.04);
+		}
+
+		.notes
+		{
+			margin-top: 24px; padding: 14px 18px;
+			background: #FFF8E7; border-left: 3px solid #E9C46A; border-radius: 4px;
+			font-size: 0.85rem; color: #5A4A3C;
+		}
+		.notes strong { color: #2A2520; }
+		.notes code { font-family: 'SFMono-Regular', Menlo, monospace; background: #F0E8DA; padding: 1px 5px; border-radius: 3px; font-size: 0.9em; }
+	</style>
+</head>
+<body>
+	<header class="pict-example-header">
+		<span class="pict-example-badge">Pict Example</span>
+		<span class="pict-example-app-name">Superhero Studio</span>
+		<span class="pict-example-module">pict-section-excalidraw &times; pict-section-markdowneditor</span>
+	</header>
+
+	<main class="page-content">
+		<div class="hero-bar">
+			<label for="hero-select">Load Superhero</label>
+			<select id="hero-select" onchange="_Pict.PictApplication.demo_loadHero(this.value)">
+				<option value="captain-verbose">Captain Verbose</option>
+				<option value="the-notebook">The Notebook</option>
+				<option value="markdown-marauder">Markdown Marauder</option>
+				<option value="the-modal-avenger">The Modal Avenger</option>
+				<option value="vector-vince">Vector Vince</option>
+			</select>
+
+			<div class="theme-group">
+				<span style="font-size:0.78rem; text-transform:uppercase; letter-spacing:0.08em; color:#5A4A3C; font-weight:600;">Portrait theme</span>
+				<span class="swatch" title="Notebook"  style="background:#FDFCF7; border-color:#1B1F23;" onclick="window.applyTheme('notebook')"></span>
+				<span class="swatch" title="Dark"      style="background:#1B1F23;" onclick="window.applyTheme('dark')"></span>
+				<span class="swatch" title="Blueprint" style="background:#5DA9E9;" onclick="window.applyTheme('blueprint')"></span>
+				<span class="swatch" title="Sepia"     style="background:#B08968;" onclick="window.applyTheme('sepia')"></span>
+			</div>
+		</div>
+
+		<div class="field-action-bar">
+			<button id="toggle-Portrait" onclick="_Pict.PictApplication.demo_toggleMode('Portrait')">Edit</button>
+			<span class="hint">Toggle the Portrait field into Excalidraw — first click lazy-loads the editor bundle.</span>
+
+			<button id="toggle-OriginStory" onclick="_Pict.PictApplication.demo_toggleMode('OriginStory')" style="margin-left:18px;">Edit</button>
+			<span class="hint">Toggle the Origin Story field into the markdown editor.</span>
+		</div>
+
+		<div id="Pict-Form-Container"></div>
+
+		<div class="notes">
+			<strong>What's happening:</strong>
+			Stock inputs (<code>Text</code>, <code>Number</code>, <code>Option</code>, <code>TextArea</code>) sit next to two complex InputTypes —
+			<code>Diagram</code> (Portrait) and <code>RichText</code> (Origin Story) — in the same form, all driven by the same
+			<code>marshalDataFromAppDataToView</code> pipeline. The portrait SVGs use <code>var(--diagram-ink, …)</code> with hex fallbacks,
+			so swapping the theme swatches recolors them live without re-rendering. Loading a new hero from the dropdown folds any open editors back
+			into view mode first, so the swap doesn't strand CodeMirror or Excalidraw on yesterday's character.
+		</div>
+	</main>
+
+	<link rel="stylesheet" href="./excalidraw-wrapper.css">
+	<script src="./pict.min.js"></script>
+	<!-- Excalidraw vendor bundle (React + Excalidraw). The Diagram InputType
+	     looks for window.PictSectionExcalidrawVendor when the Portrait field
+	     flips to edit; without these tags Excalidraw won't mount. -->
+	<script src="./react-vendor.min.js"></script>
+	<script src="./excalidraw-wrapper.min.js"></script>
+	<script src="./superhero_studio_example.min.js"></script>
+	<script>
+		const _Themes =
+		{
+			notebook:  { ink:'#1B1F23', paper:'#FDFCF7', accent:'#E66C2C', highlight:'#FFD966', deemphasis:'#A0A0A0', link:'#2E7D74' },
+			dark:      { ink:'#EAEAEA', paper:'#1B1F23', accent:'#FFB570', highlight:'#FFD966', deemphasis:'#666666', link:'#7FC4BD' },
+			blueprint: { ink:'#08296B', paper:'#E5F0FB', accent:'#5DA9E9', highlight:'#F4D35E', deemphasis:'#8AA3B6', link:'#1F77B4' },
+			sepia:     { ink:'#3D2B1F', paper:'#F1E3C9', accent:'#B07043', highlight:'#E2C58B', deemphasis:'#A48A6E', link:'#7A5A36' }
+		};
+		window.applyTheme = function(pName)
+		{
+			let tmpStyle = document.getElementById('diagram-theme');
+			let tmpT = _Themes[pName] || _Themes.notebook;
+			tmpStyle.textContent =
+				':root { ' +
+				'--diagram-ink:'        + tmpT.ink        + ';' +
+				'--diagram-paper:'      + tmpT.paper      + ';' +
+				'--diagram-accent:'     + tmpT.accent     + ';' +
+				'--diagram-highlight:'  + tmpT.highlight  + ';' +
+				'--diagram-deemphasis:' + tmpT.deemphasis + ';' +
+				'--diagram-link:'       + tmpT.link       + ';' +
+				' }';
+		};
+
+		Pict.safeOnDocumentReady(() =>
+		{
+			Pict.safeLoadPictApplication(window.SuperheroStudioExample, 1);
+		});
+	</script>
+</body>
+</html>

package/example_applications/superhero_studio/package.json

@@ -0,0 +1,29 @@
+{
+	"name": "superhero_studio_example",
+	"version": "1.0.0",
+	"description": "Pict-section-form showcase that exercises both new complex InputTypes (RichText for the origin story, Diagram for the portrait) inside a superhero character-sheet form.",
+	"main": "SuperheroStudio-Example-Application.js",
+	"scripts": {
+		"start": "node SuperheroStudio-Example-Application.js",
+		"build": "npx quack build && npx quack copy"
+	},
+	"author": "steven velozo <steven@velozo.com>",
+	"license": "MIT",
+	"devDependencies": {},
+	"copyFilesSettings": {
+		"whenFileExists": "overwrite"
+	},
+	"copyFiles": [
+		{ "from": "./html/*",                                                            "to": "./dist/" },
+		{ "from": "../../node_modules/pict/dist/*",                                      "to": "./dist/" },
+		{ "from": "../../node_modules/pict-section-excalidraw/vendor/excalidraw-built/*", "to": "./dist/" }
+	],
+	"retold": {
+		"ExampleApplication": {
+			"Stage": true,
+			"Title": "Superhero Studio",
+			"Summary": "A character-sheet form that combines both new complex InputTypes — RichText for the origin story (markdown editor + rendered view) and Diagram for the portrait (Excalidraw + inline themed SVG) — alongside stock inputs (Text, Number, Option, TextArea). A dropdown at the top loads five hand-drawn superheroes; each one's portrait recolors when you swap themes. Boots in view-mode, edit on demand.",
+			"Complexity": "Advanced"
+		}
+	}
+}