Scout Value Field Data Flow: Developer Guide

FormField (base)
  └── ValueField<TValue>
      └── BasicField<TValue>
          ├── StringField (extends BasicField<string>)
          ├── AceField (custom, extends BasicField<string>)
          └── CodeMirrorField (custom, extends BasicField<string>)

1. User types in field
2. User clicks outside field (blur)
3. 'blur' event fires
4. _onFieldBlur(event)
5.   └─> acceptInput(false)
6.       ├─> displayText = _readDisplayText()  [read from DOM]
7.       ├─> _checkDisplayTextChanged(displayText, false)
8.       └─> if changed:
9.           ├─> _setProperty('displayText', displayText)
10.          ├─> parseAndSetValue(displayText)
11.          │   ├─> removeErrorStatus()
12.          │   ├─> parseValue(displayText)  [uses parser function]
13.          │   └─> setValue(parsedValue)
14.          │       └─> _setValue(parsedValue)
15.          │           ├─> validateValue(parsedValue)
16.          │           ├─> this.value = validated
17.          │           ├─> _updateDisplayText()
18.          │           │   ├─> formatValue(this.value)
19.          │           │   └─> setDisplayText(formatted)
20.          │           │       └─> _renderDisplayText()
21.          │           │           └─> $field.val(formatted)
22.          │           └─> _valueChanged()
23.          └─> _triggerAcceptInput(false)  [event sent to server]

export class AceField extends BasicField<string> {
  editor: ace.Editor;
  protected _isUpdatingEditorFromRenderer: boolean;

  constructor() {
    super();
    this._isUpdatingEditorFromRenderer = false;
  }

  override _render() {
    // Create container and initialize editor
    this.addContainer(this.$parent, 'ace-field');
    this.addLabel();

    let $field = this.$parent.appendDiv('ace-field-content');
    this.addField($field);

    this.editor = ace.edit($field.get()[0]);
    this.editor.setValue(this.displayText);

    // Hook editor change events
    this.editor.session.on('change', () => {
      this._onEditorValueChange();
    });

    this.addMandatoryIndicator();
    this.addStatus();
  }

  override _readDisplayText(): string {
    // Read from editor instead of DOM input
    return this.editor ? this.editor.getValue() : '';
  }

  override _renderDisplayText() {
    // Guard: prevent infinite loop when we set editor value
    if (this._isUpdatingEditorFromRenderer) {
      return;
    }

    let displayText = strings.nvl(this.displayText);
    let currentEditorValue = strings.nvl(this.editor.getValue());

    // Write to editor instead of DOM input
    if (this.editor && displayText !== currentEditorValue) {
      // Set flag before setValue to prevent loop
      this._isUpdatingEditorFromRenderer = true;
      try {
        this.editor.setValue(displayText);
        this._updateHasText();
      } finally {
        // Always clear flag
        this._isUpdatingEditorFromRenderer = false;
      }
    }
  }

  protected _onEditorValueChange() {
    // Don't handle changes that we triggered ourselves
    if (this._isUpdatingEditorFromRenderer) {
      return;
    }

    // Update has-text indicator
    this._updateHasText();

    // Use Scout's built-in method for while-typing updates
    if (this.updateDisplayTextOnModify) {
      this._onDisplayTextModified();
    }
  }
}