ueca-react 1.0.7 → 2.0.0

package/docs/Arrays and Reactivity in UECA-React.md

@@ -0,0 +1,158 @@
+# Arrays and Reactivity in UECA-React
+
+In UECA-React, arrays are a fundamental part of managing collections of data, such as lists of items in a user interface. UECA-React enhances arrays with reactivity, ensuring that changes to the array or its items can automatically trigger updates in the UI. This article explains how arrays work in UECA-React, their reactivity model, and the role of the `UECA.observe()` utility in making array items observable.
+
+## Shallow Reactivity of Arrays
+
+Arrays in UECA-React are **shallowly reactive**. This means that the array itself is reactive for operations that change its structure, such as adding or removing items. For example, methods like `push`, `pop`, `splice`, and direct index assignments (e.g., `array[0] = value`) are automatically detected, and the UI updates accordingly.
+
+However, shallow reactivity only applies to the array's structure, not to the properties of the objects inside the array. If you modify a property of an object within the array (e.g., `array[0].property = newValue`), this change will **not** trigger a UI update unless the object itself is made observable.
+
+### Example of Shallow Reactivity
+
+Consider an array of tasks in a TODO list:
+
+```typescript
+const tasks = [
+  { id: 1, description: 'Task 1', done: false },
+  { id: 2, description: 'Task 2', done: true }
+];
+```
+
+- **Reactive operations**: Adding a new task with `tasks.push({ id: 3, description: 'Task 3', done: false })` or removing a task with `tasks.splice(0, 1)` will trigger a UI update.
+- **Non-reactive operations**: Changing a task's `done` status with `tasks[0].done = true` will **not** trigger a UI update because the task object is not observable.
+
+## Making Array Items Observable with `UECA.observe()`
+
+To make changes to the properties of array items reactive, you need to wrap each item with `UECA.observe()`. This utility function makes an object's properties observable, ensuring that any modifications to those properties trigger the necessary UI updates.
+
+### Usage of `UECA.observe()`
+
+When adding items to an array, wrap each item with `UECA.observe()` to make its properties reactive:
+
+```typescript
+const tasks = [
+  UECA.observe({ id: 1, description: 'Task 1', done: false }),
+  UECA.observe({ id: 2, description: 'Task 2', done: true })
+];
+```
+
+Now, both structural changes to the array and property changes to the items will trigger UI updates:
+
+- **Array-level reactivity**: `tasks.push(UECA.observe({ id: 3, description: 'Task 3', done: false }))` adds a new task and updates the UI.
+- **Item-level reactivity**: `tasks[0].done = true` changes the `done` property of the first task and triggers a UI update because the task is observable.
+
+### Why Use `UECA.observe()`?
+
+- **Efficient updates**: By making array items observable, you ensure that only the affected parts of the UI re-render when a property changes, rather than re-rendering the entire list.
+- **Simplified state management**: You can directly modify item properties without needing to create new copies of the array or use immutable update patterns.
+
+## Code Example: Reactive TODO List
+
+Below is an example of a TODO list that demonstrates how to use reactive arrays and observable items in UECA-React.
+
+### Component Structure
+
+```typescript
+type Task = {
+    taskId: number;
+    description: string;
+    done: boolean;
+}
+
+type TodoListStruct = UECA.ComponentStruct<{
+    props: {
+        newTask: string;
+        tasks: Task[];
+    };
+    methods: {
+        addTask: () => void;
+        deleteTask: (taskId: number) => void;
+        toggleTask: (taskId: number) => void;
+        taskListView: () => JSX.Element;
+    };
+}>;
+```
+
+### Implementation
+
+```typescript
+function useTodoList(params?: TodoListParams): TodoListModel {
+    const struct: TodoListStruct = {
+        props: {
+            id: useTodoList.name,
+            newTask: "",
+            tasks: []
+        },
+        methods: {
+            addTask: () => {
+                const newTaskName = model.newTask.trim();
+                if (newTaskName) {
+                    model.tasks.push(UECA.observe({
+                        description: newTaskName,
+                        done: false,
+                        taskId: Math.round(Math.random() * 1000000)
+                    }));
+                    model.newTask = "";
+                }
+            },
+            deleteTask: (taskId: number) => {
+                model.tasks = model.tasks.filter(task => task.taskId !== taskId);
+            },
+            toggleTask: (taskId: number) => {
+                const task = model.tasks.find(task => task.taskId === taskId);
+                if (task) {
+                    task.done = !task.done;  // Directly mutate the observable task
+                }
+            },
+            taskListView: () => (
+                <ul>
+                    {model.tasks.map(task => (
+                        <li key={task.taskId}>
+                            <TodoItem
+                                id={`task${task.taskId}`}
+                                task={task}
+                                onDelete={() => model.deleteTask(task.taskId)}
+                                onToggle={() => model.toggleTask(task.taskId)}
+                            />
+                        </li>
+                    ))}
+                </ul>
+            )
+        },
+        View: () => (
+            <div id={model.htmlId()}>
+                <div>
+                    <input
+                        type="text"
+                        value={model.newTask}
+                        onChange={(e) => (model.newTask = e.target.value)}
+                        placeholder="New task"
+                    />
+                    <button onClick={model.addTask}>Add</button>
+                </div>
+                <model.taskListView />
+            </div>
+        )
+    };
+    const model = UECA.useComponent(struct, params);
+    return model;
+}
+```
+
+### Explanation
+
+- **Adding a task**: When a new task is added, it is wrapped with `UECA.observe()` to make its properties (`description`, `done`) reactive.
+- **Toggling a task**: The `toggleTask` method directly mutates the `done` property of the observable task, triggering a UI update for that specific task.
+- **Deleting a task**: The `deleteTask` method filters the array, removing the task and updating the UI due to the array's shallow reactivity.
+
+## Best Practices
+
+- **Use `UECA.observe()` for item-level reactivity**: Apply it to array items when you need to track changes to their properties.
+- **Avoid unnecessary observability**: If you only need to track structural changes to the array (e.g., adding/removing items), you can skip `UECA.observe()` for the items.
+- **Performance considerations**: For large arrays or frequent updates, be mindful of the performance impact of making many items observable. Test and optimize as needed.
+- **Keep the main `View` simple**: Use methods like `taskListView` to handle complex rendering logic, keeping the main `View` clean and focused.
+
+## Conclusion
+
+In UECA-React, arrays are shallowly reactive, meaning changes to the array's structure automatically trigger UI updates. However, to make changes to the properties of array items reactive, you must wrap those items with `UECA.observe()`. This approach ensures efficient and targeted UI updates, simplifying state management and improving performance. By understanding and applying these concepts, developers can build dynamic and responsive applications with ease.

package/docs/Automatic onChange Events in UECA-React.md

@@ -0,0 +1,142 @@
+# Automatic onChange\<Prop> Events in UECA-React
+#events #reactivity #state #onchange
+
+## Description
+The automatic `onChange<Prop>` feature in UECA-React simplifies state management by generating event handlers for each property defined in a component's `props` section. These handlers, named in the format `onChange<PropertyName>` (e.g., `onChangeCaption` for a `caption` property), are triggered whenever the corresponding property in the model is modified. This feature leverages UECA’s reactive model and MobX integration to enable components to respond to state changes without requiring manual event handler definitions, enhancing code efficiency and maintainability.
+
+Key aspects of `onChange<Prop>` events:
+- **Automatic Generation**: Event handlers are created for every property in `props` without explicit declaration in component structure.
+- **Reactive**: Triggered by any change to the property, ensuring real-time updates.
+- **Type-Safe**: Fully integrated with TypeScript for robust typing and error prevention.
+
+---
+
+## API/Methods
+
+### Automatic Event Handlers
+- **onChange\<PropertyName>**  
+  An event handler automatically generated for each property in the `props` section of the component structure. It is triggered when the property’s value changes.  
+  - **Signature**: `(newValue: PropType, oldValue: PropType) => void`  
+    - `newValue`: The updated value of the property.  
+    - `oldValue`: Previous value of the property.  
+  - **Usage**: Defined in the `events` section or passed as a prop to child components to react to state changes.
+
+### Triggering Events
+- Property changes in the model (e.g., `model.caption = "new value"`) automatically invoke the corresponding `onChange<Prop>` handler if defined.
+
+---
+
+## Code Examples
+
+### Example: Handling Property Changes with onChange
+This example shows a component that uses the automatic `onChangeCaption` event to log changes to its `caption` property.
+
+```typescript
+import * as UECA from "ueca-react";
+
+type ButtonStruct = UECA.ComponentStruct<{
+    props: {
+        caption: string
+    }
+}>;
+
+type ButtonParams = UECA.ComponentParams<ButtonStruct>;
+type ButtonModel = UECA.ComponentModel<ButtonStruct>;
+
+function useButton(params?: ButtonParams): ButtonModel {
+    const struct: ButtonStruct = {
+        props: {
+            caption: "Click Me"
+        },
+        events: {
+            // Automatic OnChange event
+            onChangeCaption: (newValue, oldValue) => {
+                console.log(`Caption changed from "${oldValue}" to "${newValue}"`);
+            }
+        },
+        View: () =>
+            <div id={model.htmlId()}>
+                <button onClick={() => model.caption = "Updated!"}>
+                    {model.caption}
+                </button>
+            </div>
+    };
+    const model = UECA.useComponent(struct, params);
+    return model;
+}
+
+const Button = UECA.getFC(useButton);
+export { ButtonModel, useButton, Button };
+```
+
+- **Explanation**:  
+  - The `caption` property is defined in `props`.  
+  - The `onChangeCaption` event handler is automatically available and logs changes.  
+  - Clicking the button updates `model.caption` and triggers `onChangeCaption`.
+
+### Example: Two-Way Binding with onChange
+This example demonstrates using `onChange<Prop>` in a parent-child scenario with a form input.
+
+```typescript
+import * as UECA from "ueca-react";
+
+type FormStruct = UECA.ComponentStruct<{
+    props: {
+        userName: string
+    };
+    children: {
+        input: InputModel
+    };
+}>;
+
+type FormParams = UECA.ComponentParams<FormStruct>;
+type FormModel = UECA.ComponentModel<FormStruct>;
+
+function useForm(params?: FormParams): FormModel {
+    const struct: FormStruct = {
+        props: {
+            userName: ""
+        },
+        events: {
+            // Automatic OnChange event for "userName" property
+            onChangeUserName: (newValue, oldValue) => {
+                console.log(`User name changed from "${oldValue}" to "${newValue}"`);
+            }
+        },
+        children: {
+            input: useInput({
+                value: UECA.bind(() => model, "userName"),
+                // Automatic OnChange event for "value" property
+                onChangeValue: (newValue, oldValue) => {
+                    console.log(`Input value changed from "${oldValue}" to "${newValue}"`);
+                }
+            })
+        },
+        View: () =>
+            <div id={model.htmlId()}>
+                <model.input.View />
+            </div>
+    };
+    const model = UECA.useComponent(struct, params);
+    return model;
+}
+
+const Form = UECA.getFC(useForm);
+export { FormModel, useForm, Form };
+```
+
+- **Explanation**:  
+  - The parent’s `userName` is bound to the child’s `value` prop.  
+  - The child’s input updates the parent’s `userName`, triggering firstly child’s `onChangeValue` and then parent’s `onChangeUserName` to log the changes.
+
+---
+
+## Best Practices
+- **Use for Reactive Updates**: Leverage `onChange<Prop>` events to respond to state changes in real-time, such as logging or triggering side effects.
+- **Combine with Bindings**: Use `onChange<Prop>` with bidirectional bindings for interactive components like forms to ensure state consistency.
+- **Keep Handlers Lightweight**: Avoid heavy computations in `onChange<Prop>` handlers to maintain performance.
+
+## Notes
+- `onChange<Prop>` events are automatically declared/generated for all properties in `props`, reducing boilerplate code.
+- These events integrate seamlessly with UECA’s MobX-based reactivity system.
+- For non-property-based communication, consider the UECA Message Bus.

package/docs/Automatic onChanging Events in UECA-React.md

@@ -0,0 +1,157 @@
+# Automatic onChanging\<Prop> Events in UECA-React
+#events #reactivity #validation #state #onchanging
+
+## Description
+The `onChanging<Prop>` event in UECA-React is an automatically generated event that triggers **before** a property's value is updated in a component's state. This pre-update hook allows developers to intercept, validate, or modify the proposed change, offering fine-grained control over state transitions. Unlike the `onChange<Prop>` event, which fires after a property has been updated, `onChanging<Prop>` provides an opportunity to enforce rules or perform side effects before the state is altered.
+
+Key features:
+- **Automatic Generation**: Event handlers are created for every property in `props` without explicit declaration in component structure.
+- **Preemptive Control**: Runs before the property update, enabling validation or cancellation.
+- **Flexible**: Can return a modified value or proceed with the original value that blocks the change.
+- **Reactive Integration**: Works seamlessly with UECA-React’s reactive system and MobX.
+- **Type-Safe**: Built with TypeScript support for reliable development.
+
+This event is ideal for scenarios like input validation, data transformation, or preventing invalid state changes.
+
+---
+
+## API/Methods
+
+### Event Handler
+- **onChanging\<PropertyName>**  
+  Automatically generated for each property defined in the `props` section.  
+  - **Signature**: `(newValue: PropType, oldValue: PropType) => PropType`  
+    - `newValue`: The proposed value for the property.
+    - `oldValue`: Current value of the property.  
+    - **Return**:  
+      - A value to apply.
+      - `oldValue` to block the change.  
+  - **Usage**: Defined in the `events` section or passed as a prop to child components to react to state changes.
+
+### Triggering the Event
+- The event fires whenever a property is modified (e.g., `model.prop = value`), before the change is committed to the state.
+
+---
+
+## Code Examples
+
+### Example 1: Validating Input
+This example shows a component that ensures the `quantity` property is between 0 and 10.
+
+```typescript
+import * as UECA from "ueca-react";
+
+type CounterStruct = UECA.ComponentStruct<{
+    props: {
+        quantity: number
+    };
+}>;
+
+type CounterParams = UECA.ComponentParams<CounterStruct>;
+type CounterModel = UECA.ComponentModel<CounterStruct>;
+
+function useCounter(params?: CounterParams): CounterModel {
+    const struct: CounterStruct = {
+        props: {
+            quantity: 0
+        },
+        events: {
+            onChangingQuantity: (newValue, oldValue) => {
+                if (newValue < 0 || newValue > 10) {
+                    console.error("Quantity cannot be negative or greater than 10");
+                    return oldValue; // Prevents the update
+                }
+                return newValue;
+            },
+        },
+        View: () =>
+            <div id={model.htmlId()}>
+                <p>Quantity: {model.quantity}</p>
+                <button onClick={() => model.quantity++}>
+                    {/* Clicking triggers onChangingQuantity event */}
+                    Increment Quantity
+                </button>
+                <button onClick={() => model.quantity--}>
+                    {/* Clicking triggers onChangingQuantity event */}
+                    Decriment Quantity
+                </button>
+            </div>
+    };
+    const model = UECA.useComponent(struct, params);
+    return model;
+}
+
+const Counter = UECA.getFC(useCounter);
+export { CounterModel, useCounter, Counter };
+```
+
+- **Explanation**:  
+  - The `onChangingQuantity` handler checks if the new value is between 0 and 10.  
+  - If it is not, the update is blocked by returning the `oldValue`.  
+  - Otherwise, the `newValue` is returned and update the property.
+
+### Example 2: Transforming Input
+This example transforms a `text` property to uppercase before applying it.
+
+```typescript
+import * as UECA from "ueca-react";
+
+type TextInputStruct = UECA.ComponentStruct<{
+    props: {
+        text: string
+    };
+}>;
+
+type TextInputParams = UECA.ComponentParams<TextInputStruct>;
+type TextInputModel = UECA.ComponentModel<TextInputStruct>;
+
+function useTextInput(params?: TextInputParams): TextInputModel {
+    const struct: TextInputStruct = {
+        props: {
+            text: ""
+        },
+        events: {
+            onChangingText: (newValue) => {
+                return newValue.toUpperCase(); // Transform to uppercase
+            }
+        },
+        View: () =>
+            <div id={model.htmlId()}>
+                {/* Input value update triggers onChangingText event */}
+                <input
+                    type="text"
+                    value={model.text}
+                    onChange={(e) => model.text = e.target.value}
+                />
+            </div>
+    };
+    const model = UECA.useComponent(struct, params);
+    return model;
+}
+
+const TextInput = UECA.getFC(useTextInput);
+export { TextInputModel, useTextInput, TextInput };
+```
+
+- **Explanation**:  
+  - The `onChangingText` handler converts the input to uppercase.  
+  - The transformed value is then set as the new `text` property.
+
+---
+
+## Best Practices
+- **Validation**: Use `onChanging<Prop>` to enforce constraints (e.g., positive numbers, valid formats).  
+- **Lightweight Logic**: Keep handlers fast and simple to avoid performance issues.  
+- **Pair with onChange**: Combine with `onChange<Prop>` for pre- and post-update logic.  
+
+---
+
+## Comparison to Traditional React
+In traditional React, you might handle validation in an `onChange` handler after the state updates, requiring additional logic to revert invalid changes. With UECA-React’s `onChanging<Prop>`, you can prevent invalid updates proactively, reducing complexity and improving performance.
+
+---
+
+## Notes
+- Handlers are optional; if not defined, property updates proceed as normal.  
+- The event integrates with UECA’s reactivity, ensuring efficient state management.  
+- Returning `oldValue` explicitly cancels the update.

package/docs/Automatic onPropChange and onPropChanging Events in UECA-React.md

@@ -0,0 +1,112 @@
+# Automatic onPropChange and onPropChanging Events in UECA-React
+#events #reactivity #state #onpropchange #onpropchanging
+
+## Description
+In the UECA-React framework, `onPropChange` and `onPropChanging` are embedded events that automatically fire whenever a property in a component's model changes. Unlike the property-specific `onChange<Prop>` and `onChanging<Prop>` events, these events are designed to handle changes across **all properties** using a single handler. They include an additional `prop` parameter, which specifies the name of the property being modified, enabling centralized logic for multiple properties.
+
+Key features:
+- **Automatic Generation**: Event handlers are created without explicit declaration in component structure.
+- **Automatic Execution**: Triggered for every property update in the model.
+- **Centralized Management**: One event handler can manage all property changes.
+- **Pre- and Post-Change Hooks**: `onPropChanging` runs before the update, while `onPropChange` runs after.
+- **Flexible Use Cases**: Ideal for validation, logging, or uniform transformations.
+
+These events simplify state management in complex components by reducing the need for multiple property-specific handlers.
+
+---
+
+## API/Methods
+
+### Event Handlers
+- **onPropChanging**  
+  Fired **before** a property is updated.  
+  - **Signature**: `(prop: string, newValue: unknown, oldValue: unknown) => unknown`  
+    - `prop`: The name of the changing property.  
+    - `newValue`: The proposed new value.  
+    - `oldValue`: The current value before the change.  
+    - **Return**:  
+      - A value to apply.
+      - `oldValue` to block the change.      
+  - **Purpose**: Validate or transform values before they are set.
+
+- **onPropChange**  
+  Fired **after** a property is updated.  
+  - **Signature**: `(prop: string, newValue: unknown, oldValue: unknown) => void`  
+    - `prop`: The name of the changed property.  
+    - `newValue`: The value after the update.  
+    - `oldValue`: The value before the update.  
+  - **Purpose**: React to changes (e.g., logging or side effects).
+
+### Usage
+- Define these events in the `events` section of a UECA-React component structure.
+- They are triggered automatically by property assignments (e.g., `model.firstName = "John"`).
+
+---
+
+## Code Example
+Here’s an example demonstrating how to use `onPropChanging` for validation and `onPropChange` for logging:
+
+```typescript
+import * as UECA from "ueca-react";
+
+type DemoStruct = UECA.ComponentStruct<{
+    props: {
+        age: number;
+        username: string
+    };
+}>;
+
+type DemoParams = UECA.ComponentParams<DemoStruct>;
+type DemoModel = UECA.ComponentModel<DemoStruct>;
+
+function useDemo(params?: DemoParams): DemoModel {
+    const struct: DemoStruct = {
+        props: {
+            id: useDemo.name,
+            age: 25,
+            username: "user"
+        },
+        events: {
+            onPropChanging: (prop, newValue, oldValue) => {
+                console.log(`Attempting to change ${prop} from ${oldValue} to ${newValue}`);
+                if (prop === "age" && typeof newValue === "number" && newValue < 0) {
+                    return oldValue; // Prevent negative age
+                }
+                return newValue;
+            },
+            onPropChange: (prop, newValue, oldValue) => {
+                console.log(`${prop} updated from ${oldValue} to ${newValue}`);
+            },
+        },        
+        View: () => (
+            <div id={model.htmlId()}>
+                <p>Age: {model.age}</p>
+                <p>Username: {model.username}</p>
+                <button onClick={() => model.age = model.age - 10}>Decrease Age</button>
+                <button onClick={() => model.username = "newUser"}>Change Username</button>
+            </div>
+        ),
+    };
+    const model = UECA.useComponent(struct, params);
+    return model;
+}
+
+const Demo = UECA.getFC(useDemo);
+export { DemoModel, useDemo, Demo };
+```
+
+- **Explanation**:  
+  - `onPropChanging` checks if `age` is becoming negative and blocks it by returning `oldValue`.  
+  - `onPropChange` logs every successful change for any property.  
+  - One handler manages both `age` and `username` updates.
+
+---
+
+## Benefits
+- **Reduced Code Duplication**: No need for separate handlers per property.
+- **Dynamic Handling**: The `prop` parameter allows conditional logic based on property names.
+- **Control**: Modify or block changes with `onPropChanging`.
+
+## Notes
+- These events complement, rather than replace, `onChange<Prop>` and `onChanging<Prop>`. Use the latter for property-specific logic.
+- Ensure handlers are lightweight to maintain performance, as they execute for every property change.