@m2c2kit/core 0.3.28 → 0.3.30

package/LICENSE

@@ -1,21 +1,13 @@
-MIT License
+Copyright 2023 Scott T. Yabiku
 
-Copyright (c) 2023 Scott T. Yabiku
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+    http://www.apache.org/licenses/LICENSE-2.0
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -1,6 +1,6 @@
 # @m2c2kit/core
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://opensource.org/license/apache-2-0)
 [![CI/CD](https://github.com/m2c2-project/m2c2kit/actions/workflows/ci.yml/badge.svg)](https://github.com/m2c2-project/m2c2kit/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/@m2c2kit/core.svg)](https://www.npmjs.com/package/@m2c2kit/core)
 

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;
 }
 
 /**
@@ -1846,7 +1858,9 @@ declare class Game implements Activity {
     /**
      * Adds a scene to the game.
      *
-     * @remarks A scene, and its children nodes, cannot be presented unless it has been added to the game object.
+     * @remarks A scene, and its children nodes, cannot be presented unless it
+     * has been added to the game object. A scene can be added to the game
+     * only once.
      *
      * @param scene
      */
@@ -1972,20 +1986,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.
      *
@@ -2034,6 +2071,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.
@@ -2050,6 +2103,7 @@ declare class Game implements Activity {
      */
     private makeGameActivityConfiguration;
     private makeGameActivityConfigurationSchema;
+    private makeScoringDataSchema;
     /**
      * Should be called when current game has ended successfully.
      *
@@ -2296,14 +2350,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.
      *
@@ -3759,6 +3868,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;
 
 /**
@@ -4195,6 +4311,8 @@ declare enum LabelHorizontalAlignmentMode {
 }
 
 interface LabelOptions extends M2NodeOptions, DrawableOptions, TextOptions {
+    /** 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;
     /** Maximum width of label text before wrapping occurs. Default is the canvas width */
@@ -4229,10 +4347,14 @@ declare class Label extends M2Node implements IDrawable, IText, LabelOptions {
     private localizedFontSize;
     private localizedFontName;
     private localizedFontNames;
+    private textAfterLocalization;
+    private plainText;
+    private styleSegments;
     /**
      * Single or multi-line text formatted and rendered on the screen.
      *
-     * @remarks Label (in contrast to TextLine) has enhanced text support for line wrapping, centering/alignment, and background colors.
+     * @remarks Label (in contrast to TextLine) has enhanced text support for
+     * line wrapping, centering/alignment, and background colors.
      *
      * @param options - {@link LabelOptions}
      */
@@ -4263,6 +4385,35 @@ declare class Label extends M2Node implements IDrawable, IText, LabelOptions {
         suppressEvents?: boolean;
     };
     initialize(): void;
+    /**
+     * Parses text with formatting tags and returns plain text and style segments.
+     * Supports <b> for bold, <i> for italics, and <u> for underline.
+     * Properly handles nested tags like <b><u>bold and underlined</u></b>.
+     * Throws errors for malformed tags, but treats unknown tags as plain text.
+     *
+     * @param text - The text with formatting tags
+     * @returns The parsed text result
+     * @throws Error if tags are improperly nested or unclosed
+     */
+    private parseFormattedText;
+    /**
+     * 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
      * the Label.
@@ -4510,12 +4661,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 {
@@ -5341,4 +5507,5 @@ declare class WebGlInfo {
     static dispose(): void;
 }
 
-export { Action, type Activity, type ActivityCallbacks, type ActivityEvent, type ActivityEventListener, type ActivityKeyValueData, type ActivityLifecycleEvent, type ActivityResultsEvent, ActivityType, type BrowserImage, type BrowserImageDataReadyEvent, type CallbackOptions, CanvasKitHelpers, ColorfulMutablePath, Composite, type CompositeEvent, type CompositeOptions, Constants, ConstraintType, type Constraints, CustomAction, type CustomActionOptions, type DefaultParameter, Dimensions, type DomPointerDownEvent, type DrawableOptions, type EasingFunction, Easings, Equal, Equals, EventStore, EventStoreMode, FadeAlphaAction, type FadeAlphaActionOptions, type FontAsset, type FontData, FontManager, Game, type GameData, type GameEvent, type GameOptions, type GameParameters, type GlobalVariables, GroupAction, I18n, type I18nDataReadyEvent, type IDataStore, type IDrawable, type IText, ImageManager, Label, LabelHorizontalAlignmentMode, type LabelOptions, type Layout, LayoutConstraint, LegacyTimer, type LocaleSvg, type M2ColorfulPath, type M2DragEvent, type M2Event, type M2EventListener, M2EventType, type M2Image, M2ImageStatus, type M2KeyboardEvent, M2Node, type M2NodeAddChildEvent, type M2NodeConstructor, type M2NodeEvent, type M2NodeEventListener, M2NodeFactory, type M2NodeNewEvent, type M2NodeOptions, type M2NodePropertyChangeEvent, type M2NodeRemoveChildEvent, M2NodeType, type M2Path, type M2PointerEvent, type M2Sound, M2SoundStatus, M2c2KitHelpers, MoveAction, type MoveActionOptions, MutablePath, NoneTransition, PlayAction, type PlayActionOptions, type Plugin, type PluginEvent, type Point, RandomDraws, type RectOptions, RepeatAction, RepeatForeverAction, type RgbaColor, RotateAction, ScaleAction, type ScaleActionOptions, Scene, type SceneOptions, type ScenePresentEvent, SceneTransition, type ScoringSchema, SequenceAction, Shape, type ShapeOptions, ShapeType, type Size, SlideTransition, type SlideTransitionOptions, type SoundAsset, SoundManager, SoundPlayer, type SoundPlayerOptions, SoundRecorder, type SoundRecorderOptions, type SoundRecorderResults, Sprite, type SpriteOptions, Story, type StoryOptions, type StringInterpolationMap, type TapEvent, type TextAndFont, TextLine, type TextLineOptions, type TextLocalizationResult, type TextOptions, type TextWithFontCustomization, Timer, Transition, TransitionDirection, TransitionType, type Translation, type TranslationConfiguration, type TranslationOptions, type TrialData, type TrialSchema, Uuid, WaitAction, type WaitActionOptions, WebColors, WebGlInfo, handleInterfaceOptions };
+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 };