@stll/folio-core 0.59.0 → 0.60.0

package/dist/prosemirror/plugins/templatePreviewValues.js

@@ -1,8 +1,32 @@
+import { createPluginKeyOwner } from "../pluginKeyOwner.js";
 import { scanDirectives } from "./templateDirectives.js";
-import { Plugin, PluginKey } from "prosemirror-state";
+import { Plugin } from "prosemirror-state";
 import { Decoration, DecorationSet } from "prosemirror-view";
 import { isFieldPath } from "@stll/template-conditions";
 //#region src/prosemirror/plugins/templatePreviewValues.ts
+/**
+* Template Preview Values Plugin
+*
+* Live fill preview for template documents: given a map of field path →
+* typed value, every matching `{{path}}` marker is visually replaced by
+* the value — the marker text is hidden by an inline decoration and the
+* value is injected as a widget in its place. The document itself is
+* never modified; clearing the preview restores the markers.
+*
+* The same preview hides conditional blocks the host reports as not
+* applying: `conditions` maps an `{% if expr %}` expression to whether
+* its block applies, and a `false` block is hidden from its opener
+* through its `{% endif %}`. folio evaluates no expression.
+*
+* Two render modes: `highlighted` paints the substituted values with the
+* preview accent so it is unmistakably a preview, and keeps every
+* directive tag visible; `plain` renders the values as ordinary text and
+* drops the tag paragraphs of a block the host has ruled on, so it
+* approximates the generated document rather than the template.
+*
+* Updates are pushed via {@link setTemplatePreviewValues}; the host wires
+* this to its fill inputs.
+*/
 /** Concatenated plain text of a preview value. */
 const templatePreviewValueText = (value) => typeof value === "string" ? value : value.runs.map((run) => run.text).join("");
 /** Stable identity of a preview value (text + formatting), for decoration
@@ -26,9 +50,7 @@ const templatePreviewHidesWholeBlock = (range, block) => range.from <= block.pmS
 const ORIGINAL_CLASS = "folio-template-preview-original";
 /** Hides a conditional block the host reported as not applying. */
 const HIDDEN_CLASS = "folio-template-preview-hidden";
-const KEY_HOLDER_SYMBOL = Symbol.for("stll.folio.templatePreviewValuesKey");
-const keyHolder = globalThis;
-const templatePreviewValuesKey = keyHolder[KEY_HOLDER_SYMBOL] ?? (keyHolder[KEY_HOLDER_SYMBOL] = new PluginKey("templatePreviewValues"));
+const templatePreviewValuesKey = createPluginKeyOwner("templatePreviewValues");
 /** A rich span as DOM: text wrapped in `<em>` / `<strong>` per its flags. */
 function buildSpanNode(span) {
 	let node = document.createTextNode(span.text);
@@ -267,7 +289,7 @@ function buildDecorationSet(doc, { entries, hidden }, mode) {
 }
 function createTemplatePreviewValuesPlugin() {
 	return new Plugin({
-		key: templatePreviewValuesKey,
+		key: templatePreviewValuesKey.createKey(),
 		state: {
 			init() {
 				return {

package/dist/prosemirror/plugins/templateSlashMenu.d.ts

@@ -1,4 +1,4 @@
-import { EditorState, Plugin, PluginKey, Transaction } from "prosemirror-state";
+import { EditorState, Plugin, Transaction } from "prosemirror-state";
 //#region src/prosemirror/plugins/templateSlashMenu.d.ts
 type TemplateSlashMenuState = {
   active: false;
@@ -34,7 +34,13 @@ type TemplateSlashMenuPluginOptions = {
    */
   onKeyAction?: (action: TemplateSlashMenuKeyAction) => boolean;
 };
-declare const templateSlashMenuKey: PluginKey<TemplateSlashMenuState>;
+declare const templateSlashMenuKey: Readonly<{
+  key: string;
+  createKey: () => import("prosemirror-state").PluginKey<TemplateSlashMenuState>;
+  owns: (plugin: Plugin<TemplateSlashMenuState>) => boolean;
+  get: (state: EditorState) => Plugin<TemplateSlashMenuState> | undefined;
+  getState: (state: EditorState) => TemplateSlashMenuState | undefined;
+}>;
 declare const templateSlashMenuPlugin: (options?: TemplateSlashMenuPluginOptions) => Plugin<TemplateSlashMenuState>;
 declare const getTemplateSlashMenu: (state: EditorState) => TemplateSlashMenuState;
 /** Clear the trigger. Set on the host's marker-insert transaction so the

package/dist/prosemirror/plugins/templateSlashMenu.js

@@ -1,6 +1,26 @@
+import { createPluginKeyOwner } from "../pluginKeyOwner.js";
 import { getTemplateDirectives } from "./templateDirectives.js";
-import { Plugin, PluginKey } from "prosemirror-state";
+import { Plugin } from "prosemirror-state";
 //#region src/prosemirror/plugins/templateSlashMenu.ts
+/**
+* Template slash-menu trigger plugin.
+*
+* Watches the template editor for a `/` typed at a marker boundary (start of a
+* text block or right after whitespace) and tracks the query the author types
+* after it. The plugin owns only the *trigger* state — `{active, from, query}` —
+* and the keyboard contract while active; the floating menu UI and the actual
+* marker insertion live in the host (template-studio), which subscribes via
+* {@link TemplateSlashMenuPluginOptions.onChange} and resolves keys via
+* {@link TemplateSlashMenuPluginOptions.onKeyAction}.
+*
+* The trigger guard is deliberately strict so the menu never misfires inside
+* ordinary legal prose: dates (`30/06`), `and/or`, and URLs all have a non-space
+* char before the `/`, so only a leading or post-whitespace `/` opens the menu.
+*
+* Insertion is host-driven: a doc-changing transaction the host dispatches to
+* insert the marker carries a `clear` meta so the plugin tears down without the
+* generic doc-change reset racing the host's selection move.
+*/
 const IDLE = {
 	active: false,
 	from: null,
@@ -8,9 +28,7 @@ const IDLE = {
 	query: ""
 };
 const QUERY_CHAR = /[\p{L}\p{N}_.-]/u;
-const KEY_HOLDER_SYMBOL = Symbol.for("stll.folio.templateSlashMenuKey");
-const keyHolder = globalThis;
-const templateSlashMenuKey = keyHolder[KEY_HOLDER_SYMBOL] ?? (keyHolder[KEY_HOLDER_SYMBOL] = new PluginKey("templateSlashMenu"));
+const templateSlashMenuKey = createPluginKeyOwner("templateSlashMenu");
 /** Whether the char immediately before `pos` is a marker boundary (start of the
 *  text block or whitespace). This is the misfire guard: a `/` mid-token (dates,
 *  URLs, and/or) has a word char before it and never opens the menu. */
@@ -78,7 +96,7 @@ const tryOpenTrigger = (view) => {
 };
 const templateSlashMenuPlugin = (options = {}) => {
 	return new Plugin({
-		key: templateSlashMenuKey,
+		key: templateSlashMenuKey.createKey(),
 		state: {
 			init: () => IDLE,
 			apply: (tr, value, _oldState, newState) => {

package/dist/prosemirror/plugins/transactionInvariants.js

@@ -1,9 +1,29 @@
 import { expectParagraphAttrs } from "../attrs/index.js";
 import { effectiveParagraphNumberingReference, paragraphNumberingSourcesFromBoundary } from "../numberingAttr.js";
+import { createPluginKeyOwner } from "../pluginKeyOwner.js";
 import { validateProseMirrorDocument } from "../validation.js";
 import { getDocumentNumbering, hasDocumentNumbering } from "./documentNumbering.js";
-import { Plugin, PluginKey } from "prosemirror-state";
+import { Plugin } from "prosemirror-state";
 //#region src/prosemirror/plugins/transactionInvariants.ts
+/**
+* Transaction invariants: a development and test aid that checks the editor
+* document after every transaction, so a command that leaves a document the
+* save path will refuse fails where it happens rather than at save.
+*
+* Off by default. {@link ExtensionManager} installs it when
+* `globalThis.__folioTransactionInvariants` is `{ enabled: true }` at the time
+* the runtime is initialized; the core test preload sets that flag, which turns
+* every editor test built on the extension manager into a validity check. A
+* host may set it in a development build. Production code never reads it
+* otherwise.
+*
+* The checks are the ones the document-model validator makes that the editor
+* state can answer on its own:
+* - the ProseMirror document is structurally valid (node and mark attributes,
+*   bookmark pairing), incrementally cached per node;
+* - every paragraph numbering reference names an instance the document's
+*   numbering defines.
+*/
 /** Whether new extension-manager runtimes install the invariant plugin. */
 const areTransactionInvariantsEnabled = () => globalThis.__folioTransactionInvariants?.enabled === true;
 const MAX_REPORTED_STEPS_LENGTH = 4e3;
@@ -69,14 +89,14 @@ const introducedIssues = (before, after, transactions) => {
 		return false;
 	});
 };
-const transactionInvariantsKey = new PluginKey("transactionInvariants");
+const transactionInvariantsKey = createPluginKeyOwner("transactionInvariants");
 /**
 * Throw a {@link TransactionInvariantError} naming the offending steps when a
 * document-changing transaction leaves the state with an issue it did not
 * have before.
 */
 const createTransactionInvariantPlugin = () => new Plugin({
-	key: transactionInvariantsKey,
+	key: transactionInvariantsKey.createKey(),
 	appendTransaction(transactions, oldState, newState) {
 		if (!transactions.some((transaction) => transaction.docChanged)) return null;
 		const issues = checkEditorStateInvariants(newState);

package/dist/utils/fontLoader.d.ts

@@ -9,8 +9,8 @@
  */
 /**
  * Mapping from common Office/system fonts to bundled Croscore equivalents.
- * The CSS @font-face aliases in font-aliases.css handle the visual mapping;
- * this map is used for font availability checks and preloading.
+ * The resolver supplies the visual fallback stack; this map is used for
+ * font availability checks and preloading.
  */
 declare const FONT_MAPPING: Record<string, string>;
 /**

package/dist/utils/fontLoader.js

@@ -13,8 +13,8 @@ const loadCallbacks = /* @__PURE__ */ new Set();
 let isLoadingAny = false;
 /**
 * Mapping from common Office/system fonts to bundled Croscore equivalents.
-* The CSS @font-face aliases in font-aliases.css handle the visual mapping;
-* this map is used for font availability checks and preloading.
+* The resolver supplies the visual fallback stack; this map is used for
+* font availability checks and preloading.
 */
 const FONT_MAPPING = {
 	Aptos: "Lato",
@@ -42,11 +42,6 @@ const BUNDLED_FONTS = /* @__PURE__ */ new Set([
 	"Cousine",
 	"Lato",
 	"Source Sans 3",
-	"Calibri",
-	"Cambria",
-	"Arial",
-	"Times New Roman",
-	"Courier New",
 	"Noto Sans Arabic"
 ]);
 /**

package/dist/utils/fontResolver.d.ts

@@ -46,8 +46,12 @@ declare function isCjkFont(family: string): boolean;
 declare const CJK_FALLBACK_FONT_FAMILY = "MS Mincho";
 declare const setGoogleFontsEnabled: (enabled: boolean) => void;
 declare const getGoogleFontsEnabled: () => boolean;
-declare const setEmbeddedFontFamilyMap: (map: ReadonlyMap<string, string> | null) => void;
-declare function resolveFontFamily(docxFontName: string, alternateFontName?: string): ResolvedFont;
+type FontResolutionOptions = {
+  alternateFontName?: string | undefined;
+  embeddedFontFamilyMap?: ReadonlyMap<string, string> | undefined;
+};
+/** Resolve against the calling editor's immutable embedded-font lookup. */
+declare function resolveFontFamily(docxFontName: string, options?: FontResolutionOptions): ResolvedFont;
 /**
  * Split a CSS `font-family` list built by `quoteFontName` back into family
  * names: the inverse of the quoting and escaping applied there. Quoted entries
@@ -93,4 +97,4 @@ declare function getGoogleFontEquivalent(docxFontName: string): string | null;
  */
 declare function hasGoogleFontEquivalent(docxFontName: string): boolean;
 //#endregion
-export { CJK_FALLBACK_FONT_FAMILY, DEFAULT_SINGLE_LINE_RATIO, ResolvedFont, buildFontFamilyString, getGoogleFontEquivalent, getGoogleFontsEnabled, getGoogleFontsToLoad, hasGoogleFontEquivalent, isCjkFont, parseFontFamilyList, resolveFontFamily, resolveThemeFont, setEmbeddedFontFamilyMap, setGoogleFontsEnabled };
+export { CJK_FALLBACK_FONT_FAMILY, DEFAULT_SINGLE_LINE_RATIO, ResolvedFont, buildFontFamilyString, getGoogleFontEquivalent, getGoogleFontsEnabled, getGoogleFontsToLoad, hasGoogleFontEquivalent, isCjkFont, parseFontFamilyList, resolveFontFamily, resolveThemeFont, setGoogleFontsEnabled };

package/dist/utils/fontResolver.js

@@ -1043,11 +1043,9 @@ const setGoogleFontsEnabled = (enabled) => {
 	googleFontsEnabled = enabled;
 };
 const getGoogleFontsEnabled = () => googleFontsEnabled;
-let embeddedFontFamilyMap = null;
-const setEmbeddedFontFamilyMap = (map) => {
-	embeddedFontFamilyMap = map;
-};
-function resolveFontFamily(docxFontName, alternateFontName) {
+/** Resolve against the calling editor's immutable embedded-font lookup. */
+function resolveFontFamily(docxFontName, options = {}) {
+	const { alternateFontName, embeddedFontFamilyMap } = options;
 	const normalizedName = docxFontName.trim().toLowerCase();
 	const scopedFamily = embeddedFontFamilyMap?.get(docxFontName) ?? null;
 	const aliasTarget = CJK_FONT_ALIASES[normalizedName];
@@ -1062,7 +1060,7 @@ function resolveFontFamily(docxFontName, alternateFontName) {
 			hasGoogleEquivalent: googleFontsEnabled,
 			singleLineRatio: mapping.singleLineRatio
 		};
-		const alternate = resolveFontFamily(alternateFontName);
+		const alternate = resolveFontFamily(alternateFontName, { embeddedFontFamilyMap });
 		const category = mapping.category;
 		const concreteStack = dedupeFontFamilies([
 			scopedFamily ?? docxFontName,
@@ -1080,7 +1078,7 @@ function resolveFontFamily(docxFontName, alternateFontName) {
 	}
 	const alternateName = alternateFontName?.trim();
 	if (alternateName && alternateName.toLowerCase() !== normalizedName) {
-		const alternate = resolveFontFamily(alternateName);
+		const alternate = resolveFontFamily(alternateName, { embeddedFontFamilyMap });
 		const category = detectFontCategory(docxFontName);
 		const concreteStack = dedupeFontFamilies([scopedFamily ?? docxFontName, ...parseFontFamilyList(alternate.cssFallback)]).filter((family) => !isCssGenericFontFamily(family));
 		return {
@@ -1258,4 +1256,4 @@ function hasGoogleFontEquivalent(docxFontName) {
 	return (CJK_FONT_ALIASES[normalizedName] ?? normalizedName) in FONT_MAPPINGS;
 }
 //#endregion
-export { CJK_FALLBACK_FONT_FAMILY, DEFAULT_SINGLE_LINE_RATIO, buildFontFamilyString, getGoogleFontEquivalent, getGoogleFontsEnabled, getGoogleFontsToLoad, hasGoogleFontEquivalent, isCjkFont, parseFontFamilyList, resolveFontFamily, resolveThemeFont, setEmbeddedFontFamilyMap, setGoogleFontsEnabled };
+export { CJK_FALLBACK_FONT_FAMILY, DEFAULT_SINGLE_LINE_RATIO, buildFontFamilyString, getGoogleFontEquivalent, getGoogleFontsEnabled, getGoogleFontsToLoad, hasGoogleFontEquivalent, isCjkFont, parseFontFamilyList, resolveFontFamily, resolveThemeFont, setGoogleFontsEnabled };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/folio-core",
-  "version": "0.59.0",
+  "version": "0.60.0",
   "description": "Headless, framework-neutral core of folio: the OOXML (.docx) parser, document model, ProseMirror integration, and page-layout engine. No React.",
   "keywords": [
     "document-model",
@@ -146,7 +146,7 @@
     "perf": "bun scripts/profile-editor.ts"
   },
   "dependencies": {
-    "@stll/docx-core": "^0.36.3",
+    "@stll/docx-core": "^0.37.0",
     "@stll/docx-utils": "^0.1.0",
     "@stll/template-conditions": "^0.6.2",
     "better-result": "3.0.1",
@@ -155,6 +155,13 @@
     "fast-xml-parser": "^5.10.1",
     "hyphen": "1.14.1",
     "jszip": "3.10.2",
+    "utif2": "^4.1.0",
+    "valibot": "1.5.0"
+  },
+  "devDependencies": {
+    "@fontsource/noto-sans-devanagari": "^5.3.0",
+    "@fontsource/noto-sans-hebrew": "^5.3.0",
+    "@types/hyphen": "1.14.0",
     "prosemirror-commands": "^1.7.1",
     "prosemirror-dropcursor": "^1.8.2",
     "prosemirror-gapcursor": "^1.4.1",
@@ -166,16 +173,25 @@
     "prosemirror-tables": "^1.8.5",
     "prosemirror-transform": "^1.12.0",
     "prosemirror-view": "^1.42.6",
-    "utif2": "^4.1.0",
-    "valibot": "1.5.0",
     "y-prosemirror": "^1.3.7",
     "y-protocols": "^1.0.6",
     "yjs": "^13.6.31"
   },
-  "devDependencies": {
-    "@fontsource/noto-sans-devanagari": "^5.3.0",
-    "@fontsource/noto-sans-hebrew": "^5.3.0",
-    "@types/hyphen": "1.14.0"
+  "peerDependencies": {
+    "prosemirror-commands": "^1.7.1",
+    "prosemirror-dropcursor": "^1.8.2",
+    "prosemirror-gapcursor": "^1.4.1",
+    "prosemirror-history": "^1.5.0",
+    "prosemirror-inputrules": "^1.5.0",
+    "prosemirror-keymap": "^1.2.3",
+    "prosemirror-model": "^1.25.9",
+    "prosemirror-state": "^1.4.4",
+    "prosemirror-tables": "^1.8.5",
+    "prosemirror-transform": "^1.12.0",
+    "prosemirror-view": "^1.42.6",
+    "y-prosemirror": "^1.3.7",
+    "y-protocols": "^1.0.6",
+    "yjs": "^13.6.31"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts"