mlform 0.1.2 → 0.1.3

package/README.md

@@ -2,131 +2,212 @@
 
 [![CI Pipeline](https://github.com/UlloaSP/mlform/actions/workflows/ci.yml/badge.svg)](https://github.com/UlloaSP/mlform/actions/workflows/ci.yml)
 [![Release](https://github.com/UlloaSP/mlform/actions/workflows/release.yml/badge.svg)](https://github.com/UlloaSP/mlform/actions/workflows/release.yml)
+[![npm version](https://img.shields.io/npm/v/mlform.svg)](https://www.npmjs.com/package/mlform)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-Un framework para crear formularios dinámicos con capacidades de machine learning.
+Composable form generation for machine learning workflows. MLForm turns JSON schemas into responsive web components, validates user input with Zod, and connects submissions to your predictive backend.
 
-## 🚀 Características
+## Table of contents
 
-- **Formularios dinámicos**: Genera formularios basados en esquemas JSON
-- **Integración ML**: Soporte para modelos de clasificación y regresión  
-- **Web Components**: Componentes reutilizables basados en Lit
-- **TypeScript**: Totalmente tipado para mejor DX
-- **Validación**: Validación robusta con Zod
+- [Overview](#overview)
+- [Features](#features)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Schema essentials](#schema-essentials)
+- [Machine learning responses](#machine-learning-responses)
+- [Extensibility](#extensibility)
+- [Runtime utilities](#runtime-utilities)
+- [Tooling & scripts](#tooling--scripts)
+- [Documentation & resources](#documentation--resources)
+- [Contributing](#contributing)
+- [License](#license)
 
-## 📦 Instalación
+## Overview
+
+MLForm is a TypeScript-first library that renders adaptive forms as standards-based Web Components built with Lit. Provide a predictable JSON schema, plug in your ML inference endpoint, and receive validated input alongside structured model responses. The library ships with batteries included for common field types and ML output strategies, while remaining extensible for custom domains.
+
+## Features
+
+- Dynamic rendering of form layouts driven by strongly typed JSON signatures
+- Built-in integration with regression and classification endpoints via fetch
+- Prepackaged strategies for text, number, boolean, category, and date inputs
+- Subscription API (`onSubmit`) and accessors (`lastInputs`, `lastResponse`) for reactive UIs
+- Lazy-loaded Web Components that stay framework-agnostic and usable in any SPA or vanilla app
+- Zod-powered validation, JSON Schema generation, and type definitions out of the box
+
+## Installation
 
 ```bash
 npm install mlform
 ```
 
-## 🏗️ Desarrollo
+> Requirements: Node.js >= 22.14 and npm >= 9.
 
-### Requisitos previos
+The package exposes ESM builds and bundled type declarations. Consumers can tree-shake imports such as `mlform`, `mlform/extensions`, and `mlform/strategies` with modern bundlers (Vite, Webpack, Rollup, etc.).
 
-- Node.js >= 18
-- npm >= 9
+## Quick start
 
-### Configuración del entorno
+```typescript
+import { MLForm } from "mlform";
 
-```bash
-# Clonar el repositorio
-git clone https://github.com/UlloaSP/mlform.git
-cd mlform
+const mlForm = new MLForm("https://api.example.com/predict");
 
-# Instalar dependencias
-npm install
+const schema = {
+	inputs: [
+		{ type: "text", title: "Full Name", required: true },
+		{ type: "number", title: "Age", min: 0, max: 120, required: true },
+		{
+			type: "category",
+			title: "Department",
+			options: ["Engineering", "Sales", "Marketing"],
+			required: true,
+		},
+	],
+	outputs: [{ type: "classifier", title: "Access Level" }],
+};
+
+mlForm.onSubmit((inputs, response) => {
+	console.log("User inputs", inputs);
+	console.log("Prediction", response);
+});
+
+const container = document.getElementById("form-container")!;
+await mlForm.toHTMLElement(schema, container);
+```
+
+```html
+<div id="form-container"></div>
+<script type="module" src="./main.ts"></script>
+```
 
-# Ejecutar tests
-npm test
+MLForm mounts a custom `<ml-layout>` shell, injects the appropriate field components, and dispatches an `ml-submit` event internally when the user submits the form. Responses from your backend are automatically forwarded to registered listeners and mirrored in the report slot.
 
-# Verificar código
-npm run lint
+## Schema essentials
 
-# Formatear código
-npm run format
+Schemas follow the `Signature` type exported from `mlform/core` (re-exported as `Signature` in the root package). Each entry is validated with Zod before rendering.
 
-# Verificar tipos
-npm run type
+### Input field types
 
-# Construir proyecto
-npm run build
+| Type | Description | Key options |
+| --- | --- | --- |
+| `text` | Single-line text input | `minLength`, `maxLength`, `pattern`, `placeholder`, `value` |
+| `number` | Numeric input with constraints | `min`, `max`, `step`, `value` |
+| `boolean` | Checkbox or toggle | `required` |
+| `category` | Select or radio options | `options`, `multiple` |
+| `date` | Date picker | `min`, `max`, `format`, `value` |
 
-# Generar documentación
-npm run docs
+Every field shares a base structure of `title`, optional `description`, and an explicit `required` flag (defaulting to `true`).
+
+### Model output types
+
+| Type | Use case | Typical payload |
+| --- | --- | --- |
+| `classifier` | Discrete predictions | `prediction`, `confidence`, `probabilities`, `execution_time` |
+| `regressor` | Continuous predictions | `prediction`, `confidence_interval`, `std_deviation`, `execution_time` |
+
+You can combine multiple outputs within the same schema to present downstream analytics alongside user inputs.
+
+## Machine learning responses
+
+During submission MLForm issues a POST request to the backend URL configured in the constructor. The body contains the normalized user inputs and the requested model metadata. Responses are projected into the report slot and emitted to listeners.
+
+```json
+// Request payload
+{
+	"inputs": {
+		"Full Name": "Jane Doe",
+		"Age": 34,
+		"Department": "Engineering"
+	}
+}
+```
+
+```json
+// Expected response
+{
+	"outputs": [
+		{
+			"type": "classifier",
+			"prediction": "admin",
+			"confidence": 0.92,
+			"probabilities": {
+				"viewer": 0.05,
+				"editor": 0.03,
+				"admin": 0.92
+			},
+			"execution_time": 37
+		}
+	]
+}
 ```
 
-### Scripts disponibles
+Runtime helpers:
 
-- `npm run lint` - Ejecuta ESLint
-- `npm run lint:fix` - Corrige automáticamente los errores de linting
-- `npm run format` - Formatea el código con Prettier
-- `npm run format:check` - Verifica el formato del código
-- `npm run type` - Verifica tipos con TypeScript
-- `npm run test` - Ejecuta tests con Vitest
-- `npm run test:watch` - Ejecuta tests en modo watch
-- `npm run coverage` - Genera reporte de cobertura
-- `npm run build` - Construye el proyecto para producción
-- `npm run docs` - Genera documentación con TypeDoc
-- `npm run ci` - Ejecuta todo el pipeline de CI localmente
+- `mlForm.onSubmit(callback)` returns an unsubscribe function and delivers both the parsed inputs and the transformed backend response.
+- `mlForm.lastInputs` and `mlForm.lastResponse` expose the latest submission synchronously.
+- `DescriptorService` handles lazy loading and rendering of ML report components so predictions are shown without additional wiring.
 
-## 🔄 CI/CD Pipeline
+## Extensibility
 
-El proyecto incluye un pipeline completo de CI/CD con GitHub Actions:
+MLForm is built around strategy classes that map schema entries to UI components. You can add or replace strategies for bespoke controls or ML result renderers.
 
-### Pipeline de CI (`.github/workflows/ci.yml`)
+```typescript
+import { MLForm } from "mlform";
+import { FieldStrategy } from "mlform/extensions";
 
-Se ejecuta en cada push y pull request e incluye:
+class ColorPickerStrategy extends FieldStrategy {
+	constructor() {
+		super("color", ColorSchema, () => import("./color-field"));
+	}
 
-1. **🔍 Lint & Format** - Verificación de código con ESLint y Prettier
-2. **📝 Type Check** - Verificación de tipos TypeScript
-3. **🧪 Testing** - Tests unitarios en múltiples versiones de Node.js (18, 20, 22)
-4. **🏗️ Build** - Construcción del proyecto
-5. **📚 Documentation** - Generación de documentación (solo en main/docs)
-6. **🔒 Security** - Auditoría de seguridad de dependencias
+	buildControl(field) {
+		return {
+			tag: "color-field",
+			props: { value: field.value, label: field.title },
+		};
+	}
+}
 
-### Pipeline de Release (`.github/workflows/release.yml`)
+const mlForm = new MLForm("https://api.example.com/predict");
+mlForm.register(new ColorPickerStrategy());
+```
 
-Se ejecuta en tags de versión e incluye:
+Use the default strategies exported from `mlform/strategies` as references when crafting new descriptors. Updates and removals follow the same pattern via `mlForm.update()` and `mlForm.unregister()`.
 
-1. **🚀 Release** - Creación de releases en GitHub
-2. **📦 NPM Publish** - Publicación automática en NPM
+## Runtime utilities
 
-### Configuración de Quality Gates
+- `mlForm.validateSchema(signature)` returns a Zod safe-parse result, useful for testing incoming schemas before rendering.
+- `mlForm.schema()` produces a JSON Schema (draft 2020-12) for your current registry configuration, enabling schema introspection or documentation workflows.
 
-- **Cobertura de tests**: 80% mínimo
-- **Linting**: Sin errores
-- **Formato**: Código debe seguir las reglas de Prettier
-- **Tipos**: Sin errores de TypeScript
-- **Build**: Debe compilar sin errores
+## Tooling & scripts
 
-## 📊 Reportes
+The repository uses npm as the package manager and Vite for bundling.
 
-- **Cobertura de tests**: Generada con Vitest y c8
-- **Bundle size**: Visualización con rollup-plugin-visualizer en `stats/`
-- **Documentación**: Disponible en `docs/` después de ejecutar `npm run docs`
+- `npm run lint` – format-aware linting powered by Biome.
+- `npm run type` – TypeScript project checks with `tsc --noEmit`.
+- `npm run test` / `npm run coverage` – unit tests and coverage via Vitest and V8 instrumentation.
+- `npm run build` – generates the production-ready `dist/` bundle and declaration files.
+- `npm run ci` – convenience task combining lint, type checks, tests, and build.
 
-## 🤝 Contribución
+CI/CD pipelines verify linting, type safety, tests across Node 18/20/22, build integrity, documentation, and dependency audits. Releases are published to both GitHub and npm through GitHub Actions.
 
-1. Fork el proyecto
-2. Crea una rama para tu feature (`git checkout -b feature/AmazingFeature`)
-3. Commit tus cambios (`git commit -m 'Add some AmazingFeature'`)
-4. Push a la rama (`git push origin feature/AmazingFeature`)
-5. Abre un Pull Request
+## Documentation & resources
 
-### Guidelines de contribución
+- Product documentation: https://ulloasp.github.io/mlform/
+- Examples and guides: `docs/`
+- Bundle visualizations: `stats/bundle_size_treemap.html`
+- Issue tracker: https://github.com/UlloaSP/mlform/issues
 
-- Sigue las reglas de ESLint y Prettier
-- Escribe tests para nuevas funcionalidades
-- Mantén la cobertura de tests >= 80%
-- Documenta el código con JSDoc
-- Usa Conventional Commits para mensajes de commit
+## Contributing
 
-## 📝 Licencia
+We welcome issues, feature requests, and pull requests.
 
-Este proyecto está bajo la Licencia MIT. Ver el archivo `LICENSE` para más detalles.
+1. Fork the repository and create a feature branch.
+2. Run `npm install` followed by `npm run lint`, `npm run type`, and `npm run test` before committing.
+3. Add or update tests and documentation alongside code changes (target 80%+ coverage).
+4. Use Conventional Commit messages when possible.
+5. Open a pull request describing your change and expected impact.
 
-## 🔗 Enlaces
+## License
 
-- [Documentación](https://ulloasp.github.io/mlform/)
-- [Issues](https://github.com/UlloaSP/mlform/issues)
-- [NPM Package](https://www.npmjs.com/package/mlform)
+MLForm is released under the MIT License. See `LICENSE` for details.