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...50 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.Alright @FVTT ▹ Developer ...
The release candidate of TRL
0.2.0 is out and available. There are no further changes expected before 0.2.0 officially goes out the door. This will occur this Friday, but glad to receive any comments before then. I will discuss some of the final refactoring and detailed testing that occurred over the last month.
For reference in package.json this is:
I should note that TRL provides additional resources beyond the base Svelte library for advanced app development. The tools that I use to make the TRL components rock solid are available for you to use as well to make your components resilient.
In the video below I go over some of the high level architecture details and behind the scene work that I accomplished with 0.2.0. The goal of 0.2.0 was to harden TRL from bottom to top including all dev tooling used along with API docs. All of this successful... It just took time to get it all done. TRL is well positioned now for the Svelte 5 transition.
It's a great idea to install the essential-svelte-esm demo repo:
Or the direct package link you can drop in the Foundry package manager:
- https://github.com/typhonjs-fvtt-demo/essential-svelte-esm/releases/latest/download/module.json
I will be making an official 0.2.0 release video stepping through a lot of those demos.
I can say that TRL is 100% bug / issue free. I did detailed testing and there is 1:1 complete identical behavior between Chrome and Firefox including usage of all TRL components in cross-window contexts; IE popping out an app via the PopOut! module. This was no small feat as Firefox is quite demanding in this regard. The high level details are that the entire JS / DOM APIs are completely separate in Firefox for cross-window use cases. TRL does a lot of accessibility / focus management that involves the DOM API. The two key utility classes available are A11yHelper and the new CrossWindow.
While TRL is 100% cross-browser / cross-window certified that doesn't mean the custom components you write or any 3rd party Svelte component libraries you may use will work in a cross-window context. One must be intentional in designing for this use case.
I also tested a game controller / Rumblepad 2 w/ JoyToKey and there are no problems using TRL w/ game controllers.
With all of the final work I did a bit of preparatory refactoring at the architecture level and some small minor adjustments to the standard library. Likely these changes won't affect you, but here they are:
- all standard components use enabled as optional state to enable / disable.
- ripple / rippleFocus were moved to the base sub-path export #standard/action/animate/composable.
Notes about Vite 6.... Well TRL isn't the limiting factor here, but the Svelte 4 plugin for Vite is hard locked to Vite 5. The latest usable version for Svelte 4 is @sveltejs/vite-plugin-svelte at 3.1.2.
Also I made some adjustments to the Vite config in essential-svelte-esm as @rollup/plugin-node-resolve is no longer necessary for Vite 5. You will see a warning about the Sass 2 API, but that is a Vite 5 quirk changed in Vite 6. All is fine.
This was a very long year of lots of grind from bottom to top and it has been a complete success and positions TRL in a position of strength to successfully transition to Svelte 5 as well as deal with the upcoming Foundry v13 style / CSS changes. While the Svelte 5 transition will again be a slowish period once it's complete the sky is the limit
https://www.youtube.com/watch?v=CY9aedjx7X8TyphonJS
YouTube
TRL
0.2.0 Update Marathon #2 Release CandidateHey folks.. Just an impromptu video showing off the last month of extreme hardening of TRL and the standard component library including a high level architecture overview. I can now say that TRL is 100% rock solid across Chrome & Firefox not only in the main browser window, but also cross window when using the
PopOut! module. It took a bunch o...Looking forward to Svelte 5 to start some development with TRL. I migrated all my corporate tools and websites to Svelte 5 last month and it was painful, rewriting 50% of the code to runes with barebones documentation and basically no examples / real world projects. But now that I understand Svelte 5 much better, it feels amazing to use, and I just can't downgrade to Svelte 4 for Foundry dev.
it was painfulI'm indeed concerned about this regarding folks currently using TRL / Svelte 4 on Foundry. I don't think folks realize how large / actual paradigm shift that it will be. The API surface of TRL will change certainly at the component level and folks that have serious / supported Foundry packages using TRL will have a lot of work to do despite whatever I can do on the TRL side to make things easier. There already is some pretty clear attrition between folks either leaving Foundry dev or just not interested in TRL anymore or simply stopped by temporarily to check things out, but never got started. Getting pinned between the AppV2 Foundry side and Svelte 5 is a "double whammy" so to speak. Svelte 5 still comes across as
beta to me with non-stop fixes coming in daily and the whole WAAPI transition system has something like 60 issues that simply aren't being worked on yet. Getting through this transition I'm sure Svelte 6 will be grand.. ;P Additionally, with stock AppV2 just not being suitable for reactive frameworks despite claims, but communicating that is practically impossible on the main forums and hopefully there isn't too much confusion in discussion here.
Svelte 5 will give tremendous capabilities at the TRL / framework level though; just lots of busy work until it comes to be.
TRL will emerge through all of this strong in time. I truly believe that once reactive property field access is realized with TJSDocument that this opens up the real power of reactivity on Foundry and it will change everything especially for game system devs.Svelte 5 still comes across as beta to me with non-stop fixes coming in dailyThat's absolutely true, they have the whole Advent of Svelte going on right now with new features announced daily https://svelte.dev/blog/advent-of-svelte There are some things that I really want to see, in particular: 1) async version of
$effect i.e $asyncEffect. Using async functions in effects this way is not correct because an async function returns a promise that Svelte doesn’t expect and can’t resolve:
So you need to either make it thenable
Or use immeadiate function like this:
2) Partial track on $effect, so it will only trigger on changes I want to track, not every single variable in the function. Currently, it can be achieved with runed/watch
3) Reactive context without classes, getters and setters. Not a big deal but it just counter-intuitive that $state doesn't work in context without boilerplate code.I've always been somewhat amazed and personally bummed (because I'm "old school" and announce after engineering is complete) at the new school announcement and hype cycle stoked by Rich Harris and co. The pendulum is finally swinging back around where "announce early / over promise" is thoroughly hitting them in the rear.. ;P
The whole announce early to grab tech cred / headlines has a whole lot more to do with marketing than it does engineering.
Re:
#3: While there is a lot of power with $state when it comes to actually passing state between sources one now has to mindful of pattern construction issues. There is a lot of flexibility, but when it comes to creating a generic data source that can be shared and hooked up with generic components accepting data sources this likely requires following a very specific pattern vs a standard contract (stores). It moves the burden heavily towards sticking with a specific pattern of data construction that can be utilized by generic components that also follow that pattern. At least this is something I'll be paying attention to on the difference between stores and $state.I mean it's trivial to make it work, I just think it's something Svelte compiler should do automatically without boilerplate.
Indeed. Svelte 6 FTW. I think we'll see a long continued dev cycle for the nearly the entire Svelte 5 timeframe. It'll be fantastic eventually.
I guess what I was hinting at not specifically the use case you mentioned is that passing stateful classes like Foo is not clear cut. I have yet to explore deeper, but I don't think you'll be able to pass
foo.value or other properties IE foo.bar as a generic stateful props. I'm going to be looking into creating reactive data classes for all of the TRL components... It's just not clear right now if you have a generic data source like foo.bar that you can assign it to the data source field of the TRL component data class. IE with stores there is a defined API contract on receiving / setting the data.
Well.. We are getting off into Svelte 5 / random chat... Definitely want to leave this thread / forum post for any feedback on the TRL 0.2.0 release.
Lots to ponder in the near future re: Svelte 5! Also glad that you are diving into Svelte 5 separately. I'm sure it'll be nice to have folks with some experience around when it comes to honing the TRL Svelte 5 experience!I will say though, working on Svelte 5 from scratch on new websites it makes previous versions syntax almost unreadable now.
I have to keep reminding myself that
let makes things reactive just bcuzI know I mentioned not using this forum post regarding forlorn remembrances of magic past. Really that was just so folks see the above RC / video announcement, but likely those still interested have done so. One thing I'll miss a bunch is the on:pointerdown
|preventDefault|capture event modifiers.
While there is some benefit of passing around props for event handlers IE onpointerdown, magic and code brevity is lost. I also have a ton of custom events in TRL that are like close:popup which I assume need to be changed as on:close:popup will no longer be valid as onclose:popup.
Using
<script lang="ts"> no longer works with this version?
Error: "ApplicationShell is not defined"I would suggest doing a clean install of Node packages. One way is just deleting
node_modules & package-lock.json. I made a lot of things peer dependencies of the runtime package. If you are using NPM then things should work.
svelte-preprocess also lists typescript as an optional dependency, so I'd add typescript to devDependencies.
I won't be able to test things until Sunday. Where is that error coming from? Does it occur without lang="ts"?
This likely is a configuration issue and nothing with TRL per se.
If you are taking the straight template-svelte-esm to enable typescript might be as simple as adding it as a package to install; that template covers ESM, etc.I checked out
template-svelte-esm added <script lang="ts" the the BaseAppShell and "typescript": "^5.4.5", to devDependencies. Then I run npm install and started vite devTry using the package instead of #runtime
I assume you have a recent Node version installed.
v18+ You should see a warning otherwise.
Perhaps run npm run build to build the normal artifacts first then npm run dev. Also try the build and not the dev server straight out. Restart your Foundry server after the initial build. You can also check the modules section on the admin side to make sure Foundry sees it.
Where are you seeing the error? In the browser console or during the build process? I assume the latter, but perhaps you can include the output where the error is occurring.This has nothing to do at all with TRL / building / or running the module. The build should have produced information detailing aspects of TS hookup required. Maybe you didn't see this when running
npm run dev, but it is present in npm run build.
verbatimModuleSyntax is required to be true in any associated tsconfig.json which you should also add. This is a requirement of Svelte / svelte-preprocess.
So not a TRL problem per se. It is true that I haven't been able to thoroughly go through all of the Svelte components to explicitly type props and such; several will be typed as any, but the declarations are there. The time investment to thoroughly type all of the Svelte components is a bit moot given how much Svelte 5 is going to change things. I'd rather do a thorough job once instead of twice.
Unless you are a TS expert too you should be forewarned that using Typescript w/ Foundry in general is a really mixed bag and you should be ready for headaches.Thanks. That works for me. I already tried
verbatimModuleSyntax before but instead of a build I just started the dev server.
Unless you are a TS expert too you should be forewarned that using Typescript w/ Foundry in general is a really mixed bag and you should be ready for headaches.Coming from a backend developer background for large enterprise applications where clean code is everything it feels just wrong not to have types 😅
There will be a few things to tidy up and improve in TRL An awful lot of time has been expended in this area otherwise the API docs wouldn't be in the state that they are presently.
The Foundry side will remain problematic.
I actually write all the types I need myself. But we are getting off topic. I really appreciate the help. I'll now try to convert my actual module to the new version.
If anything comes up / needs clarification feel free to reach out.
Which version of svelte should I have installed?
^4I seem to be unable to resolve this error when trying to upgrade:
Upgrade to what? And show the code in question since it clearly says "unrecognized option
hmr"Upgrade from TRL 0.1.3 to 0.2.0-nex.x.
I know what the error says – my understanding is that it's talking about vite.config.mjs, but my vite.config.mjs doesn't include that option. In fact
hmr doesn't appear in my codebase at all.Its not though, its talking about
ModifierDialog.svelte :thonkang:I know but that file doesn't include the text
hmr either.what version of vite-plugin-svelte are you on?
5.0.3
And vite 6.x
🙃
All of those are Svelte 5 only
Aha, ok tx
Use
as far as I am aware at least, those are the last versions you can use
Are these package.json imports invalid?
its correct
I thought
@typhonjs-fvtt/svelte-standard/ should change to @typhonjs-fvtt/standard/ maybe.right, it should
Any clue about this one?
I searched for svelte/helpers in my codebase and it doesn't occur there, so I'm guessing it's some package.json mismatch.
If you are upgrading, you might as well upgrade to latest TJS and that may solve your issue
Because we are past next.2
by this point I am gonna put this here since it works https://github.com/MrVauxs/pf2e-graphics/blob/main/package.json
You should use production builds while you work through the upgrade refactoring. Read the first message above in this thread because it details the main points to watch out for including the moving of
localize from "svelte/helper".
You have been through Foundry core refactoring between versions. This is similar though in the case of TRL the refactoring is mainly where things are located and not a change in functionality though there are a few changes to note again in the first post above.
Use the API docs looking up symbols that can't be found.
The latest versions are next.6 for the runtime library and next.3 for the standard library. I am putting out what I hope is the last "beta / RC" releases on next.7 / next.4 hopefully later today.
Next week 0.2.0 final release should be out.
Just giving folks a heads up [email protected] and [email protected] is out. Now with rather comprehensive TypeScript support for both the PF2E and League types.
There are now two template repos for TS:
- template-svelte-ts-league
- template-svelte-ts-pf2e
The shim layer to generically support multiple sets of Foundry types worked out. There should be comprehensive support including TJSDocument / embedded collection reducers and in the standard library all of the C(R)UD dialogs to work with documents.
Also regarding TJSDocument & TJSDocumentCollection the data passed through to subscribers is now normalized to action and data where data will always be an array. Foundry itself will send over a string or object in single document operations and arrays of the same with multiple doc ops. Normalizing the output to always produce an array helps to simplify downstream processing. Chances are no one is using this functionality, but worth noting as technically it's a breaking change though significantly better than receiving action sometimes and renderContext (v12 change) at other times.
For those that already have set up TS repos with the previous release take a look at your template repo of choice as there is now a types entry that you need to add for the shim layer.
I also have updated the ESM repos / Vite configs to output production builds to /dist, so there are some config mods that you might find useful.
-----
From here I have a few more odds and ends to wrap up and hope to make the 0.2.0 final release on the upcoming Wednesday. If folks can hit this hard especially any TS devs that would be handy. I don't expect issues, but the template repos and my spot checking only covered only the most complex new types support.
There are several cool new features / type checking against Svelte props / context values and more in any TJSSvelte.Config you provide.
-----
I'm exhausted and will make a video & ping tomorrow. Just want to give folks especially in different time zones an early weekend heads up. Thanks for taking a look if you can...Just tested and the only hitch so far I had was changing the types of Header buttons, nothing too major
Oh and this I guess
Looks like it has to be
Partial'd
but hey VSCode no longer complains about that comment above!
For now just gonna typecast it as as ConstructorParameters<typeof TJSDialog>[1]I upgraded to next.5 / next.3. Took a day but all working.
OK... [email protected] is out.
I fixed the
SvelteApp.Options types issue. The problem was that when extending the ApplicationOptions interface of the PF2E / League types I didn't use Partial<ApplicationOptions>. The template repos are adjusted slightly to remove the necessity of using Partial in defaultOptions now.
For those using TS please hit next.8 and next.4 hard to find any remaining declaration aspects that you'd like to see adjusted / fixed before the 0.2.0 final release next week.
---
I have spot checked many of the more advanced TS types support added. The one downside currently is that there isn't a comprehensive TS demo repo like essential-svelte-esm that uses a wide range of the TRL API for type declaration verification. The API docs are solid and it all should work fine, but eventually it will be nice to have a standard demo / reference TS repo that covers a wide range of the TRL API. So yes, if you have a complex TRL package report anything that you think might need a fix.
Upgrade to next.8 / next.4. There shouldn't be refactoring for this update.Updated, all is well.
Just to keep folks updated. I've been continuing to work through various areas of TRL converting certain sub-path exports to TypeScript that benefit from stronger and more accurate typing than what is possible from JSDoc. This current round took a bit longer, but the results are fantastic especially for those working with TS.
TJSGameSettings and the additional array-object reducers are now strongly typed. IE these sub-path exports:
To not commit the cardinal sin of making a release before the weekend of which I won't be available for most of it I'll be delaying the next release until ~Monday evening or thereabout.
This will make TRL mostly fully covered with thorough typing. It's not like these areas didn't have types before, but in particular for the additional array reducers things things are now verified with A+ typing.
I have a few other backend updates to make beyond that, but really want to wrap up the official 0.2.0 release ASAP to get started on v13 compatibility.