Add Yaml Source Editor Extension

What does this MR do and why?

This MR adds a Source Editor Extension that exposes interactive methods for YAML-Files. It leverages the yaml package.

Methods exposed by the extension:

setDataModel(value)

This function can be passed any JS Variable. The Editor's value will be set to a YAML dump of that value. If enableComments: true was set in the extension's options, this supports injecting comments following the comment pattern (see below).

highlight(path)

This function will add line highlighting to the lines identified by the path. The path is a string to any object property of value as interpreted by Lodash's pick function, e.g. foo.bar[0].

getDoc()

This function returns a Document, the YAML package's AST, effectively exposing all interactive functions in conjunction with setDoc()

setDoc(doc)

Accepts a Document as its parameter. It will set the editor's value to a stringified version of the Doc.

locate(path)

Used by highlight(path) this function will return the first and last line number of the element identified by path

Constructor options

option	type	description
model	any	The initial data model to be used by the editor. The editor's value will be set to the stringified version of this. Can be updated after setup using setDataModel()
highlightPath	string	equivalent to calling highlight(path) after setup. Will add line highlighting to the element identified by this property
enableComments	boolean	Whether data values following the comment pattern below will be converted to comments. Defaults to false

Comment Pattern

If enableComments is set to true in the Extension's options, values passed to setDataModel() that include properties/elements that follow the below pattern, will be interpreted as comments and injected to the YAML as such.

In Objects, a key of '#' will be converted to a comment at the top of a property. Any key follwing the pattern #|<some other key> will be placed right before <some other key>.

Example:

{
  foo: 'bar',
  '#|baz': 'I am a comment specific to the `baz` property',
  baz: 'boo',
  '#': 'I am a generic comment, I will be placed at the top'
}

will be converted to:

# I am a generic comment, I will be placed at the top
foo: bar
# I am a comment specific to the `baz` property
baz: boo

In Arrays, any string that starts with # (including the space), will be converted to a comment at the position it was in. Example:

 ['foo', 123, '# I am a comment for abc', abc]

Will be converted to:

- foo
- 123
# I am a comment for abc
- abc

To Do before Merge:

• fix an issue with locate() when locating array instances
• complete JSDoc
• update Tests for SourceEditorExtensionBase.highlightLines

Related Issues:

• #343243 (closed)
• gitlab-org/incubation-engineering/jamstack/meta#10 (closed)

Describe in detail what your merge request does and why.

Screenshots or screen recordings

Demo video

Usage example:

These are strongly recommended to assist reviewers and reduce the time to merge your change.

Usage Example

import SourceEditor from "~/editor/source_editor";
import { YamlEditorExtension } from "~/editor/extensions/source_editor_yaml_creator_ext";

import wildAnimals from "./wild-animals.json"

const editor = new SourceEditor().createInstance({});

editor.use(
    new YamlEditorExtension({
        instance: editor,
        enableComments: true,
        model: wildAnimals, // initial value will be the stringified version of this
        highlightPath: 'foods.birds' // initial highlighting
    })
);

// update functionally
editor.setDataModel(wildAnimals)

editor.highlight('predators[2]')

editor.locate(foods.birds) // [5, 7]

import { Document } from 'yaml';
editor.getDoc() // <Document>
editor.setDoc(new Document(wildAnimals)) // when not modifying `Document`, this is equivalent to editor.setDataModel

Numbered steps to set up and validate the change are strongly suggested.

MR acceptance checklist

This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.

• I have evaluated the MR acceptance checklist for this MR.