docs(website): add template system documentation page

Author: rafaeltonholo

svg-to-compose-gradle-plugin/src/main/kotlin/dev/tonholo/s2c/gradle/tasks/ParseSvgToComposeIconTask.kt

@@ -316,7 +316,7 @@ internal abstract class ParseSvgToComposeIconTask @Inject constructor(private va
             makeInternal.set(iconConfiguration.iconVisibility.get() == IconVisibility.Internal)
             excludePattern.set(iconConfiguration.exclude.orNull?.pattern)
             kmpPreview.set(isKmp)
-            templateFilePath.set(iconConfiguration.templateFile.orNull?.asFile?.absolutePath)
+            templateFilePath.set(iconConfiguration.templateFile.orNull)
             resultFilePath.set(resultFile.absolutePath)
             this.bridgeToken.set(bridgeToken)
             tempDirPath.set(temporaryDir.resolve("worker-${path.name.hashCode()}").absolutePath)

svg-to-compose-gradle-plugin/src/main/kotlin/dev/tonholo/s2c/gradle/tasks/worker/IconParsingParameters.kt

@@ -1,5 +1,6 @@
 package dev.tonholo.s2c.gradle.tasks.worker
 
+import org.gradle.api.file.RegularFileProperty
 import org.gradle.api.provider.Property
 import org.gradle.workers.WorkParameters
 
@@ -24,7 +25,7 @@ internal interface IconParsingParameters : WorkParameters {
     val kmpPreview: Property<Boolean>
     val recursive: Property<Boolean>
     val maxDepth: Property<Int>
-    val templateFilePath: Property<String>
+    val templateFilePath: RegularFileProperty
     val resultFilePath: Property<String>
     val bridgeToken: Property<String>
 }

svg-to-compose-gradle-plugin/src/main/kotlin/dev/tonholo/s2c/gradle/tasks/worker/IconParsingWorkAction.kt

@@ -5,6 +5,7 @@ import dev.tonholo.s2c.error.ParserException
 import dev.tonholo.s2c.gradle.internal.service.S2cWorkerBridge
 import dev.tonholo.s2c.parser.ParserConfig
 import dev.tonholo.s2c.parser.config.TemplateConfig
+import okio.Path.Companion.toOkioPath
 import okio.Path.Companion.toPath
 import org.gradle.workers.WorkAction
 import java.util.UUID
@@ -80,8 +81,8 @@ internal abstract class IconParsingWorkAction : WorkAction<IconParsingParameters
         silent = true,
         keepTempFolder = true,
         template = TemplateConfig(
-            configPath = templateFilePath.orNull?.toPath(),
-            noDiscovery = templateFilePath.orNull == null,
+            configPath = templateFilePath.orNull?.asFile?.toOkioPath(),
+            noDiscovery = !templateFilePath.isPresent,
         ),
     )
 }

svg-to-compose/src/commonMain/kotlin/dev/tonholo/s2c/Converter.kt

@@ -8,6 +8,7 @@ import dev.tonholo.s2c.ConversionStep.Parsing
 import dev.tonholo.s2c.domain.FileType
 import dev.tonholo.s2c.domain.IconFileContents
 import dev.tonholo.s2c.emitter.CodeEmitterFactory
+import dev.tonholo.s2c.emitter.template.config.TemplateEmitterConfig
 import dev.tonholo.s2c.optimizer.ContentOptimizer
 import dev.tonholo.s2c.parser.ContentParser
 import dev.tonholo.s2c.parser.ParserConfig
@@ -27,7 +28,7 @@ import kotlinx.coroutines.flow.flow
  * allowing consumers to track progress and handle intermediate states such as optimization,
  * parsing, code generation, completion, or errors.
  */
-fun interface Converter {
+interface Converter {
     /**
      * Converts vector icon content into Kotlin Compose code by processing it through optimization,
      * parsing, and code generation stages.
@@ -51,6 +52,7 @@ fun interface Converter {
      * @param config the parser configuration containing package name, theme, and other generation options
      * @param fileType the type of vector file being converted (defaults to SVG)
      * @param optimizer optional optimizer to preprocess the content before parsing
+     * @param templateEmitterConfig optional template configuration for custom code generation output
      * @return a Flow of ConversionStep instances representing the progress and result of the conversion
      */
     fun convert(
@@ -59,6 +61,7 @@ fun interface Converter {
         config: ParserConfig,
         fileType: FileType,
         optimizer: ContentOptimizer?,
+        templateEmitterConfig: TemplateEmitterConfig? = null,
     ): Flow<ConversionStep>
 }
 
@@ -73,6 +76,7 @@ class DefaultConverter(
         config: ParserConfig,
         fileType: FileType,
         optimizer: ContentOptimizer?,
+        templateEmitterConfig: TemplateEmitterConfig?,
     ): Flow<ConversionStep> = flow {
         try {
             val optimizedContent = if (optimizer != null) {
@@ -88,7 +92,7 @@ class DefaultConverter(
             val iconContents = parser.parse(optimizedContent, iconName, config)
 
             emit(Generating("Generating Kotlin code..."))
-            val emitter = codeEmitterFactory.create()
+            val emitter = codeEmitterFactory.create(templateEmitterConfig = templateEmitterConfig)
             val kotlinCode = emitter.emit(iconContents)
 
             emit(

svg-to-compose/src/commonMain/kotlin/dev/tonholo/s2c/emitter/NodeChunker.kt

@@ -15,7 +15,10 @@ import kotlin.math.roundToInt
  * @property chunkFunctions The chunk function nodes extracted from [nodes],
  *   or `null` when no chunking was needed.
  */
-data class ChunkResult(val nodes: List<ImageVectorNode>, val chunkFunctions: List<ImageVectorNode.ChunkFunction>?)
+internal data class ChunkResult(
+    val nodes: List<ImageVectorNode>,
+    val chunkFunctions: List<ImageVectorNode.ChunkFunction>?,
+)
 
 /**
  * Splits an icon's nodes into [ImageVectorNode.ChunkFunction]s when the

svg-to-compose/src/commonMain/kotlin/dev/tonholo/s2c/emitter/imagevector/ImageVectorEmitter.kt

@@ -100,7 +100,7 @@ class ImageVectorEmitter(private val logger: Logger, private val formatConfig: F
     }
 
     private fun buildIconPropertyName(contents: IconFileContents): String = when {
-        contents.receiverType?.isNotEmpty() == true -> {
+        !contents.receiverType.isNullOrEmpty() -> {
             val receiverType = contents.receiverType.removeSuffix(".")
             "$receiverType.${contents.iconName.pascalCase()}"
         }
@@ -173,4 +173,19 @@ class ImageVectorEmitter(private val logger: Logger, private val formatConfig: F
             appendLine(preview.trimMargin())
         }
     }
+
+    internal companion object {
+        /** Imports required by the default preview snippet. */
+        val PREVIEW_IMPORTS: Set<String> = setOf(
+            "androidx.compose.foundation.Image",
+            "androidx.compose.foundation.layout.Arrangement",
+            "androidx.compose.foundation.layout.Column",
+            "androidx.compose.foundation.layout.width",
+            "androidx.compose.foundation.layout.height",
+            "androidx.compose.ui.Alignment",
+            "androidx.compose.ui.Modifier",
+            "androidx.compose.ui.tooling.preview.Preview",
+            "androidx.compose.runtime.Composable",
+        )
+    }
 }

svg-to-compose/src/commonMain/kotlin/dev/tonholo/s2c/emitter/template/TemplateContext.kt

@@ -33,7 +33,7 @@ internal class TemplateContext(
     private val _collectedImports: MutableSet<String> = initialImports.toMutableSet()
 
     /** Immutable snapshot of the accumulated imports. */
-    val collectedImports: Set<String> get() = _collectedImports
+    val collectedImports: Set<String> get() = _collectedImports.toSet()
 
     /** Registers a single import path. */
     fun addImport(importPath: String) {
@@ -69,7 +69,7 @@ internal class TemplateContext(
         fun forIcon(contents: IconFileContents, config: TemplateEmitterConfig, iconBody: String): TemplateContext {
             val receiverName = config.definitions.receiver?.name
             val iconPropertyName = when {
-                contents.receiverType?.isNotEmpty() == true -> {
+                !contents.receiverType.isNullOrEmpty() -> {
                     val receiverType = contents.receiverType.removeSuffix(".")
                     "$receiverType.${contents.iconName.pascalCase()}"
                 }

svg-to-compose/src/commonMain/kotlin/dev/tonholo/s2c/emitter/template/TemplateEmitter.kt

@@ -125,19 +125,7 @@ internal class TemplateEmitter(
     }
 
     private companion object {
-        // These mirror the imports that ImageVectorEmitter adds for its preview
-        // snippet. If the default preview format changes, this set must be updated.
-        val PREVIEW_IMPORTS = setOf(
-            "androidx.compose.foundation.Image",
-            "androidx.compose.foundation.layout.Arrangement",
-            "androidx.compose.foundation.layout.Column",
-            "androidx.compose.foundation.layout.width",
-            "androidx.compose.foundation.layout.height",
-            "androidx.compose.ui.Alignment",
-            "androidx.compose.ui.Modifier",
-            "androidx.compose.ui.tooling.preview.Preview",
-            "androidx.compose.runtime.Composable",
-        )
+        val PREVIEW_IMPORTS: Set<String> = ImageVectorEmitter.PREVIEW_IMPORTS
     }
 
     private fun buildChunkFunctionsContent(chunkFunctions: List<ImageVectorNode.ChunkFunction>?): String {

svg-to-compose/src/commonTest/kotlin/dev/tonholo/s2c/emitter/NodeChunkerTest.kt

@@ -61,7 +61,8 @@ class NodeChunkerTest {
         val icon = createIcon(nodeCount = NODE_COUNT_ABOVE_THRESHOLD)
         val result = chunker.chunkIfNeeded(icon, defaultNameResolver)
 
-        val allChunkedNodes = result.chunkFunctions!!.flatMap { it.nodes }
+        val chunkFunctions = requireNotNull(result.chunkFunctions) { "chunkFunctions should be present" }
+        val allChunkedNodes = chunkFunctions.flatMap { it.nodes }
         assertEquals(icon.nodes.size, allChunkedNodes.size)
     }
 
@@ -74,7 +75,8 @@ class NodeChunkerTest {
 
         val result = chunker.chunkIfNeeded(icon, nameResolver)
 
-        val names = result.chunkFunctions!!.map { it.functionName }
+        val chunkFunctions = requireNotNull(result.chunkFunctions) { "chunkFunctions should be present" }
+        val names = chunkFunctions.map { it.functionName }
         names.forEachIndexed { idx, name ->
             assertEquals("customChunk${idx + 1}", name)
         }

svg-to-compose/src/commonTest/kotlin/dev/tonholo/s2c/emitter/template/TemplateEmitterTest.kt

@@ -286,10 +286,10 @@ class TemplateEmitterTest {
             definitions = config.definitions.imports,
             fragments = config.fragments,
         )
-        val result = PlaceholderResolver.resolve(
-            config.fragments["chunk_function_name"]!!,
-            context,
-        )
+        val fragment = requireNotNull(config.fragments["chunk_function_name"]) {
+            "chunk_function_name fragment must be present in config"
+        }
+        val result = PlaceholderResolver.resolve(fragment, context)
         assertEquals("testIconPart3", result)
     }