diff --git a/.changeset/forty-cooks-film.md b/.changeset/forty-cooks-film.md new file mode 100644 index 0000000000..20ff746949 --- /dev/null +++ b/.changeset/forty-cooks-film.md @@ -0,0 +1,5 @@ +--- +'@backstage/theme': patch +--- + +More theme API cleanup diff --git a/packages/theme/api-report.md b/packages/theme/api-report.md index 41ea2420f2..72d7887214 100644 --- a/packages/theme/api-report.md +++ b/packages/theme/api-report.md @@ -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; -// 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; -// 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; -// 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; diff --git a/packages/theme/src/baseTheme.ts b/packages/theme/src/baseTheme.ts index 4a45516a55..da663e3398 100644 --- a/packages/theme/src/baseTheme.ts +++ b/packages/theme/src/baseTheme.ts @@ -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; diff --git a/packages/theme/src/pageTheme.ts b/packages/theme/src/pageTheme.ts index 5765e13c23..ae81dc8534 100644 --- a/packages/theme/src/pageTheme.ts +++ b/packages/theme/src/pageTheme.ts @@ -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 = { 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 = { darkGrey: ['#171717', '#383838'], marineBlue: ['#006D8F', '#0049A1'], @@ -43,9 +54,15 @@ export const colorVariants: Record = { 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 = { home: genPageTheme(colorVariants.teal, shapes.wave), documentation: genPageTheme(colorVariants.pinkSea, shapes.wave2), diff --git a/packages/theme/src/themes.ts b/packages/theme/src/themes.ts index d7a4a6d785..3eb1bcc252 100644 --- a/packages/theme/src/themes.ts +++ b/packages/theme/src/themes.ts @@ -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', diff --git a/packages/theme/src/types.ts b/packages/theme/src/types.ts index 770b55d341..db3e89fa4b 100644 --- a/packages/theme/src/types.ts +++ b/packages/theme/src/types.ts @@ -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;