Skip to content

Commit 4c5fb12

Browse files
andruudtabatkins
andruud
and
tabatkins
authored
[css-mixins-1] Flesh out CSSOM for mixins (w3c#13027)
This commit adds interfaces to represent @mixin, @apply, and @contents. Following the precedent of @layer, rules that can appear either as statement rules or block rules get different representations in the OM, e.g. CSSApplyBlockRule and CSSApplyStatementRule. Co-authored-by: Tab Atkins Jr. <jackalmage@gmail.com>
1 parent 41a3cb5 commit 4c5fb12

2 files changed

Lines changed: 257 additions & 5 deletions

File tree

‎css-mixins-1/Overview.bs‎

Lines changed: 256 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1286,15 +1286,15 @@ The syntax of a ''@contents'' at-rule is:
12861286
</wpt>
12871287

12881288
That is, it is either an <em>empty</em> statement ended immediately by a semicolon,
1289-
or a block treated as a [=nested declarations rule=].
1289+
or a <dfn>fallback block</dfn> treated as a [=nested declarations rule=].
12901290
The empty statement form behaves identically to passing an empty block.
12911291

12921292
* If the ''@apply'' rule invoking the [=mixin=] passed a [=contents block=],
12931293
the ''@contents'' is replaced with the [=contents block=],
12941294
treating it as a [=nested declarations rule=].
12951295
* Otherwise (if the ''@apply'' rule did not pass a [=contents block=]),
1296-
the ''@contents'' rule is replaced with its own <<declaration-list>>,
1297-
treated as a [=nested declarations rule=].
1296+
the ''@contents'' rule is replaced with its [=fallback block=],
1297+
treating it as a [=nested declarations rule=].
12981298

12991299
Outside of an ''@result'' rule,
13001300
the ''@contents'' rule is invalid and ignored.
@@ -1601,7 +1601,7 @@ appear as if wrapped in {{CSSFunctionDeclarations}} rules.
16011601
Note: This also applies to the "leading" declarations in the ''@function'' rule,
16021602
i.e those that do not follow another nested rule.
16031603

1604-
<div class='example'>
1604+
<div class='example' id=function-declarations-example>
16051605
<pre class='lang-css'>
16061606
@function --bar() {
16071607
--x: 42;
@@ -1743,6 +1743,258 @@ The {{CSSFunctionDeclarations}} rule, like {{CSSNestedDeclarations}},
17431743
[=serialize a CSS rule|serializes=] as if its [=CSS declaration block|declaration block=]
17441744
had been [=serialize a CSS declaration block|serialized=] directly.
17451745

1746+
The {{CSSMixinRule}} Interface {#the-mixin-interface}
1747+
-----------------------------------------------------
1748+
1749+
The {{CSSMixinRule}} interface represents a ''@mixin'' rule.
1750+
1751+
<pre class='idl' export>
1752+
[Exposed=Window]
1753+
interface CSSMixinRule : CSSGroupingRule {
1754+
readonly attribute CSSOMString name;
1755+
sequence&lt;FunctionParameter&gt; getParameters();
1756+
readonly attribute boolean contents;
1757+
};
1758+
</pre>
1759+
1760+
<dl dfn-for=CSSMixinRule>
1761+
<dt><dfn dfn-type=attribute>name</dfn>
1762+
<dd>
1763+
The result of [=serialize an identifier=]
1764+
on the [=mixin=]'s name.
1765+
<dt><dfn dfn-type=method>getParameters()</dfn>
1766+
<dd>
1767+
Returns [=function parameters=] associated with the [=mixin=],
1768+
excluding any '@contents' parameter.
1769+
</dd>
1770+
<dt><dfn dfn-type=attribute>contents</dfn>
1771+
<dd>
1772+
True if the [=mixin=] accepts a [=contents block=],
1773+
and false otherwise.
1774+
</dl>
1775+
1776+
While declarations may be specified directly within a ''@mixin'' rule,
1777+
they are not represented as such in the CSSOM.
1778+
Instead, consecutive segments of declarations
1779+
appear as if wrapped in {{CSSNestedDeclarations}} rules.
1780+
<div class=note>
1781+
This is similar to
1782+
<a href="#function-declarations-example">how segments of bare declarations
1783+
within '@function' are wrapped</a>,
1784+
except with {{CSSNestedDeclarations}} as the wrapper
1785+
rather than {{CSSFunctionDeclarations}}.
1786+
</div>
1787+
1788+
<div algorithm>
1789+
To <dfn export>serialize a CSSMixinRule</dfn>,
1790+
return the concatenation of the following:
1791+
1792+
1. The string <code>"@mixin"</code> followed by a single SPACE (U+0020).
1793+
2. The result of performing <a>serialize an identifier</a>
1794+
on the name of the [=mixin=],
1795+
followed by a single LEFT PARENTHESIS (U+0028).
1796+
3. The result of [=serialize a function parameter=]
1797+
on each of the [=mixin's=] [=function parameter|parameters=],
1798+
all joined by <code>", "</code>
1799+
(COMMA U+002C, followed by a single SPACE U+0020).
1800+
4. A single RIGHT PARENTHESIS (U+0029).
1801+
5. A single LEFT CURLY BRACKET (U+007B),
1802+
followed by a SPACE (U+0020).
1803+
6. The result of performing [=serialize a CSS rule=]
1804+
on each rule in cssRules,
1805+
filtering out empty strings,
1806+
all joined by a single SPACE (U+0020).
1807+
7. A single SPACE (U+0020),
1808+
followed by a single RIGHT CURLY BRACKET (U+007D).
1809+
</div>
1810+
1811+
The {{CSSApplyBlockRule}} Interface {#the-apply-block-interface}
1812+
----------------------------------------------------------------
1813+
1814+
The {{CSSApplyBlockRule}} interface represents
1815+
an ''@apply'' rule with a [=contents block=].
1816+
1817+
<pre class='idl' export>
1818+
[Exposed=Window]
1819+
interface CSSApplyBlockRule : CSSGroupingRule {
1820+
readonly attribute CSSOMString name;
1821+
sequence&lt;CSSOMString&gt; getArguments();
1822+
};
1823+
</pre>
1824+
1825+
<dl dfn-for=CSSApplyBlockRule>
1826+
<dt><dfn dfn-type=attribute>name</dfn>
1827+
<dd>
1828+
If the ''@apply'' rule has an associated <<dashed-ident>>,
1829+
the result of [=serialize an identifier=] on that [=ident=].
1830+
Otherwise,
1831+
the result of [=serialize an identifier=] on the name
1832+
of the associated <<dashed-function>>.
1833+
</dd>
1834+
<dt><dfn dfn-type=method>getArguments()</dfn>
1835+
<dd>
1836+
Returns a sequence of arguments as strings,
1837+
each item [[css-variables-1#serializing-custom-props|serialized]]
1838+
as if it had been the specified value of a [=custom property=].
1839+
</dd>
1840+
</dl>
1841+
1842+
The [=CSSRule/child CSS rules=] of a {{CSSApplyBlockRule}}
1843+
represent the [=contents block=]
1844+
of the ''@apply'' rule.
1845+
1846+
As for {{CSSMixinRule}},
1847+
consecutive segments of declarations
1848+
specified directly within the [=contents block=] of an ''@apply'' rule
1849+
are represented as {{CSSNestedDeclarations}}.
1850+
1851+
<div algorithm>
1852+
To <dfn export>serialize a CSSApplyBlockRule</dfn>,
1853+
return the concatenation of the following:
1854+
1855+
1. The string <code>"@apply"</code> followed by a single SPACE (U+0020).
1856+
2. The result of performing [=serialize an @apply prelude=]
1857+
on the ''@apply'' rule.
1858+
3. A single SPACE (U+0020).
1859+
4. A single LEFT CURLY BRACKET (U+007B),
1860+
followed by a SPACE (U+0020).
1861+
5. The result of performing [=serialize a CSS rule=]
1862+
on each rule in cssRules,
1863+
filtering out empty strings,
1864+
all joined by a single SPACE (U+0020).
1865+
6. A single SPACE (U+0020),
1866+
followed by a RIGHT CURLY BRACKET (U+007D).
1867+
</div>
1868+
1869+
<div algorithm>
1870+
To <dfn export>serialize an @apply prelude</dfn>,
1871+
given an ''@apply'' rule,
1872+
return the concatenation of the following:
1873+
1874+
1. The {{CSSApplyBlockRule/name}} of the ''@apply'' rule.
1875+
2. If the ''@apply'' rule has at least one argument,
1876+
the concatenation of:
1877+
* A single LEFT PARENTHESIS (U+0028).
1878+
* The result of performing [=serialize a function argument=]
1879+
on each argument,
1880+
all joined by <code>", "</code>.
1881+
* A single RIGHT PARENTHESIS (U+0029).
1882+
</div>
1883+
1884+
<div algorithm>
1885+
To <dfn export>serialize a function argument</dfn>,
1886+
given a <<declaration-value>> |argument|:
1887+
1888+
1. [[css-variables-1#serializing-custom-props|Serialize]] |argument|
1889+
as if it had been the specified value of a [=custom property=],
1890+
and let |serialized argument| be the result.
1891+
<div class=note>
1892+
This means that an argument serializes exactly as written,
1893+
except with leading and trailing whitespace removed.
1894+
</div>
1895+
2. If |serialized argument| does not contain any top-level <<comma-token>>s,
1896+
nor any top-level <<{-token>>s,
1897+
return |serialized argument|.
1898+
3. Otherwise, return the concatenation of the following:
1899+
* A single LEFT CURLY BRACKET (U+007B),
1900+
followed by a SPACE (U+0020).
1901+
* The value of |serialized argument|.
1902+
* A single SPACE (U+0020),
1903+
followed by a RIGHT CURLY BRACKET (U+007D).
1904+
1905+
<div class=note>
1906+
See [[css-values-5#component-function-commas]] for more information
1907+
on [=comma-containing productions=].
1908+
</div>
1909+
</div>
1910+
1911+
The {{CSSApplyStatementRule}} Interface {#the-apply-statement-interface}
1912+
------------------------------------------------------------------------
1913+
1914+
The {{CSSApplyStatementRule}} interface represents
1915+
an ''@apply'' rule without a [=contents block=].
1916+
1917+
<pre class='idl' export>
1918+
[Exposed=Window]
1919+
interface CSSApplyStatementRule : CSSRule {
1920+
readonly attribute CSSOMString name;
1921+
sequence&lt;CSSOMString&gt; getArguments();
1922+
};
1923+
</pre>
1924+
1925+
<dl dfn-for=CSSApplyStatementRule dfn-type=attribute>
1926+
<dt><dfn>name</dfn>
1927+
<dd>
1928+
The same as {{CSSApplyBlockRule/name|CSSApplyBlockRule.name}}.
1929+
</dd>
1930+
<dt><dfn dfn-type=method>getArguments()</dfn>
1931+
<dd>
1932+
The same as {{CSSApplyBlockRule/getArguments()|CSSApplyBlockRule.getArguments()}}.
1933+
</dd>
1934+
</dl>
1935+
1936+
<div algorithm>
1937+
To <dfn export>serialize a CSSApplyStatementRule</dfn>,
1938+
return the concatenation of the following:
1939+
1940+
1. The string <code>"@apply"</code> followed by a single SPACE (U+0020).
1941+
2. The result of performing [=serialize an @apply prelude=]
1942+
on the ''@apply'' rule.
1943+
3. A single SEMICOLON (U+003B).
1944+
</div>
1945+
1946+
The {{CSSContentsBlockRule}} Interface {#the-contents-block-interface}
1947+
---------------------------------------------------------------------
1948+
1949+
The {{CSSContentsBlockRule}} interface represents
1950+
a ''@contents'' rule with a [=fallback block=].
1951+
1952+
<pre class='idl' export>
1953+
[Exposed=Window]
1954+
interface CSSContentsBlockRule : CSSGroupingRule { };
1955+
</pre>
1956+
1957+
The [=CSSRule/child CSS rules=] of a {{CSSContentsBlockRule}}
1958+
represent the [=fallback block=]
1959+
of the ''@contents'' rule.
1960+
1961+
As for {{CSSMixinRule}} and {{CSSApplyBlockRule}},
1962+
consecutive segments of declarations
1963+
specified directly within the [=fallback block=] of a ''@contents'' rule
1964+
are represented as {{CSSNestedDeclarations}}.
1965+
1966+
<div algorithm>
1967+
To <dfn export>serialize a CSSContentsBlockRule</dfn>,
1968+
return the concatenation of the following:
1969+
1970+
1. The string <code>"@contents"</code> followed by a single SPACE (U+0020).
1971+
2. A single LEFT CURLY BRACKET (U+007B),
1972+
followed by a SPACE (U+0020).
1973+
3. The result of performing [=serialize a CSS rule=]
1974+
on each rule in cssRules,
1975+
filtering out empty strings,
1976+
all joined by a single SPACE (U+0020).
1977+
4. A single SPACE (U+0020),
1978+
followed by a RIGHT CURLY BRACKET (U+007D).
1979+
</div>
1980+
1981+
The {{CSSContentsStatementRule}} Interface {#the-contents-statement-interface}
1982+
------------------------------------------------------------------------------
1983+
1984+
The {{CSSContentsStatementRule}} interface represents
1985+
a ''@contents'' rule without a [=fallback block=].
1986+
1987+
<pre class='idl' export>
1988+
[Exposed=Window]
1989+
interface CSSContentsStatementRule : CSSRule { };
1990+
</pre>
1991+
1992+
<div algorithm>
1993+
To <dfn export>serialize a CSSContentsStatementRule</dfn>,
1994+
return the string <code>"@contents"</code>,
1995+
followed by a single SEMICOLON (U+003B).
1996+
</div>
1997+
17461998
Privacy Considerations {#privacy}
17471999
===============================================
17482000

‎cssom-1/Overview.bs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1808,7 +1808,7 @@ null.
18081808
<dd>A reference to a parent <a>CSS style sheet</a> or null.
18091809
This item is initialized to reference an associated style sheet when the rule is created. It can be changed to null.
18101810

1811-
<dt><dfn id=concept-css-rule-child-css-rules>child CSS rules</dfn>
1811+
<dt><dfn export id=concept-css-rule-child-css-rules>child CSS rules</dfn>
18121812
<dd>A list of child <a for=/>CSS rules</a>. The list can be mutated.
18131813
</dl>
18141814

0 commit comments

Comments
 (0)