feat: add play button component #324

luwes · 2026-01-22T19:06:23Z

This pull request introduces a comprehensive implementation plan for the new PlayButton UI component, which will serve as a model for future UI components across the project. The plan details a multi-layered approach, covering core logic, DOM integration, React and HTML custom element implementations, and accessibility/testing requirements. Additionally, a minor fix is made to the commitlint script in package.json.

Component architecture and implementation plan:

Added a detailed multi-phase plan for the PlayButton component, outlining interfaces, implementation details, and file structure across the Core, DOM, React, and HTML packages. This plan establishes conventions for component state, props, event handling, accessibility, and testing. (.claude/plans/components/play-button.md)

Accessibility and testing standards:

Defined accessibility requirements (ARIA roles, keyboard navigation, disabled state) and a shared testing strategy to ensure behavioral parity across React and HTML implementations. (.claude/plans/components/play-button.md)

Development workflow improvement:

Fixed the commitlint script in package.json to remove the unused $1 argument, ensuring consistent commit message linting. (package.json)

vercel · 2026-01-22T19:06:28Z

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
vjs-10-website	Ignored	Preview	Jan 23, 2026 7:05pm

sampotts · 2026-01-23T07:23:07Z

.claude/plans/components/play-button.md

+interface PlayButtonDataAttributes {
+  'data-paused'?: '';
+  'data-ended'?: '';
+  'data-disabled'?: '';


Out of interest, why not use the disabled attribute?

I see there's actually some more nuance here. This part in Base UI does manage disabled but carefully. They're actively removing native disabled in composite widgets (toolbars, menus, tabs).

Native disabled:

Removes from tab order entirely

Unfocusable

Screen reader might skip it completely

Based on what I'm gathering, user should be able to tab through and hear "play button, disabled" rather than it vanishing from keyboard navigation. So we would set aria-disabled="true" to provide a hint, and I guess data-disabled is for styling/consistency/docs.

That all makes sense! Good points. A related nit though; if we're going with aria-disabled, why don't we just use that for styling etc too?

Thanks for the feedback. Updated to remove data-disabled here.
We can use disabled or aria-disabled to style.

sampotts · 2026-01-23T07:27:24Z

.claude/plans/components/play-button.md

+- `aria-label: state.label`
+- `data-paused`, `data-ended`, `data-disabled` (boolean attributes)
+- `onClick` handler
+- `onKeyDown` handler (Enter/Space)


nit: Enter and space will trigger a click event when using a <button> so would we end up with two events?

Trade off with the above on managing disabled ourselves is that we need to hook into these events and manage disabled ourselves.

If we agree on how we treat disabled, then we'll need to abstract this somehow for all buttons.

.claude/plans/components/play-button.md

mihar-22 · 2026-01-23T12:35:18Z

.claude/plans/components/play-button.md

+- Uses `SnapshotController` for state
+- Uses `RequestController` for play/pause


I simplified some of the controllers/hooks here, we'll just need Claude to re-run implementation plan.

I imagine we have to wait for #323 partially so we have feature accessors (e.g., getFeature(store)) before implementing this component. I'll create a PR tomorrow prob to get that smaller piece through so UI is unblocked.

.claude/plans/components/play-button.md

mihar-22 · 2026-01-23T12:39:55Z

.claude/plans/components/play-button.md

+### Registration
+
+```ts
+customElements.define('media-play-button', PlayButtonElement);


Worth discussing with the team to confirm what prefix we're going with. I'll need to update existing Claude plans and what not to match.

Few arguments come to mind for vjs- over media-:

You don't end up with funny names like media-frosted-video-skin (media+video).

We used media- in Media Chrome and Vidstack. Prevent collision with either. Look distinct too.

vjs is iconic. I would recognize it instantly. It also popups when you inspect old player in class list.

Beyond that if the team decides media-, I'm down either way.

Good call, I think I still prefer media- for it's more native, generic feeling.

I'm wondering now if we could pull off prefix-less if there are 2 or more words in the name.
Why not just play-button, time-slider?

With scoped registries on the horizon.

https://caniuse.com/wf-scoped-custom-element-registries
https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry
https://github.com/justinfagnani/webcomponents/blob/scoped-registries/proposals/Scoped-Custom-Element-Registries.md

I can only offer my opinion as a matter of taste. I don't really have any facts to bring to the table. But. Of the three options, I really like vjs-.

To me, using media- on media chrome felt like a branding exercise. "Web components are native HTML. They're timeless. Free from the constraints of component libraries. The media components you wish the platform had built in. Let's use timeless, platform-seeming names, too."

Meanwhile, from a brand standpoint, video.js 10 feels like more its own thing, rather than a thing of the platform. It has a bright brand on its website. It has an eye-catching skin. It demands that you learn the provider, the skin, and the media source. Everything about it feels opinionated. That just feels very vjs- to me.

MIND YOU. I haven't done truly native HTML dev in almost a decade. I don't know what naming conventions are idiomatic in web components. What's more important to me than a brand expression is idiomatic web component behavior. Good DX. If vjs- stands in the way of that, I take my opinion back. (And, maybe in the near future, scoped registries with generic names will be good DX. So. That's another potential wrench in my spiel.)

.claude/plans/components/play-button.md

mihar-22 · 2026-01-23T12:43:27Z

.claude/plans/components/play-button.md

+function getPlayButtonProps(params: {
+  props: PlayButtonProps;
+  state: PlayButtonState;
+  onToggle: () => void;
+}): PlayButtonDOMProps;


Wondering if we should go a step further to simplify and just have getRootProps on core component class.

Similar to Zag.js, we can just define our own ElementProps in core (jsx), then map accordingly in html/react packages? Just a thought to co-locate more code and simplify.

heff · 2026-01-26T20:17:31Z

.claude/plans/components/play-button.md

+  onPauseRequest?: () => void;
+  onPlay?: () => void;
+  onPause?: () => void;
+  onError?: (error: Error) => void;


I can't think of a reason for error handling at this level. Is there a clear one? If not I suggest we drop things we don't know we need.

mihar-22 · 2026-01-27T05:50:08Z

Closing this one out as we're re-assigning work. I'll take the feedback from here and apply to internal design doc.

luwes added 2 commits January 22, 2026 11:00

chore: fix failing commitlint

496e0a5

docs(plan): add play button plan

9c8fc64

luwes self-assigned this Jan 22, 2026

sampotts reviewed Jan 23, 2026

View reviewed changes

mihar-22 reviewed Jan 23, 2026

View reviewed changes

Update play-button.md

0b03fdc

heff reviewed Jan 26, 2026

View reviewed changes

mihar-22 closed this Jan 27, 2026

		- Uses `SnapshotController` for state
		- Uses `RequestController` for play/pause

feat: add play button component #324

feat: add play button component #324

Conversation

luwes commented Jan 22, 2026

Uh oh!

vercel bot commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mihar-22 Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mihar-22 Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mihar-22 Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

decepulis Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mihar-22 commented Jan 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

vercel bot commented Jan 22, 2026 •

edited

Loading

mihar-22 Jan 23, 2026 •

edited

Loading

mihar-22 Jan 23, 2026 •

edited

Loading

mihar-22 Jan 23, 2026 •

edited

Loading

decepulis Jan 23, 2026 •

edited

Loading