Skip to content

Commit

Permalink
[css-values-5] Define logical <<position>> values per #549
Browse files Browse the repository at this point in the history
  • Loading branch information
@fantasai
fantasai committed Sep 13, 2024
1 parent ce239ec commit 28b1db7
Showing 1 changed file with 262 additions and 0 deletions.
262 changes: 262 additions & 0 deletions css-values-5/Overview.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -172,6 +172,10 @@ Commas and Semicolons in Functions</h4>
* <<whole-value>>
* <<declaration-value>>

<h2 id="level-4-extensions">
Extensions to Level 4 Value Types</h3>

See <a href="https://www.w3.org/TR/css-values-4/">CSS Values and Units Level 4</a>.

<!-- Big Text: url

Expand Down Expand Up @@ -238,6 +242,264 @@ Request URL Modifiers</h4>
</div>


<!-- Big Text: position

████▌ ███▌ ███▌ ████ █████▌ ████ ███▌ █ █▌
█▌ █▌ █▌ █▌ █▌ █▌ ▐▌ █▌ ▐▌ █▌ █▌ █▌ █▌
█▌ █▌ █▌ █▌ █▌ ▐▌ █▌ ▐▌ █▌ █▌ ██▌ █▌
████▌ █▌ █▌ ███▌ ▐▌ █▌ ▐▌ █▌ █▌ █▌▐█ █▌
█▌ █▌ █▌ █▌ ▐▌ █▌ ▐▌ █▌ █▌ █▌ ██▌
█▌ █▌ █▌ █▌ █▌ ▐▌ █▌ ▐▌ █▌ █▌ █▌ █▌
█▌ ███▌ ███▌ ████ █▌ ████ ███▌ █▌ ▐▌
-->

<h3 id="position">
2D Positioning: the <<position>> type</h3>

The <dfn><<position>></dfn> value specifies the position
of an [=alignment subject=] (e.g. a background image)
inside an [=alignment container=] (e.g. its [=background positioning area=])
as a pair of offsets between the specified edges
(defaulting to the left and top).
Its syntax is:

<pre class=prod>
<<position>> = <<position-one>> | <<position-two>> | <<position-four>>
<dfn><<position-one>></dfn> = [
left | center | right | top | bottom |
x-start | x-end | y-start | y-end |
block-start | block-end | inline-start | inline-end |
<<length-percentage>>
]
<dfn><<position-two>></dfn> = [
[ left | center | right | x-start | x-end ] &&
[ top | center | bottom | y-start | y-end ]
|
[ left | center | right | x-start | x-end | <<length-percentage>> ]
[ top | center | bottom | y-start | y-end | <<length-percentage>> ]
|
[ block-start | center | block-end ] &&
[ inline-start | center | inline-end ]
|
[ start | center | end ]{2}
]
<dfn><<position-four>></dfn> = [
[ [ left | right | x-start | x-end ] <<length-percentage>> ] &&
[ [ top | bottom | y-start | y-end ] <<length-percentage>> ]
|
[ [ block-start | block-end ] <<length-percentage>> ] &&
[ [ inline-start | inline-end ] <<length-percentage>> ]
|
[ [ start | end ] <<length-percentage>> ]{2}
]
</pre>

If only one value is specified (<<position-one>>),
the second value is assumed to be ''center''.

If two values are given (<<position-two>>),
a <<length-percentage>> as the first value represents
the horizontal position as the offset between
the left edges of the [=alignment subject=] and [=alignment container=],
and a <<length-percentage>> as the second value represents
the vertical position as an offset between their top edges.

If both keywords are one of ''start'' or ''end'',
the first one represents the [=block axis=]
and the second the [=inline axis=].

Note: A pair of axis-specific keywords can be reordered,
while a combination of keyword and length or percentage cannot.
So ''center left'' or ''inline-start block-end'' is valid,
while ''50% left'' is not.
''<position>/start'' and ''<position>/end'' aren't axis-specific,
so ''start end'' and ''end start'' represent two different positions.

If four values are given (<<position-four>>)
then each <<length-percentage>> represents an offset between
the edges specified by the preceding keyword.
For example, ''background-position: bottom 10px right 20px''
represents a ''10px'' vertical offset up from the bottom edge
and a ''20px'' horizontal offset leftward from the right edge.

Positive values represent an offset <em>inward</em>
from the edge of the [=alignment container=].
Negative values represent an offset <em>outward</em>
from the edge of the [=alignment container=].

<div class="example">
The following declarations give the stated (horizontal, vertical)
offsets from the top left corner:
<pre>
background-position: left 10px top 15px; /* 10px, 15px */
background-position: left top ; /* 0px, 0px */
background-position: 10px 15px; /* 10px, 15px */
background-position: left 15px; /* 0px, 15px */
background-position: 10px top ; /* 10px, 0px */
</pre>
</div>

<div class=example>
<<position>>s can also be relative to other corners than the top left.
For example, the following puts the background image
10px from the bottom and 3em from the right:

<pre>background-position: right 3em bottom 10px</pre>
</div>

The [=computed value=] of a <<position>> is
a pair of offsets (horizontal and vertical),
each given as a computed <<length-percentage>> value,
representing the distance between the left edges and top edges (respectively)
of the [=alignment subject=] and [=alignment container=].

<dl dfn-for=background-position dfn-type=value>
<dt><dfn><<length-percentage>></dfn>
<dd>
A <<length-percentage>> value specifies the size of the offset
between the specified edges of the [=alignment subject=] and [=alignment container=].

For example, for ''background-position: 2cm 1cm'',
the top left corner of the background image is placed
2cm to the right and 1cm below
the top left corner of the [=background positioning area=].

A <<percentage>> for the horizontal offset is relative to
(<var>width of [=alignment container=]</var> - <var>width of [=alignment subject=]</var>).
A <<percentage>> for the vertical offset is relative to
(<var>height of [=alignment container=]</var> - <var>height of [=alignment subject=]</var>).

<div class=example>
For example, with a value pair of ''0% 0%'',
the upper left corner of the [=alignment subject=] is aligned with
the upper left corner of the [=alignment container=]
A value pair of ''100% 100%'' places
the lower right corner of the [=alignment subject=]
in the lower right corner of the [=alignment container=].
With a value pair of ''75% 50%'',
the point 75% across and 50% down the [=alignment subject=]
is to be placed at the point 75% across and 50% down the [=alignment container=].
<figure>
<img src="images/bg-pos.png"
alt="Diagram of image position within element"
>
<figcaption>
Diagram of the meaning of ''background-position: 75% 50%''.
</figcaption>
</div>
</div>

<dt><dfn>top</dfn>
<dt><dfn>right</dfn>
<dt><dfn>bottom</dfn>
<dt><dfn>left</dfn>
<dd>
Offsets the top/left/right/bottom edges (respectively)
of the [=alignment subject=] and [=alignment container=]
by the specified amount (defaulting to ''0%'')
in the corresponding axis.

<dt><dfn>y-start</dfn>
<dt><dfn>y-end</dfn>
<dt><dfn>x-start</dfn>
<dt><dfn>x-end</dfn>
<dd>
Computes the same as the physical edge keyword
corresponding to the [=start=]/[=end=] side
in the [=y-axis|y/[=x-axis|x=] axis.

<dt><dfn>block-start</dfn>
<dt><dfn>block-end</dfn>
<dt><dfn>inline-start</dfn>
<dt><dfn>inline-end</dfn>
<dd>
Computes the same as the physical edge keyword
corresponding to the [=start=]/[=end=] side
in the [=block axis|block=]/[=inline axis|inline=] axis.

<dt><dfn>center</dfn>
<dd>
Computes to a ''50%'' offset in the corresponding axis.
</dl>

Unless otherwise specified, the [=flow-relative=] keywords are resolved
according to the [=writing mode=] of the element on which the value is specified.

Note: The 'background-position' property also accepts a three-value syntax.
This has been disallowed generically because it creates parsing ambiguities
when combined with other length or percentage components in a property value.

ISSUE: Need to define how this syntax would expand to the longhands of 'background-position'
if e.g. ''var()'' is used for some (or all) of the components.

<h4 id="position-parsing">
Parsing <<position>></h4>

When specified in a grammar alongside other keywords, <<length>>s, or <<percentage>>s,
<<position>> is <em>greedily</em> parsed;
it consumes as many components as possible.

<div class=example>
For example,
'transform-origin' defines a 3D position
as (effectively) ''<<position>> <<length>>?''.
A value such as ''left 50px''
will be parsed as a 2-value <<position>>,
with an omitted z-component;
on the other hand,
a value such as ''top 50px''
will be parsed as a single-value <<position>>
followed by a <<length>>.
</div>

<h4 id="position-serialization">
Serializing <<position>></h4>

When serializing the [=specified value=] of a <<position>>:

<dl class=switch>
<dt>If only one component is specified:
<dd>
* The implied <a value spec="css-backgrounds-3">center</a> keyword is added,
and a 2-component value is serialized.

<dt>If two components are specified:
<dd>
* Keywords are serialized as keywords.
* <<length-percentage>>s are serialized as <<length-percentage>>s.
* Components are serialized horizontal first, then vertical.

<dt>If four components are specified:
<dd>
* Keywords and offsets are both serialized.
* Components are serialized horizontal first, then vertical;
alternatively [=block-axis=] first, then [=inline-axis=].
</dl>

Note: <<position>> values are never serialized as a single value,
even when a single value would produce the same behavior,
to avoid causing parsing ambiguities in some grammars
where a <<position>> is placed next to a <<length>>,
such as 'transform-origin'.

The [=computed value=] of a <<position>>
is serialized as a pair of <<length-percentage>>s
representing offsets from the left and top edges, in that order.

<h4 id="combine-positions">
Combination of <<position>></h4>

<a>Interpolation</a> of <<position>> is defined as
the independent interpolation of each component (x, y)
normalized as an offset from the top left corner
as a <<length-percentage>>.

<a>Addition</a> of <<position>> is likewise defined as
the independent <a>addition</a> each component (x, y)
normalized as an offset from the top left corner
as a <<length-percentage>>.


<!-- Big Text: interp

████ █ █▌ █████▌ █████▌ ████▌ ████▌
Expand Down

0 comments on commit 28b1db7

Please sign in to comment.