jspsych · DomDaSquishyBomb · Sep 24, 2025 · Sep 30, 2025
diff --git a/.changeset/f8b73f8c-new-plugin.md b/.changeset/f8b73f8c-new-plugin.md
@@ -0,0 +1,5 @@
+---
+"plugin-snap-sort": major
+---
+
+Adds new snap-sort plugin for drag-and-drop sorting with ordered placement boxes. This plugin extends the free sort functionality by requiring items to be sorted into predefined ordered containers.
diff --git a/packages/plugin-snap-sort/.turbo/turbo-build.log b/packages/plugin-snap-sort/.turbo/turbo-build.log
@@ -0,0 +1,17 @@
+
+> [email protected] build
+> rollup --config
+
+[1G[0K[36m
+[1msrc/index.ts[22m → [1mdist/index.d.ts[22m...[39m
+[32mcreated [1mdist/index.d.ts[22m in [1m957ms[22m[39m
+[36m
+[1msrc/index.ts[22m → [1mdist/index.js, dist/index.cjs[22m...[39m
+[32mcreated [1mdist/index.js, dist/index.cjs[22m in [1m114ms[22m[39m
+[36m
+[1msrc/index.ts[22m → [1mdist/index.browser.js[22m...[39m
+[32mcreated [1mdist/index.browser.js[22m in [1m34ms[22m[39m
+[36m
+[1msrc/index.ts[22m → [1mdist/index.browser.min.js[22m...[39m
+[32mcreated [1mdist/index.browser.min.js[22m in [1m38ms[22m[39m
+[1G[0K⠙[1G[0K
diff --git a/packages/plugin-snap-sort/CITATION.cff b/packages/plugin-snap-sort/CITATION.cff
@@ -0,0 +1,39 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "snap-sort"
+version: "1.0.0"
+date-released: "2025-05-15"
+
+authors:
+- family-names: "Dercon"  # Replace with last name
+  given-names: "Quentin"   # Replace with first name
+  name-particle: "" # Replace with name particle(s)
+  orcid: "https://orcid.org/0000-0001-8264-347X"  # Replace with ORCID
+
+- family-names: "Harsch"  # Replace with last name
+  given-names: "Rina"   # Replace with first name
+  name-particle: "" # Replace with name particle(s)
+  orcid: "https://orcid.org/0000-0002-6314-4904"  # Replace with ORCID
+
+- family-names: "Le"  # Replace with last name
+  given-names: "Dominic"   # Replace with first name
+  name-particle: "" # Replace with name particle(s)
+  orcid: "https://orcid.org/0009-0000-4273-1379"  # Replace with ORCID
+
+- family-names: "Yasuda"  # Replace with last name
+  given-names: "Shannon"   # Replace with first name
+  name-particle: "" # Replace with name particle(s)
+  orcid: "https://orcid.org/0000-0002-4379-8150"  # Replace with ORCID
+
+- family-names: "Chang"  # Replace with last name
+  given-names: "Cherrie"   # Replace with first name
+  name-particle: "" # Replace with name particle(s)
+  orcid: "https://orcid.org/0000-0000-0000-0000"  # Replace with ORCID
+
+- family-names: "Struhl"  # Replace with last name
+  given-names: "Melissa"   # Replace with first name
+  name-particle: "" # Replace with name particle(s)
+  orcid: "https://orcid.org/0000-0003-2217-9331"  # Replace with ORCID
+
+
+# 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
diff --git a/packages/plugin-snap-sort/README.md b/packages/plugin-snap-sort/README.md
@@ -0,0 +1,21 @@
+# plugin-snap-sort
+
+## Overview
+
+The free sort core plugin, but the images have to be sorted by placing into ordered boxes.
+
+## Loading
+
+*Enter instructions for loading the plugin package here.*
+
+## Compatibility
+
+`plugin-snap-sort` requires jsPsych v8.0.0 or later.
+
+## Documentation
+
+See [documentation](/packages/plugin-snap-sort/README.md)
+
+## Author / Citation
+
+[Cherrie Chang](https://github.com/cherriechang) 
diff --git a/packages/plugin-snap-sort/assets/blue-rec.png b/packages/plugin-snap-sort/assets/blue-rec.png
diff --git a/packages/plugin-snap-sort/assets/free_sort_ordered_plugin-example_stimuli.ai b/packages/plugin-snap-sort/assets/free_sort_ordered_plugin-example_stimuli.ai
diff --git a/packages/plugin-snap-sort/assets/green-circle.png b/packages/plugin-snap-sort/assets/green-circle.png
diff --git a/packages/plugin-snap-sort/assets/green-rec.png b/packages/plugin-snap-sort/assets/green-rec.png
diff --git a/packages/plugin-snap-sort/assets/green-square.png b/packages/plugin-snap-sort/assets/green-square.png
diff --git a/packages/plugin-snap-sort/assets/green-triangle.png b/packages/plugin-snap-sort/assets/green-triangle.png
diff --git a/packages/plugin-snap-sort/assets/index.html b/packages/plugin-snap-sort/assets/index.html
@@ -0,0 +1,50 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>jsPsychPluginFreeSortOrdered Example</title>
+    <script src="https://unpkg.com/jspsych"></script>
+    <script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
+    <!-- Load the published plugin package here, e.g.
+<script src="https://unpkg.com/plugin-snap-sort"></script>
+<script src="../dist/index.browser.js"></script> -->
+    <script src="../dist/index.browser.js"></script>
+    <link rel="stylesheet" href="https://unpkg.com/jspsych/css/jspsych.css" />
+    <link rel="stylesheet" href="../src/styles.css" />
+  </head>
+
+  <body></body>
+  <script>
+    const jsPsych = initJsPsych({
+      on_finish: function() {
+        jsPsych.data.displayData();
+      }
+    });
+
+    const trial = {
+      type: jsPsychPluginFreeSortOrdered,
+      stimulus: [
+        '../assets/blue-rec.png',
+        '../assets/green-rec.png',
+        '../assets/red-rec.png',
+        '../assets/blue-rec.png',
+        '../assets/green-rec.png',
+      ],
+      stim_height: 100,
+      stim_width: 120,
+      scale_factor: 1.1,
+      holding_area_height: 400,
+      holding_area_width: 1000,
+      box_colors: ["#0271bc", "#3ab54b", "#FF0000", "#0271bc", "#3ab54b"],
+      check_correct_order: true,
+      allow_multiple: true,
+      box_margin: 30,
+      snap_margin: 15,
+      prompt: 'Drag and drop the boxes to sort them in order.',
+      prompt_location: 'above',
+      button_label: 'Continue',
+      include_counter: true,
+    };
+
+    jsPsych.run([trial])
+  </script>
+</html>
diff --git a/packages/plugin-snap-sort/assets/orange-circle.png b/packages/plugin-snap-sort/assets/orange-circle.png
diff --git a/packages/plugin-snap-sort/assets/orange-square.png b/packages/plugin-snap-sort/assets/orange-square.png
diff --git a/packages/plugin-snap-sort/assets/orange-triangle.png b/packages/plugin-snap-sort/assets/orange-triangle.png
diff --git a/packages/plugin-snap-sort/assets/purple-circle.png b/packages/plugin-snap-sort/assets/purple-circle.png
diff --git a/packages/plugin-snap-sort/assets/purple-square.png b/packages/plugin-snap-sort/assets/purple-square.png
diff --git a/packages/plugin-snap-sort/assets/purple-triangle.png b/packages/plugin-snap-sort/assets/purple-triangle.png
diff --git a/packages/plugin-snap-sort/assets/red-rec.png b/packages/plugin-snap-sort/assets/red-rec.png
diff --git a/packages/plugin-snap-sort/docs/plugin-free-sort-ordered.md b/packages/plugin-snap-sort/docs/plugin-free-sort-ordered.md
@@ -0,0 +1,33 @@
+# plugin-snap-sort
+
+The free sort core plugin, but the images have to be sorted by placing into ordered boxes.
+
+## Parameters
+
+In addition to the [parameters available in all plugins](https://www.jspsych.org/latest/overview/plugins#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of undefined must be specified. Other parameters can be left unspecified if the default value is acceptable.
+
+| Parameter           | Type             | Default Value      | Description                              |
+| ------------------- | ---------------- | ------------------ | ---------------------------------------- |
+|                     |                  |                    |                                          |
+
+## Data Generated
+
+In addition to the [default data collected by all plugins](https://www.jspsych.org/latest/overview/plugins#data-collected-by-all-plugins), this plugin collects the following data for each trial.
+
+| Name      | Type    | Value                                    |
+| --------- | ------- | ---------------------------------------- |
+|           |         |                                          |
+
+## Install
+
+*Enter instructions for installing the plugin package here.*
+
+## Examples
+
+### Title of Example
+
+```javascript
+var trial = {
+  type: jsPsychPluginFreeSortOrdered
+}
+```
diff --git a/packages/plugin-snap-sort/examples/index.html b/packages/plugin-snap-sort/examples/index.html
@@ -0,0 +1,143 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>jsPsychPluginFreeSortOrdered Example</title>
+    <script src="https://unpkg.com/jspsych"></script>
+    <script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
+    <!-- Load the published plugin package here, e.g.
+<script src="https://unpkg.com/plugin-snap-sort"></script>
+<script src="../dist/index.browser.js"></script> -->
+    <script src="../dist/index.browser.js"></script>
+    <link rel="stylesheet" href="https://unpkg.com/jspsych/css/jspsych.css" />
+    <link rel="stylesheet" href="../src/styles.css" />
+  </head>
+
+  <body></body>
+  <script>
+    const jsPsych = initJsPsych({
+      on_finish: function() {
+        jsPsych.data.displayData();
+      }
+    });
+
+    const trial1 = {
+      type: jsPsychPluginFreeSortOrdered,
+      stimulus: [
+        {id: 0, file: '../assets/blue-rec.png', height: 100, width: 200},
+        {id: 1, file: '../assets/green-rec.png', height: 100, width: 200},
+        {id: 2, file: '../assets/red-rec.png', height: 100, width: 200}
+      ],
+      stim_height: 100,
+      stim_width: 120,
+      scale_factor: 1.1,
+      boxes: [
+        {id: 0, color: '#0271bc', height: 100, width: 200},
+        {id: 1, color: '#3ab54b', height: 100, width: 200},
+        {id: 2, color: '#FF0000', height: 100, width: 200}
+      ],
+      use_correctness: true,
+      correctness_by: "color",
+      box_margin: 40,
+      snap_margin: 20,
+      prompt: 'Drag and drop the boxes to sort them in order.',
+      prompt_location: 'above',
+      button_label: 'Continue',
+      include_counter: true,
+    };
+
+    const trial2 = {
+      type: jsPsychPluginFreeSortOrdered,
+      prompt: 'This is a template trial, we can make lots of variations to see how this plugin can function!',
+      scale_factor: 1.1,
+      holding_area_height: 400,
+      holding_area_width: 800,
+      box_margin: 40,
+      snap_margin: 20,
+      prompt_location: 'above',
+      button_label: 'Continue',
+      include_counter: false,
+      stimulus: [
+        {id: 0, file: '../assets/blue-rec.png', height: 100, width: 200},
+        {id: 1, file: '../assets/blue-rec.png', height: 100, width: 200},
+        {id: 2, file: '../assets/blue-rec.png', height: 100, width: 200}
+      ],
+      stim_height: 100, 
+      <!--Debug note! If you dont include these stim height and width parameters, you get bad box clicking behavior-->
+      stim_width: 120,
+      boxes: [
+        {id: 0, colour: '#0271bc', height: 100, width: 200},
+        {id: 1, colour: '#3ab54b', height: 100, width: 200},
+        {id: 2, colour: '#FF0000', height: 100, width: 200}
+      ],
+      use_correctness: false
+
+    };
+
+
+    const trial10 = {
+      type: jsPsychPluginFreeSortOrdered,
+      prompt: 'WONT WORK YET. This is a trial with a correct answer. You have to put all of the green shapes in the single box before you can move on.',
+      scale_factor: 1.1,
+      holding_area_height: 400,
+      holding_area_width: 800,
+      box_margin: 40,
+      snap_margin: 20,
+      prompt_location: 'above',
+      button_label: 'Continue',
+      include_counter: false,
+      stimulus: [
+        {id: 0, file: '../assets/green-circle.png', height: 100, width: 100},
+        {id: 0, file: '../assets/green-triangle.png', height: 100, width: 100},
+        {id: 0, file: '../assets/green-square.png', height: 100, width: 100},
+        {id: 1, file: '../assets/orange-circle.png', height: 100, width: 100},
+        {id: 1, file: '../assets/purple-triangle.png', height: 100, width: 100},
+        {id: 1, file: '../assets/purple-square.png', height: 100, width: 100}
+      ],
+      stim_height: 100, 
+      stim_width: 120,
+      boxes: [
+        {id: 0, colour: '#0271bc', height: 100, width: 200}
+      ],
+      use_correctness: true,
+      correctness_by: 'id',
+      use_criteria: true,
+      criteria: 'exact_correct_answers',
+      show_button: 'on_criteria'
+    };
+
+    const trial11 = {
+      type: jsPsychPluginFreeSortOrdered,
+      prompt: 'WONT WORK YET. Put the circles in the red box, the triangles in the blue box, and the squares in the green box. The trial will advance automatically once you put the last shape in the boxes, even if the answer is wrong.',
+      scale_factor: 1.1,
+      holding_area_height: 400,
+      holding_area_width: 800,
+      box_margin: 40,
+      snap_margin: 20,
+      prompt_location: 'above',
+      button_label: 'Continue',
+      include_counter: false,
+      stimulus: [
+        {id: 0, file: '../assets/green-circle.png', height: 100, width: 100},
+        {id: 1, file: '../assets/green-triangle.png', height: 100, width: 100},
+        {id: 2, file: '../assets/green-square.png', height: 100, width: 100},
+        {id: 0, file: '../assets/orange-circle.png', height: 100, width: 100},
+        {id: 1, file: '../assets/purple-triangle.png', height: 100, width: 100},
+        {id: 2, file: '../assets/purple-square.png', height: 100, width: 100}
+      ],
+      stim_height: 100, 
+      stim_width: 120,
+      boxes: [
+        {id: 0, colour: 'Red', height: 100, width: 200},
+        {id: 1, colour: 'Blue', height: 100, width: 200},
+        {id: 2, colour: 'Green', height: 100, width: 200}
+      ],
+      use_correctness: false,
+      use_criteria: true,
+      criteria: 'all_items_sorted',
+      response_ends_trial: true 
+    };
+
+
+    jsPsych.run([trial1, trial2])
+  </script>
+</html>