@m2c2kit/core 0.3.27 → 0.3.29

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

@@ -403,6 +403,32 @@ interface SceneOptions extends M2NodeOptions, DrawableOptions {
     backgroundColor?: RgbaColor;
 }
 
+/**
+ * Describes an event on the device's built-in keyboard.
+ *
+ * @remarks The built-in keyboard is defined as the hardware keyboard on a
+ * desktop/laptop or the built-in soft keyboard on a tablet or phone. The
+ * latter is not used in m2c2kit. On tablet or phone, the `VirtualKeyboard`
+ * in the `@m2c2kit/addons` package should be used for key events.
+ * @remarks Key events can occur only on a `Scene` node.
+ */
+interface M2KeyboardEvent extends M2NodeEvent {
+    /** String that is generated when key is pressed, with any modifiers (e.g., Shift) applied. */
+    key: string;
+    /** Code for the key, not taking into account any modifiers. */
+    code: string;
+    /** True if the Shift key is pressed. */
+    shiftKey: boolean;
+    /** True if the Control key is pressed. */
+    ctrlKey: boolean;
+    /** True if the Alt key is pressed. */
+    altKey: boolean;
+    /** True if the Meta key is pressed. */
+    metaKey: boolean;
+    /** True if the event is being repeated. */
+    repeat: boolean;
+}
+
 declare class Scene extends M2Node implements IDrawable, SceneOptions {
     readonly type = M2NodeType.Scene;
     isDrawable: boolean;
@@ -485,6 +511,34 @@ declare class Scene extends M2Node implements IDrawable, SceneOptions {
      * @param options - {@link CallbackOptions}
      */
     onAppear(callback: (nodeEvent: M2NodeEvent) => void, options?: CallbackOptions): void;
+    /**
+     * Code that will be called after a key is pressed on the device's
+     * built-in keyboard.
+     *
+     * @remarks The built-in keyboard is defined as the hardware keyboard on a
+     * desktop/laptop or the built-in soft keyboard on a tablet or phone. The
+     * latter is not used in m2c2kit. On tablet or phone, the `VirtualKeyboard`
+     * in the `@m2c2kit/addons` package should be used for key events.
+     * @remarks Key events can occur only on a `Scene` node.
+     *
+     * @param callback - function to execute
+     * @param options - {@link CallbackOptions}
+     */
+    onKeyDown(callback: (m2KeyboardEvent: M2KeyboardEvent) => void, options?: CallbackOptions): void;
+    /**
+     * Code that will be called after a key is released on the device's
+     * built-in keyboard.
+     *
+     * @remarks The built-in keyboard is defined as the hardware keyboard on a
+     * desktop/laptop or the built-in soft keyboard on a tablet or phone. The
+     * latter is not used in m2c2kit. On tablet or phone, the `VirtualKeyboard`
+     * in the `@m2c2kit/addons` package should be used for key events.
+     * @remarks Key events can occur only on a `Scene` node.
+     *
+     * @param callback - function to execute
+     * @param options - {@link CallbackOptions}
+     */
+    onKeyUp(callback: (m2KeyboardEvent: M2KeyboardEvent) => void, options?: CallbackOptions): void;
     update(): void;
     draw(canvas: Canvas): void;
     warmup(canvas: Canvas): void;
@@ -1792,7 +1846,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
      */
@@ -2111,6 +2167,8 @@ declare class Game implements Activity {
     private htmlCanvasPointerUpHandler;
     private htmlCanvasPointerMoveHandler;
     private htmlCanvasPointerLeaveHandler;
+    private documentKeyDownHandler;
+    private documentKeyUpHandler;
     /**
      * Determines if/how m2c2kit nodes respond to the DOM PointerDown event
      *
@@ -2428,6 +2486,8 @@ declare const M2EventType: {
     readonly PointerUp: "PointerUp";
     readonly PointerMove: "PointerMove";
     readonly PointerLeave: "PointerLeave";
+    readonly KeyDown: "KeyDown";
+    readonly KeyUp: "KeyUp";
     readonly Drag: "Drag";
     readonly DragStart: "DragStart";
     readonly DragEnd: "DragEnd";
@@ -3676,8 +3736,8 @@ declare class Constants {
     /** Placeholder that will be populated during the build process. */
     static readonly MODULE_METADATA_PLACEHOLDER: ModuleMetadata;
     static readonly DEFAULT_ROOT_ELEMENT_ID = "m2c2kit";
-    static readonly ERUDA_URL = "https://cdn.jsdelivr.net/npm/eruda@3.2.3/eruda.js";
-    static readonly ERUDA_SRI = "sha384-KlRzgy/c+nZSV+eiFqoTkkbZ5pUqToho7HsNuebTbOsYTh4m0m/PAqkGsTMLXK14";
+    static readonly ERUDA_URL = "https://cdn.jsdelivr.net/npm/eruda@3.4.1/eruda.js";
+    static readonly ERUDA_SRI = "sha384-daS5bEfWdSq146t9c4BureB/fQWO3lHohseXBelPqKvbOUx2D6PE3TxcQ9jrKZDM";
 }
 
 /**
@@ -4137,6 +4197,8 @@ 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?: 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 */
@@ -4168,13 +4230,19 @@ declare class Label extends M2Node implements IDrawable, IText, LabelOptions {
     private builder?;
     private _fontPaint?;
     private _backgroundPaint?;
+    private _underlinePaint?;
     private localizedFontSize;
     private localizedFontName;
     private localizedFontNames;
+    private plainText;
+    private styleSegments;
+    private underlinedRanges;
+    private currentBuilderPosition;
     /**
      * 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}
      */
@@ -4205,6 +4273,19 @@ 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;
+    private addTextWithStylesToParagraphBuilder;
+    private addTextWithStyle;
     /**
      * Determines the M2Font objects that need to be ready in order to draw
      * the Label.
@@ -4245,6 +4326,8 @@ 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.
      *
@@ -4258,6 +4341,7 @@ 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;
 }
 
@@ -5283,4 +5367,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, 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, 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 };