bead 0.1.0__py3-none-any.whl

bead/deployment/jspsych/src/plugins/cloze-dropdown.ts

@@ -0,0 +1,252 @@
+/**
+ * bead-cloze-multi plugin
+ *
+ * jsPsych plugin for fill-in-the-blank tasks with multiple gaps.
+ *
+ * Features:
+ * - Multiple gaps in text
+ * - Dropdown (extensional constraints)
+ * - Text input (intensional constraints or free text)
+ * - Mixed field types
+ * - Per-gap response time tracking
+ * - Material Design form controls
+ * - Preserves all item and template metadata
+ *
+ * @author Bead Project
+ * @version 0.1.0
+ */
+
+import type { JsPsych, JsPsychPlugin, PluginInfo } from "../types/jspsych.js";
+
+/** Field type for cloze fields */
+type ClozeFieldType = "dropdown" | "text";
+
+/** Unfilled slot from bead metadata */
+interface UnfilledSlot {
+  slot_name: string;
+  position: number;
+  constraint_ids: string[];
+}
+
+/** Field configuration for cloze task */
+export interface ClozeFieldConfig {
+  slot_name?: string;
+  position?: number;
+  type: ClozeFieldType;
+  options?: string[];
+  placeholder?: string;
+}
+
+/** Bead item/template metadata */
+interface BeadMetadata {
+  unfilled_slots?: UnfilledSlot[];
+  [key: string]: unknown;
+}
+
+/** Cloze trial parameters */
+export interface ClozeTrialParams {
+  /** The text with gaps (use %% or {{slot_name}} for gaps) */
+  text: string | null;
+  /** Field configurations (auto-generated from unfilled_slots) */
+  fields: ClozeFieldConfig[];
+  /** Whether to require all fields to be filled */
+  require_all: boolean;
+  /** Text for the continue button */
+  button_label: string;
+  /** Complete item and template metadata */
+  metadata: BeadMetadata;
+}
+
+/** Per-field responses */
+type ClozeResponses = Record<string, string>;
+
+/** Per-field response times */
+type ClozeResponseTimes = Record<string, number>;
+
+/** Per-field start times */
+type FieldStartTimes = Record<string, number>;
+
+/** Plugin info constant */
+const info: PluginInfo = {
+  name: "bead-cloze-multi",
+  parameters: {
+    text: {
+      type: 8, // ParameterType.HTML_STRING
+      default: null,
+    },
+    fields: {
+      type: 13, // ParameterType.COMPLEX
+      default: [],
+      array: true,
+    },
+    require_all: {
+      type: 0, // ParameterType.BOOL
+      default: true,
+    },
+    button_label: {
+      type: 1, // ParameterType.STRING
+      default: "Continue",
+    },
+    metadata: {
+      type: 12, // ParameterType.OBJECT
+      default: {},
+    },
+  },
+};
+
+/**
+ * BeadClozeMultiPlugin - jsPsych plugin for fill-in-the-blank tasks
+ */
+class BeadClozeMultiPlugin implements JsPsychPlugin<typeof info, ClozeTrialParams> {
+  static info = info;
+
+  private jsPsych: JsPsych;
+
+  constructor(jsPsych: JsPsych) {
+    this.jsPsych = jsPsych;
+  }
+
+  trial(display_element: HTMLElement, trial: ClozeTrialParams): void {
+    const responses: ClozeResponses = {};
+    const response_times: ClozeResponseTimes = {};
+    const field_start_times: FieldStartTimes = {};
+
+    const start_time = performance.now();
+
+    // Auto-generate fields from metadata if not provided
+    if (trial.fields.length === 0 && trial.metadata.unfilled_slots) {
+      trial.fields = trial.metadata.unfilled_slots.map((slot) => ({
+        slot_name: slot.slot_name,
+        position: slot.position,
+        type: (slot.constraint_ids.length > 0 ? "dropdown" : "text") as ClozeFieldType,
+        options: [], // Would be populated from constraints in real implementation
+        placeholder: slot.slot_name,
+      }));
+    }
+
+    // Generate HTML
+    let html = '<div class="bead-cloze-container">';
+
+    if (trial.text) {
+      // Replace gaps with input fields
+      let processed_text = trial.text;
+      trial.fields.forEach((field, index) => {
+        const field_id = `bead-cloze-field-${index}`;
+        let field_html: string;
+
+        if (field.type === "dropdown" && field.options && field.options.length > 0) {
+          // Dropdown field
+          const optionsHtml = field.options
+            .map((opt) => `<option value="${opt}">${opt}</option>`)
+            .join("");
+          field_html = `
+            <select class="bead-dropdown bead-cloze-field" id="${field_id}" data-field="${index}">
+              <option value="">Select...</option>
+              ${optionsHtml}
+            </select>
+          `;
+        } else {
+          // Text input field
+          field_html = `
+            <input type="text"
+                   class="bead-text-field bead-cloze-field"
+                   id="${field_id}"
+                   data-field="${index}"
+                   placeholder="${field.placeholder ?? ""}" />
+          `;
+        }
+
+        // Replace placeholder in text
+        const placeholder = field.slot_name ? `{{${field.slot_name}}}` : "%%";
+        processed_text = processed_text.replace(placeholder, field_html);
+      });
+
+      html += `<div class="bead-cloze-text">${processed_text}</div>`;
+    }
+
+    // Continue button
+    html += `
+      <div class="bead-cloze-button-container">
+        <button class="bead-button bead-continue-button" id="bead-cloze-continue" ${trial.require_all ? "disabled" : ""}>
+          ${trial.button_label}
+        </button>
+      </div>
+    `;
+
+    html += "</div>"; // Close container
+
+    display_element.innerHTML = html;
+
+    // Add event listeners for input fields
+    const input_fields = display_element.querySelectorAll<HTMLInputElement | HTMLSelectElement>(
+      ".bead-cloze-field",
+    );
+    for (const field of input_fields) {
+      const field_index = field.getAttribute("data-field");
+      if (field_index === null) continue;
+
+      // Track when user starts interacting with this field
+      field.addEventListener("focus", () => {
+        if (field_start_times[field_index] === undefined) {
+          field_start_times[field_index] = performance.now();
+        }
+      });
+
+      // Track responses
+      field.addEventListener("change", () => {
+        responses[field_index] = field.value;
+
+        // Record response time for this field
+        const startTime = field_start_times[field_index];
+        if (startTime !== undefined) {
+          response_times[field_index] = performance.now() - startTime;
+        }
+
+        check_completion();
+      });
+
+      field.addEventListener("input", () => {
+        responses[field_index] = field.value;
+        check_completion();
+      });
+    }
+
+    // Continue button listener
+    const continue_button =
+      display_element.querySelector<HTMLButtonElement>("#bead-cloze-continue");
+    if (continue_button) {
+      continue_button.addEventListener("click", () => {
+        end_trial();
+      });
+    }
+
+    const check_completion = (): void => {
+      if (trial.require_all && continue_button) {
+        // Check if all fields are filled
+        const all_filled = trial.fields.every((_field, index) => {
+          const response = responses[index.toString()];
+          return response !== undefined && response.trim() !== "";
+        });
+        continue_button.disabled = !all_filled;
+      }
+    };
+
+    const end_trial = (): void => {
+      // Gather all responses
+      const trial_data: Record<string, unknown> = {
+        ...trial.metadata, // Preserve all metadata
+        responses: responses,
+        response_times: response_times,
+        total_rt: performance.now() - start_time,
+      };
+
+      // Clear display
+      display_element.innerHTML = "";
+
+      // End trial
+      this.jsPsych.finishTrial(trial_data);
+    };
+  }
+}
+
+export { BeadClozeMultiPlugin };

bead/deployment/jspsych/src/plugins/forced-choice.ts

@@ -0,0 +1,265 @@
+/**
+ * bead-forced-choice plugin
+ *
+ * jsPsych plugin for comparative judgments and forced choice tasks.
+ *
+ * Features:
+ * - Side-by-side stimulus display
+ * - Button or keyboard selection
+ * - Optional similarity rating after choice
+ * - Material Design card layout
+ * - Preserves all item and template metadata
+ *
+ * @author Bead Project
+ * @version 0.1.0
+ */
+
+import type { JsPsych, JsPsychPlugin, KeyboardResponseInfo, PluginInfo } from "../types/jspsych.js";
+
+/** Bead rendered elements from metadata */
+interface RenderedElements {
+  [key: string]: string;
+}
+
+/** Bead item/template metadata */
+interface BeadMetadata {
+  rendered_elements?: RenderedElements;
+  [key: string]: unknown;
+}
+
+/** Position type for left/right alternatives */
+type Position = "left" | "right";
+
+/** Forced choice trial parameters */
+export interface ForcedChoiceTrialParams {
+  /** The prompt/question to display */
+  prompt: string;
+  /** Array of alternatives to choose from */
+  alternatives: string[];
+  /** Whether to randomize left/right position */
+  randomize_position: boolean;
+  /** Enable keyboard responses (1/2 or left/right arrow) */
+  enable_keyboard: boolean;
+  /** Whether to require a response */
+  require_response: boolean;
+  /** Text for the continue button (if applicable) */
+  button_label: string;
+  /** Complete item and template metadata */
+  metadata: BeadMetadata;
+}
+
+/** Forced choice response data */
+interface ForcedChoiceResponse {
+  choice: string | null;
+  choice_index: number | null;
+  position: Position | null;
+  rt: number | null;
+}
+
+/** Plugin info constant */
+const info: PluginInfo = {
+  name: "bead-forced-choice",
+  parameters: {
+    prompt: {
+      type: 8, // ParameterType.HTML_STRING
+      default: "Which do you prefer?",
+    },
+    alternatives: {
+      type: 1, // ParameterType.STRING
+      default: [],
+      array: true,
+    },
+    randomize_position: {
+      type: 0, // ParameterType.BOOL
+      default: true,
+    },
+    enable_keyboard: {
+      type: 0, // ParameterType.BOOL
+      default: true,
+    },
+    require_response: {
+      type: 0, // ParameterType.BOOL
+      default: true,
+    },
+    button_label: {
+      type: 1, // ParameterType.STRING
+      default: "Continue",
+    },
+    metadata: {
+      type: 12, // ParameterType.OBJECT
+      default: {},
+    },
+  },
+};
+
+/**
+ * BeadForcedChoicePlugin - jsPsych plugin for comparative judgments
+ */
+class BeadForcedChoicePlugin implements JsPsychPlugin<typeof info, ForcedChoiceTrialParams> {
+  static info = info;
+
+  private jsPsych: JsPsych;
+
+  constructor(jsPsych: JsPsych) {
+    this.jsPsych = jsPsych;
+  }
+
+  trial(display_element: HTMLElement, trial: ForcedChoiceTrialParams): void {
+    const response: ForcedChoiceResponse = {
+      choice: null,
+      choice_index: null,
+      position: null,
+      rt: null,
+    };
+
+    const start_time = performance.now();
+
+    // Extract alternatives from metadata if not provided
+    if (trial.alternatives.length === 0 && trial.metadata.rendered_elements) {
+      const elements = trial.metadata.rendered_elements;
+      const choice_keys = Object.keys(elements)
+        .filter(
+          (k) => k.startsWith("choice_") || k.startsWith("option_"), // Fixed: startswith -> startsWith
+        )
+        .sort();
+
+      if (choice_keys.length >= 2) {
+        trial.alternatives = choice_keys.map((k) => elements[k] ?? "");
+      } else {
+        // Fallback: use all rendered elements
+        trial.alternatives = Object.values(elements);
+      }
+    }
+
+    // Randomize position if requested
+    let left_index = 0;
+    let right_index = 1;
+    if (trial.randomize_position && Math.random() < 0.5) {
+      left_index = 1;
+      right_index = 0;
+    }
+
+    // Create HTML
+    let html = '<div class="bead-forced-choice-container">';
+
+    if (trial.prompt) {
+      html += `<div class="bead-forced-choice-prompt">${trial.prompt}</div>`;
+    }
+
+    html += '<div class="bead-forced-choice-alternatives">';
+
+    // Left alternative
+    html += `
+      <div class="bead-card bead-alternative" data-index="${left_index}" data-position="left">
+        <div class="bead-alternative-label">Option 1</div>
+        <div class="bead-alternative-content">${trial.alternatives[left_index] ?? "Alternative A"}</div>
+        <button class="bead-button bead-choice-button" data-index="${left_index}" data-position="left">
+          Select
+        </button>
+      </div>
+    `;
+
+    // Right alternative
+    html += `
+      <div class="bead-card bead-alternative" data-index="${right_index}" data-position="right">
+        <div class="bead-alternative-label">Option 2</div>
+        <div class="bead-alternative-content">${trial.alternatives[right_index] ?? "Alternative B"}</div>
+        <button class="bead-button bead-choice-button" data-index="${right_index}" data-position="right">
+          Select
+        </button>
+      </div>
+    `;
+
+    html += "</div>"; // Close alternatives
+
+    html += "</div>"; // Close container
+
+    display_element.innerHTML = html;
+
+    // Add event listeners for choice buttons
+    const choice_buttons =
+      display_element.querySelectorAll<HTMLButtonElement>(".bead-choice-button");
+    for (const button of choice_buttons) {
+      button.addEventListener("click", (e) => {
+        const target = e.target as HTMLButtonElement;
+        const indexAttr = target.getAttribute("data-index");
+        const positionAttr = target.getAttribute("data-position") as Position | null;
+        if (indexAttr !== null && positionAttr !== null) {
+          const index = Number.parseInt(indexAttr, 10);
+          select_choice(index, positionAttr);
+        }
+      });
+    }
+
+    // Keyboard listener
+    let keyboard_listener: unknown = null;
+    if (trial.enable_keyboard) {
+      keyboard_listener = this.jsPsych.pluginAPI.getKeyboardResponse({
+        callback_function: (info: KeyboardResponseInfo) => {
+          const key = info.key;
+          if (key === "1" || key === "ArrowLeft") {
+            select_choice(left_index, "left");
+          } else if (key === "2" || key === "ArrowRight") {
+            select_choice(right_index, "right");
+          }
+        },
+        valid_responses: ["1", "2", "ArrowLeft", "ArrowRight"],
+        rt_method: "performance",
+        persist: false,
+        allow_held_key: false,
+      });
+    }
+
+    const select_choice = (index: number, position: Position): void => {
+      // Update response
+      response.choice = trial.alternatives[index] ?? null;
+      response.choice_index = index;
+      response.position = position;
+      response.rt = performance.now() - start_time;
+
+      // Visual feedback
+      const alternative_cards =
+        display_element.querySelectorAll<HTMLDivElement>(".bead-alternative");
+      for (const card of alternative_cards) {
+        card.classList.remove("selected");
+      }
+      const selected_card = display_element.querySelector<HTMLDivElement>(
+        `.bead-alternative[data-position="${position}"]`,
+      );
+      if (selected_card) {
+        selected_card.classList.add("selected");
+      }
+
+      // End trial immediately or after delay
+      setTimeout(() => {
+        end_trial();
+      }, 300); // Small delay for visual feedback
+    };
+
+    const end_trial = (): void => {
+      // Kill keyboard listener
+      if (keyboard_listener) {
+        this.jsPsych.pluginAPI.cancelKeyboardResponse(keyboard_listener);
+      }
+
+      // Preserve all metadata and add response data
+      const trial_data: Record<string, unknown> = {
+        ...trial.metadata, // Spread all metadata
+        choice: response.choice,
+        choice_index: response.choice_index,
+        position_chosen: response.position,
+        left_index: left_index,
+        right_index: right_index,
+        rt: response.rt,
+      };
+
+      // Clear display
+      display_element.innerHTML = "";
+
+      // End trial
+      this.jsPsych.finishTrial(trial_data);
+    };
+  }
+}
+
+export { BeadForcedChoicePlugin };

bead/deployment/jspsych/src/plugins/plugins.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Unit tests for bead jsPsych plugins.
+ *
+ * Tests plugin structure, info validation, and instantiation.
+ */
+
+import { describe, expect, test, vi } from "vitest";
+import type { JsPsych } from "../types/jspsych.js";
+import { BeadClozeMultiPlugin } from "./cloze-dropdown.js";
+import { BeadForcedChoicePlugin } from "./forced-choice.js";
+import { BeadRatingPlugin } from "./rating.js";
+
+// Mock jsPsych instance
+function createMockJsPsych(): JsPsych {
+  return {
+    pluginAPI: {
+      getKeyboardResponse: vi.fn(),
+      cancelKeyboardResponse: vi.fn(),
+    },
+    finishTrial: vi.fn(),
+  } as unknown as JsPsych;
+}
+
+describe("bead-rating plugin", () => {
+  describe("info structure", () => {
+    test("has correct plugin name", () => {
+      expect(BeadRatingPlugin.info.name).toBe("bead-rating");
+    });
+
+    test("has required parameters", () => {
+      const params = BeadRatingPlugin.info.parameters;
+      expect(params["prompt"]).toBeDefined();
+      expect(params["scale_min"]).toBeDefined();
+      expect(params["scale_max"]).toBeDefined();
+      expect(params["scale_labels"]).toBeDefined();
+      expect(params["require_response"]).toBeDefined();
+      expect(params["button_label"]).toBeDefined();
+      expect(params["metadata"]).toBeDefined();
+    });
+
+    test("has correct parameter defaults", () => {
+      const params = BeadRatingPlugin.info.parameters;
+      expect(params["scale_min"]?.default).toBe(1);
+      expect(params["scale_max"]?.default).toBe(7);
+      expect(params["require_response"]?.default).toBe(true);
+      expect(params["button_label"]?.default).toBe("Continue");
+    });
+  });
+
+  describe("plugin instantiation", () => {
+    test("can be instantiated", () => {
+      const mockJsPsych = createMockJsPsych();
+      const plugin = new BeadRatingPlugin(mockJsPsych);
+      expect(plugin).toBeDefined();
+    });
+
+    test("has trial method", () => {
+      const mockJsPsych = createMockJsPsych();
+      const plugin = new BeadRatingPlugin(mockJsPsych);
+      expect(typeof plugin.trial).toBe("function");
+    });
+  });
+});
+
+describe("bead-forced-choice plugin", () => {
+  describe("info structure", () => {
+    test("has correct plugin name", () => {
+      expect(BeadForcedChoicePlugin.info.name).toBe("bead-forced-choice");
+    });
+
+    test("has required parameters", () => {
+      const params = BeadForcedChoicePlugin.info.parameters;
+      expect(params["alternatives"]).toBeDefined();
+      expect(params["prompt"]).toBeDefined();
+      expect(params["button_label"]).toBeDefined();
+      expect(params["require_response"]).toBeDefined();
+      expect(params["randomize_position"]).toBeDefined();
+      expect(params["enable_keyboard"]).toBeDefined();
+      expect(params["metadata"]).toBeDefined();
+    });
+
+    test("has correct parameter defaults", () => {
+      const params = BeadForcedChoicePlugin.info.parameters;
+      expect(params["require_response"]?.default).toBe(true);
+      expect(params["randomize_position"]?.default).toBe(true);
+      expect(params["enable_keyboard"]?.default).toBe(true);
+      expect(params["button_label"]?.default).toBe("Continue");
+    });
+  });
+
+  describe("plugin instantiation", () => {
+    test("can be instantiated", () => {
+      const mockJsPsych = createMockJsPsych();
+      const plugin = new BeadForcedChoicePlugin(mockJsPsych);
+      expect(plugin).toBeDefined();
+    });
+
+    test("has trial method", () => {
+      const mockJsPsych = createMockJsPsych();
+      const plugin = new BeadForcedChoicePlugin(mockJsPsych);
+      expect(typeof plugin.trial).toBe("function");
+    });
+  });
+});
+
+describe("bead-cloze-multi plugin", () => {
+  describe("info structure", () => {
+    test("has correct plugin name", () => {
+      expect(BeadClozeMultiPlugin.info.name).toBe("bead-cloze-multi");
+    });
+
+    test("has required parameters", () => {
+      const params = BeadClozeMultiPlugin.info.parameters;
+      expect(params["text"]).toBeDefined();
+      expect(params["fields"]).toBeDefined();
+      expect(params["require_all"]).toBeDefined();
+      expect(params["button_label"]).toBeDefined();
+      expect(params["metadata"]).toBeDefined();
+    });
+
+    test("has correct parameter defaults", () => {
+      const params = BeadClozeMultiPlugin.info.parameters;
+      expect(params["require_all"]?.default).toBe(true);
+      expect(params["button_label"]?.default).toBe("Continue");
+    });
+  });
+
+  describe("plugin instantiation", () => {
+    test("can be instantiated", () => {
+      const mockJsPsych = createMockJsPsych();
+      const plugin = new BeadClozeMultiPlugin(mockJsPsych);
+      expect(plugin).toBeDefined();
+    });
+
+    test("has trial method", () => {
+      const mockJsPsych = createMockJsPsych();
+      const plugin = new BeadClozeMultiPlugin(mockJsPsych);
+      expect(typeof plugin.trial).toBe("function");
+    });
+  });
+});