Skip to content

Commit ecd7d27

Browse files
tabatkinstabatkins
committed
Fill in constructors and such for most of the CSSTransformComponent subclasses, and reflect the new way of distinguishing 2d and 3d transforms.
1 parent ea1f13a commit ecd7d27

File tree

1 file changed

+207
-24
lines changed

1 file changed

+207
-24
lines changed

‎css-typed-om/Overview.bs

Lines changed: 207 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1079,11 +1079,10 @@ is a [=list=] of {{CSSTransformComponent}}s.
10791079
<xmp class=idl>
10801080
interface CSSTransformComponent {
10811081
readonly attribute DOMString cssText;
1082-
readonly attribute boolean is2D;
1082+
attribute boolean is2D;
10831083
};
10841084

1085-
[Constructor(CSSNumericValue x, CSSNumericValue y),
1086-
Constructor(CSSNumericValue x, CSSNumericValue y, CSSNumericValue z)]
1085+
[Constructor(CSSNumericValue x, CSSNumericValue y, optional CSSNumericValue z)]
10871086
interface CSSTranslation : CSSTransformComponent {
10881087
attribute CSSNumericValue x;
10891088
attribute CSSNumericValue y;
@@ -1099,8 +1098,7 @@ is a [=list=] of {{CSSTransformComponent}}s.
10991098
attribute CSSNumericValue angle;
11001099
};
11011100

1102-
[Constructor(double x, double y),
1103-
Constructor(double x, double y, double z)]
1101+
[Constructor(double x, double y, optional double z)]
11041102
interface CSSScale : CSSTransformComponent {
11051103
attribute double x;
11061104
attribute double y;
@@ -1126,23 +1124,192 @@ is a [=list=] of {{CSSTransformComponent}}s.
11261124

11271125
{{CSSTransformComponent}} objects have the following properties:
11281126

1129-
<div algorithm="CSSTransformComponent/is2D">
1130-
The <dfn attribute for=CSSTransformComponent>is2D</dfn> attribute is
1131-
true if the component represents a 2D transform function,
1132-
and false otherwise.
1127+
The transform function which the component represents
1128+
is stored in string form in the <dfn attribute for=CSSTransformComponent>cssText</dfn> attribute.
1129+
1130+
<div algorithm="CSSTransformComponent.numericValues">
1131+
Unless otherwise specified,
1132+
all {{CSSTransformComponent}} subclass attributes that have a {{CSSNumericValue}} or {{DOMMatrix}} type must,
1133+
on getting,
1134+
return a new {{CSSNumericValue}} or {{DOMMatrix}}
1135+
equivalent to the one stored in the corresponding internal slot.
1136+
1137+
Unless otherwise specified,
1138+
they must,
1139+
on setting,
1140+
store a new {{CSSNumericValue}} or {{DOMMatrix}}
1141+
equivalent to the value being set.
1142+
</div>
1143+
1144+
<div algorithm="CSSTransformComponent 3D stuff">
1145+
If a {{CSSTransformComponent}}’s {{CSSTransformComponent/is2D}} internal slot is `true`,
1146+
the attributes in the following list must,
1147+
on setting,
1148+
do nothing;
1149+
on getting,
1150+
they must return the value specified in the following list:
11331151

1134-
This is only true for:
1152+
: {{CSSTranslation/z|CSSTranslation.z}}
1153+
:: A new {{CSSUnitValue}} representing ''0px''.
11351154

1136-
* {{CSSTranslation}} objects if their {{CSSTranslation/z}} attribute is 0
1137-
* {{CSSRotation}} objects if their {{CSSRotation/x}} and {{CSSRotation/y}} attributes are 0
1138-
* {{CSSScale}} objects if their {{CSSScale/z}} attribute is 1
1139-
* {{CSSSkew}} objects at all times
1140-
* {{CSSPerspective}} objects never.
1141-
* {{CSSMatrixComponent}} objects if their {{CSSMatrixComponent/matrix}}’s [=DOMMatrixReadOnly/is2D=] flag is true.
1155+
: {{CSSRotation/x|CSSRotation.x}}
1156+
: {{CSSRotation/y|CSSRotation.y}}
1157+
:: The number `0`.
1158+
1159+
: {{CSSRotation/z|CSSRotation.z}}
1160+
:: The number `1`.
1161+
1162+
: {{CSSScale/z|CSSScale.z}}
1163+
:: The number `1`.
11421164
</div>
11431165

1144-
The transform function which the component represents
1145-
is stored in string form in the <dfn attribute for=CSSTransformComponent>cssText</dfn> attribute.
1166+
<details class=note>
1167+
<summary>{{CSSTransformComponent/is2D}} Design Considerations</summary>
1168+
1169+
For legacy reasons,
1170+
2D and 3D transforms are distinct,
1171+
even if they have identical effects;
1172+
a ''translateZ(0px)'' has observable effects on a page,
1173+
even tho it's defined to be an identity transform,
1174+
as the UA activates some 3D-based optimizations for the element.
1175+
1176+
There were several possible ways to reflect this--
1177+
nullable 3D-related attributes,
1178+
separate 2D and 3D interfaces,
1179+
etc--
1180+
but we chose the current design
1181+
(an author-flippable switch that dictates the behavior)
1182+
because it allows authors to,
1183+
in most circumstances,
1184+
operate on transforms without having to care whether they're 2D or 3D,
1185+
but also prevents "accidentally" flipping a 2D transform into becoming 3D.
1186+
</details>
1187+
1188+
<div algorithm="CSSTranslation()">
1189+
The <dfn constructor for=CSSTranslation>CSSTranslation(|x|, |y|, |z|)</dfn> constructor must,
1190+
when invoked,
1191+
perform the following steps:
1192+
1193+
1. If |x|, |y| don't match <<length-percentage>>,
1194+
or |z| (if passed) doesn't match <<length-percentage>>,
1195+
[=throw=] a {{TypeError}}.
1196+
1197+
2. Let |this| be a new {{CSSTranslation}} object,
1198+
with its internal {{CSSTranslation/x}} and {{CSSTranslation/y}} slots
1199+
set to new {{CSSNumericValue}} objects
1200+
equivalent to |x| and |y|.
1201+
1202+
3. If |z| was passed,
1203+
set |this|’s {{CSSTranslation/z}} internal slot
1204+
to a new {{CSSNumericValue}} object
1205+
equivalent to |z|,
1206+
and set |this|’s {{CSSTransformComponent/is2D}} internal slot
1207+
to `false`.
1208+
1209+
4. If |z| was not passed,
1210+
set |this|’s {{CSSTranslation/z}} internal slot
1211+
to a new {{CSSNumericValue}} object
1212+
representing ''0px'',
1213+
and set |this|’s {{CSSTransformComponent/is2D}} internal slot
1214+
to `true`.
1215+
1216+
5. Return |this|.
1217+
</div>
1218+
1219+
<div algorithm="CSSRotation(angle)">
1220+
The <dfn constructor for=CSSRotation>CSSRotation(|angle|)</dfn> constructor must,
1221+
when invoked,
1222+
perform the following steps:
1223+
1224+
1. If |angle| doesn't match <<angle>>,
1225+
[=throw=] a {{TypeError}}.
1226+
1227+
2. Return a new {{CSSRotation}}
1228+
with its {{CSSRotation/angle}} internal slot
1229+
set to a new {{CSSNumericValue}} equivalent to |angle|,
1230+
its {{CSSRotation/x}} and {{CSSRotation/y}} internal slots set to `0`,
1231+
its {{CSSRotation/z}} internal slot set to `1`,
1232+
and its {{CSSTransformComponent/is2D}} internal slot set to `true`.
1233+
</div>
1234+
1235+
<div algorithm="CSSRotation(x, y, z, angle)">
1236+
The <dfn constructor for=CSSRotation>CSSRotation(|x|, |y|, |z|, |angle|)</dfn> constructor must,
1237+
when invoked,
1238+
perform the following steps:
1239+
1240+
1. If |angle| doesn't match <<angle>>,
1241+
[=throw=] a {{TypeError}}.
1242+
1243+
2. Return a new {{CSSRotation}}
1244+
with its {{CSSRotation/angle}} internal slot
1245+
set to a new {{CSSNumericValue}} equivalent to |angle|,
1246+
its {{CSSRotation/x}}, {{CSSRotation/y}}, {{CSSRotation/z}} internal slots set to |x|, |y|, and |z|,
1247+
and its {{CSSTransformComponent/is2D}} internal slot set to `false`.
1248+
</div>
1249+
1250+
<div algorithm="CSSScale()">
1251+
The <dfn constructor for=CSSScale>CSSScale(|x|, |y|, |z|)</dfn> constructor must,
1252+
when invoked,
1253+
perform the following steps:
1254+
1255+
1. Let |this| be a new {{CSSScale}} object,
1256+
with its {{CSSScale/x}} and {{CSSScale/y}} internal slots
1257+
set to |x| and |y|.
1258+
1259+
2. If |z| was passed,
1260+
set |this|’s {{CSSScale/z}} internal slot to |z|,
1261+
and set |this|’s {{CSSTransformComponent/is2D}} internal slot to `false`.
1262+
1263+
3. If |z| was not passed,
1264+
set |this|’s {{CSSScale/z}} internal slot to `1`,
1265+
and set |this|’s {{CSSTransformComponent/is2D}} internal slot to `true`.
1266+
1267+
4. Return |this|.
1268+
</div>
1269+
1270+
<div algorithm="CSSSkew()">
1271+
The <dfn constructor for=CSSSkew>CSSSkew(|ax|, |ay|)</dfn> constructor must,
1272+
when invoked,
1273+
perform the following steps:
1274+
1275+
1. If |ax| or |ay| do not match <<angle>>,
1276+
[=throw=] a {{TypeError}}.
1277+
1278+
2. Return a new {{CSSSkew}} object
1279+
with its {{CSSSkew/ax}} and {{CSSSkew/ay}} internal slots
1280+
set to new {{CSSNumericValue}}s equivalent to |ax| and |ay|,
1281+
and its {{CSSTransformComponent/is2D}} internal slot set to `true`.
1282+
</div>
1283+
1284+
<div algorithm="CSSSkew.is2D">
1285+
The <dfn attribute for=CSSSkew>is2D</dfn> attribute of a {{CSSSkew}} object must,
1286+
on setting,
1287+
do nothing.
1288+
1289+
Note: ''skew()'' functions always represent 2D transforms.
1290+
</div>
1291+
1292+
<div algorithm="CSSPerspective()">
1293+
The <dfn constructor for=CSSPerspective>CSSPerspective(|length|)</dfn> constructor must,
1294+
when invoked,
1295+
perform the following steps:
1296+
1297+
1. If |length| does not match <<length>>,
1298+
[=throw=] a {{TypeError}}.
1299+
1300+
2. Return a new {{CSSPerspective}} object
1301+
with its {{CSSPerspective/length}} internal slot
1302+
set to a new {{CSSNumericValue}} equivalent to |length|,
1303+
and its {{CSSTransformComponent/is2D}} internal slot set to `false`.
1304+
</div>
1305+
1306+
<div algorithm="CSSPerspective.is2D">
1307+
The <dfn attribute for=CSSPerspective>is2D</dfn> attribute of a {{CSSPerspective}} object must,
1308+
on setting,
1309+
do nothing.
1310+
1311+
Note: ''perspective()'' functions always represent 3D transforms.
1312+
</div>
11461313

11471314
<div class=note>
11481315
Each {{CSSTransformComponent}} can correspond to one of a number of underlying
@@ -1563,7 +1730,10 @@ while CSS <<transform-function>> values become {{CSSTransformComponent}}s.
15631730
1. Return a new {{CSSMatrixComponent}} object,
15641731
whose {{CSSMatrixComponent/matrix}} internal slot
15651732
is set to a 4x4 matrix representing the same information
1566-
as |func|.
1733+
as |func|,
1734+
and whose {{CSSTransformComponent/is2D}} internal slot
1735+
is `true` if |func| is ''matrix()'',
1736+
and `false` otherwise.
15671737

15681738
: ''translate()''
15691739
: ''translateX()''
@@ -1574,7 +1744,10 @@ while CSS <<transform-function>> values become {{CSSTransformComponent}}s.
15741744
1. Return a new {{CSSTranslation}} object,
15751745
whose {{CSSTranslation/x}}, {{CSSTranslation/y}}, and {{CSSTranslation/z}} internal slots
15761746
are set to the [=normalize a numeric value|normalization=] of the specified x/y/z offsets,
1577-
or the [=normalize a numeric value|normalization=] of ''0px'' if not specified in |func|.
1747+
or the [=normalize a numeric value|normalization=] of ''0px'' if not specified in |func|,
1748+
and whose {{CSSTransformComponent/is2D}} internal slot
1749+
is `true` if |func| is ''translate()'', ''translateX()'', or ''translateY()'',
1750+
and `false` otherwise.
15781751

15791752
: ''scale()''
15801753
: ''scaleX()''
@@ -1585,7 +1758,10 @@ while CSS <<transform-function>> values become {{CSSTransformComponent}}s.
15851758
1. Return a new {{CSSScale}} object,
15861759
whose {{CSSScale/x}}, {{CSSScale/y}}, and {{CSSScale/z}} internal slots
15871760
are set to the specified x/y/z scales,
1588-
or to ''1'' if not specified in |func|.
1761+
or to ''1'' if not specified in |func|
1762+
and whose {{CSSTransformComponent/is2D}} internal slot
1763+
is `true` if |func| is ''scale()'', ''scaleX()'', or ''scaleY()'',
1764+
and `false` otherwise.
15891765

15901766
: ''rotate()''
15911767
: ''rotate3d()''
@@ -1598,7 +1774,10 @@ while CSS <<transform-function>> values become {{CSSTransformComponent}}s.
15981774
is set to the [=normalize a numeric value|normalization=] of the specified angle,
15991775
and whose {{CSSRotation/x}}, {{CSSRotation/y}}, and {{CSSRotation/z}} internal slots
16001776
are set to the specified rotation axis coordinates,
1601-
or the implicit axis coordinates if not specified in |func|.
1777+
or the implicit axis coordinates if not specified in |func|
1778+
and whose {{CSSTransformComponent/is2D}} internal slot
1779+
is `true` if |func| is ''rotate()'',
1780+
and `false` otherwise.
16021781

16031782
: ''skew()''
16041783
: ''skewX()''
@@ -1607,13 +1786,17 @@ while CSS <<transform-function>> values become {{CSSTransformComponent}}s.
16071786
1. Return a new {{CSSSkew}} object,
16081787
whose {{CSSSkew/ax}} and {{CSSSkew/ay}} internal slots
16091788
are set to the [=normalize a numeric value|normalization=] of the specified x and y angles,
1610-
or the [=normalize a numeric value|normalization=] of ''0deg'' if not specified in |func|.
1789+
or the [=normalize a numeric value|normalization=] of ''0deg'' if not specified in |func|,
1790+
and whose {{CSSTransformComponent/is2D}} internal slot
1791+
is `true`.
16111792

16121793
: ''perspective()''
16131794
::
16141795
1. Return a new {{CSSPerspective}} object,
16151796
whose {{CSSPerspective/length}} internal slot
1616-
is set to the [=normalize a numeric value|normalization=] of the specified length.
1797+
is set to the [=normalize a numeric value|normalization=] of the specified length
1798+
and whose {{CSSTransformComponent/is2D}} internal slot
1799+
is `false`.
16171800
</dl>
16181801
</div>
16191802

0 commit comments

Comments
 (0)