Skip to content

Commit

Permalink
[css-anchor-position-1] Rename inset-area to position-area (#10592)
Browse files Browse the repository at this point in the history
* Update Overview.bs

* Rename inset-area-example.png to position-area-example.png
  • Loading branch information
nt1m authored Jul 18, 2024
1 parent 704c501 commit 99da0cb
Show file tree
Hide file tree
Showing 2 changed files with 54 additions and 55 deletions.
109 changes: 54 additions & 55 deletions css-anchor-position-1/Overview.bs
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ This can be done with the following CSS:
/* Align the tooltip's bottom to the top of the anchor;
this also defaults to horizontally center-aligning
the tooltip and the anchor (in horizontal writing modes). */
inset-area: block-start;
position-area: block-start;

/* Automatically swap if this overflows the window
so the tooltip's top aligns to the anchor's bottom
Expand Down Expand Up @@ -263,7 +263,7 @@ This property has no effect on [=implicit anchor elements=].
li .positioned {
position: absolute;
position-anchor: --list-item;
inset-area: inline-start;
position-area: inline-start;
}
</pre>

Expand Down Expand Up @@ -489,29 +489,28 @@ Anchor-Based Positioning {#positioning}
An [=absolutely-positioned=] element
can position itself relative to one or more [=anchor elements=] on the page.

The 'inset-area' function offers a convenient grid-based concept
The 'position-area' property offers a convenient grid-based concept
for positioning relative to the [=default anchor element=];
for more complex positioning or positioning relative to multiple elements,
the ''anchor()'' function can be used in the [=inset properties=]
to explicitly refer to edges of an [=anchor element=].

<!-- Big Text: inset-area
<!-- Big Text: position-area

████ ███ █████ █████ █████ █████ ███ █ █ ███ ████ █████ ███
█ █ █ █ █ █ █ █ █ █ ██ █ █ █ █ █ █ █ █
████ █ █ █████ █ █ █ █ █ █ █ █ ███ █████ ████ ████ █████
█ █ █ █ █ █ █ █ █ █ ██ █ █ █ █ █ █ █
█ ███ █████ █████ █ █████ ███ █ █ █ █ █ █ █████ █ █

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

The 'inset-area' Property {#inset-area}
The 'position-area' Property {#position-area}
---------------------------------------

<pre class=propdef>
Name: inset-area
Value: none | <<inset-area>>
Name: position-area
Value: none | <<position-area>>
Initial: none
Inherited: no
Applies to: positioned elements with a [=default anchor element=]
Expand All @@ -523,12 +522,12 @@ only need to worry about
the edges of the positioned element's [=containing block=],
and the edges of the [=default anchor element=].
These lines can be thought of as defining a 3x3 grid;
'inset-area' lets you easily set up the positioned element's [=inset properties=]
by specifying what area of this [=inset-area grid=] you want the positioned element to be in.
'position-area' lets you easily set up the positioned element's [=inset properties=]
by specifying what area of this [=position-area grid=] you want the positioned element to be in.
Its syntax is:

<pre class=prod>
<dfn>&lt;inset-area></dfn> = [
<dfn>&lt;position-area></dfn> = [
[ left | center | right | span-left | span-right
| x-start | x-end | span-x-start | span-x-end
| x-self-start | x-self-end | span-x-self-start | span-x-self-end
Expand Down Expand Up @@ -556,26 +555,26 @@ Its syntax is:
]
</pre>

<dl dfn-for=inset-area dfn-type=value>
<dl dfn-for=position-area dfn-type=value>
: <dfn>none</dfn>
:: The property has no effect.

: <dfn><<inset-area>></dfn>
: <dfn><<position-area>></dfn>
::
If the element does not have a [=default anchor element=],
or is not an [=absolutely-positioned=] element,
this value has no effect.

Otherwise, it has the following effects:

* The property selects a region of the [=inset-area grid=],
* The property selects a region of the [=position-area grid=],
and makes that the element's [=containing block=].
See [[#resolving-spans]] for details.

Note: This means that the [=inset properties=] specify offsets from the inset-area,
Note: This means that the [=inset properties=] specify offsets from the position-area,
and some property values,
like ''max-height: 100%'',
will be relative to the inset-area as well.
will be relative to the position-area as well.

* The ''align-self/normal'' value for the [=self-alignment properties=]
behaves as either ''align-self/start'', ''align-self/end'',
Expand All @@ -591,7 +590,7 @@ Its syntax is:
</dl>

<div class=note>
If the element overflows its 'inset-area' (and 'inset') -modified [=containing block=],
If the element overflows its 'position-area' (and 'inset') -modified [=containing block=],
but would still fit within its [=original containing block=],
by default it will "shift" to stay within its [=original containing block=],
even if that violates its normal alignment.
Expand All @@ -603,7 +602,7 @@ Its syntax is:
even when their [=containing block=]
ends up smaller than anticipated.

For example, an ''inset-area: bottom span-right'' value
For example, an ''position-area: bottom span-right'' value
lets the positioned element stretch
from its anchors left edge
to its containing block's right edge,
Expand All @@ -615,9 +614,9 @@ Its syntax is:


<h4 id=resolving-spans>
Resolving <<inset-area>>s</h4>
Resolving <<position-area>>s</h4>

The <dfn export>inset-area grid</dfn> is a 3x3 grid,
The <dfn export>position-area grid</dfn> is a 3x3 grid,
composed of four grid lines in each axis.
In order:

Expand All @@ -630,11 +629,11 @@ In order:
or the ''anchor-start()'' edge fo the [=default anchor element=]
if that is more [=end=]-ward.

An <<inset-area>> selects a region of this grid
An <<position-area>> selects a region of this grid
by specifying the rows and columns the region occupies,
with each of the two keywords specifying one of them:

<dl dfn-type=value dfn-for="inset-area, <inset-area>">
<dl dfn-type=value dfn-for="position-area, <position-area>">
: <dfn>start</dfn>, <dfn>end</dfn>, <dfn>self-start</dfn>, <dfn>self-end</dfn>
: <dfn>top</dfn>, <dfn>bottom</dfn>, <dfn>left</dfn>, <dfn>right</dfn>
: <dfn>y-start</dfn>, <dfn>y-end</dfn>, <dfn>y-self-start</dfn>, <dfn>y-self-end</dfn>
Expand All @@ -647,13 +646,13 @@ with each of the two keywords specifying one of them:

Like in ''anchor()'',
the plain logical keywords
(''inset-area/start'', ''inset-area/end'', etc)
(''position-area/start'', ''position-area/end'', etc)
refer to the writing mode of the element's [=containing block=].
The ''inset-area/x-start''/etc determine their direction in the same way,
The ''position-area/x-start''/etc determine their direction in the same way,
but in the specified physical axis.

The "self" logical keywords
(''inset-area/self-start'', ''inset-area/x-self-end'', etc)
(''position-area/self-start'', ''position-area/x-self-end'', etc)
are identical,
but refer to the element's own writing mode.

Expand All @@ -678,27 +677,27 @@ with each of the two keywords specifying one of them:
</dl>

Some keywords are ambiguous about what axis they refer to:
''inset-area/center'', ''inset-area/span-all'',
and the ''inset-area/start''/etc keywords that don't specify the block or inline axis explicitly.
''position-area/center'', ''position-area/span-all'',
and the ''position-area/start''/etc keywords that don't specify the block or inline axis explicitly.
If the other keyword is unambiguous about its axis,
then the ambiguous keyword is referring to the opposite axis.
(For example, in ''block-start center'',
the ''inset-area/center'' keyword is referring to the inline axis.)
the ''position-area/center'' keyword is referring to the inline axis.)
If both keywords are ambiguous, however,
then the first refers to the block axis of the element's [=containing block=],
and the second to the inline axis.
(For example, ''span-all start'' is equivalent to ''span-all inline-start''.)

If only a single keyword is given,
it behaves as if the second keyword is ''inset-area/span-all''
it behaves as if the second keyword is ''position-area/span-all''
if the given keyword is unambigous about its axis;
otherwise, it behaves as if the given keyword was repeated.
(For example, ''inset-area/top'' is equivalent to ''top span-all'',
but ''inset-area/center'' is equivalent to ''center center''.)
(For example, ''position-area/top'' is equivalent to ''top span-all'',
but ''position-area/center'' is equivalent to ''center center''.)

<hr>

The <<inset-area>> also implies a default [=self-alignment=],
The <<position-area>> also implies a default [=self-alignment=],
which will be used if the [=self-alignment property=] on the element
is ''align-self/normal'':

Expand All @@ -721,16 +720,16 @@ is ''align-self/normal'':
(making the element's end side flush with the end side of the "start+center" region).

<figure>
<img src="images/inset-area-example.png" width=400>
<img src="images/position-area-example.png" width=400>
<figcaption>
An example of ''inset-area: span-x-start top'' positioning.
An example of ''position-area: span-x-start top'' positioning.
</figcaption>
</figure>
</div>

Note: When the [=default anchor element=]
is partially or completely outside of the pre-modified [=containing block=],
some of the [=inset-area grid's=] rows or columns can be zero-sized.
some of the [=position-area grid's=] rows or columns can be zero-sized.


<!-- Big Text: anchor()
Expand Down Expand Up @@ -959,7 +958,7 @@ or does not have a [=default anchor element=],
this value behaves as ''<self-position>/center''
and has no additional effect on how [=inset properties=] resolve.

Note: Similar to 'inset-area',
Note: Similar to 'position-area',
when using ''anchor-center'',
if the anchor is too close to the edge of the element's
[=original containing block=],
Expand Down Expand Up @@ -1387,7 +1386,7 @@ Giving Fallback Options: the 'position-try-fallbacks' property {#position-try-fa

<pre class=propdef>
Name: position-try-fallbacks
Value: none | [ [<<dashed-ident>> || <<try-tactic>>] | <<'inset-area'>> ]#
Value: none | [ [<<dashed-ident>> || <<try-tactic>>] | <<'position-area'>> ]#
Initial: none
Inherited: no
Applies to: [=absolutely-positioned=] elements
Expand Down Expand Up @@ -1473,10 +1472,10 @@ Values have the following meanings:

Otherwise, does nothing.

: <dfn><<'inset-area'>></dfn>
: <dfn><<'position-area'>></dfn>
::
Automatically creates a [=position option=]
composed solely of an 'inset-area' property
composed solely of an 'position-area' property
with the given value.
</dl>

Expand Down Expand Up @@ -1572,16 +1571,16 @@ Values have the following meanings:
as it's a <<baseline-position>>
rather than a <<self-position>>.
</div>
* For 'inset-area',
* For 'position-area',
change the value
so that the selected rows/columns of the [=inset-area grid=]
so that the selected rows/columns of the [=position-area grid=]
maintain the same relative relationship to the new direction
that they had to the old.

<div class=example>
For example, if "top" and "left" are being swapped,
then ''inset-area: left span-bottom''
will become ''inset-area: top span-right''.
then ''position-area: left span-bottom''
will become ''position-area: top span-right''.
</div>

5. Return |styles|.
Expand Down Expand Up @@ -1791,7 +1790,7 @@ the following [=properties=]:
* [=sizing properties=]
* [=self-alignment properties=]
* 'position-anchor'
* 'inset-area'
* 'position-area'

It is invalid to use ''!important'' on the properties in the <<declaration-list>>.
Doing so causes the property it is used on to become invalid,
Expand Down Expand Up @@ -1896,14 +1895,14 @@ even tho they depend on layout and [=used values=].
with any non-''top/auto'' [=inset property|inset=] values
shifted by the [=snapshotted scroll offset=].

If |el| has a non-''inset-area/none'' 'inset-area' value,
If |el| has a non-''position-area/none'' 'position-area' value,
then for the purpose of the preceding calculation,
shift the value of ''anchor(start)'' and ''anchor(end)''
in the [=inset-area grid=]
in the [=position-area grid=]
by the [=snapshotted scroll offset=] as well.

Note: In other words, ''top: anchor(bottom); bottom: auto;''
and ''inset-area: bottom;''
and ''position-area: bottom;''
should result in the same IMCB
for the purpose of these overflow calculations.

Expand Down Expand Up @@ -2259,8 +2258,8 @@ interface CSSPositionTryDescriptors : CSSStyleDeclaration {
attribute CSSOMString justify-self;
attribute CSSOMString positionAnchor;
attribute CSSOMString position-anchor;
attribute CSSOMString insetArea;
attribute CSSOMString inset-area;
attribute CSSOMString positionArea;
attribute CSSOMString position-area;
};
</xmp>

Expand Down

0 comments on commit 99da0cb

Please sign in to comment.