[css-logical-props] Catch-up Commit

* Add issue explaining status
* Remove some issues
* Indicate float/clear uses inline-* prefixes per Tokyo F2F resolution.
* Rename offset-* to inset-* (and define shorthand) to avoid conflict with motion module per astearns' suggestion.
* Add an introduction and clean up a bit some prose
* Add text-orientation to the list of dependencies
* Spec mapping for CSSOM APIs per WG resolution (more details in CSSOM)
* Change 4-value mapping to put inline-start before inline-end per WG resolution & Grid Layout

Author: fantasai

css-logical-props/Overview.bs

@@ -18,10 +18,75 @@ Link Defaults: css21 (property) width/height/min-width/min-height/max-width/max-
 <h1 id="intro">
 Introduction</h1>
 
-  See [[!CSS3-WRITING-MODES]] <a href="https://www.w3.org/TR/css-writing-modes-3/#abstract-layout">Abstract Layout</a>
-  for details on how to map between logical and physical terms.
+  Note: See [[!CSS3-WRITING-MODES]] for a proper introduction to writing modes;
+  this module assumes familiarity with its terminology.
+
+  Because different writing systems are written in different directions,
+  a variety of <a>writing modes</a> exist:
+  left to right, top to bottom;
+  right to left, top to bottom;
+  bottom to top, right to left;
+  etc.
+  logical concepts like the “start” of a page or line
+  map differently to physical concepts like the “top” of a line or “left edge” of a paragraph.
+  Some aspects of a layout are actually relative to the writing directions,
+  and thus will vary when the page is translated to a different system;
+  others are inherently relative to the page's physical orientation.
+
+  <div class="example">
+    For example,
+    lists, headings, and paragraphs are typically left-aligned in English;
+    but actually they are start-aligned, because in Arabic the same constructs are right-aligned,
+    and a multilingual document will need to accommodate both writing systems accordingly.
+    However the drop shadows on buttons on a page must remain consistent throughout,
+    so their offset will be chosen based on visual considerations and physical directions,
+    and not vary by writing system.
+  </div>
+
+  Since CSS was originally designed with only physical coordinates in its controls,
+  this module introduces logical equivalents
+  so that declarations in a CSS style sheet can be expressed
+  in <a>flow-relative</a> terms.
+  It defines the mapping and cascading of equivalent properties,
+  some new properties and values equivalent to those in CSS2.1,
+  and the principles used to derive their syntaxes.
+  Future CSS specifications are expected to incorporate both sets of coordinates
+  in their property and value definitions,
+  so this module will not track the introduction of <a>flow-relative</a> variants
+  of newer CSS features.
+
+  <a href="http://www.w3.org/TR/css-writing-modes/">CSS Writing Modes</a>’ <a href="https://www.w3.org/TR/css-writing-modes-3/#abstract-layout">Abstract Layout</a> section
+  defines how to map between logical and physical terms.
   This mapping controls the interpretation of logical keywords and properties.
 
+<div class="issue">
+  <strong>Things That Are Unstable</strong>
+  Since implementation of parts of this module is effectively required for shipping an implementation of CSS Writing Modes on the Web
+  (in order to correctly implement the default HTML styles),
+  The CSSWG resolved that although the draft is not very stable overall,
+  the requisite features in
+  <a href="#logical-controls"></a> and <a href="#logical-box-props"></a>
+  are approved for shipping.
+  However, there are a number of unstable features in this draft
+  (which are not required for implementing the HTML default style sheet, incidentally),
+  and these are:
+  <ul>
+    <li><del>The 'float' and 'clear' keywords,
+        because it is not yet clear what the upcoming 2-dimensional syntax of 'float' will be.</del>
+        (This has been resolved as of April 2017.)
+    <li>The 'inset-*' properties,
+        because the name of the prefix is undecided.
+        (It used to be 'offset-*', but ended up conflicting with another CSS feature.)
+    <li>The ''logical'' keyword on shorthands,
+        because the name of the keyword may change or it may be replaced by some other syntactic marker.
+    <li>The 'background-image-transform' and 'border-image-transform' properties,
+        because they have, as far as the editor is aware,
+        received no review from anyone and may or may not be well-designed.
+  </ul>
+  Comments and suggestions are welcome on these issues.
+  Please file them in GitHub, tweet them to @csswg, or send them to www-style@w3.org.
+</div>
+
 <h2 id="logical-controls">
 Logical Directional Values: ''block-start'', ''block-end'', ''inline-start', ''inline-end''</h2>
 
@@ -45,7 +110,7 @@ Logical Values for the 'caption-side' Property</h3>
     New values: block-start | block-end | inline-start | inline-end
   </pre>
 
-  The 'caption-side' property is 1-dimensional in CSS2.1,
+  Note: The 'caption-side' property is 1-dimensional in CSS2.1,
   but was 2-dimensional in CSS2.0,
   (and presumably will be 2-dimensional again in the next update to CSS tables).
   It therefore accepts the full set of logical directions.
@@ -61,7 +126,9 @@ Logical Values for the 'float' and 'clear' Properties</h3>
     New values: inline-start | inline-end
   </pre>
 
-  Issue: Is this a 2-directional property? Should these just be ''start''/''end''?
+  Note: These properties are 1-dimensional in CSS2,
+  but are planned to be expanded to two dimensions,
+  and therefore are given unabbreviated <a>flow-relative</a> keywords.
 
 <h3 id="text-align">
 Logical Values for the 'text-align' Property</h3>
@@ -73,9 +140,6 @@ Logical Values for the 'text-align' Property</h3>
 
   These values are normatively defined in [[!CSS3TEXT]].
 
-  <p class="issue">
-    float needs coordination with GCPM where it defines page floats
-
 <h3 id="resize">
 Logical Values for the 'resize' Property</h3>
 
@@ -144,14 +208,14 @@ Logical Box Model Properties
   the specified values of the parallel physical properties,
   but the logical and physical properties share computed values.
   Which pairs of properties share computed values
-  depends on the computed values of
-  'writing-mode' and 'direction'.
+  depends on the element’s computed values of
+  'writing-mode', 'direction', and 'text-orientation'.
   For a summary of these dependencies, see
   <a href="https://drafts.csswg.org/css-writing-modes/#logical-to-physical">Abstract-to-Physical Mappings</a>
   in [[!CSS3-WRITING-MODES]].
 
-  A computed value that has logical and physical properties
-  is determined by applying the CSS cascade to declarations of both.
+  A computed value that has logical and physical properties as input
+  is determined by applying the CSS cascade to declarations of both.t
   Overriding is not determined by whether a declaration is logical or physical,
   but only by the rules of the CSS cascade [[!CSS3-CASCADE]].
 
@@ -186,11 +250,9 @@ p {
     is after the declaration of 'margin-left'.
   </div>
 
-  <p class="issue">
-    How do computed value APIs, e.g., getComputedStyle() work?
-    Can they be used with either logical or physical properties,
-    or only with the physical ones?
-  </p>
+  [[CSSOM!]] APIs that return computed values
+  (such as <code>getComputedStyle()</code>)
+  must return the same value for equivalent pairs of such properties.
 
 <h3 id="logical-dimension-properties">
 Logical Height and Logical Width: the 'block-size' and 'inline-size' properties</h3>
@@ -239,7 +301,7 @@ Logical Height and Logical Width: the 'block-size' and 'inline-size' properties<
 
 <h3 id="logical-prop">
 Logical Margins and Offsets:
-the margin- and offset- block-start/block-end/inline-start/inline-end properties</h3>
+the margin- and inset- block-start/block-end/inline-start/inline-end properties</h3>
 
   <pre class="propdef">
   Name: margin-block-start, margin-block-end, margin-inline-start, margin-inline-end
@@ -252,14 +314,12 @@ the margin- and offset- block-start/block-end/inline-start/inline-end properties
   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 element's 'writing-mode' and
-  'direction'.
+  These properties correspond to the 'margin-top', 'margin-bottom', 'margin-left', and 'margin-right' properties.
+  The mapping depends on the element's 'writing-mode', 'direction', and 'text-orientation'.
 
   <pre class="propdef">
-  Name: offset-block-start, offset-block-end, offset-inline-start, offset-inline-end
-  Value: <<'left'>>
+  Name: inset-block-start, inset-block-end, inset-inline-start, inset-inline-end
+  Value: <<'top'>>
   Initial: auto
   Applies to: positioned elements
   Inherited: no
@@ -268,9 +328,16 @@ the margin- and offset- block-start/block-end/inline-start/inline-end properties
   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' and 'direction'.
+  These properties correspond to the 'top', 'bottom', 'left', and 'right' properties.
+  The mapping depends on the element's 'writing-mode', 'direction', and 'text-orientation'.
+
+  <pre class="propdef shorthand">
+  Name: inset
+  Value: <<'top'>>{1,4}
+  </pre>
+
+  This <a>shorthand property</a> sets the 'top', 'right', 'bottom', and 'left' properties.
+  Values are assigned to its <a>sub-properties</a> as for 'margin'.
 
 <h3 id="border-padding">
   Logical Padding and Border: the padding- and border-<var>*</var>-
@@ -288,8 +355,8 @@ the margin- and offset- block-start/block-end/inline-start/inline-end properties
   </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' and 'direction'.
+  'padding-left', and 'padding-right' properties.
+  The mapping depends on the element's 'writing-mode', 'direction', and 'text-orientation'.
 
   <pre class="propdef">
   Name: border-block-start-width, border-block-end-width, border-inline-start-width, border-inline-end-width
@@ -303,8 +370,8 @@ the margin- and offset- block-start/block-end/inline-start/inline-end properties
   </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' and 'direction'.
+  '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-block-start-style, border-block-end-style, border-inline-start-style, border-inline-end-style
@@ -318,8 +385,8 @@ the margin- and offset- block-start/block-end/inline-start/inline-end properties
   </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' and 'direction'.
+  '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-block-start-color, border-block-end-color, border-inline-start-color, border-inline-end-color
@@ -333,8 +400,9 @@ the margin- and offset- block-start/block-end/inline-start/inline-end properties
   </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' and 'direction'.
+  '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-block-start, border-block-end, border-inline-start, border-inline-end
@@ -348,22 +416,25 @@ the margin- and offset- block-start/block-end/inline-start/inline-end 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' and 'direction'.
+  '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 <css>logical</css> Keyword</h3>
 
   The shorthand properties for margin, padding, and border set values
-  for physical properties by default. But authors can specify the <dfn value for="margin, padding, border-color, border-style, border-width">logical</dfn>
+  for physical properties by default.
+  But authors can specify the <dfn value for="margin, padding, border-color, border-style, border-width">logical</dfn>
   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 ''margin/logical'' keyword:
+  The following [[!CSS21]] shorthand properties
+  (and additionally the new 'inset' shorthand defined above)
+  accept the ''margin/logical'' keyword:
   <ul>
     <li>'margin'</li>
     <li>'padding'</li>
@@ -388,14 +459,10 @@ Shorthand Properties with <css>logical</css> Keyword</h3>
     <li>If three values are set, the first is for block-start,
       the second is for inline-start and inline-end,
       and the third is for block-end.</li>
-    <li>If four values are set, they apply to the block-start, inline-end, block-end, and inline-start
+    <li>If four values are set, they apply to the block-start, inline-start, block-end, and inline-end
       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:
 
@@ -405,9 +472,9 @@ Shorthand Properties with <css>logical</css> Keyword</h3>
       }
       blockquote {
         margin-block-start:  1em;
-        margin-inline-end:   2em;
+        margin-inline-start: 2em;
         margin-block-end:    3em;
-        margin-inline-start: 4em;
+        margin-inline-end:   4em;
       }
     </pre>
   </div>