Experiment: add special syntax for CSS variables

README.md

@@ -147,6 +147,67 @@ appropriate CSS into the DOM on-demand, and returns the animation identifier:
   {:animation [[(anim-frames) "560ms" 'ease-in-out]]})
 ```
 
+### Syntactic Sugar
+
+Spade also provides some extra syntactic sugar, performed at compile time
+for "zero-cost" abstractions.
+
+#### CSS Custom Properties
+
+CSS custom properties (AKA variables) can be a convenient way to, for
+example, define dynamic theme colors once and reuse them throughout the
+codebase. Spade provides some extra sugar to make using them easier and
+more idiomatic:
+
+```clojure
+(defglobal light-dark
+  (at-media {:prefers-color-scheme 'dark}
+    [":root" {:theme/*background* "#000"
+              :theme/*text* "#E0EBFF"}])
+  [":root" {:theme/*background* "#fff"
+            :theme/*text* "#000"}])
+
+(defclass page []
+  {:background :theme/*background*
+   :color :theme/*text*})
+```
+
+Notice how our declaration and usage sites are identical, and that
+they're "just" normal keywords. However, by using `*earmuffs*` around
+the name of the keyword, Spade knows that it is meant to be a variable,
+and applies the correct CSS styling based on the position within the
+style. This naming was chosen because it is reminiscent of the naming
+of dynamic Clojure vars, and because `*` is not valid in a CSS property
+name, so the meaning is unambiguous.
+
+Normal keyword namespace semantics apply, so you can expect that
+`:theme/*text*` and `:crew.quarters/*text*` will result in distinct
+variables. In fact, you don't need any namespace at all; `:*text*` will
+also result in a perfectly valid CSS variable, disinct from any of the
+other two mentioned above.
+
+The above example will generate the following CSS:
+
+```css
+@media (prefers-color-scheme: dark) {
+  :root {
+    --theme--background: #000;
+    --theme--text: #E0EBFF;
+  }
+}
+
+:root {
+  --theme--background: #fff;
+  --theme--text: #000;
+}
+
+.page {
+  background: var(--theme--background);
+  color: var(--theme--text);
+}
+```
+
+Note that [CSS Custom Properties are not supported on all browsers][4], and this syntax compiles to that feature directly without any attempt at backwards compatibility—if CSS Custom Properties are not supported on a browser you are targetting, this syntax will also not be supported.
 
 ## Development
 
@@ -172,3 +233,4 @@ Distributed under the Eclipse Public License either version 1.0
 [1]: https://github.com/css-modules/css-modules
 [2]: https://github.com/noprompt/garden/
 [3]: https://github.com/roosta/herb
+[4]: https://caniuse.com/css-variables

dev/spade/demo.cljs

@@ -12,7 +12,8 @@
   ["100%" {:opacity end}])
 
 (defglobal background
-  [:body {:background "#333"}])
+  [:body {:*my-var* "22pt"
+          :background "#333"}])
 
 (defglobal text
   [:body {:color "#fff"}])
@@ -22,7 +23,7 @@
     {:padding "80px"})
   {:padding "8px"}
 
-  [:.title {:font-size "22pt"
+  [:.title {:font-size :*my-var*
             :animation [[(parameterized-anim-frames 0 0.5) "560ms" 'ease-in-out]]}])
 
 (defclass colorized-with-key [color]

src/spade/core.cljc

@@ -1,5 +1,6 @@
 (ns spade.core
-  (:require [clojure.walk :refer [postwalk]]
+  (:require [clojure.string :as str]
+            [clojure.walk :refer [postwalk prewalk]]
             [spade.util :refer [factory->name build-style-name]]))
 
 (defn- extract-key [style]
@@ -34,6 +35,49 @@
         element))
     style))
 
+(defn- clean-property-name [n]
+  (when n
+    (str/replace n #"[^a-zA-Z0-9_-]" "-")))
+
+(defn- css-var? [element]
+  (and (keyword? element)
+       (let [n (name element)]
+         (and (str/starts-with? n "*")
+              (str/ends-with? n "*")))))
+
+(defn- varify-key [element]
+  (let [space (namespace element)
+        n (name element)]
+    (keyword (str (when space "--")
+                  (clean-property-name (namespace element))
+                  "--"
+                  (clean-property-name
+                    (subs n 1 (dec (count n))))))))
+
+(defn- varify-val [element]
+  `(spade.runtime/->css-var ~(varify-key element)))
+
+(defn- rename-vars [style]
+  (prewalk
+    (fn [element]
+      (cond
+        (map-entry? element)
+        (let [var-key? (css-var? (key element))
+              var-val? (css-var? (val element))]
+          (if (or var-key? var-val?)
+            (-> element
+                (update 0 (if var-key? varify-key identity))
+                (update 1 (if var-val? varify-val identity)))
+
+            element))
+
+        (css-var? element)
+        (varify-val element)
+
+        :else
+        element))
+    style))
+
 (defn- extract-composes [style]
   (if-let [composes (when (map? (first style))
                       (:composes (first style)))]
@@ -94,7 +138,7 @@
 (defn- transform-named-style [style params style-name-var params-var]
   (let [[composition style] (extract-composes style)
         style-var (gensym "style")
-        style (prefix-at-media style)
+        style (->> style prefix-at-media rename-vars)
         [base-style-var name-var name-let] (build-style-naming-let
                                              style params style-name-var
                                              params-var)
@@ -106,7 +150,8 @@
        ~(with-composition composition name-var style-var))))
 
 (defn- transform-keyframes-style [style params style-name-var params-var]
-  (let [[style-var name-var style-naming-let] (build-style-naming-let
+  (let [style (->> style prefix-at-media rename-vars)
+        [style-var name-var style-naming-let] (build-style-naming-let
                                                 style params style-name-var
                                                 params-var)
         info-map `{:css (spade.runtime/compile-css
@@ -127,7 +172,7 @@
   (let [style (replace-at-forms style)]
     (cond
       (#{:global} mode)
-      `{:css (spade.runtime/compile-css ~(vec style))
+      `{:css (spade.runtime/compile-css ~(vec (rename-vars style)))
         :name ~style-name-var}
 
       ; keyframes are a bit of a special case

src/spade/runtime.cljs

@@ -1,6 +1,7 @@
 (ns spade.runtime
   (:require [clojure.string :as str]
-            [garden.core :as garden]))
+            [garden.core :as garden]
+            [garden.types :refer [->CSSFunction]]))
 
 (defonce
   ^{:private true
@@ -10,6 +11,9 @@
 (defonce ^:dynamic *css-compile-flags*
   {:pretty-print? goog.DEBUG})
 
+(defn ->css-var [n]
+  (->CSSFunction "var" n))
+
 (defn compile-css [elements]
   (garden/css *css-compile-flags* elements))
 

test/spade/core_test.cljs

@@ -3,6 +3,14 @@
             [clojure.string :as str]
             [spade.core :refer [defattrs defclass defglobal defkeyframes]]))
 
+; for the linter's sake:
+(declare with-media-factory$
+         class-with-vars-factory$
+         fixed-style-attrs-factory$
+         composed-factory$
+         composed-attrs-factory$
+         parameterized-key-frames-factory$)
+
 (defclass computed-key [color]
   ^{:key (str/upper-case color)}
   {:color color})
@@ -20,6 +28,13 @@
     {:background "blue"}
     [:.nested {:background "red"}]))
 
+(defclass class-with-vars []
+  {:*my-var* "42pt"
+   ::*namespaced* "blue"
+   :font-size :*my-var*
+   :background ::*namespaced*
+   :color [[:*my-var* :!important]]})
+
 (deftest defclass-test
   (testing "computed-key test"
     (is (= "spade-core-test-computed-key_BLUE"
@@ -41,20 +56,47 @@
             generated
             (str "@media (max-width: 50px) { "
                  ".with-media { background: blue; } "
-                 ".with-media .nested { background: red; }"))))))
+                 ".with-media .nested { background: red; }")))))
+
+  (testing "CSS var declaration and usage"
+    (let [generated (-> (class-with-vars-factory$ "class-with-vars" [])
+                        :css
+                        (str/replace #"\s+" " "))]
+      (is (str/includes?
+            generated
+            (str ".class-with-vars {"
+                 " --my-var: 42pt;"
+                 " --spade-core-test--namespaced: blue;"
+                 " font-size: var(--my-var);"
+                 " background: var(--spade-core-test--namespaced);"
+                 " color: var(--my-var) !important;"
+                 " }"))))))
 
 
 (defattrs fixed-style-attrs []
-  {:color "blue"})
+  {:*my-var* "blue"
+   :color :*my-var*})
 
 (deftest defattrs-test
   (testing "Return map from defattrs"
     (is (= {:class "spade-core-test-fixed-style-attrs"}
-           (fixed-style-attrs)))))
+           (fixed-style-attrs))))
+
+  (testing "CSS var declaration and usage"
+    (let [generated (-> (fixed-style-attrs-factory$ "with-vars" [])
+                        :css
+                        (str/replace #"\s+" " "))]
+      (is (str/includes?
+            generated
+            (str ".with-vars {"
+                 " --my-var: blue;"
+                 " color: var(--my-var);"
+                 " }"))))))
 
 
 (defglobal global-1
-  [:body {:background "blue"}])
+  [":root" {:*background* "blue"}]
+  [:body {:background :*background*}])
 
 (defglobal global-2
   (at-media {:min-width "42px"}
@@ -63,7 +105,8 @@
 (deftest defglobal-test
   (testing "Declare const var with style from global"
     (is (string? global-1))
-    (is (= "body {\n  background: blue;\n}"
+    (is (= (str ":root {\n  --background: blue;\n}\n\n"
+                "body {\n  background: var(--background);\n}")
            global-1)))
 
   (testing "Support at-media automatically"
@@ -76,7 +119,8 @@
   [:from {:opacity 0}])
 
 (defkeyframes parameterized-key-frames [from]
-  [:from {:opacity from}])
+  [:from {::*from* from
+          :opacity ::*from*}])
 
 (deftest defkeyframes-test
   (testing "Return keyframes name from defkeyframes"
@@ -87,7 +131,19 @@
   (testing "Return dynamic keyframes name from parameterized defkeyframes"
     (is (fn? key-frames))
     (is (= (str "spade-core-test-parameterized-key-frames_" (hash [0]))
-           (parameterized-key-frames 0)))))
+           (parameterized-key-frames 0))))
+
+  (testing "CSS var declaration and usage"
+    (let [generated (-> (parameterized-key-frames-factory$
+                          "with-vars" [42] 42)
+                        :css
+                        (str/replace #"\s+" " "))]
+      (is (str/includes?
+            generated
+            (str "from {"
+                 " --spade-core-test--from: 42;"
+                 " opacity: var(--spade-core-test--from);"
+                 " }"))))))
 
 (defclass composed [color]
   ^{:key color}