@stll/folio-core 0.34.0 → 0.35.0

package/dist/ai-edits/snapshot.d.ts

@@ -1,6 +1,8 @@
 import { FolioAIBlock, FolioAIEditSnapshot, FolioAITextRangeHandle } from "./types.js";
 import { Node } from "prosemirror-model";
 //#region src/ai-edits/snapshot.d.ts
+/** @internal Numbering references collected during the snapshot's document walk. */
+declare const numberingReferenceKeysOf: (snapshot: FolioAIEditSnapshot) => readonly string[];
 declare const normalizeFolioAIBlockText: (text: string) => string;
 /**
  * Whether a block carries text a reader would see.
@@ -70,4 +72,4 @@ type FolioStoryTable = {
 declare const folioStoryTables: (doc: Node) => FolioStoryTable[];
 declare const createFolioAIEditSnapshot: (doc: Node) => FolioAIEditSnapshot;
 //#endregion
-export { FolioStoryTable, createFolioAIEditSnapshot, createFolioAITextRangeHandle, folioStoryTables, hashFolioAIBlockText, isFolioAIContentBlock, isHiddenTableRow, normalizeFolioAIBlockText, trailingBodyBlockId };
+export { FolioStoryTable, createFolioAIEditSnapshot, createFolioAITextRangeHandle, folioStoryTables, hashFolioAIBlockText, isFolioAIContentBlock, isHiddenTableRow, normalizeFolioAIBlockText, numberingReferenceKeysOf, trailingBodyBlockId };

package/dist/ai-edits/snapshot.js

@@ -1,8 +1,12 @@
 import { expectRunFormattingOverrideMarkAttrs } from "../prosemirror/attrs/index.js";
 import { deriveBlankBlockId, deriveBlockId } from "../types/block-id.js";
 import { buildCleanBlockText } from "./clean-text.js";
+import { panic } from "better-result";
 import { TableMap } from "prosemirror-tables";
 //#region src/ai-edits/snapshot.ts
+const numberingReferenceKeysBySnapshot = /* @__PURE__ */ new WeakMap();
+/** @internal Numbering references collected during the snapshot's document walk. */
+const numberingReferenceKeysOf = (snapshot) => numberingReferenceKeysBySnapshot.get(snapshot) ?? panic("A numbering census was requested for a snapshot that did not record one");
 const normalizeFolioAIBlockText = (text) => text.replace(/\s+/gu, " ").trim();
 /**
 * Whether a block carries text a reader would see.
@@ -126,6 +130,7 @@ const createFolioAIEditSnapshot = (doc) => {
 	const draftBlocks = [];
 	const hashCounts = /* @__PURE__ */ new Map();
 	const usedBlockIds = /* @__PURE__ */ new Set();
+	const numberingReferenceKeys = /* @__PURE__ */ new Set();
 	const tableIndexByStart = new Map(folioStoryTables(doc).map(({ start, index }) => [start, index]));
 	const path = [];
 	let blockIndex = 0;
@@ -171,6 +176,8 @@ const createFolioAIEditSnapshot = (doc) => {
 		const displayLabel = getDisplayLabel(node);
 		const styleId = getStyleId(node);
 		const listLevel = getListLevel(node);
+		const numberingReferenceKey = getNumberingReferenceKey(node);
+		if (numberingReferenceKey) numberingReferenceKeys.add(numberingReferenceKey);
 		const previewRuns = getPreviewRuns(node);
 		const table = getTableLocation({
 			path,
@@ -209,10 +216,12 @@ const createFolioAIEditSnapshot = (doc) => {
 			hashOccurrenceCount: hashCounts.get(draft.anchor.textHash) ?? 0
 		};
 	}
-	return {
+	const snapshot = {
 		blocks,
 		anchors
 	};
+	numberingReferenceKeysBySnapshot.set(snapshot, [...numberingReferenceKeys]);
+	return snapshot;
 };
 const getBlockKind = (node, headingLevel) => {
 	const listMarker = node.attrs["listMarker"];
@@ -241,6 +250,15 @@ const getListLevel = (node) => {
 	const { ilvl } = numPr;
 	return typeof ilvl === "number" && Number.isInteger(ilvl) && ilvl >= 0 ? ilvl : void 0;
 };
+const getNumberingReferenceKey = (node) => {
+	const numPr = node.attrs["numPr"];
+	if (typeof numPr !== "object" || numPr === null || !("numId" in numPr)) return null;
+	const { numId } = numPr;
+	if (typeof numId !== "number" || !Number.isInteger(numId) || numId <= 0) return null;
+	const level = "ilvl" in numPr ? numPr.ilvl : void 0;
+	if (level !== void 0 && (typeof level !== "number" || !Number.isInteger(level) || level < 0)) return null;
+	return `${String(numId)}:${String(level ?? 0)}`;
+};
 const getStyleId = (node) => {
 	const styleId = node.attrs["styleId"];
 	return typeof styleId === "string" && styleId.length > 0 ? styleId : void 0;
@@ -376,4 +394,4 @@ const isEmptyPreviewRunStyle = ({ bold, italic, underline, strike, fontFamily, f
 const sameDirectFormatting = (left, right) => left === void 0 && isEmptyPreviewRunStyle(right) || left !== void 0 && left.bold === right.bold && left.italic === right.italic && left.underline === right.underline && left.strike === right.strike && left.fontFamily === right.fontFamily && left.fontSizePt === right.fontSizePt && left.color === right.color;
 const isUnstyledPreviewRun = ({ bold, italic, underline, strike, fontFamily, fontSizePt, color }) => bold === void 0 && italic === void 0 && underline === void 0 && strike === void 0 && fontFamily === void 0 && fontSizePt === void 0 && color === void 0;
 //#endregion
-export { createFolioAIEditSnapshot, createFolioAITextRangeHandle, folioStoryTables, hashFolioAIBlockText, isFolioAIContentBlock, isHiddenTableRow, normalizeFolioAIBlockText, trailingBodyBlockId };
+export { createFolioAIEditSnapshot, createFolioAITextRangeHandle, folioStoryTables, hashFolioAIBlockText, isFolioAIContentBlock, isHiddenTableRow, normalizeFolioAIBlockText, numberingReferenceKeysOf, trailingBodyBlockId };

package/dist/compare/compare.js

@@ -1,4 +1,5 @@
 import { FolioDocxReviewer } from "../ai-edits/headless.js";
+import { numberingReferenceKeysOf } from "../ai-edits/snapshot.js";
 import { projectTableGeometry } from "../ai-edits/table-geometry.js";
 import "../document-operations.js";
 import { pairFolioDocumentStories } from "../document-stories.js";
@@ -114,11 +115,12 @@ const formattingRoundTripFailure = ({ invariant, story, changes, actualBlocks, e
 };
 const numberingKey = ({ numId, level }) => `${String(numId)}:${String(level)}`;
 const sameNumbering = (left, right) => left.format === right.format && left.levelText === right.levelText && left.start === right.start;
-const compareNumbering = (base, target) => {
+const compareNumbering = (base, target, referenced) => {
 	const baseLevels = new Map(base.readNumberingDefinitions().map((level) => [numberingKey(level), level]));
 	const targetLevels = new Map(target.readNumberingDefinitions().map((level) => [numberingKey(level), level]));
 	const changes = [];
 	for (const [key, before] of baseLevels) {
+		if (!referenced.has(key)) continue;
 		const after = targetLevels.get(key) ?? null;
 		if (after === null || !sameNumbering(before, after)) changes.push({
 			kind: "numbering",
@@ -128,7 +130,7 @@ const compareNumbering = (base, target) => {
 			after
 		});
 	}
-	for (const [key, after] of targetLevels) if (!baseLevels.has(key)) changes.push({
+	for (const [key, after] of targetLevels) if (referenced.has(key) && !baseLevels.has(key)) changes.push({
 		kind: "numbering",
 		numId: after.numId,
 		level: after.level,
@@ -162,8 +164,15 @@ const parseComparison = async (base, target, options) => {
 	});
 	const pairs = [];
 	const unsupported = [];
+	const referencedNumberingLevels = /* @__PURE__ */ new Set();
+	const collectNumberingReferences = (snapshot) => {
+		if (!snapshot) return;
+		for (const referenceKey of numberingReferenceKeysOf(snapshot)) referencedNumberingLevels.add(referenceKey);
+	};
 	for (const { baseStory, revisedStory: targetStory } of pairFolioDocumentStories(reviewer.listStories().map(({ handle }) => handle), targetReviewer.listStories().map(({ handle }) => handle))) {
 		if (!baseStory) {
+			if (!targetStory) panic("A story pair contained neither a base nor a target story");
+			collectNumberingReferences(targetReviewer.snapshotStory(targetStory));
 			unsupported.push({
 				reason: "story-missing-in-base",
 				baseStory: null,
@@ -172,6 +181,7 @@ const parseComparison = async (base, target, options) => {
 			continue;
 		}
 		if (!targetStory) {
+			collectNumberingReferences(reviewer.snapshotStory(baseStory));
 			unsupported.push({
 				reason: "story-missing-in-target",
 				baseStory,
@@ -181,6 +191,8 @@ const parseComparison = async (base, target, options) => {
 		}
 		const baseSnapshot = reviewer.snapshotStory(baseStory);
 		const targetSnapshot = targetReviewer.snapshotStory(targetStory);
+		collectNumberingReferences(baseSnapshot);
+		collectNumberingReferences(targetSnapshot);
 		if (!baseSnapshot || !targetSnapshot) {
 			unsupported.push({
 				reason: "story-not-editable",
@@ -208,7 +220,7 @@ const parseComparison = async (base, target, options) => {
 		},
 		packageDate,
 		pairs,
-		numberingChanges: compareNumbering(reviewer, targetReviewer),
+		numberingChanges: compareNumbering(reviewer, targetReviewer, referencedNumberingLevels),
 		unsupported
 	});
 };

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

@@ -9,10 +9,16 @@ type DirectiveRange = {
   /** Exclusive PM doc position of the marker end. */
   to: number;
   kind: DirectiveKind;
-  /** Field path, clause name, or condition/loop expression. */
+  /**
+   * Field path, clause name, key, condition, or — for a `for` marker — the
+   * array path the loop iterates (`{% for row in items %}` ⇒ `items`).
+   */
   expr: string;
   /** Clause-slot version selector, e.g. "v3" or "latest". */
   clauseVersion?: string;
+  /** Loop alias of a `for` marker (`{% for row in items %}` ⇒ `row`); unset
+   *  for every other kind. */
+  alias?: string;
   /** True for block directives that occupy their own paragraph. */
   block: boolean;
 };
@@ -20,15 +26,16 @@ type DirectiveRange = {
  * Nesting depth (0-based) of every block-directive opener, derived purely from
  * the scanned ranges by containment: walk the block openers/closers in document
  * order with a kind-aware stack, and record each opener's depth as the stack size
- * before it is pushed. Only `block:true` if/each pairs participate (inline markers
+ * before it is pushed. Only `block:true` if/for pairs participate (inline markers
  * resolve within a paragraph and get no rail).
  *
  * Matching is kind-aware so a mid-edit / unbalanced template stays sane: a closer
- * pops the nearest opener of the *same family* ({{/if}} ⇒ {{#if}}, {{/each}} ⇒
- * {{#each}}), dropping any still-open openers nested above it; a closer with no
- * matching opener is ignored (never decrements a foreign block's depth). A blind
- * open/close counter would mis-count here: e.g. a stray {{/each}} between {{#if}}
- * and a nested {{#each}} would wrongly pull the inner {{#each}} back to depth 0.
+ * pops the nearest opener of the *same family* (`{% endif %}` ⇒ `{% if %}`,
+ * `{% endfor %}` ⇒ `{% for %}`), dropping any still-open openers nested above it;
+ * a closer with no matching opener is ignored (never decrements a foreign block's
+ * depth). A blind open/close counter would mis-count here: e.g. a stray
+ * `{% endfor %}` between `{% if %}` and a nested `{% for %}` would wrongly pull
+ * the inner `{% for %}` back to depth 0.
  *
  * Keyed by the opener's `from` PM position, which is unique per marker, so the
  * overlay can look a band's depth up from its opener range. This is a pure

package/dist/prosemirror/plugins/templateDirectives.js

@@ -3,41 +3,42 @@ import { collectBlockChunks, joinChunks, offsetToDocPos } from "./pmTextScan.js"
 import { PluginKey } from "prosemirror-state";
 import { assertNever, isBlockDirectiveKind, scanMarkers } from "@stll/template-conditions";
 //#region src/prosemirror/plugins/templateDirectives.ts
-/** The display expression for a marker (field path, clause name, key, condition). */
+/** The display expression for a marker (field path, clause name, key,
+*  condition, loop array path, loop property). */
 const directiveExpr = (meta) => {
 	switch (meta.kind) {
 		case "placeholder": return meta.expr;
 		case "clause": return meta.name;
 		case "num":
 		case "ref": return meta.key;
+		case "loop": return meta.property;
 		case "if":
-		case "elseif":
-		case "each": return meta.expr;
-		case "index":
-		case "count":
+		case "elif": return meta.expr;
+		case "for": return meta.path;
 		case "else":
 		case "endif":
-		case "endeach": return "";
+		case "endfor": return "";
 		default: return assertNever(meta);
 	}
 };
-/** Block-directive openers ({{#if}}, {{#each}}) that start a gutter-rail band. */
-const BLOCK_OPENER_KINDS = /* @__PURE__ */ new Set(["if", "each"]);
-/** Block-directive closers ({{/if}}, {{/each}}) that end a gutter-rail band. */
-const BLOCK_CLOSER_KINDS = /* @__PURE__ */ new Set(["endif", "endeach"]);
+/** Block-directive openers (`{% if %}`, `{% for %}`) that start a gutter-rail band. */
+const BLOCK_OPENER_KINDS = /* @__PURE__ */ new Set(["if", "for"]);
+/** Block-directive closers (`{% endif %}`, `{% endfor %}`) that end a gutter-rail band. */
+const BLOCK_CLOSER_KINDS = /* @__PURE__ */ new Set(["endif", "endfor"]);
 /**
 * Nesting depth (0-based) of every block-directive opener, derived purely from
 * the scanned ranges by containment: walk the block openers/closers in document
 * order with a kind-aware stack, and record each opener's depth as the stack size
-* before it is pushed. Only `block:true` if/each pairs participate (inline markers
+* before it is pushed. Only `block:true` if/for pairs participate (inline markers
 * resolve within a paragraph and get no rail).
 *
 * Matching is kind-aware so a mid-edit / unbalanced template stays sane: a closer
-* pops the nearest opener of the *same family* ({{/if}} ⇒ {{#if}}, {{/each}} ⇒
-* {{#each}}), dropping any still-open openers nested above it; a closer with no
-* matching opener is ignored (never decrements a foreign block's depth). A blind
-* open/close counter would mis-count here: e.g. a stray {{/each}} between {{#if}}
-* and a nested {{#each}} would wrongly pull the inner {{#each}} back to depth 0.
+* pops the nearest opener of the *same family* (`{% endif %}` ⇒ `{% if %}`,
+* `{% endfor %}` ⇒ `{% for %}`), dropping any still-open openers nested above it;
+* a closer with no matching opener is ignored (never decrements a foreign block's
+* depth). A blind open/close counter would mis-count here: e.g. a stray
+* `{% endfor %}` between `{% if %}` and a nested `{% for %}` would wrongly pull
+* the inner `{% for %}` back to depth 0.
 *
 * Keyed by the opener's `from` PM position, which is unique per marker, so the
 * overlay can look a band's depth up from its opener range. This is a pure
@@ -54,12 +55,14 @@ const computeBlockDepths = (ranges) => {
 			stack.push(range.kind);
 			continue;
 		}
-		const wantOpener = range.kind === "endif" ? "if" : "each";
+		const wantOpener = range.kind === "endif" ? "if" : "for";
 		const matchIdx = stack.lastIndexOf(wantOpener);
 		if (matchIdx !== -1) stack.length = matchIdx;
 	}
 	return depths;
 };
+/** The loop alias a `for` marker binds, or undefined for every other kind. */
+const directiveAlias = (meta) => meta.kind === "for" ? meta.alias : void 0;
 const scanDirectives = (doc) => {
 	const ranges = [];
 	for (const chunks of collectBlockChunks(doc)) {
@@ -69,24 +72,28 @@ const scanDirectives = (doc) => {
 		const sole = lineMarkers.length === 1 ? lineMarkers[0] : void 0;
 		if (sole && sole.raw === trimmed && isBlockDirectiveKind(sole.meta.kind)) {
 			const last = chunks.at(-1);
+			const alias = directiveAlias(sole.meta);
 			ranges.push({
 				from: chunks[0]?.start ?? 0,
 				to: last ? last.end ?? last.start + last.text.length : 0,
 				kind: sole.meta.kind,
 				expr: directiveExpr(sole.meta),
-				block: true
+				block: true,
+				...alias !== void 0 ? { alias } : {}
 			});
 			continue;
 		}
 		for (const marker of scanMarkers(joined)) {
 			const clauseVersion = marker.meta.kind === "clause" ? marker.meta.version : void 0;
+			const alias = directiveAlias(marker.meta);
 			ranges.push({
 				from: offsetToDocPos(chunks, marker.start),
 				to: offsetToDocPos(chunks, marker.end, "end"),
 				kind: marker.meta.kind,
 				expr: directiveExpr(marker.meta),
 				block: false,
-				...clauseVersion !== void 0 ? { clauseVersion } : {}
+				...clauseVersion !== void 0 ? { clauseVersion } : {},
+				...alias !== void 0 ? { alias } : {}
 			});
 		}
 	}

package/dist/prosemirror/plugins/templateSlashMenu.js

@@ -24,8 +24,8 @@ const atTriggerBoundary = (state, pos) => {
 /** Whether `pos` falls strictly inside an existing template directive. The
 *  slash activations insert markers as raw text rather than going through
 *  `insertInline`'s overlap guard, so opening here would nest markers — e.g. a
-*  `/` typed after `#if ` inside `{{#if condition}}` could produce
-*  `{{#if {{field}}}}`, which the scanner/fill grammar cannot interpret.
+*  `/` typed after `if ` inside `{% if condition %}` could produce
+*  `{% if {{ field }} %}`, which the scanner/fill grammar cannot interpret.
 *  Boundaries are exclusive: a caret right before `{{` or after `}}` is fine. */
 const insideDirective = (state, pos) => getTemplateDirectives(state).some((range) => pos > range.from && pos < range.to);
 /** Whether the `/` that opened the trigger is still present at `from`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/folio-core",
-  "version": "0.34.0",
+  "version": "0.35.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",
@@ -117,7 +117,7 @@
   "dependencies": {
     "@stll/docx-core": "^0.19.2",
     "@stll/docx-utils": "^0.1.0",
-    "@stll/template-conditions": "^0.1.0",
+    "@stll/template-conditions": "^0.4.0",
     "better-result": "3.0.1",
     "csstype": "^3.1.3",
     "dompurify": "^3.4.13",