Customize scroll behavior

[compulim]

Fixes #2884.

Changelog Entry

Added

• Added new style options to customize auto-scroll, by @compulim in PR #3653
  • Set autoScrollSnapOnActivity to true to pause auto-scroll after more than one activity is shown, or a number to pause after X number of activities
  • Set autoScrollSnapOnPage to true to pause auto-scroll when a page is filled, or a number between 0 and 1 to pause after % of page is filled
  • Set autoScrollSnapOnActivityOffset and autoScrollSnapOnPageOffset to a number (in pixels) to overscroll/underscroll after the pause
• Supports multiple transcripts in a single composition, by @compulim in PR #3653

Description

Added style options to customize scroll behavior by pausing at specified "snap point".

Currently, support 2 snap points:

• Pause after a percentage of page is filled
• Pause after X activities arrived

In additional to snap points, 2 more options to specify number of pixels to overscroll or underscroll. If both options are specified, it will use the value that would pause the auto-scroll sooner.

The following video demonstrates the pause after 2 activities and 100 pixels. The cyan color indicates acknowledged activities and orange color indicates recently arrived activities. Equivalent to setting:

styleOptions = {
  autoScrollPauseOnActivity: 2,
  autoScrollPauseOnActivityOffset: 100
};

Media1.mp4

Design

Default behavior

By default, we did not enable this feature. We should consult our UX team before turning it on by default.

Activities acknowledgement

To pause, only unacknowledged activities are taken into account. For example, the page will pause after it filled with activities the user didn't positively indicate they have been read.

Acknowledgement means: activity is positively acknowledged by the user. If the user does not interact on Web Chat, no activities should be acknowledged.

Currently, we use 2 signals for indicating acknowledgement:

• When the user scroll to the bottom of the page
• When the user sent a message

The signals above positively identify the user read the content.

Since the DLJS and other chat adapters do not keep this acknowledgement information, we will assume, when Web Chat started, all activities are acknowledged (e.g. restoring from conversation history). And it will stop auto-acknowledging when the user send their first message.

Due to the limitation of chat adapter, we recommend content author not to send initial activities (a.k.a. welcome messages) longer than a page.

Allowing multiple instances of <BasicTranscript>

Last October, when we work on the feature to refactor some React components into API layer, the way we refactor <BasicTranscript> does not allow multiple instances of it inside the same composition (i.e. <Composer>).

In this PR, we also addressed it by allowing multiple instances of <BasicTranscript>, such as:

<Composer directLine={...}>
  <BasicTranscript />
  <BasicTranscript />
</Composer>

Resolving #2884

In #2884, the developer prefers to pause "after 1 activity and 2.5 lines of text". Since line of text is not trivial to measure in HTML, we fallback to pixels instead.

To resolve #2884, the developer should set the following style options:

styleOptions = {
  autoScrollPauseOnActivity: true,
  autoScrollPauseOnActivityOffset: 100
};

Specific Changes

• Modified <Composer> and corresponding hooks to support multiple instances of <BasicTranscript>
  • This is done by multiplexing several hooks
  • For example, when useScrollTo is being called, we will multiplex this call into all instances of <BasicTranscript>, instead of one
• Added 4 style options: autoScrollSnapOnActivity, autoScrollSnapOnActivityOffset, autoScrollSnapOnPage, autoScrollSnapOnPageOffset
• Bumped [email protected] to support pausing at a specific scrollTop position (Add scroller prop to programmatically pause scrolling and initialScrollBehavior compulim/react-scroll-to-bottom#73)

• I have added tests and executed them locally
• I have updated CHANGELOG.md
• I have updated documentation

Review Checklist

This section is for contributors to review your work.

• Accessibility reviewed (tab order, content readability, alt text, color contrast)
• Browser and platform compatibilities reviewed
• CSS styles reviewed (minimal rules, no z-index)
• Documents reviewed (docs, samples, live demo)
• Internationalization reviewed (strings, unit formatting)
• package.json and package-lock.json reviewed
• Security reviewed (no data URIs, check for nonce leak)
• Tests reviewed (coverage, legitimacy)

[amal-khalaf]

this one test validation failed as well due to inequality due to rounding to nearest decimal
Expected: 353
Received: 352.6666564941406
not sure if you saw same error before or it is a problem with my browser/display?
and i am also thinking if we could give a margin of error to make test more resilient?

[compulim]

Are you running the tests under Docker (i.e. via Jest)?

[amal-khalaf]

yes

[corinagum]

add "therefore... + explanation"

[compulim]

Added:

//      5. Therefore, even the developer set "pause after 3 activities", if activities are coming in at a slow pace (not batched in a single render)
//         Web Chat will keep scrolling and not snapped/paused

[corinagum]

Don't see 5. added to the code yet, but looks good.

Suggested change

	// 4. Acknowledge flag become useless
	// 4. Acknowledge flag becomes useless
	// 5. Therefore, when the developer sets "pause after 3 activities", if activities are coming in at a slow pace (not batched in a single render)
	// Web Chat will keep scrolling and not become snapped/paused

[corinagum]

LGTM - I approved (with comments), but since @amal-khalaf is reviewing as well, I recommend waiting for her approval too.

[Sandy2725]

Hi @compulim ,

Hope you are doing well.

I have two queries.

1.If we pass the scroll after 1 activity its working fine. But if we have a large content in the 1st message only again the scrollbar is going down. is there any way to focus on at staring of that first message.
2. And if response contains more than (150 or 200 words) or 10 lines. can we add readmore link and then when we click on readmore user can see rest. like after 100 words or 5 lines. for buttons we have readmore but inside the message response do we have that.

Thanks.

[Sandy2725]

HI @compulim ,

Can we implement this custom scroll behavior for specific responses. Is there any possibility to implement for only few responses.

styleOptions = {
autoScrollPauseOnActivity: 2,
autoScrollPauseOnActivityOffset: 100
};

Thanks .

[Elephantei]

After updating the framwork-sdk to 4.12.1 and setting the following styleOptions this still doesn't work:

version:
<script src="https://cdn.botframework.com/botframework-webchat/4.12.1/webchat-es5.js" integrity_no="sha384-YT//LqZJgkEXrmVxm6RZJKs4dSZJQo5kEX0tE9dP1XaOaVsC7NEvwnlP2gW2KWcl" crossorigin="anonymous"></script>

Styling options added for the chat rendering options:

window.WebChat.renderWebChat(
  {
    directLine: window.WebChat.createDirectLine({
      token: process.env.TOKEN,
    }),
    onTelemetry: handleTelemetry,
    store: store,
    styleOptions: {
      hideUploadButton: true,
      autoScrollPauseOnActivity: 2,
      autoScrollPauseOnActivityOffset: 100
    },
  },
  document.getElementById("webchat")
); 

Can someone shed some light on it?

[Sandy2725]

Hi @Elephantei ,

Try with below style options.

autoScrollSnapOnActivity:2,
autoScrollSnapOnPage:true,
autoScrollSnapOnActivityOffset:100,

[Jakob-vdH]

Hi @Sandy2725

thank you for your help, this worked for us really well for a bit.
Just to recap, with the following settings, the webchat was always scrolling to the top edge of a new message / adaptive card, if some messages were in the chat, that were longer that the view, which was awesome behavior.

autoScrollSnapOnActivity:2,
autoScrollSnapOnPage:true,
autoScrollSnapOnActivityOffset:100,

But now we updated to the last webchat version (4.15.2) and this just stopped working, not scrolling anymore at all as soon as the "page" is full with messages. I guess this is intended behavior of autoScrollSnapOnPage.
Is there an option to always scroll to the top of a message if it is longer than the current view?
We tried recreating the initial behavior using the autoScrollSnap options, but sadly did not succeed.