ueca-react 1.0.7 → 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,119 +1,109 @@
-![logo](/docs/logo.png)
-# UECA-React
-
-## Why UECA?
-
-Building large-scale React apps can be a mess—complex code, bug-prone patterns, and endless refactoring. UECA (Unified Encapsulated Component Architecture) changes that. Born as a pet project, it simplifies React development by hiding the low-level chaos behind a clean, unified structure.
-
-Curious about easier React development? Here’s what UECA brings to the table:
-
-**Simple Learning Curve**: No React or MobX expertise needed—just plain TypeScript and JSX.
-```typescript
-const struct = { 
-  props: {text: "" },
-  View: () => <div>{model.text}</div>
-};
-```
-
-**Single Principle**: Model-View approach keeps code predictable.
-```typescript
-View: () => <button onClick={() => model.onClick?.()}>{model.text}</button>
-```
-
-**Strong Typing Everywhere**: Full TypeScript support ensures safety and clarity across all components.
-```typescript
-// 'API.getTime' is literal type
-model.time = await model.bus.getAsync("API.getTime");
-  
-// 'onChangeTemperature' is auto-event for property 'temperature'
-onChangeTemperature={() => { console.log("Temperature changed"); }}
-```
-
-**Homogeneous Structure**: Every component looks the same—easy to read, review, and test.
-```typescript
-type ButtonStruct = UEC.ComponentStruct<{
-  props: {
-    caption: string;
-    clickMode: "click" | "toggle";
-    active: boolean;
-    disabled: boolean;
-  };
-
-  events: {
-    onClick: () => void;
-  };
-
-  methods: {
-    click: () => void;
-  };
-}>;
-```
-
-**Stateful Simplicity**: State (MobX) and React are hidden, freeing you for business logic.
-```typescript
-model.value = "new text"; // Fires onChangeValue event and auto-updates UI
-```
-
-**Powerful Bindings**: Link properties effortlessly.
-```typescript
-lastNameInput: useInput({
-  label: "Last Name:",    
-  value: UEC.bindProp(() => model.lastName, "lastName"), // two-ways binding
-  disabled: () => !model.allowEditing  // one-way binding
-}),
-```
-
-**Built-in Events**: Automatic `onChange`/`onChanging` events when property changes.
-```typescript
-onChangeTemperature={() => { model.pressure = model.calcPressure(model.temperature); }}
-```
-
-**Message Bus**: Async communication between components.
-```typescript
-messages: { 
-  "API.getItemName": async (id) => await model.apiClient.get("get-item-name?id:", { id })
-},
-```
-
-**Lifecycle Hooks**: `init`, `mount`, `unmount` out of the box.
-```typescript
-init: async () => {
-  model.itemName = await model.bus.getAsync("API.getItemName", { id: model.itemId }),
-} 
-```
-
-**Large Scale**: Perfect for large-scale apps, proven in production.
-
-**Easier Project Management**: Team leads and architects breathe easier with UECA.
-Its uniform component structure and strong typing mean predictable code—no wild variations or guesswork. Onboarding is fast, reviews are straightforward, and scaling doesn’t spiral out of control. Spend less time micromanaging and more on steering the project.
-
-UECA saved a real-world project from collapse, turning chaos into a shipped product. Ready to simplify your React journey? Try it out!
-
-Questions? Reach me at [cranesoft@protonmail.com](mailto:cranesoft@protonmail.com). Happy coding!
-
-## Current Version: 1.0.7
-
-The latest stable release of `ueca-react` is version 1.0.7. This version provides a solid UECA foundation for building React applications.
-
-### Installation
-```bash
-npm install ueca-react
-```
-Dependency npm packages (react, react-dom, lodash) should be installed separately in your React project. Compatible React versions: 16.8.0–19.1.0. Ensure your react-dom version matches your react version.
-
-## Upcoming Version: 2.0
-
-Version 2.0 of `ueca-react` is in development and testing, bringing a major upgrade:
-
-- **Fresh Core**: Rewritten from scratch for rock-solid consistency.
-- **Dynamic Content**: Seamless support for functional components in JSX.
-- **Model Cache**: Models persist through unmounts, reused on remount.
-- **New Lifecycle**: `constr`, `init`, `deinit`, `mount`, `unmount`, `draw`, `erase` hooks for finer control.
-- **Async Power**: Better async handling with centralized error management.
-- **Advanced Messaging**: `broadcast`, `castTo`, and `unicast` for flexible communication.
-- **Richer Event Log**: Enhanced component model logging.
-
-Stay tuned—2.0 will turbocharge your UECA projects! Meanwhile, 1.0.7 keeps things steady.
-
-## Getting Started
-Check out the [examples](https://codesandbox.io/p/sandbox/frosty-banach-jsf84c) and [documentation](/docs/index.md) to start building with `ueca-react`. For questions or contributions, feel free to reach out at [cranesoft@protonmail.com](mailto:cranesoft@protonmail.com).
+![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 { }