Skip to content

Box sizing migration #2739

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jun 8, 2018
Merged

Box sizing migration #2739

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f485e5f
[css-sizing-3] Add more guidance on usage of ambiguous sizing terms
frivoal Jun 6, 2018
347833a
[css-sizing-3] Port box-sizing example from css-ui-3
frivoal Jun 6, 2018
0fb011c
[css-sizing-3] Add caniuse bikeshed ref for box-sizing
frivoal Jun 6, 2018
c5c1412
[css-sizing-3][css-ui-4] Drop box-sizing from css-ui in favor of css-…
frivoal Jun 6, 2018
1cc1811
[css-ui-4][css-sizing-3] Phrasing improvements
frivoal Jun 8, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 50 additions & 3 deletions css-sizing-3/Overview.bs
View file
Open in desktop
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]].
Copy link
Collaborator

@fantasai fantasai Jun 7, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I'd probably make this a note?

Copy link
Collaborator Author

@frivoal frivoal Jun 8, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I made all the requested changes except this one.

If it is a note, then css-sizing does not normatively supersede css-ui, and we have two specs both claiming to the the canonical version. That sounds less than ideal. Merging as is for expediency, but feel free to fix after the fact if you still disagree.


<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
Open in desktop
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