Convert to ES modules, improve encapsulation#725
Convert to ES modules, improve encapsulation#725VanessaPhippsCfa wants to merge 64 commits intoableplayer:developfrom
Conversation
Also eslint fixes
Also eslint fixes
Also use "e" instead of "_" for ignored caught errors
Caught with eslint. At least, they look like bugs. Hopefully the buggy behavior wasn't important.
Also eslint
This keeps with our allowing unused principle, and also fits better, Vimeo does document these as "events"
Looks like various elements used to get passed around differently, but the old references are still present, just unused or always undefined. Get rid of 'em.
Also eslint
It's needed for demos
This allows dynamic adding of players to also dynamically remove them, preventing memory leaks, and ensuring the event handling has an accurate count of instances on the page.
|
Just noticed I was a bit overzealous when I first converted |
Questions:Rollup: That seems fine to me. I've mostly used esbuild in the past, but I'm not committed to anything in particular, and don't see any good reason not to use rollup. ES version: Yeah, those are some very fine distinctions, with a range from 94% to 96%. Switching up to 2017 is obvious, since we're already there in the code. I'm inclined to agree with ES 2022, for two reasons: 1) there isn't currently any automatic update for most users of Able Player, since it's not available through npm, so there's relatively little pressure to update and 2) my entire goal is to modernize the code base, and it just makes sense to continue in that direction. Additionally, following up from your second comment - Release version: My original intention was for the next release to be 4.9, but that was before this PR. I would either choose to do a release of 4.9 without this change in May, and add this to 5.0, or skip 4.9 and release this as 5.0. I'm fine with either choice; but obviously the latter choice will be easier in many ways, as it won't require a lot of updating of this PR. A release with this change would be preferred to not include any additional feature updates, because I don't want to have to deal with testing feature changes simultaneously with ensuring we don't have any regressions. Features:Woo hoo! I've never used require.js either. We should probably test that. Will need documentation updates to cover the new capabilities. Improved dev experience:Also woo hoo! :) Architecture notes:One thing we might want to also introduce, that's been on my todo list, is reduced builds. There are some features that I wouldn't consider valuable in a standard build - e.g., the VTS. The metadata library might also be unnecessary, but it's only 140 lines, so not really a major concern. Features not considered:That's reasonable. I've had a few occasions where I've wanted to be able to pass an object, but I wouldn't consider it a priority. It can be added later. Agree about Also agree about Breaking changes:
Having only AblePlayer on Bug fixes:👍 Code cleanup:I've spent a lot of the last few months removing dead variables...there were a lot of them when I inherited this. I might prefer to switch the unused vars to be more declarative; actually using Uncleaned up:I've been generally avoiding making nmajor indentation changes. At some point, I'm going to want to fix all of that...but definitely not at the same time as doing other major tasks. Diff noise is just not helpful...so thank you for not doing that! Switching variable declarations is also something I've been leaving for later, for the same reason. I don't have any particular desire to continue using We can actually update the documentation in this branch at any time; it won't be pushed live until we're ready. The deprecation warning is long-standing, but it still works, and the alternative still doesn't fully work. So for the time being, we're stuck with it. Existing bugs:If you have a chance, opening individual issues for those would be great; but I can do it, too. Just helpful if you're able to provide any additional context when opening them. Exclusions: You should be able to exclude everything excluded in the |
ConcernsOne thing I'd like to be able to do is allow people to import their own custom translations. The same is true for icons; I'd like to be able to pass custom icons. In both cases, those might be good future features available by passing an Object to the constructor. Since we are losing the ability to pass custom icons via file paths and also losing the ability to use a custom translation file, those might be arguments in favor of getting the constructor arguments in place sooner rather than later. Non-concerns that should be flagged in release notesThe file size has increased; however, with translations now packaged, there's no longer a need to asynchronously fetch those, so the overall performance impact is almost certainly an improvement. (I only say 'almost' because I haven't actually tested it.) |
|
Thanks so much for the review! Re: concerns
Understandable. Fwiw people could still do their own custom build with extra translations. That said, especially since Able Player is currently distributed as an IIFE, I wouldn't expect most users to be familiar with bundling. Requested changesLemme summarize my understanding of these, let me know if you'd change this list:
Further testingI ended up testing RequireJS after all and it seems to work fine :D so I can document that without guilt now! |
|
Yes, that's my main concern. Right now, you can just drop in a replacement file, which is within the scope of what more people can do. (For the record: I don't know that anybody is doing that, it's just relatively easy.) But I don't think that requiring a build step to do customization is ideal. And I'd like to consider the case where somebody really only wants to customize a handful of terms, and could just pass in an object containing the replacement terms. I don't know if this is necessary for this release, but it's something to consider. But your list of changes is a good match. My inclination is to merge this PR sooner rather than later, to ship an early beta release that I can send out for testing. With such extensive architectural changes, I think that's a priority. I might end up pushing the release a little later, as well - I'd been planning for May, but with changes of this scope, I think I'd want the release to fall further into the summer, to minimize possible concerns with schools. |
|
Is there a way I can check the home page rendering of the README? I played with Jekyll a bit but couldn't figure out how the docs here are generated. Seems like it's just that one page, and the rest are inside Edit: I think I figured it out. I needed to make a Gemfile from a fresh |
|
I filled out contributing.md with some updates. Do you want to ask that new contributions pass ESLint? I think it'd be prudent. |
|
Well...the docs. To be honest, they're on my list for an overhaul, which makes documenting how the current process works feel like a lower priority. I'd like to move them all into the jekyll docs build, rather than having two separate types of doc files - but that will mean changing a number of other things about how it's all setup. It'll be a lot more flexible, however. I'm considering using the modified version of just-the-docs that we're using for the WP Accessibility documentation. Re: new contributions guidelines. Yes, I think it would be prudent to ask for ES lint to pass in new contributions, now that the build requires |
joedolson
left a comment
There was a problem hiding this comment.
These are pretty minor changes, but there are a few things to address, for completeness.
| @@ -349,6 +351,7 @@ var AblePlayerInstances = []; | |||
| if ($(media).data('use-ttml') !== undefined) { | |||
There was a problem hiding this comment.
The TTML to VTT library is an incomplete library; I removed it from the package in version 4.6.0. This block should also be removed; I just missed it when I removed it from the build om a9d285d
| @@ -1045,13 +1050,14 @@ | |||
| // 2. span that contains the icon font (in our case, buttonIcon) | |||
There was a problem hiding this comment.
Looks like there are still comments to be removed; this refers to the font icon buttons, which should also be omitted.
| if ( existingIcon.length > 0 ) { | ||
| return; | ||
| } | ||
| $button.find('svg, img, span').remove(); |
There was a problem hiding this comment.
This shouldn't need to remove img or span anymore, now that we're only using svg.
| @@ -1,8 +1,7 @@ | |||
| (function($) { | |||
| function addTtml2webvttFunctions(AblePlayer) { | |||
There was a problem hiding this comment.
This file is currently unused. I'm inclined to remove it, as it's not a high priority. At this point, if I include it, I'm more inclined to use an existing library, rather than rolling it independently.
With all the other structural changes here, I think it's a good time to remove these old, unused files.
| } | ||
| catch (err) { | ||
| catch (e) { | ||
| // Errors are suppressed here, not sure why - VP 2026-03-02 |
There was a problem hiding this comment.
I don't know either. Predates me. May be a good idea to show them again; if this function is returning masked errors, it would be good to know.
| @@ -0,0 +1,15 @@ | |||
| .DS_Store | |||
| test.html | |||
| thirdparty/jwplayer.* | |||
There was a problem hiding this comment.
jwplayer was removed from Able Player in 2022, so this and any other references can go.
| @terrill, @candideu, @xerc, @jbylsma, @amartincua, @zwiastunsw, @conorom, @jeanem, @joedolson, @Justryuz, @dependabot | ||
|
|
||
| **Full Changelog**: https://github.com/ableplayer/ableplayer/compare/v4.5.1...v4.6.0 No newline at end of file | ||
| **Full Changelog**: https://github.com/ableplayer/ableplayer/compare/v4.5.1...v5.0.0 |
There was a problem hiding this comment.
This would be the full changelog since I took over, which I don't think is super useful. We should instead showing the the spread from e.g. v4.8.0...v5.0.0 in the changelog block for 5.0.
|
One oddity is that I haven't been able to get |
Description
I want to use Able Player in a Vue project as an NPM dependency, and this PR would make it possible to do so.
As a side effect, this PR makes Able Player better encapsulated even for IIFE users. Icons and translations are now bundled, rather than needing to be served at a particular path.
The "101 files" count is a bit misleading, I tried hard to keep this diff as small as practical while still achieving everything. 58 of those are the deleted contents of
button-icons. Many of the rest are relatively minor changes from an IIFE to a module.Would fix #189
I'll describe my changes in detail below the PR template.
How Has This Been Tested?
npm run watchto test the new build. I removed the build products from the PR, as instructed in CONTRIBUTING.md. Demos tested via Chrome 146.0.7680.31 .python3 -m http.server --bind 127.0.0.1 8888develop.Screenshots (jpeg or gifs if applicable):
N/a, the player works the same as before.
Types of changes
This includes new features, breaking changes, and bug fixes. More details below.
Checklist:
Major rewrite details follow
Open questions
asyncandawaitin the source now, so we're at least ES 2017. I would like to switch all thoseObject.prototype.hasOwnProperty.calltoObject.hasOwn, but that requires ES 2022. Which has 94% availability, compared to 95% for ES 2017, and 96% for ES 2015. terser is configured to output ES 2015, we should bump that up to ES 2017 at least, and further if we want to.New features
node_modulesand bundled alongside Vue, React, Angular, etc. It now skips initialization that requireswindowifwindowis not available, enabling server-side rendering and static site generation.disposewhen you're done with it. This prevents memory leaks and enables global Able Player keyboard shortcuts when only one instance is active.Improved dev experience
npm run watchrebuilds Able Player on the fly as you're working on itArchitecture notes
scripts/main.jscurrently is. However, we need to stripconsole.log, so that won't work yet. If we end up gating log lines behindthis.debug, we could stop building ES.jsontranslations might not work depending on the application builder and its configuration."type": "module", CommonJS files in the repo had to be renamed to.cjsto run properly. The only files affected were:Features I considered but didn't do
this.debugdetermine whether logs are output, instead of determining this at build time. For another day.js-cookiestill has to be added globally, even when using Able Player as an ES module. This seems fine though, since it's an opt-in feature.Breaking changes
data-root-pathis dropped. ES modules aren't really supposed to need this kind of thing, to fetch their own static assets, they're supposed to be bundled. So that's what I did, with translations. The image SVGs were already bundled.data-icon-typeis dropped. All icons are now always SVGs. SVG adoption in browsers is 96% so this should be fine.window.AblePlayerInstancesis no longer an array onwindow. It's aSeton theAblePlayerconstructor. Able Player instances now add themselves to this set on construction. Applications shoulddisposeinstances when dynamically unmounting them, to prevent memory leaks and enable global Able Player keyboard shortcuts when only one instance is active.ableplayer.dist.jsno longer exposes DOMPurify onwindow. I think this is an improvement, so people can opt-in to separate DOMPurify that IS also onwindow, or otherwise haveAblePlayerbe totally encapsulated. It did breaksearch2.htmlso I switched that to the separate DOMPurify build.separate-dompurifybuilds, since they no longer depend on the directory structure to find button icons, translations, etc.windoweither. We could put these onAblePlayerif we thought they were important to expose, but I didn't want to do that until I was sure it was necessary.window.AccessibleDialogwindow.AccessibleSliderwindow.validatewindowiswindow.AblePlayer, and it doesn't even do that if imported as an ES module.Bugfixes
pt-BRandzh-TW. We were lowercasing them before. We might want to make this matching more lenient on casing.catchblocks were referencing nonexistent variables.Code cleanup
translation.jsfor example,this.langlooked like it might always be undefined, and thelangingetSampleDescriptionTextlooked like it'd always be undefined.e(usually "event" or "error"), for consistency.something.hasOwnProperty('blah')was switched toObject.prototype.hasOwnProperty.call(something, 'blah'). More cumbersome, but more in keeping with modern practice, at least according to eslint. I think it's no longer considered safe to assume literally every object has all theObject.prototypefunctions available.Object.hasOwnis even more modern but requires ES 2022.Things I didn't clean up
require('xml-js')thing inableplayer-baseis supposed to work. Lmk if this needs more attention.varbased. I threw in the occasionalletorconstwhen it made sense but tried to stick withvars for consistency.windowhandler, or handlers on each individual player.slider-vertical: "[Deprecation] The keyword 'slider-vertical' specified to an 'appearance' property is not standardized. It will be removed in the future. Use<input type=range style="writing-mode: vertical-lr; direction: rtl">instead."Existing bugs I found but didn't fix
play()as returning a promise but I was not successful. Shrug.widthattribute has no effect inother-width.html. Only CSS width works.Test status
jeststill works as before. 1 test failing for reasons I'm not quite sure, but it's the same test that's already failing in upstreamdevelop.Files included in git but excluded from npm
This is crucial to keep the NPM package size manageable: about 15 megs, instead of 150.