Skip to content

Commit f3d1d53

Browse files
committed
docs(examples): reset control state on offscreen release; precise a11y labels
- replica-compare: the offscreen teardown now resets muted (element + React state), matching HoverVideo — a pair unmuted before it scrolled away no longer returns reading 'Sound on' over a paused, sourceless pair (Magi blocker). - Both controls' aria-labels now follow the mode: under reduced motion the button plays/pauses the whole comparison, and when a preview is already autoplaying muted the action is 'unmute', not 'play with sound' (self-review + Rames). - Hardened the motion-suite assertion to scope 'startBoth' to toggleSound's body (a defined-but-unused helper no longer satisfies it) and pin the offscreen muted-reset transition (Rames mutation-test gap). - html-schema: 'hyperframes validate' inspects <audio> only; note that no media-start-only reader inspects a composition host, so the kind rule strands nobody (Rames).
1 parent c49fea2 commit f3d1d53

4 files changed

Lines changed: 33 additions & 6 deletions

File tree

‎docs/reference/html-schema.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -122,7 +122,7 @@ Audio has no visual lifecycle.
122122

123123
| Attribute | Applies to | Meaning |
124124
| --- | --- | --- |
125-
| `data-media-start` / `data-playback-start` | Video, audio, nested composition | Offset into the source file, used by trim and split. Two groups of readers disagree, so the right name depends on the element. **Read only `data-media-start`:** the timing compiler, the HTML parser, `hyperframes validate`, and the engine's audio mixer (which feeds ffmpeg `-ss`). **Read `data-playback-start` first, falling back to `data-media-start`:** the runtime player, Studio (which also writes it), and `hyperframes snapshot`. Because the audio mixer reads only `data-media-start`, a `<video>` authored with just `data-playback-start` renders a trimmed picture over untrimmed audio. So set the name by kind: **`<video>` / `<audio>` → `data-media-start`**; **nested composition → `data-playback-start`** (Studio writes it, and it is the [child-timeline offset](/concepts/compositions)). |
125+
| `data-media-start` / `data-playback-start` | Video, audio, nested composition | Offset into the source file, used by trim and split. Two groups of readers disagree, so the right name depends on the element. **Read only `data-media-start`:** the timing compiler, the HTML parser, `hyperframes validate` (which only inspects `<audio>`), and the engine's audio mixer (which feeds ffmpeg `-ss`). **Read `data-playback-start` first, falling back to `data-media-start`:** the runtime player, Studio (which also writes it), and `hyperframes snapshot`. Because the audio mixer reads only `data-media-start`, a `<video>` authored with just `data-playback-start` renders a trimmed picture over untrimmed audio. Set the name by kind: **`<video>` / `<audio>` → `data-media-start`**; **nested composition → `data-playback-start`** — none of the media-start-only readers inspect a composition host, so its offset is only ever read as `data-playback-start` (Studio writes it; it is the [child-timeline offset](/concepts/compositions)). |
126126
| `data-playback-rate` | Video, audio, nested composition | Playback multiplier from `0.1` to `5` |
127127
| `data-volume` | Video and audio | Static volume from `0` to `1` |
128128
| `data-has-audio="true"` | Video | Declares that the video contributes audio |

‎docs/snippets/hover-video.jsx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,9 @@ export const HoverVideo = ({ src, poster, className, hasAudio = true }) => {
110110
aria-label={
111111
hasAudio
112112
? muted
113-
? "Play this preview with sound"
113+
? reduced
114+
? "Play this preview with sound"
115+
: "Unmute this preview"
114116
: "Mute this preview"
115117
: playing
116118
? "Pause this preview"

‎docs/snippets/replica-compare.jsx‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,9 +55,13 @@ export const ReplicaCompare = ({
5555
for (const video of videos) {
5656
if (!video) continue;
5757
video.pause();
58+
video.muted = true;
5859
video.removeAttribute("src");
5960
video.load();
6061
}
62+
// Reset the control's state too, so a card unmuted before it scrolled away
63+
// doesn't return reading "Sound on" over a paused, sourceless pair.
64+
setMuted(true);
6165
return;
6266
}
6367
if (reduced) {
@@ -151,7 +155,15 @@ export const ReplicaCompare = ({
151155
type="button"
152156
onClick={toggleSound}
153157
aria-pressed={!muted}
154-
aria-label={muted ? "Play the reference with sound" : "Mute the reference"}
158+
aria-label={
159+
muted
160+
? reduced
161+
? "Play the comparison with sound"
162+
: "Unmute the reference"
163+
: reduced
164+
? "Pause the comparison"
165+
: "Mute the reference"
166+
}
155167
className="absolute left-3 top-3 z-10 flex items-center gap-1.5 rounded-full bg-black/60 px-3 py-1.5 text-xs font-medium text-white backdrop-blur transition hover:bg-black/75 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-white"
156168
>
157169
{muted ? (

‎scripts/check-docs-snippet-motion.test.mjs‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -134,12 +134,25 @@ test("every autoplaying component in docs/snippets currently satisfies the guard
134134
// reason).
135135
test("ReplicaCompare's control starts both films and does not gate sync on reduced motion", () => {
136136
const source = readFileSync(join(here, "../docs/snippets/replica-compare.jsx"), "utf8");
137-
// The voluntary-play path starts both the reference and the replica.
138-
assert.match(source, /refVideo\.current\?\.play\(\)/, "reference is started");
139-
assert.match(source, /repVideo\.current\?\.play\(\)/, "replica is started too");
137+
// startBoth must play both elements...
138+
const startBoth = source.match(/const startBoth = \(\) => \{([\s\S]*?)\n {2}\};/);
139+
assert.ok(startBoth, "found startBoth");
140+
assert.match(startBoth[1], /refVideo\.current\?\.play\(\)/, "reference is started");
141+
assert.match(startBoth[1], /repVideo\.current\?\.play\(\)/, "replica is started too");
142+
// ...and the voluntary-play control must actually route through it, not play
143+
// the reference alone (scoped to toggleSound so a helper left defined but
144+
// unused can't satisfy the check — the exact regression this guards).
145+
const toggle = source.match(/const toggleSound = \(\) => \{([\s\S]*?)\n {2}\};/);
146+
assert.ok(toggle, "found toggleSound");
147+
assert.match(toggle[1], /startBoth\(\)/, "voluntary play goes through startBoth");
140148
// The replica-sync effect attaches in view regardless of the preference, so a
141149
// voluntary play under reduced motion still pulls the replica along.
142150
const syncGate = source.match(/const b = repVideo\.current;\s*\n\s*if \(([^)]*)\) return;/);
143151
assert.ok(syncGate, "found the replica-sync guard");
144152
assert.doesNotMatch(syncGate[1], /reduced/, "sync must not early-return on reduced motion");
153+
// Offscreen release must reset the control's state, or a card unmuted before it
154+
// scrolled away returns reading "Sound on" over a paused, sourceless pair.
155+
const teardown = source.match(/if \(!inView\) \{([\s\S]*?)return;\n {4}\}/);
156+
assert.ok(teardown, "found the offscreen teardown");
157+
assert.match(teardown[1], /setMuted\(true\)/, "offscreen release resets muted state");
145158
});

0 commit comments

Comments
 (0)