Pilot conservative input tooltips

README.md

@@ -84,6 +84,41 @@ Replace `kmeans` with the app folder name. Screenshots are source assets and sho
 
 If a Shinylive app cannot be exported, the build fails. Move it to the server runtime only when there is a deliberate reason to host it on Posit Connect Cloud.
 
+## Input Help and Tooltips
+
+Use input tooltips conservatively. Add them only when a control represents a non-obvious statistical or mathematical concept, uses a confusing scale, changes the result conceptually, or needs context that does not fit naturally in its label.
+
+- Treat two to four tooltips per app as an upper limit, not a target.
+- Do not add help to obvious controls such as the number of observations unless there is an important non-obvious consequence.
+- Keep each tooltip focused on one idea and preferably below 25 words.
+- Do not repeat the general explanation already available in `readme.md`.
+- Preserve existing label wrappers such as `tags$small()` and the current sidebar spacing.
+- Use namespace-qualified calls instead of adding `library(bsicons)`.
+- Give icon-only triggers a short accessible `title`.
+- Add a small spacing utility such as `class = "ms-1"` so the icon remains visually separate from the label.
+- Support hover, keyboard focus, and click/touch with `options = list(trigger = "hover focus click")`.
+- Test the icon at normal and narrow widths and verify the interaction directly in the running app.
+
+Use this pattern, adapting the outer wrapper to the existing label:
+
+```r
+label = tags$small(tagList(
+  "Parameter name",
+  bslib::tooltip(
+    bsicons::bs_icon(
+      "info-circle",
+      class = "ms-1",
+      title = "About parameter name"
+    ),
+    "Short explanation.",
+    placement = "right",
+    options = list(trigger = "hover focus click")
+  )
+))
+```
+
+Before implementing tooltips across an app, list the selected inputs and why each one needs help. It is valid for an app to need no tooltips.
+
 ## Build
 
 From an interactive R session at the repository root:

lorenz-attractor/app.R

@@ -48,9 +48,54 @@ ui <- page_fillable(
     sidebar = sidebar(
       title = "Lorenz System Parameters",
       withMathJax(),
-      sliderInput("sigma", "\\( \\sigma \\) (sigma):", min = 1, max = 20, value = 10, step = 0.1),
-      sliderInput("rho", "\\( \\rho \\) (rho):", min = 1, max = 50, value = 28, step = 0.1),
-      sliderInput("beta", "\\( \\beta \\) (beta):", min = 0.1, max = 10, value = 8/3, step = 0.1),
+      sliderInput(
+        "sigma",
+        tagList(
+          "\\( \\sigma \\) (sigma):",
+          bslib::tooltip(
+            bsicons::bs_icon("info-circle", class = "ms-1", title = "About sigma"),
+            "Controls how quickly x follows y.",
+            placement = "right",
+            options = list(trigger = "hover focus click")
+          )
+        ),
+        min = 1,
+        max = 20,
+        value = 10,
+        step = 0.1
+      ),
+      sliderInput(
+        "rho",
+        tagList(
+          "\\( \\rho \\) (rho):",
+          bslib::tooltip(
+            bsicons::bs_icon("info-circle", class = "ms-1", title = "About rho"),
+            "Controls the system's driving strength and whether chaotic behavior emerges.",
+            placement = "right",
+            options = list(trigger = "hover focus click")
+          )
+        ),
+        min = 1,
+        max = 50,
+        value = 28,
+        step = 0.1
+      ),
+      sliderInput(
+        "beta",
+        tagList(
+          "\\( \\beta \\) (beta):",
+          bslib::tooltip(
+            bsicons::bs_icon("info-circle", class = "ms-1", title = "About beta"),
+            "Controls damping in the z direction.",
+            placement = "right",
+            options = list(trigger = "hover focus click")
+          )
+        ),
+        min = 0.1,
+        max = 10,
+        value = 8/3,
+        step = 0.1
+      ),
       shinyWidgets::sliderTextInput(
         "n_points",
         "Number of points:",
@@ -61,7 +106,15 @@ ui <- page_fillable(
       ),
       shinyWidgets::sliderTextInput(
         "dt",
-        "Time step (dt):",
+        tagList(
+          "Time step (dt):",
+          bslib::tooltip(
+            bsicons::bs_icon("info-circle", class = "ms-1", title = "About time step"),
+            "Larger steps cover more time per point but reduce numerical accuracy.",
+            placement = "right",
+            options = list(trigger = "hover focus click")
+          )
+        ),
         choices = c("0.001", "0.002", "0.005", "0.01", "0.02", "0.05"),
         selected = "0.01",
         grid = TRUE,
@@ -152,4 +205,4 @@ server <- function(input, output, session) {
   })
 }
 
-shinyApp(ui, server)
+shinyApp(ui, server)