fix: address PR review — minProperties, RichContentInsertInput type, deduplicate alignment constant

Author: tupizz

packages/document-api/src/contract/schemas.ts

@@ -4869,24 +4869,27 @@ const operationSchemas: Record<OperationId, OperationSchemaSet> = {
         id: { type: 'string' },
         op: { const: 'format.apply', type: 'string' },
         where: stepWhereSchema,
-        args: objectSchema(
-          {
-            inline: buildInlineRunPatchSchema(),
-            alignment: {
-              type: 'string',
-              enum: ['left', 'center', 'right', 'justify'],
-              description:
-                'Set paragraph alignment on the target block(s). Can be combined with inline formatting in the same step.',
-            },
-            scope: {
-              type: 'string',
-              enum: ['match', 'block'],
-              description:
-                'When "block", inline formatting expands to cover the entire parent paragraph(s), not just the matched text. Use "block" after markdown inserts to format whole paragraphs with a short identifying pattern. Default: "match".',
+        args: {
+          ...objectSchema(
+            {
+              inline: buildInlineRunPatchSchema(),
+              alignment: {
+                type: 'string',
+                enum: ['left', 'center', 'right', 'justify'],
+                description:
+                  'Set paragraph alignment on the target block(s). Can be combined with inline formatting in the same step.',
+              },
+              scope: {
+                type: 'string',
+                enum: ['match', 'block'],
+                description:
+                  'When "block", inline formatting expands to cover the entire parent paragraph(s), not just the matched text. Use "block" after markdown inserts to format whole paragraphs with a short identifying pattern. Default: "match".',
+              },
             },
-          },
-          [], // No individual field is required — at least one must be present
-        ),
+            [], // No individual field is required
+          ),
+          minProperties: 1, // At least one of inline, alignment, or scope must be present
+        },
       },
       ['id', 'op', 'where', 'args'],
     );

packages/document-api/src/insert/insert.ts

@@ -3,6 +3,8 @@ import type { SelectionTarget, TargetLocator, SDMutationReceipt } from '../types
 import type { SDInsertInput } from '../types/structural-input.js';
 import type { SDFragment } from '../types/fragment.js';
 import type { StoryLocator } from '../types/story.types.js';
+import type { BlockNodeAddress } from '../types/base.js';
+import type { Placement } from '../types/placement.js';
 import { PLACEMENT_VALUES } from '../types/placement.js';
 import { DocumentApiValidationError } from '../errors.js';
 import {
@@ -40,6 +42,25 @@ export type TextInsertInput = OptionalInsertLocator & {
   in?: StoryLocator;
 };
 
+/**
+ * Extended input for markdown/html inserts that also accept BlockNodeAddress
+ * targets and placement. These route through the structural insert path.
+ */
+export type RichContentInsertInput = {
+  /** Block target for positioned inserts. Accepts BlockNodeAddress or SelectionTarget. */
+  target?: SelectionTarget | BlockNodeAddress;
+  /** Optional mutation ref. Mutually exclusive with target. */
+  ref?: string;
+  /** The markdown/html content to insert. */
+  value: string;
+  /** Content format — must be 'markdown' or 'html' for this input shape. */
+  type: 'markdown' | 'html';
+  /** Where to place content relative to target. Only valid with BlockNodeAddress targets. */
+  placement?: Placement;
+  /** Target a specific document story. */
+  in?: StoryLocator;
+};
+
 /** @deprecated Use {@link TextInsertInput} instead. */
 export type LegacyInsertInput = TextInsertInput;
 
@@ -53,7 +74,7 @@ export type LegacyInsertInput = TextInsertInput;
  * Discrimination: presence of `content` (structural) vs `value` (text string).
  * These are mutually exclusive — providing both is an error.
  */
-export type InsertInput = TextInsertInput | SDInsertInput;
+export type InsertInput = TextInsertInput | RichContentInsertInput | SDInsertInput;
 
 // ---------------------------------------------------------------------------
 // Allowlists for strict field validation
@@ -276,16 +297,19 @@ export function executeInsert(
   }
 
   // Text string path
-  const { target, ref, value } = input;
   const contentType = input.type ?? 'text';
 
   // For non-text content types, delegate to the adapter's structured insert path.
   if (contentType !== 'text') {
     return writeAdapter.insertStructured(input, normalizeMutationOptions(options));
   }
 
+  // After the non-text branch, input is guaranteed to be a plain TextInsertInput.
+  const textInput = input as TextInsertInput;
+  const { target, ref, value } = textInput;
+
   // Text path with target/ref → route through SelectionMutationAdapter
-  const storyIn = input.in;
+  const storyIn = textInput.in;
   if (target || ref) {
     const request = target
       ? { kind: 'insert' as const, target, text: value, ...(storyIn ? { in: storyIn } : {}) }

packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/executor.ts

@@ -39,6 +39,7 @@ import type {
 } from './executor-registry.types.js';
 import { getStepExecutor } from './executor-registry.js';
 import { planError } from './errors.js';
+import { ALIGNMENT_TO_JUSTIFICATION } from './paragraphs-wrappers.js';
 import { closeHistory } from 'prosemirror-history';
 import { yUndoPluginKey } from 'y-prosemirror';
 import { checkRevision, getRevision } from './revision-tracker.js';
@@ -804,21 +805,13 @@ export function executeTextDelete(
   return { changed: true };
 }
 
-/** Alignment API value → OOXML justification value */
-const ALIGNMENT_TO_JUSTIFICATION: Record<string, string> = {
-  left: 'left',
-  center: 'center',
-  right: 'right',
-  justify: 'both',
-};
-
 /**
  * Applies alignment to the paragraph node(s) that contain the given range.
  * Uses the same mechanism as paragraphsSetAlignmentWrapper: updates
  * paragraphProperties.justification via tr.setNodeMarkup.
  */
 function applyAlignmentToRange(tr: Transaction, absFrom: number, absTo: number, alignment: string): boolean {
-  const justification = ALIGNMENT_TO_JUSTIFICATION[alignment];
+  const justification = ALIGNMENT_TO_JUSTIFICATION[alignment as keyof typeof ALIGNMENT_TO_JUSTIFICATION];
   if (!justification) return false;
 
   let changed = false;

packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/paragraphs-wrappers.ts

@@ -238,7 +238,7 @@ function mutateParagraphProperties(
 // Alignment mapping — external API → OOXML justification value
 // ---------------------------------------------------------------------------
 
-const ALIGNMENT_TO_JUSTIFICATION: Record<ParagraphAlignment, string> = {
+export const ALIGNMENT_TO_JUSTIFICATION: Record<ParagraphAlignment, string> = {
   left: 'left',
   center: 'center',
   right: 'right',