chore(S2): audit style macro utilities (#9544)

* export all utilities

* export remaining utils

* removed unsafe exports for now

* add JSDoc descriptions

* rename colorScheme() to setColorScheme()

* remove raw/keyframes from s2 export

* export WidthProperties and HeightProperties as types

* cleanup JSDocs

* add docs

* lint

* address review comments

* extract docs from JSDoc

* add imports to all examples

* update styles->className in example

* fix size in md output

* add linearGradient

* remove getAllowedOverrides from exports/docs (could have breaking changes)

* remove WidthProperties/HeightProperties since we removed getAllowedOverrides export

* address review comments

* rename raw -> css

Author: reidbarber

packages/@react-spectrum/s2/src/CenterBaseline.tsx

@@ -10,9 +10,9 @@
  * governing permissions and limitations under the License.
  */
 
+import {css} from '../style/style-macro' with {type: 'macro'};
 import {CSSProperties, ReactNode} from 'react';
 import {mergeStyles} from '../style/runtime';
-import {raw} from '../style/style-macro' with {type: 'macro'};
 import {style} from '../style' with {type: 'macro'};
 import {StyleString} from '../style/types';
 
@@ -39,7 +39,7 @@ export function CenterBaseline(props: CenterBaselineProps): ReactNode {
   );
 }
 
-export const centerBaselineBefore = raw('&::before { content: "\u00a0"; width: 0; visibility: hidden }');
+export const centerBaselineBefore = css('&::before { content: "\u00a0"; width: 0; visibility: hidden }');
 
 export function centerBaseline(props: Omit<CenterBaselineProps, 'children'> = {}): (icon: ReactNode) => ReactNode {
   return (icon: ReactNode) => <CenterBaseline {...props}>{icon}</CenterBaseline>;

packages/@react-spectrum/s2/src/CoachMark.tsx

@@ -27,7 +27,6 @@ import {
 import {ButtonContext} from './Button';
 import {Card} from './Card';
 import {CheckboxContext} from './Checkbox';
-import {colorScheme, getAllowedOverrides, StyleProps} from './style-utils' with {type: 'macro'};
 import {ColorSchemeContext} from './Provider';
 import {ContentContext, FooterContext, KeyboardContext, TextContext} from './Content';
 import {
@@ -38,16 +37,17 @@ import {
   useContext,
   useRef
 } from 'react';
+import {css, keyframes} from '../style/style-macro' with {type: 'macro'};
 import {DividerContext} from './Divider';
 import {forwardRefType} from './types';
+import {getAllowedOverrides, StyleProps} from './style-utils' with {type: 'macro'};
 import {GlobalDOMAttributes} from '@react-types/shared';
 import {ImageContext} from './Image';
 import {ImageCoordinator} from './ImageCoordinator';
-import {keyframes, raw} from '../style/style-macro' with {type: 'macro'};
 import {mergeStyles} from '../style/runtime';
 import {PressResponder} from '@react-aria/interactions';
+import {setColorScheme, space, style} from '../style' with {type: 'macro'};
 import {SliderContext} from './Slider';
-import {space, style} from '../style' with {type: 'macro'};
 import {useId, useObjectRef, useOverlayTrigger} from 'react-aria';
 import {useLayoutEffect} from '@react-aria/utils';
 import {useMenuTriggerState} from 'react-stately';
@@ -106,7 +106,7 @@ const slideLeftKeyframes = keyframes(`
 `);
 
 let popover = style({
-  ...colorScheme(),
+  ...setColorScheme(),
   '--s2-container-bg': {
     type: 'backgroundColor',
     value: 'layer-2'
@@ -474,7 +474,7 @@ const indicator = style({
   }
 });
 
-const pulse = raw(`&:before { content: ""; display: inline-block; position: absolute; top: var(--borderOffset); bottom:  var(--borderOffset); left: var(--borderOffset); right: var(--borderOffset); border-radius: var(--ringRadius); outline-style: solid; outline-color: var(--activeElement); outline-width: 4px; animation-duration: 2s; animation-iteration-count: infinite; animation-timing-function: ease-in-out; animation-fill-mode: forwards; animation-name: ${pulseAnimation}}`);
+const pulse = css(`&:before { content: ""; display: inline-block; position: absolute; top: var(--borderOffset); bottom:  var(--borderOffset); left: var(--borderOffset); right: var(--borderOffset); border-radius: var(--ringRadius); outline-style: solid; outline-color: var(--activeElement); outline-width: 4px; animation-duration: 2s; animation-iteration-count: infinite; animation-timing-function: ease-in-out; animation-fill-mode: forwards; animation-name: ${pulseAnimation}}`);
 
 interface CoachMarkIndicatorProps {
   children: ReactNode,

packages/@react-spectrum/s2/src/ComboBox.tsx

@@ -36,9 +36,8 @@ import {
 import {AsyncLoadable, GlobalDOMAttributes, HelpTextProps, LoadingState, SingleSelection, SpectrumLabelableProps} from '@react-types/shared';
 import {AvatarContext} from './Avatar';
 import {BaseCollection, CollectionNode, createLeafComponent} from '@react-aria/collections';
-import {baseColor, focusRing, space, style} from '../style' with {type: 'macro'};
+import {baseColor, centerPadding, focusRing, space, style} from '../style' with {type: 'macro'};
 import {centerBaseline} from './CenterBaseline';
-import {centerPadding, control, controlBorderRadius, controlFont, controlSize, field, fieldInput, getAllowedOverrides, StyleProps} from './style-utils' with {type: 'macro'};
 import {
   checkmark,
   description,
@@ -49,6 +48,7 @@ import {
 } from './Menu';
 import CheckmarkIcon from '../ui-icons/Checkmark';
 import ChevronIcon from '../ui-icons/Chevron';
+import {control, controlBorderRadius, controlFont, controlSize, field, fieldInput, getAllowedOverrides, StyleProps} from './style-utils' with {type: 'macro'};
 import {createContext, CSSProperties, ForwardedRef, forwardRef, ReactNode, Ref, useCallback, useContext, useEffect, useImperativeHandle, useMemo, useRef, useState} from 'react';
 import {createFocusableRef} from '@react-spectrum/utils';
 import {edgeToText} from '../style/spectrum-theme' with {type: 'macro'};

packages/@react-spectrum/s2/src/Disclosure.tsx

@@ -12,12 +12,12 @@
 
 import {ActionButtonContext} from './ActionButton';
 import {AriaLabelingProps, DOMProps, DOMRef, DOMRefValue, forwardRefType, GlobalDOMAttributes} from '@react-types/shared';
-import {baseColor, focusRing, lightDark, space, style} from '../style' with { type: 'macro' };
+import {baseColor, centerPadding, focusRing, lightDark, space, style} from '../style' with { type: 'macro' };
 import {Button, ContextValue, DisclosureStateContext, Heading, Provider, Disclosure as RACDisclosure, DisclosurePanel as RACDisclosurePanel, DisclosurePanelProps as RACDisclosurePanelProps, DisclosureProps as RACDisclosureProps, useLocale, useSlottedContext} from 'react-aria-components';
 import {CenterBaseline} from './CenterBaseline';
-import {centerPadding, getAllowedOverrides, StyleProps, UnsafeStyles} from './style-utils' with { type: 'macro' };
 import Chevron from '../ui-icons/Chevron';
 import {filterDOMProps} from '@react-aria/utils';
+import {getAllowedOverrides, StyleProps, UnsafeStyles} from './style-utils' with {type: 'macro'};
 import React, {createContext, forwardRef, ReactNode, useContext} from 'react';
 import {useDOMRef} from '@react-spectrum/utils';
 import {useSpectrumContextProps} from './useSpectrumContextProps';

packages/@react-spectrum/s2/src/Menu.tsx

@@ -28,12 +28,12 @@ import {
   Separator,
   SeparatorProps
 } from 'react-aria-components';
-import {baseColor, focusRing, fontRelative, size, space, style} from '../style' with {type: 'macro'};
+import {baseColor, centerPadding, focusRing, fontRelative, size, space, style} from '../style' with {type: 'macro'};
 import {box, iconStyles} from './Checkbox';
 import {centerBaseline} from './CenterBaseline';
-import {centerPadding, control, controlFont, controlSize, getAllowedOverrides, StyleProps} from './style-utils' with {type: 'macro'};
 import CheckmarkIcon from '../ui-icons/Checkmark';
 import ChevronRightIcon from '../ui-icons/Chevron';
+import {control, controlFont, controlSize, getAllowedOverrides, StyleProps} from './style-utils' with {type: 'macro'};
 import {createContext, forwardRef, JSX, ReactElement, ReactNode, useContext, useRef, useState} from 'react';
 import {divider} from './Divider';
 import {DOMRef, DOMRefValue, GlobalDOMAttributes, PressEvent} from '@react-types/shared';

packages/@react-spectrum/s2/src/Modal.tsx

@@ -10,12 +10,11 @@
  * governing permissions and limitations under the License.
  */
 
-import {colorScheme} from './style-utils' with {type: 'macro'};
 import {ColorSchemeContext} from './Provider';
 import {DOMRef, GlobalDOMAttributes} from '@react-types/shared';
 import {forwardRef, MutableRefObject, useCallback, useContext} from 'react';
 import {ModalOverlay, ModalOverlayProps, Modal as RACModal, useLocale} from 'react-aria-components';
-import {style} from '../style' with {type: 'macro'};
+import {setColorScheme, style} from '../style' with {type: 'macro'};
 import {useDOMRef} from '@react-spectrum/utils';
 
 interface ModalProps extends Omit<ModalOverlayProps, 'className' | 'style' | 'render' | keyof GlobalDOMAttributes> {
@@ -28,7 +27,7 @@ interface ModalProps extends Omit<ModalOverlayProps, 'className' | 'style' | 're
 }
 
 const modalOverlayStyles = style({
-  ...colorScheme(),
+  ...setColorScheme(),
   position: 'absolute',
   top: 0,
   left: 0,

packages/@react-spectrum/s2/src/Picker.tsx

@@ -52,6 +52,7 @@ import ChevronIcon from '../ui-icons/Chevron';
 import {control, controlBorderRadius, controlFont, field, fieldInput, getAllowedOverrides, StyleProps} from './style-utils' with {type: 'macro'};
 import {createHideableComponent} from '@react-aria/collections';
 import {createShadowTreeWalker, getOwnerDocument, isFocusable, useGlobalListeners, useSlotId} from '@react-aria/utils';
+import {css} from '../style/style-macro' with {type: 'macro'};
 import {
   Divider,
   listbox,
@@ -77,7 +78,6 @@ import {Popover} from './Popover';
 import {PressResponder} from '@react-aria/interactions';
 import {pressScale} from './pressScale';
 import {ProgressCircle} from './ProgressCircle';
-import {raw} from '../style/style-macro' with {type: 'macro'};
 import React, {createContext, forwardRef, ReactNode, useContext, useEffect, useMemo, useRef, useState} from 'react';
 import {useFocusableRef} from '@react-spectrum/utils';
 import {useLocale, useLocalizedStringFormatter} from '@react-aria/i18n';
@@ -584,7 +584,7 @@ const PickerButton = createHideableComponent(function PickerButton<T extends obj
             <SelectValue
               className={
                 valueStyles({isQuiet}) +
-                (renderValue ? '' : ' ' + raw('&> :not([slot=icon], [slot=avatar], [slot=label], [data-slot=label]) {display: none;}'))
+                (renderValue ? '' : ' ' + css('&> :not([slot=icon], [slot=avatar], [slot=label], [data-slot=label]) {display: none;}'))
               }>
               {({selectedItems, defaultChildren}) => {
                 const selectedValues = selectedItems.filter((item): item is T => item != null);

packages/@react-spectrum/s2/src/Popover.tsx

@@ -20,11 +20,11 @@ import {
   OverlayTriggerStateContext,
   useLocale
 } from 'react-aria-components';
-import {colorScheme, getAllowedOverrides, heightProperties, UnsafeStyles, widthProperties} from './style-utils' with {type: 'macro'};
 import {ColorSchemeContext} from './Provider';
 import {createContext, ForwardedRef, forwardRef, ReactNode, useCallback, useContext, useMemo} from 'react';
 import {DOMRef, DOMRefValue, GlobalDOMAttributes} from '@react-types/shared';
-import {lightDark, style} from '../style' with {type: 'macro'};
+import {getAllowedOverrides, heightProperties, UnsafeStyles, widthProperties} from './style-utils' with {type: 'macro'};
+import {lightDark, setColorScheme, style} from '../style' with {type: 'macro'};
 import {mergeRefs} from '@react-aria/utils';
 import {mergeStyles} from '../style/runtime';
 import {StyleString} from '../style/types' with {type: 'macro'};
@@ -62,7 +62,7 @@ export interface PopoverProps extends UnsafeStyles, Omit<AriaPopoverProps,
 }
 
 let popover = style({
-  ...colorScheme(),
+  ...setColorScheme(),
   '--s2-container-bg': {
     type: 'backgroundColor',
     value: {

packages/@react-spectrum/s2/src/Provider.tsx

@@ -11,16 +11,16 @@
  */
 
 import type {ColorScheme, Router} from '@react-types/provider';
-import {colorScheme, UnsafeStyles} from './style-utils' with {type: 'macro'};
 import {createContext, JSX, ReactNode, useContext} from 'react';
 import {DOMProps} from '@react-types/shared';
 import {filterDOMProps} from '@react-aria/utils';
 import {Fonts} from './Fonts';
 import {generateDefaultColorSchemeStyles} from './page.macro' with {type: 'macro'};
 import {I18nProvider, RouterProvider, useLocale} from 'react-aria-components';
 import {mergeStyles} from '../style/runtime';
-import {style} from '../style' with {type: 'macro'};
+import {setColorScheme, style} from '../style' with {type: 'macro'};
 import {StyleString} from '../style/types';
+import {UnsafeStyles} from './style-utils' with {type: 'macro'};
 
 export interface ProviderProps extends UnsafeStyles, DOMProps {
   /** The content of the Provider. */
@@ -77,7 +77,7 @@ export function Provider(props: ProviderProps): JSX.Element {
 generateDefaultColorSchemeStyles();
 
 let providerStyles = style({
-  ...colorScheme(),
+  ...setColorScheme(),
   '--s2-container-bg': {
     type: 'backgroundColor',
     value: {

packages/@react-spectrum/s2/src/SearchField.tsx

@@ -22,12 +22,12 @@ import {centerBaseline} from './CenterBaseline';
 import {ClearButton} from './ClearButton';
 import {createContext, forwardRef, Ref, useContext, useImperativeHandle, useRef} from 'react';
 import {createFocusableRef} from '@react-spectrum/utils';
+import {css} from '../style/style-macro' with {type: 'macro'};
 import {field, getAllowedOverrides, StyleProps} from './style-utils' with {type: 'macro'};
 import {FieldGroup, FieldLabel, HelpText, Input} from './Field';
 import {FormContext, useFormProps} from './Form';
 import {GlobalDOMAttributes, HelpTextProps, SpectrumLabelableProps} from '@react-types/shared';
 import {IconContext} from './Icon';
-import {raw} from '../style/style-macro' with {type: 'macro'};
 import SearchIcon from '../s2wf-icons/S2_Icon_Search_20_N.svg';
 import {TextFieldRef} from '@react-types/textfield';
 import {useSpectrumContextProps} from './useSpectrumContextProps';
@@ -142,7 +142,7 @@ export const SearchField = /*#__PURE__*/ forwardRef(function SearchField(props:
             ]}>
             <SearchIcon />
           </Provider>
-          <Input ref={inputRef} UNSAFE_className={raw('&::-webkit-search-cancel-button { display: none }')} />
+          <Input ref={inputRef} UNSAFE_className={css('&::-webkit-search-cancel-button { display: none }')} />
           {!isEmpty && !searchFieldProps.isReadOnly && <ClearButton size={props.size} />}
         </FieldGroup>
         <HelpText