ueca-react 1.0.7 → 2.0.2

package/docs/bindings-overview.md

@@ -1,164 +0,0 @@
-# Bindings Overview
-
-Unified Encapsulated Component Architecture (UECA) offers various binding mechanisms to manage state and interactions between components. Understanding these bindings is crucial for building efficient, maintainable, and scalable applications. This tutorial covers all types of bindings available in UECA.
-
-## Types of Bindings in UECA
-
-UECA supports three primary types of bindings:
-
-1. **Unidirectional Binding**: Simplifies state management by ensuring the target property reflects the source property.
-2. **Bidirectional Binding**: Synchronizes state between two properties, allowing changes to propagate in both directions.
-3. **Custom Binding**: Provides flexibility to transform values during the binding process.
-
-### 1. Unidirectional Binding
-
-Unidirectional binding ensures that the value of a property in the source component is reflected in the target component. It is particularly useful for simple data flows where the target property should always match the source property.
-
-#### Example
-
-```typescript
-// skip...
-
-// Component structure declaration
-type MyComponentStruct = UEC.ComponentStruct<{
-  props: {  
-      caption: string;      
-  };
-  children: {
-      someInput: InputModel;
-  }
-}
-
-// skip...
-
-// Custom react hook. Returns component model.
-function useMyComponent(params?: MyComponentParams): MyComponentModel {
-  const struct: MyComponentStruct = {
-    props: {
-      // initialization of properties
-      caption: "",      
-    },
-
-    children: {      
-      // initialization of children
-      someInput: useInput({            
-        // Unidirectional binding (read-only).
-        label: () => model.caption,            
-      }),
-
-// skip...          
-```
-
-In this example, `model.someInput.label` will always have the value of `model.caption`.
-
-### 2. Bidirectional Binding
-
-Bidirectional binding synchronizes state between two properties, allowing changes to propagate in both directions. This is useful when both components need to update each other.
-
-#### Example
-
-
-```typescript
-// skip...
-
-// Component structure declaration
-type MyComponentStruct = UEC.ComponentStruct<{
-  props: {  
-    caption: string;      
-    userName: { firstName?: string; lastName?: string };
-  };
-  children: {
-    someInput: InputModel;        
-  }
-}
-
-// skip...
-
-// Custom react hook. Returns component model.
-function useMyComponent(params?: MyComponentParams): MyComponentModel {
-  const struct: MyComponentStruct = {
-    props: {
-      // initialization of properties
-      caption: "",   
-      userName: {},   
-    },
-
-    children: {      
-      // initialization of children
-      someInput: useInput({                        
-        label: () => model.caption,    
-        // Bidirectional binding (read-write).
-        value: UEC.bindProp(() => model.userName, "firstName"),       
-      }),
-
-// skip...           
-```
-In this example, `model.userName.firstName` and `model.someInput.value` will always be in sync, reflecting changes made to either property.
-
-### 3. Custom Binding
-
-Custom binding provides the flexibility to transform values during the binding process. This is useful for cases where the displayed value and stored value need to be different or require specific formatting.
-
-#### Example
-
-In this example, we'll create a form component called `ContactForm` where the user enters their phone number. The phone number will be displayed in a formatted way (e.g., (123) 456-7890), but it will be stored in the model without formatting.
-
-```typescript
-// skip...
-
-// Component structure declaration
-type MyComponentStruct = UEC.ComponentStruct<{
-  props: {  
-    phoneNumber: string;
-  };
-  children: {
-    phoneNumberInput: InputModel;       
-  }
-}
-
-// skip...
-
-// Custom react hook. Returns component model.
-function useMyComponent(params?: MyComponentParams): MyComponentModel {
-  const struct: MyComponentStruct = {
-    props: {
-      // initialization of properties
-      phoneNumber: ""
-    },
-
-    children: {      
-      // initialization of children
-      phoneNumberInput: useMyInput({
-        label: "Phone Number",
-        // Custom binding
-        value: UEC.bind(
-          () => _formatPhoneNumber(model.phoneNumber),  // Display formatted phone number
-          (value) => (model.phoneNumber = value.replace(/\D/g, ''))  // Store only digits
-        ),        
-      }),
-
-// skip...
-
-  // Private methods
-  function _formatPhoneNumber(phoneNumber: string): string {
-    // Remove all non-numeric characters
-    const cleaned = ('' + phoneNumber).replace(/\D/g, '');
-    // Match and format phone number
-    const match = cleaned.match(/^(\d{3})(\d{3})(\d{4})$/);
-    if (match) {
-      return `(${match[1]}) ${match[2]}-${match[3]}`;
-    }
-    return phoneNumber;
-  }
-}
-
-// skip...
-```
-
-**Custom Binding for Phone Number:**
-   - **Getter Function**: `() => _formatPhoneNumber(model.phoneNumber)` ensures that the phone number is always displayed in a formatted way.
-   - **Setter Function**: `(value) => (model.phoneNumber = value.replace(/\D/g, ''))` stores the phone number with only digits, removing any non-numeric characters.
-
-### Summary
-
-Understanding and leveraging different types of bindings in UECA can significantly enhance your application's flexibility, maintainability, and overall design. By using unidirectional, bidirectional, and custom bindings appropriately, you can create robust and scalable applications with ease.

package/docs/general-code-structure.md

@@ -1,177 +0,0 @@
-# UECA General Code Structure
-
-This section will guide you through the general structure of UECA components, explaining each section with simple code examples.
-
-## Component Structure
-
-Each UECA component follows a [structured template](./code-template.md) that includes properties (`props`), events (`events`), children (`children`), methods (`methods`), and messages (`messages`). Let's break down each part of the structure.
-
-### Example Component: MyComponent
-
-```typescript
-import * as React from "react";
-import * as UEC from "ueca-react";
-
-// Component structure declaration
-type MyComponentStruct = UEC.ComponentStruct<{
-  props: {
-    title: string;
-  };
-
-  events: {
-    onAction: () => void;
-  };
-
-  children: {
-    childComponent: ChildComponentModel;
-  };
-
-  methods: {       
-    performAction: () => void;
-  };  
-}>;
-
-type MyComponentParams = UEC.ComponentParams<MyComponentStruct>;
-type MyComponentModel = UEC.ComponentModel<MyComponentStruct>;
-
-function useMyComponent(params?: MyComponentParams): MyComponentModel {
-  const struct: MyComponentStruct = {
-    props: {
-      title: "Default Title",
-    },
-
-    events: {
-      onAction: () => {
-        console.log("Action triggered");
-      },
-    },
-
-    children: {
-      childComponent: useChildComponent(),
-    },
-
-    methods: {
-      performAction: () => {
-        console.log("Action performed");
-      },
-    },
-
-    messages: {
-      "Component.Message": (payload: { data: string }) => {
-        console.log(`Message received with data: ${payload.data}`);
-      },
-    },
-
-    init: () => {
-      console.log("Component initialized");
-    },
-
-    mount: () => {
-      console.log("Component mounted");
-    },
-
-    unmount: () => {
-      console.log("Component unmounted");
-    },
-
-    View: () => (
-      <div>
-        <h1>{model.title}</h1>
-        <button onClick={() => model.performAction()}>
-          Perform Action
-        </button>
-        <model.childComponent.View />
-      </div>
-    ),
-  };
-
-  const model: MyComponentModel = UEC.useComponent(struct, params);
-  return model;
-
-  // Private methods
-}
-
-const MyComponent = UEC.getFC(useMyComponent);
-
-export { MyComponentModel, useMyComponent, MyComponent };
-```
-
-### Explanation of Each Section
-
-1. **Props**:
-   - Props are the properties of the component, serving as the inputs. They are defined in the `props` section of the `struct`.
-
-    ```typescript
-    props: {
-      title: "Default Title",
-    },
-    ```
-
-2. **Events**:
-   - Events are custom events that the component can trigger and handle. They are defined in the `events` section.
-
-    ```typescript
-    events: {
-      onAction: () => {
-        console.log("Action triggered");
-      },
-    },
-    ```
-
-3. **Children**:
-   - Children are the child components nested within this component. They are defined in the `children` section.
-
-    ```typescript
-    children: {
-      childComponent: useChildComponent(),
-    },
-    ```
-
-4. **Methods**:
-   - Methods are the functions that the component can execute. They are defined in the `methods` section.
-
-    ```typescript
-    methods: {
-      performAction: () => {
-        console.log("Action performed");
-      },
-    },
-    ```
-
-5. **Lifecycle Hooks**:
-   - **Init**: Runs once when the component is created.
-   - **Mount**: Runs when the component mounts to React DOM.
-   - **Unmount**: Runs when the component unmounts from React DOM.
-
-    ```typescript
-    init: () => {
-      console.log("Component initialized");
-    },
-
-    mount: () => {
-      console.log("Component mounted");
-    },
-
-    unmount: () => {
-      console.log("Component unmounted");
-    },
-    ```
-
-6. **View**:
-   - The `View` function defines the JSX that represents the component's UI.
-
-    ```typescript
-    View: () => (
-      <div>
-        <h1>{model.title}</h1>
-        <button onClick={() => model.performAction()}>
-          Perform Action
-        </button>
-        <model.childComponent.View />
-      </div>
-    ),
-    ```
-
-### Conclusion
-
-This template provides a comprehensive scaffold for creating UECA components. By following this structure, you ensure that your components are modular, maintainable, and adhere to the principles of UECA. Use this guide as a reference for building new components and extending the functionality of your React application.

package/docs/introduction.md

@@ -1,56 +0,0 @@
-# Introduction
-
-Welcome to the Unified Encapsulated Component Architecture (UECA) tutorial. UECA is a modern framework designed to create scalable, maintainable, and modular web applications. This introduction will cover the base features of UECA, providing you with a comprehensive understanding of its core principles and benefits.
-
-## What is UECA?
-
-UECA stands for Unified Encapsulated Component Architecture. It is a framework that emphasizes encapsulation, modularity, and maintainability in web development. UECA leverages TypeScript and JSX to create robust and type-safe components, with minimal reliance on React-specific features.
-
-## Base Features of UECA
-
-### TypeScript Integration
-
-TypeScript is the primary language used in UECA development. It provides static typing, enhancing code quality and maintainability. By using TypeScript, developers can catch errors early and enjoy a more robust development experience.
-
-### Minimal React Usage
-
-UECA uses React's custom hooks for component model instantiation, but other React features (like class components, useState, useEffect) are avoided. This minimal reliance on React simplifies the learning curve for developers new to React while leveraging the power of React's component-based architecture.
-
-### Declarative and Modular Code Style
-
-The UECA code style emphasizes a declarative and modular approach. This approach focuses on consistency, encapsulation, and readability, ensuring that components are maintainable and scalable.
-
-### Standard Code Template
-
-To maintain consistency across different components, UECA encourages using [a standard code template](code-template.md). This ensures a uniform structure across the codebase, making it easier to navigate and understand.
-
-### Comprehensive Binding System
-
-UECA provides a comprehensive binding system with three types of bindings:
-1. **Unidirectional Binding**: Reflects the value of a property without allowing modifications.
-2. **Bidirectional Binding**: Synchronizes state between two properties, allowing changes to propagate in both directions.
-3. **Custom Binding**: Provides flexibility to transform values during the binding process.
-
-### View Rules and Patterns
-
-UECA has specific rules for handling views:
-- **View-Type Methods**: Methods returning JSX should end with "View" to become observers of all observable dependencies.
-- **View-Type Properties**: Properties storing JSX should end with "View" to avoid rendering issues and potential application crashes.
-- **Rendering**: Use `UEC.renderNode(model.someView)` for methods returning `ReactNode` and `<model.someView />` for those returning `JSX.Element`.
-
-### Messaging System
-
-UECA includes a messaging system that allows components to communicate in a decoupled manner. Components can send and receive messages without direct dependencies, promoting a modular architecture.
-
-### Lifecycle Management
-
-UECA components have lifecycle methods (`init`, `mount`, `unmount`) to manage initialization, mounting, and unmounting processes. These methods ensure that resources are appropriately managed throughout the component's lifecycle.
-
-### Encapsulation
-
-Encapsulation is a core principle of UECA. Each component encapsulates its implementation details, exposing only necessary interfaces. This reduces code complexity and enhances maintainability.
-
-## Conclusion
-
-UECA is a powerful framework designed to create maintainable, scalable, and modular web applications. By leveraging TypeScript, minimizing React usage, and following a declarative and modular code style, UECA provides a robust foundation for modern web development. This tutorial will guide you through the core features of UECA, helping you build efficient and maintainable applications.
-

package/docs/message-bus.md

@@ -1,177 +0,0 @@
-# UECA Message Bus
-
-In Unified Encapsulated Component Architecture (UECA), the messaging system plays a crucial role in enabling components to communicate in a decoupled manner. This section will provide an overview of the messaging system, including the message type declaration and a simple example of messaging usage.
-
-## What is the Messaging System?
-
-The messaging system in UECA allows components to send and receive messages without direct dependencies. This promotes a modular architecture where components can interact seamlessly, enhancing maintainability and scalability. Components can post messages to the message bus and subscribe to handle specific messages, facilitating communication across different parts of the application.
-
-## Message Type Declaration
-
-To use the messaging system, you first need to declare the message types. This declaration specifies the structure of the messages, including the input parameters and the output data.
-
-### Example Message Type Declaration
-
-```typescript
-// Application Messages: "message-type": { in: <parameter-type>, out: <parameter-type> }
-// Properties "in" and "out" describe value type of input and output parameters.
-// Both properties "in" and "out" are optional
-
-type AppMessage = {
-  "Api.GetWeatherForecast": {
-    in: { zip_code: string; date: Date };
-    out: { temperature: number; rainProbability: number };
-  };
-};
-```
-
-In this example, the `AppMessage` type defines a message `Api.GetWeatherForecast` with input parameters `zip_code` and `date`, and output data `temperature` and `rainProbability`.
-
-## Using the Messaging System
-
-To use the messaging system, follow these steps:
-
-1. **Define the Message Types**: Declare the structure of the messages as shown above.
-2. **Subscribe to Messages**: Use the message bus to subscribe to specific messages in the components that need to handle them.
-3. **Post Messages**: Send messages to the bus from components that need to trigger actions in other components.
-
-### Example: WeatherForm and WeatherService Components
-
-Let's walk through a simple example where a `WeatherForm` component sends a message to request weather data, and a `WeatherService` component handles the message and retrieves the data.
-
-### WeatherForm Component
-
-The `WeatherForm` component sends a message to request weather data.
-
-```typescript
-import * as UEC from "ueca-react";
-
-type WeatherFormStruct = UEC.ComponentStruct<{
-  children: {
-    zipcodeInputModel: MyInputModel;
-    dateInputModel: MyInputModel;
-    submitButtonModel: MyButtonModel;
-    weatherDisplayModel: WeatherDisplayModel;
-  };
-}, AppMessage>;
-
-type WeatherFormParams = UEC.ComponentParams<WeatherFormStruct, AppMessage>;
-type WeatherFormModel = UEC.ComponentModel<WeatherFormStruct, AppMessage>;
-
-function useWeatherForm(params?: WeatherFormParams): WeatherFormModel {
-  const struct: WeatherFormStruct = {    
-    children: {
-      zipcodeInputModel: useMyInput({ placeholder: "Zip Code" }),
-
-      dateInputModel: useMyInput({ placeholder: "Date" }),
-
-      submitButtonModel: useMyButton({
-        caption: "Submit",
-        onClick: async () => {
-          await _handleSubmit();
-        },
-      }),
-
-      weatherDisplayModel: useWeatherDisplay(),
-    },
-
-    View: () => (
-      <div>
-        <div>
-          <label>Zip Code:</label>
-          <model.zipcodeInputModel.View />
-        </div>
-        <div>
-          <label>Date:</label>
-          <model.dateInputModel.View />
-        </div>
-        <div>
-          <model.submitButtonModel.View />
-        </div>
-        <model.weatherDisplayModel.View />
-      </div>
-    ),
-  };
-
-  const model: WeatherFormModel = UEC.useComponent(struct, params);
-  return model;
-
-  // Private methods
-  async function _handleSubmit() {
-    model.weatherDisplayModel.data = await model.bus.getAsync(
-      "Api.GetWeatherForecast",
-      {
-        zip_code: model.zipcodeInputModel.value,
-        date: new Date(model.dateInputModel.value),
-      }
-    );
-  } 
-}
-
-const WeatherForm = UEC.getFC(useWeatherForm);
-
-export { WeatherFormModel, useWeatherForm, WeatherForm };
-```
-
-### WeatherService Component
-
-The `WeatherService` component subscribes to the message and handles the data retrieval.
-
-```typescript
-import * as UEC from "ueca-react";
-
-// Service Component Structure
-type WeatherServiceStruct = UEC.ComponentStruct<{}, AppMessage>;
-
-type WeatherServiceParams = UEC.ComponentParams<WeatherServiceStruct, AppMessage>;
-type WeatherServiceModel = UEC.ComponentModel<WeatherServiceStruct, AppMessage>;
-
-function useWeatherService(params?: WeatherServiceParams): WeatherServiceModel {
-  const struct: WeatherServiceStruct = {    
-    messages: {
-      "Api.GetWeatherForecast": async ({ zip_code, date }) => {
-        const response = await fetch(`https://api.weather.com/v3/wx/forecast/daily/5day?postalKey=${zip_code}&format=json`);
-        const data = await response.json();
-
-        return {
-          temperature: data.temperature,
-          rainProbability: data.rainProbability,
-        };
-      },
-    }
-  };
-
-  const model: WeatherServiceModel = UEC.useComponent(struct, params);
-  return model;
-}
-
-const WeatherService = UEC.getFC(useWeatherService);
-
-export { WeatherServiceModel, useWeatherService, WeatherService };
-```
-
-### Integration in the App
-
-Integrate the `WeatherForm` and `WeatherService` components in the main application.
-
-```typescript
-import * as React from "react";
-import { WeatherForm } from "./WeatherForm";
-import { WeatherService } from "./WeatherService";
-
-function App() {
-  return (
-    <div>
-      <h1>UECA Messaging System Example</h1>
-      <WeatherForm />
-      <WeatherService />
-    </div>
-  );
-}
-
-export default App;
-```
-
-## Conclusion
-
-The UECA messaging system facilitates decoupled communication between components, promoting a modular and maintainable architecture. By defining message types, subscribing to messages, and posting messages, you can create a flexible communication system within your UECA application. This overview and example demonstrate the basic usage of the messaging system, enabling you to integrate it into your projects effectively.

package/docs/technology.md

@@ -1,45 +0,0 @@
-# Technology of UECA
-
-Unified Encapsulated Component Architecture (UECA) development leverages a blend of modern web technologies to create scalable, maintainable, and modular applications. Below is a summary of the key technologies and coding practices employed in UECA development:
-
-## TypeScript
-
-- **Core Language**: TypeScript is the primary language used for UECA development. It provides static typing, which enhances code quality and maintainability.
-- **General Usage**: Most of the UECA code is written in general TypeScript, focusing on type safety and modern JavaScript features.
-
-## JSX
-
-- **User Interface**: JSX is used to describe the UI in a syntax familiar to both JavaScript and HTML, making it easier to build and understand component structures.
-- **Integration with TypeScript**: Combined with TypeScript, JSX allows for type-checked components, reducing runtime errors and improving development efficiency.
-
-## React
-
-- **Minimal Usage**: The only React feature utilized in UECA is custom hooks for component model instantiation. This minimizes the reliance on React-specific code and simplifies the learning curve for developers new to React.
-- **Custom Hooks**: Custom hooks are used to instantiate and manage the lifecycle of component models, integrating React’s state and effect management seamlessly into UECA.
-
-## Coding Techniques
-- **Property Bindings**: Synchronizes state between components and their properties automatically, reducing the need for manual updates.
-- **Automatic OnChange$Property$ Events**: Automatically triggers events when a property changes, allowing components to react to updates or intercept changes for validation.
-- **Component Lifecycle Hooks**:
-Manages initialization, mounting, and unmounting of components, ensuring predictable behavior and proper resource management.
-- **Interaction via Message Bus**:
-Facilitates decoupled communication between components, promoting a modular architecture by allowing components to interact without direct dependencies.
-
-## Coding Style
-
-- **Declarative and Modular Approach**: The UECA code style emphasizes a declarative and modular approach, focusing on consistency, encapsulation, and readability to create maintainable and scalable component-based applications.
-- **Utility Classes**: While the procedural approach is preferred, utility classes can be used where appropriate, particularly for reusable functions and routines.
-
-## Standard Code Template
-
-- **Consistency**: To maintain consistency across different components, developers are encouraged to use a [standard code template](/docs/code-template.md) for creating new components. This ensures that all components have a uniform structure, making the codebase easier to navigate and understand.
-- **Structural Similarity**: Keeping the code structurally similar from component to component helps in maintaining readability and reducing the cognitive load on developers when switching between different parts of the application.
-
-## React and TypeScript
-
-- **Web Application Foundation**: A typical UECA application is a web application built using React and TypeScript. React provides the component-based architecture, while TypeScript offers strong typing and modern JavaScript features.
-- **Ban on Other React Features**: Besides custom hooks, other React features (like class components, useState, useEffect) are banned from the application code to simplify the architecture and make the codebase more approachable for developers with a TypeScript background.
-
-## Conclusion
-
-UECA development emphasizes the use of TypeScript and JSX, with minimal reliance on React-specific features. By focusing on a declarative and modular approach and maintaining structural consistency, UECA aims to create maintainable and scalable web applications that are easy to understand and develop. Developers familiar with TypeScript and JSX can quickly adapt to UECA, even without extensive experience in React.