diff --git a/README.md b/README.md index e4db961..533723b 100644 --- a/README.md +++ b/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: diff --git a/lorenz-attractor/app.R b/lorenz-attractor/app.R index d85bc22..21b19e6 100644 --- a/lorenz-attractor/app.R +++ b/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) \ No newline at end of file +shinyApp(ui, server)