docs: add v4 migration + docs (#954)

https://media-chrome-docs-git-v4-migration-mux.vercel.app/docs/en/migration/from-3.x-to-4.0
muxinc · Aug 14, 2024 · b2148b7 · b2148b7
1 parent ea406e1
commit b2148b7
Show file tree

Hide file tree

Showing 10 changed files with 165 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -38,7 +38,7 @@ You can find the [documentation for v0.x of media-chrome here.](https://v0.media
 ### Video Example
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@3/+esm"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@4/+esm"></script>
 
 <media-controller>
   <video
@@ -73,7 +73,7 @@ You can find the [documentation for v0.x of media-chrome here.](https://v0.media
 ### Audio Example
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@3/+esm"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@4/+esm"></script>
 
 <media-controller audio>
   <audio

diff --git a/docs/src/config.ts b/docs/src/config.ts
@@ -121,6 +121,7 @@ export const SIDEBAR: Sidebar = {
       { text: 'Migrating to 1.0', link: 'docs/en/migration/from-0.x-to-1.0' },
       { text: 'Migrating to 2.0', link: 'docs/en/migration/from-1.x-to-2.0' },
       { text: 'Migrating to 3.0', link: 'docs/en/migration/from-2.x-to-3.0' },
+      { text: 'Migrating to 4.0', link: 'docs/en/migration/from-3.x-to-4.0' },
       { text: 'Showcase', link: 'docs/en/showcase' },
     ],
   },

diff --git a/docs/src/pages/docs/en/audio-player.md b/docs/src/pages/docs/en/audio-player.md
@@ -24,7 +24,7 @@ Since audio players don’t use the same visual layout as video players do, we c
 </media-controller>
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@3/+esm"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@4/+esm"></script>
 
 <media-controller audio>
   <audio

diff --git a/docs/src/pages/docs/en/components/media-audio-track-menu.mdx b/docs/src/pages/docs/en/components/media-audio-track-menu.mdx
@@ -9,6 +9,13 @@ import SandpackContainer from "../../../../components/SandpackContainer.astro";
 
 A menu for audio tracks.
 
+> Remember to add the seperate menu module for the menu components.
+
+```js
+import "media-chrome";
+import "media-chrome/menu";
+```
+
 ### Default usage
 
 <SandpackContainer

diff --git a/docs/src/pages/docs/en/components/media-captions-menu.mdx b/docs/src/pages/docs/en/components/media-captions-menu.mdx
@@ -9,6 +9,13 @@ import SandpackContainer from "../../../../components/SandpackContainer.astro";
 
 A menu for subtitles and captions.
 
+> Remember to add the seperate menu module for the menu components.
+
+```js
+import "media-chrome";
+import "media-chrome/menu";
+```
+
 ### Default usage
 
 <SandpackContainer

diff --git a/docs/src/pages/docs/en/components/media-playback-rate-menu.mdx b/docs/src/pages/docs/en/components/media-playback-rate-menu.mdx
@@ -9,6 +9,13 @@ import SandpackContainer from "../../../../components/SandpackContainer.astro";
 
 A menu for playback rates.
 
+> Remember to add the seperate menu module for the menu components.
+
+```js
+import "media-chrome";
+import "media-chrome/menu";
+```
+
 ### Default usage
 
 <SandpackContainer

diff --git a/docs/src/pages/docs/en/components/media-settings-menu.mdx b/docs/src/pages/docs/en/components/media-settings-menu.mdx
@@ -9,6 +9,13 @@ import SandpackContainer from "../../../../components/SandpackContainer.astro";
 
 A menu for nested submenu items. This is used for settings like quality, speed, and captions.
 
+> Remember to add the seperate menu module for the menu components.
+
+```js
+import "media-chrome";
+import "media-chrome/menu";
+```
+
 ### Default usage
 
 <SandpackContainer

diff --git a/docs/src/pages/docs/en/get-started.mdx b/docs/src/pages/docs/en/get-started.mdx
@@ -54,7 +54,7 @@ Load the module in the `<head>` of your HTML page. Note the `type="module"`, tha
 
 <CopyToClipboard>
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@3/+esm"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@4/+esm"></script>
 ```
 </CopyToClipboard>
 

diff --git a/docs/src/pages/docs/en/migration/from-3.x-to-4.0.md b/docs/src/pages/docs/en/migration/from-3.x-to-4.0.md
@@ -0,0 +1,125 @@
+---
+title: Migrating from v3.x to v4.0
+description: Migration guide
+layout: ../../../../layouts/MainLayout.astro
+---
+
+There are 3 breaking changes in v4 that should be relatively easy to migrate to.
+Here's a high level overview:
+
+### Release notes
+
+- The Media Chrome source code is now completely written in TypeScript.
+- A new component `<media-tooltip>` is introduced to show tooltips for the control buttons.
+- Menu related components are moved to a separate import.
+
+
+### Breaking changes
+
+**Media Chrome source code is now written in TypeScript**
+- The source code is now written in TypeScript. In most cases this should not affect your app, only in some rare cases you might have to update some types in your app. If you're importing the source code directly, you will need to update your import paths to `.ts` files.
+
+**Tooltips are enabled by default**
+- v4 comes with tooltips enabled by default. If you don't want them, you can disable them by setting the `notooltip` attribute on the specfic button. To disable all tooltips you can set the CSS var `--media-tooltip-display: none;` on the `media-controller` element.
+
+**Deprecated experimental selectmenu related components**
+- `media-chrome-listbox`, `media-chrome-option`, `media-chrome-selectmenu` and variants for captions, playback rate, rendition and audio tracks are now deprecated. Instead you can use the new menu components.
+
+**Menu components moved to separate import**
+- The menu components that were included by default in v3 are now moved to a separate import. This gives you more granular control and can save some extra weight in the final JS bundle if you don't need these components. You can import them from `media-chrome/menu`.
+
+
+### Example of HTML changes
+
+#### Disable default enabled tooltips for all buttons
+
+**Before**
+
+```html
+  <script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@3/+esm"></script>
+
+  <media-controller>
+    <mux-video
+      slot="media"
+      src="https://stream.mux.com/Sc89iWAyNkhJ3P1rQ02nrEdCFTnfT01CZ2KmaEcxXfB008.m3u8"
+    ></mux-video>
+    <media-control-bar>
+      <media-play-button></media-play-button>
+      <media-time-range></media-time-range>
+      <media-mute-button></media-mute-button>
+      <media-rendition-menu-button></media-rendition-menu-button>
+      <media-fullscreen-button></media-fullscreen-button>
+    </media-control-bar>
+  </media-controller>
+```
+
+**After**
+
+```html
+  <script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@4/+esm"></script>
+
+  <style>
+    media-controller {
+      --media-tooltip-display: none;
+    }
+  </style>
+
+  <media-controller>
+    <mux-video
+      slot="media"
+      src="https://stream.mux.com/Sc89iWAyNkhJ3P1rQ02nrEdCFTnfT01CZ2KmaEcxXfB008.m3u8"
+    ></mux-video>
+    <media-control-bar>
+      <media-play-button></media-play-button>
+      <media-time-range></media-time-range>
+      <media-mute-button></media-mute-button>
+      <media-rendition-menu-button></media-rendition-menu-button>
+      <media-fullscreen-button></media-fullscreen-button>
+    </media-control-bar>
+  </media-controller>
+```
+
+#### Menu components moved to separate import
+
+**Before**
+
+```html
+  <script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@3/+esm"></script>
+
+  <media-controller>
+    <mux-video
+      slot="media"
+      src="https://stream.mux.com/Sc89iWAyNkhJ3P1rQ02nrEdCFTnfT01CZ2KmaEcxXfB008.m3u8"
+    ></mux-video>
+    <media-rendition-menu anchor="auto" hidden></media-rendition-menu>
+    <media-control-bar>
+      <media-play-button></media-play-button>
+      <media-time-range></media-time-range>
+      <media-mute-button></media-mute-button>
+      <media-rendition-menu-button></media-rendition-menu-button>
+      <media-fullscreen-button></media-fullscreen-button>
+    </media-control-bar>
+  </media-controller>
+```
+
+**After**
+
+```html
+  <script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@4/+esm"></script>
+  <script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@4/menu/+esm"></script>
+
+  <media-controller>
+    <mux-video
+      slot="media"
+      src="https://stream.mux.com/Sc89iWAyNkhJ3P1rQ02nrEdCFTnfT01CZ2KmaEcxXfB008.m3u8"
+    ></mux-video>
+    <media-rendition-menu anchor="auto" hidden></media-rendition-menu>
+    <media-control-bar>
+      <media-play-button></media-play-button>
+      <media-time-range></media-time-range>
+      <media-mute-button></media-mute-button>
+      <media-rendition-menu-button></media-rendition-menu-button>
+      <media-fullscreen-button></media-fullscreen-button>
+    </media-control-bar>
+  </media-controller>
+```
diff --git a/docs/src/pages/docs/en/themes/index.md b/docs/src/pages/docs/en/themes/index.md
@@ -14,6 +14,13 @@ the context.
 Themes provide a great solution for changing the look and feel of your player,
 and wrap your media controls up in a nice and portable package.
 
+> Remember to add the seperate media-theme-element module for the theme component.
+
+```js
+import "media-chrome";
+import "media-chrome/media-theme-element";
+```
+
 ## Basics
 
 Themes are created primarily with HTML + CSS and its contents are defined in a