Overview.bs

<h1>CSS Logical Properties Level 1</h1>

<pre class='metadata'>
Shortname: css-logical-props
Level: 1
Status: ED
Group: csswg
ED: http://dev.w3.org/csswg/css-logical-props/
Editor: Rossen Atanassov, Microsoft, ratan@microsoft.com
Editor: fantasai, Mozilla, http://fantasai.inkedblade.net/contact
Abstract: This module introduces logical properties and values that provide the author with the ability to control layout through logical, rather than physical, direction and dimension mappings. The module defines logical properties and values for the features defined in [CSS21]. These properties are writing-mode relative equivalents of their corresponding physical properties.
Ignored Terms: div, dl, dfn
</pre>

<h2 id="logical-controls">
Logical Directional Values: before, after, start, end</h2>

  Properties that accept physical directional keyword values ('top', 'bottom',
  'left', or 'right') are redefined to also accept the appropriate logical
  directional keywords (''before'', ''after'', ''start'', or ''end''). In such cases,
  the logical values can be used in place of the corresponding physical values.
  For properties that take multiple keywords, combinations of logical and
  physical values are not allowed.

  The following properties accept the ''start'' and ''end'' keywords where 'left'
  and 'right' are allowed:
  <ul>
    <li>'caption-side', if the 'left' and 'right' values are supported in
        horizontal writing modes (See the <a href="#caption-side">section on
        <code>caption-side</code></a>)
    <li>'clear'
    <li>'background-position'
    <li>'float'
    <li>'text-align'
  </ul>

	The following properties accept the ''before'' and ''after'' keywords where
  'top' and 'bottom' are allowed:
  <ul>
    <li>'caption-side'
  </ul>

  See the section on <a href="#abstract-layout">Abstract Layout</a>
  details on how to map between logical and physical terms. This mapping
  controls the interpretation of logical keywords.

	<p class="issue">
    float needs coordination with GCPM where it defines page floats

  <p class="issue">
    'resize' accepts ''horizontal'' and ''vertical'', and these terminologies
    should be physical. should we add 'resize-x and resize-y' as logical
    values?

<h2 id="logical-page">
Logical Page Classifications</h2>

  In CSS, all pages are classified by user agents as either left pages
  or right pages. [[!CSS21]] Which page is first in a spread, however,
  depends on whether the page progression is left-to-right or right-to-left.

  To allow control of page breaking to the page that is on the earlier
  or later side of a spread, rather than to the left or right side of a
  spread, this module introduces the following additional keywords for the
  'page-break-after' and 'page-break-before' properties [[!CSS21]]:
  <dl dfn-type="value" dfn-for="logical-page">
    <dt><dfn>recto</dfn>
      <dd>
        Equivalent to 'right' in left-to-right page progressions
        and 'left' in right-to-left page progressions.

    <dt><dfn>verso</dfn>
      <dd>
        Equivalent to 'left' in left-to-right page progressions
        and 'right' in right-to-left page progressions.
  </dl>

  <p class="issue">
    recto/verso or even/odd or even-page/odd-page? If using odd/even, could use
    "The page number used to determine whether a page is even or odd
    is the physical page count starting from 1, and is sometimes different from
    the page number printed on the page. In other words, if a page is on the
    same side as the first page, it is an odd page." But which side would we
    want if page-break-before changes the first page?

  Logical page selectors are added to support logical page selection.
  Authors typically place page numbers using physical placements,
  but the contents of headers often follows conventions depending
  on which page in the spread is earlier.

  Following <a href="http://www.w3.org/TR/CSS21/page.html#page-selectors">page
  selectors</a> are added to support this scenario:
  <dl dfn-type="value" dfn-for="logical-page-selector">
    <dt><dfn>:recto</dfn>
      <dd>
        Equivalent to ':right' in left-to-right page progressions
        and ':left' in right-to-left page progressions.

    <dt><dfn>:verso</dfn>
      <dd>
        Equivalent to ':left' in left-to-right page progressions
        and ':right' in right-to-left page progressions.
  </dl>

  The logical page selectors have specificity equal to the ':left'
  and ':right' page selectors.

<h3 id="logical-dimension-properties">
Logical Height and Logical Width: the 'length' and 'measure' properties</h3>

  <pre class="propdef">
  Name: measure, length
  Value: length | percentage | auto
  Initial: auto
  Applies to: same as 'width' and 'height'
  Inherited: no
  Percentages: 'measure', 'length' of containing block
  Media: visual
  Computed value: the percentage as specified or the absolute length or auto (see text)
  </pre>

  These properties correspond to the 'width' and 'height' properties. The
  mapping depends on the element's 'writing-mode'.

  <pre class="propdef">
  Name: min-measure, min-length
  Value: length | percentage
  Initial: 0
  Applies to: same as 'width' and 'height'
  Inherited: no
  Percentages: 'measure', 'length' of containing block
  Media: visual
  Computed value: the percentage as specified or the absolute length (see text)
  </pre>

  These properties correspond to the 'max-width' and 'max-height' properties.
  The mapping depends on the element's 'writing-mode'.

  <pre class="propdef">
  Name: max-measure, max-length
  Value: length | percentage | none
  Initial: none
  Applies to: same as 'width' and 'height'
  Inherited: no
  Percentages: 'measure', 'length' of containing block
  Media: visual
  Computed value: the percentage as specified or the absolute length or none (see text)
  </pre>

  These properties correspond to the 'min-width' and 'min-height' properties.
  The mapping depends on the element's 'writing-mode'.

<h3 id="logical-prop">
	Logical Margins and Offsets: : the margin- and offset- before/after/start/end
	properties</h3>

  <pre class="propdef">
  Name: margin-before, margin-after, margin-start, margin-end
  Value: length | percentage | auto
  Initial: 0
  Applies to: same as 'margin'
  Inherited: no
  Percentages: logical-width of containing block
  Media: visual
  Computed value: the percentage as specified or the absolute length or auto (see text)
  </pre>

  These properties correspond to the 'margin-top', 'margin-bottom',
  'margin-left', and 'margin-right' properties.
  The mapping depends on the <em>parent element's</em> 'writing-mode',
  'direction', and 'text-orientation'.

  <pre class="propdef">
  Name: offset-before, offset-after, offset-start, offset-end
  Value: length | percentage | auto
  Initial: auto
  Applies to: positioned elements
  Inherited: no
  Percentages: logical-width, resp. logical-height of containing block
  Media: visual
  Computed value: same as box offsets: 'top', 'right', 'bottom', 'left' properties except that directions are logical
  </pre>

  These properties correspond to the 'top', 'bottom', 'left', and 'right'
  properties. The mapping depends on the <em>parent element's</em>
  'writing-mode', 'direction', and 'text-orientation'.

<h3 id="border-padding">
	Logical Padding and Border: the padding- and border-<var>*</var>-
  before/after/start/end properties</h3>

  <pre class="propdef">
  Name: padding-before, padding-after, padding-start, padding-end
  Value: length | percentage
  Initial: 0
  Applies to: all elements
  Inherited: no
  Percentages: logical-width of containing block
  Media: visual
  Computed value: length (see text)
  </pre>

  These properties correspond to the 'padding-top', 'padding-bottom',
  'padding-left', and 'padding-right' properties. The mapping depends on the
  element's 'writing-mode', 'direction', and 'text-orientation'.

  <pre class="propdef">
  Name: border-before-width, border-after-width, border-start-width, border-end-width
  Value: border-width
  Initial: medium
  Applies to: all elements
  Inherited: no
  Percentages: logical-width of containing block
  Media: visual
  Computed value: absolute length; 0 if the border style is none or hidden (see text)
  </pre>

  These properties correspond to the 'border-top-width', 'border-bottom-width',
  'border-left-width', and 'border-right-width' properties. The mapping depends
  on the element's 'writing-mode', 'direction', and 'text-orientation'.

  <pre class="propdef">
  Name: border-before-style, border-after-style, border-start-style, border-end-style
  Value: border-style
  Initial: none
  Applies to: all elements
  Inherited: no
  Percentages: n/a
  Media: visual
  Computed value: specified value (see text)
  </pre>

  These properties correspond to the 'border-top-style', 'border-bottom-style',
  'border-left-style', and 'border-right-style' properties. The mapping depends
  on the element's 'writing-mode', 'direction', and 'text-orientation'.

  <pre class="propdef">
  Name: border-before-color, border-after-color, border-start-color, border-end-color
  Value: color
  Initial: currentcolor
  Applies to: all elements
  Inherited: no
  Percentages: n/a
  Media: visual
  Computed value: computed color (see text)
  </pre>

  These properties correspond to the 'border-top-color', 'border-bottom-color',
  'border-left-color', and 'border-right-color' properties. The mapping depends
  on the element's 'writing-mode', 'direction', and 'text-orientation'.

  <pre class="propdef">
  Name: border-before, border-after, border-start, border-end
  Value: border-width || border-style || color
  Initial: (see individual properties)
  Applies to: all elements
  Inherited: no
  Percentages: see individual properties
  Media: visual
  Computed value: see individual properties
  </pre>

  These properties correspond to the 'border-top', 'border-bottom',
  'border-left', and 'border-right' properties. The mapping depends on the
  element's 'writing-mode', 'direction', and 'text-orientation'.

<h3 id="logical-shorthand-keyword">
	Shorthand Properties with ''logical'' Keyword</h3>

  The shorthand properties for margin, padding, and border set values
  for physical properties by default. But authors can specify the ''logical''
  keyword at the beginning of the property value to indicate that the values
  map to the logical properties instead of the physical ones.

  <p class="issue">
    other candidates of the keyword are: ''relative'', ''script'',
    ''writing-mode'', ''beas'', or the value itself (e.g., ''vertical-lr-ltr'')

  The following [[!CSS21]] shorthand properties accept the ''logical'' keyword:
  <ul>
    <li>'margin'</li>
    <li>'padding'</li>
    <li>'border-color'</li>
    <li>'border-style'</li>
    <li>'border-width'</li>
  </ul>

  The syntax for these properties is effectively changed by replacing
    <pre>&lt;<var>value-type</var>&gt;{1,4}</pre>

  with
    <pre>logical? &lt;<var>value-type</var>&gt;{1,4}</pre>

  When the logical keyword is present in the value, the values that follow are
  assigned to the logical properties as follows:
  <ul>
    <li>If only one value is set, the value applies to all four logical sides.</li>
    <li>If two values are set, the first is for before and after,
      the second is for start and end.</li>
    <li>If three values are set, the first is for before,
      the second is for start and end,
      and the third is for after.</li>
    <li>If four values are set, they apply to the before, end, after, and start
      sides in that order.</li>
  </ul>

  <p class="issue">
    Should the shorthand also reset the physical properties to their initial
    values?

  <div class="example">
    In the following example, the two rules are equivalent:
    <pre><code class="css">
<!-- -->blockquote {
<!-- -->  margin: logical 1em 2em 3em 4em;
<!-- -->}
<!-- -->blockquote {
<!-- -->  margin-before: 1em;
<!-- -->  margin-end:    2em;
<!-- -->  margin-after:  3em;
<!-- -->  margin-start:  4em;
<!-- -->}
<!----></code></pre>
  </div>

<h2 id="background-and-borders">
	Logical Background and Border Images</h2>

  [[!CSS3BG]] is handled separately because it can fill an area with specified
  images, and the area to fill can be rotated or flipped depending on the text
  flow.

<h3 id="background-image-transform-prop">
	Background Image Transform: The ''background-image-transform'' property</h3>

  <pre class="propdef">
  Name: background-image-transform
  Value: logical | physical | rotate
  Initial: physical
  Applies to: all elements
  Inherited: yes
  Percentages: n/a
  Media: visual
  Computed value: as specified
  </pre>

  <p class="issue">
    is this the right default? we need to investigate which is more common

  This property defines whether background images are transformed to match to
  the value of 'writing-mode' property, and whether 'background-size' widths and
  heights are logical or physical. Values have the following meanings:
  <dl dfn-type="value" dfn-for="background-image-transform">
    <dt><dfn>logical</dfn></dt>
    <dd>
      The values for the 'background-size' property are logical.
      The background images are transformed to match to the logical axis.

    <dt><dfn>physical</dfn></dt>
    <dd>
      The values for the 'background-size' property are physical.
      The background images remain unchanged.

    <dt><dfn>rotate</dfn></dt>
    <dd>
      Similar to ''logical'', except that the inline direction is ignored.
      The result is affected only by the block flow direction.
  </dl>

<h3 id="background-repeat-prop">
	The 'background-repeat' property</h3>

  The ''repeat-x'' and ''repeat-y'' values are logical, but in CSS3 this
  property can also accept double values to specify horizontal and vertical
  behaviors separately. The double values are considered logical if the
  ''logical'' keyword is specified, otherwise physical.

  <p class="issue">
    should also add repeat-horizontal and repeat-vertical for the physical value?

<h3 id="border-image-transform-prop">
	Border Image Transform: The 'border-image-transform' property</h3>

  <pre class="propdef">
  Name: border-image-transform
  Value: logical | physical | rotate
  Initial: rotate
  Applies to: All elements, except internal table elements when 'border-collapse' is ''collapse''
  Inherited: yes
  Percentages: n/a
  Media: visual
  Computed value: as specified
  </pre>

  <p class="issue">
    is this the right initial default?

  This property defines whether border images are transformed to match to the
  value of 'writing-mode' property, with the reference writing mode being
  ''writing-mode: horizontal-tb; direction: ltr''. Values have the following
  meanings:
  <dl dfn-type="value" dfn-for="border-image-transform">
    <dt><dfn>logical</dfn></dt>
    <dd>
      The values for the border-image-* properties are logical.
      The border images are transformed to match to the logical axis.

    <dt><dfn>physical</dfn></dt>
    <dd>
      The values for the border-image-* properties are physical.
      The border images remain unchanged.

    <dt><dfn>rotate</dfn></dt>
    <dd>
      Similar to ''logical'', except that the inline direction is ignored.
      The result is affected only by the block flow direction.
  </dl>

  The following properties use the value of this property to determine how
  directional mappings are done:
  <ul>
    <li>'border-image-slice'</li>
    <li>'border-image-width'</li>
    <li>'border-image-outset'</li>
    <li>'border-image-repeat'</li>
    <li>'border-image'</li>
  </ul>