Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,10 @@ updates:
open-pull-requests-limit: 10
labels:
- dependencies
groups:
angular:
patterns:
- "@angular/*"
- "@angular-devkit/*"
- "@angular-eslint/*"
- "ng-packagr"
56 changes: 56 additions & 0 deletions .github/workflows/angular-compat.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
name: Angular Compatibility

# Installs the packed angular-shepherd into a fresh app on every supported
# Angular major and checks that it builds and renders a tour. Keep the matrix
# in sync with peerDependencies in projects/shepherd/package.json.
#
# PRs and pushes run this through main.yml (workflow_call), so a dependency
# that breaks compatibility also blocks Dependabot automerge.

on:
workflow_call: {}
schedule:
# Weekly, so a new Angular major shows up via the `latest` entry.
- cron: '0 10 * * 1'
workflow_dispatch: {}

permissions:
contents: read

jobs:
pack:
name: Pack angular-shepherd
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
persist-credentials: false
- uses: volta-cli/action@v4
- run: npm ci
- run: npm run build_lib
- run: mkdir pack && npm pack ./projects/shepherd --pack-destination pack
- uses: actions/upload-artifact@v4
with:
name: angular-shepherd-tarball
path: pack/*.tgz

compat:
name: Angular ${{ matrix.angular }}
needs: pack
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
angular: ['18', '19', '20', '21', '22', 'latest']
steps:
- uses: actions/checkout@v4
with:
persist-credentials: false
- uses: actions/setup-node@v4
with:
node-version: 24
- uses: actions/download-artifact@v4
with:
name: angular-shepherd-tarball
path: pack
- run: compat/check.sh "${{ matrix.angular }}" pack/*.tgz "$RUNNER_TEMP/compat"
5 changes: 4 additions & 1 deletion .github/workflows/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,11 @@ jobs:
- run: npm install
- run: npm run lint
- run: npm run test -- --no-watch --no-progress --browsers=ChromeHeadless
angular-compat:
name: Angular Compatibility
uses: ./.github/workflows/angular-compat.yml
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
automerge:
needs: [test]
needs: [test, angular-compat]
runs-on: ubuntu-latest
permissions:
pull-requests: write
Expand Down
23 changes: 18 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,12 +20,25 @@ This is an Angular wrapper for the [Shepherd](https://github.com/shipshapecode/s
- Angular 15: 15.x
- Angular 16: 16.x
- Angular 17: 17.x
- Angular 18: 18.x
- Angular 19: 19.x
- Angular 20: 20.x
- Angular 21: 21.x
- Angular 18 and newer: latest

This has not been tested in anything but Angular 8+. It may or may not work in previous versions or subsequent versions of Angular. We would love to support multiple versions, if people with more Angular knowledge would be willing to help us out!
Starting with the release after 22.0.0, a single version of angular-shepherd supports Angular 18 and newer. Every supported Angular major is tested in CI by installing the packed library into a fresh app, building it, and checking that a tour renders (see `compat/check.sh`).

This release uses shepherd.js 16, which requires Node 20 or newer.

### Upgrading to shepherd.js 16

shepherd.js 16 replaced Floating UI with its own positioning engine, so the `floatingUIOptions` step option was removed. A step that still sets it logs a warning and uses default positioning. If you pass `floatingUIOptions` through `addSteps` or `defaultStepOptions`, move to `positionOptions`:

| Before | After |
| --- | --- |
| `floatingUIOptions: { strategy: 'fixed' }` | `positionOptions: { strategy: 'fixed' }` |
| `floatingUIOptions: { middleware: [offset(12)] }` | `positionOptions: { offset: 12 }` |
| `padding` on `shift()` or `flip()` | `positionOptions: { padding: 8 }` |
| Leaving out `flip()` | `positionOptions: { flip: false }` |
| `placement` | `attachTo: { on: 'bottom' }` |

There is no `middleware` option, so other custom Floating UI middleware has no equivalent. See [`StepOptionsPosition`](https://docs.shepherdjs.dev/api/step/interfaces/stepoptionsposition/) for every field.

## Installation

Expand Down
73 changes: 73 additions & 0 deletions compat/check.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
#!/usr/bin/env bash
# Verifies a packed angular-shepherd tarball works in a fresh Angular app.
#
# Usage: compat/check.sh <angular-version> <path-to-angular-shepherd.tgz> [work-dir]
# e.g. compat/check.sh 18 ./angular-shepherd-22.0.0.tgz
#
# Steps: `ng new` on the requested Angular version, install the tarball
# (without --legacy-peer-deps, so our peerDependencies range is checked too),
# `ng build`, then load the build in headless Chrome and assert the tour
# step and modal overlay rendered.
#
# Set CHROME to the Chrome binary if it is not `google-chrome` on PATH.
set -euo pipefail

VERSION="$1"
TARBALL="$(cd "$(dirname "$2")" && pwd)/$(basename "$2")"
WORK_DIR="${3:-$(mktemp -d)}"
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
mkdir -p "$WORK_DIR"
WORK_DIR="$(cd "$WORK_DIR" && pwd)"
COMPAT_DIR="$(cd "$(dirname "$0")" && pwd)"
CHROME="${CHROME:-google-chrome}"
APP="$WORK_DIR/compat-app"
export NG_CLI_ANALYTICS=false

rm -rf "$APP"
cd "$WORK_DIR"

echo "::group::ng new (Angular $VERSION)"
npx -y "@angular/cli@$VERSION" new compat-app \
--defaults --skip-git --skip-tests --minimal --skip-install --style=css
echo "::endgroup::"

cd "$APP"
echo "::group::npm install"
npm install --no-audit --no-fund
npm install --no-audit --no-fund "$TARBALL"
echo "::endgroup::"

cp "$COMPAT_DIR/main.ts" src/main.ts

echo "Angular $(node -p "require('@angular/core/package.json').version"), TypeScript $(node -p "require('typescript/package.json').version")"

echo "::group::ng build"
npx ng build
echo "::endgroup::"

DIST="$(dirname "$(find dist -name index.html | head -1)")"
PORT=$((20000 + RANDOM % 10000))
python3 -m http.server "$PORT" --directory "$DIST" > /dev/null 2>&1 &
SERVER_PID=$!
trap 'kill $SERVER_PID 2>/dev/null || true' EXIT
sleep 1

DOM="$("$CHROME" --headless=new --disable-gpu --no-sandbox \
--user-data-dir="$WORK_DIR/chrome-profile" \
--virtual-time-budget=5000 --dump-dom "http://localhost:$PORT/" 2>/dev/null)"

fail=0
for marker in 'shepherd-element' 'shepherd-modal-overlay-container' 'Compat step'; do
if grep -q "$marker" <<< "$DOM"; then
echo "✓ found $marker"
else
echo "✗ missing $marker"
fail=1
fi
done

if [ "$fail" -ne 0 ]; then
echo "Rendered DOM:"
echo "$DOM"
exit 1
fi
echo "Angular $VERSION: angular-shepherd builds and renders a tour."
29 changes: 29 additions & 0 deletions compat/main.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
// Entry point copied over src/main.ts of a fresh `ng new` app by check.sh.
// It starts a one-step tour so the check can assert that Shepherd rendered.
import { AfterViewInit, Component, inject } from '@angular/core';
import { bootstrapApplication } from '@angular/platform-browser';
import { ShepherdService } from 'angular-shepherd';

@Component({
selector: 'app-root',
standalone: true,
template: '<h1 class="first">angular-shepherd compat</h1>'
})
class AppComponent implements AfterViewInit {
private shepherdService = inject(ShepherdService);

ngAfterViewInit() {
this.shepherdService.modal = true;
this.shepherdService.addSteps([
{
id: 'compat',
title: 'Compat step',
text: 'Rendered by angular-shepherd',
attachTo: { element: '.first', on: 'bottom' }
}
]);
this.shepherdService.start();
}
}

bootstrapApplication(AppComponent).catch((err) => console.error(err));
Loading
Loading