From 45325a38213cabe0688c1c7806c7c72b2d20c3fb Mon Sep 17 00:00:00 2001 From: AMBudnik Date: Fri, 28 Aug 2026 11:21:14 +0200 Subject: [PATCH 1/3] docs(guide): named columns vs structured references (SU-637) Co-authored-by: Cursor --- docs/guide/cell-references.md | 2 +- docs/guide/named-expressions.md | 23 +++++++++++++++++++++++ 2 files changed, 24 insertions(+), 1 deletion(-) diff --git a/docs/guide/cell-references.md b/docs/guide/cell-references.md index edd88ebdf..5fcd811e1 100644 --- a/docs/guide/cell-references.md +++ b/docs/guide/cell-references.md @@ -204,7 +204,7 @@ You can reference ranges: The following restraints apply: - You can't mix two different types of range references together (=A1:B). -- Range expressions can't contain [named expressions](/guide/named-expressions.md). +- Range expressions can't contain [named expressions](/guide/named-expressions.md) (`=Name_1:Name_5` is a parse error). To name a whole column, see [Named columns](/guide/named-expressions.md#named-columns). - At the moment, HyperFormula doesn't support multi-cell range references (=A1:B2:C3). ::: tip diff --git a/docs/guide/named-expressions.md b/docs/guide/named-expressions.md index 580fad691..2ba7eb713 100644 --- a/docs/guide/named-expressions.md +++ b/docs/guide/named-expressions.md @@ -4,6 +4,8 @@ tags: - global scope - variables - named constants + - named columns + - structured references - addNamedExpression - changeNamedExpression - removeNamedExpression @@ -83,6 +85,7 @@ For examples of valid and invalid expression names, see the following table: | ASP.NET | Valid | | A1 | Invalid | | $A$1 | Invalid | +| Name1 | Invalid | | RC | Invalid | ## Using named expressions in formulas @@ -114,6 +117,26 @@ When array arithmetic is enabled (`useArrayArithmetic: true`), named ranges stil - A bare `=myRange + 1` does not spill — it returns a `#VALUE!` error rather than producing one result per element. - Inside an aggregate the operator becomes element-wise. `=SUM(myRange + 1)` adds 1 to every element and then sums, so for `myRange` covering values `1..5` it returns `20` (`SUM(2, 3, 4, 5, 6)`), not the single reduced value of the default mode. +## Named columns + +HyperFormula does not support Excel-style structured references such as `Table[Column]`, and it does not treat column headers as formula addresses. A formula like `=SUM(Name1:Name5)` is not a reference to columns named Name1 and Name5. + +Two separate problems often get stacked in that example: + +1. **Illegal name.** `Name1` matches A1 notation (column NAME, row 1), so it cannot be registered as a named expression. Use `ColSales` or `Name_1` instead. See [Naming rules](#naming-rules). +2. **Range operator.** `:` does not accept named expressions as endpoints. Even with legal names, `Name_1:Name_5` is a parse error. See [Range restraints](cell-references.md#range-restraints). + +To address a column by name, register a named expression that points at the column (or at the data range), then use that name in the formula: + +```javascript +hfInstance.addNamedExpression('ColSales', '=Sheet1!$A:$A'); +hfInstance.setCellContents({ sheet: 0, col: 2, row: 0 }, [['=SUM(ColSales)']]); +``` + +- The address inside the named expression must be **absolute** (`$A:$A` or `Sheet1!$A:$A`). Relative `A:A` is not allowed. +- If row 1 is a header, `$A:$A` includes it. For data only, use `$A$2:$A`. +- Do not put header text in the formula. Map each header to a named expression in application code. + ## Available methods These are the basic methods that can be used to add and manipulate named From d866dc15daca76699a98746b0938d2fd1a0767bc Mon Sep 17 00:00:00 2001 From: AMBudnik Date: Fri, 28 Aug 2026 11:47:22 +0200 Subject: [PATCH 2/3] docs(guide): drop redundant named-columns search tag Co-authored-by: Cursor --- docs/guide/named-expressions.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/guide/named-expressions.md b/docs/guide/named-expressions.md index 2ba7eb713..1719caf55 100644 --- a/docs/guide/named-expressions.md +++ b/docs/guide/named-expressions.md @@ -4,7 +4,6 @@ tags: - global scope - variables - named constants - - named columns - structured references - addNamedExpression - changeNamedExpression From 23fa97faabceb7fd3fb3910eca806d5cc71244a4 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 28 Aug 2026 15:11:10 +0000 Subject: [PATCH 3/3] docs: restructure named columns section - show solution first Co-authored-by: Kuba Sekowski --- docs/guide/named-expressions.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/guide/named-expressions.md b/docs/guide/named-expressions.md index 1719caf55..99249cb25 100644 --- a/docs/guide/named-expressions.md +++ b/docs/guide/named-expressions.md @@ -118,13 +118,6 @@ When array arithmetic is enabled (`useArrayArithmetic: true`), named ranges stil ## Named columns -HyperFormula does not support Excel-style structured references such as `Table[Column]`, and it does not treat column headers as formula addresses. A formula like `=SUM(Name1:Name5)` is not a reference to columns named Name1 and Name5. - -Two separate problems often get stacked in that example: - -1. **Illegal name.** `Name1` matches A1 notation (column NAME, row 1), so it cannot be registered as a named expression. Use `ColSales` or `Name_1` instead. See [Naming rules](#naming-rules). -2. **Range operator.** `:` does not accept named expressions as endpoints. Even with legal names, `Name_1:Name_5` is a parse error. See [Range restraints](cell-references.md#range-restraints). - To address a column by name, register a named expression that points at the column (or at the data range), then use that name in the formula: ```javascript @@ -136,6 +129,15 @@ hfInstance.setCellContents({ sheet: 0, col: 2, row: 0 }, [['=SUM(ColSales)']]); - If row 1 is a header, `$A:$A` includes it. For data only, use `$A$2:$A`. - Do not put header text in the formula. Map each header to a named expression in application code. +### Why SUM(Name1:Name5) does not work + +HyperFormula does not support Excel-style structured references such as `Table[Column]`, and it does not treat column headers as formula addresses. A formula like `=SUM(Name1:Name5)` is not a reference to columns named Name1 and Name5. + +Two separate problems often get stacked in that example: + +1. **Illegal name.** `Name1` matches A1 notation (column NAME, row 1), so it cannot be registered as a named expression. Use `ColSales` or `Name_1` instead. See [Naming rules](#naming-rules). +2. **Range operator.** `:` does not accept named expressions as endpoints. Even with legal names, `Name_1:Name_5` is a parse error. See [Range restraints](cell-references.md#range-restraints). + ## Available methods These are the basic methods that can be used to add and manipulate named