Title: Behavior Insight Design: A Toolkit for Integrating Behavioral Science in UI/UX Design
Version: 0.3.0
Description: Provides a framework and toolkit to guide 'shiny' developers in implementing the Behavior Insight Design (BID) framework. The package offers functions for documenting each of the five stages (Notice, Interpret, Structure, Anticipate, and Validate), along with a comprehensive concept dictionary.
License: MIT + file LICENSE
Encoding: UTF-8
Depends: R (≥ 4.1.0)
RoxygenNote: 7.3.2
Imports: cli, DBI, dplyr, jsonlite, readr (≥ 2.1.5), RSQLite, stats, stringdist (≥ 0.9.15), stringr (≥ 1.5.1), tibble (≥ 3.2.1), utils
Suggests: DiagrammeR, knitr, rmarkdown, spelling, testthat (≥ 3.0.0)
VignetteBuilder: knitr
Config/testthat/edition: 3
Language: en-US
URL: https://jrwinget.github.io/bidux/
NeedsCompilation: no
Packaged: 2025-08-29 21:12:31 UTC; user
Author: Jeremy Winget ORCID iD [aut, cre]
Maintainer: Jeremy Winget <contact@jrwinget.com>
Repository: CRAN
Date/Publication: 2025-08-29 21:30:02 UTC

bidux: Behavior Insight Design: A Toolkit for Integrating Behavioral Science in UI/UX Design

Description

logo

Provides a framework and toolkit to guide 'shiny' developers in implementing the Behavior Insight Design (BID) framework. The package offers functions for documenting each of the five stages (Notice, Interpret, Structure, Anticipate, and Validate), along with a comprehensive concept dictionary.

Author(s)

Maintainer: Jeremy Winget contact@jrwinget.com (ORCID)

See Also

Useful links:


Apply context-based scoring adjustments

Description

Apply context-based scoring adjustments

Usage

adjust_suggestion_score(suggestion, previous_stage, chosen_layout, concept)

Convert bid_stage to tibble

Description

Convert bid_stage to tibble

Usage

## S3 method for class 'bid_stage'
as_tibble(x, ...)

Arguments

x

A bid_stage object

...

Additional arguments (unused)

Value

A tibble


Document User Behavior Anticipation Stage in BID Framework

Description

This function documents the anticipated user behavior by listing bias mitigation strategies related to anchoring, framing, confirmation bias, etc. It also supports adding interaction hints and visual feedback elements.

Usage

bid_anticipate(
  previous_stage,
  bias_mitigations = NULL,
  include_accessibility = TRUE,
  ...
)

Arguments

previous_stage

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

bias_mitigations

A named list of bias mitigation strategies. If NULL, the function will suggest bias mitigations based on information from previous stages.

include_accessibility

Logical indicating whether to include accessibility mitigations. Default is TRUE.

...

Additional parameters. If 'interaction_principles' is provided, it will be ignored with a warning.

Value

A tibble containing the documented information for the "Anticipate" stage.

Examples

structure_info <- bid_structure(
  bid_interpret(
    bid_notice(
      "Issue with dropdown menus",
      evidence = "User testing indicated delays"
    ),
    central_question = "How can we improve selection efficiency?",
    data_story = list(
      hook = "Too many options",
      context = "Excessive choices",
      tension = "User frustration",
      resolution = "Simplify menu"
    )
  ),
  concepts = c("principle_of_proximity", "default_effect")
)

# Basic usage
bid_anticipate(
  previous_stage = structure_info,
  bias_mitigations = list(
    anchoring = "Use context-aware references",
    framing = "Toggle between positive and negative framing"
  )
)

# Let the function suggest bias mitigations based on previous stages
bid_anticipate(
  previous_stage = structure_info
)

# with accessibility included (default)
bid_anticipate(
  previous_stage = structure_info,
  bias_mitigations = list(
    anchoring = "Use context-aware references",
    framing = "Toggle between positive and negative framing"
  ),
  include_accessibility = TRUE
)


Get detailed information about a specific concept

Description

Returns detailed information about a specific BID framework concept, including implementation recommendations based on the concept's stage.

Usage

bid_concept(concept_name, add_recommendations = TRUE)

Arguments

concept_name

A character string with the exact or partial concept name

add_recommendations

Logical indicating whether to add stage-specific recommendations

Value

A tibble with detailed concept information


Search BID Framework Concepts

Description

Search for behavioral science and UX concepts used in the BID framework. Returns concepts matching the search term along with their descriptions, categories, and implementation guidance.

Usage

bid_concepts(search = NULL, fuzzy_match = TRUE, max_distance = 2)

Arguments

search

A character string to search for. If NULL or empty, returns all concepts.

fuzzy_match

Logical indicating whether to use fuzzy string matching (default: TRUE)

max_distance

Maximum string distance for fuzzy matching (default: 2)

Value

A tibble containing matching concepts with their details


Ingest telemetry data and identify UX friction points

Description

This function ingests telemetry data from shiny.telemetry output (SQLite or JSON) and automatically identifies potential UX issues, translating them into BID framework Notice stages. It analyzes user behavior patterns to detect friction points such as unused inputs, delayed interactions, frequent errors, and navigation drop-offs.

Usage

bid_ingest_telemetry(path, format = NULL, thresholds = list())

Arguments

path

File path to telemetry data (SQLite database or JSON log file)

format

Optional format specification ("sqlite" or "json"). If NULL, auto-detected from file extension.

thresholds

Optional list of threshold parameters: - unused_input_threshold: percentage of sessions below which input is considered unused (default: 0.05) - delay_threshold_seconds: seconds of delay considered problematic (default: 30) - error_rate_threshold: percentage of sessions with errors considered problematic (default: 0.1) - navigation_threshold: percentage of sessions visiting a page below which it's considered underused (default: 0.2) - rapid_change_window: seconds within which multiple changes indicate confusion (default: 10) - rapid_change_count: number of changes within window to flag as confusion (default: 5)

Value

A list containing bid_stage objects for each identified issue in the "Notice" stage. Each element is named by issue type (e.g., "unused_input_region", "delayed_interaction", etc.)

Examples

## Not run: 
# Analyze SQLite telemetry database
issues <- bid_ingest_telemetry("telemetry.sqlite")

# Analyze JSON log with custom thresholds
issues <- bid_ingest_telemetry(
  "telemetry.log",
  format = "json",
  thresholds = list(
    unused_input_threshold = 0.1,
    delay_threshold_seconds = 60
  )
)

# Use results in BID workflow
if (length(issues) > 0) {
  # Take first issue and continue with BID process
  interpret_result <- bid_interpret(
    previous_stage = issues[[1]],
    central_question = "How can we improve user engagement?"
  )
}

## End(Not run)


Document User Interpretation Stage in BID Framework

Description

This function documents the interpretation of user needs, capturing the central question and the data storytelling narrative. It represents stage 2 in the BID framework.

Usage

bid_interpret(
  previous_stage,
  central_question = NULL,
  data_story = NULL,
  user_personas = NULL
)

Arguments

previous_stage

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

central_question

A character string representing the main question to be answered. If NULL, will be suggested based on previous stage information.

data_story

A list containing elements such as hook, context, tension, resolution, and optionally audience, metrics, and visual_approach. If NULL, elements will be suggested based on previous stage.

user_personas

Optional list of user personas to consider in the design.

Value

A tibble containing the documented information for the "Interpret" stage.

Examples

notice <- bid_notice(
  problem = "Users struggle with complex data",
  evidence = "Test results indicate delays"
)

# Basic usage
bid_interpret(
  previous_stage = notice,
  central_question = "What drives the decline in user engagement?",
  data_story = list(
    hook = "Declining trend in engagement",
    context = "Previous high engagement levels",
    tension = "Unexpected drop",
    resolution = "Investigate new UI changes",
    audience = "Marketing team",
    metrics = c("Daily Active Users", "Session Duration"),
    visual_approach = "Comparison charts showing before/after UI change"
  )
)

# Let the function suggest content based on previous stage
bid_interpret(
  previous_stage = notice
)

# With user personas
bid_interpret(
  previous_stage = notice,
  central_question = "How can we improve data discovery?",
  data_story = list(
    hook = "Users are missing key insights",
    context = "Critical data is available but overlooked",
    tension = "Time-sensitive decisions are delayed",
    resolution = "Highlight key metrics more effectively"
  ),
  user_personas = list(
    list(
      name = "Sara, Data Analyst",
      goals = "Needs to quickly find patterns in data",
      pain_points = "Gets overwhelmed by too many visualizations",
      technical_level = "Advanced"
    ),
    list(
      name = "Marcus, Executive",
      goals = "Wants high-level insights at a glance",
      pain_points = "Limited time to analyze detailed reports",
      technical_level = "Basic"
    )
  )
)


Document User Notice Stage in BID Framework

Description

This function documents the initial observation and problem identification stage. It represents stage 1 in the BID framework and now returns a structured bid_stage object with enhanced metadata and external mapping support.

Usage

bid_notice(problem, theory = NULL, evidence = NULL, ...)

Arguments

problem

A character string describing the observed user problem.

theory

A character string describing the behavioral theory that might explain the problem. If NULL, will be auto-suggested using external theory mappings.

evidence

A character string describing evidence supporting the problem.

...

Additional parameters. Deprecated parameters like 'target_audience' will generate warnings if provided.

Value

A bid_stage object containing the documented information for the "Notice" stage with enhanced metadata and validation.

Examples

# Basic usage with auto-suggested theory
notice_result <- bid_notice(
  problem = "Users struggling with complex dropdowns and too many options",
  evidence = "User testing shows 65% abandonment rate on filter selection"
)

# Print shows human-friendly summary
print(notice_result)

# Access underlying data
summary(notice_result)

# Check stage and metadata
get_stage(notice_result)
get_metadata(notice_result)

# with explicit theory
notice_explicit <- bid_notice(
  problem = "Mobile interface is difficult to navigate",
  theory = "Fitts's Law",
  evidence = "Mobile users report frustration with small touch targets"
)


Generate BID Framework Report

Description

Creates a comprehensive report from a completed BID framework process. This report summarizes all stages and provides recommendations for implementation.

Usage

bid_report(
  validate_stage,
  format = c("text", "html", "markdown"),
  include_diagrams = TRUE
)

Arguments

validate_stage

A tibble output from bid_validate().

format

Output format: "text", "html", or "markdown"

include_diagrams

Logical, whether to include ASCII diagrams in the report (default: TRUE)

Value

A formatted report summarizing the entire BID process

Examples

if (interactive()) {
  # After completing all 5 stages
  validation_result <- bid_validate(...)

  # Generate a text report
  bid_report(validation_result)

  # Generate an HTML report
  bid_report(validation_result, format = "html")

  # Generate a markdown report without diagrams
  bid_report(
    validation_result,
    format = "markdown",
    include_diagrams = FALSE
  )
}


Constructor for BID result collection objects

Description

Constructor for BID result collection objects

Usage

bid_result(stages)

Arguments

stages

List of bid_stage objects

Value

Object of class 'bid_result'


Constructor for BID stage objects

Description

Constructor for BID stage objects

Usage

bid_stage(stage, data, metadata = list())

Arguments

stage

Character string indicating the stage name

data

Tibble containing the stage data

metadata

List containing additional metadata

Value

Object of class 'bid_stage'


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, ...)

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.

...

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

Details

Layout Auto-Selection: Uses deterministic heuristics to analyze content from previous stages and select the most appropriate layout:

Suggestion Engine: Generates ranked, actionable recommendations grouped by UX concepts. Each suggestion includes specific Shiny/bslib components, implementation details, and rationale. Suggestions are scored based on relevance, layout appropriateness, and contextual factors.

Value

A bid_stage object containing:

stage

"Structure"

layout

Auto-selected layout type

suggestions

List of concept groups with ranked suggestions

concepts

Comma-separated string of all concepts used

Examples

interpret <- bid_notice(
  problem = "Users struggle with information overload",
  evidence = "Survey results indicate delays"
) |>
  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"
    )
  )

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


Suggest UI Components Based on BID Framework Analysis

Description

This function analyzes the results from BID framework stages and suggests appropriate UI components from popular R packages like shiny, bslib, DT, etc. The suggestions are based on the design principles and user needs identified in the BID process.

Usage

bid_suggest_components(bid_stage, package = NULL)

Arguments

bid_stage

A tibble output from any BID framework stage function

package

Optional character string specifying which package to focus suggestions on. Options include "shiny", "bslib", "DT", "plotly", "reactable", "htmlwidgets". If NULL, suggestions from all packages are provided.

Value

A tibble containing component suggestions with relevance scores

Examples

if (interactive()) {
  # After completing BID stages
  notice_result <- bid_notice(
    problem = "Users struggle with complex data",
    theory = "Cognitive Load Theory"
  )

  # Get all component suggestions
  bid_suggest_components(notice_result)

  # Get only bslib suggestions
  bid_suggest_components(notice_result, package = "bslib")

  # Get shiny-specific suggestions
  bid_suggest_components(notice_result, package = "shiny")
}


Document User Validation Stage in BID Framework

Description

This function documents the validation stage, where the user tests and refines the dashboard. It represents stage 5 in the BID framework.

Usage

bid_validate(
  previous_stage,
  summary_panel = NULL,
  collaboration = NULL,
  next_steps = NULL,
  include_exp_design = TRUE,
  include_telemetry = TRUE,
  include_empower_tools = TRUE
)

Arguments

previous_stage

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

summary_panel

A character string describing the final summary panel or key insight presentation.

collaboration

A character string describing how the dashboard enables collaboration and sharing.

next_steps

A character vector or string describing recommended next steps for implementation and iteration.

include_exp_design

Logical indicating whether to include experiment design suggestions. Default is TRUE.

include_telemetry

Logical indicating whether to include telemetry tracking and monitoring suggestions. Default is TRUE.

include_empower_tools

Logical indicating whether to include context-aware empowerment tool suggestions. Default is TRUE.

Value

A tibble containing the documented information for the "Validate" stage.

Examples

structure_input <- bid_notice(
  problem  = "Issue with dropdown menus",
  evidence = "User testing indicated delays"
) |>
  bid_interpret(
    central_question = "How can we improve selection efficiency?",
    data_story = list(
      hook = "Too many options",
      context = "Excessive choices",
      tension = "User frustration",
      resolution = "Simplify menu"
    )
  )

structure_result <- bid_structure(
  previous_stage = structure_input,
  concepts       = c("Principle of Proximity", "Default Effect")
)

anticipate <- bid_anticipate(
  previous_stage = structure_result,
  bias_mitigations = list(
    anchoring = "Provide reference points",
    framing   = "Use gain-framed messaging"
  )
)

bid_validate(
  previous_stage = anticipate,
  summary_panel = "Clear summary of key insights with action items",
  collaboration = "Team annotation and sharing features",
  next_steps = c(
    "Conduct user testing with target audience",
    "Implement accessibility improvements",
    "Add mobile responsiveness"
  )
)


Build suggestions for a specific concept

Description

Build suggestions for a specific concept

Usage

build_concept_group(concept, chosen_layout, previous_stage)

Arguments

concept

Name of the concept to generate suggestions for

chosen_layout

Selected layout type

previous_stage

Previous stage data

Value

List with concept name and suggestions


Build suggestion groups organized by concept

Description

Build suggestion groups organized by concept

Usage

build_groups_with_suggestions(concepts_final, chosen_layout, previous_stage)

Arguments

concepts_final

Final list of concepts to generate suggestions for

chosen_layout

Selected layout type

previous_stage

Previous stage data for context

Value

List of concept groups with suggestions


Create notice stage for confusion patterns

Description

Create notice stage for confusion patterns

Usage

create_confusion_notice(confusion_info, total_sessions)

Arguments

confusion_info

List with confusion pattern information

total_sessions

Total number of sessions

Value

bid_stage object


Create notice stage for delayed interactions

Description

Create notice stage for delayed interactions

Usage

create_delay_notice(delay_info, total_sessions, threshold)

Arguments

delay_info

List with delay statistics

total_sessions

Total number of sessions

threshold

Threshold used for analysis

Value

bid_stage object


Create notice stage for error patterns

Description

Create notice stage for error patterns

Usage

create_error_notice(error_info, total_sessions)

Arguments

error_info

List with error pattern information

total_sessions

Total number of sessions

Value

bid_stage object


Create notice stage for navigation issues

Description

Create notice stage for navigation issues

Usage

create_navigation_notice(nav_info, total_sessions)

Arguments

nav_info

List with navigation pattern information

total_sessions

Total number of sessions

Value

bid_stage object


Create notice stage for unused input

Description

Create notice stage for unused input

Usage

create_unused_input_notice(input_info, total_sessions)

Arguments

input_info

List with input usage information

total_sessions

Total number of sessions

Value

bid_stage object


Auto-detect telemetry format from file extension

Description

Auto-detect telemetry format from file extension

Usage

detect_telemetry_format(path)

Arguments

path

File path

Value

Format string ("sqlite" or "json")


Extract specific stage from bid_result

Description

Extract specific stage from bid_result

Usage

extract_stage(workflow, stage)

Arguments

workflow

A bid_result object

stage

Character string with stage name

Value

A bid_stage object or NULL if not found


Extract theory concepts from Stage 1 (Notice)

Description

Extract theory concepts from Stage 1 (Notice)

Usage

extract_stage1_theory(previous_stage)

Arguments

previous_stage

Previous stage data

Value

Character vector of theory-based concepts


Find confusion patterns (rapid repeated changes)

Description

Find confusion patterns (rapid repeated changes)

Usage

find_confusion_patterns(events, window_seconds = 10, min_changes = 5)

Arguments

events

Telemetry events data frame

window_seconds

Time window in seconds

min_changes

Minimum changes to flag as confusion

Value

List of confusion patterns


Find sessions with delayed first interaction

Description

Find sessions with delayed first interaction

Usage

find_delayed_sessions(events, threshold_seconds = 30)

Arguments

events

Telemetry events data frame

threshold_seconds

Delay threshold in seconds

Value

List with delay statistics


Find error patterns in telemetry

Description

Find error patterns in telemetry

Usage

find_error_patterns(events, threshold_rate = 0.1)

Arguments

events

Telemetry events data frame

threshold_rate

Error rate threshold

Value

List of error patterns


Find navigation drop-offs or underused pages

Description

Find navigation drop-offs or underused pages

Usage

find_navigation_dropoffs(events, threshold = 0.2)

Arguments

events

Telemetry events data frame

threshold

Minimum visit rate threshold

Value

List of navigation issues


Find unused or under-used inputs

Description

Find unused or under-used inputs

Usage

find_unused_inputs(events, threshold = 0.05)

Arguments

events

Telemetry events data frame

threshold

Percentage threshold for considering input unused

Value

List of unused input information


Format field label based on output format

Description

Format field label based on output format

Usage

format_label(label, format, type = "field")

Arguments

label

Base label text

format

Output format ("markdown" or "text")

type

Label type ("header", "field", or "section")

Value

Formatted label string


Get accessibility recommendations for a given context

Description

Get accessibility recommendations for a given context

Usage

get_accessibility_recommendations(context = "", guidelines = NULL)

Arguments

context

Character string describing the interface context

guidelines

Optional custom accessibility guidelines

Value

Character vector of relevant accessibility recommendations


Generate Cognitive Load Theory suggestions

Description

Generate Cognitive Load Theory suggestions

Usage

get_cognitive_load_suggestions(chosen_layout, previous_stage)

Get bias mitigation strategies for concepts

Description

Get bias mitigation strategies for concepts

Usage

get_concept_bias_mappings(concepts, mappings = NULL)

Arguments

concepts

Character vector of concept names

mappings

Optional custom concept-bias mappings

Value

Data frame with relevant bias mappings


Internal function to get concepts data from external files

Description

Internal function to get concepts data from external files

Usage

get_concepts_data()

Value

A tibble with all BID framework concepts


Get default concepts data (fallback when external file unavailable)

Description

Get default concepts data (fallback when external file unavailable)

Usage

get_default_concepts_data()

Value

A tibble with default BID framework concepts


Get default layout mappings (fallback)

Description

Get default layout mappings (fallback)

Usage

get_default_layout_mappings()

Value

Data frame with default layout mappings


Get default theory mappings (fallback)

Description

Get default theory mappings (fallback)

Usage

get_default_theory_mappings()

Value

Data frame with default theory mappings


Generate Dual-Processing Theory suggestions

Description

Generate Dual-Processing Theory suggestions

Usage

get_dual_processing_suggestions(chosen_layout, previous_stage)

Generate generic suggestions for unrecognized concepts

Description

Generate generic suggestions for unrecognized concepts

Usage

get_generic_suggestions(concept, chosen_layout, previous_stage)

Generate Information Scent suggestions

Description

Generate Information Scent suggestions

Usage

get_information_scent_suggestions(chosen_layout, previous_stage)

Get concepts recommended for a layout

Description

Get concepts recommended for a layout

Usage

get_layout_concepts(layout, mappings = NULL)

Arguments

layout

Character string indicating layout type

mappings

Optional custom layout mappings

Value

Character vector of recommended concepts


Get metadata from bid_stage object

Description

Get metadata from bid_stage object

Usage

get_metadata(x)

Arguments

x

A bid_stage object

Value

List with metadata


Generate User Onboarding suggestions

Description

Generate User Onboarding suggestions

Usage

get_onboarding_suggestions(chosen_layout, previous_stage)

Generate Progressive Disclosure suggestions

Description

Generate Progressive Disclosure suggestions

Usage

get_progressive_disclosure_suggestions(chosen_layout, previous_stage)

Generate Principle of Proximity suggestions

Description

Generate Principle of Proximity suggestions

Usage

get_proximity_suggestions(chosen_layout, previous_stage)

Get stage name from bid_stage object

Description

Get stage name from bid_stage object

Usage

get_stage(x)

Arguments

x

A bid_stage object

Value

Character string with stage name


Generate Visual Hierarchy suggestions

Description

Generate Visual Hierarchy suggestions

Usage

get_visual_hierarchy_suggestions(chosen_layout, previous_stage)

Infer concepts from Stage 2 (Interpret) story elements

Description

Infer concepts from Stage 2 (Interpret) story elements

Usage

infer_concepts_from_story(previous_stage)

Arguments

previous_stage

Previous stage data

Value

Character vector of story-inferred concepts


Check if object is a bid_stage

Description

Check if object is a bid_stage

Usage

is_bid_stage(x)

Arguments

x

Object to test

Value

Logical indicating if object is bid_stage


Check if workflow is complete (has all 5 stages)

Description

Check if workflow is complete (has all 5 stages)

Usage

is_complete(x)

Arguments

x

A bid_result object

Value

Logical indicating if workflow is complete


Generate layout selection rationale

Description

Provides a concise explanation for why a particular layout was chosen based on the content analysis of the previous stage.

Usage

layout_rationale(previous_stage, chosen)

Arguments

previous_stage

A tibble or list output from an earlier BID stage

chosen

Character string with the chosen layout type

Value

Character string with explanation for the layout choice


Load accessibility guidelines

Description

Load accessibility guidelines

Usage

load_accessibility_guidelines(custom_guidelines = NULL)

Arguments

custom_guidelines

Optional custom guidelines data frame

Value

Data frame with accessibility guidelines


Load concept-bias mappings

Description

Load concept-bias mappings

Usage

load_concept_bias_mappings(custom_mappings = NULL)

Arguments

custom_mappings

Optional custom mappings data frame

Value

Data frame with concept-bias mappings


Load layout-concept mappings

Description

Load layout-concept mappings

Usage

load_layout_mappings(custom_mappings = NULL)

Arguments

custom_mappings

Optional custom mappings data frame

Value

Data frame with layout-concept mappings


Load theory mappings from external file or use defaults

Description

Load theory mappings from external file or use defaults

Usage

load_theory_mappings(custom_mappings = NULL)

Arguments

custom_mappings

Optional custom mappings data frame

Value

Data frame with theory mappings


Create a BID result collection object (internal constructor)

Description

Create a BID result collection object (internal constructor)

Usage

new_bid_result(stages)

Arguments

stages

List of bid_stage objects

Value

Object of class 'bid_result'


Create a BID stage result object (internal constructor)

Description

Create a BID stage result object (internal constructor)

Usage

new_bid_stage(stage, data, metadata = list())

Arguments

stage

Character string indicating the stage name

data

Tibble containing the stage data

metadata

List containing additional metadata

Value

Object of class 'bid_stage'


Normalize telemetry column names

Description

Normalize telemetry column names

Usage

normalize_telemetry_columns(events)

Arguments

events

Raw events data frame

Value

Normalized data frame


Print method for BID result objects

Description

Print method for BID result objects

Usage

## S3 method for class 'bid_result'
print(x, ...)

Arguments

x

A bid_result object

...

Additional arguments

Value

Returns the input bid_result object invisibly (class: c("bid_result", "list")). The method is called for its side effects: printing a workflow overview to the console showing completion status, stage progression, and key information from each completed BID stage. The invisible return supports method chaining while emphasizing the console summary output.


Print method for BID stage objects

Description

Print method for BID stage objects

Usage

## S3 method for class 'bid_stage'
print(x, ...)

Arguments

x

A bid_stage object

...

Additional arguments

Value

Returns the input bid_stage object invisibly (class: c("bid_stage", "tbl_df", "tbl", "data.frame")). The method is called for its side effects: printing a formatted summary of the BID stage to the console, including stage progress, key stage-specific information, and usage suggestions. The invisible return allows for method chaining while maintaining the primary purpose of console output.


Rank and sort suggestions within each group

Description

Rank and sort suggestions within each group

Usage

rank_and_sort_suggestions(groups, previous_stage, chosen_layout)

Arguments

groups

List of concept groups with suggestions

previous_stage

Previous stage data for scoring adjustments

chosen_layout

Selected layout type

Value

List of groups with ranked suggestions


Read telemetry data from file

Description

Read telemetry data from file

Usage

read_telemetry_data(path, format)

Arguments

path

File path

format

Format ("sqlite" or "json")

Value

Data frame of events


Read telemetry from JSON log file

Description

Read telemetry from JSON log file

Usage

read_telemetry_json(path)

Arguments

path

JSON log file path

Value

Data frame of events


Read telemetry from SQLite database

Description

Read telemetry from SQLite database

Usage

read_telemetry_sqlite(path)

Arguments

path

SQLite database path

Value

Data frame of events


Safely convert text to lowercase with null handling

Description

Helper function that safely converts text to lowercase while handling NULL, NA, and non-character values gracefully.

Usage

safe_lower(x)

Arguments

x

Input value to convert to lowercase string

Value

Character string in lowercase, or empty string if input is NULL/NA


Safe access to data_story elements from previous stage

Description

Safe access to data_story elements from previous stage

Usage

safe_stage_data_story_access(previous_stage, element)

Arguments

previous_stage

Previous stage data

element

Name of data_story element to access

Value

Character string or empty string if not found


Generate ranked, concept-grouped, actionable UI/UX suggestions

Description

Creates structured suggestions organized by UX concepts with specific component recommendations and rationales. Suggestions are ranked by relevance and grouped by concept for systematic implementation.

Usage

structure_suggestions(previous_stage, chosen_layout, concepts = NULL)

Arguments

previous_stage

A tibble or list output from an earlier BID stage

chosen_layout

Character string with the selected layout type

concepts

Optional character vector of additional concepts to include

Details

The function combines concepts from multiple sources:

Each suggestion includes:

Value

List of concept groups with ranked suggestions


Suggest layout based on previous stage content using heuristics

Description

Automatically suggests an appropriate layout type based on content analysis of previous BID stages. Uses deterministic heuristics to match keywords in problem descriptions, evidence, data story, and other contextual information to layout types that best address the identified issues.

Usage

suggest_layout_from_previous(previous_stage)

Arguments

previous_stage

A tibble or list output from an earlier BID stage function containing stage data with potential fields like problem, evidence, central_question, data_story, etc.

Details

The heuristics follow a priority order:

  1. breathable - if content suggests information overload, confusion, or cognitive load issues

  2. dual_process - if content mentions overview vs detail, quick vs deep, or two-mode interactions

  3. grid - if content focuses on grouping, clustering, visual hierarchy, or comparing related metrics

  4. card - if content mentions cards, chunks, tiles, modular blocks, or per-item summaries

  5. tabs - if content suggests sections, categories, progressive disclosure, but avoids tabs if telemetry shows tab drop-off

  6. breathable - fallback for any unmatched cases

Value

Character string indicating the suggested layout type ("breathable", "dual_process", "grid", "card", "tabs", or fallback)


Suggest theory based on problem and evidence using mappings

Description

Suggest theory based on problem and evidence using mappings

Usage

suggest_theory_from_mappings(problem, evidence = NULL, mappings = NULL)

Arguments

problem

Character string describing the problem

evidence

Optional character string with supporting evidence

mappings

Optional custom theory mappings

Value

Character string with suggested theory


Summary method for BID result objects

Description

Summary method for BID result objects

Usage

## S3 method for class 'bid_result'
summary(object, ...)

Arguments

object

A bid_result object

...

Additional arguments

Value

Returns the input bid_result object invisibly (class: c("bid_result", "list")). The method is called for its side effects: printing a detailed workflow analysis to the console including completion statistics, duration metrics, and comprehensive stage-by-stage breakdowns with key data from each BID framework stage. The invisible return facilitates method chaining while focusing on comprehensive console reporting.


Summary method for BID stage objects

Description

Summary method for BID stage objects

Usage

## S3 method for class 'bid_stage'
summary(object, ...)

Arguments

object

A bid_stage object

...

Additional arguments

Value

Returns the input bid_stage object invisibly (class: c("bid_stage", "tbl_df", "tbl", "data.frame")). The method is called for its side effects: printing a comprehensive summary to the console including stage metadata, all non-empty data columns, and timestamp information. The invisible return enables method chaining while prioritizing the detailed console output display.


Validate BID result object

Description

Validate BID result object

Usage

validate_bid_result(x)

Arguments

x

Object to validate

Value

TRUE if valid, throws error otherwise


Validate BID stage object

Description

Validate BID stage object

Usage

validate_bid_stage(x)

Arguments

x

Object to validate

Value

TRUE if valid, throws error otherwise