bidux (version 0.3.3)

bid_structure: Document Dashboard Structure Stage in BID Framework

Description

This function documents the structure of the dashboard with automatic layout selection and generates ranked, concept-grouped actionable UI/UX suggestions. Layout is intelligently chosen based on content analysis of previous stages using deterministic heuristics. Returns structured recommendations with specific component pointers and implementation rationales.

Usage

bid_structure(
  previous_stage,
  concepts = NULL,
  telemetry_flags = NULL,
  quiet = NULL,
  ...
)

Value

A bid_stage object containing:

stage

"Structure"

layout

Auto-selected layout type

suggestions

List of concept groups with ranked suggestions (nested format)

suggestions_tbl

Flattened tibble with all suggestions, includes columns: concept, title, details, components, rationale, score, difficulty, category

concepts

Comma-separated string of all concepts used

Arguments

previous_stage

A tibble or list output from an earlier BID stage function.

concepts

A character vector of additional BID concepts to include. Concepts can be provided in natural language (e.g., "Principle of Proximity") or with underscores (e.g., "principle_of_proximity"). The function uses fuzzy matching to identify the concepts. If NULL, will detect relevant concepts from previous stages automatically.

telemetry_flags

Optional named list of telemetry flags from bid_flags(). Used to adjust layout choice and suggestion scoring based on observed user behavior patterns.

quiet

Logical indicating whether to suppress informational messages. If NULL, uses getOption("bidux.quiet", FALSE).

...

Additional parameters. If layout is provided via ..., the function will abort with a helpful error message.

Details

Layout Auto-Selection: For backwards compatibility with versions < 0.3.0; to be removed in 0.4.0. Uses deterministic heuristics to analyze content from previous stages and select the most appropriate layout:

• breathable: For information overload/confusion patterns

• dual_process: For overview vs detail needs

• grid: For grouping/comparison requirements

• card: For modular/chunked content

• tabs: For categorical organization (unless telemetry shows issues)

Suggestion Engine: Generates ranked, actionable recommendations grouped by UX concepts. Each suggestion includes specific R dashboard components (Shiny, bslib, DT, plotly, etc.), implementation details, and rationale. Suggestions are scored based on relevance, layout appropriateness, and contextual factors. Component suggestions work with both Shiny applications and Quarto dashboards, with shiny-prefixed components (i.e., shiny::) requiring Shiny runtime.

Examples

notice_result <- bid_interpret(
  central_question = "How can we simplify data presentation?",
  data_story = list(
    hook = "Data is too complex",
    context = "Overloaded with charts",
    tension = "Confusing layout",
    resolution = "Introduce clear grouping"
  )
) |>
  bid_notice(
    problem = "Users struggle with information overload",
    evidence = "Survey results indicate delays"
  )

# Auto-selected layout with concept-grouped suggestions
structure_result <- bid_structure(previous_stage = notice_result)
print(structure_result$layout) # Auto-selected layout
print(structure_result$suggestions) # Ranked suggestions by concept (nested)

# Access flattened tibble format for easier manipulation
suggestions_flat <- structure_result$suggestions_tbl[[1]]
print(suggestions_flat)

# Filter by difficulty
easy_suggestions <- suggestions_flat[suggestions_flat$difficulty == "Easy", ]

# Filter by category
layout_suggestions <- suggestions_flat[suggestions_flat$category == "Layout", ]

summary(structure_result)