Skip to content

Commit f257366

Browse files
tabatkinstabatkins
committed
[css-variables] First draft of a MapLike CSSVariablesMap interface, pending heycam formalizing it in WebIDL.
1 parent 389e9fa commit f257366

2 files changed

Lines changed: 115 additions & 94 deletions

File tree

‎css-variables/Overview.html‎

Lines changed: 60 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -79,8 +79,9 @@ <h2 id="contents" class="no-num no-toc no-ref">Table of contents</h2>
7979
Invalid Variables</a></li></ul></li><li><a href="#cssom"><span class="secno">4 </span>
8080
APIs</a><ul class="toc"><li><a href="#the-cssstyledeclaration-interface"><span class="secno">4.1 </span>
8181
Extensions to the <code>CSSStyleDeclaration</code> Interface</a><ul class="toc"><li><a href="#serializing-custom-props"><span class="secno">4.1.1 </span>
82-
Serializing Custom Properties</a></li></ul></li><li><a href="#the-cssvariablesdeclaration-interface"><span class="secno">4.2 </span>
83-
The <code>CSSVariablesDeclaration</code> Interface</a></li></ul></li><li><a href="#changes"><span class="secno">5 </span>
82+
Serializing Custom Properties</a></li></ul></li><li><a href="#the-CSSVariablesMap-interface"><span class="secno">4.2 </span>
83+
The <code>CSSVariablesMap</code> Interface</a><ul class="toc"><li><a href="#cssvariablesmap-methods"><span class="secno">4.2.1 </span>
84+
<code>CSSVariablesMap Methods</code></a></li></ul></li></ul></li><li><a href="#changes"><span class="secno">5 </span>
8485
Changes from 10 April 2012 Working Draft</a></li><li><a href="#acknowledgments"><span class="secno">6 </span>
8586
Acknowledgments</a></li><li><a href="#conformance">
8687
Conformance</a><ul class="toc"><li><a href="#conventions">
@@ -635,11 +636,11 @@ <h3 id="the-cssstyledeclaration-interface" data-level="4.1"><span class="secno">
635636
<p> The <dfn id="cssstyledeclaration"><code>CSSStyleDeclaration</code></dfn> interface is amended as follows:
636637

637638
</p><pre class="idl">partial interface CSSStyleDeclaration {
638-
readonly attribute CSSVariablesDeclaration var;
639+
readonly attribute CSSVariablesMap var;
639640
}
640641
</pre>
641642
<p> A <code>CSSStyleDeclaration</code> is the <dfn id="associated-style-declaration">associated style declaration</dfn>
642-
for the <code>CSSVariablesDeclaration</code> assigned to its <code>var</code> attribute.
643+
for the <code>CSSVariablesMap</code> assigned to its <code>var</code> attribute.
643644

644645
</p><p> While the CSSStyleDeclaration interface normally contains attributes that are camel-cased name variants of all CSS properties
645646
(and sometimes also attributes for their canonical names),
@@ -661,48 +662,65 @@ <h3 id="the-cssstyledeclaration-interface" data-level="4.1"><span class="secno">
661662
Ordinarily, property names are restricted to the ASCII range and are case-insensitive,
662663
so implementations typically serialize the name lowercased.
663664

664-
</p><h3 id="the-cssvariablesdeclaration-interface" data-level="4.2"><span class="secno">4.2 </span>
665-
The <code>CSSVariablesDeclaration</code> Interface</h3>
665+
</p><h3 id="the-CSSVariablesMap-interface" data-level="4.2"><span class="secno">4.2 </span>
666+
The <code>CSSVariablesMap</code> Interface</h3>
666667

667-
<p> The <dfn id="cssvariablesdeclaration"><code>CSSVariablesDeclaration</code></dfn> interface
668+
<p> The <dfn id="cssvariablesmap"><code>CSSVariablesMap</code></dfn> interface
668669
exposes the <a data-autolink="link" href="#custom-property">custom properties</a> declared in the parent declaration block
669670
that have a non-initial value.
670671

671-
</p><pre class="idl">interface CSSVariablesDeclaration {
672-
<a data-autolink="link" href="#cssvariablesdeclaration-getter">getter</a> DOMString (DOMString varName);
673-
<a data-autolink="link" href="#cssvariablesdeclaration-setter">setter</a> <a data-autolink="link" href="#cssvariablesdeclaration-creator">creator</a> void (DOMString varName, DOMString varValue);
674-
<a data-autolink="link" href="#cssvariablesdeclaration-deleter">deleter</a> void (DOMString varName);
672+
</p><pre class="idl">[MapClass(DOMString, DOMString)]
673+
interface CSSVariablesMap {
674+
DOMString get(DOMString varName);
675+
boolean has(DOMString varName);
676+
void set(DOMString varName, DOMString varValue);
677+
DOMString delete(DOMString varName);
675678
}
676679
</pre>
677-
<p> The <a href="http://dev.w3.org/2006/webapi/WebIDL/#dfn-supported-property-names">supported property names</a>
678-
on a CSSStyleDeclaration object
680+
<p> The <a href="http://dev.w3.org/2006/webapi/WebIDL/#REPLACE-ME">map tuples</a>
681+
on a CSSVariablesMap object
679682
are the property names of all the <a data-autolink="link" href="#custom-property">custom properties</a> in the <a href="http://dev.w3.org/csswg/cssom/#css-declaration-block-declarations"><dfn id="css-declaration-block-declarations">CSS declaration block declarations</dfn></a>
680683
with a non-initial value,
681-
with the "var-" prefix removed.
684+
with the "var-" prefix removed,
685+
paired with their values.
686+
687+
</p><h4 id="cssvariablesmap-methods" data-level="4.2.1"><span class="secno">4.2.1 </span>
688+
<code>CSSVariablesMap Methods</code></h4>
689+
690+
<dl>
691+
<dt>get(DOMString varName), returns DOMString
692+
</dt><dd>
693+
Prepend "var-" to <var>varName</var>.
694+
Invoke <code>getPropertyValue()</code>
695+
on the <a data-autolink="link" href="#associated-style-declaration">associated style declaration</a>
696+
by passing <var>varName</var> as its argument,
697+
and return its returned value.
698+
699+
</dd><dt>has(DOMString varName), returns boolean
700+
</dt><dd>
701+
Invoke get() on the CSSVariablesMap object
702+
by passing <var>varName</var> as its argument.
703+
If the return value is the empty string,
704+
return <code>false</code>;
705+
otherwise, return <code>true</code>.
706+
707+
</dd><dt>set(DOMString varName, DOMString varValue), returns void
708+
</dt><dd>
709+
Prepend "var-" to <var>varName</var>.
710+
Invoke <code>getPropertyValue()</code>
711+
on the <a data-autolink="link" href="#associated-style-declaration">associated style declaration</a>
712+
by passing <var>varName</var> and <var>varValue</var> as its two arguments, in that order.
713+
714+
</dd><dt>delete(DOMString varName), return DOMString
715+
</dt><dd>
716+
Prepend "var-" to <var>varName</var>.
717+
Invoke <code>removeProperty()</code>
718+
on the <a data-autolink="link" href="#associated-style-declaration">associated style declaration</a>
719+
by passing <var>varName</var> as its argument.
720+
Return its returned value.
721+
</dd></dl>
682722

683-
</p><p> Before running any of the algorithms in this section,
684-
prepend "var-" to <var>varName's</var> value.
685-
686-
</p><p> When asked to <dfn id="cssvariablesdeclaration-getter" title="getter">get the value of a variable</dfn>,
687-
if <var>varName</var> is in the <a data-autolink="link" href="#css-declaration-block-declarations">CSS declaration block declarations</a>,
688-
invoke <code>getPropertyValue()</code> on the <a data-autolink="link" href="#associated-style-declaration">associated style declaration</a> by passing <var>varName</var> as its argument,
689-
and return the returned value.
690-
Otherwise, return the empty string.
691-
692-
</p><p> When asked to <dfn id="cssvariablesdeclaration-setter" title="setter">set</dfn> or <dfn id="cssvariablesdeclaration-creator" title="creator">create the value of a variable</dfn>,
693-
invoke <code>setProperty()</code> on the <a data-autolink="link" href="#associated-style-declaration">associated style declaration</a> by passing <var>varName</var> as the first argument and <var>varValue</var> as the second argument.
694-
695-
</p><p class="note">
696-
Note that using <code>setProperty()</code> to set a property to the empty string
697-
instead deletes the property.
698-
699-
</p><p> When asked to <dfn id="cssvariablesdeclaration-deleter" title="deleter">delete the value of a variable</dfn>,
700-
if <var>varName</var> matches the grammar of a <a data-autolink="link" href="#custom-property">custom property</a> name,
701-
invoke <code>removeProperty()</code> on the <a data-autolink="link" href="#associated-style-declaration">associated style declaration</a> by passing <var>varName</var> as its argument,
702-
and return the returned value.
703-
Otherwise, do nothing and return the empty string.
704-
705-
</p><div class="example">
723+
<div class="example">
706724
<style scoped="">
707725
#var-code-examples td { padding: 2px; }
708726
#var-code-examples code { background: rgba(0,0,0,.05); display: inline-block; padding: 1px 2px; white-space: pre; }
@@ -729,15 +747,15 @@ <h3 id="the-cssstyledeclaration-interface" data-level="4.1"><span class="secno">
729747
</th><th>Notes
730748
</th></tr></thead><tbody>
731749
<tr>
732-
<td><code>el.style.var.foo</code>
750+
<td><code>el.style.var.get("foo")</code>
733751
</td><td><code>"16px"</code>
734752
</td><td>The value of <a data-autolink="property" class="property" title="var-foo">var-foo</a>.
735753
</td></tr><tr>
736-
<td><code>el.style.var.Bar</code>
754+
<td><code>el.style.var.get("Bar")</code>
737755
</td><td><code>"red"</code>
738756
</td><td>The value of <a data-autolink="property" class="property" title="var-Bar">var-Bar</a>.
739757
</td></tr><tr>
740-
<td><code>el.style.var["foo-bar"]</code>
758+
<td><code>el.style.var.get("foo-bar")</code>
741759
</td><td><code>"50%"</code>
742760
</td><td>The value of <a data-autolink="property" class="property" title="var-foo-bar">var-foo-bar</a>.
743761
</td></tr><tr>
@@ -748,13 +766,6 @@ <h3 id="the-cssstyledeclaration-interface" data-level="4.1"><span class="secno">
748766
<td><code>el.style.varBar</code>
749767
</td><td>n/a
750768
</td><td>Not even if the casing matches.
751-
</td></tr><tr>
752-
<td><code>el.style.var.foo-bar</code>
753-
</td><td><code>NaN</code>
754-
</td><td>Retrieves the value of <a data-autolink="property" class="property" title="var-foo">var-foo</a>
755-
(the string <code>"16px"</code>)
756-
and subtracts some unrelated JavaScript variable named "bar" from it,
757-
rather than just retrieving the value of <a data-autolink="property" class="property" title="var-foo-bar">var-foo-bar</a>.
758769
</td></tr></tbody></table>
759770
</div>
760771

@@ -782,7 +793,7 @@ <h2 id="changes" data-level="5"><span class="secno">5 </span>
782793
</li><li>The fallback argument was added to the var() function.
783794
</li><li>A property that is invalid at computed-value time now either goes inherit or initial, rather than always initial.
784795
</li><li>CSSVariableComponentValue interface has been dropped, pending the *ComponentValue interfaces being created at all.
785-
</li><li>The CSSVariablesDeclaration interface has been added, which stores all the variables defined by a style rule.
796+
</li><li>The CSSVariablesMap interface has been added, which stores all the variables defined by a style rule.
786797
</li></ul>
787798

788799

@@ -932,7 +943,7 @@ <h3 id="informative" class="no-num no-ref">
932943

933944
<h2 id="index" class="no-num no-ref">
934945
Index</h2>
935-
<div data-fill-with="index"><ul class="indexlist"><li>&lt;any-value&gt;, <a href="#any-value-production" title="section 2">2</a></li><li>associated style declaration, <a href="#associated-style-declaration" title="section 4.1">4.1</a></li><li>cascading variable, <a href="#cascading-variable" title="section 2">2</a></li><li>creator, <a href="#cssvariablesdeclaration-creator" title="section 4.2">4.2</a></li><li>CSS declaration block declarations, <a href="#css-declaration-block-declarations" title="section 4.2">4.2</a></li><li>CSSStyleDeclaration, <a href="#cssstyledeclaration" title="section 4.1">4.1</a></li><li>CSSVariablesDeclaration, <a href="#cssvariablesdeclaration" title="section 4.2">4.2</a></li><li>custom property, <a href="#custom-property" title="section 2">2</a></li><li>deleter, <a href="#cssvariablesdeclaration-deleter" title="section 4.2">4.2</a></li><li>getter, <a href="#cssvariablesdeclaration-getter" title="section 4.2">4.2</a></li><li>invalid at computed-value time, <a href="#invalid-at-computed-value-time" title="section 3.1">3.1</a></li><li>invalid variable, <a href="#invalid-variable" title="section 3.1">3.1</a></li><li>resolve a variable, <a href="#resolve-a-variable" title="section 3">3</a></li><li>setter, <a href="#cssvariablesdeclaration-setter" title="section 4.2">4.2</a></li><li>var(), <a href="#variable-type" title="section 3">3</a></li><li>var-*, <a href="#var-" title="section 2">2</a></li><li>&lt;variable&gt;, <a href="#variable-type" title="section 3">3</a></li><li>variable, <a href="#cascading-variable" title="section 2">2</a></li></ul></div>
946+
<div data-fill-with="index"><ul class="indexlist"><li>&lt;any-value&gt;, <a href="#any-value-production" title="section 2">2</a></li><li>associated style declaration, <a href="#associated-style-declaration" title="section 4.1">4.1</a></li><li>cascading variable, <a href="#cascading-variable" title="section 2">2</a></li><li>CSS declaration block declarations, <a href="#css-declaration-block-declarations" title="section 4.2">4.2</a></li><li>CSSStyleDeclaration, <a href="#cssstyledeclaration" title="section 4.1">4.1</a></li><li>CSSVariablesMap, <a href="#cssvariablesmap" title="section 4.2">4.2</a></li><li>custom property, <a href="#custom-property" title="section 2">2</a></li><li>invalid at computed-value time, <a href="#invalid-at-computed-value-time" title="section 3.1">3.1</a></li><li>invalid variable, <a href="#invalid-variable" title="section 3.1">3.1</a></li><li>resolve a variable, <a href="#resolve-a-variable" title="section 3">3</a></li><li>var(), <a href="#variable-type" title="section 3">3</a></li><li>var-*, <a href="#var-" title="section 2">2</a></li><li>&lt;variable&gt;, <a href="#variable-type" title="section 3">3</a></li><li>variable, <a href="#cascading-variable" title="section 2">2</a></li></ul></div>
936947

937948
<h2 id="property-index" class="no-num no-ref">
938949
Property index</h2>

‎css-variables/Overview.src.html‎

Lines changed: 55 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -595,12 +595,12 @@ <h3 id='the-cssstyledeclaration-interface'>
595595

596596
<pre class='idl'>
597597
partial interface CSSStyleDeclaration {
598-
readonly attribute CSSVariablesDeclaration var;
598+
readonly attribute CSSVariablesMap var;
599599
}
600600
</pre>
601601

602602
A <code>CSSStyleDeclaration</code> is the <dfn>associated style declaration</dfn>
603-
for the <code>CSSVariablesDeclaration</code> assigned to its <code>var</code> attribute.
603+
for the <code>CSSVariablesMap</code> assigned to its <code>var</code> attribute.
604604

605605
While the CSSStyleDeclaration interface normally contains attributes that are camel-cased name variants of all CSS properties
606606
(and sometimes also attributes for their canonical names),
@@ -622,48 +622,65 @@ <h4 id='serializing-custom-props'>
622622
Ordinarily, property names are restricted to the ASCII range and are case-insensitive,
623623
so implementations typically serialize the name lowercased.
624624

625-
<h3 id='the-cssvariablesdeclaration-interface'>
626-
The <code>CSSVariablesDeclaration</code> Interface</h3>
625+
<h3 id='the-CSSVariablesMap-interface'>
626+
The <code>CSSVariablesMap</code> Interface</h3>
627627

628-
The <dfn><code>CSSVariablesDeclaration</code></dfn> interface
628+
The <dfn><code>CSSVariablesMap</code></dfn> interface
629629
exposes the <a>custom properties</a> declared in the parent declaration block
630630
that have a non-initial value.
631631

632632
<pre class='idl'>
633-
interface CSSVariablesDeclaration {
634-
<a>getter</a> DOMString (DOMString varName);
635-
<a>setter</a> <a>creator</a> void (DOMString varName, DOMString varValue);
636-
<a>deleter</a> void (DOMString varName);
633+
[MapClass(DOMString, DOMString)]
634+
interface CSSVariablesMap {
635+
DOMString get(DOMString varName);
636+
boolean has(DOMString varName);
637+
void set(DOMString varName, DOMString varValue);
638+
DOMString delete(DOMString varName);
637639
}
638640
</pre>
639641

640-
The <a href="http://dev.w3.org/2006/webapi/WebIDL/#dfn-supported-property-names">supported property names</a>
641-
on a CSSStyleDeclaration object
642+
The <a href="http://dev.w3.org/2006/webapi/WebIDL/#REPLACE-ME">map tuples</a>
643+
on a CSSVariablesMap object
642644
are the property names of all the <a>custom properties</a> in the <a href="http://dev.w3.org/csswg/cssom/#css-declaration-block-declarations"><dfn>CSS declaration block declarations</dfn></a>
643645
with a non-initial value,
644-
with the "var-" prefix removed.
645-
646-
Before running any of the algorithms in this section,
647-
prepend "var-" to <var>varName's</var> value.
648-
649-
When asked to <dfn id='cssvariablesdeclaration-getter' title='getter'>get the value of a variable</dfn>,
650-
if <var>varName</var> is in the <a>CSS declaration block declarations</a>,
651-
invoke <code>getPropertyValue()</code> on the <a>associated style declaration</a> by passing <var>varName</var> as its argument,
652-
and return the returned value.
653-
Otherwise, return the empty string.
654-
655-
When asked to <dfn id='cssvariablesdeclaration-setter' title='setter'>set</dfn> or <dfn id='cssvariablesdeclaration-creator' title='creator'>create the value of a variable</dfn>,
656-
invoke <code>setProperty()</code> on the <a>associated style declaration</a> by passing <var>varName</var> as the first argument and <var>varValue</var> as the second argument.
657-
658-
<p class='note'>
659-
Note that using <code>setProperty()</code> to set a property to the empty string
660-
instead deletes the property.
661-
662-
When asked to <dfn id='cssvariablesdeclaration-deleter' title='deleter'>delete the value of a variable</dfn>,
663-
if <var>varName</var> matches the grammar of a <a>custom property</a> name,
664-
invoke <code>removeProperty()</code> on the <a>associated style declaration</a> by passing <var>varName</var> as its argument,
665-
and return the returned value.
666-
Otherwise, do nothing and return the empty string.
646+
with the "var-" prefix removed,
647+
paired with their values.
648+
649+
<h4 id='cssvariablesmap-methods'>
650+
<code>CSSVariablesMap Methods</code></h4>
651+
652+
<dl>
653+
<dt>get(DOMString varName), returns DOMString
654+
<dd>
655+
Prepend "var-" to <var>varName</var>.
656+
Invoke <code>getPropertyValue()</code>
657+
on the <a>associated style declaration</a>
658+
by passing <var>varName</var> as its argument,
659+
and return its returned value.
660+
661+
<dt>has(DOMString varName), returns boolean
662+
<dd>
663+
Invoke get() on the CSSVariablesMap object
664+
by passing <var>varName</var> as its argument.
665+
If the return value is the empty string,
666+
return <code>false</code>;
667+
otherwise, return <code>true</code>.
668+
669+
<dt>set(DOMString varName, DOMString varValue), returns void
670+
<dd>
671+
Prepend "var-" to <var>varName</var>.
672+
Invoke <code>getPropertyValue()</code>
673+
on the <a>associated style declaration</a>
674+
by passing <var>varName</var> and <var>varValue</var> as its two arguments, in that order.
675+
676+
<dt>delete(DOMString varName), return DOMString
677+
<dd>
678+
Prepend "var-" to <var>varName</var>.
679+
Invoke <code>removeProperty()</code>
680+
on the <a>associated style declaration</a>
681+
by passing <var>varName</var> as its argument.
682+
Return its returned value.
683+
</dl>
667684

668685
<div class='example'>
669686
<style scoped>
@@ -694,15 +711,15 @@ <h3 id='the-cssvariablesdeclaration-interface'>
694711
<th>Notes
695712
<tbody>
696713
<tr>
697-
<td><code>el.style.var.foo</code>
714+
<td><code>el.style.var.get("foo")</code>
698715
<td><code>"16px"</code>
699716
<td>The value of 'var-foo'.
700717
<tr>
701-
<td><code>el.style.var.Bar</code>
718+
<td><code>el.style.var.get("Bar")</code>
702719
<td><code>"red"</code>
703720
<td>The value of 'var-Bar'.
704721
<tr>
705-
<td><code>el.style.var["foo-bar"]</code>
722+
<td><code>el.style.var.get("foo-bar")</code>
706723
<td><code>"50%"</code>
707724
<td>The value of 'var-foo-bar'.
708725
<tr>
@@ -713,13 +730,6 @@ <h3 id='the-cssvariablesdeclaration-interface'>
713730
<td><code>el.style.varBar</code>
714731
<td>n/a
715732
<td>Not even if the casing matches.
716-
<tr>
717-
<td><code>el.style.var.foo-bar</code>
718-
<td><code>NaN</code>
719-
<td>Retrieves the value of 'var-foo'
720-
(the string <code>"16px"</code>)
721-
and subtracts some unrelated JavaScript variable named "bar" from it,
722-
rather than just retrieving the value of 'var-foo-bar'.
723733
</table>
724734
</div>
725735

@@ -749,7 +759,7 @@ <h2 id='changes'>
749759
<li>The fallback argument was added to the var() function.
750760
<li>A property that is invalid at computed-value time now either goes inherit or initial, rather than always initial.
751761
<li>CSSVariableComponentValue interface has been dropped, pending the *ComponentValue interfaces being created at all.
752-
<li>The CSSVariablesDeclaration interface has been added, which stores all the variables defined by a style rule.
762+
<li>The CSSVariablesMap interface has been added, which stores all the variables defined by a style rule.
753763
</ul>
754764

755765

0 commit comments

Comments
 (0)