From c9ba1e1bfc83e02981a2ffad0a0f247092068687 Mon Sep 17 00:00:00 2001
From: rahim <rahim.alwer@gmail.com>
Date: Thu, 12 Feb 2026 18:12:55 +1100
Subject: [PATCH] feat(core): add poster component (#457)

---
 internal/design/ui/poster.md                  | 208 ++++++++++++++++++
 packages/core/src/core/index.ts               |   2 +
 .../core/src/core/ui/poster/poster-core.ts    |  17 ++
 .../src/core/ui/poster/poster-data-attrs.ts   |   6 +
 .../core/ui/poster/tests/poster-core.test.ts  |  73 ++++++
 packages/html/src/define/ui/poster.ts         |   9 +
 packages/html/src/index.ts                    |   1 +
 packages/html/src/ui/poster/poster-element.ts |  34 +++
 packages/react/src/index.ts                   |   1 +
 packages/react/src/ui/poster/poster.tsx       |  58 +++++
 10 files changed, 409 insertions(+)
 create mode 100644 internal/design/ui/poster.md
 create mode 100644 packages/core/src/core/ui/poster/poster-core.ts
 create mode 100644 packages/core/src/core/ui/poster/poster-data-attrs.ts
 create mode 100644 packages/core/src/core/ui/poster/tests/poster-core.test.ts
 create mode 100644 packages/html/src/define/ui/poster.ts
 create mode 100644 packages/html/src/ui/poster/poster-element.ts
 create mode 100644 packages/react/src/ui/poster/poster.tsx

diff --git a/internal/design/ui/poster.md b/internal/design/ui/poster.md
new file mode 100644
index 00000000..22d70a76
--- /dev/null
+++ b/internal/design/ui/poster.md
@@ -0,0 +1,208 @@
+---
+status: draft
+date: 2025-02-05
+---
+
+# Poster
+
+Display component for video poster image. Shows before playback starts, hides after.
+
+## Problem
+
+Video players show a poster image before playback. The poster:
+
+1. Gives users a preview of the content
+2. Should hide once playback starts
+3. May optionally reappear when playback ends
+
+Existing solutions (Media Chrome, Vidstack) either:
+
+- Manage the image internally via `src` prop
+- Expose complex state (`data-loading`, `data-error`, `data-hidden`, `data-visible`)
+
+We want a simpler approach: expose minimal state, let the user control the image.
+
+## Solution
+
+Minimal components that:
+
+1. Expose `data-visible` for CSS-based show/hide
+2. Do nothing else
+
+**HTML:** Wrapper element that accepts `<img>` as child.
+**React:** Renders `<img>` directly — no wrapper needed.
+
+### Usage
+
+#### HTML
+
+```html
+<media-poster>
+  <img src="poster.jpg" alt="Video description" />
+</media-poster>
+```
+
+#### React
+
+```tsx
+import { Poster } from '@videojs/react';
+
+<Poster src="poster.jpg" alt="Video description" />;
+```
+
+#### CSS
+
+```css
+media-poster:not([data-visible]) {
+  display: none;
+}
+```
+
+### With Responsive Image
+
+#### HTML
+
+```html
+<media-poster>
+  <img
+    src="poster.jpg"
+    srcset="poster-480.jpg 480w, poster-720.jpg 720w"
+    sizes="(max-width: 600px) 480px, 720px"
+    alt="Video description"
+    loading="lazy"
+  />
+</media-poster>
+```
+
+#### React
+
+```tsx
+<Poster
+  src="poster.jpg"
+  srcSet="poster-480.jpg 480w, poster-720.jpg 720w"
+  sizes="(max-width: 600px) 480px, 720px"
+  alt="Video description"
+  loading="lazy"
+/>
+```
+
+User controls the image entirely — responsive images, lazy loading, placeholder strategies all work naturally.
+
+### With Placeholder (Blurhash / LQIP)
+
+Use CSS `background-image` on the `<img>` element to show a placeholder while the main image loads. When the `src` loads, it naturally covers the background.
+
+#### HTML
+
+```html
+<media-poster>
+  <img
+    src="poster.jpg"
+    alt="Video description"
+    style="background: url(data:image/jpeg;base64,...) center/cover no-repeat;"
+  />
+</media-poster>
+```
+
+#### React
+
+```tsx
+<Poster
+  src="poster.jpg"
+  alt="Video description"
+  style={{ background: 'url(data:image/jpeg;base64,...) center/cover no-repeat' }}
+/>
+```
+
+For fade transitions (blur → sharp), handle the `load` event on the image:
+
+```html
+<media-poster>
+  <img
+    src="poster.jpg"
+    alt="Video description"
+    style="background: url(blur.jpg) center/cover; opacity: 0; transition: opacity 0.3s;"
+    onload="this.style.opacity = 1"
+  />
+</media-poster>
+```
+
+## API
+
+### Data Attributes
+
+| Attribute      | Description                                  |
+| -------------- | -------------------------------------------- |
+| `data-visible` | Present when poster should show (`!started`) |
+
+### Visibility Logic
+
+```ts
+visible = !playback.started;
+```
+
+The poster is visible until playback has started. Once `started` becomes `true` (user plays or seeks), the poster hides and stays hidden.
+
+**Note:** `started` persists — pausing doesn't reset it. The poster only shows on initial load or after a new source is loaded.
+
+## Styling Notes
+
+The component sets no default styles. Recommended CSS:
+
+```css
+media-poster {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+}
+
+media-poster:not([data-visible]) {
+  display: none;
+}
+
+media-poster img {
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+}
+```
+
+**`pointer-events: none`** — Clicks should pass through to the video or play button beneath.
+
+## Accessibility
+
+**Wrapper (`<media-poster>`):** No ARIA role needed. Custom elements have no implicit role, so there's no semantics to hide or override. Do not add `aria-hidden` to the wrapper — the poster image may be informative.
+
+**Child (`<img>`):** User provides appropriate `alt` text describing the poster content (e.g., `alt="Keynote speaker at a conference"`). If purely decorative, use `alt=""`.
+
+Whether a poster is informative or decorative is the author's judgment (per [WAI guidelines](https://www.w3.org/WAI/tutorials/images/decorative/)). In most video player contexts, posters are informative — they give users a preview of the video content. This is an advantage over Media Chrome (which forces `aria-hidden="true"` on the internal image) and native `<video poster>` (which has no `alt` equivalent).
+
+## Alternatives Considered
+
+### Raw state attributes (`data-started`, `data-ended`)
+
+Expose underlying state, let users compose visibility in CSS.
+
+```css
+media-poster[data-started]:not([data-ended]) {
+  display: none;
+}
+```
+
+**Why not:** Requires users to understand the state model. `data-started` on a poster doesn't make sense in the component's local context — `data-visible` directly describes the poster's state. Consistent with how button components use context-appropriate names (`data-fullscreen`, `data-muted`) rather than raw feature state.
+
+**Future:** Could add `data-started` and `data-ended` later if needed for advanced use cases (e.g., show poster on ended).
+
+### Component-managed image (`src` prop)
+
+Like Media Chrome — component owns the `<img>` internally.
+
+**Why not:** Limits user control. Can't use `srcset`, `loading="lazy"`, `<picture>`, or framework-specific optimized image components (Next.js `<Image>`, Astro `<Image>`). Media Chrome acknowledges this tradeoff in their docs: "If better control or better performance is desired, you can use `<img slot="poster" src="...">` instead."
+
+Our approach makes the flexible path the default.
+
+## Future
+
+1. **`data-ended`** — Show poster when media ends. Would allow `media-poster[data-visible]:not([data-ended])` patterns.
+2. **`data-loaded`** — Set when child image loads. Enables CSS-only placeholder-to-main transitions without user-handled `onload`. Lightweight to implement (listen for `load` event on child `<img>`).
+3. **Transition/animation support** — CSS transition recommendations for fade in/out.
diff --git a/packages/core/src/core/index.ts b/packages/core/src/core/index.ts
index 3559d209..3fbdfa84 100644
--- a/packages/core/src/core/index.ts
+++ b/packages/core/src/core/index.ts
@@ -5,6 +5,8 @@ export * from './ui/mute-button/mute-button-core';
 export * from './ui/mute-button/mute-button-data-attrs';
 export * from './ui/play-button/play-button-core';
 export * from './ui/play-button/play-button-data-attrs';
+export * from './ui/poster/poster-core';
+export * from './ui/poster/poster-data-attrs';
 export * from './ui/time/time-core';
 export * from './ui/time/time-data-attrs';
 export * from './ui/types';
diff --git a/packages/core/src/core/ui/poster/poster-core.ts b/packages/core/src/core/ui/poster/poster-core.ts
new file mode 100644
index 00000000..bfbc15ee
--- /dev/null
+++ b/packages/core/src/core/ui/poster/poster-core.ts
@@ -0,0 +1,17 @@
+import type { MediaPlaybackState } from '../../media/state';
+
+export interface PosterState {
+  visible: boolean;
+}
+
+export class PosterCore {
+  getState(media: MediaPlaybackState): PosterState {
+    return {
+      visible: !media.started,
+    };
+  }
+}
+
+export namespace PosterCore {
+  export type State = PosterState;
+}
diff --git a/packages/core/src/core/ui/poster/poster-data-attrs.ts b/packages/core/src/core/ui/poster/poster-data-attrs.ts
new file mode 100644
index 00000000..b7b60cb3
--- /dev/null
+++ b/packages/core/src/core/ui/poster/poster-data-attrs.ts
@@ -0,0 +1,6 @@
+import type { StateAttrMap } from '../types';
+import type { PosterState } from './poster-core';
+
+export const PosterDataAttrs = {
+  visible: 'data-visible',
+} as const satisfies StateAttrMap<PosterState>;
diff --git a/packages/core/src/core/ui/poster/tests/poster-core.test.ts b/packages/core/src/core/ui/poster/tests/poster-core.test.ts
new file mode 100644
index 00000000..24b596ef
--- /dev/null
+++ b/packages/core/src/core/ui/poster/tests/poster-core.test.ts
@@ -0,0 +1,73 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { MediaPlaybackState } from '../../../media/state';
+import { PosterCore } from '../poster-core';
+
+function createMediaState(overrides: Partial<MediaPlaybackState> = {}): MediaPlaybackState {
+  return {
+    paused: true,
+    ended: false,
+    started: false,
+    waiting: false,
+    play: vi.fn(async () => {}),
+    pause: vi.fn(),
+    ...overrides,
+  };
+}
+
+describe('PosterCore', () => {
+  describe('getState', () => {
+    it('returns visible: true when playback has not started', () => {
+      const core = new PosterCore();
+      const media = createMediaState({ started: false });
+
+      const state = core.getState(media);
+
+      expect(state.visible).toBe(true);
+    });
+
+    it('returns visible: false when playback has started', () => {
+      const core = new PosterCore();
+      const media = createMediaState({ started: true });
+
+      const state = core.getState(media);
+
+      expect(state.visible).toBe(false);
+    });
+
+    it('returns only primitive values (no methods)', () => {
+      const core = new PosterCore();
+      const media = createMediaState();
+
+      const state = core.getState(media);
+
+      expect(state).toEqual({ visible: true });
+
+      const functionKeys = Object.entries(state).filter(([, value]) => typeof value === 'function');
+      expect(functionKeys).toHaveLength(0);
+    });
+
+    it('visibility is independent of paused state', () => {
+      const core = new PosterCore();
+
+      // Started but paused - should not be visible
+      expect(core.getState(createMediaState({ started: true, paused: true })).visible).toBe(false);
+
+      // Started and playing - should not be visible
+      expect(core.getState(createMediaState({ started: true, paused: false })).visible).toBe(false);
+
+      // Not started and paused - should be visible
+      expect(core.getState(createMediaState({ started: false, paused: true })).visible).toBe(true);
+    });
+
+    it('visibility is independent of ended state', () => {
+      const core = new PosterCore();
+
+      // Started and ended - should not be visible (started takes precedence)
+      expect(core.getState(createMediaState({ started: true, ended: true })).visible).toBe(false);
+
+      // Not started and ended (edge case) - should be visible
+      expect(core.getState(createMediaState({ started: false, ended: true })).visible).toBe(true);
+    });
+  });
+});
diff --git a/packages/html/src/define/ui/poster.ts b/packages/html/src/define/ui/poster.ts
new file mode 100644
index 00000000..8844f8a0
--- /dev/null
+++ b/packages/html/src/define/ui/poster.ts
@@ -0,0 +1,9 @@
+import { PosterElement } from '../../ui/poster/poster-element';
+
+customElements.define(PosterElement.tagName, PosterElement);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    [PosterElement.tagName]: PosterElement;
+  }
+}
diff --git a/packages/html/src/index.ts b/packages/html/src/index.ts
index 3843738b..c888df70 100644
--- a/packages/html/src/index.ts
+++ b/packages/html/src/index.ts
@@ -19,6 +19,7 @@ export { FullscreenButtonElement } from './ui/fullscreen-button/fullscreen-butto
 export * from './ui/media-element';
 export { MuteButtonElement } from './ui/mute-button/mute-button-element';
 export { PlayButtonElement } from './ui/play-button/play-button-element';
+export { PosterElement } from './ui/poster/poster-element';
 export { TimeElement } from './ui/time/time-element';
 export { TimeGroupElement } from './ui/time/time-group-element';
 export { TimeSeparatorElement } from './ui/time/time-separator-element';
diff --git a/packages/html/src/ui/poster/poster-element.ts b/packages/html/src/ui/poster/poster-element.ts
new file mode 100644
index 00000000..1c5b7291
--- /dev/null
+++ b/packages/html/src/ui/poster/poster-element.ts
@@ -0,0 +1,34 @@
+import type { PropertyValues } from '@lit/reactive-element';
+import { PosterCore, PosterDataAttrs } from '@videojs/core';
+import { applyStateDataAttrs, logMissingFeature, selectPlayback } from '@videojs/core/dom';
+
+import { playerContext } from '../../player/context';
+import { PlayerController } from '../../player/player-controller';
+import { MediaElement } from '../media-element';
+
+export class PosterElement extends MediaElement {
+  static readonly tagName = 'media-poster';
+
+  readonly #core = new PosterCore();
+  readonly #state = new PlayerController(this, playerContext, selectPlayback);
+
+  override connectedCallback(): void {
+    super.connectedCallback();
+
+    if (__DEV__ && !this.#state.value) {
+      logMissingFeature(PosterElement.tagName, 'playback');
+    }
+  }
+
+  protected override update(changed: PropertyValues): void {
+    super.update(changed);
+
+    const media = this.#state.value;
+
+    if (!media) {
+      return;
+    }
+
+    applyStateDataAttrs(this, this.#core.getState(media), PosterDataAttrs);
+  }
+}
diff --git a/packages/react/src/index.ts b/packages/react/src/index.ts
index 5ba369b3..5bd38aad 100644
--- a/packages/react/src/index.ts
+++ b/packages/react/src/index.ts
@@ -34,6 +34,7 @@ export { FullscreenButton, type FullscreenButtonProps } from './ui/fullscreen-bu
 export { useButton } from './ui/hooks/use-button';
 export { MuteButton, type MuteButtonProps } from './ui/mute-button/mute-button';
 export { PlayButton, type PlayButtonProps } from './ui/play-button/play-button';
+export { Poster, type PosterProps } from './ui/poster/poster';
 export { Time } from './ui/time';
 
 // Utilities
diff --git a/packages/react/src/ui/poster/poster.tsx b/packages/react/src/ui/poster/poster.tsx
new file mode 100644
index 00000000..259441b5
--- /dev/null
+++ b/packages/react/src/ui/poster/poster.tsx
@@ -0,0 +1,58 @@
+'use client';
+
+import { PosterCore, PosterDataAttrs } from '@videojs/core';
+import { logMissingFeature, selectPlayback } from '@videojs/core/dom';
+import type { ForwardedRef } from 'react';
+import { forwardRef, useState } from 'react';
+
+import { usePlayer } from '../../player/context';
+import type { UIComponentProps } from '../../utils/types';
+import { renderElement } from '../../utils/use-render';
+
+export interface PosterProps extends UIComponentProps<'img', PosterCore.State> {}
+
+/**
+ * Displays the video poster image. Shows before playback starts, hides after.
+ *
+ * @example
+ * ```tsx
+ * <Poster src="poster.jpg" alt="Video description" />
+ *
+ * <Poster
+ *   src="poster.jpg"
+ *   alt="Video description"
+ *   className={(state) => state.visible ? 'visible' : 'hidden'}
+ * />
+ * ```
+ */
+export const Poster = forwardRef(function Poster(
+  componentProps: PosterProps,
+  forwardedRef: ForwardedRef<HTMLImageElement>
+) {
+  const { render, className, style, ...elementProps } = componentProps;
+
+  const playback = usePlayer(selectPlayback);
+
+  const [core] = useState(() => new PosterCore());
+
+  if (!playback) {
+    if (__DEV__) logMissingFeature('Poster', 'playback');
+    return null;
+  }
+
+  return renderElement(
+    'img',
+    { render, className, style },
+    {
+      state: core.getState(playback),
+      stateAttrMap: PosterDataAttrs,
+      ref: [forwardedRef],
+      props: [elementProps],
+    }
+  );
+});
+
+export namespace Poster {
+  export type Props = PosterProps;
+  export type State = PosterCore.State;
+}