More theme API cleanup

Signed-off-by: Fredrik Adelöw <freben@gmail.com>
2021-10-27 09:22:42 +02:00
parent 8eedc159ae
commit 40cfec8b3f
6 changed files with 131 additions and 73 deletions
@@ -0,0 +1,5 @@
+---
+'@backstage/theme': patch
+---
+
+More theme API cleanup
@@ -9,9 +9,7 @@ import { PaletteOptions } from '@material-ui/core/styles/createPalette';
 import { Theme } from '@material-ui/core';
 import { ThemeOptions } from '@material-ui/core';

-// Warning: (ae-missing-release-tag) "BackstagePalette" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type BackstagePalette = Palette & BackstagePaletteAdditions;

 // @public
@@ -69,101 +67,71 @@ export type BackstagePaletteAdditions = {
  };
 };

-// Warning: (ae-missing-release-tag) "BackstagePaletteOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type BackstagePaletteOptions = PaletteOptions &
  BackstagePaletteAdditions;

-// Warning: (ae-missing-release-tag) "BackstageTheme" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export interface BackstageTheme extends Theme {
  // (undocumented)
-  getPageTheme: ({ themeId }: PageThemeSelector) => PageTheme;
+  getPageTheme: (selector: PageThemeSelector) => PageTheme;
  // (undocumented)
  page: PageTheme;
  // (undocumented)
  palette: BackstagePalette;
 }

-// Warning: (ae-missing-release-tag) "BackstageThemeOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export interface BackstageThemeOptions extends ThemeOptions {
  // (undocumented)
-  getPageTheme: ({ themeId }: PageThemeSelector) => PageTheme;
+  getPageTheme: (selector: PageThemeSelector) => PageTheme;
  // (undocumented)
  page: PageTheme;
  // (undocumented)
  palette: BackstagePaletteOptions;
 }

-// Warning: (ae-missing-release-tag) "colorVariants" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export const colorVariants: Record<string, string[]>;

-// Warning: (ae-missing-release-tag) "createTheme" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export function createTheme(options: SimpleThemeOptions): BackstageTheme;

-// Warning: (ae-missing-release-tag) "createThemeOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export function createThemeOptions(
  options: SimpleThemeOptions,
 ): BackstageThemeOptions;

-// Warning: (ae-missing-release-tag) "createThemeOverrides" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export function createThemeOverrides(theme: BackstageTheme): Overrides;

-// Warning: (ae-missing-release-tag) "darkTheme" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export const darkTheme: BackstageTheme;

-// Warning: (ae-missing-release-tag) "genPageTheme" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export function genPageTheme(colors: string[], shape: string): PageTheme;

-// Warning: (ae-missing-release-tag) "lightTheme" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export const lightTheme: BackstageTheme;

-// Warning: (ae-missing-release-tag) "PageTheme" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type PageTheme = {
  colors: string[];
  shape: string;
  backgroundImage: string;
 };

-// Warning: (ae-missing-release-tag) "pageTheme" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export const pageTheme: Record<string, PageTheme>;

-// Warning: (ae-missing-release-tag) "PageThemeSelector" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type PageThemeSelector = {
  themeId: string;
 };

-// Warning: (ae-missing-release-tag) "shapes" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export const shapes: Record<string, string>;

-// Warning: (ae-missing-release-tag) "SimpleThemeOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type SimpleThemeOptions = {
  palette: BackstagePaletteOptions;
@@ -17,7 +17,6 @@
 import { createTheme as createMuiTheme } from '@material-ui/core/styles';
 import { darken, lighten } from '@material-ui/core/styles/colorManipulator';
 import { Overrides } from '@material-ui/core/styles/overrides';
-
 import {
  BackstageTheme,
  BackstageThemeOptions,
@@ -28,6 +27,11 @@ import { pageTheme as defaultPageThemes } from './pageTheme';
 const DEFAULT_FONT_FAMILY =
  '"Helvetica Neue", Helvetica, Roboto, Arial, sans-serif';

+/**
+ * A helper for creating theme options.
+ *
+ * @public
+ */
 export function createThemeOptions(
  options: SimpleThemeOptions,
 ): BackstageThemeOptions {
@@ -84,6 +88,11 @@ export function createThemeOptions(
  };
 }

+/**
+ * A helper for creating theme overrides.
+ *
+ * @public
+ */
 export function createThemeOverrides(theme: BackstageTheme): Overrides {
  return {
    MuiCssBaseline: {
@@ -271,8 +280,12 @@ export function createThemeOverrides(theme: BackstageTheme): Overrides {
  };
 }

-// Creates a Backstage MUI theme using a palette.
-// The theme is created with the common Backstage options and component styles.
+/**
+ * Creates a Backstage MUI theme using a palette. The theme is created with the
+ * common Backstage options and component styles.
+ *
+ * @public
+ */
 export function createTheme(options: SimpleThemeOptions): BackstageTheme {
  const themeOptions = createThemeOptions(options);
  const baseTheme = createMuiTheme(themeOptions) as BackstageTheme;
@@ -15,22 +15,33 @@
 */
 import { PageTheme } from './types';

-/*
-  # How to add a shape
-  1. Get the svg shape from figma, should be ~1400 wide, ~400 high
-    and only the white->transparent mask, no colors.
-  2. Run it through https://jakearchibald.github.io/svgomg/
-  3. Run that through https://github.com/tigt/mini-svg-data-uri
-    with something like https://npm.runkit.com/mini-svg-data-uri
-  4. Wrap the output in `url("")`
-  5. Give it a name and paste it into the `shapes` object below.
-*/
+/**
+ * The default predefined burst shapes.
+ *
+ * @public
+ * @remarks
+ *
+ * How to add a shape:
+ *
+ * 1. Get the svg shape from figma, should be ~1400 wide, ~400 high
+ *    and only the white-to-transparent mask, no colors.
+ * 2. Run it through https://jakearchibald.github.io/svgomg/
+ * 3. Run that through https://github.com/tigt/mini-svg-data-uri
+ *    with something like https://npm.runkit.com/mini-svg-data-uri
+ * 4. Wrap the output in `url("")`
+ * 5. Give it a name and paste it into the `shapes` object below.
+ */
 export const shapes: Record<string, string> = {
  wave: `url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' width='1368' height='400' fill='none'%3e%3cmask id='a' width='1368' height='401' x='0' y='0' maskUnits='userSpaceOnUse'%3e%3cpath fill='url(%23paint0_linear)' d='M437 116C223 116 112 0 112 0h1256v400c-82 0-225-21-282-109-112-175-436-175-649-175z'/%3e%3cpath fill='url(%23paint1_linear)' d='M1368 400V282C891-29 788 40 711 161 608 324 121 372 0 361v39h1368z'/%3e%3cpath fill='url(%23paint2_linear)' d='M1368 244v156H0V94c92-24 198-46 375 0l135 41c176 51 195 109 858 109z'/%3e%3cpath fill='url(%23paint3_linear)' d='M1252 400h116c-14-7-35-14-116-16-663-14-837-128-1013-258l-85-61C98 28 46 8 0 0v400h1252z'/%3e%3c/mask%3e%3cg mask='url(%23a)'%3e%3cpath fill='white' d='M-172-98h1671v601H-172z'/%3e%3c/g%3e%3cdefs%3e%3clinearGradient id='paint0_linear' x1='602' x2='1093.5' y1='-960.5' y2='272' gradientUnits='userSpaceOnUse'%3e%3cstop stop-color='white'/%3e%3cstop offset='1' stop-color='white' stop-opacity='0'/%3e%3c/linearGradient%3e%3clinearGradient id='paint1_linear' x1='482' x2='480' y1='1058.5' y2='70.5' gradientUnits='userSpaceOnUse'%3e%3cstop stop-color='white'/%3e%3cstop offset='1' stop-color='white' stop-opacity='0'/%3e%3c/linearGradient%3e%3clinearGradient id='paint2_linear' x1='424' x2='446.1' y1='-587.5' y2='274.6' gradientUnits='userSpaceOnUse'%3e%3cstop stop-color='white'/%3e%3cstop offset='1' stop-color='white' stop-opacity='0'/%3e%3c/linearGradient%3e%3clinearGradient id='paint3_linear' x1='587' x2='349' y1='-1120.5' y2='341' gradientUnits='userSpaceOnUse'%3e%3cstop stop-color='white'/%3e%3cstop offset='1' stop-color='white' stop-opacity='0'/%3e%3c/linearGradient%3e%3c/defs%3e%3c/svg%3e")`,
  wave2: `url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' width='1368' height='400' fill='none'%3e%3cmask id='a' width='1764' height='479' x='-229' y='-6' maskUnits='userSpaceOnUse'%3e%3cpath fill='url(%23paint0_linear)' d='M0 400h1350C1321 336 525 33 179-2c-345-34-395 236-408 402H0z'/%3e%3cpath fill='url(%23paint1_linear)' d='M1378 177v223H0V217s219 75 327 52C436 246 717-35 965 45s254 144 413 132z'/%3e%3cpath fill='url(%23paint2_linear)' d='M26 400l-78-16c-170 205-44-6-137-30l-4-1 4 1 137 30c37-45 89-110 159-201 399-514-45 238 1176-50 275-65 354-39 91 267H26z'/%3e%3c/mask%3e%3cg mask='url(%23a)'%3e%3cpath fill='white' d='M0 0h1368v400H0z'/%3e%3c/g%3e%3cdefs%3e%3clinearGradient id='paint0_linear' x1='431' x2='397.3' y1='-599' y2='372.8' gradientUnits='userSpaceOnUse'%3e%3cstop stop-color='white'/%3e%3cstop offset='1' stop-color='white' stop-opacity='0'/%3e%3c/linearGradient%3e%3clinearGradient id='paint1_linear' x1='236.5' x2='446.6' y1='-586' y2='381.5' gradientUnits='userSpaceOnUse'%3e%3cstop stop-color='white'/%3e%3cstop offset='1' stop-color='white' stop-opacity='0'/%3e%3c/linearGradient%3e%3clinearGradient id='paint2_linear' x1='851.8' x2='640.4' y1='-867.2' y2='363.7' gradientUnits='userSpaceOnUse'%3e%3cstop stop-color='white'/%3e%3cstop offset='1' stop-color='white' stop-opacity='0'/%3e%3c/linearGradient%3e%3c/defs%3e%3c/svg%3e")`,
  round: `url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' width='1368' height='400' fill='none'%3e%3cmask id='a' width='2269' height='1408' x='-610' y='-509' maskUnits='userSpaceOnUse'%3e%3ccircle cx='1212.8' cy='74.8' r='317.5' fill='url(%23paint0_linear)' transform='rotate(-52 1213 75)'/%3e%3ccircle cx='737.8' cy='445.8' r='317.5' fill='url(%23paint1_linear)' transform='rotate(-116 738 446)'/%3e%3ccircle cx='601.8' cy='52.8' r='418.6' fill='url(%23paint2_linear)' transform='rotate(-117 602 53)'/%3e%3ccircle cx='999.8' cy='364' r='389.1' fill='url(%23paint3_linear)' transform='rotate(31 1000 364)'/%3e%3cellipse cx='-109.2' cy='263.5' fill='url(%23paint4_linear)' rx='429.2' ry='465.8' transform='rotate(-85 -109 264)'/%3e%3c/mask%3e%3cg mask='url(%23a)'%3e%3cpath fill='white' d='M0 0h1368v400H0z'/%3e%3c/g%3e%3cdefs%3e%3clinearGradient id='paint0_linear' x1='1301.2' x2='161.4' y1='-1879.7' y2='-969.6' gradientUnits='userSpaceOnUse'%3e%3cstop stop-color='white'/%3e%3cstop offset='1' stop-color='white' stop-opacity='0'/%3e%3c/linearGradient%3e%3clinearGradient id='paint1_linear' x1='826.2' x2='-313.6' y1='-1508.7' y2='-598.6' gradientUnits='userSpaceOnUse'%3e%3cstop stop-color='white'/%3e%3cstop offset='1' stop-color='white' stop-opacity='0'/%3e%3c/linearGradient%3e%3clinearGradient id='paint2_linear' x1='718.4' x2='-784.3' y1='-2524' y2='-1324.2' gradientUnits='userSpaceOnUse'%3e%3cstop stop-color='white'/%3e%3cstop offset='1' stop-color='white' stop-opacity='0'/%3e%3c/linearGradient%3e%3clinearGradient id='paint3_linear' x1='1108.2' x2='-288.6' y1='-2031.1' y2='-915.9' gradientUnits='userSpaceOnUse'%3e%3cstop stop-color='white'/%3e%3cstop offset='1' stop-color='white' stop-opacity='0'/%3e%3c/linearGradient%3e%3clinearGradient id='paint4_linear' x1='10.4' x2='-1626.5' y1='-2603.8' y2='-1399.5' gradientUnits='userSpaceOnUse'%3e%3cstop stop-color='white'/%3e%3cstop offset='1' stop-color='white' stop-opacity='0'/%3e%3c/linearGradient%3e%3c/defs%3e%3c/svg%3e")`,
 };

+/**
+ * The color range variants that are used in e.g. colorful bursts.
+ *
+ * @public
+ */
 export const colorVariants: Record<string, string[]> = {
  darkGrey: ['#171717', '#383838'],
  marineBlue: ['#006D8F', '#0049A1'],
@@ -43,9 +54,15 @@ export const colorVariants: Record<string, string[]> = {
  pinkSea: ['#C8077A', '#C2297D'],
 };

-// As the background shapes and colors are decorative, we place them onto
-// the page as a css background-image instead of an html element of its own.
-// Utility to not have to write colors and shapes twice.
+/**
+ * Utility to not have to write colors and shapes twice.
+ *
+ * @public
+ * @remarks
+ *
+ * As the background shapes and colors are decorative, we place them onto the
+ * page as a css background-image instead of an html element of its own.
+ */
 export function genPageTheme(colors: string[], shape: string): PageTheme {
  const gradientColors = colors.length === 1 ? [colors[0], colors[0]] : colors;
  const gradient = `linear-gradient(90deg, ${gradientColors.join(', ')})`;
@@ -54,6 +71,11 @@ export function genPageTheme(colors: string[], shape: string): PageTheme {
  return { colors, shape, backgroundImage };
 }

+/**
+ * All of the builtin page themes.
+ *
+ * @public
+ */
 export const pageTheme: Record<string, PageTheme> = {
  home: genPageTheme(colorVariants.teal, shapes.wave),
  documentation: genPageTheme(colorVariants.pinkSea, shapes.wave2),
@@ -18,6 +18,11 @@ import { createTheme } from './baseTheme';
 import { pageTheme } from './pageTheme';
 import { yellow } from '@material-ui/core/colors';

+/**
+ * The default Backstage light theme.
+ *
+ * @public
+ */
 export const lightTheme = createTheme({
  palette: {
    type: 'light',
@@ -83,6 +88,11 @@ export const lightTheme = createTheme({
  pageTheme,
 });

+/**
+ * The default Backstage dark theme.
+ *
+ * @public
+ */
 export const darkTheme = createTheme({
  palette: {
    type: 'dark',
@@ -79,28 +79,63 @@ export type BackstagePaletteAdditions = {
  };
 };

+/**
+ * The full Backstage palette.
+ *
+ * @public
+ */
 export type BackstagePalette = Palette & BackstagePaletteAdditions;
+
+/**
+ * The full Backstage palette options.
+ *
+ * @public
+ */
 export type BackstagePaletteOptions = PaletteOptions &
  BackstagePaletteAdditions;

+/**
+ * Selector for what page theme to use.
+ *
+ * @public
+ */
 export type PageThemeSelector = {
  themeId: string;
 };

+/**
+ * A Backstage theme.
+ *
+ * @public
+ */
 export interface BackstageTheme extends Theme {
  palette: BackstagePalette;
  page: PageTheme;
-  getPageTheme: ({ themeId }: PageThemeSelector) => PageTheme;
-}
-
-export interface BackstageThemeOptions extends ThemeOptions {
-  palette: BackstagePaletteOptions;
-  page: PageTheme;
-  getPageTheme: ({ themeId }: PageThemeSelector) => PageTheme;
+  getPageTheme: (selector: PageThemeSelector) => PageTheme;
 }

 /**
- * A simpler configuration for creating a new theme that just tweaks some parts of the backstage one.
+ * Backstage theme options.
+ *
+ * @public
+ * @remarks
+ *
+ * This is essentially a partial theme definition made by the user, that then
+ * gets merged together with defaults and other values to form the final
+ * {@link BackstageTheme}.
+ *
+ */
+export interface BackstageThemeOptions extends ThemeOptions {
+  palette: BackstagePaletteOptions;
+  page: PageTheme;
+  getPageTheme: (selector: PageThemeSelector) => PageTheme;
+}
+
+/**
+ * A simpler configuration for creating a new theme that just tweaks some parts
+ * of the backstage one.
+ *
+ * @public
 */
 export type SimpleThemeOptions = {
  palette: BackstagePaletteOptions;
@@ -109,6 +144,11 @@ export type SimpleThemeOptions = {
  fontFamily?: string;
 };

+/**
+ * The theme definitions for a given layout page.
+ *
+ * @public
+ */
 export type PageTheme = {
  colors: string[];
  shape: string;