@nyuccl/smile 0.2.0-beta.0

package/dist/runtime/core/config.d.ts

@@ -0,0 +1,166 @@
+declare namespace _default {
+    let mode: any;
+    let smileVersion: any;
+    let projectName: any;
+    let projectRef: any;
+    let codeName: any;
+    let codeNameURL: any;
+    let localStorageKey: string;
+    let devLocalStorageKey: string;
+    namespace github {
+        let repoName: any;
+        let owner: any;
+        let branch: any;
+        let lastCommitMsg: any;
+        let lastCommitHash: any;
+        let commitURL: string;
+    }
+    let allowRepeats: boolean;
+    let autoSave: any;
+    let maxWrites: any;
+    let minWriteInterval: any;
+    let maxSteps: any;
+    let randomSeed: any;
+    let deployURL: any;
+    let labURL: any;
+    let brandLogoFn: any;
+    let colorMode: any;
+    let responsiveUI: boolean;
+    let googleAnalyticsID: any;
+    let windowsizerRequest: object;
+    let windowsizerAggressive: boolean;
+    let anonymousMode: boolean;
+    let unpaidStudy: boolean;
+    namespace sona {
+        let url: any;
+        let experimentId: any;
+        let creditToken: any;
+    }
+    namespace sonaPaid {
+        let url_1: any;
+        export { url_1 as url };
+        let experimentId_1: any;
+        export { experimentId_1 as experimentId };
+        let creditToken_1: any;
+        export { creditToken_1 as creditToken };
+    }
+    namespace spark {
+        let completionUrl: string;
+    }
+    namespace firebaseConfig {
+        let apiKey: any;
+        let authDomain: any;
+        let projectId: any;
+        let storageBucket: any;
+        let messagingSenderId: any;
+        let appId: any;
+    }
+}
+export default _default;
+/**
+ * Global configuration object for the Smile application
+ */
+export type Config = {
+    /**
+     * - Application mode ('development', 'production', 'testing')
+     */
+    mode: string;
+    /**
+     * - Name of the project
+     */
+    projectName: string;
+    /**
+     * - Project reference derived from deploy base path
+     */
+    projectRef: string;
+    /**
+     * - Project code name
+     */
+    codeName: string;
+    /**
+     * - Deploy URL for code name
+     */
+    codeNameURL: string;
+    /**
+     * - Key for storing data in localStorage
+     */
+    localStorageKey: string;
+    /**
+     * - Key for storing dev data in localStorage
+     */
+    devLocalStorageKey: string;
+    /**
+     * - GitHub repository information
+     */
+    github: {
+        repoName: string;
+        owner: string;
+        branch: string;
+        lastCommitMsg: string;
+        lastCommitHash: string;
+        commitURL: string;
+    };
+    /**
+     * - Whether to allow repeat participants
+     */
+    allowRepeats: boolean;
+    /**
+     * - Whether to auto-save data
+     */
+    autoSave: boolean;
+    /**
+     * - Maximum number of writes allowed
+     */
+    maxWrites: number;
+    /**
+     * - Minimum interval between writes
+     */
+    minWriteInterval: number;
+    /**
+     * - Maximum rows in stepper tables
+     */
+    maxSteps: number;
+    /**
+     * - Seed for random number generation
+     */
+    randomSeed: string;
+    /**
+     * - URL where app is deployed
+     */
+    deployURL: string;
+    /**
+     * - URL of the lab website
+     */
+    labURL: string;
+    /**
+     * - Function name for brand logo
+     */
+    brandLogoFn: string;
+    /**
+     * - Google Analytics tracking ID
+     */
+    googleAnalyticsID: string;
+    /**
+     * - Requested window dimensions
+     */
+    windowsizerRequest: object;
+    /**
+     * - Whether to force window sizing
+     */
+    windowsizerAggressive: boolean;
+    /**
+     * - Whether to enable anonymous mode
+     */
+    anonymousMode: boolean;
+    /**
+     * - Firebase configuration object
+     */
+    firebaseConfig: {
+        apiKey: string;
+        authDomain: string;
+        projectId: string;
+        storageBucket: string;
+        messagingSenderId: string;
+        appId: string;
+    };
+};

package/dist/runtime/core/config.js

@@ -0,0 +1,118 @@
+/**
+ * @fileoverview Global configuration options for the Smile application.
+ * @description This module exports configuration settings used throughout the app.
+ * Configuration values are populated from environment variables during build time
+ * using Vite's import.meta.env string replacement.
+ * @module config
+ */
+/**
+ * Parses a string in the format "WIDTHxHEIGHT" into width and height values
+ * @param {string} value - String in format "WIDTHxHEIGHT" (e.g. "800x600")
+ * @returns {object} Object containing parsed width and height as integers
+ * @property {number} width - The parsed width value
+ * @property {number} height - The parsed height value
+ */
+function parseWidthHeight(value) {
+  // receives configuration option as WIDTHxHEIGHT
+  // split based on 'x' and assign to objects
+  if (!value) return { width: 0, height: 0 }
+  const w_h = value.split('x')
+  return { width: Number.parseInt(w_h[0]), height: Number.parseInt(w_h[1]) }
+}
+
+/**
+ * Global configuration object for the Smile application
+ * @typedef {object} Config
+ * @property {string} mode - Application mode ('development', 'production', 'testing')
+ * @property {string} projectName - Name of the project
+ * @property {string} projectRef - Project reference derived from deploy base path
+ * @property {string} codeName - Project code name
+ * @property {string} codeNameURL - Deploy URL for code name
+ * @property {string} localStorageKey - Key for storing data in localStorage
+ * @property {string} devLocalStorageKey - Key for storing dev data in localStorage
+ * @property {object} github - GitHub repository information
+ * @property {string} github.repoName - Repository name
+ * @property {string} github.owner - Repository owner
+ * @property {string} github.branch - Current branch name
+ * @property {string} github.lastCommitMsg - Last commit message
+ * @property {string} github.lastCommitHash - Last commit hash
+ * @property {string} github.commitURL - URL to last commit
+ * @property {boolean} allowRepeats - Whether to allow repeat participants
+ * @property {boolean} autoSave - Whether to auto-save data
+ * @property {number} maxWrites - Maximum number of writes allowed
+ * @property {number} minWriteInterval - Minimum interval between writes
+ * @property {number} maxSteps - Maximum rows in stepper tables
+ * @property {string} randomSeed - Seed for random number generation
+ * @property {string} deployURL - URL where app is deployed
+ * @property {string} labURL - URL of the lab website
+ * @property {string} brandLogoFn - Function name for brand logo
+ * @property {string} googleAnalyticsID - Google Analytics tracking ID
+ * @property {object} windowsizerRequest - Requested window dimensions
+ * @property {boolean} windowsizerAggressive - Whether to force window sizing
+ * @property {boolean} anonymousMode - Whether to enable anonymous mode
+ * @property {object} firebaseConfig - Firebase configuration object
+ * @property {string} firebaseConfig.apiKey - Firebase API key
+ * @property {string} firebaseConfig.authDomain - Firebase auth domain
+ * @property {string} firebaseConfig.projectId - Firebase project ID
+ * @property {string} firebaseConfig.storageBucket - Firebase storage bucket
+ * @property {string} firebaseConfig.messagingSenderId - Firebase messaging sender ID
+ * @property {string} firebaseConfig.appId - Firebase app ID
+ */
+export default {
+  mode: import.meta.env.MODE,
+  smileVersion: import.meta.env.VITE_SMILE_VERSION,
+  projectName: import.meta.env.VITE_PROJECT_NAME, // autocompute this on intitialization
+  projectRef: (import.meta.env.VITE_DEPLOY_BASE_PATH || '/').slice(1, -1).replace(/\//g, '-'),
+  codeName: import.meta.env.VITE_CODE_NAME,
+  codeNameURL: import.meta.env.VITE_CODE_NAME_DEPLOY_URL,
+  localStorageKey: `smilestore-${import.meta.env.VITE_CODE_NAME}`,
+  devLocalStorageKey: `smilestore-${import.meta.env.VITE_CODE_NAME}_dev`,
+  github: {
+    repoName: import.meta.env.VITE_GIT_REPO_NAME,
+    owner: import.meta.env.VITE_GIT_OWNER,
+    branch: import.meta.env.VITE_GIT_BRANCH_NAME,
+    lastCommitMsg: import.meta.env.VITE_GIT_LAST_MSG,
+    lastCommitHash: import.meta.env.VITE_GIT_HASH, // autocompute this all the time
+    commitURL: `https://github.com/${import.meta.env.VITE_GIT_OWNER}/${import.meta.env.VITE_GIT_REPO_NAME}/commit/${
+      import.meta.env.VITE_GIT_HASH
+    }`,
+  },
+  // browser_exclude: import.meta.env.VITE_BROWSER_EXCLUDE,
+  allowRepeats: import.meta.env.VITE_ALLOW_REPEATS === 'true',
+  autoSave: import.meta.env.VITE_AUTO_SAVE_DATA,
+  maxWrites: import.meta.env.VITE_MAX_WRITES,
+  minWriteInterval: import.meta.env.VITE_MIN_WRITE_INTERVAL,
+  maxSteps: import.meta.env.VITE_MAX_STEPS,
+  randomSeed: import.meta.env.VITE_RANDOM_SEED,
+  deployURL: import.meta.env.VITE_DEPLOY_URL, // auto compute this
+  labURL: import.meta.env.VITE_LAB_URL,
+  brandLogoFn: import.meta.env.VITE_BRAND_LOGO_FN,
+  colorMode: import.meta.env.VITE_COLOR_MODE, // 'light' or 'dark' or 'system'
+  responsiveUI: import.meta.env.VITE_RESPONSIVE_UI === 'true',
+  googleAnalyticsID: import.meta.env.VITE_GOOGLE_ANALYTICS,
+  windowsizerRequest: parseWidthHeight(import.meta.env.VITE_WINDOWSIZER_REQUEST),
+  windowsizerAggressive: import.meta.env.VITE_WINDOWSIZER_AGGRESSIVE === 'true',
+  anonymousMode: import.meta.env.VITE_ANONYMOUS_MODE === 'true',
+  unpaidStudy: import.meta.env.VITE_UNPAID_STUDY === 'true',
+  sona: {
+    url: import.meta.env.VITE_SONA_URL,
+    experimentId: import.meta.env.VITE_SONA_EXPERIMENT_ID,
+    creditToken: import.meta.env.VITE_SONA_CREDIT_TOKEN,
+  },
+  sonaPaid: {
+    url: import.meta.env.VITE_SONA_PAID_URL,
+    experimentId: import.meta.env.VITE_SONA_PAID_EXPERIMENT_ID,
+    creditToken: import.meta.env.VITE_SONA_PAID_CREDIT_TOKEN,
+  },
+  spark: {
+    completionUrl: 'https://spark.hartleylab.org/completed',
+  },
+  firebaseConfig: {
+    apiKey: import.meta.env.VITE_FIREBASE_APIKEY,
+    authDomain: import.meta.env.VITE_FIREBASE_AUTHDOMAIN,
+    projectId: import.meta.env.VITE_FIREBASE_PROJECTID,
+    storageBucket: import.meta.env.VITE_FIREBASE_STORAGEBUCKET,
+    messagingSenderId: import.meta.env.VITE_FIREBASE_MESSAGINGSENDERID,
+    appId: import.meta.env.VITE_FIREBASE_APPID,
+  },
+}

package/dist/runtime/core/stepper/StepState.d.ts

@@ -0,0 +1,332 @@
+/**
+ * @class StepState
+ * @description A tree-based state management class for hierarchical navigation.
+ *
+ * StepState represents a node in a tree structure where each node can have:
+ * - A id (string, number, or custom type)
+ * - Multiple child states
+ * - Associated data
+ * - Navigation capabilities (next/prev)
+ *
+ * Used with StepperStateMachine for higher-level state management.
+ *
+ * @property {*} _id - The node's unique identifier (used to create a path to this node)
+ * @property {StepState[]} _states - Array of child nodes/states
+ * @property {number} _currentIndex - Index tracking current position in children
+ * @property {number} _depth - Depth of this node in the tree (0 for root)
+ * @property {StepState|null} _parent - Reference to parent node
+ * @property {StepState} _root - Reference to root node
+ * @property {object} _data - Associated data for this node
+ */
+export class StepState {
+    /**
+     * Creates a new StepState node in a tree structure.
+     * @param {*} id - The id for this node. If null, defaults to '/'
+     * @param {StepState|null} parent - The parent node. If null, this is a root node
+     *
+     * This constructor initializes:
+     * - id: The node's id (used to create a path to this node)
+     * - states: Array of child nodes (also called rows)
+     * - currentIndex: Index tracking current position when traversing children
+     * - depth: How deep this node is in the tree (0 for root)
+     * - parent: Reference to parent node
+     * - data: Object to store arbitrary data
+     * - root: Reference to root node of the tree
+     */
+    constructor(id?: any, parent?: StepState | null);
+    _id: any;
+    _states: any[];
+    _currentIndex: number;
+    _depth: number;
+    _parent: StepState | null;
+    _root: this;
+    _data: {};
+    /**
+     * Gets the number of child states in this node
+     * @returns {number} The number of child states
+     */
+    get length(): number;
+    /**
+     * Gets the parent node of this state node
+     * @returns {StepState|null} The parent StepState node, or null if this is the root
+     */
+    get parent(): StepState | null;
+    /**
+     * Sets the id of this node and updates the data field to include the id
+     * @param {*} id - The new id to set
+     */
+    set id(id: any);
+    /**
+     * Gets the id of this node
+     * @returns {*} The node's id
+     */
+    get id(): any;
+    /**
+     * Sets the array of child states for this node
+     * @param {StepState[]} states - Array of child StepState nodes to set
+     */
+    set states(states: StepState[]);
+    /**
+     * Gets the array of child states for this node
+     * @returns {StepState[]} Array of child StepState nodes
+     */
+    get states(): StepState[];
+    /**
+     * Sets the current index position in the state sequence
+     * @param {number} index - The index position to set
+     */
+    set index(index: number);
+    /**
+     * Gets the current index position in the state sequence
+     * @returns {number} The current index
+     */
+    get index(): number;
+    /**
+     * Gets the index of the parent node of the current leaf.
+     * @returns {number|null} The index of the parent node, or null if there is no parent
+     */
+    get parentIndex(): number | null;
+    /**
+     * Gets the index of the parent node of the current leaf in the state tree.
+     * Traverses down from root to find the current leaf node, then returns its parent's index.
+     * @returns {number|null} The index of the parent node of the current leaf, or null if there is no parent
+     */
+    get blockIndex(): number | null;
+    /**
+     * Gets the number of states in the parent node of the current leaf in the state tree.
+     * Traverses down from root to find the current leaf node, then returns its parent's state count.
+     * @returns {number} The number of states in the parent node, or 0 if there is no parent
+     */
+    get blockLength(): number;
+    /**
+     * Setter for data property
+     * @param {*} data - The data to store in this node
+     */
+    set data(data: any);
+    /**
+     * Getter for data property
+     * @returns {*} The data stored in this node
+     */
+    get data(): any;
+    /**
+     * Gets the root node of the state tree
+     * @returns {StepState} The root StepState node
+     */
+    get root(): StepState;
+    /**
+     * Get all child states of the current state.
+     * row is just a synonym for child states
+     * row lines a bit more with the table metaphor
+     *
+     * @returns {Array<StepState>} Array of child StepState nodes
+     */
+    get rows(): Array<StepState>;
+    /**
+     * Get data from all child states of the current state.
+     * row is just a synonym for child states
+     * row lines a bit more with the table metaphor
+     *
+     * @returns {Array} Array of data values from all child states
+     */
+    get rowsData(): any[];
+    /**
+     * Get data from all child states of the current state.
+     *
+     * @returns {Array} Array of data values from all child states
+     */
+    get statesData(): any[];
+    /**
+     * Gets the depth of this node in the tree.
+     * @returns {number} The depth of this node
+     */
+    get depth(): number;
+    /**
+     * Gets the maximum depth of the tree beneath this node.
+     * @returns {number} The maximum depth of the tree beneath this node
+     */
+    get treeDepth(): number;
+    /**
+     * Checks if this node is a leaf node (has no child states).
+     * @returns {boolean} True if this node has no child states, false otherwise
+     */
+    get isLeaf(): boolean;
+    /**
+     * Checks if this node is the first non-special leaf node in the tree.
+     *
+     * A leaf node is considered "first" if:
+     * 1. It is a leaf node (has no children)
+     * 2. It is the leftmost leaf node when traversing the tree
+     *
+     * @returns {boolean} True if this is the first non-special leaf node, false otherwise
+     */
+    get isFirstLeaf(): boolean;
+    /**
+     * Checks if there is a next state available.
+     * @returns {boolean} True if there is a next state, false otherwise
+     */
+    hasNext(): boolean;
+    /**
+     * Checks if there is a previous state available.
+     * @returns {boolean} True if there is a previous state, false otherwise
+     */
+    hasPrev(): boolean;
+    /**
+     * Checks if this state has any child states.
+     * @returns {boolean} True if this state has child states, false otherwise
+     */
+    hasSteps(): boolean;
+    /**
+     * Peeks at the next state without moving the current position.
+     * @returns {StepState|null} The next state or null if no next state exists
+     */
+    peekNext(): StepState | null;
+    /**
+     * Peeks at the previous state without moving the current position.
+     * @returns {StepState|null} The previous state or null if no previous state exists
+     */
+    peekPrev(): StepState | null;
+    /**
+     * Creates a new state instance. This method is used internally to create new states
+     * and can be overridden by subclasses to return instances of the subclass.
+     * @protected
+     * @param {*} id - The id for the new state
+     * @param {StepState} parent - The parent state
+     * @returns {StepState} A new state instance
+     */
+    protected _createNew(id: any, parent: StepState): StepState;
+    /**
+     * Creates and adds a new child state to this node.
+     * If no id is provided, automatically assigns the next available index as the id.
+     * @param {*} id - Optional id for the new state. If null, uses states.length
+     * @param {*} data - Optional data to associate with the new state
+     * @returns {StepState} The newly created child state
+     * @throws {Error} If a state with the given id already exists
+     */
+    push(id?: any, data?: any): StepState;
+    /**
+     * Inserts a new state at the specified position in the list of children.
+     * Maintains the invariant that we're always pointing to a leaf node.
+     * @param {*} id - Optional id for the new state. If null, uses states.length
+     * @param {number} index - Position to insert at. Can be positive (0-based) or negative (from end).
+     * @param {*} data - Optional data to associate with the new state
+     * @returns {StepState} The newly created child state
+     * @throws {Error} If a state with the given id already exists
+     */
+    insert(id?: any, index?: number, data?: any): StepState;
+    /**
+     * Resets the traversal state of this node and all its descendants.
+     * Sets currentIndex back to 0 for this node,
+     * then recursively resets all child nodes.
+     */
+    reset(): void;
+    /**
+     * Resets the state machine and navigates to the specified path.
+     * If the path points to a leaf node, stays at that leaf.
+     * If the path points to a non-leaf node, traverses to its leftmost leaf.
+     * @param {Array|string} path - Path to navigate to (array of ids or hyphen-separated string)
+     * @throws {Error} If the path doesn't exist
+     */
+    goTo(path: any[] | string): void;
+    /**
+     * Moves to the next state in the sequence.
+     * @returns {StepState|null} The next state or null if no next state exists
+     */
+    next(): StepState | null;
+    /**
+     * Moves to the previous state in the sequence.
+     * @returns {StepState|null} The previous state or null if no previous state exists
+     */
+    prev(): StepState | null;
+    /**
+     * Gets all leaf node paths in the tree beneath this node.
+     * A leaf node is defined as a node that has no children.
+     * @returns {string} A slash-separated string of leaf node paths
+     */
+    get leafNodes(): string;
+    /**
+     * Gets the total number of leaf nodes in the tree beneath this node.
+     * A leaf node is defined as a node that has no children.
+     * @returns {number} The count of leaf nodes
+     */
+    get countLeafNodes(): number;
+    /**
+     * Gets a child node by its index or id.
+     * @param {number|*} identifier - Either the index or id of the child node to find
+     * @returns {StepState|null} The found child node, or null if not found
+     */
+    getNode(identifier: number | any): StepState | null;
+    /**
+     * Gets the path from root to this node by walking up the parent chain.
+     * Returns an array of ids representing each node's id along the path,
+     * excluding the root node ('/').
+     * This is distinct from the currentPath property which returns the path from the
+     * root to the current selected node by following .index.
+     * For example, if we have root -> A -> B -> C, calling getPath() on C returns ['A','B','C']
+     * @returns {Array} Array of ids representing the path from root to this node
+     */
+    get path(): any[];
+    /**
+     * Gets the path string for this node by walking up the parent chain.
+     * Returns a slash-separated string of ids representing each node's id,
+     * including the root node ('/').
+     * This is distinct from the currentPath property which returns the path from the
+     * root to the current selected node by following .index.
+     * @returns {string} Slash-separated string representing the path to this node
+     */
+    get pathString(): string;
+    /**
+     * Gets all unique paths in the tree beneath this node.
+     * @returns {Set<string>} Set of all unique paths in the tree
+     */
+    get existingPaths(): Set<string>;
+    /**
+     * Gets an array of data objects from all nodes along the current path, from root to leaf.
+     * @returns {Array} Array of data objects, where each element is the complete data from a node along the path
+     */
+    get dataAlongPath(): any[];
+    /**
+     * Sets data for a node at the specified path
+     * @param {Array|string} path - Path to the node (array of ids or slash-separated string)
+     * @param {object} data - Data to associate with the node
+     * @throws {Error} If the path doesn't exist
+     */
+    setDataAtPath(path: any[] | string, data: object): void;
+    /**
+     * Returns the current path through the tree as a list of ids
+     * @returns {Array} Array of ids representing the current path
+     */
+    get currentPath(): any[];
+    /**
+     * Returns the current path through the tree as a slash-separated string
+     * @returns {string} String representation of the current path
+     */
+    get currentPathString(): string;
+    /**
+     * Returns the data from the current leaf node in the tree
+     * @returns {*} The data from the current leaf node
+     */
+    get currentData(): any;
+    /**
+     * Returns a string representation of the tree structure beneath this node
+     * @returns {string} Tree diagram
+     */
+    get treeDiagram(): string;
+    /**
+     * Completely clears all states and resets to initial condition
+     * Removes all child states and resets all internal properties
+     * also clears the data from the current node
+     */
+    clear(): void;
+    /**
+     * Clears all data from the current node by resetting the data object to empty
+     * Does not affect child nodes or the structure of the state tree
+     */
+    clearData(): void;
+    /**
+     * Completely clears all states and resets to initial condition
+     * Removes all child states and resets all internal properties
+     * does _not_ clear the data from the current node
+     */
+    clearSubTree(): void;
+}
+export default StepState;