[docs] Add docs for positionTry API

Author: necolas

packages/@stylexjs/babel-plugin/src/visitors/stylex-create-theme.js

@@ -79,7 +79,7 @@ export default function transformStyleXCreateTheme(
       );
     }
 
-    const otherInjectedCSSRules: { [animationName: string]: InjectableStyle } =
+    const otherInjectedCSSRules: { [propertyName: string]: InjectableStyle } =
       {};
 
     // eslint-disable-next-line no-inner-declarations
@@ -98,10 +98,10 @@ export default function transformStyleXCreateTheme(
 
     // eslint-disable-next-line no-inner-declarations
     function positionTry<Obj: { +[k: string]: string | number }>(
-      animation: Obj,
+      fallbackStyles: Obj,
     ): string {
       const [positionTryName, injectedStyle] = stylexPositionTry(
-        animation,
+        fallbackStyles,
         state.options,
       );
       otherInjectedCSSRules[positionTryName] = injectedStyle;

packages/@stylexjs/babel-plugin/src/visitors/stylex-create.js

@@ -73,7 +73,7 @@ export default function transformStyleXCreate(
 
     state.inStyleXCreate = true;
 
-    const otherInjectedCSSRules: { [animationName: string]: InjectableStyle } =
+    const otherInjectedCSSRules: { [propertyName: string]: InjectableStyle } =
       {};
 
     // eslint-disable-next-line no-inner-declarations

packages/docs/docs/api/index.mdx

@@ -22,6 +22,7 @@ sidebar_position: 1
 - [`stylex.defineVars()`](./javascript/defineVars.mdx)
 - [`stylex.firstThatWorks()`](./javascript/firstThatWorks.mdx)
 - [`stylex.keyframes()`](./javascript/keyframes.mdx)
+- [`stylex.positionTry()`](./javascript/positionTry.mdx)
 - [`stylex.props()`](./javascript/props.mdx)
 - [`stylex.types.*()`](./javascript/types.mdx)
 

packages/docs/docs/api/javascript/keyframes.mdx

@@ -38,8 +38,7 @@ const styles = stylex.create({
 });
 ```
 
-To declare keyframes in a separate file, you can use `defineVars` to hold
-animation names:
+To use `keyframes` return values in a separate file, you can use `defineVars` to hold animation names:
 
 ```tsx title="animations.stylex.js"
 import * as stylex from '@stylexjs/stylex';
@@ -68,4 +67,4 @@ export const animations = stylex.defineVars({
 ```
 
 These variables can then be imported and used like any other variables created
-with defineVars.
+with `defineVars`.

packages/docs/docs/api/javascript/positionTry.mdx

@@ -0,0 +1,60 @@
+---
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+sidebar_position: 6
+---
+
+# `stylex.positionTry`
+
+Creates a [`@position-try`](https://developer.mozilla.org/en-US/docs/Web/CSS/@position-try) rule used to define a custom position-try fallback option, which can be used to define positioning and alignment for anchor-positioned elements. One or more sets of position-try fallback options can be applied to the anchored element via the `positionTryFallbacks` property.
+
+```ts
+function positionTry(descriptors: {[key: string]: RawStyles}): string;
+```
+
+The only properties allowed in a `positionTry` call are `positionAnchor`, `positionArea`, inset properties (`top`, `left`, `insetInline`, etc.), margin properties, size properties (`height`, `inlineSize`, etc.), and self-alignment properties (`alignSelf`, `justifySelf`, `placeSelf`).
+
+You must declare your position-try rules in the same file as where you use them. Duplicate declarations will be deduplicated in the generated CSS output.
+
+### Example use:
+
+```tsx
+import * as stylex from '@stylexjs/stylex';
+
+const fallback = stylex.positionTry({
+  positionAnchor: '--anchor',
+  top: '0',
+  left: '0',
+  width: '100px',
+  height: '100px'
+});
+
+const styles = stylex.create({
+  anchor: {
+    positionTryFallbacks: fallback,
+  },
+});
+```
+
+To use `positionTry` return values in a separate file, you can use `defineVars` to hold position fallback values:
+
+```tsx title="positionFallbacks.stylex.js"
+import * as stylex from '@stylexjs/stylex';
+
+const topLeftCorner = stylex.positionTry({
+  positionAnchor: '--anchor',
+  top: '0',
+  left: '0',
+  width: '100px',
+  height: '100px'
+});
+
+export const positionFallbacks = stylex.defineVars({
+  topLeftCorner
+});
+```
+
+These variables can then be imported and used like any other variables created
+with `defineVars`.