@lookit/templates 0.0.1

package/dist/utils.d.ts

@@ -0,0 +1,14 @@
+import { PluginInfo, TrialType } from "jspsych";
+/**
+ * Pulled from EFP. Function to convert researcher's text to HTML.
+ *
+ * @param text - Text
+ * @returns Formatted string
+ */
+export declare const expFormat: (text?: string | string[]) => string;
+/**
+ * Initialize i18next with parameters from trial.
+ *
+ * @param trial - Trial data including user supplied parameters.
+ */
+export declare const setLocale: (trial: TrialType<PluginInfo>) => void;

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@lookit/templates",
+  "version": "0.0.1",
+  "description": "CHS jsPsych trial templates and their translations",
+  "homepage": "https://github.com/lookit/lookit-jspsych#readme",
+  "bugs": {
+    "url": "https://github.com/lookit/lookit-jspsych/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lookit/lookit-jspsych.git"
+  },
+  "license": "ISC",
+  "author": "Christopher J Green <okaycj@mit.edu> (https://github.com/okaycj)",
+  "main": "dist/index.js",
+  "unpkg": "dist/index.browser.min.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "src",
+    "dist"
+  ],
+  "scripts": {
+    "build": "rollup --config",
+    "dev": "rollup --config rollup.config.dev.mjs --watch",
+    "test": "jest --coverage"
+  },
+  "devDependencies": {
+    "@jspsych/config": "^2.0.0",
+    "handlebars": "^4.7.8",
+    "rollup-plugin-dotenv": "^0.5.1",
+    "rollup-plugin-polyfill-node": "^0.13.0"
+  },
+  "peerDependencies": {
+    "@lookit/data": "^0.0.4",
+    "jspsych": "^8.0.2"
+  }
+}

package/src/consentVideoTemplate.ts

@@ -0,0 +1,57 @@
+import { LookitWindow } from "@lookit/data/dist/types";
+import Handlebars from "handlebars";
+import { PluginInfo, TrialType } from "jspsych";
+import consent_garden from "../hbs/consent-garden.hbs";
+import consent_template_5 from "../hbs/consent-template-5.hbs";
+import consentVideoTrialTemplate from "../hbs/consent-video-trial.hbs";
+import { ConsentTemplateNotFound } from "./errors";
+import { setLocale } from "./utils";
+
+declare const window: LookitWindow;
+
+const video_container_id = "lookit-jspsych-video-container";
+
+/**
+ * Translate, render, and get consent document HTML.
+ *
+ * @param trial - JsPsych trial object containing trial params
+ * @returns Consent document HTML
+ */
+export const consentVideo = (trial: TrialType<PluginInfo>) => {
+  const experiment = window.chs.study.attributes;
+  const { PIName, PIContact } = trial;
+
+  setLocale(trial);
+
+  const consentDocumentTemplate = consentDocument(trial);
+
+  const consent = Handlebars.compile(consentDocumentTemplate)({
+    ...trial,
+    name: PIName,
+    contact: PIContact,
+    experiment,
+  });
+
+  return Handlebars.compile(consentVideoTrialTemplate)({
+    ...trial,
+    consent,
+    video_container_id,
+  });
+};
+
+/**
+ * Get consent template by name.
+ *
+ * @param trial - Trial data including user supplied parameters.
+ * @returns Consent template
+ */
+const consentDocument = (trial: TrialType<PluginInfo>) => {
+  switch (trial.template) {
+    case "consent-template-5":
+      return consent_template_5;
+    case "consent-garden":
+      return consent_garden;
+    default:
+      throw new ConsentTemplateNotFound(trial.template);
+  }
+};

package/src/environment.d.ts

@@ -0,0 +1,9 @@
+declare global {
+  namespace NodeJS {
+    interface ProcessEnv {
+      DEBUG?: string;
+    }
+  }
+}
+
+export {};

package/src/errors.ts

@@ -0,0 +1,22 @@
+/** Error thrown when specified language isn't found */
+export class LocaleNotFoundError extends Error {
+  /**
+   * This will be thrown when attempting to init i18n
+   *
+   * @param baseName - Language a2code with region
+   */
+  public constructor(baseName: string) {
+    super(`"${baseName}" locale not found.`);
+  }
+}
+/** Error thrown when researcher selects template that isn't available. */
+export class ConsentTemplateNotFound extends Error {
+  /**
+   * This will let the researcher know that their template isn't found.
+   *
+   * @param template - Supplied name of consent template.
+   */
+  public constructor(template: string) {
+    super(`Consent template "${template}" not found.`);
+  }
+}

package/src/index.spec.ts

@@ -0,0 +1,74 @@
+import { LookitWindow } from "@lookit/data/dist/types";
+import { PluginInfo, TrialType } from "jspsych";
+import { ConsentTemplateNotFound } from "./errors";
+import chsTemplate from "./index";
+
+declare const window: LookitWindow;
+
+/**
+ * Test helper function to create trial object.
+ *
+ * @param values - Object to replace default trial values
+ * @returns Trial object
+ */
+const getTrial = (values: Record<string, string> = {}) => {
+  return {
+    locale: "en-us",
+    template: "consent-template-5",
+    ...values,
+  } as unknown as TrialType<PluginInfo>;
+};
+
+test("consent video", () => {
+  const trial = getTrial();
+  const name = "some name";
+  window.chs = {
+    study: {
+      attributes: {
+        name,
+        duration: "duration",
+      },
+    },
+  } as typeof window.chs;
+
+  expect(chsTemplate.consentVideo(trial)).toContain(
+    '<div id="consent-video-trial">',
+  );
+  expect(chsTemplate.consentVideo(trial)).toContain(
+    `Consent to participate in research:\n  ${name}`,
+  );
+});
+
+test("consent video in French", () => {
+  const trial = getTrial({ locale: "fr" });
+  const name = "some name";
+  window.chs = {
+    study: {
+      attributes: {
+        name,
+        duration: "duration",
+      },
+    },
+  } as typeof window.chs;
+
+  expect(chsTemplate.consentVideo(trial)).toContain(
+    '<div id="consent-video-trial">',
+  );
+  expect(chsTemplate.consentVideo(trial)).toContain(
+    `Consentement à participer à la recherche:\n  ${name}`,
+  );
+});
+
+test("consent video with unknown template", () => {
+  const trial = getTrial({
+    template: "not a real template name",
+  });
+  expect(() => chsTemplate.consentVideo(trial)).toThrow(
+    ConsentTemplateNotFound,
+  );
+});
+
+test("consent garden template", () => {
+  const trial = getTrial({ template: "consent-garden" });
+  expect(chsTemplate.consentVideo(trial)).toContain("Project GARDEN");
+});

package/src/index.ts

@@ -0,0 +1,3 @@
+import { consentVideo } from "./consentVideoTemplate";
+
+export default { consentVideo };

package/src/string-import.d.ts

@@ -0,0 +1,14 @@
+declare module "*.svg" {
+  const file: string;
+  export default file;
+}
+
+declare module "*.yaml" {
+  const file: string;
+  export default file;
+}
+
+declare module "*.hbs" {
+  const file: string;
+  export default file;
+}

package/src/utils.spec.ts

@@ -0,0 +1,27 @@
+import { PluginInfo, TrialType } from "jspsych";
+import { LocaleNotFoundError } from "./errors";
+import { expFormat, setLocale } from "./utils";
+
+test("expFormat convert written text to format well in HTML", () => {
+  expect(expFormat("abcdefg")).toStrictEqual("abcdefg");
+  expect(expFormat("AAABBBCCC")).toStrictEqual("AAABBBCCC");
+  expect(expFormat("A normal sentence with multiple words.")).toStrictEqual(
+    "A normal sentence with multiple words.",
+  );
+  expect(expFormat(["Array", "of", "strings"])).toStrictEqual(
+    "Array<br><br>of<br><br>strings",
+  );
+  expect(expFormat("carriage return an newline\r\n")).toStrictEqual(
+    "carriage return an newline<br>",
+  );
+  expect(expFormat("new line\n")).toStrictEqual("new line<br>");
+  expect(expFormat("carriage return\r")).toStrictEqual("carriage return<br>");
+  expect(expFormat("\tTabbed text")).toStrictEqual(
+    "&nbsp;&nbsp;&nbsp;&nbsp;Tabbed text",
+  );
+});
+
+test("setLocale throw error with non-existing locale", () => {
+  const trial = { locale: "non-existing" } as unknown as TrialType<PluginInfo>;
+  expect(() => setLocale(trial)).toThrow(LocaleNotFoundError);
+});

package/src/utils.ts

@@ -0,0 +1,94 @@
+import Handlebars from "handlebars";
+import i18next from "i18next";
+import ICU from "i18next-icu";
+import Yaml from "js-yaml";
+import { PluginInfo, TrialType } from "jspsych";
+import en_us from "../i18n/en-us.yaml";
+import eu from "../i18n/eu.yaml";
+import fr from "../i18n/fr.yaml";
+import hu from "../i18n/hu.yaml";
+import it from "../i18n/it.yaml";
+import ja from "../i18n/ja.yaml";
+import nl from "../i18n/nl.yaml";
+import pt_br from "../i18n/pt-br.yaml";
+import pt from "../i18n/pt.yaml";
+import { LocaleNotFoundError } from "./errors";
+
+/**
+ * Pulled from EFP. Function to convert researcher's text to HTML.
+ *
+ * @param text - Text
+ * @returns Formatted string
+ */
+export const expFormat = (text?: string | string[]) => {
+  if (!text) {
+    return "";
+  }
+
+  if (Array.isArray(text)) {
+    text = text.join("\n\n");
+  }
+
+  return text
+    .replace(/(\r\n|\n|\r)/gm, "<br>")
+    .replace(/\t/gm, "&nbsp;&nbsp;&nbsp;&nbsp;");
+};
+
+/**
+ * Get a translation resources from yaml files.
+ *
+ * @returns Resources for i18next
+ */
+const resources = () => {
+  const translations = {
+    "en-us": en_us,
+    eu,
+    fr,
+    hu,
+    it,
+    ja,
+    nl,
+    "pt-br": pt_br,
+    pt,
+  };
+
+  return Object.entries(translations).reduce((prev, [locale, translation]) => {
+    const lcl = new Intl.Locale(locale);
+    return {
+      ...prev,
+      [lcl.baseName]: {
+        translation: Yaml.load(translation) as Record<string, string>,
+      },
+    };
+  }, {});
+};
+
+/**
+ * Initialize i18next with parameters from trial.
+ *
+ * @param trial - Trial data including user supplied parameters.
+ */
+export const setLocale = (trial: TrialType<PluginInfo>) => {
+  const lcl = new Intl.Locale(trial.locale);
+
+  if (!i18next.hasResourceBundle(lcl.baseName, "translation")) {
+    throw new LocaleNotFoundError(trial.locale);
+  }
+
+  if (i18next.language !== lcl.baseName) {
+    i18next.changeLanguage(lcl.baseName);
+  }
+};
+
+// Initialize translations
+i18next.use(ICU).init({
+  debug: process.env.DEBUG === "true",
+  resources: resources(),
+});
+
+// Setup Handlebars' helpers
+Handlebars.registerHelper("exp-format", (context) => expFormat(context));
+Handlebars.registerHelper("t", (context, { hash }) => {
+  const txt = String(i18next.t(context, hash));
+  return hash.htmlSafe ? new Handlebars.SafeString(txt) : txt;
+});