docs(css): Fx116 - syntax updates for offset-path and ray()

files/en-us/web/css/basic-shape/circle/index.md

@@ -30,7 +30,7 @@ clip-path: circle(6rem at 12rem 8rem);
       - : Uses the length from the center of the shape to the farthest side of the reference box. For circles, this is the closest side in any dimension.
 
 - `<position>`
-  - : Moves the center of the circle. May be a {{cssxref("length")}}, or a {{cssxref("percentage")}}, or a values such as `left`.
+  - : Moves the center of the circle. May be a {{cssxref("length")}}, or a {{cssxref("percentage")}}, or a values such as `left`. The `<position>` value defaults to center if omitted.
 
 ## Examples
 

files/en-us/web/css/basic-shape/ellipse/index.md

@@ -32,7 +32,7 @@ An ellipse is essentially a squashed circle and so `ellipse()` acts in a very si
       - : Uses the length from the center of the shape to the farthest side of the reference box. For ellipses, this is the farthest side in the radius dimension.
 
 - `<position>`
-  - : Moves the center of the ellipse. May be a {{cssxref("length")}}, or a {{cssxref("percentage")}}, or a values such as `left`.
+  - : Moves the center of the ellipse. May be a {{cssxref("length")}}, or a {{cssxref("percentage")}}, or a values such as `left`. The `<position>` value defaults to center if omitted.
 
 ## Examples
 

files/en-us/web/css/box-edge/index.md

@@ -0,0 +1,86 @@
+---
+title: <box-edge>
+slug: Web/CSS/box-edge
+page-type: css-type
+spec-urls: https://drafts.csswg.org/css-box-4/#keywords
+---
+
+{{CSSRef}}
+
+The **`<box-edge>`** value types represent a [box edge](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model) keyword, such as [`content-box`](#content-box) and [`border-box`](#border-box). The box-edge keywords are used to define different aspects of an element's box model and how elements are positioned and rendered on screen.
+
+The box-edge keywords are the components of, but not limited to, the data types `<visual-box>`, `<layout-box>`, `<paint-box>`, `<coord-box>`, and `<geometry-box>`. These types are applied to properties such as {{cssxref("transform-box")}} and {{cssxref("background-clip")}}.
+
+## Syntax
+
+```css
+<visual-box> = content-box | padding-box | border-box /* also referred to as <box> */
+<layout-box> = <box> | margin-box /* also referred to as <shape-box> */
+<paint-box> = <box> | fill-box | stroke-box
+<coord-box> = <box> | fill-box | stroke-box | view-box
+<geometry-box> = <layout-box> | fill-box | stroke-box | view-box
+```
+
+### Values
+
+A `<box-edge>` can be of the type `<visual-box>`, `<layout-box>`, `<paint-box>`, `<coord-box>`, or `<geometry-box>`.
+
+- `<visual-box>`
+
+  - : Refers to the rectangular box generated for an element as seen by a user on a web page. It includes the element's content, padding, and border. It excludes the margin area. This value type is used for the {{cssxref("background-clip")}} and {{cssxref("overflow-clip-margin")}} properties.
+
+- `<layout-box>`
+
+  - : Refers to the space occupied by an element, including its content, padding, border, and margin. This value type is used for layout and positioning purposes. This value type is used for the {{cssxref("shape-outside")}} property.
+
+- `<paint-box>`
+
+  - : Refers to the area within the layout box that is used to render the content visually. This includes the area where the element's background and borders are painted. It excludes the margin area.
+
+- `<coord-box>`
+
+  - : Refers to the coordinate box used for positioning and sizing an element within its parent container. It is used to control how content flows around the edges of the box. It excludes the margin area. This value type is used for the {{cssxref("offset-path")}} property.
+
+- `<geometry-box>`
+  - : Defines the reference box for a [basic shape](/en-US/docs/Web/CSS/basic-shape), or if specified by itself, causes the edges of the specified box, including any corner shaping (such as a {{cssxref("border-radius")}}), to be the clipping path. This value type is used for the {{cssxref("clip-path")}}, {{cssxref("mask-clip")}}, and {{cssxref("mask-origin")}} properties and the SVG {{SVGAttr("clip-path")}} attribute.
+
+### Keywords
+
+The `<box-edge>` keywords are defined as follows:
+
+- `content-box`
+
+  - : Refers to the edge of the content area of the box. In SVG, this value is treated as `fill-box`. It is the innermost box and contains the actual content, such as text, images, or other HTML elements.
+
+- `padding-box`
+
+  - : Refers to the edge of the padding of the box. If there is no padding on a side, then the value is the same as `content-box`. In SVG, `padding-box` is treated as `fill-box`. The padding area surrounds the content area.
+
+- `border-box`
+
+  - : Refers to the edge of the border of the box. If there is no border on a side, then the value is the same as `padding-box`. In SVG, `border-box` is treated as `stroke-box`. The border area surrounds the padding area.
+
+- `margin-box`
+
+  - : Refers to the edge of the margin of the box. If there is no margin on a side, then the value is the same as `border-box`. In SVG, `margin-box` is treated as `stroke-box`.
+
+- `fill-box`
+
+  - : Refers to the object bounding box in SVG. In CSS, `fill-box` is treated as `content-box`. It is used to wrap the content around the edges defined by the `coord-box` values.
+
+- `stroke-box`
+
+  - : Refers to the stroke bounding box in SVG. In CSS, `stroke-box` is treated as `border-box`. It is used to define the shape of the element when strokes are applied.
+
+- `view-box`
+
+  - : Refers to the nearest SVG viewport element's origin box. The origin box is a rectangle with the width and height of the initial SVG user coordinate system established by the {{svgattr("viewBox")}} attribute for that element. The origin box is positioned such that its top left corner is anchored at the coordinate system origin. In CSS, `view-box` treated as `border-box`.
+    > **Note:** When the SVG viewport is not anchored at the origin, the origin box does not correspond to the SVG viewport.
+
+## Specifications
+
+{{Specifications}}
+
+## See also
+
+- [CSS box model](/en-US/docs/Web/CSS/CSS_box_model) module

files/en-us/web/css/offset-path/index.md

@@ -7,7 +7,9 @@ browser-compat: css.properties.offset-path
 
 {{CSSRef}}
 
-The **`offset-path`** [CSS](/en-US/docs/Web/CSS) property specifies a motion path for an element to follow and defines the element's positioning within the parent container or SVG coordinate system.
+The **`offset-path`** [CSS](/en-US/docs/Web/CSS) property specifies a path for an element to follow and the element's positioning within the path's parent container or SVG coordinate system. The path is a line, a curve, or geometrical shape along which the element gets positioned or moves.
+
+The `offset-path` property is used in combination with the {{cssxref("offset-distance")}}, {{cssxref("offset-rotate")}}, and {{cssxref("offset-anchor")}} properties to control the position and orientation of the element along a path.
 
 {{EmbedInteractiveExample("pages/css/offset-path.html")}}
 
@@ -19,18 +21,19 @@ offset-path: none;
 
 /* Line segment */
 offset-path: ray(45deg closest-side contain);
+offset-path: ray(contain 150deg at center center);
 offset-path: ray(45deg);
 
 /* URL */
-offset-path: url(#path);
+offset-path: url(#myCircle);
 
-/* Shape */
+/* Basic shape */
 offset-path: circle(50% at 25% 25%);
 offset-path: inset(50% 50% 50% 50%);
 offset-path: polygon(30% 0%, 70% 0%, 100% 50%, 30% 100%, 0% 70%, 0% 30%);
 offset-path: path("M 0,200 Q 200,200 260,80 Q 290,20 400,0 Q 300,100 400,200");
 
-/* Coord box */
+/* Coordinate box */
 offset-path: content-box;
 offset-path: padding-box;
 offset-path: border-box;
@@ -48,21 +51,35 @@ offset-path: unset;
 
 ### Values
 
-- {{cssxref("ray","ray()")}}
-  - : Defines a path that is a line segment from the starting position of an element and proceeding in the direction defined by the specified angle. This value accepts up to three parameters – an {{CSSxRef("angle")}} similar to the CSS [linear-gradient](/en-US/docs/Web/CSS/gradient/linear-gradient) angle, a size value similar to the CSS [radial-gradient](/en-US/docs/Web/CSS/gradient/radial-gradient) size values, and the keyword `contain`. The angle `0deg` starts on the y-axis, pointing up, with positive angles increasing in the clockwise direction. The possible values for the optional size parameter include `closest-side`, `closest-corner`, `farthest-side`, `farthest-corner`, and `sides`. If omitted, the value of the size parameter defaults to `closest-side`. The optional `contain` keyword reduces the length of the offset path so that the element stays within its containing block.
-
-> **Note:** While the size parameter is optional in the specification, some browsers implement `ray()` with a required size value. Including the default `closest-side` is the equivalent of omitting the size, but has better support.
+The `offset-path` takes as it's value an `<offset-path>` value, a `<coord-box>` value, or both or the `none` keyword. The `<offset-path>` value is a {{cssxref("ray","ray()")}}, a {{cssxref("url","url()")}}, or a [`<basic-shape>`](/en-US/docs/Web/CSS/basic-shape) value.
 
-- `url()`
-  - : References the ID of an SVG shape — `circle`, `ellipse`, `line`, `path`, `polygon`, `polyline`, or `rect` — using the shape's geometry as the path.
-- `<basic-shape>`
-  - : Specifies a [CSS shape](/en-US/docs/Web/CSS/CSS_shapes/Basic_shapes) by using one of the shape functions such as [`circle()`](/en-US/docs/Web/CSS/basic-shape/circle), [`ellipse()`](/en-US/docs/Web/CSS/basic-shape/ellipse), [`inset()`](/en-US/docs/Web/CSS/basic-shape/inset), [`polygon()`](/en-US/docs/Web/CSS/basic-shape/polygon), or {{cssxref("path","path()")}}.
 - `none`
-  - : Specifies no motion path at all.
+
+  - : Specifies that the element does not follow any offset path. The `none` value is equivalent to the element not having any [offset transform](/en-US/docs/Web/CSS/offset). The element's movement in this case is determined by its default position properties, such as {{cssxref("top")}} and {{cssxref("left")}}, instead of an offset path. This is the default value.
+
+- `<offset-path>`
+
+  - : A `ray()`, a `url()`, or a `<basic-shape>` specifying the geometrical offset path. If omitted, the path shape for the `<coord-box>` value is `inset(0 round X)`, where `X` is the value of {{cssxref("border-radius")}} of the element that establishes the [containing block](/en-US/docs/Web/CSS/Containing_block).
+
+    - {{cssxref("ray","ray()")}}
+
+      - : Defines a line starting at a set position, of a set length, and extending at the specified angle. The `ray()` function accepts up to four parameters – an {{CSSxRef("angle")}}, an optional size value, the optional keyword `contain`, and an optional `at <position>`.
+
+    - {{cssxref("url","url()")}}
+
+      - : Specifies the URL reference of a shape element with an SVG. The path is the shape of the SVG {{SVGElement("circle")}}, {{SVGElement("ellipse")}}, {{SVGElement("line")}}, {{SVGElement("path")}}, {{SVGElement("polygon")}}, or {{SVGElement("rect")}} element referenced by the`id` in the `url()` parameter. If the URL does not reference a shape element or is otherwise invalid, the resolved value for the offset path is `path("M0,0")` (which is a valid `<basic-shape>` value).
+
+    - [`<basic-shape>`](/en-US/docs/Web/CSS/basic-shape)
+
+      - : Specifies the offset path as the equivalent path of a [CSS basic shape function](/en-US/docs/Web/CSS/CSS_shapes/Basic_shapes), such as [`circle()`](/en-US/docs/Web/CSS/basic-shape/circle), [`ellipse()`](/en-US/docs/Web/CSS/basic-shape/ellipse), [`inset()`](/en-US/docs/Web/CSS/basic-shape/inset), {{cssxref("path","path()")}}, or [`polygon()`](/en-US/docs/Web/CSS/basic-shape/polygon). For example, if the `<basic_shape>` is an `ellipse()` function, then the path is the outline of the ellipse, starting at the rightmost point of the ellipse, proceeding clockwise through a full rotation. For `ellipse()` and `circle()`, which accept the `at <position>` parameter, if the `<position>` is omitted, the position defaults to `center` unless the element has an {{cssxref("offset-position")}} specified. In this case, the `offset-position` value is used for the `at <position>` parameter.
+
+- [`<coord-box>`](/en-US/docs/Web/CSS/box-edge#values)
+
+  - : Specifies the size information of the reference box containing the path. The reference box is derived from the element that establishes the containing block for this element. This parameter is optional. If not specified, the default value is `border-box`. In SVG, the value is treated as `view-box`. If `ray()` or `<basic-shape>` is used to define the offset path, the `<coord-box>` value provides the reference box for the ray or the `<basic-shape>`, respectively. If `url()` is used to define the offset path, the `<coord-box>` value provides the viewport and user coordinate system for the shape element, with the origin (`0 0`) at the top left corner and size being `1px`.
 
 ## Description
 
-This property defines a path an animated element can follow. An offset path is either a specified path with one or multiple sub-paths or the geometry of a not-styled basic shape. The element's exact position on the offset path is determined by the {{cssxref("offset-distance")}} property. Each shape or path must define an initial position for the computed value of `0` for {{cssxref("offset-distance")}} and an initial direction which specifies the rotation of the object to the initial position.
+The `offset-path` property defines a path an animated element can follow. An offset path is either a specified path with one or multiple sub-paths or the geometry of a not-styled basic shape. The element's exact position on the offset path is determined by the {{cssxref("offset-distance")}} property. Each shape or path must define an initial position for the computed value of `0` for {{cssxref("offset-distance")}} and an initial direction which specifies the rotation of the object to the initial position.
 
 Early versions of the spec called this property `motion-path`. It was changed to `offset-path` because the property describes static positions, not motion.
 
@@ -76,13 +93,78 @@ Early versions of the spec called this property `motion-path`. It was changed to
 
 ## Examples
 
+### Creating an offset-path using coord-box positioning
+
+This example shows the how `<coord-box>` parameter of `offset-path` works in with {{cssxref("border-radius")}}.
+
+```html hidden
+<div class="box blueBox"></div>
+<div class="box redBox"></div>
+<div class="box greenBox"></div>
+```
+
+```css
+body {
+  width: 300px;
+  height: 200px;
+  border-radius: 50px;
+  border: dashed aqua;
+  border-width: 25px;
+  padding: 25px;
+  margin: 50px;
+}
+
+.box {
+  width: 40px;
+  height: 20px;
+  animation: move 8000ms infinite ease-in-out;
+}
+
+.blueBox {
+  background-color: blue;
+  offset-path: border-box;
+  offset-distance: 5%;
+}
+
+.greenBox {
+  background-color: green;
+  offset-path: padding-box;
+  offset-distance: 8%;
+}
+
+.redBox {
+  background-color: red;
+  offset-path: content-box;
+  offset-distance: 12%;
+}
+
+@keyframes move {
+  0%,
+  20% {
+    offset-distance: 0%;
+  }
+  80%,
+  100% {
+    offset-distance: 100%;
+  }
+}
+```
+
+In this example, the margin, border, and padding have been purposely been given large values to demonstrate the placement of the blue, green, and red boxes on their respective `coord-box` edges: border-box, padding-box, and content-box.
+
+![Box model showing the placement of the blue, red, and green boxes on the border-box, padding-box, and context-box, respectively, by using the coord-box value in the offset-path property.](offset-path-coord-box.png)
+
+#### Result
+
+{{EmbedLiveSample('Creating an offset-path using coord-box positioning', '100%', 400)}}
+
 ### Animating an element with offset-path
 
-The `offset-path` properties in the CSS code sample defines a motion path that is identical to the `<path>` element in the SVG. The path, as can be seen in the rendering of the SVG code, is a line drawing of a house with a chimney.
+The `offset-path` properties in the CSS code sample defines a path that is identical to the `<path>` element in the SVG. The path, as can be seen in the rendering of the SVG code, is a line drawing of a house with a chimney.
 
 #### SVG
 
-The top and bottom halves of the scissors would appear in the top left of the canvas were they not positioned along the starting point of the motion path defined by `offset-path`.
+The top and bottom halves of the scissors would appear in the top left of the canvas were they not positioned along the starting point of the path defined by `offset-path`.
 
 ```html
 <svg
@@ -139,7 +221,6 @@ The top and bottom halves of the scissors would appear in the top left of the ca
 
 @keyframes followpath {
   to {
-    motion-offset: 100%;
     offset-distance: 100%;
   }
 }
@@ -164,10 +245,8 @@ The top and bottom halves of the scissors would appear in the top left of the ca
 - {{cssxref("offset-rotate")}}
 - [SVG \<path>](/en-US/docs/Web/SVG/Tutorial/Paths)
 - {{cssxref("path","path()")}}
-
-Other demos:
-
-- [Examples of the various values](https://codepen.io/team/css-tricks/pen/WZdKMq)
-- [Triangle](https://codepen.io/ericwilligers/pen/jMbJPp)
-- [Scissors](https://codepen.io/ericwilligers/pen/bwVZNa)
-- [Eyes](https://jsfiddle.net/ericwilligers/r1snqdan/)
+- Other demos:
+  - [Examples using various shapes values](https://codepen.io/team/css-tricks/pen/WZdKMq) on Codepen by CSS-Tricks
+  - [Moving a triangle along a curved path](https://codepen.io/ericwilligers/pen/jMbJPp) on Codepen by Eric Willigers
+  - [Moving a pair of scissors along the shape of a house](https://codepen.io/ericwilligers/pen/bwVZNa) on Codepen by Eric Willigers
+  - [Moving multiple pairs of eyes](https://jsfiddle.net/ericwilligers/r1snqdan/) on JSFiddle by Eric Willigers