HF-122: Framework integration guides for React, Angular, Vue, Svelte

[marcin-kordas-hoc]

Summary

Expand the four framework integration pages (React, Angular, Vue, Svelte) from one-line redirects into self-contained guides with code snippets extracted from the respective Stackblitz demos.

Each guide's primary snippet is a simplified version of the demo's framework pattern — same lifecycle hooks, same service architecture, same reactivity approach — with simplified data (buildFromArray instead of Employee Table).

Design rationale

Snippets from demos, not invented patterns

Per review feedback: every code snippet must match what's in the corresponding Stackblitz demo. This ensures the snippets are tested, idiomatic, and consistent with what users see when they click the demo link. Patterns not present in demos (e.g., Angular Signals, Svelte 5 runes) are deliberately excluded until validated by a framework expert.

Framework	Demo file	Primary pattern in guide
React	react-demo/src/lib/employee/employee.provider.tsx	useRef + useEffect init/cleanup + useState
Angular	angular-demo/src/app/employees/employees.service.ts	@Injectable + BehaviorSubject + async pipe
Vue	vue-3-demo/src/lib/employees-data-provider.ts	Class wrapper with private HF field + ref
Svelte	svelte-demo/src/routes/Hyperformula.svelte	buildFromArray + getCellValue + on:click + onDestroy

Other decisions

• TypeScript in all snippets (HF ships .d.ts typings)
• licenseKey: 'gpl-v3' in every snippet (without it, engine throws license warning)
• SSR notes for Next.js, Nuxt, SvelteKit (HF depends on browser-only APIs)
• VuePress template fix — Stackblitz links use <a :href> Vue binding instead of {{ }} interpolation in markdown

Test plan

• Render docs locally (npm run docs:dev) and verify all four integration pages
• Click each Stackblitz demo link — confirm it opens the demo
• Verify snippets match demo patterns (React=useRef, Angular=BehaviorSubject, Vue=class wrapper, Svelte=on:click)
• Verify no untested patterns remain (no Signals, no $state runes, no Pinia, no NgZone)
• Confirm licenseKey: 'gpl-v3' present in every snippet
• Confirm destroy() cleanup present in every applicable snippet

---

Note

Low Risk
Docs-only changes; primary risk is broken documentation rendering/links or misleading integration guidance if snippets drift from supported patterns.

Overview
Adds AGENTS.md with repo-wide guidance for AI assistants, including HyperFormula usage patterns and framework integration do/don’ts.

Replaces the previously minimal React/Angular/Vue/Svelte integration pages with full, self-contained guides and code snippets (lifecycle/cleanup patterns, SSR notes, and next-steps links), and updates Vue troubleshooting guidance around reactivity (markRaw) and licensing.

Fixes VuePress rendering of Stackblitz demo URLs by switching markdown interpolation to bound <a :href> links across the affected guides (including custom-functions.md).

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

[qunabu]

Task linked: HF-122 Docs: Add basic code snippet to React, Angular, Vue and Svelte guides

[github-actions]

Performance comparison of head (d6a316c) vs base (1852159)

                                     testName |   base |   head | change
------------------------------------------------------------------------
                                      Sheet A | 503.72 | 498.99 | -0.94%
                                      Sheet B | 171.88 | 165.27 | -3.85%
                                      Sheet T | 147.09 | 144.58 | -1.71%
                                Column ranges | 532.88 | 527.26 | -1.05%
Sheet A:  change value, add/remove row/column |  17.28 |  16.97 | -1.79%
 Sheet B: change value, add/remove row/column | 150.17 | 138.65 | -7.67%
                   Column ranges - add column | 162.24 |  156.4 | -3.60%
                Column ranges - without batch | 498.37 | 481.11 | -3.46%
                        Column ranges - batch | 126.33 | 126.55 | +0.17%

[marcin-kordas-hoc]

Question: Automated testing for framework demos?

During this PR I ran a manual tsc smoke check on all 10 code snippets extracted from the guides — found and fixed a real type bug (unknown → RawCellContent).

This raises a broader question: should we have automated tests for the framework demos (both the guide snippets and the Stackblitz demos in hyperformula-demos)?

The risk

Framework demos can silently break when:

• A framework releases a breaking change (React 19, Angular 18, Svelte 6...)
• HyperFormula API changes (new required params, renamed types)
• Bundler updates (Vite, Webpack config changes)
• Dependency drift (stale lockfile, removed transitive dep)

Currently there are no automated checks — breakage is discovered only when a user clicks a broken Stackblitz link or copy-pastes a non-compiling snippet.

Options considered

Option	Where	What it catches	Setup cost
A: Scheduled CI in demos repo	hyperformula-demos	Framework breaks	~20 min
B: Cross-repo job in publish.yml	HF main repo	HF API breaks (before deploy)	~1h
C: Nightly scheduled in HF repo	HF main repo	Both (builds demos against develop)	~2h

Option A is lowest cost and most immediately useful — a weekly npm ci && npm run build per framework in the demos repo. Zero changes to HF main CI.

Option B catches the other direction (HF breaking demos) and could gate docs deployment.

Related: demo visibility for AI tools

Stackblitz links are invisible to AI coding assistants (Copilot, Cursor, Claude). AI relies solely on the inline snippets in docs/guide/integration-with-*.md. I've added AGENTS.md with framework integration patterns to make these discoverable.

A potential follow-up: vendoring a subset of demo code into docs/examples/ (where 49 examples already live) so AI tools see working examples during code search. This is a separate discussion — noting it here for visibility.

@sequba What do you think — is option A worth setting up? Or is manual verification sufficient for now?

[sequba]

@marcin-kordas-hoc I need to be sure the snippets work correctly and align with each framework's best practices, so I want them to be exact code fragments from the linked Stackblitz demos.

You can achieve this by either:

• updating the code snippets to match the demo code
• modifying the demos to match the code snippets (but in this case, please make sure that all demos are really well written - this is the code that other devs copy and use in their products, it must be perfect; also we will ask framework experts to review the demos before publication)

[marcin-kordas-hoc]

Following our Slack discussion where you approved keeping snippets focused on framework-specific patterns rather than extracting from the demos directly — that's the approach taken here (useEffect, BehaviorSubject, markRaw, on:click as the core of each guide, data as // your data goes here).

The reason for not extracting from demos directly: they use multi-file setup (buildEmpty → addSheet → named expressions, EmployeeRow types, helper files) — copying them produces either 60+ unreadable lines or decontextualised fragments. The Demo section caption already sets the expectation: "For a more advanced example, check out the demo on Stackblitz".

The demos themselves are unchanged.

[codecov]

Codecov Report

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

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1653      +/-   ##
===========================================
+ Coverage    96.77%   97.18%   +0.41%     
===========================================
  Files          174      174              
  Lines        15086    15086              
  Branches      3223     3223              
===========================================
+ Hits         14599    14662      +63     
+ Misses         487      424      -63     

see 1 file with indirect coverage changes

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