feat: dnd with overlay and sortable in drag element

Author: carloscuatin

DECISIONS.md

@@ -46,34 +46,34 @@ Se usa **JSONB** para dos columnas clave:
 
 ---
 
-## 3. Frontend: Arquitectura de Componentes por Features (autocontenidos)
+## 3. Frontend: Vertical Slicing (Arquitectura por Features)
 
 ### Decisión
 
-El frontend sigue una **arquitectura de componentes por feature**, donde cada feature (auth, dashboard, forms, builder, theme) es **autocontenido**: tiene su propio `index.ts` como API pública, y agrupa dentro de sí componentes, hooks, contexto y schemas. No hay carpeta global `components/hooks`; cada feature lleva sus hooks en una subcarpeta `hooks/` si los necesita (ej. `builder/hooks/`).
+El frontend sigue **vertical slicing** (también conocido como **feature-based architecture** o **slice-by-feature**): cada **slice** o feature (auth, dashboard, forms, builder, theme) es una **unidad vertical autocontenida** con su propio `index.ts` como API pública, y agrupa dentro de sí componentes, hooks, contexto y schemas. No existe carpeta global `components/hooks`; cada feature lleva sus hooks en una subcarpeta `hooks/` si los necesita (ej. `builder/hooks/`).
 
-Estructura actual:
+Estructura actual (cada carpeta bajo `components/` es un slice vertical):
 
 ```
 components/
   auth/         → AuthForm, auth-form-schema (index exporta la API)
   builder/      → form-builder, context, schema + layout/, fields/, preview/, hooks/
-  dashboard/    → Navbar, FormCard, EmptyState, ResponseTable, etc. + charts/
-  forms/        → PublicForm, FieldRenderer, response-schema, form-defaults
+  dashboard/    → Navbar, FormCard, EmptyState, ResponseTable, etc. + charts/, list/, layout/, responses/
+  forms/        → PublicForm, FieldRenderer, response-schema, form-defaults (public/, renderer/)
   theme/        → ThemeProvider, ThemeToggle
   ui/           → Primitivos shadcn (sin index; import por archivo)
 ```
 
-Las páginas importan desde el barrel del feature: `import { FormBuilder } from '@/components/builder'`, `import { AuthForm } from '@/components/auth'`. La convención completa está en el [README principal](./README.md#convenciones-de-componentes-frontend).
+Las páginas importan desde el barrel del feature: `import { FormBuilder } from '@/components/builder'`, `import { AuthForm } from '@/components/auth'`. La convención completa está en el [README](./README.md#convenciones-de-componentes-vertical-slicing).
 
 ### Justificación
 
-- **Colocación por feature**: Todo lo que pertenece a un flujo (login, builder, dashboard) vive junto. Cambios en el builder no dispersan archivos por `components/` y `hooks/`; todo está en `builder/`.
-- **API pública clara**: El `index.ts` de cada feature define qué se expone al resto de la app. El resto son detalles internos del feature (layout, campos, hooks), lo que reduce acoplamiento y facilita refactors.
-- **Hooks por feature, no globales**: Evitamos un cajón de sastre `src/hooks/` con lógica de un solo feature. Cada feature lleva sus hooks (use-form-builder, use-form-builder-dnd, use-form-builder-save en `builder/hooks/`). Solo hooks de utilidad realmente reutilizables (useDebounce, useMediaQuery) tendrían sentido en `src/hooks/` si se añaden.
-- **Escalabilidad**: Si un feature crece (como el builder), se subdivide en subcarpetas (layout, fields, preview, hooks) con sus propios `index.ts`, sin contaminar la raíz de `components/`.
+- **Vertical slicing**: Cada slice corta “en vertical” la capa de presentación: todo lo que pertenece a un flujo (login, builder, dashboard) vive junto. Cambios en el builder no dispersan archivos por `components/` y `hooks/`; todo está en `builder/`.
+- **API pública por slice**: El `index.ts` de cada feature define qué se expone al resto de la app. El resto son detalles internos del slice (layout, campos, hooks), lo que reduce acoplamiento y facilita refactors.
+- **Hooks por feature, no globales**: Evitamos un cajón de sastre `src/hooks/` con lógica de un solo feature. Cada slice lleva sus hooks (use-form-builder, use-form-builder-dnd, use-form-builder-save en `builder/hooks/`). Solo hooks de utilidad realmente reutilizables (useDebounce, useMediaQuery) tendrían sentido en `src/hooks/` si se añaden.
+- **Escalabilidad**: Si un slice crece (como el builder), se subdivide en subcarpetas (layout, fields, preview, hooks) con sus propios `index.ts`, sin contaminar la raíz de `components/`.
 - **Reutilización controlada**: `FieldRenderer` se usa en el preview del builder y en el formulario público; se exporta desde `@/components/forms` y el builder lo importa desde ahí, manteniendo una única fuente de verdad.
-- **Composición**: Componentes pequeños y enfocados que se componen por feature; la app orquesta features, no decenas de componentes sueltos.
+- **Composición**: Componentes pequeños y enfocados que se componen por feature; la app orquesta slices, no decenas de componentes sueltos.
 
 ---
 

README.md

@@ -79,30 +79,30 @@ src/
 │   ├── adapters/supabase/        # Implementación Supabase
 │   └── mappers/                  # Transformación Domain ↔ DB
 │
-├── components/                   # 🎨 Componentes React (ver convenciones abajo)
-│   ├── auth/                     # Login/registro
-│   ├── builder/                  # Editor de formularios (layout, fields, preview, hooks)
-│   ├── dashboard/                # Listado, detalle, gráficas
-│   ├── forms/                    # Formulario público y renderer de campos
-│   ├── theme/                    # ThemeProvider, ThemeToggle
-│   └── ui/                       # shadcn/ui (primitivos)
+├── components/                   # 🎨 Vertical slicing (por feature)
+│   ├── auth/                     # Slice: login/registro
+│   ├── builder/                  # Slice: editor (layout, fields, preview, hooks)
+│   ├── dashboard/                # Slice: listado, detalle, gráficas
+│   ├── forms/                    # Slice: formulario público y renderer
+│   ├── theme/                    # Slice: ThemeProvider, ThemeToggle
+│   └── ui/                       # Primitivos shadcn (sin slice; import por archivo)
 │
 └── lib/                          # Utilidades (Supabase client, cn)
 ```
 
-### Convenciones de componentes (frontend)
+### Convenciones de componentes (vertical slicing)
 
-Cada **feature** (auth, dashboard, forms, builder, theme) es **autocontenido**: tiene su propio `index.ts` (API pública), y opcionalmente subcarpetas por responsabilidad. La app importa desde el barrel del feature, no por archivo.
+El frontend usa **vertical slicing** (arquitectura por features): cada **slice** (auth, dashboard, forms, builder, theme) es una unidad vertical autocontenida con su propio `index.ts` (API pública) y, opcionalmente, subcarpetas por responsabilidad. La app importa desde el barrel del slice, no por archivo. Detalle en [DECISIONS.md §3](./DECISIONS.md#3-frontend-vertical-slicing-arquitectura-por-features).
 
-| Regla                  | Descripción                                                                                                                                                                                            |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **API por feature**    | `import { AuthForm } from '@/components/auth'`, `import { FormBuilder } from '@/components/builder'`, etc.                                                                                             |
-| **ui/**                | Sin index; imports directos: `@/components/ui/button`, `@/components/ui/card` (patrón shadcn).                                                                                                         |
-| **Subcarpetas**        | Si un feature crece (ej. builder), se agrupa en `layout/`, `fields/`, `preview/`, `hooks/`, cada uno con su `index.ts`.                                                                                |
-| **Schemas y contexto** | Pertenecen al feature: `auth-form-schema.ts`, `form-builder-context.tsx`, `form-builder-schema.ts`.                                                                                                    |
-| **Hooks**              | No hay `components/hooks` global. Cada feature lleva sus hooks dentro (ej. `builder/hooks/`). Solo hooks de utilidad reutilizables (useDebounce, useMediaQuery) irían en `src/hooks/` si se necesitan. |
-| **Naming**             | Archivos en kebab-case; componentes/hooks en PascalCase/camelCase.                                                                                                                                     |
-| **Tests**              | `__tests__/` dentro del feature; imports relativos a archivos.                                                                                                                                         |
+| Regla                  | Descripción                                                                                                                                                        |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **API por slice**      | `import { AuthForm } from '@/components/auth'`, `import { FormBuilder } from '@/components/builder'`, etc.                                                         |
+| **ui/**                | Sin index; imports directos: `@/components/ui/button`, `@/components/ui/card` (patrón shadcn).                                                                     |
+| **Subcarpetas**        | Si un slice crece (ej. builder), se agrupa en `layout/`, `fields/`, `preview/`, `hooks/`, cada uno con su `index.ts`.                                              |
+| **Schemas y contexto** | Pertenecen al slice: `auth-form-schema.ts`, `form-builder-context.tsx`, `form-builder-schema.ts`.                                                                  |
+| **Hooks**              | No hay `components/hooks` global. Cada slice lleva sus hooks dentro (ej. `builder/hooks/`). Hooks de utilidad reutilizables irían en `src/hooks/` si se necesitan. |
+| **Naming**             | Archivos en kebab-case; componentes/hooks en PascalCase/camelCase.                                                                                                 |
+| **Tests**              | `__tests__/` dentro del slice; imports relativos a archivos.                                                                                                       |
 
 ## Funcionalidades
 
@@ -125,7 +125,7 @@ Cada **feature** (auth, dashboard, forms, builder, theme) es **autocontenido**:
 ### Arquitectura
 
 - ✅ Arquitectura Hexagonal (Clean Architecture) en backend
-- ✅ Arquitectura de Componentes en frontend
+- ✅ Arquitectura por componentes, estructura en vertical slicing (por features) en frontend
 - ✅ TypeScript estricto
 - ✅ Separación de responsabilidades
 

jest.config.ts

@@ -20,7 +20,10 @@ const config: Config = {
       preset: 'ts-jest',
       testEnvironment: 'jsdom',
       roots: ['<rootDir>/src'],
-      testMatch: ['<rootDir>/src/components/**/__tests__/**/*.test.tsx'],
+      testMatch: [
+        '<rootDir>/src/components/**/__tests__/**/*.test.tsx',
+        '<rootDir>/src/utils/**/__tests__/**/*.test.ts',
+      ],
       moduleNameMapper: {
         '^@/(.*)$': '<rootDir>/src/$1',
       },

src/components/builder/constants.ts

@@ -0,0 +1,11 @@
+/** Min height of a field row; used for insertion spacer during drag. */
+export const FIELD_ROW_MIN_HEIGHT = 52;
+
+/** Sortable transition config for smooth reorder animation. */
+export const SORTABLE_TRANSITION = {
+  duration: 280,
+  easing: 'cubic-bezier(0.33, 1, 0.68, 1)' as const,
+};
+
+/** Minimum pointer movement (px) before starting drag. */
+export const DND_POINTER_ACTIVATION_DISTANCE = 6;

src/components/builder/fields/field-type-drag-overlay.tsx

@@ -19,7 +19,7 @@ export const FieldTypeDragOverlay: FC<FieldTypeDragOverlayProps> = ({
   const Icon = FIELD_TYPE_ICON_MAP[type];
 
   return (
-    <div className="flex items-center gap-2 rounded-lg border border-indigo-300 bg-white px-4 py-3 shadow-lg dark:border-indigo-700 dark:bg-gray-900">
+    <div className="flex flex-col items-center justify-center gap-2 rounded-lg border border-indigo-300 bg-white px-4 py-3 text-center shadow-lg dark:border-indigo-700 dark:bg-gray-900">
       <Icon className="h-4 w-4 text-indigo-600 dark:text-indigo-400" />
       <span className="text-sm font-medium">{FIELD_TYPE_LABELS[type]}</span>
     </div>

src/components/builder/fields/sortable-field-item.tsx

@@ -11,6 +11,7 @@ import { FormField } from '@/core/domain/entities/form';
 import { FIELD_TYPE_LABELS } from '@/core/domain/value-objects/field-types';
 import { cn } from '@/utils/cn';
 
+import { SORTABLE_TRANSITION } from '../constants';
 import { useFormBuilderContext } from '../form-builder-context';
 
 interface SortableFieldItemProps {
@@ -32,7 +33,10 @@ export const SortableFieldItem: FC<SortableFieldItemProps> = ({ field }) => {
     transform,
     transition,
     isDragging,
-  } = useSortable({ id: field.id });
+  } = useSortable({
+    id: field.id,
+    transition: SORTABLE_TRANSITION,
+  });
 
   const style = {
     transform: CSS.Transform.toString(transform),

src/components/builder/form-builder.tsx

@@ -41,6 +41,7 @@ const FormBuilderInner: FC<{ formId?: string }> = ({ formId }) => {
     activeField,
     isDropTarget,
     dragWidth,
+    insertionIndex,
   } = useFormBuilderDnD();
 
   return (
@@ -62,6 +63,7 @@ const FormBuilderInner: FC<{ formId?: string }> = ({ formId }) => {
             <FormBuilderFieldsColumn
               activeTab={activeTab}
               isDropTarget={isDropTarget}
+              insertionIndex={insertionIndex}
             />
             <div
               className={`lg:col-span-4 ${

src/components/builder/hooks/use-form-builder-dnd.ts

@@ -2,21 +2,24 @@
 
 import { useState, useCallback, useMemo } from 'react';
 import {
-  pointerWithin,
-  closestCenter,
   KeyboardSensor,
   PointerSensor,
   useSensor,
   useSensors,
   type DragEndEvent,
   type DragStartEvent,
   type DragOverEvent,
-  type CollisionDetection,
 } from '@dnd-kit/core';
 import { sortableKeyboardCoordinates } from '@dnd-kit/sortable';
 
 import type { FieldType } from '@/core/domain/value-objects/field-types';
+import { createListCollisionDetection } from '@/utils/dnd/collision-detection';
+import {
+  getOverId,
+  resolveNewItemInsertionIndex,
+} from '@/utils/dnd/insertion-index';
 
+import { DND_POINTER_ACTIVATION_DISTANCE } from '../constants';
 import { useFormBuilderContext } from '../form-builder-context';
 import { DROP_ZONE_ID } from '../fields';
 
@@ -31,33 +34,31 @@ export function useFormBuilderDnD() {
   const [activeDragType, setActiveDragType] = useState<FieldType | null>(null);
   const [activeDragId, setActiveDragId] = useState<string | null>(null);
   const [overId, setOverId] = useState<string | null>(null);
+  const [insertionIndex, setInsertionIndex] = useState<number | null>(null);
   const [dragWidth, setDragWidth] = useState<number | null>(null);
 
   const sensors = useSensors(
-    useSensor(PointerSensor, { activationConstraint: { distance: 5 } }),
+    useSensor(PointerSensor, {
+      activationConstraint: { distance: DND_POINTER_ACTIVATION_DISTANCE },
+    }),
     useSensor(KeyboardSensor, {
       coordinateGetter: sortableKeyboardCoordinates,
     }),
   );
 
-  const collisionDetection: CollisionDetection = useCallback((args) => {
-    if (args.active.data.current?.isNewField) {
-      const pointerCollisions = pointerWithin(args);
-      if (pointerCollisions.length > 0) return pointerCollisions;
-      return [];
-    }
-    return closestCenter({
-      ...args,
-      droppableContainers: args.droppableContainers.filter(
-        (c) => c.id !== DROP_ZONE_ID,
-      ),
-    });
-  }, []);
+  const collisionDetection = useMemo(
+    () =>
+      createListCollisionDetection({
+        dropZoneId: DROP_ZONE_ID,
+      }),
+    [],
+  );
 
   const clearDragState = useCallback(() => {
     setActiveDragType(null);
     setActiveDragId(null);
     setOverId(null);
+    setInsertionIndex(null);
     setDragWidth(null);
   }, []);
 
@@ -77,37 +78,67 @@ export function useFormBuilderDnD() {
   const handleDragOver = useCallback(
     (event: DragOverEvent) => {
       const { active, over } = event;
-      setOverId(over?.id != null ? String(over.id) : null);
-
-      if (
-        !active.data.current?.isNewField &&
-        over &&
-        active.id !== over.id &&
-        over.id !== DROP_ZONE_ID
-      ) {
-        reorderFields(String(active.id), String(over.id));
+      const newOverId = getOverId(over);
+      setOverId((prev) => (prev === newOverId ? prev : newOverId));
+
+      if (!active.data.current?.isNewField) {
+        setInsertionIndex((prev) => (prev === null ? prev : null));
+        return;
       }
+
+      const nextIndex = resolveNewItemInsertionIndex({
+        overId: newOverId,
+        overRect: over?.rect ?? null,
+        activeRect: active.rect.current.translated,
+        items: fields,
+        dropZoneId: DROP_ZONE_ID,
+      });
+      setInsertionIndex((prev) => (prev === nextIndex ? prev : nextIndex));
     },
-    [reorderFields],
+    [fields],
   );
 
   const handleDragEnd = useCallback(
     (event: DragEndEvent) => {
       const { active, over } = event;
-      clearDragState();
-      if (!over) return;
+      const overId = getOverId(over);
+
+      if (overId == null || !over) {
+        clearDragState();
+        return;
+      }
 
       if (active.data.current?.isNewField) {
         const type = active.data.current.type as FieldType;
-        if (over.id === DROP_ZONE_ID) {
-          addField(type);
-        } else {
-          const overIndex = fields.findIndex((f) => f.id === over.id);
-          if (overIndex !== -1) addFieldAt(type, overIndex);
+        const targetIndex =
+          insertionIndex != null
+            ? Math.max(0, Math.min(insertionIndex, fields.length))
+            : resolveNewItemInsertionIndex({
+                overId,
+                overRect: over.rect,
+                activeRect: active.rect.current.translated,
+                items: fields,
+                dropZoneId: DROP_ZONE_ID,
+              });
+
+        if (targetIndex != null) {
+          if (targetIndex >= fields.length) addField(type);
+          else addFieldAt(type, targetIndex);
         }
+      } else if (overId !== DROP_ZONE_ID && overId !== String(active.id)) {
+        reorderFields(String(active.id), overId);
       }
+
+      clearDragState();
     },
-    [addField, addFieldAt, fields, clearDragState],
+    [
+      addField,
+      addFieldAt,
+      fields,
+      insertionIndex,
+      reorderFields,
+      clearDragState,
+    ],
   );
 
   const activeField = useMemo(
@@ -135,5 +166,6 @@ export function useFormBuilderDnD() {
     activeField,
     isDropTarget,
     dragWidth,
+    insertionIndex,
   };
 }

src/components/builder/hooks/use-form-builder.ts

@@ -110,9 +110,9 @@ export const useFormBuilder = (initialData?: FormBuilderData) => {
   /** Reorder fields after drag & drop */
   const reorderFields = (activeId: string, overId: string) => {
     const oldIndex = fields.findIndex((f) => f.id === activeId);
-    const newIndex = fields.findIndex((f) => f.id === overId);
-    if (oldIndex === -1 || newIndex === -1) return;
-    fieldArray.move(oldIndex, newIndex);
+    const overIndex = fields.findIndex((f) => f.id === overId);
+    if (oldIndex === -1 || overIndex === -1) return;
+    fieldArray.move(oldIndex, overIndex);
   };
 
   /** Add option to a select field */