Merge pull request #146 from iamgio/css-function

feat(stdlib): add `.css` and `.cssproperties`

Author: iamgio

quarkdown-core/build.gradle.kts

@@ -12,7 +12,7 @@ dependencies {
     implementation(kotlin("reflect"))
     implementation("com.github.h0tk3y.betterParse:better-parse:0.4.4")
     implementation("org.apache.logging.log4j:log4j-core:2.24.3")
-    implementation("org.apache.commons:commons-text:1.13.0")
+    implementation("org.apache.commons:commons-text:1.13.1")
     implementation("com.github.ajalt.colormath:colormath:3.6.1")
     implementation("com.github.fracpete:romannumerals4j:0.0.1")
     implementation("org.jbibtex:jbibtex:1.0.20")

quarkdown-html/build.gradle.kts

@@ -10,7 +10,7 @@ dependencies {
     implementation(project(":quarkdown-core"))
     implementation(project(":quarkdown-interaction"))
     implementation(project(":quarkdown-server"))
-    implementation("org.apache.commons:commons-text:1.13.0")
+    implementation("org.apache.commons:commons-text:1.13.1")
 }
 
 tasks.compileSass {

quarkdown-stdlib/src/main/kotlin/com/quarkdown/stdlib/Injection.kt

@@ -4,6 +4,8 @@ import com.quarkdown.core.ast.base.block.Html
 import com.quarkdown.core.function.library.loader.Module
 import com.quarkdown.core.function.library.loader.moduleOf
 import com.quarkdown.core.function.reflect.annotation.LikelyBody
+import com.quarkdown.core.function.reflect.annotation.Name
+import com.quarkdown.core.function.value.Value
 import com.quarkdown.core.function.value.wrappedAsValue
 
 /**
@@ -13,14 +15,76 @@ import com.quarkdown.core.function.value.wrappedAsValue
 val Injection: Module =
     moduleOf(
         ::html,
+        ::css,
+        ::cssProperties,
     )
 
 /**
- * Creates an HTML element, which is rendered as-is without any additional processing or escaping.
+ * Creates an HTML element, which is rendered as-is without any additional processing or escaping,
+ * as long as the rendering target supports HTML.
  * @param content raw HTML content to inject
  * @return a new [Html] node
  * @wiki HTML
  */
 fun html(
     @LikelyBody content: String,
 ) = Html(content).wrappedAsValue()
+
+/**
+ * Creates a `<style>` HTML element with the provided CSS content.
+ * The content is wrapped in a `<style>` tag and rendered as-is,
+ * without any additional processing or escaping, as long as the rendering target supports HTML.
+ *
+ * Example:
+ * ```
+ * .css
+ *   body {
+ *     background-color: green !important;
+ *   }
+ * ```
+ *
+ * @param content raw CSS content to inject
+ * @return a new [Html] node representing the style element
+ * @see [cssProperties] for a more structured way to override CSS properties.
+ * @wiki CSS
+ */
+fun css(
+    @LikelyBody content: String,
+) = Html("<style data-hidden=\"\">$content</style>").wrappedAsValue()
+
+private const val CSS_ROOT_SELECTOR = ":root"
+private const val CSS_PROPERTY_PREFIX = "--qd-"
+
+/**
+ * Overrides the value of Quarkdown CSS properties.
+ * Each entry corresponds to a Quarkdown CSS property name and its value.
+ * The names will be prefixed with `--qd-` to match the Quarkdown CSS variable naming convention.
+ *
+ * For example:
+ * ```
+ * .cssproperties
+ *   - background-color: green
+ *   - main-font-size: 20px
+ * ```
+ *
+ * For a complete list of properties, see the [global theme](https://github.com/iamgio/quarkdown/blob/main/quarkdown-html/src/main/resources/render/theme/global.scss).
+ * Unknown properties will be ignored.
+ *
+ * The content is wrapped in a `<style>` tag and rendered as-is,
+ * without any additional processing or escaping, as long as the rendering target supports HTML.
+ * @param properties a map of CSS property names and their values
+ * @return a new [Html] node representing the style element
+ * @wiki CSS
+ */
+@Name("cssproperties")
+fun cssProperties(properties: Map<String, Value<*>>) =
+    css(
+        buildString {
+            append(CSS_ROOT_SELECTOR)
+            append(" { ")
+            properties.forEach { (name, value) ->
+                append("$CSS_PROPERTY_PREFIX$name: ${value.unwrappedValue} !important; ")
+            }
+            append("}")
+        },
+    )

quarkdown-test/src/test/kotlin/com/quarkdown/test/InjectionTest.kt

@@ -0,0 +1,89 @@
+package com.quarkdown.test
+
+import com.quarkdown.test.util.execute
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+/**
+ * Tests for language injection functions.
+ */
+class InjectionTest {
+    @Test
+    fun html() {
+        execute(".html\n\tHello, <b>world</b>!") {
+            assertEquals("Hello, <b>world</b>!", it)
+        }
+    }
+
+    @Test
+    fun `block html`() {
+        execute(
+            """
+            Hello
+            
+            .html
+                <p><sup>World</sup></p>
+            """.trimIndent(),
+        ) {
+            assertEquals(
+                "<p>Hello</p><p><sup>World</sup></p>",
+                it,
+            )
+        }
+    }
+
+    @Test
+    fun `inline html`() {
+        execute("Hello, .html {<sup>World</sup>}") {
+            assertEquals(
+                "<p>Hello, <sup>World</sup></p>",
+                it,
+            )
+        }
+    }
+
+    @Test
+    fun css() {
+        execute(
+            """
+            .css
+                .class {
+                    background: red;
+                }
+            """.trimIndent(),
+        ) {
+            assertEquals(
+                "<style data-hidden=\"\">.class {\n    background: red;\n}</style>",
+                it,
+            )
+        }
+    }
+
+    @Test
+    fun `css from file`() {
+        execute(".css {.read {css/style.css}}") {
+            assertEquals(
+                "<style data-hidden=\"\">body {\n    background-color: orange;\n}</style>",
+                it,
+            )
+        }
+    }
+
+    @Test
+    fun `css properties`() {
+        execute(
+            """
+            .cssproperties
+                - background-color: blue
+                - main-font-size: 16px
+            """.trimIndent(),
+        ) {
+            assertEquals(
+                "<style data-hidden=\"\">" +
+                    ":root { --qd-background-color: blue !important; --qd-main-font-size: 16px !important; }" +
+                    "</style>",
+                it,
+            )
+        }
+    }
+}

quarkdown-test/src/test/kotlin/com/quarkdown/test/NodesTest.kt

@@ -310,31 +310,4 @@ class NodesTest {
             )
         }
     }
-
-    @Test
-    fun `block html`() {
-        execute(
-            """
-            Hello
-            
-            .html
-                <p><sup>World</sup></p>
-            """.trimIndent(),
-        ) {
-            assertEquals(
-                "<p>Hello</p><p><sup>World</sup></p>",
-                it,
-            )
-        }
-    }
-
-    @Test
-    fun `inline html`() {
-        execute("Hello, .html {<sup>World</sup>}") {
-            assertEquals(
-                "<p>Hello, <sup>World</sup></p>",
-                it,
-            )
-        }
-    }
 }

quarkdown-test/src/test/resources/data/css/style.css

@@ -0,0 +1,3 @@
+body {
+    background-color: orange;
+}