@yamato-daiwa/universal-reactive 0.0.0 → 0.1.0

package/Distributable/Component.d.ts

@@ -1,9 +1,19 @@
 import type GeneralizedView from "./GeneralizedView";
+import type EventHandlersDataMap from "./Types/EventHandlersDataMap";
+import type { ArbitraryObject } from "@yamato-daiwa/es-extensions";
 export default abstract class Component {
     /** @description Initialized by `View` decorator. */
-    readonly $$mount: (mountingPoint: Element) => void;
+    readonly $mount: (mountingPoint: Element) => void;
     /** @description Initialized by `View` decorator. */
-    protected readonly $$DOM: ReadonlyArray<Element>;
+    protected readonly $DOM: ReadonlyArray<Element>;
     /** @description Initialized by `View` decorator. */
-    protected readonly $$view: GeneralizedView;
+    protected readonly $view: GeneralizedView;
+    /** @description Initialized by `ReactiveState` or `View` decorators. */
+    protected readonly $reactiveState: ArbitraryObject;
+    /** @description Initialized by `ConstantState` or `View` decorators. */
+    protected readonly $constantState: ArbitraryObject;
+    /** @description Initialized and frozen by `View` decorator. */
+    protected readonly $isReactivityEnabled: false;
+    /** @description Initialized by `EventHandler` or `View` decorators. */
+    protected readonly $eventsHandlers: EventHandlersDataMap;
 }

package/Distributable/Constants/EventPropagationTypes.d.ts

@@ -0,0 +1,5 @@
+declare enum EventPropagationTypes {
+    bubbling = "BUBBLING",
+    capturing = "CAPTURING"
+}
+export default EventPropagationTypes;

package/Distributable/Decorators/ConstantState.d.ts

@@ -0,0 +1,2 @@
+declare const ConstantState: PropertyDecorator;
+export default ConstantState;

package/Distributable/Decorators/EventHandler.d.ts

@@ -0,0 +1,14 @@
+import type EventPropagationTypes from "../Constants/EventPropagationTypes";
+/**
+ * @description
+ * Been executed BEFORE `View` decorator, thus the methods (and fields) of `Component` class are not defined yet.
+ */
+declare const EventHandler: (options?: EventHandler.Options) => MethodDecorator;
+declare namespace EventHandler {
+    type Options = Readonly<{
+        eventPropagation?: EventPropagationTypes | false;
+        mustBeCalledOnce?: boolean;
+        mustKeepDefaultBehaviour?: boolean;
+    }>;
+}
+export default EventHandler;

package/Distributable/Decorators/ReactiveState.d.ts

@@ -0,0 +1,2 @@
+declare const ReactiveState: PropertyDecorator;
+export default ReactiveState;

package/Distributable/Decorators/View.d.ts

@@ -1,3 +1,8 @@
 import type GeneralizedView from "../GeneralizedView";
+/**
+ * @description
+ * If class component uses "ReactiveState" decorator, "View" decorator will be called AFTER "ReactiveState" thus to
+ *   access the reactive state, the patching of the constructor is required.
+ */
 declare const View: (generalizedView: GeneralizedView) => ClassDecorator;
 export default View;

package/Distributable/GeneralizedView.d.ts

@@ -1,6 +1,17 @@
+import type EventHandlersDataMap from "./Types/EventHandlersDataMap";
+import type { ArbitraryObject } from "@yamato-daiwa/es-extensions";
 type GeneralizedView = {
     onStateFieldsChangedHandlers: Map<string, Set<(currentValue: unknown) => unknown>>;
     methodsReferences: Map<string, (handler: () => unknown) => unknown>;
-    generateInitialDOM: () => Array<Element>;
+    generateInitialDOM: (parameter: GeneralizedView.InitialDOM_Generating.Parameter) => Array<Element>;
 };
+declare namespace GeneralizedView {
+    namespace InitialDOM_Generating {
+        type Parameter = Readonly<{
+            $reactiveState: ArbitraryObject;
+            $constantState: ArbitraryObject;
+            $eventsHandlers: EventHandlersDataMap;
+        }>;
+    }
+}
 export default GeneralizedView;

package/Distributable/Types/EventHandlersDataMap.d.ts

@@ -0,0 +1,10 @@
+import type EventHandler from "../Decorators/EventHandler";
+type EventHandlersDataMap = Map<EventHandlersDataMap.MethodName, EventHandlersDataMap.Payload>;
+declare namespace EventHandlersDataMap {
+    type MethodName = string;
+    type Payload = {
+        handler: (event: Event) => unknown;
+        options: EventHandler.Options;
+    };
+}
+export default EventHandlersDataMap;

package/Distributable/index.d.ts

@@ -1,5 +1,8 @@
 export type { default as GeneralizedView } from "./GeneralizedView";
 export { default as Component } from "./Component";
-export { default as initializeFrontendApplication } from "./Tools/initializeFrontendApplication";
-export { default as StateField } from "./Decorators/StateField";
+export type { default as EventPropagationTypes } from "./Constants/EventPropagationTypes";
+export { default as ConstantState } from "./Decorators/ConstantState";
+export { default as EventHandler } from "./Decorators/EventHandler";
+export { default as ReactiveState } from "./Decorators/ReactiveState";
 export { default as View } from "./Decorators/View";
+export { default as initializeFrontendApplication } from "./Tools/initializeFrontendApplication";

package/Distributable/index.js

@@ -1 +1 @@
-class e{}function t(e){return void 0===e}function n(e){return"string"==typeof e}function r(e){return"string"==typeof e&&e.length>0}function o(e,{mustConsiderNaN_AsNumber:t}){return"number"==typeof e&&(!isNaN(e)||t)}function i(e){return"bigint"==typeof e}function a(e){return"boolean"==typeof e}function c(e){return void 0!==e}function s(e){return null===e}function l(e){return null!==e}class u{static DOUBLE_SPACE="  ";#e=0;get currentIndentationMultiplier(){return this.#e}incrementIndent(){this.#e++}decrementIndent(){this.#e--}insertIndent(){return u.DOUBLE_SPACE.repeat(this.#e)}incrementIndentAndInsert(){return this.incrementIndent(),this.insertIndent()}decrementIndentAndInsert(){return this.decrementIndent(),this.insertIndent()}insertIncrementedIndentWithoutUpdatingOfIndentationMultiplier(){return u.DOUBLE_SPACE.repeat(this.#e+1)}addCurrentIndentationToEachLineOf(e){return function(e){return e.split("\n")}(e).map(e=>`${this.insertIndent()}${e}`).join("\n")}}function m(e){const t=Array.from(e);return t.pop(),t.join("")}class d{static stringifyAndFormat(e,t){switch(typeof e){case"string":return`"${e}"`;case"symbol":case"number":return e.toString();case"bigint":return`${e.toString()}n`;case"boolean":return`${e}`;case"undefined":return"undefined";case"function":return["String","Number","BigInt","Boolean","Array"].includes(e.name)?`[${e.name}]`:e.toString();case"object":return e instanceof Error||e instanceof RegExp?e.toString():null===e?"null":e instanceof Array?d.stringifyAsArray(e,t):e instanceof Set?d.stringifyAndFormatSet(e,t):e instanceof Map?d.stringifyAndFormatMap(e,t):e instanceof Date?e.toISOString():d.stringifyAsPlainObject(e,t)}}static stringifyAsArray(e,t=new u){let n="[";t.incrementIndent();for(const r of e)n=n+`\n${t.insertIndent()}`+`${d.stringifyAndFormat(r,t)},`;return n=m(n),t.decrementIndent(),`${n}\n${t.insertIndent()}]`}static stringifyAndFormatSet(e,t=new u){let n=`Set(${e.size}) [`;t.incrementIndent();for(const r of e)n=n+`\n${t.insertIndent()}`+`${d.stringifyAndFormat(r,t)},`;return n=m(n),t.decrementIndent(),`${n}\n${t.insertIndent()}]`}static stringifyAndFormatMap(e,t=new u){let n=`Map(${e.size}) [`;t.incrementIndent();for(const[r,o]of e.entries())n=n+`\n${t.insertIndent()}[\n`+t.incrementIndentAndInsert()+`${d.stringifyAndFormat(r,t)},\n`+t.insertIndent()+`${d.stringifyAndFormat(o,t)}\n`+`${t.decrementIndentAndInsert()}],`;return n=m(n),t.decrementIndent(),`${n}\n${t.insertIndent()}]`}static stringifyAsPlainObject(e,t=new u){let n="{";t.incrementIndent();for(const[r,o]of Object.entries(e))n=n+`\n${t.insertIndent()}`+`${r}: ${d.stringifyAndFormat(o,t)},`;return n=m(n),t.decrementIndent(),`${n}\n${t.insertIndent()}}`}}function g(e){return d.stringifyAndFormat(e)}const p={badgesDefaultTitles:{error:"Error",warning:"Warning",success:"Success",info:"Info",debug:"Debug",generic:"Common"},errorType:"Error type",occurrenceLocation:"Occurrence location",caughtError:"Caught error",innerError:"Inner error",appendedData:"Appended data"};class f{static implementation=null;static localization=p;static setImplementation(e){return f.implementation=e,f}static setLocalization(e){return f.localization=e,f}static throwErrorWithFormattedMessage(e,t={}){if(c(f.implementation?.throwErrorWithFormattedMessage))return f.implementation.throwErrorWithFormattedMessage(e,t);let n;c(e.innerError)&&(n=g(e.innerError),e.innerError instanceof Error&&r(e.innerError.stack)&&(n=e.innerError.stack.includes(n)?e.innerError.stack:`${n}\n${e.innerError.stack}`));const o=f.generateFormattedErrorFromThrownErrorLog(e,n);if("errorInstance"in e)throw e.errorInstance.message=o,e.errorInstance;const i=new Error(o);throw i.name=e.errorType,!0===t.mustLogErrorBeforeThrowing&&f.logErrorLikeMessage({title:i.name,description:i.message}),i}static logError(e){l(f.implementation)?f.implementation.logError(e):n(e)?console.error(e):!1!==e.mustOutputIf&&console.error(f.formatErrorLog(e))}static logErrorLikeMessage(e){l(f.implementation)?f.implementation.logErrorLikeMessage(e):n(e)?console.error(e):!1!==e.mustOutputIf&&console.error(f.formatGenericLog(e,f.localization.badgesDefaultTitles.error))}static logWarning(e){l(f.implementation)?f.implementation.logWarning(e):n(e)?console.warn(e):!1!==e.mustOutputIf&&console.warn(f.formatGenericLog(e,f.localization.badgesDefaultTitles.warning))}static logInfo(e){l(f.implementation)?f.implementation.logInfo(e):n(e)?console.info(e):!1!==e.mustOutputIf&&console.info(f.formatGenericLog(e,f.localization.badgesDefaultTitles.info))}static logSuccess(e){l(f.implementation)?f.implementation.logSuccess(e):n(e)?console.info(e):!1!==e.mustOutputIf&&console.info(f.formatGenericLog(e,f.localization.badgesDefaultTitles.success))}static logDebug(e){l(f.implementation)?f.implementation.logDebug(e):n(e)||o(e,{mustConsiderNaN_AsNumber:!0})||i(e)||a(e)||s(e)||t(e)?console.debug(e):!1!==e.mustOutputIf&&console.debug(f.formatGenericLog(e,f.localization.badgesDefaultTitles.debug))}static logGeneric(e){l(f.implementation)?f.implementation.logGeneric(e):n(e)||o(e,{mustConsiderNaN_AsNumber:!0})||i(e)||a(e)||s(e)||t(e)?console.log(e):!1!==e.mustOutputIf&&console.log(f.formatGenericLog(e,f.localization.badgesDefaultTitles.generic))}static logPromiseError(e){l(f.implementation)&&c(f.implementation.logPromiseError)?f.implementation.logPromiseError(e):console.error(e)}static highlightText(e){return l(f.implementation)?f.implementation.highlightText(e):e}static generateFormattedErrorFromThrownErrorLog(e,t){return[e.title,...!0===e.compactLayout?[" "]:["\n"],..."errorInstance"in e?[e.errorInstance.message]:[e.description],`\n\n${f.localization.occurrenceLocation}: ${e.occurrenceLocation}`,...c(t)?[`\n\n${f.localization.innerError}:\n${t}`]:[],...c(e.additionalData)?[`\n\n${f.localization.appendedData}:\n${g(e.additionalData)}`]:[],"\n"].join("")}static formatErrorLog(e){return[...f.generateBadgeIfMust(e.badge,f.localization.badgesDefaultTitles.error),e.title,...!0===e.compactLayout?[" "]:["\n"],e.description,`\n\n${f.localization.errorType}: ${e.errorType}`,`\n${f.localization.occurrenceLocation}: ${e.occurrenceLocation}`,...c(e.caughtError)?[`\n\n${f.localization.caughtError}:\n${g(e.caughtError)}`+(e.caughtError instanceof Error&&r(e.caughtError.stack)?`\n${e.caughtError.toString()}\n${e.caughtError.stack}`:"")]:[],...c(e.additionalData)?[`\n\n${f.localization.appendedData}:\n${g(e.additionalData)}`]:[]].join("")}static formatGenericLog(e,t){return[...f.generateBadgeIfMust(e.badge,t),e.title,...!0===e.compactLayout?[" "]:["\n"],e.description,..."occurrenceLocation"in e?[`\n${f.localization.occurrenceLocation}: ${e.occurrenceLocation}`]:[],...c(e.additionalData)?[`\n\n${f.localization.appendedData}:\n${g(e.additionalData)}`]:[]].join("")}static generateBadgeIfMust(e,t){return!1===e?[]:[`[ ${e?.customText??t} ] `]}}const E=f,h={defaultTitle:"DOM Element not Found",generateDescription:({selector:e})=>`The DOM element with selector: ${e} not found.`};class I extends Error{static NAME="DOM_ElementRetrievingFailedError";static localization=h;constructor(e){super(),this.name=I.NAME,this.message="customMessage"in e?e.customMessage:I.localization.generateDescription(e)}}const $=I,y={defaultTitle:"Unexpected Event Occurred"};class b extends Error{static NAME="UnexpectedEventError";static localization=y;constructor(e){super(),this.name=b.NAME,this.message=e}}const M=b;function D({mountingPointSelector:e,rootComponent:n}){(new n).$$mount(function(e){let n;if(t(e.contextElement))n=document;else if("selector"in e.contextElement){const t=document.querySelectorAll(e.contextElement.selector);0===t.length?E.throwErrorWithFormattedMessage({errorInstance:new $({customMessage:`The context element has not been found by the selector "${e.contextElement.selector}".`}),title:$.localization.defaultTitle,occurrenceLocation:"getExpectedToBeSingleDOM_Element(compoundParameter)"}):t.length>1&&E.logError({errorType:M.NAME,title:M.localization.defaultTitle,description:`Multiple elements are corresponding to context element selector "${e.contextElement.selector}" while the context element must be single.`,occurrenceLocation:"getExpectedToBeSingleDOM_Element(compoundParameter)"}),n=t[0]}else n=e.contextElement;const r=e.selector,o=n.querySelectorAll(r);0===o.length&&E.throwErrorWithFormattedMessage({errorInstance:new $({selector:r}),title:$.localization.defaultTitle,occurrenceLocation:"getExpectedToBeSingleDOM_Element(compoundParameter)"}),o.length>1&&E.logError({errorType:M.NAME,title:M.localization.defaultTitle,description:`Contrary to expectations, ${o.length} elements has been found for the selector "${r}". First one will be picked.`,occurrenceLocation:"getExpectedToBeSingleDOM_Element(compoundParameter)"});const i=o[0];return t(e.expectedDOM_ElementSubtype)||i instanceof e.expectedDOM_ElementSubtype||E.throwErrorWithFormattedMessage({errorInstance:new M(`Contrary to expectations, the picked element in not instance of "${e.expectedDOM_ElementSubtype.name}".`),title:M.localization.defaultTitle,occurrenceLocation:"getExpectedToBeSingleDOM_Element(compoundParameter)"}),i}({selector:e,contextElement:document}))}const A=(e,n)=>{let r=e[n];Object.defineProperty(e,n,{get:()=>r,set(e){if(e!==r||"object"==typeof e||"function"==typeof e||"object"==typeof r||"function"==typeof r){r=e;for(const e of function(e,n){const r=e.get(n);return t(r)&&E.throwErrorWithFormattedMessage({errorInstance:new M(`Contrary to expectations, there is no pair with key "${String(n)}" in target map.`),title:M.localization.defaultTitle,occurrenceLocation:"getExpectedToBeExistingMapValue(targetMap, targetKey)"}),r}(this.$$view.onStateFieldsChangedHandlers,n))e(r)}},enumerable:!0,configurable:!0})},w=e=>t=>{const n=t;Object.defineProperty(n.prototype,"$$view",{value:e,writable:!1,configurable:!1,enumerable:!1});const r=e.generateInitialDOM();Object.defineProperty(n.prototype,"$$DOM",{value:r,writable:!1,configurable:!1,enumerable:!1}),Object.defineProperty(n.prototype,"$$mount",{value(e){e.replaceWith(...r)},writable:!1,configurable:!1,enumerable:!1});for(const[t,r]of e.methodsReferences.entries())r(n.prototype[t].bind(n.prototype));return t};export{e as Component,A as StateField,w as View,D as initializeFrontendApplication};
+class e{}function t(e){return"string"==typeof e}function n(e){return"string"==typeof e&&e.length>0}function r(e,{mustConsiderNaN_AsNumber:t}){return"number"==typeof e&&(!isNaN(e)||t)}function o(e){return"bigint"==typeof e}function i(e){return"boolean"==typeof e}function a(e){return void 0===e}function c(e){return void 0!==e}function s(e){return null===e}function l(e){return null!==e}class u{static DOUBLE_SPACE="  ";#e=0;get currentIndentationMultiplier(){return this.#e}incrementIndent(){this.#e++}decrementIndent(){this.#e--}insertIndent(){return u.DOUBLE_SPACE.repeat(this.#e)}incrementIndentAndInsert(){return this.incrementIndent(),this.insertIndent()}decrementIndentAndInsert(){return this.decrementIndent(),this.insertIndent()}insertIncrementedIndentWithoutUpdatingOfIndentationMultiplier(){return u.DOUBLE_SPACE.repeat(this.#e+1)}addCurrentIndentationToEachLineOf(e){return function(e){return e.split("\n")}(e).map(e=>`${this.insertIndent()}${e}`).join("\n")}}function d(e){const t=Array.from(e);return t.pop(),t.join("")}class m{static stringifyAndFormat(e,t){switch(typeof e){case"string":return`"${e}"`;case"symbol":case"number":return e.toString();case"bigint":return`${e.toString()}n`;case"boolean":return`${e}`;case"undefined":return"undefined";case"function":return["String","Number","BigInt","Boolean","Array"].includes(e.name)?`[${e.name}]`:e.toString();case"object":return e instanceof Error||e instanceof RegExp?e.toString():null===e?"null":e instanceof Array?m.stringifyAsArray(e,t):e instanceof Set?m.stringifyAndFormatSet(e,t):e instanceof Map?m.stringifyAndFormatMap(e,t):e instanceof Date?e.toISOString():m.stringifyAsPlainObject(e,t)}}static stringifyAsArray(e,t=new u){if(0===e.length)return"[]";let n="[";t.incrementIndent();for(const r of e)n=n+`\n${t.insertIndent()}`+`${m.stringifyAndFormat(r,t)},`;return n=d(n),t.decrementIndent(),`${n}\n${t.insertIndent()}]`}static stringifyAndFormatSet(e,t=new u){if(0===e.size)return"Set(0) []";let n=`Set(${e.size}) [`;t.incrementIndent();for(const r of e)n=n+`\n${t.insertIndent()}`+`${m.stringifyAndFormat(r,t)},`;return n=d(n),t.decrementIndent(),`${n}\n${t.insertIndent()}]`}static stringifyAndFormatMap(e,t=new u){if(0===e.size)return"Map(0) []";let n=`Map(${e.size}) [`;t.incrementIndent();for(const[r,o]of e.entries())n=n+`\n${t.insertIndent()}[\n`+t.incrementIndentAndInsert()+`${m.stringifyAndFormat(r,t)},\n`+t.insertIndent()+`${m.stringifyAndFormat(o,t)}\n`+`${t.decrementIndentAndInsert()}],`;return n=d(n),t.decrementIndent(),`${n}\n${t.insertIndent()}]`}static stringifyAsPlainObject(e,t=new u){const n=Object.entries(e);if(0===n.length)return"{}";let r="{";t.incrementIndent();for(const[e,o]of n)r=r+`\n${t.insertIndent()}`+`${e}: ${m.stringifyAndFormat(o,t)},`;return r=d(r),t.decrementIndent(),`${r}\n${t.insertIndent()}}`}}function g(e){return m.stringifyAndFormat(e)}const p={badgesDefaultTitles:{error:"Error",warning:"Warning",success:"Success",info:"Info",debug:"Debug",generic:"Common"},errorType:"Error type",occurrenceLocation:"Occurrence location",caughtError:"Caught error",innerError:"Inner error",appendedData:"Appended data"};class f{static implementation=null;static localization=p;static setImplementation(e){return f.implementation=e,f}static setLocalization(e){return f.localization=e,f}static throwErrorWithFormattedMessage(e,t={}){if(c(f.implementation?.throwErrorWithFormattedMessage))return f.implementation.throwErrorWithFormattedMessage(e,t);let r;c(e.innerError)&&(r=g(e.innerError),e.innerError instanceof Error&&n(e.innerError.stack)&&(r=e.innerError.stack.includes(r)?e.innerError.stack:`${r}\n${e.innerError.stack}`));const o=f.generateFormattedErrorFromThrownErrorLog(e,r);if("errorInstance"in e)throw e.errorInstance.message=o,e.errorInstance;const i=new Error(o);throw i.name=e.errorType,!0===t.mustLogErrorBeforeThrowing&&f.logErrorLikeMessage({title:i.name,description:i.message}),i}static logError(e){l(f.implementation)?f.implementation.logError(e):t(e)?console.error(e):!1!==e.mustOutputIf&&console.error(f.formatErrorLog(e))}static logErrorLikeMessage(e){l(f.implementation)?f.implementation.logErrorLikeMessage(e):t(e)?console.error(e):!1!==e.mustOutputIf&&console.error(f.formatGenericLog(e,f.localization.badgesDefaultTitles.error))}static logWarning(e){l(f.implementation)?f.implementation.logWarning(e):t(e)?console.warn(e):!1!==e.mustOutputIf&&console.warn(f.formatGenericLog(e,f.localization.badgesDefaultTitles.warning))}static logInfo(e){l(f.implementation)?f.implementation.logInfo(e):t(e)?console.info(e):!1!==e.mustOutputIf&&console.info(f.formatGenericLog(e,f.localization.badgesDefaultTitles.info))}static logSuccess(e){l(f.implementation)?f.implementation.logSuccess(e):t(e)?console.info(e):!1!==e.mustOutputIf&&console.info(f.formatGenericLog(e,f.localization.badgesDefaultTitles.success))}static logDebug(e){l(f.implementation)?f.implementation.logDebug(e):t(e)||r(e,{mustConsiderNaN_AsNumber:!0})||o(e)||i(e)||s(e)||a(e)?console.debug(e):!1!==e.mustOutputIf&&console.debug(f.formatGenericLog(e,f.localization.badgesDefaultTitles.debug))}static logGeneric(e){l(f.implementation)?f.implementation.logGeneric(e):t(e)||r(e,{mustConsiderNaN_AsNumber:!0})||o(e)||i(e)||s(e)||a(e)?console.log(e):!1!==e.mustOutputIf&&console.log(f.formatGenericLog(e,f.localization.badgesDefaultTitles.generic))}static logPromiseError(e){l(f.implementation)&&c(f.implementation.logPromiseError)?f.implementation.logPromiseError(e):console.error(e)}static highlightText(e){return l(f.implementation)?f.implementation.highlightText(e):e}static generateFormattedErrorFromThrownErrorLog(e,t){return[e.title,...!0===e.compactLayout?[" "]:["\n"],..."errorInstance"in e?[e.errorInstance.message]:[e.description],`\n\n${f.localization.occurrenceLocation}: ${e.occurrenceLocation}`,...c(t)?[`\n\n${f.localization.innerError}:\n${t}`]:[],...c(e.additionalData)?[`\n\n${f.localization.appendedData}:\n${g(e.additionalData)}`]:[],"\n"].join("")}static formatErrorLog(e){return[...f.generateBadgeIfMust(e.badge,f.localization.badgesDefaultTitles.error),e.title,...!0===e.compactLayout?[" "]:["\n"],e.description,`\n\n${f.localization.errorType}: ${e.errorType}`,`\n${f.localization.occurrenceLocation}: ${e.occurrenceLocation}`,...c(e.caughtError)?[`\n\n${f.localization.caughtError}:\n${g(e.caughtError)}`+(e.caughtError instanceof Error&&n(e.caughtError.stack)?`\n${e.caughtError.toString()}\n${e.caughtError.stack}`:"")]:[],...c(e.additionalData)?[`\n\n${f.localization.appendedData}:\n${g(e.additionalData)}`]:[]].join("")}static formatGenericLog(e,t){return[...f.generateBadgeIfMust(e.badge,t),e.title,...!0===e.compactLayout?[" "]:["\n"],e.description,..."occurrenceLocation"in e?[`\n${f.localization.occurrenceLocation}: ${e.occurrenceLocation}`]:[],...c(e.additionalData)?[`\n\n${f.localization.appendedData}:\n${g(e.additionalData)}`]:[]].join("")}static generateBadgeIfMust(e,t){return!1===e?[]:[`[ ${e?.customText??t} ] `]}}const h=f,E={defaultTitle:"Improper Usage"};class b extends Error{static NAME="ImproperUsageError";static localization=E;constructor(e){super(),this.name=b.NAME,this.message=e}}const $=b,y=(t,n)=>{t instanceof e||h.throwErrorWithFormattedMessage({errorInstance:new $("The `StateField` decorator can be used only for YDUR component classes."),title:$.localization.defaultTitle,occurrenceLocation:"StateField(componentClassPrototype, propertyKey)"}),a(Reflect.get(t,"$constantState"))&&Object.defineProperty(t,"$constantState",{value:{},enumerable:!1,configurable:!1,writable:!1}),Object.defineProperty(t,n,{get(){return this.$constantState[n]},set(e){Object.defineProperty(this.$constantState,n,{configurable:!1,writable:!1,value:e})},enumerable:!1,configurable:!1})},I=(t={})=>(n,r,o)=>{n instanceof e||h.throwErrorWithFormattedMessage({errorInstance:new $("The `EventHandler` decorator can be used only for YDUR component classes."),title:$.localization.defaultTitle,occurrenceLocation:"EventHandler.MethodDecorator(componentClassPrototype, methodKey, descriptor)"});const i=Reflect.get(n,"$eventsHandlers");let a;i instanceof Map?a=i:(a=new Map,Object.defineProperty(n,"$eventsHandlers",{value:a,enumerable:!1,configurable:!1,writable:!1})),a.set(String(r),{handler:o.value.bind(n),options:t})},M={defaultTitle:"Unexpected Event Occurred"};class S extends Error{static NAME="UnexpectedEventError";static localization=M;constructor(e){super(),this.name=S.NAME,this.message=e}}const w=S,D=(t,n)=>{t instanceof e||h.throwErrorWithFormattedMessage({errorInstance:new $("The `StateField` decorator can be used only for YDUR component classes."),title:$.localization.defaultTitle,occurrenceLocation:"StateField(componentClassPrototype, propertyKey)"}),a(Reflect.get(t,"$reactiveState"))&&Object.defineProperty(t,"$reactiveState",{value:{},enumerable:!1,configurable:!1,writable:!1}),Object.defineProperty(t,n,{get(){return this.$reactiveState[n]},set(e){const t=this.$reactiveState[n];if((e!==t||"object"==typeof e||"function"==typeof e||"object"==typeof t||"function"==typeof t)&&(this.$reactiveState[n]=e,this.$isReactivityEnabled))for(const e of function(e,t){const n=e.get(t);return a(n)&&h.throwErrorWithFormattedMessage({errorInstance:new w(`Contrary to expectations, there is no pair with key "${String(t)}" in target map.`),title:w.localization.defaultTitle,occurrenceLocation:"getExpectedToBeExistingMapValue(targetMap, targetKey)"}),n}(this.$view.onStateFieldsChangedHandlers,n))e(this.$reactiveState[n])},enumerable:!0,configurable:!0})},O=e=>t=>{const n=t;Object.defineProperty(n.prototype,"$view",{value:e,writable:!1,configurable:!1,enumerable:!1});const r=n;return class extends r{constructor(){super(),a(this.$reactiveState)&&Object.defineProperty(this,"$reactiveState",{value:{},enumerable:!1,configurable:!1,writable:!1}),a(this.$constantState)&&Object.defineProperty(this,"$constantState",{value:{},enumerable:!1,configurable:!1,writable:!1}),a(this.$eventsHandlers)&&Object.defineProperty(this,"$eventsHandlers",{value:new Map,enumerable:!1,configurable:!1,writable:!1}),Object.defineProperty(n.prototype,"$DOM",{value:e.generateInitialDOM({$reactiveState:this.$reactiveState,$constantState:this.$constantState,$eventsHandlers:this.$eventsHandlers}),writable:!1,configurable:!1,enumerable:!1}),Object.defineProperty(n.prototype,"$mount",{value:e=>{e.replaceWith(...this.$DOM)},writable:!1,configurable:!1,enumerable:!1}),Object.defineProperty(n.prototype,"$isReactivityEnabled",{value:!0,configurable:!1,enumerable:!1,writable:!1})}}},T={defaultTitle:"DOM Element not Found",generateDescription:({selector:e})=>`The DOM element with selector: ${e} not found.`};class v extends Error{static NAME="DOM_ElementRetrievingFailedError";static localization=T;constructor(e){super(),this.name=v.NAME,this.message="customMessage"in e?e.customMessage:v.localization.generateDescription(e)}}const A=v;function L({mountingPointSelector:e,rootComponent:t}){(new t).$mount(function(e){let t;if(a(e.contextElement))t=document;else if("selector"in e.contextElement){const n=document.querySelectorAll(e.contextElement.selector);0===n.length?h.throwErrorWithFormattedMessage({errorInstance:new A({customMessage:`The context element has not been found by the selector "${e.contextElement.selector}".`}),title:A.localization.defaultTitle,occurrenceLocation:"getExpectedToBeSingleDOM_Element(compoundParameter)"}):n.length>1&&h.logError({errorType:w.NAME,title:w.localization.defaultTitle,description:`Multiple elements are corresponding to context element selector "${e.contextElement.selector}" while the context element must be single.`,occurrenceLocation:"getExpectedToBeSingleDOM_Element(compoundParameter)"}),t=n[0]}else t=e.contextElement;const n=e.selector,r=t.querySelectorAll(n);0===r.length&&h.throwErrorWithFormattedMessage({errorInstance:new A({selector:n}),title:A.localization.defaultTitle,occurrenceLocation:"getExpectedToBeSingleDOM_Element(compoundParameter)"}),r.length>1&&h.logError({errorType:w.NAME,title:w.localization.defaultTitle,description:`Contrary to expectations, ${r.length} elements has been found for the selector "${n}". First one will be picked.`,occurrenceLocation:"getExpectedToBeSingleDOM_Element(compoundParameter)"});const o=r[0];return a(e.expectedDOM_ElementSubtype)||o instanceof e.expectedDOM_ElementSubtype||h.throwErrorWithFormattedMessage({errorInstance:new w(`Contrary to expectations, the picked element in not instance of "${e.expectedDOM_ElementSubtype.name}".`),title:w.localization.defaultTitle,occurrenceLocation:"getExpectedToBeSingleDOM_Element(compoundParameter)"}),o}({selector:e,contextElement:document}))}export{e as Component,y as ConstantState,I as EventHandler,D as ReactiveState,O as View,L as initializeFrontendApplication};

package/README.md

@@ -2,10 +2,13 @@
 
 <figure align="center">
   <img 
-    src="https://github.com/user-attachments/assets/c129e15c-4969-4178-8213-c0acfd2b7b47" 
-    alt="The decrative image shows that the library is in development."
+    src="https://imgur.com/a/NMyzesK" 
+    alt="The decorative image shows that the library is in development."
   >
-  <figcaption style="text-align: center;">The library is in development. See the "Roadmap" section for progress.</figcaption>
+  <figcaption style="text-align: center;">
+    The library is in development. 
+    See the <a href="#planned">Features/Planned</a> section to get information about progress.
+  </figcaption>
 </figure>
 
 
@@ -14,15 +17,18 @@
 The object-oriented programming-based library for the frontend Web+ development alternative to React, Vue, Svelte and 
   the like.
 
-No plans to position is as a framework because it is intended to be the tool taking care of typical frontend development 
-  tasks without stealing too much attention and forcing of specific architecture, naming and directories structure. 
+No plans to position it as a framework because it is intended to be the just the _tool_ taking care of typical frontend 
+  development tasks without stealing too much attention and forcing of specific architecture, naming and directories 
+  structure. 
 
 
-## Features (May be Pros of Cons Depending on Your Preferences)
+## Features
+
+The following feature may be pros of cons depending on your preferences.
 
 + Class-based components. No functional API planned.
-+ [Pug](https://pugjs.org/api/getting-started.html) is the only language for templates. No plaing HTML support planned. 
-+ No new file names extension like `.vue` or `.jsx`.
++ [Pug](https://pugjs.org/api/getting-started.html) is the only language for templates. No plain HTML support planned. 
++ No new file names extensions like `.vue` or `.jsx`.
 + No new syntaxes like Vue single file components or JSX. Just plain Pug and TypeScript.
 + Project building tool like Webpack is required.
 
@@ -45,22 +51,22 @@ The sequence may be changed during the development.
 ##### "Counter.ydfr.pug" — The Component Template
 
 ```pug
-samp= $currentValue
+samp= $reactiveState.currentValue
 
 .Counter-ActionBar
 
   button(
     type="button"
-    @click=onClickIncrementingButton
+    @onLeftClick=onClickIncrementingButton
   ) Increment
 
   button(
     type="button"
-    @click=onClickDecrementingButton
+    @onLeftClick=onClickDecrementingButton
   ) Decrement
 ```
 
-The YDUR components templates is been defined by [Pug](https://github.com/pugjs/pug), the template language.
+The YDUR components templates are been defined by [Pug](https://github.com/pugjs/pug), the template language.
 No plans to support HTML.
 
 
@@ -74,15 +80,17 @@ import componentTemplate from "./Counter.ydur.pug";
 @YDFR.View(componentTemplate)
 export default class Counter extends YDFR.Component {
 
-  @YDFR.StateField
-  public $currentValue: number = 0;
+  @YDFR.ReactiveState
+  protected currentValue: number = 0;
 
-  public onClickIncrementingButton(): void {
-    this.$currentValue++;
+  @YDFR.EventHandler()
+  protected onClickIncrementingButton(): void {
+    this.currentValue++;
   }
 
-  public onClickDecrementingButton(): void {
-    this.$currentValue--;
+  @YDFR.EventHandler()
+  protected onClickDecrementingButton(): void {
+    this.currentValue--;
   }
 
 }
@@ -91,12 +99,21 @@ export default class Counter extends YDFR.Component {
 + The component logic is the plain TypeScript class with decorators.
   Besides its main role, you can use it as the plain TypeScript classes, for example, define
     the public static members and call them from outside (when it makes sense).
-* To import `componentTemplate` from Pug file correctly, you need the appropriate plugin for you project building
++ To import `componentTemplate` from Pug file correctly, you need the appropriate plugin for you project building
     system. 
   Currently, the [Webpack loader](https://www.npmjs.com/package/@yamato-daiwa/universal-reactive-webpack-loader) is available.
-  The value of `componentTemplate` is not the string with HTML code — the YDUR templates compiler builds the JavaScript 
+  The value of `componentTemplate` is _not_ the string with HTML code — the YDUR templates compiler builds the JavaScript 
     object called "View" based on Pug code.
   Such an approach is Svelte-like, one advantage of it is better performance than DOM diffing as in React.
++ The `currentValue` field has been declared with `@YDFR.ReactiveState` decorator.
+  It means the changing of this field will update the DOM depends on it.
+  `currentValue` is accessible from template as `$reativeState.currentValue`.
+  Contrary to `$reativeState` state, there is the `$constantState` one.
++ The methods are accessible from the template by names as event handlers, but must be decorated by 
+  `@YDFR.EventHandler()` decoratory. Unlike `@YDFR.ReactiveState`, it requires `()` becaue optionally the event hanling
+  options may be passed.
++ You can make all instance members private in this example, but the **TypeScript** and/all linting tool may complain
+  about these fields have not been explicitly used.
 
 
 ##### index.ts — The Entry Point
@@ -113,4 +130,169 @@ YDFR.initializeFrontendApplication({
 ```
 
 You need at least one component to create the application instance.
-Once it defined, the application may created by one function.
+Once it defined, the application may be created by one function.
+Of course, the HTML element with ID `APPLICATION_ROOT` must exist to initialize the application succesfully. 
+
+
+
+### Reactive and Constant State
+
+Some state fields are not intended to be updated during the component lifecycle.
+It means no need to make them to a reactive state for performance purposes.
+As default, the class fields are not accessible from template, but to declare the constant state field you can use the
+  `@YDFR.ConstantState` field:
+
+```ts
+import * as YDFR from "@yamato-daiwa/universal-reactive";
+import componentTemplate from "./Counter.ydur.pug";
+
+
+@YDFR.View(componentTemplate)
+export default class Counter extends YDFR.Component {
+
+  // Basically, should be set to `readonly` but we will try to change it for experiment.
+  @YDFR.ConstantState
+  protected heading: string = "Counter";
+  
+  @YDFR.ReactiveState
+  public currentValue: number = 0;
+
+  @YDFR.EventHandler()
+  public onClickIncrementingButton(): void {
+    
+    this.currentValue++;
+    
+    // You will get TypeError if try to chage it. Of course, DOM dependes in this firld will not be updated.
+    this.heading = "NEW HEADING"
+    
+  }
+
+  @YDFR.EventHandler()
+  public onClickDecrementingButton(): void {
+    this.currentValue--;
+  }
+
+}
+```
+
+You can access to `heading` in template via `$constantState` object:
+
+```pug
+h1= $constantState.heading
+
+samp= $reativeState.currentValue
+
+.Counter-ActionBar
+
+  button(
+    type="button"
+    @onLeftClick=onClickIncrementingButton
+  ) Increment
+
+  button(
+    type="button"
+    @onLeftClick=onClickDecrementingButton
+  ) Decrement
+```
+
+
+### Events Handling
+
+You can access to instance methods by name from template if they has been decorated by `@YDFR.EventHandler()`:
+
+```ts
+@YDFR.View(componentTemplate)
+export default class Counter extends YDFR.Component {
+
+  // ...
+
+  @YDFR.EventHandler()
+  public onClickIncrementingButton(): void {
+    // ...
+  }
+
+  @YDFR.EventHandler()
+  public onClickDecrementingButton(): void {
+    // ...
+  }
+
+}
+```
+
+Unlike `@YDFR.ReactiveState` or `@YDFR.ConstantState`, `@YDFR.EventHandler` decorator must be invoked because the optons
+  may be passed:
+
+```ts
+type Options = Readonly<{
+  
+  /* @default EventPropagationTypes.bubbling */
+  eventPropagation?: EventPropagationTypes | false;
+  
+  /* @default false */
+  mustBeCalledOnce?: boolean;
+  
+  /* @default false */
+  mustKeepDefaultBehaviour?: boolean;
+  
+}>;
+
+enum EventPropagationTypes {
+  bubbling = "BUBBLING",
+  capturing = "CAPTURING"
+}
+```
+
+The names of the options has been designed such as does not need any explanations.
+
+If you don't know about **bubbling** and **capturing**, it is a *common* terminology, not terminology of YDR.
+Check [this](https://javascript.info/bubbling-and-capturing) tutorial for details.
+
+Once decorated, the method can be referred from the template by the following attributes.
+
+```pug
+.Counter-ActionBar
+
+  button(
+    type="button"
+    @onLeftClick=onClickIncrementingButton
+  ) Increment
+
+  button(
+    type="button"
+    @onLeftClick=onClickDecrementingButton
+  ) Decrement
+```
+
+Currently available events name listed below.
+
+#### Mouse Events
+
+| YDUR Event Name    | Native event name |
+|--------------------|-------------------|
+| @onLeftClick       | click             |
+| @onDoubleLeftClick | dblclick          |
+| @onRightClick      | auxclick          |
+| @onMouseDown       | mousedown         |
+| @onMouseUp         | mouseup           |
+| @onMouseMoved      | mousemove         |
+| @onMouseOver       | mouseover         |
+| @onMouseOut        | mouseout          |
+| @onMouseEntered    | mouseenter        |
+| @onMouseLeft       | mouseleave        |
+
+
+#### Keyboard Events
+
+| YDUR Event Name | Native event name |
+|-----------------|-------------------|
+| @onKeyPressed   | keyup             |
+| @onKeyUp        | keyup             |
+| @onKeyDown      | keydown           |
+| @onInput        | input             |
+
+
+#### Common Events
+
+| YDUR Event Name | Native event name |
+|-----------------|-------------------|
+| @onChange       | change            |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yamato-daiwa/universal-reactive",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "OOP-based library for frontend development.",
   "keywords": [
     "frontend"
@@ -25,14 +25,14 @@
   "module": "./Distributable/index.js",
   "types": "./Distributable/index.d.ts",
   "dependencies": {
-    "@yamato-daiwa/es-extensions": "1.8.2",
-    "@yamato-daiwa/es-extensions-browserjs": "1.8.2"
+    "@yamato-daiwa/es-extensions": "1.8.4",
+    "@yamato-daiwa/es-extensions-browserjs": "1.8.4"
   },
   "devDependencies": {
-    "@yamato-daiwa/automation": "0.8.0",
+    "@yamato-daiwa/automation": "0.9.0-alpha.3",
     "@yamato-daiwa/frontend": "2.0.0-beta.11",
-    "@yamato-daiwa/style_guides": "0.10.1",
-    "rimraf": "6.0.1",
+    "@yamato-daiwa/style_guides": "0.11.2",
+    "rimraf": "6.1.2",
     "typescript": "5.9.3"
   },
   "scripts": {

package/Distributable/Decorators/StateField.d.ts

@@ -1,2 +0,0 @@
-declare const StateField: PropertyDecorator;
-export default StateField;