Skip to content

Commit

Permalink
[css-shapes-2] Specify the grammar for shape() (#11207)
Browse files Browse the repository at this point in the history 
* [css-shapes-2] Specify the grammar for `shape()`

- <<position>> can be used instead of an absolute point.
- One of a <<position>>'s dimension can be used for hline/vline
- Since keywords define the different components, order of components is flexible.

Curves:
- `with` is used for control points
- Two control points are separated by /
- Relative control points can be relative to segment-start/segment-end/reference-box

Resolution: #10649 (comment)

Closes #10649
Closes #10666

* Update css-shapes-2/Overview.bs

Co-authored-by: fantasai <[email protected]>

* Update css-shapes-2/Overview.bs

Co-authored-by: fantasai <[email protected]>

* Update css-shapes-2/Overview.bs

Co-authored-by: fantasai <[email protected]>

* Update css-shapes-2/Overview.bs

Co-authored-by: fantasai <[email protected]>

* Add note about by/to

* Update css-shapes-2/Overview.bs

* Update css-shapes-2/Overview.bs

* Update css-shapes-2/Overview.bs

* Update css-shapes-2/Overview.bs

* Update css-shapes-2/Overview.bs

---------

Co-authored-by: fantasai <[email protected]>
Co-authored-by: Tab Atkins Jr. <[email protected]>
  • Loading branch information
@noamr @fantasai @tabatkins
3 people authored Dec 10, 2024
1 parent 75a4d2b commit 8814e9e
Showing 1 changed file with 90 additions and 31 deletions.
121 changes: 90 additions & 31 deletions css-shapes-2/Overview.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,16 @@ spec:css-writing-modes-4; type:concept; text:physical
spec:css-writing-modes-4; type:concept; text:"writing mode"
spec:svg2; type:property;
text:fill-rule
spec:css-values-5; type:value;
text:top;
text:right;
text:bottom;
text:left;
text:center;
text:x-start;
text:y-start;
text:x-end;
text:y-end;
</pre>

<style type="text/css">
Expand Down Expand Up @@ -162,17 +172,32 @@ The ''shape()'' Function</h4>
Each command's starting point is the previous command's ending point.

<pre class=prod>
<<shape-command>> = <<move-command>> | <<line-command>> | <<hv-line-command>> |
<<curve-command>> | <<smooth-command>> | <<arc-command>> | close
<<shape-command>> = <<move-command>> | <<line-command>> | close |
<<horizontal-line-command>> | <<vertical-line-command>> |
<<curve-command>> | <<smooth-command>> | <<arc-command>>
<<move-command>> = move <<command-end-point>>
<<line-command>> = line <<command-end-point>>
<<horizontal-line-command>> = hline
[ to [ <<length-percentage>> | left | center | right | x-start | x-end ]
| by <<length-percentage>> ]
<<vertical-line-command>> = vline
[ to [ <<length-percentage>> | top | center | bottom | y-start | y-end ]
| by <<length-percentage>> ]
<<curve-command>> = curve
[ [ to <<position>> && [ with <<control-point>> [ / <<control-point>> ]? ] ]
| [ by <<coordinate-pair>> && [ with <<relative-control-point>> [ / <<relative-control-point>> ]? ] ] ]
<<smooth-command>> = smooth
[ [ to <<position>> && [ with <<control-point>> ]? ]
| [ by <<coordinate-pair>> && [ with <<relative-control-point>> ]? ] ]
<<arc-command>> = arc [ <<command-end-point>>
&& [ of <<coordinate-pair>> ]
&& <<arc-sweep>>? && <<arc-size>>? && [rotate <<angle>>]? ]
<<command-end-point>> = [ to <<position>> | by <<coordinate-pair>> ]
<<control-point>> = [ <<position>> | <<relative-control-point>> ]
<<relative-control-point>> = <<coordinate-pair>> [ from [ start | end | origin ] ]?
<<coordinate-pair>> = <<length-percentage>>{2}
<<by-to>> = by | to
<<move-command>> = move <<by-to>> <<coordinate-pair>>
<<line-command>> = line <<by-to>> <<coordinate-pair>>
<<hv-line-command>> = [hline | vline] <<by-to>> <<length-percentage>>
<<curve-command>> = curve [<<by-to>> <<coordinate-pair>> using <<coordinate-pair>>{1,2}]
<<smooth-command>> = smooth [[<<by-to>> <<coordinate-pair>>] || [using <<coordinate-pair>>]?]
<<arc-command>> = arc [[<<by-to>> <<coordinate-pair>>] || [of <<length-percentage>>{1,2}] ||
<<arc-sweep>>? || <<arc-size>>? || [rotate <<angle>>]?]
<<arc-sweep>> = cw | ccw
<<arc-size>> = large | small
</pre>
Expand All @@ -185,19 +210,25 @@ The ''shape()'' Function</h4>
Percentages are resolved against the width or height, respectively,
of the [=reference box=].

<dt><dfn><<by-to>></dfn> = <dfn value for="shape(), <by-to>">by</dfn> | <dfn value for="shape(), <by-to>">to</dfn>
<dt><dfn><<command-end-point>></dfn> = [ <dfn value for="shape(), <command-end-point>">by</dfn> <<position>> | <dfn value for="shape(), <command-end-point>">to</dfn> <<coordinate-pair>> ]
<dd>
Every command can be specified in "absolute" or "relative" coordinates,
determined by their <<by-to>> component.
''to'' indicates that any <<coordinate-pair>>s in the command
determined by their ''shape()/by'' or ''shape()/to'' component.
''shape()/to'' indicates that any <<coordinate-pair>>s in the command
are relative to the top-left corner of the [=reference box=],
while ''by'' indicates that the <<coordinate-pair>>s
while ''shape()/by'' indicates that the <<coordinate-pair>>s
are relative to the command's starting point.

<<relative-control-point>> defines how ''shape()/by'' and ''shape()/to'' are interpreted for curve control points,
while <<horizontal-line-command>> and <<vertical-line-command>> define how ''shape()/by'' and ''shape()/to'' are
interpreted for horizontal and vertical lines, respectively.

When ''shape()/to'' is used, the coordinates can be specified as <<position>>s instead of <<coordinate-pair>>s.

Note: In either case, <<percentage>> values in <<coordinate-pair>>s
are always computed relative to the [=reference box's=] size.

<dt><dfn><<move-command>></dfn> = <dfn value>move</dfn> <<by-to>> <<coordinate-pair>>
<dt><dfn><<move-command>></dfn> = <dfn value>move</dfn> <<command-end-point>>
<dd>
Adds a <a href="https://www.w3.org/TR/SVG/paths.html#PathDataMovetoCommands">moveto</a> command
to the list of path data commands,
Expand All @@ -209,42 +240,58 @@ The ''shape()'' Function</h4>
Note: This starts a new subpath,
for the purpose of the ''close'' command.

<dt><dfn><<line-command>></dfn> = <dfn value>line</dfn> <<by-to>> <<coordinate-pair>>
<dt><dfn><<line-command>></dfn> = <dfn value>line</dfn> <<command-end-point>>
<dd>
Adds a <a href="https://www.w3.org/TR/SVG/paths.html#PathDataLinetoCommands">lineto</a> command
to the list of path data commands,
with an ending point specified by the <<coordinate-pair>>.

This draws a straight line from the command's starting point to its ending point.

<dt><dfn><<hv-line-command>></dfn> = [<dfn value>hline</dfn> | <dfn value>vline</dfn>] <<by-to>> <<length-percentage>>
<dt><dfn><<horizontal-line-command>></dfn> = hline [ to [ <length-percentage> | left | center | right | x-start | x-end ]
| by <length-percentage> ]
<dd>
Adds a horizontal (for ''hline'') or vertical (for ''vline'')
Adds a horizontal
<a href="https://www.w3.org/TR/SVG/paths.html#PathDataLinetoCommands">lineto</a> command
to the list of path data commands.

This is equivalent to a ''line'' command
with the <<length-percentage>> given as the horizontal or vertical component, respectively,
of the <<coordinate-pair>>,
and the other component specified appropriately to make the line horizontal or vertical.
with the <<length-percentage>> given as the horizontal component of the <<coordinate-pair>>.
Specifying the horizontal component of <<position>> instead of a <<length-percentage>> (''left'', ''center'', ''right'', ''x-start'', or ''x-end''),
would draw a line to that <<position>>, with the <<position>>'s vertical component remaining the same as the starting point.

<dt><dfn><<vertical-line-command>></dfn> = vline [ to [ <length-percentage> | top | center | bottom | y-start | y-end ] | by <length-percentage> ]
<dd>
Adds a vertical
<a href="https://www.w3.org/TR/SVG/paths.html#PathDataLinetoCommands">lineto</a> command
to the list of path data commands.

<dt><dfn><<curve-command>></dfn> = <dfn value>curve</dfn> [[<<by-to>> <<coordinate-pair>>] || [using <<coordinate-pair>>{1,2}]]
This is equivalent to a ''line'' command
with the <<length-percentage>> given as the vertical component of the <<coordinate-pair>>.
Specifying the horizontal component of <<position>>
(''top'', ''center'', ''bottom'', ''y-start'', or ''y-end'')
instead of a <<length-percentage>>,
would draw a line to that <<position>>, with the <<position>>'s horizontal component remaining the same as the starting point.

<dt><dfn><<curve-command>></dfn> = <dfn value>curve</dfn> [ [ to <<position>> && with <<control-point>> [ / <<control-point>> ]? ]
| [ by <<coordinate-pair>> && with <<relative-control-point>> [ / <<relative-control-point>> ]? ] ]
<dd>
Adds a Bézier curve command to the list of path data commands,
ending at the point specified by the first <<coordinate-pair>>.
ending at the point specified by the <<position>> following the ''shape()/to'' keyword,
or the <<coordinate-pair>> following the ''shape()/by'' keyword, as specified by <<command-end-point>>.

The <css>using</css> component specifies control points for the curve:
if a single <<coordinate-pair>> is provided,
The <css>with</css> component specifies control points for the curve:
if a single <<control-point>> or <<relative-control-point>> is provided,
the command specifies a <a href="https://www.w3.org/TR/SVG/paths.html#PathDataQuadraticBezierCommands">quadratic curve</a>;
if two <<coordinate-pair>>s are provided,
if two <<control-point>>s or <<relative-control-point>>s are provided,
it specifies a <a href="https://www.w3.org/TR/SVG/paths.html#PathDataCubicBezierCommands">cubic curve</a>.

<dt><dfn><<smooth-command>></dfn> = <dfn value>smooth</dfn> [[<<by-to>> <<coordinate-pair>>] || [using <<coordinate-pair>>]?]
<dt><dfn><<smooth-command>></dfn> = <dfn value>smooth</dfn> [ [ to <<position>> && [with <<control-point>> ]? ]
| [ by <<coordinate-pair>> && [ with <<relative-control-point>> ]? ] ]
<dd>
Adds a smooth Bézier curve command to the list of path data commands,
ending at the point specified by the first <<coordinate-pair>>.

The <css>using</css> component specifies control points for the curve:
ending at the point specified by the <<position>> following the ''shape()/to'' keyword, or the <<coordinate-pair>> following the ''shape()/by'' keyword, as specified by <<command-end-point>>.
The <css>with</css> component specifies control points for the curve:
if it's omitted,
the command specifies a <a href="https://www.w3.org/TR/SVG/paths.html#PathDataQuadraticBezierCommands">smooth quadratic curve</a>;
if it's provided,
Expand All @@ -259,11 +306,23 @@ The ''shape()'' Function</h4>
so the curve appears to smoothly continue from the previous command,
rather than possibly making a sudden direction change.

<dt><dfn><<control-point>></dfn> = [ <<position>> | <<relative-control-point>> ]
<dd>
Provides a control point to a quadratic or cubic Bézier curve.

<dt><dfn><<relative-control-point>></dfn> = <<coordinate-pair>> [ from [ start | end | origin ] ]?
<dd>
Provides a control point to a quadratic or cubic Bézier curve.
When a <css>from</css> keyword is specified followed by <css>start</css>, <css>end</css>, or <css>origin</css>,
the given <<coordinate-pair>> is relative to
the command's starting point, the command's end point, or the [=reference box=], respectively.
If such component is not provided, the <<coordinate-pair>> is relative to the segment's start.

<dt><dfn><<arc-command>></dfn> = <dfn value>arc</dfn> [[<<by-to>> <<coordinate-pair>>] || [of <<length-percentage>>{1,2}] || <<arc-sweep>>? || <<arc-size>>?|| rotate <<angle>>? ]
<dd>
Add an <a href="https://www.w3.org/TR/SVG/paths.html#PathDataEllipticalArcCommands">elliptical arc</a> command
to the list of path data commands,
ending at the point specified by the <<coordinate-pair>>.
ending at the <<command-end-point>>.

The <css>of</css> component specifies the size of the ellipse that the arc is taken from.
The first <<length-percentage>> provides the horizontal radius of the ellipse
Expand Down

0 comments on commit 8814e9e

Please sign in to comment.