Accept Marker type in StyleXStyles for passing between component prop boundaries

[titchimoto]

What changed / motivation ?

In our Design System, we follow StyleX's docs recommend pattern for constraining component style props using StyleXStyles<T>:

// Design system component
type BoxProps = {
  /** Only layout properties allowed, other styles are intentionally blocked */
  xstyle?: StyleXStyles<{
    margin?: CSSProperties['margin'];
    padding?: CSSProperties['padding'];
    flexGrow?: CSSProperties['flexGrow'];
  }>;
};

This pattern works for style overrides but consumers also need to use the marker API to implement ancestor-state patterns, for example, revealing a child element when a parent is hovered, entirely in CSS:

const styles = stylex.create({
  actions: {
    opacity: {
      default: 0,
      [stylex.when.ancestor(':hover')]: 1,
    },
  },
});

// Mark the parent component as the hover anchor...
<Box xstyle={stylex.defaultMarker()}>  {/* ❌ Type error */}
  <ChildComponent xstyle={styles.actions} />
</Box>

// ...or compose layout styles and a marker together
<Box xstyle={[styles.layout, stylex.defaultMarker()]}>  {/* ❌ Type error */}
  <ChildComponent xstyle={styles.actions} />
</Box>

Because StyleXStyles<T> has no way to express "a marker token is also valid here", in our DS, we've created an internal XStyle type which is essentially a union of StylexStyles<T> | StyleXMarkerToken (which we've just created internally from the ReturnType's as in this PR), which does work & without that our DS consumers are forced to either add additional wrapping elements, or are generally unable to use our components for their use-case.

But it would be nice to not have to manage this at the DS level & could live in the library instead to pass between component prop boundaries easier.

Pre-flight checklist

• I have read the contributing guidelines
  Contribution Guidelines
• Performed a self-review of my code

[meta-cla]

Hi @titchimoto!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at cla@meta.com. Thanks!

[vercel]

@titchimoto is attempting to deploy a commit to the Meta Open Source Team on Vercel.

A member of the Team first needs to authorize it.

[nmn]

Default markers and custom markers should really be combined into a single type.

[nmn]

Suggested change

	export type StyleXMarker = MapNamespace<{
	readonly marker: symbol;
	}>;
	export type StyleX$DefineMarker = () => StyleXMarker;
	export type StyleX$DefaultMarker = () => StyleXMarker;

[nmn]

Suggested change

	| StyleXMarkerToken,
	| StyleXMarker,

[Copilot]

Pull request overview

This PR updates StyleX’s public typing so marker tokens (stylex.defaultMarker() / stylex.defineMarker()) are accepted anywhere StyleXStyles<T> is used, enabling marker-based ancestor/descendant styling patterns to pass cleanly through constrained component style props (e.g., design-system xstyle?: StyleXStyles<...>).

Changes:

• Extend StyleXStyles<T> to accept a new StyleXMarkerToken union type.
• Define and export StyleXMarkerToken (and StyleX$DefaultMarker) in both Flow and TypeScript type surfaces.
• Add TypeScript type-tests validating marker tokens work with constrained StyleXStyles<T> without weakening CSS constraints.

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated no comments.

File	Description
packages/typescript-tests/src/typetests.ts	Adds TS type-tests proving marker tokens satisfy StyleXMarkerToken and are accepted by constrained StyleXStyles<T> while preserving constraints.
packages/@stylexjs/stylex/src/types/StyleXTypes.js	Updates Flow StyleXStyles to include StyleXMarkerToken and introduces StyleX$DefaultMarker + StyleXMarkerToken type exports.
packages/@stylexjs/stylex/src/types/StyleXTypes.d.ts	Updates TS StyleXStyles to include StyleXMarkerToken and introduces StyleX$DefaultMarker + StyleXMarkerToken type exports.
packages/@stylexjs/stylex/src/stylex.js	Re-exports StyleXMarkerToken and types defaultMarker on the legacy interface via StyleX$DefaultMarker.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[titchimoto]

Default markers and custom markers should really be combined into a single type.

@nmn sounds good! updated here to collapse both these marker types down into a single type. I did keep the Flow custom-marker type in both cases now if that works? but I think that should keep these both closer in sync now.

[meta-cla]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!