DEV: Introduce a value transformer front-end plugin API

[megothss]

This PR introduces the valueTransformerAPI to safely override values defined in Discourse.

Two new plugin APis are introduced:

• addValueTransformerName which allows plugins and theme-components to add a new valid transformer name if they want to provide overridable values;
• registerValueTransformer to register a transformer to override values.

It also introduces the function applyValueTransformer which can be imported from discourse/lib/transformer. This function marks the desired value as overridable and applies the transformer logic.

How does it work?

Marking a value as overridable:

To mark a value as overridable, in Discourse core, first the transformer name must be added to app/assets/javascripts/discourse/app/lib/transformer/registry.js. For plugins and theme-components, use the plugin API addValueTransformerName instead.

Then, in your component or class, use the function applyValueTransformer to mark the value as overridable and handle the logic:

• example:

export default class HomeLogo extends Component {
  @service session;
  @service site;
  ...
  get href() {
    return applyValueTransformer("home-logo-href", getURL("/"));
  }	

Overriding a value in plugins or themes

To override a value in plugins, themes, or TCs use the plugin API registerValueTransformer:

• Example:

withPluginApi("1.34.0", (api) => {
  api.registerValueTransformer("example-transformer", ({ value }) => {
    return "new-value";
  });
});

[davidtaylorhq]

One concern I have is that people are gonna pass something weird into 'context'.

e.g. they might do

applyTransformer("blah", value, this);

and pass an entire component instance. That would make any integrations quite fragile.

Could something like this help?

if(context && !(typeof context === 'object' && context.constructor === Object)){
  throw "Context must be a simple JS object"
}

[megothss]

We can add this, but TBH, it will just make it slightly harder.
If people want to pass the component in the context, they will.

It won't prevent them from doing something like:

applyTransformer("blah", value, { component: this });

[megothss]

On second thought, there is nothing we can do about third-party abusing it, but since most of these extension points will live in core and/or official plugins.

Adding this error might just be enough to prevent us, from doing it, like a not so gentle nudge.

[davidtaylorhq]

Yeah agreed - it won't be perfect, but it should at least discourage it 🤞

[discoursebot]

This pull request has been mentioned on Discourse Meta. There might be relevant details there:

https://meta.discourse.org/t/upcoming-header-changes-preparing-themes-and-plugins/296544/1