vue-screenfull 1.1.1 → 1.1.2

package/README.md

@@ -8,38 +8,33 @@
 [license-image]: https://img.shields.io/npm/l/vue-screenfull.svg
 [license-url]: https://github.com/chengchuu/vue-screenfull/blob/main/LICENSE
 
-Reactive, strongly typed, and SSR-safe fullscreen utilities for Vue 3, with an optional CSS
-pseudo-fullscreen fallback.
+`vue-screenfull` provides reactive, strongly typed fullscreen controls for Vue 3, with SSR-safe
+imports and an optional CSS fallback when native arbitrary-element fullscreen is unavailable.
 
 - [Project website](https://chengchuu.github.io/vue-screenfull/)
 - [Live playground](https://chengchuu.github.io/vue-screenfull/playground/)
 - [API documentation](https://chengchuu.github.io/vue-screenfull/api/)
 
-## Features
-
-- Reactive Composition API state with automatic scope cleanup.
-- Standard, WebKit, Mozilla, and Microsoft-prefixed API detection.
-- Vue template refs, component refs, elements, and safe CSS selectors.
-- Structured results and actionable errors instead of swallowed rejections.
-- Renderless component, directive, optional plugin, and framework-neutral controller.
-
 ## Installation
 
+Install the package in a Vue 3.3 or later project:
+
 ```bash
 npm install vue-screenfull
 ```
 
-`lib/vue-screenfull.min.js` exposes `VUE_SCREENFULL` and requires the global `Vue`. Although Vue is
-an optional peer dependency, package-root imports still require Vue 3 at runtime.
+`vue-screenfull` provides the Vue composables, component, directive, and plugin, and requires Vue 3
+at runtime. Vue remains an optional peer dependency so `vue-screenfull/browser` can run without it.
+The browser IIFE, `lib/vue-screenfull.min.js`, exposes `VUE_SCREENFULL` and expects a global `Vue`.
 
 ## Basic Usage
 
 ```vue
 <script setup lang="ts">
-import { useTemplateRef } from "vue";
+import { ref } from "vue";
 import { useScreenfull } from "vue-screenfull";
 
-const target = useTemplateRef<HTMLElement>("target");
+const target = ref<HTMLElement | null>(null);
 const { isEnabled, isFullscreen, error, toggle } = useScreenfull();
 </script>
 
@@ -61,9 +56,10 @@ require transient user activation and can reject a request even when `isEnabled.
 
 ```vue
 <script setup lang="ts">
-import { useTemplateRef } from "vue";
+import { ref } from "vue";
 import { useScreenfullTarget } from "vue-screenfull";
-const panel = useTemplateRef<HTMLElement>("panel");
+
+const panel = ref<HTMLElement | null>(null);
 const { request, isFullscreen } = useScreenfullTarget(panel);
 </script>
 <template>
@@ -85,8 +81,10 @@ const result = await toggle(target, { navigationUI: "hide" });
 if (!result.ok) console.warn(result.error.code, result.error.suggestion);
 ```
 
-For image content, pass the image template ref. For a video, pass an `HTMLVideoElement` ref.
-Some mobile browsers offer video-only fullscreen independently of arbitrary-element fullscreen.
+For image content, pass the image template ref. An `HTMLVideoElement` is also a valid target. If a
+video presentation needs custom controls, target a wrapper that contains both the video and those
+controls so they remain available in native or fallback fullscreen. Some mobile browsers offer
+browser-managed video fullscreen independently of arbitrary-element fullscreen.
 
 ## Exit Fullscreen
 
@@ -94,9 +92,9 @@ Some mobile browsers offer video-only fullscreen independently of arbitrary-elem
 <button type="button" @click="exit">Exit fullscreen</button>
 ```
 
-Always include a visible exit button, particularly when fallback is enabled. Escape often exits
-fullscreen, but its browser behavior cannot be overridden reliably. Native change events reflect
-exits initiated through the browser UI.
+Keep a visible exit button inside the fullscreen target, particularly when fallback is enabled.
+Escape often exits fullscreen, but its browser behavior cannot be overridden reliably. Native
+change events reflect exits initiated through the browser UI.
 
 ## Check Support
 
@@ -121,8 +119,8 @@ if (!result.ok) {
 }
 ```
 
-Errors distinguish unsupported/SSR environments, invalid or detached targets, user activation,
-permissions and iframe policy, pending transitions, native request/exit failures, and fallback
+Errors distinguish unsupported or SSR environments, invalid or detached targets, user activation,
+permissions, iframe policy, pending transitions, native request or exit failures, and fallback
 failures. `error` keeps the last error until `clearError()` is called.
 
 ## CSS Fallback
@@ -160,15 +158,17 @@ cleanup.
   v-slot="screenfull"
   @error="report"
 >
-  <button type="button" @click="screenfull.toggle()">
-    {{ screenfull.isFullscreen ? "Exit" : "Open article" }}
-  </button>
-  <button v-if="screenfull.isFullscreen" type="button" @click="screenfull.exit">Exit</button>
+  <article id="article">
+    <button type="button" @click="screenfull.toggle()">
+      {{ screenfull.isFullscreen.value ? "Exit" : "Open article" }}
+    </button>
+  </article>
 </Screenfull>
 ```
 
 The renderless component emits `change`, `enter`, `exit`, `error`, and `fallback`. Its default slot
-receives all composable refs and actions without imposing a visual system.
+receives all composable refs and actions without imposing a visual system. Because `screenfull` is a
+scoped-slot object, access its nested refs with `.value`.
 
 ## Directive Usage
 
@@ -467,8 +467,6 @@ so deployable website changes can be detected without precaching unversioned bun
 
 ## Development
 
-Node.js 22 is used in CI.
-
 ```bash
 npm install
 npm run typecheck

package/README.zh-CN.md

@@ -8,31 +8,28 @@
 [license-image]: https://img.shields.io/npm/l/vue-screenfull.svg
 [license-url]: https://github.com/chengchuu/vue-screenfull/blob/main/LICENSE
 
-专为 Vue 3 设计的响应式、强类型且支持 SSR 的全屏工具。
-还提供可选的 CSS 伪全屏回退方案。
+`vue-screenfull` 为 Vue 3 提供响应式、强类型的全屏控制。在服务端渲染
+(Server-Side Rendering，SSR) 期间也可以安全导入该软件包。原生任意元素全屏不可用时，可以启用
+CSS 伪全屏回退方案。
 
 - [项目网站](https://chengchuu.github.io/vue-screenfull/)
 - [在线演练场](https://chengchuu.github.io/vue-screenfull/playground/)
 - [API 文档](https://chengchuu.github.io/vue-screenfull/api/)
 
-## 功能特性
-
-- 响应式 Composition API 状态，支持自动清理作用域。
-- 检测标准 API。
-- 检测带 WebKit、Mozilla、Microsoft 前缀的 API。
-- 支持 Vue 模板引用、组件引用、元素和安全的 CSS 选择器。
-- 返回结构化结果和可操作的错误，不会静默忽略 Promise 拒绝。
-- 提供无渲染组件、指令、可选插件和框架无关的控制器。
-- 提供适用于 npm、浏览器原生模块和经典脚本的无 Vue 浏览器入口。
-- 提供 CJS、ESM、浏览器 IIFE、源映射和类型声明。
-
 ## 安装
 
+在 Vue 3.3 或更高版本的项目中安装软件包：
+
 ```bash
 npm install vue-screenfull
 ```
 
-浏览器包为 `lib/vue-screenfull.min.js`。它会暴露 `VUE_SCREENFULL`，并要求通过全局变量 `Vue` 访问 Vue。Vue 只在软件包安装层面标记为可选。通过软件包根入口导入 API 时，运行时仍需要 Vue 3。
+软件包根入口 `vue-screenfull` 提供 Vue 组合式函数、组件、指令和插件。该入口在运行时需要
+Vue 3。Vue 被标记为可选的对等依赖，因此只使用框架无关入口 `vue-screenfull/browser` 的项目
+无需安装 Vue。
+
+默认浏览器 IIFE 位于 `lib/vue-screenfull.min.js`。它会暴露 `VUE_SCREENFULL`，并要求通过全局
+变量 `Vue` 访问 Vue。
 
 ### 无 Vue 浏览器入口
 
@@ -113,10 +110,10 @@ async function dispose() {
 
 ```vue
 <script setup lang="ts">
-import { useTemplateRef } from "vue";
+import { ref } from "vue";
 import { useScreenfull } from "vue-screenfull";
 
-const target = useTemplateRef<HTMLElement>("target");
+const target = ref<HTMLElement | null>(null);
 const { isEnabled, isFullscreen, error, toggle } = useScreenfull();
 </script>
 
@@ -137,9 +134,10 @@ const { isEnabled, isFullscreen, error, toggle } = useScreenfull();
 
 ```vue
 <script setup lang="ts">
-import { useTemplateRef } from "vue";
+import { ref } from "vue";
 import { useScreenfullTarget } from "vue-screenfull";
-const panel = useTemplateRef<HTMLElement>("panel");
+
+const panel = ref<HTMLElement | null>(null);
 const { request, isFullscreen } = useScreenfullTarget(panel);
 </script>
 <template>
@@ -159,7 +157,9 @@ const result = await toggle(target, { navigationUI: "hide" });
 if (!result.ok) console.warn(result.error.code, result.error.suggestion);
 ```
 
-对于图片内容，请传入图片的模板引用。对于视频，请传入 `HTMLVideoElement` 引用。部分移动浏览器提供仅限视频的全屏功能，与任意元素全屏相互独立。
+对于图片内容，请传入图片的模板引用。`HTMLVideoElement` 也是有效目标。如果视频演示需要自定义
+控件，请将视频及其控件放入同一个容器，并将该容器设为目标。这样可以确保原生或回退全屏模式下
+仍能使用这些控件。部分移动浏览器提供由浏览器管理的视频全屏功能，该功能与任意元素全屏相互独立。
 
 ## 退出全屏
 
@@ -167,7 +167,7 @@ if (!result.ok) console.warn(result.error.code, result.error.suggestion);
 <button type="button" @click="exit">Exit fullscreen</button>
 ```
 
-请始终提供可见的退出按钮，启用回退方案时尤其如此。Escape 键通常可以退出，但无法可靠地覆盖浏览器的 Escape 键行为。通过浏览器界面发起的退出操作会由原生变更事件反映。
+请在全屏目标内保留可见的退出按钮，启用回退方案时尤其如此。Escape 键通常可以退出，但无法可靠地覆盖浏览器的 Escape 键行为。通过浏览器界面发起的退出操作会由原生变更事件反映。
 
 ## 检查支持情况
 
@@ -224,14 +224,17 @@ CSS 回退方案会将 `HTMLElement` 固定到可视视口。它会保留自身
   v-slot="screenfull"
   @error="report"
 >
-  <button type="button" @click="screenfull.toggle()">
-    {{ screenfull.isFullscreen ? "Exit" : "Open article" }}
-  </button>
-  <button v-if="screenfull.isFullscreen" type="button" @click="screenfull.exit">Exit</button>
+  <article id="article">
+    <button type="button" @click="screenfull.toggle()">
+      {{ screenfull.isFullscreen.value ? "Exit" : "Open article" }}
+    </button>
+  </article>
 </Screenfull>
 ```
 
-无渲染组件会触发 `change`、`enter`、`exit`、`error` 和 `fallback` 事件。其默认插槽接收组合式函数的所有引用和操作。组件不会施加任何视觉样式。
+无渲染组件会触发 `change`、`enter`、`exit`、`error` 和 `fallback` 事件。其默认插槽接收组合式
+函数的所有引用和操作。组件不会施加任何视觉样式。`screenfull` 是作用域插槽对象，因此需要使用
+`.value` 访问其中嵌套的 `ref`。
 
 ## 指令用法
 
@@ -404,8 +407,6 @@ Worker 更新仍由用户控制。有新版本等待更新时，选择 **立即
 
 ## 开发
 
-CI 使用 Node.js 22。
-
 ```bash
 npm install
 npm run typecheck

package/guides/MANUAL_TESTING.md

@@ -32,7 +32,7 @@ permission. Confirm errors are visible, focus returns after library-driven exit,
 inline styles/body scroll, navigation and app switching do not leave stale state, and an accessible
 exit remains keyboard/touch reachable.
 
-## iPhone Chrome video-wrapper check
+## iPhone Chrome video-card check
 
 This check requires a physical iPhone; desktop emulation and jsdom do not reproduce WebKit's native
 video and arbitrary-element fullscreen behavior reliably.
@@ -43,10 +43,10 @@ video and arbitrary-element fullscreen behavior reliably.
    element**, and **Document fullscreen element** from Diagnostics.
 4. Confirm **Exit video fullscreen** remains visible and touch-accessible in portrait and landscape,
    then use it to exit.
-5. Confirm focus returns to **View video fullscreen**, the wrapper's fallback styles are removed, body
+5. Confirm focus returns to **View video fullscreen**, the card's fallback styles are removed, body
    scrolling is restored, and the page, element, and image examples still work.
 
-If the request reports `fallback`, the controller element should be the video wrapper and the document
+If the request reports `fallback`, the controller element should be the video card and the document
 fullscreen element should be `none`. If it reports `native`, record both element fields and investigate
 WebKit-specific behavior separately before changing the shared controller.
 

package/lib/browser.cjs.js

@@ -1,5 +1,5 @@
 /*!
- * vue-screenfull v1.1.1
+ * vue-screenfull v1.1.2
  * (c) 2018-2026 Cheng https://www.npmjs.com/package/vue-screenfull
  * Released under the MIT License.
  */

package/lib/browser.esm.js

@@ -1,5 +1,5 @@
 /*!
- * vue-screenfull v1.1.1
+ * vue-screenfull v1.1.2
  * (c) 2018-2026 Cheng https://www.npmjs.com/package/vue-screenfull
  * Released under the MIT License.
  */

package/lib/browser.mjs

@@ -1,5 +1,5 @@
 /*!
- * vue-screenfull v1.1.1
+ * vue-screenfull v1.1.2
  * (c) 2018-2026 Cheng https://www.npmjs.com/package/vue-screenfull
  * Released under the MIT License.
  */

package/lib/index.cjs.js

@@ -1,5 +1,5 @@
 /*!
- * vue-screenfull v1.1.1
+ * vue-screenfull v1.1.2
  * (c) 2018-2026 Cheng https://www.npmjs.com/package/vue-screenfull
  * Released under the MIT License.
  */

package/lib/index.esm.js

@@ -1,5 +1,5 @@
 /*!
- * vue-screenfull v1.1.1
+ * vue-screenfull v1.1.2
  * (c) 2018-2026 Cheng https://www.npmjs.com/package/vue-screenfull
  * Released under the MIT License.
  */

package/lib/index.mjs

@@ -1,5 +1,5 @@
 /*!
- * vue-screenfull v1.1.1
+ * vue-screenfull v1.1.2
  * (c) 2018-2026 Cheng https://www.npmjs.com/package/vue-screenfull
  * Released under the MIT License.
  */

package/lib/vue-screenfull.browser.min.js

@@ -1,5 +1,5 @@
 /*!
- * vue-screenfull v1.1.1
+ * vue-screenfull v1.1.2
  * (c) 2018-2026 Cheng https://www.npmjs.com/package/vue-screenfull
  * Released under the MIT License.
  */

package/lib/vue-screenfull.min.js

@@ -1,5 +1,5 @@
 /*!
- * vue-screenfull v1.1.1
+ * vue-screenfull v1.1.2
  * (c) 2018-2026 Cheng https://www.npmjs.com/package/vue-screenfull
  * Released under the MIT License.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vue-screenfull",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Reactive, strongly typed, SSR-safe fullscreen utilities for Vue 3.",
   "main": "lib/index.cjs.js",
   "module": "lib/index.esm.js",