braid-design-system 31.0.0 → 31.2.2

package/lib/components/Box/Box.docs.tsx

@@ -1,7 +1,6 @@
 import React from 'react';
 import { ComponentDocs } from '../../../site/src/types';
 import {
-  Box,
   Text,
   TextLink,
   Stack,
@@ -12,6 +11,10 @@ import {
   Strong,
   Alert,
 } from '../';
+// TODO: COLORMODE RELEASE
+// Use public import
+import { Box } from './Box';
+import type { SimpleBackground } from './Box';
 import source from '../../utils/source.macro';
 import Code from '../../../site/src/App/Code/Code';
 import {
@@ -23,15 +26,12 @@ import {
   PseudoProperties,
   BoxShadow,
 } from '../../css/atoms/atomicProperties';
-import { vars } from '../../themes/vars.css';
 import { ThemedExample } from '../../../site/src/App/ThemeSetting';
 
-type BackgroundDocs = Required<
-  Record<keyof typeof vars.backgroundColor, string>
->;
+type BackgroundDocs = Required<Record<SimpleBackground, string>>;
 const validateBackgrounds = (backgrounds: BackgroundDocs) => backgrounds;
 
-type BoxShadowDocs = Required<Record<Exclude<BoxShadow, 'none'>, string>>;
+type BoxShadowDocs = Required<Record<BoxShadow, string>>;
 const validateBoxShadows = (boxShadows: BoxShadowDocs) => boxShadows;
 
 interface AtomicPropertyProps {
@@ -466,6 +466,9 @@ const docs: ComponentDocs = {
             {Object.entries(
               validateBackgrounds({
                 body: 'Used for elements that need to match the body background.',
+                // TODO: COLORMODE RELEASE
+                // bodyDark:
+                //   'Used for elements that need to match the body background in dark context.',
                 brand: 'Used for branding larger areas of the screen.',
                 brandAccent: 'Used for hero elements on the screen.',
                 brandAccentHover: 'Hover colour for “brandAccent” elements.',
@@ -508,6 +511,9 @@ const docs: ComponentDocs = {
                 neutralSoftActive: 'Active colour for "neutralSoft" elements',
                 neutralSoftHover: 'Hover colour for "neutralSoft" elements',
                 surface: 'Used for surfaces that sit on top of body elements',
+                // TODO: COLORMODE RELEASE
+                // surfaceDark:
+                //   'Used for surfaces that sit on top of body elements in a dark context',
               }),
             ).map(([background, description]) => (
               <Columns key={background} space="medium" alignY="center">
@@ -518,11 +524,17 @@ const docs: ComponentDocs = {
                     padding="gutter"
                   >
                     <Box
-                      background={background as keyof BackgroundDocs}
+                      background={{
+                        lightMode: background as keyof BackgroundDocs,
+                        darkMode: background as keyof BackgroundDocs,
+                      }}
                       boxShadow={
-                        background === 'surface'
-                          ? 'borderNeutralLight'
-                          : undefined
+                        (
+                          {
+                            surface: { lightMode: 'borderNeutralLight' },
+                            surfaceDark: { darkMode: 'borderNeutral' },
+                          } as const
+                        )[background]
                       }
                       borderRadius="large"
                       padding="gutter"
@@ -632,14 +644,22 @@ const docs: ComponentDocs = {
               <Columns key={boxShadow} space="medium" alignY="center">
                 <Column width="content">
                   <Box
-                    background={
-                      boxShadow.includes('Inverted') ? 'brand' : 'surface'
-                    }
+                    background={{
+                      lightMode: boxShadow.includes('Inverted')
+                        ? 'neutral'
+                        : 'surface',
+                      darkMode: /^border|outline/.test(boxShadow)
+                        ? 'surfaceDark'
+                        : 'surface',
+                    }}
                     borderRadius="large"
                     padding="gutter"
                   >
                     <Box
-                      boxShadow={boxShadow as keyof BoxShadowDocs}
+                      boxShadow={{
+                        lightMode: boxShadow as keyof BoxShadowDocs,
+                        darkMode: boxShadow as keyof BoxShadowDocs,
+                      }}
                       borderRadius="large"
                       padding="gutter"
                     />

package/lib/components/Box/Box.playroom.tsx

@@ -0,0 +1,37 @@
+import React, { forwardRef } from 'react';
+import { atoms, Atoms } from '../../css/atoms/atoms';
+import { sprinkles } from '../../css/atoms/sprinkles.css';
+import { Box as BraidBox, BoxProps } from './Box';
+
+export const Box = forwardRef<HTMLElement, BoxProps>((props, ref) => {
+  const sprinklesProps: Record<string, unknown> = {};
+  const otherProps: Record<string, unknown> = {};
+
+  for (const key in props) {
+    if (sprinkles.properties.has(key as keyof Omit<Atoms, 'reset'>)) {
+      const value = props[key as keyof typeof props];
+      try {
+        // Try passing to atoms, if sprinkle property but value is not
+        // valid, property will be left out until value is valid.
+        atoms({ [key]: value });
+        sprinklesProps[key] = value;
+      } catch (e) {
+        if (key === 'background') {
+          if (
+            (typeof value === 'string' &&
+              /^customDark|customLight$/.test(value)) ||
+            (typeof value === 'object' && (value.darkMode || value.lightMode))
+          ) {
+            sprinklesProps[key] = value;
+          }
+        }
+      }
+    } else {
+      otherProps[key] = props[key as keyof typeof props];
+    }
+  }
+
+  return <BraidBox ref={ref} {...sprinklesProps} {...otherProps} />;
+});
+
+Box.displayName = 'Box';

package/lib/components/Box/Box.tsx

@@ -9,15 +9,15 @@ import React, {
 import dedent from 'dedent';
 import { base as baseReset } from '../../css/reset/reset.css';
 import { atoms, Atoms } from '../../css/atoms/atoms';
-import { sprinkles } from '../../css/atoms/sprinkles.css';
+import { sprinkles, ColorModeValue } from '../../css/atoms/sprinkles.css';
 import { ColoredBox } from './ColoredBox';
-import { Background } from '../../css/atoms/atomicProperties';
+import { Background, BoxShadow } from '../../css/atoms/atomicProperties';
 
 export type BoxBackgroundVariant = Background | 'customDark' | 'customLight';
 
 export interface BoxBaseProps extends Omit<Atoms, 'reset' | 'background'> {
   className?: ClassValue;
-  background?: BoxBackgroundVariant;
+  background?: ColorModeValue<BoxBackgroundVariant>;
 }
 
 export interface BoxProps
@@ -27,7 +27,7 @@ export interface BoxProps
 }
 
 export const Box = forwardRef<HTMLElement, BoxProps>(
-  ({ component = 'div', className, ...props }, ref) => {
+  ({ component = 'div', className, background, boxShadow, ...props }, ref) => {
     const atomProps: Record<string, unknown> = {};
     const nativeProps: Record<string, unknown> = {};
 
@@ -61,17 +61,17 @@ export const Box = forwardRef<HTMLElement, BoxProps>(
     const atomicClasses = atoms({
       reset: typeof component === 'string' ? component : 'div',
       ...atomProps,
-      background: undefined,
     });
 
     const combinedClasses = `${atomicClasses}${
       userClasses ? ` ${userClasses}` : ''
     }`;
 
-    return props.background ? (
+    return background || boxShadow ? (
       <ColoredBox
         component={component}
-        background={props.background}
+        background={background}
+        boxShadow={boxShadow}
         className={combinedClasses}
         ref={ref}
         {...nativeProps}
@@ -87,3 +87,34 @@ export const Box = forwardRef<HTMLElement, BoxProps>(
 );
 
 Box.displayName = 'Box';
+
+// TODO: COLORMODE RELEASE
+// Remove PublicBox
+export type SimpleBackground = Exclude<Background, 'bodyDark' | 'surfaceDark'>;
+export interface PublicBoxProps extends BoxProps {
+  background?: SimpleBackground | 'customDark' | 'customLight';
+  boxShadow?: BoxShadow;
+}
+
+export const PublicBox = forwardRef<HTMLElement, PublicBoxProps>(
+  (props, ref) => {
+    if (process.env.NODE_ENV !== 'production') {
+      if (
+        typeof props.background !== 'undefined' &&
+        typeof props.background !== 'string'
+      ) {
+        throw new Error('Conditional backgrounds are not suppported');
+      }
+
+      if (
+        typeof props.boxShadow !== 'undefined' &&
+        typeof props.boxShadow !== 'string'
+      ) {
+        throw new Error('Conditional boxShadows are not suppported');
+      }
+    }
+    return <Box {...props} ref={ref} />;
+  },
+);
+
+PublicBox.displayName = 'Box';

package/lib/components/Box/BoxRenderer.tsx

@@ -1,28 +1,42 @@
 import React, { ReactElement } from 'react';
 import clsx from 'clsx';
-import { renderBackgroundProvider } from './BackgroundContext';
+import { BackgroundProvider } from './BackgroundContext';
 import { atoms, Atoms } from '../../css/atoms/atoms';
-import { BoxBaseProps } from './Box';
-import { resolveBackgroundAtom } from './ColoredBox';
+import { BoxBaseProps, SimpleBackground } from './Box';
+import { useColoredBoxClasses } from './ColoredBox';
+import { BoxShadow } from '../../css/atoms/atomicProperties';
 
 export interface BoxRendererProps extends BoxBaseProps {
   component?: Atoms['reset'];
+  // TODO: COLORMODE RELEASE
+  // Remove overrides
+  background?: SimpleBackground | 'customDark' | 'customLight';
+  boxShadow?: BoxShadow;
   children: (className: string) => ReactElement | null;
 }
 
 const ColoredBoxRenderer = ({
   background,
+  boxShadow,
   children,
   className,
 }: {
-  background: NonNullable<BoxRendererProps['background']>;
+  background: BoxRendererProps['background'];
+  boxShadow: BoxRendererProps['boxShadow'];
   children: BoxRendererProps['children'];
   className: string;
 }) => {
-  const colorClasses = resolveBackgroundAtom(background);
-  const element = children(clsx(className, colorClasses));
+  const { backgroundContext, classList } = useColoredBoxClasses({
+    background,
+    boxShadow,
+  });
+  const element = children(clsx(className, classList));
 
-  return renderBackgroundProvider(background, element);
+  return backgroundContext ? (
+    <BackgroundProvider value={backgroundContext}>{element}</BackgroundProvider>
+  ) : (
+    element
+  );
 };
 
 export const BoxRenderer = ({
@@ -30,12 +44,17 @@ export const BoxRenderer = ({
   component = 'div',
   className,
   background,
+  boxShadow,
   ...props
 }: BoxRendererProps) => {
   const classes = clsx(className, atoms({ reset: component, ...props }));
 
-  return background ? (
-    <ColoredBoxRenderer background={background} className={classes}>
+  return background || boxShadow ? (
+    <ColoredBoxRenderer
+      background={background}
+      boxShadow={boxShadow}
+      className={classes}
+    >
       {children}
     </ColoredBoxRenderer>
   ) : (

package/lib/components/Box/ColoredBox.tsx

@@ -1,23 +1,172 @@
-import { createElement, forwardRef } from 'react';
+import React, { createElement, forwardRef } from 'react';
 import { atoms } from '../../css/atoms/atoms';
-import { renderBackgroundProvider } from './BackgroundContext';
-import { BoxProps } from './Box';
+import { useBraidTheme } from '../BraidProvider/BraidThemeContext';
+import {
+  BackgroundProvider,
+  useBackground,
+  useBackgroundLightness,
+} from './BackgroundContext';
+import { BoxBackgroundVariant, BoxProps } from './Box';
+import { Background, BoxShadow } from '../../css/atoms/atomicProperties';
+import * as typographyStyles from '../../hooks/typography/typography.css';
 
 export interface ColoredBoxProps extends BoxProps {
   component: NonNullable<BoxProps['component']>;
-  background: NonNullable<BoxProps['background']>;
 }
 
-export const resolveBackgroundAtom = (
-  background: ColoredBoxProps['background'],
-) =>
-  background === 'customDark' || background === 'customLight'
-    ? undefined
-    : atoms({ background });
+const adaptiveBackgrounds: Partial<Record<BoxBackgroundVariant, Background>> = {
+  body: 'bodyDark',
+  surface: 'surfaceDark',
+  brand: 'neutral',
+  promoteLight: 'neutral',
+  infoLight: 'neutral',
+  positiveLight: 'neutral',
+  cautionLight: 'neutral',
+  criticalLight: 'neutral',
+  neutralLight: 'neutral',
+  formAccentSoft: 'neutral',
+  formAccentSoftActive: 'neutralActive',
+  formAccentSoftHover: 'neutralHover',
+};
+
+const adaptiveBoxShadow: Partial<Record<BoxShadow, BoxShadow>> = {
+  borderBrandAccentLarge: 'borderBrandAccentLightLarge',
+  borderCaution: 'borderCautionLight',
+  borderCritical: 'borderCriticalLight',
+  borderCriticalLarge: 'borderCriticalLightLarge',
+  borderFormAccent: 'borderFormAccentLight',
+  borderFormAccentLarge: 'borderFormAccentLightLarge',
+  borderInfo: 'borderInfoLight',
+  borderNeutral: 'borderNeutralInverted',
+  borderNeutralLarge: 'borderNeutralInvertedLarge',
+  borderNeutralLight: 'borderNeutral',
+  borderPositive: 'borderPositiveLight',
+  borderPromote: 'borderPromoteLight',
+};
+
+const normaliseBackground = (background: ColoredBoxProps['background']) => ({
+  lightMode: typeof background === 'object' ? background.lightMode : background,
+  darkMode:
+    typeof background === 'object'
+      ? background.darkMode
+      : adaptiveBackgrounds[background!] || background,
+});
+
+const normalisedBoxShadow = (boxShadow: ColoredBoxProps['boxShadow']) => ({
+  lightMode: typeof boxShadow === 'object' ? boxShadow.lightMode : boxShadow,
+  darkMode: typeof boxShadow === 'object' ? boxShadow.darkMode : boxShadow,
+});
+
+export const useColoredBoxClasses = ({
+  background,
+  boxShadow,
+}: {
+  background?: ColoredBoxProps['background'];
+  boxShadow?: ColoredBoxProps['boxShadow'];
+}) => {
+  const parentLightness = useBackgroundLightness();
+  const currentBackgroundContext = useBackground();
+  const { backgroundLightness } = useBraidTheme();
+  const lightnessMap = {
+    ...backgroundLightness,
+    customDark: 'dark',
+    customLight: 'light',
+  } as const;
+
+  const classList: Array<string> = [];
+
+  if (boxShadow) {
+    const normalisedBoxShadows = normalisedBoxShadow(boxShadow);
+    const isSemantic = typeof boxShadow === 'string';
+
+    classList.push(
+      atoms({
+        boxShadow: {
+          lightMode:
+            isSemantic && parentLightness.lightMode === 'dark'
+              ? adaptiveBoxShadow[normalisedBoxShadows.lightMode!] ||
+                normalisedBoxShadows.lightMode
+              : normalisedBoxShadows.lightMode,
+          darkMode:
+            isSemantic && parentLightness.darkMode === 'dark'
+              ? adaptiveBoxShadow[normalisedBoxShadows.darkMode!] ||
+                normalisedBoxShadows.darkMode
+              : normalisedBoxShadows.darkMode,
+        },
+      }),
+    );
+  }
+
+  if (background) {
+    // ---------------------------------------------------------------------------
+    // Normalise simple background to populated conditional value
+    const { lightMode, darkMode } = normaliseBackground(background);
+
+    // ---------------------------------------------------------------------------
+    // Assign text tone vars based on the lightness context
+    classList.push(typographyStyles.lightModeTone[lightnessMap[lightMode!]]);
+    classList.push(typographyStyles.darkModeTone[lightnessMap[darkMode!]]);
+
+    // ---------------------------------------------------------------------------
+    // Override `neutral` text tone based on the lightness context
+
+    //  1. If `neutral` background, check background tone in opposite color mode
+    const lightModeTone = lightMode === 'neutral' ? darkMode : lightMode;
+    const darkModeTone = darkMode === 'neutral' ? lightMode : darkMode;
+
+    //  2. If neutral text override exists for background, apply it
+    if (
+      lightModeTone &&
+      typographyStyles.lightModeNeutralOverride[lightModeTone]
+    ) {
+      classList.push(typographyStyles.lightModeNeutralOverride[lightModeTone]);
+    }
+
+    if (
+      darkModeTone &&
+      typographyStyles.darkModeNeutralOverride[darkModeTone]
+    ) {
+      classList.push(typographyStyles.darkModeNeutralOverride[darkModeTone]);
+    }
+
+    // ---------------------------------------------------------------------------
+    // Set background atoms classes
+    classList.push(
+      atoms({
+        background: {
+          lightMode:
+            lightMode === 'customDark' || lightMode === 'customLight'
+              ? undefined
+              : lightMode,
+          darkMode:
+            darkMode === 'customDark' || darkMode === 'customLight'
+              ? undefined
+              : darkMode,
+        },
+      }),
+    );
+
+    // ---------------------------------------------------------------------------
+    // Return updated background context and class list
+    return {
+      backgroundContext: {
+        lightMode: lightMode || currentBackgroundContext.lightMode,
+        darkMode: darkMode || currentBackgroundContext.darkMode,
+      },
+      classList: classList.join(' '),
+    };
+  }
+
+  return {
+    classList: classList.join(' '),
+  };
+};
 
 export const ColoredBox = forwardRef<HTMLElement, ColoredBoxProps>(
-  ({ component, background, className, ...props }, ref) => {
-    const colorClasses = resolveBackgroundAtom(background);
+  ({ component, background, boxShadow, className, ...props }, ref) => {
+    const { backgroundContext, classList: colorClasses } = useColoredBoxClasses(
+      { background, boxShadow },
+    );
 
     const element = createElement(component, {
       className: `${className}${colorClasses ? ` ${colorClasses}` : ''}`,
@@ -25,7 +174,13 @@ export const ColoredBox = forwardRef<HTMLElement, ColoredBoxProps>(
       ref,
     });
 
-    return renderBackgroundProvider(background, element);
+    return backgroundContext ? (
+      <BackgroundProvider value={backgroundContext}>
+        {element}
+      </BackgroundProvider>
+    ) : (
+      element
+    );
   },
 );
 

package/lib/components/BraidPortal/BraidPortal.tsx

@@ -2,6 +2,7 @@ import React, { ReactNode } from 'react';
 import { createPortal } from 'react-dom';
 import { TextContext } from '../Text/TextContext';
 import { useBraidTheme } from '../BraidProvider/BraidThemeContext';
+import { VanillaThemeContainer } from '../BraidProvider/VanillaThemeContainer';
 
 export interface BraidPortalProps {
   children: ReactNode;
@@ -13,7 +14,9 @@ export const BraidPortal = ({ children, container }: BraidPortalProps) => {
 
   return createPortal(
     <TextContext.Provider value={false}>
-      <div className={vanillaTheme}>{children}</div>
+      <VanillaThemeContainer theme={vanillaTheme} setDefaultTextTones>
+        {children}
+      </VanillaThemeContainer>
     </TextContext.Provider>,
     container ?? document.body,
   );

package/lib/components/BraidProvider/BraidProvider.tsx

@@ -17,6 +17,8 @@ import { BraidTestProviderContext } from '../BraidTestProvider/BraidTestProvider
 import { BreakpointProvider } from './BreakpointContext';
 import { BraidThemeContext } from './BraidThemeContext';
 import { BraidTheme } from '../../themes/BraidTheme';
+import { darkMode } from '../../css/atoms/sprinkles.css';
+import { VanillaThemeContainer } from './VanillaThemeContainer';
 
 if (process.env.NODE_ENV === 'development') {
   ensureResetImported();
@@ -92,9 +94,15 @@ export const BraidProvider = ({
     <BraidThemeContext.Provider value={theme}>
       <TreatProvider theme={theme.treatTheme}>
         {styleBody ? (
-          <style type="text/css">{`body{margin:0;padding:0;background:${theme.background}}`}</style>
+          <style type="text/css">{`
+            html,body{margin:0;padding:0;background:${theme.background.lightMode}}
+            html.${darkMode},html.${darkMode} body{color-scheme:dark;background:${theme.background.darkMode}}
+          `}</style>
         ) : null}
-        <div className={theme.vanillaTheme}>
+        <VanillaThemeContainer
+          theme={theme.vanillaTheme}
+          setDefaultTextTones={!alreadyInBraidProvider}
+        >
           <LinkComponentContext.Provider
             value={linkComponent || linkComponentFromContext}
           >
@@ -104,7 +112,7 @@ export const BraidProvider = ({
               <BreakpointProvider>{children}</BreakpointProvider>
             )}
           </LinkComponentContext.Provider>
-        </div>
+        </VanillaThemeContainer>
       </TreatProvider>
     </BraidThemeContext.Provider>
   );

package/lib/components/BraidProvider/VanillaThemeContainer.tsx

@@ -0,0 +1,24 @@
+import React, { ReactNode } from 'react';
+
+import * as typographyStyles from '../../hooks/typography/typography.css';
+
+interface Props {
+  children: ReactNode;
+  theme: string;
+  setDefaultTextTones: boolean;
+}
+
+const textTones = [
+  typographyStyles.lightModeTone.light,
+  typographyStyles.darkModeTone.dark,
+].join(' ');
+
+export const VanillaThemeContainer = ({
+  children,
+  theme,
+  setDefaultTextTones,
+}: Props) => (
+  <div className={`${theme}${setDefaultTextTones ? ` ${textTones}` : ''}`}>
+    {children}
+  </div>
+);

package/lib/components/Button/Button.css.ts

@@ -1,6 +1,7 @@
 import { keyframes, style, styleVariants } from '@vanilla-extract/css';
 import { calc } from '@vanilla-extract/css-utils';
 import { rgba } from 'polished';
+import { colorModeStyle } from '../../css/colorModeStyle';
 import { responsiveStyle } from '../../css/responsiveStyle';
 import { vars } from '../../themes/vars.css';
 
@@ -12,9 +13,11 @@ export const root = style({
   textDecoration: 'none',
 });
 
+export const forceActive = style({});
+
 export const activeOverlay = style({
   selectors: {
-    [`${root}:active &`]: {
+    [`${root}:active &, ${forceActive}&`]: {
       opacity: 1,
     },
   },
@@ -121,8 +124,38 @@ export const loadingDot = style({
   },
 });
 
-export const invertedBackgrounds = styleVariants({
-  soft: { background: rgba('#fff', 0.075) },
-  hover: { background: rgba('#fff', 0.15) },
-  active: { background: rgba('#000', 0.05) },
+export const invertedBackgroundsLightMode = styleVariants({
+  soft: colorModeStyle({
+    lightMode: {
+      background: rgba('#fff', 0.1),
+    },
+  }),
+  hover: colorModeStyle({
+    lightMode: {
+      background: rgba('#fff', 0.15),
+    },
+  }),
+  active: colorModeStyle({
+    lightMode: {
+      background: rgba('#fff', 0.15),
+    },
+  }),
+});
+
+export const invertedBackgroundsDarkMode = styleVariants({
+  soft: colorModeStyle({
+    darkMode: {
+      background: rgba('#fff', 0.1),
+    },
+  }),
+  hover: colorModeStyle({
+    darkMode: {
+      background: rgba('#fff', 0.15),
+    },
+  }),
+  active: colorModeStyle({
+    darkMode: {
+      background: rgba('#fff', 0.15),
+    },
+  }),
 });

package/lib/components/Button/Button.screenshots.tsx

@@ -1,6 +1,9 @@
 import React, { Fragment } from 'react';
 import { ComponentScreenshot } from '../../../site/src/types';
-import { Box, Button } from '../';
+import { Button } from '../';
+// TODO: COLORMODE RELEASE
+// Use public import
+import { Box } from '../Box/Box';
 import { Inline } from '../Inline/Inline';
 import { Heading } from '../Heading/Heading';
 import { backgrounds } from '../../utils/docsHelpers';