@ufjs/webview 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# @ufjs/webview
+
+## 0.1.3
+
+- First release. `<web-view>` is one tag: a platform WebView on the app
+  (`webview_flutter`) and an iframe on the web, with the same `src`, navigation
+  and message props on both. Version 0.1.3 to line up with the rest of the fjs
+  packages; nothing before it was published.
+- A `<web-view>` nested inside a `<scroll-view>` keeps its own gestures: the
+  page scrolls under the finger instead of the outer scroller stealing the
+  drag.
+- `src` accepts an app-owned page from the project's `html/` directory
+  (`/html/guide.html`), alongside http URLs and the `asset://` files a module
+  ships. Requires `@ufjs/cli` >= 0.1.3, which serves and bundles that
+  directory.
+- The module no longer writes a second copy of its files into the app's
+  `public/fjs-modules/`. `.fjs/modules/<name>/` is the only copy; the
+  `/fjs-modules/<name>/<file>` URL contract is unchanged.
+- The Flutter tests actually compile now — a missing
+  `package:flutter/gestures.dart` import meant `flutter test` reported the file
+  as a failed "loading …" and the suite had never run.
+
+## Requirements
+
+- `@ufjs/cli` >= 0.1.3 and `flutter_fjs` >= 0.1.3.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 flutter-js contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# @ufjs/webview
+
+把网页嵌进 fjs 页面：App 使用 Flutter WebView，Web 使用 iframe。
+
+## 安装
+
+```bash
+pnpm add @ufjs/webview
+```
+
+模块会被 fjs 自动发现和注册，不需要手动 import 组件或修改 Flutter host。
+
+## 用法
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+
+const lastMessage = ref('');
+
+function onMessage(payload: string) {
+  lastMessage.value = payload;
+}
+</script>
+
+<template>
+  <view class="page">
+    <web-view
+      class="frame"
+      src="https://example.com/terms"
+      @load="(payload) => console.log('loaded', payload)"
+      @error="(payload) => console.error('failed', payload)"
+      @message="onMessage"
+    />
+    <text>{{ lastMessage }}</text>
+  </view>
+</template>
+
+<style scoped>
+.page { flex-grow: 1; }
+.frame { flex-grow: 1; }
+</style>
+```
+
+`web-view` 是普通盒子，不会自动铺满页面，也不会覆盖兄弟节点。网页没有自然高度，
+请给它明确的 `height`、`flex-grow` 或其它有界父容器。
+
+## Props 和事件
+
+| 名称 | 说明 |
+|------|------|
+| `src` | `http://` / `https://` 外部页面，或 `asset://<path>` 模块自带页面 |
+| `@load` | 页面加载完成，载荷为 `{"src":"..."}` |
+| `@error` | 主文档加载失败，载荷为 `{"src":"...","errMsg":"web-view load failed"}` |
+| `@message` | 网页调用 `fjs.postMessage(string)`，载荷为 `{"data":"..."}` |
+
+事件载荷都是字符串。需要传对象时，在网页侧先使用 `JSON.stringify`。
+`src` 变化会开始新一轮加载，旧页面的事件不会回派。
+
+## 模块自带页面
+
+模块的 `public/` 文件会自动打包。页面使用 `asset://`，同一个地址会按目标解析：
+
+| 目标 | 实际位置 |
+|------|----------|
+| App dev | `http://<devHost>/modules/webview/<path>` |
+| App release | Flutter asset `assets/fjs/modules/webview/<path>` |
+| Web | `/fjs-modules/webview/<path>` |
+
+例如：
+
+```vue
+<web-view src="asset://demo.html?q=hello#top" style="height: 320px" />
+```
+
+release 会用不含 `?` / `#` 的路径查找 Flutter asset，再把 query 和 fragment 还原到
+页面 URL。因此页面初始脚本可以正常读取 `location.search` 和 `location.hash`，相对
+CSS、JS、图片也仍以该 HTML 的目录为基准。页面最终触发的 `@load` 仍使用完整的
+`src` 语义。
+
+## 网页与宿主通信
+
+App 中，WebView 会提供：
+
+```js
+fjs.postMessage('hello');
+```
+
+Web 的跨源 iframe 不能由宿主注入 `fjs`，网页需要自带一个 shim：
+
+```js
+window.fjs = window.fjs || {
+  postMessage: (data) => parent.postMessage({ __fjs: String(data) }, '*'),
+};
+```
+
+网页里的 JavaScript 世界与 fjs 页面互不相通；网页不能 import fjs natives，只能通过
+`fjs.postMessage` 发送字符串。

package/components/WebViewWeb.vue

@@ -0,0 +1,134 @@
+<script setup lang="ts">
+// Browser stand-in for the Flutter widget <web-view />. The build registers
+// it under that tag, so one template line is a WKWebView on a device and
+// this iframe in a browser.
+//
+// Two things are NOT the same as on the app, and both are the browser's
+// doing rather than something left undone (docs/web.md):
+//
+//   * a cross-origin iframe cannot be injected, so the loaded page brings
+//     its own `fjs.postMessage` shim (see public/demo.html) and talks to us
+//     through window.postMessage;
+//   * `error` on an iframe almost never fires. An HTTP 404 or 500 is a
+//     successful load of an error page, and network-level failures are
+//     silent. A page that needs to know it loaded should say so itself with
+//     fjs.postMessage('ready').
+import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue';
+import {
+  errorPayload,
+  LoadCycle,
+  loadPayload,
+  messagePayload,
+  resolveSrc,
+  classifySrc,
+  unsupportedSrcMessage,
+} from '../index';
+import type { FjsHtmlSrc } from '@ufjs/runtime';
+
+// FjsHtmlSrc, not string: the tag's type comes from this component's props
+// (the toolchain reads them through FjsWidgetProps), so this one line is
+// what makes <web-view src> complete the project's html/ pages on both
+// targets. It still accepts any string — http URLs and asset:// included.
+const props = defineProps<{ src?: FjsHtmlSrc }>();
+
+const emit = defineEmits<{
+  (e: 'load', payload: string): void;
+  (e: 'error', payload: string): void;
+  (e: 'message', payload: string): void;
+  (e: 'tap'): void;
+}>();
+
+const frame = ref<HTMLIFrameElement | null>(null);
+const cycle = new LoadCycle();
+/** The generation the currently rendered iframe belongs to. */
+const generation = ref(cycle.begin());
+
+const warned = new Set<string>();
+function warnOnce(key: string, message: string): void {
+  if (warned.has(key)) return;
+  warned.add(key);
+  console.warn(`[fjs] ${message}`);
+}
+
+/** The URL this iframe should carry, or undefined for "load nothing". */
+const url = computed(() => {
+  const raw = props.src ?? '';
+  const kind = classifySrc(raw);
+  if (kind === 'unsupported') {
+    warnOnce(`web-view-src:${raw}`, unsupportedSrcMessage(raw));
+    return undefined;
+  }
+  const resolved = resolveSrc(raw, { target: 'web' });
+  return resolved.kind === 'url' ? resolved.url : undefined;
+});
+
+// A new src is a new load: bump the generation so the old page's load,
+// error and messages are dropped instead of reported against the new URL.
+watch(
+  () => props.src,
+  () => {
+    generation.value = cycle.begin();
+  },
+);
+
+/** The element a result came from has to be the one on screen now.
+ *
+ * A src change replaces the iframe (it is keyed), but the OLD element stays
+ * alive long enough to finish loading, and its listener is this same
+ * closure. Without this check that stale finish would be reported — against
+ * the new URL, which is the one thing it certainly is not. */
+const isCurrent = (event: Event) => event.target === frame.value;
+
+const onLoad = (event: Event) => {
+  // An iframe with no src fires `load` for about:blank; that is not a page
+  // anybody asked for.
+  if (!url.value || !isCurrent(event)) return;
+  if (cycle.finish(generation.value)) emit('load', loadPayload(url.value));
+};
+
+const onError = (event: Event) => {
+  if (!url.value || !isCurrent(event)) return;
+  if (cycle.finish(generation.value)) emit('error', errorPayload(url.value));
+};
+
+/** Double filter. The window's message event is a party line: anything on
+ * the page can post to it, and other iframes get their own. A message is
+ * this web-view's only when it came from THIS frame's window and carries the
+ * shape the shim sends. Everything else is somebody else's traffic, so it is
+ * ignored silently — it is not an error. */
+function onWindowMessage(event: MessageEvent): void {
+  const element = frame.value;
+  if (!element || event.source !== element.contentWindow) return;
+  const data = event.data as { __fjs?: unknown } | null;
+  if (!data || typeof data !== 'object' || typeof data.__fjs !== 'string') return;
+  if (!cycle.accepts(generation.value)) return;
+  emit('message', messagePayload(data.__fjs));
+}
+
+onMounted(() => window.addEventListener('message', onWindowMessage));
+onBeforeUnmount(() => window.removeEventListener('message', onWindowMessage));
+</script>
+
+<template>
+  <iframe
+    ref="frame"
+    class="fjs-web-view"
+    :src="url"
+    :key="generation"
+    @load="onLoad"
+    @error="onError"
+    @click="emit('tap')"
+  />
+</template>
+
+<style>
+/* The box is the page's; the content is the loaded page's. Same as the app
+   side, which draws no chrome of its own either. */
+.fjs-web-view {
+  border: 0;
+  display: block;
+  width: 100%;
+  height: 100%;
+  background: transparent;
+}
+</style>

package/flutter/.dart_tool/flutter_build/dart_plugin_registrant.dart

@@ -0,0 +1,132 @@
+//
+// Generated file. Do not edit.
+// This file is generated from template in file `flutter_tools/lib/src/flutter_plugins.dart`.
+//
+
+// @dart = 3.5
+
+import 'dart:io'; // flutter_ignore: dart_io_import.
+import 'package:path_provider_android/path_provider_android.dart';
+import 'package:sqflite_android/sqflite_android.dart';
+import 'package:webview_flutter_android/webview_flutter_android.dart';
+import 'package:path_provider_foundation/path_provider_foundation.dart';
+import 'package:sqflite_darwin/sqflite_darwin.dart';
+import 'package:webview_flutter_wkwebview/webview_flutter_wkwebview.dart';
+import 'package:path_provider_linux/path_provider_linux.dart';
+import 'package:path_provider_foundation/path_provider_foundation.dart';
+import 'package:sqflite_darwin/sqflite_darwin.dart';
+import 'package:webview_flutter_wkwebview/webview_flutter_wkwebview.dart';
+import 'package:path_provider_windows/path_provider_windows.dart';
+
+@pragma('vm:entry-point')
+class _PluginRegistrant {
+
+  @pragma('vm:entry-point')
+  static void register() {
+    if (Platform.isAndroid) {
+      try {
+        PathProviderAndroid.registerWith();
+      } catch (err) {
+        print(
+          '`path_provider_android` threw an error: $err. '
+          'The app may not function as expected until you remove this plugin from pubspec.yaml'
+        );
+      }
+
+      try {
+        SqfliteAndroid.registerWith();
+      } catch (err) {
+        print(
+          '`sqflite_android` threw an error: $err. '
+          'The app may not function as expected until you remove this plugin from pubspec.yaml'
+        );
+      }
+
+      try {
+        AndroidWebViewPlatform.registerWith();
+      } catch (err) {
+        print(
+          '`webview_flutter_android` threw an error: $err. '
+          'The app may not function as expected until you remove this plugin from pubspec.yaml'
+        );
+      }
+
+    } else if (Platform.isIOS) {
+      try {
+        PathProviderFoundation.registerWith();
+      } catch (err) {
+        print(
+          '`path_provider_foundation` threw an error: $err. '
+          'The app may not function as expected until you remove this plugin from pubspec.yaml'
+        );
+      }
+
+      try {
+        SqfliteDarwin.registerWith();
+      } catch (err) {
+        print(
+          '`sqflite_darwin` threw an error: $err. '
+          'The app may not function as expected until you remove this plugin from pubspec.yaml'
+        );
+      }
+
+      try {
+        WebKitWebViewPlatform.registerWith();
+      } catch (err) {
+        print(
+          '`webview_flutter_wkwebview` threw an error: $err. '
+          'The app may not function as expected until you remove this plugin from pubspec.yaml'
+        );
+      }
+
+    } else if (Platform.isLinux) {
+      try {
+        PathProviderLinux.registerWith();
+      } catch (err) {
+        print(
+          '`path_provider_linux` threw an error: $err. '
+          'The app may not function as expected until you remove this plugin from pubspec.yaml'
+        );
+      }
+
+    } else if (Platform.isMacOS) {
+      try {
+        PathProviderFoundation.registerWith();
+      } catch (err) {
+        print(
+          '`path_provider_foundation` threw an error: $err. '
+          'The app may not function as expected until you remove this plugin from pubspec.yaml'
+        );
+      }
+
+      try {
+        SqfliteDarwin.registerWith();
+      } catch (err) {
+        print(
+          '`sqflite_darwin` threw an error: $err. '
+          'The app may not function as expected until you remove this plugin from pubspec.yaml'
+        );
+      }
+
+      try {
+        WebKitWebViewPlatform.registerWith();
+      } catch (err) {
+        print(
+          '`webview_flutter_wkwebview` threw an error: $err. '
+          'The app may not function as expected until you remove this plugin from pubspec.yaml'
+        );
+      }
+
+    } else if (Platform.isWindows) {
+      try {
+        PathProviderWindows.registerWith();
+      } catch (err) {
+        print(
+          '`path_provider_windows` threw an error: $err. '
+          'The app may not function as expected until you remove this plugin from pubspec.yaml'
+        );
+      }
+
+    }
+  }
+}