Update Shepherd to the latest 14.5.0

[sdwjoomla]

GT version is 11.2 and the latest available as of May 2, 2025 is 14.5.0
The React Version should not be used, we use pure javascript

[garstud]

Steps to reproduce the issue

Guided tour import implements ShepherdJS library version 11.2.0 since 2023-09-02.

Expected result

Guided tour should works with a recent version of Shepherd, like the v14.5.0 (Last release on 2025-02-20).

Actual result

Guided tour is build and works only with the old Shepherd version (11.2.0).

System information (as much as possible)

It needs to review the dependencies and build Joomla distribution with the new Shepherd version and dependencies.

Additional comments

[garstud]

Preparing Shepherd & dependencies updates

I process to build a new Joomla 5.3.1 distribution with the new target of the Shepherd v14.5.0.

The dependencies have changed. To integrate Shepherd v11.2.0, we use :

• "@floating-ui/dom": "^1.5.1",
• "deepmerge": "^4.3.1"

Now for Shepherd v14.5.0, we need :

• "@floating-ui/dom": "^1.6.12", (update)
• "@scarf/scarf": "^1.4.0", (new dependencie)
• "deepmerge-ts": "^7.1.1" (new dependencie to replace classic 'deemerge')

I have executed the following commands before calling 'npm ci':

npm i --save @scarf/scarf
npm install deepmerge-ts
(whithout this dependencies, the CI won't works well).

The command 'npm ci' now works to import Shepherd v14.5.0.

Building the Joomla distribution with the new Shepherd

I don't succeed to execute the following last command:

npm install -g npm@lts

Error:

npm error code ETARGET
npm error notarget No matching version found for npm@lts.
npm error notarget In most cases you or one of your dependencies are requesting
npm error notarget a package version that doesn't exist.

Does somebody have a solution?

So i execute only:

npm install

The build of the Joomla v5.3.1-dev seems to ended correctly :

WARNING: 615 repetitive deprecation warnings omitted.
Run in verbose mode to see all warnings.

████████████████████████████████████████ 100% | 50/50 files done

[garstud]

Checking & Testing phase

I check the file \media\plg_system_guidedtours\js\guidedtours.js :

• at the top: i found "/*! shepherd.js 14.5.0 */" (line 1)
• by searching the word "joomla": i found the added joomla JS codes (lines 5466 to 6074)

I put all the Joomla generated files on my local web server :

• I completed the installation process.
• I logged in as an administrator.
• I completed the Welcome Tour.

Everything seems to works well!
(... but further testing is needed to ensure that all types of guided tours work well!)

[HLeithner]

Joomla is not able to update to shepherd js after 13.x, shepherd js changed it's license to a dual license for Commercial use with 14 which is not compatible with joomla's GPLv2 licence approach since we do not wan to restrict joomla to non commercial users. So please keep this in mind when updating, also we don't update dependencies within a minor version cycle so next possibility (if needed) is 5.4 oder 6.0.

[garstud]

Since the imported version of v11.2.0 (2023-09-02), there was 41 releases of Shepherd!
I've reviewed part of the md file's changelog since v11.2.0:
https://github.com/shipshapecode/shepherd/blob/main/CHANGELOG.md

I haven't noticed any issues that would affect the Joomla Guided Tours implementation, but I need more time to read all the version fixes.

There aren't many issues that impact the Shepherd Core code.
There are some tickets discussing improvements to Accessibility Mode browsing... worth testing!

• Prevent ESC, KEY_RIGHT, KEY_LEFT propagation when keyboardNav is enabled shipshapecode/shepherd#2399
• Accessibility issue: unnecessary tabstop shipshapecode/shepherd#3071

Some potentials interesting new features:

• Implement multiple element highlighting feature shipshapecode/shepherd#2995
• ✨ Add reading for isAutoStart value sent from app shipshapecode/shepherd#2895

And bug fixes that might have a positive (or negative) impact on Guided Tours:

• ✨ Update shepherd element to use html dialog shipshapecode/shepherd#2982
• 🐛 Fix event timing issue and add button for demo start shipshapecode/shepherd#2980
• 🐛 Add small padding to arrow if edge alignment is used shipshapecode/shepherd#2900

[garstud]

Joomla is not able to update to shepherd js after 13.x, shepherd js changed it's license to a dual license for Commercial use with 14 which is not compatible with joomla's GPLv2 licence approach since we do not wan to restrict joomla to non commercial users. ....

Yes you're right, and joomla Team (@exlemor ) has contact them to make a partner ship ... They agree to give Joomla a free access ... but I agree that we need to wait for a written approval ;)
CC @obuisard

[garstud]

.... So please keep this in mind when updating, also we don't update dependencies within a minor version cycle so next possibility (if needed) is 5.4 oder 6.0.

Ok, i see i don't use the correct branch version (5.3.1-dev) ... it was just a test, we will target Joomla 6 (because not sure it can be done in Joomla 5.4? If there doesn't seem to be any backward compatibility issues, the patch introduces new dependencies, so ...)

[HLeithner]

Didn't see any written permission, even then I'm not sure if it make sense to support this approach, because it makes it more complicate for joomla and for 3 Integrators / extension developers. Maybe finding an alternative or forking it makes more sense. At least for now I would only target 13.x until Production decided if the license change with exception is suitable for joomla.

[sdwjoomla]

@exlemor reported sending communications with Shephard.js to the maintainers team.

[garstud]

After J6.0 release, build a joomla web site to test the last Shepherd shepherd.js 14.5.1 (july 2025)
https://github.com/shipshapecode/shepherd/releases