csswg-drafts/css-logical-props/Overview.bs at ec69053bb5d6afca1f0b579310596173c392078a · w3c/csswg-drafts · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
<h1>CSS Logical Properties Level 1</h1>

<pre class='metadata'>
Shortname: css-logical-props
Level: 1
Status: ED
Work Status: Exploring
Group: csswg
ED: https://drafts.csswg.org/css-logical-props/
Editor: Rossen Atanassov, Microsoft, ratan@microsoft.com
Editor: Elika J. Etemad / fantasai, Invited Expert, http://fantasai.inkedblade.net/contact, w3cid 35400
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
Ignored Vars: *
Link Defaults: css21 (property) width/height/min-width/min-height/max-width/max-height
</pre>

<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.
  This mapping controls the interpretation of logical keywords and properties.

<h2 id="logical-controls">
Logical Directional Values: ''block-start'', ''block-end'', ''inline-start', ''inline-end''</h2>

  Properties that accept physical directional keyword values
  ('top', 'bottom', 'left', or 'right') are redefined
  to also accept the appropriate logical directional keywords.
  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 (unless otherwise specified in a future specification).

  Properties can be either 1-dimensional or 2-dimensional.
  When contextually constrained to one dimension,
  the logical keywords are shortened.

<h3 id="caption-side">
Logical Values for the 'caption-side' Property</h3>

  <pre class="propdef">
    Name: caption-side
    New values: block-start | block-end | inline-start | inline-end
  </pre>

  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.
  However, the ''inline-start'' and ''inline-end'' properties
  (which correspond to the behavior of the ''caption-side/left'' and ''caption-side/right'' values in CSS2.0)
  are only required to be supported by UAs that support ''caption-side/left'' and ''caption-side/right''.

<h3 id="float-clear">
Logical Values for the 'float' and 'clear' Properties</h3>

  <pre class="propdef">
    Name: float, clear
    New values: inline-start | inline-end
  </pre>

  Issue: Is this a 2-directional property? Should these just be ''start''/''end''?

<h3 id="text-align">
Logical Values for the 'text-align' Property</h3>

  <pre class="propdef">
    Name: text-align
    New values: start | end
  </pre>

  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>

  <pre class="propdef">
    Name: resize
    New values: block | inline
  </pre>

<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>

  These values are further defined in [[!CSS3-BREAK]].

  Logical page selectors are also 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="https://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.

<h2 id="logical-box-props">
Logical Box Model Properties
</h2>

  This specification introduces new CSS properties
  that are logical equivalents
  of physical box model properties.

  The specified values of these properties are separate from
  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'.
  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.
  Overriding is not determined by whether a declaration is logical or physical,
  but only by the rules of the CSS cascade [[!CSS3-CASCADE]].

  <p class="note">
    Note that this requires implementations to maintain
    relative order of declarations within a CSS declaration block,
    which was not previously required for CSS cascading.
  </p>

  <div class="example">
    For example, given the following rule:

    <pre class="lang-css">
p {
  margin-inline-start: 1px;
  margin-left: 2px;
  margin-inline-end: 3px;
}
    </pre>

    In a paragraph with computed 'writing-mode' being ''horizontal-tb''
    and computed 'direction' being ''ltr'',
    the computed value of 'margin-left' is ''2px'',
    since for that 'writing-mode' and 'direction',
    'margin-inline-start' and 'margin-left' share a computed value,
    and the declaration of 'margin-left'
    is after the declaration of 'margin-inline-start'.
    However, if the computed 'direction' were instead ''rtl'',
    the computed value of 'margin-left' is ''3px'',
    since 'margin-inline-end' and 'margin-left' share a computed value,
    and the declaration of 'margin-inline-end'
    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>

<h3 id="logical-dimension-properties">
Logical Height and Logical Width: the 'block-size' and 'inline-size' properties</h3>

  <pre class="propdef">
  Name: block-size, inline-size
  Value: <<'width'>>
  Initial: auto
  Applies to: same as 'width' and 'height'
  Inherited: no
  Percentages: block-size/inline-size, respectively, of containing block
  Media: visual
  Computed value: same as 'width' and 'height'
  </pre>

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

  <pre class="propdef">
  Name: min-block-size, min-inline-size
  Value: <<'min-width'>>
  Initial: 0
  Applies to: same as 'width' and 'height'
  Inherited: no
  Percentages: block-size/inline-size, respectively, of containing block
  Media: visual
  Computed value: same as 'min-width' and 'min-height'
  </pre>

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

  <pre class="propdef">
  Name: max-block-size, max-inline-size
  Value: <<'max-width'>>
  Initial: none
  Applies to: same as 'width' and 'height'
  Inherited: no
  Percentages: block-size/inline-size, respectively, of containing block
  Media: visual
  Computed value: same as 'max-width' and 'max-height'
  </pre>

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

<h3 id="logical-prop">
Logical Margins and Offsets:
the margin- and offset- 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
  Value: <<'margin-left'>>
  Initial: 0
  Applies to: same as 'margin'
  Inherited: no
  Percentages: depends on layout model
  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 element's 'writing-mode' and
  'direction'.

  <pre class="propdef">
  Name: offset-block-start, offset-block-end, offset-inline-start, offset-inline-end
  Value: <<'left'>>
  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' and 'direction'.

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

  <pre class="propdef">
  Name: padding-block-start, padding-block-end, padding-inline-start, padding-inline-end
  Value: <<'padding-left'>>
  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' and 'direction'.

  <pre class="propdef">
  Name: border-block-start-width, border-block-end-width, border-inline-start-width, border-inline-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' and 'direction'.

  <pre class="propdef">
  Name: border-block-start-style, border-block-end-style, border-inline-start-style, border-inline-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' and 'direction'.

  <pre class="propdef">
  Name: border-block-start-color, border-block-end-color, border-inline-start-color, border-inline-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' and 'direction'.

  <pre class="propdef">
  Name: border-block-start, border-block-end, border-inline-start, border-inline-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' and 'direction'.

<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>
  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:
  <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 class="prod">&lt;<var>value-type</var>&gt;{1,4}</pre>

  with
    <pre class="prod">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 block-start and block-end,
      the second is for inline-start and inline-end.</li>
    <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
      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 class="lang-css">
      blockquote {
        margin: logical 1em 2em 3em 4em;
      }
      blockquote {
        margin-block-start:  1em;
        margin-inline-end:   2em;
        margin-block-end:    3em;
        margin-inline-start: 4em;
      }
    </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 ''background-image-transform/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
  ''background-image-transform/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 ''border-image-transform/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>