TyphonJS•3w ago

Discussion: TRL 0.2.0-next.1 Pre-release

Greets @FVTT ▹ Developer, I'd like to open a discussion prior to the initial 0.2.0-next.1 release to set expectations and address concerns. When released I recommend as many folks to upgrade as soon as possible to get a better testing pool. Like all of the TRL releases even the first "beta" release will be rock solid and production ready. The further next.X series of releases will mostly be refining types particularly new Foundry core types and other odds and ends. All of the major refactoring of sub-path exports will be present from the initial release as well as various fixes reported since v12 dropped and many other useful enhancements to TRL. The discussion below relates to 0.2.0 update concerns and not TRL 0.1.x. --- Repo and NPM package name changes. The main repo in typhonjs-fvtt-lib is now runtime instead of typhonjs. Likewise svelte-standard is now standard. I will be making a new NPM package release for the standard library: @typhonjs-fvtt/standard instead of svelte-standard and marking the older package as deprecated. --- This release is large and will require some package import refactoring depending on what parts of TRL you utilize in your projects. Please see the pre-release 0.2.0 API docs which have now been updated reflecting all of the sub-path changes. More or less a lot of these changes affect the standard component library as now instead of #standard/component the components are logically separated into associated groupings. like #standard/component/button for buttons, etc. The following changes will be the most likely: - All application shell components #runtime/svelte/component/core -> #runtime/svelte/component/application. - localize (helper function for i18n support): #runtime/svelte/helper -> #runtime/util/i18n. - Components from the standard library will now have more explicit groups / sub-paths. Expand the tree for #standard/components in the updated API docs. I was able to make tremendous progress in the last week cleanly separating all non-Foundry specific components from the FVTT standard library into a base standard component library that can be used anywhere. This significantly increases the timeline of the Svelte 5 transition because I can now iterate on the Svelte 5 conversion without involving Foundry itself. To facilitate this separation though the Vite config will need a small mod:

{
  resolve: { conditions: ['import', 'browser'] }
}

{
  resolve: { conditions: ['import', 'browser'] }
}

Adding the alias directive allows the generic components to compile against the FVTT runtime and not the "base runtime".

{
  resolve: {
    alias: { '#runtime/': '@typhonjs-fvtt/runtime/' },
    conditions: ['import', 'browser']
  }
}

{
  resolve: {
    alias: { '#runtime/': '@typhonjs-fvtt/runtime/' },
    conditions: ['import', 'browser']
  }
}

--- There is only one code / breaking change. In the past various callbacks whether for app header buttons, TJSDialog callbacks, or various components from the standard library that provide data defined callbacks took argument lists. Instead of a variable number of arguments a single object will be passed now. This allows flexibility in typing and further extension in the future without disruptive refactoring if those arguments would have changed. If you have a dialog callback for instance that previously was:

function onSomeButtonPress(application) { /* Do something */ }

function onSomeButtonPress(application) { /* Do something */ }

all you have to do is add {} to destructure:

function onSomeButtonPress({ application }) { /* Do something */ }

function onSomeButtonPress({ application }) { /* Do something */ }

That's the breaking change for 0.2.0. This does require naming the destructured properties correctly and being mindful that you need to find / replace all callbacks appropriately across your codebase. For most folks that might be TJSDialog usage and app header buttons. It's less likely folks are using the data defined callbacks from the components in the standard library.

50 Replies

TyphonJS (Michael)•3w ago

Timing wise I'm still one solid ~4-5 day coding push out. I didn't know / think the generic standard library could be easily separated, so that took up the last week. Hopefully by the end of the next week 0.2.0-next.1 is out. The remaining work should go smoothly and I'm addressing almost all concerns raised over the last year. For instance refactoring TJSGameSettings so that it can be used independently without pulling in the UI / components; IE reduce the dependency tree that snuck into a previous TRL release. About the only concern I won't get to is modal app window / dialog closing support for game controllers which is an edge case reported by one developer over the summer, but I'll look at it soonish. Ooo... I should mention too a major feature of TRL 0.2.0 is that it works out of the box on mobile / tablets if you are using the standard library of components. There are also some spicy new Foundry integration components in the standard library. Very easy core file browser integration including a modal file picker! --- Ahh... Yes...Three more important refactoring concerns that I'd like to discuss. If anyone has concerns please respond soon. I don't think any of this should affect those with greenfield Svelte projects using TRL. 1. I am removing #runtime/svelte/application/legacy. This sub-path export has long had backward compatibility / helper functionality for folks converting a core Handlebars project to Svelte incrementally. I don't think anyone is using it nor should they with a Svelte native project. I think most folks that started using TRL did so with greenfield efforts using SvelteApplication. 2. I am removing #runtime/svelte/helper. localize has already moved to #runtime/util/i18n. The remaining legacy helpers just duplicate core Handlebars helpers and can be removed. Again just there to help folks transition away from Handlebars. 3. I am removing #runtime/tinymce. This loaded a custom oEmbed plugin I made for TinyMCE to be able to embed videos from YouTube / Vimeo in editor content. This was mainly used in FQL and it requires storing data in document flags, so has limited use cases because of the Foundry server side scrubbing of editor content. If by chance you were using this which I gather probably no one is then it is still available, but you just have to load it manually instead of using #runtime/tinymce.

Vauxs•3w ago

Gonna be updating the moment its up! Also you might want to add the "small nod to Vite" text to the readme

david aka claudekennilol•3w ago

I'm assuming 0.2.0 is specific to v12? PF1 (the only system I write my mods for) is still finalizing the last v11 before updating for v12 so I'll probably be out of this for a bit

TyphonJS (Michael)•2w ago

Vauxs:

Also you might want to add the "small nod to Vite" text to the readme

Yep, I'll add a wiki entry and link it to the README. david:

I'm assuming 0.2.0 is specific to v12?

Nope v11 still works fine. The two areas where v12 changed (again!) underlying API is the ClientDocumentMixin properties for app / document registration. This got handled in the 0.1.3 hot patch. The initially uncaught v12 change in the core function fromUuidSync is that it now throws an exception instead of returning a falsy value for malformed data. It turns out in ProseMirror when you drag and drop a document this triggers the paste callback chain in PM and with the new exception behavior a TRL PM plugin just needed to add a try / catch instead of just a conditional check on the returned result. --- That being said I very much think the forthcoming v13 release will be significantly more disruptive to folks dealing with core UI aspects like the sidebar and other Foundry aspects like possibly the file picker and such. If I can I'll try and time things as best as possible with the Svelte 5 / 0.3.x release series to coincide with v13 and handle any core platform changes there. SO 0.3.x / future Svelte 5 version of TRL might be locked to a newer version of Foundry. OK... I should be done with all of the API / sub-path changes. The temporarily hosted 0.2.0-next.1 API docs have been updated. I'm now down to just a few changes / additions in the standard library of components and making the menu for essential-svelte-esm just a bit nicer. Looks like 0.2.0-next.1 will be released this week! Alright... Just a few more sub-path changes for tidiness. An example is #runtime/svelte/gsap moving to #runtime/svelte/animate/gsap. The temporarily hosted 0.2.0-next.1 API docs have been updated. Some good news is that I worked out the build step for the generic standard library to be included in the FVTT standard library without requiring a modification to the Vite config / no need to add the alias mentioned above in the first post. I'm now really just down to some final cleanup in the generic standard library and demo app. I'm going to push hard through the weekend and if all goes well the initial 0.2.0-next.1 release will be minted. I hope you folks don't mind the updates. Another removal was #runtime/security/client/dompurify which was just loosely referenced in the FVTT editor components. This one again was a holdover from FQL and storing editor contents in flags where it isn't sanitized by the server. With the removal of the oEmbed TinyMCE plugin it only makes sense to remove dompurify as well as it likely wasn't used by anyone. I'm pretty confident that the 0.2.0-next.1 API docs in regard to sub-path exports is refined at this point. I don't expect much to change before initial 0.2.0 release. Feels quite a bit cleaner and will make perusing the docs clearer. After the initial release I'll likely spend 3-5 days adding lots of descriptions and details to the API docs, quick start guide, and such. Just a note for those still targetting v11 in regard to the ProseMirror editor component in TRL / Foundry. Previously there were various bugs on v11 in the core PM implementation which caused issues / errors thrown and hang ups when multiple editors were open. To get around / take a preventative approach the TRL PM editor component automatically closed any open editor when an additional editor was opened. In my current testing the latest v11 doesn't throw errors with multiple editors open like it used to, but still the target for key commands is the last opened editor component regardless if focus returns to a different one. The same problem will happen with any core editors. Since errors are no longer caused on v11 I've taken out my "preventative" workaround, but just keep in mind that it's just a bit wonky when key commands may not target the focused editor. This affects v11 only. I'm removing the workaround so that v12 onward when working with the PM editor component you can have multiple open at the same time as key commands will target the focused editor correctly. Heya @Faey. I think I saw a comment from you on the mothership. If this is referring to TJSGameSettings pulling in the UI code that is fixed in the imminent 0.2.0 release. It was one area where things got a little out of hand if all you wanted to use was game setting capabilities. One of the challenges with TRL is that presently the easiest way to distribute it is to bundle in what is used from the library to each package. I have experimented with delivering TRL as a Foundry library package where for a large part of it you can link against the Foundry library package which is not included in your package. This significantly reduces 3rd party package sizes to the 20-100kb size. The problem with that approach is the lack of reasonable versioning in the Foundry package manager. An alternate approach that I think is a very good fit is using an importmap script. This is tricky in a shared platform like Foundry though because there can be only one importmap script on a page, so this is something that would need to be added to Foundry to manage like additional details in package manifests for import map linking to a CDN and a possible fallback to a local package when there is no external internet connection. If you think about it Foundry ships all the resources and more for the core libs for folks to build their packages. If you had to link in all of AppV1 or AppV2 + handlebars to each package instead of using the global / pre-loaded options by the core platform package sizes would increase for the default tech.

Faey•2w ago

Hi there, while that is an issue for sure, TJSGameSettings pulling in the UI code only really matters because the UI code is quite big (although I think lazy-loading code is a good practice that more module developers should employ, no need to force the full multi-hundred kb bundle down to the players for modules where half of the code is GM only) The real issues for bundle size are gl-matrix and especially svelte/store/position position is a whopping 200kb after transformations and treeshake (but before minify) in a project that barely uses any of TJS After minify it is 55kb together, gl-matrix and position are responsible for about 2/3 of the total size of TJS That said, would you think it might be reasonable to try and ship a TJS Mixin for AppV2? Svelte version management would for sure be a bit complicated, but as it stands we'd have to ship svelte twice anyway, as there is no way I could find to render a svelte component with another module's svelte runtime. The "required" section of the module manifest should be more than enough to do dependency resolution for TJS versions

TyphonJS (Michael)•2w ago

Alright... So here is the deal. I haven't done the best job communicating the goals of TRL and the larger scope of work that has been completed since the get go. From the first year of TRL / Svelte 3 I have had an experimental build that offloads TRL & Svelte in a way that you can link against a hosted version of both across independent package deployments. This works for Svelte 3 & 4. I have in-depth knowledge of how Svelte works and create a version where a single runtime version of Svelte can be linked to multiple independently compiled packages. Likewise TRL / #runtime part of the library is also experimentally available. In the build process there is a non-described publicly additional Rollup plugin you can add to the build process to link against a served version of TRL & Svelte. The reason this is not available is because of the weakness / very basic functionality of the Foundry package manager. This build just needs to be served and nothing is loaded (well some CSS), but no JS in the main Foundry loading process. So yes... If you know what you are doing it is possible to build Svelte in a way that it can be shared across independent packages. Likewise TRL can be too. The biggest example is that the basic template-svelte-esm goes from ~522kB to ~4kB. This is a massive reduction. The work is done and proven for Svelte 3 & 4; unsure about 5 as internals probably drastically changed. Even if Svelte 5 can't be offloaded the runtime is reportedly much smaller; the bulk is in not being able to provide TRL as a shared library. Once TRL stabilizes after the Svelte 5 transition I will consider releasing a shared package, however it is problematic to do so at this time because this TRL shared library needs to duplicate every version released because the Foundry package manager is deficient when it comes to library packages that just need to serve code versus be loaded like a normal module / system, etc. You can't have multiple versions of the same package installed. This means I have to keep adding new TRL releases manually versioning them by path. This is not sustainable as the TRL package would keep growing larger each release. Check out the video... The space saving is dramatic. https://www.youtube.com/watch?v=EQ9X8GpajeE

TyphonJS

YouTube

TRL Experimental Package Linking

This video is a demo of the non-released experimental package linking of a 100% served version of the #runtime package of TRL including a shared modified version of Svelte 4 that can be linked across packages. This reduces your package size to just what you include as your content components and any other custom JS in your package. Three di...

TyphonJS (Michael)•2w ago

TJSGameSettings pulling in the UI code only really matters because the UI code is quite big

Fixed in 0.2.0

(although I think lazy-loading code is a good practice that more module developers should employ, no need to force the full multi-hundred kb bundle down to the players for modules where half of the code is GM only

Developers responsibility and not TRL.. You can have a conditional and use import dynamic if game.user.isGM is detected to load a GM only bundle / your package.

That said, would you think it might be reasonable to try and ship a TJS Mixin for AppV2?

Yes for those that don't care about full application dev experience reactivity this is possible. The mixin will just load your Svelte component into an AppV2 shell. Have patience. AppV2 is still very beta... The premise of TRL which 100% is possible with AppV1 is what if everything about application development could be made reactive and improved. This is and has been the entire time a successful effort. AppV2 prevents this capability by closing off extension mechanisms in the base class through private variables / functions. So a mixin will be available soon for those that want a minimal dev experience. IE you get what Foundry provides in AppV2 for the app frame / lose all app reactivity. This may be fine for a lot of you. I have yet to decide the larger course of action to take regarding the future of a fully reactive app dev experience beyond AppV1. The transition to Svelte 5 is more important. There are many things in play here, so please be patient. --- Part of the communication gap too in regard to the "heavyweight" features of TRL like TJSPosition is a lack of understanding the full power granted. Not only in app positioning, but positioning any element with a super efficient render / layout pipeline that can't be beat for performance. Besides the reactivity available there is an essential positional tweening system and full 3D validation system that can be extended. That is an awful lot of power in 55kB minified / gzipped, etc. The built-in tweening / animation capability is ~33% faster than GSAP. However if you need advanced features like timeline / animating non-position properties then GSAP is the way to go. There is a bridge and easy data defined vs functional capability to link TJSPosition to GSAP. Also easy loading / access to GSAP through TRL. Offloaded in a shared TRL library direction this costs nothing, but for now compiling these resources directly into your package is a limitation of Foundry and not TRL.

Faey•7d ago

while I do understand the concerns with foundry's package manager I do not think that having the ability to install multiple different versions of the same code base is at all desirable, foundry does provide a mechanism to define compatibility to a given library module in the same "minmum", "verified", "maximum" format that you can use to define foundry version compatibility. Personally, I think this consensus algorithm should be enough for module development. If the library module properly utilizes semver, there should be no issues here that you wouldn't also face in environments like NPM and while this is very impressive, I do have to admit that I don't know what I would use this capability for presently, is there a demo of this functionality?

oWave•7d ago

I'm not sure if foundry actually looks at the version requirements when installing a dependency. And even if it did, it doesn't solve the issue. You can't have multiple versions of the same module

Vauxs•7d ago

It does (albeit, sometimes poorly) Historically it did not but now I think it has support for all inter-dependencies (system, world, module)

Gaming

Programming

Discussion: TRL 0.2.0-next.1 Pre-release