@varialkit/video 0.1.0

package/docs.md

@@ -0,0 +1,59 @@
+# Video
+
+The `Video` component wraps native HTML `<video>` playback with Solara styling and a custom control system.
+
+## Usage
+
+```tsx
+import { Video } from "@solara/video";
+
+export function Example() {
+  return (
+    <Video
+      src="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"
+      poster="https://interactive-examples.mdn.mozilla.net/media/examples/friday.jpg"
+      controlsType="control-bar"
+      caption="Demo clip"
+    />
+  );
+}
+```
+
+## Control Types
+
+- `controlsType="control-bar"`: full-width custom bar with icon buttons for playback, sound, and fullscreen, plus scrubber/time/volume.
+- `controlsType="quick"`: floating action-only bar with icon-based `Play`/`Pause`/`Restart`.
+- `controlsType="minimal"`: floating action-only bar with icon-based `Play`/`Pause`/`Restart`.
+- `controlsType="none"`: hides all custom controls.
+
+Playback icon states: `media_play_filled_16` -> `media_pause_16` -> `arrow_line_rotate_left_16`.
+Sound toggle states: `media_sound_filled_16` and `media_sound_off_filled_16`.
+Fullscreen toggle icon: `view_box_inside_16`.
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `showControls` | `boolean` | `true` | Legacy visibility switch for custom controls. |
+| `controlsType` | `"control-bar" \| "quick" \| "minimal" \| "none"` | derived | Primary control type selector. |
+| `showScrubber` | `boolean` | `true` | Shows seek slider in `control-bar` mode. |
+| `showTimeDisplay` | `boolean` | `true` | Shows elapsed/total time in `control-bar` mode. |
+| `showVolumeControl` | `boolean` | `true` | Shows sound icon toggle and volume slider in `control-bar` mode. |
+| `showFullscreenControl` | `boolean` | `true` | Shows fullscreen icon control in `control-bar` mode. |
+| `controlBarClassName` | `string` | — | Class hook for custom control-bar styling. |
+| `tapToTogglePlayback` | `boolean` | `true` | Enables tapping/clicking the video surface to toggle play/pause. |
+| `controlsAutoHideDelay` | `number` | `1400` | Milliseconds before auto-hiding the `control-bar` after inactivity. |
+| `sources` | `VideoSource[]` | — | Optional `<source>` definitions for multiple formats. |
+| `aspectRatio` | `"auto" \| "16:9" \| "4:3" \| "1:1" \| "21:9" \| number` | `"16:9"` | Controls wrapper ratio. |
+| `fit` | `"contain" \| "cover" \| "fill" \| "none" \| "scale-down"` | `"cover"` | Controls media fitting in frame. |
+| `caption` | `ReactNode` | — | Optional caption content shown below the player. |
+| `showCaption` | `boolean` | `true` | Toggles caption visibility. |
+| `rounded` | `boolean` | `true` | Applies rounded corners to the frame. |
+| `shadow` | `boolean` | `false` | Applies a subtle elevation shadow. |
+| `videoClassName` | `string` | — | Additional class for the `<video>` node. |
+
+`Video` also supports native video attributes such as `src`, `poster`, `autoPlay`, `loop`, `muted`, `playsInline`,
+`preload`, and event handlers.
+
+Legacy note: `controlBarMode` is still supported for backward compatibility, but new usage should prefer
+`controlsType` only.

package/examples.tsx

@@ -0,0 +1,169 @@
+import React from "react";
+import { Video } from "./src/Video";
+import type { VideoProps } from "./src/Video.types";
+
+const sampleVideo = "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4";
+const samplePoster = "https://interactive-examples.mdn.mozilla.net/media/examples/friday.jpg";
+
+export const stories = {
+  playground: {
+    title: "Playground",
+    description: "Adjust player controls, ratio, and playback settings.",
+    render: (props: VideoProps & { captionText?: string }) => {
+      const { captionText, ...videoProps } = props;
+      return <Video {...videoProps} caption={captionText} />;
+    },
+    controls: [
+      { name: "src", type: "text" },
+      { name: "poster", type: "text" },
+      {
+        name: "aspectRatio",
+        type: "select",
+        options: ["auto", "16:9", "4:3", "1:1", "21:9"],
+      },
+      {
+        name: "controlsType",
+        type: "select",
+        options: ["control-bar", "quick", "minimal", "none"],
+      },
+      {
+        name: "fit",
+        type: "select",
+        options: ["contain", "cover", "fill", "none", "scale-down"],
+      },
+      { name: "showControls", type: "boolean", label: "Show controls" },
+      { name: "showScrubber", type: "boolean", label: "Show scrubber" },
+      { name: "showTimeDisplay", type: "boolean", label: "Show time" },
+      { name: "showVolumeControl", type: "boolean", label: "Show volume controls" },
+      { name: "showFullscreenControl", type: "boolean", label: "Show fullscreen control" },
+      { name: "tapToTogglePlayback", type: "boolean", label: "Tap video toggles play" },
+      { name: "controlsAutoHideDelay", type: "number", label: "Controls auto-hide delay (ms)" },
+      { name: "autoPlay", type: "boolean", label: "Autoplay" },
+      { name: "muted", type: "boolean", label: "Muted" },
+      { name: "loop", type: "boolean", label: "Loop" },
+      { name: "playsInline", type: "boolean", label: "Plays inline" },
+      { name: "showCaption", type: "boolean", label: "Show caption" },
+      { name: "captionText", type: "text", label: "Caption" },
+      { name: "rounded", type: "boolean", label: "Rounded" },
+      { name: "shadow", type: "boolean", label: "Shadow" },
+      {
+        name: "preload",
+        type: "select",
+        options: ["none", "metadata", "auto"],
+      },
+    ],
+    initialProps: {
+      src: sampleVideo,
+      poster: samplePoster,
+      aspectRatio: "16:9",
+      controlsType: "control-bar",
+      fit: "cover",
+      showControls: true,
+      showScrubber: true,
+      showTimeDisplay: true,
+      showVolumeControl: true,
+      showFullscreenControl: true,
+      tapToTogglePlayback: true,
+      controlsAutoHideDelay: 1400,
+      autoPlay: false,
+      muted: true,
+      loop: false,
+      playsInline: true,
+      showCaption: true,
+      captionText: "A calm flower field clip used for video demos.",
+      rounded: true,
+      shadow: false,
+      preload: "metadata",
+    },
+  },
+  ratios: {
+    title: "Aspect Ratios",
+    description: "Built-in ratio presets for common media frames.",
+    showProps: false,
+    render: () => (
+      <div style={{ display: "grid", gap: "1rem" }}>
+        <Video src={sampleVideo} aspectRatio="16:9" caption="16:9 widescreen" />
+        <Video src={sampleVideo} aspectRatio="4:3" caption="4:3 standard" />
+        <Video src={sampleVideo} aspectRatio="1:1" caption="1:1 square" />
+      </div>
+    ),
+    code: `import { Video } from "@solara/video";
+
+export function Example() {
+  const src = "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4";
+
+  return (
+    <div style={{ display: "grid", gap: "1rem" }}>
+      <Video src={src} aspectRatio="16:9" caption="16:9 widescreen" />
+      <Video src={src} aspectRatio="4:3" caption="4:3 standard" />
+      <Video src={src} aspectRatio="1:1" caption="1:1 square" />
+    </div>
+  );
+}
+`,
+  },
+  minimal: {
+    title: "Minimal Player",
+    description: "A floating action-only control bar with icon-based play, pause, and restart.",
+    showProps: false,
+    render: () => (
+      <Video
+        src={sampleVideo}
+        poster={samplePoster}
+        controlsType="minimal"
+        muted
+        showCaption={false}
+        shadow
+      />
+    ),
+    code: `import { Video } from "@solara/video";
+
+export function Example() {
+  return (
+    <Video
+      src="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"
+      poster="https://interactive-examples.mdn.mozilla.net/media/examples/friday.jpg"
+      controlsType="minimal"
+      muted
+      showCaption={false}
+      shadow
+    />
+  );
+}
+`,
+  },
+  noControls: {
+    title: "No Controls",
+    description: "Hides custom controls entirely for ambient or decorative playback.",
+    showProps: false,
+    render: () => (
+      <Video
+        src={sampleVideo}
+        poster={samplePoster}
+        controlsType="none"
+        muted
+        loop
+        autoPlay
+        showCaption={false}
+        shadow
+      />
+    ),
+    code: `import { Video } from "@solara/video";
+
+export function Example() {
+  return (
+    <Video
+      src="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"
+      poster="https://interactive-examples.mdn.mozilla.net/media/examples/friday.jpg"
+      controlsType="none"
+      muted
+      loop
+      autoPlay
+      showCaption={false}
+      shadow
+    />
+  );
+}
+`,
+  },
+};

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@varialkit/video",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./examples": "./examples.tsx"
+  },
+  "dependencies": {
+    "@varialkit/icons": "0.1.0"
+  },
+  "files": [
+    "src",
+    "docs.md",
+    "examples.tsx"
+  ],
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "19.0.10",
+    "react": "19.0.0"
+  }
+}

package/src/Video.scss

@@ -0,0 +1,317 @@
+.solara-video {
+  --video-border: var(--color-divider-secondary);
+  --video-background: var(--color-surface-200);
+  --video-caption: var(--color-text-secondary);
+  --video-radius: var(--radius-3);
+  --video-controls-surface: rgba(6, 10, 16, 0.76);
+  --video-controls-surface-soft: rgba(6, 10, 16, 0.45);
+  --video-controls-foreground: var(--color-text-inverse);
+
+  display: grid;
+  gap: calc(var(--space-2) * var(--spacing-multiplier));
+  width: 100%;
+  margin: 0;
+  font-family: var(--font-body);
+}
+
+.solara-video__frame {
+  position: relative;
+  width: 100%;
+  overflow: hidden;
+  border: 1px solid var(--video-border);
+  border-radius: var(--video-radius);
+  background: var(--video-background);
+  aspect-ratio: 16 / 9;
+}
+
+.solara-video__element {
+  display: block;
+  width: 100%;
+  height: 100%;
+  background: var(--video-background);
+}
+
+.solara-video__controls {
+  position: absolute;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  opacity: 0;
+  transform: translateY(8px);
+  pointer-events: none;
+  transition: opacity 160ms ease, transform 160ms ease;
+}
+
+.solara-video__frame:hover .solara-video__controls,
+.solara-video__frame:focus-within .solara-video__controls {
+  opacity: 1;
+  transform: translateY(0);
+  pointer-events: auto;
+}
+
+.solara-video__controls--visible {
+  opacity: 1;
+  transform: translateY(0);
+  pointer-events: auto;
+}
+
+.solara-video__controls--control-bar {
+  display: flex;
+  align-items: center;
+  padding: calc(var(--space-2) * var(--spacing-multiplier));
+  background: linear-gradient(to top, var(--video-controls-surface), rgba(0, 0, 0, 0));
+}
+
+.solara-video__controls--control-bar .solara-video__controls-row {
+  padding: calc(var(--space-1) * var(--spacing-multiplier))
+    calc(var(--space-2) * var(--spacing-multiplier));
+  // border: 1px solid rgba(255, 255, 255, 0.32);
+  border-radius: var(--radius-pill);
+  // background: rgba(0, 0, 0, 0.52);
+  // box-shadow: 0 8px 18px rgba(0, 0, 0, 0.38);
+  // -webkit-backdrop-filter: blur(12px) saturate(1.2);
+  // backdrop-filter: blur(12px) saturate(1.2);
+}
+
+.solara-video__controls--minimal {
+  display: flex;
+  justify-content: flex-end;
+  padding: calc(var(--space-2) * var(--spacing-multiplier));
+  background: linear-gradient(to top, var(--video-controls-surface-soft), rgba(0, 0, 0, 0));
+}
+
+.solara-video__controls-row {
+  display: flex;
+  align-items: center;
+  gap: calc(var(--space-2) * var(--spacing-multiplier));
+  width: 100%;
+  flex-wrap: nowrap;
+}
+
+.solara-video__controls-group {
+  display: flex;
+  align-items: center;
+  gap: calc(var(--space-2) * var(--spacing-multiplier));
+  min-width: 0;
+}
+
+.solara-video__controls-group--end {
+  margin-left: auto;
+}
+
+.solara-video__control-button {
+  appearance: none;
+  border: 1px solid rgba(255, 255, 255, 0.38);
+  border-radius: var(--radius-pill);
+  padding: calc(var(--space-1) * var(--spacing-multiplier))
+    calc(var(--space-3) * var(--spacing-multiplier));
+  font-size: var(--font-size-caption-scaled);
+  line-height: var(--line-height-caption-scaled);
+  font-weight: var(--font-weight-semi-bold);
+  color: var(--video-controls-foreground);
+  background: rgba(0, 0, 0, 0.62);
+  box-shadow: 0 0 0 1px rgba(0, 0, 0, 0.25), 0 6px 14px rgba(0, 0, 0, 0.35);
+  -webkit-backdrop-filter: blur(8px) saturate(1.1);
+  backdrop-filter: blur(8px) saturate(1.1);
+  cursor: pointer;
+  white-space: nowrap;
+}
+
+.solara-video__control-button--secondary {
+  background: rgba(0, 0, 0, 0.7);
+}
+
+.solara-video__control-button--icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 2rem;
+  height: 2rem;
+  padding: 0;
+  border-radius: 999px;
+  color: #fff;
+}
+
+.solara-video__control-icon {
+  display: block;
+  color: #fff;
+  filter: drop-shadow(0 1px 1px rgba(0, 0, 0, 0.9)) drop-shadow(0 0 4px rgba(0, 0, 0, 0.7));
+}
+
+.solara-video__control-icon [fill]:not([fill="none"]) {
+  fill: #fff !important;
+}
+
+.solara-video__control-icon [stroke]:not([stroke="none"]) {
+  stroke: #fff !important;
+}
+
+.solara-video__control-button:hover {
+  background: rgba(0, 0, 0, 0.78);
+  border-color: rgba(255, 255, 255, 0.55);
+}
+
+.solara-video__control-button:active {
+  background: rgba(0, 0, 0, 0.85);
+}
+
+.solara-video__controls--control-bar .solara-video__control-button {
+  border-color: transparent;
+  background: transparent;
+  box-shadow: none;
+  -webkit-backdrop-filter: none;
+  backdrop-filter: none;
+}
+
+.solara-video__controls--control-bar .solara-video__control-button:hover {
+  background: rgba(255, 255, 255, 0.16);
+  border-color: transparent;
+}
+
+.solara-video__controls--control-bar .solara-video__control-button:active {
+  background: rgba(255, 255, 255, 0.24);
+}
+
+.solara-video__control-button:focus-visible,
+.solara-video__scrubber:focus-visible,
+.solara-video__volume:focus-visible {
+  box-shadow: 0 0 0 3px var(--color-focus-halo);
+  outline-offset: 2px;
+}
+
+.solara-video__scrubber,
+.solara-video__volume {
+  appearance: none;
+  -webkit-appearance: none;
+  cursor: pointer;
+}
+
+.solara-video__scrubber-wrap {
+  position: relative;
+  flex: 1 1 auto;
+  min-width: 7rem;
+  --solara-video-progress: 0%;
+  --solara-video-tooltip-position: 0%;
+}
+
+.solara-video__scrubber {
+  width: 100%;
+  height: 0.5rem;
+  border: 0;
+  border-radius: 999px;
+  background: linear-gradient(
+    to right,
+    var(--color-accent-primary) 0%,
+    var(--color-accent-primary) var(--solara-video-progress),
+    rgba(255, 255, 255, 0.34) var(--solara-video-progress),
+    rgba(255, 255, 255, 0.34) 100%
+  );
+}
+
+.solara-video__scrubber::-webkit-slider-runnable-track {
+  -webkit-appearance: none;
+  height: 0.5rem;
+  border-radius: 999px;
+  background: transparent;
+}
+
+.solara-video__scrubber::-webkit-slider-thumb {
+  -webkit-appearance: none;
+  appearance: none;
+  margin-top: -0.25rem;
+  width: 1rem;
+  height: 1rem;
+  border: 2px solid rgba(0, 0, 0, 0.2);
+  border-radius: 999px;
+  background: var(--color-text-inverse);
+}
+
+.solara-video__scrubber::-moz-range-track {
+  height: 0.5rem;
+  border: 0;
+  border-radius: 999px;
+  background: rgba(255, 255, 255, 0.28);
+}
+
+.solara-video__scrubber::-moz-range-progress {
+  height: 0.5rem;
+  border-radius: 999px;
+  background: var(--color-accent-primary);
+}
+
+.solara-video__scrubber::-moz-range-thumb {
+  width: 1rem;
+  height: 1rem;
+  border: 2px solid rgba(0, 0, 0, 0.2);
+  border-radius: 999px;
+  background: var(--color-text-inverse);
+}
+
+.solara-video__scrubber-tooltip {
+  position: absolute;
+  left: var(--solara-video-tooltip-position);
+  bottom: calc(100% + 0.6rem);
+  transform: translateX(-50%);
+  padding: 0.15rem 0.4rem;
+  border-radius: var(--radius-2);
+  font-size: 0.7rem;
+  line-height: 1.1;
+  color: var(--color-text-inverse);
+  background: rgba(0, 0, 0, 0.82);
+  white-space: nowrap;
+  pointer-events: none;
+}
+
+.solara-video__volume {
+  width: min(7rem, 30vw);
+  height: 0.4rem;
+  accent-color: var(--color-accent-primary);
+}
+
+.solara-video__time {
+  color: #fff;
+  font-size: var(--font-size-caption-scaled);
+  line-height: var(--line-height-caption-scaled);
+  white-space: nowrap;
+  text-shadow: 0 1px 1px rgba(0, 0, 0, 0.95), 0 0 6px rgba(0, 0, 0, 0.6);
+}
+
+.solara-video__caption {
+  margin: 0;
+  font-size: var(--font-size-caption-scaled);
+  line-height: var(--line-height-caption-scaled);
+  color: var(--video-caption);
+}
+
+.solara-video--rounded {
+  --video-radius: var(--radius-3);
+}
+
+.solara-video--square {
+  --video-radius: var(--radius-0);
+}
+
+.solara-video--shadow .solara-video__frame {
+  box-shadow: var(--elevation-2);
+}
+
+@media (max-width: 640px) {
+  .solara-video__controls-row {
+    gap: calc(var(--space-1) * var(--spacing-multiplier));
+  }
+
+  .solara-video__control-button {
+    padding: calc(var(--space-1) * var(--spacing-multiplier))
+      calc(var(--space-2) * var(--spacing-multiplier));
+  }
+
+  .solara-video__control-button--icon {
+    width: 1.875rem;
+    height: 1.875rem;
+    padding: 0;
+  }
+
+  .solara-video__volume {
+    width: min(5rem, 24vw);
+  }
+}

package/src/Video.tsx

@@ -0,0 +1,606 @@
+import React, { forwardRef, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Icon } from "@solara/icons";
+import type { VideoAspectRatio, VideoProps } from "./Video.types";
+import "./Video.scss";
+
+const aspectRatioMap: Record<Exclude<VideoAspectRatio, number>, string | null> = {
+  auto: null,
+  "16:9": "16 / 9",
+  "4:3": "4 / 3",
+  "1:1": "1 / 1",
+  "21:9": "21 / 9",
+};
+
+const resolveAspectRatio = (value: VideoAspectRatio | undefined) => {
+  if (value === undefined) return aspectRatioMap["16:9"];
+  if (typeof value === "number") return value > 0 ? `${value}` : aspectRatioMap["16:9"];
+  return aspectRatioMap[value];
+};
+
+const formatTime = (seconds: number) => {
+  if (!Number.isFinite(seconds) || seconds < 0) return "0:00";
+
+  const total = Math.floor(seconds);
+  const hours = Math.floor(total / 3600);
+  const minutes = Math.floor((total % 3600) / 60);
+  const remainder = total % 60;
+
+  if (hours > 0) {
+    return `${hours}:${minutes.toString().padStart(2, "0")}:${remainder
+      .toString()
+      .padStart(2, "0")}`;
+  }
+
+  return `${minutes}:${remainder.toString().padStart(2, "0")}`;
+};
+
+/**
+ * Video component built on native `<video>` with a custom, scalable control system.
+ *
+ * Architecture notes:
+ * - The media element remains the source of truth for playback and volume.
+ * - React state mirrors key media values so custom controls can render instantly.
+ * - `controlsType` is the top-level selector for `control-bar`, `minimal`, or `none`.
+ * - `controlBarMode` and `showControls` remain as compatibility inputs and map into `controlsType`.
+ */
+export const Video = forwardRef<HTMLVideoElement, VideoProps>(
+  (
+    {
+      showControls = true,
+      controlsType,
+      controlBarMode = "default",
+      tapToTogglePlayback = true,
+      controlsAutoHideDelay = 1400,
+      showScrubber = true,
+      showTimeDisplay = true,
+      showVolumeControl = true,
+      showFullscreenControl = true,
+      sources,
+      aspectRatio = "16:9",
+      fit = "cover",
+      caption,
+      showCaption = true,
+      rounded = true,
+      shadow = false,
+      className,
+      videoClassName,
+      videoStyle,
+      controlBarClassName,
+      style,
+      poster,
+      children,
+      onPlay,
+      onPause,
+      onEnded,
+      onClick,
+      onLoadedMetadata,
+      onTimeUpdate,
+      onVolumeChange,
+      ...videoProps
+    },
+    ref
+  ) => {
+    const resolvedAspectRatio = resolveAspectRatio(aspectRatio);
+    const frameRef = useRef<HTMLDivElement | null>(null);
+    const internalVideoRef = useRef<HTMLVideoElement | null>(null);
+    const controlsHideTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const previousVolumeRef = useRef(1);
+
+    // Playback state drives button labels and progress UI.
+    const [isPlaying, setIsPlaying] = useState(false);
+    const [hasEnded, setHasEnded] = useState(false);
+    const [duration, setDuration] = useState(0);
+    const [currentTime, setCurrentTime] = useState(0);
+    const [isScrubbing, setIsScrubbing] = useState(false);
+    const [scrubPreviewTime, setScrubPreviewTime] = useState<number | null>(null);
+    const [isHoveringScrubber, setIsHoveringScrubber] = useState(false);
+    const [hoverPreviewTime, setHoverPreviewTime] = useState<number | null>(null);
+    const [isFrameHovered, setIsFrameHovered] = useState(false);
+    const [areControlsVisible, setAreControlsVisible] = useState(true);
+
+    // Audio/fullscreen state is isolated so each concern scales independently.
+    const [volume, setVolume] = useState(1);
+    const [isMuted, setIsMuted] = useState(false);
+    const [isFullscreen, setIsFullscreen] = useState(false);
+
+    const setVideoRef = useCallback(
+      (node: HTMLVideoElement | null) => {
+        internalVideoRef.current = node;
+
+        if (typeof ref === "function") {
+          ref(node);
+          return;
+        }
+
+        if (ref) {
+          ref.current = node;
+        }
+      },
+      [ref]
+    );
+
+    useEffect(() => {
+      const video = internalVideoRef.current;
+      if (!video) return;
+
+      // Sync initial values from the underlying media element.
+      setIsPlaying(!video.paused && !video.ended);
+      setHasEnded(video.ended);
+      setDuration(Number.isFinite(video.duration) ? video.duration : 0);
+      setCurrentTime(Number.isFinite(video.currentTime) ? video.currentTime : 0);
+      setVolume(video.volume);
+      setIsMuted(video.muted);
+    }, []);
+
+    useEffect(() => {
+      const onFullscreenChange = () => {
+        const frame = frameRef.current;
+        const activeElement = document.fullscreenElement;
+        setIsFullscreen(Boolean(frame && activeElement && frame.contains(activeElement)));
+      };
+
+      document.addEventListener("fullscreenchange", onFullscreenChange);
+      return () => {
+        document.removeEventListener("fullscreenchange", onFullscreenChange);
+      };
+    }, []);
+
+    const togglePlayback = useCallback(() => {
+      const video = internalVideoRef.current;
+      if (!video) return;
+
+      if (video.ended || hasEnded) {
+        video.currentTime = 0;
+        void video.play();
+        return;
+      }
+
+      if (!video.paused) {
+        video.pause();
+        return;
+      }
+
+      void video.play();
+    }, [hasEnded]);
+
+    const seekTo = useCallback((nextTime: number) => {
+      const video = internalVideoRef.current;
+      if (!video || !Number.isFinite(nextTime)) return;
+      video.currentTime = Math.max(0, Math.min(nextTime, duration || nextTime));
+    }, [duration]);
+
+    const getScrubberTimeFromPointer = useCallback(
+      (event: React.PointerEvent<HTMLInputElement>) => {
+        const activeDuration = Number.isFinite(duration) && duration > 0 ? duration : 0;
+        if (!activeDuration) return 0;
+
+        const rect = event.currentTarget.getBoundingClientRect();
+        const relativeX = event.clientX - rect.left;
+        const ratio = Math.max(0, Math.min(relativeX / rect.width, 1));
+        return ratio * activeDuration;
+      },
+      [duration]
+    );
+
+    const setVideoVolume = useCallback((nextVolume: number) => {
+      const video = internalVideoRef.current;
+      if (!video) return;
+
+      const clamped = Math.max(0, Math.min(nextVolume, 1));
+      video.volume = clamped;
+      video.muted = clamped === 0;
+
+      if (clamped > 0) {
+        previousVolumeRef.current = clamped;
+      }
+    }, []);
+
+    const toggleMute = useCallback(() => {
+      const video = internalVideoRef.current;
+      if (!video) return;
+
+      if (video.muted || video.volume === 0) {
+        video.muted = false;
+        if (video.volume === 0) {
+          video.volume = previousVolumeRef.current > 0 ? previousVolumeRef.current : 1;
+        }
+        return;
+      }
+
+      previousVolumeRef.current = video.volume > 0 ? video.volume : previousVolumeRef.current;
+      video.muted = true;
+    }, []);
+
+    const toggleFullscreen = useCallback(async () => {
+      const frame = frameRef.current;
+      if (!frame) return;
+
+      if (!document.fullscreenElement) {
+        await frame.requestFullscreen();
+        return;
+      }
+
+      await document.exitFullscreen();
+    }, []);
+
+    const wrapperClasses = [
+      "solara-video",
+      rounded ? "solara-video--rounded" : "solara-video--square",
+      shadow ? "solara-video--shadow" : null,
+      className,
+    ]
+      .filter(Boolean)
+      .join(" ");
+
+    const videoClasses = ["solara-video__element", videoClassName]
+      .filter(Boolean)
+      .join(" ");
+
+    // Controls API precedence:
+    // 1) `controlsType` is the modern source of truth and should be used in new code.
+    // 2) `showControls={false}` remains a compatibility escape hatch to force `none`.
+    // 3) `controlBarMode` remains supported for older consumers and maps into controlsType semantics.
+    const resolvedControlsType = useMemo(() => {
+      if (controlsType) return controlsType;
+      if (!showControls) return "none";
+      return controlBarMode === "quick" ? "quick" : "control-bar";
+    }, [controlBarMode, controlsType, showControls]);
+
+    const clearControlsHideTimer = useCallback(() => {
+      if (!controlsHideTimerRef.current) return;
+      clearTimeout(controlsHideTimerRef.current);
+      controlsHideTimerRef.current = null;
+    }, []);
+
+    const scheduleControlsHide = useCallback(() => {
+      // Auto-hide is only for the full control-bar experience.
+      if (resolvedControlsType !== "control-bar") return;
+      clearControlsHideTimer();
+      controlsHideTimerRef.current = setTimeout(() => {
+        setAreControlsVisible(false);
+      }, Math.max(0, controlsAutoHideDelay));
+    }, [clearControlsHideTimer, controlsAutoHideDelay, resolvedControlsType]);
+
+    const revealControls = useCallback(() => {
+      setAreControlsVisible(true);
+      clearControlsHideTimer();
+
+      // On touch devices there may be no hover state, so we still auto-hide after inactivity.
+      if (
+        resolvedControlsType === "control-bar" &&
+        !isFrameHovered &&
+        !isScrubbing &&
+        !isHoveringScrubber
+      ) {
+        controlsHideTimerRef.current = setTimeout(() => {
+          setAreControlsVisible(false);
+        }, Math.max(0, controlsAutoHideDelay));
+      }
+    }, [
+      clearControlsHideTimer,
+      controlsAutoHideDelay,
+      isFrameHovered,
+      isHoveringScrubber,
+      isScrubbing,
+      resolvedControlsType,
+    ]);
+
+    useEffect(() => {
+      // On unmount we clean timers to avoid delayed state updates.
+      return () => {
+        clearControlsHideTimer();
+      };
+    }, [clearControlsHideTimer]);
+
+    useEffect(() => {
+      if (resolvedControlsType !== "control-bar") {
+        setAreControlsVisible(true);
+        clearControlsHideTimer();
+        return;
+      }
+
+      if (isFrameHovered || isScrubbing || isHoveringScrubber) {
+        revealControls();
+        return;
+      }
+
+      scheduleControlsHide();
+    }, [
+      clearControlsHideTimer,
+      isFrameHovered,
+      isHoveringScrubber,
+      isScrubbing,
+      resolvedControlsType,
+      scheduleControlsHide,
+      revealControls,
+    ]);
+
+    const controlsClasses = [
+      "solara-video__controls",
+      areControlsVisible ? "solara-video__controls--visible" : null,
+      resolvedControlsType === "minimal" || resolvedControlsType === "quick"
+        ? "solara-video__controls--minimal"
+        : "solara-video__controls--control-bar",
+      controlBarClassName,
+    ]
+      .filter(Boolean)
+      .join(" ");
+
+    const controlButtonLabel = hasEnded ? "Restart" : isPlaying ? "Pause" : "Play";
+    const controlButtonIconName = hasEnded
+      ? "arrow_line_rotate_left_16"
+      : isPlaying
+        ? "media_pause_16"
+        : "media_play_filled_16";
+    const volumeButtonLabel = isMuted || volume === 0 ? "Unmute video" : "Mute video";
+    const volumeButtonIconName =
+      isMuted || volume === 0 ? "media_sound_off_filled_16" : "media_sound_filled_16";
+    const fullscreenButtonLabel = isFullscreen ? "Exit fullscreen" : "Enter fullscreen";
+    const resolvedDuration = Number.isFinite(duration) && duration > 0 ? duration : 0;
+    const safeCurrentTime = Math.min(currentTime, resolvedDuration || currentTime);
+    const scrubberValue =
+      isScrubbing && scrubPreviewTime !== null ? scrubPreviewTime : safeCurrentTime;
+    const tooltipTime =
+      isScrubbing && scrubPreviewTime !== null
+        ? scrubPreviewTime
+        : isHoveringScrubber && hoverPreviewTime !== null
+          ? hoverPreviewTime
+          : safeCurrentTime;
+
+    const scrubberPercent = useMemo(() => {
+      if (!resolvedDuration) return 0;
+      return Math.max(0, Math.min((scrubberValue / resolvedDuration) * 100, 100));
+    }, [resolvedDuration, scrubberValue]);
+
+    const tooltipPercent = useMemo(() => {
+      if (!resolvedDuration) return 0;
+      return Math.max(0, Math.min((tooltipTime / resolvedDuration) * 100, 100));
+    }, [resolvedDuration, tooltipTime]);
+
+    return (
+      <figure className={wrapperClasses} style={style}>
+        <div
+          ref={frameRef}
+          className="solara-video__frame"
+          style={resolvedAspectRatio ? { aspectRatio: resolvedAspectRatio } : undefined}
+          onPointerEnter={() => {
+            setIsFrameHovered(true);
+            revealControls();
+          }}
+          onPointerMove={() => {
+            if (resolvedControlsType === "control-bar") {
+              revealControls();
+            }
+          }}
+          onPointerLeave={() => {
+            setIsFrameHovered(false);
+          }}
+          onFocusCapture={() => {
+            revealControls();
+          }}
+          onBlurCapture={(event) => {
+            const nextFocused = event.relatedTarget as Node | null;
+            if (!frameRef.current?.contains(nextFocused)) {
+              scheduleControlsHide();
+            }
+          }}
+        >
+          <video
+            {...videoProps}
+            ref={setVideoRef}
+            className={videoClasses}
+            controls={false}
+            poster={poster}
+            style={{ objectFit: fit, ...videoStyle }}
+            onLoadedMetadata={(event) => {
+              const video = event.currentTarget;
+              setDuration(Number.isFinite(video.duration) ? video.duration : 0);
+              onLoadedMetadata?.(event);
+            }}
+            onClick={(event) => {
+              // Surface taps/clicks can control playback while still honoring consumer callbacks.
+              if (tapToTogglePlayback) {
+                togglePlayback();
+              }
+              revealControls();
+              onClick?.(event);
+            }}
+            onTimeUpdate={(event) => {
+              const video = event.currentTarget;
+              setCurrentTime(video.currentTime);
+              onTimeUpdate?.(event);
+            }}
+            onVolumeChange={(event) => {
+              const video = event.currentTarget;
+              setVolume(video.volume);
+              setIsMuted(video.muted);
+              onVolumeChange?.(event);
+            }}
+            onPlay={(event) => {
+              setIsPlaying(true);
+              setHasEnded(false);
+              revealControls();
+              onPlay?.(event);
+            }}
+            onPause={(event) => {
+              // Keep ended-state visual intact when playback naturally finishes.
+              if (!event.currentTarget.ended) {
+                setHasEnded(false);
+              }
+              setIsPlaying(false);
+              revealControls();
+              onPause?.(event);
+            }}
+            onEnded={(event) => {
+              setIsPlaying(false);
+              setHasEnded(true);
+              revealControls();
+              onEnded?.(event);
+            }}
+          >
+            {sources?.map((source) => (
+              <source key={`${source.src}-${source.type ?? "auto"}-${source.media ?? "all"}`} {...source} />
+            ))}
+            {children}
+          </video>
+
+          {resolvedControlsType !== "none" ? (
+            <div className={controlsClasses}>
+              <div className="solara-video__controls-row">
+                <button
+                  type="button"
+                  className="solara-video__control-button solara-video__control-button--icon"
+                  onClick={() => {
+                    revealControls();
+                    togglePlayback();
+                  }}
+                  aria-label={`${controlButtonLabel} video`}
+                >
+                  <Icon
+                    name={controlButtonIconName}
+                    size={16}
+                    aria-hidden
+                    className="solara-video__control-icon"
+                  />
+                </button>
+
+                {resolvedControlsType === "control-bar" && showScrubber ? (
+                  <div
+                    className="solara-video__scrubber-wrap"
+                    style={
+                      {
+                        "--solara-video-progress": `${scrubberPercent}%`,
+                        "--solara-video-tooltip-position": `${tooltipPercent}%`,
+                      } as React.CSSProperties
+                    }
+                  >
+                    {/* Scrubber tooltip follows hover or drag position via a dedicated % CSS variable. */}
+                    {isScrubbing || (isHoveringScrubber && resolvedDuration > 0) ? (
+                      <span className="solara-video__scrubber-tooltip">{formatTime(tooltipTime)}</span>
+                    ) : null}
+                    <input
+                      className="solara-video__scrubber"
+                      type="range"
+                      min={0}
+                      max={resolvedDuration || 0}
+                      step={0.1}
+                      value={scrubberValue}
+                      disabled={!resolvedDuration}
+                      onPointerDown={(event) => {
+                        revealControls();
+                        setIsScrubbing(true);
+                        setScrubPreviewTime(Number(event.currentTarget.value));
+                      }}
+                      onPointerUp={() => {
+                        setIsScrubbing(false);
+                        setScrubPreviewTime(null);
+                      }}
+                      onPointerCancel={() => {
+                        setIsScrubbing(false);
+                        setScrubPreviewTime(null);
+                      }}
+                      onPointerEnter={(event) => {
+                        setIsHoveringScrubber(true);
+                        setHoverPreviewTime(getScrubberTimeFromPointer(event));
+                      }}
+                      onPointerMove={(event) => {
+                        revealControls();
+                        setHoverPreviewTime(getScrubberTimeFromPointer(event));
+                      }}
+                      onPointerLeave={() => {
+                        setIsHoveringScrubber(false);
+                        setHoverPreviewTime(null);
+                      }}
+                      onBlur={() => {
+                        setIsScrubbing(false);
+                        setScrubPreviewTime(null);
+                        setIsHoveringScrubber(false);
+                        setHoverPreviewTime(null);
+                      }}
+                      onInput={(event) => {
+                        revealControls();
+                        const nextTime = Number(event.currentTarget.value);
+                        setScrubPreviewTime(nextTime);
+                        seekTo(nextTime);
+                      }}
+                      onChange={(event) => {
+                        const nextTime = Number(event.currentTarget.value);
+                        seekTo(nextTime);
+                      }}
+                      aria-label="Seek video position"
+                    />
+                  </div>
+                ) : null}
+
+                {resolvedControlsType === "control-bar" && showTimeDisplay ? (
+                  <span className="solara-video__time" aria-live="off">
+                    {formatTime(currentTime)} / {formatTime(resolvedDuration)}
+                  </span>
+                ) : null}
+
+                {resolvedControlsType === "control-bar" && showVolumeControl ? (
+                  <>
+                    <button
+                      type="button"
+                      className="solara-video__control-button solara-video__control-button--secondary solara-video__control-button--icon"
+                      onClick={() => {
+                        revealControls();
+                        toggleMute();
+                      }}
+                      aria-label={volumeButtonLabel}
+                    >
+                      <Icon
+                        name={volumeButtonIconName}
+                        size={16}
+                        aria-hidden
+                        className="solara-video__control-icon"
+                      />
+                    </button>
+
+                    <input
+                      className="solara-video__volume"
+                      type="range"
+                      min={0}
+                      max={1}
+                      step={0.05}
+                      value={isMuted ? 0 : volume}
+                      onChange={(event) => {
+                        revealControls();
+                        setVideoVolume(Number(event.currentTarget.value));
+                      }}
+                      aria-label="Adjust volume"
+                    />
+                  </>
+                ) : null}
+
+                {resolvedControlsType === "control-bar" && showFullscreenControl ? (
+                  <button
+                    type="button"
+                    className="solara-video__control-button solara-video__control-button--secondary solara-video__control-button--icon"
+                    onClick={() => {
+                      revealControls();
+                      void toggleFullscreen();
+                    }}
+                    aria-label={fullscreenButtonLabel}
+                  >
+                    <Icon
+                      name="view_box_inside_16"
+                      size={16}
+                      aria-hidden
+                      className="solara-video__control-icon"
+                    />
+                  </button>
+                ) : null}
+              </div>
+            </div>
+          ) : null}
+        </div>
+        {showCaption && caption ? (
+          <figcaption className="solara-video__caption">{caption}</figcaption>
+        ) : null}
+      </figure>
+    );
+  }
+);
+
+Video.displayName = "Video";

package/src/Video.types.ts

@@ -0,0 +1,59 @@
+import type React from "react";
+
+export type VideoAspectRatio = "auto" | "16:9" | "4:3" | "1:1" | "21:9" | number;
+export type VideoFit = "contain" | "cover" | "fill" | "none" | "scale-down";
+export type VideoPreload = "none" | "metadata" | "auto";
+export type VideoControlBarMode = "default" | "quick";
+export type VideoControlsType = "control-bar" | "quick" | "minimal" | "none";
+
+export type VideoSource = {
+  /** Source URL for a video format. */
+  src: string;
+  /** MIME type for this source, such as `video/mp4`. */
+  type?: string;
+  /** Optional media condition for responsive source selection. */
+  media?: string;
+};
+
+export type VideoProps = Omit<React.VideoHTMLAttributes<HTMLVideoElement>, "controls"> & {
+  /** Controls whether custom overlay controls are visible. */
+  showControls?: boolean;
+  /** Preferred controls presentation: full control-bar, quick/minimal icon action button, or none. */
+  controlsType?: VideoControlsType;
+  /** @deprecated Use `controlsType` instead. */
+  controlBarMode?: VideoControlBarMode;
+  /** Shows a seek bar in the default control bar mode. */
+  showScrubber?: boolean;
+  /** Shows current time and duration in the default control bar mode. */
+  showTimeDisplay?: boolean;
+  /** Shows sound toggle icon + volume controls in the default control bar mode. */
+  showVolumeControl?: boolean;
+  /** Shows fullscreen toggle icon in the default control bar mode. */
+  showFullscreenControl?: boolean;
+  /** Optional list of source definitions. If provided, they render as nested `<source>` tags. */
+  sources?: VideoSource[];
+  /** Preferred presentation ratio for the player wrapper. */
+  aspectRatio?: VideoAspectRatio;
+  /** How the video should scale inside the frame. */
+  fit?: VideoFit;
+  /** Optional caption text or node shown beneath the player. */
+  caption?: React.ReactNode;
+  /** Toggles caption visibility when caption content is provided. */
+  showCaption?: boolean;
+  /** Renders a rounded frame around the video. */
+  rounded?: boolean;
+  /** Applies a subtle elevation shadow to the frame. */
+  shadow?: boolean;
+  /** Optional class name for the outer wrapper element. */
+  className?: string;
+  /** Optional class name for the inner `<video>` element. */
+  videoClassName?: string;
+  /** Optional style object for the inner `<video>` element. */
+  videoStyle?: React.CSSProperties;
+  /** Optional class name for the custom control bar container. */
+  controlBarClassName?: string;
+  /** Enables tapping/clicking the video surface to toggle play and pause. */
+  tapToTogglePlayback?: boolean;
+  /** Delay in milliseconds before auto-hiding the default control bar after interaction ends. */
+  controlsAutoHideDelay?: number;
+};

package/src/index.ts

@@ -0,0 +1,10 @@
+export { Video } from "./Video";
+export type {
+  VideoProps,
+  VideoSource,
+  VideoAspectRatio,
+  VideoFit,
+  VideoPreload,
+  VideoControlBarMode,
+  VideoControlsType,
+} from "./Video.types";