refactor(seq-fields): share parsed attr projection

luccas-harbour · luccas-harbour · commit 0c379b2c4cfe · 2026-06-04T09:46:22.000-03:00
Add sequenceFieldAttrsFromParsed beside the SEQ parser and use it from import, raw field insertion, caption insertion/configuration, and PM recompute. This keeps parsed instruction attrs and null/default normalization in one place.
diff --git a/packages/super-editor/src/editors/v1/core/super-converter/field-references/shared/seq-instruction.js b/packages/super-editor/src/editors/v1/core/super-converter/field-references/shared/seq-instruction.js
@@ -21,6 +21,19 @@ const TOKEN_PATTERN = /"((?:[^"\\]|\\.)*)"|\\[#*]|\\[^\s]+|[^\s]+/g;
  *   hasGeneralFormat: boolean,
  *   unknownSwitches: string[],
  * }} ParsedSeqInstruction
+ *
+ * @typedef {{
+ *   identifier: string,
+ *   fieldArgument: string,
+ *   sequenceMode: SeqMode,
+ *   hideResult: boolean,
+ *   restartNumber: number | null,
+ *   restartLevel: number | null,
+ *   format: string,
+ *   hasGeneralFormat: boolean,
+ *   pageNumberFieldFormat: import('@superdoc/contracts').PageNumberFieldFormat | null,
+ *   numericPictureFormat: SeqNumericPictureFormat | null,
+ * }} SequenceFieldParsedAttrs
  */
 
 /**
@@ -149,6 +162,27 @@ export function normalizeSeqIdentifier(identifier) {
   return typeof identifier === 'string' ? identifier.trim() : '';
 }
 
+/**
+ * Project parsed SEQ instruction metadata into sequenceField PM attrs.
+ *
+ * @param {ParsedSeqInstruction} parsed
+ * @returns {SequenceFieldParsedAttrs}
+ */
+export function sequenceFieldAttrsFromParsed(parsed) {
+  return {
+    identifier: parsed.identifier,
+    fieldArgument: parsed.fieldArgument,
+    sequenceMode: parsed.sequenceMode,
+    hideResult: parsed.hideResult,
+    restartNumber: parsed.restartNumber,
+    restartLevel: parsed.restartLevel,
+    format: parsed.hasGeneralFormat ? parsed.format : 'ARABIC',
+    hasGeneralFormat: parsed.hasGeneralFormat,
+    pageNumberFieldFormat: parsed.pageNumberFieldFormat ?? null,
+    numericPictureFormat: parsed.numericPictureFormat,
+  };
+}
+
 /**
  * @param {string} instruction
  */
diff --git a/packages/super-editor/src/editors/v1/core/super-converter/field-references/shared/seq-instruction.test.js b/packages/super-editor/src/editors/v1/core/super-converter/field-references/shared/seq-instruction.test.js
@@ -1,5 +1,10 @@
 import { describe, expect, it } from 'vitest';
-import { isSeqInstruction, normalizeSeqIdentifier, parseSeqInstruction } from './seq-instruction.js';
+import {
+  isSeqInstruction,
+  normalizeSeqIdentifier,
+  parseSeqInstruction,
+  sequenceFieldAttrsFromParsed,
+} from './seq-instruction.js';
 
 describe('parseSeqInstruction', () => {
   it.each([
@@ -156,3 +161,33 @@ describe('normalizeSeqIdentifier', () => {
     expect(normalizeSeqIdentifier(null)).toBe('');
   });
 });
+
+describe('sequenceFieldAttrsFromParsed', () => {
+  it('projects parsed SEQ metadata into normalized sequenceField attrs', () => {
+    const attrs = sequenceFieldAttrsFromParsed(parseSeqInstruction('SEQ Figure \\r 3 \\* roman'));
+
+    expect(attrs).toEqual({
+      identifier: 'Figure',
+      fieldArgument: '',
+      sequenceMode: 'next',
+      hideResult: false,
+      restartNumber: 3,
+      restartLevel: null,
+      format: 'roman',
+      hasGeneralFormat: true,
+      pageNumberFieldFormat: { format: 'lowerRoman' },
+      numericPictureFormat: null,
+    });
+  });
+
+  it('keeps the parser default separate from the legacy PM attr default', () => {
+    const parsed = parseSeqInstruction('SEQ Figure');
+
+    expect(parsed.format).toBe('Arabic');
+    expect(sequenceFieldAttrsFromParsed(parsed)).toMatchObject({
+      format: 'ARABIC',
+      pageNumberFieldFormat: null,
+      numericPictureFormat: null,
+    });
+  });
+});
diff --git a/packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/sd/sequenceField/sequenceField-translator.js b/packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/sd/sequenceField/sequenceField-translator.js
@@ -1,7 +1,10 @@
 // @ts-check
 import { NodeTranslator } from '@translator';
 import { exportSchemaToJson, processOutputMarks } from '../../../../exporter.js';
-import { parseSeqInstruction } from '../../../../field-references/shared/seq-instruction.js';
+import {
+  parseSeqInstruction,
+  sequenceFieldAttrsFromParsed,
+} from '../../../../field-references/shared/seq-instruction.js';
 import { buildInstructionElements } from '../shared/index.js';
 
 /** @type {import('@translator').XmlNodeName} */
@@ -26,23 +29,15 @@ const encode = (params) => {
 
   const instruction = node.attributes?.instruction || '';
   const parsed = parseSeqInstruction(instruction);
+  const parsedAttrs = sequenceFieldAttrsFromParsed(parsed);
 
   return {
     type: SD_NODE_NAME,
     attrs: {
       instruction,
       instructionTokens: node.attributes?.instructionTokens || null,
       // Raw instruction remains the export source of truth; these parsed attrs support import-time routing and later evaluation.
-      identifier: parsed.identifier,
-      fieldArgument: parsed.fieldArgument,
-      sequenceMode: parsed.sequenceMode,
-      hideResult: parsed.hideResult,
-      restartNumber: parsed.restartNumber,
-      restartLevel: parsed.restartLevel,
-      format: parsed.format,
-      hasGeneralFormat: parsed.hasGeneralFormat,
-      pageNumberFieldFormat: parsed.pageNumberFieldFormat ?? null,
-      numericPictureFormat: parsed.numericPictureFormat,
+      ...parsedAttrs,
       resolvedNumber: extractResolvedText(processedText),
       resolvedNumberIsCurrent: false,
       marksAsAttrs: node.marks || [],
diff --git a/packages/super-editor/src/editors/v1/document-api-adapters/helpers/sequence-field-updater.ts b/packages/super-editor/src/editors/v1/document-api-adapters/helpers/sequence-field-updater.ts
@@ -8,6 +8,7 @@ import { SequenceFieldEvaluator } from '../../core/super-converter/field-referen
 import {
   normalizeSeqIdentifier,
   parseSeqInstruction,
+  sequenceFieldAttrsFromParsed,
 } from '../../core/super-converter/field-references/shared/seq-instruction.js';
 
 export type SequenceFieldUpdateScope =
@@ -117,20 +118,13 @@ function resolveNodeHeadingLevel(node: ProseMirrorNode, converterContext?: Conve
 function buildEvaluatedSequenceAttrs(node: ProseMirrorNode): SequenceFieldAttrs {
   const instruction = typeof node.attrs.instruction === 'string' ? node.attrs.instruction : '';
   const parsed = parseSeqInstruction(instruction);
+  const parsedAttrs = sequenceFieldAttrsFromParsed(parsed);
 
   return {
     ...node.attrs,
     instruction,
-    identifier: parsed.identifier || readStringAttr(node, 'identifier'),
-    fieldArgument: parsed.fieldArgument,
-    sequenceMode: parsed.sequenceMode,
-    hideResult: parsed.hideResult,
-    restartNumber: parsed.restartNumber,
-    restartLevel: parsed.restartLevel,
-    format: parsed.format,
-    hasGeneralFormat: parsed.hasGeneralFormat,
-    pageNumberFieldFormat: parsed.pageNumberFieldFormat ?? null,
-    numericPictureFormat: parsed.numericPictureFormat,
+    ...parsedAttrs,
+    identifier: parsedAttrs.identifier || readStringAttr(node, 'identifier'),
   };
 }
 
diff --git a/packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/caption-wrappers.ts b/packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/caption-wrappers.ts
@@ -35,7 +35,10 @@ import {
   getSequenceFieldUpdaterConverterContext,
   updateSequenceFieldsInTransaction,
 } from '../helpers/sequence-field-updater.js';
-import { parseSeqInstruction } from '../../core/super-converter/field-references/shared/seq-instruction.js';
+import {
+  parseSeqInstruction,
+  sequenceFieldAttrsFromParsed,
+} from '../../core/super-converter/field-references/shared/seq-instruction.js';
 
 // ---------------------------------------------------------------------------
 // Result helpers
@@ -140,16 +143,7 @@ export function captionsInsertWrapper(
         children.push(
           schema.nodes.sequenceField.create({
             instruction,
-            identifier: parsed.identifier,
-            fieldArgument: parsed.fieldArgument,
-            sequenceMode: parsed.sequenceMode,
-            hideResult: parsed.hideResult,
-            restartNumber: parsed.restartNumber,
-            restartLevel: parsed.restartLevel,
-            format: parsed.format,
-            hasGeneralFormat: parsed.hasGeneralFormat,
-            pageNumberFieldFormat: parsed.pageNumberFieldFormat ?? null,
-            numericPictureFormat: parsed.numericPictureFormat,
+            ...sequenceFieldAttrsFromParsed(parsed),
             resolvedNumber: '',
             resolvedNumberIsCurrent: false,
             sdBlockId: `seq-${Date.now()}`,
@@ -291,22 +285,19 @@ export function captionsConfigureWrapper(
         const format = CAPTION_FORMAT_TO_OOXML[input.format ?? 'decimal'] ?? 'ARABIC';
         const newInstruction = `SEQ ${input.label} \\* ${format}`;
         const parsed = parseSeqInstruction(newInstruction);
-        const pageNumberFieldFormat = parsed.pageNumberFieldFormat ?? { format: 'decimal' };
+        const parsedAttrs = sequenceFieldAttrsFromParsed(parsed);
         if (
           node.attrs.instruction === newInstruction &&
           node.attrs.format === format &&
-          JSON.stringify(node.attrs.pageNumberFieldFormat) === JSON.stringify(pageNumberFieldFormat)
+          JSON.stringify(node.attrs.pageNumberFieldFormat) === JSON.stringify(parsedAttrs.pageNumberFieldFormat)
         ) {
           return true;
         }
 
         tr.setNodeMarkup(tr.mapping.map(pos), undefined, {
           ...node.attrs,
           instruction: newInstruction,
-          format,
-          pageNumberFieldFormat,
-          hasGeneralFormat: true,
-          numericPictureFormat: null,
+          ...parsedAttrs,
           resolvedNumberIsCurrent: false,
         });
         changed = true;
diff --git a/packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/field-wrappers.ts b/packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/field-wrappers.ts
@@ -34,6 +34,7 @@ import { parsePageNumberFieldSwitches } from '../../core/super-converter/field-r
 import {
   isSeqInstruction,
   parseSeqInstruction,
+  sequenceFieldAttrsFromParsed,
 } from '../../core/super-converter/field-references/shared/seq-instruction.js';
 import {
   getSequenceFieldUpdaterConverterContext,
@@ -279,16 +280,7 @@ function insertRawField(
         parsed
           ? {
               instruction: input.instruction,
-              identifier: parsed.identifier,
-              fieldArgument: parsed.fieldArgument,
-              sequenceMode: parsed.sequenceMode,
-              hideResult: parsed.hideResult,
-              restartNumber: parsed.restartNumber,
-              restartLevel: parsed.restartLevel,
-              format: parsed.format,
-              hasGeneralFormat: parsed.hasGeneralFormat,
-              pageNumberFieldFormat: parsed.pageNumberFieldFormat ?? null,
-              numericPictureFormat: parsed.numericPictureFormat,
+              ...sequenceFieldAttrsFromParsed(parsed),
               resolvedNumber: '',
               resolvedNumberIsCurrent: false,
               sdBlockId: `field-${Date.now()}`,
