PardusLabs.NuFlexiArch 1.0.9.4

NuFlexiArch + JSVaporizer

NuFlexiArch + JSVapor is an experimental, lightweight framework for building interactive web applications using C# and WebAssembly, without relying on higher-level abstractions like Blazor. It provides:

1. A component model (NuFlexiArch) to define and manage UI components, their data, and metadata.
2. A renderer and DOM interop layer (JSVapor) to generate HTML, manipulate the DOM, and manage events directly through [JSImport] and [JSExport].
3. A transformer system for converting DTOs (data transfer objects) to JSON or views, supporting a registry of transformers.

The goal is to give developers fine-grained control over the DOM while avoiding large amounts of “spaghetti JavaScript” by writing most application logic in C#.

Table of Contents

• Features
• Project Structure
• Getting Started
• How It Works
• Roadmap
• Contributing
• License

Features

• C#-First Approach: Consolidate your UI logic, event handling, and rendering in C#.
• Component Architecture: Build components that inherit from an abstract AComponent and manage their own state (CompDataDto) and metadata.
• Custom Rendering: Render HTML through IComponentRenderer implementations that generate DOM elements on the fly.
• Fine-Grained DOM Control: Use [JSImport] calls for direct DOM manipulation with minimal overhead or abstraction.
• Event Handling: Attach C# event handlers to DOM events via an event pool, eliminating the need for raw JavaScript event listeners.
• DTO to JSON: Serialize and deserialize component state with strongly typed data-transfer objects using System.Text.Json source generation.
• Registry & Transformers: Dynamically switch between transformers to convert JSON strings into component DTOs (or vice versa).

Project Structure

This framework is split across three main namespaces (and corresponding files/folders):

1. NuFlexiArch

   • Defines the core abstractions for components (AComponent, IComponentRenderer, CompDataDto, etc.)
   • Handles serialization/deserialization (CompMetadata, CompInstanceDto, JSON contexts).

2. JSVNuFlexiArch

   • Contains concrete WASM-focused components (e.g., JSVSlider, JSVTextDisplay) that build upon NuFlexiArch.
   • Uses the JSVapor API to create DOM elements, attach events, etc.

3. JSVapor (or JSVaporizer)

   • The low-level DOM interop layer for .NET WASM.
   • Provides classes like Document, Element, Window and direct [JSImport] references to JavaScript.
   • Manages event listener pools and function pools to coordinate DOM events and callback invocation in C#.

Getting Started

1. Prerequisites

   • .NET 7 (or higher) SDK
   • A browser environment that supports WebAssembly and the new System.Runtime.InteropServices.JavaScript features.

2. Cloning the Repository

   git clone https://github.com/PardusLabs/JSVaporizer-NuFlexiArch.git
   cd NuFlexiArch-JSVapor

3. Building

   • Open the solution (or project) in Visual Studio / VS Code / JetBrains Rider.
   • Build the project. This should produce a WASM application that you can serve or run.

4. Running

   • Depending on your setup, you might have a dotnet run project or a static host for the generated WASM.

   • In many .NET WASM templates, you’ll do something like:

     dotnet run --project MyWasmProject

   • Then navigate to the displayed local URL (e.g., https://localhost:5001).

5. Creating a Custom Component

   • Inherit from AComponent (or a specialized base like ASlider).
   • Define your own DTO class (e.g. public class MyCompDataDto : CompDataDto { ... }).
   • Provide an implementation for UpdateState() and GetState().
   • Optionally override Initialize() to attach event listeners or do post-render actions.
   • Create a matching renderer implementing IComponentRenderer (or extend JSVComponentRenderer).

How It Works

1. Define a Component

   • For example, JSVSlider inherits from ASlider. It keeps track of _value, _labelValue, etc.

2. Render to the Browser

   • A JSVSliderRenderer creates the HTML markup for your slider.
   • You call JSVapor.Document.CreateElement, set properties, add attributes, etc.
   • The markup is placed in the DOM by calling AppendChild or setting innerHTML.

3. Attach Event Handlers

   • In Initialize(), a slider can register a "change" listener to update the C# _value.
   • This uses JSVapor.Element.AddEventListener plus the event pool WasmJSVEventHandlerPool.

4. Update State

   • When an event triggers, the component updates its internal data.
   • Any secondary UI (e.g., a text display showing the slider value) can be synced as well.

5. Serialize / Deserialize

   • If needed, the component’s CompDataDto (e.g. SliderDataDto) can be serialized to JSON.
   • This enables storing/restoring UI states or sending state to other services.

Roadmap

1. Additional Components

   • Buttons, dropdowns, text inputs, checkboxes, etc.

2. Lifecycle Hooks

   • Provide a more robust lifecycle (e.g., OnRender, OnAfterRender, OnDispose) for better resource management.

3. Routing / Navigation

   • Potentially integrate with a lightweight routing system.

4. Improved Error Handling & Logging

   • More graceful handling of DOM operations or events that fail.

5. Tooling / CLI

   • Possibly a CLI or templates for easier scaffolding of new components.

Contributing

We welcome contributions, whether it’s fixing bugs, adding features, or enhancing documentation!

1. Fork & Clone the repo.
2. Create a Branch for your feature or fix.
3. Commit & Push your changes.
4. Create a Pull Request against the main branch.

Please follow any existing code style guidelines and ensure all new code is well-documented.

Enjoy building UI in .NET with direct DOM control! Let us know how you use NuFlexiArch + JSVapor in your own projects.