You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Since #35, columnHeader/rowHeader: true persists sheet as records keyed by whatever text is literally in the sheet's header row/column. That's fine when the uploaded file's header text is exactly what you want as the JSON key, but it breaks down when:
The sheet's header wording is inconsistent across uploads/template revisions (extra whitespace, punctuation, casing) — the persisted key drifts with it, and anything addressing it (e.g. a ComputedControl reading sheet.<key>) silently breaks.
The desired persisted key isn't a good display label, or vice versa (e.g. a schema author wants the stable key metric but the sheet legitimately says "Metrics" for a human).
The schema author wants to name columns explicitly rather than trusting whatever's in row 1/column A of whatever gets uploaded.
What's needed
Let columnHeader/rowHeader optionally be an array of {id, label?} instead of only a boolean, matched positionally to the sheet's columns/rows (array order = column/row order) — a backward-compatible union type, since the existing boolean form keeps working exactly as today:
id is always the persisted record key (stable, author-controlled, independent of the sheet's actual text).
label, if given, is presumably what the preview table shows as the column/row header; falling back to the sheet's own text or to id when omitted is an open question (see below).
columnHeader: true (today's behavior) stays exactly as-is: derive both the key and the display label from the sheet's own header text.
Open questions to resolve during design
Length mismatch. What happens when the array is shorter than the sheet's actual column/row count (extra data columns with no configured id), or longer (configured ids with no corresponding column)? Silently ignore the excess either direction, or surface an error/warning?
Does label drive the preview only, or does it also gate the sheet's own header text somehow (e.g. validate that row 1 actually says "Metrics" and warn if it doesn't)?
Symmetric for rowHeader too — same array-of-{id,label} shape, matched positionally to the sheet's rows via column A. Should both flags support this the same way, or could it start as columnHeader-only and add rowHeader later?
Does this want its own new x-spreadsheet field (e.g. columnKeys) instead of overloading columnHeader's type, to avoid a boolean-vs-array runtime type-check on every read? Worth weighing against the "reuse the existing flag" framing above.
utils/spreadsheet/process.ts (shapeSheet, rowsToRecords, columnsToRecords) — where the header-row/column key extraction currently happens and would need to branch on the boolean-vs-array shape.
docs/spreadsheet-value-shape.md — would need updating alongside whatever's implemented here.
Problem
Since #35,
columnHeader/rowHeader: truepersistssheetas records keyed by whatever text is literally in the sheet's header row/column. That's fine when the uploaded file's header text is exactly what you want as the JSON key, but it breaks down when:ComputedControlreadingsheet.<key>) silently breaks.metricbut the sheet legitimately says "Metrics" for a human).What's needed
Let
columnHeader/rowHeaderoptionally be an array of{id, label?}instead of only a boolean, matched positionally to the sheet's columns/rows (array order = column/row order) — a backward-compatible union type, since the existingbooleanform keeps working exactly as today:idis always the persisted record key (stable, author-controlled, independent of the sheet's actual text).label, if given, is presumably what the preview table shows as the column/row header; falling back to the sheet's own text or toidwhen omitted is an open question (see below).columnHeader: true(today's behavior) stays exactly as-is: derive both the key and the display label from the sheet's own header text.Open questions to resolve during design
labeldrive the preview only, or does it also gate the sheet's own header text somehow (e.g. validate that row 1 actually says "Metrics" and warn if it doesn't)?rowHeadertoo — same array-of-{id,label}shape, matched positionally to the sheet's rows via column A. Should both flags support this the same way, or could it start ascolumnHeader-only and addrowHeaderlater?x-spreadsheetfield (e.g.columnKeys) instead of overloadingcolumnHeader's type, to avoid a boolean-vs-array runtime type-check on every read? Worth weighing against the "reuse the existing flag" framing above.References
columnHeader/rowHeader-driven records persistence this extends.utils/spreadsheet/process.ts(shapeSheet,rowsToRecords,columnsToRecords) — where the header-row/column key extraction currently happens and would need to branch on the boolean-vs-array shape.docs/spreadsheet-value-shape.md— would need updating alongside whatever's implemented here.