HF-161: document OFFSET function limitations

[marcin-kordas-hoc]

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").

Note on PR routing: this PR replaces #1662 which was opened from a fork branch. Same content, same SHA (dac40aebe28435f181b56257fe1964c4266574b6), 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 — Docs: describe limitations of the OFFSET function
• Tracks the dynamic-args follow-up: #910
• Out of scope (separate task): #943 — restructuring known-limitations / list-of-differences / specifications-and-limits pages
• Internal spec / tech rationale / implementation plan: tracked in the team workspace (not committed); summary in this PR description
• Supersedes: HF-161: document OFFSET function limitations #1662

Limits documented

1. First argument must be a single-cell reference (passing a range = parser error)
2. Row/column/height/width arguments must be static integer literals (parser error otherwise)
3. Height and width must be positive integers
4. Result outside sheet evaluates to #REF!
5. getCellFormula returns the resolved reference, not the original =OFFSET(...)
6. Architectural rationale: OFFSET is rewritten at parse time, so it does not appear in getRegisteredFunctionNames and the resolved reference is what getCellFormula returns

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
• Manual: npm run docs:dev and visit /guide/known-limitations to verify the new sub-section renders, including the four embedded js code blocks
• Manual: visit /guide/list-of-differences to confirm 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.

---

Note

Low Risk
Docs-only changes; no runtime behavior, APIs, or data handling are modified.

Overview
Adds a canonical ### OFFSET function subsection to docs/guide/known-limitations.md, explaining that OFFSET is resolved at parse time and documenting the resulting constraints (single-cell first arg, static integer shift/size args, positive height/width, #REF! when out of bounds, and getCellFormula returning the rewritten reference), with small code examples.

Removes the now-superseded single-row OFFSET entry from docs/guide/list-of-differences.md so the limitation is documented in one place.

^{Reviewed by Cursor Bugbot for commit 8b0b936. Bugbot is set up for automated code reviews on this repo. Configure here.}

[qunabu]

Task linked: HF-161 Document limitations of the OFFSET function

[netlify]

✅ Deploy Preview for hyperformula-docs ready!

Name	Link
🔨 Latest commit	8b0b936
🔍 Latest deploy log	https://app.netlify.com/projects/hyperformula-docs/deploys/69f1d9f8698e2f0008279b97
😎 Deploy Preview	https://deploy-preview-1666--hyperformula-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[github-actions]

Performance comparison of head (8b0b936) vs base (8b525cb)

                                     testName |   base |   head | change
------------------------------------------------------------------------
                                      Sheet A | 504.21 | 497.05 | -1.42%
                                      Sheet B | 160.31 | 161.62 | +0.82%
                                      Sheet T | 140.99 | 141.09 | +0.07%
                                Column ranges | 475.81 | 465.71 | -2.12%
Sheet A:  change value, add/remove row/column |  15.12 |  13.95 | -7.74%
 Sheet B: change value, add/remove row/column | 134.32 | 124.59 | -7.24%
                   Column ranges - add column | 149.54 | 140.32 | -6.17%
                Column ranges - without batch | 442.73 |  425.9 | -3.80%
                        Column ranges - batch |  113.4 | 110.56 | -2.50%

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.18%. Comparing base (8b525cb) to head (8b0b936).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #1666   +/-   ##
========================================
  Coverage    97.18%   97.18%           
========================================
  Files          174      174           
  Lines        15086    15086           
  Branches      3223     3223           
========================================
  Hits         14662    14662           
  Misses         424      424           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.