cross-compatibilty +|Unit Testability|:white_check_mark:|:x:3|:question: + +1Cordova & CapacitorJS supports binary via Base64 encoding whereas Fuse +has native binary support. + +2Cordova has limited support for distributing plugins as native modules due to their usage of looking up symbols by string. It's not known if CapacitorJS has the same restriction. + +3Cordova has an internal `paramedic` tool for unit testing plugins, but plugin projects are typically not housed in a real native project and do not have access to native test tools. It's not known if CapacitorJS have the same limitations. Fuse has access to native test tools as well as your choice of a JS test runner. + +4CapacitorJS has a community-driven Electron platform. + +## Architecture + +The architecture of the Fuse framework consists of primarily two layers: Native and Webview side, glued by a HTTP protocol API with plugin support to extend functionality where needed. + +For iOS, web content is served using the [WKURLSchemeHandler](https://developer.apple.com/documentation/webkit/wkurlschemehandler?language=objc) which powers the DOM requests for your web assets. + +For Android, the [WebViewAssetLoader](https://developer.android.com/reference/androidx/webkit/WebViewAssetLoader) powers the DOM requests for your web assets. + +Due to limitations on both platforms, an embedded HTTP server is used to power an HTTP API. The web environment doesn't have a direct communication link to the native environment, and the existing APIs to transfer data in and out of the environment is incredibly slow. The embedded HTTP server serves that socket gap with the capability of sending large amounts of data, including binary data very efficiently. + +Android lacks the [feature](https://issuetracker.google.com/issues/119844519) to intercept and read HTTP content bodies making it unsuitable for an API since data cannot be passed to native. iOS doesn't support sending binary data over non-https protocols, and the scheme must use a custom, non-standard protocol as the scheme, making it unsuitable for the API since it will Base64 encoding of binary data, which is the primarily bottleneck of the typical JS bridge API. + +
+ 
+
+
+
+The key value of using an HTTP based API over the traditional [WKUserContentController](https://developer.apple.com/documentation/webkit/wkusercontentcontroller)/[JavascriptInterface](https://developer.android.com/reference/android/webkit/JavascriptInterface) APIs is speed.
+These APIs only supports strings well and with no stream interface, it's hard to send larger datasets, especially binary data in an efficient manner. The HTTP-based API allows you to send strings, but also allows you to stream binary data, as binary data if required.
+
+For example, if you need to fetch a large file, it can be sent to the WebView as an [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) or [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob), and those APIs can be sent as is back to native via the HTTP API. No need to base64 encode into an immutable string to send it across an IPC bridge for to be parsed back into raw binary.
+
+In our testing, a Cordova app with the file plugin installed using the traditional native bridge API can send a 100mb data file to the webview in approximately 2,000ms. With the HTTP API approach, that same 100mb data file can be sent to the webview in approximately 100ms. That's about a 20x improvement on performance.
+
+### API Server Security
+
+The embedded API server is secured in several ways.
+
+#### Security by Obscurity
+
+The first layer is done by obscurity. The API server is only listened on localhost, on a random available port. This is a requirement to avoid conflicts with potentially other apps running the Fuse framework, as well as making it more difficult for the API server to be discovered or probed.
+
+The application itself contains an API to find the current port.
+
+#### Secret Tokens
+
+The API server will generate a crytographic token which must be present when making API requests. The application itself contains an API to get this token. If the token is not present or correct, the embedded API server will refuse to accept any connections.
+
+#### TLS Enabled
+
+The API Server has TLS enabled using a self-signed certificate and private key generated during application launch. The embedded WebView will trust the certificate that was signed by its own private key.
+
+The generated keypair for TLS is never stored permanently and is used only for the lifetime of the application. On every application launch, a new keypair is generated. While self-signed certificates don't have a trusted CA, this specific self-signed certificates can be trusted since the application itself is the entity that created them. The embedded webview will test and assert the certificate was signed by its current generated private key. This gives the application some confidence that HTTPS is at least encrypting data securely for transit.
+
+Enabling TLS even on localhost connections allows the application to send data from the webview to the API server and vice versa securely, without third-party snooping on the network interfaces.
+
+The embedded API server is a closed system intended for a single client, which is your own application. This is how we can assert trust on a self-signed certificate since the application itself acts as the CA.
+
+#### The Web Environment
+
+The Fuse framework for the most part is rather unopinionated about your web assets. Simply drop in your HTML, css and JS and it can load them up. It does make few assumptions:
+
+1. The `/assets/` path is a reserved path for serving your assets. This path will lead to your app's root asset directory.
+2. The `/api/` path is reserved for plugin endpoints.
+
+URL fragment design in general are reserved by the Fuse framework.
+
+Additionally if you want to make use of the Fuse API and use Fuse plugins, you'll need to import `@btfuse/core` which is an unbundled JS module.
+It would be recommended to incorporate a module bundle that can take NPM modules and bundle them (either in a single file, or a chunked fashion). See the test app for a [webpack configuration example](https://github.com/btfuse/fuse-test-app).
+
+## License
+
+Copyright 2023-2024 Breautek
+
+Licensed under the Apache License, Version 2.0 (the "License");
+
+For full details, see http://www.apache.org/licenses/LICENSE-2.0
diff --git a/docs/docs/plugin-development/android-module.md b/docs/docs/plugin-development/android-module.md
new file mode 100644
index 0000000..28bad39
--- /dev/null
+++ b/docs/docs/plugin-development/android-module.md
@@ -0,0 +1,546 @@
+
+# Android Module
+
+This guide assumes you've already read and followed [Fuse JS Module](js-module.md). If not,
+we strongly recommend beginning there first before proceeding.
+
+A Fuse android module is an Android implementation of a plugin. They serve the
+purpose of handling requests by the webview via the API server and doing an action
+on behalf of the webview.
+
+
+
+ 
+
+
+
+Before we dive into creating an Android project we will discuss a few Fuse topics.
+
+A `FuseContext` is a state holding object that holds a reference to all `FusePlugin` instances as well as the `FuseAPIServer` and `FuseAPIRouter`. When the webview makes a request to the API server, the message will be routed to the appropriate `FusePlugin` via `FuseAPIRouter`.
+
+The plugin may have 0 to many APIHandler's attached to respond to these requests. If invoked, it is then the responsibility of the APIHandler to use the given `FuseAPIResponse` object to respond to the request.
+
+NOTE: Requests has no timeouts, but a request should be responded in a timely manner as the webview will limit active requests to about 6 concurrent requests. If this limit is reached, the browser will start but block requests until an active request has been closed.
+
+## Creating the Android project.
+
+Following along the [Getting Started](getting-started.md) guide, you should already have a `android` directory. If not, then create one now.
+
+Open up Android Studio and create a new `Empty Views Activity` Android Project.
+
+
+
+ 
+
+
+
+Choose an acceptable name and package. Make sure to set the `Save Location` to the `android/` directory.
+
+This guide will use Java, but feel free to use Kotlin if you're experienced.
+
+Currently the Fuse framework uses a Minimum SDK of 24, therefore it's best that your plugin matches. However it is valid to choose a higher minimum SDK if necessary.
+
+
+
+ 
+
+
+
+Click `Finish` and let Android Studio do it's thing syncing with Gradle and such.
+This will provide you a new project with a single `app` module, which can serve as your test application.
+
+Once Android Studio is synced with Gradle, we'll need to create a new `Android Library Module`, which for your plugin.
+
+Right click the Project Navigator and click `New` -> `Module`.
+
+
+
+ 
+
+
+
+This is personal preference but I like to keep the `app` module and the library module separate, so when supplying the `Module name` remove the `:app` prefix. This will make Android Studio place the module at the root level.
+
+Your project window should look something like:
+
+
+
+ 
+
+
+
+## Adding the Fuse dependency
+
+The Fuse framework can be synced via maven and is available via https://archiva.breautek.com
+
+First we'll need to add this maven repo. Edit the `settings.gradle.kts` file.
+Inside the `dependencyResolutionManagement.repositories` block add:
+
+``` kotlin
+maven {
+ url = uri("https://archiva.breautek.com/repository/breautek")
+}
+```
+
+The full file should now look like:
+
+``` kotlin linenums="1" title="settings.gradle.kts"
+pluginManagement {
+ repositories {
+ google()
+ mavenCentral()
+ gradlePluginPortal()
+ }
+}
+
+dependencyResolutionManagement {
+ repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+ repositories {
+ google()
+ mavenCentral()
+
+ maven {
+ url = uri("https://archiva.breautek.com/repository/breautek")
+ }
+ }
+}
+
+rootProject.name = "EchoPlugin"
+include(":app")
+include(":EchoPlugin")
+```
+
+This will allow us to pull and add fuse dependencies to our modules.
+
+Let's open `EchoPlugin`'s `build.gradle.kts` and add our dependency now.
+Inside the `dependencies` block add:
+
+``` kotlin
+compileOnly("com.breautek.fuse:core:0.7.1")
+```
+
+TIP: Check out [Breautek's Archiva](https://archiva.breautek.com/#artifact/com.breautek.fuse/core) for the latest available version.
+
+NOTE: We are using `compileOnly` because we only need the artefact to compile and test. It is the application's responsibility to provide the framework via a `implementation` dependency.
+
+NOTE: We can (and should) use an exact version pin, because unlike NodeJS modules Android doesn't have a true concept of peer dependencies but using `compileOnly` / `implementation` acheives a similar effect. However, it does not enforce a particular version range on the application.
+
+The full dependency blocks will look something like:
+
+``` kotlin
+dependencies {
+ compileOnly("com.breautek.fuse:core:0.7.1")
+ implementation("androidx.appcompat:appcompat:1.6.1")
+ implementation("com.google.android.material:material:1.10.0")
+ testImplementation("junit:junit:4.13.2")
+ androidTestImplementation("androidx.test.ext:junit:1.1.5")
+ androidTestImplementation("androidx.test.espresso:espresso-core:3.5.1")
+}
+```
+
+## Implementing the EchoPlugin
+
+Now we are ready to write some code. Let's create a new class `EchoPlugin`:
+
+``` java linenums="1" title="EchoPlugin.java"
+package com.example.fuse.echoplugin;
+
+import java.io.IOException;
+
+import com.breautek.fuse.FuseAPIPacket;
+import com.breautek.fuse.FuseAPIResponse;
+import com.breautek.fuse.FuseContext;
+import com.breautek.fuse.FusePlugin;
+
+public class EchoPlugin extends FusePlugin {
+ public EchoPlugin(FuseContext context) {
+ super(context);
+ }
+
+ @Override
+ public String getID() {
+ return "EchoPlugin";
+ }
+
+ @Override
+ protected void _initHandles() {
+ this.attachHandler("/echo", new APIHandler
+
+ 
+
+
+
+And add the following code:
+
+``` java linenums="1" title="EchoPluginTest.java"
+package com.example.fuse.echoplugin.test;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertTrue;
+
+import androidx.test.ext.junit.rules.ActivityScenarioRule;
+import androidx.test.ext.junit.runners.AndroidJUnit4;
+
+import org.junit.AfterClass;
+import org.junit.BeforeClass;
+import org.junit.Rule;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+
+import com.breautek.fuse.test.FuseTestAPIClient;
+
+@RunWith(AndroidJUnit4.class)
+public class EchoPluginTest {
+
+ @Rule
+ public ActivityScenarioRule
+
+ 
+
+
+
+Then click on the `+` icon to add a new configuration and select `Android Instrumented Tests`.
+
+Optionally you can give the configuration a new name. The default name is `All Tests`.
+
+Select the `EchoPlugin.EchoPlugin.androidTest` module then click `OK`.
+
+Now the `Run Configuration` will be set to `All Tests`. When you run this configuration, the unit tests will build and run against the selected device.
+
+
+
+ 
+
+
+
+If your tests passes, conguratulations! You have successfully created an android module that is capable of listening and responding to API calls from the webview!
+
+Alternatively you can run the tests via Gradle from command line:
+
+Unix: `./gradlew connectedAndroidTest`
+
+Windows: `./gradlew.bat connectedAndroidTest`
+
+## Creating a Test App
+
+TBD
+
+Meanwhile, most of [User Guide](../user-guide/getting-started.md) applies.
diff --git a/docs/docs/plugin-development/getting-started.md b/docs/docs/plugin-development/getting-started.md
new file mode 100644
index 0000000..5e5a118
--- /dev/null
+++ b/docs/docs/plugin-development/getting-started.md
@@ -0,0 +1,139 @@
+
+# Getting Started
+
+Fuse Framework provides a protocol for extending the behaviour of the webview. The protocol allows the JS in the webview to make calls over to the native environment via an embedded API server.
+
+This guide is in 4 parts:
+
+- Prerequisites (We are here!)
+- JS Modules
+- Android Modules
+- iOS Modules
+
+Naturally, if a module is for a specific platform, then an implementation for that platform can be omitted.
+
+## Plugin Architecture
+
+Let's take a look at a overview diagram.
+
+
+
+ 
+
+
+
+An application is split between two environments: 1) The Native platform and 2) The webview.
+
+On the Native platform side, we have a `FuseContext` class created by the application, which holds all the states including active `FusePlugin` instances. An `API Server` receives messages from the webview, and uses a `FuseAPIRouter` to dispatch those messages to the appropriate `FusePlugin`. A `FusePlugin` implements API handlers to handle the request, perform work using native device APIs and may respond back to the webview.
+
+On the webview side, share some "sister" objects. There is a `FuseContext` who serves a similar role to the native's `FuseContext`, but it holds the state on the webview. It also maintains a reference of all active `FusePlugin` instances created on the webview side. A `FusePlugin` may implement public APIs usable by the application in which calls on the `FuseAPI` which dispatches to the native's `API Server`.
+
+If this doesn't make much sense right now, don't fret. We will dig into more details later.
+
+### Plugin Identifiers
+
+A plugin has an identifier which is provided by a concrete implementation.
+The ID shall be constant and unique, and should be replicated in the Android and iOS framework code. It is a glue piece that ties your JS module to the native code.
+
+The ID must be unique to not clash with other plugins, so choose a descriptive name that represents your plugin. It's a good idea to prefix with your company name, or the initials of your company name, or a reverse domain.
+
+NOTE: Breautek reserves the prefixes `Fuse`, `BT`, and `BTFuse`.
+
+NOTE: The ID is used inside a HTTP URL, therefore choose URL safe characters.
+
+Let's assume your company is `Super Example Incorporated` then
+
+Good examples include (but not limited to):
+
+- `SuperExampleEcho`
+- `SEIEcho`
+- `SEI_Echo`
+- `SEI-Echo`
+- `com.superexample.echo`
+
+Bad examples includes (but not limited to):
+
+- `Echo` (too generic)
+- `FuseEcho` (Using a reserved prefix)
+- `ApacheEcho` (Using a prefix that is likely used by another corporation)
+- `BTEcho` (Another reserved prefix)
+
+## Plugin Directory Structure
+
+While there is nothing that requires this structure, this guide will recommend and assume the following directory structure:
+
+```
+.
+├── android/
+├── ios/
+├── src/
+└── spec/
+```
+
+|directory|purpose|
+|---|---|
+|`android/`|The directory that contains the android project.|
+|`ios/`|The directory that contains the ios project.|
+|`src/`|The directory that contains the JS project.|
+|`spec/`|The directory that contains JS test code.|
+
+Additional files and directories will be created later.
+
+## Distribution Mechanisms
+
+Your Fuse Plugin will use several distribution mechanisms. Unlike other platforms,
+Fuse embraces the "native" way of distribution.
+
+|Module|Distribution Method|
+|---|---|
+|JS|tarball via NPM|
+|Android|AAR via maven|
+|iOS|via XCFramework|
+
+These distribution methods aren't the only way but they are more-or-less the official way.
+
+NOTE: Apple does not have an official way to manage or distribute XCFrameworks.
+Fuse distributes their XCframeworks via GitHub Releases and offers a bash script
+to download and sync xcframeworks.
++There are however, third-party ways of distributing XCFrameworks which can be used as well (e.g. CocoaPods, Carthage, etc...) + +Fuse uses native distribution channels to take advantage of native dependency management systems. Because of this, the modules should only contain relevant resources. For example the NPM package should only contain the JS runtime code, +and the XCFramework/AAR should only contain the native framework executable. + +### Version Management + +The Fuse plugin is made up of 2-3 modules (the JS package, and the native framework). +This has some pros and cons: + +**Pros**: + +- Ability to update and release patches of your JS module independently of your native framework. +- Decoupling of the JS module to the native framework allows +you to swap out native implementations (e.g. A free vs paid version of a library). +- Allows you to distribute your plugin via standard distribution channels. + +**Cons**: + +- The decoupled nature allows users to mix and match your native framework version and JS module version that is potentially incompatible. +- Can be more difficult to manage, and errors arising from +version mismatches can be difficult to recognize. + +While these guidelines are not set in stone, we would highly recommend adopting [semver](https://semver.org/) Semantic Versioning. + +At a glance: + +> Given a version number MAJOR.MINOR.PATCH, increment the: +> +> 1. MAJOR version when you make incompatible API changes +> 2. MINOR version when you add functionality in a backward compatible manner +> 3. PATCH version when you make backward compatible bug fixes + +In otherwords, if your native API changes in such a way that it requires modifications to your JS module, both your native API and JS module should have a **MAJOR** version increment. + +Adding a new API to the native framework doesn't affect the JS module, it simply just won't be *exposed* and therefore this update could be a **MINOR** version update because it is still backwards compatible. The JS Module could then be updated to include this new API, which as long as no existing features depend on this API, it can be considered *non-breaking* and be released as a **MINOR** version update. + +## Further Reading + +This concludes the getting started. +The information contained here is useful knowledge to know while developing your JS and native modules. + +At this point, it would be recommended to read [JS Module Guide](js-module.md) next, which goes more in depth on implementing a Fuse JS plugin. diff --git a/docs/docs/plugin-development/ios-module.md b/docs/docs/plugin-development/ios-module.md new file mode 100644 index 0000000..11a6504 --- /dev/null +++ b/docs/docs/plugin-development/ios-module.md @@ -0,0 +1,408 @@ + +# iOS Module + +This guide assumes you've already read and followed [Fuse JS Module](js-module.md). If not, +we strongly recommend beginning there first before proceeding. + +A Fuse iOS module is an iOS implementation of a plugin. They serve the +purpose of handling requests by the webview via the API server and doing an action +on behalf of the webview. + +TODO - Show architecture diagram + +Before we dive into creating an iOS project, we will discuss a few Fuse topics. + +All Fuse classes will have a prefix of `BTFuse`, which for brevity will be omitted, unless if explicitly referencing a class using inline code syntax, (for example, `BTFuseContext`). + +NOTE: Fuse framework is written in Objective-C and consuming the framework from Swift is not currently supported. + +A `BTFuseContext` is a state holding object that holds a reference to all `BTFusePlugin` instances as well as the `BTFuseAPIServer` and `BTFuseAPIRouter`. When the webview makes a request to the API server, the message will be routed to the appropriate Fuse plugin via the API router. + +## Creating the iOS project + +Following along the [Getting Started](getting-started.md) guide, you should already have a `ios` directory. If not, then create one now. + +Open XCode and create a new `Workspace` inside the `ios` directory. A Xcode workspace allows you to group several related projects, which will be used later. Name the workspace `EchoPlugin`. + +NOTE: Per [Apple's naming convention](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/CodingGuidelines/Articles/NamingBasics.html#//apple_ref/doc/uid/20001281-1002226), it's recommended to choose a minimum 3-letter prefix as a way to avoid naming collisions. This guide will however omit prefixing. + +TODO - Show screenshot of creating workspace + +After creating a workspace, XCode will have an empty workspace window. Now we need to create a new XCode `Project`, select `Framework` and name the project `EchoPlugin`. Save the project in the `ios` directory and assign it to the `EchoPlugin` workspace. + +Now the workspace should have an `EchoPlugin` project and you're directory structure should look something like: + +``` +. +└── ios/ + ├── EchoPlugin.xcworkspace + └── EchoPlugin/ + └── EchoPlugin.xcproj +``` + +While we are here, we can also create an Application project which can be used as our test application. Create a new `Project` called `testapp`, assign it to the `EchoPlugin` workspace and save it inside the `ios` directory. + +NOTE: The default Application project will add support for iPadOS, WatchOS, TVOS, VisionOS, etc... however, the Fuse framework at this time only has support for iOS. + +## Adding the Fuse dependency + +The Fuse framework can be synced either via CocoaPods or by downloading the XCFramework directly from [GitHub](https://github.com/btfuse/fuse-ios/releases). + +CocoaPods can make managing dependencies more easier since you can mark version of pods and CocoaPods can fetch +all the required dependencies to use that pod. If using CocoaPods, see the [Using CocoaPods](#using-cocoapods) section. If manually managing dependencies is preferred, then see [Managing Dependencies Manually](#managing-dependencies-manually) section. + +### Using CocoaPods + +If you don't already have cocoapods installed, see [CocoaPods](https://cocoapods.org/) website to get started. CocoaPods 1.15.0 or later is recommended. + +Once CocoaPods is installed, create a `Podfile` inside the `ios` directory and paste in the following content: + +``` ruby linenums="1" title="/Podfile" +workspace 'EchoPlugin' + +platform :ios, '15.0' + +source 'https://github.com/breautek/pods.git' + +target 'EchoPlugin' do + project 'EchoPlugin/EchoPlugin' + use_frameworks! + + pod 'BTFuse', '0.8.7' +end +``` + +Save the file and run `pod install`, which will create a `Pods` project and adds it to your `EchoPlugin` workspace. + +NOTE: It will be recommended to add `Pods` directory to your source version control ignore file. + +NOTE: If you had XCode opened, it will likely detect project structure changes and you should reload the project from disk, if prompted. + +CocoaPods usually does a lot of project level management for you, however for framework targets, CocoaPods will just make the pod available, but CocoaPods will not link or embed the pod to your framework target. Therefore, we need to link against `BTFuse.xcframework`, without embedding it. + +Click on the `EchoPlugin` project to open the Project view panel. + +TODO - show screenshot + +Ensure that the `EchoPlugin` target is selected on the left side, and then view the `General` tab. Under `Frameworks and Libraries`, change `BTFuse.xcframework`'s `Embed` option `Do not embed`. This allows your framework to compile against the Fuse framework without including the framework when you publishing your own plugin. + +TODO - show screenshot + +### Managing Dependencies Manually + +If you have already setup and used CocoaPods, then you can proceed to the [next section](#implementing-the-echoplugin). + +If you prefer not to use CocoaPods, then managing the dependencies manually is another option and may be suitable for smaller projects. Create a `frameworks` folder inside the `ios` directory and download the latest version of `BTFuse.xcframework.zip` file from [Fuse GitHub Releases](https://github.com/btfuse/fuse-ios/releases). + +Extract the contents into `ios/frameworks`. There should now be a `ios/frameworks/BTFuse.xcframework`. + +Inside XCode's Project Navigator, right-click the `EchoPlugin` project and create a `New Group`, name it `frameworks`. + +TODO - Show screenshot + +Now, open the path to `ios/frameworks` in `Finder` and drag & drop the `BTFuse.xcframework` inside `EchoPlugin` `frameworks` group. + +TODO - Show screenshot + +When dropping the XCFramework, a dialog will be opened to asking the target memberships. Select `EchoPlugin`. + +TODO - show Screenshot + +By default, XCode will link against the XCFramework by embedding & signing it. However Fuse framework should **not** be embedded in Fuse plugin frameworks, as doing so will cause conflicts when users try to consume your plugin. To address this, click on the `EchoPlugin` project to open the Project view panel. + +TODO - show screenshot + +Ensure that the `EchoPlugin` target is selected on the left side, and then view the `General` tab. Under `Frameworks and Libraries`, change `BTFuse.xcframework`'s `Embed` option `Do not embed`. This allows your framework to compile against the Fuse framework without including the framework when you publishing your own plugin. + +TODO - show screenshot + +You may repeat these steps for the `testapp`, however it is fine for the test app to `Embed & Sign` the `BTFuse.xcframework`, as the application is the final product. + +## Implementing the EchoPlugin + +Now we are ready to start writing some code! + +Create a new `Header` file inside the `EchoPlugin` project and name it `EchoPlugin.h`. Paste in the following contents: + +``` obj-c title="EchoPlugin.h" linenums="1" +#ifndef EchoPlugin_h +#define EchoPlugin_h + +#import
+
+
+
+
+## Development Tooling
+
+The Fuse framework is written in TypeScript. While writing pure JS is also do-able, it would be recommended to build your JS module using TypeScript. Users of Fuse will be expecting type definitions and it will provide you the compiler checks necessary to have confidence that you're following the Fuse API as intended.
+
+## WebView Runtime
+
+The JS module are node modules however they **do not run** in a NodeJS environment. They will run in a webview environment in the native application shell. That is [WKWebView](https://developer.apple.com/documentation/webkit/wkwebview?language=objc) on iOS, and [android.webkit.WebView](https://developer.android.com/reference/android/webkit/WebView) on Android.
+
+These webview environments are more like a browser. Care needs to be taken to use browser APIs instead of NodeJS APIs.
+
+## Preparing the package.json
+
+To create a new JS module, simply create a new node package:
+
+``` bash
+npm init
+```
+
+And follow the prompts as you see fit, choosing the package name, etc.
+
+When you're done, you'll have a fairly barebones `package.json` file.
+
+Open it and add a `main` and `types` property:
+
+``` json
+{
+ ...
+ "main": "./lib/api.js",
+ "types": "./lib/api.d.ts"
+}
+```
+
+And while we are here, let's add some scripts:
+
+``` json
+{
+ ...
+ "scripts": {
+ "build": "tsc"
+ }
+}
+```
+
+### Configuring the Fuse JS dependency
+
+#### peerDependency
+
+While your JS module will require a dependency on Fuse framework, it is important to declare the dependency as a `peerDependendency`.
+
+A peer dependency is a kind of dependency where your module does not *provide* the dependency and instead the consuming application must install the dependency themselves. This is important because an Fuse JS Module **shall not** have their own embedded copy of the Fuse JS runtime. If they did, it will cause issues with duplicate/copied classes and state objects. Delegating the Fuse JS runtime to the application allows you to guarentee that a single Fuse JS runtime will be in the application.
+
+NOTE: Using a `peerDependency` is not strictly for Fuse JS Modules, but for any library that wants to depend on the Fuse JS framework, including helper libraries that could be shared across multiple Fuse JS modules.
+
+A `peerDependency` can be thought as the Fuse JS version range that is supported by your Fuse JS Module. When choosing a `peerDependency` version, choose lowest version possible that your Fuse JS Module will support, but keep the range open until the next major version update. Some examples may include:
+
+|Use Case|Version Range Example|Reasoning|
+|---|---|---|
+|Tested against a single major version|`1.x`|Will allow any version inside a **MAJOR** version 1 range.
+|Tested against 2 major versions|`1.x \|\| 2.x`|Will allow any version sinide a **MAJOR** version **or** 2 range.
+|Requires a feature update|`>=1.1 <2`|Will allow any **MAJOR** version range of 1 with **MINOR** being >= 1.
+
+This allows the application to choose a specific Fuse JS runtime that works for them, while keeping your Fuse JS module compatible with other installed Fuse JS modules.
+
+WARNING: If your Fuse JS Module requires a strict version, it will
+prevent your JS module from being installed with other modules that may require a newer patch.
+
+The current recommendation for new Fuse JS modules is the following peer dependency:
+
+``` json
+{
+ "peerDependencies": {
+ "@btfuse/core": "0.7.x"
+ }
+}
+```
+
+#### devDependency
+
+While the `peerDependency` described above is used to declare a supported version range of the Fuse JS runtime, it's not used when developing and testing your Fuse JS module. A locally installed version still needs to be installed for development purposes.
+
+NPM allows both a `peerDependency` and a `devDependency` to co-exists. This will give access to TypeScript symbols and give the ability to TypeScript compile your Fuse JS module, or even write unit test using the Fuse JS testing library.
+
+The `devDependency` declaration should be a version within the range of your `peerDependency`.
+
+WARNING: If you install a `devDependency` that is outside of the range of your `peerDependency`, NPM will update your `peerDependency` potentially with a strict version requirement.
+
+The exact version to choose as your `devDependency` will depend on your mantra. For example, choosing the lowest supported version will help ensure that a breaking change isn't introduced by accidentally using an API that might have been only added in a later feature update. Choosing the latest version of a given supported major will allow testing against the current release.
+
+``` bash
+npm install --save-dev @btfuse/core@0.x
+```
+
+### Additional dev dependencies
+
+In addition to `@btfuse/core`, it's also recommended to install [TypeScript](https://www.typescriptlang.org/).
+
+``` bash
+npm install --save-dev typescript
+```
+
+NOTE: The remainder of this guide will assume you're using TypeScript. If you choose not to use TypeScript, you'll need to incorporate a bundler to import `@btfuse/core` modules.
+
+TypeScript has a `tslib` package that imports reusable runtime helpers which can reduce code size. This should be installed as a `dependency`:
+
+``` bash
+npm install tslib
+```
+
+Both the `package.json` and `package-lock.json` can and should be committed into your Version Control System.
+
+### Configuring TypeScript
+
+Before we start coding, we must first configure TypeScript.
+A quick way to do this is by issueing the init command:
+
+``` bash
+npx tsc --init
+```
+
+This will create a `tsconfig.json` file with some sensible defaults.
+
+The following modifications are recommended:
+
+|Setting|Value|
+|---|---|
+|`compilerOptions.target`|`"ES2017"`|
+|`compilerOptions.module`|`"commonjs"`|
+|`compilerOptions.moduleResolution`|`"node"`|
+|`compilerOptions.declaration`|`true`|
+|`compilerOptions.sourceMap`|`true`|
+|`compilerOptions.outDir`|`"./lib"`|
+|`compilerOptions.importHelpers`|`true`|
+|`compilerOptions.sourceRoot`|`"/"`|
+|`compilerOptions.inlineSources`|`true`|
+|`compilerOptions.esModuleInterop`|`true`|
+|`compilerOptions.forceConsistentCasingInFileNames`|`true`|
+|`compilerOptions.strict`|`true`|
+|`compilerOptions.noImplicitAny`|`true`|
+|`compilerOptions.useUnknownInCatchVariables`|`true`|
+|`compilerOptions.alwaysStrict`|`true`|
+|`include`|
+[
"./src/*.ts",
"./src/**/*.ts"
]|
+|`exclude`| [
"./lib",
"./spec"
]|
+
+### Git Ignore
+
+There are a few folders/files that should be added to the `.gitignore` file:
+
+```
+node_modules
+/lib
+.DS_Store
+```
+
+We ignore `node_modules` because it will include all your dependencies to build/run your library. `npm install` will sync this folder according to your `package.json` / `package-lock.json`.
+
+`/lib` because this directory will contain your built JS artefacts.
+
+`.DS_Store` is a common mac file that aids Finder, it doesn't need to be checked into the repository.
+
+TIP: Additional folders and files will be added depending on if you support iOS and/or Android.
+
+### NPM Ignore
+
+Similar to `.gitignore`, NPM accepts a `.npmignore` which can be used
+to ignore files while packing your distributable.
+
+Include anything that shouldn't be included in your distributable.
+
+```
+spec
+tsconfig.json
+```
+
+TIP: Additional folders and files will be added depending on if you support iOS and/or Android.
+
+### Directory Structure
+
+At this point, you're directory structure should look something like:
+
+```
+.
+├── node_modules/
+│ └── ...
+├── .gitignore
+├── .npmignore
+├── package.json
+├── package-lock.json
+└── tsconfig.json
+```
+
+Let's add a new directory `src` with the files `api.ts` and `EchoPlugin.ts`:
+
+```
+.
+├── node_modules/
+│ └── ...
+├── src/
+│ ├── api.ts
+│ └── EchoPlugin.ts
+├── .gitignore
+├── .npmignore
+├── package.json
+├── package-lock.json
+└── tsconfig.json
+```
+
+The `src` folder will be the directory that contains your source implementation files.
+
+We aren't ready to build yet, but when we are, a `lib` folder will appear containing the built JS.
+
+## EchoPlugin.ts
+
+Now let's implement our `EchoPlugin.ts` file.
+
+It will include a class that has a public API `echo`, which takes in a single `string` parameter, and uses the native API. The native API will respond back with the `string` in which we return back.
+
+NOTE: As a plugin guide that focuses purely on building a JS Module, this guide won't have a demonstratable code that can be ran.
+
+
+```typescript linenums="1" title="/src/EchoPlugin.ts"
+import {
+ FusePlugin,
+ ContentType,
+ FuseAPIResponse
+} from '@btfuse/core';
+
+export class EchoPlugin extends FusePlugin {
+ protected override _getID(): string {
+ return 'EchoPlugin';
+ }
+
+ public async echo(message: string): Promise
+ 
+
+
+
+### Installing the SDK Platform
+
+Under the `SDK Platforms` tab there will be a list of platforms you can install, as well as system images for simulators.
+
+The first SDK in the list is usually an early developer release/preview of the upcoming Android version. These are great to be ahead of the curve and to ensure your app continues to work on new android releases before the general public has access. The platform itself however may be buggy and generally isn't suitable for general app development.
+
+The second in the list is generally the latest release, at the time of writing that's Android 14.0 "UpsideDownCake". This guide will assume Android 14, but if there is a newer SDK feel free to use it instead.
+
+- Check `Android SDK Platform 34`, this is the main package containing the Android SDK.
+- `Sources for Android 34` is optional, but may assist in debugging packages.
+
+Lastly a system image should be installed for the Android simulator. Which one that you should choose will depend on your host development machine. Users running on Intel/AMD x86 architecture should choose a `x86_64` system image and users running on Mac with Apple silicon should choose `ARM64` system image.
+
+There are also several image types outside of architecture including:
+
+- AOSP (ARM64 / Intel Atom)
+- Google APIs
+- Google Play
+
+Which one you use will depend on your requirements. It is also possible to have more than one simulator created with different images for different test cases.
+
+The `Arm64` / `Intel Atom` image are generally barebones Android AOSP (Android Open Source Project). They will include original AOSP software which is often out-dated packages. It can be useful to test against old webview versions to ensure your app still works, even if the user has a severely out-dated device. Additionally these system images tends to offer better debug tools since the security policies are often relaxed.
+
+`Google APIs` images ships with Google Play services allowing you to test against several google products including Firebase, Google Maps, Google Sign-in, etc. If your app integrates with any of these services, a Google APIs image might be necessary.
+
+`Google Play` images are similar to `Google APIs` but they also have the `Google Play Store` available. They behave very closely to a real retail device and have a lot of security restrictions, so debuggability may be hindered on these images. But you'll have the ability to sign into a google account and update the simulator with the latest packages from the Google Play store, including the system webview.
+
+Using a `Google Play` image when possible would be recommended for Fuse projects because it will allow you to keep your simulator up to date with the latest system webview, which your app will live in. Ensuring that it always works against the latest webview will be desirable.
+
+
+
+ 
+
+
+
+Once all of the packages is selected, click `Apply` to download and install. This may take awhile.
+
+### SDK Tools
+
+Under the `SDK Tools` tab there is several additional tools. Install the following:
+
+- Android SDK Build-Tools
+- Android SDK Command-line Tools
+- Android Emulator
+- Android SDK Platform-Tools
+- Google Play Services (Optional, but required if you use any Google APIs)
+- Layout inspector image server for API 31-34 (Optional)
+
+If you plan on using C++ and native development then you'll also need:
+
+- CMake
+- NDK (Side by side)
+
+TIP: `Show Package Details` will make the SDK Tools list expandable so that specific versions of each package can be installed if necessary.
+
+
+
+ 
+
+
+
+Once all the SDK tools is selected, click on `Apply` to download and install. This may take awhile.
+
+Once done, you may close the SDK Manager.
+
+## Creating an Android Emulator
+
+Now that we have our packages installed, now it's a good time to create an Android emulator.
+
+From the `Welcome to Android Studio` window, click on the triple dot and go to `Virtual Device Manager`.
+
+
+
+ 
+
+
+
+This will open a `Device Manager` window that will list any virtual and physical devices. You can start or edit any virtual device or create new ones. Click on the `+` button to create a new virtual device, which will open a wizard.
+
+First, it will ask you to create a device definition. You can select from variety of different phones based on their size, density, and other hardware profiles. I'd recommend choosing a profile that has `Play Store` support as indicated by the Google Play icon.
+
+For this guide, I'll be choosing the `Pixel 7`
+
+
+
+ 
+
+
+
+TIP: Keep your Android Studio updated to have the latest profiles avilable.
+
+Click `Next` to continue. The next step is to select a system image.
+
+The UI will provide 3 tabs: `Recommended`, `ARM/x86_64 Images`, and `Other Images`.
+
+`ARM/x86_64 Images` depends on your host CPU architecture. Apple Silicon users for example will see `ARM Images`, which will show a filtered list of ARM images of all supported API levels. `Other Images` will show all available images regardless of architecture.
+
+If you're missing any particular image, you can also download it in this screen.
+
+For the purpose of this guide, we will be using the current Android Release (Android 14), so I'll be choosing API 34 with Google Play.
+
+NOTE: This guide is being authored on an ARM64 host machine. If you're using AMD/Intel, then you'll likely see `x86_64` architectures instead.
+
+
+
+ 
+
+
+
+Click `Next` to continue, to verify your device configuration.
+
+Here we can set a name of your device, and adjust some other advanced settings. Most of the time you can simply click `Finish` but feel free to explore your options.
+
+
+
+ 
+
+
+
+Now your virtual devilce will appear in the `Device Manager`. Click on the play icon to start it!
+
+
+
+ 
+
+
+
+This simulator is a Google Play simulator. Feel free to sign into your google account on the simulator and start updating the device to the latest version of all the packages, especially the `Android System Webview`.
+
+Android simulators are full-featured virtual machines and are very powerful but can also be expensive on your system resources. We won't be using the simulator for awhile, so if you're using a more constrained system, you may stop the simulator as well, or stop it after it has finished updating from Google Play store.
+
+## Creating an Android Project
+
+Now that we got all of our pre-requisites covered, it's time to start on more exciting stuff!
+
+From the `Welcome to Android Studio` screen, click on `New Project` and select `No Activity`.
+
+NOTE: We are selecting `No Activity` because the other templates includes things that doesn't make a whole lot of sense for a hybrid application. However if you have unique requirements, other activity templates should work too.
+
+
+
+ 
+
+
+
+Click `Next` will take you to a form detailing some details of your project.
+
+The important bit is `Save location`, which I'd suggest saving it inside a `/android` directory of your project repo.
+All other settings are preference but this guide will use `Java` programming language and the `Kotlin DSL`.
+
+
+
+ 
+
+
+
+Click `Finish` and Android Studio will setup your application and initiate a Gradle sync. Once Gradle is finished syncing, you'll be able to interact the IDE.
+
+### Creating the MainActivity
+
+Since we used a `No Activity` template, the App has no starting activity. Let's fix that right now.
+
+Right click on the `app` module, and go to `New` -> `Activity` -> `Empty Views Activity`. This will open a `New Android Activity` dialog.
+
+
+
+ 
+
+
+
+Check `Launcher Activity` because we want this activity to be the main activity, then click `Finish`
+
+
+
+ 
+
+
+
+Now that we have a main activity, we can successfully build and launch our app.
+
+
+
+ 
+
+
+
+TIP: If you don't want the "action bar", change your `/res/values/themes/themes.xml` to use `Theme.AppCompat.NoActionBar` as the `parent`.
+
+### Creating the asset folder
+
+Like many apps, we probably want to bundle app assets. This is especially true for Fuse applications since most of our application will live in the webview, using the webpack-built JS and other web assets.
+
+Right click the `res` folder and go to `New` -> `Folder` -> `Assets Folder`. This will open a `New Android Component` folder providing an opportunity to change the location, however we should keep the default location. Click `Finish`.
+
+
+
+ 
+
+
+
+
+
+ 
+
+
+
+This will create a folder path `/android/app/src/main/assets` which will be used later in Webpack.
+
+#### Preparing your Assets
+
+Now it's time to build some build hooks that uses webpack to build your JS code, and deploy them into your assets directory. We will utilise a build hook in Gradle so that this process is part of your build process when building your Android project.
+
+First however, when [Getting Started](./getting-started.md) we only built a base webpack config. We will need to extend that config for our android platform.
+
+##### Android Webpack Config
+
+Create a `/webpack.config.android.js` file with the following contents:
+
+```javascript
+
+const Path = require('path');
+const CopyPlugin = require("copy-webpack-plugin");
+
+const config = require('./webpack.config');
+
+config.output.path = Path.resolve(__dirname, 'android/app/src/main/assets/');
+config.plugins.push(new CopyPlugin({
+ patterns: [
+ { from: "./src/index.html", to: Path.resolve(__dirname, "./android/app/src/main/assets/index.html") }
+ ]
+}));
+
+module.exports = config;
+```
+
+This pulls from our main `/webpack.config.js` file and updates the `output.path` option which tells webpack to distribute any built files in our app's assets directory.
+
+Additionally, we utilise a Webpack Copy plugin to copy our `index.html` file into our app's assets directory as part of the webpack build process.
+
+TIP: There are multiple ways to skin a cat. The method shown here is just one way. Fuse is agnostic to these tools, as long as you can bundle your JS against Fuse's CommonJS codebase and provide an `index.html` file somehow.
+
+##### Gradle Build Hook
+
+Open up your `app` module's `build.gradle.kts` file:
+
+
+
+ 
+
+
+
+At the end of the file, add:
+
+```kotlin
+tasks.register("runWebpackDebug", Exec::class) {
+ workingDir = file("../../")
+ commandLine("npx", "webpack", "--mode", "development", "-c", "webpack.config.android.js")
+}
+
+tasks.register("runWebpackRelease", Exec::class) {
+ workingDir = file("../../")
+ commandLine("npx", "webpack", "--mode", "production", "-c", "webpack.config.android.js")
+}
+
+tasks.withType
+
+ 
+
+
+
+If you've made it this far, congrats! We now have a Fuse project in a state where you can build an application using standard webview technologies.
+
+### Integrating Fuse Plugins
+
+Restricting yourself to just browser features however can be rather limiting. So we can incorporate Fuse Plugins that extends the functionality available using the embedded API server as a communication channel between the webview and native platform environment.
+
+Generally speaking, a fuse plugin will offer API endpoints which will do tasks on the native platform using native device APIs and then will return a response back to the webview. If you're familiar with REST APIs, this is akin to having the webview (frontend) client making a REST API request to a backend server.
+
+_Unfortunately, this section isn't complete yet!_
+
+TODO - Come back to this when we have a simple released plugin available that we can use for demonstrating purposes.
+
+## Writing App Tests
+
+TODO
+
+## Distributing your Application
+
+TODO
diff --git a/docs/docs/user-guide/getting-started.md b/docs/docs/user-guide/getting-started.md
new file mode 100644
index 0000000..9ef273b
--- /dev/null
+++ b/docs/docs/user-guide/getting-started.md
@@ -0,0 +1,285 @@
+
+# Getting Started
+
+The Fuse Framework provides a means to build a native application with a webview user interface, without sacrificing the means to use device APIs from the webview.
+
+This guide will go over how to setup the JavaScript environment and then will branch off into native environment. For plugin development, [click here](../plugin-development/getting-started.md).
+
+For the purpose of this guide, we'll assume that you're starting off with an empty git repository.
+
+## Requirements
+
+To complete this guide you'll need:
+
+- Current NodeJS LTS
+- Webpack or another JS bundler
+
+Additionally for Android development, Android Studio is required. For iOS development, XCode will be required. Details for each environment will be provided later.
+
+## The JS Runtime
+
+Start off with creating a NPM package by issuing: `npm init`. Fill out the NPM prompt to create a NPM package.
+
+(Optional) Once you're done, go into `package.json` and add `"private": true` to prevent accidentally publishing your app to NPM.
+
+A quick note regarding the JS environment. While we are working with node modules, the JS environment ran inside the app is not a NodeJS runtime. Care has to be taken not to use NodeJS-specific modules.
+
+Fuse framework makes use of TypeScript so it will make sense to also use TypeScript to get the advantage of compilation checks and some level of type safety. Fuse is also distributed as a CommonJS module, which means it can't be ran inside directly inside the webview as is. We require a web bundler. This guide will use Webpack but any bundler should do.
+
+Let's start with installing our dependencies:
+
+``` bash
+npm install --save-dev webpack webpack-cli copy-webpack-plugin typescript ts-loader source-map-loader @btfuse/core
+```
+
+### Configuration Files
+
+Fuse is tailored to develop larger-scale projects, so bear with us as we setup our boilerplate project configuration. A basic Fuse project will typically contain Webpack (or some other JS bundler) as well as TypeScript.
+
+NOTE: All paths mentioned will be assumed to be relative of your project root directory. In otherwords `/src/myFile.js` is expected to be located at `
++ Version: ${version.toString()} + `; +})(); +``` + +This is a simple program that setups up a `FuseContext` and uses some built-in APIs to get the current platform runtime and the version and then finally update the HTML body node with the fetched information. + +## Next Steps + +We have setup the webview bits that are mostly common between the Android & iOS platform, however, we don't have something buildable yet! +Don't worry that's covered in our next guides. + +Please see: + +- iOS User Guide +- [Android User Guide](./android-guide.md) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 0000000..b85e475 --- /dev/null +++ b/docs/mkdocs.yml @@ -0,0 +1,88 @@ +# Copyright 2023 Breautek + +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at + +# http://www.apache.org/licenses/LICENSE-2.0 + +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +site_name: Breautek Fuse +site_url: https://fuse.breautek.com/ +site_description: Breautek Fuse Framework User Documentation +site_author: Breautek +copyright: Copyright © 2023 Breautek +repo_url: https://github.com/btfuse/fuse-docs/ +edit_uri: blob/main/docs/ + +theme: + name: material + logo: res/fuse-logo.svg + favicon: res/favicon.svg + features: + - search.suggest + - content.code.copy + - content.code.select + - content.code.annotate + palette: + primary: white + custom_dir: theme_overrides + +plugins: + - tags: [] + - search: [] + # - typedoc: + # source: ../fuse-js/src + # tsconfig: ../fuse-js/tsconfig.json + # output_dir: ./docs/ref/test + # - typedoc: + # source: './external/fuse-js/' + # tsconfig: './external/fuse-js/tsconfig.json' + # options: './external/fuse-js/typedoc.json' + # tsconfig: './external/fuse-js/tsconfig.json' + # - typedoc: + # tsconfig: './external/fuse-js/tsconfig.json' + # # output_dir: 'FuseJSReference' + # # name: 'Fuse JS Reference' + # # disable_system_check: False + +markdown_extensions: + - callouts + - pymdownx.emoji: + emoji_index: !!python/name:pymdownx.emoji.gemoji + emoji_generator: !!python/name:pymdownx.emoji.to_alt + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences + +extra_css: + - css/tip.css + - css/broken-link.css + +nav: + - Home: index.md + - User Guide: + - Getting Started: user-guide/getting-started.md + - Android Guide: user-guide/android-guide.md + - Plugin Development: + - Getting Started: plugin-development/getting-started.md + - Fuse JS Modules: plugin-development/js-module.md + - Android Modules: plugin-development/android-module.md + - iOS Modules: plugin-development/ios-module.md + - API Reference: + - Fuse JS: ref/fuse-js/index.html + - Fuse Android: ref/fuse-android/index.html + + # - API Reference: + # - Index: api-ref/index.md + # - Webview: + # - Core: api-ref/js/core.md diff --git a/docs/package-lock.json b/docs/package-lock.json new file mode 100644 index 0000000..80fcb83 --- /dev/null +++ b/docs/package-lock.json @@ -0,0 +1,145 @@ +{ + "name": "fuse-docs", + "version": "1.0.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "fuse-docs", + "version": "1.0.0", + "license": "Apache-2.0", + "devDependencies": { + "typedoc": "^0.25.13", + "typedoc-plugin-markdown": "^4.0.2", + "typescript": "^5.4.5" + } + }, + "node_modules/ansi-sequence-parser": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/ansi-sequence-parser/-/ansi-sequence-parser-1.1.1.tgz", + "integrity": "sha512-vJXt3yiaUL4UU546s3rPXlsry/RnM730G1+HkpKE012AN0sx1eOrxSu95oKDIonskeLTijMgqWZ3uDEe3NFvyg==", + "dev": true + }, + "node_modules/balanced-match": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz", + "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==", + "dev": true + }, + "node_modules/brace-expansion": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz", + "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", + "dev": true, + "dependencies": { + "balanced-match": "^1.0.0" + } + }, + "node_modules/jsonc-parser": { + "version": "3.2.1", + "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.2.1.tgz", + "integrity": "sha512-AilxAyFOAcK5wA1+LeaySVBrHsGQvUFCDWXKpZjzaL0PqW+xfBOttn8GNtWKFWqneyMZj41MWF9Kl6iPWLwgOA==", + "dev": true + }, + "node_modules/lunr": { + "version": "2.3.9", + "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz", + "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==", + "dev": true + }, + "node_modules/marked": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/marked/-/marked-4.3.0.tgz", + "integrity": "sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A==", + "dev": true, + "bin": { + "marked": "bin/marked.js" + }, + "engines": { + "node": ">= 12" + } + }, + "node_modules/minimatch": { + "version": "9.0.4", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.4.tgz", + "integrity": "sha512-KqWh+VchfxcMNRAJjj2tnsSJdNbHsVgnkBhTNrW7AjVo6OvLtxw8zfT9oLw1JSohlFzJ8jCoTgaoXvJ+kHt6fw==", + "dev": true, + "dependencies": { + "brace-expansion": "^2.0.1" + }, + "engines": { + "node": ">=16 || 14 >=14.17" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/shiki": { + "version": "0.14.7", + "resolved": "https://registry.npmjs.org/shiki/-/shiki-0.14.7.tgz", + "integrity": "sha512-dNPAPrxSc87ua2sKJ3H5dQ/6ZaY8RNnaAqK+t0eG7p0Soi2ydiqbGOTaZCqaYvA/uZYfS1LJnemt3Q+mSfcPCg==", + "dev": true, + "dependencies": { + "ansi-sequence-parser": "^1.1.0", + "jsonc-parser": "^3.2.0", + "vscode-oniguruma": "^1.7.0", + "vscode-textmate": "^8.0.0" + } + }, + "node_modules/typedoc": { + "version": "0.25.13", + "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.25.13.tgz", + "integrity": "sha512-pQqiwiJ+Z4pigfOnnysObszLiU3mVLWAExSPf+Mu06G/qsc3wzbuM56SZQvONhHLncLUhYzOVkjFFpFfL5AzhQ==", + "dev": true, + "dependencies": { + "lunr": "^2.3.9", + "marked": "^4.3.0", + "minimatch": "^9.0.3", + "shiki": "^0.14.7" + }, + "bin": { + "typedoc": "bin/typedoc" + }, + "engines": { + "node": ">= 16" + }, + "peerDependencies": { + "typescript": "4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x" + } + }, + "node_modules/typedoc-plugin-markdown": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/typedoc-plugin-markdown/-/typedoc-plugin-markdown-4.0.2.tgz", + "integrity": "sha512-4MV3M+0lsmIaXuDBzeqLYemZqwTQDWQow+o8zdT9hC7KFu06GaFo2uUEbkjE6pgZA9hnkOTtzRVd0R9YJWcH8A==", + "dev": true, + "peerDependencies": { + "typedoc": "0.25.x" + } + }, + "node_modules/typescript": { + "version": "5.4.5", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.4.5.tgz", + "integrity": "sha512-vcI4UpRgg81oIRUFwR0WSIHKt11nJ7SAVlYNIu+QpqeyXP+gpQJy/Z4+F0aGxSE4MqwjyXvW/TzgkLAx2AGHwQ==", + "dev": true, + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/vscode-oniguruma": { + "version": "1.7.0", + "resolved": "https://registry.npmjs.org/vscode-oniguruma/-/vscode-oniguruma-1.7.0.tgz", + "integrity": "sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA==", + "dev": true + }, + "node_modules/vscode-textmate": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/vscode-textmate/-/vscode-textmate-8.0.0.tgz", + "integrity": "sha512-AFbieoL7a5LMqcnOF04ji+rpXadgOXnZsxQr//r83kLPr7biP7am3g9zbaZIaBGwBRWeSvoMD4mgPdX3e4NWBg==", + "dev": true + } + } +} diff --git a/docs/package.json b/docs/package.json new file mode 100644 index 0000000..7648784 --- /dev/null +++ b/docs/package.json @@ -0,0 +1,18 @@ +{ + "name": "fuse-docs", + "version": "1.0.0", + "description": "Fuse Documentation", + "private": true, + "main": "index.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1", + "build:ref:fusejs": "npx typedoc --options typedoc.fusejs.json" + }, + "author": "norman@breautek.com", + "license": "Apache-2.0", + "devDependencies": { + "typedoc": "^0.25.13", + "typedoc-plugin-markdown": "^4.0.2", + "typescript": "^5.4.5" + } +} diff --git a/docs/readme.md b/docs/readme.md new file mode 100644 index 0000000..6d97a37 --- /dev/null +++ b/docs/readme.md @@ -0,0 +1,71 @@ + + +# Contributor Documentation + +Fuse documentation and website is powered by mkdocs. For full documentation visit [mkdocs.org](https://www.mkdocs.org). + +Python is required to build the website. Mkdocs also provides a server with auto hot reload for development. + +## Setting up the development environment + +If you don't have already have a virtual env, it would be recommended to create one: + +```bash +python3 -m venv venv +``` + +Activate the environment: + +```bash +source venv/bin/activate +``` + +And install the dependencies: + +```bash +pip3 install -r requirements.txt +``` + +To deactivate/exit the virtual environment, run: + +```bash +deactivate +``` + +## Building the documentation + +This section assumes you're already in a python virtual env. + +Building can be done by running: + +```bash +mkdocs build +``` + +However, if you want to actually test and see your changes, serving might be better: + +```bash +mkdocs serve +``` + +This will run a local webserver. + +## Common Mkdocs Commands + +* `mkdocs serve` - Start the live-reloading docs server. +* `mkdocs build` - Build the documentation site. +* `mkdocs -h` - Print help message and exit. diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..ae6902d --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,30 @@ +Babel==2.14.0 +certifi==2024.2.2 +charset-normalizer==3.3.2 +click==8.1.7 +colorama==0.4.6 +ghp-import==2.1.0 +idna==3.6 +Jinja2==3.1.3 +Markdown==3.5.1 +markdown-callouts==0.3.0 +MarkupSafe==2.1.5 +mergedeep==1.3.4 +mkdocs==1.5.3 +mkdocs-material==9.4.8 +mkdocs-material-extensions==1.3.1 +mkdocs-typedoc==1.0.2 +packaging==23.2 +paginate==0.5.6 +pathspec==0.12.1 +platformdirs==4.2.0 +Pygments==2.17.2 +pymdown-extensions==10.7 +python-dateutil==2.8.2 +PyYAML==6.0.1 +pyyaml_env_tag==0.1 +regex==2023.12.25 +requests==2.31.0 +six==1.16.0 +urllib3==2.2.0 +watchdog==3.0.0 diff --git a/docs/src/AndroidModuleArchitecture.drawio b/docs/src/AndroidModuleArchitecture.drawio new file mode 100644 index 0000000..8ad76ec --- /dev/null +++ b/docs/src/AndroidModuleArchitecture.drawio @@ -0,0 +1,88 @@ +
+
+ {{ super() }}
+{% endblock %}
diff --git a/docs/typedoc.fusejs.json b/docs/typedoc.fusejs.json
new file mode 100644
index 0000000..cd55001
--- /dev/null
+++ b/docs/typedoc.fusejs.json
@@ -0,0 +1,10 @@
+{
+ "navigationLinks": {
+ "Main Documentation": "/"
+ },
+ "name": "FuseJS",
+ "out": "./docs/ref/fuse-js",
+ "tsconfig": "./external/fuse-js/tsconfig.json",
+ "entryPoints": ["./external/fuse-js/src/api.ts"],
+ "readme": "none"
+}
diff --git a/echo/.gitignore b/echo/.gitignore
new file mode 100644
index 0000000..216bf0e
--- /dev/null
+++ b/echo/.gitignore
@@ -0,0 +1,3 @@
+/node_modules
+/lib
+/dist
diff --git a/echo/android/.gitignore b/echo/android/.gitignore
new file mode 100644
index 0000000..42afabf
--- /dev/null
+++ b/echo/android/.gitignore
@@ -0,0 +1 @@
+/build
\ No newline at end of file
diff --git a/echo/android/build.gradle.kts b/echo/android/build.gradle.kts
new file mode 100644
index 0000000..84385a8
--- /dev/null
+++ b/echo/android/build.gradle.kts
@@ -0,0 +1,40 @@
+plugins {
+ id("com.android.library")
+}
+
+android {
+ namespace = "com.breautek.fuse.plugins.echo"
+ compileSdk = 34
+
+ androidResources {
+ noCompress += ""
+ }
+
+ defaultConfig {
+ minSdk = 26
+
+ testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+ consumerProguardFiles("consumer-rules.pro")
+ }
+
+ buildTypes {
+ release {
+ isMinifyEnabled = false
+ proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
+ }
+ }
+
+ compileOptions {
+ sourceCompatibility = JavaVersion.VERSION_17
+ targetCompatibility = JavaVersion.VERSION_17
+ }
+}
+
+dependencies {
+ implementation("androidx.appcompat:appcompat:1.7.0")
+ implementation("com.google.android.material:material:1.12.0")
+ implementation(project(":fuse"))
+ testImplementation("junit:junit:4.13.2")
+ androidTestImplementation("androidx.test.ext:junit:1.2.1")
+ androidTestImplementation("androidx.test.espresso:espresso-core:3.5.1")
+}
\ No newline at end of file
diff --git a/echo/android/consumer-rules.pro b/echo/android/consumer-rules.pro
new file mode 100644
index 0000000..e69de29
diff --git a/echo/android/proguard-rules.pro b/echo/android/proguard-rules.pro
new file mode 100644
index 0000000..ff59496
--- /dev/null
+++ b/echo/android/proguard-rules.pro
@@ -0,0 +1,21 @@
+# Add project specific ProGuard rules here.
+# You can control the set of applied configuration files using the
+# proguardFiles setting in build.gradle.kts.
+#
+# For more details, see
+# http://developer.android.com/guide/developing/tools/proguard.html
+
+# If your project uses WebView with JS, uncomment the following
+# and specify the fully qualified class name to the JavaScript interface
+# class:
+#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
+# public *;
+#}
+
+# Uncomment this to preserve the line number information for
+# debugging stack traces.
+#-keepattributes SourceFile,LineNumberTable
+
+# If you keep the line number information, uncomment this to
+# hide the original source file name.
+#-renamesourcefileattribute SourceFile
\ No newline at end of file
diff --git a/echo/android/src/main/AndroidManifest.xml b/echo/android/src/main/AndroidManifest.xml
new file mode 100644
index 0000000..a5918e6
--- /dev/null
+++ b/echo/android/src/main/AndroidManifest.xml
@@ -0,0 +1,4 @@
+
+Warning
+This documentation is actively being developed and links may change.
+