bidux API Modernization Features

# Basic interpretation with modern flat API (RECOMMENDED)
result <- bid_interpret(
  central_question = "How can we reduce cognitive load in our signup form?",
  data_story = new_data_story(
    hook = "Users abandon signup forms at 60% rate",
    context = "Current form has 15 required fields",
    tension = "Users feel overwhelmed and leave",
    resolution = "Simplify form using progressive disclosure"
  ),
  quiet = FALSE
)

# View results
print(result)

# Enhanced interpretation with user personas
interpretation <- bid_interpret(
  central_question = "What drives user engagement in our dashboard?",
  data_story = new_data_story(
    hook = "Daily active users declining despite new features",
    context = "Rich dashboard with multiple visualizations",
    tension = "Users aren't discovering valuable insights",
    resolution = "Guide attention to high-value content"
  ),
  user_personas = list(
    list(
      name = "Data Analyst",
      goals = "Find patterns quickly",
      pain_points = "Too many visualizations",
      technical_level = "Advanced"
    )
  ),
  quiet = TRUE
)

# Enhanced S3 print method shows summary
print(interpretation)

# Follow correct BID framework order: Interpret → Notice → Anticipate → Structure
notice_result <- result |>
  bid_notice(
    problem = "Users struggle with cognitive overload in signup forms",
    evidence = "60% abandonment rate and user feedback surveys",
    quiet = TRUE
  )

# Anticipate potential user interactions and biases
anticipate_result <- notice_result |>
  bid_anticipate(
    interaction_modes = list(
      primary = "Progressive form completion",
      fallback = "Quick signup option"
    ),
    quiet = TRUE
  )

# Structure creates actionable dashboard recommendations
structured <- bid_structure(
  previous_stage = anticipate_result,
  concepts = c("Progressive Disclosure", "Cognitive Load Theory"),
  quiet = TRUE
)

# View auto-selected layout and concept-grouped suggestions
print(paste("Auto-selected layout:", structured$layout))
print("Structured recommendations:")
print(structured$suggestions)

# Summary provides overview of all recommendations
summary(structured)

# Step 1: Interpret user needs and context (using RECOMMENDED flat API)
ui_analysis <- bid_interpret(
  central_question = "How can we improve landing page conversion without damaging user trust?",
  data_story = new_data_story(
    hook = "High-pressure sales tactics may be reducing user trust",
    context = "Landing page with multiple persuasive elements",
    tension = "Need conversions but not at expense of user experience",
    resolution = "Balance persuasion with trust-building elements"
  ),
  user_personas = list(
    list(
      name = "Potential Customer",
      goals = "Evaluate product value",
      pain_points = "Feels pressured by aggressive sales tactics",
      technical_level = "Basic"
    )
  ),
  quiet = TRUE
)

# Step 2: Notice specific problems
problem_analysis <- ui_analysis |>
  bid_notice(
    problem = "Aggressive persuasion tactics creating user pressure",
    evidence = "Lower conversion rates and negative user feedback on pressure tactics",
    quiet = TRUE
  )

# Step 3: Anticipate user interactions and cognitive biases
interaction_analysis <- problem_analysis |>
  bid_anticipate(
    interaction_modes = list(
      primary = "Trust-based evaluation of product value",
      secondary = "Quick decision under time pressure"
    ),
    quiet = TRUE
  )

# Step 4: Structure actionable recommendations
recommendations <- bid_structure(
  previous_stage = interaction_analysis,
  concepts = c("Social Proof", "Trust Signals", "Progressive Disclosure"),
  quiet = TRUE
)

# Step 5: Validate design decisions
validation_analysis <- bid_validate(
  previous_stage = recommendations,
  validation_method = "expert_review",
  quiet = TRUE
)

# Step 6: Create comprehensive data story from complete workflow using flat API
optimization_story <- new_data_story(
  hook = "High-pressure persuasive elements creating user trust concerns",
  context = "Complete BID Framework Analysis: Landing Page Trust-Based Conversion Optimization across all 5 stages",
  tension = "Need to balance conversion goals with user trust - current approach damages long-term relationships",
  resolution = "Apply validated BID framework recommendations balancing persuasion with trust-building, monitoring both conversion rates and user trust metrics"
)

# View complete analysis results
print("=== Complete BID Framework Workflow Results ===")
print(optimization_story)
print("\n=== Stage Summaries ===")
summary(recommendations)
summary(validation_analysis)

# Clear error messages for invalid inputs
try(bid_interpret()) # Missing required parameter
try(bid_interpret(central_question = 123)) # Wrong type for central_question
try(bid_interpret(central_question = "test", data_story = "invalid")) # Invalid data_story

# Descriptive validation errors for data story creation (flat API)
try(new_data_story()) # Missing required parameter (context)
try(new_data_story(context = "")) # Invalid empty context

# Deprecated format still validates (but triggers warnings)
try(new_data_story(
  context = "Valid context",
  variables = "invalid_type"  # Must be a list
))

# Check if tibble is available
if (requireNamespace("tibble", quietly = TRUE)) {
  # BID framework functions return tibbles by default when available
  # Using RECOMMENDED flat API
  result_tbl <- bid_interpret(
    central_question = "How can we test tibble integration?",
    data_story = new_data_story(
      hook = "Package supports modern tibble output",
      context = "Enhanced data handling with tibble package",
      tension = "Need to verify integration works correctly",
      resolution = "Test and validate tibble functionality"
    ),
    quiet = TRUE
  )

  cat("Result class:", class(result_tbl), "\n")

  # Works seamlessly with dplyr if available
  if (requireNamespace("dplyr", quietly = TRUE)) {
    library(dplyr)

    # Filter and analyze BID framework results
    interpret_summary <- result_tbl %>%
      select(stage, central_question, hook) %>%
      filter(!is.na(central_question))

    print(interpret_summary)
  }
} else {
  cat("Tibble package not available, using base data.frame\n")
}

# Consistent parameter patterns across functions
bid_interpret_params <- c("text", "method", "context", "return_tibble", "quiet")
bid_structure_params <- c("insights", "format", "priority", "context", "return_tibble", "quiet")

# Common parameters:
# - return_tibble: Enable modern tibble output
# - quiet: Control informational messages
# - context: Provide analysis context

# All functions return objects with:
# - S3 classes for proper method dispatch
# - Timestamp columns for tracking
# - Consistent attribute structures
# - Modern data types (tibble when available)

# Legacy nested format still works (with deprecation warning)
old_style_story <- new_data_story(
  context = "Dashboard analysis",
  variables = list(metric = "engagement"),
  relationships = list(trend = "declining")
)
# Triggers deprecation warning but functions correctly

# Modern flat API is recommended
new_style_story <- new_data_story(
  hook = "Engagement metrics show concerning trends",
  context = "Dashboard analysis of Q3 2024 usage patterns",
  tension = "User engagement declining despite new features",
  resolution = "Implement BID framework to identify UX friction"
)

# Both can be used with bid_interpret()
result_old <- bid_interpret(
  central_question = "How to improve engagement?",
  data_story = old_style_story,
  quiet = TRUE
)

result_new <- bid_interpret(
  central_question = "How to improve engagement?",
  data_story = new_style_story,
  quiet = TRUE
)

# Both return compatible structures
identical(names(result_old), names(result_new))