css3-regions/Overview.src.html@2e04f2d16ef5
css3-regions/Overview.src.html
Mon, 23 Apr 2012 22:27:12 -0700
- author
- Alan Stearns <stearns@adobe.com>
- date
- Mon, 23 Apr 2012 22:27:12 -0700
- changeset 5598
- 2e04f2d16ef5
- parent 5579
- afb867e7b4ae
- child 5599
- c76a4ff42fc3
- permissions
- -rw-r--r--
added CSSRegionStyleRule to OM section
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">
9 <style type="text/css">
10 #region-style-example p, #region-style-example pre {
11 clear: both;
12 }
14 #region_styling_illustration {
15 margin: 0px auto;
16 width: 70ex;
17 }
18 </style>
20 <link rel="stylesheet" type="text/css"
21 href="http://www.w3.org/StyleSheets/TR/W3C-ED.css">
23 <link rel="stylesheet" type="text/css"
24 href="../shared/style/issues.css">
26 <link id="st" href="../shared/style/alternate-spec-style.css" rel="stylesheet"
27 type="text/css" title="alternate spec style">
28 </head>
31 <body>
32 <div class="head" id="div-head">
33 <p><a href="http://www.w3.org/"><img id="mobile-logo" alt="W3C" height="53" src=
34 "http://www.w3.org/2008/site/images/logo-w3c-mobile-lg" width="90"></a>
37 <!--begin-logo-->
39 <p><a href="http://www.w3.org/"><img id="logo" alt="W3C" height="48" src=
40 "http://www.w3.org/Icons/w3c_home" width="72"></a> <!--end-logo--></p>
42 <h1 id="css-regions-module">CSS Regions Module Level 3</h1>
44 <h2 class="no-num no-toc" id="longstatus-date">[LONGSTATUS]
45 [DATE]</h2>
47 <dl>
48 <dt>This version:</dt>
50 <dd><a href=
51 "[VERSION]">http://www.w3.org/csswg/css3-regions</a></dd>
53 <dt>Latest version:</dt>
55 <dd><a href=
56 "http://www.w3.org/TR/css3-regions/">http://www.w3.org/TR/css3-regions/</a></dd>
58 <dt>Previous version:</dt>
60 <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>
62 <dt>Editors:</dt>
64 <dd class="vcard"><span class="fn">Vincent Hardy</span>,
65 <span class="org">Adobe Systems, Inc.</span>, <span class=
66 "email">vhardy@adobe.com</span></dd>
67 <dd class="vcard"><span class="fn">Alex Mogilevsky</span>,
68 <span class="org">Microsoft</span>, <span class=
69 "email">alexmog@microsoft.com</span></dd>
71 <dt>Issues List:</dt>
72 <dd><a href="https://www.w3.org/Bugs/Public/buglist.cgi?product=CSS&component=Regions&resolution=---">Bugzilla Bugs for CSS regions</a></dd>
73 <dt>Discussion:</dt>
74 <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>
75 </dl><!--begin-copyright--><!--end-copyright-->
76 <hr title="Separator for header">
77 </div>
79 <h2 class="no-num no-toc" id="abstract">Abstract</h2>
81 <p>The CSS regions module allows content to flow across multiple areas
82 called regions. The regions are not necessarily contiguous in the document order.
83 The CSS regions module provides an advanced content flow mechanism, which
84 can be combined with positioning schemes as defined by other CSS modules
85 such as the Multi-Column Module [[CSS3COL]] or the Grid Layout Module
86 [[CSS3-GRID-LAYOUT]] to position the regions where content flows.</p>
88 <h2 class="no-num no-toc" id="status-of-this-document">Status of this
89 document</h2>
91 <p class="big note"><span class="note-prefix">Note </span>This document uses an experimental style
92 sheet. We welcome your feedback on the styles at
93 <a href="mailto:site-comments@w3.org">site-comments@w3.org</a>.</p>
95 <!--begin-status-->
96 <p><em>This section describes the status of this document at the time of
97 its publication. Other documents may supersede this document. A list of
98 current W3C publications and the latest revision of this technical report
99 can be found in the <a href="http://www.w3.org/TR/">W3C technical reports
100 index at http://www.w3.org/TR/.</a></em></p>
102 <p>This is a public copy of the editors' draft. It is provided for
103 discussion only and may change at any moment. Its publication here does not
104 imply endorsement of its contents by W3C. Don't cite this document other
105 than as work in progress.</p>
107 <p>The archived public mailing list www-style@w3.org is preferred for
108 discussion of this specification. When sending e-mail, please put the text
109 "css3-regions" in the subject, preferably like this: "[css3-regions]
110 …summary of comment…"</p>
111 <!--end-status-->
113 <p>This draft is related to the drafts about Multi-column Layout
114 [[CSS3COL]], Grid Layout [[CSS3GRID]], Flexible Box Layout
115 [[CSS3-FLEXBOX]], and Template Layout [[CSS3LAYOUT]].</p>
117 <h2 class="no-num no-toc" id="table-of-contents">Table of contents</h2>
118 <!--begin-toc--><!--end-toc-->
120 <h2 id="introduction">Introduction</h2>
122 <p><em>This section is non-normative.</em></p>
124 <p>Displaying the complex layouts
125 of a typical magazine, newspaper, or textbook on the web
126 requires capabilities beyond those available in existing CSS modules.
127 Dynamic magazine layout in particular requires flexibility
128 in placement of boxes for content flows.
129 This is the purpose of the CSS regions module.</p>
131 <div class="issue-marker" data-bug_id="15733" data-bug_status="NEW">
132 <a href=
133 "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15733">Bug-15733</a>
135 <div class="issue-details">
136 <p class="short-desc">Should the region specification define a
137 mechanism to create blocks that can be regions with CSS
138 syntax?</p>
139 </div>
140 </div>
142 <p>For more complex layouts,
143 content needs to flow from one area of the page to the next
144 without limitation on the areas' sizes and positions.
145 These arbitrary areas are the target of specific content flows
146 which this document calls <span>named flows</span>.
147 Each <span>named flow</span> can be associated
148 with a set of CSS Regions called a region chain.
149 CSS Regions are based on the rectangular geometry
150 of the CSS box model.
151 Elements in a <span>named flow</span>
152 are taken out of the normal visual formatting
153 and rendered in a chain of CSS Regions.</p>
155 <h3 id="named-flows-and-regions">Named flows and region chains</h3>
157 <p>Consider the layout illustrated in figure 1.</p>
160 <div class="figure">
161 <img src="images/intro-example-layout.svg" width="400" alt=
162 "multiple chained regions which should receive content from a flow">
164 <p class="caption">Layout requiring sophisticated content flow</p>
165 </div>
167 <p>The designer's intent is
168 to position an image in box 'A'
169 and to flow an article's content
170 from box '1' through boxes '2', '3' and '4'.
171 Note that the second box should have two columns,
172 and the image is not contained in the article.
173 Box '4' should auto-size to render
174 the remainder of the article content
175 that did not fit in the earlier boxes.</p>
177 <p>Figure 2 shows an example
178 of the intended visual rendering
179 of the content.</p>
181 <div class="figure">
182 <img src="images/regions-intro-rendering.png" width="450" alt=
183 "Sample rendering showing a single thread of text flowing through a chain of regions">
185 <p class="caption">Sample rendering for desired layout</p>
186 </div>
189 <p>There is no existing mechanism in CSS
190 to associate the content with these boxes
191 arranged in this manner
192 so that content flows as intended.
193 The CSS regions module properties provide that mechanism.</p>
195 <p>The following example illustrates
196 how the content of an <code><article></code> element
197 becomes a <span>named flow</span>
198 and how boxes marked with 'region1', 'region2', 'region3' and 'region4' IDs
199 become CSS Regions that consume the 'article_flow' content.</p>
201 <div class="example">
202 <pre>
203 <style>
204 article {
205 <strong>flow-into: article_flow;</strong>
206 }
208 #region1, #region2, #region3, #region4 {
209 <strong>flow-from: article_flow;</strong>
210 }
211 </style>
212 </pre>
213 </div>
215 <p>The 'article_flow' value on the 'flow-into' property
216 directs the <code>article</code> element
217 to the 'article_flow' <span>named flow</span>.
218 Setting the 'flow-from' property on block containers
219 to 'article_flow' makes them CSS Regions
220 and associates the resulting region chain
221 with the <span>named flow</span>:
222 the flow is ''poured''
223 into the region chain.</p>
225 <p>See <a href="#intro-example-code">Appendix A</a>
226 for sample code using grid layout
227 that implements this example</p>
229 <div class="note"><span class="note-prefix">Note </span>
230 <p><strong>CSS Regions are independent from layout</strong></p>
232 <p>Any of the CSS layout facilities can be used
233 to create, position and size boxes that can become CSS Regions.
234 Using a grid layout [[CSS3-GRID-LAYOUT]] is just an example.
235 The example could use
236 a flexible box layout [[CSS3-FLEXBOX]] instead.</p>
237 <p>The CSS regions specification does not
238 define a layout mechanism
239 and is meant to integrate
240 with existing and future CSS layout facilities.</p>
242 <p><strong>CSS Regions do not have to be elements</strong></p>
244 <p>The CSS regions module is independent
245 of the layout of boxes and
246 the mechanism used to create them.
247 For simplicity,
248 our example code in <a href="#intro-example-code">Appendix A</a>
249 uses elements to define the boxes.</p>
252 <p>While the example uses elements for CSS Regions
253 (since [[CSS3-GRID-LAYOUT]] requires elements to create grid items)
254 it is important to note that
255 this is not required.
256 CSS Regions can be pseudo-elements,
257 such as '::before' and '::after'.
258 The only requirement
259 for an element or pseudo-element
260 to become a CSS Region
261 is that it needs to be subject
262 to CSS styling
263 to receive the 'flow-from' property.
264 The CSS page template module
265 (see [[CSS3-PAGE-TEMPLATE]])
266 proposes another mechanism
267 to create stylable boxes that can become CSS Regions
268 with the <code class="css">@slot</code> syntax.</p>
269 </div>
271 <h3 id="region-styling">CSS Region names and styling</h3>
273 <p>Content can be styled depending on
274 the CSS Region it flows into.
275 It is an extension
276 of pseudo-element styling such as
277 <a href="http://www.w3.org/TR/css3-selectors/#first-line">
278 <code class="css">::first-line</code>
279 </a>
280 which applies a particular style
281 to a fragment of content.
282 With CSS Region styling,
283 additional selectors may apply
284 depending on the CSS Region
285 into which content flows.</p>
287 <p>In our example,
288 the designer wants to make
289 text flowing into #region1
290 dark blue and bold.</p>
292 <p>This design can be expressed as shown below.</p>
294 <div class="example">
295 <pre>
296 <style>
297 @region #region1 {
298 p {
299 color: #0C3D5F;
300 font-weight: bold;
301 }
302 </style></pre>
303 </div>
305 <p>The <code class="css">@region #region1</code> rule
306 limits its selectors to content
307 flowing into <code class="css">#region1</code>.
308 The following figure shows how
309 the rendering changes
310 if we apply styling specific to <code>#region1</code>.
311 Note how less text fits into this box
312 now that the 'font-weight' is
313 bold instead of normal.</p>
315 <div class="figure">
316 <img src="images/region-styling.png" width="450" alt=
317 "Illustrate how changing region styling affects the flow of content.">
319 <p class="caption">Different rendering with a different region
320 styling</p>
321 </div>
323 <h2 id="css-regions-concepts">CSS regions concepts</h2>
325 <h3 id="regions">Regions</h3>
327 <div class="issue-marker wrapper">
328 <div class="issue-marker" data-bug_id="15186" data-bug_status="NEW">
329 <a href=
330 "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15186">Bug-15186</a>
332 <div class="issue-details">
333 <p class="short-desc">Is a mechanism to auto-generate regions
334 necessary in order to support reusable style sheets?</p>
335 </div>
336 </div>
338 <div class="issue-marker" data-bug_id="15187" data-bug_status="NEW">
339 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15187">Bug-15187</a>
340 <div class="issue-details">
341 <p class="short-desc">Explain how regions and pages interact. How can regions be placed onto certain pages, and how can they be positiond wrt. pages.</p>
342 </div>
343 </div>
344 </div>
346 <p id="region">
347 A <dfn title="region">CSS Region</dfn>
348 is a block container
349 that has an associated
350 <em><span>named flow</span></em>
351 (see the 'flow-from' property).</p>
353 <h3 id="region-chain">Region chain</h3>
355 <p>A <dfn>region chain</dfn> is the sequence of regions that are associated with
356 a <span>named flow</span>. <span title="region">CSS Regions</span> in a
357 region chain receive content from the
358 named flow following their order in the chain. <span title="region">CSS Regions</span> are organized
359 into a <span title="region-chain">region chain</span>
360 according to the document order.</p>
362 <h3 id="named-flow">Named flows</h3>
364 <p>A <dfn>named flow</dfn> is the ordered sequence of elements
365 associated with a flow with a given identifier.
366 Elements in a <span>named flow</span> are ordered
367 according to the document order.</p>
369 <p>Elements are placed into a <span>named flow</span>
370 with the 'flow-into' property.
371 The elements in a <span>named flow</span> are laid out
372 in the <span title="region-chain">region chain</span>
373 that is associated with this <span>named flow</span>.
374 </p>
376 <p>Content from a <span>named flow</span>
377 is broken up between regions
378 according to the regions flow breaking rules.</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-overflow' 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="15811" data-bug_status="NEW">
422 <a href=
423 "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15811">Bug-15811</a>
425 <div class="issue-details">
426 <p class="short-desc">Creating a named flow from external resource</p>
427 </div>
428 </div>
429 <div class="issue-marker" data-bug_id="16002" data-bug_status="NEW">
430 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16002">Bug-16002</a>
431 <div class="issue-details">
432 <p class="short-desc">flow-into and anonymous blocks or fix-ups</p>
433 </div>
434 </div>
435 <div class="issue-marker" data-bug_id="16527" data-bug_status="ASSIGNED">
436 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16527">Bug-16527</a>
437 <div class="issue-details">
438 <p class="short-desc">[Shadow]: getFlowByName and shadow DOM</p>
439 </div>
440 </div>
441 </div>
443 <p>The ‘flow-into’ property can place an element
444 into a <span>named flow</span>.
445 Elements that belong to the same flow
446 are laid out in the region chain
447 associated with that flow.</p>
449 <table class="propdef" summary="flow property definition">
450 <tr>
451 <th>Name:</th>
453 <td><dfn id="flow-into">flow-into</dfn></td>
454 </tr>
456 <tr>
457 <th>Value:</th>
459 <td><ident> | none | inherit</td>
460 </tr>
462 <tr>
463 <th>Initial:</th>
465 <td>none</td>
466 </tr>
468 <tr>
469 <th>Applies to:</th>
471 <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
472 <code class="css">::first-line</code>, <code class="css">::first-letter</code>,
473 <code class="css">::before</code> or <code class="css">::after</code>.</p></td>
474 </tr>
476 <tr>
477 <th>Inherited:</th>
479 <td>no</td>
480 </tr>
482 <tr>
483 <th>Percentages:</th>
485 <td>N/A</td>
486 </tr>
488 <tr>
489 <th>Media:</th>
491 <td>visual</td>
492 </tr>
494 <tr>
495 <th>Computed value:</th>
497 <td>as specified</td>
498 </tr>
499 </table>
501 <dl>
502 <dt>none</dt>
504 <dd>The element is not moved to a <span>named flow</span> and normal CSS processing takes place.</dd>
506 <dt><a href="http://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#value-def-identifier"><ident></a></dt>
508 <dd>The element is taken out
509 of its parent's flow
510 and placed into the flow
511 with the name '<ident>'.
512 The element is said to have
513 a <dfn id="specified-flow">specified flow</dfn>.
514 The values 'none', 'inherit', 'default', 'auto' and 'initial'
515 are invalid flow names.</dd>
516 </dl>
518 <p>A <span>named flow</span> needs to be associated
519 with a region chain
520 (one or more CSS regions)
521 for its elements to be visually formatted.
522 If no region chain is associated
523 with a given <span>named flow</span>,
524 the elements in the <span>named flow</span>
525 are not rendered:
526 they do not generate boxes
527 and are not displayed.</p>
529 <p>The children of an element
530 with a specified flow
531 may themselves have a specified flow.</p>
533 <p>If an element has the same specified flow
534 as one of its ancestors,
535 it becomes a sibling of its ancestor
536 for the purpose of layout
537 in the region chain
538 laying out content
539 from that flow.</p>
541 <p>The 'flow-into' property does not affect
542 the CSS cascade and inheritance
543 for the elements on which it is specified.
544 The 'flow-into' property affects
545 the visual formatting of elements
546 placed into a <span>named flow</span>
547 and of the region chain laying out content
548 from a <span>named flow</span>.</p>
550 <div class="issue-marker wrapper">
552 <div class="issue-marker" data-bug_id="15870" data-bug_status="NEW">
553 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15870">Bug-15870</a>
554 <div class="issue-details">
555 <p class="short-desc">Describe how containing blocks are used for element fragments</p>
556 </div>
557 </div>
558 </div>
560 <p>The edges of the first CSS region in a region chain
561 associated with a <span>named flow</span>
562 establish the rectangle that is the
563 <a href="http://www.w3.org/TR/CSS2/visudet.html#containing-block-details">containing block</a>
564 used for absolutely positioned elements
565 in the <span>named flow</span>
566 which do not have an ancestor
567 with a 'position' of 'absolute', 'relative' or 'fixed'
568 (see [[!CSS21]]).
569 That first CSS region rectangle is used
570 as the containing block
571 instead of the initial containing block.</p>
573 <p>The first region defines the
574 <a href="http://www.w3.org/TR/css3-writing-modes/#writing-mode">writing mode</a>
575 for the entire flow.
576 The writing mode
577 on subsequent regions is ignored.</p>
579 <p>Elements in a <span>named flow</span>
580 are sequenced in document order.</p>
582 <div class="note"><span class="note-prefix">Note </span>
583 <p>The 'flow-into' property moves an element into the flow
584 and the interplay with selectors should be considered carefully.</p>
585 <p>For example, </p>
586 <pre>table {flow-into: table-content}</pre>
587 <p>will move all tables in the 'table-content'
588 <span>named flow</span>.
589 However, the</p>
590 <pre>table > * {flow-into: table-content} ...</pre>
591 <p>selector will move all immediate children
592 of all table elements
593 into the ‘table-content’ <span>named flow</span>
594 (which may be useful as it will usually result,
595 if the immediate children are rows,
596 in merging rows of multiple tables),
597 but the</p>
598 <pre>table * {flow-into: table-content}</pre>
599 <p>selector will move all descendants
600 of table elements into the ‘table-content’ <span>named flow</span>,
601 transforming the element tree
602 into a flat list in order of opening tags
603 (which is probably not intentional).
604 This will make all the descendants
605 of table elements siblings
606 in the <span>named flow</span>.
607 Having the descendants become siblings
608 in the <span>named flow</span>
609 results in a different processing
610 (see <a href="http://www.w3.org/TR/2011/REC-CSS2-20110607/tables.html#anonymous-boxes">CSS 2.1's anonymous table objects</a>).
611 This note illustrates how authors must exercise caution
612 when choosing a particular selector
613 for setting the 'flow-into' property
614 to avoid unintended results.</p>
615 </div>
620 <h3 id="the-flow-from-property">The 'flow-from' property</h3>
622 <p>The 'flow-from' property makes
623 a block container a region
624 and associates it with
625 a <span>named flow</span>.</p>
627 <table class="propdef" summary="flow-from property definition">
628 <tr>
629 <th>Name:</th>
631 <td><dfn id="flow-from">flow-from</dfn></td>
632 </tr>
634 <tr>
635 <th>Value:</th>
637 <td><ident> | none | inherit</td>
638 </tr>
640 <tr>
641 <th>Initial:</th>
643 <td>none</td>
644 </tr>
646 <tr>
647 <th>Applies to:</th>
649 <td>Non-replaced <a href="http://www.w3.org/TR/CSS21/visuren.html#block-boxes">block containers</a>.
650 <br />
651 This might be expanded in future versions of the specification
652 to allow other types of containers to receive flow content.</td>
653 </tr>
655 <tr>
656 <th>Inherited:</th>
658 <td>no</td>
659 </tr>
661 <tr>
662 <th>Percentages:</th>
664 <td>N/A</td>
665 </tr>
667 <tr>
668 <th>Media:</th>
670 <td>visual</td>
671 </tr>
673 <tr>
674 <th>Computed value:</th>
676 <td>as specified</td>
677 </tr>
678 </table>
680 <dl>
681 <dt><strong>none</strong></dt>
683 <dd>The block container is not a <span title="region">region</span>.</dd>
685 <dt><strong><ident></strong></dt>
687 <dd>
688 If the 'content' property computes
689 to something else than 'normal',
690 the block container does not become a <span>CSS Region</span>.
691 If the 'content' property computes to 'normal',
692 then the block container becomes a <span>CSS Region</span>
693 and is ordered in a <span>region chain</span>
694 according to its document order.
695 The content from the flow
696 with the <a href="http://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#value-def-identifier"><ident></a>
697 name will be <a href="#region-flow-break">broken
698 into fragments</a> and visually formatted in the
699 <a href="http://www.w3.org/TR/CSS21/visuren.html#principal-box">principal boxes</a>
700 of the <span>regions</span>
701 in the <span>region chain</span>.
702 <br/>
703 If there is no flow with name <ident>,
704 then the block container does not
705 format any content visually.
706 <br/>
707 Likewise, if the block container is part
708 of the flow with name <ident>,
709 then the block container does not format any content visually.
710 </dd>
711 </dl>
713 <div class="issue-marker" data-bug_id="16819" data-bug_status="ASSIGNED">
714 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16819">Bug-16819</a>
715 <div class="issue-details">
716 <p class="short-desc">No display when combining flow-from and flow-into is bad</p>
717 </div>
718 </div>
720 <p>A <span>CSS Region</span>'s document children
721 are not visually formatted
722 unless they are directed
723 to a <span>named flow</span>
724 with an associated <span>region chain</span>.</p>
726 <div class="note"><span class="note-prefix">Note </span>
727 <p>An block container becomes a <span>CSS Region</span>
728 when its 'flow-from' property is set
729 to a valid <ident> value,
730 even if there is no content contributing
731 to the referenced flow.
732 For example:</p>
733 <pre>
734 <style>
735 .article{
736 flow-into: thread;
737 }
738 .region{
739 flow-from: thread;
740 }
741 </style>
742 <html>
743 <body>
744 <div class=region>div content</div>
745 </body>
746 </html>
747 </pre>
749 There is no element matching the <code>.article</code> selector
750 and therefore no content
751 in the <code>thread</code> flow.
752 However, the block container matching the <code>.region</code> selector
753 is still associated with that empty <span>named flow</span>
754 and, consequently,
755 its children are not formatted visually.
756 </div>
758 <div class="issue-marker wrapper">
759 <div class="issue-marker" data-bug_id="15189" data-bug_status="NEW">
760 <a href=
761 "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15189">Bug-15189</a>
763 <div class="issue-details">
764 <p class="short-desc">Should regions be non-breakable?</p>
765 </div>
766 </div>
767 <div class="issue-marker" data-bug_id="15824" data-bug_status="NEW">
769 <a href=
770 "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15824">Bug-15824</a>
772 <div class="issue-details">
773 <p class="short-desc">Should regions not create a new stacking context?</p>
774 </div>
775 </div>
776 <div class="issue-marker" data-bug_id="15827" data-bug_status="NEW">
778 <a href=
779 "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15824">Bug-15827</a>
781 <div class="issue-details">
782 <p class="short-desc">Specify behavior of stacking contexts that are split between regions</p>
783 </div>
784 </div>
786 <div class="issue-marker" data-bug_id="16636" data-bug_status="NEW">
787 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16636">Bug-16636</a>
788 <div class="issue-details">
789 <p class="short-desc">Should re-introduce region order</p>
790 </div>
791 </div>
792 </div>
794 <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>
796 <div class="note"><span class="note-prefix">Note </span>
797 <p>With <span>region chains</span>,
798 an element may be split across multiple boxes
799 and these boxes may overlap
800 (for example if they are absolutely positioned).
801 So fragments of the same element
802 can overlap each other.
803 Since each element has a single z-index,
804 it would be required to find another mechanism
805 to decide in which order
806 the fragments are rendered.
807 Since each <span>CSS Region</span> creates
808 a new stacking context,
809 it is clear that each fragment is rendered separately
810 and their rendering order follows
811 the regular CSS rendering model.</p>
812 </div>
814 <p>Floats or other exclusions
815 (see [[CSS3-EXCLUSIONS]])
816 potentially impact the content
817 laid out in region chains,
818 just as for non-regions.</p>
820 <p>See the
821 <a href="#regions-visual-formatting-details">regions visual formatting details</a>
822 section for a description of how
823 'width' and 'height' values are resolved
824 for <span>CSS Region</span> boxes.</p>
826 <h3 id=
827 "region-flow-break">Region
828 flow break properties: 'break-before', 'break-after', 'break-inside'</h3>
830 <p>User agents laying out content in multiple regions must
831 determine where content breaks occur. The problem of breaking content into
832 fragments fitting in regions is similar to breaking content into pages or
833 columns.</p>
835 <p>Each break ends layout in the current region and causes remaining pieces
836 of content from the <span>named flow</span> to be visually formatted in the following
837 region in the region chain, if there is one.</p>
839 <p>The following extends the 'break-before', 'break-after' and
840 'break-inside' properties from the [[!CSS3COL]] specification to account
841 for regions. The additional values are described below.</p>
843 <table class="propdef" summary="break-before property definition">
844 <tr>
845 <td><em>Name:</em></td>
847 <td><dfn>break-before</dfn></td>
848 </tr>
850 <tr>
851 <td><em>Value:</em></td>
853 <td>auto | always | avoid | left | right | page | column | region |
854 avoid-page | avoid-column | avoid-region</td>
855 </tr>
857 <tr>
858 <td><em>Initial:</em></td>
860 <td>auto</td>
861 </tr>
863 <tr>
864 <td><em>Applies to:</em></td>
866 <td>block-level elements</td>
867 </tr>
869 <tr>
870 <td><em>Inherited:</em></td>
872 <td>no</td>
873 </tr>
875 <tr>
876 <td><em>Percentages:</em></td>
878 <td>N/A</td>
879 </tr>
881 <tr>
882 <td><em>Media:</em></td>
884 <td>visual</td>
885 </tr>
887 <tr>
888 <td><em>Computed value:</em></td>
890 <td>specified value</td>
891 </tr>
892 </table>
894 <table class="propdef" summary="break-after property definition">
895 <tr>
896 <td><em>Name:</em></td>
898 <td><dfn>break-after</dfn></td>
899 </tr>
901 <tr>
902 <td><em>Value:</em></td>
904 <td>auto | always | avoid | left | right | page | column | region |
905 avoid-page | avoid-column | avoid-region</td>
906 </tr>
908 <tr>
909 <td><em>Initial:</em></td>
911 <td>auto</td>
912 </tr>
914 <tr>
915 <td><em>Applies to:</em></td>
917 <td>block-level elements</td>
918 </tr>
920 <tr>
921 <td><em>Inherited:</em></td>
923 <td>no</td>
924 </tr>
926 <tr>
927 <td><em>Percentages:</em></td>
929 <td>N/A</td>
930 </tr>
932 <tr>
933 <td><em>Media:</em></td>
935 <td>visual</td>
936 </tr>
938 <tr>
939 <td><em>Computed value:</em></td>
941 <td>specified value</td>
942 </tr>
943 </table>
945 <table class="propdef" summary="break-inside property definition">
946 <tr>
947 <td><em>Name:</em></td>
949 <td><dfn>break-inside</dfn></td>
950 </tr>
952 <tr>
953 <td><em>Value:</em></td>
955 <td>auto | avoid | avoid-page | avoid-column | avoid-region</td>
956 </tr>
958 <tr>
959 <td><em>Initial:</em></td>
961 <td>auto</td>
962 </tr>
964 <tr>
965 <td><em>Applies to:</em></td>
967 <td>block-level elements</td>
968 </tr>
970 <tr>
971 <td><em>Inherited:</em></td>
973 <td>no</td>
974 </tr>
976 <tr>
977 <td><em>Percentages:</em></td>
979 <td>N/A</td>
980 </tr>
982 <tr>
983 <td><em>Media:</em></td>
985 <td>visual</td>
986 </tr>
988 <tr>
989 <td><em>Computed value:</em></td>
991 <td>specified value</td>
992 </tr>
993 </table>
995 <p>These properties describe page, column and region break behavior
996 before/after/inside the generated box. These values are normatively defined
997 in [[!CSS3COL]]:</p>
999 <p>This specification adds the following new values:</p>
1001 <dl>
1002 <dt>region</dt>
1004 <dd>Always force a region break before (after) the generated box.</dd>
1006 <dt>avoid-region</dt>
1008 <dd>Avoid a region break before (after, inside) the generated box.</dd>
1009 </dl>
1011 <p>The behavior of region breaks with regards to regions is identical to the behavior
1012 of page breaks with regards to pages, as defined in the [[!CSS21]].</p>
1014 <h3 id="the-region-overflow-property">The region-overflow property</h3>
1016 <div class="issue-marker" data-bug_id="15878" data-bug_status="NEW">
1017 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15878">Bug-15878</a>
1018 <div class="issue-details">
1019 <p class="short-desc">region-overflow:nobreak</p>
1020 </div>
1021 </div>
1023 <table class="propdef" summary="break-after property definition">
1024 <tr>
1025 <td><em>Name:</em></td>
1027 <td><dfn>region-overflow</dfn></td>
1028 </tr>
1030 <tr>
1031 <td><em>Value:</em></td>
1033 <td>auto | break</td>
1034 </tr>
1036 <tr>
1037 <td><em>Initial:</em></td>
1039 <td>auto</td>
1040 </tr>
1042 <tr>
1043 <td><em>Applies to:</em></td>
1045 <td><em title="region element">CSS Regions</em></td>
1046 </tr>
1048 <tr>
1049 <td><em>Inherited:</em></td>
1051 <td>no</td>
1052 </tr>
1054 <tr>
1055 <td><em>Percentages:</em></td>
1057 <td>N/A</td>
1058 </tr>
1060 <tr>
1061 <td><em>Media:</em></td>
1063 <td>visual</td>
1064 </tr>
1066 <tr>
1067 <td><em>Computed value:</em></td>
1069 <td>specified value</td>
1070 </tr>
1071 </table>
1073 <div class="issue-marker wrapper">
1074 <div class="issue-marker" data-bug_id="15832" data-bug_status="NEW">
1075 <a href=
1076 "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15832">Bug-15832</a>
1078 <div class="issue-details">
1079 <p class="short-desc">Should we have region-overflow:nobreak and have 'region-overflow' apply to all regions, not just the last?</p>
1080 </div>
1081 </div>
1082 <div class="issue-marker" data-bug_id="16622" data-bug_status="NEW">
1083 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16622">Bug-16622</a>
1084 <div class="issue-details">
1085 <p class="short-desc">Should we rename region-overflow to flow-overset?</p>
1086 </div>
1087 </div>
1088 </div>
1090 <p>The 'region-overflow' property controls the behavior of the <em id=
1091 "last-region">last region</em> associated with a <span>named
1092 flow</span>.</p>
1094 <dl>
1095 <dt>auto</dt>
1097 <dd>Content flows as it would in a regular content box. If the
1098 content exceeds the container box, it is subject to the <a href=
1099 "http://www.w3.org/TR/CSS21/visufx.html#propdef-overflow">overflow</a>
1100 property's computed value on the CSS Region. Region breaks must be
1101 ignored on the last region.</dd>
1103 <dt>break</dt>
1105 <dd><p>If the content fits within the <em>CSS Region</em>, then this
1106 property has no effect. If the content does not fit within the
1107 <em>CSS Region</em>, the content breaks as if flow was going to
1108 continue in a subsequent region. See the <a href=
1109 "#regions-flow-breaking-rules">breaking rules</a> section. A forced region break takes precedence over
1110 a natural break point.</p>
1112 <p>Flow content that follows the last break in the last region, if any is not rendered.</p>
1115 </dd>
1116 </dl>
1118 <p>The 'region-overflow' property does not influence
1119 the size of the region it applies to.</p>
1121 <p>The following code sample illustrates
1122 the usage of the 'region-overflow' property.</p>
1124 <div class="example">
1125 <pre>
1126 <style>
1127 article {
1128 flow-into: "article";
1129 }
1131 #region_1, #region_2 {
1132 flow-from: article;
1133 <strong>region-overflow: break;</strong> /* or none */
1134 <strong>overflow: visible;</strong> /* or hidden */
1135 }
1137 </style>
1139 <article>...</article>
1141 <div id="region_1"></div>
1142 <div id="region_2"></div>
1144 </pre>
1145 </div>
1147 <div class="figure">
1148 <table style="border: 1px solid gray;width: 100%;" summary=
1149 "Different values for the region-overflow property - Illustration.">
1150 <tr>
1151 <td>''flow-into: "article"''</td>
1153 <td><code class="html">region_1</code> and <code class=
1154 "html">region_2</code></td>
1156 <td>''region-overflow: auto''<br>
1157 ''overflow:visible''</td>
1158 </tr>
1160 <tr>
1161 <td rowspan="3" style="vertical-align: top;"><img src=
1162 "images/region-overflow-flow.png" alt=
1163 "regions receiving the flow content"></td>
1165 <td><img src="images/region-overflow-regions.png" alt=
1166 "result if region-overflow is set to 'break'"></td>
1168 <td><img src="images/region-overflow-auto-overflow-visible.png"
1169 alt="regions receiving the flow content"></td>
1170 </tr>
1172 <tr>
1173 <td>''region-overflow: break''</td>
1175 <td>''region-overflow: auto''<br>
1176 ''overflow:hidden''</td>
1177 </tr>
1179 <tr>
1180 <td><img src="images/region-overflow-break.png" alt=
1181 "result if region-overflow is set to 'break'"></td>
1183 <td><img src="images/region-overflow-auto-overflow-hidden.png"
1184 alt="regions receiving the flow content"></td>
1185 </tr>
1186 </table>
1188 <p class="caption">Different values for the region-overflow
1189 property</p>
1190 </div>
1192 <div class="note"><span class="note-prefix">Note </span>
1193 <p>The 'overflow' property is honored on a region: if region content overflows,
1194 such as the borders of elements on the
1195 last line, the 'overflow' property controls the visibility of the overflowing
1196 content. See the 'overflow' property definition
1197 ([[CSS21]]).</p>
1198 </div>
1200 <h3 id="the-at-region-style-rule">The @region rule</h3>
1202 <p>An '@region' rule contains style declarations specific to particular
1203 regions.</p>
1205 <pre>
1206 @region <selector> {
1207 ... CSS styling rules ...
1208 }
1209 </pre>
1211 <p>The '@region' rule consists of the keyword '@region' followed by a
1212 <a href="http://www.w3.org/TR/css3-selectors/#selector-syntax">selector</a>
1213 and a block of style rules. The '@region' rule and the selector constitute
1214 the region's 'flow fragment' selector. The region's flow fragment selector
1215 specifies which range of elements in the flow are subject to the style rules in the
1216 following block: it applies to the range (see
1217 [[!DOM]]) from the region's flow that flows in the
1218 selected region(s).</p>
1220 <div class="issue-marker" data-bug_id="15713" data-bug_status="NEW">
1221 <a href=
1222 "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15713">Bug-15713</a>
1224 <div class="issue-details">
1225 <p class="short-desc">Model for styling element fragments</p>
1226 </div>
1227 </div>
1229 <p>Elements that are fully or partially in the 'flow fragment' may match any of the
1230 selectors found in the style rule. However, the style rules only apply to the
1231 portion of the element that falls into the corresponding region.</p>
1235 <p>Only a limited list of properties can be set in a region style rule:</p>
1237 <div class="issue-marker" data-bug_id="15190" data-bug_status="NEW">
1238 <a href=
1239 "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15190">Bug-15190</a>
1241 <div class="issue-details">
1242 <p class="short-desc">List of region style properties</p>
1243 </div>
1244 </div>
1246 <ol>
1247 <li><a href="http://www.w3.org/TR/CSS2/fonts.html">font properties</a></li>
1248 <li><a href="http://www.w3.org/TR/CSS2/colors.html">color property</a></li>
1249 <li><a href="http://www.w3.org/TR/css3-color/#transparency">opacity property</a></li>
1250 <li><a href="http://www.w3.org/TR/css3-background/#backgrounds">background property</a></li>
1251 <li><a href="http://www.w3.org/TR/CSS2/text.html#propdef-word-spacing">'word-spacing'</a></li>
1252 <li><a href="http://www.w3.org/TR/CSS2/text.html#propdef-letter-spacing">'letter-spacing'</a></li>
1253 <li><a href="http://www.w3.org/TR/CSS2/text.html#propdef-text-decoration">'text-decoration'</a></li>
1254 <li><a href="http://www.w3.org/TR/CSS2/text.html#propdef-text-transform">'text-transform'</a></li>
1255 <li><a href="http://www.w3.org/TR/CSS2/visudet.html#propdef-line-height">'line-height'</a></li>
1256 <li><a href="http://www.w3.org/TR/css3-background/#borders">border properties</a></li>
1257 <li><a href="http://www.w3.org/TR/css3-background/#corners">rounded corner properties</a></li>
1258 <li><a href="http://www.w3.org/TR/css3-background/#border-images">border images properties</a></li>
1259 <li><a href="http://www.w3.org/TR/CSS2/box.html#margin-properties">margin properties</a></li>
1260 <li><a href="http://www.w3.org/TR/CSS2/box.html#padding-properties">padding properties</a></li>
1261 <li><a href="http://www.w3.org/TR/css3-text/#text-shadow">'text-shadow' property</a></li>
1262 <li><a href="http://www.w3.org/TR/css3-background/#the-box-shadow">'box-shadow' property</a></li>
1263 <li><a href="http://www.w3.org/TR/css3-background/#the-box-decoration-break">'box-decoration-break' property</a></li>
1264 <li><a href="http://www.w3.org/TR/CSS2/visudet.html#the-width-property">'width' property</a></li>
1265 </ol>
1269 <div class="example" id="region-style-example">
1270 <p>In the following example, the <span>named flow</span> 'article_flow' flows
1271 through 'region_1' and 'region_2'.</p>
1272 <pre>
1273 <style>
1274 #div_1 {
1275 <strong>flow-into: article_flow;</strong>
1276 }
1278 #region1, #region2 {
1279 <strong>flow-from: article_flow;</strong>
1280 }
1282 /* region style "RSA" */
1283 <strong>@region #region1, #region2</strong> {
1284 div {...}
1285 p {...}
1286 }
1288 /* region style "RSB" */
1289 <strong>@region #region1</strong> {
1290 p {...}
1291 }
1293 </style>
1295 <div id="div_1">
1296 <p id="p_1">...</p>
1297 <p id="p_2">...</p>
1298 </div>
1300 <div id="region1"></div>
1301 <div id="region2"></div>
1303 </pre>
1305 <div id="region_styling_illustration">
1306 <img id="region_styling_img_2" src="images/region-styling-2.png"
1307 alt=
1308 "Illustration showing how a named flow content fits into regions to illustrate the @region styling."
1309 name="region_styling_img_2">
1311 <ul class="swatch-list">
1312 <li><span class="swatch" style=
1313 "background:#1C75BC"> </span>div div_1</li>
1315 <li><span class="swatch" style=
1316 "background:crimson"> </span>paragraph p_1</li>
1318 <li><span class="swatch" style=
1319 "background:white"> </span>paragraph p_2</li>
1321 <li><span class="swatch" style=
1322 "background:#E6E7E8"> </span>range of flow that fits into
1323 region_1</li>
1325 <li><span class="swatch" style=
1326 "background:#BCBEC0"> </span>range of flow that fits into
1327 region_2</li>
1328 </ul>
1329 </div>
1331 <p>The region style ''RSA'' applies to flow content that is laid out in either
1332 'region_1' or 'region_2'.</p>
1334 <p>The first rule set ''div {...}'' applies to all <code class=
1335 "html"><div></code> elements that fit partially or fully into 'region_1' or
1336 'region_2'. <code class="html">div_1</code> is split between 'region_1' and
1337 'region_2' and gets the style from this style rule.</p>
1339 <p>The second rule set ''p {...}'' applies to all <code class=
1340 "html"><p></code> elements that fit into 'region_1' or
1341 'region_2'. In our example, both <code class="html">p_1</code>
1342 and <code class="html">p_2</code> are selected.</p>
1344 <p>The region style ''RSB'' applies to flow content that fits in
1345 'region_1'.</p>
1347 <p>The first rule set ''p {...}'' matches <code class="html">p_1</code>
1348 and <code class="html">p_2</code>
1349 because these paragraphs flow into 'region_1'. Only the fragment of
1350 <code class="html">p_2</code> that flows into <code class="html">region_1</code>
1351 is styled with this rule.</p>
1352 </div>
1356 <div class="issue-marker" data-bug_id="15734" data-bug_status="NEW">
1357 <a href=
1358 "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15734">Bug-15734</a>
1360 <div class="issue-details">
1361 <p class="short-desc">@region and specificity</p>
1362 </div>
1363 </div>
1365 <p>The specificity of the selectors in a '@region' rule is calculated as
1366 <a href="http://www.w3.org/TR/css3-selectors/#specificity">defined</a> in
1367 the CSS Selectors module (see [[SELECT]]). In other words, the '@region'
1368 rule adds an extra condition to the selector's matching, but does not
1369 change the selector's specificity. This is the same behavior as selectors
1370 appearing in '@media' rules declaration blocks (see [[MEDIAQ]]), where the
1371 rule does not influence the selectors' specificity.</p>
1373 <p>Consequently, selectors that match a given element (as describe above),
1374 participate in the <a href="http://www.w3.org/TR/2011/REC-CSS2-20110607/cascade.html#cascading-order">CSS Cascading
1375 order</a> as defined in [[!CSS21]].</p>
1377 <div>
1378 Region styling does not apply to nested regions. For example, if a region
1379 'A' receives content from a flow that contains region 'B', the content that
1380 flows into 'B' does not receive the region styling specified for region 'A'.
1381 </div>
1383 <h2 id="multi-column-regions">Multi-column regions</h2>
1385 <p>A
1386 <a href="http://dev.w3.org/csswg/css3-multicol/#multi-column-element">multi-column</a>
1387 [[CSS3COL]]
1388 element can have
1389 an assigned <em><span>named flow</span></em>.
1390 The element becomes part
1391 of the region chain
1392 for that named flow,
1393 and flows its content fragments
1394 through columns according to
1395 the multi-column specification
1396 [[!CSS3COL]].
1397 In particular,
1398 when computing the
1399 <a href="#flow-fragment-height-resolution">flow fragment height</a>
1400 of a multi-column element
1401 that is associated with a <em><span>named flow</span></em>,
1402 the <a href="http://dev.w3.org/csswg/css3-multicol/#column-fill">'column-fill'</a>
1403 [[!CSS3COL]]
1404 property is honored
1405 to balance the fragments of content
1406 that would flow through
1407 its columns.</p>
1409 <div class="example">
1410 <p>The following example:</p>
1411 <pre>
1412 <style>
1413 #multi-col {
1414 column-count: 2;
1415 flow-from: article;
1416 height: 6em;
1417 column-gap: 1em;
1418 }
1420 #remainder {
1421 flow-from: article;
1422 height: auto;
1423 }
1424 </style>
1426 <article>...</article>
1427 <div id="multicol"></div>
1428 <div id="remainder"></div></pre>
1429 <p>is equivalent in rendering to, for example:</p>
1430 <pre>
1431 <style>
1432 #flex {
1433 display: flex;
1434 flex-pack: justify;
1435 height: 6em;
1436 }
1437 #flex > div {
1438 flow-from: article;
1439 width: calc(50% - 0.5em);
1440 }
1442 #remainder {
1443 flow-from: article;
1444 height: auto;
1445 }
1446 </style>
1448 <article>...</article>
1449 <div id="flex">
1450 <div />
1451 <div />
1452 </div>
1453 <div id="remainder"></div></pre>
1457 </div>
1459 <p>Overflow of multicol regions
1460 is mostly handled
1461 according to the same rules
1462 as other CSS Regions.
1463 If the remainder of the named flow
1464 does not fit
1465 in the multicol region,
1466 then the rest
1467 of the content flows into
1468 the remaining region chain.
1469 However,
1470 if a multicol region
1471 is the last region
1472 in a <span>region chain</a>,
1473 then the multicol region must follow the
1474 <a href="http://dev.w3.org/csswg/css3-multicol/#overflow-columns">overflow column rules</a>
1475 [[!CSS3COL]].</p>
1477 <h2 id="pseudo_elements">Pseudo-elements</h2>
1479 <div class="issue-marker" data-bug_id="15188" data-bug_status="NEW">
1480 <a href=
1481 "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15188">Bug-15188</a>
1483 <div class="issue-details">
1484 <p class="short-desc">add functionality for having textual description like "continued here" or "continued on page x" to regions.</p>
1485 </div>
1486 </div>
1488 <p>It can be useful
1489 to visually mark the content
1490 to highlight that a content thread
1491 is flowing through the region chain.
1492 For example, a marker
1493 such as <em>'continued below'</em> clearly indicates,
1494 at the end of a CSS Region,
1495 that there is more content in the flow
1496 which can be found by scrolling past
1497 whatever content interrupts the region chain.</p>
1499 <p>The '::before' and '::after' pseudo-elements (see [[!SELECT]])
1500 let content authors mark the beginning
1501 and end of a region with such markers.</p>
1503 <h3 id="processing-model">Processing model</h3>
1505 <p>The '::before' content is laid out
1506 in the region prior to
1507 any other content coming from the flow.
1508 Note that it is possible
1509 to set the '::before' pseudo-element's 'display' property
1510 to 'run-in' to align it
1511 with the content's inline boxes.</p>
1513 <p>The '::after' content is laid out
1514 in the region after laying out
1515 the flow fragment content.
1516 Then, flow content is removed from the fragment
1517 to accommodate the '::after' content.
1518 Accommodating means that the '::after' content
1519 is laid out without overflowing the region.
1520 The 'display' property of the '::after' content
1521 can be set to 'run-in' to align
1522 with the region's content's inline boxes.
1523 In that case, the '::after' content becomes
1524 the last inline box of the previous element
1525 in the flow that has some visual rendering
1526 in the region and can accommodate for the '::after' box.</p>
1528 <p>If there is not enough room to accommodate
1529 the ::before content,
1530 the '::after' content after removing all flow fragment content,
1531 or a combination of the two,
1532 then the ::before and/or ::after content overflows.</p>
1534 <h2 id="cssom_view_and_css_regions">CSSOM</h2>
1536 <div class="issue-marker-wrapper">
1537 <div class="issue-marker" data-bug_id="15679" data-bug_status="NEW">
1538 <a href=
1539 "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15679">Bug-15679</a>
1541 <div class="issue-details">
1542 <p class="short-desc">elementFromPoint and CSS regions</p>
1543 </div>
1544 </div>
1545 <div class="issue-marker" data-bug_id="15933" data-bug_status="ASSIGNED">
1546 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15933">Bug-15933</a>
1547 <div class="issue-details">
1548 <p class="short-desc">Terms in WebIDL snippets inconsistently linked</p>
1549 </div>
1550 </div>
1551 </div>
1553 <p>Since content may flow into multiple regions, authors need a way to
1554 determine if there are enough regions to flow all the content from a named
1555 flow. This is especially important considering that the size of regions or
1556 the size of the content may change depending on the display context. For
1557 example, flowing the same content on a mobile phone with a small screen may
1558 require more regions than on a large desktop display. Another example is the
1559 user changing the font size of text flowing through regions. Depending on
1560 the change, new regions may be needed to accommodate for the additional
1561 space required to fit the larger text or some regions may need to be removed
1562 for smaller text.
1563 </p>
1565 <h3 id="the-namedflow-interface">The NamedFlow interface</h3>
1567 <p>A <span>named flow</span> is created when it becomes referenced by the
1568 'flow-into' and/or 'flow-from' computed values. The following APIs allow
1569 scripts to reference a <code class="idl">NamedFlow</code> object representation
1570 of a <span>named flow</span>.</p>
1572 <p>An additional method and an additional attribute on the <a href=
1573 "http://www.w3.org/TR/dom/#interface-document"><code class=
1574 "idl">Document</code></a> interface provide access to <span>named flows</span>.</p>
1576 <pre class="idl">
1577 partial interface <a href=
1578 "http://www.w3.org/TR/dom/#interface-document">Document</a> {
1579 readonly attribute <a href="#dom-named-flow-collection">NamedFlowCollection</a> <a href="#document-namedflows">namedFlows</a>;
1580 <a href="#dom-named-flow">NamedFlow?</a> <a href="#document-getflowbyname">getFlowByName(DOMString name)</a>;
1581 };
1582 </pre>
1584 <p>The <dfn id="document-namedflows"><code class="idl">namedFlows</code></dfn> attribute on the <a href=
1585 "http://www.w3.org/TR/dom/#interface-document"><code class=
1586 "idl">Document</code></a> interface returns the live list of all the current <span>named
1587 flows</span> in the document. </p>
1589 <p>The <code class="idl">namedFlows</code> collection must include all <span>named flows</span>
1590 that are currently in the <code>CREATED</code> state.
1591 The list must not include <span>named flows</span> that are in the <code>NULL</code> state. </p>
1593 <p>The <dfn id="document-getflowbyname"><code class="idl">getFlowByName</code></dfn> method on the <a href=
1594 "http://www.w3.org/TR/dom/#interface-document"><code class=
1595 "idl">Document</code></a> interface provides access to the document's <code class="idl">NamedFlow</code>
1596 instances. The return value depends on the <span>named flow</span>
1597 state:</p>
1599 <ul>
1600 <li><code class="idl">NULL</code>: the user agent must return <code>null</code>.</li>
1601 <li><code class="idl">CREATED</code>: the user agent must return a valid
1602 <code class="idl">NamedFlow</code> instance.</li>
1603 </ul>
1606 <p>The <dfn id="dom-named-flow-collection"><code class="idl">NamedFlowCollection</code></dfn>
1607 interface provides a list of current <code class="idl">NamedFlow</code> instances in the
1608 document. The collection is live and methods operate on the underlying data, not a snapshot of
1609 the data.</p>
1611 <pre class="idl">
1612 interface NamedFlowCollection {
1613 readonly attribute unsigned long <a href="#dom-named-flow-collection-length">length</a>;
1614 getter <a href="#dom-named-flow">NamedFlow?</a> <a href="#named-flow-collection-item">item (unsigned long index)</a>;
1615 };</pre>
1617 <p>The <dfn id="dom-named-flow-collection-length"><code class="idl">length</code></dfn>
1618 attribute returns the number of items in the collection.</p>
1619 <p>The <dfn id="dom-named-flow-collection-item"><code class="idl">item(index)</code></dfn>
1620 method returns the item at index <em>index</em>
1621 in the collection or <code class="idl">null</code> if <em>index</em> is out of range.
1622 An object <code>collection</code> implementing <code>NamedFlowCollection</code> supports
1623 indices in the range <code>0 ≤ index < collection.length</code>.</p>
1625 <p>The <dfn id="dom-named-flow"><code class="idl">NamedFlow</code></dfn>
1626 interface offers a representation of a <span>named flow</span> instance.</p>
1628 <p>The <code class="idl">NamedFlow</code> interface
1629 can be used for different purposes.
1630 For example, the <code>getRegionsByContent()</code> method
1631 can help navigate by bookmark:
1632 a script can find the <span>region</span>s
1633 that display a particular anchor
1634 and bring them to view.</p>
1636 <p>Likewise, the interface allows authors
1637 to check if all content has been fitted
1638 into existing regions.
1639 If it has, the <code>overset</code> attribute
1640 would be false.</p>
1642 <pre class="idl">
1643 interface <a href="#dom-named-flow">NamedFlow</a> implements <a href="http://www.w3.org/TR/dom/#interface-eventtarget">EventTarget</a> {
1644 readonly attribute DOMString <a href="#dom-named-flow-name">name</a>;
1645 readonly attribute boolean <a href="#dom-named-flow-overset">overset</a>;
1646 sequence<<a href="#region-interface">Region</a>> <a href="#dom-named-flow-get-regions">getRegions()</a>;
1647 readonly attribute integer <a href="#dom-named-flow-first-empty-region-index">firstEmptyRegionIndex</a>;
1648 <a href="http://www.w3.org/TR/dom/#interface-nodelist">NodeList</a> <a href="#dom-named-flow-get-content">getContent()</a>;
1649 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)</a>;
1650 };</pre>
1652 <p>The <dfn id="dom-named-flow-name"><code class="idl">name</code></dfn> attribute
1653 returns the name of the <code class="idl">NamedFlow</code> instance.</p>
1655 <p>The <dfn id="dom-named-flow-overset"><code class= "idl">overset</code></dfn>
1656 attribute returns true
1657 if there are <span>named flow</span> fragments
1658 that do not fit in the associated region chain.
1659 The attribute also returns true
1660 if there is no associated region chain.
1661 Otherwise, it returns false. </p>
1663 <p>The <dfn id="dom-named-flow-get-regions"><code class="idl">getRegions()</code></dfn>
1664 method returns the sequence
1665 of regions in the <span>region chain</span>
1666 associated with the <span>named flow</span>.
1667 Note that the returned values
1668 is a static sequence
1669 in document order.</p>
1671 <p>The <dfn id="dom-named-flow-first-empty-region-index">firstEmptyRegionIndex</dfn>
1672 is the index of the first region
1673 in the region chain with the <code>regionOverset</code> attribute
1674 set to <code>empty</code>.
1675 If all regions have the <code>regionOverset</code> attribute
1676 set to <code>fit</code> or <code>overset</code>,
1677 the value for <code>firstEmptyRegionIndex</code> is <code>-1</code>.
1678 If there are no regions in the <span>region chain</span>,
1679 the value is <code>-1</code> as well. </p>
1681 <p>The <dfn id="dom-named-flow-get-content">getContent()</dfn>
1682 method returns an ordered collection
1683 of nodes that constitute the <span>named flow</span>.
1684 The returned list is a static snapshot
1685 of the <span>named flow</span> content
1686 at the time the method is invoked.
1687 This list contains the elements
1688 that were moved to the <span>named flow</span>
1689 but not their descendants
1690 (unless the descendants are themselves
1691 moved to the <span>named flow</span>).
1692 </p>
1694 <p>The <dfn id="dom-named-flow-get-regions-by-content">getRegionsByContent()</dfn>
1695 method returns the sequence of regions
1696 that contain at least part
1697 of the target content node.
1698 Note that the returned values
1699 is a static sequence
1700 in document order.</p>
1703 <p>The <span>named flow</span> states are :</p>
1705 <ul>
1706 <li><code class="idl">NULL</code>: the <span>named flow</span> is not referenced
1707 by any 'flow-into' or 'flow-from' computed value.</li>
1708 <li><code class="idl">CREATED</code>: the <span>named flow</span> is referenced by
1709 at least one 'flow-into' or 'flow-from' computed value.</li>
1710 </ul>
1712 <p>A <code class="idl">NamedFlow</code>
1713 object is live: it always represents the <span>named flow</span> with the corresponding
1714 name even if that <span>named flow</span> has transitioned to the <code>NULL</code> state.</p>
1716 <p>If a script holds a reference to a <code class="idl">NamedFlow</code> instance that
1717 has entered the <code>NULL</code> state, its attributes and methods should behave
1718 as follows:</p>
1720 <ul>
1721 <li>the <code class="idl">name</code> attribute returns its value as normal.</li>
1722 <li>the <code class="idl">overset</code> attribute returns <code class="idl">true</code>.</li>
1723 <li>the <code class="idl">getRegions</code> method returns an empty sequence.</li>
1724 <li>the <code class="idl">firstEmptyRegionIndex</code> attribute returns <code class="idl">-1</code>.</li>
1725 <li>the <code class="idl">getContent()</code> method returns an empty <code class="idl">NodeList</code> instance.</li>
1726 <li>the <code class="idl">getRegionsByContentNode()</code> method retuns an empty sequence.</li>
1727 </ul>
1729 <div class="issue-marker" data-bug_id="16382" data-bug_status="ASSIGNED">
1730 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16382">Bug-16382</a>
1731 <div class="issue-details">
1732 <p class="short-desc">Should we have a NamedFlow.getRegionsByFlowRanges?</p>
1733 </div>
1734 </div>
1736 <h3 id="the-region-interface">The Region interface</h3>
1738 <p>The <dfn id='region-interface'><code class="idl">Region</code> interface</dfn>
1739 provides an abstraction for <a href=
1740 "http://www.w3.org/TR/dom/#interface-element"><code class=
1741 "idl">Element</code>s</a>, pseudo-elements or other CSS constructs (such as
1742 <a href="http://dev.w3.org/csswg/css3-page-template/#templates-and-slots">slots</a>
1743 [[!CSS3-PAGE-TEMPLATE]]) which can be regions.</p>
1745 <pre class="idl">
1746 interface Region {
1747 readonly attribute DOMString <a href="#dom-region-regionoverset">regionOverset</a>;
1748 readonly attribute DOMString <a href="#dom-region-flowfrom">flowFrom</a>;
1749 sequence<<a href="#">Range</a>>? <a href=
1750 "#dom-region-getregionflowranges">getRegionFlowRanges()</a>;
1751 };</pre>
1753 <p>The <dfn id="dom-region-regionoverset"><code class=
1754 "idl">regionOverset</code></dfn> attribute returns one of the following
1755 values:</p>
1757 <dl>
1758 <dt>'overset'</dt>
1760 <dd>The region is the last one in the
1761 <span title="region-chain">region chain</span> and
1762 not able to fit the remaining content from the <span>named flow</span>.
1763 Note that the region's <a href=
1764 "http://www.w3.org/TR/CSS21/visufx.html#overflow"><code class=
1765 "idl">overflow</code></a> property value can be used to control the
1766 visibility of the overflowing content and the
1767 'region-overflow' property controls whether or not fragmentation happens
1768 on the content that overflows the last region.</dd>
1770 <dt>'fit'</dt>
1772 <dd>The region's flow fragment content fits into the region's <a href=
1773 "http://www.w3.org/TR/CSS21/box.html#box-dimensions">content box</a>.
1774 If the region is the last one in the <span title=
1775 "region-chain">region chain</span>, it means that the content fits
1776 without overflowing. If the region is not the last one in the region
1777 chain, that means the <span>named flow</span>
1778 content is further fitted in subsequent regions. In this
1779 last case, note that the <span>named flow</span> fragment may be
1780 empty (for example if the region is too small to accommodate any content).</dd>
1782 <dt>'empty'</dt>
1784 <dd>All content from the <span>named flow</span> was fitted in prior regions.</dd>
1786 </dl>
1788 <p>Note that if there is no content in the <span>named flow</span>, all regions associated
1789 with that <span>named flow</span> should have their <code class="idl">regionOverset</code>
1790 attribute return 'empty'.
1791 If there is content in the flow but that content does not generate any box
1792 for visual formatting, the 'overset' attribute on the first region in the
1793 region chain associated with the flow will return 'fit'.</p>
1795 <p>The <dfn id="dom-region-flowfrom">flowFrom</dfn> attribute returns the name of the
1796 <span>named flow</span> this region is associated with.</p>
1798 <p>The <dfn id="dom-region-getregionflowranges">getRegionFlowRanges</dfn> method
1799 returns an array of <a href= "http://www.w3.org/TR/dom/#interface-range">Range</a>
1800 instances corresponding to fragment
1801 from the <span>named flow</span>
1802 that is laid out in the region.
1803 If the region has not received a fragment
1804 because it is too small to accommodate any,
1805 the method returns a single <code class="idl">Range</code>
1806 where the <code>startContainer</code>
1807 and <code>startOffset</code>
1808 have the same values as
1809 the <code>endContainer</code>
1810 and <code>endOffset</code>
1811 and therefore the collapsed attribute
1812 on the <code class="idl">Range</code> is true.
1813 In that situation,
1814 if the region is the first
1815 in the <span>region chain</span>,
1816 the <code>startContainer</code>
1817 is the first <code>Node</code>
1818 in the <span>named flow</span>
1819 and the <code>startOffset</code> is zero.
1820 If the region is the last region
1821 in the region chain
1822 (but not the first and only one),
1823 the <code>startContainer</code>
1824 and <code>startOffset</code>
1825 are the same values as
1826 the <code>endContainer</code>
1827 and <code>endOffset</code>
1828 on the previous region
1829 in the <span>region chain</span>.
1830 The method returns null
1831 if the <span>region</span> object
1832 is not (or no longer) a region.</p>
1834 <div class="note">
1835 <p>A <code class="idl">Region</code> instance may represent and
1836 object that is no longer a <span>region</span>. This may happen, for example if the
1837 'flow-from' property on the corresponding pseudo-element, element or other construct
1838 becomes 'none' but a script is still holding a reference to the <code class="idl">Region</code> object.</p>
1839 </div>
1841 <p>If a <code class="idl">Region</code> instance is no longer a <span>region</span>,
1842 accessing its attributes (<code class="idl">regionOverset</code> and <code class="idl">flowFrom</code>) or
1843 invoking its <code class=
1844 "idl"><span title="#document-element-getregionflowranges">getRegionFlowRanges</span></code>
1845 method throws a <a href="http://www.w3.org/TR/dom/#interface-domexception"><code class="idl">DOMException</code></a> with the
1846 <a href="http://www.w3.org/TR/dom/#dom-domexception-invalid_access_err"><code class="idl">INVALID_ACCESS_ERR</code></a> error code.</p>
1847 </div>
1849 <h3 id="region-style-rule-interface">The CSSRegionStyleRule interface</h3>
1851 <p>The CSSRegionStyleRule interface represents
1852 an '@region' rule
1853 in a CSS style sheet.
1854 This rule type is added
1855 to the <a href="http://dev.w3.org/csswg/cssom/#cssrule"><code>CSSRule</code></a> [[!CSSOM]] interface.</p>
1857 <pre class="idl">
1858 partial interface CSSRule {
1859 const unsigned short REGION_STYLE_RULE = 1001;
1860 }
1861 </pre>
1862 <dt>REGION_STYLE_RULE</dt>
1863 <dd>The rule is a CSSRegionStyleRule</dd>
1865 <pre class="idl">
1866 interface CSSRegionStyleRule : CSSRule {
1867 attribute DOMString selectorText;
1868 readonly attribute CSSRuleList cssRules;
1869 unsigned long insertRule(DOMString rule, unsigned long index)
1870 raises(DOMException);
1871 void deleteRule(unsigned long index)
1872 raises(DOMException);
1873 };
1874 </pre>
1876 <p>The <dfn id="region-style-rule-selectorText">
1877 <code class="idl">selectorText</code></dfn>
1878 attribute gets and sets
1879 the associated selector
1880 as defined in section <a href="http://dev.w3.org/csswg/cssom/#dom-cssstylerule-selectortext">6.4.3</a> of [[!CSSOM]].
1882 <p>The <dfn id="region-style-rule-cssRules">
1883 <code class="idl">cssRules</code></dfn>
1884 attribute must return a
1885 <a href="http://dev.w3.org/csswg/cssom/#cssrulelist"><code>CSSRuleList</code></a> [[!CSSOM]]
1886 object for the list of
1887 <a href="http://www.w3.org/TR/DOM-Level-2-Style/css.html#CSS-CSSStyleRule"><code class="idl">CSSStyleRules</code></a>
1888 specified in the region style block.</p>
1890 <p>The <dfn id="region-style-rule-insertRule">
1891 <code class="idl">insertRule(rule, index)</code></dfn>
1892 method inserts a
1893 <a href="http://www.w3.org/TR/DOM-Level-2-Style/css.html#CSS-CSSStyleRule"><code class="idl">CSSStyleRule</code></a>
1894 into the region style block
1895 before the specified index.
1896 If the index is equal to the length
1897 of the <a href="http://dev.w3.org/csswg/cssom/#cssrulelist"><code>CSSRuleList</code></a> the
1898 <a href="http://www.w3.org/TR/DOM-Level-2-Style/css.html#CSS-CSSStyleRule"><code class="idl">CSSStyleRule</code></a>
1899 is inserted at the end of the list.</p>
1901 <p>Possible exceptions:</p>
1902 <ul>
1903 <li>HIERARCHY_REQUEST_ERR:
1904 Raised if the rule to insert is not a
1905 <a href="http://www.w3.org/TR/DOM-Level-2-Style/css.html#CSS-CSSStyleRule"><code class="idl">CSSStyleRule</code></a>.</li>
1906 <li>INDEX_SIZE_ERR:
1907 Raised if the specified index
1908 is not a valid insertion point.</li>
1909 <li>SYNTAX_ERR:
1910 Raised if the specified rule
1911 has a syntax error
1912 and is unparsable.</li>
1913 </ul>
1914 <p>The <dfn id="region-style-rule-deleteRule">
1915 <code class="idl">deleteRule(index)</code></dfn>
1916 method deletes the <a href="http://www.w3.org/TR/DOM-Level-2-Style/css.html#CSS-CSSStyleRule"><code class="idl">CSSStyleRule</code></a> in the CSSRuleList
1917 at the specified index.</p>
1919 <p>Possible exceptions:</p>
1920 <ul>
1921 <li>INDEX_SIZE_ERR:
1922 Raised if the specified index
1923 does not correspond to a rule
1924 in the region style block.</li>
1925 </ul>
1927 <h3 id="region-flow-layout-events">Region flow layout events</h3>
1929 <p><a href="#dom-named-flow"><code class="idl">NamedFlow</code></a> objects are
1930 <a href="">Event Targets</a> which
1931 dispatch <code class="idl">regionLayoutUpdate</code> events when there is a
1932 possible layout change of their <span>named flow</span> fragment. Note that the event is asynchronous.</p>
1934 <div class="issue-marker" data-bug_id="16391" data-bug_status="ASSIGNED">
1935 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16391">Bug-16391</a>
1936 <div class="issue-details">
1937 <p class="short-desc">regionLayoutUpdate needs to be async</p>
1938 </div>
1939 </div>
1940 <div class="note">The remaining issue in this bug is when the event gets fired.</div>
1942 <table class="event-desc" border="0" summary="This table contains information about the semantics of the given event type" cellpadding="2" cellspacing="0">
1943 <tbody><tr class="assert must"><th>Type</th>
1944 <td class="eventname"><strong><code>regionLayoutUpdate</code></strong></td></tr>
1945 <tr class="assert must"><th>Interface</th> <td><code><a href="http://www.w3.org/TR/DOM-Level-3-Events/#webidl-events-UIEvent">UIEvent</a></code> (see [[!DOM-LEVEL-3-EVENTS]])</td></tr>
1946 <tr class="assert must"><th>Sync / Async</th> <td>Async</td></tr>
1947 <tr class="assert must"><th>Bubbles</th> <td>Yes</td></tr>
1948 <tr class="assert must"><th>Target</th> <td><a href="#dom-named-flow"><code class="idl">NamedFlow</code></a></td></tr>
1949 <tr class="assert must"><th>Cancelable</th> <td>Yes</td></tr>
1950 <tr class="assert must"><th>Default action</th> <td>none</td></tr>
1951 <tr class="assert must"><th>Context info</th>
1952 <td>
1953 <ul>
1954 <li><code class="attribute-name">Event.target</code>:
1955 <a href="#dom-named-flow"><code class="idl">NamedFlow</code></a> whose layout may have changed</li>
1956 </ul>
1957 </td>
1958 </tr>
1959 </tbody></table>
1961 <h3 id="cssomview-and-regions">Clarifications on pre-existing APIs</h3>
1964 <h4 id="cssomview-getclientrects-and-getboundingclientrect"><code class="idl">getClientRects()</code> and <code>getBoundingClientRects()</code></h4>
1966 <p>The <a href="http://www.w3.org/TR/cssom-view/">CSSOM View Module</a>
1967 defines how user agents compute
1968 the bounding client rectangle
1969 for an element (<code class="idl">getBoundingClientRect()</code>)
1970 and its generated boxes (<code class="idl">getClientRects()</code>).</p>
1972 <p>This definition applies to
1973 the (possibly) multiple boxes
1974 generated for an element in a named flow
1975 flowing through a region chain.
1976 The <code class="idl">getClientRects()</code> method
1977 returns the list of boxes generated
1978 for each of the element fragments
1979 laid out in different regions.
1980 The <code>getBoundingClientRect()</code> method
1981 operates as specified in the
1982 <a href="http://www.w3.org/TR/cssom-view/">CSSOM View Module</a>
1983 as well and is computed
1984 from the set of rectangles
1985 returned by <code class="idl">getClientRects()</code>.</p>
1987 <h4 id="cssomview-offset-attributes"><code class="idl">offsetTop</code>, <code class="idl">offsetLeft</code>,
1988 <code class="idl">offsetWidth</code> and <code class="idl">offsetWidth</code></h4>
1990 <p>The computation of the <a href="http://dev.w3.org/csswg/cssom-view/#offset-attributes">offset attributes</a>
1991 for elements laid out in a <span>named flow</code> follow the <a href="http://dev.w3.org/csswg/cssom-view/#offset-attribute">specification</a>. For the purpose of the
1992 algorithm, the <em>first CSS layout box</em> associated
1993 with an element laid out in a <span>named flow</span> is the box generated for the first region
1994 the element is laid out into.</p>
1996 <h2 id="regions-visual-formatting-details">Regions visual formatting details</h2>
1998 <p>Regions are laid out by CSS and take part in the normal box model and other layout models
1999 offered by CSS modules such as flexible boxes ([[CSS3-FLEXBOX]]). However, <span>regions</span>
2000 lay out a fragment of their <span>named flow</span> instead of laying out descendant content as happens with other
2001 boxes.</p>
2003 <p>This section describes the model for laying out <span>regions</span>
2004 and for laying out <span>named flow</span> content into regions.
2005 The descriptions in this section are biased towards a horizontal writing mode,
2006 using <span>width</span> for logical width (or measure)
2007 and <span>height</span> for logical height (or extent)
2008 as <a href="http://www.w3.org/TR/css3-writing-modes/#abstract-dimensions">defined</a>
2009 in the CSS Writing Modes Module [[!CSS3-WRITING-MODES]]).
2010 To use this model in a vertical writing mode apply the principles
2011 <a href="http://www.w3.org/TR/css3-writing-modes/#vertical-layout">described</a>
2012 in that specification.</p>
2014 <h3 id="regions-flow-content-box">The Region Flow Content Box (RFBC)</h3>
2016 <p>A region box lays out the following boxes:</p>
2018 <ul>
2019 <li>The boxes generated by its <code class="css">::before</code> and
2020 <code class="css">::after</code> pseudo-elements, if any.</code>
2021 <li>The anonymous <def>region flow content box</dev> (called <def>RFCB</def> in this document) which
2022 contains the fragment of the <span>named flow</span> that the region receives.</li>
2023 </ul>
2025 <div class="figure">
2026 <img src="images/RFCB.svg" width="600px" />
2027 <p class="caption">The Region Flow Content Box (RFCB)</p>
2028 </div>
2030 <p>Laying out a <span>region</span> box follows the same processing rules as for any other
2031 <a href="http://www.w3.org/TR/CSS2/visuren.html#block-boxes">block container box</a>.</p>
2033 <p>The <span>RFCB</span> is a <a href="http://www.w3.org/TR/CSS21/visuren.html#block-boxes">block container box</a>
2034 with a <a href="">computed</a> 'width' of 'auto' and a whose <a href="">used</a> 'height' is
2035 resolved as detailed below.</li>
2037 <h4 id="rfbc-width-resolution">RFCB 'width' resolution</h4>
2039 <p>At various points in the visual formatting of documents containing regions, the
2040 used 'width' of RFCBs and regions need to be resolved. In all cases, the resolution is done following the
2041 rules for <a href="http://www.w3.org/TR/CSS2/visudet.html#Computing_widths_and_margins">calculating
2042 widths and margins</a> (see [[!CSS21]]). Sometimes, resolving the used 'width' value
2043 requires measuring the content's
2044 <code class="css">min-content</code> and <code class="css">max-content</code> values (as
2045 <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
2046 made on the <em>entire</em> associated <span>named flow</span> content</strong>.</p>
2048 <p>As a consequence, all <span>RFCBs</span> of <span>regions</span> associated with a given
2049 <span>named flow</span> share the
2050 same <code class="css">min-content</code> and <code class="css">max-content</code> measures.</p>
2052 <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>
2055 <h3 id="regions-visual-formatting-steps">Regions visual formatting steps</h3>
2057 <p>Formatting documents that contain <span>named flows</span> laid out in regions is a three-step
2058 process:</p>
2060 <ul>
2061 <li><em>Step 1: RFCB <def>flow fragment height</def> resolution</em>. In this step, the heights of fragments
2062 fitting in the regions' RFCBs are resolved.</li>
2063 <li><em>Step 2: document and regions layout</em>. In this step, the document content and regions are
2064 laid out. However, <span>named flow</span> content is not laid out in regions yet.</li>
2065 <li><em>Step 3: <span>named flow</span> layout</em>. In this step, the content of <span>named flows</span> is laid
2066 out in their respective <span>region chains</span>.</li>
2067 </ul>
2069 <div class="figure">
2070 <img src="images/regions-layout-three-steps.svg" width="600px" />
2071 <p class="caption">Regions visual formatting steps</p>
2072 </div>
2075 <h4 id="rfcb-flow-fragment-height-resolution">Step 1: RFCB flow fragment height resolution</h4>
2077 <p>Conceptually, resolving the flow fragment height is a two phase process.</p>
2079 <h5 id="rfcb-flow-fragment-height-resolution-phase-1">RFCB flow fragment height resolution, Phase 1</h5>
2081 <p>The document is laid out with a
2082 <a href="http://www.w3.org/TR/CSS2/cascade.html#used-value">used</a> height of zero
2083 for all <span>RFCB</span>s. In this phase, the content of <span>named flows</span> is not laid out in
2084 <span>regions</span>. This phase yields resolved position and sizes for all regions and
2085 their RFCBs in the document.</p>
2087 <h5 id="rfcb-flow-fragment-height-resolution-phase-2">RFCB flow fragment height resolution, Phase 2</h5>
2089 <p><span>Named flows</span> are laid out in <span>regions</span>. The
2090 user agent resolves the <em><span>flow fragment height</span></em> for
2091 the <span>RFCB</span>s using the remainder of the flow and accounting for
2092 <a href="http://www.w3.org/TR/css3-break/">fragmentation rules</a>.
2093 This process accounts for constraints such as the 'height' or 'max-height' values, as described
2094 in the CSS 2.1 section on
2095 <a href="http://www.w3.org/TR/CSS2/visudet.html#Computing_heights_and_margins">calculating heights
2096 and margins</a> (see the <a href="http://www.w3.org/TR/CSS2/visudet.html#normal-block">Block-level
2097 non-replaced elements in normal flow when 'overflow' computes to 'visible'</a> section and the
2098 <a href="http://www.w3.org/TR/CSS2/visudet.html#block-root-margin">complicated cases</a> section).
2099 During this phase, generated content is laid out according to the
2100 <a href="#processing-model">rules</a> described earlier in this document.
2101 </p>
2103 <h4 id="regions-boxes-layout">Step 2: region boxes layout</h4>
2105 <p>In this step, the document is laid out according to the normal CSS layout rules.</p>
2107 <p>If a measure of the content is required to resolve the used 'width' of the region box, the value
2108 is resolved as described in the
2109 <a href="#rfbc-width-resolution">RFCB width resolution</a> section.</p>
2111 <p>If a measure of the content
2112 is required to resolve the used height of the RFCB (for example if the region box is absolutely positioned),
2113 the <span>flow fragment height</span> resolved in Step 1 is used for the vertical content measure of the
2114 RFCB.</p>
2116 <p>At the end of this step, regions are laid out and ready to receive
2117 content from their associated <span>named flows</span>.</p>
2119 <h4 id="named-flows-layout">Step 3: named flows layout</h4>
2121 <p>In this final step, the content of <span>named flows</span> is laid out in the <span>regions</span>' RFCBs
2122 along with the generated content boxes.</p>
2124 <p>The used 'width' for RFCBs is resolved <a href="#rfbc-width-resolution">as described before</a>.</p>
2126 <p>The used 'height' of RFCBs is resolved such that none of the boxes in the region box's normal flow
2127 overflow the region's box. In other words, the RFCB boxes are stretched vertically
2128 to accommodate as much of the flow as possible without overflowing the region box and
2129 accounting for <a href="http://www.w3.org/TR/css3-break/">fragmentation rules</a> and
2130 generated content boxes.</p>
2132 <p>During this phase, generated content is laid out according to the
2133 <a href="#processing-model">rules</a>
2134 described earlier in this document.</p>
2136 <div class="note">
2137 <p>The model for resolving auto sized regions will cause, under certain circumstances,
2138 the flow content to be overset or underset. In other words, it will not fit tightly.
2139 The model prevents having circular dependencies in the layout model. Implementations
2140 may decide to apply further layout steps to ensure that the whole flow content is
2141 displayed to the user, even in edge cases.</p>
2142 </div>
2144 <h3 id="regions-visual-formatting-implementation-note">Regions visual formatting: implementation note</h3>
2146 <p>The process for resolving an RFCB's 'height' and the three-step process used to
2147 lay out documents containing regions and <span>named flows</span> are
2148 <em>conceptual</em> descriptions of what the layout
2149 should yield and implementations should optimize to reduce the number of
2150 steps and phases necessary wherever possible.</p>
2152 <h3 id="regions-visual-formatting-examples">Regions visual formatting example</h3>
2154 <p>This section is non-normative.</p>
2156 <p>This example considers a document where content flows between three regions,
2157 and region boxes are intermixed with the normal document content.</p>
2159 <div class="example">
2160 <pre>
2161 <style>
2162 article {
2163 flow-into: article;
2164 }
2166 #rA, #rB, #rC {
2167 flow-from: article;
2168 height: auto;
2169 margin: 1em 1em 0em 1em;
2170 padding: 1em;
2171 border: 3px solid #46A4E9;
2172 }
2174 #rA {
2175 width: auto;
2176 height: auto;
2177 }
2179 #rB {
2180 float: left;
2181 width: 15em;
2182 height: auto;
2183 max-height: 150px;
2184 }
2186 #rC {
2187 float: right;
2188 width: 12em;
2189 height: auto;
2190 }
2192 #main-flow {
2193 padding: 0em 1em 0em 1em;
2194 }
2196 </style>
2197 <body>
2198 <article>
2199 <p style="region-break-after:always;">I am not a ... </p>
2200 <p>...</p>
2201 </article>
2202 <div id="rA"></div>
2203 <div id="rB"></div>
2204 <div id="rC"></div>
2206 <div id="main-flow">
2207 <p>Lorem ipsum dolor ...</p>
2208 </div>
2209 </body>
2210 </pre>
2211 </div>
2213 <p>The following sections and figures illustrate the intermediate results for the visual formatting process.
2214 In the following, we call RFCB-A, RFCB-B and RFCB-C the <span>RFCBs</span> for
2215 regions rA, rB and rC respectively. </p>
2217 <h4>Step 1 - Phase 1: Laying out RFCBs with used height of zero</h4>
2219 <p>Applying the rules for Step 1, Phase 1, the computed 'auto' 'width' values for the RFCBs are resolved
2220 to used values according to the normal
2221 <a href="http://www.w3.org/TR/CSS2/visudet.html#Computing_widths_and_margins">CSS layout rules</a> meaning they
2222 stretch to the width of their containing block's content box.</p>
2224 <ol>
2225 <li>RFCB-A: stretches to fit the rA content box.</li>
2226 Since rA also has an 'auto' 'width', its own used 'width' is stretched to fit the
2227 <code><body></code> content box.</p>
2228 <li>RFCB-B: stretches to fit the <code>rB</code> content box.</li>
2229 <li>RFCB-C: stretches to fit the <code>rC</code> content box.</li>
2230 </ol>
2232 <p>Also applying the rules for Step 1, Phase 1, the used values for the RFCBs 'height' properties are all zero.</p>
2234 <p>Conceptually, this produces the layout illustrated below.</p>
2236 <div class="figure">
2237 <img src="images/flow-fragment-height-phase-1.png" width="500px" alt="Step 1 - Phase 1: Layout RFBCs with used heights of 0"/>
2238 <p class="caption">Step 1 - Phase 1: Layout RFBCs with used heights of 0</p>
2239 </div>
2241 <h4>Step 1 - Phase 2: Layout flow to compute the RFCBs' flow fragments heights</h4>
2243 <p>In this second phase of Step 1, the named flow is laid out in <span>regions</span>
2244 and the height of each fragment falling in each RFCB is computed.</p>
2246 <p>The user agent lays out as much of the flow into an area
2247 with RFCB-A's used 'width'. rA's 'height' computes to 'auto' and there is no vertical maximum
2248 height for RFCA's 'height'. However, because there is a break after the
2249 first paragraph in the 'article' <code>named flow</code>, only this first paragraph is
2250 laid out in RFCB-A and FH-A (the flow fragment height for RFCB-A) is resolved by laying out
2251 this first paragraph in the used 'width'.</p>
2253 <p>At this point, the user agent lays out as much of the remaining flow as possible in RFCB-B.
2254 Because rB's 'max-height' computed value is '150px', the user agent only lays out
2255 the 'article' named flow using RFCB-B's used 'width' until the point where
2256 laying out additional content would cause RFCB-B to overflow rB's box.
2257 The fragment height for RFCB-B is resolved: FH-B (<code class="css">150px</code>).</p>
2259 <p>Finally, the user agent lays out the remainder of the flow in RFCB-C.
2260 Because rC has no other constraints and no region breaks, the remaining content is
2261 laid out in RFCB-C's used 'width'. This results in a resolved flow fragment height: FH-C.</p>
2263 <div class="figure">
2264 <img src="images/flow-fragment-height-phase-2.png" width="370px" alt="Step 1 - Phase 2: Measure flow fragments heights"/>
2265 <p class="caption">Step 1 - Phase 2: Measure flow fragments heights</p>
2266 </div>
2268 <h4>Step 2: Layout document and regions without named flows</h4>
2270 <p>The used 'width' of RFCB-A, RFCB-B and RFCB-C are resolved as in the previous step. However, the
2271 'height' is resolved differently.</p>
2273 <p>Resolving the 'height' of rA <a href="http://www.w3.org/TR/CSS2/visudet.html#normal-block">requires a content measure</a>
2274 which is FH-A (the flow fragment height for RFCB-A).</p>
2276 <p>The 'height' of rB results from first computing its
2277 <a href="http://www.w3.org/TR/CSS2/visudet.html#block-root-margin">content measure</a> and then applying the
2278 <a href="http://www.w3.org/TR/CSS2/visudet.html#min-max-heights">rules for 'max-height'</a>. Here, the
2279 vertical content measure evaluates to FH-B. After applying the
2280 rules for 'max-height' and accounting for margins, padding and borders, the used 'height' of rB
2281 is resolved to LH-B (<code class="css">150px</code>).</a>.
2283 <p>The 'height' of rC's box results from
2284 <a href="http://www.w3.org/TR/CSS2/visudet.html#block-root-margin">calculating
2285 its content measure</a>: FH-C becomes rC's used 'height'.</a>
2287 <div class="figure">
2288 <img src="images/regions-visual-formatting-step-2.png" width="370px" alt="Step 2: Layout document and regions without named flows"/>
2289 <p class="caption">Step 2: Layout document and regions without <span>named flows</span></p>
2290 </div>
2292 <h4>Step 3: named flows layout</h4>
2294 <p>In this final step, the <code class="css">article</code> <span>named flow</span> is laid out in its
2295 <span>region chain</span>. The used 'width' for each of the RFCB is resolved as in step 1 above.</p>
2297 <p>The used 'height' for the RFCB is a result of laying out the as much of the content in the
2298 <span>region</span> without overflowing its content box and following the
2299 <a href="http://www.w3.org/TR/css3-break/">fragmentation rules</a>.</p>
2301 <p>Because the computed 'width' of the RFCB has not changed and the fragmentation rules applied are
2302 the same as in Phase 1, Step 2, the used 'height' for RFCB-A, RFCB-B and RFCB-C are
2303 LH-A, LH-B and LH-C, respectively.</p>
2305 <p>There may be situations where the used 'height' of RFCBs resolved in Step 3 are different from the
2306 <span>flow fragment height</span> computed in Step 1 Phase 2.</p>
2308 <div class="figure">
2309 <img src="images/regions-visual-formatting-step-3.png" width="370px" alt="Step 3: Final result after laying out named flows in regions"/>
2310 <p class="caption">Step 3: Final result after laying out named flows in regions</p>
2311 </div>
2314 <h2 id="relation-to-document-events">Relation to document events</h2>
2316 <p>The CSS regions module does not alter the normal processing of
2317 events in the document tree. In particular, if an event occurs on an
2318 element that is part of a <span>named flow</span>, the <a href=
2319 "http://www.w3.org/TR/dom/#events">event's
2320 bubble and capture phases</a> happen following the document tree order.</p>
2323 <h2 id="relation-to-other-specifications">Relation to other
2324 specifications</h2>
2326 <p>This specification is related to other specifications as described in
2327 the <a href='#references'>references</a> section. In addition, it is
2328 related to the following specifications:</p>
2330 <ol>
2331 <li>CSS Fragmentation Module Level 3 [[CSS3-BREAK]]. This module defines the
2332 rules for fragmenting content over multiple containers and applies to
2333 CSS regions in addition to applying to multi-column and paged media.</li>
2335 <li>CSS Pagination Templates Module Level 3 [[CSS3-PAGE-TEMPLATE]]. This module
2336 defines a syntax to define layout templates which can be used
2337 when paginating content. The page templates use regions.</li>
2339 <li>CSS Exclusions Module [[CSS3-EXCLUSIONS]]. This module defines a
2340 generic way to define arbitrarily shaped exclusions into which content
2341 can flow or around which content can flow. This can be seen as an
2342 extension to the way CSS floats provide rectangular areas into which
2343 content flows and around which content flows. In advanced layout
2344 designs, it is expected that the CSS Exclusions module will be commonly
2345 combined with the CSS regions module.</li>
2347 <li>CSS Line Grid Module [[CSS3-LINE-GRID]]. This module defines a
2348 concept of line grid to align the position of lines in different
2349 elements. The line grid functionality is related and needed for
2350 aligning content flowing in separate regions.</li>
2351 </ol>
2353 <h2 id="usecases">Use Cases</h2>
2355 <p>Use cases are described on <a href="http://wiki.csswg.org/spec/css3-regions/regions-use-cases">this
2356 page</a>.</p>
2358 <h2 id="conformance">Conformance</h2>
2360 <h2 id="changes">Changes</h2>
2362 <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>
2364 <ul>
2365 <li>Modified region styling examples to use element selector instead of of pseudo-code selectors (this had been omitted in the
2366 previous pass at removing pseudo-code from the examples).</li>
2367 <li>Removed divs with class set to "issue moved", "issue stale" and "issue resolved" since these divs where not displayed.
2368 <li>Minor updates to the alternate stylesheet.</li>
2369 <li>Removed "This section is normative" paragraphs since in CSS specifications, sections are normative unless
2370 otherwise specified.</li>
2371 <li>Removed "This section is informative" paragraphs since in CSS specifications notes are always informative.</li>
2372 <li>Reworded the text about flow-into: <ident> and removed obsolete text about the interaction with the
2373 'content' property.</li>
2374 <li>Removed "this section is non-normative" from the "Regions Concepts" section.</li>
2375 <li>In the section on region breaks, removed descriptions of break values normatively defined in external specifications.
2376 Removed the section about split boxes and replaced with paragraph referencing the page breaking behavior.
2377 Removed the discussion about how the 'overflow' property applies to content flown in regions from the
2378 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>
2379 <li>Clarified that @region style rules only apply to the 'portion' of an element that falls into
2380 the corresponding region and added an issue that the model for 'partial' styling needs to
2381 be defined. See <a href="http://lists.w3.org/Archives/Public/www-style/2011Dec/0480.html">mailing list feedback</a>.</li>
2382 <li>Clarified that the <code>NodeList</code> returned by <code>getRegionsByContentNode</code> is live.</li>
2383 <li>Added a name property to the <code>NamedFlow</code> interface. Added a <code>NamedFlowCollection</code>
2384 interface and added a <code>getNamedFlows</code> method on the <code>Document</code> interface, as
2385 per <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15828">Bug 15828</a>.</li>
2386 <li>Modified wording about containing block resolution for absolutely positioned elements in a
2387 named flow.</li>
2388 <li>Modified initial examples as per <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15131">Bug 15131</a></li>
2389 <li>Multiple editorial changes following
2390 <a href="http://lists.w3.org/Archives/Public/www-style/2012Feb/0001.html">mailing list review comments</a></li>
2391 <li>Fixed DOM references to now point to the DOM TR</li>
2392 <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>
2393 <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>
2394 <li>Renamed 'regionOverflow' to 'regionOverset' to avoid confusion between fitting a flow in
2395 regions and the concept of visual overflow that the word 'overflow' (and the property) carry.</li>
2396 <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>
2397 <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:
2398 <ul>
2399 <li>introduced a <code>Region</code> interface to replace the supplemental Element interface</li>
2400 <li>Added a 'flowFrom' attribute on the Region interface</li>
2401 <li>NamedFlow.getRegions() was added</li>
2402 <li>Renamed getContentNode to getContent and getRegionsByContentNode to getRegionsByContent as
2403 per <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15879">Isseu 15879</a></li>
2404 <li>NamedFlow now returns static lists (see <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16286">Issue 16286</a>)</li>
2406 </ul>
2407 </li>
2408 <li>Modified region layout event to be dispatched on <code>NamedFlow</code> instead of region
2409 as before. Was requested by <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15938">Issue 15938</a>
2410 and required in the general effort to have the DOM APIs work with non-element regions.</li>
2411 <li>Changed paragraph on pseudo-elements to disallow 'flow-into' on all pseudo-elements because
2412 moving a '::before' element (for a example) to a named flow does not seem useful and causes specification
2413 and implementation complexity.</li>
2414 <li>Added section about getClientRects(), getBoundingClientRect(), offsetWidth, offsetHeight, offsetTop and
2415 offsetLeft.</li>
2416 <li>Added 'Regions visual formatting details' section to better describe the model for
2417 resolving auto sizing on regions.</li>
2418 <li>Reworked the initial specification example.</li>
2419 <li>Changed break and region-overflow properties to apply to visual media instead of paged.</li>
2420 <li>Added opacity to region styling.</li>
2421 <li>Added possibility of ::before content contributing to overflow.</li>
2422 <li>Added CSSRegionStyleRule</li>
2423 </ul>
2426 <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>
2428 <ul>
2429 <li>Editorial changes (typos, rephrasings).</li>
2430 <li>Made 'content-order' a <integer> and not a <float> following a working group
2431 <a href="http://lists.w3.org/Archives/Public/www-style/2011Jun/0329.html">resolution</a></li>
2432 <li>Added Alex Mogilevsky as an editor</li>
2433 <li>Flow names became <ident> instead of <string> following a working group
2434 <a href="http://lists.w3.org/Archives/Public/www-style/2011Jun/0413.html">resolution</a></li>
2435 <li>Removed issue about possibly altering the DOM Events model for region events following
2436 a working group
2437 <a href="http://lists.w3.org/Archives/Public/www-style/2011Jun/0413.html">resolution</a></li>
2438 <li>Made the "relation to document events" section informative following a working group
2439 <a href="http://lists.w3.org/Archives/Public/www-style/2011Jun/0413.html">resolution</a></li>
2440 <li>Removed issue in section "The NamedFlow interface" following the working group's
2441 <a href="http://lists.w3.org/Archives/Public/www-style/2011Jun/0413.html">resolution</a> to
2442 have both NamedFlow and the Element interface extension</li>
2443 <li>Following a working group <a href="http://lists.w3.org/Archives/Public/www-style/2011Jun/0413.html">resolution</a>:
2444 <ul>
2445 <li>Turned the first issue in the "Extensions to the Element interface" into a note
2446 explaining that the NamedFlow interface can be used when regions are pseudo-elements.</li>
2447 <li>Added NamedFlowUpdate</li>
2448 </ul>
2449 </li>
2450 <li>Excluded 'none', 'inherit' and 'initial' from the possible identifier names on
2451 the flow property following <a href="http://lists.w3.org/Archives/Public/www-style/2011Jun/0583.html">discussion</a> on the mailing list.</li>
2452 <li>Simplified integration discussion on multi-column layout and just state that since
2453 column boxes are not addressable by selectors, they cannot be regions.</li>
2454 <li>Added specification of how the 'flow-into' property interacts with object, embed and iframe
2455 elements.</li>
2456 <li>Excluded 'default' from the possible identifier names on the flow property because it
2457 <a href="http://www.w3.org/TR/2006/WD-css3-values-20060919/#keywords">may get reserved</a>.</li>
2458 <li>Added to the definition of 'auto' on 'region-overflow' specifying that region breaks must
2459 be ignored.</li>
2460 <li>Renamed 'Document.flowWithName' to 'Document.getFlowByName' since it is not a property.</li>
2461 <li>Added a note that a 'NamedFlow' instance is live.</li>
2462 <li>Added an 'undefined' string value to the regionOverflow property on the Element interface
2463 extension.</li>
2464 <li>Renamed NamedFlowEvent to regionLayoutUpdate to avoid having 'Event' in the event name.</li>
2465 <li>Added description for special behavior of iframe/object/embed as
2466 flow source</li>
2467 <li>Removed issue on copying content to a named flow instead of moving elements to named
2468 flow following working group <a href="http://lists.w3.org/Archives/Public/www-style/2011Aug/0069.html">resolution</a>.</li>
2469 <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>
2470 <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>
2471 <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
2472 it should use <div> instead of grid-cell pseudo elements that were removed
2473 from the CSS Grid Layout specification.</li>
2474 <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>
2475 <li>Limited the applicability of 'content: flow-from()' to block container box and added
2476 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>
2477 <li>Removed issue about API to find which region displays an element in a named flow
2478 since <a href="http://www.w3.org/Style/CSS/Tracker/actions/350">ACTION-350</a> was
2479 created to add this API.</li>
2480 <li>In the 'flow' property description, removed the required wrapper anonymous
2481 block as agreed on <a href="http://lists.w3.org/Archives/Public/www-style/2011Aug/0161.html">mailing list discussion</a>.</li>
2482 <li>Reworded the paragraph on how regions create a new stacking context, as
2483 per the <a href="http://lists.w3.org/Archives/Public/www-style/2011Aug/0025.html">mailing list discussion</a>.</li>
2484 <li>Reworked the "CSS regions Model" section to now be "CSS regions Layout". Moved the
2485 definition of a region as the first sub-section.</li>
2486 <li>Removed the "Visual Formatting Model and Flows" section to match the new Regions Model
2487 (now CSS regions Layout) section.</li>
2488 <li>Moved the sections on allowed region breaks, forced region breaks and "best" regions
2489 breaks to follow the property definitions to follow the formatting of the paged
2490 media section in CSS 2.1.</li>
2491 <li>Added note about why regions create a new stacking context following the discussion
2492 on the <a href="http://lists.w3.org/Archives/Public/www-style/2011Jul/0158.html">mailing list</a>.</li>
2493 <li>Removed sentence about content:none making elements disconnected following the
2494 discussion on the <a href="http://lists.w3.org/Archives/Public/www-style/2011Jul/0158.html">mailing list</a>.</li>
2495 <li>Removed sentence about content:none making elements disconnected following the
2496 discussion on the <a href="http://lists.w3.org/Archives/Public/www-style/2011Jul/0158.html">mailing list</a>.</li>
2497 <li>Added the ::region-before and a ::region-after pseudo-elements.</li>
2498 <li>Added note of caution when using selectors and the 'flow-into' property following
2499 a <a href="http://lists.w3.org/Archives/Public/www-style/2011Jul/0191.html">mailing list discussion</a>.</li>
2500 <li>Removed sections about allowed, forced and best region breaks to align with the
2501 multi-column specification approach and until the group agrees on where and how the
2502 general issue of breaks (regions/pages/columns) should be addressed.</li>
2503 <li>Removed the section on Integration with other specifications since specifications that
2504 was superfluous especially since there is no specific integration with multi column,
2505 grid or template layout.</li>
2506 <li>Added a note that regions establish a new block formatting context.</li>
2507 <li>Renamed content-order to region-order.</li>
2508 <li>Added a note about overflowing content in regions (e.g., for content with borders).</li>
2509 <li>Added a note that a region cannot layout content it is part of (to avoid creating a
2510 circular dependency) in the flow-from description, specifying that if flow-from
2511 references the flow an element is part of, then the element does not format
2512 anything visually.</li>
2513 <li>Replaced 'content:flow-from(<ident>)' with 'flow-from: <ident>' following a
2514 <a href="http://krijnhoetmer.nl/irc-logs/css/20110824">working group resolution</a>.</li>
2515 <li>Added more specific wording about auto width and auto height, following
2516 <a href="http://www.w3.org/Style/CSS/Tracker/actions/351">ACTION 351</a>.</li>
2517 <li>Reworked section on region markers to now use '::before' and '::after' and explain
2518 how 'display:run-in' works with regions.</li>
2519 <li>Modified the @region style rule to remove the ::region-lines pseudo-selector.</li>
2520 <li>Removed the 'region-order' property following implementation feedback.</li>
2521 <li>Specified that region-overflow does not influence a region's size.</li>
2522 <li>Specified that the flow's writing mode is defined by the first region's writing mode
2523 following <a href="http://lists.w3.org/Archives/Public/www-style/2011Aug/0306.html">mailing list discussion</a>.</li>
2524 <li>Made iframe, object and embed support of flow-into optional following
2525 <a href="http://lists.w3.org/Archives/Public/www-style/2011Sep/0073.html">mailing list discussion</a>.</li>
2526 <li>Clarified that flow content following the last break in the last region is not rendered,
2527 following <a href="http://lists.w3.org/Archives/Public/www-style/2011Oct/0167.html">mailing list
2528 discussions.</a></li>
2529 <li>Modified the rule for computing the width and height of a region when they are set to auto,
2530 following <a href="http://lists.w3.org/Archives/Public/www-style/2011Oct/0216.html">a mailing list
2531 discussion.</a></li>
2532 <li>Added 'auto' to the list of invalid flow identifiers.</li>
2533 <li>Made 'none' the initial value for 'flow-into' and aligned with 'flow-from', as
2534 explained in this <a href="http://lists.w3.org/Archives/Public/www-style/2011Oct/0576.html">email</a>.
2535 Also allowed the 'inherit' value on 'flow-from' and 'flow-into' (same email).</li>
2536 <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>
2537 <li>Added additional DOM interface following <a href="http://www.w3.org/Style/CSS/Tracker/actions/350">Action 350</a>.</li>
2538 <li>Clarified that a region becomes a region only if its 'content' property computes to
2539 normal, following the resolution of <a href="http://wiki.csswg.org/spec/css3-regions#issue-22content-vs-flow-from-precedence">Issue 22</a>.</li>
2540 <li>Removed text about special iframe behavior as a result of
2541 <a href="http://www.w3.org/Style/CSS/Tracker/actions/376">ACTION 376</a>.</li>
2542 <li>Made the selectors explicit in the initial section code examples, following
2543 discussion in <a href="http://krijnhoetmer.nl/irc-logs/css/20111030">San Jose, October 2011</a> face to face meeting.</li>
2544 <li>Added section on use cases following <a href="http://www.w3.org/Style/CSS/Tracker/actions/377">ACTION-377</a>.</li>
2545 </ul>
2547 <h2 class="no-num" id="acknowledgments">Acknowledgments</h2>
2549 <p>The editors are grateful to the CSS working group for their feedback and help with
2550 the genesis of this specification.</p>
2552 <p>In addition, the editors would like to thank the following individuals for their contributions,
2553 either during the conception of CSS regions or during its development and specification review
2554 process:</p>
2555 <ul>
2556 <li>Rossen Atanassov</li>
2557 <li>Tab Atkins</li>
2558 <li>Andrei Bucur</li>
2559 <li>Alexandru Chiculita</li>
2560 <li>Phil Cupp</li>
2561 <li>Arron Eicholz</li>
2562 <li>John Jansen</li>
2563 <li>Daniel Glazman</li>
2564 <li>Arno Gourdol</li>
2565 <li>David Hyatt</li>
2566 <li>Brian Heuston</li>
2567 <li>Ian Hickson</li>
2568 <li>Jonathan Hoersch</li>
2569 <li>Michael Jolson</li>
2570 <li>Brad Kemper</li>
2571 <li>Håkon Wium Lie</li>
2572 <li>Markus Mielke</li>
2573 <li>Robert O'Callahan</li>
2574 <li>Edward O'Connor</li>
2575 <li>Mihnea Ovidenie</li>
2576 <li>Virgil Palanciuc</li>
2577 <li>Olga Popiv</li>
2578 <li>Christoph Päper</li>
2579 <li>Anton Prowse</li>
2580 <li>Peter Sorotokin</li>
2581 <li>Alan Stearns</li>
2582 <li>Christian Stockwell</li>
2583 <li>Eugene Veselov</li>
2584 <li>Boris Zbarsky</li>
2585 <li>Stephen Zilles</li>
2586 </ul>
2588 <h2 id="intro-example-code" class="no-num">Appendix A. Example Code for Introduction</h2>
2589 <p>The following is one possible way
2590 to code the example from
2591 the <a href="#introduction">introduction</a>.
2592 This code uses grid cells
2593 to define, size and position the region areas
2594 but table layout, absolute positioning,
2595 or any other CSS layout facility could be used.</p>
2597 <div class="example"><pre>
2598 <style>
2599 #grid {
2600 width: 80vw;
2601 height: 60vw;
2602 grid-template: "aaa.d"
2603 "....d"
2604 "bbb.d"
2605 "....d"
2606 "ccc.d";
2607 grid-rows: 52% 4% 20% 4% 20%;
2608 grid-columns: 30% 5% 30% 5% 30%;
2609 }
2610 #region1 { grid-cell: a; }
2611 #region2 { grid-cell: b; }
2612 #boxA { grid-cell: c; }
2613 #region3 { grid-cell: d; }
2615 #region4 {
2616 width: 80vw;
2617 }
2619 #region2 {
2620 column-count: 2;
2621 }
2623 <span class="highlight">/*
2624 * Creates the named flow
2625 */</span>
2626 article {
2627 <strong>flow-into: article_flow;</strong>
2628 }
2630 <span class="highlight">/*
2631 * Associate it with the intended CSS Regions.
2632 * This creates a region chain for the named flow.
2633 */</span>
2634 #region1, #region2, #region3, #region4 {
2635 <strong>flow-from: article_flow;</strong>
2636 }
2638 </style>
2640 <span class="highlight"><!--
2641 The following code element is the content to flow
2642 through the region chain.
2643 --></span>
2645 <article</em>>
2646 <h1>Introduction</h1>
2647 <p>This is an example ...</p>
2649 <h2>More Details</h2>
2650 <p>This illustrates ...</p>
2651 <p>Then, the example ...</p>
2652 <p>Finally, this ...</p>
2653 </article>
2655 <span class="highlight"><!--
2656 For this example, we layout the regions with a grid.
2657 Regions could be pseudo-elements and could be laid out
2658 with another layout module (e.g., flexible boxes)
2659 --></span>
2660 <div id="grid">
2661 <div id="region1"></div>
2662 <div id="region2"></div>
2663 <div id="boxA"></div>
2664 <div id="region3"></div>
2665 </div>
2666 <div id="region4"></div>
2667 </pre></div>
2671 <div class="note"><span class="note-prefix">Note </span>
2672 <p>
2673 Note that a multi-column element is used for #region2,
2674 which is a bit gratuitous here
2675 (because grid cells could be used).
2676 The reason to use a multi-column element
2677 is to illustrate that
2678 regions can be multi-column.</p>
2679 </div>
2682 <h2 class="no-num" id="references">References</h2>
2684 <div class="issue-marker" data-bug_id="16404" data-bug_status="ASSIGNED">
2685 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16404">Bug-16404</a>
2686 <div class="issue-details">
2687 <p class="short-desc">Fix specification dependencies</p>
2688 </div>
2689 </div>
2691 <h3 class="no-num" id="normative-references">Normative references</h3>
2692 <!--begin-normative--><!--end-normative-->
2694 <h3 class="no-num" id="other-references">Other references</h3>
2695 <!--begin-informative--><!--end-informative-->
2697 <h2 class="no-num" id="index">Index</h2><!--index-->
2699 <h2 class="no-num" id="property-index">Property index</h2>
2701 <!-- template markup for issues pulled from Bugzilla -->
2702 <script type="text/template" id="issue-template">
2703 <div class="issue-marker" style="display:none" data-bug_id="{{bug_id}}" data-bug_status="{{bug_status}}">
2704 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id={{bug_id}}">Bug-{{bug_id}}</a>
2705 <div class="issue-details">
2706 <p class="short-desc">{{short_desc}}</p>
2707 </div>
2708 </div>
2709 </script>
2711 <script type="text/javascript" src="../shared/scripts/BugzillaTrackerUtil.js"></script>
2712 <script type="text/javascript" src="../shared/scripts/BugzillaTracker.js"></script>
2713 <script type="text/javascript">
2714 checkSpecificationIssues('CSS', 'Regions');
2715 </script>
2718 <div id="issue-manager">
2719 <h2>Issue manager</h2>
2720 <form action="#">
2721 <label>
2722 <input type="radio" name="issue-filter" value="all" checked/>
2723 All issues
2724 </label>
2725 <label>
2726 <input type="radio" name="issue-filter" value="updated" />
2727 Updated issues
2728 </label>
2729 <label>
2730 <input type="radio" name="issue-filter" value="new" />
2731 New issues
2732 </label>
2733 </form>
2735 <!-- all the bugs are dumped the #issue-list after being retreived and matched to the ones in the page -->
2736 <div id="issue-list">
2738 </div>
2739 </div>
2741 </body>
2742 </html>
2743 <!-- Keep this comment at the end of the file
2744 Local variables:
2745 mode: sgml
2746 sgml-declaration:"~/SGML/HTML4.decl"
2747 sgml-default-doctype-name:"html"
2748 sgml-minimize-attributes:t
2749 sgml-nofill-elements:("pre" "style" "br")
2750 sgml-live-element-indicator:t
2751 sgml-omittag:nil
2752 sgml-shorttag:nil
2753 sgml-namecase-general:t
2754 sgml-general-insert-case:lower
2755 sgml-always-quote-attributes:t
2756 sgml-indent-step:nil
2757 sgml-indent-data:t
2758 sgml-parent-document:nil
2759 sgml-exposed-tags:nil
2760 sgml-local-catalogs:nil
2761 sgml-local-ecat-files:nil
2762 End:
2763 -->
