docs(css): FF126 - Support for shape() function

files/en-us/_redirects.txt

@@ -11616,7 +11616,7 @@
 /en-US/docs/Web/CSS/filter-function/hue-rotate()	/en-US/docs/Web/CSS/filter-function/hue-rotate
 /en-US/docs/Web/CSS/filter-function/invert()	/en-US/docs/Web/CSS/filter-function/invert
 /en-US/docs/Web/CSS/filter-function/opacity()	/en-US/docs/Web/CSS/filter-function/opacity
-/en-US/docs/Web/CSS/filter-function/path()	/en-US/docs/Web/CSS/path
+/en-US/docs/Web/CSS/filter-function/path()	/en-US/docs/Web/CSS/basic-shape/path
 /en-US/docs/Web/CSS/filter-function/saturate()	/en-US/docs/Web/CSS/filter-function/saturate
 /en-US/docs/Web/CSS/filter-function/sepia()	/en-US/docs/Web/CSS/filter-function/sepia
 /en-US/docs/Web/CSS/filter-function/url	/en-US/docs/Web/CSS/url
@@ -11682,7 +11682,8 @@
 /en-US/docs/Web/CSS/pad	/en-US/docs/Web/CSS/@counter-style/pad
 /en-US/docs/Web/CSS/paint	/en-US/docs/Web/CSS/image/paint
 /en-US/docs/Web/CSS/paint()	/en-US/docs/Web/CSS/image/paint
-/en-US/docs/Web/CSS/path()	/en-US/docs/Web/CSS/path
+/en-US/docs/Web/CSS/path	/en-US/docs/Web/CSS/basic-shape/path
+/en-US/docs/Web/CSS/path()	/en-US/docs/Web/CSS/basic-shape/path
 /en-US/docs/Web/CSS/prefix	/en-US/docs/Web/CSS/@counter-style/prefix
 /en-US/docs/Web/CSS/radial-gradient	/en-US/docs/Web/CSS/gradient/radial-gradient
 /en-US/docs/Web/CSS/radial-gradient()	/en-US/docs/Web/CSS/gradient/radial-gradient

files/en-us/_wikihistory.json

@@ -80630,6 +80630,10 @@
       "rebeccahauck"
     ]
   },
+  "Web/CSS/basic-shape/path": {
+    "modified": "2020-12-11T11:12:50.012Z",
+    "contributors": ["chrisdavidmills", "rachelandrew"]
+  },
   "Web/CSS/blend-mode": {
     "modified": "2020-10-15T21:29:47.283Z",
     "contributors": [
@@ -88381,10 +88385,6 @@
       "AkashMishraa"
     ]
   },
-  "Web/CSS/path": {
-    "modified": "2020-12-11T11:12:50.012Z",
-    "contributors": ["chrisdavidmills", "rachelandrew"]
-  },
   "Web/CSS/percentage": {
     "modified": "2020-12-14T06:48:33.216Z",
     "contributors": [

files/en-us/mozilla/firefox/releases/97/index.md

@@ -37,7 +37,7 @@ No notable changes
 ### SVG
 
 - The SVG {{SVGAttr('d')}} attribute, used to define a path to be drawn, can now be used as a property in CSS.
-  It accepts the values [path()](/en-US/docs/Web/CSS/path) or `none`. (See [Firefox bug 1744599](https://bugzil.la/1744599) for details.)
+  It accepts the values [path()](/en-US/docs/Web/CSS/basic-shape/path) or `none`. (See [Firefox bug 1744599](https://bugzil.la/1744599) for details.)
 
 #### Removals
 

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

@@ -7,7 +7,7 @@ browser-compat: css.types.basic-shape.circle
 
 {{CSSRef}}
 
-The **`circle()`** [CSS](/en-US/docs/Web/CSS) function is one of the {{cssxref("<basic-shape>")}} [data types](/en-US/docs/Web/CSS/CSS_Types).
+The **`circle()`** CSS [function](/en-US/docs/Web/CSS/CSS_Functions) defines a circle using a radius and a position. It is one of the {{cssxref("<basic-shape>")}} data types.
 
 {{EmbedInteractiveExample("pages/css/function-circle.html")}}
 

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

@@ -1,13 +1,13 @@
 ---
 title: path()
-slug: Web/CSS/path
+slug: Web/CSS/basic-shape/path
 page-type: css-function
 browser-compat: css.types.basic-shape.path
 ---
 
 {{CSSRef}}
 
-The **`path()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Functions) accepts an SVG path string, and is used in [CSS Shapes](/en-US/docs/Web/CSS/CSS_shapes) and CSS Motion Path to enable a shape to be drawn.
+The **`path()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Functions) accepts an [SVG path](/en-US/docs/Web/SVG/Element/path) string, and is used in the [CSS shapes](/en-US/docs/Web/CSS/CSS_shapes) and [CSS motion path](/en-US/docs/Web/CSS/CSS_motion_path) modules to enable a shape to be drawn. The `path()` function is a {{cssxref("<basic-shape>")}} data type value. It can be used in the CSS [`offset-path`](/en-US/docs/Web/CSS/offset-path) and [`clip-path`](/en-US/docs/Web/CSS/clip-path) properties and in the SVG [`d`](/en-US/docs/Web/SVG/Attribute/d) attribute.
 
 {{EmbedInteractiveExample("pages/css/function-path.html")}}
 
@@ -22,13 +22,16 @@ path(<string>)
 When used in {{cssxref("clip-path")}}:
 
 ```css
-path([<'fill-rule'>,]?<string>)
+path( [<fill-rule>,]? <string> )
 ```
 
 ### Parameters
 
 - [`<fill-rule>`](/en-US/docs/Web/SVG/Attribute/fill-rule) {{optional_inline}}
-  - : An optional value of [`nonzero`](/en-US/docs/Web/SVG/Attribute/fill-rule#nonzero) (the default when omitted) or [`evenodd`](/en-US/docs/Web/SVG/Attribute/fill-rule#evenodd), which specifies the filling rule.
+
+  - : An optional value of [`nonzero`](/en-US/docs/Web/SVG/Attribute/fill-rule#nonzero) (the default when omitted) or [`evenodd`](/en-US/docs/Web/SVG/Attribute/fill-rule#evenodd), which defines how the inside of the shape to be filled is determined.
+    > **Note:** `<fill-rule>` is not supported in {{cssxref("offset-path")}} and using it invalidates the property.
+
 - {{cssxref("string")}}
   - : A [data string](/en-US/docs/Web/SVG/Attribute/d) for defining an [SVG path](/en-US/docs/Web/SVG/Element/path). The syntax for the contents of this `<string>` is identical to SVG.
 

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

@@ -111,8 +111,8 @@ In this example, the {{cssxref("offset-path")}} property uses the `rect()` funct
 
 ## See also
 
-- [`inset()`](/en-US/docs/Web/CSS/basic-shape#inset) function
-- [`xywh()`](/en-US/docs/Web/CSS/basic-shape#xywh) function
+- {{cssxref("basic-shape/inset","inset()")}} function
+- {{cssxref("basic-shape/xywh","xywh()")}} function
 - {{cssxref("clip-path")}} property
 - {{cssxref("offset-path")}} property
 - {{cssxref("<basic-shape>")}} data type

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

@@ -0,0 +1,278 @@
+---
+title: shape()
+slug: Web/CSS/basic-shape/shape
+page-type: css-function
+browser-compat: css.types.basic-shape.shape
+---
+
+{{CSSRef}}
+
+The **`shape()`** [CSS function](/en-US/docs/Web/CSS/CSS_Functions) is used to define a shape for the {{cssxref("clip-path")}} and {{cssxref("offset-path")}} properties. It combines an initial starting point with a series of shape commands that define the path of the shape. The `shape()` function is one of the {{cssxref("<basic-shape>")}} data types.
+
+## Syntax
+
+```css
+/* <fill-rule> */
+clip-path: shape(nonzero from 0 0, line to 10px 10px);
+
+/* <move-command>, <line-command>, and close */
+offset-path: shape(from 10px 10px, move by 10px 5px, line by 20px 40%, close);
+
+/* <hvline-command> */
+offset-path: shape(from 10px 10px, hline by 50px, vline to 5rem);
+
+/* <curve-command> */
+offset-path: shape(from 10px 10px, curve to 80px 80px via 160px 1px 20% 16px);
+
+/* <smooth-command> */
+offset-path: shape(from 10px 10px, smooth to 100px 50pt);
+
+/* <arc-command> */
+offset-path: shape(
+  from 5% 0.5rem,
+  arc to 80px 1pt of 10% ccw large rotate 25deg
+);
+
+/* Using a CSS math function */
+offset-path: shape(
+  from 5px -5%,
+  hline to 50px,
+  vline by calc(0% + 160px),
+  hline by 70.5px,
+  close,
+  vline by 60px
+);
+
+clip-path: shape(
+  nonzero from 10px 10px,
+  curve to 60px 20% via 40px 0,
+  smooth to 90px 0,
+  curve by -20px 60% via 10% 40px 20% 20px,
+  smooth by -40% -10px via -10px 70px
+);
+```
+
+### Parameters
+
+- [`<fill-rule>`](/en-US/docs/Web/SVG/Attribute/fill-rule) {{optional_inline}}
+
+  - : Specifies how overlapping regions of a shape should be filled. The possible values include:
+
+    - `nonzero`: A point is considered inside the shape if a ray drawn from the point crosses more left-to-right than right-to-left path segments, resulting in a non-zero count. This is the default value when `<fill-rule>` is omitted.
+
+    - `evenodd`: A point is considered inside the shape if a ray drawn from the point crosses an odd number of path segments.
+
+    > **Note:** `<fill-rule>` is not supported in {{cssxref("offset-path")}} and using it invalidates the property.
+
+- `from <coordinate-pair>`
+
+  - : Defines the starting point for the first `<shape-command>` as a pair of coordinates that are measured from the top-left corner of the reference box. The coordinates are specified as a {{cssxref("&lt;length-percentage&gt;")}} value. Add a comma after this parameter.
+
+- `<shape-command>`
+
+  - : Specifies one or a list of comma-seperated commands that define the shape, using syntax similar to [SVG path commands](/en-US/docs/Web/SVG/Attribute/d#path_commands). The commands to define a shape include `<move-command>`, `<line-command>`, `<hv-line-command>`, `<curve-command>`, `<smooth-command>`, `<arc-command>`, and `close`. Each command's starting point is the previous command's ending point; the starting point of the shape is defined by the [`from <coordinate-pair>`](#from_coordinate-pair) parameter.
+
+    The syntax of most shape commands is the operation keyword such as `move` or `line`, followed by the `by` or `to` keyword, and then a set of coordinates.
+
+    `by`: Indicates that the `<coordinate-pair>` is relative to the command's starting point ("relative" value).
+
+    `to`: Indicates that the `<coordinate-pair>` is relative to the top-left corner of the reference box ("absolute" value).
+
+    > **Note:** If a coordinate in `<coordinate-pair>` is specified as a percentage, the value is calculated relative to the respective width or height of the reference box.
+
+    The following `<shape-command>`s can be specified:
+
+    - `<move-command>`: Specified as `move [by | to] <coordinate-pair>`. This command adds a [MoveTo command](/en-US/docs/Web/SVG/Attribute/d#moveto_path_commands) to the list of shape commands. It draws nothing. Rather, it specifies the starting position for the next command. The `by`or `to` keyword specify whether the `<coordinate-pair>` point is "relative" or "absolute", respectively. If the `<move-command>` follows the `close` command, it identifies the starting point of the next shape or subpath. 
+
+    - `<line-command>`: Specified as `line [by | to] <coordinate-pair>`. This command adds a [LineTo command](/en-US/docs/Web/SVG/Attribute/d#lineto_path_commands) to the list of shape commands. It draws a straight line from the command's starting point to its ending point. The `by`or `to` keyword specify whether the ending point specified by `<coordinate-pair>` is "relative" or "absolute", respectively.
+
+    - `<hv-line-command>`: Specified as `[hline | vline] [by | to] <length-percentage>`. This command adds a horizontal (`hline`) or vertical (`vline`) [LineTo command](/en-US/docs/Web/SVG/Attribute/d#lineto_path_commands) to the list of shape commands. With `hline`, a horizontal line is drawn from the command's starting point `to` or `by` the `x` position defined by `<length-percentage>`. With `vline`, a vertical line  is drawn from the command's starting point `to` or `by` the `y` position defined by `<length-percentage>`. The `by` or `to` keyword determines the "relative" or "absolute" ending point, respectively. This command is equivalent to `<line-command>` with one coordinate value remaining unchanged from its starting command.
+
+    - `<curve-command>`: Specified as `curve [by | to] <coordinate-pair> via <coordinate-pair> [<coordinate-pair>]`. This command adds a [Bézier curve command](/en-US/docs/Web/SVG/Attribute/d#cubic_bézier_curve) to the list of shape commands. The `by`or `to` keyword determines whether the ending point of the curve, specified by the first `<coordinate-pair>`, is "relative" or "absolute", respectively.
+
+      The `via` keyword specifies the control points of the cubic Bézier curve as one or two `<coordinate-pair>` values. If only a single `<coordinate-pair>` is provided, the command draws a [quadratic Bézier curve](/en-US/docs/Web/SVG/Attribute/d#quadratic_bézier_curve).
+
+    - `<smooth-command>`: Specified as `smooth [by | to] <coordinate-pair> [via <coordinate-pair>]`. This command adds a smooth [Bézier curve command](/en-US/docs/Web/SVG/Attribute/d#cubic_bézier_curve) to the list of shape commands. The `by`or `to` keyword determines whether the ending point of the curve, specified by the first `<coordinate-pair>`, is "relative" or "absolute", respectively.
+
+      The `via` keyword can be optionally included to specify the control points of the curve through `<coordinate-pair>`. If `via <coordinate-pair>` is omitted, the command draws a smooth quadratic curve; if it is provided, the command draws a smooth cubic curve.
+
+    - `<arc-command>`: Specified as `arc [by | to] <coordinate-pair> of <length-percentage> [<length-percentage>] [<arc-sweep> | <arc-size> | rotate <angle>]`. This command adds an [elliptical arc curve command](/en-US/docs/Web/SVG/Attribute/d#elliptical_arc_curve) to the list of shape commands. It draws an elliptical arc between a starting point and an ending point. The `by`or `to` keyword determine whether the ending point of the curve, specified by the first `<coordinate-pair>`, is "relative" or "absolute", respectively.
+
+      The elliptical arc curve command defines two possible ellipses, which intersect both the starting and ending points, and each can be traced in either direction, resulting in four possible arcs depending on the arc size, direction, and angle. The `of` keyword specifies the size of the ellipse from which the arc is taken. The first `<length-percentage>` provides the horizontal radius of the ellipse, and the second provides the vertical radius. If only one `<length-percentage>` is provided, the same value is used for both radii. The following parameters help to determine which of the four arcs are used:
+
+      - `<arc-sweep>`: Indicates whether the desired arc is the one traced around the ellipse clockwise (`cw`) or counter-clockwise (`ccw`). If omitted, this defaults to `ccw`.
+      - `<arc-size>`: Indicates whether the desired arc is the larger (`large`) or smaller (`small`) of the two arcs. If omitted, this defaults to `small`.
+      - `<angle>`: Specifies the angle, in degrees, by which to rotate the ellipse relative to the x-axis. A positive angle rotates the ellipse clockwise, and a negative angle rotates it counter-clockwise. If omitted, this defaults to `0deg`.
+
+      > **Note:** If the starting and ending points of the arc lie on exactly opposite sides of the ellipse, there is only one possible ellipse and two possible arcs. In this case, `<arc-sweep>` specifies the arc to choose, and `<arc-size>` has no effect.
+
+    - `close`: Adds a [ClosePath command](/en-US/docs/Web/SVG/Attribute/d#closepath) to the list of shape commands, drawing a straight line from the current position (end of the last command) to the first point in the path defined in the `from <coordinate-pair>` parameter. To close the shape without drawing a line, use `<move-command>` with the originating coordinates. If the `close` command is immediately followed by a `<move-command>`, it defines the starting point of the next shape or subpath.
+
+## Description
+
+The `shape()` function allows you to define complex shapes. It is similar to the {{cssxref("basic-shape/path","path()")}} function in several ways:
+
+- The `<fill-rule>` parameter in the `shape()` function works exactly like the same parameter in the `path()` function.
+- The `shape()` function requires specifying one or more `<shape-command>`s, where each command uses an underlying [path command](/en-US/docs/Web/SVG/Attribute/d#path_commands), such as [MoveTo](/en-US/docs/Web/SVG/Attribute/d#moveto_path_commands), [LineTo](/en-US/docs/Web/SVG/Attribute/d#lineto_path_commands), and [ClosePath](/en-US/docs/Web/SVG/Attribute/d#closepath).
+
+However, `shape()` offers several advantages over using `path()`:
+
+- Unlike `path()`, which uses the [SVG path](/en-US/docs/Web/SVG/Element/path) syntax, `shape()` uses standard CSS syntax, making it easier to create and modify shapes directly in your stylesheet.
+- The `path()` function inherits some limitations from SVG, such as requiring shapes to be written as a single string and limiting units to `px`. The `shape()` function, on the other hand, supports a variety of CSS units, including percentages, `rem`, and `em`.
+- `shape()` also allows the use of CSS math functions, providing more versatility when defining shapes.
+
+## Formal syntax
+
+{{csssyntax}}
+
+## Examples
+
+### Using `shape()` to define a path
+
+This example demonstrates how the `shape()` function can be used in the {{cssxref("offset-path")}} property to define the shape of the path that an element can follow. We're creating a curved path in this example.
+
+```html hidden
+<div class="container">
+  Using <code>&lt;curve-command&gt;</code>
+  <div class="shape shape1">>></div>
+</div>
+
+<div class="container">
+  Using <code>&lt;move-command&gt;</code> and
+  <code>&lt;hvline-command&gt;</code>
+  <div class="shape shape2">>></div>
+</div>
+```
+
+```css hidden
+body {
+  align-items: center;
+  justify-content: center;
+  display: flex;
+}
+
+.container {
+  position: relative;
+  display: inline-block;
+  width: 250px;
+  height: 250px;
+  border: 2px dotted green;
+  margin: 20px;
+}
+```
+
+```css
+.shape {
+  width: 50px;
+  height: 50px;
+  background: #2bc4a2;
+  position: absolute;
+  text-align: center;
+  line-height: 50px;
+  animation: move 5s infinite alternate ease-in-out;
+}
+
+.shape1 {
+  offset-path: shape(from 30% 60px, curve to 180px 180px via 90px 190px);
+}
+
+.shape2 {
+  offset-path: shape(
+    from 20px 20px,
+    move to 50px 90px,
+    hline to 8em,
+    vline by 20%
+  );
+}
+
+@keyframes move {
+  0% {
+    offset-distance: 0%;
+  }
+  100% {
+    offset-distance: 100%;
+  }
+}
+```
+
+#### Result
+
+{{EmbedLiveSample('Using shape() to define a path', '100%', 300)}}
+
+### Using `shape()` to define the visible part of an element
+
+This example demonstrates how the `shape()` function can be used in the {{cssxref("clip-path")}} property to create the shape of the clipping region.
+
+```html hidden
+<div class="container">
+  <div class="shape shape1"></div>
+</div>
+
+<div class="container">
+  <div class="shape shape2"></div>
+</div>
+```
+
+```css hidden
+body {
+  align-items: center;
+  justify-content: center;
+  display: flex;
+}
+
+.container {
+  position: relative;
+  display: inline-block;
+  width: 200px;
+  height: 200px;
+  margin: 20px;
+  background-color: lightgray;
+}
+```
+
+```css
+.shape {
+  width: 100%;
+  height: 100%;
+  background: #2bc4a2;
+  position: absolute;
+  text-align: center;
+  line-height: 50px;
+}
+
+/* Simple triangle */
+.shape1 {
+  clip-path: shape(from 0% 0%, line to 100% 0%, line to 50% 100%, close);
+}
+
+/* More complex shape with curves and smooth transitions */
+.shape2 {
+  clip-path: shape(
+    from 10px 10px,
+    curve to 60px 20% via 40px 0,
+    smooth to 90px 0,
+    curve by -20px 60% via 10% 40px 20% 20px,
+    smooth by -40% -10px via -10px 70px
+  );
+}
+```
+
+#### Result
+
+{{EmbedLiveSample('Using shape() to define the visible part of an element', '100%', 300)}}
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{cssxref("clip-path")}}
+- {{cssxref("offset-path")}}
+- [CSS shapes](/en-US/docs/Web/CSS/CSS_shapes) module
+- [Overview of shapes](/en-US/docs/Web/CSS/CSS_shapes/Overview_of_shapes) guide
+- [Basic shapes](/en-US/docs/Web/CSS/CSS_shapes/Basic_shapes) guide

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

@@ -96,8 +96,8 @@ In the example below, the {{cssxref("offset-path")}} property uses the `xywh()`
 
 ## See also
 
-- [`inset()`](/en-US/docs/Web/CSS/basic-shape#inset) function
-- [`rect()`](/en-US/docs/Web/CSS/basic-shape#rect) function
+- {{cssxref("basic-shape/inset","inset()")}} function
+- {{cssxref("basic-shape/rect","rect()")}} function
 - {{cssxref("clip-path")}} property
 - {{cssxref("offset-path")}} property
 - {{cssxref("<basic-shape>")}} data type