capacitor-sora-editor 1.0.10 → 1.2.0

package/DEPENDENCY_SOLUTION.md

@@ -0,0 +1,87 @@
+# Dependency Solution: Full Source Integration (Standalone Mode)
+
+## Problem Statement
+
+This Capacitor plugin (`capacitor-sora-editor`) needs to include the `sora-editor` library. We initially tried:
+1. **Local Project Dependency** ❌ (Fails for end-users without source)
+2. **JitPack Build** ❌ (Unreliable, environment errors)
+3. **Remote AAR via Ivy** ❌ (Requires manual GitHub Release uploads and complex Gradle configuration for consumers)
+4. **Local AAR Bundling** ❌ (Strict Gradle restriction for Library modules)
+
+## Final (Best) Solution: Full Source Integration
+
+We have integrated the primary modules of `sora-editor` directly into the plugin as source code. This makes the plugin **completely standalone** and **zero-configuration** for users.
+
+### Architecture
+
+The following modules from `sora-editor` have been copied into `capacitor-sora-editor/android/sora-editor/`:
+- `editor`: The core editor UI and logic.
+- `language-textmate`: TextMate grammar support.
+- `oniguruma-native`: JNI bindings for the Oniguruma regex engine.
+
+### Implementation Details
+
+#### 1. Source Sets Configuration
+In the plugin's `android/build.gradle`, we manually include these source directories in the `main` sourceSet:
+
+```gradle
+sourceSets {
+    main {
+        java.srcDirs = [
+            'src/main/java',
+            'sora-editor/editor/src/main/java',
+            'sora-editor/language-textmate/src/main/java',
+            'sora-editor/oniguruma-native/src/main/java'
+        ]
+        res.srcDirs = [
+            'src/main/res',
+            'sora-editor/editor/src/main/res',
+            'sora-editor/language-textmate/src/main/res',
+            'sora-editor/oniguruma-native/src/main/res'
+        ]
+        assets.srcDirs = [
+            'src/main/assets',
+            'sora-editor/editor/src/main/assets',
+            'sora-editor/language-textmate/src/main/assets',
+            'sora-editor/oniguruma-native/src/main/assets'
+        ]
+    }
+}
+```
+
+#### 2. Native Build (C++)
+The Oniguruma engine is compiled using CMake directly from the integrated source:
+
+```gradle
+externalNativeBuild {
+    cmake {
+        path = file("sora-editor/oniguruma-native/src/main/cpp/CMakeLists.txt")
+        version = "3.22.1"
+    }
+}
+ndkVersion = "29.0.14206865"
+```
+
+#### 3. Module Namespace
+To match the existing source code packagename and resource references, the plugin's `namespace` is set to:
+`io.github.abc15018045126.sora`
+
+## Why This is the Best Approach
+
+| Feature | Remote AAR | Source Integration |
+|---------|------------|--------------------|
+| **Setup for Users** | Complex (Requires Ivy repo config) | **Zero (Standard npm install)** |
+| **Development** | Slow (Build -> Upload -> Download) | **Fast (Direct source edits)** |
+| **Stability** | Depends on remote server | **Self-contained** |
+| **Binary Size** | Fixed | Optimized by user's proguard/R8 |
+| **Sync Issues** | Common (missing AAR in build cache) | **None** |
+
+## Maintenance
+
+As the author, you can now modify the editor code directly within the plugin's `sora-editor` directory. These changes will be picked up immediately by any app using the local plugin (e.g., the `notes` app).
+
+When you are ready to release, simply:
+1. `npm version patch`
+2. `npm publish`
+
+The complete source code will be packaged into the npm tarball, and Gradle will compile it on the user's machine during their app's build process.

package/DEVELOPMENT.md

@@ -0,0 +1,152 @@
+# Development Workflow
+
+This document describes the development workflow for `capacitor-sora-editor` and its integration with the Notes applications.
+
+## Project Structure
+
+```
+notes/
+├── capacitor-sora-editor/         # Plugin source code (standalone)
+│   └── android/sora-editor/       # Integrated sora-editor source (CORE)
+├── sora-editor/                   # Original Android library source (External)
+├── notes/                         # Development app (uses local plugin)
+└── notes-new/                     # Testing app (uses npm published plugin)
+```
+
+## Development Environments
+
+### `notes` - Development Environment
+
+**Purpose**: Active development and debugging of `capacitor-sora-editor`.
+
+**Configuration**:
+```json
+{
+  "dependencies": {
+    "capacitor-sora-editor": "file:capacitor-sora-editor"
+  }
+}
+```
+
+**Usage**:
+- Modify plugin code directly in `capacitor-sora-editor/android/src`
+- Modify core editor code in `capacitor-sora-editor/android/sora-editor/`
+- Changes are immediately reflected upon rebuilding the app.
+
+### `notes-new` - Testing Environment
+
+**Purpose**: Validate published npm package as end-users would experience it.
+
+**Configuration**:
+```json
+{
+  "dependencies": {
+    "capacitor-sora-editor": "^1.1.0"
+  }
+}
+```
+
+**Usage**:
+- Install from npm registry.
+- Test the exact package users will receive.
+- No special Gradle configuration required for users.
+
+## Development Workflow
+
+### 1. Developing New Features
+
+Work in the `notes` project for rapid iteration. You can modify either the plugin wrapper or the editor core:
+
+```bash
+cd notes
+
+# 1. Edit code in capacitor-sora-editor/android/
+#    - Wrapper: src/main/java/...
+#    - Core Editor: sora-editor/editor/...
+
+# 2. Build and test
+npm run build
+npx cap sync android
+cd android && ./gradlew.bat assembleDebug
+
+# 3. Install to device
+./gradlew.bat installDebug
+```
+
+### 2. Updating Core Logic (sora-editor)
+
+Since the source is integrated, you no longer need to build AARs or upload to GitHub Releases for functional updates. Simply editing the files in `capacitor-sora-editor/android/sora-editor/` is enough for local development.
+
+## Publishing Workflow
+
+When you are satisfied with your changes and want to release to npm:
+
+### Step 1: Bump Version & Build
+
+```bash
+cd capacitor-sora-editor
+
+# Update version (e.g., 1.1.0 -> 1.1.1)
+npm version patch
+
+# Build the web part of the plugin
+npm run build
+```
+
+### Step 2: Publish to npm
+
+```bash
+cd capacitor-sora-editor
+npm publish
+```
+
+The entire `android/sora-editor` source tree will be included in the npm package.
+
+### Step 3: Validate in notes-new
+
+```bash
+cd notes-new
+
+# Install the latest version
+npm install capacitor-sora-editor@latest
+
+# Standard Capacitor sync and build
+npx cap sync android
+cd android && ./gradlew.bat assembleDebug
+```
+
+## Troubleshooting
+
+### Issue: "Unresolved reference: R"
+
+**Cause**: Package namespace mismatch.
+**Solution**: The plugin namespace is set to `io.github.abc15018045126.sora` in `android/build.gradle` to match the core editor's resource usage. Ensure all new activity/fragment code uses the correct R import if necessary.
+
+### Issue: C++ Compilation Errors
+
+**Cause**: Missing NDK or CMake issues.
+**Solution**: Ensure you have NDK `29.0.14206865` installed via Android Studio SDK Manager. The build will automatically compile the Oniguruma engine using CMake.
+
+### Issue: Changes not reflected
+
+**Cause**: Gradle cache.
+**Solution**:
+```bash
+cd android
+./gradlew.bat clean
+```
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Local Test | `cd notes && npm run build && npx cap sync android` |
+| Sync Android | `npx cap sync android` |
+| Build (Dev) | `cd android && ./gradlew.bat assembleDebug` |
+| Install | `cd android && ./gradlew.bat installDebug` |
+| Publish | `cd capacitor-sora-editor && npm publish` |
+
+## Related Documentation
+
+- [DEPENDENCY_SOLUTION.md](./DEPENDENCY_SOLUTION.md) - Why we use source integration.
+- [NO_JITPACK_WARNING.md](./NO_JITPACK_WARNING.md) - Why we avoid JitPack.

package/android/build.gradle

@@ -21,12 +21,18 @@ apply plugin: 'kotlin-android'
 apply plugin: 'org.jetbrains.kotlin.plugin.compose'
 
 android {
-    namespace "com.abc15018045126.capacitor.soraeditor"
+    namespace "io.github.abc15018045126.sora"
     compileSdk project.ext.compileSdkVersion
 
     defaultConfig {
         minSdk project.ext.minSdkVersion
         targetSdk project.ext.targetSdkVersion
+        
+        externalNativeBuild {
+            cmake {
+                cppFlags ""
+            }
+        }
     }
 
     compileOptions {
@@ -47,33 +53,66 @@ android {
 
     buildFeatures {
         compose true
+        buildConfig true
+    }
+
+    sourceSets {
+        main {
+            java.srcDirs = [
+                'src/main/java',
+                'sora-editor/editor/src/main/java',
+                'sora-editor/language-textmate/src/main/java',
+                'sora-editor/oniguruma-native/src/main/java'
+            ]
+            res.srcDirs = [
+                'src/main/res',
+                'sora-editor/editor/src/main/res',
+                'sora-editor/language-textmate/src/main/res',
+                'sora-editor/oniguruma-native/src/main/res'
+            ]
+            assets.srcDirs = [
+                'src/main/assets',
+                'sora-editor/editor/src/main/assets',
+                'sora-editor/language-textmate/src/main/assets',
+                'sora-editor/oniguruma-native/src/main/assets'
+            ]
+        }
+    }
+
+    externalNativeBuild {
+        cmake {
+            path = file("sora-editor/oniguruma-native/src/main/cpp/CMakeLists.txt")
+            version = "3.22.1"
+        }
     }
+    
+    // Required NDK version for Oniguruma-native
+    ndkVersion = "29.0.14206865"
 }
 
 repositories {
     google()
     mavenCentral()
-    ivy {
-        url 'https://github.com/abc15018045126/sora-editor/releases/download/v0.0.7/'
-        patternLayout {
-            artifact '[artifact].[ext]'
-        }
-        metadataSources { artifact() }
-    }
 }
 
 dependencies {
     implementation fileTree(dir: 'libs', include: ['*.jar'])
     implementation project(':capacitor-android')
+    
+    // Core Android dependencies
     implementation "androidx.appcompat:appcompat:1.7.0"
     implementation "androidx.core:core-ktx:1.15.0"
+    implementation "androidx.annotation:annotation:1.9.1"
+    implementation "androidx.collection:collection:1.4.5"
     
-    implementation 'sora-editor:editor-release:v0.0.7@aar'
-    
-    // Local Sora Editor project for local builds (commented for distribution)
-    // implementation project(':sora-editor')
+    // Editor dependencies (extracted from sora-editor modules)
+    implementation "com.google.code.gson:gson:2.13.2"
+    implementation "org.snakeyaml:snakeyaml-engine:3.0.1"
+    implementation "org.eclipse.jdt:org.eclipse.jdt.annotation:2.4.100"
     
-
+    // Textmate engine components
+    implementation "org.jruby.jcodings:jcodings:1.0.63"
+    implementation "org.jruby.joni:joni:2.2.6"
 
     // Compose
     def composeBom = platform('androidx.compose:compose-bom:2024.12.01')

package/android/sora-editor/editor/src/main/AndroidManifest.xml

@@ -0,0 +1,27 @@
+<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  ~    sora-editor - the awesome code editor for Android
+  ~    https://github.com/abc15018045126/sora-editor
+  ~    Copyright (C) 2020-2024  abc15018045126
+  ~
+  ~     This library is free software; you can redistribute it and/or
+  ~     modify it under the terms of the GNU Lesser General Public
+  ~     License as published by the Free Software Foundation; either
+  ~     version 2.1 of the License, or (at your option) any later version.
+  ~
+  ~     This library is distributed in the hope that it will be useful,
+  ~     but WITHOUT ANY WARRANTY; without even the implied warranty of
+  ~     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+  ~     Lesser General Public License for more details.
+  ~
+  ~     You should have received a copy of the GNU Lesser General Public
+  ~     License along with this library; if not, write to the Free Software
+  ~     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
+  ~     USA
+  ~
+  ~     Please contact abc15018045126 by email 2073412493@qq.com if you need
+  ~     additional information or have any questions
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
+
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+</manifest>

package/android/sora-editor/editor/src/main/java/io/github/abc15018045126/sora/I18nConfig.java

@@ -0,0 +1,69 @@
+/*
+ *    sora-editor - the awesome code editor for Android
+ *    https://github.com/abc15018045126/sora-editor
+ *    Copyright (C) 2020-2024  abc15018045126
+ *
+ *     This library is free software; you can redistribute it and/or
+ *     modify it under the terms of the GNU Lesser General Public
+ *     License as published by the Free Software Foundation; either
+ *     version 2.1 of the License, or (at your option) any later version.
+ *
+ *     This library is distributed in the hope that it will be useful,
+ *     but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *     Lesser General Public License for more details.
+ *
+ *     You should have received a copy of the GNU Lesser General Public
+ *     License along with this library; if not, write to the Free Software
+ *     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
+ *     USA
+ *
+ *     Please contact abc15018045126 by email 2073412493@qq.com if you need
+ *     additional information or have any questions
+ */
+package io.github.abc15018045126.sora;
+
+import android.content.Context;
+import android.util.SparseIntArray;
+
+import androidx.annotation.NonNull;
+
+/**
+ * Map editor built-in string resources to your given string resource. Editor string resource has
+ * limited i18n function, as it only contains English and Chinese.
+ * <p>
+ * Note that you should configure this before creating editor instances
+ *
+ * @author abc15018045126
+ */
+public class I18nConfig {
+
+    private static final SparseIntArray mapping = new SparseIntArray();
+
+    /**
+     * Map the given editor resId to new one
+     */
+    public static void mapTo(int originalResId, int newResId) {
+        mapping.put(originalResId, newResId);
+    }
+
+    /**
+     * Get mapped resource id or itself
+     */
+    public static int getResourceId(int resId) {
+        int newResource = mapping.get(resId);
+        if (newResource == 0) {
+            return resId;
+        }
+        return newResource;
+    }
+
+    /**
+     * Get mapped resource string
+     */
+    public static String getString(@NonNull Context context, int resId) {
+        return context.getString(getResourceId(resId));
+    }
+
+}
+

package/android/sora-editor/editor/src/main/java/io/github/abc15018045126/sora/annotations/Experimental.java

@@ -0,0 +1,41 @@
+/*
+ *    sora-editor - the awesome code editor for Android
+ *    https://github.com/abc15018045126/sora-editor
+ *    Copyright (C) 2020-2024  abc15018045126
+ *
+ *     This library is free software; you can redistribute it and/or
+ *     modify it under the terms of the GNU Lesser General Public
+ *     License as published by the Free Software Foundation; either
+ *     version 2.1 of the License, or (at your option) any later version.
+ *
+ *     This library is distributed in the hope that it will be useful,
+ *     but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *     Lesser General Public License for more details.
+ *
+ *     You should have received a copy of the GNU Lesser General Public
+ *     License along with this library; if not, write to the Free Software
+ *     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
+ *     USA
+ *
+ *     Please contact abc15018045126 by email 2073412493@qq.com if you need
+ *     additional information or have any questions
+ */
+package io.github.abc15018045126.sora.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * This annotation marks those fields, methods and constructors experimentally created.
+ * <p>
+ * Methods, fields and constructors with this annotation is very subject to keep or delete.
+ * For that reason, they are not stable for production use.
+ */
+@Target({ElementType.FIELD, ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.TYPE})
+@Retention(RetentionPolicy.SOURCE)
+public @interface Experimental {
+}
+

package/android/sora-editor/editor/src/main/java/io/github/abc15018045126/sora/annotations/InvalidateRequired.java

@@ -0,0 +1,40 @@
+/*
+ *    sora-editor - the awesome code editor for Android
+ *    https://github.com/abc15018045126/sora-editor
+ *    Copyright (C) 2020-2024  abc15018045126
+ *
+ *     This library is free software; you can redistribute it and/or
+ *     modify it under the terms of the GNU Lesser General Public
+ *     License as published by the Free Software Foundation; either
+ *     version 2.1 of the License, or (at your option) any later version.
+ *
+ *     This library is distributed in the hope that it will be useful,
+ *     but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *     Lesser General Public License for more details.
+ *
+ *     You should have received a copy of the GNU Lesser General Public
+ *     License along with this library; if not, write to the Free Software
+ *     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
+ *     USA
+ *
+ *     Please contact abc15018045126 by email 2073412493@qq.com if you need
+ *     additional information or have any questions
+ */
+package io.github.abc15018045126.sora.annotations;
+
+import android.view.View;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks you must call {@link View#invalidate()} after changing this property
+ */
+@Retention(RetentionPolicy.CLASS)
+@Target({ElementType.FIELD})
+public @interface InvalidateRequired {
+}
+

package/android/sora-editor/editor/src/main/java/io/github/abc15018045126/sora/annotations/UnsupportedUserUsage.java

@@ -0,0 +1,39 @@
+/*
+ *    sora-editor - the awesome code editor for Android
+ *    https://github.com/abc15018045126/sora-editor
+ *    Copyright (C) 2020-2024  abc15018045126
+ *
+ *     This library is free software; you can redistribute it and/or
+ *     modify it under the terms of the GNU Lesser General Public
+ *     License as published by the Free Software Foundation; either
+ *     version 2.1 of the License, or (at your option) any later version.
+ *
+ *     This library is distributed in the hope that it will be useful,
+ *     but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *     Lesser General Public License for more details.
+ *
+ *     You should have received a copy of the GNU Lesser General Public
+ *     License along with this library; if not, write to the Free Software
+ *     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
+ *     USA
+ *
+ *     Please contact abc15018045126 by email 2073412493@qq.com if you need
+ *     additional information or have any questions
+ */
+package io.github.abc15018045126.sora.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks that this member is internally used and that it is not recommended using this
+ * member at your side.
+ */
+@Retention(RetentionPolicy.CLASS)
+@Target({ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR, ElementType.TYPE})
+public @interface UnsupportedUserUsage {
+}
+

package/android/sora-editor/editor/src/main/java/io/github/abc15018045126/sora/event/ClickEvent.java

@@ -0,0 +1,49 @@
+/*
+ *    sora-editor - the awesome code editor for Android
+ *    https://github.com/abc15018045126/sora-editor
+ *    Copyright (C) 2020-2024  abc15018045126
+ *
+ *     This library is free software; you can redistribute it and/or
+ *     modify it under the terms of the GNU Lesser General Public
+ *     License as published by the Free Software Foundation; either
+ *     version 2.1 of the License, or (at your option) any later version.
+ *
+ *     This library is distributed in the hope that it will be useful,
+ *     but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *     Lesser General Public License for more details.
+ *
+ *     You should have received a copy of the GNU Lesser General Public
+ *     License along with this library; if not, write to the Free Software
+ *     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
+ *     USA
+ *
+ *     Please contact abc15018045126 by email 2073412493@qq.com if you need
+ *     additional information or have any questions
+ */
+package io.github.abc15018045126.sora.event;
+
+import android.view.MotionEvent;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+
+import io.github.abc15018045126.sora.lang.styling.Span;
+import io.github.abc15018045126.sora.text.CharPosition;
+import io.github.abc15018045126.sora.text.TextRange;
+import io.github.abc15018045126.sora.widget.CodeEditor;
+
+/**
+ * Report a single click
+ *
+ * @author abc15018045126
+ */
+public class ClickEvent extends EditorMotionEvent {
+
+    public ClickEvent(@NonNull CodeEditor editor, @NonNull CharPosition position, @NonNull MotionEvent event,
+                      @Nullable Span span, @Nullable TextRange spanRange, int motionRegion, int motionBound) {
+        super(editor, position, event, span, spanRange, motionRegion, motionBound);
+    }
+
+}
+

package/android/sora-editor/editor/src/main/java/io/github/abc15018045126/sora/event/ColorSchemeUpdateEvent.kt

@@ -0,0 +1,43 @@
+/*******************************************************************************
+ *    sora-editor - the awesome code editor for Android
+ *    https://github.com/abc15018045126/sora-editor
+ *    Copyright (C) 2020-2024  abc15018045126
+ *
+ *     This library is free software; you can redistribute it and/or
+ *     modify it under the terms of the GNU Lesser General Public
+ *     License as published by the Free Software Foundation; either
+ *     version 2.1 of the License, or (at your option) any later version.
+ *
+ *     This library is distributed in the hope that it will be useful,
+ *     but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *     Lesser General Public License for more details.
+ *
+ *     You should have received a copy of the GNU Lesser General Public
+ *     License along with this library; if not, write to the Free Software
+ *     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
+ *     USA
+ *
+ *     Please contact abc15018045126 by email 2073412493@qq.com if you need
+ *     additional information or have any questions
+ ******************************************************************************/
+
+package io.github.abc15018045126.sora.event
+
+import io.github.abc15018045126.sora.widget.CodeEditor
+
+/**
+ * Event trigger when any updates to the editor color scheme, including setting a new color and setting
+ *  a new color scheme
+ *
+ *  @author abc15018045126
+ */
+class ColorSchemeUpdateEvent(editor: CodeEditor) : Event(editor) {
+
+    /**
+     * Updated color scheme (the new one if new color scheme is set)
+     */
+    val colorScheme
+        get() = editor.colorScheme
+
+}