@toclocoinc/lattice-grid 1.67.0 → 1.68.0

package/modules/data-router.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.67.0, data-router module type declarations
+ * Lattice Grid 1.68.0, data-router module type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */

package/modules/data-router.esm.min.js

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.67.0, data-router module
+ * Lattice Grid 1.68.0, data-router module
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -52,12 +52,12 @@ Object.defineProperty(__exports,"frameBatched",{enumerable:true,get:function(){r
 Object.defineProperty(__exports,"settleDebounce",{enumerable:true,get:function(){return settleDebounce;}});
 Object.defineProperty(__exports,"whenIdle",{enumerable:true,get:function(){return whenIdle;}});
 Object.defineProperty(__exports,"uid",{enumerable:true,get:function(){return uid;}});
-const STAMPED_VERSION="1.67.0";
+const STAMPED_VERSION="1.68.0";
 async function resolveVersion(){
 if(STAMPED_VERSION!=='0.0.0-source')return STAMPED_VERSION;
 return STAMPED_VERSION;
 }
-const VERSION="1.67.0";
+const VERSION="1.68.0";
 const warned=new Set();
 const WARNED_LIMIT=2000;
 function rememberWarned(key){
@@ -1544,6 +1544,180 @@ grandTotals:()=>lastGrand,
 };
 }
 });
+__def("packages/core/src/model/rowkey.js",function(__exports,__req){
+'use strict';
+Object.defineProperty(__exports,"KEY_DEPENDENT_FEATURES",{enumerable:true,get:function(){return KEY_DEPENDENT_FEATURES;}});
+Object.defineProperty(__exports,"compositeKey",{enumerable:true,get:function(){return compositeKey;}});
+Object.defineProperty(__exports,"createRowKey",{enumerable:true,get:function(){return createRowKey;}});
+Object.defineProperty(__exports,"warnMissingKeys",{enumerable:true,get:function(){return warnMissingKeys;}});
+Object.defineProperty(__exports,"groupPathKey",{enumerable:true,get:function(){return groupPathKey;}});
+Object.defineProperty(__exports,"splitPathKey",{enumerable:true,get:function(){return splitPathKey;}});
+const __m0=__req("packages/core/src/internal/util.js");
+const warnOnce=__m0["warnOnce"];
+const pathGetter=__m0["pathGetter"];
+const isFunction=__m0["isFunction"];
+const isBlank=__m0["isBlank"];
+const KEY_DEPENDENT_FEATURES=[
+'changes (rows.apply / rows.queue)',
+'streaming dedupe',
+'selection persistence',
+'remote reload',
+'cell comments',
+];
+const SEP='\u001f';
+function part(value){
+if(value===null)return'\u0000n';
+if(value===undefined)return'\u0000u';
+const t=typeof value;
+if(t==='string')return value;
+if(t==='number'||t==='bigint'||t==='boolean')return String(value);
+if(value instanceof Date)return`\u0000d${value.getTime()}`;
+try{
+return`\u0000o${JSON.stringify(value)}`;
+}catch{
+return'\u0000o?';
+}
+}
+function compositeKey(parts){
+if(parts.length===1)return part(parts[0]);
+let out='';
+for(let i=0;i<parts.length;i++){
+if(i)out+=SEP;
+out+=part(parts[i]);
+}
+return out;
+}
+function createRowKey(spec,opts={}){
+const warn=opts.warn!==false;
+if(isFunction(spec)){
+const fn=(spec);
+return{
+stable:true,
+fields:[],
+disabled:[],
+key(data,index){
+try{
+const value=fn(data);
+return Array.isArray(value)?compositeKey(value):part(value);
+}catch(err){
+warnOnce('rowKey.throw','rowKey function threw; falling back to index identity for the affected rows.',err);
+return`#${index??-1}`;
+}
+},
+keyEmpty(data){
+try{
+const value=fn(data);
+return Array.isArray(value)?value.length===0||value.some(isBlank):isBlank(value);
+}catch{
+return false;
+}
+},
+missingFields(){return[];},
+};
+}
+if(Array.isArray(spec)&&spec.length>0){
+const fields=spec.filter((f)=>typeof f==='string');
+const getters=fields.map((f)=>pathGetter(f));
+const n=getters.length;
+return{
+stable:true,
+fields,
+disabled:[],
+key(data){
+const parts=new Array(n);
+for(let i=0;i<n;i++)parts[i]=getters[i](data);
+return compositeKey(parts);
+},
+keyEmpty(data){
+for(let i=0;i<n;i++)if(isBlank(getters[i](data)))return true;
+return false;
+},
+missingFields(data){
+const out=[];
+for(let i=0;i<n;i++)if(isBlank(getters[i](data)))out.push(fields[i]);
+return out;
+},
+};
+}
+if(typeof spec==='string'&&spec.length>0){
+const get=pathGetter(spec);
+return{
+stable:true,
+fields:[spec],
+disabled:[],
+key(data){
+return part(get(data));
+},
+keyEmpty(data){
+return isBlank(get(data));
+},
+missingFields(data){
+return isBlank(get(data))?[spec]:[];
+},
+};
+}
+if(warn){
+warnOnce(
+'rowKey.missing',
+`no rowKey configured, so rows are identified by object identity. This disables: ${KEY_DEPENDENT_FEATURES.join(', ')}. Set rowKey to a field name, an array of field names, or a function.`,
+);
+}
+return{
+stable:false,
+fields:[],
+disabled:KEY_DEPENDENT_FEATURES.slice(),
+key(data,index){
+if(data===null||typeof data!=='object'){
+return`#${index??0}:${String(data)}`;
+}
+let assigned=autoKeys.get(data);
+if(assigned===undefined){
+assigned=`#${autoKeySeq++}`;
+autoKeys.set(data,assigned);
+}
+return assigned;
+},
+};
+}
+const autoKeys=new WeakMap();
+let autoKeySeq=0;
+function warnMissingKeys(resolver,rows){
+if(!resolver||resolver.stable===false||!isFunction(resolver.keyEmpty))return;
+if(!Array.isArray(rows)||rows.length===0)return;
+let missing=0;
+let sampleFields=null;
+let sampleData;
+for(let i=0;i<rows.length;i++){
+const data=rows[i];
+if(!resolver.keyEmpty(data))continue;
+missing++;
+if(sampleFields===null){
+sampleFields=isFunction(resolver.missingFields)?resolver.missingFields(data):[];
+sampleData=data;
+}
+}
+if(missing===0)return;
+const dedupFields=resolver.fields.length?resolver.fields.join(','):'(function)';
+const named=sampleFields&&sampleFields.length
+?sampleFields.join(', ')
+:(resolver.fields.length?resolver.fields.join(', '):'the rowKey function');
+const present=sampleData!==null&&typeof sampleData==='object'
+?(Object.keys((sampleData)).join(', ')||'(no fields)')
+:String(sampleData);
+warnOnce(
+`rowKey.emptyValue:${dedupFields}`,
+`rowKey ${named} is missing on ${missing} of ${rows.length} rows; the first such row has: ${present}. `
++'Rows without a key value collapse onto one key, so selection, edits and rows.apply updates land on '
++'whichever row now shares it. Set rowKey to a field present on every row, or fix the source data.',
+);
+}
+function groupPathKey(path){
+return compositeKey(path);
+}
+function splitPathKey(key){
+return key.split(SEP);
+}
+});
 __def("packages/modules/data-router/devtools.js",function(__exports,__req){
 'use strict';
 Object.defineProperty(__exports,"mountRouterDevtools",{enumerable:true,get:function(){return mountRouterDevtools;}});
@@ -1629,8 +1803,10 @@ const warnOnce=__m0["warnOnce"];
 const __m1=__req("packages/core/src/source/pushdown.js");
 const planQuery=__m1["planQuery"];
 const capabilitiesOf=__m1["capabilitiesOf"];
-const __m2=__req("packages/modules/data-router/devtools.js");
-const mountRouterDevtools=__m2["mountRouterDevtools"];
+const __m2=__req("packages/core/src/model/rowkey.js");
+const compositeKey=__m2["compositeKey"];
+const __m3=__req("packages/modules/data-router/devtools.js");
+const mountRouterDevtools=__m3["mountRouterDevtools"];
 function resolver(spec,fallback){
 if(typeof spec==='function')return spec;
 if(typeof spec==='string')return(row)=>row[spec];
@@ -1683,6 +1859,8 @@ const maxLag=(Number.isFinite(spec.maxLag)&&spec.maxLag>=0)?Math.floor(Number(sp
 if(minInterval===0&&sample===1&&maxLag===null)return null;
 return{minInterval,sample,maxLag};
 }
+let routeSeq=0;
+function nextRouteId(){routeSeq+=1;return`r${routeSeq}`;}
 function grouper(groupBy){
 const specs=Array.isArray(groupBy)?groupBy:[groupBy];
 const parts=specs.map((s)=>({name:typeof s==='string'?s:null,get:resolver(s,()=>undefined)}));
@@ -1694,7 +1872,7 @@ const v=part.get(row);
 vals.push(v);
 if(part.name)fields[part.name]=v;
 }
-return{key:vals.map((v)=>String(v)).join('\u0001'),fields};
+return{key:compositeKey(vals),fields};
 };
 }
 function aggregateOne(spec,rows){
@@ -1863,10 +2041,25 @@ return fallbackRoute?[fallbackRoute]:[];
 };
 const applyChange=(route,change)=>{
 if(change.add.length||change.update.length||change.remove.length){
-route.sink(change);
+const result=route.sink(change);
+warnRejectedRemovals(route,result);
 }
 return{added:change.add.length,updated:change.update.length,removed:change.remove.length};
 };
+const warnRejectedRemovals=(route,result)=>{
+const rejected=(result)?.rejected;
+if(!Array.isArray(rejected)||!rejected.length)return;
+const removals=rejected.filter((r)=>r&&r.operation==='remove');
+if(!removals.length)return;
+const name=route.label||`route ${route.routeId}`;
+warnOnce(
+`data-router:remove-rejected:${route.routeId}`,
+`route "${name}" asked its target to remove ${removals.length} row(s) the target does not have`
++` (for example ${JSON.stringify(String(removals[0].id))}). The rows are still on screen.`
++' This is a key mismatch: the key the route derives for a row is not the key the grid derives'
++' for it. Check that the route\'s `rowKey` names the same value as the grid\'s.',
+);
+};
 const passes=(route,row)=>{
 for(const link of links){
 if(link.to!==route.grid)continue;
@@ -1904,7 +2097,9 @@ shown=new Map(summaries.map((s)=>[s.gkey,s.row]));
 let rows=kept;
 if(route.sort)rows=rows.slice().sort(route.sort);
 shown=new Map();
-for(const row of rows)shown.set(String(route.keyOf(row)),route.transform?route.transform(row):row);
+for(const row of rows){
+shown.set(compositeKey([route.keyOf(row)]),route.transform?route.transform(row):row);
+}
 }
 const add=[];
 const update=[];
@@ -2053,6 +2248,7 @@ return()=>{};
 };
 const makeRoute=(grid,match,o)=>({
 grid,
+routeId:nextRouteId(),
 sink:targetSink(grid),
 match,
 keyOf:resolver(assertRowKeySpec(o.rowKey,'routes'),defaultKeyOf),

package/modules/data-router.min.cjs

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.67.0, data-router module
+ * Lattice Grid 1.68.0, data-router module
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -54,12 +54,12 @@ Object.defineProperty(__exports,"frameBatched",{enumerable:true,get:function(){r
 Object.defineProperty(__exports,"settleDebounce",{enumerable:true,get:function(){return settleDebounce;}});
 Object.defineProperty(__exports,"whenIdle",{enumerable:true,get:function(){return whenIdle;}});
 Object.defineProperty(__exports,"uid",{enumerable:true,get:function(){return uid;}});
-const STAMPED_VERSION="1.67.0";
+const STAMPED_VERSION="1.68.0";
 async function resolveVersion(){
 if(STAMPED_VERSION!=='0.0.0-source')return STAMPED_VERSION;
 return STAMPED_VERSION;
 }
-const VERSION="1.67.0";
+const VERSION="1.68.0";
 const warned=new Set();
 const WARNED_LIMIT=2000;
 function rememberWarned(key){
@@ -1546,6 +1546,180 @@ grandTotals:()=>lastGrand,
 };
 }
 });
+__def("packages/core/src/model/rowkey.js",function(__exports,__req){
+'use strict';
+Object.defineProperty(__exports,"KEY_DEPENDENT_FEATURES",{enumerable:true,get:function(){return KEY_DEPENDENT_FEATURES;}});
+Object.defineProperty(__exports,"compositeKey",{enumerable:true,get:function(){return compositeKey;}});
+Object.defineProperty(__exports,"createRowKey",{enumerable:true,get:function(){return createRowKey;}});
+Object.defineProperty(__exports,"warnMissingKeys",{enumerable:true,get:function(){return warnMissingKeys;}});
+Object.defineProperty(__exports,"groupPathKey",{enumerable:true,get:function(){return groupPathKey;}});
+Object.defineProperty(__exports,"splitPathKey",{enumerable:true,get:function(){return splitPathKey;}});
+const __m0=__req("packages/core/src/internal/util.js");
+const warnOnce=__m0["warnOnce"];
+const pathGetter=__m0["pathGetter"];
+const isFunction=__m0["isFunction"];
+const isBlank=__m0["isBlank"];
+const KEY_DEPENDENT_FEATURES=[
+'changes (rows.apply / rows.queue)',
+'streaming dedupe',
+'selection persistence',
+'remote reload',
+'cell comments',
+];
+const SEP='\u001f';
+function part(value){
+if(value===null)return'\u0000n';
+if(value===undefined)return'\u0000u';
+const t=typeof value;
+if(t==='string')return value;
+if(t==='number'||t==='bigint'||t==='boolean')return String(value);
+if(value instanceof Date)return`\u0000d${value.getTime()}`;
+try{
+return`\u0000o${JSON.stringify(value)}`;
+}catch{
+return'\u0000o?';
+}
+}
+function compositeKey(parts){
+if(parts.length===1)return part(parts[0]);
+let out='';
+for(let i=0;i<parts.length;i++){
+if(i)out+=SEP;
+out+=part(parts[i]);
+}
+return out;
+}
+function createRowKey(spec,opts={}){
+const warn=opts.warn!==false;
+if(isFunction(spec)){
+const fn=(spec);
+return{
+stable:true,
+fields:[],
+disabled:[],
+key(data,index){
+try{
+const value=fn(data);
+return Array.isArray(value)?compositeKey(value):part(value);
+}catch(err){
+warnOnce('rowKey.throw','rowKey function threw; falling back to index identity for the affected rows.',err);
+return`#${index??-1}`;
+}
+},
+keyEmpty(data){
+try{
+const value=fn(data);
+return Array.isArray(value)?value.length===0||value.some(isBlank):isBlank(value);
+}catch{
+return false;
+}
+},
+missingFields(){return[];},
+};
+}
+if(Array.isArray(spec)&&spec.length>0){
+const fields=spec.filter((f)=>typeof f==='string');
+const getters=fields.map((f)=>pathGetter(f));
+const n=getters.length;
+return{
+stable:true,
+fields,
+disabled:[],
+key(data){
+const parts=new Array(n);
+for(let i=0;i<n;i++)parts[i]=getters[i](data);
+return compositeKey(parts);
+},
+keyEmpty(data){
+for(let i=0;i<n;i++)if(isBlank(getters[i](data)))return true;
+return false;
+},
+missingFields(data){
+const out=[];
+for(let i=0;i<n;i++)if(isBlank(getters[i](data)))out.push(fields[i]);
+return out;
+},
+};
+}
+if(typeof spec==='string'&&spec.length>0){
+const get=pathGetter(spec);
+return{
+stable:true,
+fields:[spec],
+disabled:[],
+key(data){
+return part(get(data));
+},
+keyEmpty(data){
+return isBlank(get(data));
+},
+missingFields(data){
+return isBlank(get(data))?[spec]:[];
+},
+};
+}
+if(warn){
+warnOnce(
+'rowKey.missing',
+`no rowKey configured, so rows are identified by object identity. This disables: ${KEY_DEPENDENT_FEATURES.join(', ')}. Set rowKey to a field name, an array of field names, or a function.`,
+);
+}
+return{
+stable:false,
+fields:[],
+disabled:KEY_DEPENDENT_FEATURES.slice(),
+key(data,index){
+if(data===null||typeof data!=='object'){
+return`#${index??0}:${String(data)}`;
+}
+let assigned=autoKeys.get(data);
+if(assigned===undefined){
+assigned=`#${autoKeySeq++}`;
+autoKeys.set(data,assigned);
+}
+return assigned;
+},
+};
+}
+const autoKeys=new WeakMap();
+let autoKeySeq=0;
+function warnMissingKeys(resolver,rows){
+if(!resolver||resolver.stable===false||!isFunction(resolver.keyEmpty))return;
+if(!Array.isArray(rows)||rows.length===0)return;
+let missing=0;
+let sampleFields=null;
+let sampleData;
+for(let i=0;i<rows.length;i++){
+const data=rows[i];
+if(!resolver.keyEmpty(data))continue;
+missing++;
+if(sampleFields===null){
+sampleFields=isFunction(resolver.missingFields)?resolver.missingFields(data):[];
+sampleData=data;
+}
+}
+if(missing===0)return;
+const dedupFields=resolver.fields.length?resolver.fields.join(','):'(function)';
+const named=sampleFields&&sampleFields.length
+?sampleFields.join(', ')
+:(resolver.fields.length?resolver.fields.join(', '):'the rowKey function');
+const present=sampleData!==null&&typeof sampleData==='object'
+?(Object.keys((sampleData)).join(', ')||'(no fields)')
+:String(sampleData);
+warnOnce(
+`rowKey.emptyValue:${dedupFields}`,
+`rowKey ${named} is missing on ${missing} of ${rows.length} rows; the first such row has: ${present}. `
++'Rows without a key value collapse onto one key, so selection, edits and rows.apply updates land on '
++'whichever row now shares it. Set rowKey to a field present on every row, or fix the source data.',
+);
+}
+function groupPathKey(path){
+return compositeKey(path);
+}
+function splitPathKey(key){
+return key.split(SEP);
+}
+});
 __def("packages/modules/data-router/devtools.js",function(__exports,__req){
 'use strict';
 Object.defineProperty(__exports,"mountRouterDevtools",{enumerable:true,get:function(){return mountRouterDevtools;}});
@@ -1631,8 +1805,10 @@ const warnOnce=__m0["warnOnce"];
 const __m1=__req("packages/core/src/source/pushdown.js");
 const planQuery=__m1["planQuery"];
 const capabilitiesOf=__m1["capabilitiesOf"];
-const __m2=__req("packages/modules/data-router/devtools.js");
-const mountRouterDevtools=__m2["mountRouterDevtools"];
+const __m2=__req("packages/core/src/model/rowkey.js");
+const compositeKey=__m2["compositeKey"];
+const __m3=__req("packages/modules/data-router/devtools.js");
+const mountRouterDevtools=__m3["mountRouterDevtools"];
 function resolver(spec,fallback){
 if(typeof spec==='function')return spec;
 if(typeof spec==='string')return(row)=>row[spec];
@@ -1685,6 +1861,8 @@ const maxLag=(Number.isFinite(spec.maxLag)&&spec.maxLag>=0)?Math.floor(Number(sp
 if(minInterval===0&&sample===1&&maxLag===null)return null;
 return{minInterval,sample,maxLag};
 }
+let routeSeq=0;
+function nextRouteId(){routeSeq+=1;return`r${routeSeq}`;}
 function grouper(groupBy){
 const specs=Array.isArray(groupBy)?groupBy:[groupBy];
 const parts=specs.map((s)=>({name:typeof s==='string'?s:null,get:resolver(s,()=>undefined)}));
@@ -1696,7 +1874,7 @@ const v=part.get(row);
 vals.push(v);
 if(part.name)fields[part.name]=v;
 }
-return{key:vals.map((v)=>String(v)).join('\u0001'),fields};
+return{key:compositeKey(vals),fields};
 };
 }
 function aggregateOne(spec,rows){
@@ -1865,10 +2043,25 @@ return fallbackRoute?[fallbackRoute]:[];
 };
 const applyChange=(route,change)=>{
 if(change.add.length||change.update.length||change.remove.length){
-route.sink(change);
+const result=route.sink(change);
+warnRejectedRemovals(route,result);
 }
 return{added:change.add.length,updated:change.update.length,removed:change.remove.length};
 };
+const warnRejectedRemovals=(route,result)=>{
+const rejected=(result)?.rejected;
+if(!Array.isArray(rejected)||!rejected.length)return;
+const removals=rejected.filter((r)=>r&&r.operation==='remove');
+if(!removals.length)return;
+const name=route.label||`route ${route.routeId}`;
+warnOnce(
+`data-router:remove-rejected:${route.routeId}`,
+`route "${name}" asked its target to remove ${removals.length} row(s) the target does not have`
++` (for example ${JSON.stringify(String(removals[0].id))}). The rows are still on screen.`
++' This is a key mismatch: the key the route derives for a row is not the key the grid derives'
++' for it. Check that the route\'s `rowKey` names the same value as the grid\'s.',
+);
+};
 const passes=(route,row)=>{
 for(const link of links){
 if(link.to!==route.grid)continue;
@@ -1906,7 +2099,9 @@ shown=new Map(summaries.map((s)=>[s.gkey,s.row]));
 let rows=kept;
 if(route.sort)rows=rows.slice().sort(route.sort);
 shown=new Map();
-for(const row of rows)shown.set(String(route.keyOf(row)),route.transform?route.transform(row):row);
+for(const row of rows){
+shown.set(compositeKey([route.keyOf(row)]),route.transform?route.transform(row):row);
+}
 }
 const add=[];
 const update=[];
@@ -2055,6 +2250,7 @@ return()=>{};
 };
 const makeRoute=(grid,match,o)=>({
 grid,
+routeId:nextRouteId(),
 sink:targetSink(grid),
 match,
 keyOf:resolver(assertRowKeySpec(o.rowKey,'routes'),defaultKeyOf),