Values need to be abstracted for primitive type values and custom yaml tags

[Zoramite]

There is an issue currently when trying to use yaml tags in places where the editor is expecting a primitive type. For example, the editor may be expecting a string value, but the yaml file uses a !IfEnvironment tag to determine which value to use. In the editor this comes across as an object instead of a string (ex: { _type: 'IfEnvironment', _value: {...} }).

Ideally the editor needs to be able to edit the custom yaml tags without knowing that it is editing a custom yaml tag.

There are a few considerations that need to be made:

• The editor can define a set of classes for handling built in custom yaml tags for a given project type (ex: IfEnvironment, String, IfLocale, etc in Amagaki project type).
• Individual projects in Amagaki are encouraged to define their own custom types which would be outside of the 'built-in' support the editor could give.
  • Could define in the editor.yaml how the different custom tags should behave? ex: define for the CustomTag that it is a mapping type custom tag and to use the default key when editing as a string in the editor?
  • Built-in support for scalar, mapping, and sequence unknown yaml tags. But may limit how it would work in practice. For example, if the field provides a text field for editing, but the value is a mapping, how do you convert the mapping to a string value for editing?

Initial fix idea is to abstract the value in editor so that all interactions with the value for displaying fields would go through helper methods (ex: currentValue.toString()). There would be a default primitive class that would be used for normal values, but for things like custom tags the object would use the same interface but could change how the value was stored.

Concept for the value interface:

interface FieldValue {
  /**
   * Update the value from a string value (ex: text input).
   */
  fromString(value: string): void;
  /**
   * When the value is expected to be used as a string (ex: text input).
   */
  toString(): string;
  /**
   * Saving the field values needs to serialze in a 'final' format that
   * gets sent to the api to save.
   */
  serialize: any;
  /**
   * Value of the field. (Not in the serialized form, but the raw value)
   */
  value: any;
}

Then it could be implemented as follows:

class PrimitiveValue implements FieldValue {
  value: any;

  constructor(value: any) {
    this.value = value;
  }

  fromString(value: string) {
    this.value = value;
  }

  get serialize() {
    return this.value;
  }

  toString() {
    return this.value;
  }
}

class CustomTagValue implements FieldValue {
  protected _value: any;
  protected _type: any;
  protected options?: Record<string, any>;

  constructor(value: any, options?: Record<string, any>) {
    this._value = value._value; // ex: Mapping of locale to value
    this._type = value._type; // ex: IfLocale
    // A set of defined options, such as what key to use for string fields,
    // that could be defined in the editor.yaml so that the editor knows how
    // to treat the custom field when used in different field types.
    this.options = options;
  }

  fromString(value: string) {
    // TODO: Options for the custom tag can be read from the editor config
    // to tell the field how to act. For instance, what key to use from a
    // mapping type tag which then would update the key only when changed
    // from a string (ex: text field).
    this._value = value;
  }

  /**
   * When serializing a custom tag it needs to be in the 'tag' format so that
   * the api can convert it into a yaml tag when writing the yaml to the file.
   */
  get serialize() {
    return {
      _type: this._type,
      _value: this._value,
    };
  }

  get value() {
    // TODO: Options for the custom tag can be read from the editor config
    // to tell the field how to act. For instance, what key to use from a
    // mapping type tag
    return this._value;
  }

  set value(value: any) {
    this._value = value;
  }

  toString() {
    // TODO: Options for the custom tag can be read from the editor config
    // to tell the field how to act. For instance, what key to use from a
    // mapping type tag to provide a text value.
    return this._value;
  }
}

And when the value is used in a field type:

html`<input type="text" value=${currentValue.toString()} @change=${(evt) => {currentValue.fromString(evt.target.value)}}>`

Thoughts?

[jeremydw]

A few quick thoughts:

1. I like the idea of being able to define schemas for custom tags in editor.yaml. For example, if a project defines a !Foo tag that takes a string, I could define in editor.yaml:

!Foo:
  type: text

(and any other fields that might be needed in the schema). If no schema is provided for a custom tag then I think maybe we just show a placeholder, e.g.

[ !Foo (custom data) ]

2. The separate situation can happen with either custom or non-custom tags -- e.g. when invalid data is in the document (i.e. when the document's data doesn't match the schema). In this case, rather than trying to jam the invalid data into the schema, I would suggest we do one of two things:

a. We could autoguess the fields
b. We show a placeholder that says

[ <Warning Icon> Data does not match schema ]

I think I like (b) more than (a). (That's how other similar CMS work.)

I would also add that in situations (1) and (2) saving the document should be non-destructive -- i.e. the original data should be preserved. But for both (1) and (2b) the data wouldn't be editable in the fields UI (which I think is OK).