Feat (core): Make theme settings user-specific and user-configurable (#…

…5652)


* feat (core): make theme UI settings client-side

1. Add optional `preferBrowserSetting` to UISettings that should be defined client-side
2. Make `theme:darkMode` and `theme:version` prefer browser settings
3. Update UISettings client-side client to check localstorage for settings that prefer browser settings
4. Refactor logos to be responsive to browser-defined theme mode
5. Add a new `startup` script that handles theme/dark mode (injected as blocking script to head)
6. Remove theme/mode-specific logic from injected Styles and Fonts (move logic to `startup` script instead, define all font-faces)
7. Only inject theme values necessary for loading/error screens via `startup`
8. Update branding metadata to pass the correct dark mode
9. Add a new control for admin  Enable user control. This setting is enabled as default. When this setting is disabled, admin can disable any user control and we will have the exact previous behavior. 

---------

Signed-off-by: Josh Romero <[email protected]>

CHANGELOG.md

@@ -207,6 +207,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - [Discover] Added customizable pagination options based on Discover UI settings [#5610](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/5610)
 - [PM] Enhance single version requirements imposed during bootstrapping ([#5675](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/5675))
 - [Custom Branding] Relative URL should be allowed for logos ([#5572](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/5572))
+- [Theme] Make theme and dark mode settings user/device specific (in local storage), with opt-out ([#5652](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/5652))
 - Revert to legacy discover table and add toggle to new discover table ([#5789](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/5789))
 - [Discover] Add collapsible and resizeable sidebar ([#5789](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/5789))
 - [Discover] Enhanced the data source selector with added sorting functionality ([#5719](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/5719))

docs/theme.md

@@ -0,0 +1,131 @@
+# Theme System
+
+## Basic concepts
+
+### Theme definitions in OUI
+
+Themes are defined in OUI via https://github.com/opensearch-project/oui/blob/main/src/themes/themes.ts. When Building OUI, there are several theming artifacts generated (beyond the react components) for each mode (light/dark) of each theme:
+
+1. Theme compiled stylesheets (e.g. `@elastic/eui/dist/eui_theme_dark.css`). Consumed as entry files in [/packages/osd-ui-shared-deps/webpack.config.js](/packages/osd-ui-shared-deps/webpack.config.js) and republished by `osd-ui-shared-deps` (e.g. [UiSharedDeps.darkCssDistFilename](/packages/osd-ui-shared-deps/index.js)).
+2. Theme compiled and minified stylesheets (e.g. `@elastic/eui/dist/eui_theme_dark.min.css`). These appear unused by OpenSearch Dashboards
+3. Theme computed SASS variables as JSON (e.g. `@elastic/eui/dist/eui_theme_dark.json`). Consumed by [/packages/osd-ui-shared-deps/theme.ts](/packages/osd-ui-shared-deps/theme.ts) and made available to other components via the mode and theme aware `euiThemeVars`. In general, these should not be consumed by any other component directly.
+4. Theme type definition file for SASS variables as JSON (e.g. `@elastic/eui/dist/eui_theme_dark.json.d.ts`)
+
+Note that all of these artifacts should ideally only be imported or used directly in one place (by `osd-ui-shared-deps`).
+
+In addition to these artifacts, OpenSearch Dashboards also makes heavy use of the theme SASS variables and mixins as defined in the source files (e.g. `@elastic/eui/src/theme_dark.scss`).
+
+### Theme definitions in OpenSearch Dashboards
+
+1. Theme tags are defined in [/packages/osd-optimizer/src/common/theme_tags.ts](/packages/osd-optimizer/src/common/theme_tags.ts) corresponding to each mode (light/dark) of each OUI theme.
+2. These tags must correspond to entrypoint SCSS files in [/src/core/public/core_app/styles/](/src/core/public/core_app/styles/_globals_v8dark.scss), because they are imported by all SCSS files as part of the `sass-loader` in [/packages/osd-optimizer/src/worker/webpack.config.ts](/packages/osd-optimizer/src/worker/webpack.config.ts) and [/packages/osd-optimizer/src/worker/theme_loader.ts](/packages/osd-optimizer/src/worker/theme_loader.ts). Note that the optimizer webpack will compile a separate stylesheet for each unique mode and theme combination.
+3. OUI SCSS source files are also imported by `osd-ui-framework`, which generates the legacy KUI stylesheets (e.g. [/packages/osd-ui-framework/src/kui_next_dark.scss](/packages/osd-ui-framework/src/kui_next_dark.scss)). KUI is a UI library that predates EUI/OUI, and should be deprecated and fully removed via [#1060](https://github.com/opensearch-project/OpenSearch-Dashboards/issues/1060). Because it's a legacy package it has its own build process that doesn't use webpack; it just [compiles the SCSS files with grunt](/packages/osd-ui-framework/Gruntfile.js). But similarly to 2., a separate stylesheet is generated for each mode and theme combination.
+
+### Thmemed assets in OpenSearch Dasboards
+
+In general, most themed assests can be found in [/src/core/server/core_app/assets](src/core/server/core_app/assets/fonts/readme.md) (it also includes non-themed assets such as `favicons`, which could easily be themed if desired in the future).
+
+Most of the graphics/images are only dark/light mode-specific, not theme-specific:
+
+1. `default_branding` marks
+2. `logos`
+
+This directory also includes legacy CSS files ([/src/core/server/core_app/assets/legacy_dark_theme.css](/src/core/server/core_app/assets/legacy_dark_theme.css) and [/src/core/server/core_app/assets/legacy_light_theme.css](/src/core/server/core_app/assets/legacy_light_theme.css)), which predate even KUI, and are still used by some plugins (notably `discover`). See [#4385](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/4385) for an experiment in removing these. Unlike KUI, they don't rely on OUI themes at all.
+
+Finally, font assets are a bit of a special case. Theme-specific fonts are defined by OUI, but it doesn't include the font definitions directly. Instead, the font assets are in [/src/core/server/core_app/assets/fonts](/src/core/server/core_app/assets/fonts/readme.md). The corresponding `@font-face` style definitions are generated at runtime via [/src/core/server/rendering/views/fonts.tsx](/src/core/server/rendering/views/fonts.tsx).
+
+## Theme settings
+
+## Theme loading
+
+```mermaid
+sequenceDiagram
+    autonumber
+    critical Setup
+        core/server->>core/server/rendering: setup rendering service
+        core/server/rendering->>core/server: provide render() method
+        core/server->>core/server: setup legacy service
+        core/server->>legacy: create legacy server
+        legacy->>legacy: start ui mixin to<br>handle special routes
+        core/server->>core/server/core_app: setup core app
+        core/server/core_app->>core/server/core_app: register default routes
+        core/server/core_app->>core/server/core_app: register static asset dir routes
+    end
+    Browser->>core/server: OSD page request (e.g. /app/home#/ )
+    core/server->>core/server/core_app: request to default route<br>(via `http` service)
+    core/server/core_app->>core/server: call renderCoreApp()
+    core/server->>core/server/rendering: call render()
+    critical Initial page bootstrap
+        core/server/rendering->>core/server/rendering: get theme settings from config
+        core/server/rendering->>core/server/rendering: assign branding values \<br>(including dark mode)
+        core/server/rendering->>Browser: return static loading page template
+        Note over core/server/rendering,Browser: includes inlined font-face styles and static loading page styles
+        critical <head> (render blocking)
+            Browser->>Browser: define injection points
+            Browser->>Browser: load static loading page styles
+            Browser->>Browser: load font-face styles
+            Browser->>legacy: load startup.js special route
+            legacy->>legacy: build startup.js from template
+            Note over legacy: inject theme settings and font sources
+            legacy->>Browser: startup.js
+            critical startup.js
+                Browser->>Browser: get theme preferences from local storage
+                Browser->>Browser: set global theme tag
+                Browser->>Browser: inject theme-specific loading page styles
+                Browser->>Browser: inject theme-specific font css vars
+            end
+        end
+        Browser->>Browser: render loading/error page<br>(with loaders hidden)
+        Browser->>legacy: load bootstrap.js special route
+        legacy->>legacy: build bootstrap.js from template
+        legacy->>Browser: bootstrap.js
+        critical bootstrap.js
+            Browser->>Browser: toggle visibility of errors/loaders
+            Browser->>Browser: get theme preferences from local storage
+            Browser->>core/server/core_app: load js bundles
+            core/server/core_app->>Browser: (React application)
+            Browser->>core/server/core_app: load theme-specific stylesheets<br>(base, OUI, KUI, legacy)
+            core/server/core_app->>Browser: themed css
+        end
+    end
+```
+
+### Loading
+
+`src/legacy/ui/ui_render/ui_render_mixin.js` via `src/legacy/ui/ui_render/bootstrap/template.js.hbs` and `src/legacy/ui/ui_render/bootstrap/app_bootstrap.js`. Aliased in `src/legacy/ui/ui_mixin.js`, called by `src/legacy/server/osd_server.js`. Called by `src/core/server/legacy/legacy_service.ts` via `src/core/server/server.ts`
+
+### Injected style tags
+
+1. `src/core/server/rendering/views/styles.tsx` - depends on dark/light mode and injects style tag in head
+2. `src/core/server/rendering/views/fonts.tsx` - depends on theme version and injects font style tag in head
+3. Monaco editor styles
+4. Ace styles
+5. Ace TM overrides
+6. Ace error styles
+6. Component styles
+
+### Styleshsheets loaded
+
+Each of the following are loaded in the browser by the [bootstrap script](/src/legacy/ui/ui_render/bootstrap/template.js.hbs) in this order. Currently, these are never unloaded.
+
+1. Monaco editor styles (e.g. [/packages/osd-ui-shared-deps/target/osd-ui-shared-deps.css](/packages/osd-ui-shared-deps/target/osd-ui-shared-deps.css)), packaged by [/packages/osd-ui-shared-deps/webpack.config.js](/packages/osd-ui-shared-deps/webpack.config.js). In theory, this file could include styles from other shared dependencies, but currently `osd-monaco` is the only package that exports styles. Note that these are the default, un-themed styles; theming of monaco editors is handled by [/src/plugins/opensearch_dashboards_react/public/code_editor/editor_theme.ts](/src/plugins/opensearch_dashboards_react/public/code_editor/editor_theme.ts).
+2. Theme and mode-specific OUI styles (e.g. [](), compiled by `packages/osd-ui-shared-deps/webpack.config.js`).
+3. Theme and mode-specific KUI styles (e.g. `packages/osd-ui-framework/src/kui_next_dark.scss`, compiled by `packages/osd-ui-framework/Gruntfile.js`). Separate stylesheets for each theme version/dark mode combo (colors).
+4. Mode-specific legacy styles (e.g. [/src/core/server/core_app/assets/legacy_dark_theme.css](/src/core/server/core_app/assets/legacy_dark_theme.css))
+
+Component styles are not loaded as stylesheets.
+
+## Current theme usage
+
+### JSON/JS Vars
+
+1. Defined by `packages/osd-ui-shared-deps/theme.ts`
+	1. Used by `src/plugins/charts/public/static/color_maps/color_maps.ts` to set vis colors
+	2. Used by `src/plugins/discover/public/application/components/chart/histogram/histogram.tsx` to define Discover histogram Elastic Chart styling
+	3. Used by `src/plugins/maps_legacy/public/map/opensearch_dashboards_map.js` and `src/plugins/region_map/public/choropleth_layer.js` for minor map UI styling (line color, empty shade)
+	4. Used by `src/plugins/vis_type_vega/public/data_model/vega_parser.ts` for Vega/Vega-Lite theming
+2. Used by `src/plugins/vis_type_vislib/public/vislib/components/tooltip/tooltip.js` for tooltip spacing
+3. Used by `src/plugins/expressions/public/react_expression_renderer.tsx` to define padding options.
+4. Used by `src/core/server/rendering/views/theme.ts` to inject values into `src/core/server/rendering/views/styles.tsx`
+5. Used (incorrectly) to style a badge color in `src/plugins/index_pattern_management/public/components/create_button/create_button.tsx`
+6. Used by `src/plugins/opensearch_dashboards_react/public/code_editor/editor_theme.ts` to create Monaco theme styles

src/core/public/osd_bootstrap.test.ts

@@ -34,6 +34,7 @@ import { __osdBootstrap__ } from './';
 describe('osd_bootstrap', () => {
   beforeAll(() => {
     const metadata = {
+      branding: { darkMode: 'true' },
       i18n: { translationsUrl: 'http://localhost' },
       vars: { apmConfig: null },
     };

src/core/public/osd_bootstrap.ts

@@ -38,6 +38,11 @@ export async function __osdBootstrap__() {
     document.querySelector('osd-injected-metadata')!.getAttribute('data')!
   );
 
+  const globals: any = typeof window === 'undefined' ? {} : window;
+  const themeTag: string = globals.__osdThemeTag__ || '';
+
+  injectedMetadata.branding.darkMode = themeTag.endsWith('dark');
+
   let i18nError: Error | undefined;
   const apmSystem = new ApmSystem(injectedMetadata.vars.apmConfig, injectedMetadata.basePath);
 

src/core/public/ui_settings/ui_settings_client.ts

@@ -58,6 +58,13 @@ export class UiSettingsClient implements IUiSettingsClient {
     this.defaults = cloneDeep(params.defaults);
     this.cache = defaultsDeep({}, this.defaults, cloneDeep(params.initialSettings));
 
+    if (
+      this.cache['theme:enableUserControl']?.userValue ??
+      this.cache['theme:enableUserControl']?.value
+    ) {
+      this.cache = defaultsDeep(this.cache, this.getBrowserStoredSettings());
+    }
+
     params.done$.subscribe({
       complete: () => {
         this.update$.complete();
@@ -173,6 +180,28 @@ You can use \`IUiSettingsClient.get("${key}", defaultValue)\`, which will just r
     return this.updateErrors$.asObservable();
   }
 
+  private getBrowserStoredSettings() {
+    const uiSettingsJSON = window.localStorage.getItem('uiSettings') || '{}';
+    try {
+      return JSON.parse(uiSettingsJSON);
+    } catch (error) {
+      this.updateErrors$.next(error);
+    }
+    return {};
+  }
+
+  private setBrowserStoredSettings(key: string, newVal: any) {
+    const oldSettings = this.getBrowserStoredSettings();
+    const newSettings = cloneDeep(oldSettings);
+    if (newVal === null) {
+      delete newSettings[key];
+    } else {
+      newSettings[key] = { userValue: newVal };
+    }
+    window.localStorage.setItem(`uiSettings`, JSON.stringify(newSettings));
+    return { settings: newSettings };
+  }
+
   private assertUpdateAllowed(key: string) {
     if (this.isOverridden(key)) {
       throw new Error(
@@ -198,8 +227,18 @@ You can use \`IUiSettingsClient.get("${key}", defaultValue)\`, which will just r
     this.setLocally(key, newVal);
 
     try {
-      const { settings } = (await this.api.batchSet(key, newVal)) || {};
-      this.cache = defaultsDeep({}, defaults, settings);
+      if (
+        this.cache['theme:enableUserControl']?.userValue ??
+        this.cache['theme:enableUserControl']?.value
+      ) {
+        const { settings } = this.cache[key]?.preferBrowserSetting
+          ? this.setBrowserStoredSettings(key, newVal)
+          : (await this.api.batchSet(key, newVal)) || {};
+        this.cache = defaultsDeep({}, defaults, this.getBrowserStoredSettings(), settings);
+      } else {
+        const { settings } = (await this.api.batchSet(key, newVal)) || {};
+        this.cache = defaultsDeep({}, defaults, settings);
+      }
       this.saved$.next({ key, newValue: newVal, oldValue: initialVal });
       return true;
     } catch (error) {