@nyuccl/smile 0.2.0-beta.0

package/dist/runtime/composables/useViewAPI.d.ts

@@ -0,0 +1,513 @@
+/**
+ * Creates and returns a reactive ViewAPI instance
+ * @returns {ViewAPI} A reactive ViewAPI instance with all view-specific functionality
+ */
+declare function useViewAPI(): ViewAPI;
+declare namespace useViewAPI {
+    /**
+     * Resets the ViewAPI instance to null. Used for testing purposes.
+     * @private
+     * @function _reset
+     * @memberof useViewAPI
+     */
+    function _reset(): void;
+}
+export default useViewAPI;
+/**
+ * ViewAPI class extends SmileAPI with view-specific functionality
+ * @class
+ * @extends SmileAPI
+ * @description Extends the core SmileAPI with additional view-specific functionality including:
+ * - Stepper controls and state management
+ * - Data recording capabilities
+ * - Mouse and keyboard event handlers
+ */
+declare class ViewAPI extends SmileAPI {
+    constructor(store: any, logStore: any, route: any, router: any, timeline: any, runtimeConfig: any);
+    _route: any;
+    _page: import("vue").ComputedRef<any>;
+    _stepper: import("vue").ComputedRef<object | null>;
+    _dataAlongPath: import("vue").Ref<null, null>;
+    _path: import("vue").Ref<null, null>;
+    _pathString: import("vue").Ref<string, string>;
+    _index: import("vue").Ref<null, null>;
+    _stateMachine: import("vue").Ref<null, null>;
+    _gvars: import("vue").Ref<{}, {}>;
+    componentRegistry: Map<any, any>;
+    onKeyDown: typeof onKeyDown;
+    onKeyPressed: typeof onKeyPressed;
+    onKeyUp: typeof onKeyUp;
+    useMouse: typeof useMouse;
+    useMousePressed: typeof useMousePressed;
+    /**
+     * The underlying state machine instance
+     * @name steps
+     * @memberof ViewAPI
+     * @instance
+     * @type {Stepper}
+     * @description Provides direct access to the underlying Stepper state machine instance.
+     * This allows advanced manipulation of the state machine when needed.
+     */
+    get steps(): Stepper;
+    /**
+     * Checks if there is a next step available in the stepper.
+     * @returns {boolean} True if there is a next step available, false otherwise.
+     * @memberof ViewAPI
+     * @instance
+     */
+    hasNextStep(): boolean;
+    /**
+     * Checks if there is a previous step available in the stepper.
+     * @returns {boolean} True if there is a previous step available, false otherwise.
+     * @memberof ViewAPI
+     * @instance
+     */
+    hasPrevStep(): boolean;
+    /**
+     * Checks if there are any steps in the stepper.
+     * Calls on the root stepper to check for steps, avoiding leaf node checks if none exist.
+     * @returns {boolean} True if there are steps in the stepper, false otherwise.
+     * @memberof ViewAPI
+     * @instance
+     */
+    hasSteps(): boolean;
+    /**
+     * Advances to the next step in the stepper.
+     * Updates the stepper state if a next step exists.
+     * @param {boolean} [resetScroll] - Whether to reset scroll position to top after navigation
+     * @returns {object | null} The next state object if one exists, null otherwise
+     * @memberof ViewAPI
+     * @instance
+     */
+    goNextStep(resetScroll?: boolean): object | null;
+    /**
+     * Returns to the previous step in the stepper.
+     * Updates the stepper state if a previous step exists.
+     * @param {boolean} [resetScroll] - Whether to reset scroll position to top after navigation
+     * @returns {object | null} The previous state object if one exists, null otherwise
+     * @memberof ViewAPI
+     * @instance
+     */
+    goPrevStep(resetScroll?: boolean): object | null;
+    /**
+     * Resets the stepper to its first step.
+     * Updates the stepper state after resetting to the initial position.
+     * @param {boolean} [resetScroll] - Whether to reset scroll position to top after navigation
+     * @returns {void}
+     * @memberof ViewAPI
+     * @instance
+     */
+    goFirstStep(resetScroll?: boolean): void;
+    /**
+     * Navigates to a specific step by path.
+     * Updates the stepper state after navigating to the specified path.
+     * @param {string} path - The path of the step to navigate to (e.g. "trial/block1/step2")
+     * @param {boolean} [resetScroll] - Whether to reset scroll position to top after navigation
+     * @returns {void}
+     * @memberof ViewAPI
+     * @instance
+     */
+    goToStep(path: string, resetScroll?: boolean): void;
+    /**
+     * Gets the current step index among leaf nodes in the stepper.
+     * The step index represents the position of the current path string
+     * within the flattened array of leaf nodes.
+     * @returns {number} The zero-based index of the current step, or -1 if not found
+     * @memberof ViewAPI
+     * @instance
+     */
+    get stepIndex(): number;
+    /**
+     * Gets the current block index in the stepper.
+     * The block index represents the position within the current block of steps.
+     * @returns {number} The zero-based index within the current block
+     * @memberof ViewAPI
+     * @instance
+     */
+    get blockIndex(): number;
+    /**
+     * Gets the current path as a string representation.
+     * The path string is a forward-slash delimited string of step names representing
+     * the current location in the stepper (e.g. "trial/block1/step2").
+     * @returns {string} The current path string
+     * @memberof ViewAPI
+     * @instance
+     */
+    get pathString(): string;
+    /**
+     * Gets the current path as an array.
+     * The path array contains the sequence of step names representing the current
+     * location in the stepper (e.g. ['trial', 'block1', 'step2']).
+     * @returns {string[]} The current path array
+     * @memberof ViewAPI
+     * @instance
+     */
+    get path(): string[];
+    /**
+     * Gets the total number of leaf nodes in the stepper.
+     * This represents the total number of steps in the sequence, excluding any parent/container nodes.
+     * @returns {number} The total number of leaf nodes
+     * @memberof ViewAPI
+     * @instance
+     */
+    get length(): number;
+    /**
+     * Checks if the current step is the last step in the sequence.
+     * This compares the current step index against the total number of steps.
+     * @returns {boolean} True if this is the last step, false otherwise
+     * @memberof ViewAPI
+     * @instance
+     */
+    isLastStep(): boolean;
+    /**
+     * Checks if the current step is the last step in the current block.
+     * This compares the current block index against the total length of the block.
+     * @returns {boolean} True if this is the last step in the block, false otherwise
+     * @memberof ViewAPI
+     * @instance
+     */
+    isLastBlockStep(): boolean;
+    /**
+     * Gets the number of steps in the current block.
+     * This represents the total number of steps at the current level in the stepper hierarchy.
+     * @returns {number} The number of steps in the current block
+     * @memberof ViewAPI
+     * @instance
+     */
+    get blockLength(): number;
+    /**
+     * Gets the total number of leaf nodes in the stepper.
+     * This is an alias for nSteps that represents the total number of steps in the sequence.
+     * @returns {number} The total number of leaf nodes
+     * @memberof ViewAPI
+     * @instance
+     * @see nSteps
+     */
+    get stepLength(): number;
+    /**
+     * Alias for stepLength.
+     * Returns the total number of leaf nodes in the stepper.
+     * @returns {number} The total number of leaf nodes
+     * @memberof ViewAPI
+     * @instance
+     * @see stepLength
+     */
+    get nSteps(): number;
+    /**
+     * Persistence Methods
+     *
+     * These methods provide functionality for storing and accessing variables that persist across browser reloads.
+     * Persistence is handled through the stepper's root data store and variables are accessible via the `persist` getter.
+     *
+     * Available persistence methods:
+     * - persist: Getter that provides access to persisted variables stored in stepper root data
+     * - persist.isDefined(key): Checks if a persisted variable exists
+     * - clearPersist(): Clears all persisted variables
+     *
+     * Example usage:
+     * ```js
+     * // Set a persisted value
+     * api.persist.myVar = 'some value'
+     *
+     * // Check if variable exists
+     * if (api.persist.isDefined('myVar')) {
+     *   // Access persisted value
+     *   console.log(api.persist.myVar)
+     * }
+     *
+     * // Clear all persisted values
+     * api.clearPersist()
+     * ```
+     */
+    /**
+     * Getter that provides access to persisted variables stored in the stepper's root data.
+     * Creates a recursive proxy to handle nested object access and updates.
+     *
+     * @returns {Proxy} A proxy object that provides access to persisted variables with:
+     *   - get: Returns persisted values and the isDefined() helper method
+     *   - set: Updates persisted values and triggers stepper update
+     * @memberof ViewAPI
+     * @instance
+     *
+     * @example
+     * // Set a persisted value
+     * api.persist.myVar = 'value'
+     *
+     * // Get a persisted value
+     * const value = api.persist.myVar
+     *
+     * // Check if variable exists
+     * if (api.persist.isDefined('myVar')) {
+     *   // Variable exists
+     * }
+     */
+    get persist(): ProxyConstructor;
+    /**
+     * Clears all persisted variables stored in the stepper's root data.
+     * This resets both the internal gvars ref and the stepper's root data gvars to empty objects.
+     * @method clearPersist
+     * @memberof ViewAPI
+     * @instance
+     * @returns {void}
+     * @example
+     * // Clear all persisted variables
+     * api.clearPersist()
+     */
+    clearPersist(): void;
+    /**
+     * Timing Methods
+     *
+     * These methods provide functionality for tracking elapsed time during the experiment.
+     * Times are stored in the persisted variables (gvars) and can be accessed across steps.
+     * Multiple named timers can be running simultaneously.
+     *
+     * Available timing methods:
+     * - startTimer(name): Starts a named timer
+     * - isTimerStarted(name): Checks if a timer exists
+     * - elapsedTime(name): Gets elapsed time in milliseconds
+     * - elapsedTimeInSeconds(name): Gets elapsed time in seconds
+     * - elapsedTimeInMinutes(name): Gets elapsed time in minutes
+     *
+     * @memberof ViewAPI
+     */
+    /**
+     * Starts a named timer by storing the current timestamp in persisted variables
+     * @param {string} [name] - The name of the timer to start
+     * @returns {void}
+     * @memberof ViewAPI
+     * @instance
+     */
+    startTimer(name?: string): void;
+    /**
+     * Checks if a named timer has been started
+     * @param {string} [name] - The name of the timer to check
+     * @returns {boolean} True if the timer exists and has been started, false otherwise
+     * @memberof ViewAPI
+     * @instance
+     */
+    isTimerStarted(name?: string): boolean;
+    /**
+     * Gets the elapsed time in milliseconds since a named timer was started
+     * @param {string} [name] - The name of the timer to check
+     * @returns {number} Elapsed time in milliseconds
+     * @memberof ViewAPI
+     * @instance
+     */
+    elapsedTime(name?: string): number;
+    /**
+     * Gets the elapsed time in seconds since a named timer was started
+     * @param {string} [name] - The name of the timer to check
+     * @returns {number} Elapsed time in seconds
+     * @memberof ViewAPI
+     * @instance
+     */
+    elapsedTimeInSeconds(name?: string): number;
+    /**
+     * Gets the elapsed time in minutes since a named timer was started
+     * @param {string} [name] - The name of the timer to check
+     * @returns {number} Elapsed time in minutes
+     * @memberof ViewAPI
+     * @instance
+     */
+    elapsedTimeInMinutes(name?: string): number;
+    /**
+     * Data Methods
+     *
+     * These methods provide functionality for storing and retrieving data associated with each step in a view.
+     * Data is persisted with each step and can be accessed later when revisiting steps.
+     *
+     * The data methods include:
+     * - stepData: Gets/sets merged data from all steps in the current path (parent blocks + current step)
+     * - stepDataLeaf: Gets/sets data for only the current step (leaf node)
+     * - dataAlongPath: Gets raw data array for all steps in the current path
+     * - queryStepData(): Gets data for all steps, optionally filtered by path pattern
+     * - clearCurrentStepData(): Clears data for the current step
+     * - clear(): Clears all step data for the current view
+     *
+     * Data can be accessed and modified through stepData (merged) or stepDataLeaf (current step only):
+     * @example
+     * // Get merged data from current path (includes parent block data)
+     * const data = api.stepData
+     *
+     * // Get data from only current step
+     * const leafData = api.stepDataLeaf
+     *
+     * // Set data on current step
+     * api.stepDataLeaf.response = 'some value'
+     *
+     * // Get data from all steps matching a path pattern
+     * const allData = api.queryStepData('trial/block*')
+     *
+     * // Clear current step data
+     * api.clearCurrentStepData()
+     *
+     * @memberof ViewAPI
+     */
+    /**
+     * Gets merged data from all steps in the current path (parent blocks + current step)
+     * @returns {object | null} Merged data object containing properties from all steps in current path, or null if no path data exists
+     * @memberof ViewAPI
+     * @instance
+     * @example
+     * // Get merged data including parent block data
+     * const data = api.stepData
+     * console.log(data.blockType) // Access block-level property
+     * console.log(data.response) // Access step-level property
+     *
+     * // Modify data (changes are saved to current step)
+     * api.stepData.response = 'new value'
+     */
+    get stepData(): object | null;
+    /**
+     * Gets the data only from the current leaf node of the current path.
+     * This is similar to stepData but only includes data from the current leaf node,
+     * not the entire path. Works with nested objects and arrays through a proxy.
+     * @returns {Proxy|null} A proxy object for the current leaf node's data, or null if no data exists
+     * @memberof ViewAPI
+     * @instance
+     * @example
+     * // Get a value from the current leaf node
+     * const value = api.stepDataLeaf.myVariable
+     *
+     * // Set a value in the current leaf node
+     * api.stepDataLeaf.myVariable = 'new value'
+     *
+     * // Work with nested objects
+     * api.stepDataLeaf.nested.obj.prop = 123
+     *
+     * // Work with arrays
+     * api.stepDataLeaf.myArray[0] = 'first item'
+     */
+    get stepDataLeaf(): ProxyConstructor | null;
+    /**
+     * Gets the path data for the current step, with component types resolved from the registry
+     * @returns {Array|null} Array of path data objects with resolved component types, or null if no path data exists
+     */
+    get dataAlongPath(): any[] | null;
+    /**
+     * Gets data for all leaf nodes in the stepper, optionally filtered by path pattern.
+     * Returns only the data directly associated with each leaf node, without merging parent block data.
+     * @param {string|null} [pathFilter] - Optional path pattern to filter nodes (e.g. 'trial/block*')
+     * @returns {Array<object>} Array of data objects for each matching leaf node
+     * @memberof ViewAPI
+     * @instance
+     * @example
+     * // Get data for all leaf nodes
+     * const allLeafData = api.queryStepDataLeaf()
+     *
+     * // Get data for nodes matching a pattern
+     * const trialData = api.queryStepDataLeaf('trial/block*')
+     */
+    queryStepDataLeaf(pathFilter?: string | null): Array<object>;
+    /**
+     * Gets data for all leaf nodes in the stepper, optionally filtered by path pattern.
+     * Returns only the data directly associated with each leaf node, excluding global variables.
+     * @param {string|null} pathFilter - Optional path pattern to filter nodes (e.g. 'trial/block*')
+     * @returns {Array} Array of data objects for each matching leaf node, with gvars removed
+     * @memberof ViewAPI
+     * @instance
+     * @example
+     * // Get data for all leaf nodes
+     * const allData = api.queryStepData()
+     *
+     * // Get data for nodes matching a pattern
+     * const trialData = api.queryStepData('trial/block*')
+     */
+    queryStepData(pathFilter?: string | null): any[];
+    /**
+     * Clears all data for the current view's stepper
+     * @method clear
+     * @memberof ViewAPI
+     * @instance
+     * @description Removes the stepper state from browser storage, clears the stepper's data subtree,
+     * clears the component registry, and saves the cleared state
+     * @returns {void}
+     * @example
+     * // Clear all data for current view
+     * api.clear()
+     */
+    clear(): void;
+    /**
+     * Clears the data for the current step in the stepper
+     * @method clearCurrentStepData
+     * @memberof ViewAPI
+     * @instance
+     * @description Clears only the data for the current step, leaving other step data intact,
+     * then saves the updated stepper state
+     * @returns {void}
+     * @example
+     * // Clear data for current step
+     * api.clearCurrentStepData()
+     */
+    clearCurrentStepData(): void;
+    /**
+     * Records the current step data to the experiment data store
+     * @method recordStep
+     * @memberof ViewAPI
+     * @instance
+     * @description Logs the current step data and records it to the experiment data store using recordPageData
+     * @returns {void}
+     */
+    recordStep(): void;
+    /**
+     * Utility Functions
+     *
+     * These methods handle updating and saving the reactive state properties of the view:
+     * - _updateStepperState: Updates internal reactive refs from stepper data
+     * - updateStepper: Public method to trigger stepper state update
+     * - _visualizeStateMachine: Creates clean visualization of state machine
+     * - _saveStepperState: Persists current stepper state to store
+     *
+     * The utility functions maintain consistency between the stepper state machine
+     * and the reactive view properties that components depend on.
+     *
+     * @memberof ViewAPI
+     */
+    /**
+     * Saves the current stepper state to persistent storage
+     * @private
+     * @method _saveStepperState
+     * @memberof ViewAPI
+     * @instance
+     * @description Persists the current stepper state to storage using the current page name as the key.
+     * Only saves if there is an active stepper instance.
+     * @returns {void}
+     */
+    private _saveStepperState;
+    /**
+     * Updates the internal stepper state with new data
+     * @private
+     * @param {object} data - The new stepper state data
+     * @param {object} data.dataAlongPath - Data collected along the current path
+     * @param {string} data.currentPathString - String representation of current path
+     * @param {string[]} data.currentPath - Array of steps in current path
+     * @param {number} data.index - Current step index
+     * @param {object} data.data - Stepper data object
+     * @param {object} data.data.gvars - Global variables object
+     * @param {boolean} [save] - Whether to persist state changes
+     * @memberof ViewAPI
+     * @instance
+     */
+    private _updateStepperState;
+    /**
+     * Triggers an update of the stepper state
+     * @method updateStepper
+     * @memberof ViewAPI
+     * @instance
+     */
+    updateStepper(): void;
+    /**
+     * Creates a clean visualization of the state machine structure
+     * @private
+     * @returns {object} Processed state machine representation
+     * @memberof ViewAPI
+     * @instance
+     */
+    private _visualizeStateMachine;
+}
+import { SmileAPI } from './useAPI.js';
+import { onKeyDown } from '@vueuse/core';
+import { onKeyPressed } from '@vueuse/core';
+import { onKeyUp } from '@vueuse/core';
+import { useMouse } from '@vueuse/core';
+import { useMousePressed } from '@vueuse/core';