Skip to content

[css-shapes-2] Specify the grammar for shape() #11207

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 11 commits into from
Dec 10, 2024
Merged

[css-shapes-2] Specify the grammar for shape() #11207

Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
772d7e7
[css-shapes-2] Specify the grammar for `shape()`
noamr Nov 13, 2024
924abaa
Update css-shapes-2/Overview.bs
noamr Nov 14, 2024
52a829b
Update css-shapes-2/Overview.bs
noamr Nov 14, 2024
a691bfc
Update css-shapes-2/Overview.bs
noamr Nov 14, 2024
27335ce
Update css-shapes-2/Overview.bs
noamr Nov 14, 2024
3036180
Add note about by/to
noamr Nov 14, 2024
71fc268
Update css-shapes-2/Overview.bs
tabatkins Dec 10, 2024
05f5fd9
Update css-shapes-2/Overview.bs
tabatkins Dec 10, 2024
2762144
Update css-shapes-2/Overview.bs
tabatkins Dec 10, 2024
66905cf
Update css-shapes-2/Overview.bs
tabatkins Dec 10, 2024
1e72e75
Update css-shapes-2/Overview.bs
tabatkins Dec 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 90 additions & 31 deletions css-shapes-2/Overview.bs
View file
Open in desktop
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