Skip to content

feat: step-through walkthroughs for doc pages - #6667

Merged
emarc merged 4 commits into
mainfrom
feat/copilot-walkthrough-stepper
Nov 16, 2026
Merged

emarc merged 4 commits into
mainfrom
feat/copilot-walkthrough-stepper

Conversation

@emarc

@emarc emarc commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

Adds a step-through player for walkthrough clips: a walkthrough is a list of steps, each with a short clip, shown one step at a time. A clip plays on its own while it's in view, and there are light and dark versions.

The markup is generated AsciiDoc (a list of steps with media), so a page without the script still reads as a plain list. Used by the Copilot feature walkthroughs in the stacked PR.

Changes dspublisher/theme/ only: walkthrough.ts, its styles in global.css, and the init in init-browser.ts.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Rq75h4rxBUs4mABwUwqNuJ

A [.walkthrough] ordered list, one step per item with a short looping clip
or a still, becomes a stepper: one step at a time with Back and Next, the
arrow keys, and Show all steps for the list. Clips have a -dark twin that
is shown in the dark theme. Without the script the list reads as is.
A [.walkthrough] block without a list is a single clip, for a page that
has a section for each. It gets the same Pause button and dark-theme
twin as the steps, and plays only while it's in view. The frame around
a walkthrough is now only for the stepped ones.
@cla-assistant

cla-assistant Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@cla-assistant

cla-assistant Bot commented Nov 13, 2026

Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

@emarc
emarc force-pushed the feat/copilot-walkthrough-stepper branch from 66a35b6 to 6eea308 Compare November 13, 2026 08:21
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Preview Deployment

This PR has been deployed for preview.

URL: https://docs-preview-pr-6667.fly.dev

No documentation page changes detected.

Built from a966723

@emarc
emarc marked this pull request as ready for review November 13, 2026 14:04

@vaadin-review-bot vaadin-review-bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the changes — left 2 comments.

Finding
⚠️ The walkthrough video styles can't match a standalone clip, because the role lands on the videoblock itself
⚠️ A clip the browser already started autoplaying keeps looping for a reduced-motion user

Comment thread dspublisher/theme/global.css Outdated
/* Walkthroughs (walkthrough.ts): an ordered list of steps, each with a short clip or a still, or one clip on its own. */

/* The publisher's video box is 16:9 (a padding-bottom of 56.25%); the clips are 16:10. */
div.walkthrough .videoblock .content {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ The walkthrough video styles can't match a standalone clip, because the role lands on the videoblock itself

[.walkthrough] on a video:: macro renders as <div class="videoblock walkthrough">, so every .walkthrough .videoblock ... rule needs a descendant that doesn't exist. The existing teaser on articles/styling/themes/aura/index.adoc:98 shows the same role rendering, targeted as a compound selector.

For the single-clip form the script supports, that means no 16:10 box, no border/radius/object-fit, and a Pause button that never fades out. Adding .walkthrough.videoblock alongside each selector covers both forms.

global.css:1008 · correctness

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in c08c3a6: .walkthrough.videoblock is now styled alongside .walkthrough .videoblock, so a clip with the role on the macro gets the box, border and fading Pause.

video.controls = false;
video.muted = true;
video.playsInline = true;
video.autoplay = false;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ A clip the browser already started autoplaying keeps looping for a reduced-motion user

setUpVideos clears autoplay, but never pauses. With the documented options="autoplay,loop,muted" markup the browser usually starts playback before the idle callback runs, and neither reduced-motion branch pauses what is already playing: the intersection observer only skips play(), and so does show() for the current step. The result is one clip looping indefinitely for exactly the users who asked for no motion.

A video.pause() in setUpVideos would make both branches authoritative.

walkthrough.ts:61 · correctness

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in c08c3a6: setUpVideos now calls video.pause(), so a clip the browser already started doesn't keep playing for reduced-motion users (checked: 0 of 5 clips play on the menu page with reduced motion).

…ads, and respect reduced motion

- Once the first clip can play, load the rest (they're small), instead of only the next one, so Next doesn't wait. A clip that should play but is still loading shows a spinner, after a moment, instead of its poster, which looks like a finished step.
- Pause the clips when setting them up: the browser may have started autoplaying one already, and it kept looping for a reader who asked for reduced motion.
- Style a single clip that carries [.walkthrough] on the video:: macro itself, where the role lands on the videoblock.
@emarc
emarc merged commit 83d6c18 into main Nov 16, 2026
11 checks passed
@emarc
emarc deleted the feat/copilot-walkthrough-stepper branch November 16, 2026 15:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants