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	9be0229
🔍 Latest deploy log	https://app.netlify.com/projects/hyperformula-dev-docs/deploys/6a1ec3c3aadcfe000859ae5c
😎 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 (9be0229) vs base (00e5c73)

                                     testName |   base |   head | change
------------------------------------------------------------------------
                                      Sheet A | 473.35 | 467.06 | -1.33%
                                      Sheet B | 148.94 | 151.47 | +1.70%
                                      Sheet T | 135.03 |  136.2 | +0.87%
                                Column ranges | 527.98 | 535.39 | +1.40%
Sheet A:  change value, add/remove row/column |  15.08 |  14.92 | -1.06%
 Sheet B: change value, add/remove row/column | 126.24 | 128.94 | +2.14%
                   Column ranges - add column | 160.38 | 154.78 | -3.49%
                Column ranges - without batch | 483.93 | 453.93 | -6.20%
                        Column ranges - batch |  121.1 | 117.08 | -3.32%