feat(fields): add user-facing 'description' of special fields

This provides an explanation of all Special Fields
 to the user in the 'Insert field' dialog

This also produces contextual help for all fields
based on the context of the selected card/note (if any)

Author: david-allison

AnkiDroid/src/main/java/com/ichi2/anki/CardTemplateEditor.kt

@@ -536,6 +536,9 @@ open class CardTemplateEditor :
         private val cardIndex
             get() = requireArguments().getInt(CARD_INDEX)
 
+        private val templateName
+            get() = tempModel.notetype.templates[cardIndex].name
+
         val insertFieldRequestKey
             get() = "request_field_insert_$cardIndex"
 
@@ -767,17 +770,40 @@ open class CardTemplateEditor :
             "the kotlin migration made this method crash due to a recursive call when the dialog would return its data",
         )
         fun showInsertFieldDialog() {
-            templateEditor.fieldNames?.let { fieldNames ->
+            launchCatchingTask {
+                val fieldNames = templateEditor.fieldNames ?: return@launchCatchingTask
+
                 val side =
                     when (currentEditTab) {
                         EditTab.FRONT -> SingleCardSide.FRONT
                         EditTab.BACK -> SingleCardSide.BACK
                         else -> SingleCardSide.FRONT
                     }
+
+                val noteId = if (templateEditor.noteId > 0) templateEditor.noteId else null
+
+                // deletions change ordinals
+                val ord =
+                    if (tempModel.templateChanges.any {
+                            it.type == CardTemplateNotetype.ChangeType.DELETE
+                        }
+                    ) {
+                        null
+                    } else {
+                        templateEditor.ord
+                    }
+
                 val dialog =
                     InsertFieldDialog.newInstance(
                         fieldItems = fieldNames,
-                        metadata = InsertFieldMetadata(side = side),
+                        metadata =
+                            InsertFieldMetadata.query(
+                                side = side,
+                                noteId = noteId,
+                                ord = ord,
+                                cardTemplateName = templateName,
+                                noteTypeName = tempModel.notetype.name,
+                            ),
                         requestKey = insertFieldRequestKey,
                     )
                 templateEditor.showDialogFragment(dialog)

AnkiDroid/src/main/java/com/ichi2/anki/dialogs/InsertFieldDialog.kt

@@ -16,17 +16,21 @@
 
 package com.ichi2.anki.dialogs
 
+import android.content.Context
 import android.os.Bundle
+import android.text.Spanned
+import android.view.LayoutInflater
 import android.view.View
-import android.view.View.MeasureSpec
 import android.view.ViewGroup
 import android.widget.TextView
+import androidx.annotation.CheckResult
 import androidx.annotation.StringRes
 import androidx.appcompat.app.AlertDialog
 import androidx.core.os.bundleOf
+import androidx.core.text.HtmlCompat
+import androidx.core.text.parseAsHtml
 import androidx.fragment.app.DialogFragment
 import androidx.fragment.app.Fragment
-import androidx.fragment.app.FragmentManager
 import androidx.fragment.app.viewModels
 import androidx.recyclerview.widget.LinearLayoutManager
 import androidx.recyclerview.widget.RecyclerView
@@ -35,18 +39,23 @@ import androidx.viewpager2.widget.ViewPager2
 import com.google.android.material.tabs.TabLayout
 import com.google.android.material.tabs.TabLayoutMediator
 import com.ichi2.anki.CardTemplateEditor
+import com.ichi2.anki.Flag
 import com.ichi2.anki.R
 import com.ichi2.anki.databinding.DialogGenericRecyclerViewBinding
 import com.ichi2.anki.databinding.DialogInsertFieldBinding
+import com.ichi2.anki.databinding.DialogInsertSpecialFieldRecyclerItemBinding
 import com.ichi2.anki.dialogs.InsertFieldDialogViewModel.Companion.KEY_FIELD_ITEMS
 import com.ichi2.anki.dialogs.InsertFieldDialogViewModel.Companion.KEY_INSERT_FIELD_METADATA
 import com.ichi2.anki.dialogs.InsertFieldDialogViewModel.Companion.KEY_REQUEST_KEY
 import com.ichi2.anki.dialogs.InsertFieldDialogViewModel.Tab
 import com.ichi2.anki.launchCatchingTask
+import com.ichi2.anki.model.SpecialField
+import com.ichi2.anki.model.SpecialFields
 import com.ichi2.utils.create
 import com.ichi2.utils.negativeButton
 import com.ichi2.utils.title
 import dev.androidbroadcast.vbpd.viewBinding
+import org.jetbrains.annotations.VisibleForTesting
 
 /**
  * Dialog fragment used to show the fields that the user can insert in the card editor. This
@@ -99,8 +108,6 @@ class InsertFieldDialog : DialogFragment() {
                             viewModel.currentTab = selectedTab
                         }
                     super.onPageSelected(position)
-
-                    binding.viewPager.updateHeight(childFragmentManager)
                 }
             },
         )
@@ -199,6 +206,11 @@ class InsertFieldDialog : DialogFragment() {
                     override fun getItemCount(): Int = viewModel.fieldNames.size
                 }
         }
+
+        override fun onResume() {
+            super.onResume()
+            this.requireView().requestLayout() // update the height of the ViewPager
+        }
     }
 
     class SelectSpecialFieldFragment : Fragment(R.layout.dialog_generic_recycler_view) {
@@ -214,52 +226,93 @@ class InsertFieldDialog : DialogFragment() {
             super.onViewCreated(view, savedInstanceState)
 
             binding.root.adapter =
-                object : RecyclerView.Adapter<RecyclerView.ViewHolder>() {
+                object : RecyclerView.Adapter<InsertFieldViewHolder>() {
                     override fun onCreateViewHolder(
                         parent: ViewGroup,
                         viewType: Int,
-                    ): RecyclerView.ViewHolder {
-                        val root = layoutInflater.inflate(R.layout.material_dialog_list_item, parent, false)
-                        return object : RecyclerView.ViewHolder(root) {}
-                    }
+                    ) = InsertFieldViewHolder(
+                        DialogInsertSpecialFieldRecyclerItemBinding.inflate(
+                            LayoutInflater.from(parent.context),
+                            parent,
+                            false,
+                        ),
+                    )
 
                     override fun onBindViewHolder(
-                        holder: RecyclerView.ViewHolder,
+                        holder: InsertFieldViewHolder,
                         position: Int,
                     ) {
-                        val textView = holder.itemView as TextView
                         val field = viewModel.specialFields[position]
-                        textView.text = field.name
-                        textView.setOnClickListener { viewModel.selectSpecialField(field) }
+
+                        holder.binding.title.text = "{{${field.name}}}"
+                        holder.binding.description.text = field.buildDescription(requireContext(), viewModel.metadata)
+                        holder.binding.root.setOnClickListener { viewModel.selectSpecialField(field) }
                     }
 
                     override fun getItemCount(): Int = viewModel.specialFields.size
                 }
             binding.root.layoutManager = LinearLayoutManager(context)
         }
+
+        override fun onResume() {
+            super.onResume()
+            this.requireView().requestLayout() // update the height of the ViewPager
+        }
     }
+
+    private class InsertFieldViewHolder(
+        val binding: DialogInsertSpecialFieldRecyclerItemBinding,
+    ) : RecyclerView.ViewHolder(binding.root)
 }
 
-fun ViewPager2.updateHeight(fragmentManager: FragmentManager) {
-    fun getCurrentFragment(fragmentManager: FragmentManager): Fragment? {
-        val currentTag = "f$currentItem"
-        return fragmentManager.findFragmentByTag(currentTag)
+@VisibleForTesting
+@CheckResult
+fun SpecialField.buildDescription(
+    context: Context,
+    metadata: InsertFieldMetadata,
+): Spanned {
+    fun buildSuffix(value: String?): String {
+        if (value == null) return ""
+        return context.getString(R.string.special_field_example_suffix, value)
     }
+    return when (this) {
+        SpecialFields.FrontSide -> context.getString(R.string.special_field_front_side_help)
+        SpecialFields.Deck ->
+            context.getString(R.string.special_field_deck_help, buildSuffix(metadata.deck))
 
-    post {
-        val fragment = getCurrentFragment(fragmentManager) ?: return@post
-        val recyclerView = fragment.view as? RecyclerView ?: return@post
+        SpecialFields.Subdeck ->
+            context.getString(R.string.special_field_subdeck_help, buildSuffix(metadata.subdeck))
+        SpecialFields.Flag -> {
+            val code = metadata.flag ?: "N"
+            context.getString(
+                R.string.special_field_card_flag_help,
+                if (code == "N") "flag$code" else "<b>flag$code</b>",
+                "<b>$code</b>",
+                Flag.entries.minOf { it.code },
+                Flag.entries.maxOf { it.code },
+            )
+        }
+        SpecialFields.Tags -> {
+            val tags = if (metadata.tags.isNullOrBlank()) null else metadata.tags
+            context.getString(R.string.special_field_tags_help, buildSuffix(tags))
+        }
+        SpecialFields.CardId ->
+            context.getString(R.string.special_field_card_id_help, buildSuffix(metadata.cardId?.toString()))
 
-        // Measure RecyclerView height
-        recyclerView.measure(
-            MeasureSpec.makeMeasureSpec(width, MeasureSpec.EXACTLY),
-            MeasureSpec.makeMeasureSpec(0, MeasureSpec.UNSPECIFIED),
-        )
+        SpecialFields.CardTemplate ->
+            context.getString(
+                R.string.special_field_card_help,
+                buildSuffix(metadata.cardTemplateName),
+            )
 
-        // Update ViewPager height
-        layoutParams.height = recyclerView.measuredHeight
-        requestLayout()
-    }
+        SpecialFields.NoteType ->
+            context.getString(
+                R.string.special_field_type_help,
+                buildSuffix(metadata.noteTypeName),
+            )
+        // this shouldn't happen
+        else -> ""
+    }.parseAsHtml(HtmlCompat.FROM_HTML_MODE_LEGACY)
 }
 
 context(dialog: InsertFieldDialog)

AnkiDroid/src/main/java/com/ichi2/anki/dialogs/InsertFieldDialogViewModel.kt

@@ -20,7 +20,12 @@ import android.os.Parcelable
 import androidx.annotation.CheckResult
 import androidx.lifecycle.SavedStateHandle
 import androidx.lifecycle.ViewModel
+import com.ichi2.anki.CollectionManager.withCol
 import com.ichi2.anki.cardviewer.SingleCardSide
+import com.ichi2.anki.common.utils.ellipsize
+import com.ichi2.anki.libanki.CardId
+import com.ichi2.anki.libanki.Decks
+import com.ichi2.anki.libanki.NoteId
 import com.ichi2.anki.model.FieldName
 import com.ichi2.anki.model.SpecialFields
 import com.ichi2.anki.utils.ext.require
@@ -43,7 +48,12 @@ class InsertFieldDialogViewModel(
     /** The field names of the note type */
     val fieldNames = savedStateHandle.require<ArrayList<String>>(KEY_FIELD_ITEMS).map(::FieldName)
 
-    private val metadata = savedStateHandle.require<InsertFieldMetadata>(KEY_INSERT_FIELD_METADATA)
+    /**
+     * State of the selected card when the screen was opened
+     *
+     * Used for providing [special fields][SpecialFields] with the output they'd produce.
+     */
+    val metadata = savedStateHandle.require<InsertFieldMetadata>(KEY_INSERT_FIELD_METADATA)
 
     val selectedFieldFlow = MutableStateFlow<SelectedField?>(null)
 
@@ -120,4 +130,63 @@ class InsertFieldDialogViewModel(
 @Parcelize
 data class InsertFieldMetadata(
     val side: SingleCardSide,
-) : Parcelable
+    val cardTemplateName: String,
+    val noteTypeName: String,
+    val tags: String?,
+    val flag: Int?,
+    val cardId: CardId?,
+    val deck: String?,
+) : Parcelable {
+    val subdeck: String?
+        get() = deck?.let { Decks.basename(it) }
+
+    companion object {
+        @CheckResult
+        suspend fun query(
+            side: SingleCardSide,
+            cardTemplateName: String,
+            noteTypeName: String,
+            noteId: NoteId?,
+            ord: Int?,
+        ): InsertFieldMetadata {
+            val note =
+                try {
+                    noteId?.let { nid -> withCol { getNote(nid) } }
+                } catch (e: Exception) {
+                    Timber.w(e, "failed to get note")
+                    null
+                }
+
+            // BUG: This is the saved tags of the note, not the currently edited tags
+            val tags =
+                note
+                    ?.tags
+                    ?.joinToString(separator = " ")
+                    // truncate, so we don't pass unbounded text into the arguments
+                    ?.ellipsize(75)
+
+            val card =
+                try {
+                    if (ord == null || note == null) {
+                        null
+                    } else {
+                        // ord can be invalid if the user has in-memory template additions
+                        withCol { note.cards(this).getOrNull(ord) }
+                    }
+                } catch (e: Exception) {
+                    Timber.w(e, "failed to get card")
+                    null
+                }
+
+            return InsertFieldMetadata(
+                side = side,
+                cardTemplateName = cardTemplateName,
+                noteTypeName = noteTypeName,
+                tags = tags,
+                cardId = card?.id,
+                flag = card?.userFlag(),
+                deck = card?.currentDeckId()?.let { did -> withCol { decks.get(did)?.name } },
+            )
+        }
+    }
+}

AnkiDroid/src/main/res/layout/dialog_insert_special_field_recycler_item.xml

@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="utf-8"?><!--
+  ~  Copyright (c) 2026 David Allison <[email protected]>
+  ~
+  ~  This program is free software; you can redistribute it and/or modify it under
+  ~  the terms of the GNU General Public License as published by the Free Software
+  ~  Foundation; either version 3 of the License, or (at your option) any later
+  ~  version.
+  ~
+  ~  This program is distributed in the hope that it will be useful, but WITHOUT ANY
+  ~  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+  ~  PARTICULAR PURPOSE. See the GNU General Public License for more details.
+  ~
+  ~  You should have received a copy of the GNU General Public License along with
+  ~  this program.  If not, see <http://www.gnu.org/licenses/>.
+  -->
+
+<LinearLayout
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools"
+    android:orientation="vertical"
+    android:layout_width="match_parent"
+    android:layout_height="wrap_content"
+    android:paddingHorizontal="24dp"
+    android:background="?attr/selectableItemBackground"
+    android:gravity="center_vertical">
+
+    <TextView
+        android:id="@+id/title"
+        android:layout_width="match_parent"
+        android:layout_height="wrap_content"
+        android:layout_gravity="center_vertical"
+        android:maxLines="1"
+        android:paddingBottom="2dp"
+        android:fontFamily="monospace"
+        android:textAppearance="?attr/textAppearanceTitleMedium"
+        tools:text="{{FrontSide}}"
+        />
+
+
+    <TextView
+        android:id="@+id/description"
+        android:layout_width="match_parent"
+        android:layout_height="wrap_content"
+        android:layout_gravity="center_vertical"
+        android:textAppearance="?attr/textAppearanceBodyMedium"
+        android:maxLines="3"
+        android:paddingBottom="12dp"
+        tools:text="The content of the front template. Audio is not automatically played"
+        />
+
+</LinearLayout>

AnkiDroid/src/main/res/values/03-dialogs.xml

@@ -279,4 +279,13 @@ also changes the interval of the card"
     <!-- Special Fields -->
     <string name="basic_fields_tab_header" comment="Tab header for inserting non-special fields: {{Front}}">Basic</string>
     <string name="special_fields_tab_header" comment="Tab header for inserting special fields: {{Deck}}">Special</string>
+    <string name="special_field_example_suffix"><![CDATA[: ‘<b>%1$s</b>’]]></string>
+    <string name="special_field_front_side_help">The front template content. Audio is not automatically played</string>
+    <string name="special_field_deck_help">The full deck of the card, including parent decks%s</string>
+    <string name="special_field_subdeck_help">The current deck of the card, excluding parent decks%s</string>
+    <string name="special_field_card_flag_help">Outputs ‘%1$s’, where %2$s is the flag code (%3$d\–%4$d\)</string>
+    <string name="special_field_tags_help">The tags of the note%s</string>
+    <string name="special_field_card_id_help">The ID of the card%s</string>
+    <string name="special_field_card_help">The name of the card template%s</string>
+    <string name="special_field_type_help">The name of the note type%s</string>
 </resources>