CSS Regions Module

Editor's Draft [DATE]

This version:: http://www.w3.org/csswg/css3-regions
Latest version:: http://www.w3.org/csswg/css3-regions
Previous version:: none
Editors:: Vincent Hardy, Adobe Systems, Inc., vhardy@adobe.com
Authors and Former Editors:: Stephen Zilles, Adobe Systems, Inc., szilles@adobe.com; Alexandru Chiculita, Adobe Systems, Inc., achicu@adobe.com; Andrei Bucur, Adobe Systems, Inc., abucur@adobe.com; Mihnea Ovidenie, Adobe Systems, Inc., mihnea@adobe.com; Peter Sorotokin, Adobe Systems, Inc., psorotok@adobe.com; Virgil Palanciuc, Adobe Systems, Inc., virgilp@adobe.com; Arno Gourdol, Adobe Systems, Inc., agourdol@adobe.com

Abstract

The CSS Regions module allows content to flow across multiple areas called regions. The regions do not necessarily follow the document order. The CSS Regions module provides an advanced content flow mechanism, which can be combined with positioning schemes as defined by other CSS modules such as the Multi-Column Module [[CSS3COL]] or the Grid Layout Module [[CSS3-GRID-LAYOUT]] to position the regions where content flows.

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This is a public copy of the editors' draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don't cite this document other than as work in progress.

The archived public mailing list www-style@w3.org is preferred for discussion of this specification. When sending e-mail, please put the text "css3-regions" in the subject, preferably like this: "[css3-regions] …summary of comment…"

Introduction

Capturing the complex layouts of a typical magazine, newspaper, or textbook requires capabilities beyond those possible with existing CSS modules. This is the purpose of the CSS Regions module.

The CSS Regions module can be seen as an extension of the concept of multi-column elements. With CSS Multi-column layout [[CSS3COL]], columns share the same dimensions and define column boxes organized in rows. Content flows from one column to the next.

The multi-column model is an example of flowing content from one area to another, where the areas are the multi-column element's column boxes and the flow is made of the multi-column element's children.

However, for more complex layouts, content needs to flow from one area of the page to the next without limitation of the areas sizes and positions. These arbitrary areas are the target of specific content flows. In this document these areas are called regions, and the content flows are called named flows. Regions are based on the rectangular geometry of the CSS box model. Elements in a named flow are taken out of the normal visual formatting and rendered in a chain of regions.

Named flows and regions

The designer's intent is to position an image in region 'A' and to flow an article's text from region '1', to region '2', '3' and '4'.

The following code snippet shows the content to flow between the regions 1, 2, 3 and 4.

CSS layout facilities can position and size regions as needed. However, there is no existing mechanism to associate the content with the regions so that content flows as intended. Figure 2 shows an example of the intended visual rendering of the content.

Since the CSS Regions module is independent of the layout of regions and the mechanism used to create them, the following assumes there is a CSS selector for the region and, for the purpose of the example, the selectors for regions 1, 2, 3 and 4 are showing as <region1_sel>, <region2_sel>, <region3_sel> and <region4_sel> respectively. Such a selector could be an id selector (e.g., "#region_1") or a grid cell selector (e.g., ""#myGrid::grid-cell([cell-name])") if using the CSS Grid Layout module, for example.

<style>

#article {
    flow: article_flow;
}

<region1_sel>, <region2_sel>, 
<region3_sel>, <region4_sel> {
    content: from(article_flow);
}
</style>

The above stylesheet directs the #article element to a named flow called 'article_flow' by setting the 'flow' property. Then, content is "poured" from that named flow into the desired regions by setting the regions' 'content' property to from(article_flow).

Regions Styling

Region styling allows content to be styled depending on the region it flows into. It is a form of context-based styling, similar to Media Queries [[MEDIAQ]] which enable or disable selectors depending on the rendering context. With region styling, additional selectors may match an element depending on the region into which it flows.

In our example, the designer wants to make text that falls into region 1 larger, bold and dark blue. In addition, <h1> headers should be run-ins and crimson.

<style>
/*
 * Default article styling.
 */
#article {
    color:#777;
    text-align: justify;
}

#article h1 {
    border-left: 1px solid #777;
    padding-left: 2ex;
}

/*
 * Additional styling to apply to content when it falls into 
 * region_1
 */
@region_style <region1_sel> {
    #article {
        font-weight: bold;
        color: #0C3D5F;
        font-size: larger;
    }

    #article h1 {
        color: crimson;
        display: run-in;
        border: none;
        padding: 0px;
    }
}
</style>

The '@region_style' rule for region 1 limits its selectors to elements that flow into region 1. The following figure shows how the rendering changes if we do not increase the font size nor make it bold for content falling into region 1. As more content can be fitted, more content is subject to the contextual selectors, resulting in more dark blue text into region 1.

CSS Regions Model

Named flows

In the CSS formatting model, elements can be in the normal flow or out of the (normal) flow. Boxes generated by elements in the normal flow are subject to their container box's normal layout scheme. Boxes generated by elements out of the normal flow are subject to a different layout scheme. For example, absolutely positioned elements are subject to absolute positioning into their containing block. This can be described by saying that the absolutely positioned elements are part of a special flow (called 'positioned flow') which is subject to a special layout by its container box (i.e., its container box positions it into the containing block's box).

In both cases, there is a notion of flow containing a sequence of elements and there is a notion of (block) container box into which the elements flow.

The CSS Regions module generalizes the concept of flow by adding the concept of a named flow. This module lets authors explicitly place elements into a named flow.

With this model, all elements are moved to a flow as part of the visual formatting. That flow may be the normal flow, a named flow or a positioned flow, for example. A flow gets formatted visually when associated with one or several elements' container box(es). When an flow is associated with container boxes, the boxes generated by the flow's elements are laid out according to the container box's layout scheme and the flow is subject to the 'flow breaking rules' described below.

A container's layout scheme is the strategy used by a container to position the boxes generated by its children and itself. Examples are the normal layout (block and inline formatting) ([[CSS21]]), table layout ([[CSS21]]), the multi-column layout ([[CSS3COL]]) or the grid layout ([[CSS3-GRID-LAYOUT]]).

Regions

A region is an element that generates a block container box and has an associated named flow (see the 'content' property).

Flow breaking rules

This section describes how container boxes consume content from a flow. The previous sections described how a flow may be referenced by one or more regions. The regions are the flow consumers and are ordered in a chain (see the 'content-order' property). The current flow consumer is initially the first one in the chain.

Positioning recursion -- while there are remaining boxes in the flow, the current flow consumer is allowed to take more boxes from the flow and position them. If the consumer is unable to position additional boxes without overflowing, then one of two things happen:

The above describes the simple case. It should explain how breaks influence this recursion.

Should the model provide a way to balance regions, as in the [[CSS3COL]] module?

Is there a way to allow regions to be generated when content that does not fit into the last region remains. This would be analogous to the way the additional columns are generated when a multi-column box overflows (see [[CSS3COL]]).

The Visual Formatting Model and Flows

This section describes the flows that elements formatted according to the CSS Visual Formatting Model and other layout modules (such as Multi-Column Layout [[CSS3COL]]) may belong to.

The following describes the 'generated flow' where generated content of pseudo-elements is placed and several 'auto flows' where children of content elements are automatically placed.

Normal flow

In the CSS formatting model, elements are by default placed in the normal flow of their container. Also, by default, a container element gets its content from its normal flow. This means that by default, a container element will visually format its children element and will be the only container associated with that flow.

Note that floats and relatively positioned elements, in this model, are part of the same flow of content and flow into the same container but are positioned in different ways.

Positioned flow

An absolutely positioned element is placed into the positioned flow of its container. The container positions this element into its containing block.

If a container has children in the normal flow and in the positioned flow, it applies different positioning schemes to each flows.

Column flow

Children of the multi-column element are placed in the element's column flow. The column boxes are then implicitly associated with the element's 'column flow'. In this model, multiple regions (column boxes) get their content from a single flow (the element's 'column flow', which is the content of the element).

Need to add a grid cell flow section.

Generated flow

In the CSS formatting model, when the ::before or ::after pseudo-elements have their content property set to one of <string>, <uri>, <counter>, attr(<identifier>), open-quote, close-quote, no-open-quote or no-close-quote, they create a generated flow which they format visually.

Relation to document events

The CSS Region module does not alter in any way the normal processing of events in the document tree. In particular, if an event occurs on an element that is part of a named flow, the event's bubble and capture phases happen following the document tree order.

Properties and Rules

The main CSS Regions module properties are the ‘flow’ and 'content' properties. The ‘flow’ property is used to place an element into a specific named flow or lets the automatic flow assignment take place. The ‘content’ property is bind regions with a flow. When multiple regions are bound to the same flow, the 'content-order' property determines the order in which content flows into the sequence of regions. This sequences of regions is called a chain of regions.

The way in which the content is broken into segments that fit in a region can be controlled by the “break” properties. Finally, styling that is unique to the region can be specified by ‘region-style’ rules.

The 'flow' property

The ‘flow’ property places an element into a named flow or automatically places it in the appropriate flow (see the Formatting Model Considerations section). Elements that belong to the same flow are laid out in the regions associated with that flow.

A named flow needs to be associated with one or more regions for its elements to be visually formatted. If no region is associated with a given named flow, the elements in the named flow are not rendered: they do not generate boxes and are not displayed.

The children of an element with a specified flow may themselves have a specified flow.

If an element has a the same specified flow value as one of its ancestors, it is moved out of its parent's normal flow and becomes a sibling of it's ancestor for the purpose of layout in the regions taking content from this flow.

The 'flow' property does not affect the CSS cascade and inheritance for the elements on which it is specified. The flow property affects the visual formatting of elements associated to a named flow and of regions getting their content from a named flow.

The containing block for absolutely positioned descendants of an element with a specified flow is the region into which the element is rendered.

All the elements participating inside a named flow are rendered as children of an anonymous block that spans across all the regions associated with the specified named flow. The elements flowed inside the same named flow are taken in document order.

The 'content' property

This specification extends the definition of the 'content' property and makes it applicable to all block elements and pseudo-elements.

Name:	flow
Value:	<name>
Initial:	auto
Applies to:	any element
Inherited:	no
Percentages:	N/A
Media:	visual
Computed value:	as specified

Name:	content
Value:	normal \| none \| from(<name>)\| [ <string> \| <uri> \| <counter> \| attr(<identifier>) \| open-quote \| close-quote \| no-open-quote \| no-close-quote ]+ \| inherit
Initial:	normal
Applies to:	any block element
Inherited:	no
Percentages:	N/A
Media:	visual
Computed value:	as specified

Should we consider adding the ability to do the following:

Support repeatable content. For example, have a repeatable heading at the start of each region where content flows.
Support flow breaking marks. It might be very useful to support a mark (such as ...) at the region breaking points to indicate that content has been broken out and is continuing on a different region.

Should the 'content' property be limited to block elements or should it be allowed on all elements?

The 'content-order' property

Defines the ordering of the chain of regions into which content flows. If region A and region B are in the same chain of regions and the ‘content-order’ of region A is lower than that of region B, then region A will precede region B in that chain: content will flow into region A before it flows into region B.

If two or more regions with the same 'from( <name>)' value for their 'content' property, they are first sorted according to their 'content-order' value. If multiple regions in have the same 'content-order' value, they are sorted according to the document order.

CSS Modules should define the document order for pseudo elements. For example, the [CSSGRID] specification should define the document order for the '::grid-cell' pseudo elements (e.g., row-major sorting or column major sorting of cells).

Region flow break properties: 'break-before', 'break-after', 'break-inside'

When content is laid out in multiple regions, the user agent must determine where content break occur. The problem of breaking content into segments fitting in regions is similar to breaking content into pages or columns.

Each break ends layout in the current region and causes remaining pieces of content from the named flow to be visually formatted in the following region, in the order defined by the 'content-order' computed values. Note that there is no region break in the last region associated to a named flow.

The following extends the 'break-before', 'break-after' and 'break-inside' properties from the [[!CSS3COL]] specification to account for regions. The additional values are described below.

These properties describe page, column and region break behavior before/after/inside the generated box. These values are normatively defined in [[!CSS3COL]]:

When a break splits a box, the box's margins, borders, and padding have no visual effect where the split occurs. However, the margin immediately after a forced page/column/region break will be preserved. A forced page/column/region break is a break that does not occur naturally.

Name:	content-order
Value:	<float>
Initial:	0
Applies to:	any block container
Inherited:	no
Percentages:	N/A
Media:	visual
Computed value:	as specified

Note: When the 'avoid' value is used, regions may overflow. In that case the 'overflow' property specified on the region element should be used to determine how to render the overflow.

There are elements, such as tables, where it is desirable to use break-inside to avoid so that the end user experience reading the page is not deteriorated. It such cases, it might be useful to provide some flexibility in the order in which content is pulled from the flow. For example, it might be good to allow a non breakable table to be moved to the next region where it fits and show more of the content that precedes that table in the flow in the previous region. This could be achieved with a

flow-priority:
        flexible

setting, for example.

The region-style rule

Authors define style declarations specific to a regions within an '@region-style' rule. An '@region-style' rule consists of the keyword '@region-style' followed by a selector and a declarations block. The '@region-style' rule and the selector constitute the region's 'flow segment' selector. The region's flow segment selector specifies which range in the flow is subject to the following declaration blocks: it applies to the range (see [[DOM-LEVEL-2-TRAVERSAL-RANGE]]) from the region's flow that flow in the selected region(s).

In the following example, the named flow 'article_flow' flows through 'region1' and 'region2'. If the flow contains an <h1> element that falls into any of these two regions, it will be displayed as a 'run-in'. Likewise, if a <p> element falls into any of these two regions, its 'color' will be 'cornflowerblue'. However, if an <h1> header falls into region1, its text will be transformed to uppercase, but not if it falls in region2.

<style>

<region1_sel>, <region2_sel> {
    content: from(article_flow);
}

@region_style <region1_sel>, <region2_sel> {
    p {
        color: cornflowerblue;
    }
    
    h1 {
        display: run-in;
    }
}

@region_style <region1_sel> {
    h1 {
         text-transform: uppercase;
    }
}
</style>

The properties allowed in '@region-style' declarations is limited to the same set as those available on the 'first-line' pseudo-element:

font properties
color properties
background properties
word-spacing
letter-spacing
text-decoration
vertical-align
text-transform
line-height
clear

The selectors for style declarations in a '@region-style' rule only match an element if the element flows into one of the regions in the rule selector.

The specificity of the selectors in a '@region-style' rule is calculated as defined in the CSS Selectors module (see [[SELECT]]). In other words, the '@region-style' rule adds an extra condition to the selector's matching, but does not change the selector's specificity. This is the same behavior as selectors appearing in '@media' rules declaration blocks (see [[MEDIAQ]]), where the rule does not influence the selectors' specificity.

Consequently, selectors that match a given element (as describe above), participate in the CSS Cascading order as defined in [[!CSS21]].

The above text defines that the @region-style <selector> matches a range in the flow because elements may be split across regions. For example, a paragraph element may start in region A and end in region B. Let's assume there are @region-style rules that apply to region A and region B content that would select the paragraph, for example to get red text in region A and blue text in region B. The intention is to have the red text styling applied to the range that flows into region A and the blue text styling applied to the range that flows into region B. This means that the selector really matches elements, so to speak.

CSSOM View and CSS Regions

Since content may flow into multiple regions, authors need a way to determine if there are enough regions to flow all the content in a named flow. This is especially important considering that the size of regions may change depending on the display context. For example, flowing the same content on a mobile phone with a small screen may require more regions than on a large desktop display. Another example where creating more regions might be needed is if the user may change the font size of text flowing through regions: it might be required to add new regions to accommodate for the additional space required to fit the larger text or reduce the number of regions for smaller text.

The CSS OM View ([[CSSOMVIEW]]) specification defines extensions to the Element interface that would let an author find out if the last region overflows its content boundaries (by comparing its 'scrollHeight' with its 'contentHeight'). However, this assumes the region is a document element, which may not always be the case. For example, as described in a later section, a grid cell (see [[CSSGRID]]) may be a region, but it is a pseudo-element, not an document element. Therefore, it is not possible to access its 'scrollHeight' or 'contentHeight'.

Since an element may be split into multiple regions, there should be a way to get the client rectangles for the region. Note that this issue exists for elements children of a multi-column container.

To address this need, this specification proposes to add a method to the Document interface to access an element's flow.

With the ContentFlow interface, authors can easily check if all content has been fitted into existing regions. If it has, the overflow property would be true.

Integration with other specifications

This specification does not specify how regions are created or laid out. This section illustrates how regions can be crated and laid out with other specifications. It first defines the requirements for integrating CSS Regions. Then it provides examples for different existing solutions.

Region requirements

For a container element (or pseudo-element) to become a region, it must be selectable with a CSS selector and accept the content property as defined in this specification.

Integration Examples

Authors can use different methods to layout regions in CSS. Some solutions can be expressed with CSS only and not require document changes, some solutions leverage the document tree. The following examples illustrate these different options.

CSS Grid Layout

The CSS Grid Layout specification (see [[CSS3-GRID-LAYOUT]]) defines a grid-cell pseudo-element selector for grid cells. Consequently, grid cells can be a region.

The following example shows how CSS Grid Layout could be use to create regions and position them to create the example given in the introduction.

To completely allow the use-case presented in the introduction, ::grid-cell pseudo elements should also allow box sizing properties which they do not at the moment.

<style>
body:before {
    display: grid;
    grid-template: "aae"
                   "bbe"
                   "cde";
}

body:before::grid-cell(a) {
    content: url('illustration.png');
}

body:before::grid-cell(b),
body:before::grid-cell(c),
body:before::grid-cell(d),
body:before::grid-cell(e) {
    content: from('article_flow');
}
</style>

CSS Multi-Column Layout

The CSS Multi-Column Layout (see [[CSSMULTICOL]]) does not specify a selector for column regions.

The CSS Multi-Column specification could offer a pseudo-element selector (e.g., called nth-column) for its column boxes. This would enable different content to flow through different columns. The following example illustrates how two different content flows could be threaded on alternate columns.

<style>
body:before {
    columns: 4;
}

body:before::nth-column(even) {
    content: from('article_1_flow');
}

body:before::nth-column(odd) {
    content: from('article_2_flow');
}
</style>

<body>
    <div id="article_1">...</div>
    <div id="article_2">...</div>
</body>

Note that if a column box becomes associated with a flow by its content property, it is no longer associated to the 'column flow', as discussed before. For example, if the second column in a multi column element was associated with the 'illustration' named flow, the regular 'column-flow' would thread through the first and third column while column two would flow content from the 'illustration' named flow.

CSS Flexible Box Layout Module

The CSS Flexible Box Layout Module (see [[CSS3FLEXBOX]]) aranges elements vertically or horizontally depending on various properties.

The following example shows how CSS Flexible Box Layout could be use to create regions and position them to create the example given in the introduction.

<style>
#article {
    flow: article_flow;
}

#region_1, #region_2, #region_3, #region_4 {
    content: from(article_flow);
}

#top_flex {
    display: flexbox;
    flex-direction: lr;
}

#left_col {
     display: flexbox;
     flex-direction: tb;
}

#bottom_row {
     display: flexbox;
     flex-direction: lr;
}
</style>
<html>
    <body>
        <div id="article">...</div>
        <div id="top_flex"> 
            <div id="left_col"> 
                <div id="region_A"></div> 
                <div id="region_1"></div>
                <div id="bottom-row">
                    <div id="region_2"></div>
                    <div id="region_3"></div>
                </div> 
            </div>
            <div id="region_4"></div>
        </div>
    </body>
</html>

CSS Visual Formatting

CSS (see [[CSS21]]) offers a way to visually format content with different layout schemes: inline and block formatting, float, absolute positioning, relative positioning or table layout.

Elements laid out using these schemes can be regions, as illustrated below, using absolutely positioned elements for simplicity.

<style>
#article {
    flow: article_flow;
}

#region_1, #region_2, #region_3, #region_4 {
    content: from(article_flow);
}

#region_1 {
    /* positioning properties */
}

/* ... positioning of other regions ... */

</style>
<html>
    <body>
        <div id="article">...</div>
        <div id="region_A"></div>
        <div id="region_1"></div>
        <div id="region_2"></div>
        <div id="region_3"></div>
        <div id="region_4"></div>
    </body>
</html>

Relation to other specifications

This specification is related to other specifications as described in the references section. In addition, it is related to the following specifications:

Name:	break-before
Value:	auto \| always \| avoid \| left \| right \| page \| column \| region \| avoid-page \| avoid-column \| avoid-region
Initial:	auto
Applies to:	block-level elements
Inherited:	no
Percentages:	N/A
Media:	paged
Computed value:	specified value

Name:	break-after
Value:	auto \| always \| avoid \| left \| right \| page \| column \| region \| avoid-page \| avoid-column \| avoid-region
Initial:	auto
Applies to:	block-level elements
Inherited:	no
Percentages:	N/A
Media:	paged
Computed value:	specified value

Name:	break-inside
Value:	auto \| avoid \| avoid-page \| avoid-column \| avoid-region
Initial:	auto
Applies to:	block-level elements
Inherited:	no
Percentages:	N/A
Media:	paged
Computed value:	specified value