@canvist/react-native 0.0.0 → 0.2.0

package/ios/CanvistEditorComponentView.mm

@@ -0,0 +1,132 @@
+#import "CanvistEditorComponentView.h"
+
+#import <react/renderer/components/CanvistReactNativeSpec/ComponentDescriptors.h>
+#import <react/renderer/components/CanvistReactNativeSpec/EventEmitters.h>
+#import <react/renderer/components/CanvistReactNativeSpec/Props.h>
+#import <react/renderer/components/CanvistReactNativeSpec/RCTComponentViewHelpers.h>
+
+#import "CanvistSwift.h"
+
+using namespace facebook::react;
+
+@interface CanvistEditorComponentView () <RCTCanvistEditorViewViewProtocol>
+@end
+
+@implementation CanvistEditorComponentView {
+  CanvistHostView *_host;
+}
+
++ (ComponentDescriptorProvider)componentDescriptorProvider
+{
+  return concreteComponentDescriptorProvider<CanvistEditorViewComponentDescriptor>();
+}
+
+// Each view owns one editor for its whole life, created from its first props.
++ (BOOL)shouldBeRecycled
+{
+  return NO;
+}
+
+- (instancetype)initWithFrame:(CGRect)frame
+{
+  if (self = [super initWithFrame:frame]) {
+    static const auto defaultProps = std::make_shared<const CanvistEditorViewProps>();
+    _props = defaultProps;
+    _host = [CanvistHostView new];
+    self.contentView = _host;
+
+    __weak CanvistEditorComponentView *weakSelf = self;
+    _host.onReady = ^(NSString *editorId) {
+      if (auto emitter = [weakSelf editorEventEmitter]) {
+        emitter->onEditorReady({.editorId = std::string(editorId.UTF8String)});
+      }
+    };
+    _host.onChange = ^(BOOL document, BOOL selection, BOOL composition) {
+      if (auto emitter = [weakSelf editorEventEmitter]) {
+        emitter->onEditorChange({.document = (bool)document, .selection = (bool)selection, .composition = (bool)composition});
+      }
+    };
+    _host.onFocusChange = ^(BOOL focused) {
+      if (auto emitter = [weakSelf editorEventEmitter]) {
+        emitter->onEditorFocus({.focused = (bool)focused});
+      }
+    };
+    _host.onError = ^(NSString *code, NSString *message) {
+      if (auto emitter = [weakSelf editorEventEmitter]) {
+        emitter->onEditorError({.code = std::string(code.UTF8String), .message = std::string(message.UTF8String)});
+      }
+    };
+  }
+
+  return self;
+}
+
+- (void)dealloc
+{
+  [_host stop];
+}
+
+- (std::shared_ptr<const CanvistEditorViewEventEmitter>)editorEventEmitter
+{
+  return std::static_pointer_cast<const CanvistEditorViewEventEmitter>(_eventEmitter);
+}
+
+- (void)updateProps:(Props::Shared const &)props oldProps:(Props::Shared const &)oldProps
+{
+  const auto &oldViewProps = *std::static_pointer_cast<const CanvistEditorViewProps>(_props);
+  const auto &newViewProps = *std::static_pointer_cast<const CanvistEditorViewProps>(props);
+
+  if (oldViewProps.fontSize != newViewProps.fontSize) {
+    _host.fontSize = newViewProps.fontSize;
+  }
+
+  if (oldViewProps.accessibilityLabel != newViewProps.accessibilityLabel) {
+    _host.accessibilityLabel = newViewProps.accessibilityLabel.empty()
+        ? nil
+        : [NSString stringWithUTF8String:newViewProps.accessibilityLabel.c_str()];
+  }
+
+  [super updateProps:props oldProps:oldProps];
+}
+
+// The editor starts once the first transaction has mounted, when the event
+// emitter that announces it exists.
+- (void)finalizeUpdates:(RNComponentViewUpdateMask)updateMask
+{
+  [super finalizeUpdates:updateMask];
+
+  const auto &props = *std::static_pointer_cast<const CanvistEditorViewProps>(_props);
+
+  if (props.editorId.empty()) {
+    return;
+  }
+
+  NSMutableArray<NSString *> *extensions = [NSMutableArray arrayWithCapacity:props.extensions.size()];
+  for (const auto &name : props.extensions) {
+    [extensions addObject:[NSString stringWithUTF8String:name.c_str()]];
+  }
+
+  NSString *format = props.contentFormat.empty() ? nil : [NSString stringWithUTF8String:props.contentFormat.c_str()];
+  NSString *content = props.content.empty() ? nil : [NSString stringWithUTF8String:props.content.c_str()];
+  [_host startWithEditorId:[NSString stringWithUTF8String:props.editorId.c_str()]
+                extensions:extensions
+                    format:format
+                   content:content];
+}
+
+- (void)handleCommand:(const NSString *)commandName args:(const NSArray *)args
+{
+  RCTCanvistEditorViewHandleCommand(self, commandName, args);
+}
+
+- (void)focus
+{
+  [_host focus];
+}
+
+- (void)blur
+{
+  [_host blur];
+}
+
+@end

package/ios/CanvistEditorsModule.h

@@ -0,0 +1,10 @@
+#import <CanvistReactNativeSpec/CanvistReactNativeSpec.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// The `CanvistEditors` TurboModule: synchronous calls into the editors of
+/// mounted `CanvistEditorView`s.
+@interface CanvistEditorsModule : NSObject <NativeCanvistEditorsSpec>
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/CanvistEditorsModule.mm

@@ -0,0 +1,101 @@
+#import "CanvistEditorsModule.h"
+
+#import "CanvistSwift.h"
+
+// Every method runs synchronously on the JavaScript thread. A failure raises
+// an exception, which React Native rethrows in JavaScript with its reason:
+// `[canvist:<code>] <message>`.
+static id Checked(id result, NSError *error)
+{
+  if (result == nil) {
+    @throw [NSException exceptionWithName:@"CanvistError" reason:error.localizedDescription userInfo:nil];
+  }
+
+  return result;
+}
+
+#define CANVIST_CALL(expression)               \
+  ({                                           \
+    NSError *error = nil;                      \
+    id result = [CanvistHostCalls expression]; \
+    Checked(result, error);                    \
+  })
+
+@implementation CanvistEditorsModule
+
++ (NSString *)moduleName
+{
+  return @"CanvistEditors";
+}
+
+- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:(const facebook::react::ObjCTurboModule::InitParams &)params
+{
+  return std::make_shared<facebook::react::NativeCanvistEditorsSpecJSI>(params);
+}
+
+- (NSNumber *)run:(NSString *)editorId name:(NSString *)name args:(NSString *)args
+{
+  return CANVIST_CALL(runWithId:editorId name:name args:args error:&error);
+}
+
+- (NSNumber *)can:(NSString *)editorId name:(NSString *)name args:(NSString *)args
+{
+  return CANVIST_CALL(canWithId:editorId name:name args:args error:&error);
+}
+
+- (NSString *)query:(NSString *)editorId name:(NSString *)name args:(NSString *)args
+{
+  return CANVIST_CALL(queryWithId:editorId name:name args:args error:&error);
+}
+
+- (NSNumber *)load:(NSString *)editorId format:(NSString *)format content:(NSString *)content
+{
+  return CANVIST_CALL(loadWithId:editorId format:format content:content error:&error);
+}
+
+- (NSString *)exportDocument:(NSString *)editorId format:(NSString *)format
+{
+  return CANVIST_CALL(exportWithId:editorId format:format error:&error);
+}
+
+- (NSString *)selection:(NSString *)editorId
+{
+  return CANVIST_CALL(selectionWithId:editorId error:&error);
+}
+
+- (NSNumber *)select:(NSString *)editorId range:(NSString *)range
+{
+  return CANVIST_CALL(selectWithId:editorId range:range error:&error);
+}
+
+- (NSNumber *)selectAll:(NSString *)editorId
+{
+  return CANVIST_CALL(selectAllWithId:editorId error:&error);
+}
+
+- (NSNumber *)insertText:(NSString *)editorId text:(NSString *)text
+{
+  return CANVIST_CALL(insertTextWithId:editorId text:text error:&error);
+}
+
+- (NSNumber *)undo:(NSString *)editorId
+{
+  return CANVIST_CALL(undoWithId:editorId error:&error);
+}
+
+- (NSNumber *)redo:(NSString *)editorId
+{
+  return CANVIST_CALL(redoWithId:editorId error:&error);
+}
+
+- (NSNumber *)canUndo:(NSString *)editorId
+{
+  return CANVIST_CALL(canUndoWithId:editorId error:&error);
+}
+
+- (NSNumber *)canRedo:(NSString *)editorId
+{
+  return CANVIST_CALL(canRedoWithId:editorId error:&error);
+}
+
+@end

package/ios/CanvistSwift.h

@@ -0,0 +1,3 @@
+// The Objective-C face of the `Canvist` pod's Swift: `CanvistHostView` and
+// `CanvistHostCalls`. The podspec puts its directory on the search path.
+#import "Canvist-Swift.h"

package/package.json

@@ -1 +1,94 @@
-{"description":"Placeholder package for @canvist/react-native","name":"@canvist/react-native","repository":"https://github.com/canvist/canvist","version":"0.0.0"}
+{
+	"name": "@canvist/react-native",
+	"version": "0.2.0",
+	"description": "The canvist rich-text editor for React Native: the native iOS and Android editors as a Fabric component, with commands and queries typed from the extensions you register.",
+	"license": "Unlicense",
+	"homepage": "https://github.com/canvist/canvist/tree/main/packages/canvist-react-native#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/canvist/canvist.git",
+		"directory": "packages/canvist-react-native"
+	},
+	"bugs": {
+		"url": "https://github.com/canvist/canvist/issues",
+		"email": "support@canvist.dev"
+	},
+	"keywords": [
+		"react-native",
+		"rich-text",
+		"editor",
+		"ios",
+		"android",
+		"fabric"
+	],
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/mod.d.ts",
+			"react-native": "./src/mod.ts"
+		},
+		"./package.json": "./package.json"
+	},
+	"files": [
+		"dist",
+		"src",
+		"ios",
+		"android/build.gradle",
+		"android/src/main",
+		"CanvistReactNative.podspec"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"check:types": "tsc --noEmit",
+		"test": "jest",
+		"build": "tsc -p tsconfig.build.json",
+		"prepack": "npm run build"
+	},
+	"dependencies": {
+		"@canvist/headless": "^0.2.0"
+	},
+	"peerDependencies": {
+		"react": "^19.0.0",
+		"react-native": ">=0.80.0"
+	},
+	"devDependencies": {
+		"@react-native/babel-preset": "0.88.0",
+		"@react-native/jest-preset": "0.88.0",
+		"@testing-library/react-native": "^14.1.0",
+		"@types/jest": "^29.5.14",
+		"@types/react": "^19.2.0",
+		"jest": "^29.7.0",
+		"react": "19.3.0",
+		"react-native": "0.88.0",
+		"test-renderer": "^1.3.1",
+		"typescript": "^7.0.2"
+	},
+	"codegenConfig": {
+		"name": "CanvistReactNativeSpec",
+		"type": "all",
+		"jsSrcsDir": "src",
+		"android": {
+			"javaPackageName": "io.github.ifiokjr.canvist.reactnative"
+		},
+		"ios": {
+			"componentProvider": {
+				"CanvistEditorView": "CanvistEditorComponentView"
+			},
+			"modulesProvider": {
+				"CanvistEditors": "CanvistEditorsModule"
+			}
+		}
+	},
+	"jest": {
+		"preset": "@react-native/jest-preset",
+		"testMatch": [
+			"<rootDir>/tests/**/*.test.ts?(x)"
+		],
+		"transformIgnorePatterns": [
+			"node_modules/(?!((jest-)?react-native|@react-native(-community)?|@canvist)/)"
+		],
+		"modulePaths": [
+			"<rootDir>/node_modules"
+		]
+	}
+}

package/readme.md

@@ -0,0 +1,105 @@
+<p align="center">
+  <a href="https://github.com/canvist/canvist">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/canvist/canvist/main/assets/brand/vector/lockup-dark.svg">
+      <img width="220" src="https://raw.githubusercontent.com/canvist/canvist/main/assets/brand/vector/lockup.svg" alt="canvist" />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/canvist/canvist/blob/main/docs/src/quick-start/react-native.md"><strong>Quick start</strong></a> ·
+  <a href="https://github.com/canvist/canvist/blob/main/docs/src/readme.md"><strong>Docs</strong></a> ·
+  <a href="https://github.com/canvist/canvist/blob/main/docs/src/reference/contributing.md"><strong>Contributing</strong></a> ·
+  <a href="https://github.com/canvist/canvist"><strong>canvist</strong></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/canvist/canvist/actions/workflows/react-native.yml"><img src="https://github.com/canvist/canvist/actions/workflows/react-native.yml/badge.svg?branch=main" alt="react-native status" /></a>
+  <a href="https://unlicense.org"><img src="https://img.shields.io/badge/license-Unlicense-3B2CF5" alt="Unlicense" /></a>
+</p>
+
+# @canvist/react-native
+
+canvist's rich-text editor for React Native: the native iOS and Android `CanvistView`s as a Fabric component, not a WebView. Typing goes through each platform's own text input (the keyboard, input methods, autocorrect, dictation, selection handles), and the Rust engine lays out and paints every line. Commands, queries, and documents are typed from the extensions you register, with the same API as [`@canvist/web`](../canvist-web).
+
+```tsx
+import { CanvistEditor } from "@canvist/react-native";
+
+<CanvistEditor
+	content={{ format: "markdown", input: "# Notes" }}
+	onUpdate={(editor) => save(editor.export("markdown"))}
+	accessibilityLabel="Note"
+	style={{ flex: 1 }}
+/>;
+```
+
+Needs React Native 0.80 or newer with the New Architecture, iOS 17, and Android 7 (API 24).
+
+## A toolbar that follows the selection
+
+`useCanvistEditor` gives you the editor and the props for its view; `useEditorState` re-renders when something you read changes. Calls are synchronous, so a query answers at once:
+
+```tsx
+import {
+	bold,
+	CanvistView,
+	heading,
+	useCanvistEditor,
+	useEditorState,
+} from "@canvist/react-native";
+
+function Notes() {
+	const { editor, props } = useCanvistEditor({ extensions: [bold, heading] });
+	const isBold = useEditorState(editor, (e) => e.query.isBold(), false);
+
+	return (
+		<>
+			<Button
+				title={isBold ? "Unbold" : "Bold"}
+				onPress={() => editor?.commands.toggleBold()}
+			/>
+			<CanvistView {...props} style={{ flex: 1 }} />
+		</>
+	);
+}
+```
+
+Only registered extensions have commands: with `[bold, heading]`, `editor.commands.toggleItalic()` is a type error, and so is `setHeading({ level: 7 })`.
+
+## The editor
+
+`editor` is `null` until the native view has created its editor. Then it offers:
+
+- `commands`, `can`, and `query`, one method per registered command and query, plus `run`, `canRun`, and `ask` by name.
+- `setContent(content)`, `export(format)` (`"json"`, `"html"`, `"markdown"`, or `"text"`), and `toJson()`.
+- `selection`, `select(anchor, head)`, `selectAll()`, and `insertText(text)`, which types as the keyboard does.
+- `undo()`, `redo()`, `canUndo()`, and `canRedo()`.
+- `focus()`, `blur()`, and `focused`.
+- `subscribe(listener)`, called after every change to the document, the selection, or focus.
+
+Failures throw a `CanvistError` with a stable `code`, as on every other platform.
+
+## Install
+
+The native editors aren't on a package registry yet, so build them from the repository. For iOS, add the `Canvist` pod to your Podfile after building it with `platforms/apple/build.sh`:
+
+```ruby
+pod "Canvist", path: "path/to/canvist/platforms/apple"
+```
+
+For Android, the package depends on `io.github.ifiokjr:canvist-android`; until it's on Maven Central, publish it to Maven Local with `platforms/android/build.sh` and `./gradlew :canvist:publishToMavenLocal`, and add `mavenLocal()` to your repositories. [`examples/react-native`](../../examples/react-native) is set up this way.
+
+<details>
+<summary><strong>Development</strong></summary>
+
+```sh
+npm test                                      # Jest: the typed editor, the view's props and events
+npx tsc --noEmit                              # types, including the type-level tests
+../../examples/react-native/e2e/test.sh ios   # the example in Release on a simulator, driven by Maestro
+../../examples/react-native/e2e/test.sh android
+```
+
+The package's `react-native` export is its TypeScript source: React Native's codegen reads the Fabric and TurboModule specs in `src/` when an app builds.
+
+</details>

package/src/CanvistEditorViewNativeComponent.ts

@@ -0,0 +1,63 @@
+/**
+ * The Fabric component spec for the native editor view: React Native's
+ * codegen reads this file to generate the iOS and Android glue, so it keeps
+ * to the shapes codegen understands.
+ *
+ * @module
+ */
+import type * as React from "react";
+import type { CodegenTypes, HostComponent, ViewProps } from "react-native";
+import { codegenNativeCommands, codegenNativeComponent } from "react-native";
+
+/** What changed, after every change to the document or selection. */
+export type EditorChangeEvent = Readonly<{
+	document: boolean;
+	selection: boolean;
+	composition: boolean;
+}>;
+
+/** The view gained or lost focus. */
+export type EditorFocusEvent = Readonly<{
+	focused: boolean;
+}>;
+
+/** The view could not create or load its editor. */
+export type EditorErrorEvent = Readonly<{
+	code: string;
+	message: string;
+}>;
+
+/** The view is ready for calls through the `CanvistEditors` module. */
+export type EditorReadyEvent = Readonly<{
+	editorId: string;
+}>;
+
+export interface NativeProps extends ViewProps {
+	/** The key the `CanvistEditors` module finds this view's editor by. */
+	editorId: string;
+	/** The extensions to register, by name. Read when the view is created. */
+	extensions: ReadonlyArray<string>;
+	/** The format of `content`. Read when the view is created. */
+	contentFormat?: string;
+	/** The document to start with. Read when the view is created. */
+	content?: string;
+	/** The body text size before the user's text size setting; 0 is the platform's default. */
+	fontSize?: CodegenTypes.WithDefault<CodegenTypes.Float, 0>;
+	onEditorReady?: CodegenTypes.DirectEventHandler<EditorReadyEvent>;
+	onEditorChange?: CodegenTypes.DirectEventHandler<EditorChangeEvent>;
+	onEditorFocus?: CodegenTypes.DirectEventHandler<EditorFocusEvent>;
+	onEditorError?: CodegenTypes.DirectEventHandler<EditorErrorEvent>;
+}
+
+export type CanvistEditorViewType = HostComponent<NativeProps>;
+
+interface NativeCommands {
+	focus: (viewRef: React.ElementRef<CanvistEditorViewType>) => void;
+	blur: (viewRef: React.ElementRef<CanvistEditorViewType>) => void;
+}
+
+export const Commands: NativeCommands = codegenNativeCommands<NativeCommands>({
+	supportedCommands: ["focus", "blur"],
+});
+
+export default codegenNativeComponent<NativeProps>("CanvistEditorView");

package/src/NativeCanvistEditors.ts

@@ -0,0 +1,33 @@
+/**
+ * The TurboModule spec for calls into a view's editor. Every method is
+ * synchronous on the JavaScript thread, so commands and queries answer at
+ * once, as they do on the web. Methods return a value even when there is
+ * nothing to say, because React Native runs `void` methods asynchronously.
+ *
+ * Failures throw with `[canvist:<code>] <reason>` in the message.
+ *
+ * @module
+ */
+import type { TurboModule } from "react-native";
+import { TurboModuleRegistry } from "react-native";
+
+export interface Spec extends TurboModule {
+	run(editorId: string, name: string, args: string): boolean;
+	can(editorId: string, name: string, args: string): boolean;
+	query(editorId: string, name: string, args: string): string;
+	/** Returns `true`. */
+	load(editorId: string, format: string, content: string): boolean;
+	exportDocument(editorId: string, format: string): string;
+	selection(editorId: string): string;
+	/** Returns whether the selection moved. */
+	select(editorId: string, range: string): boolean;
+	/** Returns whether the selection moved. */
+	selectAll(editorId: string): boolean;
+	insertText(editorId: string, text: string): boolean;
+	undo(editorId: string): boolean;
+	redo(editorId: string): boolean;
+	canUndo(editorId: string): boolean;
+	canRedo(editorId: string): boolean;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>("CanvistEditors");

package/src/bridge.ts

@@ -0,0 +1,64 @@
+/**
+ * The bridge from the typed editor to one native view: synchronous calls
+ * through the `CanvistEditors` TurboModule, and focus through the view's
+ * commands.
+ *
+ * @module
+ */
+import type { NativeBridge } from "@canvist/headless/native";
+import type * as React from "react";
+
+import {
+	type CanvistEditorViewType,
+	Commands,
+} from "./CanvistEditorViewNativeComponent.ts";
+import type { Spec } from "./NativeCanvistEditors.ts";
+
+/** The mounted native view, as React refers to it. */
+export type EditorViewInstance = React.ElementRef<CanvistEditorViewType>;
+
+/**
+ * A bridge to the editor `editorId` names through `module`, focusing the
+ * view `view` returns. Focus calls do nothing once the view is gone.
+ */
+export function nativeBridge(
+	module: Spec,
+	editorId: string,
+	view: () => EditorViewInstance | null,
+): NativeBridge {
+	return {
+		run: (name, args) => module.run(editorId, name, args),
+		can: (name, args) => module.can(editorId, name, args),
+		query: (name, args) => module.query(editorId, name, args),
+		load: (format, content) => {
+			module.load(editorId, format, content);
+		},
+		export: (format) => module.exportDocument(editorId, format),
+		selection: () => module.selection(editorId),
+		select: (range) => {
+			module.select(editorId, range);
+		},
+		selectAll: () => {
+			module.selectAll(editorId);
+		},
+		insertText: (text) => module.insertText(editorId, text),
+		undo: () => module.undo(editorId),
+		redo: () => module.redo(editorId),
+		canUndo: () => module.canUndo(editorId),
+		canRedo: () => module.canRedo(editorId),
+		focus: () => {
+			const instance = view();
+
+			if (instance !== null) {
+				Commands.focus(instance);
+			}
+		},
+		blur: () => {
+			const instance = view();
+
+			if (instance !== null) {
+				Commands.blur(instance);
+			}
+		},
+	};
+}