feat(files): knownFolders.externalDocuments for android ease of use (#9966)

packages/core/file-system/file-system-access.android.ts

@@ -224,6 +224,11 @@ export class FileSystemAccess implements IFileSystemAccess {
 
 		return dir.getAbsolutePath();
 	}
+	public getExternalDocumentsFolderPath(): string {
+		const dir = getApplicationContext().getExternalFilesDir(null);
+
+		return dir.getAbsolutePath();
+	}
 
 	public getLogicalRootPath(): string {
 		const dir = getApplicationContext().getFilesDir();

packages/core/file-system/file-system-access.d.ts

@@ -100,6 +100,12 @@ export interface IFileSystemAccess {
 	 */
 	getDocumentsFolderPath(): string;
 
+	/**
+	 * Gets the special documents folder on external storage.
+	 * As there is no external storage on iOS it is the same as getDocumentsFolderPath
+	 */
+	getExternalDocumentsFolderPath(): string;
+
 	/**
 	 * Gets the special temp folder.
 	 * Returns for Android: "/data/data/applicationPackageName/cache", iOS: "/var/mobile/Applications/appID/Library/Caches"

packages/core/file-system/file-system-access.ios.ts

@@ -248,6 +248,9 @@ export class FileSystemAccess {
 	public getDocumentsFolderPath(): string {
 		return this.getKnownPath(NSSearchPathDirectory.DocumentDirectory);
 	}
+	public getExternalDocumentsFolderPath(): string {
+		return this.getDocumentsFolderPath();
+	}
 
 	public getTempFolderPath(): string {
 		return this.getKnownPath(NSSearchPathDirectory.CachesDirectory);

packages/core/file-system/index.d.ts

@@ -217,6 +217,13 @@ export module knownFolders {
 	 */
 	export function documents(): Folder;
 
+	/**
+	 * Gets the Documents folder available for the current application on an external storage. This Folder is private for the application and not accessible from Users/External apps.
+	 * On android this requires READ_EXTERNAL_STORAGE/WRITE_EXTERNAL_STORAGE permissions
+	 * There is no external storage on iOS os it is the same as `documents()`
+	 */
+	export function externalDocuments(): Folder;
+
 	/**
 	 * Gets the Temporary (Caches) folder available for the current application. This Folder is private for the application and not accessible from Users/External apps.
 	 */

packages/core/file-system/index.ts

@@ -548,6 +548,7 @@ export class Folder extends FileSystemEntity {
 
 export namespace knownFolders {
 	let _documents: Folder;
+	let _externalDocuments: Folder;
 	let _temp: Folder;
 	let _app: Folder;
 
@@ -562,6 +563,17 @@ export namespace knownFolders {
 		return _documents;
 	}
 
+	export function externalDocuments(): Folder {
+		if (!_externalDocuments) {
+			const path = getFileAccess().getExternalDocumentsFolderPath();
+			_externalDocuments = new Folder();
+			_externalDocuments._path = path;
+			_externalDocuments._isKnown = true;
+		}
+
+		return _externalDocuments;
+	}
+
 	export function temp(): Folder {
 		if (!_temp) {
 			const path = getFileAccess().getTempFolderPath();