Move plugins metadata from OB to packages

[ma2ciek]

Scope of this ticket:

• Make a final proposal for the metadata format and verify whether putting that into package.json is a good idea (taking into account that we'll have quite a lot of data there).
• Move the data from OB to each package and update it to the new format (excludes HTML format - it'll be covered separately).
• We don't need to scan existing plugins currently. We can base on what's available in OB right now.

---

[from meeting notes]

Which plugins do we cover?

• Only the glue code. No reason to cover *Editing, *UI
• We need to cover soft-deps of other plugins (e.g. CloudServices)

Plugins data

• Essential data
  • plugin name
  • human-readable plugin name
  • description
  • link to a feature guide
  • path to the plugin
  • additional toolbars
  • requires (soft and other weird requirements)
  • UI components:
    • name
    • path to SVG
      • what about plugins that use icons from other package?
      • relative if local
      • or npm's path: @ckeditor/ckeditor5-core/theme/icons/...
    • type (button, dropdown, split button)
    • additional info (e.g. dropdown config - with or without text/icon?)
    • target toolbar
      • if defined, OB adds it automatically to this toolbar
    • if not, the user can
• Online builder data
  • metadata of all packages + source SVG files
  • exclusions
    • what about exclusion groups? e.g. upload adapters
    • gets more complicated e.g. in the case of RTE plugins
  • which sample
  • whether to show a certain plugin (e.g. Paragraph, Essentials)
  • "requiresServer"
  • private → premium

The default configuration of builds

• duplicates the src/ckeditor.js file of each build
• might be reasonable to write a parser to exclude builtinPlugins and defaultConfig

[Reinmar]

package.json vs separate file:

• quite a lot of data, would make package.json a lot longer
• we need to have this published on npm anyway
• potential performance implications if it lands in package.json
• separate file - easier for people to learn about it
• separate file - adds a bit to the mess in each package's root dir
• separate file - possible to have JS if needed
  • may be harder for integrators to use it
  • but there's an option for the future if we really need it

Decision: Let's have this metadata in a separate file.

File name?

• package may expose not only plugins
• we may want to document e.g. a theme in the future
• do any other systems (Angular, React, other frameworks/cms-es) expose their metadata? what name do they use?

For now: ckeditor-metadata.json

[ma2ciek]

This is my current proposal:

interface PluginMetadata {
    /** The human readable plugin name. */
    name: string;

    /** The plugin's JS class name */
    className: string;

    /** A path to the plugin, relative to the metadata file. */
    path: string;

    /** The plugin's description. */
    description: string;

    /** The plugin's documentation link. */
    docs: string;

    /** The plugin's soft requirements and other not explicit requirements.*/
    requires?: Array<string>;

    /**
     * All toolbar components that the plugin exposes.
     * (buttons and dropdowns, possibly others in the future).
     */
    uiComponents?: Array<UIComponent>;

    /**
     * All toolbar names that are registered by the plugin.
     * These names need to contain the full configuration path
     * (e.g. `table.contentToolbar` and `table.tableToolbar` for `Table`).
     */
    registeredToolbars: Array<string>;

    htmlOutput?: any // To be done. 
}

interface UIComponent {
    /** The type of the component. */
    type: 'button' | 'dropdown' | 'split button';

    /** The component name that the plugin exposes. */
    name: string;

    /** A path to the SVG icon for button-like components. */
    iconPath?: string;

    /** Text content for dropdown-like components. */
    label?: string;

    /**
     * The target toolbars of this UI component. `[ "main" ]` by default.
     *
     * Note that some features may be added to multiple toolbars like `comments`.
     */
    targetToolbars?: Array<string>;
}

I changed from targetToolbar to targetToolbars to support comments and possibly other features in the future that can be placed in various toolbars (e.g. alignment).

[psmyrek]

Currently, the plugin preset in Online Builder contains also excludes array to define conflicting plugins. Do we need it in the PluginMetadata?

[ma2ciek]

Currently, the plugin preset in Online Builder contains also excludes array to define conflicting plugins. Do we need it in the PluginMetadata?

We have agreed that we'll keep this data in the OB separately for now as this won't be easy for 3rd-party plugins to provide information there - we'd need to introduce some kind of exclusionGroup first and this can be done as a follow-up. (And unfortunately, this approach would not work for some scenarios currently).

[Reinmar]

@ma2ciek What you proposed looks good to me. I'd only consider naming properties of  UIComponents after our UI lib. I think that things like a label are called differently there.

[Reinmar]

Also, perhaps the type of a UIComponent might be the name of the view class? So Button, Dropdown, SplitButton or even ButtonView, etc.

[ma2ciek]

I applied these changes ☝️

Closed by #9473.