ueca-react 1.0.5 → 2.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 ISC License
 
-Copyright (c) Aleksey Suvorov, CraneSoft LLC
+Copyright (c) 2022-2026 Aleksey Suvorov
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted, provided that the above

package/README.md

@@ -1,57 +1,109 @@
-![logo](/docs/logo.png)
-
-# Unified Encapsulated Component Architecture
-
-## From the Author
-
-The UECA framework was initially developed as a fun pet project to explore the unification of building blocks (components) in React-based applications. The rationale behind this was straightforward: developing large-scale React applications, especially the business logic, using pure React and the recommended React patterns is unequivocally challenging. Even with a well-organized, experienced, and motivated development team, pure React code often appears overly complex, creating unnecessary cognitive load for developers. This complexity usually leads to poor code structure, numerous bugs, tensions among developers, and frequently missed deadlines, ultimately harming the business.
-
-React, while powerful, is a relatively low-level technology that demands developers not only have substantial React programming experience but also meticulously organize their code to avoid confusion. This approach is labor-intensive during both development and maintenance. Statistically, low-level, non-templated code tends to have more bugs than code built on a foundation of higher-order architectural principles. Ideally, low-level programming patterns should be encapsulated behind a facade of these principles.
-
-In most cases, UI application development employs a component-based approach. The user interface is constructed from various unified parts called components, and React is built on this model. However, standard React patterns force developers to worry excessively about component interactions. As a result, developers often write different code that serves similar functions. In a team environment, this issue can multiply exponentially. Normalizing such logic is either prohibitively expensive or nearly impossible. Unfortunately, businesses often prioritize enhancements over code refactoring, leaving teams to manage redundant code that becomes increasingly costly to support over time. Statistically, the likelihood of bugs in the system increases with the volume of code.
-
-UECA addresses this problem by encapsulating routine code, allowing developers to focus on high-level logic and unifying the code structure. Additionally, UECA mitigates the need for highly experienced React developers. The code pattern requires minimal React experience, making the primary technologies TypeScript and JSX. Even a group of junior developers, guided by a UI architect, can perform well using this framework.
-
-The UECA library has already been successfully employed to develop a large-scale commercial web application. Initially, the project began with pure React, but it gradually became unmanageable. Adopting UECA saved the project from shutdown, preserved developers' jobs, and ultimately allowed the product to be released. This is a true success story. 
-
-Special thanks to *Artem Tsetkhalin, Roman Ilyuchonak, Roman Nekliukov, Andrey Solovyov, and Pavel Borodaev* for their testing and bug reports.
-
-If you have any questions or comments, please feel free to reach out to me at cranesoft@protonmail.com.
-
-Thank you very much for your interest in and support of UECA ideas. Happy coding! 😎
-
-## UECA Basic Documentation
-
-Comprehensive documentation detailing UECA aspects, code patterns, and examples will be available soon.
-
-### [1. Component Mental Model](/docs/component-mental-model.md)
-
-### [2. Component Integration Model](/docs/component-intergation-model.md)
-
-### [3. Introduction to UECA](/docs/introduction.md)
-
-### [4. Technology of UECA ](/docs/technology.md)
-
-### [5. Base Concepts of UECA ](/docs/base-concepts.md)
-
-### [6. General Code Structure](/docs/general-code-structure.md)
-
-### [7. Property Bindings ](/docs/bindings-overview.md)
-
-### [8. Message Bus ](/docs/message-bus.md)
-
-### [9. Standard Code Template](/docs/code-template.md)
-
-## Code Examples on CodeSandbox
-#### [UECA Basics: Application (Code Examples Menu)](https://codesandbox.io/p/sandbox/frosty-banach-jsf84c)
-
-Additional code examples will be available soon. Check the CodeSandbox UECA project.
-
-#
-
-<iframe src="https://codesandbox.io/embed/8x7yst?view=preview&module=%2Fsrc%2Fcomponents%2FappMessages.ts&hidenavigation=1"
-     style="width:100%; height: 500px; border:0; border-radius: 4px; overflow:hidden;"
-     title="UECA Basics: Message Bus"
-     allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
-     sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
-/>
+![logo](./docs/logo.png)
+# UECA-React
+
+> **⚠️ NOTICE: This is a test publication for early testing and feedback. The API may change before the stable release. Not recommended for production use yet.**
+
+UECA-React is a framework for building scalable React applications with a unified and encapsulated component architecture. It simplifies development by hiding the complexities of React and MobX behind a consistent component pattern.
+
+## Installation
+
+To install UECA-React, run the following command:
+
+```bash
+npm install ueca-react
+```
+
+Ensure that your project also has the following dependencies installed:
+
+- react
+- react-dom
+- mobx
+- mobx-react
+
+Compatible React versions: 16.8.0–19.1.0. Make sure your react-dom version matches your react version.
+
+## Usage
+
+Here's a simple example of a UECA component:
+
+```typescript
+import * as UECA from "ueca-react";
+
+type ButtonStruct = UECA.ComponentStruct<{
+    props: { 
+        caption: string;
+        disabled: boolean;
+    };
+
+    events: {
+        onClick: () => void;
+    };
+}>;
+
+type ButtonParams = UECA.ComponentParams<ButtonStruct>;
+type ButtonModel = UECA.ComponentModel<ButtonStruct>;
+
+function useButton(params?: ButtonParams): ButtonModel {
+    const struct: ButtonStruct = {
+        props: {            
+            caption: "MyButton",
+            disabled: false
+        },
+
+        events: {
+            onChangeDisabled: (value) => {
+                console.log(`Button id=${model.fullId()} disabled=${value}`);
+            }
+        },
+
+        View: () => (
+            <button id={model.htmlId()} disabled={model.disabled} onClick={() => model.onClick?.()}>
+                {model.caption}
+            </button>
+        )
+    };
+
+    const model = UECA.useComponent(struct, params);
+    return model;
+}
+
+const Button = UECA.getFC(useButton);
+export { ButtonModel, useButton, Button };
+```
+
+For more detailed information, check out the [full documentation](./docs/index.md).
+
+## Features
+
+- **Unified Component Pattern**: Consistent structure for all components
+- **Type-Safe**: Full TypeScript support with comprehensive type definitions
+- **MobX Integration**: Automatic reactivity without manual state management
+- **Automatic onChange Events**: Auto-generated event handlers for every property (e.g., `onChangeCaption` for `caption` prop)
+- **Lifecycle Hooks**: Built-in lifecycle management (constr, init, mount, draw, erase, unmount, deinit)
+- **Message Bus**: Decoupled inter-component communication
+- **Property Bindings**: Bidirectional data binding between components
+- **AI-Friendly**: Designed for easy code generation and AI assistance
+
+## Documentation
+
+Comprehensive documentation is available in the [docs](./docs) folder:
+- [Introduction to UECA-React](./docs/Introduction%20to%20UECA-React.md)
+- [Component Guide](./docs/Introduction%20to%20UECA-React%20Components.md)
+- [State Management](./docs/State%20Management%20in%20UECA-React.md)
+- [Message Bus](./docs/Message%20Bus%20in%20UECA-React.md)
+- [Lifecycle Hooks](./docs/Lifecycle%20Hooks%20in%20UECA-React.md)
+- [Property Bindings](./docs/Property%20Bindings%20in%20UECA-React.md)
+
+## Support
+
+For questions, issues, or feature requests, please use the [GitHub issue tracker](https://github.com/nekutuzov/ueca-react-npm/issues).
+
+## License
+
+This project is licensed under the ISC License - see the [LICENSE](./LICENSE) file for details.
+
+## Author
+
+**Aleksey Suvorov**  
+Email: cranesoft@protonmail.com  
+GitHub: [nekutuzov/ueca-react-npm](https://github.com/nekutuzov/ueca-react-npm)

package/dist/index.d.ts

@@ -1,4 +1,266 @@
-export { ComponentModel, AnyComponentModel, ComponentTemplate, ComponentStruct, ComponentProps, ComponentMethods, ComponentEvents, ComponentMessages, ComponentParams, ComponentView, DynamicChildren, ComponentModelTrap, ComponentModelTrapRegistry, useComponentModelTrap, newComponentModelTrapRegistry, useComponent, mergeStruct, blankView, bind, bindProp, componentModelDebug, getFC, $ } from "./componentModel";
-export { IMessageBus, Messages, AsyncMethod, AnyMessage, MessageBusEvent, AnyName, Messaging, messageBusEventPost, useMessaging, useCustomMessaging, createMessageBus, defaultMessageBus } from "./messageBus";
-export { DynamicContentModel, DynamicContent, useDynamicContent } from "./dynamicContent";
-export { IF, renderNode, isSimpleNode } from "./utils";
+import * as React_2 from 'react';
+
+export declare const $: unique symbol;
+
+export declare const $name = "$";
+
+export declare type AnyComponentModel = ComponentModel<AnyComponentStruct>;
+
+export declare type AnyComponentParams = ComponentParams<AnyComponentStruct>;
+
+export declare type AnyComponentStruct = ComponentStruct<ComponentStructBase<BusMessages>>;
+
+export declare function bind<T extends NonNullable<unknown>, P extends keyof T>(obj: () => T, prop: P): Bond<T[P]>;
+
+export declare function bind<T>(get: () => T, set: ((value: T) => void) | undefined): Bond<T>;
+
+/**
+ * @deprecated Use the `bind` function instead.
+ */
+export declare function bindProp<T extends NonNullable<unknown>, P extends keyof T>(obj: () => T, prop: P): Bond<T[P]>;
+
+export declare type Bond<T> = [(() => T) | undefined, ((value: T) => void) | undefined];
+
+export declare type BusMessageHandlers<TMsg extends BusMessages> = {
+    [Msg in keyof TMsg]?: ParamIn<TMsg, Msg> extends undefined ? MessageHandlerNoPar<TMsg, Msg> : MessageHandler<TMsg, Msg>;
+};
+
+export declare type BusMessages = Record<MessageID, InParam | OutParam | InParam & OutParam> | EmptyObject;
+
+export declare function clone<T>(obj: T): T | undefined;
+
+declare type ComponentChildren<TStruct extends GeneralComponentStruct> = NonNullable<TStruct["children"]>;
+
+declare type ComponentEvents<TStruct extends GeneralComponentStruct> = Partial<NonNullable<TStruct["events"]>>;
+
+declare type ComponentMessages<TStruct extends ComponentStructBase<TMsg>, TMsg extends BusMessages> = NonNullable<TStruct["messages"]>;
+
+declare type ComponentMethods<TStruct extends GeneralComponentStruct> = NonNullable<TStruct["methods"]>;
+
+export declare type ComponentModel<TStruct extends ComponentStruct<ComponentStructBase<TMsg>, TMsg>, TMsg extends BusMessages = BusMessages> = ComponentProps<NonNullable<TStruct["__struct"]>> & Readonly<ComponentChildren<NonNullable<TStruct["__struct"]>>> & Readonly<ComponentMethods<NonNullable<TStruct["__struct"]>>> & ComponentStructEvents<ComponentProps<NonNullable<TStruct["__struct"]>>> & ComponentEvents<NonNullable<TStruct["__struct"]>> & {
+    readonly $: ComponentPrivateMembers;
+    readonly bus: MessageBus<TMsg>;
+    readonly View: ComponentView;
+    readonly BaseView: ComponentView;
+    readonly disableOnChange: () => void;
+    readonly enableOnChange: () => void;
+    readonly changeNotifyDisabled: () => boolean;
+    readonly fullId: () => string;
+    readonly htmlId: () => string | undefined;
+    readonly birthMark: () => string;
+    readonly clearModelCache: () => void;
+    readonly getChildrenModels: GetChildrenModels;
+    readonly invalidateView: () => void;
+};
+
+export declare type ComponentParams<TStruct extends ComponentStruct<ComponentStructBase<TMsg>, TMsg>, TMsg extends BusMessages = BusMessages> = ComponentProps<TStruct> & ComponentEvents<TStruct> & {
+    constr?: (model: ComponentModel<TStruct, TMsg>) => void;
+    init?: (model: ComponentModel<TStruct, TMsg>) => void;
+    deinit?: (model: ComponentModel<TStruct, TMsg>) => void;
+    mount?: (model: ComponentModel<TStruct, TMsg>) => void;
+    unmount?: (model: ComponentModel<TStruct, TMsg>) => void;
+    draw?: (model: ComponentModel<TStruct, TMsg>) => void;
+    erase?: (model: ComponentModel<TStruct, TMsg>) => void;
+};
+
+declare type ComponentPrivateMembers = {
+    __status: {
+        initPhase?: "constructing" | "constructed" | "initializing" | "initialized" | "unmount-deinit" | "deinitializing";
+        mountPhase?: "init-mount" | "mounting" | "mounted" | "unmounting";
+        cached: boolean;
+        initCount: number;
+        mountCount: number;
+        baseResult: unknown;
+    };
+    __settersInProgress: string[];
+    __owner: AnyComponentModel;
+    __struct: AnyComponentStruct;
+    __params: AnyComponentParams;
+    __assignParams: (params: AnyComponentParams) => void;
+    __dynamicChildrenIds: string[];
+    __staticChildrenCache: AnyComponentModel[];
+    __proxy: AnyComponentModel;
+    __initializeModel: (params?: AnyComponentParams) => void;
+};
+
+declare type ComponentProps<TStruct extends GeneralComponentStruct> = Partial<NonNullable<TStruct["props"]>>;
+
+export declare type ComponentStruct<TStruct extends GeneralComponentStruct, TMsg extends BusMessages = BusMessages> = PartialGeneralComponentStruct<ComponentStructBase<TMsg>, TMsg> & Omit<TStruct & ComponentStructBase<TMsg>, "props" | "children" | "methods" | "events" | "messages"> & PartialGeneralComponentStruct<TStruct, TMsg> & {
+    __struct?: TStruct;
+};
+
+declare type ComponentStructBase<TMsg extends BusMessages> = GeneralComponentStruct & {
+    props?: {
+        id?: string;
+        cacheable?: boolean;
+    };
+    messages?: BusMessageHandlers<TMsg>;
+    View?: ComponentView;
+    BaseView?: ComponentView;
+    constr?: (model: ComponentModel<ComponentStructBase<TMsg>, TMsg>) => MaybePromise;
+    init?: (model: ComponentModel<ComponentStructBase<TMsg>, TMsg>) => MaybePromise;
+    deinit?: (model: ComponentModel<ComponentStructBase<TMsg>, TMsg>) => MaybePromise;
+    mount?: (model: ComponentModel<ComponentStructBase<TMsg>, TMsg>) => MaybePromise;
+    unmount?: (model: ComponentModel<ComponentStructBase<TMsg>, TMsg>) => MaybePromise;
+    draw?: (model: ComponentModel<ComponentStructBase<TMsg>, TMsg>) => MaybePromise;
+    erase?: (model: ComponentModel<ComponentStructBase<TMsg>, TMsg>) => MaybePromise;
+} & {
+    __struct?: ComponentStructBase<TMsg>;
+};
+
+declare type ComponentStructEvents<TProps> = {
+    onPropChanging?: (prop: keyof TProps | string, newValue: unknown, oldValue: unknown) => unknown;
+    onPropChange?: (prop: keyof TProps | string, value: unknown, oldValue: unknown) => void;
+} & {
+    [Evt in keyof TProps as `onChanging${Capitalize<Evt & string>}`]?: (newValue: TProps[Evt], oldValue: TProps[Evt]) => TProps[Evt];
+} & {
+    [Evt in keyof TProps as `onChange${Capitalize<Evt & string>}`]?: (value: TProps[Evt], oldValue: TProps[Evt]) => void;
+};
+
+export declare type ComponentView = (params?: ViewParams) => ReactElement;
+
+export declare function defaultMessageBus<TMsg extends BusMessages>(): MessageBus<TMsg>;
+
+export declare type DynamicChildren = Record<string, AnyComponentModel>;
+
+export declare type EmptyObject = Record<never, never>;
+
+export declare type ErrorHandler = (error: Error) => void;
+
+export declare function errorIf(condition: boolean, errorMessage?: string): void;
+
+export declare function errorIfNot(condition: boolean, errorMessage?: string): void;
+
+export declare type GeneralComponentStruct = {
+    props?: EmptyObject;
+    children?: EmptyObject;
+    methods?: EmptyObject;
+    events?: EmptyObject;
+};
+
+declare type GetChildrenModels = (childrenTypeFilter?: ModelType) => AnyComponentModel[];
+
+export declare function getFC<TStruct extends ComponentStruct<ComponentStructBase<TMsg>, TMsg>, TMsg extends BusMessages>(modelHook: (params: ComponentParams<TStruct, TMsg>) => ComponentModel<TStruct, TMsg>): (params: ComponentParams<TStruct, TMsg>) => React_2.JSX.Element;
+
+declare type GlobalSettings = {
+    traceLog: boolean;
+    hashHtmlId: boolean;
+    modelCacheMode: "no-cache" | "cache" | "auto-cache";
+    errorHandler?: ErrorHandler;
+};
+
+export declare const globalSettings: GlobalSettings;
+
+export declare function IF(props: {
+    condition: boolean;
+    children: React_2.ReactNode;
+}): React_2.JSX.Element;
+
+declare type InParam = {
+    in: unknown;
+};
+
+export declare function intersection(a: unknown[], b: unknown[]): unknown[];
+
+export declare function isArray(value: unknown): value is unknown[];
+
+export declare function isBoolean(value: unknown): value is boolean;
+
+export declare function isComponentModel(obj: unknown): boolean;
+
+export declare function isEqual(a: unknown, b: unknown): boolean;
+
+export declare function isFunction(value: unknown): value is () => unknown;
+
+export declare function isMap(value: unknown): value is Map<unknown, unknown>;
+
+export declare function isNull(value: unknown): value is null;
+
+export declare function isNumber(value: unknown): value is number;
+
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+
+export declare function isString(value: unknown): value is string;
+
+export declare function isSymbol(value: unknown): value is symbol;
+
+export declare function isUndefined(value: unknown): value is undefined;
+
+export declare type MaybePromise = void | Promise<void>;
+
+export declare type MessageBus<TMsg extends BusMessages> = {
+    readonly name?: string;
+    subscribe(subscriber: Subscriber<TMsg>): void;
+    unsubscribe(subscriber: Subscriber<TMsg>): void;
+    broadcast<Msg extends keyof TMsg>(modelId: string | RegExp | null, message: Msg, param: ParamIn<TMsg, Msg>): Promise<ParamOut<TMsg, Msg>[]>;
+    castTo<Msg extends keyof TMsg>(modelId: string, message: Msg, param: ParamIn<TMsg, Msg>): Promise<ParamOut<TMsg, Msg>>;
+    unicast<Msg extends keyof TMsg>(message: Msg, param: ParamIn<TMsg, Msg>): Promise<ParamOut<TMsg, Msg>>;
+    /**
+     * @deprecated Use the `unicast` function instead.
+     */
+    getAsync<Msg extends keyof TMsg>(message: Msg, param: ParamIn<TMsg, Msg>): Promise<ParamOut<TMsg, Msg>>;
+    /**
+     * @deprecated Use the `unicast` function instead.
+     */
+    postAsync<Msg extends keyof TMsg>(message: Msg, param: ParamIn<TMsg, Msg>): Promise<ParamOut<TMsg, Msg>>;
+};
+
+declare type MessageHandler<TMsg extends BusMessages, Msg extends keyof TMsg> = (param: ParamIn<TMsg, Msg>) => Promise<ParamOut<TMsg, Msg> extends undefined ? void : ParamOut<TMsg, Msg>>;
+
+declare type MessageHandlerNoPar<TMsg extends BusMessages, Msg extends keyof TMsg> = () => Promise<ParamOut<TMsg, Msg> extends undefined ? void : ParamOut<TMsg, Msg>>;
+
+declare type MessageID = string;
+
+declare type ModelType = "static" | "dynamic";
+
+export declare function observe<T extends object>(value: T): T;
+
+declare type OutParam = {
+    out: unknown;
+};
+
+declare type ParamIn<TMsg extends BusMessages, Msg extends keyof TMsg> = TMsg[Msg] extends InParam ? TMsg[Msg][keyof InParam] : undefined;
+
+declare type ParamOut<TMsg extends BusMessages, Msg extends keyof TMsg> = TMsg[Msg] extends OutParam ? TMsg[Msg][keyof OutParam] : void;
+
+declare type PartialGeneralComponentStruct<TStruct extends GeneralComponentStruct, TMsg extends BusMessages> = {
+    props?: Partial<StructProps<ComponentProps<TStruct>>>;
+    children?: Partial<ComponentChildren<TStruct>>;
+    methods?: Partial<ComponentMethods<TStruct>>;
+    events?: Partial<ComponentStructEvents<ComponentProps<TStruct>>> & Partial<ComponentEvents<TStruct>>;
+    messages?: Partial<ComponentMessages<TStruct, TMsg>>;
+};
+
+export declare type ReactCSS = React_2.CSSProperties;
+
+export declare type ReactElement = React_2.JSX.Element;
+
+export declare const RenderNode: (props: {
+    node: React_2.ReactNode | React_2.ComponentType;
+    render?: boolean;
+}) => React_2.JSX.Element;
+
+export declare function renderNode(node: React_2.ReactNode | React_2.ComponentType): React_2.ReactNode;
+
+export declare function sleep(ms: number): Promise<void>;
+
+declare type StructProp<T> = T | (() => T) | Bond<T>;
+
+declare type StructProps<TProps extends object> = {
+    [Prop in keyof TProps]: StructProp<TProps[Prop]>;
+};
+
+declare type Subscriber<TMsg extends BusMessages> = ComponentModel<ComponentStructBase<TMsg>, TMsg>;
+
+export declare function useComponent<TStruct extends ComponentStruct<ComponentStructBase<TMsg>, TMsg>, TMsg extends BusMessages>(struct: TStruct, params?: ComponentParams<TStruct, TMsg>): ComponentModel<TStruct, TMsg>;
+
+export declare function useExtendedComponent<TStruct extends ComponentStruct<ComponentStructBase<TMsg>, TMsg>, TMsg extends BusMessages>(struct: ComponentStruct<ComponentStructBase<TMsg>, TMsg>, extStruct: TStruct, params?: ComponentParams<TStruct, TMsg>, modelHook?: (struct: TStruct, params?: ComponentParams<TStruct, TMsg>) => ComponentModel<TStruct, TMsg>): ComponentModel<TStruct, TMsg>;
+
+export declare function useMessaging<TMsg extends BusMessages>(model: Subscriber<TMsg>): MessageBus<TMsg>;
+
+declare type ViewParams = {
+    render?: boolean;
+    children?: React_2.ReactNode;
+};
+
+export { }