[WIP] chore(S2): audit style macro utilities

[reidbarber]

This PR audits the style macro utilities we use throughout @react-spectrum/s2 to help decide which ones we should export. This will make it easier for users to build custom S2 components that are similar to existing S2 components.

We should:

• Decide which ones to export
• Finalize naming/APIs for those
• Add docs + JSDocs

We probably want to export most of these, so it might be better to focus on which ones we don't want to export and why.

Utilities

Utility	Usage Count	Description
getAllowedOverrides()	57	Returns the list of allowed style override properties for the styles prop.
focusRing()	29	Provides consistent focus ring outline styles.
mergeStyles()	16	Merges multiple style strings together, combining properties from each style. Used for composing styles dynamically.
field()	14	Grid layout styles for form fields. Handles label positioning (top/side) and subgrid integration.
controlFont()	14	Returns font size values for controls based on the size prop (XS, S, M, L, XL).
fieldInput()	10	Styles for field input containers, including default width and size containment.
control()	9	Composite utility for pill or rounded rectangle shaped containers with text and icon slots. Supports wrapping text and icon-only modes.
controlSize()	9	Returns height/width values for controls based on size prop. Has 'sm' and 'md' variants.
raw()	8	Injects raw CSS strings into the style system with optional layer specification.
staticColor()	6	Sets container background color variable for static color variants (black/white).
colorScheme()	6	Configures the CSS color-scheme property for light/dark mode.
centerPadding()	6	Calculates vertical padding to center single-line content within a minimum height container.
controlBorderRadius()	5	Generates border radius for t-shirt sizes using the Major Second logarithmic scale (power of 1.125).
edgeToText()	4	Calculates spacing from edge to text content based on Spectrum spacing tokens.
keyframes()	4	Defines CSS keyframe animations.
fieldLabel()	3	Styles for field labels including font, cursor, and color states.
iconStyle()	1	Icon styling utility with size and color options.
linearGradient()	1	Creates animated linear gradients with color stops.

Constants

Constant	Description
widthProperties	Array of allowed width-related properties. Only used by Popover.
heightProperties	Array of allowed height-related properties. Only used by Popover.

Types

Type	Description
StylesProp	Style prop type with width properties
StylesPropWithHeight	Style prop type with width and height properties
StylesPropWithoutWidth	Style prop type without width properties
UnsafeClassName	Type for unsafe className prop
UnsafeStyles	Interface for unsafe style props
StyleProps	Interface for style props

✅ Pull Request Checklist:

• Included link to corresponding React Spectrum GitHub Issue.
• Added/updated unit tests and storybook for this change (for new code or code which already has tests).
• Filled out test instructions.
• Updated documentation (if it already exists for this component).
• Looked at the Accessibility Practices for this feature - Aria Practices

📝 Test Instructions:

🧢 Your Project:

[rspbot]

Build successful! 🎉

• View the storybook
• View the S2 storybook
• View the S2 docs
• View the React Aria docs

[rspbot]

Build successful! 🎉

• View the storybook
• View the S2 storybook
• View the S2 docs
• View the React Aria docs

[rspbot]

## API Changes

@react-spectrum/s2

/@react-spectrum/s2:getAllowedOverrides

+getAllowedOverrides {
+  undefined: any
+  returnVal: undefined
+}

/@react-spectrum/s2:field

+field {
+  returnVal: undefined
+}

/@react-spectrum/s2:fieldLabel

+fieldLabel {
+  returnVal: undefined
+}

/@react-spectrum/s2:fieldInput

+fieldInput {
+  returnVal: undefined
+}

/@react-spectrum/s2:control

+control {
+  options: ControlOptions
+  returnVal: undefined
+}

/@react-spectrum/s2:controlFont

+controlFont {
+  returnVal: undefined
+}

/@react-spectrum/s2:controlSize

+controlSize {
+  size: 'sm' | 'md'
+  returnVal: undefined
+}

/@react-spectrum/s2:controlBorderRadius

+controlBorderRadius {
+  size: 'default' | 'sm'
+  returnVal: undefined
+}

/@react-spectrum/s2:centerPadding

+centerPadding {
+  minHeight: string
+  returnVal: undefined
+}

/@react-spectrum/s2:colorScheme

+colorScheme {
+  returnVal: undefined
+}

/@react-spectrum/s2:staticColor

+staticColor {
+  returnVal: undefined
+}

/@react-spectrum/s2:widthProperties

+widthProperties {
+  UNTYPED
+}

/@react-spectrum/s2:heightProperties

+heightProperties {
+  UNTYPED
+}

/@react-spectrum/s2:focusRing

+focusRing {
+  returnVal: undefined
+}

/@react-spectrum/s2:iconStyle

+iconStyle {
+  this: MacroContext | void
+  options: IconStyle
+  returnVal: undefined
+}

/@react-spectrum/s2:linearGradient

+linearGradient {
+  this: MacroContext | void
+  angle: string
+  tokens: Array<[SpectrumColor, number]>
+  returnVal: undefined
+}

/@react-spectrum/s2:edgeToText

+edgeToText {
+  this: MacroContext | void
+  height: keyof any
+  returnVal: undefined
+}

/@react-spectrum/s2:raw

+raw {
+  this: MacroContext | void
+  css: string
+  layer: any
+  returnVal: undefined
+}

/@react-spectrum/s2:keyframes

+keyframes {
+  this: MacroContext | void
+  css: string
+  returnVal: undefined
+}

/@react-spectrum/s2:mergeStyles

+mergeStyles {
+  styles: Array<StyleString | null | undefined>
+  returnVal: undefined
+}

/@react-spectrum/s2:StylesProp

+StylesProp {
+  S: undefined
+}

/@react-spectrum/s2:StylesPropWithHeight

+StylesPropWithHeight {
+  S: undefined
+}

/@react-spectrum/s2:StylesPropWithoutWidth

+StylesPropWithoutWidth {
+  S: undefined
+}

/@react-spectrum/s2:UnsafeClassName

+UnsafeClassName {
+  U: undefined
+}

/@react-spectrum/s2:UnsafeStyles

+UnsafeStyles {
+  UNSAFE_className?: UnsafeClassName
+  UNSAFE_style?: CSSProperties
+}

/@react-spectrum/s2:StyleProps

+StyleProps {
+  UNSAFE_className?: UnsafeClassName
+  UNSAFE_style?: CSSProperties
+  styles?: StylesProp
+}

---