docs: add docs for pressScale

packages/@react-spectrum/s2/src/pressScale.ts

@@ -13,6 +13,28 @@
 import {composeRenderProps} from 'react-aria-components/composeRenderProps';
 import {CSSProperties, RefObject} from 'react';
 
+/**
+ * Returns a render prop style function that applies a subtle Spectrum "press" scale
+ * effect to an element while it is being pressed.
+ *
+ * @param ref - A ref to the element receiving the press effect.
+ * @param style - An optional base style object, or a render prop function returning
+ * one.
+ * @returns A render prop function suitable for passing to a React Aria component's
+ * `style` prop.
+ *
+ * @example
+ * ```tsx
+ * import {Button} from 'react-aria-components/Button';
+ * import {pressScale} from '@react-spectrum/s2';
+ * import {useRef} from 'react';
+ *
+ * function MyButton(props) {
+ *   let ref = useRef(null);
+ *   return <Button {...props} ref={ref} style={pressScale(ref, props.style)} />;
+ * }
+ * ```
+ */
 export function pressScale<R extends {isPressed: boolean}>(ref: RefObject<HTMLElement | null>, style?: CSSProperties | ((renderProps: R) => CSSProperties)): (renderProps: R) => CSSProperties {
   return composeRenderProps(style, (style, renderProps: R) => {
     if (renderProps.isPressed && ref.current) {

packages/dev/s2-docs/pages/s2/style-macro.mdx

@@ -108,6 +108,10 @@ See the [Icons](icons#api) page for more information.
 
 <FunctionJSDoc function={docs.exports.mergeStyles} />
 
+### pressScale
+
+<FunctionJSDoc function={docs.exports.pressScale} />
+
 ### centerPadding
 
 <FunctionJSDoc function={styleDocs.exports.centerPadding} />