revised Themes implementation - draft

[weedySeaDragon]

@sidharthv96 Perhaps you've already figured out how you want to revised Themes and Configurations. But just in case you haven't....

I've been thinking and playing around with Themes a bit. Here are my thoughts so far:

Themes (draft)

Themes describe the look and feel of the diagrams produced by mermaid. This includes colors, fonts,
line thicknesses, etc. Each theme has a name and a list of settings that provide the information mermaid needs to display
diagrams.

Theme

The list of settings is a Map so that settings can be accessed ('looked up') efficiently and to ensure that settings are not duplicated.
The keys in the Map are the names of the setting and the values are the ThemeSettings. Map<string, ThemeSetting>

When a new theme is instantiated, if it is given no settings, it will use the settings from the DefaultThemeSettingsFactory. This way, the minimal list of settings is always defined.

Serialization

A theme can be read in from and written out to JSON. This is how they can be saved, duplicated, changed, and imported.
(Will make it possible for users to easily define their own themes.)

Adding, Deleting, or Changing Setting Values

A setting value can be changed by overriding it.

When a setting value is changed, a setting is added, or a setting is deleted, the theme will update any calculated settings.

ThemeSetting

• name
• description (important for end-user documentation)
• category (helpful for displaying lists of settings in an organized, user-friendly way)
• value -- always a stored as a string. Diagrams and other consumers are responsible for converting as needed

ThemeColor

• a specialied ThemeSetting that also has a darkMode. This is the color to be used if displaying in dark mode.

classDiagram

 direction TB
    class ThemeSettingCategory{
        <<enumeration>>
        Global
        Colors
        Fonts
        Lines
    }
      
    class ThemeSetting{
      +string name
      +string description
      +string value
      +ThemeSettingCategory category
      +setPropertiesFrom( otherSetting)
      +toYAML() string
      #propertyToString(propertyName, propertyValue, indentLevel): string 
    }

    class ThemeColor {
        +string darkValue
        +setPropertiesFrom( otherSetting)
        +toYAML() string
    }

    ThemeSetting <|-- ThemeColor
    ThemeSettingCategory --> ThemeSetting
 
   
    class Theme {
      +string name
      +Map~string, ThemeSetting~ settings
      +constructor(aName, settings = DefaultThemeSettingsFactory.settings()))$ Theme
      +fromJsonFile(filename)$ Theme 
      +getSetting(settingName: string) ThemeSetting
      +overrideSetting(givenSetting: ThemeSetting, options)
      +overrideSettingsWith(givenThemeSettings: MapOfSettings, options)
      +updateCalculatedSettings()
      +writeJsonTo(filename)
      +asJSON(): string
      +settingsAsJSON(): string
      +toString(): string
    }
 

    Theme "1" --> "0..n" ThemeSetting: has
   

Loading

Questions / Issues / Discussion

• What is the minimal list of settings?
• For documentation, it will be helpful (necessary?) to be able to answer "What settings are used by which diagrams?" This is another classifier in addition to 'category'. ('category' is what display entity uses the setting (color, font, etc.). This is more about which entities use it.
• Will need to validate a theme
• What will be the development workflow when a new Diagram is added?
  • will some settings be optional? should all diagram-specific settings be optional? (If so, does this mean they are all calculated by default?)

Configuration

A Configuration is conceptually similar (though will have important differences).

• has a list of ConfigurationSettings (one of those is a Theme)
• override a specific setting; may need to recalculate
• validate
• be able to serialize (import/export)?

Seems like it would be easier to implement Themes first, both because they have less potential to break the system and to learn what works best (both implementation and for end-user documentation).

[knsv]

This is good!

The idea with the new themes is to make it easy to configure/setup a custom theme and I think this might help users to do so.

I think as a first step we/I will look through the current variables so that we know what we have to work with. In general it we have three levels of variables:

• Base color variables like primary color, secondary etc
• Derived palette, generic color variables derived from the base colors
• Diagram specific color variables based on the base colors and the derived palette

Ideally with the base theme you can set the primary color only and have the rest calculated for you. As a site integrator or even diagram author you can override any of these variables. The trick is cleaning things up a bit before we start. Above all we need to keep the color variables as low as possible as dedicated diagram variables is impossible to keep track of. My aim is to, if possible, align things like with the base theme and to try git rid of diagram specific variables, sticking with base colors and the derived palette.