[7.x] [kbn/optimizer] only build specified themes (elastic#70389) (el…

…astic#70671)

Co-authored-by: spalger <spalger@users.noreply.github.com>
Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>
Co-authored-by: cchaos <caroline.horn@elastic.co>

CONTRIBUTING.md

@@ -425,7 +425,7 @@ We are still to develop a proper process to accept any contributed translations.
 
 When writing a new component, create a sibling SASS file of the same name and import directly into the JS/TS component file. Doing so ensures the styles are never separated or lost on import and allows for better modularization (smaller individual plugin asset footprint).
 
-Any JavaScript (or TypeScript) file that imports SASS (.scss) files will automatically build with the [EUI](https://elastic.github.io/eui/#/guidelines/sass) & Kibana invisibles (SASS variables, mixins, functions) from the [`styling_constants.scss` file](https://github.com/elastic/kibana/blob/master/src/legacy/ui/public/styles/_styling_constants.scss). However, any Legacy (file path includes `/legacy`) files will not.
+All SASS (.scss) files will automatically build with the [EUI](https://elastic.github.io/eui/#/guidelines/sass) & Kibana invisibles (SASS variables, mixins, functions) from the [`globals_[theme].scss` file](src/legacy/ui/public/styles/_globals_v7light.scss).
 
 **Example:**
 
@@ -668,15 +668,15 @@ Part of this process only applies to maintainers, since it requires access to Gi
 Kibana publishes [Release Notes](https://www.elastic.co/guide/en/kibana/current/release-notes.html) for major and minor releases. The Release Notes summarize what the PRs accomplish in language that is meaningful to users. To generate the Release Notes, the team runs a script against this repo to collect the merged PRs against the release.
 
 #### Create the Release Notes text
-The text that appears in the Release Notes is pulled directly from your PR title, or a single paragraph of text that you specify in the PR description. 
+The text that appears in the Release Notes is pulled directly from your PR title, or a single paragraph of text that you specify in the PR description.
 
 To use a single paragraph of text, enter `Release note:` or a `## Release note` header in the PR description, followed by your text. For example, refer to this [PR](https://github.com/elastic/kibana/pull/65796) that uses the `## Release note` header.
 
 When you create the Release Notes text, use the following best practices:
-* Use present tense. 
+* Use present tense.
 * Use sentence case.
 * When you create a feature PR, start with `Adds`.
-* When you create an enhancement PR, start with `Improves`. 
+* When you create an enhancement PR, start with `Improves`.
 * When you create a bug fix PR, start with `Fixes`.
 * When you create a deprecation PR, start with `Deprecates`.
 

packages/kbn-optimizer/README.md

@@ -42,6 +42,26 @@ When a directory is listed in the "extraPublicDirs" it will always be included i
 
 Any import in a bundle which resolves into another bundles "context" directory, ie `src/plugins/*`, must map explicitly to a "public dir" exported by that plugin. If the resolved import is not in the list of public dirs an error will be thrown and the optimizer will fail to build that bundle until the error is fixed.
 
+## Themes
+
+SASS imports in bundles are automatically converted to CSS for one or more themes. In development we build the `v7light` and `v7dark` themes by default to improve build performance. When producing distributable bundles the default shifts to `*` so that the distributable bundles will include all themes, preventing the bundles from needing to be rebuilt when users change the active theme in Kibana's advanced settings.
+
+To customize the themes that are built for development you can specify the `KBN_OPTIMIZER_THEMES` environment variable to one or more theme tags, or use `*` to build styles for all themes. Unfortunately building more than one theme significantly impacts build performance, so try to be strategic about which themes you build.
+
+Currently supported theme tags: `v7light`, `v7dark`, `v8light`, `v8dark`
+
+Examples:
+```sh
+# start Kibana with only a single theme
+KBN_OPTIMIZER_THEMES=v7light yarn start
+
+# start Kibana with dark themes for version 7 and 8
+KBN_OPTIMIZER_THEMES=v7dark,v8dark yarn start
+
+# start Kibana with all the themes
+KBN_OPTIMIZER_THEMES=* yarn start
+```
+
 ## API
 
 To run the optimizer from code, you can import the [`OptimizerConfig`][OptimizerConfig] class and [`runOptimizer`][Optimizer] function. Create an [`OptimizerConfig`][OptimizerConfig] instance by calling it's static `create()` method with some options, then pass it to the [`runOptimizer`][Optimizer] function. `runOptimizer()` returns an observable of update objects, which are summaries of the optimizer state plus an optional `event` property which describes the internal events occuring and may be of use. You can use the [`logOptimizerState()`][LogOptimizerState] helper to write the relevant bits of state to a tooling log or checkout it's implementation to see how the internal events like [`WorkerStdio`][ObserveWorker] and [`WorkerStarted`][ObserveWorker] are used.

packages/kbn-optimizer/src/__fixtures__/mock_repo/src/legacy/ui/public/styles/_globals_v7light.scss

@@ -0,0 +1 @@
+$globalStyleConstant: 11;

packages/kbn-optimizer/src/__fixtures__/mock_repo/src/legacy/ui/public/styles/_globals_v8dark.scss

@@ -0,0 +1 @@
+$globalStyleConstant: 12;

packages/kbn-optimizer/src/__fixtures__/mock_repo/src/legacy/ui/public/styles/_globals_v8light.scss

@@ -0,0 +1 @@
+$globalStyleConstant: 13;

packages/kbn-optimizer/src/common/index.ts

@@ -29,3 +29,4 @@ export * from './array_helpers';
 export * from './event_stream_helpers';
 export * from './disallowed_syntax_plugin';
 export * from './parse_path';
+export * from './theme_tags';

packages/kbn-optimizer/src/common/theme_tags.test.ts

@@ -0,0 +1,92 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { parseThemeTags } from './theme_tags';
+
+it('returns default tags when passed undefined', () => {
+  expect(parseThemeTags()).toMatchInlineSnapshot(`
+    Array [
+      "v7dark",
+      "v7light",
+    ]
+  `);
+});
+
+it('returns all tags when passed *', () => {
+  expect(parseThemeTags('*')).toMatchInlineSnapshot(`
+    Array [
+      "v7dark",
+      "v7light",
+      "v8dark",
+      "v8light",
+    ]
+  `);
+});
+
+it('returns specific tag when passed a single value', () => {
+  expect(parseThemeTags('v8light')).toMatchInlineSnapshot(`
+    Array [
+      "v8light",
+    ]
+  `);
+});
+
+it('returns specific tags when passed a comma separated list', () => {
+  expect(parseThemeTags('v8light, v7dark,v7light')).toMatchInlineSnapshot(`
+    Array [
+      "v7dark",
+      "v7light",
+      "v8light",
+    ]
+  `);
+});
+
+it('returns specific tags when passed an array', () => {
+  expect(parseThemeTags(['v8light', 'v7light'])).toMatchInlineSnapshot(`
+    Array [
+      "v7light",
+      "v8light",
+    ]
+  `);
+});
+
+it('throws when an invalid tag is in the array', () => {
+  expect(() => parseThemeTags(['v8light', 'v7light', 'bar'])).toThrowErrorMatchingInlineSnapshot(
+    `"Invalid theme tags [bar], options: [v7dark, v7light, v8dark, v8light]"`
+  );
+});
+
+it('throws when an invalid tags in comma separated list', () => {
+  expect(() => parseThemeTags('v8light ,v7light,bar,box ')).toThrowErrorMatchingInlineSnapshot(
+    `"Invalid theme tags [bar, box], options: [v7dark, v7light, v8dark, v8light]"`
+  );
+});
+
+it('returns tags in alphabetical order', () => {
+  const tags = parseThemeTags(['v7light', 'v8light']);
+  expect(tags).toEqual(tags.slice().sort((a, b) => a.localeCompare(b)));
+});
+
+it('returns an immutable array', () => {
+  expect(() => {
+    const tags = parseThemeTags('v8light');
+    // @ts-expect-error
+    tags.push('foo');
+  }).toThrowErrorMatchingInlineSnapshot(`"Cannot add property 1, object is not extensible"`);
+});

packages/kbn-optimizer/src/common/theme_tags.ts

@@ -0,0 +1,65 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { ascending } from './array_helpers';
+
+const tags = (...themeTags: string[]) =>
+  Object.freeze(themeTags.sort(ascending((tag) => tag)) as ThemeTag[]);
+
+const validTag = (tag: any): tag is ThemeTag => ALL_THEMES.includes(tag);
+const isArrayOfStrings = (input: unknown): input is string[] =>
+  Array.isArray(input) && input.every((v) => typeof v === 'string');
+
+export type ThemeTags = readonly ThemeTag[];
+export type ThemeTag = 'v7light' | 'v7dark' | 'v8light' | 'v8dark';
+export const DEFAULT_THEMES = tags('v7light', 'v7dark');
+export const ALL_THEMES = tags('v7light', 'v7dark', 'v8light', 'v8dark');
+
+export function parseThemeTags(input?: any): ThemeTags {
+  if (!input) {
+    return DEFAULT_THEMES;
+  }
+
+  if (input === '*') {
+    return ALL_THEMES;
+  }
+
+  if (typeof input === 'string') {
+    input = input.split(',').map((tag) => tag.trim());
+  }
+
+  if (!isArrayOfStrings(input)) {
+    throw new Error(`Invalid theme tags, must be an array of strings`);
+  }
+
+  if (!input.length) {
+    throw new Error(
+      `Invalid theme tags, you must specify at least one of [${ALL_THEMES.join(', ')}]`
+    );
+  }
+
+  const invalidTags = input.filter((t) => !validTag(t));
+  if (invalidTags.length) {
+    throw new Error(
+      `Invalid theme tags [${invalidTags.join(', ')}], options: [${ALL_THEMES.join(', ')}]`
+    );
+  }
+
+  return tags(...input);
+}

packages/kbn-optimizer/src/common/worker_config.ts

@@ -20,11 +20,13 @@
 import Path from 'path';
 
 import { UnknownVals } from './ts_helpers';
+import { ThemeTags, parseThemeTags } from './theme_tags';
 
 export interface WorkerConfig {
   readonly repoRoot: string;
   readonly watch: boolean;
   readonly dist: boolean;
+  readonly themeTags: ThemeTags;
   readonly cache: boolean;
   readonly profileWebpack: boolean;
   readonly browserslistEnv: string;
@@ -80,6 +82,8 @@ export function parseWorkerConfig(json: string): WorkerConfig {
       throw new Error('`browserslistEnv` must be a string');
     }
 
+    const themes = parseThemeTags(parsed.themeTags);
+
     return {
       repoRoot,
       cache,
@@ -88,6 +92,7 @@ export function parseWorkerConfig(json: string): WorkerConfig {
       profileWebpack,
       optimizerCacheKey,
       browserslistEnv,
+      themeTags: themes,
     };
   } catch (error) {
     throw new Error(`unable to parse worker config: ${error.message}`);