@nyuccl/smile 0.2.0-beta.0

package/dist/runtime/utils/randomization.js

@@ -0,0 +1,189 @@
+/**
+ * Gets random integer between min (inclusive) and max (inclusive)
+ * @param {number} min - Minimum value (inclusive)
+ * @param {number} max - Maximum value (inclusive)
+ * @returns {number} Random integer between min and max
+ */
+export function randomInt(min, max) {
+  return Math.floor(Math.random() * (Math.floor(max) - Math.ceil(min) + 1) + Math.ceil(min))
+}
+
+/**
+ * Shuffles array in place using Fisher-Yates algorithm
+ * @param {Array} array - Array to shuffle
+ * @returns {Array} New shuffled array
+ */
+export function shuffle(array) {
+  const arrayCopy = array.slice(0)
+  for (let i = arrayCopy.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1))
+    const temp = arrayCopy[i]
+    arrayCopy[i] = arrayCopy[j]
+    arrayCopy[j] = temp
+  }
+  return arrayCopy
+}
+
+/**
+ * Samples elements from array without replacement
+ * @param {Array} array - Array to sample from
+ * @param {number} sampleSize - Number of elements to sample
+ * @returns {Array} Array of sampled elements
+ */
+export function sampleWithoutReplacement(array, sampleSize) {
+  if (sampleSize > array.length) {
+    console.error('sample size larger than array length')
+  }
+  return shuffle(array).slice(0, sampleSize)
+}
+
+/**
+ * Samples elements from array with replacement, optionally using weights
+ * @param {Array} array - Array to sample from
+ * @param {number} sampleSize - Number of elements to sample
+ * @param {Array<number>} [weights] - Optional array of weights for weighted sampling
+ * @returns {Array} Array of sampled elements
+ */
+export function sampleWithReplacement(array, sampleSize, weights = undefined) {
+  // if weights are not provided, normal sample with replacement
+  if (!weights) {
+    const sample = []
+    let s = sampleSize
+    while (s > 0) {
+      sample.push(array[randomInt(0, array.length - 1)])
+      s -= 1
+    }
+    return sample
+  }
+
+  // if weights are provided, sample with replacement with weights
+  // normalize weights array -- get sum of all weights
+  const sumOfWeights = weights.reduce((a, b) => a + b, 0)
+  // divide each weight by the sum of all weights
+  const normalizedWeights = weights.map(weight => weight / sumOfWeights)
+
+  const sample = []
+  let s = sampleSize
+  while (s > 0) {
+    const random = Math.random()
+    let i = 0
+    let sum = normalizedWeights[i]
+    while (random > sum) {
+      i += 1
+      sum += normalizedWeights[i]
+    }
+    sample.push(array[i])
+    s -= 1
+  }
+  return sample
+}
+
+/**
+ * Computes Cartesian product of input arrays
+ * @param {...Array} arr - Arrays to compute product of
+ * @returns {Array} Array containing all combinations
+ */
+export function expandProduct(...arr) {
+  // get length of each sub array in arr
+  const lengths = arr.map(x => x.length)
+  // get product of lengths
+  const product = lengths.reduce((a, b) => a * b, 1)
+  if (product > 1000) {
+    console.warn('That\'s a whole lot of combinations! Are you sure you want to do that?')
+  }
+  return arr.reduce((a, b) => a.flatMap(d => b.map(e => [d, e].flat())))
+}
+
+/**
+ * Collection of functions for generating random values from different distributions
+ * @namespace
+ */
+export const fakerDistributions = {
+  /**
+   * Generates random number from normal distribution
+   * @param {number} mean - Mean of distribution
+   * @param {number} sd - Standard deviation of distribution
+   * @returns {{val: number, type: string}} Object containing random value and type
+   */
+  rnorm: (mean, sd) => {
+    let u = 0,
+      v = 0
+    while (u === 0) u = Math.random()
+    while (v === 0) v = Math.random()
+    return {
+      val: mean + sd * Math.sqrt(-2.0 * Math.log(u)) * Math.cos(2.0 * Math.PI * v),
+      type: 'fake',
+    }
+  },
+
+  /**
+   * Generates random number from uniform distribution
+   * @param {number} min - Minimum value
+   * @param {number} max - Maximum value
+   * @returns {{val: number, type: string}} Object containing random value and type
+   */
+  runif: (min, max) => ({
+    val: Math.random() * (max - min) + min,
+    type: 'fake',
+  }),
+
+  /**
+   * Generates random number from binomial distribution
+   * @param {number} n - Number of trials
+   * @param {number} p - Probability of success
+   * @returns {{val: number, type: string}} Object containing random value and type
+   */
+  rbinom: (n, p) => ({
+    val: Array(n)
+      .fill(0)
+      .reduce(acc => acc + (Math.random() < p ? 1 : 0), 0),
+    type: 'fake',
+  }),
+
+  /**
+   * Generates random number from ex-Gaussian distribution
+   * @param {number} mu - Mean of normal component
+   * @param {number} sigma - Standard deviation of normal component
+   * @param {number} tau - Rate parameter of exponential component
+   * @returns {{val: number, type: string}} Object containing random value and type
+   */
+  rexGaussian: (mu, sigma, tau) => {
+    const x = fakerDistributions.rnorm(0, 1).val
+    const z = fakerDistributions.runif(0, 1).val
+    return {
+      val: mu + sigma * x + tau * -Math.log(z),
+      type: 'fake',
+    }
+  },
+
+  /**
+   * Randomly selects an element from an array of options
+   * @param {Array} options - Array of options to choose from
+   * @returns {{val: *, type: string}} Object containing selected value and type
+   * @throws {Error} If options array is empty or not an array
+   */
+  rchoice: (options) => {
+    if (!Array.isArray(options) || options.length === 0) {
+      throw new Error('rchoice requires a non-empty array of options')
+    }
+    const index = Math.floor(Math.random() * options.length)
+    return {
+      val: options[index],
+      type: 'fake',
+    }
+  },
+
+  /**
+   * Evaluates any function values in a trial object
+   * @param {object} trial - Trial object potentially containing function values
+   * @returns {object} Trial object with functions evaluated
+   */
+  render: (trial) => {
+    for (let [key, value] of Object.entries(trial)) {
+      if (typeof value === 'function') {
+        trial[key] = value()
+      }
+    }
+    return trial
+  },
+}

package/dist/runtime/utils/utils.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Performs service-specific initialization before the experiment begins.
+ * Currently handles PANDA's dual-iframe quirk and localStorage clearing.
+ * @param {string} service - Recruitment service name
+ * @returns {boolean} Whether initialization succeeded (false = abort navigation)
+ */
+export function initService(service: string): boolean;
+/**
+ * Gets URL query parameters from the current window location
+ * @returns {object} Dictionary of query parameter key-value pairs
+ */
+export function getQueryParams(): object;
+/**
+ * Processes URL query parameters to determine recruitment service and store participant info
+ * @param {object} query - Query parameters object
+ * @param {string} service - Recruitment service name ('prolific', 'cloudresearch', 'mturk', 'citizensci')
+ */
+export function processQuery(query: object, service: string): void;
+export default processQuery;

package/dist/runtime/utils/utils.js

@@ -0,0 +1,147 @@
+/**
+ * @fileoverview Utility functions for URL parameter handling and recruitment service processing
+ * @module utils
+ */
+
+/**
+ * Import store composables
+ * @requires useSmileStore Global store composable for managing application state
+ * @requires useLog Logging store composable for application logging
+ */
+import useSmileStore from '../stores/smilestore.js'
+import useLog from '../stores/log.js'
+
+/**
+ * Performs service-specific initialization before the experiment begins.
+ * Currently handles PANDA's dual-iframe quirk and localStorage clearing.
+ * @param {string} service - Recruitment service name
+ * @returns {boolean} Whether initialization succeeded (false = abort navigation)
+ */
+export function initService(service) {
+  const log = useLog()
+
+  if (service === 'panda') {
+    // PANDA loads the study in two iframes simultaneously (one hidden for
+    // mobile/desktop switching). A hidden iframe reports window.innerWidth === 0,
+    // so block it from initializing.
+    if (window.innerWidth === 0) {
+      log.log('PANDA: hidden iframe detected, cancelling navigation')
+      return false
+    }
+    // Clear existing smilestore localStorage to handle the sibling/retry case
+    // where families need to run the study multiple times
+    Object.keys(localStorage).forEach((key) => {
+      if (key.startsWith('smilestore')) {
+        localStorage.removeItem(key)
+      }
+    })
+  }
+
+  return true
+}
+
+/**
+ * Gets URL query parameters from the current window location
+ * @returns {object} Dictionary of query parameter key-value pairs
+ */
+export function getQueryParams() {
+  if (typeof window === 'undefined') return {}
+  const queryString = window.location.search
+  const urlParams = new URLSearchParams(queryString)
+  const queryDict = {}
+  for (const [key, value] of urlParams.entries()) {
+    queryDict[key] = value
+  }
+  return queryDict
+}
+
+/**
+ * Processes URL query parameters to determine recruitment service and store participant info
+ * @param {object} query - Query parameters object
+ * @param {string} service - Recruitment service name ('prolific', 'cloudresearch', 'mturk', 'citizensci')
+ */
+export function processQuery(query, service) {
+  const smilestore = useSmileStore()
+  const urlParams = query
+  const log = useLog()
+
+  if (!urlParams) return // do nothing if no query
+
+  if (service === 'prolific' && urlParams.PROLIFIC_PID && urlParams.STUDY_ID && urlParams.SESSION_ID) {
+    // this is a prolific experiment
+    log.log('Prolific mode')
+    smilestore.setRecruitmentService(service, {
+      prolific_id: urlParams.PROLIFIC_PID,
+      study_id: urlParams.STUDY_ID,
+      session_id: urlParams.SESSION_ID,
+    })
+  }
+  else if (service === 'cloudresearch' && urlParams.assignmentId && urlParams.hitId && urlParams.workerId) {
+    log.log('CloudResearch mode')
+    smilestore.setRecruitmentService(service, {
+      worker_id: urlParams.workerId,
+      hit_id: urlParams.hitId,
+      assignment_id: urlParams.assignmentId,
+    })
+  }
+  else if (service === 'mturk' && urlParams.assignmentId && urlParams.hitId && urlParams.workerId) {
+    if (urlParams.assignmentId == 'ASSIGNMENT_ID_NOT_AVAILABLE') {
+      log.log('AMT mode, but no assignment (preview mode)')
+      // supposed to show the ad here
+    }
+    else {
+      log.log('AMT mode, with assignment')
+      smilestore.setRecruitmentService(service, {
+        worker_id: urlParams.workerId,
+        hit_id: urlParams.hitId,
+        assignment_id: urlParams.assignmentId,
+      })
+    }
+  }
+  else if (
+    service === 'citizensci'
+    && urlParams.CITIZEN_ID
+    && urlParams.CITIZEN_STUDY_ID
+    && urlParams.CITIZEN_SESSION_ID
+  ) {
+    log.log('Future citizen mode')
+    smilestore.setRecruitmentService(service, {
+      citizen_id: urlParams.CITIZEN_ID,
+      study_id: urlParams.CITIZEN_STUDY_ID,
+      session_id: urlParams.CITIZEN_SESSION_ID,
+    })
+  }
+  else if (service === 'sona' && urlParams.survey_code) {
+    log.log('SONA (credit) mode')
+    smilestore.setRecruitmentService(service, {
+      survey_code: urlParams.survey_code,
+    })
+  }
+  else if (service === 'sona_paid' && urlParams.survey_code) {
+    log.log('SONA (paid) mode')
+    smilestore.setRecruitmentService(service, {
+      survey_code: urlParams.survey_code,
+    })
+  }
+  else if (service === 'spark' && urlParams.subject_ID) {
+    log.log('SPARK mode')
+    smilestore.setRecruitmentService(service, {
+      subject_ID: urlParams.subject_ID,
+      participant_ID: urlParams.participant_ID,
+      age: urlParams.age,
+      gender: urlParams.gender,
+    })
+  }
+  else if (service === 'panda' && urlParams.ID) {
+    log.log('PANDA mode')
+    smilestore.data.panda_id = urlParams.ID
+    smilestore.setRecruitmentService(service, {
+      panda_id: urlParams.ID,
+    })
+  }
+  else {
+    // log.log('const { next, prev } = useTimeline() mode')
+  }
+}
+
+export default processQuery

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "@nyuccl/smile",
+  "version": "0.2.0-beta.0",
+  "description": "SMILE experiment framework as a Nuxt module",
+  "author": "Todd Gureckis <gureckis@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nyuccl/smile-nuxt.git"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24.13.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@codenamize/codenamize": "1.1.1",
+    "@internationalized/date": "^3.7.0",
+    "@libsql/client": "^0.14.0",
+    "@nuxt/kit": "^4.3.0",
+    "@pinia/nuxt": "^0.9.0",
+    "@tailwindcss/vite": "^4.1.10",
+    "@vueuse/core": "^12.8.2",
+    "axios": "^1.7.9",
+    "class-variance-authority": "^0.7.1",
+    "clipboard": "^2.0.11",
+    "clsx": "^2.1.1",
+    "crypto-js": "^4.2.0",
+    "drizzle-orm": "^0.38.0",
+    "json-stable-stringify": "^1.2.1",
+    "lodash": "^4.17.21",
+    "lucide-vue-next": "^0.517.0",
+    "motion": "^12.3.1",
+    "pinia": "^2.3.1",
+    "qrcode-svg": "^1.1.0",
+    "reka-ui": "^2.6.1",
+    "seedrandom": "^3.0.5",
+    "tailwind-merge": "^3.3.1",
+    "tailwindcss": "^4.1.11",
+    "tw-animate-css": "^1.3.4",
+    "unplugin-icons": "^22.1.0",
+    "unplugin-vue-components": "^28.4.1",
+    "uuid": "^11.0.5",
+    "vue-sonner": "^2.0.1"
+  },
+  "devDependencies": {
+    "@iconify/json": "^2.2.351",
+    "@mdit/plugin-sub": "^0.16.0",
+    "@nuxt/devtools": "^3.1.1",
+    "@nuxt/eslint-config": "^1.13.0",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/schema": "^4.3.0",
+    "@nuxt/test-utils": "^3.23.0",
+    "@pinia/testing": "^1.0.3",
+    "@playwright/test": "^1.58.2",
+    "@types/node": "latest",
+    "@vue/test-utils": "^2.4.6",
+    "bumpp": "^10.4.1",
+    "changelogen": "^0.6.2",
+    "drizzle-kit": "^0.30.0",
+    "eslint": "^9.39.2",
+    "happy-dom": "^20.8.3",
+    "markdown-it-footnote": "^4.0.0",
+    "markdown-it-mark": "^4.0.0",
+    "nuxt": "^4.3.0",
+    "prettier": "^3.4.2",
+    "shiki": "^2.3.1",
+    "typescript": "~5.9.3",
+    "vitepress": "^1.6.3",
+    "vitest": "^4.0.18",
+    "vue-tsc": "^3.2.4"
+  },
+  "scripts": {
+    "dev": "pnpm run dev:prepare && nuxt dev playground",
+    "dev:build": "nuxt build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground",
+    "release": "bumpp && pnpm run lint && pnpm run test && pnpm run prepack && changelogen --release && pnpm publish --access public --tag beta && git push --follow-tags",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit",
+    "generate-env": "bash scripts/generate_git_env.sh",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:serve": "vitepress serve docs"
+  }
+}