@zendeskgarden/react-theming 9.3.0 → 9.5.0

package/README.md

@@ -42,7 +42,37 @@ complex, depending on your needs:
   behavior and RTL layout of Garden's tabs component with an alternate visual
   design (i.e. closer to the look of browser tabs).
 
-### RTL
+#### Color scheme
+
+The `ColorSchemeProvider` and `useColorScheme` hook add the capability for a
+user to persist a preferred system color scheme (`'light'`, `'dark'`, or
+`'system'`). See
+[Storybook](https://zendeskgarden.github.io/react-components/?path=/docs/packages-theming-colorschemeprovider--color-scheme-provider)
+for more details.
+
+```jsx
+import {
+  useColorScheme,
+  ColorSchemeProvider,
+  ThemeProvider,
+  DEFAULT_THEME
+} from '@zendeskgarden/react-theming';
+
+const ThemedApp = ({ children }) => {
+  const { colorScheme } = useColorScheme();
+  const theme = { ...DEFAULT_THEME, colors: { ...DEFAULT_THEME.colors, base: colorScheme } };
+
+  return <ThemeProvider theme={theme}>{children}</ThemeProvider>;
+};
+
+const App = ({ children }) => (
+  <ColorSchemeProvider>
+    <ThemedApp>{children}</ThemedApp>
+  </ColorSchemeProvider>
+);
+```
+
+#### RTL
 
 ```jsx
 import { ThemeProvider, DEFAULT_THEME } from '@zendeskgarden/react-theming';

package/dist/esm/elements/ColorSchemeProvider.js

@@ -0,0 +1,71 @@
+/**
+* Copyright Zendesk, Inc.
+*
+* Use of this source code is governed under the Apache License, Version 2.0
+* found at http://www.apache.org/licenses/LICENSE-2.0.
+*/
+import React, { createContext, useMemo, useCallback, useState, useEffect } from 'react';
+
+const useColorScheme = function (initialState) {
+  let colorSchemeKey = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 'color-scheme';
+  const localStorage = typeof window === 'undefined' ? undefined : window.localStorage;
+  const mediaQuery = typeof window === 'undefined' ? undefined : window.matchMedia('(prefers-color-scheme: dark)');
+  const getState = useCallback(_state => {
+    const isSystem = _state === 'system' || _state === undefined || _state === null;
+    let colorScheme;
+    if (isSystem) {
+      colorScheme = mediaQuery?.matches ? 'dark' : 'light';
+    } else {
+      colorScheme = _state;
+    }
+    return {
+      isSystem,
+      colorScheme
+    };
+  }, [mediaQuery?.matches]);
+  const [state, setState] = useState(getState(localStorage?.getItem(colorSchemeKey) || initialState));
+  useEffect(() => {
+    const eventListener = () => {
+      setState(getState('system'));
+    };
+    if (state.isSystem) {
+      mediaQuery?.addEventListener('change', eventListener);
+    } else {
+      mediaQuery?.removeEventListener('change', eventListener);
+    }
+    return () => {
+      mediaQuery?.removeEventListener('change', eventListener);
+    };
+  }, [getState, state.isSystem, mediaQuery]);
+  return {
+    isSystem: state.isSystem,
+    colorScheme: state.colorScheme,
+    setColorScheme: colorScheme => {
+      setState(getState(colorScheme));
+      localStorage?.setItem(colorSchemeKey, colorScheme);
+    }
+  };
+};
+const ColorSchemeContext = createContext(undefined);
+const ColorSchemeProvider = _ref => {
+  let {
+    children,
+    colorSchemeKey,
+    initialColorScheme
+  } = _ref;
+  const {
+    isSystem,
+    colorScheme,
+    setColorScheme
+  } = useColorScheme(initialColorScheme, colorSchemeKey);
+  const contextValue = useMemo(() => ({
+    colorScheme,
+    isSystem,
+    setColorScheme
+  }), [isSystem, colorScheme, setColorScheme]);
+  return React.createElement(ColorSchemeContext.Provider, {
+    value: contextValue
+  }, children);
+};
+
+export { ColorSchemeContext, ColorSchemeProvider };

package/dist/esm/index.js

@@ -4,10 +4,12 @@
 * Use of this source code is governed under the Apache License, Version 2.0
 * found at http://www.apache.org/licenses/LICENSE-2.0.
 */
+export { ColorSchemeProvider } from './elements/ColorSchemeProvider.js';
 export { ThemeProvider } from './elements/ThemeProvider.js';
 export { default as DEFAULT_THEME } from './elements/theme/index.js';
 export { default as PALETTE } from './elements/palette/index.js';
 export { default as retrieveComponentStyles } from './utils/retrieveComponentStyles.js';
+export { componentStyles } from './utils/componentStyles.js';
 export { getArrowPosition } from './utils/getArrowPosition.js';
 export { getCheckeredBackground } from './utils/getCheckeredBackground.js';
 export { getColor } from './utils/getColor.js';
@@ -18,6 +20,7 @@ export { default as getLineHeight } from './utils/getLineHeight.js';
 export { getMenuPosition } from './utils/getMenuPosition.js';
 export { default as mediaQuery } from './utils/mediaQuery.js';
 export { default as arrowStyles } from './utils/arrowStyles.js';
+export { useColorScheme } from './utils/useColorScheme.js';
 export { useDocument } from './utils/useDocument.js';
 export { useWindow } from './utils/useWindow.js';
 export { useText } from './utils/useText.js';

package/dist/esm/utils/componentStyles.js

@@ -0,0 +1,21 @@
+/**
+* Copyright Zendesk, Inc.
+*
+* Use of this source code is governed under the Apache License, Version 2.0
+* found at http://www.apache.org/licenses/LICENSE-2.0.
+*/
+const componentStyles = props => {
+  let retVal;
+  const components = props.theme.components;
+  const componentId = props.componentId || props['data-garden-id'];
+  if (components && componentId) {
+    retVal = components[componentId];
+    if (typeof retVal === 'function') {
+      const fn = retVal;
+      retVal = fn(props);
+    }
+  }
+  return retVal;
+};
+
+export { componentStyles };

package/dist/esm/utils/retrieveComponentStyles.js

@@ -5,7 +5,7 @@
 * found at http://www.apache.org/licenses/LICENSE-2.0.
 */
 function retrieveComponentStyles(componentId, props) {
-  const components = props.theme && props.theme.components;
+  const components = props.theme?.components;
   if (!components) {
     return undefined;
   }

package/dist/esm/utils/useColorScheme.js

@@ -0,0 +1,18 @@
+/**
+* Copyright Zendesk, Inc.
+*
+* Use of this source code is governed under the Apache License, Version 2.0
+* found at http://www.apache.org/licenses/LICENSE-2.0.
+*/
+import { useContext } from 'react';
+import { ColorSchemeContext } from '../elements/ColorSchemeProvider.js';
+
+const useColorScheme = () => {
+  const context = useContext(ColorSchemeContext);
+  if (!context) {
+    throw new Error('Error: this component must be rendered within a <ColorSchemeProvider>.');
+  }
+  return context;
+};
+
+export { useColorScheme };

package/dist/index.cjs.js

@@ -20,6 +20,68 @@ var styled__default = /*#__PURE__*/_interopDefault(styled);
 var get__default = /*#__PURE__*/_interopDefault(get);
 var memoize__default = /*#__PURE__*/_interopDefault(memoize);
 
+const useColorScheme$1 = function (initialState) {
+  let colorSchemeKey = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 'color-scheme';
+  const localStorage = typeof window === 'undefined' ? undefined : window.localStorage;
+  const mediaQuery = typeof window === 'undefined' ? undefined : window.matchMedia('(prefers-color-scheme: dark)');
+  const getState = React.useCallback(_state => {
+    const isSystem = _state === 'system' || _state === undefined || _state === null;
+    let colorScheme;
+    if (isSystem) {
+      colorScheme = mediaQuery?.matches ? 'dark' : 'light';
+    } else {
+      colorScheme = _state;
+    }
+    return {
+      isSystem,
+      colorScheme
+    };
+  }, [mediaQuery?.matches]);
+  const [state, setState] = React.useState(getState(localStorage?.getItem(colorSchemeKey) || initialState));
+  React.useEffect(() => {
+    const eventListener = () => {
+      setState(getState('system'));
+    };
+    if (state.isSystem) {
+      mediaQuery?.addEventListener('change', eventListener);
+    } else {
+      mediaQuery?.removeEventListener('change', eventListener);
+    }
+    return () => {
+      mediaQuery?.removeEventListener('change', eventListener);
+    };
+  }, [getState, state.isSystem, mediaQuery]);
+  return {
+    isSystem: state.isSystem,
+    colorScheme: state.colorScheme,
+    setColorScheme: colorScheme => {
+      setState(getState(colorScheme));
+      localStorage?.setItem(colorSchemeKey, colorScheme);
+    }
+  };
+};
+const ColorSchemeContext = React.createContext(undefined);
+const ColorSchemeProvider = _ref => {
+  let {
+    children,
+    colorSchemeKey,
+    initialColorScheme
+  } = _ref;
+  const {
+    isSystem,
+    colorScheme,
+    setColorScheme
+  } = useColorScheme$1(initialColorScheme, colorSchemeKey);
+  const contextValue = React.useMemo(() => ({
+    colorScheme,
+    isSystem,
+    setColorScheme
+  }), [isSystem, colorScheme, setColorScheme]);
+  return React__default.default.createElement(ColorSchemeContext.Provider, {
+    value: contextValue
+  }, children);
+};
+
 const PALETTE = {
   black: '#000',
   white: '#fff',
@@ -512,7 +574,7 @@ const ThemeProvider = _ref => {
 };
 
 function retrieveComponentStyles(componentId, props) {
-  const components = props.theme && props.theme.components;
+  const components = props.theme?.components;
   if (!components) {
     return undefined;
   }
@@ -523,6 +585,20 @@ function retrieveComponentStyles(componentId, props) {
   return componentStyles;
 }
 
+const componentStyles = props => {
+  let retVal;
+  const components = props.theme.components;
+  const componentId = props.componentId || props['data-garden-id'];
+  if (components && componentId) {
+    retVal = components[componentId];
+    if (typeof retVal === 'function') {
+      const fn = retVal;
+      retVal = fn(props);
+    }
+  }
+  return retVal;
+};
+
 const POSITION_MAP = {
   top: 'bottom',
   'top-start': 'bottom-left',
@@ -1319,6 +1395,14 @@ function arrowStyles(position) {
   return styled.css(["position:relative;&::before,&::after{position:absolute;border-width:inherit;border-style:inherit;background-color:inherit;width:", ";height:", ";content:'';box-sizing:inherit;}&::before{border-color:inherit;clip-path:polygon(100% ", "px,", "px 100%,100% 100%);}&::after{border-color:transparent;background-clip:content-box;clip-path:polygon(100% ", "px,", "px 100%,100% 100%);}", ";", ";"], squareSizePx, squareSizePx, beforeOffset, beforeOffset, afterOffset, afterOffset, positionStyles(position, squareSizeRounded, inset, shift), options.animationModifier && animationStyles$1(position, options.animationModifier));
 }
 
+const useColorScheme = () => {
+  const context = React.useContext(ColorSchemeContext);
+  if (!context) {
+    throw new Error('Error: this component must be rendered within a <ColorSchemeProvider>.');
+  }
+  return context;
+};
+
 const useDocument = theme => {
   const [controlledDocument, setControlledDocument] = React.useState();
   React.useEffect(() => {
@@ -1472,6 +1556,7 @@ const MENU_POSITION = ['top', 'right', 'bottom', 'left'];
 const PLACEMENT = ['top', 'top-start', 'top-end', 'bottom', 'bottom-start', 'bottom-end', 'end', 'end-top', 'end-bottom', 'start', 'start-top', 'start-bottom'];
 
 exports.ARROW_POSITION = ARROW_POSITION;
+exports.ColorSchemeProvider = ColorSchemeProvider;
 exports.DEFAULT_THEME = DEFAULT_THEME;
 exports.MENU_POSITION = MENU_POSITION;
 exports.PALETTE = PALETTE;
@@ -1480,6 +1565,7 @@ exports.SELECTOR_FOCUS_VISIBLE = SELECTOR_FOCUS_VISIBLE;
 exports.StyledBaseIcon = StyledBaseIcon;
 exports.ThemeProvider = ThemeProvider;
 exports.arrowStyles = arrowStyles;
+exports.componentStyles = componentStyles;
 exports.focusStyles = focusStyles;
 exports.getArrowPosition = getArrowPosition;
 exports.getCheckeredBackground = getCheckeredBackground;
@@ -1492,6 +1578,7 @@ exports.getMenuPosition = getMenuPosition;
 exports.mediaQuery = mediaQuery;
 exports.menuStyles = menuStyles;
 exports.retrieveComponentStyles = retrieveComponentStyles;
+exports.useColorScheme = useColorScheme;
 exports.useDocument = useDocument;
 exports.useText = useText;
 exports.useWindow = useWindow;

package/dist/typings/elements/ColorSchemeProvider.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright Zendesk, Inc.
+ *
+ * Use of this source code is governed under the Apache License, Version 2.0
+ * found at http://www.apache.org/licenses/LICENSE-2.0.
+ */
+import React, { PropsWithChildren } from 'react';
+import { IColorSchemeContext, IColorSchemeProviderProps } from '../types';
+export declare const ColorSchemeContext: React.Context<IColorSchemeContext | undefined>;
+export declare const ColorSchemeProvider: ({ children, colorSchemeKey, initialColorScheme }: PropsWithChildren<IColorSchemeProviderProps>) => React.JSX.Element;

package/dist/typings/index.d.ts

@@ -4,10 +4,12 @@
  * Use of this source code is governed under the Apache License, Version 2.0
  * found at http://www.apache.org/licenses/LICENSE-2.0.
  */
+export { ColorSchemeProvider } from './elements/ColorSchemeProvider';
 export { ThemeProvider } from './elements/ThemeProvider';
 export { default as DEFAULT_THEME } from './elements/theme';
 export { default as PALETTE } from './elements/palette';
 export { default as retrieveComponentStyles } from './utils/retrieveComponentStyles';
+export { componentStyles } from './utils/componentStyles';
 export { getArrowPosition } from './utils/getArrowPosition';
 export { getCheckeredBackground } from './utils/getCheckeredBackground';
 export { getColor } from './utils/getColor';
@@ -18,10 +20,11 @@ export { default as getLineHeight } from './utils/getLineHeight';
 export { getMenuPosition } from './utils/getMenuPosition';
 export { default as mediaQuery } from './utils/mediaQuery';
 export { default as arrowStyles } from './utils/arrowStyles';
+export { useColorScheme } from './utils/useColorScheme';
 export { useDocument } from './utils/useDocument';
 export { useWindow } from './utils/useWindow';
 export { useText } from './utils/useText';
 export { default as menuStyles } from './utils/menuStyles';
 export { focusStyles, SELECTOR_FOCUS_VISIBLE } from './utils/focusStyles';
 export { StyledBaseIcon } from './utils/StyledBaseIcon';
-export { ARROW_POSITION, MENU_POSITION, PLACEMENT, type IGardenTheme, type IStyledBaseIconProps, type IThemeProviderProps, type ArrowPosition, type CheckeredBackgroundParameters, type ColorParameters, type FocusBoxShadowParameters, type FocusStylesParameters, type MenuPosition, type Placement } from './types';
+export { ARROW_POSITION, MENU_POSITION, PLACEMENT, type IColorSchemeContext, type IColorSchemeProviderProps, type IGardenTheme, type IStyledBaseIconProps, type IThemeProviderProps, type ArrowPosition, type CheckeredBackgroundParameters, type ColorParameters, type ColorScheme, type FocusBoxShadowParameters, type FocusStylesParameters, type MenuPosition, type Placement } from './types';

package/dist/typings/types/index.d.ts

@@ -165,6 +165,28 @@ export interface IGardenTheme {
         xxl: string;
     };
 }
+export type ColorScheme = IGardenTheme['colors']['base'] | 'system';
+export interface IColorSchemeContext {
+    /** Returns the current color scheme */
+    colorScheme: IGardenTheme['colors']['base'];
+    /** Indicates whether the `colorScheme` is determined by the system */
+    isSystem: boolean;
+    /** Provides the mechanism for updating the current color scheme */
+    setColorScheme: (colorScheme: ColorScheme) => void;
+}
+export interface IColorSchemeProviderProps {
+    /**
+     * Sets the initial color scheme and provides `localStorage` persistence (see
+     * the `useColorScheme` hook). A user's stored preference overrides this
+     * value.
+     */
+    initialColorScheme?: ColorScheme;
+    /**
+     * Specifies the key used to store the user's preferred color scheme in
+     * `localStorage`
+     */
+    colorSchemeKey?: string;
+}
 export interface IThemeProviderProps extends Partial<ThemeProviderProps<IGardenTheme>> {
     /**
      * Provides values for component styling. See styled-components

package/dist/typings/utils/componentStyles.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright Zendesk, Inc.
+ *
+ * Use of this source code is governed under the Apache License, Version 2.0
+ * found at http://www.apache.org/licenses/LICENSE-2.0.
+ */
+import { DefaultTheme } from 'styled-components';
+/**
+ * CSS for component customizations based on `theme.components[componentId]`.
+ *
+ * @param {Object} props.theme Provides `components` object use to resolve the given component ID
+ * @param {String} [props.componentId] Specifies the lookup id for * `theme.components` styles.
+ *  The ID will be inferred from the `'data-garden-id'` attribute if not provided.
+ *
+ * @returns component CSS styles
+ */
+export declare const componentStyles: (props: {
+    theme: DefaultTheme;
+    componentId?: string;
+}) => string | undefined;

package/dist/typings/utils/retrieveComponentStyles.d.ts

@@ -4,6 +4,8 @@
  * Use of this source code is governed under the Apache License, Version 2.0
  * found at http://www.apache.org/licenses/LICENSE-2.0.
  */
-import { ThemeProps, DefaultTheme } from 'styled-components';
-/** @component */
-export default function retrieveComponentStyles(componentId: string, props: Partial<ThemeProps<Partial<DefaultTheme>>>): any;
+import { DefaultTheme } from 'styled-components';
+/** @deprecated Use `componentStyles` instead. */
+export default function retrieveComponentStyles(componentId: string, props: {
+    theme?: Partial<DefaultTheme>;
+}): any;

package/dist/typings/utils/useColorScheme.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright Zendesk, Inc.
+ *
+ * Use of this source code is governed under the Apache License, Version 2.0
+ * found at http://www.apache.org/licenses/LICENSE-2.0.
+ */
+/**
+ * Provides the current color scheme for the context `ThemeProvider`.
+ *
+ * @returns {object} Current color scheme accessor and mutator.
+ */
+export declare const useColorScheme: () => import("..").IColorSchemeContext;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zendeskgarden/react-theming",
-  "version": "9.3.0",
+  "version": "9.5.0",
   "description": "Theming utilities and components within the Garden Design System",
   "license": "Apache-2.0",
   "author": "Zendesk Garden <garden@zendesk.com>",
@@ -47,5 +47,5 @@
     "access": "public"
   },
   "zendeskgarden:src": "src/index.ts",
-  "gitHead": "fa6461e0d9fae27956980056006e8013daedc6b9"
+  "gitHead": "43546784a9aa985332ddcc6dd09209a11e2c03ff"
 }