mlform 0.1.2 → 0.1.4

package/README.md

@@ -2,131 +2,284 @@
 
 [![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.
+Schema-driven forms for machine learning applications.
 
-## 🚀 Características
+MLForm gives you a predictable UI layer between users and model backends. You describe inputs and reports with a schema, MLForm renders accessible Web Components, validates values, submits structured payloads, and displays model results in the same host container.
 
-- **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
+Version `0.1.4` is the current release in this repository.
 
-## 📦 Instalación
+## Why MLForm
 
-```bash
-npm install mlform
-```
+Most ML product forms drift over time:
 
-## 🏗️ Desarrollo
+- the frontend shape stops matching the backend contract
+- validation rules end up duplicated across components
+- model outputs are rendered ad hoc in each screen
+- design and accessibility regress when teams move fast
 
-### Requisitos previos
+MLForm solves that by centering everything on an explicit schema and a transport layer.
 
-- Node.js >= 18
-- npm >= 9
+Use it for:
 
-### Configuración del entorno
+- prediction forms
+- scoring and approval tools
+- forecasting dashboards
+- internal review consoles
+- embedded model workflows inside larger apps
 
-```bash
-# Clonar el repositorio
-git clone https://github.com/UlloaSP/mlform.git
-cd mlform
+## Install
 
-# Instalar dependencias
-npm install
+For application usage:
 
-# Ejecutar tests
-npm test
+```bash
+npm install mlform
+```
 
-# Verificar código
-npm run lint
+Import from the root package unless you specifically need a lower-level surface:
 
-# Formatear código
-npm run format
+```ts
+import { createJsonTransport, mountForm } from "mlform";
+```
 
-# Verificar tipos
-npm run type
+## Quick Start
 
-# Construir proyecto
-npm run build
+Create a host element:
 
-# Generar documentación
-npm run docs
+```html
+<div id="prediction-form"></div>
 ```
 
-### Scripts disponibles
+Mount a form:
+
+```ts
+import { createJsonTransport, mountForm } from "mlform";
+
+const container = document.querySelector("#prediction-form");
+
+if (!container) {
+  throw new Error("Missing #prediction-form container.");
+}
+
+const mounted = mountForm(container as HTMLElement, {
+  transport: createJsonTransport({ endpoint: "/api/predict" }),
+  schema: {
+    fields: [
+      {
+        id: "prompt",
+        kind: "text",
+        label: "Prompt",
+        required: true,
+        minLength: 3,
+      },
+      {
+        id: "threshold",
+        kind: "number",
+        label: "Confidence threshold",
+        min: 0,
+        max: 1,
+        step: 0.05,
+        defaultValue: 0.75,
+      },
+    ],
+    reports: [
+      {
+        id: "prediction",
+        kind: "classifier",
+        label: "Prediction",
+      },
+    ],
+  },
+  labels: {
+    submit: "Run prediction",
+    submitting: "Running...",
+  },
+  layout: "split",
+  designSystem: {
+    mode: "auto",
+    theme: "cobalt",
+    recipe: "soft",
+  },
+});
+
+window.addEventListener("beforeunload", () => mounted.unmount());
+```
 
-- `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
+The default JSON transport sends:
 
-## 🔄 CI/CD Pipeline
+```json
+{
+  "inputs": {
+    "prompt": "Example text",
+    "threshold": 0.75
+  }
+}
+```
 
-El proyecto incluye un pipeline completo de CI/CD con GitHub Actions:
+Return reports keyed by report id:
+
+```json
+{
+  "reports": {
+    "prediction": {
+      "label": "Approved",
+      "confidence": 0.91,
+      "probabilities": {
+        "Approved": 0.91,
+        "Rejected": 0.09
+      }
+    }
+  },
+  "meta": {
+    "model": "credit-risk-v2"
+  }
+}
+```
 
-### Pipeline de CI (`.github/workflows/ci.yml`)
+## What You Get
+
+- Schema-driven fields, reports, conditions, defaults, and serialization
+- Accessible Web Components for form inputs, submit actions, and result rendering
+- Built-in JSON transport plus composable transport middleware
+- Headless engine APIs for custom orchestration and registries
+- Runtime design system with themes, recipes, density, motion, and token overrides
+- Extension points for custom field, report, and explanation kinds
+
+Built-in fields:
+
+- `text`
+- `number`
+- `boolean`
+- `category`
+- `date`
+- `time-series`
+
+Built-in reports:
+
+- `classifier`
+- `regressor`
+
+Built-in themes:
+
+- `neutral`
+- `cobalt`
+- `graphite`
+- `sage`
+- `sunset`
+
+Built-in recipes:
+
+- `default`
+- `minimal`
+- `soft`
+- `contrast`
+
+## Package Surfaces
+
+| Surface                | Use it for                                                                               |
+| ---------------------- | ---------------------------------------------------------------------------------------- |
+| `mlform`               | Application-first API for mounting forms with sensible defaults.                         |
+| `mlform/kit`           | Explicit kit entrypoint with mount, transport, labels, and lifecycle utilities.          |
+| `mlform/engine`        | Headless state, validation, registries, hooks, conditions, and submission orchestration. |
+| `mlform/primitives`    | Web Component renderers and custom renderer registries.                                  |
+| `mlform/design-system` | Themes, recipes, tokens, mode resolution, and host integration.                          |
+| `mlform/transport`     | Transport composition, middleware, resilience policies, and orchestration helpers.       |
+
+## Custom Domain Kinds
+
+When built-in kinds are not enough, define your own field and report kinds without rewriting the normal rendering path.
+
+```ts
+import { createBuiltinRegistry, defineFieldKind } from "mlform/engine";
+import { z } from "zod";
+
+const registry = createBuiltinRegistry();
+
+registry.registerField(
+  defineFieldKind({
+    kind: "score",
+    schema: z.object({
+      kind: z.literal("score"),
+      id: z.string().optional(),
+      label: z.string(),
+      min: z.number().default(0),
+      max: z.number().default(100),
+    }),
+    value: {
+      default: () => 0,
+      normalize: (value) => Number(value ?? 0),
+      serialize: (value) => value,
+    },
+    validate: ({ value, config }) =>
+      value < config.min || value > config.max ? ["Score out of range."] : [],
+    render: {
+      widget: "number",
+      hints: ({ config }) => ({
+        min: config.min,
+        max: config.max,
+        unit: "%",
+      }),
+    },
+  }),
+);
+```
 
-Se ejecuta en cada push y pull request e incluye:
+Stay at the declarative `define*Kind` layer unless you truly need fully custom rendering or low-level primitive behavior.
 
-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
+## Typical Flow
 
-### Pipeline de Release (`.github/workflows/release.yml`)
+1. Define the schema with `fields` and `reports`.
+2. Mount the form with `mountForm`.
+3. Point the transport at your model endpoint or custom backend adapter.
+4. Return normalized reports from the backend.
+5. Customize theme, recipe, labels, or registries only where your product needs it.
 
-Se ejecuta en tags de versión e incluye:
+## Documentation
 
-1. **🚀 Release** - Creación de releases en GitHub
-2. **📦 NPM Publish** - Publicación automática en NPM
+- Docs home: https://ulloasp.github.io/mlform/
+- Quick start: https://ulloasp.github.io/mlform/getting-started/quick-start/
+- Installation: https://ulloasp.github.io/mlform/getting-started/installation/
+- Backend contract: https://ulloasp.github.io/mlform/guides/backend-contract/
+- Transport guide: https://ulloasp.github.io/mlform/kit/transport/
+- Design system: https://ulloasp.github.io/mlform/design-system/overview/
+- API reference: https://ulloasp.github.io/mlform/reference/kit/
+- Migration guide: https://ulloasp.github.io/mlform/migration/from-legacy-mlform/
+- Versioning notes: https://ulloasp.github.io/mlform/support/versioning/
 
-### Configuración de Quality Gates
+## Development
 
-- **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
+This repository uses Vite+. Do not use `npm`, `pnpm`, or `yarn` directly for workspace tasks in this repo.
 
-## 📊 Reportes
+Run the main package checks:
 
-- **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`
+```bash
+vp install
+vp check
+vp test
+vp build
+```
 
-## 🤝 Contribución
+Docs live in `docs/`:
 
-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
+```bash
+cd docs
+vp install
+vp run typecheck
+vp run build
+vp run dev
+```
 
-### Guidelines de contribución
+The main package targets Node.js `>=24.9.0`.
 
-- 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
+## Release Notes
 
-## 📝 Licencia
+For `0.1.4`, use the repository release entry and the published docs as the source of truth:
 
-Este proyecto está bajo la Licencia MIT. Ver el archivo `LICENSE` para más detalles.
+- GitHub releases: https://github.com/UlloaSP/mlform/releases
+- npm package: https://www.npmjs.com/package/mlform
 
-## 🔗 Enlaces
+## License
 
-- [Documentación](https://ulloasp.github.io/mlform/)
-- [Issues](https://github.com/UlloaSP/mlform/issues)
-- [NPM Package](https://www.npmjs.com/package/mlform)
+MIT