@backstage/theme 0.3.0 → 0.4.0-next.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @backstage/theme
 
+## 0.4.0-next.0
+
+### Minor Changes
+
+- 1fd38bc4141a: **MUI v5 Support:** Adding platform-wide support for MUI v5 allowing a transition phase for migrating central plugins & components over. We still support v4 instances & plugins by adding a
+
+  To allow the future support of plugins & components using MUI v5 you want to upgrade your `AppTheme`'s to using the `UnifiedThemeProvider`
+
+  ```diff
+       Provider: ({ children }) => (
+  -    <ThemeProvider theme={lightTheme}>
+  -      <CssBaseline>{children}</CssBaseline>
+  -    </ThemeProvider>
+  +    <UnifiedThemeProvider theme={builtinThemes.light} children={children} />
+       ),
+  ```
+
 ## 0.3.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -1,6 +1,21 @@
-import { Theme, ThemeOptions } from '@material-ui/core';
-import { Palette, PaletteOptions } from '@material-ui/core/styles/createPalette';
 import { Overrides } from '@material-ui/core/styles/overrides';
+import { ComponentsProps } from '@material-ui/core/styles/props';
+import { Theme, ThemeOptions, PaletteOptions as PaletteOptions$1 } from '@mui/material/styles';
+import { ThemeOptions as ThemeOptions$1 } from '@material-ui/core/styles';
+import { PaletteOptions, Palette } from '@material-ui/core/styles/createPalette';
+import { ReactNode } from 'react';
+import * as _material_ui_core from '@material-ui/core';
+import { ThemeOptions as ThemeOptions$2, Theme as Theme$1 } from '@material-ui/core';
+
+/**
+ * Transform MUI v5 component themes into a v4 theme props and overrides.
+ *
+ * @public
+ */
+declare function transformV5ComponentThemesToV4(theme: Theme, components?: ThemeOptions['components']): {
+    overrides: Overrides;
+    props: ComponentsProps;
+};
 
 /**
  * Backstage specific additions to the material-ui palette.
@@ -72,108 +87,155 @@ type BackstagePaletteAdditions = {
     };
 };
 /**
- * The full Backstage palette.
- *
- * @public
- */
-type BackstagePalette = Palette & BackstagePaletteAdditions;
-/**
- * The full Backstage palette options.
+ * Selector for what page theme to use.
  *
  * @public
  */
-type BackstagePaletteOptions = PaletteOptions & BackstagePaletteAdditions;
+type PageThemeSelector = {
+    themeId: string;
+};
 /**
- * Selector for what page theme to use.
+ * The theme definitions for a given layout page.
  *
  * @public
  */
-type PageThemeSelector = {
-    themeId: string;
+type PageTheme = {
+    colors: string[];
+    shape: string;
+    backgroundImage: string;
+    fontColor: string;
 };
 /**
- * A Backstage theme.
+ * Backstage specific additions to the material-ui theme.
  *
  * @public
  */
-interface BackstageTheme extends Theme {
-    palette: BackstagePalette;
+type BackstageThemeAdditions = {
     page: PageTheme;
     getPageTheme: (selector: PageThemeSelector) => PageTheme;
-}
+};
+
 /**
- * Backstage theme options.
+ * A container of one theme for multiple different MUI versions.
  *
- * @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}.
+ * Currently known keys are 'v4' and 'v5'.
  *
+ * @public
  */
-interface BackstageThemeOptions extends ThemeOptions {
-    palette: BackstagePaletteOptions;
-    page: PageTheme;
-    getPageTheme: (selector: PageThemeSelector) => PageTheme;
+interface UnifiedTheme {
+    getTheme(version: string): unknown | undefined;
 }
+
 /**
- * A simpler configuration for creating a new theme that just tweaks some parts
- * of the backstage one.
+ * Options for creating a new {@link UnifiedTheme}.
  *
  * @public
  */
-type SimpleThemeOptions = {
-    palette: BackstagePaletteOptions;
-    defaultPageTheme: string;
+interface UnifiedThemeOptions {
+    palette: PaletteOptions & PaletteOptions$1;
+    defaultPageTheme?: string;
     pageTheme?: Record<string, PageTheme>;
     fontFamily?: string;
     htmlFontSize?: number;
-};
+    components?: ThemeOptions['components'];
+}
 /**
- * The theme definitions for a given layout page.
+ * Creates a new {@link UnifiedTheme} using the provided options.
  *
  * @public
  */
-type PageTheme = {
-    colors: string[];
-    shape: string;
-    backgroundImage: string;
-    fontColor: string;
-};
-
+declare function createUnifiedTheme(options: UnifiedThemeOptions): UnifiedTheme;
 /**
- * The default Backstage light theme.
+ * Creates a new {@link UnifiedTheme} using MUI v4 theme options.
+ * Note that this uses `adaptV4Theme` from MUI v5, which is deprecated.
  *
  * @public
  */
-declare const lightTheme: BackstageTheme;
+declare function createUnifiedThemeFromV4(options: ThemeOptions$1): UnifiedTheme;
+
 /**
- * The default Backstage dark theme.
+ * Built-in Backstage MUI themes.
  *
  * @public
  */
-declare const darkTheme: BackstageTheme;
+declare const themes: {
+    light: UnifiedTheme;
+    dark: UnifiedTheme;
+};
 
 /**
- * A helper for creating theme options.
+ * Props for {@link UnifiedThemeProvider}.
  *
  * @public
  */
-declare function createThemeOptions(options: SimpleThemeOptions): BackstageThemeOptions;
+interface UnifiedThemeProviderProps {
+    children: ReactNode;
+    theme: UnifiedTheme;
+    noCssBaseline?: boolean;
+}
 /**
- * A helper for creating theme overrides.
+ * Provides themes for all MUI versions supported by the provided unified theme.
  *
  * @public
  */
-declare function createThemeOverrides(theme: BackstageTheme): Overrides;
+declare function UnifiedThemeProvider(props: UnifiedThemeProviderProps): JSX.Element;
+
+/**
+ * Options for {@link createBaseThemeOptions}.
+ *
+ * @public
+ */
+interface BaseThemeOptionsInput<PaletteOptions> {
+    palette: PaletteOptions;
+    defaultPageTheme?: string;
+    pageTheme?: Record<string, PageTheme>;
+    fontFamily?: string;
+    htmlFontSize?: number;
+}
 /**
- * Creates a Backstage MUI theme using a palette. The theme is created with the
- * common Backstage options and component styles.
+ * A helper for creating theme options.
  *
  * @public
  */
-declare function createTheme(options: SimpleThemeOptions): BackstageTheme;
+declare function createBaseThemeOptions<PaletteOptions>(options: BaseThemeOptionsInput<PaletteOptions>): {
+    palette: PaletteOptions;
+    typography: {
+        htmlFontSize: number;
+        fontFamily: string;
+        h1: {
+            fontSize: number;
+            fontWeight: number;
+            marginBottom: number;
+        };
+        h2: {
+            fontSize: number;
+            fontWeight: number;
+            marginBottom: number;
+        };
+        h3: {
+            fontSize: number;
+            fontWeight: number;
+            marginBottom: number;
+        };
+        h4: {
+            fontWeight: number;
+            fontSize: number;
+            marginBottom: number;
+        };
+        h5: {
+            fontWeight: number;
+            fontSize: number;
+            marginBottom: number;
+        };
+        h6: {
+            fontWeight: number;
+            fontSize: number;
+            marginBottom: number;
+        };
+    };
+    page: PageTheme;
+    getPageTheme: ({ themeId }: PageThemeSelector) => PageTheme;
+};
 
 /**
  * The default predefined burst shapes.
@@ -221,4 +283,287 @@ declare function genPageTheme(props: {
  */
 declare const pageTheme: Record<string, PageTheme>;
 
-export { BackstagePalette, BackstagePaletteAdditions, BackstagePaletteOptions, BackstageTheme, BackstageThemeOptions, PageTheme, PageThemeSelector, SimpleThemeOptions, colorVariants, createTheme, createThemeOptions, createThemeOverrides, darkTheme, genPageTheme, lightTheme, pageTheme, shapes };
+/**
+ * Built-in Backstage color palettes.
+ *
+ * @public
+ */
+declare const palettes: {
+    light: {
+        type: "light";
+        mode: "light";
+        background: {
+            default: string;
+            paper: string;
+        };
+        status: {
+            ok: string;
+            warning: string;
+            error: string;
+            running: string;
+            pending: string;
+            aborted: string;
+        };
+        bursts: {
+            fontColor: string;
+            slackChannelText: string;
+            backgroundColor: {
+                default: string;
+            };
+            gradient: {
+                linear: string;
+            };
+        };
+        primary: {
+            main: string;
+        };
+        banner: {
+            info: string;
+            error: string;
+            text: string;
+            link: string;
+            closeButtonColor: string;
+            warning: string;
+        };
+        border: string;
+        textContrast: string;
+        textVerySubtle: string;
+        textSubtle: string;
+        highlight: string;
+        errorBackground: string;
+        warningBackground: string;
+        infoBackground: string;
+        errorText: string;
+        infoText: string;
+        warningText: string;
+        linkHover: string;
+        link: string;
+        gold: string;
+        navigation: {
+            background: string;
+            indicator: string;
+            color: string;
+            selectedColor: string;
+            navItem: {
+                hoverBackground: string;
+            };
+            submenu: {
+                background: string;
+            };
+        };
+        pinSidebarButton: {
+            icon: string;
+            background: string;
+        };
+        tabbar: {
+            indicator: string;
+        };
+    };
+    dark: {
+        type: "dark";
+        mode: "dark";
+        background: {
+            default: string;
+            paper: string;
+        };
+        status: {
+            ok: string;
+            warning: string;
+            error: string;
+            running: string;
+            pending: string;
+            aborted: string;
+        };
+        bursts: {
+            fontColor: string;
+            slackChannelText: string;
+            backgroundColor: {
+                default: string;
+            };
+            gradient: {
+                linear: string;
+            };
+        };
+        primary: {
+            main: string;
+            dark: string;
+        };
+        secondary: {
+            main: string;
+        };
+        banner: {
+            info: string;
+            error: string;
+            text: string;
+            link: string;
+            closeButtonColor: string;
+            warning: string;
+        };
+        border: string;
+        textContrast: string;
+        textVerySubtle: string;
+        textSubtle: string;
+        highlight: string;
+        errorBackground: string;
+        warningBackground: string;
+        infoBackground: string;
+        errorText: string;
+        infoText: string;
+        warningText: string;
+        linkHover: string;
+        link: string;
+        gold: string;
+        navigation: {
+            background: string;
+            indicator: string;
+            color: string;
+            selectedColor: string;
+            navItem: {
+                hoverBackground: string;
+            };
+            submenu: {
+                background: string;
+            };
+        };
+        pinSidebarButton: {
+            icon: string;
+            background: string;
+        };
+        tabbar: {
+            indicator: string;
+        };
+    };
+};
+
+/**
+ * The old MUI v4 Backstage light theme.
+ *
+ * @public
+ * @deprecated Use {@link themes.light} instead.
+ */
+declare const lightTheme: _material_ui_core.Theme;
+/**
+ * The old MUI v4 Backstage dark theme.
+ *
+ * @public
+ * @deprecated Use {@link themes.dark} instead.
+ */
+declare const darkTheme: _material_ui_core.Theme;
+
+/**
+ * The full Backstage palette.
+ *
+ * @public
+ * @deprecated This type is deprecated, the MUI Palette type is now always extended instead.
+ */
+type BackstagePalette = Palette & BackstagePaletteAdditions;
+/**
+ * The full Backstage palette options.
+ *
+ * @public
+ * @deprecated This type is deprecated, the MUI PaletteOptions type is now always extended instead.
+ */
+type BackstagePaletteOptions = PaletteOptions & BackstagePaletteAdditions;
+/**
+ * Backstage theme options.
+ *
+ * @public
+ * @deprecated This type is deprecated, the MUI ThemeOptions type is now always extended instead.
+ * @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}.
+ *
+ */
+interface BackstageThemeOptions extends ThemeOptions$2 {
+    palette: BackstagePaletteOptions;
+    page: PageTheme;
+    getPageTheme: (selector: PageThemeSelector) => PageTheme;
+}
+/**
+ * A Backstage theme.
+ *
+ * @public
+ * @deprecated This type is deprecated, the MUI Theme type is now always extended instead.
+ */
+interface BackstageTheme extends Theme$1 {
+    palette: BackstagePalette;
+    page: PageTheme;
+    getPageTheme: (selector: PageThemeSelector) => PageTheme;
+}
+/**
+ * A simpler configuration for creating a new theme that just tweaks some parts
+ * of the backstage one.
+ *
+ * @public
+ * @deprecated Use {@link BaseThemeOptionsInput} instead.
+ */
+type SimpleThemeOptions = {
+    palette: PaletteOptions;
+    defaultPageTheme?: string;
+    pageTheme?: Record<string, PageTheme>;
+    fontFamily?: string;
+    htmlFontSize?: number;
+};
+declare module '@material-ui/core/styles/createPalette' {
+    interface Palette extends BackstagePaletteAdditions {
+    }
+    interface PaletteOptions extends BackstagePaletteAdditions {
+    }
+}
+declare module '@material-ui/core/styles/createTheme' {
+    interface Theme extends BackstageThemeAdditions {
+    }
+    interface ThemeOptions extends BackstageThemeAdditions {
+    }
+}
+
+/**
+ * An old helper for creating MUI v4 theme options.
+ *
+ * @public
+ * @deprecated Use {@link createBaseThemeOptions} instead.
+ */
+declare function createThemeOptions(options: SimpleThemeOptions): ThemeOptions$2;
+/**
+ * * An old helper for creating MUI v4 theme overrides.
+ *
+ * @public
+ * @deprecated Use {@link defaultComponentThemes} with {@link transformV5ComponentThemesToV4} instead.
+ */
+declare function createThemeOverrides(theme: Theme$1): Overrides;
+/**
+ * The old method to create a Backstage MUI v4 theme using a palette.
+ * The theme is created with the common Backstage options and component styles.
+ *
+ * @public
+ * @deprecated Use {@link createUnifiedTheme} instead.
+ */
+declare function createTheme(options: SimpleThemeOptions): Theme$1;
+
+declare module '@mui/material/styles' {
+    interface Palette extends BackstagePaletteAdditions {
+    }
+    interface PaletteOptions extends BackstagePaletteAdditions {
+    }
+}
+declare module '@mui/material/styles' {
+    interface Theme extends BackstageThemeAdditions {
+    }
+    interface ThemeOptions extends BackstageThemeAdditions {
+    }
+}
+declare module '@mui/private-theming/defaultTheme' {
+    interface DefaultTheme extends Theme {
+    }
+}
+
+/**
+ * A helper for creating theme overrides.
+ *
+ * @public
+ */
+declare const defaultComponentThemes: ThemeOptions['components'];
+
+export { BackstagePalette, BackstagePaletteAdditions, BackstagePaletteOptions, BackstageTheme, BackstageThemeAdditions, BackstageThemeOptions, BaseThemeOptionsInput, PageTheme, PageThemeSelector, SimpleThemeOptions, UnifiedTheme, UnifiedThemeOptions, UnifiedThemeProvider, UnifiedThemeProviderProps, colorVariants, createBaseThemeOptions, createTheme, createThemeOptions, createThemeOverrides, createUnifiedTheme, createUnifiedThemeFromV4, darkTheme, defaultComponentThemes, genPageTheme, lightTheme, pageTheme, palettes, shapes, themes, transformV5ComponentThemesToV4 };