@decaf-ts/ui-decorators 0.5.9 → 0.5.11

package/LICENSE.md

@@ -1,157 +1,21 @@
-# GNU LESSER GENERAL PUBLIC LICENSE
-
-Version 3, 29 June 2007
-
-Copyright (C) 2025 Tiago Venceslau
-<https:/github.com/TiagoVenceslau>
-
-Everyone is permitted to copy and distribute verbatim copies of this
-license document, but changing it is not allowed.
-
-This version of the GNU Lesser General Public License incorporates the
-terms and conditions of version 3 of the GNU General Public License,
-supplemented by the additional permissions listed below.
-
-## 0. Additional Definitions.
-
-As used herein, "this License" refers to version 3 of the GNU Lesser
-General Public License, and the "GNU GPL" refers to version 3 of the
-GNU General Public License.
-
-"The Library" refers to a covered work governed by this License, other
-than an Application or a Combined Work as defined below.
-
-An "Application" is any work that makes use of an interface provided
-by the Library, but which is not otherwise based on the Library.
-Defining a subclass of a class defined by the Library is deemed a mode
-of using an interface provided by the Library.
-
-A "Combined Work" is a work produced by combining or linking an
-Application with the Library. The particular version of the Library
-with which the Combined Work was made is also called the "Linked
-Version".
-
-The "Minimal Corresponding Source" for a Combined Work means the
-Corresponding Source for the Combined Work, excluding any source code
-for portions of the Combined Work that, considered in isolation, are
-based on the Application, and not on the Linked Version.
-
-The "Corresponding Application Code" for a Combined Work means the
-object code and/or source code for the Application, including any data
-and utility programs needed for reproducing the Combined Work from the
-Application, but excluding the System Libraries of the Combined Work.
-
-## 1. Exception to Section 3 of the GNU GPL.
-
-You may convey a covered work under sections 3 and 4 of this License
-without being bound by section 3 of the GNU GPL.
-
-## 2. Conveying Modified Versions.
-
-If you modify a copy of the Library, and, in your modifications, a
-facility refers to a function or data to be supplied by an Application
-that uses the facility (other than as an argument passed when the
-facility is invoked), then you may convey a copy of the modified
-version:
-
--   a) under this License, provided that you make a good faith effort
-    to ensure that, in the event an Application does not supply the
-    function or data, the facility still operates, and performs
-    whatever part of its purpose remains meaningful, or
--   b) under the GNU GPL, with none of the additional permissions of
-    this License applicable to that copy.
-
-## 3. Object Code Incorporating Material from Library Header Files.
-
-The object code form of an Application may incorporate material from a
-header file that is part of the Library. You may convey such object
-code under terms of your choice, provided that, if the incorporated
-material is not limited to numerical parameters, data structure
-layouts and accessors, or small macros, inline functions and templates
-(ten or fewer lines in length), you do both of the following:
-
--   a) Give prominent notice with each copy of the object code that
-    the Library is used in it and that the Library and its use are
-    covered by this License.
--   b) Accompany the object code with a copy of the GNU GPL and this
-    license document.
-
-## 4. Combined Works.
-
-You may convey a Combined Work under terms of your choice that, taken
-together, effectively do not restrict modification of the portions of
-the Library contained in the Combined Work and reverse engineering for
-debugging such modifications, if you also do each of the following:
-
--   a) Give prominent notice with each copy of the Combined Work that
-    the Library is used in it and that the Library and its use are
-    covered by this License.
--   b) Accompany the Combined Work with a copy of the GNU GPL and this
-    license document.
--   c) For a Combined Work that displays copyright notices during
-    execution, include the copyright notice for the Library among
-    these notices, as well as a reference directing the user to the
-    copies of the GNU GPL and this license document.
--   d) Do one of the following:
-    -   0) Convey the Minimal Corresponding Source under the terms of
-           this License, and the Corresponding Application Code in a form
-           suitable for, and under terms that permit, the user to
-           recombine or relink the Application with a modified version of
-           the Linked Version to produce a modified Combined Work, in the
-           manner specified by section 6 of the GNU GPL for conveying
-           Corresponding Source.
-    -   1) Use a suitable shared library mechanism for linking with
-           the Library. A suitable mechanism is one that (a) uses at run
-           time a copy of the Library already present on the user's
-           computer system, and (b) will operate properly with a modified
-           version of the Library that is interface-compatible with the
-           Linked Version.
--   e) Provide Installation Information, but only if you would
-    otherwise be required to provide such information under section 6
-    of the GNU GPL, and only to the extent that such information is
-    necessary to install and execute a modified version of the
-    Combined Work produced by recombining or relinking the Application
-    with a modified version of the Linked Version. (If you use option
-    4d0, the Installation Information must accompany the Minimal
-    Corresponding Source and Corresponding Application Code. If you
-    use option 4d1, you must provide the Installation Information in
-    the manner specified by section 6 of the GNU GPL for conveying
-    Corresponding Source.)
-
-## 5. Combined Libraries.
-
-You may place library facilities that are a work based on the Library
-side by side in a single library together with other library
-facilities that are not Applications and are not covered by this
-License, and convey such a combined library under terms of your
-choice, if you do both of the following:
-
--   a) Accompany the combined library with a copy of the same work
-    based on the Library, uncombined with any other library
-    facilities, conveyed under the terms of this License.
--   b) Give prominent notice with the combined library that part of it
-    is a work based on the Library, and explaining where to find the
-    accompanying uncombined form of the same work.
-
-## 6. Revised Versions of the GNU Lesser General Public License.
-
-The Free Software Foundation may publish revised and/or new versions
-of the GNU Lesser General Public License from time to time. Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns.
-
-Each version is given a distinguishing version number. If the Library
-as you received it specifies that a certain numbered version of the
-GNU Lesser General Public License "or any later version" applies to
-it, you have the option of following the terms and conditions either
-of that published version or of any later version published by the
-Free Software Foundation. If the Library as you received it does not
-specify a version number of the GNU Lesser General Public License, you
-may choose any version of the GNU Lesser General Public License ever
-published by the Free Software Foundation.
-
-If the Library as you received it specifies that a proxy can decide
-whether future versions of the GNU Lesser General Public License shall
-apply, that proxy's public statement of acceptance of any version is
-permanent authorization for you to choose that version for the
-Library.
+# MIT License
+
+Copyright (c) 2025 Tiago Venceslau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,8 +2,9 @@
 
 ## User Interface Decorators
 
-Introduces a declarative way to render UI forms
+A TypeScript library that provides a declarative approach to UI rendering through model decorators. It extends the functionality of `@decaf-ts/decorator-validation` by adding UI rendering capabilities to models, allowing them to be automatically rendered as UI components with proper validation and styling.
 
+The library offers a flexible rendering engine architecture that can be extended to support different UI frameworks (React, Angular, HTML5, etc.) while maintaining a consistent model-driven approach to UI development. It bridges the gap between data models and their visual representation, enabling developers to define UI behavior directly on their domain models.
 
 
 ![Licence](https://img.shields.io/github/license/decaf-ts/ui-decorators.svg?style=plastic)
@@ -31,17 +32,52 @@ Documentation available [here](https://decaf-ts.github.io/ui-decorators/)
 
 ### Description
 
-Extension of `db-decorators`, exposes a simple implementation to handle automatic model rendering:
-- decorate classes and attributes as UI elements or UI element properties;
-- provides the base objects to implement `RenderingEngine` specific to each tech (Ionic, Angular, React, HTML5, etc);
-    - automatic CRUD view rendering;
-    - automatic UI validation according to `decorator-validation`'s decorators;
-    - enables automatic custom validation (not HTML standard);
+The UI Decorators library is an extension of `@decaf-ts/decorator-validation` and `@decaf-ts/db-decorators` that provides a comprehensive framework for automatic model rendering in user interfaces. It enables a declarative approach to UI development by allowing developers to define how their data models should be rendered directly on the model classes and properties.
 
-Adds a new Decorator ```uimodel``` to add UI metadata to the model, that can be later interpreted by different rendering strategies
-Adds a new Decorator ```uiprop``` to add UI metadata to the model's properties, that can later be converted into properties for the `uimodel`
-Adds a new Decorator ```uielement``` to add UI metadata to the model's properties, that can later be converted into Graphical elements
-Adds a new Decorator ```hideOn``` to add UI metadata to the model's properties, so heir visibility can be controlled depending on the CRUD operation
+#### Core Functionality
+
+- **Model Rendering**: Extends the Model class with the ability to render itself as a UI component
+- **Flexible Rendering Engine**: Provides an abstract RenderingEngine class that can be implemented for different UI frameworks
+- **Validation Integration**: Automatically applies validation rules from `@decaf-ts/decorator-validation` to UI elements
+- **CRUD Operation Support**: Controls element visibility and behavior based on the current CRUD operation (Create, Read, Update, Delete)
+- **List Rendering**: Special support for rendering collections of models as lists with customizable item templates
+
+#### Class Decorators
+
+- **`@uimodel(tag?, props?)`**: Marks a class as a UI model and specifies how it should be rendered, including the HTML tag to use and additional properties
+- **`@renderedBy(engine)`**: Specifies which rendering engine implementation should be used for a particular model
+- **`@uilistitem(tag?, props?)`**: Defines how a model should be rendered when it appears as an item in a list
+
+#### Property Decorators
+
+- **`@uiprop(propName?, stringify?)`**: Maps a model property to a UI component property, optionally with a different name or stringified
+- **`@uielement(tag, props?, serialize?)`**: Maps a model property to a specific UI element with custom properties
+- **`@uilistprop(propName?, props?)`**: Maps a model property containing a list to a list container component
+- **`@hideOn(...operations)`**: Hides a property during specific CRUD operations
+- **`@hidden()`**: Completely hides a property in all UI operations
+
+#### Rendering Engine
+
+The abstract `RenderingEngine` class provides the foundation for implementing rendering strategies for different UI frameworks:
+
+- **Type Translation**: Converts between model types and HTML input types
+- **Validation Handling**: Applies validation rules from the model to UI elements
+- **Field Definition Generation**: Converts model metadata into UI field definitions
+- **Engine Management**: Registers and retrieves rendering engine implementations
+- **Extensibility**: Can be extended to support any UI framework or rendering strategy
+
+#### Integration with Validation
+
+The library seamlessly integrates with the validation system from `@decaf-ts/decorator-validation`, automatically applying validation rules to UI elements:
+
+- Required fields
+- Minimum and maximum values
+- Minimum and maximum length
+- Pattern matching
+- Type-specific validation (email, URL, date, password)
+- Custom validation rules
+
+This integration ensures that UI components not only display data correctly but also enforce the same validation rules defined in the model.
 
 
 ### How to Use
@@ -49,7 +85,381 @@ Adds a new Decorator ```hideOn``` to add UI metadata to the model's properties,
 - [Initial Setup](../../workdocs/tutorials/For%20Developers.md#_initial-setup_)
 - [Installation](../../workdocs/tutorials/For%20Developers.md#installation)
 
-
+## Basic Usage
+
+### Creating a UI Model
+
+The most basic usage involves decorating a model class with `@uimodel` to make it renderable:
+
+```typescript
+import { Model, attribute } from '@decaf-ts/decorator-validation';
+import { uimodel, uielement } from '@decaf-ts/ui-decorators';
+
+@uimodel()
+class UserProfile extends Model {
+  @attribute()
+  @uielement('input', { type: 'text', placeholder: 'Enter your name' })
+  name: string;
+
+  @attribute()
+  @uielement('input', { type: 'email', placeholder: 'Enter your email' })
+  email: string;
+}
+
+// Create an instance
+const user = new UserProfile();
+user.name = 'John Doe';
+user.email = 'john@example.com';
+
+// Render the model (the actual rendering depends on the registered rendering engine)
+const renderedUI = user.render();
+```
+
+### Customizing UI Model Rendering
+
+You can customize how a model is rendered by providing a tag and properties to the `@uimodel` decorator:
+
+```typescript
+import { Model, attribute } from '@decaf-ts/decorator-validation';
+import { uimodel, uielement } from '@decaf-ts/ui-decorators';
+
+@uimodel('div', { class: 'user-card', style: 'border: 1px solid #ccc; padding: 16px;' })
+class UserCard extends Model {
+  @attribute()
+  @uielement('h2', { class: 'user-name' })
+  name: string;
+
+  @attribute()
+  @uielement('p', { class: 'user-bio' })
+  bio: string;
+}
+```
+
+### Specifying a Rendering Engine
+
+You can specify which rendering engine to use for a particular model:
+
+```typescript
+import { Model, attribute } from '@decaf-ts/decorator-validation';
+import { uimodel, renderedBy, uielement } from '@decaf-ts/ui-decorators';
+
+@uimodel()
+@renderedBy('react')
+class ReactComponent extends Model {
+  @attribute()
+  @uielement('input', { type: 'text' })
+  title: string;
+}
+```
+
+### Mapping Properties to UI Elements
+
+The `@uielement` decorator maps a model property to a specific UI element:
+
+```typescript
+import { Model, attribute, required, minLength, maxLength } from '@decaf-ts/decorator-validation';
+import { uimodel, uielement } from '@decaf-ts/ui-decorators';
+
+@uimodel('form')
+class LoginForm extends Model {
+  @attribute()
+  @required()
+  @minLength(3)
+  @maxLength(50)
+  @uielement('input', { 
+    type: 'text', 
+    placeholder: 'Username', 
+    class: 'form-control' 
+  })
+  username: string;
+
+  @attribute()
+  @required()
+  @minLength(8)
+  @uielement('input', { 
+    type: 'password', 
+    placeholder: 'Password', 
+    class: 'form-control' 
+  })
+  password: string;
+
+  @attribute()
+  @uielement('button', { 
+    type: 'submit', 
+    class: 'btn btn-primary' 
+  })
+  submitButton: string = 'Login';
+}
+```
+
+### Mapping Properties to Component Properties
+
+The `@uiprop` decorator maps a model property to a UI component property:
+
+```typescript
+import { Model, attribute } from '@decaf-ts/decorator-validation';
+import { uimodel, uiprop } from '@decaf-ts/ui-decorators';
+
+@uimodel('user-profile-component')
+class UserProfile extends Model {
+  @attribute()
+  @uiprop() // Will be passed as 'fullName' to the component
+  fullName: string;
+
+  @attribute()
+  @uiprop('userEmail') // Will be passed as 'userEmail' to the component
+  email: string;
+
+  @attribute()
+  @uiprop('userData', true) // Will be passed as stringified JSON
+  userData: Record<string, any>;
+}
+```
+
+### Controlling Property Visibility
+
+You can control when properties are visible using the `@hideOn` and `@hidden` decorators:
+
+```typescript
+import { Model } from '@decaf-ts/decorator-validation';
+import { uimodel, uielement, hideOn, hidden } from '@decaf-ts/ui-decorators';
+import { OperationKeys } from '@decaf-ts/db-decorators';
+
+@uimodel()
+class User extends Model {
+  @uielement('input', { type: 'text' })
+  username: string;
+
+  @uielement('input', { type: 'password' })
+  @hideOn(OperationKeys.READ) // Hide during READ operations
+  password: string;
+
+  @uielement('input', { type: 'text' })
+  @hidden() // Completely hidden in all operations
+  internalId: string;
+}
+```
+
+### Rendering Lists of Models
+
+You can render lists of models using the `@uilistitem` and `@uilistprop` decorators:
+
+```typescript
+import { Model, list } from '@decaf-ts/decorator-validation';
+import { uimodel, uilistitem, uilistprop, uielement } from '@decaf-ts/ui-decorators';
+
+// Define a list item model
+@uimodel()
+@uilistitem('li', { class: 'todo-item' })
+class TodoItem extends Model {
+  @uielement('span', { class: 'todo-text' })
+  text: string;
+
+  @uielement('input', { type: 'checkbox' })
+  completed: boolean;
+}
+
+// Define a list container model
+@uimodel('div', { class: 'todo-app' })
+class TodoList extends Model {
+  @uielement('h1')
+  title: string = 'My Todo List';
+
+  @list(TodoItem)
+  @uilistprop('items', { class: 'todo-items-container' })
+  items: TodoItem[];
+}
+
+// Usage
+const todoList = new TodoList();
+todoList.items = [
+  new TodoItem({ text: 'Learn TypeScript', completed: true }),
+  new TodoItem({ text: 'Build a UI with decorators', completed: false })
+];
+
+const renderedList = todoList.render();
+```
+
+## Creating a Custom Rendering Engine
+
+To implement a custom rendering engine for a specific UI framework, you need to extend the `RenderingEngine` abstract class:
+
+```typescript
+import { Model } from '@decaf-ts/decorator-validation';
+import { RenderingEngine, FieldDefinition } from '@decaf-ts/ui-decorators';
+
+// Define the output type for your rendering engine
+type ReactElement = any; // Replace with actual React element type
+
+// Create a custom rendering engine for React
+class ReactRenderingEngine extends RenderingEngine<ReactElement> {
+  constructor() {
+    super('react'); // Specify the engine flavor
+  }
+
+  // Initialize the engine (required abstract method)
+  async initialize(...args: any[]): Promise<void> {
+    // Import React or perform any other initialization
+    this.initialized = true;
+  }
+
+  // Implement the render method (required abstract method)
+  render<M extends Model>(
+    model: M,
+    globalProps: Record<string, unknown> = {},
+    ...args: any[]
+  ): ReactElement {
+    // Convert the model to a field definition
+    const fieldDef = this.toFieldDefinition(model, globalProps);
+
+    // Convert the field definition to a React element
+    return this.createReactElement(fieldDef);
+  }
+
+  // Helper method to create React elements
+  private createReactElement(fieldDef: FieldDefinition<ReactElement>): ReactElement {
+    // Implementation would use React.createElement or JSX
+    // This is just a placeholder
+    return {
+      type: fieldDef.tag,
+      props: {
+        ...fieldDef.props,
+        children: fieldDef.children?.map(child => this.createReactElement(child))
+      }
+    };
+  }
+}
+
+// Register the custom rendering engine
+new ReactRenderingEngine();
+
+// Now models can specify to use this engine
+@uimodel()
+@renderedBy('react')
+class ReactComponent extends Model {
+  // ...
+}
+```
+
+## Integration with Validation
+
+The UI decorators library automatically integrates with the validation system from `@decaf-ts/decorator-validation`:
+
+```typescript
+import { Model, required, email, minLength, pattern } from '@decaf-ts/decorator-validation';
+import { uimodel, uielement } from '@decaf-ts/ui-decorators';
+
+@uimodel('form', { class: 'registration-form' })
+class RegistrationForm extends Model {
+  @required()
+  @minLength(3)
+  @uielement('input', { type: 'text', placeholder: 'Username' })
+  username: string;
+
+  @required()
+  @email()
+  @uielement('input', { type: 'email', placeholder: 'Email' })
+  email: string;
+
+  @required()
+  @minLength(8)
+  @pattern(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).*$/) // Requires lowercase, uppercase, and digit
+  @uielement('input', { type: 'password', placeholder: 'Password' })
+  password: string;
+
+  // Validation will be automatically applied to the rendered UI elements
+}
+```
+
+## Complete Example
+
+Here's a complete example showing how to use the UI decorators library to create a user registration form:
+
+```typescript
+import { Model, attribute, required, email, minLength, maxLength, pattern } from '@decaf-ts/decorator-validation';
+import { uimodel, uielement, renderedBy } from '@decaf-ts/ui-decorators';
+
+@uimodel('form', { class: 'registration-form', id: 'user-registration' })
+@renderedBy('html5') // Use the HTML5 rendering engine
+class UserRegistration extends Model {
+  @required()
+  @minLength(2)
+  @maxLength(50)
+  @uielement('input', { 
+    type: 'text', 
+    placeholder: 'First Name',
+    class: 'form-control'
+  })
+  firstName: string;
+
+  @required()
+  @minLength(2)
+  @maxLength(50)
+  @uielement('input', { 
+    type: 'text', 
+    placeholder: 'Last Name',
+    class: 'form-control'
+  })
+  lastName: string;
+
+  @required()
+  @email()
+  @uielement('input', { 
+    type: 'email', 
+    placeholder: 'Email Address',
+    class: 'form-control'
+  })
+  email: string;
+
+  @required()
+  @minLength(8)
+  @pattern(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]{8,}$/)
+  @uielement('input', { 
+    type: 'password', 
+    placeholder: 'Password (min 8 chars, include uppercase, lowercase, number, and special char)',
+    class: 'form-control'
+  })
+  password: string;
+
+  @required()
+  @uielement('select', { class: 'form-control' })
+  country: string;
+
+  @attribute()
+  @uielement('textarea', { 
+    placeholder: 'Tell us about yourself',
+    class: 'form-control',
+    rows: 4
+  })
+  bio: string;
+
+  @uielement('input', { 
+    type: 'checkbox',
+    class: 'form-check-input'
+  })
+  acceptTerms: boolean = false;
+
+  @uielement('button', { 
+    type: 'submit',
+    class: 'btn btn-primary'
+  })
+  submitButton: string = 'Register';
+}
+
+// Create an instance
+const registration = new UserRegistration();
+
+// Render the form
+const form = registration.render();
+
+// Check for validation errors
+const errors = registration.hasErrors();
+if (errors) {
+  console.error('Validation errors:', errors);
+}
+```
+
+This example demonstrates how to create a complete registration form with various input types and validation rules, all defined declaratively using decorators.
 
 
 ### Related