plugin-barchart-button-response

README.md

@@ -52,6 +52,7 @@ Plugin | Contributor | Description
 [video-several-keyboard-responses](https://github.com/jspsych/jspsych-contrib/blob/main/packages/plugin-video-several-keyboard-responses/README.md) | [Maria Emine Nylund](https://github.com/marianylund) | jsPsych plugin for playing a video file and getting several keyboard responses 
 [vsl-animate-occlusion](https://github.com/jspsych/jspsych-contrib/blob/main/packages/plugin-vsl-animate-occlusion/README.md) | [Josh de Leeuw](https://github.com/jodeleeuw) | he VSL (visual statistical learning) animate occlusion plugin displays an animated sequence of shapes that disappear behind an occluding rectangle while they change from one shape to another. 
 [vsl-grid-scene](https://github.com/jspsych/jspsych-contrib/blob/main/packages/plugin-vsl-grid-scene/README.md) | [Josh de Leeuw](https://github.com/jodeleeuw) | The VSL (visual statistical learning) grid scene plugin displays images arranged in a grid. 
+[barchart-button-response](https://github.com/jspsych/jspsych-contrib/blob/main/packages/plugin-vsl-grid-scene/README.md) | [Courtney B. Hilton](https://github.com/courtney-bryce-hilton) | This plugin displays an interactive barchart to the participant.
 
 
 ### Extensions

packages/plugin-barchart-button-response/CITATION.cff

@@ -0,0 +1,40 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+  - family-names: "Courtney B. Hilton" # Replace with last name
+    given-names: "Courtney B. Hilton" # Replace with first name
+    name-particle: "Courtney B. Hilton" # Replace with name particle(s)
+    orcid: "https://orcid.org/0000-0000-0000-0000" # Replace with ORCID
+# More  authors can be listed here in the same format as above
+contact: # Contact person for this extension
+  - family-names: "Courtney B. Hilton"
+    given-names: "Courtney B. Hilton"
+    email: "{email}" # Replace with contact person's email
+    orcid: "https://orcid.org/0000-0000-0000-0000" # Replace with contact person's ORCID
+title: "jsPsychPluginBarchartButtonResponse"
+version: 0.0.0
+doi: 10.5281/zenodo.1234 # Replace with DOI
+date-released: 2000-01-01
+url: "{softwareUrl}" # Replace with URL to this extension
+
+# If you wish to cite a paper on this extension instead, you can use the following template:
+preferred-citation:
+  authors:
+    - family-names: "Courtney B. Hilton"
+      given-names: "Courtney B. Hilton"
+      name-particle: "Courtney B. Hilton"
+      orcid: "https://orcid.org/0000-0000-0000-0000"
+  # More authors can be listed here in the same format as above
+  date-published: 2023-05-11
+  doi: 10.21105/joss.12345
+  issn: 1234-5678
+  issue: 01
+  journal: Journal for Open Source Software
+  publisher:
+    name: Open Journals
+  start: 0001
+  title: "{title}"
+  type: article # Other options include: book, pamphlet, conference-paper...
+  url: "{linkToPublicationInJournal}"
+  volume: 1
+# More information on the preffered-citation CFF format can be found at https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files#citing-something-other-than-software

packages/plugin-barchart-button-response/README.md

@@ -0,0 +1,115 @@
+# plugin-barchart-button-response
+
+## Overview
+
+The `barchart-button-response` plugin displays a bar chart and records responses generated by a button click. The chart can be displayed until a response is given, or for a pre-determined amount of time. The trial can be ended automatically if the participant does not respond within a fixed length of time. The buttons themselves can be customized using HTML formatting.
+
+The bar chart stimulus is generated from an array of objects, where each object should contain a numeric `value` (used for the y-axis) and a string `key` (used for the x-axis label). One of the bars can optionally be highlighted in a distinct color and annotated with a text label.
+
+This plugin uses [Chart.js](https://www.chartjs.org/) under the hood, and supports features like axis labeling, legend display, and percentage formatting on the y-axis.
+
+---
+
+## Loading (Note: these CDN resources don't currently exist... but maybe will eventually?)
+
+Using the CDN-hosted JavaScript file:
+
+```js
+<script src="https://unpkg.com/@jspsych/plugin-barchart-button-response@VERSION_HERE"></script>
+```
+
+Using the JavaScript file downloaded from a GitHub release dist archive:
+
+```js
+<script src="jspsych/plugin-barchart-button-response.js"></script>
+```
+
+Using NPM:
+
+```
+npm install @jspsych/plugin-barchart-button-response
+```
+
+```js
+import jsPsychBarchartButtonresponse from "@jspsych/plugin-barchart-button-response";
+```
+
+## Compatibility
+
+- jsPsych version: **v8.0.0 or later**
+
+---
+
+## Parameters
+
+| Name               | Type             | Default       | Description                                                                                            |
+| ------------------ | ---------------- | ------------- | ------------------------------------------------------------------------------------------------------ |
+| `description_text` | HTML string      | `undefined`   | Optional text shown above the chart for instructions or context.                                       |
+| `chart_data`       | Array of objects | `undefined`   | Required data for the chart. Each object must have a `key` (x-axis label) and `value` (y-axis height). |
+| `base_color`       | String (color)   | `"#02c39a80"` | Color for non-highlighted bars.                                                                        |
+| `highlight_value`  | String           | `undefined`   | The `key` of the bar to be visually highlighted.                                                       |
+| `highlight_color`  | String (color)   | `"#fee44080"` | Color used for the highlighted bar.                                                                    |
+| `highlight_label`  | String           | `undefined`   | Label text shown above the highlighted bar.                                                            |
+| `x_axis_label`     | String           | `""`          | Text label for the x-axis.                                                                             |
+| `y_axis_label`     | String           | `""`          | Text label for the y-axis.                                                                             |
+| `y_percent`        | Boolean          | `false`       | Whether to format y-axis values as percentages (0–1 → 0–100%).                                         |
+| `show_legend`      | Boolean          | `false`       | Whether to display a legend showing the highlight label.                                               |
+| `choices`          | Array of strings | `undefined`   | Labels for the response buttons.                                                                       |
+| `button_html`      | Function         | _(see below)_ | Function that returns HTML for each response button.                                                   |
+
+**Default `button_html` function:**
+
+```ts
+(choice: string, choice_index: number) =>
+  `<button class="jspsych-btn">${choice}</button>`;
+```
+
+---
+
+## Data Generated
+
+The following data is stored for each trial:
+
+| Name       | Type    | Description                                                     |
+| ---------- | ------- | --------------------------------------------------------------- |
+| `rt`       | Integer | Response time in milliseconds from trial start to button click. |
+| `response` | Integer | Index (0-based) of the selected button in the `choices` array.  |
+
+---
+
+## Example
+
+```js
+const trial = {
+  type: "barchart-button-response",
+  description_text: "<p>Which bar is the highest?</p>",
+  chart_data: [
+    { key: "A", value: 0.4 },
+    { key: "B", value: 0.6 },
+    { key: "C", value: 0.2 },
+  ],
+  highlight_value: "B",
+  highlight_label: "Target",
+  base_color: "#cccccc",
+  highlight_color: "#ff9999",
+  x_axis_label: "Category",
+  y_axis_label: "Proportion",
+  y_percent: true,
+  show_legend: true,
+  choices: ["A", "B", "C"],
+};
+```
+
+---
+
+## Notes
+
+- If both `grid_rows` and `grid_columns` are `null` and `button_layout` is `"grid"`, an error will be thrown. One must be specified.
+- The plugin currently assumes static size for the chart canvas. You can customize via CSS or extend the `createChartContainer()` logic.
+
+---
+
+## Author / Citation
+
+[Courtney B. Hilton](https://github.com/courtney-bryce-hilton)  
+If you use this plugin in your research, please cite the corresponding repository or paper when available.

packages/plugin-barchart-button-response/docs/plugin-barchart-button-response.md

@@ -0,0 +1,115 @@
+# plugin-barchart-button-response
+
+## Overview
+
+The `barchart-button-response` plugin displays a bar chart and records responses generated by a button click. The chart can be displayed until a response is given, or for a pre-determined amount of time. The trial can be ended automatically if the participant does not respond within a fixed length of time. The buttons themselves can be customized using HTML formatting.
+
+The bar chart stimulus is generated from an array of objects, where each object should contain a numeric `value` (used for the y-axis) and a string `key` (used for the x-axis label). One of the bars can optionally be highlighted in a distinct color and annotated with a text label.
+
+This plugin uses [Chart.js](https://www.chartjs.org/) under the hood, and supports features like axis labeling, legend display, and percentage formatting on the y-axis.
+
+---
+
+## Loading (Note: these CDN resources don't currently exist... but maybe will eventually?)
+
+Using the CDN-hosted JavaScript file:
+
+```js
+<script src="https://unpkg.com/@jspsych/plugin-barchart-button-response@VERSION_HERE"></script>
+```
+
+Using the JavaScript file downloaded from a GitHub release dist archive:
+
+```js
+<script src="jspsych/plugin-barchart-button-response.js"></script>
+```
+
+Using NPM:
+
+```
+npm install @jspsych/plugin-barchart-button-response
+```
+
+```js
+import jsPsychBarchartButtonresponse from "@jspsych/plugin-barchart-button-response";
+```
+
+## Compatibility
+
+- jsPsych version: **v8.0.0 or later**
+
+---
+
+## Parameters
+
+| Name               | Type             | Default       | Description                                                                                            |
+| ------------------ | ---------------- | ------------- | ------------------------------------------------------------------------------------------------------ |
+| `description_text` | HTML string      | `undefined`   | Optional text shown above the chart for instructions or context.                                       |
+| `chart_data`       | Array of objects | `undefined`   | Required data for the chart. Each object must have a `key` (x-axis label) and `value` (y-axis height). |
+| `base_color`       | String (color)   | `"#02c39a80"` | Color for non-highlighted bars.                                                                        |
+| `highlight_value`  | String           | `undefined`   | The `key` of the bar to be visually highlighted.                                                       |
+| `highlight_color`  | String (color)   | `"#fee44080"` | Color used for the highlighted bar.                                                                    |
+| `highlight_label`  | String           | `undefined`   | Label text shown above the highlighted bar.                                                            |
+| `x_axis_label`     | String           | `""`          | Text label for the x-axis.                                                                             |
+| `y_axis_label`     | String           | `""`          | Text label for the y-axis.                                                                             |
+| `y_percent`        | Boolean          | `false`       | Whether to format y-axis values as percentages (0–1 → 0–100%).                                         |
+| `show_legend`      | Boolean          | `false`       | Whether to display a legend showing the highlight label.                                               |
+| `choices`          | Array of strings | `undefined`   | Labels for the response buttons.                                                                       |
+| `button_html`      | Function         | _(see below)_ | Function that returns HTML for each response button.                                                   |
+
+**Default `button_html` function:**
+
+```ts
+(choice: string, choice_index: number) =>
+  `<button class="jspsych-btn">${choice}</button>`;
+```
+
+---
+
+## Data Generated
+
+The following data is stored for each trial:
+
+| Name       | Type    | Description                                                     |
+| ---------- | ------- | --------------------------------------------------------------- |
+| `rt`       | Integer | Response time in milliseconds from trial start to button click. |
+| `response` | Integer | Index (0-based) of the selected button in the `choices` array.  |
+
+---
+
+## Example
+
+```js
+const trial = {
+  type: "barchart-button-response",
+  description_text: "<p>Which bar is the highest?</p>",
+  chart_data: [
+    { key: "A", value: 0.4 },
+    { key: "B", value: 0.6 },
+    { key: "C", value: 0.2 },
+  ],
+  highlight_value: "B",
+  highlight_label: "Target",
+  base_color: "#cccccc",
+  highlight_color: "#ff9999",
+  x_axis_label: "Category",
+  y_axis_label: "Proportion",
+  y_percent: true,
+  show_legend: true,
+  choices: ["A", "B", "C"],
+};
+```
+
+---
+
+## Notes
+
+- If both `grid_rows` and `grid_columns` are `null` and `button_layout` is `"grid"`, an error will be thrown. One must be specified.
+- The plugin currently assumes static size for the chart canvas. You can customize via CSS or extend the `createChartContainer()` logic.
+
+---
+
+## Author / Citation
+
+[Courtney B. Hilton](https://github.com/courtney-bryce-hilton)  
+If you use this plugin in your research, please cite the corresponding repository or paper when available.

packages/plugin-barchart-button-response/examples/index.html

@@ -0,0 +1,35 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>jsPsychPluginBarchartButtonResponse Example</title>
+    <script src="https://unpkg.com/jspsych@8"></script>
+    <!-- Load the published plugin package here, e.g.
+    <script src="https://unpkg.com/plugin-barchart-button-response"></script>-->
+    <script src="../dist/index.browser.js"></script>
+    <link rel="stylesheet" href="https://unpkg.com/jspsych@8/css/jspsych.css" />
+  </head>
+
+  <body></body>
+  <script>
+    const jsPsych = initJsPsych();
+
+    const trial = {
+      type: jsPsychPluginBarchartButtonResponse,
+      description_text: "<h3>Which animal is most popular?</h3>",
+      chart_data: [
+        { key: "Cat", value: 0.1 },
+        { key: "Dog", value: 0.15 },
+        { key: "Bird", value: 0.5 },
+        { key: "Dinosaur", value: 0.25 },
+      ],
+      highlight_value: "Dog",
+      highlight_label: "Your Choice!",
+      x_axis_label: "Animals",
+      y_axis_label: "% People Prefer",
+      y_percent: true,
+      choices: ["Next"],
+    };
+
+    jsPsych.run([trial]);
+  </script>
+</html>

packages/plugin-barchart-button-response/jest.config.cjs

@@ -0,0 +1 @@
+module.exports = require("@jspsych/config/jest").makePackageConfig(__dirname);