TRL `0.2.0-next.X` Update Marathon
Greets @FVTT ▹ Developer,
I am starting a new post to discuss / troubleshoot any problems or concerns you might have in regard to updating to the beta build of TRL
0.2.0-next.2 and beyond. The 0.2.x release series of TRL is all about hardening & streamlining the API taking a solid 2nd+ pass over everything. It represents "peak TRL" for Svelte 4.
My goal is to ship 0.2.0 on Wednesday. It's API / feature complete, but receiving any early feedback and learning about any problems you have in updating will help me create a better official release video where I can mention aspects that will help others update. If you have time before Wednesday to start your effort now is appreciated. If you are having problems let me know here or get in contact directly. I can help out with a PR if necessary.
As mentioned it's important to get on 0.2.0 as 0.3.0 will be out ASAP addressing Foundry v13 as early in the core dev release cycle as possible. There are many refinements / sub-path export changes to account for in the 0.2.0 release.
I was able to update Automatic Animations (AA) from an really old alpha build of TRL (0.0.23!) in 3 hours. AA is a huge package. I spent another hour adding new 0.2.0 features to AA definitely improving it. See the attached video for more details on what was fixed in 0.2.0-next.2.
I realize I didn't put out some release / update notes which will help somewhat in the process. There aren't many breaking changes, but a pertinent one for callbacks. You'll mainly have to watch out for app header buttons and any TJSDialog callbacks as now an object is passed back instead of an argument list. Here is the overview / notes:
Package sub-path Changes:
- Widely used change: localize is located in #runtime/util/i18n.
- All "application shell" components are located in #runtime/svelte/component/application.
- Several more sub-paths are refined in the runtime & standard library. Use API docs to find new sub-paths. This package overview page is handy too.
Breaking Changes:
- Runtime library
- SvelteApplication - app header
- onPress callback now takes an object { button, event }. To change the button icon / label on press modify button after destructuring.
- To define Svelte components set the svelte property to a TJSSvelteConfig object.
- SvelteApplication.state method name changes. If you are serializing / storing app positional state you need to update get() to current().
- get() to current()
- getSave() to get()
- TJSDialog
- onClose & onPress callbacks take an object { application }
- #runtime/svelte/store/fvtt -> gameState removed; use globalThis.game in templates instead.
- All document CRUD dialogs moved to standard library #standard/application/dialog/document
- Standard library:
- Various components / mostly buttons -> onClickPropagate to clickPropagate
- TJSMenu / TJSContextMenu onPress callbacks take an object { event, focusSource, item }
---
Refinements:
- TJSDocument / TJSDocumentCollection
- Improved Foundry callback registration. No need to manually call destroy().
- TJSGameSettings
- No longer checks for equality on game setting store update allowing objects to be stored.
------
These are many other refinements, but some of those above were concerns from various developers. Of course the breaking changes to look out for as well.
Here is the 0.2.0-next.2 / AA update video:
https://www.youtube.com/watch?v=tlaBOCmGBe8TyphonJS
YouTube
TRL 0.2.0-next.2 Update Marathon
#1Just a brief discussion of
0.2.0-next.2 and confirmation that Automatic Animations (AA) is now current. AA was on TRL 0.0.23 / alpha version of TRL, so besides being a huge package it took me 3 hours to update to 0.2.0-next.1 then an extra hour to add new features from the latest TRL for modal file pickers which is a nice improvement.
I a...5 Replies
Also a heads up when using the latest Vite
5.4.10. If you are deploying your repo directly into Data/modules/<MODULE_NAME> using the provided Vite configs from essential-svelte-esm or the template repo that compile to ./index.js in the module path you will see the (!) build.outDir warning. This is to be expected and is OK in this case.
svelte-preprocess uses an older JS API for sass. I'm sure this will be updated soon. You can install the latest svelte-preprocess for Svelte 4 & 5. This is what the sass warning refers to, but is fine. The latest is automatically installed as a peer dependency of #runtime.
Upgraded, no real issues here.
Had to upgrade
svelte-preprocess to v6 and change a couple of imports but works fine.
I do have a minor issue with typescript not reconginzing the imports for some reason, I added them to the tsconfig as paths but still no dice, it is very minor tho and the code does compile, just an issue in webstorm it seems
Right on.. For folks that haven't dug in too deep or that are already on
0.1.x the upgrade shouldn't be too bad. Mostly just changing sub-path exports to more refined paths. The callback changes to an object and not argument list for app header buttons / TJSDialog are a point to watch out for if used.
For instance the Automatic Animations PR was deep, but it also was coded at a much earlier point in time and uses more of TRL, so many of the points above in the list of things to watch out for were applied. AA also had problems being a large Handlebars package before conversion to Svelte. It works, but isn't a good example of how to go about things per se; no fault of the original author though. IE a very good MVP that in a professional context would get an architecture overhaul / restructure.
Regarding types for anything that touches Foundry like #runtime/svelte/application types are withheld / not hooked up because there are no minimal types for Foundry core API / IE Application and whatever else is referenced that are suitable to hook up. If things were quiet on the Foundry front without a looming need to address v13 immediately I was planning on making a minimal set of Foundry types for just the aspects where TRL touches Foundry, but alas things are not quiet and v13 / 0.3.0 work to adjust to Foundry platform CSS / style changes must commence immediately to get ahead of those changes and give folks using TRL enough time to test packages on v13. Alas I can't tie TRL to the Foundry community types for several reasons despite the effort expended by folks in that area.
I will get a types solution in place for those sub-path exports soonish, but alas not likely before v13 concerns are solved and this is mostly due to "unknowns" in Foundry platform changes at this time. As things go first / early Foundry prototype release can also be incomplete / far from finished. The big problem there is that there is no visibility when v13 will be released, so the cautious approach is to drop everything and work on that ASAP.
---
What I am working on the next two days is adding as much detail / additional API docs to in the source JSDoc / various sub-path package descriptions. I'm also going to try and get basic architecture overview / programmers guide / getting started resources together and clean up various repo guides / info.
Oh hey.... Just noticed some funky bits in the image; IE:
TRL 0.2.0 is more capable than core AppV1/V2. You can use percentages for width / height data ala
Also TRL supports setting minWidth / maxWidth as data values. There are many other handy positional features.
I also highly recommend never using JQuery at this point and learning the DOM API. IE window.offsetHeight is the same value.
Granted this thread is to support folks upgrading to 0.2.0, but worth mentioning the above.Cool, I remmber trying that a while back and it didnt work so I went with this, I'l give it a try
The percentage support is new. The underlying TJSPosition which is what you are working with as
SvelteApplication.position vs a bare object in the core API is quite robust / fully reactive positional store + animation / movement validation. I recommend folks check out the App Control / Animation demo in essential-svelte-esm.
You can do all sorts of fancy things now like relaitive adjustments: app.position.width = '+=100px' to add 100px to current width or app.position.width = '150%~' to make the width 150% of the current width.
Just bumped @typhonjs-fvtt/runtime to 0.2.0-next.3. No changes / fixes to API. I just moved all dependencies to peerDependencies with open forward versioning.
This benefits anyone using pnpm though you will need to use pnpm install --legacy-peer-deps.
TRL takes advantage of the flat node_modules structure created by NPM to install dependencies like Vite, Svelte, and everything else required as peer dependencies without requiring explicit configuration in a local project package.json. You can now however provide explicit package dependency if desired.
----
I'll be available on Sunday to help out with any potential PRs for folks running into trouble updating to 0.2.0. Unless any problems arise after this weekend I'll be making the final release on Monday. Just to be prudent I figured I'd give just a little more time for anyone to start the update process and report any issues. If you have the time to update this weekend please give it a shot. This is an opportunity to provide any feedback before 0.2.0 ships. It's rock solid now and there are no expected changes before final release.