[cross_file] Updates cross_file to a package separated federated plugin

.ci/scripts/prepare_tool.sh

@@ -8,6 +8,9 @@ set -e
 git fetch origin main
 git branch main origin/main
 
+# Enables long paths to work on Windows.
+git config --global core.longpaths true
+
 cd script/tool
 dart pub get
 

.github/dependabot.yml

@@ -3,7 +3,7 @@
 
 version: 2
 updates:
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
       interval: "weekly"
@@ -23,12 +23,14 @@
         update-types: ["version-update:semver-patch"]
 
   # Android example apps.
   - package-ecosystem: "gradle"
     directories:
       - /packages/animations/example/android/app
       - /packages/camera/camera_android/example/android/app
       - /packages/camera/camera_android_camerax/example/android/app
       - /packages/camera/camera/example/android/app
+      - /packages/cross_file/cross_file/example/android/app
+      - /packages/cross_file/cross_file_android/example/android/app
       - /packages/espresso/example/android/app
       - /packages/extension_google_sign_in_as_googleapis_auth/example/android/app
       - /packages/file_selector/file_selector/example/android/app
@@ -80,10 +82,11 @@
         update-types: ["version-update:semver-minor", "version-update:semver-patch"]
 
   # Android packages (excluding example apps).
   - package-ecosystem: "gradle"
     directories:
       - /packages/camera/camera_android/android
       - /packages/camera/camera_android_camerax/android
+      - /packages/cross_file/cross_file_android/android
       - /packages/espresso/android
       - /packages/file_selector/file_selector_android/android
       - /packages/flutter_plugin_android_lifecycle/android

packages/cross_file/CHANGELOG.md → packages/cross_file/cross_file/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 0.4.0
+
+* Updates `cross_file` to a package-separated federated plugin.
+* Adds `XDirectory` to access file containers.
+* Adds implementation for file systems. See `FileSystemXFile` and `FileSystemXDirectory`.
+* Adds implementation for scoped storage APIs that use ephemeral URLS. See `ScopedStorageXFile`
+  and `ScopedStorageXDirectory`.
+* **Breaking Change** Replaces `XFile(String path)` with `XFile.fileSystem({required String path})`
+  or `FileSystem(String path)`.
+* **Breaking Change** Removes `XFile.fromData`. `XFile`s can no longer be instantiated with a
+  `Uint8List`. For web, see README for an example to create one from a `Blob`/`File`.
+* **Breaking Change** Removes `XFile.saveTo()`. `FileSystemXFile.writeAsBytes` has been added
+  and the web implementation can use `WebScopedStorageXFileExtension.download`. See README to see
+  how to access platform-specific feature.
+* **Breaking Change** Removes `XFile.mimeType`.
+* **Breaking Change** Removes `XFile.path`. This has been replaced by `FileSystemXFile.path`.
+* **Breaking Change** Changes `XFile.name` to return `Future<String>` rather than `String`.
+
 ## 0.3.5+4
 
 * Adds a runnable `main` entry point and an additional `XFile.fromData`

packages/cross_file/cross_file/README.md

@@ -0,0 +1,108 @@
+# cross_file
+
+An abstraction to allow working with files across multiple platforms.
+
+<?code-excerpt path-base="example/lib"?>
+
+[![pub package](https://img.shields.io/pub/v/cross_file.svg)](https://pub.dartlang.org/packages/cross_file)
+
+|             | Android | iOS     | Linux | macOS  | Web | Windows     |
+|-------------|---------|---------|-------|--------|-----|-------------|
+| **Support** | SDK 24+ | iOS 13+ | Any   | 10.15+ | Any | Windows 10+ |
+
+## Usage
+
+Instantiate a `XFile` using a uri or path and use its methods and properties to access the file and
+its metadata.
+
+Example:
+
+<?code-excerpt "readme_excerpts.dart (Instantiate)"?>
+```dart
+final file = XFile.fileSystem(path: 'assets/hello.txt');
+
+debugPrint('File information:');
+debugPrint('- URI: ${file.uri}');
+debugPrint('- Name: ${await file.name()}');
+
+if (await file.exists()) {
+  final String fileContent = await file.readAsString();
+  debugPrint('Content of the file: $fileContent');
+}
+```
+
+You can find links to the API docs on the [pub page](https://pub.dev/packages/cross_file).
+
+### Implementation-Specific Features
+
+Classes in this package contain an underlying platform implementation that provides features that
+are specific to an implementation.
+
+To access implementation-specific features, start by adding the platform implementation packages to
+your app or package:
+
+* **dart:io** [cross_file_io](https://pub.dev/packages/cross_file_io/install)
+* **Android Scoped Storage**: [cross_file_android](https://pub.dev/packages/cross_file_android/install)
+* **iOS/macOS App Sandbox**: [cross_file_darwin](https://pub.dev/packages/cross_file_darwin/install)
+* **Web**: [cross_file_web](https://pub.dev/packages/cross_file_web/install)
+
+Next, add the imports of the implementation packages to your app or package:
+
+<?code-excerpt "readme_excerpts.dart (platform_imports)"?>
+```dart
+// Import for Darwin App Sandbox features.
+import 'package:cross_file_darwin/cross_file_darwin.dart';
+// Import for Web features.
+import 'package:cross_file_web/cross_file_web.dart';
+```
+
+Now, additional features can be accessed through the platform implementations. Classes
+[FileSystemXFile], [FileSystemXDirectory], [ScopedStorageXFile], and [ScopedStorageXDirectory] pass
+their functionality to a class provided by the current platform. Below are a couple of ways to
+access additional functionality provided by the platform and is followed by an example.
+
+1. Pass a creation params class provided by a platform implementation to a `fromCreationParams`
+   constructor (e.g. `XFile.fromCreationParams`, `XDirectory.fromCreationParams`, etc.).
+2. Call methods on an implementation of a class by using `getExtension` method (e.g.
+   `XFile.getExtension`, `XDirectory.getExtension`, etc.).
+
+Below is an example of using additional iOS/macOS and Web features for a `XFile`.
+
+<?code-excerpt "readme_excerpts.dart (platform_features)"?>
+```dart
+late final XFile file;
+
+switch (CrossFile.implementation) {
+  case CrossFileWeb():
+    final params = WebScopedStorageXFileCreationParams.fromObjectUrl(
+      objectUrl: 'blob:https://some/url:for/file',
+    );
+    file = ScopedStorageXFile.fromCreationParams(params);
+  case CrossFileDarwin():
+    file = ScopedStorageXFile.fromUri(Uri.file('/my/file.txt'));
+  default:
+    file = XFile.fileSystem(path: '/my/file.txt');
+}
+
+await file
+    .getExtension<SecurityScopedDarwinScopedStorageXFileExtension>()
+    ?.startAccessingSecurityScopedResource();
+
+debugPrint(await file.readAsString());
+
+await file
+    .getExtension<SecurityScopedDarwinScopedStorageXFileExtension>()
+    ?.stopAccessingSecurityScopedResource();
+```
+
+See https://pub.dev/documentation/cross_file_darwin/latest/cross_file_darwin/cross_file_darwin-library.html
+for more details on iOS/macOS App Sandbox features.
+
+See https://pub.dev/documentation/cross_file_android/latest/cross_file_android/cross_file_android-library.html
+for more details on Android Scoped Storage features.
+
+See https://pub.dev/documentation/cross_file_io/latest/cross_file_io/cross_file_io-library.html
+for more details on `dart:io` features.
+
+See https://pub.dev/documentation/cross_file_web/latest/cross_file_web/cross_file_web-library.html
+for more details on Web features.

packages/cross_file/cross_file/example/README.md

@@ -0,0 +1,3 @@
+# cross_file_example
+
+Demonstrates how to use the cross_file plugin.

packages/cross_file/cross_file/example/android/app/build.gradle.kts

@@ -0,0 +1,50 @@
+plugins {
+    id("com.android.application")
+    id("dev.flutter.flutter-gradle-plugin")
+}
+
+android {
+    namespace = "dev.flutter.packages.crossfileexample"
+    compileSdk = flutter.compileSdkVersion
+    ndkVersion = flutter.ndkVersion
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    defaultConfig {
+        applicationId = "dev.flutter.packages.crossfileexample"
+        minSdk = flutter.minSdkVersion
+        targetSdk = flutter.targetSdkVersion
+        versionCode = flutter.versionCode
+        versionName = flutter.versionName
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+    }
+
+    buildTypes {
+        release {
+            signingConfig = signingConfigs.getByName("debug")
+        }
+    }
+    lint {
+        disable.add("InvalidPackage")
+    }
+}
+
+kotlin {
+    compilerOptions {
+        jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17
+    }
+}
+
+flutter {
+    source = "../.."
+}
+
+dependencies {
+    testImplementation("junit:junit:4.13.2")
+    androidTestImplementation("androidx.test:runner:1.2.0")
+    androidTestImplementation("androidx.test.espresso:espresso-core:3.2.0")
+    api("androidx.test:core:1.4.0")
+}

packages/cross_file/cross_file/example/android/app/src/androidTest/kotlin/dev/flutter/packages/crossfileexample/MainActivityTest.kt

@@ -0,0 +1,17 @@
+// Copyright 2013 The Flutter Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+package dev.flutter.packages.crossfileexample
+
+import androidx.test.rule.ActivityTestRule
+import dev.flutter.plugins.integration_test.FlutterTestRunner
+import io.flutter.plugins.DartIntegrationTest
+import org.junit.Rule
+import org.junit.runner.RunWith
+
+@DartIntegrationTest
+@RunWith(FlutterTestRunner::class)
+class MainActivityTest {
+  @JvmField @Rule var rule = ActivityTestRule(MainActivity::class.java)
+}

packages/cross_file/cross_file/example/android/app/src/debug/AndroidManifest.xml

@@ -0,0 +1,20 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <!-- The INTERNET permission is required for development. Specifically,
+         the Flutter tool needs it to communicate with the running application
+         to allow setting breakpoints, to provide hot reload, etc.
+    -->
+    <uses-permission android:name="android.permission.INTERNET"/>
+    <application android:usesCleartextTraffic="true">
+        <activity
+            android:name="dev.flutter.packages.crossfileexample.DriverExtensionActivity"
+            android:launchMode="singleTop"
+            android:theme="@style/LaunchTheme"
+            android:configChanges="orientation|keyboardHidden|keyboard|screenSize|smallestScreenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
+            android:hardwareAccelerated="true"
+            android:windowSoftInputMode="adjustResize">
+            <meta-data
+                android:name="io.flutter.Entrypoint"
+                android:value="integrationTestMain" />
+        </activity>
+    </application>
+</manifest>

packages/cross_file/cross_file/example/android/app/src/main/AndroidManifest.xml

@@ -0,0 +1,45 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <application
+        android:label="cross_file_example"
+        android:name="${applicationName}"
+        android:icon="@mipmap/ic_launcher">
+        <activity
+            android:name=".MainActivity"
+            android:exported="true"
+            android:launchMode="singleTop"
+            android:taskAffinity=""
+            android:theme="@style/LaunchTheme"
+            android:configChanges="orientation|keyboardHidden|keyboard|screenSize|smallestScreenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
+            android:hardwareAccelerated="true"
+            android:windowSoftInputMode="adjustResize">
+            <!-- Specifies an Android theme to apply to this Activity as soon as
+                 the Android process has started. This theme is visible to the user
+                 while the Flutter UI initializes. After that, this theme continues
+                 to determine the Window background behind the Flutter UI. -->
+            <meta-data
+              android:name="io.flutter.embedding.android.NormalTheme"
+              android:resource="@style/NormalTheme"
+              />
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN"/>
+                <category android:name="android.intent.category.LAUNCHER"/>
+            </intent-filter>
+        </activity>
+        <!-- Don't delete the meta-data below.
+             This is used by the Flutter tool to generate GeneratedPluginRegistrant.java -->
+        <meta-data
+            android:name="flutterEmbedding"
+            android:value="2" />
+    </application>
+    <!-- Required to query activities that can process text, see:
+         https://developer.android.com/training/package-visibility and
+         https://developer.android.com/reference/android/content/Intent#ACTION_PROCESS_TEXT.
+
+         In particular, this is used by the Flutter engine in io.flutter.plugin.text.ProcessTextPlugin. -->
+    <queries>
+        <intent>
+            <action android:name="android.intent.action.PROCESS_TEXT"/>
+            <data android:mimeType="text/plain"/>
+        </intent>
+    </queries>
+</manifest>

packages/cross_file/cross_file/example/android/app/src/main/kotlin/dev/flutter/packages/crossfileexample/DriverExtensionActivity.kt

@@ -0,0 +1,10 @@
+// Copyright 2013 The Flutter Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+package dev.flutter.packages.crossfileexample
+
+import io.flutter.embedding.android.FlutterActivity
+
+/** Test Activity that sets the name of the Dart method entrypoint in the manifest. */
+class DriverExtensionActivity : FlutterActivity()

packages/cross_file/cross_file/example/android/app/src/main/kotlin/dev/flutter/packages/crossfileexample/MainActivity.kt

@@ -0,0 +1,9 @@
+// Copyright 2013 The Flutter Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+package dev.flutter.packages.crossfileexample
+
+import io.flutter.embedding.android.FlutterActivity
+
+class MainActivity : FlutterActivity()