Overview.bs

<pre class='metadata'>
Title: CSS Box Sizing Module Level 4
Shortname: css-sizing
Level: 4
Status: ED
Work Status: Exploring
Group: csswg
ED: https://drafts.csswg.org/css-sizing-4/
TR: https://www.w3.org/TR/css-sizing-4/
Issue Tracking: CSSWG GitHub https://github.com/w3c/csswg-drafts/issues
Previous Version: https://www.w3.org/TR/2020/WD-css-sizing-4-20201020/
Editor: Tab Atkins, Google, http://xanthir.com/contact/, w3cid 42199
Editor: Elika J. Etemad / fantasai, Invited Expert, http://fantasai.inkedblade.net/contact, w3cid 35400
Editor: Jen Simmons, Mozilla, http://jensimmons.com/
Abstract: This module extends the CSS sizing properties with keywords that represent content-based "intrinsic" sizes and context-based "extrinsic" sizes, allowing CSS to more easily describe boxes that fit their content or fit into a particular layout context. This is a delta spec over CSS Sizing Level 3.
Ignored Terms: block-level box
</pre>

<pre class='link-defaults'>
spec:css-display-3; type:dfn; text:box
spec:css-align-3; type:property; text:column-gap
spec:css2; type: property
	text: min-width
	text: min-height
	text: max-width
	text: max-height
spec:css-align-3; type:value; text:stretch
</pre>


<!-- Notes on stuff to do... [copy/pasted from etherpad, probably out-of-date, evaluate later]
  Swap definition of preferred size in for max-content.
  Define current max-content as super-max-content.
  Mark an isssue about whether it's a necessary concept;
  I'm unsure, but I think it will show up in orthogonal flow sizing.
-->

<h2 id="intro">
Introduction</h2>

	ISSUE: This is a diff spec over <a href="https://www.w3.org/TR/css-sizing-3/">CSS Sizing Level 3</a>.
	It is currently an Exploratory Working Draft:
	if you are implementing anything, please use Level 3 as a reference.
	We will merge the Level 3 text into this draft once it reaches CR.

<h3 id="placement">
Module interactions</h3>

	<p>This module extends the 'width', 'height', 'min-width', 'min-height', 'max-width', 'max-height', and 'column-width'
	features defined in [[!CSS2]] chapter 10 and in [[!CSS3COL]]

<h3 id="values">
Value Definitions</h3>

	This specification follows the <a href="https://www.w3.org/TR/CSS2/about.html#property-defs">CSS property definition conventions</a> from [[!CSS2]]
	using the <a href="https://www.w3.org/TR/css-values-3/#value-defs">value definition syntax</a> from [[!CSS-VALUES-3]].
	Value types not defined in this specification are defined in CSS Values &amp; Units [[!CSS-VALUES-3]].
	Combination with other CSS modules may expand the definitions of these value types.

	In addition to the property-specific values listed in their definitions,
	all properties defined in this specification
	also accept the <a>CSS-wide keywords</a> as their property value.
	For readability they have not been repeated explicitly.

<!--
████████ ████████ ████████  ██     ██  ██████
   ██    ██       ██     ██ ███   ███ ██    ██
   ██    ██       ██     ██ ████ ████ ██
   ██    ██████   ████████  ██ ███ ██  ██████
   ██    ██       ██   ██   ██     ██       ██
   ██    ██       ██    ██  ██     ██ ██    ██
   ██    ████████ ██     ██ ██     ██  ██████
-->

<h2 id="terms">
Terminology</h2>

Issue: [[css-sizing-3#terms]]

<!--
████████  ████████   ███████  ████████  ████████  ████████ ████████  ██████
██     ██ ██     ██ ██     ██ ██     ██ ██     ██ ██       ██       ██    ██
██     ██ ██     ██ ██     ██ ██     ██ ██     ██ ██       ██       ██
████████  ████████  ██     ██ ████████  ██     ██ ██████   ██████    ██████
██        ██   ██   ██     ██ ██        ██     ██ ██       ██             ██
██        ██    ██  ██     ██ ██        ██     ██ ██       ██       ██    ██
██        ██     ██  ███████  ██        ████████  ████████ ██        ██████
-->

<h2 id="specifying-sizes" oldids='size-keywords'>
Specifying Box Sizes</h2>

ISSUE: [[css-sizing-3#specifying-sizes]]

<h3 id="sizing-properties">
Sizing Properties</h3>

ISSUE(820): Add shorthands.

<h3 id="sizing-values" oldids='width-height-keywords'>
New Sizing Values: the ''stretch'', ''fit-content'', and ''contain'' keywords</h3>

	<pre class="propdef partial">
	Name: width, height, inline-size, block-size, min-width, min-height, min-inline-size, min-block-size, max-width, max-height, max-inline-size, max-block-size
	New Values: stretch | fit-content | contain
	</pre>

	<dl dfn-type=value dfn-for="width, height, inline-size, block-size, min-width, min-height, min-inline-size, min-block-size, max-width, max-height, max-inline-size, max-block-size">
		<dt><dfn>stretch</dfn>
		<dd>
			Applies [=stretch-fit sizing=],
			attempting to match the size of the box’s [=margin box=] to the size of its [=containing block=].
			See [[#stretch-fit-sizing]].

		<dt><dfn>fit-content</dfn>
		<dd>
			Essentially ''fit-content(stretch)''
			i.e. min(''width/max-content'', max(''width/min-content'', ''width/stretch'')).

		<dt><dfn>contain</dfn>
		<dd>
			If the box has a [=preferred aspect ratio=],
			applies [=contain-fit sizing=],
			attempting to fit into the box’s constraints
			while maintaining its [=preferred aspect ratio=] insofar as possible.
			See [[#contain-fit-sizing]].

			If the box has no [=preferred aspect ratio=],
			applies [=stretch-fit sizing=].
	</dl>

<!--
   ███     ██████  ████████  ████████  ██████  ████████         ████████     ███    ████████ ████  ███████
  ██ ██   ██    ██ ██     ██ ██       ██    ██    ██            ██     ██   ██ ██      ██     ██  ██     ██
 ██   ██  ██       ██     ██ ██       ██          ██            ██     ██  ██   ██     ██     ██  ██     ██
██     ██  ██████  ████████  ██████   ██          ██    ███████ ████████  ██     ██    ██     ██  ██     ██
█████████       ██ ██        ██       ██          ██            ██   ██   █████████    ██     ██  ██     ██
██     ██ ██    ██ ██        ██       ██    ██    ██            ██    ██  ██     ██    ██     ██  ██     ██
██     ██  ██████  ██        ████████  ██████     ██            ██     ██ ██     ██    ██    ████  ███████
-->

<h2 id="ratios">
Aspect Ratios</h2>

	Images often have an [=intrinsic aspect ratio=],
	which the CSS layout algorithms attempt to preserve
	as they resize the element.

	The 'aspect-ratio' property allows specifying this behavior
	for non-replaced elements,
	and for altering the effective aspect ratio of replaced elements.

<h3 id="aspect-ratio">
Preferred Aspect Ratios: the 'aspect-ratio' property</h3>

	<pre class="propdef">
	Name: aspect-ratio
	Value: auto || <<ratio>>
	Initial: auto
	Inherited: no
	Applies to: all elements except <a>inline boxes</a> and internal ruby or table boxes
	Computed value: specified keyword or a pair of numbers
	</pre>

	This property sets a <dfn export>preferred aspect ratio</dfn> for the box,
	which will be used in the calculation of ''height/auto'' sizes
	and some other layout functions.

	<dl dfn-for="aspect-ratio" dfn-type="value">
		<dt><dfn>auto</dfn>
		<dd>
			<a>Replaced elements</a> with an <a>intrinsic aspect ratio</a>
			use that aspect ratio;
			otherwise the box has no <a>preferred aspect ratio</a>.
			Size calculations involving the aspect ratio
			work with the <a>content box</a> dimensions always.

		<dt><dfn><<ratio>></dfn>
		<dd>
			The box’s <a>preferred aspect ratio</a> is the specified ratio
			of ''<var>width</var> / <var>height</var>''.
			Size calculations involving the aspect ratio
			work with the dimensions of the box specified by 'box-sizing'.

			If the <<ratio>> is [=degenerate ratio|degenerate=],
			the property instead behaves as ''aspect-ratio/auto''.

		<dt><dfn>auto && <<ratio>></dfn>
		<dd>
			If both ''auto'' and a <<ratio>> are specified together,
			the [=preferred aspect ratio=] is the specified ratio
			of ''<var>width</var> / <var>height</var>''
			unless it is a [=replaced element=] with an [=intrinsic aspect ratio=],
			in which case that aspect ratio is used instead.
			In all cases, size calculations involving the aspect ratio
			work with the [=content box=] dimensions always.

			If the <<ratio>> is [=degenerate ratio|degenerate=],
			the property instead behaves as ''aspect-ratio/auto''.
	</dl>

	Note: Having a [=preferred aspect ratio=] does not make a box into a [=replaced element=];
	layout rules specific to [=replaced elements=]
	do not generally apply to [=non-replaced=] boxes with a [=preferred aspect ratio=].
	For example, a [=non-replaced=] [=absolutely-positioned=] box
	treats ''justify-self: normal'' as ''justify-self/stretch'', not as ''justify-self/start''
	([[CSS-ALIGN-3#justify-abspos]]),
	even if it has a [=preferred aspect ratio=]

	ISSUE: CSS2.1 does not cleanly differentiate between
	replaced elements vs. elements with an aspect ratio;
	need to figure out specific cases that are unclear and define them,
	either in the appropriate Level 3 spec or here.

	<div class="example">
		This example sets each item in the grid to render as a square,
		determining the number of items and their widths by the available space.

		<xmp highlight="html">
		  <ul>
		    <li>…
		    <li>…
		    <li>…
		    <li>…
		  </ul>
		</xmp>
		<pre highlight="css">
			ul {
				display: grid;
				grid-template-columns: repeat(auto-fill, minmax(12em, 1fr));
			}
			li {
				aspect-ratio: 1/1;
				overflow: auto;
			}
		</pre>
	</div>

	<div class="example">
		This example uses the <{iframe}> element’s
		<code>width</code> and <code>height</code> attributes
		to set the 'aspect-ratio' property,
		giving the iframe an aspect ratio to use for sizing
		so that it behaves exactly like an image with that aspect ratio.
		<!-- https://twitter.com/ausi/status/1053013616239288320 -->
		<pre highlight="html">
			&lt;iframe
			  src="https://www.youtube.com/embed/0Gr1XSyxZy0"
			  width=560
			  height=315>
		</pre>
		<pre highlight="css">
			@supports (aspect-ratio: attr(width number) / 1) {
			  iframe {
			    aspect-ratio: attr(width number) / attr(height number);
			    width: 100%;
			    height: auto;
			  }
			}
		</pre>
	</div>

	If a replaced element's only [=intrinsic dimension=]
	is an intrinsic width or an intrinsic height,
	giving it a [=preferred aspect ratio=]
	also gives it an intrinsic height or width,
	whichever was missing,
	by transferring the existing size
	through the [=preferred aspect ratio=].

<h3 id="aspect-ratio-automatic">
Effects of Preferred Aspect Ratio on Automatic Sizes</h3>

	When a box has a [=preferred aspect ratio=],
	its <a>automatic sizes</a>
	are calculated the same as for
	a <a>replaced element</a> with an <a>intrinsic aspect ratio</a>
	and no <a>intrinsic dimension</a> in that axis,
	see e.g. <a href="https://www.w3.org/TR/CSS2/visudet.html">CSS2 &sect;&#x202F;10</a>
	and <a href="https://www.w3.org/TR/css-flexbox-1/#algo-main-item">CSS Flexible Box Model Level 1 &sect;&#x202F;9.2</a>.
	The axis in which the <a>preferred size</a> calculation
	depends on this aspect ratio
	is called the <dfn export>ratio-dependent axis</dfn>,
	and the resulting size is <a>definite</a>
	if its input sizes are also <a>definite</a>.
	The opposite axis (on which the [=ratio-dependent axis=] size depends)
	is the <dfn export>ratio-determining axis</dfn>.

	Note: A [=preferred aspect ratio=]
	only ever has an effect if at least one of the box's sizes
	is [=automatic size|automatic=].
	If neither 'width' nor 'height' is an [=automatic size=],
	it can have no effect on its [=preferred sizes=].

	Issue: When we move all the sizing information here,
	rather than crowbar-ing our way into 2.1,
	then the core principle here is just:
	the resolved [=preferred size=] in the ratio-determining axis
	(before applying min/max)
	gets transferred thru the ratio.
	Min/max constraints get transferred afterwards,
	and then applied to each axis independently without regards to aspect-ratio.

<h4 id="aspect-ratio-margin-collapse">
Margin-collapsing</h4>

	For the purpose of margin collapsing ([[css2/box#collapsing-margins]]),
	if the [=block axis=] is the [=ratio-dependent axis=],
	it is not considered to have a [=computed value|computed=] 'block-size' of ''height/auto''.

<h3 id="aspect-ratio-minimum">
Automatic Content-based Minimum Sizes</h3>

	In order to avoid unintentional overflow,
	the <a>automatic minimum size</a> in the <a>ratio-dependent axis</a>
	of a box with a <a>preferred aspect ratio</a>
	that is neither a <a>replaced element</a> nor a <a>scroll container</a>
	is its <a>min-content size</a>
	capped by its <a>maximum size</a>.

	<div class="example">
		In the following example,
		the box is as wide as the container (as usual),
		and its height is as tall as needed to contain its content
		but at least as tall as it is wide.

		<pre highlight=css>
		  div {
		    aspect-ratio: 1/1;
		    /* 'width' and 'height' both default to 'auto' */
		  }
		</pre>

		<pre class="figure">
		+----------+  +----------+  +----------+
		| ~~~~~~~~ |  | ~~~~~~~~ |  | ~~~~~~~~ |
		| ~~~~~~~~ |  | ~~~~~~~~ |  | ~~~~~~~~ |
		| ~~~~~~~  |  | ~~~~~~~~ |  | ~~~~~~~~ |
		|          |  | ~~~      |  | ~~~~~~~~ |
		+----------+  +----------+  | ~~~~~~~~ |
		                            | ~~~~~~   |
		                            +----------+
		</pre>

		When ''overflow: auto'' is specified, however,
		even the box with excess content maintains the 1:1 aspect ratio
		(and handles overflow by becoming scrollable instead, as usual).

		<pre highlight=css>
		  div {
		    overflow: auto;
		    aspect-ratio: 1/1;
		  }
		</pre>

		<pre class="figure">
		+----------+  +----------+  +----------+
		| ~~~~~~~~ |  | ~~~~~~~~ |  | ~~~~~~~~^|
		| ~~~~~~~~ |  | ~~~~~~~~ |  | ~~~~~~~~ |
		| ~~~~~~~  |  | ~~~~~~~~ |  | ~~~~~~~~ |
		|          |  | ~~~      |  | ~~~~~~~~v|
		+----------+  +----------+  +----------+
		</pre>

		Overriding the 'min-height' property also maintains the 1:1 aspect ratio,
		but will result in content overflowing the box
		if it is not otherwise handled.

		<pre highlight=css>
		  div {
		    aspect-ratio: 1/1;
		    min-height: 0;
		  }
		</pre>

		<pre class="figure">
		+----------+  +----------+  +----------+
		| ~~~~~~~~ |  | ~~~~~~~~ |  | ~~~~~~~~ |
		| ~~~~~~~~ |  | ~~~~~~~~ |  | ~~~~~~~~ |
		| ~~~~~~~  |  | ~~~~~~~~ |  | ~~~~~~~~ |
		|          |  | ~~~      |  | ~~~~~~~~ |
		+----------+  +----------+  +-~~~~~~~~-+
		&nbsp;                             ~~~~~~   &nbsp;
		</pre>
	</div>

	<div class="example">
		This automatic minimum operates in both axes.
		Consider this example:

		<pre highlight=html>
			&lt;div style="height: 100px; aspect-ratio: 1/1;">
				&lt;span style="display: inline-block; width: 50px;">&lt;/span>
				&lt;span style="display: inline-block; width: 150px;">&lt;/span>
			&lt;/div>
		</pre>

		The 'width' of the container, being ''width/auto'',
		resolves through the aspect ratio to 100px.
		However, its 'min-width', being ''min-width/auto'',
		resolves to 150px.
		The resulting width of the container is thus 150px.
		To ignore the contents when sizing the container,
		''min-width: 0'' can be specified.
	</div>

<h3 id="aspect-ratio-size-transfers">
Min/Max Size Transfers</h3>

	Sizing constraints in either axis
	(the <var>origin</var> axis)
	are transferred through the [=preferred aspect ratio=]
	to the other axis (the <var>destination</var> axis)
	as follows:

	* First, any [=definite=] [=minimum size=] is converted and transferred
		from the <var>origin</var> to <var>destination</var> axis.
		This transferred minimum is capped
		by any [=definite=] [=preferred size|preferred=] or [=maximum size=]
		in the <var>destination</var> axis.
	* Then, any [=definite=] [=maximum size=] is converted and transferred
		from the <var>origin</var> to <var>destination</var>.
		This transferred maximum is floored
		by any [=definite=] [=preferred size|preferred=] or [=minimum size=]
		in the <var>destination</var> axis
		as well as by the transferred minimum, if any.

	Note: The basic principle is that sizing constraints
	transfer through the aspect-ratio to the other side
	to preserve the aspect ratio to the extent that they can
	without violating any sizes specified explictly on that affected axis.
	<!-- This is the principle that drove the contents of the table in CSS2 Section 10.4. -->

	<div class="example">
		In the following example:

		<pre highlight=html>
			&lt;div id=container style="height: 100px; float: left;">
				&lt;div id=item style="height: 100%; aspect-ratio: 1/1;">content&lt;/div>
			&lt;/div>
		</pre>

		Since the height of the <code>#item</code> is a percentage that resolves against a definite container,
		the width of the item resolves to 100px for both its intrinsic size contributions as well as for final layout,
		so the container also sizes to a width of 100px.

		<pre highlight=html>
			&lt;div id=container style="height: auto; float: left;">
				&lt;div id=item style="height: 100%; aspect-ratio: 1/1;">content&lt;/div>
			&lt;/div>
		</pre>

		In this next example,
		the percentage height of the item cannot be resolved and [=behaves as auto=]
		(see [[CSS2/visudet#the-height-property]]).
		Since both axes now have an [=automatic size=],
		the height becomes the [=ratio-dependent axis=].
		Calculating the [=intrinsic size contributions=] of the box
		produces a width derived from its content,
		and a height calculated from that width and the aspect ratio,
		yielding a square box (and a container) sized
		to the width of the word “content”.
	</div>


<!--
████ ██    ██ ████████ ████████  ████ ██    ██  ██████  ████  ██████
 ██  ███   ██    ██    ██     ██  ██  ███   ██ ██    ██  ██  ██    ██
 ██  ████  ██    ██    ██     ██  ██  ████  ██ ██        ██  ██
 ██  ██ ██ ██    ██    ████████   ██  ██ ██ ██  ██████   ██  ██
 ██  ██  ████    ██    ██   ██    ██  ██  ████       ██  ██  ██
 ██  ██   ███    ██    ██    ██   ██  ██   ███ ██    ██  ██  ██    ██
████ ██    ██    ██    ██     ██ ████ ██    ██  ██████  ████  ██████
-->

<h2 id='intrinsic'>
Intrinsic Size Determination</h2>

<h3 id="intrinsic-contribution">
Intrinsic Sizes</h3>

	ISSUE: [[css-sizing-3#intrinsic-sizes]]

<h3 id='intrinsic-size-override'>
Overriding Contained Intrinsic Sizes: the 'contain-intrinsic-size' property</h3>

	<pre class="propdef">
	Name: contain-intrinsic-size
	Value: none | <<length>>{1,2}
	Initial: none
	Inherited: no
	Applies to: elements with [=size containment=]
	Computed value: as specified, with <<length>> values computed
	Percentages: n/a
	Animation type: by computed value type
	</pre>

	This property allows elements with [=size containment=] to specify
	an <dfn export>explicit intrinsic inner size</dfn>,
	causing the box to size as if its in-flow content
	totals to a width and height
	matching the specified [=explicit intrinsic inner size=]
	(rather than sizing as if it were empty).

	Note: This is not always equivalent
	to laying out as if the element had one child of the specified [=explicit intrinsic inner size=].

	Note: An element with [=size containment=] is laid out as if it had no contents [[!CSS-CONTAIN-1]],
	which in many cases this will cause the element to collapse to zero inner height.
	This can be corrected with an explicit 'height' chosen to show the expected contents,
	but that can have unintended effects in some layout systems,
	such as Flex and Grid Layout,
	which treat an explicit 'height' as a stronger command
	than an implicit content-based height.
	The element thus might lay out substantially differently than it would have
	were it simply filled with content up to that height.
	Providing an [=explicit intrinsic inner size=] for the element
	preserves the performance benefits of ignoring its contents for layout
	while still allowing it to size as if it had content.

	Values are defined as:

	<dl dfn-type=value dfn-for="contain-intrinsic-size">
		: <dfn>none</dfn>
		::
			Does not specify an [=explicit intrinsic inner size=]
			for elements with [=size containment=].

		: <dfn><<length>>{2}</dfn>
		::
			If the element has [=size containment=],
			specifies an [=explicit intrinsic inner size=].
			The first <<length>> provides the inner width of the element,
			the second provides the inner height.
			If the second <<length>> is omitted,
			it defaults to the same value as the first.
	</dl>

<h4 id='cis-scrollbars'>
Interaction With ''overflow: auto''</h4>

	The 'contain-intrinsic-size' property provides an estimate
	of how large the author expects the content of an element to be,
	but this estimate is not actual content
	and does not represent anything that needs to be shown to the user.
	Therefore, an element with ''overflow: auto'' must not generate scrollbars
	as a consequence of 'contain-intrinsic-size'.

	However, if 'contain-intrinsic-size' indicates a size large enough
	that the element would generate scrollbars
	if it contained actual content of that size,
	then the element must be <em>sized</em> as if it generated those scrollbar(s)
	in accordance with such hypothetical content.

	<div class='example'>
		In the following example code:

		<pre highlight=css>
		div {
			width: max-content;
			contain-intrinsic-size: 100px 100px;
			overflow: auto;
		}
		</pre>

		The element ends up being ''100px'' wide and ''100px'' tall:
		'contain-intrinsic-size' provides the max-content width,
		and also the height.

		If the element then ended up with content that was ''150px'' tall,
		it would show a vertical scrollbar;
		if the scrollbar is not overlay,
		it will take up some of that ''100px'' width,
		leaving a smaller amount
		(roughly ''84px'', typically)
		for the content to flow into.
		(See [[css-overflow-3#scrollbar-layout]].)

		Even though there's now less than ''100px'' of horizontal space available for the content,
		it will not generate a horizontal scrollbar just because 'contain-intrinsic-size' indicates a ''100px'' width;
		that would only happen if the actual content
		had something unbreakable
		and wider than the remaining space.
	</div>

	<div class=example>
		In contrast, in the following example code:

		<pre highlight=css>
		div {
			width: max-content;
			contain-intrinsic-size: 100px 100px;
			height: 50px;
			overflow: auto;
		}
		</pre>

		The element has a fixed ''50px'' height,
		but 'contain-intrinsic-size' indicates a ''100px'' “estimated content height”.
		The element thus assumes that it will need a vertical scrollbar
		when it's filled with actual content,
		resulting in a max-content width a little more than ''100px''
		(roughly ''116px'', typically),
		to accommodate the estimated ''100px'' of max-content width from 'contain-intrinsic-size',
		and as well as the vertical scrollbar width (roughly ''16px'', typically).

		However, even though the element reserves space on the assumption of needing a scrollbar,
		it will not actually generate one
		unless the actual content overflows:
		if it ends up containing content that's less than 50px tall,
		no vertical scrollbar will be generated at all,
		but the element will still be ''116px'' wide.
	</div>


<!--
 ██████   ███████  ██    ██ ████████ ████████  ████ ████████   ██████
██    ██ ██     ██ ███   ██    ██    ██     ██  ██  ██     ██ ██    ██
██       ██     ██ ████  ██    ██    ██     ██  ██  ██     ██ ██
██       ██     ██ ██ ██ ██    ██    ████████   ██  ████████   ██████
██       ██     ██ ██  ████    ██    ██   ██    ██  ██     ██       ██
██    ██ ██     ██ ██   ███    ██    ██    ██   ██  ██     ██ ██    ██
 ██████   ███████  ██    ██    ██    ██     ██ ████ ████████   ██████
-->

<h3 id="intrinsic-contribution">
Intrinsic Size Contributions</h3>

	ISSUE: [[css-sizing-3#intrinsic-contribution]]


<!--
████████ ██     ██ ████████ ████████  ████ ██    ██  ██████  ████  ██████
██        ██   ██     ██    ██     ██  ██  ███   ██ ██    ██  ██  ██    ██
██         ██ ██      ██    ██     ██  ██  ████  ██ ██        ██  ██
██████      ███       ██    ████████   ██  ██ ██ ██  ██████   ██  ██
██         ██ ██      ██    ██   ██    ██  ██  ████       ██  ██  ██
██        ██   ██     ██    ██    ██   ██  ██   ███ ██    ██  ██  ██    ██
████████ ██     ██    ██    ██     ██ ████ ██    ██  ██████  ████  ██████
-->

<h2 id='extrinsic'>
Extrinsic Size Determination</h2>

	ISSUE: [[css-sizing-3#extrinsic]]

<h3 id="stretch-fit-sizing">
Stretch-fit Sizing: filling the containing block</h3>

	Stretch-fit sizing tries to set the box’s used size
	to the length necessary
	to make its outer size as close to filling the [=containing block=] as possible
	while still respecting the constraints imposed by min-height/min-width/max-height/max-width.

	Formally, its behavior is the same as specifying an [=automatic size=]
	together with a [=self-alignment property=] value of ''width/stretch''
	(in the relevant axis),
	except that the resulting box,
	which can end up not exactly fitting its [=alignment container=],
	can be subsequently aligned by its actual [=self-alignment property=] value.

	Additionally,
	in [=formatting contexts=] and axes in which the relevant [=self-alignment property=] does not apply
	(such as the block axis in Block Layout, or the main axis in Flex Layout),
	in cases where a percentage size in that axis would resolve to a definite value,
	a [=stretch-fit size=]
	causes the box to attempt to fill its containing block--
	behaving as ''100%''
	but applying the resulting size to its margin box
	instead of the box indicated by 'box-sizing'.
	For this purpose, ''margin/auto'' margins are treated as zero,
	and furthermore, for [=block-level boxes=] in particular,
	if its block-start/block-end [=margin=]
	would be adjoining to its parent's block-start/block-end [=margin=]
	if its parent’s [=sizing properties=] all had their [=initial values=],
	then its block-start/block-end [=margin=] is treated as zero.

	Note: Consequently, if neither ''align-self/stretch'' alignment applies
	nor percentage sizing can resolve,
	then the box will resolve to its [=automatic size=].

	<div class="example">
		For example, given the following HTML representing two [=block boxes=]:
		<pre class=html>
		  &lt;div class="outer">
		    &lt;div class="inner">&lt;/div>
		  &lt;/div>
		</pre>

		In the following case,
		the [=outer height=] of the inner box
		will exactly match the height of the outer box (200px),
		but its [=inner height=] will be 20px less, to account for its margins.

		<pre>
		  .outer { height: 200px; border: solid; }
		  .inner { height: stretch; margin: 10px; }
		</pre>

		In the following case,
		the height of the inner box
		will exactly match the height of the outer box (200px).
		The top margins will collapse,
		but the bottom margins do not collapse
		(because the bottom margin of a box is not adjoining
		to the bottom margin of a parent with a non-''height/auto'' height,
		see [[CSS2/box#collapsing-margins]]),
		and therefore the inner box’s bottom margin will be truncated.

		<pre>
		  .outer { height: 200px; margin: 0; }
		  .inner { height: stretch; margin: 10px; }
		</pre>
	</div>

	<div class="example">
		Similarly, ''width: stretch'' causes the box to fill its container,
		being 20px narrower than the width of "some more text"
		(due to the 10px margin):

		<pre class=html>
		  &lt;div class="outer">
		    &lt;div class="inner">text&lt;/div>
		  &lt;/div>
		  some more text
		</pre>

		<pre>
			.outer { float: left; margin: 0; }
			.inner { width: stretch; margin: 10px; }
		</pre>
	</div>

	<div class="example">
		On the other hand,
		in this example the container's height is indefinite,
		which would cause a percentage height on the child to [=behave as auto=],
		so ''height: stretch'' [=behaves as auto=] as well.

		<pre>
		  .outer { height: auto; margin: 0; }
		  .inner { height: stretch; margin: 10px; }
		</pre>
	</div>


<h3 id="contain-fit-sizing" dfn lt="contain-fit sizing" export>
Contain-fit Sizing: stretching while maintaining an aspect ratio</h3>

	Contain-fit sizing essentially applies stretch-fit sizing,
	but reduces the size of the box in one axis
	to maintain the box’s intrinsic aspect ratio,
	similar to the ''object-fit/contain'' keyword of the 'object-fit' and 'background-size' properties.

	First, a target rectangle is determined:

	<ol>
		<li>
			The initial target rectangle is the size of the box’s containing block,
			with any indefinite size assumed as infinity.
			If both dimensions are indefinite,
			the initial target rectangle is set
			to match the outer edges of the box were it <a>stretch-fit sized</a>.

		<li>
			Next, if the box has a non-''max-width/none'' 'max-width' or 'max-height',
			the target rectangle is clamped in the affected dimension
			to less than or equal to the “maximum size” of the box’s margin box,
			i.e. the size its margin box would be
			if the box was sized at its max-width/height.
			(Note that, consistent with normal <a href="http://www.w3.org/TR/CSS2/visuren.html">box-sizing rules</a>,
			this “maximum size” is floored by the effects of the box’s 'min-width'/'min-height'.)

		<li>
			Last, the target rectangle is reduced in one dimension
			by the minimum necessary for it to match the box's intrinsic aspect ratio.
	</ol>

	The contain-fit size in each dimension is
	the size that would result from stretch-fitting into the target rectangle.

	Issue: Copy whatever stretch-fit ends up doing wrt margin collapsing.

	Issue: If there is a minimum size in one dimension
	that would cause overflow of the target rectangle if the aspect ratio were honored,
	do we honor the aspect ratio or skew the image?
	If the former, we need a step similar to #2 that applies the relevant minimums.

<h3 id="percentage-sizing">
Percentage Sizing</h3>

	…

<h2 class=no-num id="changes">
Changes</h2>

<h3 class=no-num id="changes-2020-05">
Recent Changes</h3>
  Significant changes since the <a href="https://www.w3.org/TR/2020/WD-css-sizing-4-20200526/">26 May 2020 First Public Working Draft</a> include:

	* Define [=ratio-determining axis=] as a term.

	* Define that min/max sizing constraints are transferred across an aspect-ratio,
		(<a href="https://github.com/w3c/csswg-drafts/issues/5257">Issue 5257</a>)
		<blockquote>
			<p>Additionally, sizing constraints in either axis
			(the <var>origin</var> axis)
			are transferred through the [=preferred aspect ratio=]
			to the other axis (the <var>destination</var> axis)
			as follows:

			* First, any [=definite=] [=minimum size=] is converted and transferred
				from the <var>origin</var> to <var>destination</var> axis.
				This transferred minimum is capped
				by any [=definite=] [=preferred size|preferred=] or [=maximum size=]
				in the <var>destination</var> axis.
			* Then, any [=definite=] [=maximum size=] is converted and transferred
				from the <var>origin</var> to <var>destination</var>.
				This transferred maximum is floored
				by any [=definite=] [=preferred size|preferred=] or [=minimum size=]
				in the <var>destination</var> axis
				as well as by the transferred minimum, if any.

			Note: The basic principle is that sizing constraints
			transfer through the aspect-ratio to the other side
			to preserve the aspect ratio to the extent that they can
			without violating any sizes specified explictly on that affected axis.
			<!-- This is the principle that drove the contents of the table in CSS2 Section 10.4. -->
		</blockquote>

	* Clarify that 'aspect-ratio' on a replaced element with only one intrinsic dimension determines the other dimension.
		(<a href="https://github.com/w3c/csswg-drafts/issues/5306">Issue 5306</a>)
		<blockquote>
			<p>If a replaced element's only [=intrinsic dimension=]
			is an intrinsic width or an intrinsic height,
			giving it a [=preferred aspect ratio=]
			also gives it an intrinsic height or width,
			whichever was missing,
			by transferring the existing size
			through the [=preferred aspect ratio=].
		</blockquote>

	* Define that 'aspect-ratio' inhibits margin self-collapsing
		(<a href="https://github.com/w3c/csswg-drafts/issues/5328">Issue 5328</a>)
		<blockquote>
			<p>For the purpose of margin collapsing ([[css2/box#collapsing-margins]]),
			if the [=block axis=] is the [=ratio-dependent axis=],
			it is not considered to have a [=computed value|computed=] 'block-size' of ''height/auto''.
		</blockquote>


<h3 class=no-num id="additions-L3">
Additions Since Level 3</h3>

	<ul>
		<li>Added ''stretch'', ''fit-content'', and ''contain'' keywords for sizing properties.
		<li>Added 'aspect-ratio' property.
		<li>Added 'contain-intrinsic-size' property.
	</ul>

<h2 class=no-num id="acknowledgments">
Acknowledgments</h2>

	<p>Special thanks go to Aaron Gustafson, L. David Baron
	for their contributions to this module.

<h2 class=no-num id=priv-sec>
Privacy and Security Considerations</h2>

This specification introduces no new privacy or security considerations.