Skip to content

Commit 28b1db7

Browse files
fantasaifantasai
committed
[css-values-5] Define logical <<position>> values per #549 
1 parent ce239ec commit 28b1db7

File tree

1 file changed

+262
-0
lines changed

1 file changed

+262
-0
lines changed

‎css-values-5/Overview.bs

+262
Original file line numberDiff line numberDiff line change
@@ -172,6 +172,10 @@ Commas and Semicolons in Functions</h4>
172172
* <<whole-value>>
173173
* <<declaration-value>>
174174

175+
<h2 id="level-4-extensions">
176+
Extensions to Level 4 Value Types</h3>
177+
178+
See <a href="https://www.w3.org/TR/css-values-4/">CSS Values and Units Level 4</a>.
175179

176180
<!-- Big Text: url
177181

@@ -238,6 +242,264 @@ Request URL Modifiers</h4>
238242
</div>
239243

240244

245+
<!-- Big Text: position
246+
247+
████▌ ███▌ ███▌ ████ █████▌ ████ ███▌ █ █▌
248+
█▌ █▌ █▌ █▌ █▌ █▌ ▐▌ █▌ ▐▌ █▌ █▌ █▌ █▌
249+
█▌ █▌ █▌ █▌ █▌ ▐▌ █▌ ▐▌ █▌ █▌ ██▌ █▌
250+
████▌ █▌ █▌ ███▌ ▐▌ █▌ ▐▌ █▌ █▌ █▌▐█ █▌
251+
█▌ █▌ █▌ █▌ ▐▌ █▌ ▐▌ █▌ █▌ █▌ ██▌
252+
█▌ █▌ █▌ █▌ █▌ ▐▌ █▌ ▐▌ █▌ █▌ █▌ █▌
253+
█▌ ███▌ ███▌ ████ █▌ ████ ███▌ █▌ ▐▌
254+
-->
255+
256+
<h3 id="position">
257+
2D Positioning: the <<position>> type</h3>
258+
259+
The <dfn><<position>></dfn> value specifies the position
260+
of an [=alignment subject=] (e.g. a background image)
261+
inside an [=alignment container=] (e.g. its [=background positioning area=])
262+
as a pair of offsets between the specified edges
263+
(defaulting to the left and top).
264+
Its syntax is:
265+
266+
<pre class=prod>
267+
<<position>> = <<position-one>> | <<position-two>> | <<position-four>>
268+
<dfn><<position-one>></dfn> = [
269+
left | center | right | top | bottom |
270+
x-start | x-end | y-start | y-end |
271+
block-start | block-end | inline-start | inline-end |
272+
<<length-percentage>>
273+
]
274+
<dfn><<position-two>></dfn> = [
275+
[ left | center | right | x-start | x-end ] &&
276+
[ top | center | bottom | y-start | y-end ]
277+
|
278+
[ left | center | right | x-start | x-end | <<length-percentage>> ]
279+
[ top | center | bottom | y-start | y-end | <<length-percentage>> ]
280+
|
281+
[ block-start | center | block-end ] &&
282+
[ inline-start | center | inline-end ]
283+
|
284+
[ start | center | end ]{2}
285+
]
286+
<dfn><<position-four>></dfn> = [
287+
[ [ left | right | x-start | x-end ] <<length-percentage>> ] &&
288+
[ [ top | bottom | y-start | y-end ] <<length-percentage>> ]
289+
|
290+
[ [ block-start | block-end ] <<length-percentage>> ] &&
291+
[ [ inline-start | inline-end ] <<length-percentage>> ]
292+
|
293+
[ [ start | end ] <<length-percentage>> ]{2}
294+
]
295+
</pre>
296+
297+
If only one value is specified (<<position-one>>),
298+
the second value is assumed to be ''center''.
299+
300+
If two values are given (<<position-two>>),
301+
a <<length-percentage>> as the first value represents
302+
the horizontal position as the offset between
303+
the left edges of the [=alignment subject=] and [=alignment container=],
304+
and a <<length-percentage>> as the second value represents
305+
the vertical position as an offset between their top edges.
306+
307+
If both keywords are one of ''start'' or ''end'',
308+
the first one represents the [=block axis=]
309+
and the second the [=inline axis=].
310+
311+
Note: A pair of axis-specific keywords can be reordered,
312+
while a combination of keyword and length or percentage cannot.
313+
So ''center left'' or ''inline-start block-end'' is valid,
314+
while ''50% left'' is not.
315+
''<position>/start'' and ''<position>/end'' aren't axis-specific,
316+
so ''start end'' and ''end start'' represent two different positions.
317+
318+
If four values are given (<<position-four>>)
319+
then each <<length-percentage>> represents an offset between
320+
the edges specified by the preceding keyword.
321+
For example, ''background-position: bottom 10px right 20px''
322+
represents a ''10px'' vertical offset up from the bottom edge
323+
and a ''20px'' horizontal offset leftward from the right edge.
324+
325+
Positive values represent an offset <em>inward</em>
326+
from the edge of the [=alignment container=].
327+
Negative values represent an offset <em>outward</em>
328+
from the edge of the [=alignment container=].
329+
330+
<div class="example">
331+
The following declarations give the stated (horizontal, vertical)
332+
offsets from the top left corner:
333+
<pre>
334+
background-position: left 10px top 15px; /* 10px, 15px */
335+
background-position: left top ; /* 0px, 0px */
336+
background-position: 10px 15px; /* 10px, 15px */
337+
background-position: left 15px; /* 0px, 15px */
338+
background-position: 10px top ; /* 10px, 0px */
339+
</pre>
340+
</div>
341+
342+
<div class=example>
343+
<<position>>s can also be relative to other corners than the top left.
344+
For example, the following puts the background image
345+
10px from the bottom and 3em from the right:
346+
347+
<pre>background-position: right 3em bottom 10px</pre>
348+
</div>
349+
350+
The [=computed value=] of a <<position>> is
351+
a pair of offsets (horizontal and vertical),
352+
each given as a computed <<length-percentage>> value,
353+
representing the distance between the left edges and top edges (respectively)
354+
of the [=alignment subject=] and [=alignment container=].
355+
356+
<dl dfn-for=background-position dfn-type=value>
357+
<dt><dfn><<length-percentage>></dfn>
358+
<dd>
359+
A <<length-percentage>> value specifies the size of the offset
360+
between the specified edges of the [=alignment subject=] and [=alignment container=].
361+
362+
For example, for ''background-position: 2cm 1cm'',
363+
the top left corner of the background image is placed
364+
2cm to the right and 1cm below
365+
the top left corner of the [=background positioning area=].
366+
367+
A <<percentage>> for the horizontal offset is relative to
368+
(<var>width of [=alignment container=]</var> - <var>width of [=alignment subject=]</var>).
369+
A <<percentage>> for the vertical offset is relative to
370+
(<var>height of [=alignment container=]</var> - <var>height of [=alignment subject=]</var>).
371+
372+
<div class=example>
373+
For example, with a value pair of ''0% 0%'',
374+
the upper left corner of the [=alignment subject=] is aligned with
375+
the upper left corner of the [=alignment container=]
376+
A value pair of ''100% 100%'' places
377+
the lower right corner of the [=alignment subject=]
378+
in the lower right corner of the [=alignment container=].
379+
With a value pair of ''75% 50%'',
380+
the point 75% across and 50% down the [=alignment subject=]
381+
is to be placed at the point 75% across and 50% down the [=alignment container=].
382+
<figure>
383+
<img src="images/bg-pos.png"
384+
alt="Diagram of image position within element"
385+
>
386+
<figcaption>
387+
Diagram of the meaning of ''background-position: 75% 50%''.
388+
</figcaption>
389+
</div>
390+
</div>
391+
392+
<dt><dfn>top</dfn>
393+
<dt><dfn>right</dfn>
394+
<dt><dfn>bottom</dfn>
395+
<dt><dfn>left</dfn>
396+
<dd>
397+
Offsets the top/left/right/bottom edges (respectively)
398+
of the [=alignment subject=] and [=alignment container=]
399+
by the specified amount (defaulting to ''0%'')
400+
in the corresponding axis.
401+
402+
<dt><dfn>y-start</dfn>
403+
<dt><dfn>y-end</dfn>
404+
<dt><dfn>x-start</dfn>
405+
<dt><dfn>x-end</dfn>
406+
<dd>
407+
Computes the same as the physical edge keyword
408+
corresponding to the [=start=]/[=end=] side
409+
in the [=y-axis|y/[=x-axis|x=] axis.
410+
411+
<dt><dfn>block-start</dfn>
412+
<dt><dfn>block-end</dfn>
413+
<dt><dfn>inline-start</dfn>
414+
<dt><dfn>inline-end</dfn>
415+
<dd>
416+
Computes the same as the physical edge keyword
417+
corresponding to the [=start=]/[=end=] side
418+
in the [=block axis|block=]/[=inline axis|inline=] axis.
419+
420+
<dt><dfn>center</dfn>
421+
<dd>
422+
Computes to a ''50%'' offset in the corresponding axis.
423+
</dl>
424+
425+
Unless otherwise specified, the [=flow-relative=] keywords are resolved
426+
according to the [=writing mode=] of the element on which the value is specified.
427+
428+
Note: The 'background-position' property also accepts a three-value syntax.
429+
This has been disallowed generically because it creates parsing ambiguities
430+
when combined with other length or percentage components in a property value.
431+
432+
ISSUE: Need to define how this syntax would expand to the longhands of 'background-position'
433+
if e.g. ''var()'' is used for some (or all) of the components.
434+
435+
<h4 id="position-parsing">
436+
Parsing <<position>></h4>
437+
438+
When specified in a grammar alongside other keywords, <<length>>s, or <<percentage>>s,
439+
<<position>> is <em>greedily</em> parsed;
440+
it consumes as many components as possible.
441+
442+
<div class=example>
443+
For example,
444+
'transform-origin' defines a 3D position
445+
as (effectively) ''<<position>> <<length>>?''.
446+
A value such as ''left 50px''
447+
will be parsed as a 2-value <<position>>,
448+
with an omitted z-component;
449+
on the other hand,
450+
a value such as ''top 50px''
451+
will be parsed as a single-value <<position>>
452+
followed by a <<length>>.
453+
</div>
454+
455+
<h4 id="position-serialization">
456+
Serializing <<position>></h4>
457+
458+
When serializing the [=specified value=] of a <<position>>:
459+
460+
<dl class=switch>
461+
<dt>If only one component is specified:
462+
<dd>
463+
* The implied <a value spec="css-backgrounds-3">center</a> keyword is added,
464+
and a 2-component value is serialized.
465+
466+
<dt>If two components are specified:
467+
<dd>
468+
* Keywords are serialized as keywords.
469+
* <<length-percentage>>s are serialized as <<length-percentage>>s.
470+
* Components are serialized horizontal first, then vertical.
471+
472+
<dt>If four components are specified:
473+
<dd>
474+
* Keywords and offsets are both serialized.
475+
* Components are serialized horizontal first, then vertical;
476+
alternatively [=block-axis=] first, then [=inline-axis=].
477+
</dl>
478+
479+
Note: <<position>> values are never serialized as a single value,
480+
even when a single value would produce the same behavior,
481+
to avoid causing parsing ambiguities in some grammars
482+
where a <<position>> is placed next to a <<length>>,
483+
such as 'transform-origin'.
484+
485+
The [=computed value=] of a <<position>>
486+
is serialized as a pair of <<length-percentage>>s
487+
representing offsets from the left and top edges, in that order.
488+
489+
<h4 id="combine-positions">
490+
Combination of <<position>></h4>
491+
492+
<a>Interpolation</a> of <<position>> is defined as
493+
the independent interpolation of each component (x, y)
494+
normalized as an offset from the top left corner
495+
as a <<length-percentage>>.
496+
497+
<a>Addition</a> of <<position>> is likewise defined as
498+
the independent <a>addition</a> each component (x, y)
499+
normalized as an offset from the top left corner
500+
as a <<length-percentage>>.
501+
502+
241503
<!-- Big Text: interp
242504

243505
████ █ █▌ █████▌ █████▌ ████▌ ████▌

0 commit comments

Comments
 (0)