feat(frontend) :: upgrade to typescript

[81reap]

feat(frontend) :: upgrade to typescript

Motivation

build.rs reads .js and .css files for top level comments to create a custom installer for 3rd party deps.

/* !include https://cdn.jsdelivr.net/npm/@tabler/core@1.4.0/dist/js/tabler.min.js */

This resulted in a few issues ::

1. cargo build requires a network to finish successfully. This also requires pulling in deps like awc, rustls, and actix-rt.
2. Frontend code had to be writtin in loosly typed JavaScript with the help of JSDoc.
3. Frontend code could not pull in types from 3rd party libs as those libs were downloaded by cargo build.
4. Frontend tests would redefine types and hack around the browser to run properly. This resulted in every top level function in sqlpage.js to be a global.
5. When DOCS_RS was set, build.rs would return early and ship broken assets.

What changed

Before	After
sqlpage/sqlpage.js	frontend/src/sqlpage.ts
sqlpage/apexcharts.js	frontend/src/apexcharts.ts + frontend/src/chart_series.ts
sqlpage/tomselect.js	frontend/src/tomselect.ts
sqlpage/sqlpage.css	frontend/src/sqlpage.css
sqlpage/favicon.svg	frontend/src/favicon.svg
sqlpage/globals.d.ts	frontend/types/globals.d.ts
sqlpage/tabler-icons.svg	deleted; the sprite comes from npm

The frontend is now built through frontend/build.mjs, an esbuild script, which builds with proper attribution and outputs to frontend/dist. build.rs now only compresses and hashes the output files.

Benefits

• cargo build no longer touches the network. npm handles installing frontend deps.

• docs.rs gets assets because frontend/dist ships in the crate. Verified with cargo package --list.

• The browser code is type-checked as against published 3rd party types (eg :: apexcharts and tom-select).

• Frontend can now be updated via npm update rather than manual comment updates. 3rd party packages are still pinned at the current versions.

• The served bundles are slightly smaller, because esbuild:

  Asset (gzipped, as served)	Before	After	Change
  sqlpage.js	35,050	33,583	−1,467
  apexcharts.js	189,889	188,488	−1,401
  sqlpage.css	104,753	103,221	−1,532
  tomselect.js	19,531	19,680	+149
  Total	349,223	344,972	−4,251 (−1.2%)

tomselect.js grew because we now bundle @orchidjs/sifter from source rather than taking tom-select's prebuilt file.

Downsides & How to avoid them

• A clean build requires running npm ci && npm run build before running cargo build. There is no easy path to hot reload the entire app.
  • we could also commit the frontend/dist folder but then we would run the risk of committing outdated files if folks don't build before committing.
  • flake.nix fixes this and I would be happy to make a follow up PR to add one.
• Bundles are minified with no sourcemaps. I kept this out of scope for this change as shipping source maps to prod is an opinion to be decided by maintainers.
  • This can be fixed by updating build.mjs
• This breaks custom scripts that called sqlpage_table() or reached for window.tabler.
  • This wasn't a documented feature nor do we use it in the repo, so end users should not be using this.

Testing

npm ci && npm run build
npm test
cargo build
cd examples/official-site && cargo run --manifest-path ../../Cargo.toml
cd tests/end-to-end && npx playwright test
# manually visited the localhost page and navigated around. doubled checked modals as well.

[81reap]

there is a lot more optimisations and type safety we can do here but i tried to keep it 1:1 ish so that its easy to review

[lovasoa]

This is useful, I do stand by the idea of getting rid of our custom dependency management system. But I think this PR tries to do too much at once to be actionable, and reviewable. I think a good first step would be to just change the build system. I also think we should try to make things as easy as possible for downstream packagers like homebrew and nix, helping them with the build system changes: at least make the changelog very explicit for them, and at best contributing directly to them.

[81reap]

ut I think this PR tries to do too much at once to be actionable, and reviewable. I think a good first step would be to just change the build system.

oof, I had already broken up the changes to bar raise the build and CI. I also figured since most of my changes thus far were frontend only this would be a good place to start. Is there a reccomended path forward to raise the typescript changes?

It's also totally okay if you want the project to stay on javascript to avoid this build step. We were already using typescript for the tests so I assumed it would be worth bringing it to the published code.

I also think we should try to make things as easy as possible for downstream packagers like homebrew and nix, helping them with the build system changes: at least make the changelog very explicit for them, and at best contributing directly to them.

I 100% agree, although currently I can only show efforts of up streaming changes as I haven't touched the publish CI path locally yet.

NixOS/nixpkgs#552148