docs(fx112-css-ray): Create new page for ray() function

[dipikabh]

The syntax for the ray() function (value in offset-path) has been updated in Fx112.

• <ray-size> is now optional.
• The default value of <ray-size> is closest-side.

Changes in this PR

• Updates the ray() function description in the existing offset-path page, adds links to some shape pages

• Adds a new page for the ray() function. The webref is not updated with the new syntax so I have not included a "Formal syntax" section. I've added the syntax to the "Syntax" section for now.

Spec: https://drafts.fxtf.org/motion/#ray-function
Firefox bug: https://bugzilla.mozilla.org/show_bug.cgi?id=1820071

Support in browsers

• Firefox: ray() is available behind the flag layout.css.motion-path-ray.enabled .
• Chrome: some offset-path: ray() functionality is available with "Experimental Web Platform features" enabled but the syntax implementation is not in sync with the latest spec. The BCD table on offset-path page contains a row on ray() that indicates complete support, which is contrary to what I saw in testing.

Codepens

Codepens for the examples used in the doc can be found here (tested in Firefox behind the flag):
Example 1: https://codepen.io/dipikabh/pen/yLReQaZ
Example 2: https://codepen.io/dipikabh/pen/PoyNQdz

Caveat

The functionality is still undergoing discussions:

• The contain keyword behavior is due to be fixed in Firefox (https://bugzilla.mozilla.org/show_bug.cgi?id=1821450) as a result of [motion-1] the description of contain flag in ray() function w3c/fxtf-drafts#363.
• More change in behavior is expected to come via [motion-1] offset-position + circle() w3c/fxtf-drafts#504.

To Do

• Open BCD PR - (fx112) Add file for ray function and update ray() in offset-path browser-compat-data#19421
• Update mdn/data - docs(fx112-css): Add syntax for ray() function data#661
• Update Fx112 release note - docs(fx112-relnote): Add support for updated ray() function syntax #26275

Related issues

Doc issue tracker: #25358

[github-actions]

Preview URLs

• /en-US/docs/Web/CSS/offset-path
• /en-US/docs/Web/CSS/ray

Flaws (1)

Note! 1 document with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/CSS/ray
Title: ray()
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: css.types.ray

External URLs (1)

URL: /en-US/docs/Web/CSS/ray
Title: ray()

• https://drafts.fxtf.org/motion/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2023-04-20 03:57:06)

[estelle]

a few comments. looking good. still working on the review.

[estelle]

Suggested change

	The **`ray()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Functions) defines a line segment that begins from an [offset starting position](https://drafts.fxtf.org/motion/#offset-starting-position) and extends in the direction of the specified angle. The line segment is referred to as "ray". The length of a ray can be constrained by specifying a size.
	The **`ray()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Functions) defines a line segment that begins from a starting position set by {{CSSXref("offset-position")}} and extending in the direction of the specified angle. The line segment is referred to as "ray". The length of a ray can be constrained by specifying a size and the keyword `contain`.

[dipikabh]

I intentionally left out linking to offset-position page on MDN because the property is currently not supported on any browser (and therefore not used in any example) but the concept is supported in calculations. I took cue from the offset-position description that contains a link to spec's "initial position" definition to add a similar link here to a definition in the spec for the "offset starting position".

[estelle]

made some suggestions. Also forked your codepens. The first example doesn't work for me without size.

[dipikabh]

Thanks for the review @estelle and for your help with fixing the code.

1. I have fixed your comments except I wasn't able to move part of CSS in second example to "css hidden" (Firefox 112 with the flag layout.css.motion-path-ray.enabled):

• In the first example, I put part of the CSS in "css hidden" like you suggested and the example works fine.
• In the second example, when I put part of CSS code in "css hidden", the animation stopped working (while I could see the animation working in your codepen in the same browser, different tab). The animation started working after I removed "css hidden".

2. I added closest-side to all cases in the first example because I could validate the "Note" text you've added. Just to make a record of the observations here:

• specifying only the angle value is working in Firefox 112 behind the flag
• specifying only the angle value is working in Chrome Canary with #enable-experimental-web-platform-features
• not working in Chrome 112 with or without #enable-experimental-web-platform-features (in exp mode, first example works with explicit mention of closest-side, second example still not working)
• second example is working in Safari TP, indicating that sides might be better supported than closest-side? offset-anchor does not work

[estelle]

Thanks! 🎉