@adriansteffan/reactive 0.1.1 → 0.1.3

package/src/components/text.tsx

@@ -2,6 +2,7 @@ import React, { useEffect, useRef } from 'react';
 import { BaseComponentProps, now } from '../mod';
 import { registerSimulation } from '../utils/simulation';
 import { registerFlattener } from '../utils/upload';
+import { uniform } from '../utils/distributions';
 
 registerFlattener('Text', 'text');
 
@@ -10,7 +11,7 @@ registerSimulation('Text', (trialProps, _experimentState, simulators, participan
   return { responseData: result.value, participantState: result.participantState, duration: result.value.reactionTime };
 }, {
   respond: (_input: any, participant: any) => ({
-    value: { key: 'button', reactionTime: 500 + Math.random() * 1500 },
+    value: { key: 'button', reactionTime: uniform(500, 2000) },
     participantState: participant,
   }),
 });

package/src/components/tutorial.tsx

@@ -0,0 +1,232 @@
+import { useState, useRef, useEffect, useCallback, useContext, createContext, ReactNode } from 'react';
+import { motion, AnimatePresence, LayoutGroup } from 'motion/react';
+import { BaseComponentProps } from '../mod';
+import { registerSimulation } from '../utils/simulation';
+import { registerFlattener } from '../utils/upload';
+
+registerFlattener('Tutorial', 'session');
+
+registerSimulation('Tutorial', (trialProps, _experimentState, simulators, participant) => {
+  const slideCount = trialProps.slides?.length ?? 0;
+  const slideData: Record<number, Record<string, unknown>> = {};
+  let totalDuration = 0;
+  for (let i = 0; i < slideCount; i++) {
+    const result = simulators.respondToSlide(i, trialProps, participant);
+    participant = result.participantState;
+    slideData[i] = result.value ?? {};
+    totalDuration += result.duration ?? 500;
+  }
+  return { responseData: { slides: slideData }, participantState: participant, duration: totalDuration };
+}, {
+  respondToSlide: (_slideIndex: number, _trialProps: any, participant: any) => ({
+    value: {},
+    participantState: participant,
+    duration: 500,
+  }),
+});
+
+interface TutorialSlideContextValue {
+  setCanProgress: (canProgress: boolean) => void;
+  autoAdvance: (delayMs?: number) => void;
+  setSlideData: (data: Record<string, unknown>) => void;
+}
+
+const TutorialSlideContext = createContext<TutorialSlideContextValue>({
+  setCanProgress: () => {},
+  autoAdvance: () => {},
+  setSlideData: () => {},
+});
+
+/**
+ * Hook for interactive slide components.
+ * Call with `{ locked: true }` to start with the next button disabled.
+ * Then call `unlock()` when the interaction is complete.
+ * Call `unlock({ autoAdvanceMs: 1000 })` to auto-advance after a delay.
+ */
+export const useTutorialSlide = ({ locked = false } = {}) => {
+  const ctx = useContext(TutorialSlideContext);
+  const initialized = useRef(false);
+  if (!initialized.current && locked) {
+    initialized.current = true;
+    ctx.setCanProgress(false);
+  }
+  return {
+    setData: ctx.setSlideData,
+    unlock: ({ autoAdvanceMs }: { autoAdvanceMs?: number } = {}) => {
+      ctx.setCanProgress(true);
+      if (autoAdvanceMs !== undefined) ctx.autoAdvance(autoAdvanceMs);
+    },
+  };
+};
+
+export interface TutorialProps extends BaseComponentProps {
+  slides: ReactNode[];
+  /** Fade duration in seconds (default: 0.3) */
+  fadeDuration?: number;
+  finishText?: string;
+  containerClass?: string;
+  /** Key to go forward (default: 'ArrowRight', set to false to disable) */
+  nextKey?: string | false;
+  /** Key to go back (default: 'ArrowLeft', set to false to disable) */
+  backKey?: string | false;
+  /** Color mode for dot indicators (default: 'light') */
+  theme?: 'light' | 'dark';
+}
+
+const NAV_BTN =
+  'px-4 py-3 border-2 border-black font-bold text-lg rounded-xl shadow-[2px_2px_0px_rgba(0,0,0,1)] transition-all duration-100 outline-none focus:outline-none focus:ring-0';
+
+const NAV_BTN_ACTIVE = NAV_BTN + ' bg-white text-black cursor-pointer hover:translate-x-[2px] hover:translate-y-[2px] hover:shadow-none';
+
+const NAV_BTN_DISABLED = NAV_BTN + ' bg-gray-200 text-gray-400 border-gray-400 shadow-[2px_2px_0px_rgba(156,163,175,1)] cursor-default';
+
+export const Tutorial = ({
+  next,
+  slides,
+  fadeDuration = 0.3,
+  finishText = 'Start',
+  containerClass,
+  nextKey = 'ArrowRight',
+  backKey = 'ArrowLeft',
+  theme = 'light',
+}: TutorialProps) => {
+  const [page, setPage] = useState(0);
+  const [progressMap, setProgressMap] = useState<Record<number, boolean>>({});
+  const autoAdvanceTimer = useRef<ReturnType<typeof setTimeout>>();
+  const dataMap = useRef<Record<number, Record<string, unknown>>>({});
+
+  const canProgress = progressMap[page] !== false;
+
+  const handleSetCanProgress = useCallback(
+    (value: boolean) => {
+      setProgressMap((prev) => ({ ...prev, [page]: value }));
+    },
+    [page],
+  );
+
+  const handleSetSlideData = useCallback(
+    (data: Record<string, unknown>) => {
+      dataMap.current[page] = { ...dataMap.current[page], ...data };
+    },
+    [page],
+  );
+
+  const goNext = useCallback(() => {
+    if (page === slides.length - 1) next({ slides: dataMap.current });
+    else setPage((p) => p + 1);
+  }, [page, slides.length, next]);
+
+  const goNextIfCan = useCallback(() => {
+    if (!canProgress) return;
+    goNext();
+  }, [canProgress, goNext]);
+
+  const handleAutoAdvance = useCallback(
+    (delayMs = 0) => {
+      if (autoAdvanceTimer.current) clearTimeout(autoAdvanceTimer.current);
+      autoAdvanceTimer.current = setTimeout(() => goNext(), delayMs);
+    },
+    [goNext],
+  );
+
+  useEffect(() => () => { if (autoAdvanceTimer.current) clearTimeout(autoAdvanceTimer.current); }, []);
+
+  const goBack = useCallback(() => {
+    if (page > 0) setPage((p) => p - 1);
+  }, [page]);
+
+  useEffect(() => {
+    if (nextKey === false && backKey === false) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (nextKey && e.key === nextKey) goNextIfCan();
+      if (backKey && e.key === backKey) goBack();
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [nextKey, backKey, goNextIfCan, goBack]);
+
+  return (
+    <LayoutGroup>
+      <div
+        className={containerClass}
+        style={{
+          width: '100vw',
+          height: '100vh',
+          display: 'flex',
+          flexDirection: 'column',
+          overflow: 'hidden',
+        }}
+      >
+        <div style={{ flex: 1, position: 'relative' }}>
+          <AnimatePresence mode='sync'>
+            <motion.div
+              key={page}
+              initial={{ opacity: 0 }}
+              animate={{ opacity: 1 }}
+              exit={{ opacity: 0 }}
+              transition={{ duration: fadeDuration }}
+              style={{
+                position: 'absolute',
+                inset: 0,
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+              }}
+            >
+              <TutorialSlideContext.Provider value={{ setCanProgress: handleSetCanProgress, autoAdvance: handleAutoAdvance, setSlideData: handleSetSlideData }}>
+                {slides[page]}
+              </TutorialSlideContext.Provider>
+            </motion.div>
+          </AnimatePresence>
+        </div>
+
+        <div
+          style={{
+            padding: '1.5rem',
+            display: 'grid',
+            gridTemplateColumns: '1fr auto 1fr',
+            alignItems: 'center',
+          }}
+        >
+          <div style={{ justifySelf: 'end', marginRight: '1rem' }}>
+            <button
+              onClick={goBack}
+              className={NAV_BTN_ACTIVE}
+              tabIndex={-1}
+              style={{ visibility: page > 0 ? 'visible' : 'hidden' }}
+            >
+              ←
+            </button>
+          </div>
+
+          <div style={{ display: 'flex', gap: 6 }}>
+            {slides.map((_, i) => (
+              <div
+                key={i}
+                style={{
+                  width: 8,
+                  height: 8,
+                  borderRadius: '50%',
+                  backgroundColor: i === page
+                    ? (theme === 'dark' ? '#fff' : '#000')
+                    : (theme === 'dark' ? 'rgba(255,255,255,0.3)' : 'rgba(0,0,0,0.2)'),
+                  transition: 'background-color 0.2s',
+                }}
+              />
+            ))}
+          </div>
+
+          <div style={{ justifySelf: 'start', marginLeft: '1rem' }}>
+            <button
+              onClick={goNextIfCan}
+              tabIndex={-1}
+              className={(canProgress ? NAV_BTN_ACTIVE : NAV_BTN_DISABLED) + (page === slides.length - 1 ? ' px-8' : '')}
+            >
+              {page === slides.length - 1 ? finishText : '→'}
+            </button>
+          </div>
+        </div>
+      </div>
+    </LayoutGroup>
+  );
+};

package/src/components/upload.tsx

@@ -16,9 +16,10 @@ import { BlobWriter, TextReader, ZipWriter } from '@zip.js/zip.js';
 import { Filesystem, Directory, Encoding } from '@capacitor/filesystem';
 import { buildUploadFiles, convertArrayOfObjectsToCSV } from '../utils/upload';
 import { registerSimulation, getBackendUrl, getInitialParticipant } from '../utils/simulation';
+import { uniform } from '../utils/distributions';
 
 registerSimulation('Upload', async (trialProps, experimentState, _simulators, participant) => {
-  const sessionID = trialProps.sessionID || `sim_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+  const sessionID = trialProps.sessionID || `sim_${Date.now()}_${Math.floor(uniform(0, 36 ** 6)).toString(36)}`;
   const files = buildUploadFiles({
     sessionID,
     data: experimentState.data || [],

package/src/mod.tsx

@@ -6,6 +6,8 @@ export * from './utils/array';
 export * from './utils/common';
 export * from './utils/simulation';
 export { registerFlattener, arrayFlattener } from './utils/upload';
+export { normal, poisson, uniform, seedDistributions, sobol, halton, sampleParticipants } from './utils/distributions';
+export type { DimensionSpec, UniformSpec, NormalSpec, PoissonSpec, SamplingMethod } from './utils/distributions';
 export * from './components';
 
 export * from 'react-toastify';

package/src/utils/array.ts

@@ -1,3 +1,5 @@
+import { uniform } from './distributions';
+
 declare global {
   interface Array<T> {
     /**
@@ -36,7 +38,7 @@ export function sample<T>(array: T[], n: number = 1): T[] {
   }
   
   for (let i = 0; i < n; i++) {
-    const randomIndex = Math.floor(Math.random() * array.length);
+    const randomIndex = Math.floor(uniform(0, 1) * array.length);
     result.push(array[randomIndex]);
   }
   
@@ -50,7 +52,7 @@ export function shuffle<T>(array: T[]): T[] {
   const result = [...array];
   
   for (let i = result.length - 1; i >= 0; i--) {
-    const j = Math.floor(Math.random() * (i + 1));
+    const j = Math.floor(uniform(0, 1) * (i + 1));
     [result[i], result[j]] = [result[j], result[i]];
   }
   return result;

package/src/utils/distributions.test.ts

@@ -0,0 +1,209 @@
+import { describe, it, expect } from 'vitest';
+import { sobol, halton, seedDistributions, normal, uniform, poisson, sampleParticipants } from './distributions';
+
+// Known Sobol sequence values (1D, Van der Corput base 2, skipping the zero point)
+// Reference: https://en.wikipedia.org/wiki/Van_der_Corput_sequence
+const SOBOL_1D_EXPECTED = [0.5, 0.75, 0.25, 0.375, 0.875, 0.625, 0.125, 0.1875];
+
+// Known Halton sequence values (base 2 and 3, skipping the zero point)
+// Reference: https://en.wikipedia.org/wiki/Halton_sequence
+const HALTON_2D_EXPECTED = [
+  [0.5, 1 / 3],
+  [0.25, 2 / 3],
+  [0.75, 1 / 9],
+  [0.125, 4 / 9],
+  [0.625, 7 / 9],
+];
+
+describe('sobol', () => {
+  it('produces known 1D Van der Corput values', () => {
+    const result = sobol(8, [{ distribution: 'uniform', min: 0, max: 1 }]) as number[];
+    expect(result).toHaveLength(8);
+    for (let i = 0; i < SOBOL_1D_EXPECTED.length; i++) {
+      expect(result[i]).toBeCloseTo(SOBOL_1D_EXPECTED[i], 10);
+    }
+  });
+
+  it('produces known 2D values', () => {
+    const result = sobol(4, [
+      { distribution: 'uniform', min: 0, max: 1 },
+      { distribution: 'uniform', min: 0, max: 1 },
+    ]) as number[][];
+    // First 2D Sobol points (after skipping zero): [0.5, 0.5], [0.75, 0.25], [0.25, 0.75]
+    expect(result[0]).toEqual([expect.closeTo(0.5, 10), expect.closeTo(0.5, 10)]);
+    expect(result[1]).toEqual([expect.closeTo(0.75, 10), expect.closeTo(0.25, 10)]);
+    expect(result[2]).toEqual([expect.closeTo(0.25, 10), expect.closeTo(0.75, 10)]);
+  });
+
+  it('scales uniform dimensions correctly', () => {
+    const result = sobol(3, [{ distribution: 'uniform', min: 200, max: 800 }]) as number[];
+    // 0.5 * 600 + 200 = 500, 0.75 * 600 + 200 = 650, 0.25 * 600 + 200 = 350
+    expect(result[0]).toBeCloseTo(500, 10);
+    expect(result[1]).toBeCloseTo(650, 10);
+    expect(result[2]).toBeCloseTo(350, 10);
+  });
+
+  it('produces correct count of points', () => {
+    const result = sobol(100, [{ distribution: 'uniform', min: 0, max: 1 }]) as number[];
+    expect(result).toHaveLength(100);
+  });
+
+  it('returns flat array for 1D, nested for multi-D', () => {
+    const r1 = sobol(3, [{ distribution: 'uniform', min: 0, max: 1 }]);
+    expect(typeof r1[0]).toBe('number');
+
+    const r2 = sobol(3, [
+      { distribution: 'uniform', min: 0, max: 1 },
+      { distribution: 'uniform', min: 0, max: 1 },
+    ]);
+    expect(Array.isArray(r2[0])).toBe(true);
+  });
+
+  it('all 1D values are in [0, 1] for unit range', () => {
+    const result = sobol(1000, [{ distribution: 'uniform', min: 0, max: 1 }]) as number[];
+    for (const v of result) {
+      expect(v).toBeGreaterThanOrEqual(0);
+      expect(v).toBeLessThan(1);
+    }
+  });
+
+  it('produces no duplicate points in 2D', () => {
+    const result = sobol(100, [
+      { distribution: 'uniform', min: 0, max: 1 },
+      { distribution: 'uniform', min: 0, max: 1 },
+    ]) as number[][];
+    const keys = new Set(result.map(([a, b]) => `${a},${b}`));
+    expect(keys.size).toBe(100);
+  });
+
+  it('is deterministic (same call twice gives same result)', () => {
+    const a = sobol(50, [{ distribution: 'uniform', min: 0, max: 1 }]);
+    const b = sobol(50, [{ distribution: 'uniform', min: 0, max: 1 }]);
+    expect(a).toEqual(b);
+  });
+
+  it('throws for dimensions > 21', () => {
+    const specs = Array.from({ length: 22 }, () => ({ distribution: 'uniform' as const, min: 0, max: 1 }));
+    expect(() => sobol(10, specs)).toThrow('1-21 dimensions');
+  });
+});
+
+describe('halton', () => {
+  it('produces known 2D values (bases 2, 3)', () => {
+    const result = halton(5, [
+      { distribution: 'uniform', min: 0, max: 1 },
+      { distribution: 'uniform', min: 0, max: 1 },
+    ]) as number[][];
+    for (let i = 0; i < HALTON_2D_EXPECTED.length; i++) {
+      expect(result[i][0]).toBeCloseTo(HALTON_2D_EXPECTED[i][0], 10);
+      expect(result[i][1]).toBeCloseTo(HALTON_2D_EXPECTED[i][1], 10);
+    }
+  });
+
+  it('is deterministic', () => {
+    const a = halton(50, [{ distribution: 'uniform', min: 0, max: 1 }]);
+    const b = halton(50, [{ distribution: 'uniform', min: 0, max: 1 }]);
+    expect(a).toEqual(b);
+  });
+});
+
+describe('normal distribution spec', () => {
+  it('produces values centered around the mean', () => {
+    const result = sobol(1000, [{ distribution: 'normal', mean: 500, sd: 100 }]) as number[];
+    const avg = result.reduce((a, b) => a + b, 0) / result.length;
+    expect(avg).toBeCloseTo(500, 0);
+  });
+
+  it('median is close to mean (symmetric distribution)', () => {
+    const result = sobol(1000, [{ distribution: 'normal', mean: 500, sd: 100 }]) as number[];
+    const sorted = [...result].sort((a, b) => a - b);
+    const median = sorted[500];
+    expect(median).toBeCloseTo(500, 0);
+  });
+});
+
+describe('poisson distribution spec', () => {
+  it('produces non-negative integers', () => {
+    const result = sobol(100, [{ distribution: 'poisson', mean: 5 }]) as number[];
+    for (const v of result) {
+      expect(v).toBeGreaterThanOrEqual(0);
+      expect(Number.isInteger(v)).toBe(true);
+    }
+  });
+
+  it('mean is close to lambda', () => {
+    const result = sobol(1000, [{ distribution: 'poisson', mean: 5 }]) as number[];
+    const avg = result.reduce((a, b) => a + b, 0) / result.length;
+    expect(avg).toBeCloseTo(5, 0);
+  });
+});
+
+describe('sampleParticipants', () => {
+  it('returns objects with the correct keys', () => {
+    const result = sampleParticipants('sobol', 5, {
+      rtMean: { distribution: 'normal', mean: 500, sd: 100 },
+      threshold: { distribution: 'uniform', min: 0.3, max: 0.7 },
+    });
+    expect(result).toHaveLength(5);
+    for (const p of result) {
+      expect(p).toHaveProperty('rtMean');
+      expect(p).toHaveProperty('threshold');
+      expect(typeof p.rtMean).toBe('number');
+      expect(typeof p.threshold).toBe('number');
+    }
+  });
+
+  it('sobol produces deterministic results', () => {
+    const a = sampleParticipants('sobol', 10, { x: { distribution: 'uniform', min: 0, max: 1 } });
+    const b = sampleParticipants('sobol', 10, { x: { distribution: 'uniform', min: 0, max: 1 } });
+    expect(a).toEqual(b);
+  });
+
+  it('halton produces deterministic results', () => {
+    const a = sampleParticipants('halton', 10, { x: { distribution: 'uniform', min: 0, max: 1 } });
+    const b = sampleParticipants('halton', 10, { x: { distribution: 'uniform', min: 0, max: 1 } });
+    expect(a).toEqual(b);
+  });
+
+  it('random method produces valid values', () => {
+    const result = sampleParticipants('random', 50, {
+      score: { distribution: 'poisson', mean: 5 },
+    });
+    expect(result).toHaveLength(50);
+    for (const p of result) {
+      expect(Number.isInteger(p.score)).toBe(true);
+      expect(p.score).toBeGreaterThanOrEqual(0);
+    }
+  });
+
+  it('works with a single dimension', () => {
+    const result = sampleParticipants('sobol', 3, {
+      rt: { distribution: 'uniform', min: 200, max: 800 },
+    });
+    expect(result[0].rt).toBeCloseTo(500, 10);
+    expect(result[1].rt).toBeCloseTo(650, 10);
+    expect(result[2].rt).toBeCloseTo(350, 10);
+  });
+});
+
+describe('seedDistributions', () => {
+  it('makes pseudorandom samplers reproducible', () => {
+    seedDistributions(42);
+    const a = [normal(0, 1), uniform(0, 10), poisson(5)];
+
+    seedDistributions(42);
+    const b = [normal(0, 1), uniform(0, 10), poisson(5)];
+
+    expect(a).toEqual(b);
+  });
+
+  it('different seeds produce different sequences', () => {
+    seedDistributions(1);
+    const a = normal(0, 1);
+
+    seedDistributions(2);
+    const b = normal(0, 1);
+
+    expect(a).not.toBe(b);
+  });
+});