HF-161: document OFFSET function limitations (#1666)

## Summary

Adds a single canonical `### OFFSET function` sub-section under `##
Nuances of the implemented functions` in
`docs/guide/known-limitations.md`. Documents all six behavioral limits
of the OFFSET function in HyperFormula, each backed either by an
existing test in `unit/parser/offset-translation.spec.ts` or by a
runtime check captured before this PR was opened.

Removes the now-superseded one-row OFFSET entry from
`docs/guide/list-of-differences.md` (per Kuba's decision in the
2026-04-21 meeting: *"można wtedy to stąd też usunąć. Żeby wszystko było
tam jednak"*). The HF-vs-Excel/Sheets behavioral differences for OFFSET
are not lost — they remain documented in full in `known-limitations.md`
under the new sub-section, which is the canonical place for parse-time
restrictions per the 04-21 decision to consolidate.

> **Note on PR routing**: this PR replaces #1662 which was opened from a
fork branch. Same content, now from upstream branch — CI will have full
access (no fork-PR DEPLOY_TOKEN issue). Closing #1662 in favor of this
one.

## Linked

- Closes
[#1572](#1572) —
*Docs: describe limitations of the OFFSET function*
- Tracks the dynamic-args follow-up:
[#910](#910)
- Out of scope (separate task):
[#943](#943) —
restructuring `known-limitations` / `list-of-differences` /
`specifications-and-limits` pages
- Unblocked by:
[handsontable/hyperformula-tests#12](handsontable/hyperformula-tests#12)
(merged 2026-05-14, cleared lint regression introduced by #1672)
- Internal spec / tech rationale / implementation plan: tracked in the
team workspace (not committed); summary in this PR description
- Supersedes: #1662

## Limits documented

1. First argument must be a single-cell reference (passing a range =
parser error stored as cell value)
2. Row/column/height/width arguments must be static integer literals
(parser error otherwise)
3. Height and width must be **bare** positive integer literals —
`NUMBER` AST nodes only (unary `+`, parens, non-integers, values <1 all
rejected at parse time)
4. Out-of-sheet target → `#REF!` error stored at parse time (not
evaluation time), with the message *Resulting reference is out of the
sheet*
5. `getCellFormula` returns the resolved reference, not the original
`=OFFSET(...)`
6. Architectural rationale: OFFSET is rewritten at parse time into a
plain cell reference, so introspection via `getCellFormula` shows the
resolved reference rather than the call

## Runtime verification

All six limits were verified against this branch's HEAD before
publishing:

```
A. OFFSET in registered names: false  (correct — OFFSET is parse-time, not registered)
B. getCellFormula recovers: "=B1"     (rewritten reference, NOT "=OFFSET(A1, 0, 1)")
C. Out-of-sheet value: { value: "#REF!", message: "Resulting reference is out of the sheet." }
```

Tests covering all six limits live in
`test/hyperformula-tests/unit/parser/offset-translation.spec.ts` (24
tests, lines 13–206 in the private repo). Run via `npm run test:jest --
--testPathPattern="offset-translation"`.

## Test plan

- [ ] CI green on `handsontable/hyperformula`
- [ ] Netlify deploy preview:
[`/guide/known-limitations`](https://deploy-preview-1666--hyperformula-dev-docs.netlify.app/docs/guide/known-limitations.html)
— verify the new `### OFFSET function` sub-section renders, including
the four embedded `js` code blocks
- [ ] Netlify deploy preview:
[`/guide/list-of-differences`](https://deploy-preview-1666--hyperformula-dev-docs.netlify.app/docs/guide/list-of-differences.html)
— verify the table is intact and the OFFSET row is gone

## Notes

- This is docs-only — no CHANGELOG entry per project convention.
- The internal `ErrorMessage.OutOfSheet` string is intentionally NOT
quoted verbatim in the docs; the bullet describes the behavior instead,
so future internal-string refactors don't break the docs.
- Post-Codex review (2026-05-14): wording clarified to distinguish
parser-error-as-cell-value vs API exception, and to specify that
height/width accept only bare `NUMBER` literals (unary `+` etc.
rejected).

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Low risk docs-only change; the main risk is confusing users if the
newly documented OFFSET constraints are inaccurate or drift from
implementation.
> 
> **Overview**
> Adds a canonical **`### OFFSET function`** section to
`docs/guide/known-limitations.md` describing HyperFormula’s parse-time
rewriting behavior and the resulting constraints (single-cell first arg,
static integer shifts/sizes, strict positive literal height/width,
out-of-sheet `#REF!` at parse time, and `getCellFormula` returning the
resolved reference), with small JS snippets.
> 
> Removes the now-redundant `OFFSET` row from
`docs/guide/list-of-differences.md` to consolidate documentation in one
place.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
67ad2cd. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Kuba Sekowski <jakub.sekowski@handsontable.com>

Author: marcin-kordas-hoc

docs/guide/known-limitations.md

@@ -38,3 +38,37 @@ you can't compare the arguments in a formula like this:
 * The INDEX function doesn't support returning whole rows or columns of the source range – it always returns the contents of a single cell.
 * The FILTER function accepts either single rows of equal width or single columns of equal height. In other words, all arrays passed to the FILTER function must have equal dimensions, and at least one of those dimensions must be 1.
 * Array-producing functions (e.g., SEQUENCE, FILTER) require their output dimensions to be determinable at parse time. Passing cell references or formulas as dimension arguments (e.g., `=SEQUENCE(A1)`) results in a `#VALUE!` error, because the output size cannot be resolved before evaluation.
+
+### OFFSET function
+
+HyperFormula resolves the OFFSET function at parse time rather than during evaluation. The parser inspects the arguments and rewrites the expression into a plain cell reference or range. This keeps the dependency graph accurate but imposes several restrictions.
+
+* The first argument must be a reference to a single cell. Passing a range causes the cell to store a parser error (the API call itself does not throw — read the error via `getCellValue`).
+
+  ```js
+  // Cell A1 stores a parser error — the first argument must be a single cell, not a range
+  hf.setCellContents({ sheet: 0, row: 0, col: 0 }, '=OFFSET(A1:B1, 0, 0)');
+  ```
+
+* The row-shift, column-shift, height, and width arguments must be static integer literals known at parse time. Cell references and formulas passed as shift or size arguments cause the cell to store a parser error.
+
+  ```js
+  // Cell A1 stores a parser error — the row-shift argument must be a static integer literal
+  hf.setCellContents({ sheet: 0, row: 0, col: 0 }, '=OFFSET(A1, C3, 0)');
+  ```
+
+* The height and width arguments must be bare positive integer literals (the parser accepts only `NUMBER` AST nodes). Unary `+` prefixes, parenthesised expressions, values less than 1, and non-integer values are rejected at parse time.
+
+* When the computed target falls outside the sheet, the parser stores a `#REF!` error in the cell at parse time (rather than during evaluation) with the message *Resulting reference is out of the sheet*.
+
+  ```js
+  // Cell A1 stores #REF!
+  hf.setCellContents({ sheet: 0, row: 0, col: 0 }, '=OFFSET(A1, -1, 0)');
+  ```
+
+* OFFSET is resolved at parse time, so `getCellFormula` returns the computed reference, not the original `OFFSET` call.
+
+  ```js
+  const hf = HyperFormula.buildFromArray([[1, 45, '=OFFSET(A1, 0, 1)']]);
+  hf.getCellFormula({ sheet: 0, row: 0, col: 2 }); // '=B1'
+  ```

docs/guide/list-of-differences.md

@@ -35,7 +35,6 @@ See a full list of differences between HyperFormula, Microsoft Excel, and Google
 | TIMEVALUE function                                 | =TIMEVALUE("14:31")                                                       | Type of the returned value: `CellValueDetailedType.NUMBER_TIME` (compliant with the [OpenDocument](https://docs.oasis-open.org/office/OpenDocument/v1.3/os/part4-formula/OpenDocument-v1.3-os-part4-formula.html) standard)                                                                                                                                  | Cell auto-formatted as **regular number**                                                                                      | Cell auto-formatted as **regular number**                                                                                      |
 | EDATE function                                     | =EDATE(DATE(2019, 7, 31), 1)                                              | Type of the returned value: `CellValueDetailedType.NUMBER_DATE`. This is non-compliant with the [OpenDocument](https://docs.oasis-open.org/office/OpenDocument/v1.3/os/part4-formula/OpenDocument-v1.3-os-part4-formula.html) standard, which defines the return type as a Number, while describing it as a Date serial number through the function summary. | Cell auto-formatted as **date**                                                                                                | Cell auto-formatted as **regular number**                                                                                      |
 | EOMONTH function                                   | =EOMONTH(DATE(2019, 7, 31), 1)                                            | Type of the returned value: `CellValueDetailedType.NUMBER_DATE`. This is non-compliant with the [OpenDocument](https://docs.oasis-open.org/office/OpenDocument/v1.3/os/part4-formula/OpenDocument-v1.3-os-part4-formula.html) standard, which defines the return type as a Number, while describing it as a Date serial number through the function summary. | Cell auto-formatted as **date**                                                                                                | Cell auto-formatted as **regular number**                                                                                      |
-| OFFSET function                                    | =OFFSET(A1:B1, 0, 0)                                                      | First parameter must be a **reference to a single cell**.                                                                                                                                                                                                                                                                                                    | First parameter may be a single cell or a range.                                                                               | First parameter may be a single cell or a range.                                                                               |
 
 ## Built-in functions