Version switcher

[davepagurek]

Here's an experiment to see what a version picker could look like on the web editor.

What works so far:

• Updating the version when index.html is edited seems stable and not super laggy!
• The logic of detecting a version only if we see exactly one script tag that we recognize seems to feel right

Screen.Recording.2025-02-06.at.8.24.27.PM.mov

What does not work so far, if I uncomment the code to actually replace the contents:

• After replacing, dom.documentElement.outerHTML doesn't have quite the same formatting as before (e.g. the DOCTYPE tag is gone) -- maybe there's another attribute I can use, need to experiment more
• Is there a good way to force CodeMirror to update when this happens? I have a commented-out attempt to replace its contents when the props change and are different than the current content, but this also has the effect of preventing people from typing.

Screen.Recording.2025-02-06.at.8.17.15.PM.mov

[welcome]

🎉 Thanks for opening this pull request! Please check out our contributing guidelines if you haven't already.

[davepagurek]

I made some updates to put the version settings in a modal! To do that, I mostly had to switch the tabs to being controlled instead of uncontrolled so that I could make an action that sets the starting tab.

Screen.Recording.2025-02-19.at.8.18.53.PM.mov

One thing that isn't quite handled yet is multiple p5.sound versions, that might take a bit more thought.

[davepagurek]

I looked into a few HTML parsing options using libraries, and.... none of them did a better job than the native DOMParser API at preserving whitespace (meaning: it doesn't do a great job.) So for now I'm just going to keep using the DOMParser API, and possibly if we want we can make it also run Tidy Code afterwards.

[davepagurek]

Another update! Now I'm detecting p5.sound versions, and offering a button to revert back if it was something non-default and we change it at all. This is stored in React state for the IDE view, so even if you close and open the preferences modal, the revert button will still be available.

Screen.Recording.2025-02-27.at.6.07.01.PM.mov

[ksen0]

Hi @davepagurek , just checked this out with @raclim !

What do think if the big button is not a button but an explanation of what happens if you click "on?" Right now looks like the big button reverts but the "On" button will update to a new version, which is a little unintuitive, so we were thinking about how to make it a bit more understandable.

What if there are still only "on" and "off" as clickable buttons, but in this special state, there's a (pink, obvious, bold?) text like "Want to turn this addon back on? The editor will use the original version you were using before turning it off!"

This is stored in React state for the IDE view, so even if you close and open the preferences modal, the revert button will still be available.

Sounds like this means if the user closes the tab and reopens, the information is lost? That seems fine for me, since then the basic idea of "go back to what you had before" is also very hard to remember and interpret.

[davepagurek]

What if there are still only "on" and "off" as clickable buttons, but in this special state, there's a (pink, obvious, bold?) text like "Want to turn this addon back on? The editor will use the original version you were using before turning it off!"

Agreed, that sounds like more intuitive behaviour. It does mean that old sketches wouldn't have an easy way to switch to using the new p5.sound.js, is that OK? I think that leads to the least confusion for now, and maybe in the future we could add a button like "Try the new p5.sound addon" once we or a contributor has the time to consider the UX edge cases.

Sounds like this means if the user closes the tab and reopens, the information is lost? That seems fine for me, since then the basic idea of "go back to what you had before" is also very hard to remember and interpret.

Right, exactly.

[davepagurek]

Here's an initial little animation to play when 2.0 is selected!

Screen.Recording.2025-03-11.at.1.27.15.PM.mov

[davepagurek]

Ok the p5.sound toggle now looks like this if you turned off a custom version, and toggling it back on restores it:

I've also made some UI updates to allow the long dropdown of versions to scroll, and detect p5.sound.min.js along with just .js.

Still to do before this is shippable:

• The version picker itself is pretty unstyled currently, it could look more like a dropdown
• Looks like there are some variations on the figma that use admonitions, @raclim do we want to switch to that?
• We have some description text missing too that we'll want to fill in

[ksen0]

That looks great @davepagurek !

It does mean that old sketches wouldn't have an easy way to switch to using the new p5.sound.js, is that OK? I think that leads to the least confusion for now, and maybe in the future we could add a button like "Try the new p5.sound addon" once we or a contributor has the time to consider the UX edge cases.

Reasonable!

We have some description text missing too that we'll want to fill in

I think this should is linking to the 2.0 beta reference website and the "Switching to 2.0" tutorial which is WIP for now

[raclim]

@davepagurek I love the animation, it's so cute!!!

Looks like there are some variations on the figma that use admonitions, @raclim do we want to switch to that?

Thanks for mentioning the admonitions in the figma! It was mostly added as a suggestion—I forgot that I wanted to ask if you and @ksen0 had thoughts on it?

[davepagurek]

I like them! do you know if we have them anywhere else in the web editor yet or if it would be a new component?

Also do you know if we have a button with a down arrow resembling a <select> yet that I can use for the version picker button, or is that also something new?

[raclim]

The closest thing that we have to it so far is toast messaging, but I feel like it will probably be a new component!

I don't think we have anything like that yet either 😅 I think the button doesn't have to resemble the one in the design too much though!

[davepagurek]

Updated some of the styles! The dropdown looks a bit less jank, and we use an admonition now.

I think that mostly leaves the description left unimplemented.

[ksen0]

@davepagurek This was pending the CM6 upgrade which will need ~2-3 weeks (after p5.js 2.0 release in any case). So we can move forward without waiting to resolve this TODO but need to keep it in mind when the upgrade is happening, @raclim will coordinate!

[davepagurek]

I think I made this not break on the current version of CM so I think this TODO comment may be good to remove. I'll double-check this week!

[ksen0]

This is looking great! Minor comments below.

(1) Admonition - the functionality is great but Rachel and I were discussing color and title choice, given one of the original design intents:

If version management from the editor is not possible, then the UI should not just look “off” or “broken”. It should be clear that there is a reason the version is not editable. For example, if someone uses index.html to manage their own version, the UI shouldn’t make it look like an error or bad just because it can’t be managed from the settings modal

How about:

• Gray not pink box (flower is a nice touch but pink is too close to red and looks like a "warning" or that something is "broken")
• Title - rather then "Note" what about something like... "Managing your own libraries? Nice!" (if you think of another phrasing, feel free to use that, but the point is that it's not an error, or mistake, if it's intentional, and is actually a very reasonable use-case and worthy of positive acknowledgment)

The copy itself looks great.

(2) the "TODO add helpful info..." - how about:

There's a new 2.0 release of p5.js available! It will become default in August, 2026, so take this time to test it out and report bugs. Interested in transitioning sketches from 1.x to 2.0? Check out the compatibility & transition resources.

It's kind of kicking the can down the road (for me to add transition instructions to the p5.js-compatibility repo) but I think if we have ONE link, it feels like it should be the compatibility add-ons link in particular. If there's a better link, like a transition tutorial, we can update this copy, so it doesn't need to be blocking.

So with the above, if it sounds alright to you, I think we can call this one done!

[davepagurek]

That all sounds good to me! I'll make those updates this week. I assume then we'll leave this PR open until the 2.0 release and then merge after that?

[ksen0]

@davepagurek Yes, that sounds great! I can give approval whenever it's done and we can just coordinate on merge timing.

[davepagurek]

Here's what it looks like now! I saw in the figma a blue variant, which I used here because it felt like it had a little more contrast than another shade of grey, but I can also try a grey variant if you prefer.

Also @raclim I wasn't sure if there was a precedent yet for translatable text that has links within it so I ended up putting some markdown in the translations file and using the existing react-markdown dependency to render it. This seemed maybe simpler for translators than splitting up the different chunks around the <a> and </a>s into different translation strings, but let me know if there's something else we prefer there.

[davepagurek]

It also occurs to me that before actually updating (and also after each release), we'll want to update the list of p5 versions on npm here:

p5.js-web-editor/client/modules/IDE/hooks/useP5Version.jsx

Lines 9 to 14 in 53a517b

	export const p5Versions = [
	'1.11.3',
	'2.0.0-beta.2',
	'1.11.2',
	'1.11.1',
	'1.11.0',

This will work for now but let me know if there's any way I can make it easier to integrate this into the release workflow for the future!

Also one last small blocking update: once we make a public release of the p5.js-compatibility repo, I need to update the URLs for that.

[GregStanton]

Hi all! The design is looking good! I like how it integrates with the existing modal for settings, while also providing an extra cue above the editor for discoverability. The copy and aesthetics also look great (not to mention the fun animation Dave added!). Below, I'll outline a few possible accessibility and usability improvements. (I'm partly going off of the screen recordings and captures, so it's possible some of these points have already been addressed.)

Color contrast (accessibility)

Have you run the new colors through a contrast checker for accessibility? For example, it looks like the colors (background: #E4F8FF, foreground: #0E86A1) in the admonition for "Managing your own libraries? Nice!" might fail WCAG, according to the WebAIM contrast checker.

Version-number button (accessibility, discoverability)

Hover behavior, persistent visual cue

To the left of the version number, the text "sketch.js" isn't interactive. To the right, the "Preview" text isn't interactive. The version number is interactive, but there's no visual distinction between it and those neighboring elements. There are two things we might add to the version number, both of which would improve consistency with existing features and therefore guide user expectation:

1. Could we make the text change to red on hover?
2. Could we add a persistent visual indicator of interactivity?

An extra visual indicator would be in line with the WCAG recommendation to not rely on color alone to distinguish a visual element, and it'd indicate interactivity without requiring the user to hover with a mouse. For this purpose, similar features currently use a dropdown icon, a pencil icon, or a checkbox. In this case, how about a small version of the gear icon, to indicate that this feature will open the settings modal?

(There doesn't seem to be a standard icon for buttons that open a modal. An ellipsis does seem to be a standard way to indicate that further action is needed—according to WAI and UX Stack Exchange—but that might be problematic here. Specifically, an ellipsis might be confusing after a version number that already uses periods as separators; it's also not an icon, so it'd be inconsistent with the other features.)

Positioning

I suspect there will be greater user engagement if we move the version number to the right of the auto-refresh and project-title features. I'm not sure if there are any significant cons to this, but here are a couple of pros:

1. This would be an extra cue for discoverability—instead of being between two non-interactive elements ("sketch.js" and "Preview"), possibly causing it to be "camouflaged," it'd be located alongside other interactive features, in accordance with the principle of proximity.¹
2. It'd make it possible to provide a larger area for users to tap or click on, without requiring a change to the overall page design. (See WAI and WCAG for relevant guidelines.)

Putting it on the right would also maintain the placement of the existing features, so that the interface would conform to the expectations of current users.

Explanatory text for p5.sound.js add-on (accessibility, semantics)

Could we wrap the radio group in a <fieldset> element and include a <legend>? According to WAI, "Radio button groups should always be grouped using <fieldset>." This seems to be a more accessible and semantic way of associating the conditional explanation ("Want to use p5.sound.js again? Turning it back on...") with the controls.

More generally, it looks like a good idea to replace the <div> containers for the various radio groups with <fieldset> containers. Sorry... if this change is made, I guess it might necessitate some changes to the CSS too! But I think it's worthwhile from an accessibility standpoint.

I'm not sure, but I think you can get the correct positioning by replacing the <legend>'s CSS in this Codepen sample (cited in this Stack Overflow answer) with the following:

legend {
  font-weight: bold;
  float: right;
  margin-bottom: .5em;
}

In case you run into any other issues, there's a breakdown of special styling considerations for <fieldset> on MDN.

Compatibility add-ons

Two questions:

1. Would it make sense to change the umbrella term for these features from "p5.js 2.0 Addon" to "p5.js 1.x Compatibility addon"? Some user testing would be helpful, but to me, the name "p5.js 2.0 Addon - Shapes" suggests this feature adds shapes to p5.js 2.0, which isn't accurate. If we combine "p5.js 1.x Compatibility addon" with conditional behavior (e.g. by graying out the options unless 2.0 is the selected version), the meaning may be clearer. Here, I'm adding to a comment from @xinemata on the figma that was shared.
2. Could we switch from "Addon" to "Add-on"? I know "addon" does get used in practice, so this isn't a hill I will die on 😅 However, I find "add-on" to be less confusing, and it seems to be far more standard. ²³ Especially for users with limited English proficiency, I'd expect it to be easier to parse "add-on" and to look it up in references. The trade-off is readability vs. writability, but in this context, I think readability wins hands down.

Bug?

I noticed that it's possible to tab to the settings button and open it with Enter, but it looks like it's not possible to tab through the options in the modal. When I tried to do that, tabbing moved me to the sidebar button and then the editor. I'm guessing this would make the features inside the modal (including the new versioning feature) inaccessible to keyboard users? What do you think, @raclim? If this is a real issue, maybe we could open a separate PR to deal with this.

Minor polish

Please forgive me for being me here... If you all prefer to ignore the following points, I would understand 😜

1. Could we consistently use either title case or sentence case everywhere? In the English-language site, title case (e.g. "Library Management") is used almost consistently, but there are some instances of sentence case (e.g. "General settings"). There's a bit of scope creep with this one, but it probably wouldn't take much time to resolve.
2. Could we use an em dash in the add-on names, like "p5.js 2.0 Add-on — Shapes," instead of a hyphen? I don't think any style guides would call for a hyphen here, and a long dash would be easier to parse if we switch to "add-on" being hyphenated. (But if anyone across the pond prefers an en dash, I wouldn't complain too much😄) A colon would work too.

Footnotes

1. "Items close together are likely to be perceived as part of the same group — sharing similar functionality or traits... On the other hand, grouping together unrelated elements may camouflage them from users... When looking around the page, users may only look at one item within a perceived grouping and use that to make a judgement about what the other items in that group must be." ↩

2. According to Google Ngram, "add-on" is about an order of magnitude more common in books. The surge in usage after the year 2000 suggests that much of the usage may be specific to information technology. ↩

3. Of the three dictionaries I checked, the term "add-on" appears in all of them (Merriam Webster, Cambridge Dictionary, and Collins Dictionary), whereas "addon" appears in none of them. ↩

[davepagurek]

Thanks @GregStanton! I pushed some updates:

• Colors of the admonition are modified from the figma to be contrasty enough to pass the contrast check
• We use fieldset and legend now (I had to use display: contents for it to render like a normal element, TIL about that value)
• Used em dashes 🙂
• Added the data addon (all URLs are still placeholders for now)
• Fixed a bug where I copy and pasted another aria label for all the compatibility addons but never changed them
• Added a hover style to the p5 version button + the settings gear icon after it

So far I haven't changed the position of the version switcher yet, or changed to "add-on" (that's a quick change, we just need to also update the p5.js-compatibility repo to match -- also, one other data point, we refer to addons as "libraries" on the p5 site) -- let me know what you think about those @ksen0! None of them are difficult changes if we want to do them, just want to make sure we've got consensus.

[ksen0]

Hi @GregStanton and @davepagurek , thanks so much for this really thorough review and update! Here's another co-authored review from @raclim and I.

Terminology: "add-on library"

Addon vs add-on: I've only ever see "addon" as a term in the p5.js ecosystem, and it seems to be used, e.g., in contributor documentation, which call them "addon libraries" as yet another data point. Using either add-on or library would be an update from prior language, and neither Rachel nor I have attachments about it. On discussion, we would suggest "add-on library" which is the corrected spelling of an already common phrase.

"Library"

• Pro: more commonly used outside of p5.js; definitely used in p5.js as well (including on the website)
• Con: arguably less intuitive, it's a term of art? However, using more common terminology more consistently would be in line with the changes we're making more generally in this phase of the project

"Add-on"

• Pro: correct spelling of Addon
• Con: it's a change (all change needs some amount of change management, including updating docs etc, which is effort) but it's not a meaningful change (so why make the effort?)

Compromise (yes, and): "Add-on Library?"

• Pro: not incorrect in any particular way
• Con: still change management (e.g., need to update contributor docs?)

Compatibility Addons Add-on Libraries

Would it make sense to change the umbrella term for these features from "p5.js 2.0 Addon" to "p5.js 1.x Compatibility addon"? Some user testing would be helpful, but to me, the name "p5.js 2.0 Addon - Shapes" suggests this feature adds shapes to p5.js 2.0, which isn't accurate. If we combine "p5.js 1.x Compatibility addon" with conditional behavior (e.g. by graying out the options unless 2.0 is the selected version), the meaning may be clearer.

This makes a lot of sense. I just made a PR in the compatibility repo to update the language accordingly.

@davepagurek is it straightforward to add conditional graying out to the compatibility add-on libraries? Unless it is extremely easy, I think it's not necessary but a nice to have.

Version placement

Other relevant considerations: there is also a "copy" button coming to the web editor, which would copy the text content from the part of the code currently displayed to clipboard.

Even without that, on consideration, the challenge with the version switched being in its current position is that it's sketch-specific not file-specific so its scope should visually be on sketch not on file.

If placing it to the right of Auto-refresh and Title, then there's a problem with clickability: the settings icon is the one that makes most sense (great analysis btw @GregStanton thank you for thinking though it) but there's already a gear on the right edge of the panel.

Would it fulfill the criteria of clickability and sketch-level scope to have a big button like this next to the gear? It's also related to the gear. Arguably, it's redundant (they open the same modal) but this way doesn't change existing behavior, and adds a more visible version number.

Also, does this make sense to you both: When we are in the case where version cannot be managed, this element is not visible but the user can still read the details in the normal settings modal > Library management?

We are not totally convinced by this idea ourselves, so more ideas on this are welcome. (Unless we have collectively some up with how to improve it, let's keep it as it is, though.)

Bug? Yes

I noticed that it's possible to tab to the settings button and open it with Enter, but it looks like it's not possible to tab through the options in the modal. When I tried to do that, tabbing moved me to the sidebar button and then the editor. I'm guessing this would make the features inside the modal (including the new versioning feature) inaccessible to keyboard users? What do you think, @raclim? If this is a real issue, maybe we could open a separate PR to deal with this.

Yes this is a bug, please feel free to create the PR!

Modal tab case: "Library Management" and "General Settings"

All tabs should be title case ("Library Management" and "General Settings") - but Rachel can use this as an example in her upcoming contribution workshop, so we made it into an issue.

In this PR, please keep using title case for Library Management and ignore General Settings.

Release

@davepagurek: "Also one last small blocking update: once we make a public release of the p5.js-compatibility repo, I need to update the URLs for that."

I made an initial release for compatibility repo but it doesn't have the correct data addon. So I need to update that and will ping when I do. Is it possible to poll from npm / GH to get latest addon release? Or are compatibility versions also needing to be manually maintained in this list as for p5.js?

[davepagurek]

Also, does this make sense to you both: When we are in the case where version cannot be managed, this element is not visible but the user can still read the details in the normal settings modal > Library management?

Some initial thoughts on this design:

• We might need the context of a "p5.js version" label, since I'm not sure the number will have meaning to unfamiliar users otherwise. Do we have room to have that still?
• It might be a little confusing if it fully goes away when on a custom version, e.g. if an accidental change to index.html causes that

Another idea could be to keep the positioning where it is, but add some kind of notification dot or other indicator (slowly pulsing the color of the text?) the first time a user sees the version picker that goes away permanently once they click it. That could let people know that it exists, but still keeps it sort of out of the way after that. For clickability, with an icon + hover state, it already matches the clickability of the editable sketch title above, so I think that could be sufficient if we don't also need more visibility.

@davepagurek is it straightforward to add conditional graying out to the compatibility add-on libraries? Unless it is extremely easy, I think it's not necessary but a nice to have.

I think the ideal behaviour is like, when you switch to 1.x, it hides the compatibility addon toggles and and also turns them off, but also it remembers what you had so that if you switch back to 2.x, you return to the same state as before. So far I've left them visible all the time so that at least you can manually enable/disable. I think nothing blocks implementing this other than taking the time to do it, which is a little less easy than just conditionally hiding as it adds some state management, but I'll try to get to that this week.

I made an initial release for compatibility repo but it doesn't have the correct data addon. So I need to update that and will ping when I do. Is it possible to poll from npm / GH to get latest addon release? Or are compatibility versions also needing to be manually maintained in this list as for p5.js?

So far it's manual. A while ago I started looking into getting version info from npm for the libraries page of the p5 site, so it's definitely possible, but it's unclear what the API rate limits are, so ideally this would be something we could fetch only periodically (e.g. just when we deploy a new version?) instead of doing it live for every visitor. It'd be great to be able to do this with the p5 version list too.

@raclim do you know if there's anything existing in the setup so far to run and cache a value once on deploy? Alternatively, we could put those values in a special file that gets auto-generated via a script that we manually run sometimes. In any case, we can launch without this, but we could reduce the amount of maintenance in the future with this.

[ksen0]

Another idea could be to keep the positioning where it is, but add some kind of notification dot or other indicator (slowly pulsing the color of the text?) the first time a user sees the version picker that goes away permanently once they click it. That could let people know that it exists, but still keeps it sort of out of the way after that. For clickability, with an icon + hover state, it already matches the clickability of the editable sketch title above, so I think that could be sufficient if we don't also need more visibility.

I think that makes sense conceptually, I don't mind keeping it where it is. @GregStanton do you see any accessibility concerns about the dot concept here?

I think the ideal behaviour is like, when you switch to 1.x, it hides the compatibility addon toggles and and also turns them off, but also it remembers what you had so that if you switch back to 2.x, you return to the same state as before. So far I've left them visible all the time so that at least you can manually enable/disable. I think nothing blocks implementing this other than taking the time to do it, which is a little less easy than just conditionally hiding as it adds some state management, but I'll try to get to that this week.

This behavior can also be an issue and a future work separate from this PR.

So far it's manual. A while ago I started processing/p5.js-website#158, so it's definitely possible, but it's npm/feedback#658, so ideally this would be something we could fetch only periodically (e.g. just when we deploy a new version?) instead of doing it live for every visitor. It'd be great to be able to do this with the p5 version list too.

What about an action to pull versions every month or so (can also be triggered manually) and that creates a PR with the updated lists? Also a fine issue for the future and out of scope for this PR.

[ksen0]

Overall, there are some outstanding points that can be follow-up issues, but it looks great and just about ready to go when the new release is ready.