Skip to content

Commit

Permalink
[css-sizing-3][css-ui-4] Box sizing migration
Browse files Browse the repository at this point in the history 
* Add more guidance on usage of ambiguous sizing terms
* Port box-sizing example from css-ui-3/4 to css-sizing-3
* Add caniuse bikeshed ref for box-sizing in css-sizing-3
* Drop box-sizing from css-ui-4 in favor of css-sizing-3

Closes #2458
  • Loading branch information
@frivoal
frivoal committed Jun 8, 2018
1 parent 7507d61 commit 727d9c1
Show file tree
Hide file tree
Showing 2 changed files with 64 additions and 193 deletions.
53 changes: 50 additions & 3 deletions css-sizing-3/Overview.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,8 @@ 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]]

<p>The definition of the 'box-sizing' property in module supersedes the one in [[CSS-UI-3]].

<h3 id="values">
Values</h3>

Expand Down Expand Up @@ -508,7 +510,7 @@ Containing or Excluding Floats</h4>
████████ ███████ ██ ██ ██████ ████ ████████ ████ ██ ██ ██████
-->

<h3 id="box-sizing">
<h3 id="box-sizing" caniuse="css3-boxsizing">
Box Edges for Sizing: the 'box-sizing' property</h3>


Expand Down Expand Up @@ -620,22 +622,67 @@ Box Edges for Sizing: the 'box-sizing' property</h3>
</pre>
</div>

<div class="example">
This example uses box-sizing to evenly horizontally split
two divs with fixed size borders inside a div container,
which would otherwise require additional markup.

sample CSS:
<pre><code class="lang-css">
div.container {
width:38em;
border:1em solid black;
}

div.split {
box-sizing:border-box;
width:50%;
border:1em silver ridge;
float:left;
}
</code></pre>

sample HTML fragment:
<pre><code class="lang-markup">
&lt;div class="container"&gt;
&lt;div class="split"&gt;This div occupies the left half.&lt;/div&gt;
&lt;div class="split"&gt;This div occupies the right half.&lt;/div&gt;
&lt;/div&gt;
</code></pre>

demonstration of sample CSS and HTML:
<div style="max-width:38em; border:1em solid black"><div style="box-sizing:border-box; width:50%; border:1em silver ridge; float:left">This div should occupy the left half.</div><div style="box-sizing:border-box; width:50%; border:1em silver ridge; float:left">This div should occupy the right half.</div>The two divs above should appear side by side, each (including borders) 50% of the content width of their container. If instead they are stacked one on top of the other then your browser does not support 'box-sizing'.</div>
</div>

Note: Certain HTML elements,
such as <{button}>,
default to ''border-box'' behavior.
See HTML for details on which elements have this behavior.

In the CSS specifications,
In legacy CSS specifications,
the terms <a>width</a>, <a>height</a>,
<a lt="min width">minimum (min) width</a>,
<a lt="min height">minimum (min) height</a>,
<a lt="max width">maximum (max) width</a>, and
<a lt="max height">maximum (max) height</a>
refer to the <a lt="inner size">inner</a> size
generally refer to the <a lt="inner size">inner</a> size
(<a lt="content box">content-box</a> size)
of a <a>box</a>
unless otherwise indicated.

Refer to [[CSS-UI-3#box-sizing]] for an explicit disambiguation of these terms
for the <a href="https://www.w3.org/TR/CSS21/visudet.html">Visual formatting model details</a> section of [[CSS2]].

<div class=advisement>To avoid ambiguities,
specification authors should avoid ambiguous uses of terms such as width or height without further qualification,
and should explicitely refer and link to
the <a lt="inner size">inner</a> size,
the <a lt="outer size">outer</a> size,
the size of the <a href="https://www.w3.org/TR/css2/box.html#box-dimensions">border-box</a>,
the <a>computed value</a> of the <a>sizing properties</a>,
etc,
as appropriate for each case.
</div>

<!--
██████ ███████ ██ ██ ██ ██ ██ ██ ██
Expand Down
204 changes: 14 additions & 190 deletions css-ui-4/Overview.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -140,196 +140,20 @@ which itself replaced and superseded the following:
<a href="https://www.w3.org/TR/2000/WD-css3-userint-20000216">User Interface for CSS3 (16 February 2000)</a> [[CSS-UI-3]]
</ul>


<h2 id="box-model">Box Model addition</h2>

<h3 id="box-sizing" caniuse="css3-boxsizing">Changing the Box Model: the 'box-sizing' property</h3>

<pre class="propdef">
Name: box-sizing
Value: content-box | border-box
Initial: content-box
Applies to: all elements that accept width or height
Inherited: no
Percentages: N/A
Media: visual
Computed value: specified value
</pre>

<dl dfn-type=value dfn-for=box-sizing>
<dt><dfn>content-box</dfn>
<dd>
This is the behavior of width and height as specified by CSS2.1.
The specified width and height (and respective min/max properties)
apply to the width and height respectively of the content box of the element.
The padding and border of the element are laid out
and drawn outside the specified width and height.

<dt><dfn>border-box</dfn>
<dd>
Length and percentages values for width and height (and respective min/max properties)
on this element determine the border box of the element.
That is, any padding or border specified on the element
is laid out and drawn inside this specified width and height.
The content width and height are calculated
by subtracting the border and padding widths of the respective sides
from the specified 'width'
and 'height' properties.
As the content width and height
<a href="https://www.w3.org/TR/CSS21/visudet.html#the-width-property">cannot be negative</a> ([[!CSS21]], section 10.2),
this computation is floored at 0.
Used values, as exposed for instance through getComputedStyle(), also refer to the border box.

Note: This is the behavior of width and height as commonly implemented
by legacy HTML user agents for replaced elements and input elements.
</dl>

Note: In contrast to the length and percentage values,
the ''width/auto'' value of the 'width' and 'height' properties
(as well as other keyword values introduced by later specifications,
unless otherwise specified)
is not influenced by the 'box-sizing' property,
and always sets the size of the content box.

The following terms, whose definitions vary based on the computed value of 'box-sizing' are introduced:

<table border="1">
<tr>
<th>
<th>''box-sizing: content-box''
<th>''box-sizing: border-box''

<tr>
<td><dfn>min inner width</dfn>
<td>'min-width'
<td>max(0, 'min-width' &minus; 'padding-left' &minus; 'padding-right' &minus; 'border-left-width' &minus; 'border-right-width')

<tr>
<td><dfn>max inner width</dfn>
<td>'max-width'
<td>max(0, 'max-width' &minus; 'padding-left' &minus; 'padding-right' &minus; 'border-left-width' &minus; 'border-right-width')

<tr>
<td><dfn>min inner height</dfn>
<td>'min-height'
<td>max(0, 'min-height' &minus; 'padding-top' &minus; 'padding-bottom' &minus; 'border-top-width' &minus; 'border-bottom-width')

<tr>
<td><dfn>max inner height</dfn>
<td>'max-height'
<td>max(0, 'max-height' &minus; 'padding-top' &minus; 'padding-bottom' &minus; 'border-top-width' &minus; 'border-bottom-width')
</table>

The <a href="https://www.w3.org/TR/CSS21/visudet.html">Visual formatting model details</a> of [[!CSS21]] are written assuming ''box-sizing: content-box''. The following disambiguations are made to clarify the behavior for all values of 'box-sizing':

<ol>
<li>
In <a href="https://www.w3.org/TR/CSS21/visudet.html#blockwidth">10.3.3</a>,
the second <q>width</q> in the following phrase is to be interpreted as <a spec="css21">content width</a>:
<q>If 'width' is not ''width/auto'' and 'border-left-width' + 'padding-left' + 'width' + [...]</q>

<li>
In <a href="https://www.w3.org/TR/CSS21/visudet.html#abs-non-replaced-width">10.3.7</a>,
<q>width</q> is to be interpreted as <a spec="css21">content width</a> in the following equation:
<q>'left' + 'margin-left' + 'border-left-width' + 'padding-left' + 'width' + [...]</q>

<li>
In <a href="https://www.w3.org/TR/CSS21/visudet.html#min-max-widths">10.4</a>,
<q>width</q>, <q>height</q>, <q>min-width</q>, <q>max-width</q>, <q>min-height</q> and <q>max-height</q>
are respectively to be interpreted as
<a spec="css21">content width</a>, <a spec="css21">content height</a>, <a>min inner width</a>, <a>max inner width</a>, <a>min inner height</a> and <a>max inner height</a> in the following phrases:

<ol>
<li>
<q>The tentative used width is calculated [...]</q>

<li>
<q>If the tentative used width is greater than 'max-width',
the rules above are applied again,
but this time using the computed value of 'max-width' as the computed value for 'width'.</q>

<li>
<q>If the resulting width is smaller than 'min-width',
the rules above are applied again,
but this time using the value of 'min-width' as the computed value for 'width'.</q>

<li>
<q>Select from the table the resolved height and width values for the appropriate constraint violation.
Take the max-width and max-height as max(min, max) so that min ≤ max holds true.
In this table w and h stand for the results of the width and height computations [...]</q>

<li>
All instances of these words in the table

<li>
<q>Then apply the rules under "Calculating widths and margins" above, as if 'width' were computed as this value.</q>
</ol>

<li>
In <a href="https://www.w3.org/TR/CSS21/visudet.html#abs-non-replaced-height">10.6.4</a>,
<q>height</q> is to be interpreted as <a spec="css21">content height</a> in the following equation:
<q>'top' + 'margin-top' + 'border-top-width' + 'padding-top' + 'height' + [...]</q>

<li>
In <a href="https://www.w3.org/TR/CSS21/visudet.html#min-max-heights">10.7</a>,
<q>width</q>, <q>height</q>, <q>min-height</q> and <q>max-height</q>
are respectively to be interpreted as
<a spec="css21">content width</a>, <a spec="css21">content height</a>, <a>min inner height</a> and <a>max inner height</a> in the following phrases:

<ol>
<li>
<q>The tentative used height is calculated [...]</q>

<li>
<q>If this tentative height is greater than 'max-height',
the rules above are applied again, but this time using the value of 'max-height' as the computed value for 'height'.</q>

<li>
<q>If the resulting height is smaller than 'min-height',
the rules above are applied again,
but this time using the value of 'min-height' as the computed value for 'height'.</q>

<li>
<q>[...] use the algorithm under Minimum and maximum widths above to find the used width and height.
Then apply the rules under "Computing heights and margins" above,
using the resulting width and height as if they were the computed values.</q>
</ol>
</ol>

<div class="example">
<h4 id="box-sizing-example" class="no-num no-toc">Using box-sizing to evenly share space</h4>

This example uses box-sizing to evenly horizontally split
two divs with fixed size borders inside a div container,
which would otherwise require additional markup.

sample CSS:
<pre><code class="lang-css">
div.container {
width:38em;
border:1em solid black;
}

div.split {
box-sizing:border-box;
width:50%;
border:1em silver ridge;
float:left;
}
</code></pre>

sample HTML fragment:
<pre><code class="lang-markup">
&lt;div class="container"&gt;
&lt;div class="split"&gt;This div occupies the left half.&lt;/div&gt;
&lt;div class="split"&gt;This div occupies the right half.&lt;/div&gt;
&lt;/div&gt;
</code></pre>

demonstration of sample CSS and HTML:
<div style="width:38em; border:1em solid black"><div style="box-sizing:border-box; width:50%; border:1em silver ridge; float:left">This div should occupy the left half.</div><div style="box-sizing:border-box; width:50%; border:1em silver ridge; float:left">This div should occupy the right half.</div>The two divs above should appear side by side, each (including borders) 50% of the content width of their container. If instead they are stacked one on top of the other then your browser does not support 'box-sizing'.</div>
</div>

Note:
<span id="box-model"></span>
<span id="box-sizing"></span>
<span id="propdef-box-sizing"></span>
<span id="valdef-box-sizing-content-box"></span>
<span id="valdef-box-sizing-border-box"></span>
<span id="min-inner-width"></span>
<span id="max-inner-width"></span>
<span id="min-inner-height"></span>
<span id="max-inner-height"></span>
<span id="example-d824f1dc"></span>
<span id="box-sizing-example"></span>
The 'box-sizing' property was previously defined in this section of the specification,
but has been moved to [[CSS-SIZING-3#box-sizing]].

<h2 id="outline-props" caniuse="outline">Outline properties</h2>

Expand Down

0 comments on commit 727d9c1

Please sign in to comment.