Improved advanceOn: Conditional inputs for touring through forms

Bắt đầu bằng cách đọc cách xử lý advanceOn hiện có của Shepherd và các định nghĩa tùy chọn TypeScript của nó, sau đó so sánh chúng với hành vi advancing-on-actions được ghi trong tài liệu và API beforeShowPromise. Xác định những sự kiện đầu vào có điều kiện và các kiểm tra giá trị nào nằm trong phạm vi của đề xuất. Được xem là hoàn tất khi API được chọn đã được ghi trong tài liệu, định kiểu, triển khai và được bao phủ bởi các bài kiểm thử cho những tương tác biểu mẫu được hỗ trợ.

Context

I have an application, where we are touring the user through forms.
It explains how to filter for data and how to submit queries.
Shepherd.js already allows some basic advancing using the advanceOn property;

{
  title: 'Click the button',
  buttons: [], // do not allow to advance by buttons
  advanceOn: {
    selector: '.my-form button',
    event: 'click'
  }
}

However, we have some steps, where I want to explain to the user that selecting a specific value in a <select/> or entering a specific text in an <input type="text"/>. That is not possible with advanceOn.

Workaround

Using when, it is possible to add custom triggers.
Example:

// event handlers
export const whenInputOnEnterValue = (
    elementSelector: string,
    expectedValue: string
): {
    show: () => void;
    hide: () => void;
} => {
    return {
        show: () => {
            createEventOnEnterInputValue(elementSelector, expectedValue);
        },
        hide: () => {
            removeEventOnEnterInputValue(elementSelector);
        }
    };
};

const createEventOnEnterInputValue = (elementSelector: string, expectedValue: string): void => {
    if (stepEventListener) {
        throw new Error('Event listener already created');
    }
    stepEventListener = (event) => {
        if (!(event.target instanceof HTMLInputElement)) {
            return;
        }

        if (event.target.value !== expectedValue) {
            return;
        }

        document.dispatchEvent(new Event('shepherd:next')); // Advancing using https://docs.shepherdjs.dev/guides/usage/#advancing-on-actions
    };
    document.querySelector(elementSelector)?.addEventListener('input', stepEventListener);
};

const removeEventOnEnterInputValue = (elementSelector: string): void => {
    document.querySelector(elementSelector)?.removeEventListener('input', stepEventListener!);
    stepEventListener = null;
};

// shepherd.js
    {
        attachTo: {
            element: '.my-form select#type',
            on: 'bottom'
        },
        canClickTarget: true,
        buttons: [],
        title: 'Select "Type 1" to continue',
        when: whenInputOnEnterValue('.my-form select#type', 'Example Type 1')
    },

This workaround is annoying for the following reasons;

• Additional boilerplate code for registering events
• Additional code that must be tested with unit tests
• Doesn't reuse the advanceOn object.
• We have automated bots that click through tours to ensure that they still work. The when property (or any callback for that matter) is really hard to test with. Static values in a property would be much easier.

[!NOTE]
The above example is simplified and does not compile for the sake of a minimal example.

Suggestion

It would be nice, if Shepherd would allow for more complex advanceOn, similar to the async beforeShowPromise().
A possible API implementation could be the following:

{
  title: 'Click the button',
  buttons: [], // do not allow to advance by buttons
  advanceOn: {
    selector: '.my-form select#type',
    elementEvent: 'change-select-option',
    optionValue: 'example-type-1' // Use TypeScript Unions to only allow this option when 'elementEvent' is set to 'change-select-option'
  }
}

Alternatively,

{
  title: 'Click the button',
  buttons: [], // do not allow to advance by buttons
  advanceAfter() {
    await waitForSelection('.my-form select#type', 'example-type-1');
  }
}

Environment

Node: v24
angular-shepherd@19.0.2
shepherd.js@15.2.2