feat(template): add customizable code generation template system (#249)

* docs(templates): document template system and color mapping in ARCHITECTURE.md

* feat(template): add core template engine with lexer, resolver, and config parser

* feat(gradle-plugin): add templateFile option and functional tests

* chore: bump version and add template integrity check CI

* docs: add template system to CLI, Gradle plugin READMEs, and help output

* feat(playground): add template editor with validation, autocomplete, and persistence

* docs(website): add template system documentation page

* chore: remove conditional check for nodeJS environment setup in pull request workflow

* fix(ci): use explicit bash invocation and numeric comparison in template script

- Invoke template-script.sh via `bash` for portability when executable permissions aren't preserved.
- Use `-eq` instead of `==` for numeric array-length comparison.

* fix(template): consume entire malformed placeholder span as literal in lexer

When tryParsePlaceholder returns null for a `${...}` sequence, consume the entire span up to the closing `}` as literal text instead of just the `$` character. This prevents inner content from being re-interpreted as nested placeholders.

* fix(template): fall through to default preview when template key is null

- When [templates.preview] exists but the template key is null (e.g. empty section), fall through to default preview behavior instead of suppressing preview generation.
- Refactor buildPreview to use a when expression.

* fix(template): use template-aware emission for group fallback and chunk functions

- Extract emitGroupHeader from ImageVectorNodeEmitter so the fallback path in TemplateNodeEmitter still recurses children template-aware.
- Make splitTopLevelParams and findMatchingCloseParen respect string literals, angle brackets, braces, and brackets via a shared NestingTracker.

* fix(template): include fileHeader in definition key validation

Add config.templates.fileHeader to allTemplateTexts so that ${def:...} references in file headers are validated against defined import keys.

* docs: fix templateFile() behavior inconsistencies and chunk:index comment

- Align docs, website, and playground on consistent templateFile() behavior: omitting it in Gradle disables auto-discovery; use common config for inheritance.
- Fix method signature to templateFile(path: RegularFile).
Correct chunk:index comment from 0-based to 1-based.

* fix(template): enhance flag parsing and default differ handling in script

* refactor(ci): use flag-based args and add --default-differ to integrity scripts

Refactor both integrity check scripts to parse flags via a while/case
loop instead of positional arguments. Add --default-differ flag to skip
delta and use plain diff for machine-readable output.

* feat(template): add emitClipPathData function and integrate clip path handling in group parameters

* feat(template): add iconGroup function for enhanced group handling in ImageVector

* feat(template): replace group with iconGroup for improved clip path handling in SVG templates

* fix: bad rebase state

* feat(navigation): implement WebRoute structure for improved routing management

* feat(website): add CodeAwareSpanText component with callout variants

Replaces RichSpanText with a more descriptive name. Renders text that
may contain inline code segments using backtick syntax. Adds typed
CssStyleVariant support with per-CalloutVariant variants (Tip, Warning,
Important) for proper InlineCode colour theming inside callouts.

* refactor(website): convert docs to CodeAwareSpanText and fix Canadian English

Replace Span { Text() InlineCode() } patterns across all five docs
files with CodeAwareSpanText using backtick syntax. Callout blocks
now use typed variants instead of manually resolving InlineCodeVars.

Fix US English spellings in copy text: color to colour in section
titles, descriptions, and variable labels. Code identifiers (Color,
SolidColor, color_mapping) are left unchanged.

* docs(website): add KDoc to WebRoute and CodeAwareSpanText

Add KDoc to WebRoute class, its properties, and companion entries.
Add KDoc to CodeAwareSpanText composable, ComponentKind marker, and
all three callout style variants.

* fix(website): correct CodeAwareSpanText parsing when text starts with backtick

The previous logic dropped leading empty parts and reset the index,
which inverted the even/odd check and rendered code as text and vice
versa. Now iterates all parts using the original split index and
skips empty segments instead.

* fix(website): replace "elision/elides" with "trimming/trims" in copy and tests

Update ToC entry in Templates.kt and test names in
PlaceholderResolverTest.kt to use "trim" instead of "elide".

* refactor(website): convert remaining InlineCode patterns to CodeAwareSpanText

Convert TemplateSystemCallout in CliDocsContent and --max-workers Li
in GradlePluginDocsContent to use CodeAwareSpanText with backtick
syntax. Remove now-unused resolveInlineCodeColors from DocsStyles.

* fix(website): use Canadian English spelling for "customise/customisation"

Replace all US English "customize/customization/customizing" with
"customise/customisation/customising" in website copy across docs,
playground, and landing page.

* refactor(website): replace SpanText with CodeAwareSpanText and update filename casing in documentation

* fix: address code review findings across script, tests, and website

- fix(ci): clean up cli-integrity-check script parameter parsing, remove
  vestigial $2 assignment, add --extension required validation, fix
  suffix not being set to "optimized" when --optimize flag is passed,
  use POSIX = for string comparisons and -eq for numeric comparisons
- fix(gradle-plugin): replace auto-bootstrap with assertion failure for
  missing template golden files in functional tests
- fix(website): remove trailing spaces after line-continuation
  backslashes in FaqContent shell code block
- fix(website): expand icon namespace scope to include file_header and
  preview contexts in TemplateDocsContent
- fix(website): remove editorial inline comment from null-handling
  code example in TemplateDocsContent
- fix(website): correct contradictory auto-discovery guidance in
  TemplateDocsContent - omitting templateFile() inherits common config
- refactor(website): use lazy delegate for WebRoute.all property

* feat: integrate template configuration support in Processor

* feat: add template option for customizable Kotlin code generation

* feat: add option to disable template auto-discovery in Kotlin code generation

Author: rafaeltonholo

.github/actions/cli-integrity-check/action.yml

@@ -11,8 +11,8 @@ runs:
     - name: Verify ${{ inputs.type }} conversion without optimization
       shell: bash
       run: |
-        ./.github/actions/cli-integrity-check/script.sh . ${{ inputs.type }}
+        ./.github/actions/cli-integrity-check/script.sh . --extension ${{ inputs.type }}
     - name: Verify ${{ inputs.type }} conversion with optimization
       shell: bash
       run: |
-        ./.github/actions/cli-integrity-check/script.sh . ${{ inputs.type }} optimize
+        ./.github/actions/cli-integrity-check/script.sh . --extension ${{ inputs.type }} --optimize

.github/actions/cli-integrity-check/script.sh

@@ -1,30 +1,59 @@
 #!/bin/bash
-# Parse and validate required parameters
+# Parse and validate the required positional parameter
 root_directory="${1:?Error: Root directory must be the first parameter}"
-ext="${2:?Error: File extension must be the second parameter}"
+shift # consume root_directory, leaving only flags
 
-# Parse optimization and rebuild flags (rebuild can be $3 or $4)
+# Parse flags
 optimize="false"
 suffix="nonoptimized"
 rebuild=""
+use_default_differ="false"
+rebuild_applied="false"
+ext=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --extension)
+      ext="${2:?Error: --extension flag requires a value}"
+      shift 2
+      ;;
+    --optimize)
+      optimize="true"
+      suffix="optimized"
+      shift
+      ;;
+    --rebuild)
+      rebuild="--upgrade"
+      shift
+      ;;
+    --default-differ)
+      use_default_differ="true"
+      shift
+      ;;
+    *)
+      echo "Warning: unknown flag '$1'" >&2
+      shift
+      ;;
+  esac
+done
 
-if [ "$3" == "optimize" ]; then
-  optimize="true"
-  suffix="optimized"
-  [ "$4" == "--rebuild" ] && rebuild="--upgrade"
-elif [ "$3" == "--rebuild" ]; then
-  rebuild="--upgrade"
+if [ -z "$ext" ]; then
+  echo "Error: --extension flag is required" >&2
+  exit 1
 fi
 
 # Determine file type based on extension
-if [ "$ext" == "xml" ]; then
+if [ "$ext" = "xml" ]; then
   type="avg"
 else
   type="svg"
   ext="svg"
 fi
 
-rebuild_applied="false"
+differ="diff --strip-trailing-cr"
+if [ "$use_default_differ" = "false" ] && command -v delta &> /dev/null; then
+  differ="delta -s --paging=never"
+fi
 
 # Package must match exactly what the Gradle plugin functional tests use so
 # both tools validate against the same expected .kt files.
@@ -34,10 +63,10 @@ errors=()
 
 # Convert kebab-case or snake_case filename to PascalCase.
 to_pascal_case() {
-   echo "$1" | awk -F'[-_]' '{ for(i=1;i<=NF;i++) $i=toupper(substr($i,1,1)) substr($i,2); print }' OFS=''
- }
+  echo "$1" | awk -F'[-_]' '{ for(i=1;i<=NF;i++) $i=toupper(substr($i,1,1)) substr($i,2); print }' OFS=''
+}
 
-# Only process flat (non-directory) files in samples/{type}/ — subdirectories
+# Only process flat (non-directory) files in samples/{type}/ - subdirectories
 # such as gradient/, rects/, css/ etc. are intentionally excluded.
 for input in "$root_directory/samples/${type}"/*."${ext}"; do
   [ -f "$input" ] || continue
@@ -47,8 +76,8 @@ for input in "$root_directory/samples/${type}"/*."${ext}"; do
   icon_name=$(to_pascal_case "$stem")
   expected_file="$expected_dir/${icon_name}.${ext}.${suffix}.kt"
 
-  if [ "$optimize" == "true" ]; then
-    if [ "$type" == "svg" ]; then
+  if [ "$optimize" = "true" ]; then
+    if [ "$type" = "svg" ]; then
       echo "svgo version $(svgo --version)"
     else
       echo "avocado version $(avocado --version)"
@@ -64,7 +93,7 @@ for input in "$root_directory/samples/${type}"/*."${ext}"; do
   tmp_output="${tmp_dir}/${icon_name}.kt"
 
   rebuild_arg=""
-  if [ "$rebuild_applied" == "false" ]; then
+  if [ "$rebuild_applied" = "false" ]; then
     rebuild_arg="$rebuild"
   fi
 
@@ -96,7 +125,7 @@ for input in "$root_directory/samples/${type}"/*."${ext}"; do
   fi
 
   echo "Verifying $stem against expected file."
-  if ! diff --strip-trailing-cr "$tmp_output" "$expected_file"; then
+  if ! $differ "$tmp_output" "$expected_file"; then
     errors+=("$stem.$ext")
   else
     echo "✅ $stem.$ext pass"
@@ -106,7 +135,7 @@ done
 
 echo
 echo
-if [ "${#errors[@]}" == 0 ]; then
+if [ "${#errors[@]}" -eq 0 ]; then
   echo "✅ Integrity check pass"
   exit 0
 else

.github/actions/template-integrity-check/action.yml

@@ -0,0 +1,9 @@
+name: Template Integrity check
+description: Runs the CLI command checking if template-based output still works as intended
+runs:
+  using: composite
+  steps:
+    - name: Verify template conversion
+      shell: bash
+      run: |
+        bash ./.github/actions/template-integrity-check/script.sh .

.github/actions/template-integrity-check/script.sh

@@ -0,0 +1,137 @@
+#!/bin/bash
+root_directory=$1
+if [ "$root_directory" == "" ]; then
+  echo "The root directory must be the first parameter."
+  exit 1
+fi
+
+use_default_differ="false"
+rebuild=""
+
+shift # consume root_directory ($1), leaving only flags
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --rebuild)
+      rebuild="--upgrade"
+      shift
+      ;;
+    --default-differ)
+      use_default_differ="true"
+      shift
+      ;;
+    *)
+      echo "Warning: unknown flag '$1'" >&2
+      shift
+      ;;
+  esac
+done
+
+differ="diff --strip-trailing-cr"
+if [ "$use_default_differ" == "false" ] && command -v delta &> /dev/null; then
+  differ="delta -s --paging=never"
+fi
+rebuild_applied="false"
+
+template_file="$root_directory/playground/s2c.template.toml"
+expected_dir="$root_directory/integrity-check/expected/template"
+errors=()
+
+# Convert kebab-case or snake_case filename to PascalCase.
+to_pascal_case() {
+   echo "$1" | awk -F'[-_]' '{ for(i=1;i<=NF;i++) $i=toupper(substr($i,1,1)) substr($i,2); print }' OFS=''
+ }
+
+# Hardcoded list of input files covering all 5 categories (simple, groups,
+# chunks, gradients, masks) across SVG and AVG.
+svg_files=(
+  "samples/svg/attention-filled.svg"
+  "samples/svg/android.svg"
+  "samples/svg/brasil.svg"
+  "samples/svg/gradient/linear-gradient01.svg"
+  "samples/svg/mask/mask-with-group.svg"
+)
+avg_files=(
+  "samples/avg/shield-halved-solid.xml"
+  "samples/avg/android.xml"
+  "samples/avg/gradient/stroke_gradient.xml"
+)
+
+process_file() {
+  local input="$1"
+  local type="$2"
+  local ext="$3"
+  local package="dev.tonholo.s2c.integrity.icon.${type}"
+
+  basename="${input##*/}"
+  stem="${basename%.*}"
+  icon_name=$(to_pascal_case "$stem")
+  expected_file="$expected_dir/${icon_name}.${ext}.template.kt"
+
+  s2c_version=$(command "$root_directory/s2c" --version)
+  echo "Parsing $stem to Jetpack Compose Icon (template) using $s2c_version"
+
+  tmp_dir="$(mktemp -d)"
+  tmp_output="${tmp_dir}/${icon_name}.kt"
+
+  rebuild_arg=""
+  if [ "$rebuild_applied" == "false" ]; then
+    rebuild_arg="$rebuild"
+  fi
+
+  if ! command "$root_directory/s2c" \
+        -o "$tmp_output" \
+        -p "$package" \
+        --theme "" \
+        --no-preview \
+        --template "$template_file" \
+        ${rebuild_arg:+"$rebuild_arg"} \
+        "$root_directory/$input"; then
+    echo "Failed to execute CLI template integrity check for $stem."
+    rm -rf "$tmp_dir"
+    errors+=("$stem.$ext")
+    return
+  fi
+
+  if [ -n "$rebuild" ]; then
+    rebuild_applied="true"
+  fi
+
+  if [ ! -f "$expected_file" ]; then
+    mkdir -p "$expected_dir"
+    cp "$tmp_output" "$expected_file"
+    echo "BOOTSTRAP: Wrote expected file ${icon_name}.${ext}.template.kt"
+    rm -rf "$tmp_dir"
+    return
+  fi
+
+  echo "Verifying $stem (template) against expected file."
+  if ! $differ "$tmp_output" "$expected_file"; then
+    errors+=("$stem.$ext")
+  else
+    echo "✅ $stem.$ext (template) pass"
+  fi
+  rm -rf "$tmp_dir"
+}
+
+for input in "${svg_files[@]}"; do
+  process_file "$input" "svg" "svg"
+done
+
+for input in "${avg_files[@]}"; do
+  process_file "$input" "avg" "xml"
+done
+
+echo
+echo
+if [ "${#errors[@]}" -eq 0 ]; then
+  echo "✅ Template integrity check pass"
+  exit 0
+else
+  echo "❌ Template integrity check failed"
+  echo
+  echo "Failed files:"
+  for f in "${errors[@]}"; do
+    echo "    - $f"
+  done
+  exit 1
+fi