MMOFramework MCP

# MMO Map System - Documentation The `MMO.core.Map` class extends the JavaScript `Map` class with additional features and events. This document provides an overview of the methods available in the `MMO.core.Map` class. # Binding in MMO Framework Binding in the MMO framework allows you to synchronize data between the JavaScript `Map` and the DOM elements. This ensures that changes in the data are automatically reflected in the UI and vice versa. ## Special Attributes ### `value` The `value` attribute binds the value of an `input`, `select`, `textarea`, or any custom element to the map's data. When the element's value changes, the map's data is updated accordingly. ### `set-xxx` The `set-xxx` attribute binds a property of an HTML element to the map's data. This creates a two-way binding: - When the map's data changes, the element's property `xxx` is updated: `element.xxx = map.get('xxx')` - When the custom element's property `xxx` changes, the map is updated: `map.set('xxx', element.xxx)` ## Example Usage ### Binding `value` Attribute ```html ``` In this example, the `value` attribute of the `input` element is bound to the `name` key in the map. When the user types in the input field, the `name` key in the map is updated. ### Binding `set-xxx` Attribute ```html ``` In this example, the `foo` property of the `custom-element` is bound to the `bar` key in the map. When the `bar` key in the map changes, the `foo` property of the `custom-element` is updated, and vice versa. ## Dynamic Variables You can define dynamic variables using the `{= xxx}` notation. This allows you to inject JavaScript expressions into the template. ### Example ```html

{= {name} + ' is ' + {age} + ' years old' }

``` In this example, the expression inside the curly brackets is evaluated, and the result is injected into the template. If `name` is `John` and `age` is `30`, the rendered output will be: ```html

John is 30 years old

``` ## MMO.core.Map Class - Methods ### Conversion Methods - **toObject(deep = true, _hash = new WeakMap())** - Converts the map to a primitive object or array. If `deep` is true, it recursively converts inner `MMO.core.Map` instances. - **toArray(deep = true, _hash = new WeakMap())** - Converts the map to an array. If `toObject` returns an array, only its values are returned. - **static From(obj, schema = null, _hash = new WeakMap())** - Creates a new `MMO.core.Map` instance from an object, optionally applying a schema. - **static FromJSON(json)** - Creates a new `MMO.core.Map` instance from a JSON string. - **toJSON()** - Converts the map to a JSON-compatible object or array. ### Utility Methods - **isArray(allowEmpty = false)** - Checks if the map's content is a JSON array (indexes are ordered integers starting from 0). - **isEqual(obj, strictOrder = true)** - Tests if the map's content is strictly equal to the content of an object. - **isEmpty()** - Checks if the map is empty. - **getText(key)** - Gets the text representation of the value at the specified key. - **getHTML(key)** - Gets the HTML representation of the value at the specified key. ### Event Handling Methods - **onChildChange(map)** - Handles changes in child maps. - **connectChild(map, key)** - Connects a child map at the specified key. - **disconnectChild(map, key)** - Disconnects a child map from the specified key. - **getEventsByScope(scope, _hash = new WeakSet())** - Yields all events concerning a given scope. ### Index Methods - **keyOf(value)** - Gets the key of the specified value. - **indexOf(value)** - Gets the index of the specified value. - **indexOfKey(key)** - Gets the index of the specified key. - **atIndex(index)** - Gets the value at the specified index. - **pathOf(value, _hash = new WeakSet())** - Gets the path of the specified value. ### Modification Methods - **clear()** - Clears the map, removing all key-value pairs. - **set(key, value, _hash = new WeakMap())** - Sets the value at the specified key. - **delete(key)** - Deletes the value at the specified key. - **setValue(obj, _hash = new WeakMap())** - Sets the content of the map with the content of an object. - **merge(obj, _hash = new WeakMap())** - Merges values from another object into the map. ### Array-like Methods - **push(value)** - Adds a value to the end of the map (if it is an array). - **unshift(value)** - Adds a value to the beginning of the map (if it is an array). - **pop()** - Removes and returns the last value of the map (if it is an array). - **shift()** - Removes and returns the first value of the map (if it is an array). ### Change Handling Methods - **addChange(type, key)** - Adds a change event to the map. - **emitChanges()** - Emits all queued change events. ### Path Methods - **yieldWalk(path, create = false)** - Walks through the map using a JSON path, creating the structure if needed. - **walkTo(path, create = false)** - Walks to the specified path in the map, creating the structure if needed. - **keyAt(path)** - Gets the key at the specified path. - **mapAt(path, create = false)** - Gets the map at the specified path, creating the structure if needed. - **getAt(path, create = false)** - Gets the value at the specified path, creating the structure if needed. - **safeGetAt(path, def)** - Safely gets the value at the specified path, returning a default value if the path does not exist. - **exists(path)** - Checks if the specified path exists in the map. - **setAt(path, value)** - Sets the value at the specified path. - **mergeAt(path, value)** - Merges the value at the specified path. ### Schema Methods - **setSchema(schema)** - Sets the schema for the map. - **getKeySchema(key)** - Gets the schema for the specified key. - **setKeySchema(key, schema)** - Sets the schema for the specified key. - **validate()** - Validates the map against its schema. - **validateKey(key)** - Validates the value at the specified key against its schema. ### Sorting Methods - **usort(cmp, reorderKeys = true)** - Sorts the map by key and value using a custom comparison function. - **ksort(cmp)** - Sorts the map by keys using a custom comparison function. - **sort(cmp, reorderKeys = true)** - Sorts the map by values using a custom comparison function. ## MMO Map Event System - Overview The MMO Map Event System extends the JavaScript `Map` class by incorporating an event-driven approach. Events are triggered whenever changes occur in the map, allowing developers to react to modifications efficiently. This event-based extension of JavaScript's `Map` class provides a powerful mechanism for tracking and responding to changes dynamically. By leveraging these events, developers can efficiently manage state changes and interactions within MMO app. ## Event Types There are three categories of events: **async key events**, **sync key events**, and **async symbol events**. ### 1. Async Key Events These events are triggered asynchronously on a specific key using an animation frame. #### Event Structure ```js function(type, map, key) ``` #### Triggered Events - **Value Changed:** Triggered when a value is modified. ```js on(key, (MMO.core.MAP_VALUE_CHANGED, map, key) => { ... }) ``` - **Value Created:** Triggered when a new value is added. ```js on(key, (MMO.core.MAP_VALUE_CREATED, map, key) => { ... }) ``` - **Value Deleted:** Triggered when a value is removed. ```js on(key, (MMO.core.MAP_VALUE_DELETED, map, key) => { ... }) ``` - **Index Changed:** Triggered when the position of a key within a list changes. ```js on(key, (MMO.core.MAP_INDEX_CHANGED, map, key) => { ... }) ``` **Example:** ```js {a: 1, b: 2} => {b: 2, a: 1} ``` - `a` changes index from `0` to `1` - `b` changes index from `1` to `0` ### 2. Sync Key Events These events are triggered directly on a specific key. #### Event Structure ```js function(type, map, key, newKey) ``` #### Triggered Events - **Key Changed:** Triggered when a list key is modified. ```js on(key, (MMO.core.MAP_KEY_CHANGED, map, key, newKey) => { ... }) ``` **Example:** ```js [a, b] => [b, a] ``` - Event at index `0`: `(MMO.core.MAP_KEY_CHANGED, map, 0, 1) // 'a' moved from 0 to 1` - Event at index `1`: `(MMO.core.MAP_KEY_CHANGED, map, 1, 0) // 'b' moved from 1 to 0` - **Child Map Connected:** Triggered when a child map is attached at a key. ```js on(key, (MMO.core.MAP_CONNECT, map, key, childMap) => { ... }) ``` - **Child Map Disconnected:** Triggered when a child map is removed from a key. ```js on(key, (MMO.core.MAP_DISCONNECT, map, key, childMap) => { ... }) ``` ### 3. Async Symbol Events key: - `MMO.core.MAP_VALUE_CHANGED` - `MMO.core.MAP_VALUE_CREATED` - `MMO.core.MAP_VALUE_DELETED` #### Event Structure ```js function(map) ``` #### Usage ```js on(MMO.core.MAP_VALUE_CHANGED, (map) => { ... }) on(MMO.core.MAP_VALUE_CREATED, (map) => { ... }) on(MMO.core.MAP_VALUE_DELETED, (map) => { ... }) ``` These events trigger whenever any of the following events occur on any