Better (and better documented) Tailwind v3 support

Author: plexus

CHANGELOG.md

@@ -2,9 +2,8 @@
 
 ## Added
 
-## Fixed
-
-## Changed
+- Added a `:tw-version` flag for the preflight, similar to `set-tokens!`
+- Document how to opt-in to Tailwind v3 
 
 # 0.8.84 (2023-02-28 / 8d54daa)
 
@@ -67,4 +66,4 @@
 
 ## Added
 
-- Initial implementation
+- Initial implementation

README.md

@@ -82,7 +82,9 @@ so it gets served as any other plain CSS file.
 
 If you prefer to use [Girouette](https://github.com/green-coder/girouette)
 (Tailwind) utility classes (a.k.a. tokens), then you can do that as well, or you
-can mix and match.
+can mix and match. Note that for compatibility reasons Ornament will continue to
+default to Tailwind v2 components, but you can opt-in to v3, see the section
+below.
 
 ```clojure
 (o/defstyled freebies-link :a
@@ -113,6 +115,32 @@ to explain Ornament's philosophy on how to deal with CSS, to give you accurate
 expectations of how it will behave. This is especially relevant for
 ClojureScript projects.
 
+## Choosing your Tailwind version
+
+We rely on [Girouette](https://github.com/green-coder/girouette) to provide us
+with a re-implementation in Clojure of Tailwinds components, classes, and
+styles. At time of writing Girouette is compatible with either Tailwind 2.0.3,
+or 3.0.24.
+
+To use Tailwind 3 tokens (classes), pass an extra `:tw-version 3` option to
+`set-tokens!`
+
+```clj
+(o/set-tokens! {:tw-version 3})
+```
+
+See "Customizing Girouette" below for more info on `set-tokens`, or check the
+docstring.
+
+The `girouette.tw.preflight` namespace provides the Tailwind preflight (reset)
+stylesheet for either v2 or v3. If you are using `o/defined-styles` you can also
+opt to have it automatically prepended. This function also accepts a similar
+`:tw-version` argument (`2` or `3)
+
+```clj
+(o/defined-styles {:preflight? true :tw-version 3})
+```
+
 ## Choosing a Hiccup Implementation
 
 Representing HTML using nested Clojure vectors is an approach that was
@@ -754,7 +782,8 @@ style declarations.
 - `:components`: sequence of Girouette components, each a map with `:id`
   (keyword), `:rules` (string, instaparse, can be omitted), and `:garden` (map,
   or function taking instaparse results and returning Garden map)
-
+- `:tw-version`: which Girouette defaults to use, either based on Tailwind
+  v2, or v3. Valid values: `2`, `3`. Defaults to v2.
 
 ```clojure
 (o/set-tokens! {:colors {:primary "001122"}
@@ -818,7 +847,7 @@ The end result is that we can do something like this:
 
 And get a bullet list which uses bear emojis for the bullets.
 
-`set-tokens` will add the new colors, fonts, and components to the defaults that
+`set-tokens!` will add the new colors, fonts, and components to the defaults that
 Girouette provides. You can change that by adding a `^:replace` tag (this uses
 meta-merge). e.g. `{:colors ^:replace {...}}`) 
 

bb.edn

@@ -1,3 +1,3 @@
 {:deps
  {lambdaisland/open-source {:git/url "https://github.com/lambdaisland/open-source"
-                            :git/sha "5ae5327ff37b45228a40a3981fa83ad151bedf3c"}}}
+                            :git/sha "99b33741ea499e1c58e5ab6c2b785ba18eca84d2"}}}

deps.edn

@@ -14,15 +14,15 @@
 
   :byo
   {:extra-deps {hawk/hawk {:mvn/version "0.2.11"}
-                com.lambdaisland/glogi {:mvn/version "1.2.164"}
+                com.lambdaisland/glogi {:mvn/version "1.3.169"}
                 io.pedestal/pedestal.log {:mvn/version "0.5.10"}}}
 
   :test
   {:extra-paths ["test"]
    :extra-deps  {lambdaisland/kaocha {:mvn/version "RELEASE"}
                  lambdaisland/kaocha-cljs {:mvn/version "RELEASE"}
                  org.clojure/clojurescript {:mvn/version "RELEASE"}
-                 com.lambdaisland/glogi {:mvn/version "1.2.164"}
+                 com.lambdaisland/glogi {:mvn/version "1.3.169"}
                  ;; for lambdaisland.hiccup and lambdaisland.thicc, used in testing
                  lambdaisland/webstuff {:git/url "https://github.com/lambdaisland/webstuff"
                                         :git/sha "9284216340a8107dea553f20bc247787f4f2efa9"

src/lambdaisland/ornament.cljc

@@ -76,6 +76,8 @@
         :colors     girouette-color/tw-v3-unified-colors-extended
         :fonts      girouette-typography/tw-v2-font-family-map})
 
+     (def default-tokens default-tokens-v2)
+
      (defn set-tokens!
        "Set \"design tokens\": colors, fonts, and components
 
@@ -88,6 +90,8 @@
           `:id` (keyword), `:rules` (string, instaparse, can be omitted), and
           `:garden` (map, or function taking instaparse results and returning Garden
           map)
+        - `:tw-version`: which Girouette defaults to use, either based on Tailwind
+          v2, or v3. Valid values: 2, 3.
 
         If `:rules` is omitted we assume this is a static token, and we'll
         generate a rule of the form `token-id = <'token-id'>`.
@@ -100,8 +104,11 @@
         multiple tokens/maps/stylesUse `[:&]` for returning multiple
         tokens/maps/styles.
 
-        By default these are added to the Girouette defaults, use meta-merge
-        annotations (e.g. `{:colors ^:replace {...}}`) to change that behaviour."
+        By default these are added to the Girouette defaults, which are in terms
+        based on the Tailwind defaults. We still default to v2 (to avoid breaking
+        changes), but you can opt-in to Tailwind v3 by adding `:tw-version 3`. Use
+        meta-merge annotations (e.g. `{:colors ^:replace {...}}`) to change that
+        behaviour."
        [{:keys [components colors fonts tw-version]
          :or {tw-version 2}}]
        (let [{:keys [components colors fonts]}
@@ -638,8 +645,15 @@
        (into [(str "." css-class)] (process-rules rules)))))
 
 #?(:clj
-   (defn defined-styles [& [{:keys [preflight?]
-                             :or {preflight? false}}]]
+   (defn defined-styles
+     "Collect all styles that have been defined, and compile them down to CSS. Use
+  this to either spit out or inline a stylesheet with all your Ornament styles.
+  Optionally the Tailwind preflight (reset) stylesheet can be prepended using
+  `:preflight? true`. This defaults to Tailwind v2 (as provided by Girouette).
+  Version 3 is available with `:tw-version 3`"
+     [& [{:keys [preflight? tw-version]
+          :or {preflight? false
+               tw-version 2}}]]
      ;; Use registry, instead of inspecting metadata, for better cljs-only
      ;; support
      (let [registry-css (->> @registry
@@ -648,7 +662,9 @@
                              (map (fn [{:keys [var tag rules classname]}]
                                     (css (styled var classname tag rules nil)))))]
        (cond->> registry-css
-         preflight? (into [(gc/compile-css girouette-preflight/preflight-v2_0_3)])
+         preflight? (into [(gc/compile-css (case tw-version
+                                             2 girouette-preflight/preflight-v2_0_3
+                                             3 girouette-preflight/preflight-v3_0_24))])
          :always (str/join "\n")))))
 
 #?(:clj