@ansonlai/docx-redline-js 0.8.4 → 0.9.0

package/docs/schemas/document-operations.schema.json

@@ -87,6 +87,55 @@
         }
       ]
     },
+    "paragraphFormatProperties": {
+      "description": "Closed set. Unknown keys are rejected with INVALID_OPERATION (field properties.<key>) since 0.9.0.",
+      "type": "object",
+      "properties": {
+        "alignment": { "type": "string", "examples": ["left", "center", "right", "both"] },
+        "keepNext": { "type": "boolean" },
+        "keepLines": { "type": "boolean" },
+        "pageBreakBefore": { "type": "boolean" },
+        "style": { "type": "string", "description": "Paragraph style id (w:pStyle)." },
+        "numbering": {
+          "description": "Direct list binding recorded as a tracked w:pPrChange. An object binds the paragraph to an EXISTING numId at a level; null removes the direct binding. Never allocates a list. Refused with PARAGRAPH_NUMBERING_NOT_FOUND when the numId or level is not defined.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["numId"],
+              "properties": {
+                "numId": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] },
+                "level": { "type": "integer", "minimum": 0, "maximum": 8, "default": 0 }
+              },
+              "additionalProperties": false
+            }
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "listFormat": {
+      "description": "list-format-v1 (CLI contract version 9). convert-plain binds plain paragraphs to a NEW list definition in place: the binding is a tracked w:pPrChange and, with strip \"marker\" (default), the typed marker (A. / 1. / 1) / iv. / - ) is removed with a tracked deletion; Reject All restores the literal marker and the unnumbered paragraph. Each marker's value is the item's start value; consecutive values share one list, and a later convert-plain in the same batch whose first value continues the previous one joins that list. Refusals: LIST_MARKER_NOT_FOUND, LIST_MARKER_AMBIGUOUS (single roman-looking letter such as I. or C.; set format), LIST_MARKER_UNSUPPORTED (mixed markers, multi-level 2.1., (a), marker not in plain runs, format mismatch), LIST_FORMAT_TARGET_IS_LIST, LIST_FORMAT_STYLE_NUMBERED, PARAGRAPH_FORMAT_REVISION_CONFLICT. change-format and join (capability list-format-change-v1, same contract version): change-format allocates a NEW abstractNum + num copying the source definition (levels, indentation, fonts) with only the requested level redefined, and rebinds the list items to it with one tracked w:pPrChange each; the shared definition is never edited in place, so Reject All restores the original labels and Accept All shows the new ones. join rebinds the target list to the numId of list.continueFrom (an earlier list) so it continues that count. Tracked-deleted paragraphs keep their numPr. Refusals: LIST_FORMAT_TARGET_NOT_LIST, LIST_FORMAT_MIXED_RANGE (non-list paragraphs, several lists, several levels), LIST_FORMAT_STYLE_LINKED, LIST_FORMAT_STYLE_NUMBERED, LIST_FORMAT_SPLIT_UNSUPPORTED (mid-sequence range, nested restart, shared abstract definition, interleaved join), LIST_FORMAT_DEFINITION_UNSUPPORTED (missing definition, instance level override, lvlRestart in a split), LIST_FORMAT_JOIN_INVALID, PARAGRAPH_FORMAT_REVISION_CONFLICT; LIST_FORMAT_UNCHANGED is a warning on a no-op. Body only (no part). Composition: one single-paragraph redline/replace of the same paragraph may share the batch when it keeps the typed marker exactly (\"1. Old\" -> \"1. New\" = redline + convert-plain); the redline always runs first. scope \"list\" counts as a write to every rebound item. Other combinations fail LIST_FORMAT_COMPOSITION_CONFLICT. detach and materializeMarker are not available.",
+      "type": "object",
+      "required": ["mode"],
+      "properties": {
+        "mode": { "enum": ["convert-plain", "change-format", "join"] },
+        "kind": { "enum": ["bullet", "numbered"] },
+        "format": { "enum": ["decimal", "upperLetter", "lowerLetter", "upperRoman", "lowerRoman", "bullet"], "description": "convert-plain: required with strip \"none\"; with strip \"marker\" it must match the typed markers and disambiguates letters from roman numerals. change-format: the new numbering format of the level." },
+        "level": { "type": "integer", "minimum": 0, "maximum": 8, "description": "convert-plain: the level to bind (default 0). change-format: the level to redefine (default: the single level the target paragraphs use; refused LIST_FORMAT_MIXED_RANGE reason levels when they use several)." },
+        "strip": { "enum": ["marker", "none"], "default": "marker", "description": "convert-plain only. marker: remove the typed marker (tracked). none: keep the text and only bind." },
+        "start": { "type": "integer", "minimum": 1, "maximum": 32767, "description": "convert-plain: strip \"none\" only; defaults to continuing the batch's previous list of the same format, else 1 (with strip \"marker\" the start is the typed marker's value). change-format: restart value of the level, written as the w:start of the new definition (scope \"list\" only)." },
+        "lvlText": { "type": "string", "minLength": 1, "maxLength": 32, "description": "change-format only: the level text. Numbered: %1..%9 placeholders including the level's own (\"%1.\", \"(%2)\"); bullet: the bullet character. Default: the source level text when the kind stays, \"%<level+1>.\" for bullet -> numbered, \"•\" for numbered -> bullet." },
+        "scope": { "enum": ["list", "range"], "default": "list", "description": "change-format and join. list: every live paragraph of the target's list is rebound (paragraphs outside the target range included; result items carry inTarget). range: only the target range, which must run to the end of its list (LIST_FORMAT_SPLIT_UNSUPPORTED reason mid-sequence otherwise); change-format continues the count with per-level start values on the new definition." },
+        "continueFrom": { "$ref": "#/$defs/target", "description": "join only (required): an item of the earlier list the target list continues; bound at batch start like target." }
+      },
+      "allOf": [
+        { "if": { "properties": { "mode": { "const": "convert-plain" } } }, "then": { "not": { "anyOf": [ { "required": ["lvlText"] }, { "required": ["scope"] }, { "required": ["continueFrom"] } ] } } },
+        { "if": { "properties": { "mode": { "const": "change-format" } } }, "then": { "anyOf": [ { "required": ["format"] }, { "required": ["kind"] }, { "required": ["lvlText"] }, { "required": ["start"] } ], "not": { "anyOf": [ { "required": ["strip"] }, { "required": ["continueFrom"] } ] } } },
+        { "if": { "properties": { "mode": { "const": "join" } } }, "then": { "required": ["continueFrom"], "not": { "anyOf": [ { "required": ["kind"] }, { "required": ["format"] }, { "required": ["level"] }, { "required": ["strip"] }, { "required": ["start"] }, { "required": ["lvlText"] } ] } } }
+      ],
+      "additionalProperties": false
+    },
     "base": {
       "type": "object",
       "required": ["type", "target"],
@@ -98,6 +147,7 @@
         "author": { "type": "string", "minLength": 1 }, "generateRedlines": { "type": "boolean" },
         "existingRevisions": { "enum": ["merge-same-author", "slice-cross-author", "reject-input", "accept-all-first", "accept-all-first-keep-normalized"] },
         "pairReplacements": { "type": "boolean" },
+        "listMarkers": { "const": "literal", "description": "Accepts list-marker text as literal text. Suppresses LIST_MARKER_NOT_BOUND / UNSUPPORTED_LIST_CONVERSION and LIST_FORMAT_NOT_APPLIED / UNSUPPORTED_LIST_FORMAT_CHANGE for this operation." },
         "insertionAffinity": {
           "type": "object",
           "properties": {
@@ -160,7 +210,10 @@
           "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["textToFormat", "properties"], "properties": { "type": { "enum": ["format", "character-format"] }, "textToFormat": { "type": "string", "minLength": 1 }, "textOccurrence": { "type": "integer", "minimum": 1, "default": 1 }, "properties": { "type": "object" }, "formattingRevisionPolicy": { "enum": ["always", "coalesce-own-insertion"] } } } ]
         },
         {
-          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["properties"], "properties": { "type": { "const": "paragraph-format" }, "properties": { "type": "object" } } } ]
+          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["list"], "not": { "anyOf": [ { "required": ["part"] }, { "required": ["modified"] }, { "required": ["replacements"] } ] }, "properties": { "type": { "const": "list-format" }, "list": { "$ref": "#/$defs/listFormat" }, "targetEnd": { "$ref": "#/$defs/target" }, "targetEndRef": { "type": ["integer", "string", "null"] } } } ]
+        },
+        {
+          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["properties"], "properties": { "type": { "const": "paragraph-format" }, "properties": { "$ref": "#/$defs/paragraphFormatProperties" } } } ]
         }
       ]
     }