fix(super-editor): import <w:temporary/> and lock appearance default contract (SD-3111) (#3295)

* fix(super-editor): import <w:temporary/> and lock appearance default contract (SD-3111)

Two narrow gaps, both about the import contract for content-control
properties:

1. <w:temporary/> was being dropped on import.
   Word emits it (ECMA-376 §17.5.2.43), our exporter preserves it on
   round-trip, the editor's node-attrs typedef carries it, the
   sdt-info-builder maps it to ContentControlInfo.properties.temporary
   — but handle-structured-content-node.js never read it from sdtPr.
   So properties.temporary was always undefined, even for parts where
   the source XML said true.

   Fix: new extractTemporary helper applies Word's toggle conventions
   (empty element = true; w:val "true"/"1" = true; "false"/"0" = false).
   When the element is absent, the attr is NOT stamped — so consumers
   can distinguish "absent from source" from "explicit false."

2. The appearance default contract was implicit.
   ECMA-376 lets the source XML omit <w15:appearance>, and Word's
   effective default is boundingBox. SuperDoc correctly returns
   undefined when the source omits the element (resolveAppearance
   validates against the three spec values). But the public type
   JSDoc said nothing about this, so consumers building UI on top
   of appearance could not tell whether undefined meant "data
   missing" or "Word default applies."

   Fix: JSDoc on ContentControlProperties.appearance now spells out
   all four states explicitly, including 'undefined → treat as
   boundingBox.' Same treatment for temporary's 'undefined → treat
   as false.' No runtime behavior change — pure contract lock.

Tests:
  - 7 new w:temporary parsing cases (empty toggle, w:val true/1/false/0,
    absent twice, absent-doesn't-stamp).
  - Existing info-builder tests already cover the attr-to-properties
    mapping; they still pass.

Verified:
  - super-editor v3/w/sdt suite: 134/134
  - @superdoc/document-api: 1398/1398

Out of scope:
  - The exporter side already round-trips <w:temporary/> (per ticket
    description). Not modified.
  - The appearance default behavior is unchanged — only the JSDoc that
    documents it.

* wip(document-api): tighten temporary JSDoc wording per review (SD-3111)

The previous wording 'Word removes the SDT once the user fills it in'
paraphrases user-visible behavior but isn't quite the spec's framing.
Updated to 'When enabled, Word treats the content control as temporary
and may remove the SDT wrapper after the user edits/fills the control.'

No runtime change.

* fix(super-editor): route extractTemporary through shared ST_OnOff parser (SD-3111)

Codex bot review caught a real bug: my hand-rolled ST_OnOff check in
extractTemporary only recognized '0' and 'false' as off tokens, but
the project's shared ST_OnOff convention (token-sets.ts:27) also
accepts 'off'. So <w:temporary w:val="off"/> incorrectly returned
true, contradicting the source XML's explicit "not temporary".

Replaced with parseStrictStOnOff from the same utils.js other
ST_OnOff importers use. Gets: 'true'/'1'/'on' → true,
'false'/'0'/'off' → false, invalid tokens → undefined (with the
import-diagnostic side effect for consistency with other ST_OnOff
properties).

Strict ECMA-376 §22.9.2.7 lists only 1|0|true|false, but the project
deliberately accepts on/off for Word-in-the-wild robustness — same
convention bold/italic/strike already follow.

Three new tests:
  - <w:temporary w:val="on"/> → true
  - <w:temporary w:val="off"/> → false (the bug)
  - invalid token → undefined

Verified:
  - 32/32 in handle-structured-content-node.test.js
  - 137/137 across the SDT handler suite

Author: caio-pizzol

packages/document-api/src/content-controls/content-controls.types.ts

@@ -124,10 +124,39 @@ export interface RepeatingSectionControlProperties {
 export interface ContentControlProperties {
   tag?: string;
   alias?: string;
+  /**
+   * Visual chrome behavior (`<w15:appearance w15:val="…">`).
+   *
+   * Returned verbatim from the imported XML. When the source omits
+   * the element, this field is `undefined` — NOT silently set to
+   * `boundingBox`. Word's effective default when the element is
+   * absent is `boundingBox`, but consumers building UI on top of
+   * appearance (e.g. deciding whether to draw chrome) must apply
+   * that default themselves; the API does not fabricate it.
+   *
+   * Contract:
+   *   - `'boundingBox'` → explicit; show chrome
+   *   - `'tags'`        → explicit; show tag markers
+   *   - `'hidden'`      → explicit; render transparently
+   *   - `undefined`     → source XML omitted the element; treat as
+   *                       Word's effective default (`'boundingBox'`).
+   */
   appearance?: ContentControlAppearance;
   color?: string;
   placeholder?: string;
   showingPlaceholder?: boolean;
+  /**
+   * `<w:temporary/>` toggle (ECMA-376 §17.5.2.43).
+   *
+   * When enabled, Word treats the content control as temporary and may
+   * remove the SDT wrapper after the user edits/fills the control.
+   *
+   * Returned verbatim from the imported XML:
+   *   - `true`      → element present (`<w:temporary/>` or `w:val="true"`/`"1"`)
+   *   - `false`     → element present with `w:val="false"`/`"0"`
+   *   - `undefined` → element absent in source; treat as Word's
+   *                   effective default (`false`).
+   */
   temporary?: boolean;
   tabIndex?: number;
 

packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/sdt/helpers/handle-structured-content-node.js

@@ -1,4 +1,5 @@
 import { parseAnnotationMarks } from './handle-annotation-node';
+import { parseStrictStOnOff } from '../../../utils.js';
 
 /**
  * Detect the semantic control type from sdtPr child elements.
@@ -56,6 +57,24 @@ function extractPlaceholder(sdtPr) {
   return docPart?.attributes?.['w:val'] ?? null;
 }
 
+/**
+ * Extract the `<w:temporary/>` toggle from sdtPr (ECMA-376 §17.5.2.43).
+ *
+ * Delegates to `parseStrictStOnOff` so token recognition matches the
+ * project's shared ST_OnOff convention (`true`/`1`/`on` → true;
+ * `false`/`0`/`off` → false). Returns `undefined` when the element is
+ * absent or carries an invalid token, preserving the "absent vs explicit
+ * false" distinction at the Document API surface.
+ *
+ * @param {Object|null} sdtPr
+ * @returns {boolean|undefined}
+ */
+function extractTemporary(sdtPr) {
+  const el = sdtPr?.elements?.find((e) => e.name === 'w:temporary');
+  if (!el) return undefined;
+  return parseStrictStOnOff(el.attributes?.['w:val'], 'temporary', 'w:temporary');
+}
+
 /**
  * @param {Object} params
  * @returns {Object|null}
@@ -84,9 +103,10 @@ export function handleStructuredContentNode(params) {
   // Control type detection from sdtPr children
   const controlType = detectControlType(sdtPr);
 
-  // Appearance and placeholder
+  // Appearance, placeholder, and temporary toggle
   const appearance = extractAppearance(sdtPr);
   const placeholder = extractPlaceholder(sdtPr);
+  const temporary = extractTemporary(sdtPr);
 
   if (!sdtContent) {
     return null;
@@ -117,6 +137,10 @@ export function handleStructuredContentNode(params) {
       type: controlType,
       appearance,
       placeholder,
+      // `temporary` is only set when the XML carries `<w:temporary/>`;
+      // omitted attrs stay undefined so consumers can distinguish
+      // "absent from source" from explicit false.
+      ...(temporary !== undefined ? { temporary } : {}),
       sdtPr,
     },
   };

packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/sdt/helpers/handle-structured-content-node.test.js

@@ -225,6 +225,64 @@ describe('handleStructuredContentNode', () => {
     });
   });
 
+  describe('w:temporary parsing (SD-3111)', () => {
+    const parseTemporary = (sdtPrElements) => {
+      const node = createNode(sdtPrElements, [{ name: 'w:r', text: 'content' }]);
+      const params = { nodes: [node], nodeListHandler: mockNodeListHandler };
+      parseAnnotationMarks.mockReturnValue({ marks: [] });
+      return handleStructuredContentNode(params).attrs.temporary;
+    };
+
+    it('reads <w:temporary/> as true (empty toggle)', () => {
+      expect(parseTemporary([{ name: 'w:temporary' }])).toBe(true);
+    });
+
+    it('reads <w:temporary w:val="true"/> as true', () => {
+      expect(parseTemporary([{ name: 'w:temporary', attributes: { 'w:val': 'true' } }])).toBe(true);
+    });
+
+    it('reads <w:temporary w:val="1"/> as true', () => {
+      expect(parseTemporary([{ name: 'w:temporary', attributes: { 'w:val': '1' } }])).toBe(true);
+    });
+
+    it('reads <w:temporary w:val="false"/> as false', () => {
+      expect(parseTemporary([{ name: 'w:temporary', attributes: { 'w:val': 'false' } }])).toBe(false);
+    });
+
+    it('reads <w:temporary w:val="0"/> as false', () => {
+      expect(parseTemporary([{ name: 'w:temporary', attributes: { 'w:val': '0' } }])).toBe(false);
+    });
+
+    it('reads <w:temporary w:val="on"/> as true (ST_OnOff alias)', () => {
+      expect(parseTemporary([{ name: 'w:temporary', attributes: { 'w:val': 'on' } }])).toBe(true);
+    });
+
+    it('reads <w:temporary w:val="off"/> as false (ST_OnOff alias)', () => {
+      // Without going through the shared ST_OnOff set this would
+      // incorrectly fall through to true. See utils.js parseStrictStOnOff.
+      expect(parseTemporary([{ name: 'w:temporary', attributes: { 'w:val': 'off' } }])).toBe(false);
+    });
+
+    it('returns undefined for invalid w:val tokens (parser rejects unknown tokens)', () => {
+      expect(parseTemporary([{ name: 'w:temporary', attributes: { 'w:val': 'banana' } }])).toBeUndefined();
+    });
+
+    it('returns undefined (not false) when <w:temporary> is absent', () => {
+      // Spec contract: absent in source XML stays undefined so consumers
+      // can distinguish "Word's effective default" from "explicit false".
+      expect(parseTemporary([])).toBeUndefined();
+      expect(parseTemporary([{ name: 'w:tag', attributes: { 'w:val': 'unrelated' } }])).toBeUndefined();
+    });
+
+    it('does not stamp temporary on attrs when absent (preserves "undefined" semantics)', () => {
+      const node = createNode([], [{ name: 'w:r', text: 'content' }]);
+      const params = { nodes: [node], nodeListHandler: mockNodeListHandler };
+      parseAnnotationMarks.mockReturnValue({ marks: [] });
+      const result = handleStructuredContentNode(params);
+      expect('temporary' in result.attrs).toBe(false);
+    });
+  });
+
   describe('controlType detection', () => {
     const detectFrom = (sdtPrElements) => {
       const node = createNode(sdtPrElements, [{ name: 'w:r', text: 'content' }]);