@tmf_ciclica/ciclicastorybook 1.2.163 → 1.2.165

package/README.md

@@ -2,5 +2,76 @@
 
 Necesidades:
 
-- Para el componente MapboxMap hay que importar import "mapbox-gl/dist/mapbox-gl.css" 
+- Para el componente MapboxMap hay que importar import "mapbox-gl/dist/mapbox-gl.css"
 
+## Depuración de errores en aplicaciones consumidoras
+
+Cuando usas los componentes desde otra aplicación, los errores pueden aparecer
+encriptados en la consola porque apuntan al bundle compilado (`dist/index.es.js`).
+
+### Source maps
+
+El build genera source maps (`dist/index.es.js.map`). Para que el navegador los
+use y los stack traces apunten al código fuente original (`.jsx`), asegúrate de
+que la app consumidora no los descarte. En Vite, por defecto se usan en dev; en
+producción puedes habilitarlos con:
+
+```js
+// vite.config.js de la app consumidora
+export default defineConfig({
+  build: {
+    sourcemap: true,
+  },
+})
+```
+
+### Nombres de componentes legibles
+
+Cuando la app consumidora pre-bundla la librería con esbuild, los nombres de los
+componentes se renombran a identificadores minificados (`d0`, `d1`, ...), por lo
+que los warnings de React (como el de las `key`) muestran nombres encriptados.
+
+El build de la librería añade automáticamente `displayName` a todos los
+componentes exportados. Los strings no se renombran nunca, así que los warnings
+y stack traces de React mostrarán el nombre real del componente:
+
+```
+Warning: Each child in a list should have a unique "key" prop.
+Check the render method of `Legend`. It was passed a child from DataLayout.
+```
+
+No requiere configuración en la app consumidora: basta con usar la versión
+publicada de la librería.
+
+### Warnings de `key` en listas
+
+Si ves el warning `Each child in a list should have a unique "key" prop`, el
+problema está en un componente de la librería que renderiza una lista sin `key`
+o con `key` duplicada. Los componentes de la librería ya usan `key` correctas,
+pero si encuentras uno que no, el warning ahora te dirá **qué componente** es
+(gracias a los `displayName`), lo que facilita localizarlo y corregirlo.
+
+### ErrorBoundary
+
+La librería exporta un `ErrorBoundary` que captura errores de los componentes y
+muestra el nombre del componente que falló y su jerarquía, en lugar de un stack
+trace encriptado:
+
+```jsx
+import { ErrorBoundary, MapboxMap } from "@tmf_ciclica/ciclicastorybook"
+
+<ErrorBoundary name="MapboxMap">
+  <MapboxMap ... />
+</ErrorBoundary>
+```
+
+También acepta un `fallback` personalizado:
+
+```jsx
+<ErrorBoundary
+  name="MapboxMap"
+  fallback={(error, errorInfo) => <div>Ha fallado: {error.message}</div>}
+>
+  <MapboxMap ... />
+</ErrorBoundary>
+```