|
|
|
@@ -0,0 +1,138 @@
|
|
|
|
|
# Herramientas interactivas
|
|
|
|
|
|
|
|
|
|
Estado: primera versión funcional. Este documento conserva el contexto necesario para extender `DsSortableList` y `DsLogicTree` sin cambiar accidentalmente sus contratos públicos.
|
|
|
|
|
|
|
|
|
|
## Principios compartidos
|
|
|
|
|
|
|
|
|
|
- Los modelos son serializables y no contienen referencias DOM ni estado interno de Vue.
|
|
|
|
|
- Cada elemento o nodo necesita un `id` estable y único.
|
|
|
|
|
- Las actualizaciones reemplazan arreglos y nodos en lugar de mutar los objetos recibidos.
|
|
|
|
|
- La interacción con puntero siempre debe tener una alternativa de teclado.
|
|
|
|
|
- La lógica de negocio, persistencia y traducción a consultas pertenece a la aplicación consumidora o a adaptadores independientes.
|
|
|
|
|
- Cualquier ampliación debe actualizar tipos, API pública, pruebas, playground y documentación.
|
|
|
|
|
|
|
|
|
|
## `DsSortableList`
|
|
|
|
|
|
|
|
|
|
### Contrato actual
|
|
|
|
|
|
|
|
|
|
Recibe `v-model<DsSortableItem[]>`. Cada elemento contiene:
|
|
|
|
|
|
|
|
|
|
```ts
|
|
|
|
|
interface DsSortableItem {
|
|
|
|
|
id: string;
|
|
|
|
|
label: string;
|
|
|
|
|
description?: string;
|
|
|
|
|
disabled?: boolean;
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
El usuario puede arrastrar un elemento o utilizar los botones subir/bajar. Cada cambio reemplaza el arreglo y emite:
|
|
|
|
|
|
|
|
|
|
```ts
|
|
|
|
|
interface DsSortableChange {
|
|
|
|
|
item: DsSortableItem;
|
|
|
|
|
from: number;
|
|
|
|
|
to: number;
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
El slot predeterminado puede personalizar la representación, pero `id` y `label` continúan formando parte del contrato porque se utilizan para identidad y nombres accesibles.
|
|
|
|
|
|
|
|
|
|
### Decisiones
|
|
|
|
|
|
|
|
|
|
- Se usa drag-and-drop nativo del navegador para mantener pequeña la primera versión y evitar una dependencia runtime.
|
|
|
|
|
- Los botones subir/bajar son la alternativa accesible y también permiten operar la lista en pantallas táctiles.
|
|
|
|
|
- La nueva posición se anuncia mediante una región `status`.
|
|
|
|
|
- Un elemento `disabled` no puede iniciar un movimiento.
|
|
|
|
|
|
|
|
|
|
### Limitaciones conocidas
|
|
|
|
|
|
|
|
|
|
- Solo reordena elementos dentro de una misma lista.
|
|
|
|
|
- No tiene gesto táctil de arrastre; en móvil se usan los botones.
|
|
|
|
|
- No ofrece clonación, selección múltiple, grupos ni zonas de descarte.
|
|
|
|
|
- El destino corresponde al elemento sobre el que se suelta; todavía no existe un indicador entre filas.
|
|
|
|
|
- No administra persistencia ni historial para deshacer/rehacer.
|
|
|
|
|
|
|
|
|
|
### Próximas extensiones
|
|
|
|
|
|
|
|
|
|
1. Mejorar el indicador de inserción antes/después de una fila.
|
|
|
|
|
2. Evaluar Pointer Events para arrastre táctil sin eliminar la alternativa por botones.
|
|
|
|
|
3. Diseñar drag-and-drop entre listas. Antes de implementarlo hay que definir `sourceListId`, `targetListId`, copia frente a movimiento y el evento público resultante.
|
|
|
|
|
4. Añadir soporte opcional para deshacer/rehacer como composable independiente.
|
|
|
|
|
5. Incorporar pruebas visuales y de interacción en navegadores reales.
|
|
|
|
|
|
|
|
|
|
## `DsLogicTree`
|
|
|
|
|
|
|
|
|
|
### Contrato actual
|
|
|
|
|
|
|
|
|
|
Recibe `v-model<DsLogicGroup>`. El árbol utiliza una unión discriminada:
|
|
|
|
|
|
|
|
|
|
```ts
|
|
|
|
|
type DsLogicNode = DsLogicCondition | DsLogicGroup;
|
|
|
|
|
|
|
|
|
|
interface DsLogicGroup {
|
|
|
|
|
id: string;
|
|
|
|
|
type: "group";
|
|
|
|
|
operator: "and" | "or";
|
|
|
|
|
children: DsLogicNode[];
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
interface DsLogicCondition {
|
|
|
|
|
id: string;
|
|
|
|
|
type: "condition";
|
|
|
|
|
field: string;
|
|
|
|
|
comparison: string;
|
|
|
|
|
value: string;
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
`fields` y `comparisons` usan opciones `{ label, value, disabled? }`. La prop `labels` permite adaptar todos los textos del editor y `readonly` conserva la estructura sin permitir cambios. Cada edición actualiza el `v-model` y emite `change` con el árbol completo.
|
|
|
|
|
|
|
|
|
|
El render recursivo vive en `DsLogicTreeNode.vue`, que es una implementación interna y no forma parte de la API pública.
|
|
|
|
|
|
|
|
|
|
### Decisiones
|
|
|
|
|
|
|
|
|
|
- `AND` y `OR` se almacenan como `and` y `or`; los textos visibles son configurables.
|
|
|
|
|
- Las condiciones usan cadenas para que la primera versión sea neutral respecto al dominio.
|
|
|
|
|
- Los nodos nuevos reciben UUID y los nodos proporcionados por el consumidor deben conservar IDs estables.
|
|
|
|
|
- El árbol solamente describe reglas. No evalúa condiciones ni genera SQL, JSON Logic u otra sintaxis.
|
|
|
|
|
- Los controles nativos mantienen nombres accesibles y el anidamiento se representa con listas y grupos.
|
|
|
|
|
|
|
|
|
|
### Limitaciones conocidas
|
|
|
|
|
|
|
|
|
|
- Todos los valores se editan como texto, sin tipos `number`, `boolean`, fecha o selección múltiple.
|
|
|
|
|
- No existe validación de campos vacíos, operadores incompatibles o grupos sin condiciones.
|
|
|
|
|
- Los nodos no pueden reordenarse ni moverse entre grupos.
|
|
|
|
|
- No hay operadores unarios como `is-empty` ni condiciones que omitan `value`.
|
|
|
|
|
- No se muestran resúmenes en lenguaje natural.
|
|
|
|
|
- No se incluye un evaluador ni adaptadores para backends.
|
|
|
|
|
|
|
|
|
|
### Próximas extensiones
|
|
|
|
|
|
|
|
|
|
1. Añadir validación sin cambiar el modelo serializable; los errores deben asociarse al control correspondiente.
|
|
|
|
|
2. Diseñar definiciones de campo tipadas con un `valueType` y opciones de valor. Hay que conservar compatibilidad con el esquema actual o introducir el cambio en una versión mayor.
|
|
|
|
|
3. Permitir comparadores que no requieran valor y editores personalizados mediante slots.
|
|
|
|
|
4. Reordenar condiciones y mover nodos entre grupos reutilizando un contrato de drag-and-drop estable.
|
|
|
|
|
5. Crear adaptadores separados para evaluar el árbol o convertirlo a formatos como JSON Logic. Estos adaptadores no deben acoplar el componente visual a un backend.
|
|
|
|
|
6. Añadir colapsado de grupos, resumen legible y deshacer/rehacer cuando el árbol crezca.
|
|
|
|
|
|
|
|
|
|
## Checklist para futuras sesiones
|
|
|
|
|
|
|
|
|
|
Antes de modificar estas herramientas:
|
|
|
|
|
|
|
|
|
|
1. Revisa este documento, `src/types.ts` y las pruebas de `tests/data-tools.test.ts`.
|
|
|
|
|
2. Decide si el cambio es compatible con los modelos actuales y documenta cualquier migración.
|
|
|
|
|
3. Conserva una alternativa completa al arrastre para teclado y tecnologías asistivas.
|
|
|
|
|
4. Añade el caso nuevo al playground en `?section=tools`.
|
|
|
|
|
5. Actualiza `docs/components.md` si cambia la API pública.
|
|
|
|
|
6. Ejecuta `npm run check` y `npm run test:coverage`.
|
|
|
|
|
|
|
|
|
|
## Fuera de alcance actual
|
|
|
|
|
|
|
|
|
|
- Ejecución de reglas contra datos reales.
|
|
|
|
|
- Generación directa de SQL o llamadas a APIs.
|
|
|
|
|
- Colaboración en tiempo real.
|
|
|
|
|
- Persistencia automática.
|
|
|
|
|
- Un editor visual de flujos con nodos y conexiones libres.
|
|
|
|
|
|
|
|
|
|
Estas capacidades requieren contratos y análisis de seguridad propios; no deben incorporarse como comportamiento implícito de los componentes visuales.
|
