virtual-tree-canvas 0.7.0 → 0.7.2

package/docs/icon-catalog.md

@@ -1,171 +1,171 @@
-# Catálogo de iconos
+# Icon catalog
 
-Los 65 iconos incluidos están disponibles en `resources/icons/`.
-Consulta la [galería visual](./icon-catalog.html) para verlos sobre fondos claros
-u oscuros y comparar tamaños. `builtinIconNames` permite enumerar sus IDs desde JavaScript.
+The 65 bundled icons are available in `resources/icons/`. Open the
+[rendered visual catalog](https://htmlpreview.github.io/?https://github.com/mploscos/virtual-tree-canvas/blob/main/docs/icon-catalog.html)
+to compare them at different sizes on light and dark backgrounds. The
+[HTML source](./icon-catalog.html) is also available. `builtinIconNames` lists
+their IDs from JavaScript.
 
-## Uso
+## Usage
 
-Asigna un ID a la propiedad `icon` del nodo:
+Assign an ID to the node's `icon` property:
 
 ```js
-view.setData([{ id: 'operator-1', label: 'Operador', icon: 'person' }]);
+view.setData([{ id: 'operator-1', label: 'Operator', icon: 'person' }]);
 ```
 
-- `data-bus` representa un bus de datos; `bus-vehicle`, un autobús.
-- `placeholder` es el icono utilizado cuando no hay uno específico.
-- Acompaña los iconos con etiquetas. Para estados como advertencias o errores,
-  proporciona también texto y no dependas únicamente del color.
-- Para añadir un icono propio, usa `view.registerIcon('custom', svgStringOrUrl)`
-  y asigna `icon: 'custom'` al nodo.
-- Configura `iconsBaseUrl` al crear la vista si los recursos se sirven desde otra URL.
-  Los SVG se cargan al dibujarlos o mediante `view.controller.iconRegistry.prepare()`.
+- `data-bus` represents a data bus; `bus-vehicle` represents a passenger bus.
+- `placeholder` is used when no specific icon is available.
+- Pair icons with labels. For states such as warnings or errors, also provide
+  text instead of relying on color alone.
+- To add a custom icon, call `view.registerIcon('custom', svgStringOrUrl)` and
+  assign `icon: 'custom'` to the node.
+- Set `iconsBaseUrl` when creating the view if assets are served from another URL.
+  SVGs are loaded when drawn or through `view.controller.iconRegistry.prepare()`.
 
-## Iconos disponibles
+## Available icons
 
-### Personas y organización
+### People and organization
 
-| ID | Significado |
+| ID | Meaning |
 | --- | --- |
-| `person` | Persona |
-| `people` | Grupo |
-| `child` | Infancia |
+| `person` | Person |
+| `people` | Group |
+| `child` | Child |
 
-### Animales
+### Animals
 
-| ID | Significado |
+| ID | Meaning |
 | --- | --- |
-| `dog` | Perro |
-| `cat` | Gato |
-| `bird` | Ave |
-| `fish` | Pez |
-| `insect` | Insecto |
+| `dog` | Dog |
+| `cat` | Cat |
+| `bird` | Bird |
+| `fish` | Fish |
+| `insect` | Insect |
 
-### Plantas y ecosistemas
+### Plants and ecosystems
 
-| ID | Significado |
+| ID | Meaning |
 | --- | --- |
-| `tree` | Árbol |
-| `leaf` | Hoja |
-| `flower` | Flor |
-| `seedling` | Brote |
+| `tree` | Tree |
+| `leaf` | Leaf |
+| `flower` | Flower |
+| `seedling` | Seedling |
 
-### Tiempo atmosférico
+### Weather
 
-| ID | Significado |
+| ID | Meaning |
 | --- | --- |
-| `sun` | Sol |
-| `moon` | Luna |
-| `cloud` | Nube |
-| `rain` | Lluvia |
-| `snow` | Nieve |
-| `wind` | Viento |
-| `storm` | Tormenta |
-| `fog` | Niebla |
+| `sun` | Sun |
+| `moon` | Moon |
+| `cloud` | Cloud |
+| `rain` | Rain |
+| `snow` | Snow |
+| `wind` | Wind |
+| `storm` | Storm |
+| `fog` | Fog |
 
-### Terreno y agua
+### Terrain and water
 
-| ID | Significado |
+| ID | Meaning |
 | --- | --- |
-| `ground` | Dominio terrestre |
-| `surface` | Dominio de superficie |
-| `subsurface` | Dominio submarino |
+| `ground` | Ground domain |
+| `surface` | Surface domain |
+| `subsurface` | Subsurface domain |
 
-### Transporte terrestre
+### Ground transportation
 
-| ID | Significado |
+| ID | Meaning |
 | --- | --- |
-| `car` | Coche |
-| `bicycle` | Bicicleta |
-| `bus-vehicle` | Autobús de pasajeros |
+| `car` | Car |
+| `bicycle` | Bicycle |
+| `bus-vehicle` | Passenger bus |
 
-### Aviación y espacio
+### Aviation and space
 
-| ID | Significado |
+| ID | Meaning |
 | --- | --- |
-| `aircraft` | Avión |
-| `helicopter` | Helicóptero |
-| `drone` | Dron |
-| `space` | Dominio espacial |
+| `aircraft` | Aircraft |
+| `helicopter` | Helicopter |
+| `drone` | Drone |
+| `space` | Space domain |
 
-### Entorno marítimo
+### Maritime environment
 
-| ID | Significado |
+| ID | Meaning |
 | --- | --- |
-| `ship` | Buque |
+| `ship` | Ship |
 
-### Objetos e instalaciones
+### Objects and facilities
 
-| ID | Significado |
+| ID | Meaning |
 | --- | --- |
-| `box` | Caja |
-| `building` | Edificio |
+| `box` | Box |
+| `building` | Building |
 
-### Datos y redes
+### Data and networks
 
-| ID | Significado |
+| ID | Meaning |
 | --- | --- |
-| `data-bus` | Bus de datos |
-| `network` | Red |
-| `server` | Servidor |
-| `database` | Base de datos |
-| `link` | Enlace |
+| `data-bus` | Data bus |
+| `network` | Network |
+| `server` | Server |
+| `database` | Database |
+| `link` | Link |
 
-### Sensores y mediciones
+### Sensors and measurements
 
-| ID | Significado |
+| ID | Meaning |
 | --- | --- |
-| `sensor` | Sensor genérico |
+| `sensor` | Generic sensor |
 | `radar` | Radar |
-| `thermometer` | Termómetro |
+| `thermometer` | Thermometer |
 
-### Geografía y navegación
+### Geography and navigation
 
-| ID | Significado |
+| ID | Meaning |
 | --- | --- |
-| `globe` | Globo terrestre |
-| `point` | Punto |
-| `track` | Traza |
+| `globe` | Globe |
+| `point` | Point |
+| `track` | Track |
 
-### Inspector y documentos
+### Inspector and documents
 
-| ID | Significado |
+| ID | Meaning |
 | --- | --- |
-| `folder` | Carpeta |
-| `inspector-object` | Objeto de datos |
+| `folder` | Folder |
+| `inspector-object` | Data object |
 | `inspector-array` | Array |
-| `inspector-value` | Valor escalar |
+| `inspector-value` | Scalar value |
 
-### Estados y alertas
+### States and alerts
 
-| ID | Significado |
+| ID | Meaning |
 | --- | --- |
-| `warning` | Advertencia |
+| `warning` | Warning |
 | `error` | Error |
-| `placeholder` | Tipo desconocido |
-| `damage` | Daño |
-| `situation` | Situación |
-| `lock` | Bloqueado |
+| `placeholder` | Unknown type |
+| `damage` | Damage |
+| `situation` | Situation |
+| `lock` | Locked |
 
-### Acciones y controles
+### Actions and controls
 
-| ID | Significado |
+| ID | Meaning |
 | --- | --- |
 | `control` | Control |
-| `task` | Tarea |
-| `star` | Favorito |
-| `pin` | Fijado |
-| `heart` | Preferencia afectiva |
-| `grip` | Asa de arrastre |
+| `task` | Task |
+| `star` | Favorite |
+| `star-filled` | Active favorite |
+| `pin` | Pinned |
+| `heart` | Favorite |
+| `grip` | Drag handle |
+| `trash` | Delete or remove |
 
-### Tiempo y simulación
+### Time and simulation
 
-| ID | Significado |
+| ID | Meaning |
 | --- | --- |
-| `clock` | Reloj |
-| `calendar` | Calendario |
-| `munition` | Munición |
-
-- `trash`: eliminar un elemento o quitarlo de una lista.
-
-- `star-filled`: favorito activo; combina con `star` para el estado inactivo.
+| `clock` | Clock |
+| `calendar` | Calendar |
+| `munition` | Munition |

package/docs/performance/dynamic-updates-0.7.1.md

@@ -0,0 +1,38 @@
+# Dynamic update benchmark: 0.7.0 → 0.7.1
+
+Measured on 2026-09-13 in headless Chromium on the development host. Each case
+uses 10,000 flat nodes, approximately 40 visible rows, 60 update ticks and 500
+patches per tick (30,000 patches/case). Times are milliseconds. The reproducible
+command is `npm run benchmark:dynamic`.
+
+The 0.7.0 measurement used an extracted clean `HEAD` and the same benchmark file.
+Icon-load invalidations and initial ResizeObserver work were settled before each
+sample. “Total avg” is patch application plus render time per tick; a zero-render
+case therefore contains only patch processing.
+
+| Sorted | RowActions | Visible patches | Patch avg/p95 before → after | Render avg/p95 before → after | Renders before → after | Total avg before → after |
+|---|---:|---:|---:|---:|---:|---:|
+| no | no | 0% | 0.417/0.700 → 0.788/1.200 | 1.573/2.000 → 0/0 | 60 → 0 | 1.990 → 0.788 |
+| no | no | 10% | 0.413/0.600 → 0.657/0.900 | 1.422/2.100 → 1.485/2.000 | 60 → 60 | 1.835 → 2.142 |
+| no | no | 100% | 0.285/0.400 → 0.212/0.400 | 1.335/2.000 → 1.335/1.900 | 60 → 60 | 1.620 → 1.547 |
+| no | yes | 0% | 0.303/0.500 → 0.635/0.900 | 2.408/3.600 → 0/0 | 60 → 0 | 2.712 → 0.635 |
+| no | yes | 10% | 0.318/0.500 → 0.592/0.800 | 2.708/3.400 → 2.960/3.900 | 60 → 60 | 3.027 → 3.552 |
+| no | yes | 100% | 0.203/0.300 → 0.153/0.300 | 2.535/3.600 → 2.552/3.700 | 60 → 60 | 2.738 → 2.705 |
+| yes | no | 0% | 0.317/0.400 → 0.548/0.800 | 2.012/3.400 → 0/0 | 60 → 0 | 2.328 → 0.548 |
+| yes | no | 10% | 0.345/0.500 → 0.582/0.800 | 1.945/2.600 → 1.343/2.300 | 60 → 60 | 2.290 → 1.925 |
+| yes | no | 100% | 0.267/0.500 → 0.220/0.400 | 2.005/2.600 → 1.305/2.300 | 60 → 60 | 2.272 → 1.525 |
+| yes | yes | 0% | 0.287/0.400 → 0.493/0.700 | 3.087/3.900 → 0/0 | 60 → 0 | 3.373 → 0.493 |
+| yes | yes | 10% | 0.307/0.500 → 0.478/0.800 | 3.402/5.200 → 2.782/4.100 | 60 → 60 | 3.708 → 3.260 |
+| yes | yes | 100% | 0.182/0.300 → 0.137/0.300 | 3.103/4.800 → 2.447/3.800 | 60 → 60 | 3.285 → 2.583 |
+
+In every 0%-visible case, 0.7.1 recorded 60 renders avoided because the changes
+were offscreen, with zero render requests and executions. In visible cases,
+0.7.0 performed 60 full RowActions synchronizations; 0.7.1 performed 60
+incremental and zero full synchronizations. At 100% visible, repeated patches for
+the approximately 40 visible IDs coalesced 30,000 received patches into 2,400
+unique changed nodes across the 60 frames.
+
+The queue adds measurable bookkeeping when nearly all 500 IDs are unique and a
+render is required anyway; this is visible in the two unsorted 10% cases. The
+largest gains are the intended real-time-tree case (offscreen traffic), and active
+sorting additionally benefits from removing the 10,000-entry scene copy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "virtual-tree-canvas",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "High-performance Canvas2D virtual tree/table widget for very large hierarchical datasets.",
   "type": "module",
   "main": "./src/index.js",
@@ -34,7 +34,8 @@
   "scripts": {
     "demo": "python3 -m http.server 4173 --bind localhost",
     "test": "node --test test/*.test.js",
-    "test:browser": "node test/run-browser.mjs"
+    "test:browser": "node test/run-browser.mjs",
+    "benchmark:dynamic": "node scripts/diagnostics/profile-dynamic-updates.mjs"
   },
   "keywords": [
     "tree",

package/src/assets/icons.js

@@ -1,9 +1,15 @@
-/** Resolve built-in SVG resources independently of the bundled JavaScript location.
+/**
+ * Resolve built-in SVG resources independently of the bundled JavaScript location.
  * @param {string | URL} [iconsBaseUrl] Directory URL, with or without a trailing slash.
  */
 export function createBuiltinIconUrls(iconsBaseUrl) {
-  const base = String(iconsBaseUrl ?? new URL('../../resources/icons/', import.meta.url)).replace(/\/+$/, '');
-  return Object.freeze(Object.fromEntries(builtinIconNames.map(name => [name, `${base}/${name}.svg`])));
+  const base = String(iconsBaseUrl ?? new URL('../../resources/icons/', import.meta.url)).replace(
+    /\/+$/,
+    ''
+  );
+  return Object.freeze(
+    Object.fromEntries(builtinIconNames.map((name) => [name, `${base}/${name}.svg`]))
+  );
 }
 
 export const builtinIconNames = Object.freeze([
@@ -71,5 +77,5 @@ export const builtinIconNames = Object.freeze([
   'track',
   'tree',
   'warning',
-  'wind',
+  'wind'
 ]);

package/src/core/dynamic-state.js

@@ -1,44 +1,34 @@
 const hasOwn = Object.prototype.hasOwnProperty;
 
-const knownDynamicStateKeys = new Set([
-  'value',
-  'status',
-  'progress',
-  'pulse',
-  'color',
-  'selected',
-  'highlighted',
-  'visible',
-  'updated',
-  'updatedAt',
-  'icon',
-]);
-
 /**
  * @param {import('./types.js').NodeDynamicState} target
  * @param {import('./types.js').NodeDynamicState} state
  */
 export function mergeDynamicState(target, state) {
-  if (!state) return target;
+  mergeDynamicStateChanged(target, state);
+  return target;
+}
 
-  if (hasOwn.call(state, 'value') && target.value !== state.value) target.value = state.value;
-  if (hasOwn.call(state, 'status') && target.status !== state.status) target.status = state.status;
-  if (hasOwn.call(state, 'progress') && target.progress !== state.progress) target.progress = state.progress;
-  if (hasOwn.call(state, 'pulse') && target.pulse !== state.pulse) target.pulse = state.pulse;
-  if (hasOwn.call(state, 'color') && target.color !== state.color) target.color = state.color;
-  if (hasOwn.call(state, 'selected') && target.selected !== state.selected) target.selected = state.selected;
-  if (hasOwn.call(state, 'highlighted') && target.highlighted !== state.highlighted) target.highlighted = state.highlighted;
-  if (hasOwn.call(state, 'visible') && target.visible !== state.visible) target.visible = state.visible;
-  if (hasOwn.call(state, 'updated') && target.updated !== state.updated) target.updated = state.updated;
-  if (hasOwn.call(state, 'updatedAt') && target.updatedAt !== state.updatedAt) target.updatedAt = state.updatedAt;
-  if (hasOwn.call(state, 'icon') && target.icon !== state.icon) target.icon = state.icon;
+/**
+ * Merge a dynamic state patch and report whether at least one own property changed.
+ * Values are compared with Object.is so repeated NaN values and signed zero are
+ * handled consistently.
+ *
+ * @param {import('./types.js').NodeDynamicState} target
+ * @param {import('./types.js').NodeDynamicState} state
+ * @returns {boolean}
+ */
+export function mergeDynamicStateChanged(target, state) {
+  if (!state) return false;
+  let changed = false;
 
   for (const key in state) {
-    if (!hasOwn.call(state, key) || knownDynamicStateKeys.has(key)) continue;
-    if (target[key] !== state[key]) target[key] = state[key];
+    if (!hasOwn.call(state, key) || Object.is(target[key], state[key])) continue;
+    target[key] = state[key];
+    changed = true;
   }
 
-  return target;
+  return changed;
 }
 
 /** @param {import('./types.js').NodeDynamicState} state */

package/src/core/patch-batcher.js

@@ -24,6 +24,10 @@ export class PatchBatcher {
     return patches;
   }
 
+  clear() {
+    this.pending.clear();
+  }
+
   get size() {
     return this.pending.size;
   }