@m2c2kit/core 0.3.29 → 0.3.31

package/dist/index.d.ts

@@ -937,6 +937,15 @@ interface LocalizationOptions {
     additionalTranslation?: Translation;
 }
 
+/**
+ * ScoringSchema defines the data that are generated by the scoring code. They
+ * are key-value pairs in which the key is the variable name, and the value is
+ * JSON Schema that defines the type of the variable.
+ */
+interface ScoringSchema {
+    [key: string]: JsonSchema;
+}
+
 /**
  * Options to specify HTML canvas, set game canvas size, and load game assets.
  */
@@ -965,6 +974,8 @@ interface GameOptions extends LocalizationOptions {
     stretch?: boolean;
     /** Schema of trial data; JSON object where key is variable name, value is data type */
     trialSchema?: TrialSchema;
+    /** Schema of scoring data; JSON object where key is variable name, value is data type */
+    scoringSchema?: ScoringSchema;
     /** Default game parameters; JSON object where key is the game parameter, value is default value */
     parameters?: GameParameters;
     /** Font assets to use. The first element will be the default font */
@@ -997,6 +1008,7 @@ interface GameOptions extends LocalizationOptions {
 
 interface GameData extends ActivityKeyValueData {
     trials: Array<TrialData>;
+    scoring: ActivityKeyValueData;
 }
 
 /**
@@ -1593,6 +1605,22 @@ declare class Game implements Activity {
      */
     constructor(options: GameOptions);
     private createFreeNodesScene;
+    /**
+     * Returns the base URL of an imported module.
+     *
+     * @remarks Previously, a regex was used:
+     * `const regex = new RegExp(`^.*${packageName}[^\\/]*`);`
+     * but this triggered irrelevant warnings for ReDoS in some overly
+     * sensitive package scanners, so now we use URL and pathname parsing.
+     * Also: trailing slashes are removed from the returned base URL.
+     *
+     * @param packageName - the name of the imported package module, like
+     * `@m2c2kit/assessment-symbol-search`
+     * @param moduleUrl - the full URL of the module's entrypoint, possibly
+     * including a version suffix, like `https://cdn.com/@m2c2kit/assessment-symbol-search@0.8.13/dist/index.js`
+     * @returns - the base URL of the imported module, without the entrypoint,
+     * like `https://cdn.com/@m2c2kit/assessment-symbol-search@0.8.13`
+     */
     private getImportedModuleBaseUrl;
     private addLocalizationParametersToGameParameters;
     init(): Promise<void>;
@@ -1974,20 +2002,43 @@ declare class Game implements Activity {
      */
     dispose(): void;
     private initData;
+    private validateSchema;
     private propertySchemaDataTypeIsValid;
     private getDeviceMetadata;
     /**
      * Adds data to the game's TrialData object.
      *
-     * @remarks The variableName must be previously defined in the trialSchema
-     * object passed in during game initialization through
-     * {@link GameInitOptions.trialSchema}. The type of the value must match
-     * what was defined in the trialSchema, otherwise an error is thrown.
+     * @remarks `variableName` must be previously defined in the
+     * {@link TrialSchema} object in {@link GameOptions}. The type of the value
+     * must match what was defined in the trial schema, otherwise an error is
+     * thrown.
      *
      * @param variableName - variable to be set
      * @param value - value of the variable to set
      */
     addTrialData(variableName: string, value: JsonSchemaDataTypeScriptTypes): void;
+    /**
+     * Adds data to the game's scoring data.
+     *
+     * @remarks The variable name (or object property names) must be previously
+     * defined in the {@link ScoringSchema} object in {@link GameOptions}.
+     * The type of the value must match what was defined in the scoring schema,
+     * otherwise an error is thrown.
+     *
+     * @param variableNameOrObject - Either a variable name (string) or an object
+     * containing multiple key-value pairs to add all at once.
+     * @param value - Value of the variable to set (only used when
+     * variableNameOrObject is a variable name string).
+     */
+    addScoringData(variableNameOrObject: string | Record<string, JsonSchemaDataTypeScriptTypes> | Array<Record<string, JsonSchemaDataTypeScriptTypes>>, value?: JsonSchemaDataTypeScriptTypes): void;
+    /**
+     * Helper method to validate and set a single scoring variable
+     *
+     * @param variableName - Name of the variable to set
+     * @param value - Value to set
+     * @private
+     */
+    private validateAndSetScoringVariable;
     /**
      * Adds custom trial schema to the game's trialSchema object.
      *
@@ -2036,6 +2087,22 @@ declare class Game implements Activity {
      * the appropriate time. It is not triggered automatically.
      */
     trialComplete(): void;
+    /**
+     * Marks scoring as complete.
+     *
+     * @remarks This method must be called after the game has finished adding
+     * scores using addScoringData(). Calling will trigger the onActivityResults
+     * callback function, if one was provided in SessionOptions. This is how the
+     * game communicates scoring data to the parent session, which can then save
+     * or process the data. It is the responsibility of the the game programmer
+     * to call this at the appropriate time. It is not triggered automatically.
+     */
+    scoringComplete(): void;
+    /**
+     * The m2c2kit engine will automatically include these schema and their
+     * values in the scoring data.
+     */
+    private readonly automaticScoringSchema;
     /**
      * The m2c2kit engine will automatically include these schema and their
      * values in the trial data.
@@ -2052,6 +2119,7 @@ declare class Game implements Activity {
      */
     private makeGameActivityConfiguration;
     private makeGameActivityConfigurationSchema;
+    private makeScoringDataSchema;
     /**
      * Should be called when current game has ended successfully.
      *
@@ -2298,14 +2366,69 @@ declare class I18n {
     private localeTranslationAvailable;
     switchToLocale(locale: string): void;
     /**
+     * Returns the localized text and font information for the given key in the
+     * current locale.
      *
      * @param key - Translation key
      * @param interpolation - Interpolation keys and values to replace
-     * placeholders in the translated text
-     * @returns a `TextLocalizationResult` object with the localized text, font
-     * information, and whether the translation is a fallback.
+     * string interpolation placeholders in the translated text
+     * @returns object with the localized text, font information, and whether the
+     * translation is a fallback.
      */
     getTextLocalization(key: string, interpolation?: StringInterpolationMap): TextLocalizationResult;
+    /**
+     *
+     * @param key - Translation key to be translated
+     * @param interpolation - String interpolation keys and values to replace
+     * @returns result object with the localized text, font
+     */
+    private attemptTranslation;
+    /**
+     * Handles translation placeholders in a string.
+     *
+     * @remarks The value of a translation placeholder (text within `[[]]`)
+     * may also contain string interpolation placeholders (`{{}}`), so we need
+     * to handle that as well.
+     *
+     * @param key - Translation key for the string to be localized
+     * @param initialResult - Initial translation result for the string
+     * @param interpolation - Interpolation keys and values to replace
+     * interpolation placeholders in the translated text
+     * @returns result object with the localized text,
+     */
+    private handleTranslationPlaceholders;
+    /**
+     * Translates a translation placeholder key to its text and collects font properties.
+     *
+     * @param placeholderKey - Translation key for the placeholder
+     * @param fontProps - Font properties sets to collect font information
+     * @param interpolation - Interpolation keys and values to replace
+     * string interpolation placeholders in the translated text
+     * @returns result object with the translated text and whether it is a fallback translation
+     */
+    private translatePlaceholder;
+    /**
+     * Extracts translation key placeholders from a string.
+     *
+     * @remarks Translation key placeholders are denoted by double square brackets,
+     * e.g., "The translated word is [[RED]]", and RED is a key for translation.
+     *
+     * @param s - string to search for placeholders
+     * @returns an array of placeholders found in the string, without the square
+     * brackets
+     */
+    private getTranslationPlaceholders;
+    /**
+     * Logs warnings if the string to be localized has conflicting font
+     * properties.
+     *
+     * @remarks This can happen due to multiple placeholders in the string
+     * that specify different font sizes, font names, or font names arrays.
+     *
+     * @param key - Translation key for which the string is being localized
+     * @param fontProps - font properties sets collected from the placeholders
+     */
+    private warnConflictingFontProperties;
     /**
      * Returns the translation text for the given key in the current locale.
      *
@@ -3761,6 +3884,13 @@ declare enum Dimensions {
     MatchConstraint = 0
 }
 
+/**
+ * Custom error class for m2c2kit errors.
+ */
+declare class M2Error extends Error {
+    constructor(...params: string[]);
+}
+
 type M2NodeConstructor = new (options?: M2NodeOptions) => M2Node;
 
 /**
@@ -4197,7 +4327,7 @@ declare enum LabelHorizontalAlignmentMode {
 }
 
 interface LabelOptions extends M2NodeOptions, DrawableOptions, TextOptions {
-    /** Text to be displayed. Tags for bold, italic, and underline are supported, e.g., `<b><u>Bold and underline</u></b>`. */
+    /** Text to be displayed. When operating with localization, text within double square brackets will be replaced with the value of the key in the translation. For example, if the text is `The translated word is [[RED]]`, `[[RED]]` will be replaced with the translation. If no localization is used, or a translation for the key is missing, then the text will be rendered as is. Tags for bold (`b`), italic (`i`), underline (`u`), overline(`o`), and strikethrough (`s`) are supported, e.g., `<b><u>Bold and underline</u></b>`. Note that while bold and italic and be combined, only one of underline, overline, and strikethrough can be used on a text segment. */
     text?: string;
     /** Horizontal alignment of label text. see {@link LabelHorizontalAlignmentMode}. Default is LabelHorizontalAlignmentMode.center  */
     horizontalAlignmentMode?: LabelHorizontalAlignmentMode;
@@ -4230,14 +4360,12 @@ declare class Label extends M2Node implements IDrawable, IText, LabelOptions {
     private builder?;
     private _fontPaint?;
     private _backgroundPaint?;
-    private _underlinePaint?;
     private localizedFontSize;
     private localizedFontName;
     private localizedFontNames;
+    private textAfterLocalization;
     private plainText;
     private styleSegments;
-    private underlinedRanges;
-    private currentBuilderPosition;
     /**
      * Single or multi-line text formatted and rendered on the screen.
      *
@@ -4284,7 +4412,23 @@ declare class Label extends M2Node implements IDrawable, IText, LabelOptions {
      * @throws Error if tags are improperly nested or unclosed
      */
     private parseFormattedText;
-    private addTextWithStylesToParagraphBuilder;
+    /**
+     * Adds text segments with consistent styling to the paragraph builder.
+     *
+     * @param builder - {@link ParagraphBuilder}
+     * @param styleSegments - Segments of text with consistent styling
+     * @param defaultStyle - Default style to apply
+     */
+    private addStyleSegmentsToParagraphBuilder;
+    /**
+     * Helper that adds text to the paragraph builder with the specified style.
+     *
+     * @param builder - {@link ParagraphBuilder}
+     * @param text - The text to add
+     * @param defaultStyle - The default style to apply
+     * @param styleModifiers - Additional style modifications
+     * @returns void
+     */
     private addTextWithStyle;
     /**
      * Determines the M2Font objects that need to be ready in order to draw
@@ -4326,8 +4470,6 @@ declare class Label extends M2Node implements IDrawable, IText, LabelOptions {
     private set backgroundPaint(value);
     private get fontPaint();
     private set fontPaint(value);
-    private get underlinePaint();
-    private set underlinePaint(value);
     /**
      * Duplicates a node using deep copy.
      *
@@ -4341,7 +4483,6 @@ declare class Label extends M2Node implements IDrawable, IText, LabelOptions {
     duplicate(newName?: string): Label;
     update(): void;
     draw(canvas: Canvas): void;
-    private drawUnderlines;
     warmup(canvas: Canvas): void;
 }
 
@@ -4536,12 +4677,27 @@ declare class RandomDraws {
 }
 
 /**
- * ScoringSchema defines the data that are generated by the scoring code. They
- * are key-value pairs in which the key is the variable name, and the value is
- * JSON Schema that defines the type of the variable.
+ * Assessments that generate scoring data must implement the ScoringProvider
+ * interface
  */
-interface ScoringSchema {
-    [key: string]: JsonSchema;
+interface ScoringProvider {
+    /**
+     * Calculates scores based on the provided activity data and optional
+     * additional parameters.
+     *
+     * @param data - Activity data from which to calculate scores.
+     * @param extras - Optional additional parameters that are needed for an
+     * activity's scoring calculations. This can include things like
+     * game parameters, user context, or other metadata that is relevant
+     * to the scoring logic. The structure of this object is not
+     * defined by this interface, as it can vary widely between different
+     * activities.
+     * @returns The calculated scores object or an array of such objects. If an
+     * array of is returned, it should have length 1.
+     */
+    calculateScores(data: ActivityKeyValueData[], extras?: {
+        [key: string]: unknown;
+    }): ActivityKeyValueData | Array<ActivityKeyValueData>;
 }
 
 declare enum ShapeType {
@@ -5367,5 +5523,5 @@ declare class WebGlInfo {
     static dispose(): void;
 }
 
-export { Action, ActivityType, CanvasKitHelpers, ColorfulMutablePath, Composite, Constants, ConstraintType, CustomAction, Dimensions, Easings, Equal, Equals, EventStore, EventStoreMode, FadeAlphaAction, FontManager, Game, GroupAction, I18n, ImageManager, Label, LabelHorizontalAlignmentMode, LayoutConstraint, LegacyTimer, M2EventType, M2ImageStatus, M2Node, M2NodeFactory, M2NodeType, M2SoundStatus, M2c2KitHelpers, MoveAction, MutablePath, NoneTransition, PlayAction, RandomDraws, RepeatAction, RepeatForeverAction, RotateAction, ScaleAction, Scene, SceneTransition, SequenceAction, Shape, ShapeType, SlideTransition, SoundManager, SoundPlayer, SoundRecorder, Sprite, Story, TextLine, Timer, Transition, TransitionDirection, TransitionType, Uuid, WaitAction, WebColors, WebGlInfo, handleInterfaceOptions };
-export type { Activity, ActivityCallbacks, ActivityEvent, ActivityEventListener, ActivityKeyValueData, ActivityLifecycleEvent, ActivityResultsEvent, BrowserImage, BrowserImageDataReadyEvent, CallbackOptions, CompositeEvent, CompositeOptions, Constraints, CustomActionOptions, DefaultParameter, DomPointerDownEvent, DrawableOptions, EasingFunction, FadeAlphaActionOptions, FontAsset, FontData, GameData, GameEvent, GameOptions, GameParameters, GlobalVariables, I18nDataReadyEvent, IDataStore, IDrawable, IText, LabelOptions, Layout, LocaleSvg, M2ColorfulPath, M2DragEvent, M2Event, M2EventListener, M2Image, M2KeyboardEvent, M2NodeAddChildEvent, M2NodeConstructor, M2NodeEvent, M2NodeEventListener, M2NodeNewEvent, M2NodeOptions, M2NodePropertyChangeEvent, M2NodeRemoveChildEvent, M2Path, M2PointerEvent, M2Sound, MoveActionOptions, PlayActionOptions, Plugin, PluginEvent, Point, RectOptions, RgbaColor, ScaleActionOptions, SceneOptions, ScenePresentEvent, ScoringSchema, ShapeOptions, Size, SlideTransitionOptions, SoundAsset, SoundPlayerOptions, SoundRecorderOptions, SoundRecorderResults, SpriteOptions, StoryOptions, StringInterpolationMap, TapEvent, TextAndFont, TextLineOptions, TextLocalizationResult, TextOptions, TextWithFontCustomization, Translation, TranslationConfiguration, TranslationOptions, TrialData, TrialSchema, WaitActionOptions };
+export { Action, ActivityType, CanvasKitHelpers, ColorfulMutablePath, Composite, Constants, ConstraintType, CustomAction, Dimensions, Easings, Equal, Equals, EventStore, EventStoreMode, FadeAlphaAction, FontManager, Game, GroupAction, I18n, ImageManager, Label, LabelHorizontalAlignmentMode, LayoutConstraint, LegacyTimer, M2Error, M2EventType, M2ImageStatus, M2Node, M2NodeFactory, M2NodeType, M2SoundStatus, M2c2KitHelpers, MoveAction, MutablePath, NoneTransition, PlayAction, RandomDraws, RepeatAction, RepeatForeverAction, RotateAction, ScaleAction, Scene, SceneTransition, SequenceAction, Shape, ShapeType, SlideTransition, SoundManager, SoundPlayer, SoundRecorder, Sprite, Story, TextLine, Timer, Transition, TransitionDirection, TransitionType, Uuid, WaitAction, WebColors, WebGlInfo, handleInterfaceOptions };
+export type { Activity, ActivityCallbacks, ActivityEvent, ActivityEventListener, ActivityKeyValueData, ActivityLifecycleEvent, ActivityResultsEvent, BrowserImage, BrowserImageDataReadyEvent, CallbackOptions, CompositeEvent, CompositeOptions, Constraints, CustomActionOptions, DefaultParameter, DomPointerDownEvent, DrawableOptions, EasingFunction, FadeAlphaActionOptions, FontAsset, FontData, GameData, GameEvent, GameOptions, GameParameters, GlobalVariables, I18nDataReadyEvent, IDataStore, IDrawable, IText, LabelOptions, Layout, LocaleSvg, M2ColorfulPath, M2DragEvent, M2Event, M2EventListener, M2Image, M2KeyboardEvent, M2NodeAddChildEvent, M2NodeConstructor, M2NodeEvent, M2NodeEventListener, M2NodeNewEvent, M2NodeOptions, M2NodePropertyChangeEvent, M2NodeRemoveChildEvent, M2Path, M2PointerEvent, M2Sound, MoveActionOptions, PlayActionOptions, Plugin, PluginEvent, Point, RectOptions, RgbaColor, ScaleActionOptions, SceneOptions, ScenePresentEvent, ScoringProvider, ScoringSchema, ShapeOptions, Size, SlideTransitionOptions, SoundAsset, SoundPlayerOptions, SoundRecorderOptions, SoundRecorderResults, SpriteOptions, StoryOptions, StringInterpolationMap, TapEvent, TextAndFont, TextLineOptions, TextLocalizationResult, TextOptions, TextWithFontCustomization, Translation, TranslationConfiguration, TranslationOptions, TrialData, TrialSchema, WaitActionOptions };