docs: clarify setRowOrder/setColumnOrder permutation semantics

[sequba]

Context

Fixes #1668. The reporter ran setRowOrder expecting the array argument to mean "previous position for each new row", got the opposite behavior, and was unable to disambiguate from the docs.

Root cause: every example in the JSDoc and guide pages used a self-inverse permutation ([2, 1, 0] on 3 rows, [0, 3, 2, 1] on 4 rows). Self-inverse permutations produce the same output under both of the two natural interpretations of the argument:

• A. newOrder[i] = new position for the row/column currently at index i (this is the actual behavior, verified in mappingFromOrder in src/CrudOperations.ts and Operations.setRowOrder in src/Operations.ts)
• B. newOrder[i] = previous position of the row/column that should end up at index i

So the examples didn't actually demonstrate which interpretation was correct.

Changes

Doc-only. No runtime behavior changed.

• Replaced the self-inverse examples with non-self-inverse cyclic shifts ([1, 2, 0] on a 3-element sheet → result [['C'], ['A'], ['B']]). Under interpretation B the result would have been [['B'], ['C'], ['A']], so the example now visibly reinforces the correct semantics.
• Added explicit prose to the JSDoc and guide pages stating the convention: "the value at index i is the new position for the row/column currently at index i".
• Added a ::: warning callout in the sorting guide explicitly contrasting the correct interpretation with the inverse-permutation interpretation that the reporter assumed.
• Updated the analogous setColumnOrder/isItPossibleToSetColumnOrder documentation for consistency.
• Added a note to DEV_DOCS.md clarifying that documentation-only PRs do not require a CHANGELOG.md entry.

Files touched:

• src/HyperFormula.ts - JSDoc for setRowOrder, isItPossibleToSetRowOrder, setColumnOrder, isItPossibleToSetColumnOrder.
• docs/guide/sorting-data.md - intro paragraph, "Sorting rows" and "Sorting columns" step-by-step sections.
• docs/guide/basic-operations.md - "Reordering rows" and "Reordering columns" subsections.
• DEV_DOCS.md - new "Documentation-only changes" note under "Definition of Done".

Out of scope: swapRowIndexes / swapColumnIndexes use [[source, target], ...] pairs and are already described as "array mapping original positions to final positions"; the ambiguity does not apply, so those are untouched.

How did you test your changes?

• npm run lint - 0 errors (pre-existing warnings in tests are unrelated).
• npm run compile - clean TypeScript compile.
• Read the rendered JSDoc and Markdown by inspection to confirm the new examples and prose are accurate against the verified implementation.

Types of changes

• Breaking change (a fix or a feature because of which an existing functionality doesn't work as expected anymore)
• New feature or improvement (a non-breaking change that adds functionality)
• Bug fix (a non-breaking change that fixes an issue)
• Additional language file, or a change to an existing language file (translations)
• Change to the documentation

Related issues:

1. Fixes [Bug]: Documentation about setRowOrder is unclear #1668

Checklist:

• I have reviewed the guidelines about Contributing to HyperFormula and I confirm that my code follows the code style of this project.
• I have signed the Contributor License Agreement.
• My change is compliant with the OpenDocument standard.
• My change is compatible with Microsoft Excel.
• My change is compatible with Google Sheets.
• I described my changes in the CHANGELOG.md file. (Not required: documentation-only change.)
• My changes require a documentation update.
• My changes require a migration guide.

  

[netlify]

✅ Deploy Preview for hyperformula-dev-docs ready!

Name	Link
🔨 Latest commit	a189ead
🔍 Latest deploy log	https://app.netlify.com/projects/hyperformula-dev-docs/deploys/6a57272de70e8d0008121d9e
😎 Deploy Preview	https://deploy-preview-1687--hyperformula-dev-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.

[sequba]

@cursoragent fix it

[cursor]

Done. Commit ed3abc353 pushed. The note is now a sub-bullet under - changelog entry instead of a separate section:

- changelog entry
  - not required for documentation-only changes (guides, JSDoc, README, etc.)

  

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.16%. Comparing base (00e5c73) to head (9be0229).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #1687   +/-   ##
========================================
  Coverage    97.16%   97.16%           
========================================
  Files          176      176           
  Lines        15322    15322           
  Branches      3356     3356           
========================================
  Hits         14887    14887           
  Misses         427      427           
  Partials         8        8           

Files with missing lines	Coverage Δ
src/HyperFormula.ts	99.73% <ø> (ø)

🚀 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.

[github-actions]

Performance comparison of head (a189ead) vs base (3064a8b)

                                     testName |   base |   head | change
------------------------------------------------------------------------
                                      Sheet A | 490.94 | 492.18 | +0.25%
                                      Sheet B | 159.74 | 157.26 | -1.55%
                                      Sheet T | 141.87 | 139.76 | -1.49%
                                Column ranges | 473.41 | 465.67 | -1.63%
Sheet A:  change value, add/remove row/column |  15.65 |  14.88 | -4.92%
 Sheet B: change value, add/remove row/column | 131.76 | 131.51 | -0.19%
                   Column ranges - add column | 154.48 | 149.59 | -3.17%
                Column ranges - without batch | 450.36 | 452.54 | +0.48%
                        Column ranges - batch | 114.72 | 113.36 | -1.19%

[marcin-kordas-hoc]

LGTM. I verified every example against a live HyperFormula build:

• The documented semantics (newOrder[i] = the new position for the row/column currently at index i) match the implementation (mappingFromOrder yields [i, newOrder[i]], and Operations.setRowOrder moves the row at source=i to target=newOrder[i]).
• All guide + JSDoc examples reproduce exactly, including the changes array contents and ordering: [A,B,C] + [1,2,0] -> [[C],[A],[B]] (rows) / [[C,A,B]] (columns), and the isItPossible... true/false cases.

Using a non-self-inverse permutation ([1,2,0]) is the right call for disambiguating #1668, and nice cleanups on the side (fixing the bare setRowOrder(...)/setColumnOrder(...) calls, dropping the ragged [4,5] data that produced confusing null changes).

One tiny typo inline.

[marcin-kordas-hoc]

Unbalanced parentheses — the opening ( before "not required" is never closed; the ) at the end closes the inner (guides, JSDoc, README, etc.).

Suggested change

	- Changelog entry (not required for documentation-only changes (guides, JSDoc, README, etc.)
	- Changelog entry (not required for documentation-only changes such as guides, JSDoc, README, etc.)