Skip to content

Commit aab2632

Browse files
tabatkinstabatkins
committed
[css-sizing] Import full propdef tables for all sizing properties, and import box-sizing. Fixes w3c#1920 and fixes w3c#1906.
1 parent 5b725a5 commit aab2632

File tree

1 file changed

+252
-24
lines changed

1 file changed

+252
-24
lines changed

‎css-sizing-3/Overview.bs‎

Lines changed: 252 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Editor: Tab Atkins, Google, http://xanthir.com/contact/, w3cid 42199
1111
Editor: Elika J. Etemad / fantasai, Invited Expert, http://fantasai.inkedblade.net/contact, w3cid 35400
1212
Previous version: https://www.w3.org/TR/2016/WD-css-sizing-3-20160512/
1313
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.
14-
Ignored Terms: block-level box
14+
Ignored Terms: content box, border box, non-replaced
1515
</pre>
1616

1717
<pre class='link-defaults'>
@@ -273,26 +273,99 @@ Intrinsic Size Constraints</h3>
273273
██ ██ ██ ███████ ██ ████████ ████████ ██ ██████
274274
-->
275275

276-
<h2 id='size-keywords'>
277-
New Sizing Keywords</h2>
276+
<h2 id="specifying-sizes" oldid='size-keywords'>
277+
Specifying Box Sizes</h2>
278278

279-
<h3 id='width-height-keywords'>
280-
New Keywords for 'width' and 'height'</h3>
279+
<h3 id="sizing-properties">
280+
Sizing Properties: the 'width', 'height', 'min-width', 'min-height', 'max-width', and 'max-height' properties</h3>
281281

282-
<pre class=propdef partial>
283-
Name: width, max-width, height, max-height
284-
New values: max-content | min-content | fit-content(<<length-percentage>>)
282+
This section defines the <dfn lt="sizing property">sizing properties</dfn>
283+
'width', 'height', 'min-width', 'min-height', 'max-width', and 'max-height'.
284+
285+
Note: Additional <a>flow-relative</a> aliases to these properties are defined in [[CSS-LOGICAL-1]].
286+
287+
<pre class=propdef>
288+
Name: width, height
289+
Value: auto | <<length-percentage>> | min-content | max-content | <nobr>fit-content(<<length-percentage>>)</nobr>
290+
Initial: auto
291+
Applies to: all elements except <a>non-replaced</a> <a>inlines</a>
292+
Inherited: no
293+
Percentages: relative to width/height of <a>containing block</a>
294+
Computed Value: as specified, with lengths made absolute
295+
Animatable: As <<length-percentage>>, or keyword, or as ''fit-content()'' with the <<length-percentage>> argument interpolable
285296
</pre>
286297

287-
<pre class=propdef partial>
298+
The 'width' and 'height' properties specify
299+
the preferred (<a>physical</a>) <dfn>width</dfn> and <dfn>height</dfn> of the box, respectively.
300+
301+
<pre class=propdef>
288302
Name: min-width, min-height
289-
New values: max-content | min-content
303+
Value: auto | <<length-percentage>> | min-content | max-content | <nobr>fit-content(<<length-percentage>>)</nobr>
304+
Initial: auto
305+
Applies to: all elements that accept 'width' or 'height'
306+
Inherited: no
307+
Percentages: relative to width/height of <a>containing block</a>
308+
Computed Value: as specified, with lengths made absolute
309+
Animatable: As <<length-percentage>>, or keyword, or as ''fit-content()'' with the <<length-percentage>> argument interpolable
310+
</pre>
311+
312+
The 'min-width' and 'min-height' properties specify
313+
the <dfn lt="min width | minimum width | min size | minimum size">minimum width</dfn> (or “min width”)
314+
and <dfn lt="min height | minimum height">minimum height</dfn> (or “min height”)
315+
of the box, respectively.
316+
317+
Note: The initial value of ''min-width/auto'' is new;
318+
in [[CSS2]] the initial value was zero.
319+
320+
<pre class=propdef>
321+
Name: max-width, max-height
322+
Value: none | <<length-percentage>> | min-content | max-content | <nobr>fit-content(<<length-percentage>>)</nobr>
323+
Initial: none
324+
Applies to: all elements that accept 'width' or 'height'
325+
Inherited: no
326+
Percentages: relative to width/height of <a>containing block</a>
327+
Computed Value: as specified, with lengths made absolute
328+
Animatable: As <<length-percentage>>, or keyword, or as ''fit-content()'' with the <<length-percentage>> argument interpolable
290329
</pre>
291330

292-
<p>These new values allow authors to explicitly request that a box
293-
take its intrinsic size:
331+
The 'max-width' and 'max-height' properties specify
332+
the <dfn lt="max width | maximum width | max size | maximum size">maximum width</dfn> (or “max width”)
333+
and <dfn lt="max height | maximum height">maximum height</dfn> (or “max height”)
334+
of the box, respectively.
335+
336+
337+
<h3 id="sizing-values" oldids='width-height-keywords'>
338+
Sizing Values: the <<length-percentage>>, ''width/auto'' | ''max-width/none'', ''width/min-content'', ''width/max-content'', and ''width/fit-content()'' values</h3>
294339

295340
<dl dfn-type=value dfn-for="width, min-width, max-width, height, min-height, max-height">
341+
<dt><dfn><<length-percentage>></dfn>
342+
<dd>
343+
Specifies the size of the box using <<length>> and/or <<percentage>>.
344+
The 'box-sizing' property indicates whether the <a>content box</a> or <a>border box</a> is measured.
345+
346+
Percentages are resolved against the width/height, as appropriate,
347+
of the box's <a>containing block</a>.
348+
If, in a particular axis,
349+
the <a>containing block’s</a> size depends on the box’s size,
350+
see the relevant layout module
351+
for special rules on how to resolve percentages.
352+
353+
Negative values are invalid.
354+
355+
<dt><dfn for="width, height, min-width, min-height">auto</dfn>
356+
<dd>
357+
For 'width'/'height', specifies an <dfn dfn for>automatic size</dfn>.
358+
See the relevant layout module for how to calculate this.
359+
360+
For 'min-width'/'min-height',
361+
specifies an <dfn dfn for>automatic minimum size</dfn>.
362+
Unless otherwise defined by the relevant layout module,
363+
this computes to zero.
364+
365+
<dt><dfn for="max-width, max-height">none</dfn>
366+
<dd>
367+
No limit on the size of the box.
368+
296369
<!--
297370
<dt><dfn>stretch</dfn>
298371
<dd>
@@ -311,16 +384,16 @@ New Keywords for 'width' and 'height'</h3>
311384
like tables.
312385
-->
313386

314-
<dt><dfn>max-content</dfn>
387+
<dt><dfn>min-content</dfn>
315388
<dd>
316389
If specified for the inline axis,
317-
use the <a>max-content inline size</a>;
390+
use the <a>min-content inline size</a>;
318391
otherwise compute to the property’s <a>initial value</a>.
319392

320-
<dt><dfn>min-content</dfn>
393+
<dt><dfn>max-content</dfn>
321394
<dd>
322395
If specified for the inline axis,
323-
use the <a>min-content inline size</a>;
396+
use the <a>max-content inline size</a>;
324397
otherwise compute to the property’s <a>initial value</a>.
325398
<!--
326399
<dt><dfn>fit-content</dfn>
@@ -339,8 +412,19 @@ New Keywords for 'width' and 'height'</h3>
339412
i.e.
340413
<code>min(''width/max-content'', max(''width/min-content'', <<length-percentage>>))</code>;
341414
otherwise compute to the property’s <a>initial value</a>.
415+
416+
Negative values are invalid.
342417
</dl>
343418

419+
In all cases,
420+
the used value is floored to preserve a non-negative <a>inner size</a>.
421+
422+
Note: The ''width/min-content'', ''width/max-content'', and ''width/fit-content()'' values
423+
are new in Level 3.
424+
425+
Note: The 'flex-basis' property hereby also gains these new keywords,
426+
as its values are defined by reference to <'width'>.
427+
344428
Note: This section previously defined ''width/stretch'' and ''width/fit-content''
345429
as keywords representing the <a>stretch-fit size</a> and <a>fit-content size</a>,
346430
respectively.
@@ -351,9 +435,6 @@ New Keywords for 'width' and 'height'</h3>
351435
to better work out the implications in situations with
352436
<a>indefinite</a> <a>available space</a>.
353437

354-
Note: The 'flex-basis' property hereby also gains these new keywords,
355-
as its values are defined by reference to <'width'>.
356-
357438
<h4 id="behave-auto">
358439
“Behaving as ''width/auto''”</h4>
359440

@@ -379,6 +460,8 @@ New Keywords for 'width' and 'height'</h3>
379460
these should be interpreted as meaning <a>behaves as auto</a>,
380461
and reported to the CSSWG for updating.
381462

463+
ISSUE: Replace this section with references to the new term <a>automatic size</a>.
464+
382465
<h4 id='the-contain-floats-value'>
383466
Containing or Excluding Floats</h4>
384467

@@ -394,12 +477,156 @@ Containing or Excluding Floats</h4>
394477

395478
Note: Boxes participating in Flex, Grid, or Table layout will automatically have this behavior.
396479

480+
<!--
481+
████████ ███████ ██ ██ ██████ ████ ████████ ████ ██ ██ ██████
482+
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ███ ██ ██ ██
483+
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ████ ██ ██
484+
████████ ██ ██ ███ ███████ ██████ ██ ██ ██ ██ ██ ██ ██ ████
485+
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ████ ██ ██
486+
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ███ ██ ██
487+
████████ ███████ ██ ██ ██████ ████ ████████ ████ ██ ██ ██████
488+
-->
489+
490+
<h3 id="box-sizing">
491+
Inner vs Outer Sizes: the 'box-sizing' property</h3>
492+
493+
494+
<pre class="propdef">
495+
Name: box-sizing
496+
Value: content-box | border-box
497+
Initial: content-box
498+
Applies to: all elements that accept 'width' or 'height'
499+
Inherited: no
500+
Percentages: N/A
501+
Animation type: discrete
502+
</pre>
503+
504+
The 'box-sizing' property switches the box model
505+
between asssigning finite sizes such as <<length>>s and <<percentage>>s
506+
to either the <a>content box</a> or <a>border box</a>.
507+
It affects the interpretation of all <a>sizing properties</a>,
508+
including 'flex-basis'.
509+
510+
Values have the following meanings:
511+
512+
<dl dfn-type=value dfn-for=box-sizing>
513+
<dt><dfn>content-box</dfn>
514+
<dd>
515+
Sizes specified on <a>sizing properties</a>
516+
as <<length-percentage>>
517+
represent <a>inner sizes</a>:
518+
they are applied to the <a>content box</a>.
519+
The padding and border of the box
520+
are laid out and drawn <em>outside</em> the specified 'width' and 'height'.
521+
522+
Note: This is the behavior of width and height as specified by CSS2.1,
523+
and is thus the default.
524+
525+
<dt><dfn>border-box</dfn>
526+
<dd>
527+
Sizes specified on <a>sizing properties</a>
528+
as <<length-percentage>>
529+
represent <a>outer sizes</a>:
530+
they are applied to the <a>border box</a>.
531+
The padding and border of the box
532+
are laid out and drawn <em>inside</em> the specified 'width' and 'height',
533+
with the <a>content box</a> sized to fill the remaining space,
534+
floored at zero.
535+
536+
The content width and height are calculated
537+
by subtracting the border and padding widths of the respective sides
538+
from the specified <<length-percentage>>.
539+
As the content width and height
540+
[[#sizing-values|cannot be negative]],
541+
this computation is floored at zero.
542+
543+
Used values, as exposed for instance through {{getComputedStyle()}},
544+
also refer to the border box.
545+
</dl>
546+
547+
Values affected by 'box-sizing' include
548+
both raw <<length-percentage>> values
549+
and those used in functional notations such as ''width/fit-content()''.
550+
In contrast,
551+
non-quantitative values such as ''width/auto'' and ''width/min-content''
552+
are not influenced by the 'box-sizing' property
553+
(unless otherwise specified).
554+
555+
<div class=example>
556+
For example, the following properties set the <a>inner size</a> of the box to ''100px'',
557+
and the <a>outer size</a> to ''120px'':
558+
559+
<pre class=lang-css>
560+
.box {
561+
box-sizing: content-box; /* default */
562+
width: 100px;
563+
padding-left: 10px;
564+
border-left: 10px solid;
565+
}
566+
</pre>
567+
568+
On the other hand, by changing to ''border-box'',
569+
the <a>inner size</a> is now ''80px'',
570+
while the <a>outer size</a> is ''100px'':
571+
572+
<pre class=lang-css>
573+
.box {
574+
box-sizing: border-box;
575+
width: 100px;
576+
padding-left: 10px;
577+
border-left: 10px solid;
578+
}
579+
</pre>
580+
581+
The <a>inner size</a> can't be less than zero,
582+
so if the 'padding' + 'border' is greater than the specified <a>outer size</a>,
583+
the box will end up larger than specified.
584+
In this case, the <a>inner size</a> will be ''0px''
585+
while the <a>outer size</a> is ''120px'',
586+
even though ''width: 100px'' is specified:
587+
588+
<pre class=lang-css>
589+
.box {
590+
box-sizing: border-box;
591+
width: 100px;
592+
padding-left: 60px;
593+
border-left: 60px solid;
594+
/* padding + border = 120px */
595+
}
596+
</pre>
597+
</div>
598+
599+
Note: Certain HTML elements,
600+
such as <{button}>,
601+
default to ''border-box'' behavior.
602+
See HTML for details on which elements have this behavior.
603+
604+
In the CSS specifications,
605+
the terms <a>width</a>, <a>height</a>,
606+
<a lt="min width">minimum (min) width</a>,
607+
<a lt="min height">minimum (min) height</a>,
608+
<a lt="max width">maximum (max) width</a>, and
609+
<a lt="max height">maximum (max) height</a>
610+
refer to the <a lt="inner size">inner</a> (<a>content box</a>) size
611+
unless otherwise specified.
612+
613+
614+
<!--
615+
██████ ███████ ██ ██ ██ ██ ██ ██ ██
616+
██ ██ ██ ██ ██ ██ ██ ███ ███ ███ ██
617+
██ ██ ██ ██ ██ ██ ████ ████ ████ ██
618+
██ ██ ██ ██ ██ ██ ██ ███ ██ ██ ██ ██
619+
██ ██ ██ ██ ██ ██ ██ ██ ██ ████
620+
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ███
621+
██████ ███████ ████████ ███████ ██ ██ ██ ██
622+
-->
623+
397624
<h3 id='column-sizing'>
398-
Column Sizing Keywords</h3>
625+
New Column Sizing Values: the ''column-width/min-content'', ''column-width/max-content'', and ''column-width/fit-content()'' values</h3>
399626

400627
<pre class="propdef partial">
401628
Name: column-width
402-
New values: max-content | min-content | fit-content(<<length-percentage>>)
629+
New values: min-content | max-content | fit-content(<<length-percentage>>)
403630
</pre>
404631

405632
<p>When used as values for 'column-width',
@@ -411,13 +638,14 @@ Column Sizing Keywords</h3>
411638
<dd>Specifies the optimal column width as the <a>stretch-fit inline size</a>
412639
of the multi-column element.
413640
-->
414-
<dt><dfn>max-content</dfn>
415-
<dd>Specifies the optimal column width as the <a>max-content inline size</a>
416-
of the multi-column element's contents.
417641

418642
<dt><dfn>min-content</dfn>
419643
<dd>Specifies the optimal column width as the <a>min-content inline size</a>
420644
of the multi-column element's contents.
645+
646+
<dt><dfn>max-content</dfn>
647+
<dd>Specifies the optimal column width as the <a>max-content inline size</a>
648+
of the multi-column element's contents.
421649
<!--
422650
<dt><dfn>fit-content</dfn>
423651
<dd>Specifies the optimal column width as

0 commit comments

Comments
 (0)