css3-regions/Overview.src.html@09b933bd65e2
css3-regions/Overview.src.html
Fri, 12 Oct 2012 15:30:09 -0700
- author
- Alan Stearns <stearns@adobe.com>
- date
- Fri, 12 Oct 2012 15:30:09 -0700
- changeset 6847
- 09b933bd65e2
- parent 6841
- d99a9a222d1d
- child 6903
- a11e43b48600
- permissions
- -rwxr-xr-x
[css-regions] defer named flows from external resources
1 <!DOCTYPE html public '-//W3C//DTD HTML 4.01//EN'
2 'http://www.w3.org/TR/html4/strict.dtd'>
3 <html lang="en">
4 <head profile="http://www.w3.org/2006/03/hcard">
5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6 <title>CSS Regions Module Level 3</title>
7 <link rel="stylesheet" type="text/css" href="../shared/style/default.css">
8 <script src='http://test.csswg.org/harness/annotate.js#CSS3-REGIONS_DEV' type='text/javascript' defer></script>
10 <style type="text/css">
11 #region-style-example p, #region-style-example pre {
12 clear: both;
13 }
15 #region_styling_illustration {
16 margin: 0px auto;
17 width: 70ex;
18 }
19 </style>
21 <link rel="stylesheet" type="text/css"
22 href="http://www.w3.org/StyleSheets/TR/W3C-ED.css">
24 <link rel="stylesheet" type="text/css"
25 href="../shared/style/issues.css">
27 <link id="st" href="../shared/style/alternate-spec-style.css" rel="stylesheet"
28 type="text/css" title="alternate spec style">
29 </head>
32 <body>
33 <div class="head" id="div-head">
34 <p><a href="http://www.w3.org/"><img id="mobile-logo" alt="W3C" height="53" src=
35 "http://www.w3.org/2008/site/images/logo-w3c-mobile-lg" width="90"></a>
38 <!--begin-logo-->
40 <p><a href="http://www.w3.org/"><img id="logo" alt="W3C" height="48" src=
41 "http://www.w3.org/Icons/w3c_home" width="72"></a> <!--end-logo--></p>
43 <h1 id="css-regions-module">CSS Regions Module Level 3</h1>
45 <h2 class="no-num no-toc" id="longstatus-date">[LONGSTATUS]
46 [DATE]</h2>
48 <dl>
49 <dt>This version:</dt>
51 <dd><a href=
52 "[VERSION]">http://www.w3.org/csswg/css3-regions</a></dd>
54 <dt>Latest version:</dt>
56 <dd><a href=
57 "http://www.w3.org/TR/css3-regions/">http://www.w3.org/TR/css3-regions/</a></dd>
59 <dt>Previous version:</dt>
61 <dd><a href="http://www.w3.org/TR/2011/WD-css3-regions-20111129/">http://www.w3.org/TR/2011/WD-css3-regions-20111129/</a></dd>
63 <dt>Editors:</dt>
65 <dd class="vcard"><span class="fn">Vincent Hardy</span>,
66 <span class="org">Adobe Systems, Inc.</span>, <span class=
67 "email">vhardy@adobe.com</span></dd>
68 <dd class="vcard"><span class="fn">Alex Mogilevsky</span>,
69 <span class="org">Microsoft</span>, <span class=
70 "email">alexmog@microsoft.com</span></dd>
71 <dd class="vcard"><span class="fn">Alan Stearns</span>,
72 <span class="org">Adobe Systems, Inc.</span>, <span class=
73 "email">stearns@adobe.com</span></dd>
75 <dt>Issues List:</dt>
76 <dd><a href="https://www.w3.org/Bugs/Public/buglist.cgi?product=CSS&component=Regions&resolution=---">Bugzilla Bugs for CSS regions</a></dd>
77 <dt>Discussion:</dt>
78 <dd><a href="http://lists.w3.org/Archives/Public/www-style/">www-style@w3.org</a> with subject line "<code>[css3-regions] message topic</code>"</dd>
79 </dl><!--begin-copyright--><!--end-copyright-->
80 <hr title="Separator for header">
81 </div>
83 <h2 class="no-num no-toc" id="abstract">Abstract</h2>
85 <p>The CSS regions module allows content to flow across multiple areas
86 called regions. The regions are not necessarily contiguous in the document order.
87 The CSS regions module provides an advanced content flow mechanism, which
88 can be combined with positioning schemes as defined by other CSS modules
89 such as the Multi-Column Module [[CSS3COL]] or the Grid Layout Module
90 [[CSS3-GRID-LAYOUT]] to position the regions where content flows.</p>
92 <h2 class="no-num no-toc" id="status-of-this-document">Status of this
93 document</h2>
95 <p class="big note"><span class="note-prefix">Note </span>This document uses an experimental style
96 sheet. We welcome your feedback on the styles at
97 <a href="mailto:site-comments@w3.org">site-comments@w3.org</a>.</p>
99 <!--status-->
101 <p>This draft is related to the drafts about Multi-column Layout
102 [[CSS3COL]], Grid Layout [[CSS3GRID]], Flexible Box Layout
103 [[CSS3-FLEXBOX]], and Template Layout [[CSS3LAYOUT]].</p>
105 <h2 class="no-num no-toc" id="table-of-contents">Table of contents</h2>
106 <!--begin-toc--><!--end-toc-->
108 <h2 id="introduction">Introduction</h2>
110 <p><em>This section is non-normative.</em></p>
112 <p>Displaying the complex layouts
113 of a typical magazine, newspaper, or textbook on the web
114 requires capabilities beyond those available in existing CSS modules.
115 Dynamic magazine layout in particular requires flexibility
116 in placement of boxes for content flows.
117 This is the purpose of the CSS regions module.</p>
119 <div class="issue-marker" data-bug_id="15733" data-bug_status="NEW">
120 <a href=
121 "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15733">Issue-15733</a>
123 <div class="issue-details">
124 <p class="short-desc">Should the region specification define a
125 mechanism to create blocks that can be regions with CSS
126 syntax?</p>
127 </div>
128 </div>
130 <p>For more complex layouts,
131 content needs to flow from one area of the page to the next
132 without limitation on the areas' sizes and positions.
133 These arbitrary areas are the target of specific content flows
134 which this document calls <span>named flows</span>.
135 Each <span>named flow</span> can be associated
136 with a set of CSS Regions called a region chain.
137 CSS Regions are based on the rectangular geometry
138 of the CSS box model.
139 Elements in a <span>named flow</span>
140 are taken out of the normal visual formatting
141 and rendered in a chain of CSS Regions.</p>
143 <h3 id="named-flows-and-regions">Named flows and region chains</h3>
145 <p>Consider the layout illustrated in figure 1.</p>
148 <div class="figure">
149 <img src="images/intro-example-layout.svg" width="400" alt=
150 "multiple chained regions which should receive content from a flow">
152 <p class="caption">Layout requiring sophisticated content flow</p>
153 </div>
155 <p>The designer's intent is
156 to position an image in box 'A'
157 and to flow an article's content
158 from box '1' through boxes '2', '3' and '4'.
159 Note that the second box should have two columns,
160 and the image is not contained in the article.
161 Box '4' should auto-size to render
162 the remainder of the article content
163 that did not fit in the earlier boxes.</p>
165 <p>Figure 2 shows an example
166 of the intended visual rendering
167 of the content.</p>
169 <div class="figure">
170 <img src="images/regions-intro-rendering.png" width="450" alt=
171 "Sample rendering showing a single thread of text flowing through a chain of regions">
173 <p class="caption">Sample rendering for desired layout</p>
174 </div>
177 <p>There is no existing mechanism in CSS
178 to associate the content with these boxes
179 arranged in this manner
180 so that content flows as intended.
181 The CSS regions module properties provide that mechanism.</p>
183 <p>The following example illustrates
184 how the content of an <code><article></code> element
185 becomes a <span>named flow</span>
186 and how boxes marked with 'region1', 'region2', 'region3' and 'region4' IDs
187 become CSS Regions that consume the 'article_flow' content.</p>
189 <div class="example">
190 <pre>
191 <style>
192 article {
193 <strong>flow-into: article_flow;</strong>
194 }
196 #region1, #region2, #region3, #region4 {
197 <strong>flow-from: article_flow;</strong>
198 }
199 </style>
200 </pre>
201 </div>
203 <p>The 'article_flow' value on the 'flow-into' property
204 directs the <code>article</code> element
205 to the 'article_flow' <span>named flow</span>.
206 Setting the 'flow-from' property on block containers
207 to 'article_flow' makes them CSS Regions
208 and associates the resulting region chain
209 with the <span>named flow</span>:
210 the flow is ''poured''
211 into the region chain.</p>
213 <p>See <a href="#intro-example-code">Appendix A</a>
214 for sample code using grid layout
215 that implements this example</p>
217 <div class="issue-marker" data-bug_id="16858" data-bug_status="ASSIGNED">
218 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16858">Issue-16858</a>
219 <div class="issue-details">
220 <p class="short-desc">Should creation of regions from elements be disallowed?</p>
221 </div>
222 </div>
224 <div class="note"><span class="note-prefix">Note </span>
225 <p><strong>CSS Regions are independent from layout</strong></p>
227 <p>Any of the CSS layout facilities can be used
228 to create, position and size boxes that can become CSS Regions.
229 Using a grid layout [[CSS3-GRID-LAYOUT]] is just an example.
230 The example could use
231 a flexible box layout [[CSS3-FLEXBOX]] instead.</p>
232 <p>The CSS regions specification does not
233 define a layout mechanism
234 and is meant to integrate
235 with existing and future CSS layout facilities.</p>
237 <p><strong>CSS Regions do not have to be elements</strong></p>
239 <p>The CSS regions module is independent
240 of the layout of boxes and
241 the mechanism used to create them.
242 For simplicity,
243 our example code in <a href="#intro-example-code">Appendix A</a>
244 uses elements to define the boxes.</p>
247 <p>While the example uses elements for CSS Regions
248 (since [[CSS3-GRID-LAYOUT]] requires elements to create grid items)
249 it is important to note that
250 this is not required.
251 CSS Regions can be pseudo-elements,
252 such as '::before' and '::after'.
253 The only requirement
254 for an element or pseudo-element
255 to become a CSS Region
256 is that it needs to be subject
257 to CSS styling
258 to receive the 'flow-from' property.
259 The CSS page template module
260 (see [[CSS3-PAGE-TEMPLATE]])
261 proposes another mechanism
262 to create stylable boxes that can become CSS Regions
263 with the <code class="css">@slot</code> syntax.</p>
264 </div>
266 <h3 id="region-styling">CSS Region names and styling</h3>
268 <div class="issue-marker" data-bug_id="16859" data-bug_status="NEW">
269 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16859">Issue-16859</a>
270 <div class="issue-details">
271 <p class="short-desc">Reconsider using @rule for region styling</p>
272 </div>
273 </div>
275 <p>Content can be styled depending on
276 the CSS Region it flows into.
277 It is an extension
278 of pseudo-element styling such as
279 <a href="http://www.w3.org/TR/css3-selectors/#first-line">
280 <code class="css">::first-line</code>
281 </a>
282 which applies a particular style
283 to a fragment of content.
284 With CSS Region styling,
285 additional selectors may apply
286 depending on the CSS Region
287 into which content flows.</p>
289 <p>In our example,
290 the designer wants to make
291 text flowing into #region1
292 dark blue and bold.</p>
294 <p>This design can be expressed as shown below.</p>
296 <div class="example">
297 <pre>
298 <style>
299 @region #region1 {
300 p {
301 color: #0C3D5F;
302 font-weight: bold;
303 }
304 </style></pre>
305 </div>
307 <p>The <code class="css">@region #region1</code> rule
308 limits its selectors to content
309 flowing into <code class="css">#region1</code>.
310 The following figure shows how
311 the rendering changes
312 if we apply styling specific to <code>#region1</code>.
313 Note how less text fits into this box
314 now that the 'font-weight' is
315 bold instead of normal.</p>
317 <div class="figure">
318 <img src="images/region-styling.png" width="450" alt=
319 "Illustrate how changing region styling affects the flow of content.">
321 <p class="caption">Different rendering with a different region
322 styling</p>
323 </div>
325 <h2 id="css-regions-concepts">CSS regions concepts</h2>
327 <h3 id="regions">Regions</h3>
329 <div class="issue-marker wrapper">
330 <div class="issue-marker" data-bug_id="15186" data-bug_status="NEW">
331 <a href=
332 "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15186">Issue-15186</a>
334 <div class="issue-details">
335 <p class="short-desc">Is a mechanism to auto-generate regions
336 necessary in order to support reusable style sheets?</p>
337 </div>
338 </div>
339 </div>
341 <p id="region">
342 A <dfn title="region">CSS Region</dfn>
343 is a block container
344 that has an associated
345 <em><span>named flow</span></em>
346 (see the 'flow-from' property).</p>
348 <h3 id="region-chain">Region chain</h3>
350 <p>A <dfn>region chain</dfn> is the sequence of regions that are associated with
351 a <span>named flow</span>. <span title="region">CSS Regions</span> in a
352 region chain receive content from the
353 named flow following their order in the chain. <span title="region">CSS Regions</span> are organized
354 into a <span title="region-chain">region chain</span>
355 according to the document order.</p>
357 <h3 id="named-flow">Named flows</h3>
359 <p>A <dfn>named flow</dfn> is the ordered sequence of elements
360 associated with a flow with a given identifier.
361 Elements in a <span>named flow</span> are ordered
362 according to the document order.</p>
364 <p>Elements are placed into a <span>named flow</span>
365 with the 'flow-into' property.
366 The elements in a <span>named flow</span> are laid out
367 in the <span title="region-chain">region chain</span>
368 that is associated with this <span>named flow</span>.
369 </p>
371 <p>Content from a <span>named flow</span>
372 is broken up between regions
373 according to the regions flow breaking rules.</p>
375 <p>A <span>named flow</span> is created when
376 at least one element is moved
377 into the flow with the given identifier
378 or when at least one CSS Region
379 requests content from that flow.</p>
381 <h3 id="regions-flow-breaking-rules">Regions flow breaking rules</h3>
383 <p>Breaking a <span>named flow</span> across a region chain
384 is similar to breaking a document's content across pages
385 (see [[CSS3PAGE]])
386 or a multi-column element's content across column boxes
387 (see [[CSS3COL]]).
388 One difference is that page boxes are generated
389 based on the available content
390 whereas a region chain is a set of recipient boxes
391 for the <span>named flow</span> content
392 whose dynamic generation is not in the scope
393 of this specification.</p>
395 <p>Each CSS Region in turn
396 consumes content from its associated <span>named flow</span>.
397 The <span>named flow</span> content is positioned
398 in the <dfn title="current-region">current region</dfn>
399 until a natural or forced region break occurs,
400 at which point the next region
401 in the <span title="region-chain">region chain</span>
402 becomes the <span title="current-region">current region</span>.
403 If there are no more <span>region</span>s
404 in the region chain
405 and there is still content in the flow,
406 the positioning of the remaining content
407 is controlled by the 'region-fragment' property
408 on the last <span>region</span> in the chain.</p>
410 <p>The CSS regions module follows
411 the fragmentation rules defined
412 in the CSS Fragmentation Module Level 3
413 (see [[!CSS3-BREAK]]).</p>
416 <h2 id="properties-and-rules">Properties and rules</h2>
418 <h3 id="the-flow-into-property">The 'flow-into' property</h3>
420 <div class="issue-marker wrapper">
421 <div class="issue-marker" data-bug_id="16527" data-bug_status="ASSIGNED">
422 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16527">Issue-16527</a>
423 <div class="issue-details">
424 <p class="short-desc">[Shadow]: getFlowByName and shadow DOM</p>
425 </div>
426 </div>
427 </div>
429 <p>The ‘flow-into’ property can place an element
430 into a <span>named flow</span>.
431 Elements that belong to the same flow
432 are laid out in the region chain
433 associated with that flow.</p>
435 <table class="propdef" summary="flow property definition">
436 <tr>
437 <th>Name:</th>
439 <td><dfn id="flow-into">flow-into</dfn></td>
440 </tr>
442 <tr>
443 <th>Value:</th>
445 <td><ident> | none | inherit</td>
446 </tr>
448 <tr>
449 <th>Initial:</th>
451 <td>none</td>
452 </tr>
454 <tr>
455 <th>Applies to:</th>
457 <td>any element. <p>The 'flow-into' property does not apply to any <a href="http://www.w3.org/TR/selectors/#pseudo-elements">pseudo-element</a> such as
458 <code class="css">::first-line</code>, <code class="css">::first-letter</code>,
459 <code class="css">::before</code> or <code class="css">::after</code>.</p></td>
460 </tr>
462 <tr>
463 <th>Inherited:</th>
465 <td>no</td>
466 </tr>
468 <tr>
469 <th>Percentages:</th>
471 <td>N/A</td>
472 </tr>
474 <tr>
475 <th>Media:</th>
477 <td>visual</td>
478 </tr>
480 <tr>
481 <th>Computed value:</th>
483 <td>as specified</td>
484 </tr>
485 </table>
487 <dl>
488 <dt>none</dt>
490 <dd>The element is not moved to a <span>named flow</span> and normal CSS processing takes place.</dd>
492 <dt><a href="http://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#value-def-identifier"><ident></a></dt>
494 <dd>The element is taken out
495 of its parent's flow
496 and placed into the flow
497 with the name '<a href="http://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#value-def-identifier"><ident></a>'.
498 The element is said to have
499 a <dfn id="specified-flow">specified flow</dfn>.
500 The values 'none', 'inherit', 'default', 'auto' and 'initial'
501 are invalid flow names.</dd>
502 </dl>
504 <p>A <span>named flow</span> needs to be associated
505 with a region chain
506 (one or more CSS regions)
507 for its elements to be visually formatted.
508 If no region chain is associated
509 with a given <span>named flow</span>,
510 the elements in the <span>named flow</span>
511 are not rendered:
512 they do not generate boxes
513 and are not displayed.</p>
515 <p>The children of an element
516 with a specified flow
517 may themselves have a specified flow.</p>
519 <p>If an element has the same specified flow
520 as one of its ancestors,
521 it becomes a sibling of its ancestor
522 for the purpose of layout
523 in the region chain
524 laying out content
525 from that flow.</p>
527 <p>The 'flow-into' property does not affect
528 the CSS cascade and inheritance
529 for the elements on which it is specified.
530 The 'flow-into' property affects
531 the visual formatting of elements
532 placed into a <span>named flow</span>
533 and of the region chain laying out content
534 from a <span>named flow</span>.</p>
536 <p>The edges of the first CSS region in a region chain
537 associated with a <span>named flow</span>
538 establish the rectangle that is the
539 <a href="http://www.w3.org/TR/CSS2/visudet.html#containing-block-details">containing block</a>
540 used for absolutely positioned elements
541 in the <span>named flow</span>
542 which do not have an ancestor
543 with a 'position' of 'absolute', 'relative' or 'fixed'
544 (see [[!CSS21]]).
545 That first CSS region rectangle is used
546 as the containing block
547 instead of the initial containing block.
548 This does not affect
549 fixed position elements
550 in the <span>named flow</span> -
551 they are still positioned relative
552 to the viewport or page area even if
553 they have been redirected
554 to a named flow.</p>
556 <p>The first region defines the
557 <a href="http://www.w3.org/TR/css3-writing-modes/#writing-mode">writing mode</a>
558 for the entire flow.
559 The writing mode
560 on subsequent regions is ignored.</p>
562 <p>Elements in a <span>named flow</span>
563 are sequenced in document order.
564 The structure of a named flow
565 is equivalent to the result
566 of moving the elements to a common parent.
567 The visual formatting model
568 uses the relationships between elements
569 in the named flow structure as input,
570 rather than the elements’ original positions.
571 </p>
573 <div class="note"><span class="note-prefix">Note </span>
574 <p>The 'flow-into' property moves an element into the flow
575 and the interplay with selectors should be considered carefully.</p>
576 <p>For example, </p>
577 <pre>table {flow-into: table-content}</pre>
578 <p>will move all tables in the 'table-content'
579 <span>named flow</span>.
580 However, the</p>
581 <pre>table > * {flow-into: table-content} ...</pre>
582 <p>selector will move all immediate children
583 of all table elements
584 into the ‘table-content’ <span>named flow</span>
585 (which may be useful as it will usually result,
586 if the immediate children are rows,
587 in merging rows of multiple tables),
588 but the</p>
589 <pre>table * {flow-into: table-content}</pre>
590 <p>selector will move all descendants
591 of table elements into the ‘table-content’ <span>named flow</span>,
592 transforming the element tree
593 into a flat list in order of opening tags
594 (which is probably not intentional).
595 This will make all the descendants
596 of table elements siblings
597 in the <span>named flow</span>.
598 Having the descendants become siblings
599 in the <span>named flow</span>
600 results in a different processing
601 (see <a href="http://www.w3.org/TR/2011/REC-CSS2-20110607/tables.html#anonymous-boxes">CSS 2.1's anonymous table objects</a>).
602 This note illustrates how authors must exercise caution
603 when choosing a particular selector
604 for setting the 'flow-into' property
605 to avoid unintended results.</p>
606 </div>
608 <div class="note"><span class="note-prefix">Note </span>
609 <p>Another consequence of moving elements
610 into named flows is that surrounding whitespace
611 is not moved into the named flow.
612 If you have code like this:
613 <pre>span {flow-into: span-content}
614 <span>one</span>
615 <span>two</span>
616 </pre>
617 Then the 'span-content' named flow contents
618 will contain this:
619 <pre><span>one</span><span>two</span>
620 </pre>
621 Which will change the display
622 from "one two" to "onetwo".
623 If whitespace is significant,
624 then moving the parent
625 that contains the whitespace
626 to the named flow
627 is required.
628 </div>
630 <div class="note"><span class="note-prefix">Note </span>
631 <p>A future CSS Regions module level
632 will define a mechanism
633 for creating a named flow
634 from an external resource.</p>
635 </div>
637 <h3 id="the-flow-from-property">The 'flow-from' property</h3>
639 <p>The 'flow-from' property makes
640 a block container a region
641 and associates it with
642 a <span>named flow</span>.</p>
644 <table class="propdef" summary="flow-from property definition">
645 <tr>
646 <th>Name:</th>
648 <td><dfn id="flow-from">flow-from</dfn></td>
649 </tr>
651 <tr>
652 <th>Value:</th>
654 <td><ident> | none | inherit</td>
655 </tr>
657 <tr>
658 <th>Initial:</th>
660 <td>none</td>
661 </tr>
663 <tr>
664 <th>Applies to:</th>
666 <td>Non-replaced <a href="http://www.w3.org/TR/CSS21/visuren.html#block-boxes">block containers</a>.
667 <br/>
668 This might be expanded in future versions of the specification
669 to allow other types of containers to receive flow content.</td>
670 </tr>
672 <tr>
673 <th>Inherited:</th>
675 <td>no</td>
676 </tr>
678 <tr>
679 <th>Percentages:</th>
681 <td>N/A</td>
682 </tr>
684 <tr>
685 <th>Media:</th>
687 <td>visual</td>
688 </tr>
690 <tr>
691 <th>Computed value:</th>
693 <td>as specified</td>
694 </tr>
695 </table>
697 <dl>
698 <dt><strong>none</strong></dt>
700 <dd>The block container is not a <span title="region">region</span>.</dd>
702 <dt><strong><a href="http://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#value-def-identifier"><ident></a></strong></dt>
704 <dd>
705 If the 'content' property computes
706 to something else than 'normal'
707 (or 'none' for a pseudo-element),
708 the block container does not become a <span>CSS Region</span>.
709 If the 'content' property computes to 'normal'
710 (or 'none' for a pseudo-element),
711 then the block container becomes a <span>CSS Region</span>
712 and is ordered in a <span>region chain</span>
713 according to its document order.
714 The content from the flow
715 with the <a href="http://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#value-def-identifier"><ident></a>
716 name will be <a href="#region-flow-break">broken
717 into fragments</a> and visually formatted in the
718 <a href="http://www.w3.org/TR/CSS21/visuren.html#principal-box">principal boxes</a>
719 of the <span>regions</span>
720 in the <span>region chain</span>.
721 <br/>
722 If there is no flow with name
723 <a href="http://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#value-def-identifier"><ident></a>,
724 then the block container does not
725 format any content visually.
726 </dd>
727 </dl>
729 <p>A <span>CSS Region</span>'s document children
730 are not visually formatted
731 unless they are directed
732 to a <span>named flow</span>
733 with an associated <span>region chain</span>.</p>
735 <div class="note"><span class="note-prefix">Note </span>
736 <p>An block container becomes a <span>CSS Region</span>
737 when its 'flow-from' property is set
738 to a valid <a href="http://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#value-def-identifier"><ident></a> value,
739 even if there is no content contributing
740 to the referenced flow.
741 For example:</p>
742 <pre>
743 <style>
744 .article{
745 flow-into: thread;
746 }
747 .region{
748 flow-from: thread;
749 }
750 </style>
751 <html>
752 <body>
753 <div class=region>div content</div>
754 </body>
755 </html>
756 </pre>
758 There is no element matching
759 the <code>.article</code> selector
760 and therefore no content
761 in the <code>thread</code> flow.
762 However, the block container matching
763 the <code>.region</code> selector
764 is still associated with
765 that empty <span>named flow</span>
766 and, consequently,
767 its children are not formatted visually.
768 </div>
770 <div class="note"><span class="note-prefix">Note </span>
771 <p>At the time of this note-writing,
772 the <code>display</code> values that always result
773 in a non-replaced block container include
774 <code>block</code>,
775 <code>inline-block</code>,
776 <code>table-cell</code>,
777 <code>table-caption</code>,
778 and <code>list-item</code>.
779 All of these display values
780 work as regions with
781 non-replaced elements.
782 </div>
784 <div class="issue-marker wrapper">
785 <div class="issue-marker" data-bug_id="15824" data-bug_status="NEW">
787 <a href=
788 "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15824">Issue-15824</a>
790 <div class="issue-details">
791 <p class="short-desc">Should regions not create a new stacking context?</p>
792 </div>
793 </div>
794 <div class="issue-marker" data-bug_id="15827" data-bug_status="NEW">
796 <a href=
797 "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15824">Issue-15827</a>
799 <div class="issue-details">
800 <p class="short-desc">Specify behavior of stacking contexts that are split between regions</p>
801 </div>
802 </div>
803 </div>
805 <p><span title="region">CSS Regions</span> create a new <a href="http://www.w3.org/TR/CSS2/visuren.html#z-index">stacking context</a>. <span title="region">CSS Regions</span> establish a new <a href="http://www.w3.org/TR/CSS2/visuren.html#block-formatting">block formatting Context</a>.</p>
807 <div class="note"><span class="note-prefix">Note </span>
808 <p>With <span>region chains</span>,
809 an element may be split across multiple boxes
810 and these boxes may overlap
811 (for example if they are absolutely positioned).
812 So fragments of the same element
813 can overlap each other.
814 Since each element has a single z-index,
815 it would be required to find another mechanism
816 to decide in which order
817 the fragments are rendered.
818 Since each <span>CSS Region</span> creates
819 a new stacking context,
820 it is clear that each fragment is rendered separately
821 and their rendering order follows
822 the regular CSS rendering model.</p>
823 </div>
825 <p>Floats or other exclusions
826 (see [[CSS3-EXCLUSIONS]])
827 potentially impact the content
828 laid out in region chains,
829 just as for non-regions.</p>
831 <p>See the
832 <a href="#regions-visual-formatting-details">regions visual formatting details</a>
833 section for a description of how
834 'width' and 'height' values are resolved
835 for <span>CSS Region</span> boxes.</p>
837 <h4 id="circular-dependencies">Cycle Detection</h4>
839 <p><span>Named flows</span> containing elements
840 where the value of 'flow-from' computes to an
841 <a href="http://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#value-def-identifier"><ident></a>
842 can produce nonsensical circular relationships,
843 such as a <span>named flow</span> containing <span>CSS Regions</span>
844 in its own <span>region chain</span>.
845 These relationships can be easily
846 and reliably detected and resolved, however,
847 by keeping track of a dependency graph
848 and using common cycle-detection algorithms.</p>
850 <p>The dependency graph consists of edges such that:</p>
852 <ul>
853 <li>Every <span>named flow</span> depends on its elements
854 where the value of 'flow-from' computes to an
855 <a href="http://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#value-def-identifier"><ident></a>
856 .</li>
857 <li>Every element in a <span>named flow</span>
858 where the value of 'flow-from' computes to an
859 <a href="http://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#value-def-identifier"><ident></a>
860 depends on the <span>named flow</span> with the
861 <a href="http://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#value-def-identifier"><ident></a>
862 name.</li>
863 </ul>
865 <p>If the graph contains a cycle,
866 any elements where the value of 'flow-from'
867 computes to an
868 <a href="http://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#value-def-identifier"><ident></a>
869 participating in the cycle
870 do not become <span>CSS Regions</span>.</p>
872 <h4 id="fragmenting-regions">Nested fragmentation contexts</h4>
874 <p>A <span>CSS Region</span> that contains
875 a fragment of a <span>named flow</span>
876 can itself be fragmented if it is nested
877 within a fragmentation context [[!CSS3-BREAK]],
878 such as when a layout
879 using a region chain is printed.
880 In these cases break opportunities
881 in the named flow fragment
882 contained by the <span>CSS Region</span>
883 are determined using the standard
884 <a href="http://www.w3.org/TR/css3-break/">fragmentation rules</a>.
885 In other words,
886 each region box and its associated fragment
887 should break as if it were a simple div
888 containing the fragment contents.
889 This can be controlled by using
890 an avoid break value on the <span>CSS Region</span>,
891 if that is desired.</p>
893 <h3 id=
894 "region-flow-break">Region
895 flow break properties: 'break-before', 'break-after', 'break-inside'</h3>
897 <p>User agents laying out content in multiple regions must
898 determine where content breaks occur. The problem of breaking content into
899 fragments fitting in regions is similar to breaking content into pages or
900 columns.</p>
902 <p>Each break ends layout in the current region and causes remaining pieces
903 of content from the <span>named flow</span> to be visually formatted in the following
904 region in the region chain, if there is one.</p>
906 <p>The following extends the 'break-before', 'break-after' and
907 'break-inside' properties from the [[!CSS3COL]] specification to account
908 for regions. The additional values are described below.</p>
910 <table class="propdef" summary="break-before property definition">
911 <tr>
912 <td><em>Name:</em></td>
914 <td><dfn>break-before</dfn></td>
915 </tr>
917 <tr>
918 <td><em>Value:</em></td>
920 <td>auto | always | avoid | left | right | page | column | region |
921 avoid-page | avoid-column | avoid-region</td>
922 </tr>
924 <tr>
925 <td><em>Initial:</em></td>
927 <td>auto</td>
928 </tr>
930 <tr>
931 <td><em>Applies to:</em></td>
933 <td>block-level elements</td>
934 </tr>
936 <tr>
937 <td><em>Inherited:</em></td>
939 <td>no</td>
940 </tr>
942 <tr>
943 <td><em>Percentages:</em></td>
945 <td>N/A</td>
946 </tr>
948 <tr>
949 <td><em>Media:</em></td>
951 <td>visual</td>
952 </tr>
954 <tr>
955 <td><em>Computed value:</em></td>
957 <td>specified value</td>
958 </tr>
959 </table>
961 <table class="propdef" summary="break-after property definition">
962 <tr>
963 <td><em>Name:</em></td>
965 <td><dfn>break-after</dfn></td>
966 </tr>
968 <tr>
969 <td><em>Value:</em></td>
971 <td>auto | always | avoid | left | right | page | column | region |
972 avoid-page | avoid-column | avoid-region</td>
973 </tr>
975 <tr>
976 <td><em>Initial:</em></td>
978 <td>auto</td>
979 </tr>
981 <tr>
982 <td><em>Applies to:</em></td>
984 <td>block-level elements</td>
985 </tr>
987 <tr>
988 <td><em>Inherited:</em></td>
990 <td>no</td>
991 </tr>
993 <tr>
994 <td><em>Percentages:</em></td>
996 <td>N/A</td>
997 </tr>
999 <tr>
1000 <td><em>Media:</em></td>
1002 <td>visual</td>
1003 </tr>
1005 <tr>
1006 <td><em>Computed value:</em></td>
1008 <td>specified value</td>
1009 </tr>
1010 </table>
1012 <table class="propdef" summary="break-inside property definition">
1013 <tr>
1014 <td><em>Name:</em></td>
1016 <td><dfn>break-inside</dfn></td>
1017 </tr>
1019 <tr>
1020 <td><em>Value:</em></td>
1022 <td>auto | avoid | avoid-page | avoid-column | avoid-region</td>
1023 </tr>
1025 <tr>
1026 <td><em>Initial:</em></td>
1028 <td>auto</td>
1029 </tr>
1031 <tr>
1032 <td><em>Applies to:</em></td>
1034 <td>block-level elements</td>
1035 </tr>
1037 <tr>
1038 <td><em>Inherited:</em></td>
1040 <td>no</td>
1041 </tr>
1043 <tr>
1044 <td><em>Percentages:</em></td>
1046 <td>N/A</td>
1047 </tr>
1049 <tr>
1050 <td><em>Media:</em></td>
1052 <td>visual</td>
1053 </tr>
1055 <tr>
1056 <td><em>Computed value:</em></td>
1058 <td>specified value</td>
1059 </tr>
1060 </table>
1062 <p>These properties describe page, column and region break behavior
1063 before/after/inside the generated box. These values are normatively defined
1064 in [[!CSS3COL]]:</p>
1066 <p>This specification adds the following new values:</p>
1068 <dl>
1069 <dt>region</dt>
1071 <dd>Always force a region break before (after) the generated box.</dd>
1073 <dt>avoid-region</dt>
1075 <dd>Avoid a region break before (after, inside) the generated box.</dd>
1076 </dl>
1078 <p>The behavior of region breaks with regards to regions is identical to the behavior
1079 of page breaks with regards to pages, as defined in the [[!CSS21]].</p>
1081 <h3 id="the-region-fragment-property">The region-fragment property</h3>
1083 <table class="propdef" summary="break-after property definition">
1084 <tr>
1085 <td><em>Name:</em></td>
1087 <td><dfn>region-fragment</dfn></td>
1088 </tr>
1090 <tr>
1091 <td><em>Value:</em></td>
1093 <td>auto | break</td>
1094 </tr>
1096 <tr>
1097 <td><em>Initial:</em></td>
1099 <td>auto</td>
1100 </tr>
1102 <tr>
1103 <td><em>Applies to:</em></td>
1105 <td><em title="region element">CSS Regions</em></td>
1106 </tr>
1108 <tr>
1109 <td><em>Inherited:</em></td>
1111 <td>no</td>
1112 </tr>
1114 <tr>
1115 <td><em>Percentages:</em></td>
1117 <td>N/A</td>
1118 </tr>
1120 <tr>
1121 <td><em>Media:</em></td>
1123 <td>visual</td>
1124 </tr>
1126 <tr>
1127 <td><em>Computed value:</em></td>
1129 <td>specified value</td>
1130 </tr>
1131 </table>
1133 <p>The 'region-fragment' property controls the behavior of the <em id=
1134 "last-region">last region</em> associated with a <span>named
1135 flow</span>.</p>
1137 <dl>
1138 <dt>auto</dt>
1140 <dd>Content flows as it would in a regular content box. If the
1141 content exceeds the container box, it is subject to the <a href=
1142 "http://www.w3.org/TR/CSS21/visufx.html#propdef-overflow">overflow</a>
1143 property's computed value on the CSS Region. Region breaks must be
1144 ignored on the last region.</dd>
1146 <dt>break</dt>
1148 <dd><p>If the content fits within the <em>CSS Region</em>, then this
1149 property has no effect. If the content does not fit within the
1150 <em>CSS Region</em>, the content breaks as if flow was going to
1151 continue in a subsequent region. See the <a href=
1152 "#regions-flow-breaking-rules">breaking rules</a> section. A forced region break takes precedence over
1153 a natural break point.</p>
1155 <p>Flow content that follows the last break in the last region is not rendered.</p>
1158 </dd>
1159 </dl>
1161 <p>The 'region-fragment' property does not influence
1162 the size of the region it applies to.</p>
1164 <p>The following code sample illustrates
1165 the usage of the 'region-fragment' property.</p>
1167 <div class="example">
1168 <pre>
1169 <style>
1170 article {
1171 flow-into: "article";
1172 }
1174 #region_1, #region_2 {
1175 flow-from: article;
1176 <strong>region-fragment: break;</strong> /* or auto */
1177 <strong>overflow: visible;</strong> /* or hidden */
1178 }
1180 </style>
1182 <article>...</article>
1184 <div id="region_1"></div>
1185 <div id="region_2"></div>
1187 </pre>
1188 </div>
1190 <div class="figure">
1191 <table style="border: 1px solid gray;width: 100%;" summary=
1192 "Different values for the region-fragment property - Illustration.">
1193 <tr>
1194 <td>''flow-into: "article"''</td>
1196 <td><code class="html">region_1</code> and <code class=
1197 "html">region_2</code></td>
1199 <td>''region-fragment: auto''<br>
1200 ''overflow:visible''</td>
1201 </tr>
1203 <tr>
1204 <td rowspan="3" style="vertical-align: top;"><img src=
1205 "images/region-overflow-flow.png" alt=
1206 "regions receiving the flow content"></td>
1208 <td><img src="images/region-overflow-regions.png" alt=
1209 "result if region-overflow is set to 'break'"></td>
1211 <td><img src="images/region-overflow-auto-overflow-visible.png"
1212 alt="regions receiving the flow content"></td>
1213 </tr>
1215 <tr>
1216 <td>''region-fragment: break''</td>
1218 <td>''region-fragment: auto''<br>
1219 ''overflow:hidden''</td>
1220 </tr>
1222 <tr>
1223 <td><img src="images/region-overflow-break.png" alt=
1224 "result if region-overflow is set to 'break'"></td>
1226 <td><img src="images/region-overflow-auto-overflow-hidden.png"
1227 alt="regions receiving the flow content"></td>
1228 </tr>
1229 </table>
1231 <p class="caption">Different values for the region-fragment
1232 property</p>
1233 </div>
1235 <div class="note"><span class="note-prefix">Note </span>
1236 <p>The 'overflow' property is honored on a region: if region content overflows,
1237 such as the borders of elements on the
1238 last line, the 'overflow' property controls the visibility of the overflowing
1239 content. See the 'overflow' property definition
1240 ([[CSS21]]).</p>
1241 </div>
1243 <h3 id="the-at-region-style-rule">The @region rule</h3>
1245 <p>An '@region' rule contains style declarations specific to particular
1246 regions.</p>
1248 <pre>
1249 @region <selector> {
1250 ... CSS styling rules ...
1251 }
1252 </pre>
1254 <p>The '@region' rule consists of the keyword '@region' followed by a
1255 <a href="http://www.w3.org/TR/css3-selectors/#selector-syntax">selector</a>
1256 and a block of style rules. The '@region' rule and the selector constitute
1257 the region's 'flow fragment' selector. The region's flow fragment selector
1258 specifies which range of elements in the flow are subject to the style rules in the
1259 following block: it applies to the range (see
1260 [[!DOM]]) from the region's flow that flows in the
1261 selected region(s).</p>
1263 <div class="issue-marker" data-bug_id="15713" data-bug_status="NEW">
1264 <a href=
1265 "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15713">Issue-15713</a>
1267 <div class="issue-details">
1268 <p class="short-desc">Model for styling element fragments</p>
1269 </div>
1270 </div>
1272 <p>Elements that are fully or partially in the 'flow fragment' may match any of the
1273 selectors found in the style rule. However, the style rules only apply to the
1274 portion of the element that falls into the corresponding region.</p>
1278 <p>Only a limited list of properties can be set in a region style rule:</p>
1280 <ol>
1281 <li><a href="http://www.w3.org/TR/CSS2/fonts.html">font properties</a></li>
1282 <li><a href="http://www.w3.org/TR/CSS2/colors.html">color property</a></li>
1283 <li><a href="http://www.w3.org/TR/css3-color/#transparency">opacity property</a></li>
1284 <li><a href="http://www.w3.org/TR/css3-background/#backgrounds">background property</a></li>
1285 <li><a href="http://www.w3.org/TR/CSS2/text.html#propdef-word-spacing">'word-spacing'</a></li>
1286 <li><a href="http://www.w3.org/TR/CSS2/text.html#propdef-letter-spacing">'letter-spacing'</a></li>
1287 <li><a href="http://www.w3.org/TR/CSS2/text.html#propdef-text-decoration">'text-decoration'</a></li>
1288 <li><a href="http://www.w3.org/TR/CSS2/text.html#propdef-text-transform">'text-transform'</a></li>
1289 <li><a href="http://www.w3.org/TR/CSS2/visudet.html#propdef-line-height">'line-height'</a></li>
1290 <li><a href="http://www.w3.org/TR/css3-text/#justification">alignment and justification properties</a></li>
1291 <li><a href="http://www.w3.org/TR/css3-background/#borders">border properties</a></li>
1292 <li><a href="http://www.w3.org/TR/css3-background/#corners">rounded corner properties</a></li>
1293 <li><a href="http://www.w3.org/TR/css3-background/#border-images">border images properties</a></li>
1294 <li><a href="http://www.w3.org/TR/CSS2/box.html#margin-properties">margin properties</a></li>
1295 <li><a href="http://www.w3.org/TR/CSS2/box.html#padding-properties">padding properties</a></li>
1296 <li><a href="http://www.w3.org/TR/css3-text/#text-shadow">'text-shadow' property</a></li>
1297 <li><a href="http://www.w3.org/TR/css3-background/#the-box-shadow">'box-shadow' property</a></li>
1298 <li><a href="http://www.w3.org/TR/css3-background/#the-box-decoration-break">'box-decoration-break' property</a></li>
1299 <li><a href="http://www.w3.org/TR/CSS2/visudet.html#the-width-property">'width' property</a></li>
1300 </ol>
1304 <div class="example" id="region-style-example">
1305 <p>In the following example, the <span>named flow</span> 'article_flow' flows
1306 through 'region_1' and 'region_2'.</p>
1307 <pre>
1308 <style>
1309 #div_1 {
1310 <strong>flow-into: article_flow;</strong>
1311 }
1313 #region_1, #region_2 {
1314 <strong>flow-from: article_flow;</strong>
1315 }
1317 /* region style "RSA" */
1318 <strong>@region #region_1, #region_2</strong> {
1319 div {...}
1320 p {...}
1321 }
1323 /* region style "RSB" */
1324 <strong>@region #region_1</strong> {
1325 p {...}
1326 }
1328 </style>
1330 <div id="div_1">
1331 <p id="p_1">...</p>
1332 <p id="p_2">...</p>
1333 </div>
1335 <div id="region_1"></div>
1336 <div id="region_2"></div>
1338 </pre>
1340 <div id="region_styling_illustration">
1341 <img id="region_styling_img_2" src="images/region-styling-2.png"
1342 alt=
1343 "Illustration showing how a named flow content fits into regions to illustrate the @region styling."
1344 name="region_styling_img_2">
1346 <ul class="swatch-list">
1347 <li><span class="swatch" style=
1348 "background:#1C75BC"> </span>div div_1</li>
1350 <li><span class="swatch" style=
1351 "background:crimson"> </span>paragraph p_1</li>
1353 <li><span class="swatch" style=
1354 "background:white"> </span>paragraph p_2</li>
1356 <li><span class="swatch" style=
1357 "background:#E6E7E8"> </span>range of flow that fits into
1358 region_1</li>
1360 <li><span class="swatch" style=
1361 "background:#BCBEC0"> </span>range of flow that fits into
1362 region_2</li>
1363 </ul>
1364 </div>
1366 <p>The region style ''RSA'' applies to flow content that is laid out in either
1367 'region_1' or 'region_2'.</p>
1369 <p>The first rule set ''div {...}'' applies to all <code class=
1370 "html"><div></code> elements that fit partially or fully into 'region_1' or
1371 'region_2'. <code class="html">div_1</code> is split between 'region_1' and
1372 'region_2' and gets the style from this style rule.</p>
1374 <p>The second rule set ''p {...}'' applies to all <code class=
1375 "html"><p></code> elements that fit into 'region_1' or
1376 'region_2'. In our example, both <code class="html">p_1</code>
1377 and <code class="html">p_2</code> are selected.</p>
1379 <p>The region style ''RSB'' applies to flow content that fits in
1380 'region_1'.</p>
1382 <p>The first rule set ''p {...}'' matches <code class="html">p_1</code>
1383 and <code class="html">p_2</code>
1384 because these paragraphs flow into 'region_1'. Only the fragment of
1385 <code class="html">p_2</code> that flows into <code class="html">region_1</code>
1386 is styled with this rule.</p>
1387 </div>
1391 <div class="issue-marker" data-bug_id="15734" data-bug_status="NEW">
1392 <a href=
1393 "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15734">Issue-15734</a>
1395 <div class="issue-details">
1396 <p class="short-desc">@region and specificity</p>
1397 </div>
1398 </div>
1400 <p>The specificity of the selectors in a '@region' rule is calculated as
1401 <a href="http://www.w3.org/TR/css3-selectors/#specificity">defined</a> in
1402 the CSS Selectors module (see [[SELECT]]). In other words, the '@region'
1403 rule adds an extra condition to the selector's matching, but does not
1404 change the selector's specificity. This is the same behavior as selectors
1405 appearing in '@media' rules declaration blocks (see [[MEDIAQ]]), where the
1406 rule does not influence the selectors' specificity.</p>
1408 <p>Consequently, selectors that match a given element (as describe above),
1409 participate in the <a href="http://www.w3.org/TR/2011/REC-CSS2-20110607/cascade.html#cascading-order">CSS Cascading
1410 order</a> as defined in [[!CSS21]].</p>
1412 <div>
1413 Region styling does not apply to nested regions. For example, if a region
1414 'A' receives content from a flow that contains region 'B', the content that
1415 flows into 'B' does not receive the region styling specified for region 'A'.
1416 </div>
1418 <h2 id="multi-column-regions">Multi-column regions</h2>
1420 <p>A
1421 <a href="http://dev.w3.org/csswg/css3-multicol/#multi-column-element">multi-column</a>
1422 [[CSS3COL]]
1423 element can have
1424 an assigned <em><span>named flow</span></em>.
1425 The element becomes part
1426 of the region chain
1427 for that named flow,
1428 and flows its content fragments
1429 through columns according to
1430 the multi-column specification
1431 [[!CSS3COL]].
1432 In particular,
1433 when computing the
1434 <a href="#rfcb-flow-fragment-height-resolution">flow fragment height</a>
1435 of a multi-column element
1436 that is associated with a <em><span>named flow</span></em>,
1437 the <a href="http://dev.w3.org/csswg/css3-multicol/#column-fill">'column-fill'</a>
1438 [[!CSS3COL]]
1439 property is honored
1440 to balance the fragments of content
1441 that would flow through
1442 its columns.</p>
1444 <div class="example">
1445 <p>The following example:</p>
1446 <pre>
1447 <style>
1448 #multi-col {
1449 column-count: 2;
1450 flow-from: article;
1451 height: 6em;
1452 column-gap: 1em;
1453 }
1455 #remainder {
1456 flow-from: article;
1457 height: auto;
1458 }
1459 </style>
1461 <article>...</article>
1462 <div id="multicol"></div>
1463 <div id="remainder"></div></pre>
1464 <p>is equivalent in rendering to, for example:</p>
1465 <pre>
1466 <style>
1467 #flex {
1468 display: flex;
1469 flex-pack: justify;
1470 height: 6em;
1471 }
1472 #flex > div {
1473 flow-from: article;
1474 width: calc(50% - 0.5em);
1475 }
1477 #remainder {
1478 flow-from: article;
1479 height: auto;
1480 }
1481 </style>
1483 <article>...</article>
1484 <div id="flex">
1485 <div />
1486 <div />
1487 </div>
1488 <div id="remainder"></div></pre>
1492 </div>
1494 <p>Overflow of multicol regions
1495 is mostly handled
1496 according to the same rules
1497 as other CSS Regions.
1498 If the remainder of the named flow
1499 does not fit
1500 in the multicol region,
1501 then the rest
1502 of the content flows into
1503 the remaining region chain.
1504 However,
1505 if a multicol region
1506 is the last region
1507 in a <span>region chain</span>,
1508 then the multicol region must follow the
1509 <a href="http://dev.w3.org/csswg/css3-multicol/#overflow-columns">overflow column rules</a>
1510 [[!CSS3COL]].</p>
1512 <h2 id="pseudo_elements">Pseudo-elements</h2>
1514 <div class="issue-marker" data-bug_id="15188" data-bug_status="NEW">
1515 <a href=
1516 "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15188">Issue-15188</a>
1518 <div class="issue-details">
1519 <p class="short-desc">add functionality for having textual description like "continued here" or "continued on page x" to regions.</p>
1520 </div>
1521 </div>
1523 <p>It can be useful
1524 to visually mark the content
1525 to highlight that a content thread
1526 is flowing through the region chain.
1527 For example, a marker
1528 such as <em>'continued below'</em> clearly indicates,
1529 at the end of a CSS Region,
1530 that there is more content in the flow
1531 which can be found by scrolling past
1532 whatever content interrupts the region chain.</p>
1534 <p>The '::before' and '::after' pseudo-elements (see [[!SELECT]])
1535 let content authors mark the beginning
1536 and end of a region with such markers.</p>
1538 <h3 id="processing-model">Processing model</h3>
1540 <p>The '::before' content is laid out
1541 in the region prior to
1542 any other content coming from the flow.
1543 Note that it is possible
1544 to set the '::before' pseudo-element's 'display' property
1545 to 'run-in' to align it
1546 with the content's inline boxes.</p>
1548 <p>The '::after' content is laid out
1549 in the region after laying out
1550 the flow fragment content.
1551 Then, flow content is removed from the fragment
1552 to accommodate the '::after' content.
1553 Accommodating means that the '::after' content
1554 is laid out without overflowing the region.
1555 The 'display' property of the '::after' content
1556 can be set to 'run-in' to align
1557 with the region's content's inline boxes.
1558 In that case, the '::after' content becomes
1559 the last inline box of the previous element
1560 in the flow that has some visual rendering
1561 in the region and can accommodate for the '::after' box.</p>
1563 <p>If there is not enough room to accommodate
1564 the ::before content,
1565 the '::after' content after removing all flow fragment content,
1566 or a combination of the two,
1567 then the ::before and/or ::after content overflows.</p>
1569 <h2 id="cssom_view_and_css_regions">CSSOM</h2>
1571 <div class="issue-marker-wrapper">
1572 <div class="issue-marker" data-bug_id="15679" data-bug_status="NEW">
1573 <a href=
1574 "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15679">Issue-15679</a>
1576 <div class="issue-details">
1577 <p class="short-desc">elementFromPoint and CSS regions</p>
1578 </div>
1579 </div>
1580 </div>
1581 </div>
1583 <p>Since content may flow into multiple regions, authors need a way to
1584 determine if there are enough regions to flow all the content from a named
1585 flow. This is especially important considering that the size of regions or
1586 the size of the content may change depending on the display context. For
1587 example, flowing the same content on a mobile phone with a small screen may
1588 require more regions than on a large desktop display. Another example is the
1589 user changing the font size of text flowing through regions. Depending on
1590 the change, new regions may be needed to accommodate for the additional
1591 space required to fit the larger text or some regions may need to be removed
1592 for smaller text.
1593 </p>
1595 <h3 id="the-namedflow-interface">The NamedFlow interface</h3>
1597 <p>A <span>named flow</span> is created when it becomes referenced by the
1598 'flow-into' and/or 'flow-from' computed values. The following APIs allow
1599 scripts to reference a <code class="idl">NamedFlow</code> object representation
1600 of a <span>named flow</span>.</p>
1602 <p>An additional method on the <a href=
1603 "http://www.w3.org/TR/dom/#interface-document"><code class=
1604 "idl">Document</code></a> interface provide access to <span>named flows</span>.</p>
1606 <pre class="idl">
1607 partial interface <a href=
1608 "http://www.w3.org/TR/dom/#interface-document">Document</a> {
1609 <a href="#dom-named-flow-collection">NamedFlowCollection</a> <a href="#document-getnamedflows">getNamedFlows()</a>;
1610 };
1611 </pre>
1613 <p>The <dfn id="document-getnamedflows"><code class="idl">getNamedFlows()</code></dfn> method on the <a href=
1614 "http://www.w3.org/TR/dom/#interface-document"><code class=
1615 "idl">Document</code></a> interface returns a static snapshot of all the current <span>named
1616 flows</span> in the document. </p>
1618 <p>The <code class="idl">namedFlows</code> collection must include all <span>named flows</span>
1619 that are currently in the <code>CREATED</code> state.
1620 The list must not include <span>named flows</span> that are in the <code>NULL</code> state. </p>
1622 <ul>
1623 <li><code class="idl">NULL</code>: the user agent must return <code>null</code>.</li>
1624 <li><code class="idl">CREATED</code>: the user agent must return a valid
1625 <code class="idl">NamedFlow</code> instance.</li>
1626 </ul>
1629 <p>The <dfn id="dom-named-flow-collection"><code class="idl">NamedFlowCollection</code></dfn>
1630 interface provides a list of current
1631 <code class="idl">NamedFlow</code> instances
1632 in the document.
1633 The collection is
1634 a snapshot of the data.</p>
1636 <pre class="idl">
1637 interface <a href="#dom-named-flow-collection">NamedFlowCollection</a> {
1638 readonly attribute unsigned long <a href="#dom-named-flow-collection-length">length</a>;
1639 [IndexGetter] <a href="#dom-named-flow">NamedFlow?</a> <a href="#dom-named-flow-collection-item">item</a> (unsigned long index);
1640 [NameGetter] <a href="#dom-named-flow">NamedFlow?</a> <a href="#dom-named-flow-collection-named-item">namedItem</a> (DOMString name);
1641 };</pre>
1643 <p>The <dfn id="dom-named-flow-collection-length"><code class="idl">length</code></dfn>
1644 attribute returns
1645 the number of items
1646 in the collection.</p>
1647 <p>The <dfn id="dom-named-flow-collection-item"><code class="idl">item(index)</code></dfn>
1648 method returns
1649 the <code>NamedFlow</code> instance
1650 at index <em>index</em>
1651 in the collection
1652 or <code class="idl">undefined</code>
1653 if <em>index</em> is out of range.
1654 An object <code>collection</code>
1655 implementing <code>NamedFlowCollection</code>
1656 supports indices in the range
1657 <code>0 ≤ index < collection.length</code>.</p>
1659 <p>The <dfn id="dom-named-flow-collection-named-item"><code class="idl">namedItem(name)</code></dfn>
1660 method returns the <code>NamedFlow</code> instance
1661 in the collection
1662 whose name attribute
1663 matches the supplied <em>name</em>,
1664 or <code class="idl">undefined</code>
1665 if there is no match.
1667 <p>The <dfn id="dom-named-flow"><code class="idl">NamedFlow</code></dfn>
1668 interface offers a representation
1669 of a <span>named flow</span> instance.</p>
1671 <p>The <code class="idl">NamedFlow</code> interface
1672 can be used for different purposes.
1673 For example, the <code>getRegionsByContent()</code> method
1674 can help navigate by bookmark:
1675 a script can find the <span>region</span>s
1676 that display a particular anchor
1677 and bring them to view.</p>
1679 <p>Likewise, the interface allows authors
1680 to check if all content has been fitted
1681 into existing regions.
1682 If it has, the <code>overset</code> attribute
1683 would be false.</p>
1685 <pre class="idl">
1686 interface <a href="#dom-named-flow">NamedFlow</a> : <a href="http://www.w3.org/TR/dom/#interface-eventtarget">EventTarget</a> {
1687 readonly attribute DOMString <a href="#dom-named-flow-name">name</a>;
1688 readonly attribute boolean <a href="#dom-named-flow-overset">overset</a>;
1689 sequence<<a href="#region-interface">Region</a>> <a href="#dom-named-flow-get-regions">getRegions()</a>;
1690 readonly attribute integer <a href="#dom-named-flow-first-empty-region-index">firstEmptyRegionIndex</a>;
1691 <a href="http://www.w3.org/TR/dom/#interface-nodelist">NodeList</a> <a href="#dom-named-flow-get-content">getContent()</a>;
1692 sequence<<a href="#region-interface">Region</a>> <a href="#dom-named-flow-get-regions-by-content">getRegionsByContent</a>(<a href="http://www.w3.org/TR/dom/#interface-node">Node</a> node);
1693 };</pre>
1695 <p>The <dfn id="dom-named-flow-name"><code class="idl">name</code></dfn> attribute
1696 returns the name of the <code class="idl">NamedFlow</code> instance.</p>
1698 <p>The <dfn id="dom-named-flow-overset"><code class= "idl">overset</code></dfn>
1699 attribute returns true
1700 if there are <span>named flow</span> fragments
1701 that do not fit in the associated region chain.
1702 The attribute also returns true
1703 if there is no associated region chain.
1704 Otherwise, it returns false. </p>
1706 <p>The <dfn id="dom-named-flow-get-regions"><code class="idl">getRegions()</code></dfn>
1707 method returns the sequence
1708 of regions in the <span>region chain</span>
1709 associated with the <span>named flow</span>.
1710 Note that the returned values
1711 is a static sequence
1712 in document order.</p>
1714 <p>The <dfn id="dom-named-flow-first-empty-region-index">firstEmptyRegionIndex</dfn>
1715 is the index of the first region
1716 in the region chain with the <code>regionOverset</code> attribute
1717 set to <code>empty</code>.
1718 If all regions have the <code>regionOverset</code> attribute
1719 set to <code>fit</code> or <code>overset</code>,
1720 the value for <code>firstEmptyRegionIndex</code> is <code>-1</code>.
1721 If there are no regions in the <span>region chain</span>,
1722 the value is <code>-1</code> as well. </p>
1724 <p>The <dfn id="dom-named-flow-get-content">getContent()</dfn>
1725 method returns an ordered collection
1726 of nodes that constitute the <span>named flow</span>.
1727 The returned list is a static snapshot
1728 of the <span>named flow</span> content
1729 at the time the method is invoked.
1730 This list contains the elements
1731 that were moved to the <span>named flow</span>
1732 by their flow-into property
1733 but not their descendants
1734 (unless the descendants are themselves
1735 moved to the <span>named flow</span>).
1736 </p>
1738 <p>The <dfn id="dom-named-flow-get-regions-by-content">getRegionsByContent()</dfn>
1739 method returns the sequence of regions
1740 that contain at least part
1741 of the target content node if it belongs to the <span>named flow</span> directly
1742 (i.e., its 'flow-into' computed value is the <span>named flow</span>) or one of its
1743 ancestors belongs to the <span>named flow</span>. Otherwise, the method returns an
1744 empty sequence. The returned value
1745 is a static sequence in document order.</p>
1748 <p>The <span>named flow</span> states are :</p>
1750 <ul>
1751 <li><code class="idl">NULL</code>: the <span>named flow</span> is not referenced
1752 by any 'flow-into' or 'flow-from' computed value.</li>
1753 <li><code class="idl">CREATED</code>: the <span>named flow</span> is referenced by
1754 at least one 'flow-into' or 'flow-from' computed value.</li>
1755 </ul>
1757 <p>A <code class="idl">NamedFlow</code>
1758 object is live: it always represents the <span>named flow</span> with the corresponding
1759 name even if that <span>named flow</span> has transitioned to the <code>NULL</code> state.</p>
1761 <p>If a script holds a reference to a <code class="idl">NamedFlow</code> instance that
1762 has entered the <code>NULL</code> state, its attributes and methods should behave
1763 as follows:</p>
1765 <ul>
1766 <li>the <code class="idl">name</code> attribute returns its value as normal.</li>
1767 <li>the <code class="idl">overset</code> attribute returns <code class="idl">false</code>.</li>
1768 <li>the <code class="idl">getRegions</code> method returns an empty sequence.</li>
1769 <li>the <code class="idl">firstEmptyRegionIndex</code> attribute returns <code class="idl">-1</code>.</li>
1770 <li>the <code class="idl">getContent()</code> method returns an empty <code class="idl">NodeList</code> instance.</li>
1771 <li>the <code class="idl">getRegionsByContent()</code> method retuns an empty sequence.</li>
1772 </ul>
1774 <h3 id="the-region-interface">The Region interface</h3>
1776 <p>The <dfn id='region-interface'>
1777 <code class="idl">Region</code>
1778 interface</dfn> is a
1779 <a href="http://www.w3.org/TR/WebIDL/#idl-implements-statements">supplemental interface</a>
1780 which must be implemented by all objects
1781 (<a href="http://www.w3.org/TR/dom/#interface-element">
1782 <code class= "idl">Elements</code></a>,
1783 pseudo-elements or other CSS constructs
1784 such as <a href="http://dev.w3.org/csswg/css3-page-template/#templates-and-slots">slots</a>) in an implementation which can be CSS Regions.</p>
1786 <pre class="idl">
1787 [NoInterfaceObject]
1788 interface <a href="#region-interface">Region</a> {
1789 readonly attribute DOMString <a href="#dom-region-regionoverset">regionOverset</a>;
1790 sequence<<a href="#">Range</a>>? <a href=
1791 "#dom-region-getregionflowranges">getRegionFlowRanges()</a>;
1792 <a href="http://dev.w3.org/csswg/cssom/#the-cssstyledeclaration-interface">CSSStyleDeclaration</a> <a href="#dom-region-getComputedRegionStyle">getComputedRegionStyle</a>(Element elt);
1793 <a href="http://dev.w3.org/csswg/cssom/#the-cssstyledeclaration-interface">CSSStyleDeclaration</a> <a href="#dom-region-getComputedRegionStyle">getComputedRegionStyle</a>(Element elt, DOMString pseudoElt);
1794 };
1796 Element implements Region;</pre>
1798 <p>The <dfn id="dom-region-regionoverset"><code class=
1799 "idl">regionOverset</code></dfn> attribute returns one of the following
1800 values:</p>
1802 <dl>
1803 <dt>'overset'</dt>
1805 <dd>The region is the last one in the
1806 <span title="region-chain">region chain</span> and
1807 not able to fit the remaining content from the <span>named flow</span>.
1808 Note that the region's <a href=
1809 "http://www.w3.org/TR/CSS21/visufx.html#overflow"><code class=
1810 "idl">overflow</code></a> property value can be used to control the
1811 visibility of the overflowing content and the
1812 'region-fragment' property controls whether or not fragmentation happens
1813 on the content that overflows the last region.</dd>
1815 <dt>'fit'</dt>
1817 <dd>The region's flow fragment content
1818 fits into the region's
1819 <a href="http://www.w3.org/TR/CSS21/box.html#box-dimensions">content box</a>.
1820 If the region is the last one
1821 in the <span title="region-chain">region chain</span>,
1822 it means that the content
1823 fits without overflowing.
1824 If the region is not the last one
1825 in the region chain,
1826 that means the <span>named flow</span> content
1827 is further fitted in subsequent regions.
1828 In this last case,
1829 note that the <span>named flow</span> fragment may be empty
1830 (for example if the region is too small
1831 to accommodate any content).
1832 This value is returned if the <span>region</span> object
1833 is not (or no longer) a region.</dd>
1835 <dt>'empty'</dt>
1837 <dd>All content from the <span>named flow</span> was fitted in prior regions.</dd>
1839 </dl>
1841 <p>Note that if there is no content in the <span>named flow</span>, all regions associated
1842 with that <span>named flow</span> should have their <code class="idl">regionOverset</code>
1843 attribute return 'empty'.
1844 If there is content in the flow but that content does not generate any box
1845 for visual formatting, the 'overset' attribute on the first region in the
1846 region chain associated with the flow will return 'fit'.</p>
1848 <p>The <dfn id="dom-region-getregionflowranges">getRegionFlowRanges</dfn> method
1849 returns an array of <a href= "http://www.w3.org/TR/dom/#interface-range">Range</a>
1850 instances corresponding to fragment
1851 from the <span>named flow</span>
1852 that is laid out in the region.
1853 If the region has not received a fragment
1854 because it is too small to accommodate any,
1855 the method returns a single <code class="idl">Range</code>
1856 where the <code>startContainer</code>
1857 and <code>startOffset</code>
1858 have the same values as
1859 the <code>endContainer</code>
1860 and <code>endOffset</code>
1861 and therefore the collapsed attribute
1862 on the <code class="idl">Range</code> is true.
1863 In that situation,
1864 if the region is the first
1865 in the <span>region chain</span>,
1866 the <code>startContainer</code>
1867 is the first <code>Node</code>
1868 in the <span>named flow</span>
1869 and the <code>startOffset</code> is zero.
1870 If the region is the last region
1871 in the region chain
1872 (but not the first and only one),
1873 the <code>startContainer</code>
1874 and <code>startOffset</code>
1875 are the same values as
1876 the <code>endContainer</code>
1877 and <code>endOffset</code>
1878 on the previous region
1879 in the <span>region chain</span>.
1880 The method returns null
1881 if the <span>region</span> object
1882 is not (or no longer) a region.</p>
1884 <p>The <dfn id="dom-region-getComputedRegionStyle">getComputedRegionStyle</dfn>
1885 methods on the Region interface work the same as the
1886 <a href="http://dev.w3.org/csswg/cssom/#extensions-to-the-window-interface"><code class="idl">getComputedStyle</code></a> [[!CSSOM]]
1887 methods on the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#window"><code class="idl">Window</code></a>
1888 interface [[!HTML5]] with the following exceptions.
1889 For the <code class="idl">Region</code> interface
1890 the <a href="http://dev.w3.org/csswg/cssom/#the-cssstyledeclaration-interface">CSSStyleDeclaration</a>
1891 returned must include the result of
1892 <a href="#the-at-region-style-rule">region styling</a>.
1893 If the element is fragmented across region boundaries,
1894 the <a href="http://dev.w3.org/csswg/cssom/#the-cssstyledeclaration-interface">CSSStyleDeclaration</a> returned must apply only
1895 to the fragment that flows through
1896 the <span>CSS Region</span>.
1897 The method returns null
1898 if the <span>region</span> object
1899 is not (or no longer) a region.</p>
1901 <div class="note">
1902 <p>If the element is not contained
1903 in the <span>CSS Region</span> at all,
1904 the method returns
1905 the <a href="#the-at-region-style-rule">region styling</a>
1906 that would apply to the element
1907 if it were contained in the <span>CSS Region</span>
1908 (following how <a href="http://dev.w3.org/csswg/cssom/#extensions-to-the-window-interface"><code class="idl">getComputedStyle</code></a> works
1909 with elements not contained
1910 in the window's document).</p>
1911 </div>
1913 <p>A <code class="idl">Region</code> instance
1914 may represent an object
1915 that is no longer a <span>region</span>.
1916 This may happen for example
1917 if the 'flow-from' property
1918 on the corresponding pseudo-element,
1919 element or other construct
1920 becomes 'none'
1921 but a script is still holding
1922 a reference to the <code class="idl">Region</code> object.</p>
1924 <h3 id="region-style-rule-interface">The CSSRegionStyleRule interface</h3>
1926 <p>The <dfn id='dom-region-style-rule-interface'>
1927 <code class="idl">CSSRegionStyleRule</code>
1928 interface</dfn> represents
1929 an '@region' rule
1930 in a CSS style sheet.
1931 This rule type is added
1932 to the <a href="http://dev.w3.org/csswg/cssom/#the-cssrule-interface"><code>CSSRule</code></a> [[!CSSOM]] interface.</p>
1934 <pre class="idl">
1935 partial interface <a href="http://dev.w3.org/csswg/cssom/#the-cssrule-interface">CSSRule</a> {
1936 const unsigned short <a href="#region-style-rule-const">REGION_STYLE_RULE</a> = 16;
1937 };
1938 </pre>
1939 <dl>
1940 <dt><dfn id="region-style-rule-const">REGION_STYLE_RULE</dfn></dt>
1941 <dd>The rule is a CSSRegionStyleRule</dd>
1942 </dl>
1943 <pre class="idl">
1944 interface <a href="#dom-region-style-rule-interface">CSSRegionStyleRule</a> : <a href="http://dev.w3.org/csswg/cssom/#the-cssrule-interface">CSSRule</a> {
1945 attribute DOMString <a href="#region-style-rule-selectorText">selectorText</a>;
1946 readonly attribute <a href="http://dev.w3.org/csswg/cssom/#the-cssrulelist-sequence">CSSRuleList</a> <a href="#region-style-rule-cssRules">cssRules</a>;
1947 unsigned long <a href="#region-style-rule-insertRule">insertRule</a>(DOMString rule, unsigned long index)
1948 raises(<a href="http://www.w3.org/TR/dom/#exception-domexception">DOMException</a>);
1949 void <a href="#region-style-rule-deleteRule">deleteRule</a>(unsigned long index)
1950 raises(<a href="http://www.w3.org/TR/dom/#exception-domexception">DOMException</a>);
1951 };
1952 </pre>
1954 <p>The <dfn id="region-style-rule-selectorText">
1955 <code class="idl">selectorText</code></dfn>
1956 attribute gets and sets
1957 the associated selector
1958 as defined in section <a href="http://dev.w3.org/csswg/cssom/#widl-CSSStyleRule-selectorText">6.4.3</a> of [[!CSSOM]].
1960 <p>The <dfn id="region-style-rule-cssRules">
1961 <code class="idl">cssRules</code></dfn>
1962 attribute must return a
1963 <a href="http://dev.w3.org/csswg/cssom/#the-cssrulelist-sequence"><code>CSSRuleList</code></a> [[!CSSOM]]
1964 object for the list of
1965 <a href="http://www.w3.org/TR/DOM-Level-2-Style/css.html#CSS-CSSStyleRule"><code class="idl">CSSStyleRules</code></a>
1966 specified in the region style block.</p>
1968 <p>The <dfn id="region-style-rule-insertRule">
1969 <code class="idl">insertRule(rule, index)</code></dfn>
1970 method inserts a
1971 <a href="http://www.w3.org/TR/DOM-Level-2-Style/css.html#CSS-CSSStyleRule"><code class="idl">CSSStyleRule</code></a>
1972 into the region style block
1973 before the specified index.
1974 If the index is equal to the length
1975 of the <a href="http://dev.w3.org/csswg/cssom/#the-cssrulelist-sequence"><code>CSSRuleList</code></a> the
1976 <a href="http://www.w3.org/TR/DOM-Level-2-Style/css.html#CSS-CSSStyleRule"><code class="idl">CSSStyleRule</code></a>
1977 is inserted at the end of the list.</p>
1979 <p>Possible exceptions:</p>
1980 <ul>
1981 <li><a href="http://www.w3.org/TR/dom/#dom-domexception-hierarchy_request_err"><code class="idl">HIERARCHY_REQUEST_ERR</code></a>:
1982 Raised if the rule to insert is not a
1983 <a href="http://www.w3.org/TR/DOM-Level-2-Style/css.html#CSS-CSSStyleRule"><code class="idl">CSSStyleRule</code></a>.</li>
1984 <li><a href="http://www.w3.org/TR/dom/#dom-domexception-index_size_err"><code class="idl">INDEX_SIZE_ERR</code></a>:
1985 Raised if the specified index
1986 is not a valid insertion point.</li>
1987 <li><a href="http://www.w3.org/TR/dom/#dom-domexception-syntax_err"><code class="idl">SYNTAX_ERR</code></a>:
1988 Raised if the specified rule
1989 has a syntax error
1990 and is unparsable.</li>
1991 </ul>
1992 <p>The <dfn id="region-style-rule-deleteRule">
1993 <code class="idl">deleteRule(index)</code></dfn>
1994 method deletes the <a href="http://www.w3.org/TR/DOM-Level-2-Style/css.html#CSS-CSSStyleRule"><code class="idl">CSSStyleRule</code></a>
1995 in the <a href="http://dev.w3.org/csswg/cssom/#the-cssrulelist-sequence"><code>CSSRuleList</code></a>
1996 at the specified index.</p>
1998 <p>Possible exception:</p>
1999 <ul>
2000 <li><a href="http://www.w3.org/TR/dom/#dom-domexception-index_size_err"><code class="idl">INDEX_SIZE_ERR</code></a>:
2001 Raised if the specified index
2002 does not correspond to a rule
2003 in the region style block.</li>
2004 </ul>
2006 <h3 id="region-flow-layout-events">Region flow layout events</h3>
2008 <p><a href="#dom-named-flow"><code class="idl">NamedFlow</code></a>
2009 objects are <a href="http://www.w3.org/TR/dom/#interface-eventtarget">EventTargets</a>
2010 which dispatch <code class="idl">regionLayoutUpdate</code> events
2011 when there is a possible layout change
2012 in their region chain.
2013 The event is asynchronous,
2014 and fires in the same step of the
2015 <a href="http://www.w3.org/TR/html5/webappapis.html#processing-model-2">event loop</a>
2016 [[!HTML5]] as when
2017 <a href="http://www.w3.org/TR/2012/WD-dom-20120405/#mutation-observers">MutationObservers</a>
2018 [[!DOM]] are invoked.</p>
2019 <p>If region chain nesting occurs
2020 (the contents of a <a href="#dom-named-flow"><code class="idl">NamedFlow</code></a>
2021 contains regions
2022 for a different <a href="#dom-named-flow"><code class="idl">NamedFlow</code></a>)
2023 then the <code class="idl">regionLayoutUpdate</code> event
2024 for the nested flow(s)
2025 must be dispatched
2026 before the <code class="idl">regionLayoutUpdate</code> event
2027 for the containing flow
2028 is dispatched.</p>
2030 <table class="event-desc" border="0" summary="This table contains information about the semantics of the given event type" cellpadding="2" cellspacing="0">
2031 <tbody><tr class="assert must"><th>Type</th>
2032 <td class="eventname"><strong><code>regionLayoutUpdate</code></strong></td></tr>
2033 <tr class="assert must"><th>Interface</th> <td><code><a href="http://www.w3.org/TR/DOM-Level-3-Events/#events-UIEvent">UIEvent</a></code> (see [[!DOM-LEVEL-3-EVENTS]])</td></tr>
2034 <tr class="assert must"><th>Sync / Async</th> <td>Async</td></tr>
2035 <tr class="assert must"><th>Bubbles</th> <td>No</td></tr>
2036 <tr class="assert must"><th>Target</th> <td><a href="#dom-named-flow"><code class="idl">NamedFlow</code></a></td></tr>
2037 <tr class="assert must"><th>Cancelable</th> <td>Yes</td></tr>
2038 <tr class="assert must"><th>Default action</th> <td>none</td></tr>
2039 <tr class="assert must"><th>Context info</th>
2040 <td>
2041 <ul>
2042 <li><code class="attribute-name">Event.target</code>:
2043 <a href="#dom-named-flow"><code class="idl">NamedFlow</code></a> whose layout may have changed</li>
2044 </ul>
2045 </td>
2046 </tr>
2047 </tbody></table>
2049 <h3 id="cssomview-and-regions">Clarifications on pre-existing APIs</h3>
2052 <h4 id="cssomview-getclientrects-and-getboundingclientrect"><code class="idl">getClientRects()</code> and <code>getBoundingClientRects()</code></h4>
2054 <p>The <a href="http://www.w3.org/TR/cssom-view/">CSSOM View Module</a>
2055 defines how user agents compute
2056 the bounding client rectangle
2057 for an element (<code class="idl">getBoundingClientRect()</code>)
2058 and its generated boxes (<code class="idl">getClientRects()</code>).</p>
2060 <p>This definition applies to
2061 the (possibly) multiple boxes
2062 generated for an element in a named flow
2063 flowing through a region chain.
2064 The <code class="idl">getClientRects()</code> method
2065 returns the list of boxes generated
2066 for each of the element fragments
2067 laid out in different regions.
2068 The <code>getBoundingClientRect()</code> method
2069 operates as specified in the
2070 <a href="http://www.w3.org/TR/cssom-view/">CSSOM View Module</a>
2071 as well and is computed
2072 from the set of rectangles
2073 returned by <code class="idl">getClientRects()</code>.</p>
2075 <h4 id="cssomview-offset-attributes"><code class="idl">offsetTop</code>, <code class="idl">offsetLeft</code>,
2076 <code class="idl">offsetWidth</code> and <code class="idl">offsetWidth</code></h4>
2078 <p>The computation of the <a href="http://dev.w3.org/csswg/cssom-view/#extensions-to-the-htmlelement-interface">offset attributes</a>
2079 for elements laid out in a <span>named flow</span> follow the <a href="http://dev.w3.org/csswg/cssom-view/#extensions-to-the-htmlelement-interface">specification</a> [[!CSSOM]]. For the purpose of the
2080 algorithm, the <em>first CSS layout box</em> associated
2081 with an element laid out in a <span>named flow</span> is the box generated for the first region
2082 the element is laid out into.</p>
2084 <h2 id="regions-visual-formatting-details">Regions visual formatting details</h2>
2086 <p>Regions are laid out by CSS and take part in the normal box model and other layout models
2087 offered by CSS modules such as flexible boxes ([[CSS3-FLEXBOX]]). However, <span>regions</span>
2088 lay out a fragment of their <span>named flow</span> instead of laying out descendant content as happens with other
2089 boxes.</p>
2091 <p>This section describes the model for laying out <span>regions</span>
2092 and for laying out <span>named flow</span> content into regions.
2093 The descriptions in this section are biased towards a horizontal writing mode,
2094 using <span>width</span> for logical width (or measure)
2095 and <span>height</span> for logical height (or extent)
2096 as <a href="http://www.w3.org/TR/css3-writing-modes/#abstract-dimensions">defined</a>
2097 in the CSS Writing Modes Module [[!CSS3-WRITING-MODES]]).
2098 To use this model in a vertical writing mode apply the principles
2099 <a href="http://www.w3.org/TR/css3-writing-modes/#vertical-layout">described</a>
2100 in that specification.</p>
2102 <h3 id="regions-flow-content-box">The Region Flow Content Box (RFBC)</h3>
2104 <p>A region box lays out the following boxes:</p>
2106 <ul>
2107 <li>The boxes generated by its <code class="css">::before</code> and
2108 <code class="css">::after</code> pseudo-elements, if any.</li>
2109 <li>The anonymous <dfn>region flow content box</dfn> (called <dfn>RFCB</dfn> in this document) which
2110 contains the fragment of the <span>named flow</span> that the region receives.</li>
2111 </ul>
2113 <div class="figure">
2114 <img src="images/RFCB.svg" width="600px" alt="The ::before, RFCB and ::after boxes contained in the Region Box"/>
2115 <p class="caption">The Region Flow Content Box (RFCB)</p>
2116 </div>
2118 <p>Laying out a <span>region</span> box follows the same processing rules as for any other
2119 <a href="http://www.w3.org/TR/CSS2/visuren.html#block-boxes">block container box</a>.</p>
2121 <p>The <span>RFCB</span> is a <a href="http://www.w3.org/TR/CSS21/visuren.html#block-boxes">block container box</a>
2122 with a <a href="">computed</a> 'width' of 'auto' and a whose <a href="">used</a> 'height' is
2123 resolved as detailed below.</p>
2125 <h4 id="rfbc-width-resolution">RFCB 'width' resolution</h4>
2127 <p>At various points in the visual formatting of documents containing regions, the
2128 used 'width' of RFCBs and regions need to be resolved. In all cases, the resolution is done following the
2129 rules for <a href="http://www.w3.org/TR/CSS2/visudet.html#Computing_widths_and_margins">calculating
2130 widths and margins</a> (see [[!CSS21]]). Sometimes, resolving the used 'width' value
2131 requires measuring the content's
2132 <code class="css">min-content</code> and <code class="css">max-content</code> values (as
2133 <a href="http://www.w3.org/TR/css3-writing-modes/#intrinsic-sizing">defined</a> in the CSS Writing Modes Module [[!CSS3-WRITING-MODES]]). For an RFCB, <strong>these measures are
2134 made on the <em>entire</em> associated <span>named flow</span> content</strong>.</p>
2136 <p>As a consequence, all <span>RFCBs</span> of <span>regions</span> associated with a given
2137 <span>named flow</span> share the
2138 same <code class="css">min-content</code> and <code class="css">max-content</code> measures.</p>
2140 <p>This approach is consistent with the <a href="http://www.w3.org/TR/css3-break/#varying-size-boxes">box model for breaking</a> ([[!CSS3-BREAK]]).</p>
2143 <h3 id="regions-visual-formatting-steps">Regions visual formatting steps</h3>
2145 <p>Formatting documents that contain <span>named flows</span> laid out in regions is a three-step
2146 process:</p>
2148 <ul>
2149 <li><em>Step 1: RFCB <dfn>flow fragment height</dfn> resolution</em>. In this step, the heights of fragments
2150 fitting in the regions' RFCBs are resolved.</li>
2151 <li><em>Step 2: document and regions layout</em>. In this step, the document content and regions are
2152 laid out. However, <span>named flow</span> content is not laid out in regions yet.</li>
2153 <li><em>Step 3: <span>named flow</span> layout</em>. In this step, the content of <span>named flows</span> is laid
2154 out in their respective <span>region chains</span>.</li>
2155 </ul>
2157 <div class="figure">
2158 <img src="images/regions-layout-three-steps.svg" width="600px" alt="visual representation of the three-step process"/>
2159 <p class="caption">Regions visual formatting steps</p>
2160 </div>
2163 <h4 id="rfcb-flow-fragment-height-resolution">Step 1: RFCB flow fragment height resolution</h4>
2165 <p>Conceptually, resolving the flow fragment height is a two phase process.</p>
2167 <h5 id="rfcb-flow-fragment-height-resolution-phase-1">RFCB flow fragment height resolution, Phase 1</h5>
2169 <p>The document is laid out with a
2170 <a href="http://www.w3.org/TR/CSS2/cascade.html#used-value">used</a> height of zero
2171 for all <span>RFCB</span>s. In this phase, the content of <span>named flows</span> is not laid out in
2172 <span>regions</span>. This phase yields resolved position and sizes for all regions and
2173 their RFCBs in the document.</p>
2175 <h5 id="rfcb-flow-fragment-height-resolution-phase-2">RFCB flow fragment height resolution, Phase 2</h5>
2177 <p><span>Named flows</span> are laid out in <span>regions</span>. The
2178 user agent resolves the <em><span>flow fragment height</span></em> for
2179 the <span>RFCB</span>s using the remainder of the flow and accounting for
2180 <a href="http://www.w3.org/TR/css3-break/">fragmentation rules</a>.
2181 This process accounts for constraints such as the 'height' or 'max-height' values, as described
2182 in the CSS 2.1 section on
2183 <a href="http://www.w3.org/TR/CSS2/visudet.html#Computing_heights_and_margins">calculating heights
2184 and margins</a> (see the <a href="http://www.w3.org/TR/CSS2/visudet.html#normal-block">Block-level
2185 non-replaced elements in normal flow when 'overflow' computes to 'visible'</a> section and the
2186 <a href="http://www.w3.org/TR/CSS2/visudet.html#block-root-margin">complicated cases</a> section).
2187 During this phase, generated content is laid out according to the
2188 <a href="#processing-model">rules</a> described earlier in this document.
2189 </p>
2191 <h4 id="regions-boxes-layout">Step 2: region boxes layout</h4>
2193 <p>In this step, the document is laid out according to the normal CSS layout rules.</p>
2195 <p>If a measure of the content is required to resolve the used 'width' of the region box, the value
2196 is resolved as described in the
2197 <a href="#rfbc-width-resolution">RFCB width resolution</a> section.</p>
2199 <p>If a measure of the content
2200 is required to resolve the used height of the RFCB (for example if the region box is absolutely positioned),
2201 the <span>flow fragment height</span> resolved in Step 1 is used for the vertical content measure of the
2202 RFCB.</p>
2204 <p>At the end of this step, regions are laid out and ready to receive
2205 content from their associated <span>named flows</span>.</p>
2207 <h4 id="named-flows-layout">Step 3: named flows layout</h4>
2209 <p>In this final step, the content of <span>named flows</span> is laid out in the <span>regions</span>' RFCBs
2210 along with the generated content boxes.</p>
2212 <p>The used 'width' for RFCBs is resolved <a href="#rfbc-width-resolution">as described before</a>.</p>
2214 <p>The used 'height' of RFCBs is resolved such that none of the boxes in the region box's normal flow
2215 overflow the region's box. In other words, the RFCB boxes are stretched vertically
2216 to accommodate as much of the flow as possible without overflowing the region box and
2217 accounting for <a href="http://www.w3.org/TR/css3-break/">fragmentation rules</a> and
2218 generated content boxes.</p>
2220 <p>During this phase, generated content is laid out according to the
2221 <a href="#processing-model">rules</a>
2222 described earlier in this document.</p>
2224 <div class="note">
2225 <p>The model for resolving auto sized regions will cause, under certain circumstances,
2226 the flow content to be overset or underset. In other words, it will not fit tightly.
2227 The model prevents having circular dependencies in the layout model. Implementations
2228 may decide to apply further layout steps to ensure that the whole flow content is
2229 displayed to the user, even in edge cases.</p>
2230 </div>
2232 <h3 id="regions-visual-formatting-implementation-note">Regions visual formatting: implementation note</h3>
2234 <p>The process for resolving an RFCB's 'height' and the three-step process used to
2235 lay out documents containing regions and <span>named flows</span> are
2236 <em>conceptual</em> descriptions of what the layout
2237 should yield and implementations should optimize to reduce the number of
2238 steps and phases necessary wherever possible.</p>
2240 <h3 id="regions-visual-formatting-examples">Regions visual formatting example</h3>
2242 <p>This section is non-normative.</p>
2244 <p>This example considers a document where content flows between three regions,
2245 and region boxes are intermixed with the normal document content.</p>
2247 <div class="example">
2248 <pre>
2249 <style>
2250 article {
2251 flow-into: article;
2252 }
2254 #rA, #rB, #rC {
2255 flow-from: article;
2256 height: auto;
2257 margin: 1em 1em 0em 1em;
2258 padding: 1em;
2259 border: 3px solid #46A4E9;
2260 }
2262 #rA {
2263 width: auto;
2264 height: auto;
2265 }
2267 #rB {
2268 float: left;
2269 width: 15em;
2270 height: auto;
2271 max-height: 150px;
2272 }
2274 #rC {
2275 float: right;
2276 width: 12em;
2277 height: auto;
2278 }
2280 #main-flow {
2281 padding: 0em 1em 0em 1em;
2282 }
2284 </style>
2285 <body>
2286 <article>
2287 <p style="break-after:region;">I am not a ... </p>
2288 <p>...</p>
2289 </article>
2290 <div id="rA"></div>
2291 <div id="rB"></div>
2292 <div id="rC"></div>
2294 <div id="main-flow">
2295 <p>Lorem ipsum dolor ...</p>
2296 </div>
2297 </body>
2298 </pre>
2299 </div>
2301 <p>The following sections and figures illustrate the intermediate results for the visual formatting process.
2302 In the following, we call RFCB-A, RFCB-B and RFCB-C the <span>RFCBs</span> for
2303 regions rA, rB and rC respectively. </p>
2305 <h4>Step 1 - Phase 1: Laying out RFCBs with used height of zero</h4>
2307 <p>Applying the rules for Step 1, Phase 1, the computed 'auto' 'width' values for the RFCBs are resolved
2308 to used values according to the normal
2309 <a href="http://www.w3.org/TR/CSS2/visudet.html#Computing_widths_and_margins">CSS layout rules</a> meaning they
2310 stretch to the width of their containing block's content box.</p>
2312 <ol>
2313 <li>RFCB-A: stretches to fit the rA content box.
2314 <p>Since rA also has an 'auto' 'width', its own used 'width' is stretched to fit the
2315 <code><body></code> content box.</p></li>
2316 <li>RFCB-B: stretches to fit the <code>rB</code> content box.</li>
2317 <li>RFCB-C: stretches to fit the <code>rC</code> content box.</li>
2318 </ol>
2320 <p>Also applying the rules for Step 1, Phase 1, the used values for the RFCBs 'height' properties are all zero.</p>
2322 <p>Conceptually, this produces the layout illustrated below.</p>
2324 <div class="figure">
2325 <img src="images/flow-fragment-height-phase-1.png" width="500px" alt="Step 1 - Phase 1: Layout RFBCs with used heights of 0"/>
2326 <p class="caption">Step 1 - Phase 1: Layout RFBCs with used heights of 0</p>
2327 </div>
2329 <h4>Step 1 - Phase 2: Layout flow to compute the RFCBs' flow fragments heights</h4>
2331 <p>In this second phase of Step 1, the named flow is laid out in <span>regions</span>
2332 and the height of each fragment falling in each RFCB is computed.</p>
2334 <p>The user agent lays out as much of the flow into an area
2335 with RFCB-A's used 'width'. rA's 'height' computes to 'auto' and there is no vertical maximum
2336 height for RFCA's 'height'. However, because there is a break after the
2337 first paragraph in the 'article' <code>named flow</code>, only this first paragraph is
2338 laid out in RFCB-A and FH-A (the flow fragment height for RFCB-A) is resolved by laying out
2339 this first paragraph in the used 'width'.</p>
2341 <p>At this point, the user agent lays out as much of the remaining flow as possible in RFCB-B.
2342 Because rB's 'max-height' computed value is '150px', the user agent only lays out
2343 the 'article' named flow using RFCB-B's used 'width' until the point where
2344 laying out additional content would cause RFCB-B to overflow rB's box.
2345 The fragment height for RFCB-B is resolved: FH-B (<code class="css">150px</code>).</p>
2347 <p>Finally, the user agent lays out the remainder of the flow in RFCB-C.
2348 Because rC has no other constraints and no region breaks, the remaining content is
2349 laid out in RFCB-C's used 'width'. This results in a resolved flow fragment height: FH-C.</p>
2351 <div class="figure">
2352 <img src="images/flow-fragment-height-phase-2.png" width="370px" alt="Step 1 - Phase 2: Measure flow fragments heights"/>
2353 <p class="caption">Step 1 - Phase 2: Measure flow fragments heights</p>
2354 </div>
2356 <h4>Step 2: Layout document and regions without named flows</h4>
2358 <p>The used 'width' of RFCB-A, RFCB-B and RFCB-C are resolved as in the previous step. However, the
2359 'height' is resolved differently.</p>
2361 <p>Resolving the 'height' of rA <a href="http://www.w3.org/TR/CSS2/visudet.html#normal-block">requires a content measure</a>
2362 which is FH-A (the flow fragment height for RFCB-A).</p>
2364 <p>The 'height' of rB results from first computing its
2365 <a href="http://www.w3.org/TR/CSS2/visudet.html#block-root-margin">content measure</a> and then applying the
2366 <a href="http://www.w3.org/TR/CSS2/visudet.html#min-max-heights">rules for 'max-height'</a>. Here, the
2367 vertical content measure evaluates to FH-B. After applying the
2368 rules for 'max-height' and accounting for margins, padding and borders, the used 'height' of rB
2369 is resolved to LH-B (<code class="css">150px</code>).</p>
2371 <p>The 'height' of rC's box results from
2372 <a href="http://www.w3.org/TR/CSS2/visudet.html#block-root-margin">calculating
2373 its content measure</a>: FH-C becomes rC's used 'height'.</p>
2375 <div class="figure">
2376 <img src="images/regions-visual-formatting-step-2.png" width="370px" alt="Step 2: Layout document and regions without named flows"/>
2377 <p class="caption">Step 2: Layout document and regions without <span>named flows</span></p>
2378 </div>
2380 <h4>Step 3: named flows layout</h4>
2382 <p>In this final step, the <code class="css">article</code> <span>named flow</span> is laid out in its
2383 <span>region chain</span>. The used 'width' for each of the RFCB is resolved as in step 1 above.</p>
2385 <p>The used 'height' for the RFCB is a result of laying out the as much of the content in the
2386 <span>region</span> without overflowing its content box and following the
2387 <a href="http://www.w3.org/TR/css3-break/">fragmentation rules</a>.</p>
2389 <p>Because the computed 'width' of the RFCB has not changed and the fragmentation rules applied are
2390 the same as in Phase 1, Step 2, the used 'height' for RFCB-A, RFCB-B and RFCB-C are
2391 LH-A, LH-B and LH-C, respectively.</p>
2393 <p>There may be situations where the used 'height' of RFCBs resolved in Step 3 are different from the
2394 <span>flow fragment height</span> computed in Step 1 Phase 2.</p>
2396 <div class="figure">
2397 <img src="images/regions-visual-formatting-step-3.png" width="370px" alt="Step 3: Final result after laying out named flows in regions"/>
2398 <p class="caption">Step 3: Final result after laying out named flows in regions</p>
2399 </div>
2402 <h2 id="relation-to-document-events">Relation to document events</h2>
2404 <p>The CSS regions module does not alter the normal processing of
2405 events in the document tree. In particular, if an event occurs on an
2406 element that is part of a <span>named flow</span>, the <a href=
2407 "http://www.w3.org/TR/dom/#events">event's
2408 bubble and capture phases</a> happen following the document tree order.</p>
2411 <h2 id="relation-to-other-specifications">Relation to other
2412 specifications</h2>
2414 <p>This specification is related to other specifications as described in
2415 the <a href='#references'>references</a> section. In addition, it is
2416 related to the following specifications:</p>
2418 <ol>
2419 <li>CSS Fragmentation Module Level 3 [[CSS3-BREAK]]. This module defines the
2420 rules for fragmenting content over multiple containers and applies to
2421 CSS regions in addition to applying to multi-column and paged media.</li>
2423 <li>CSS Pagination Templates Module Level 3 [[CSS3-PAGE-TEMPLATE]]. This module
2424 defines a syntax to define layout templates which can be used
2425 when paginating content. The page templates use regions.</li>
2427 <li>CSS Exclusions Module [[CSS3-EXCLUSIONS]]. This module defines a
2428 generic way to define arbitrarily shaped exclusions into which content
2429 can flow or around which content can flow. This can be seen as an
2430 extension to the way CSS floats provide rectangular areas into which
2431 content flows and around which content flows. In advanced layout
2432 designs, it is expected that the CSS Exclusions module will be commonly
2433 combined with the CSS regions module.</li>
2435 <li>CSS Line Grid Module [[CSS3-LINE-GRID]]. This module defines a
2436 concept of line grid to align the position of lines in different
2437 elements. The line grid functionality is related and needed for
2438 aligning content flowing in separate regions.</li>
2439 </ol>
2441 <h2 id="usecases">Use Cases</h2>
2443 <p>Use cases are described on
2444 <a href="http://wiki.csswg.org/spec/css3-regions/regions-use-cases">these</a>
2445 <a href="http://wiki.csswg.org/spec/css3-regions/regions-print-use-cases">pages</a>.</p>
2447 <h2 id="conformance">Conformance</h2>
2449 <h2 id="changes">Changes</h2>
2451 <h3 id="changes_from_Aug_28_2012">Changes from <a href="http://www.w3.org/TR/2012/WD-css3-regions-20120823/">August 28<sup>th</sup> 2012</a> version</h3>
2453 <ul>
2454 <li>Added section on fragmenting the fragmenters</li>
2455 <li>Added section on handling circular flow-from and flow-into situations</li>
2456 <li>Added alignment and justification to region styling properties</li>
2457 <li>Added timing for regionLayoutUpdate event</li>
2458 <li>Clarified interaction between content and flow-from for pseudo-elements</li>
2459 <li>Changed NamedFlowCollection getters to return undefined when there is no NamedFlow.</li>
2460 <li>Changed region-overflow property to region-fragment.</li>
2461 </ul>
2463 <h3 id="changes_from_May_03_2012">Changes from <a href="http://www.w3.org/TR/2012/WD-css3-regions-20120503/">May 3<sup>rd</sup> 2012</a> version</h3>
2465 <ul>
2466 <li>Removed exceptions from the Region interface.</li>
2467 <li>Changed NamedFlowCollection from live to a static snapshot.</li>
2468 <li>Changed NamedFlow to inherit from EventTarget.</li>
2469 <li>Removed flowFrom from Region interface and changed method name to getComputedRegionStyle().</li>
2470 <li>Region interface is now a supplemental interface with the [NoInterfaceObject] extended attribute.</li>
2471 <li>Added note for regionLayoutUpdate dispatching in nested flows.</li>
2472 <li>Removed Document.getFlowByName() in favor of NamedFlowCollection.namedItem().</li>
2473 <li>Changed to overset:false for NULL NamedFlow.</li>
2474 <li>Changed regionLayoutUpdate to not bubble.</li>
2475 </ul>
2477 <h3 id="changes_from_November_29_2011">Changes from <a href="http://www.w3.org/TR/2011/WD-css3-regions-20111129/">November 29<sup>th</sup> 2011</a> version</h3>
2479 <ul>
2480 <li>Modified region styling examples to use element selector instead of of pseudo-code selectors (this had been omitted in the
2481 previous pass at removing pseudo-code from the examples).</li>
2482 <li>Removed divs with class set to "issue moved", "issue stale" and "issue resolved" since these divs where not displayed.
2483 <li>Minor updates to the alternate stylesheet.</li>
2484 <li>Removed "This section is normative" paragraphs since in CSS specifications, sections are normative unless
2485 otherwise specified.</li>
2486 <li>Removed "This section is informative" paragraphs since in CSS specifications notes are always informative.</li>
2487 <li>Reworded the text about flow-into: <ident> and removed obsolete text about the interaction with the
2488 'content' property.</li>
2489 <li>Removed "this section is non-normative" from the "Regions Concepts" section.</li>
2490 <li>In the section on region breaks, removed descriptions of break values normatively defined in external specifications.
2491 Removed the section about split boxes and replaced with paragraph referencing the page breaking behavior.
2492 Removed the discussion about how the 'overflow' property applies to content flown in regions from the
2493 break section, since this is covered in the section on 'region-overflow' already. See <a href="http://lists.w3.org/Archives/Public/www-style/2011Dec/0477.html">mailing list feedback.</a></li>
2494 <li>Clarified that @region style rules only apply to the 'portion' of an element that falls into
2495 the corresponding region and added an issue that the model for 'partial' styling needs to
2496 be defined. See <a href="http://lists.w3.org/Archives/Public/www-style/2011Dec/0480.html">mailing list feedback</a>.</li>
2497 <li>Clarified that the <code>NodeList</code> returned by <code>getRegionsByContentNode</code> is live.</li>
2498 <li>Added a name property to the <code>NamedFlow</code> interface. Added a <code>NamedFlowCollection</code>
2499 interface and added a <code>getNamedFlows</code> method on the <code>Document</code> interface, as
2500 per <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15828">Bug 15828</a>.</li>
2501 <li>Modified wording about containing block resolution for absolutely positioned elements in a
2502 named flow.</li>
2503 <li>Modified initial examples as per <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15131">Bug 15131</a></li>
2504 <li>Multiple editorial changes following
2505 <a href="http://lists.w3.org/Archives/Public/www-style/2012Feb/0001.html">mailing list review comments</a></li>
2506 <li>Fixed DOM references to now point to the DOM TR</li>
2507 <li>Fixed Web IDL issues as reported in <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15931">Issue 15931</a></li>
2508 <li>Added text to explain support for multi-column elements as required by <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15191">Issue 15191</a> and <a href="http://www.w3.org/Style/CSS/Tracker/actions/375">Action 375</a>.</li>
2509 <li>Renamed 'regionOverflow' to 'regionOverset' to avoid confusion between fitting a flow in
2510 regions and the concept of visual overflow that the word 'overflow' (and the property) carry.</li>
2511 <li>Reworked the partial document interface following the <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=14948">Issue 14948</a> on <code>getFlowByName</code>.</li>
2512 <li>Updated the object model section as proposed on the <a href="http://wiki.csswg.org/spec/css3-regions/css-om">wiki</a> and in particular:
2513 <ul>
2514 <li>introduced a <code>Region</code> interface to replace the supplemental Element interface</li>
2515 <li>Added a 'flowFrom' attribute on the Region interface</li>
2516 <li>NamedFlow.getRegions() was added</li>
2517 <li>Renamed getContentNode to getContent and getRegionsByContentNode to getRegionsByContent as
2518 per <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15879">Isseu 15879</a></li>
2519 <li>NamedFlow now returns static lists (see <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16286">Issue 16286</a>)</li>
2521 </ul>
2522 </li>
2523 <li>Modified region layout event to be dispatched on <code>NamedFlow</code> instead of region
2524 as before. Was requested by <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15938">Issue 15938</a>
2525 and required in the general effort to have the DOM APIs work with non-element regions.</li>
2526 <li>Changed paragraph on pseudo-elements to disallow 'flow-into' on all pseudo-elements because
2527 moving a '::before' element (for a example) to a named flow does not seem useful and causes specification
2528 and implementation complexity.</li>
2529 <li>Added section about getClientRects(), getBoundingClientRect(), offsetWidth, offsetHeight, offsetTop and
2530 offsetLeft.</li>
2531 <li>Added 'Regions visual formatting details' section to better describe the model for
2532 resolving auto sizing on regions.</li>
2533 <li>Reworked the initial specification example.</li>
2534 <li>Changed break and region-overflow properties to apply to visual media instead of paged.</li>
2535 <li>Added opacity to region styling.</li>
2536 <li>Added possibility of ::before content contributing to overflow.</li>
2537 <li>Added CSSRegionStyleRule</li>
2538 </ul>
2541 <h3 id="changes_from_June_09_2011">Changes from <a href="http://www.w3.org/TR/2011/WD-css3-regions-20110609/">June 09<sup>th</sup> 2011</a> version</h3>
2543 <ul>
2544 <li>Editorial changes (typos, rephrasings).</li>
2545 <li>Made 'content-order' a <integer> and not a <float> following a working group
2546 <a href="http://lists.w3.org/Archives/Public/www-style/2011Jun/0329.html">resolution</a></li>
2547 <li>Added Alex Mogilevsky as an editor</li>
2548 <li>Flow names became <ident> instead of <string> following a working group
2549 <a href="http://lists.w3.org/Archives/Public/www-style/2011Jun/0413.html">resolution</a></li>
2550 <li>Removed issue about possibly altering the DOM Events model for region events following
2551 a working group
2552 <a href="http://lists.w3.org/Archives/Public/www-style/2011Jun/0413.html">resolution</a></li>
2553 <li>Made the "relation to document events" section informative following a working group
2554 <a href="http://lists.w3.org/Archives/Public/www-style/2011Jun/0413.html">resolution</a></li>
2555 <li>Removed issue in section "The NamedFlow interface" following the working group's
2556 <a href="http://lists.w3.org/Archives/Public/www-style/2011Jun/0413.html">resolution</a> to
2557 have both NamedFlow and the Element interface extension</li>
2558 <li>Following a working group <a href="http://lists.w3.org/Archives/Public/www-style/2011Jun/0413.html">resolution</a>:
2559 <ul>
2560 <li>Turned the first issue in the "Extensions to the Element interface" into a note
2561 explaining that the NamedFlow interface can be used when regions are pseudo-elements.</li>
2562 <li>Added NamedFlowUpdate</li>
2563 </ul>
2564 </li>
2565 <li>Excluded 'none', 'inherit' and 'initial' from the possible identifier names on
2566 the flow property following <a href="http://lists.w3.org/Archives/Public/www-style/2011Jun/0583.html">discussion</a> on the mailing list.</li>
2567 <li>Simplified integration discussion on multi-column layout and just state that since
2568 column boxes are not addressable by selectors, they cannot be regions.</li>
2569 <li>Added specification of how the 'flow-into' property interacts with object, embed and iframe
2570 elements.</li>
2571 <li>Excluded 'default' from the possible identifier names on the flow property because it
2572 <a href="http://www.w3.org/TR/2006/WD-css3-values-20060919/#keywords">may get reserved</a>.</li>
2573 <li>Added to the definition of 'auto' on 'region-overflow' specifying that region breaks must
2574 be ignored.</li>
2575 <li>Renamed 'Document.flowWithName' to 'Document.getFlowByName' since it is not a property.</li>
2576 <li>Added a note that a 'NamedFlow' instance is live.</li>
2577 <li>Added an 'undefined' string value to the regionOverflow property on the Element interface
2578 extension.</li>
2579 <li>Renamed NamedFlowEvent to regionLayoutUpdate to avoid having 'Event' in the event name.</li>
2580 <li>Added description for special behavior of iframe/object/embed as
2581 flow source</li>
2582 <li>Removed issue on copying content to a named flow instead of moving elements to named
2583 flow following working group <a href="http://lists.w3.org/Archives/Public/www-style/2011Aug/0069.html">resolution</a>.</li>
2584 <li>Removed issue on content:flow-from v.s., flow-from property following working group <a href="http://lists.w3.org/Archives/Public/www-style/2011Aug/0069.html">resolution</a>.</li>
2585 <li>Renamed 'flow' to 'flow-into' following working group <a href="http://lists.w3.org/Archives/Public/www-style/2011Aug/0069.html">resolution</a>.</li>
2586 <li>Updated the css3-grid-align example following working group <a href="http://lists.w3.org/Archives/Public/www-style/2011Aug/0069.html">resolution</a> that
2587 it should use <div> instead of grid-cell pseudo elements that were removed
2588 from the CSS Grid Layout specification.</li>
2589 <li>Renamed 'from-flow' to 'flow-from' following a working group <a href="http://lists.w3.org/Archives/Public/www-style/2011Aug/0069.html">resolution</a>.</li>
2590 <li>Limited the applicability of 'content: flow-from()' to block container box and added
2591 a note that this might be expanded in the future, following a working group <a href="http://lists.w3.org/Archives/Public/www-style/2011Aug/0069.html">resolution</a>.</li>
2592 <li>Removed issue about API to find which region displays an element in a named flow
2593 since <a href="http://www.w3.org/Style/CSS/Tracker/actions/350">ACTION-350</a> was
2594 created to add this API.</li>
2595 <li>In the 'flow' property description, removed the required wrapper anonymous
2596 block as agreed on <a href="http://lists.w3.org/Archives/Public/www-style/2011Aug/0161.html">mailing list discussion</a>.</li>
2597 <li>Reworded the paragraph on how regions create a new stacking context, as
2598 per the <a href="http://lists.w3.org/Archives/Public/www-style/2011Aug/0025.html">mailing list discussion</a>.</li>
2599 <li>Reworked the "CSS regions Model" section to now be "CSS regions Layout". Moved the
2600 definition of a region as the first sub-section.</li>
2601 <li>Removed the "Visual Formatting Model and Flows" section to match the new Regions Model
2602 (now CSS regions Layout) section.</li>
2603 <li>Moved the sections on allowed region breaks, forced region breaks and "best" regions
2604 breaks to follow the property definitions to follow the formatting of the paged
2605 media section in CSS 2.1.</li>
2606 <li>Added note about why regions create a new stacking context following the discussion
2607 on the <a href="http://lists.w3.org/Archives/Public/www-style/2011Jul/0158.html">mailing list</a>.</li>
2608 <li>Removed sentence about content:none making elements disconnected following the
2609 discussion on the <a href="http://lists.w3.org/Archives/Public/www-style/2011Jul/0158.html">mailing list</a>.</li>
2610 <li>Removed sentence about content:none making elements disconnected following the
2611 discussion on the <a href="http://lists.w3.org/Archives/Public/www-style/2011Jul/0158.html">mailing list</a>.</li>
2612 <li>Added the ::region-before and a ::region-after pseudo-elements.</li>
2613 <li>Added note of caution when using selectors and the 'flow-into' property following
2614 a <a href="http://lists.w3.org/Archives/Public/www-style/2011Jul/0191.html">mailing list discussion</a>.</li>
2615 <li>Removed sections about allowed, forced and best region breaks to align with the
2616 multi-column specification approach and until the group agrees on where and how the
2617 general issue of breaks (regions/pages/columns) should be addressed.</li>
2618 <li>Removed the section on Integration with other specifications since specifications that
2619 was superfluous especially since there is no specific integration with multi column,
2620 grid or template layout.</li>
2621 <li>Added a note that regions establish a new block formatting context.</li>
2622 <li>Renamed content-order to region-order.</li>
2623 <li>Added a note about overflowing content in regions (e.g., for content with borders).</li>
2624 <li>Added a note that a region cannot layout content it is part of (to avoid creating a
2625 circular dependency) in the flow-from description, specifying that if flow-from
2626 references the flow an element is part of, then the element does not format
2627 anything visually.</li>
2628 <li>Replaced 'content:flow-from(<ident>)' with 'flow-from: <ident>' following a
2629 <a href="http://krijnhoetmer.nl/irc-logs/css/20110824">working group resolution</a>.</li>
2630 <li>Added more specific wording about auto width and auto height, following
2631 <a href="http://www.w3.org/Style/CSS/Tracker/actions/351">ACTION 351</a>.</li>
2632 <li>Reworked section on region markers to now use '::before' and '::after' and explain
2633 how 'display:run-in' works with regions.</li>
2634 <li>Modified the @region style rule to remove the ::region-lines pseudo-selector.</li>
2635 <li>Removed the 'region-order' property following implementation feedback.</li>
2636 <li>Specified that region-overflow does not influence a region's size.</li>
2637 <li>Specified that the flow's writing mode is defined by the first region's writing mode
2638 following <a href="http://lists.w3.org/Archives/Public/www-style/2011Aug/0306.html">mailing list discussion</a>.</li>
2639 <li>Made iframe, object and embed support of flow-into optional following
2640 <a href="http://lists.w3.org/Archives/Public/www-style/2011Sep/0073.html">mailing list discussion</a>.</li>
2641 <li>Clarified that flow content following the last break in the last region is not rendered,
2642 following <a href="http://lists.w3.org/Archives/Public/www-style/2011Oct/0167.html">mailing list
2643 discussions.</a></li>
2644 <li>Modified the rule for computing the width and height of a region when they are set to auto,
2645 following <a href="http://lists.w3.org/Archives/Public/www-style/2011Oct/0216.html">a mailing list
2646 discussion.</a></li>
2647 <li>Added 'auto' to the list of invalid flow identifiers.</li>
2648 <li>Made 'none' the initial value for 'flow-into' and aligned with 'flow-from', as
2649 explained in this <a href="http://lists.w3.org/Archives/Public/www-style/2011Oct/0576.html">email</a>.
2650 Also allowed the 'inherit' value on 'flow-from' and 'flow-into' (same email).</li>
2651 <li>Added note about nested region styling following <a href="http://lists.w3.org/Archives/Public/www-style/2011Oct/0650.html">a mailing list discussion</a>.</li>
2652 <li>Added additional DOM interface following <a href="http://www.w3.org/Style/CSS/Tracker/actions/350">Action 350</a>.</li>
2653 <li>Clarified that a region becomes a region only if its 'content' property computes to
2654 normal, following the resolution of <a href="http://wiki.csswg.org/spec/css3-regions#issue-22content-vs-flow-from-precedence">Issue 22</a>.</li>
2655 <li>Removed text about special iframe behavior as a result of
2656 <a href="http://www.w3.org/Style/CSS/Tracker/actions/376">ACTION 376</a>.</li>
2657 <li>Made the selectors explicit in the initial section code examples, following
2658 discussion in <a href="http://krijnhoetmer.nl/irc-logs/css/20111030">San Jose, October 2011</a> face to face meeting.</li>
2659 <li>Added section on use cases following <a href="http://www.w3.org/Style/CSS/Tracker/actions/377">ACTION-377</a>.</li>
2660 </ul>
2662 <h2 class="no-num" id="acknowledgments">Acknowledgments</h2>
2664 <p>The editors are grateful to the CSS working group for their feedback and help with
2665 the genesis of this specification.</p>
2667 <p>In addition, the editors would like to thank the following individuals for their contributions,
2668 either during the conception of CSS regions or during its development and specification review
2669 process:</p>
2670 <p>Rossen Atanassov,
2671 Tab Atkins,
2672 Mihai Balan,
2673 Andrei Bucur,
2674 Razvan Caliman,
2675 Alexandru Chiculita,
2676 Phil Cupp,
2677 Arron Eicholz,
2678 John Jansen,
2679 Dimitri Glazkov,
2680 Daniel Glazman,
2681 Arno Gourdol,
2682 David Hyatt,
2683 Brian Heuston,
2684 Ian Hickson,
2685 Jonathan Hoersch,
2686 Michael Jolson,
2687 Brad Kemper,
2688 Håkon Wium Lie,
2689 Markus Mielke,
2690 Robert O'Callahan,
2691 Edward O'Connor,
2692 Mihnea Ovidenie,
2693 Virgil Palanciuc,
2694 Olga Popiv,
2695 Christoph Päper,
2696 Anton Prowse,
2697 Peter Sorotokin,
2698 Christian Stockwell,
2699 Eugene Veselov,
2700 Boris Zbarsky,
2701 Stephen Zilles
2702 and the CSS Working Group members.
2703 </p>
2705 <h2 id="intro-example-code" class="no-num">Appendix A. Example Code for Introduction</h2>
2706 <p>The following is one possible way
2707 to code the example from
2708 the <a href="#introduction">introduction</a>.
2709 This code uses grid cells
2710 to define, size and position the region areas
2711 but table layout, absolute positioning,
2712 or any other CSS layout facility could be used.</p>
2714 <div class="example"><pre>
2715 <style>
2716 #grid {
2717 width: 80vw;
2718 height: 60vw;
2719 grid-template: "aaa.d"
2720 "....d"
2721 "bbb.d"
2722 "....d"
2723 "ccc.d";
2724 grid-rows: 52% 4% 20% 4% 20%;
2725 grid-columns: 30% 5% 30% 5% 30%;
2726 }
2727 #region1 { grid-cell: a; }
2728 #region2 { grid-cell: b; }
2729 #boxA { grid-cell: c; }
2730 #region3 { grid-cell: d; }
2732 #region4 {
2733 width: 80vw;
2734 }
2736 #region2 {
2737 column-count: 2;
2738 }
2740 <span class="highlight">/*
2741 * Creates the named flow
2742 */</span>
2743 article {
2744 <strong>flow-into: article_flow;</strong>
2745 }
2747 <span class="highlight">/*
2748 * Associate it with the intended CSS Regions.
2749 * This creates a region chain for the named flow.
2750 */</span>
2751 #region1, #region2, #region3, #region4 {
2752 <strong>flow-from: article_flow;</strong>
2753 }
2755 </style>
2757 <span class="highlight"><!--
2758 The following code element is the content to flow
2759 through the region chain.
2760 --></span>
2762 <article>
2763 <h1>Introduction</h1>
2764 <p>This is an example ...</p>
2766 <h2>More Details</h2>
2767 <p>This illustrates ...</p>
2768 <p>Then, the example ...</p>
2769 <p>Finally, this ...</p>
2770 </article>
2772 <span class="highlight"><!--
2773 For this example, we layout the regions with a grid.
2774 Regions could be pseudo-elements and could be laid out
2775 with another layout module (e.g., flexible boxes)
2776 --></span>
2777 <div id="grid">
2778 <div id="region1"></div>
2779 <div id="region2"></div>
2780 <div id="boxA"></div>
2781 <div id="region3"></div>
2782 </div>
2783 <div id="region4"></div>
2784 </pre></div>
2788 <div class="note"><span class="note-prefix">Note </span>
2789 <p>
2790 Note that a multi-column element is used for #region2,
2791 which is a bit gratuitous here
2792 (because grid cells could be used).
2793 The reason to use a multi-column element
2794 is to illustrate that
2795 regions can be multi-column.</p>
2796 </div>
2799 <h2 class="no-num" id="references">References</h2>
2801 <div class="issue-marker wrapper">
2802 <div class="issue-marker" data-bug_id="18767" data-bug_status="NEW">
2803 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=18767">Issue-18767</a>
2804 <div class="issue-details">
2805 <p class="short-desc">Something appears to be wrong with the checkSpecificationIssues() call</p>
2806 </div>
2807 </div>
2808 </div>
2810 <h3 class="no-num" id="normative-references">Normative references</h3>
2811 <!--begin-normative--><!--end-normative-->
2813 <h3 class="no-num" id="other-references">Other references</h3>
2814 <!--begin-informative--><!--end-informative-->
2816 <h2 class="no-num" id="index">Index</h2>
2817 <!--index-->
2819 <h2 class="no-num" id="property-index">Property index</h2>
2820 <!-- properties -->
2822 <!-- template markup for issues pulled from Bugzilla --> <!-- template markup for issues pulled from Bugzilla -->
2823 <script type="text/template" id="issue-template">
2824 <div class="issue-marker" data-bug_id="{{bug_id}}" data-bug_status="{{bug_status}}">
2825 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id={{bug_id}}">Issue-{{bug_id}}</a>
2826 <div class="issue-details">
2827 <p class="short-desc">{{short_desc}}</p>
2828 </div>
2829 </div>
2830 </script>
2832 <script type="text/javascript" src="../shared/scripts/BugzillaTrackerUtil.js"></script>
2833 <script type="text/javascript" src="../shared/scripts/BugzillaTracker.js"></script>
2834 <script type="text/javascript">
2835 checkSpecificationIssues('CSS', 'Regions');
2836 </script>
2838 </body>
2839 </html>
2840 <!-- Keep this comment at the end of the file
2841 Local variables:
2842 mode: sgml
2843 sgml-declaration:"~/SGML/HTML4.decl"
2844 sgml-default-doctype-name:"html"
2845 sgml-minimize-attributes:t
2846 sgml-nofill-elements:("pre" "style" "br")
2847 sgml-live-element-indicator:t
2848 sgml-omittag:nil
2849 sgml-shorttag:nil
2850 sgml-namecase-general:t
2851 sgml-general-insert-case:lower
2852 sgml-always-quote-attributes:t
2853 sgml-indent-step:nil
2854 sgml-indent-data:t
2855 sgml-parent-document:nil
2856 sgml-exposed-tags:nil
2857 sgml-local-catalogs:nil
2858 sgml-local-ecat-files:nil
2859 End:
2860 -->
