Materiales del taller

Tutorial paso a paso del catálogo de materiales de Despiece: el chip de la fila plana, el picker con proyecto / recientes / catálogo, el tab Materiales del taller en Configuración (catálogo built-in + customs + recientes), y cómo alimenta al Nest / BOM / Pedido / Etiquetas.

01 Cargar el modelo y el chip de material

Al importar el STEP/IGES/BREP/glTF/GLB, la sidebar izquierda muestra el árbol jerárquico. En la lista plana, cada pieza expone un chip de material (selector .sb-material-btn) en la misma línea que el de rol, veta y cantos.

Internamente el chip vive en src/ui/product-tree/row-chips.ts: buildMaterialButton(part) lee part.material, consulta swatchForMaterial() para el color, y renderiza un dot del color del catálogo. Si no hay material asignado, el chip queda vacío (sin dot) y se ve el ícono de la paleta en gris.

02 Picker: proyecto · recientes · catálogo

Click en el chip de material abre el picker (handler en src/ui/material-picker.ts:openMaterialPicker). El picker arma tres listas con listMaterialChoices():

El buscador usa suggestMaterials(q) que ordena por score (exacto 300, prefix 200, contains 100, sólo finish 90/180/250). Cuando elegís un material, el picker llama canonicalizeMaterial para normalizar el string (a veces un built-in tiene un whitespace distinto del custom).

03 Otro: crear material al vuelo con toggle Color | Textura

04 Asignar a una pieza

El flujo de una sola pieza vive en src/ui/apply-material.ts:pickAndApplyMaterial:

// Click en el chip →
const next = await openMaterialPicker({
  current:           primary.material ?? '',
  projectMaterials:  projectMaterialsFromParts(parts),
  applyCount:        targets.length,
});
if (next === null) return;        // cancelado
applyMaterialToIds(targets, next);

applyMaterialToIds arma un solo entry de history (withHistory('set-material')), así un undo deshace toda la asignación de una. Internamente setPartMaterial(id, material) actualiza state.model.parts[i].material (string) y dispara la re-render del árbol.

El picker también hace pushRecentMaterial(display) automáticamente — el material elegido sube al tope de Recientes en la próxima apertura.

05 Asignar a toda la selección

El mismo pickAndApplyMaterial detecta si la pieza clickeada es parte de la selección múltiple y abre el picker con todos los ids seleccionados como target:

const selected = state.selectedPartIds.filter(...);
const targets =
  selected.length > 1 && selected.includes(primaryId)
    ? selected
    : [primaryId];
// picker.applyCount = targets.length → muestra "Aplicar a N piezas"

Si tu selección es de un color distinto al de la primera pieza, el picker muestra el current del primary (no un mixto) — pero el material que elijas reemplaza los N strings en una sola operación atómica de history.

06 Configuración → Materiales

El botón Configuración de la topbar (icono engranaje) abre el panel lateral. La primera sección del tab Materiales del taller (id #stg-materials) está implementada en src/ui/settings-panel/materials-ui.ts.

El tab tiene tres zonas:

07 Catálogo built-in Faplac-style

BUILTIN_MATERIAL_DEFS en src/materials/catalog.ts lleva 26 entradas:

Los built-ins viven en el código (src/materials/catalog.ts), no en localStorage — son inamovibles. Si querés un simil custom (Roble español, Blanco nórdico, etc.), agregalo como custom (paso 7). El badge fijo en la fila lo deja claro.

08 Crear un material custom (con toggle Color|Textura)

+ Agregar material abre el form inline con cuatro campos:

Guardar llama addCustomMaterial({kind, finish, swatch, costPerM2}) en src/materials/store.ts. La función devuelve {ok:false, error:'duplicate' | 'empty' | 'limit'} si algo no cierra (límite 80 customs; duplicado por kind+finish case-insensitive; simil vacío).

09 Renombrar / borrar custom

Dos botones por fila custom:

• ✎ (data-mat-edit) → showForm(root, def); el form se abre con todos los campos pre-poblados y #stg-mat-edit-id con el id del def. Guardar en este caso llama updateCustomMaterial(id, patch), que valida duplicate / empty y vuelve a persistir.
• × (data-mat-del) → removeCustomMaterial(id): saca del catálogo y remapea cualquier entrada de recent o favorites que apuntaba al label viejo.

Lo importante: al renombrar (cambiar simil o tipo) el sistema reescribe automáticamente todas las piezas del modelo cargado que tenían el label anterior. Esto evita huérfanos silenciosos:

// src/ui/apply-material.ts
if (r.previousName !== r.def.name) {
  const n = rewriteMaterialsInLoadedModel(r.previousName, r.def.name);
  if (n > 0) {
    setTransient(`${n} piezas actualizadas con el material renombrado`, 3000);
  }
}

10 Recientes y persistencia

El catálogo se persiste en localStorage bajo la clave despiece.materials.v1 con la forma:

interface MaterialCatalogV3 {
  version:   3;
  recent:    string[];             // MRU 30, string canonico "Melamina MDP · Petiribí"
  favorites: string[];             // reservado (sin UI v1)
  custom:    MaterialDef[];        // hasta 80, editable
}

La función pushRecentMaterial(display) en src/materials/store.ts hace lo siguiente:

1. Trim + colapsar whitespace al display string.
2. Buscar key lowercase en recent; si existe, sacarlo.
3. Insertar al tope; truncar a MAX_RECENT = 30.
4. Persistir.

Vaciar (#stg-mat-clear-recent) llama clearRecentMaterials que setea recent: []. No toca favorites ni custom.

11 Integración con Nest · BOM · Etiquetas

El material asignado a cada pieza fluye hacia abajo de tres formas distintas. Es importante entender las tres para no mezclar colores en el nest sin querer:

Atajos del flujo de materiales:

En Mac el modificador de sistema es ⌘; en otros sistemas Ctrl.

Ver también

• Tutorial · Cantos y auto-cantos
• Tutorial · Roles y auto-roles
• Tutorial · Optimización de corte
• Tutorial · Plano de taller
• Spec 2026-07-15-material-purchase-labels.md — modelo de material + lista de compra + etiquetas.