@eclosion-tech/react-native-yjs-text 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog
+
+## 0.1.0
+
+Initial release. See [`SPEC.md`](./SPEC.md) for the full design and the
+[`README`](./README.md) for usage.
+
+### Added
+
+- TypeScript layer
+  - `YTextInput`, `YTextRenderer`, `useYTextEditor`
+  - `defaultSchema` covering the v0.1 canonical mark set
+    (`bold`, `italic`, `underline`, `strike`, `code`, `link`)
+  - `Y.Text` ↔ runs delta translation with loop-breaking and
+    `Y.RelativePosition`-based caret stability
+- iOS native view (`YjsTextView`) backed by `UITextView`
+  - `NSAttributedString` rendering with schema-driven mark styles
+  - Edit capture via `textView(_:shouldChangeTextIn:replacementText:)`
+  - Focus / selection events, imperative `focus` / `blur` / `setSelection`
+- Android native view (`YjsTextView`) backed by `AppCompatEditText`
+  - `SpannableStringBuilder` rendering with the same schema-driven marks
+  - Edit capture via `TextWatcher`
+  - Focus / selection events, imperative methods matching iOS
+- Expo Modules registration and `expo-module.config.json` wiring
+- Example Expo app (`example/`) exercising every default mark and
+  programmatic mutations via `useYTextEditor`
+- Example bare RN app (`example-bare/`) using `@react-native-community/cli`
+  scaffolding with Expo Modules autolinking wired in via Podfile,
+  settings.gradle, `AppDelegate.swift`, and `MainApplication.kt`. Proves the
+  library installs without the Expo app shell.
+- pnpm workspace setup so the examples consume the library directly from
+  source, with Metro configs (one per example) that follow the workspace
+  symlink and block-list the library's hoisted `node_modules` to avoid
+  duplicate-React hook errors
+- Jest suite (59 tests, ~1.5s, `babel-jest` + jsdom env)
+  - `schema.test.ts` — `compileRenderSpec` / `validateMarks` (required attrs,
+    type checks, unknown-mark rejection, declared-default fallback)
+  - `bridge.test.ts` — `ytextToRuns`, `inheritedMarksAt`, `marksInRange`,
+    `applyReplaceEdit` (insert / delete / replace / inherit / sanitise /
+    null-out-on-violation), `formatRange` (origin tag + observer round-trip),
+    and round-trip stability of `Y.RelativePosition` selection across remote
+    edits
+  - `useYTextEditor.test.ts` — every imperative command driven through a
+    fake `EditorHandle`, including the collapsed-caret pending-mark
+    behaviour and the marks-at-selection overlay logic
+  - `YTextRenderer.test.tsx` — verifies merged underline+strike decorations
+    and that `null` / `false` mark values are not applied
+
+### Fixed (during initial build verification)
+
+- `applyReplaceEdit` actively `null`s out any inherited mark that fails the
+  schema sanitiser (instead of silently letting it leak into newly inserted
+  characters via Y.Text's default attribute inheritance). Also honours
+  `pendingMarks[mark] = false` as an explicit "do not inherit".
+- Android: switched `EditText.BufferType` → `TextView.BufferType`
+  (`EditText` doesn't re-expose the nested enum in Kotlin) and replaced the
+  deprecated `DisplayMetrics.scaledDensity` with
+  `TypedValue.applyDimension(COMPLEX_UNIT_SP, ...)`.
+- `formatRange` no longer tags its transaction with `ORIGIN_LOCAL_VIEW`, so
+  toolbar-driven format changes round-trip through the Y.Text observer and
+  trigger a re-render of the editor view (previously only the read-only
+  `YTextRenderer` would update on the first toggle).
+- `null` / `false` mark values are now treated as "explicitly off" everywhere
+  (JS renderer, iOS `attributes(for:)`, Android `applyRunSpans`) so a Y.Text
+  delta of `{ bold: null }` does not visually re-bold the affected run.
+- Selection prop is now sent to native as a single atomic
+  `pendingSelection: { from, to, version }` record. Splitting it into
+  separate `selection` + `selectionVersion` props was triggering Fabric prop
+  re-ordering races where the version setter fired before the range setter
+  and the caret jumped back to a stale selection.
+- `runs` setter on both iOS and Android now unconditionally rebuilds the
+  attributed/spannable text. The previous `contentVersion` companion prop
+  was racing with `runs` under Fabric (version setter fired first, runs
+  arrived second) and causing every format toggle to appear one edit
+  behind.
+- iOS native re-assignment of `attributedText` / Android re-assignment of
+  `editText.text` is now wrapped in a `suppressSelectionEvents` guard.
+  UIKit / Android both fire a synthetic selection-change to `{0, 0}` as
+  part of swapping the text in place; without the guard that
+  `onNativeSelectionChange` would overwrite JS's `selectionRef` and the
+  next toolbar tap would read a collapsed caret and silently do nothing.
+- iOS combined bold + italic on system fonts: `UIFontDescriptor`'s symbolic-
+  trait path drops `.traitBold` when `.traitItalic` is also requested.
+  `makeFont` now tries multiple descriptor paths and, when no true bold-
+  italic font can be resolved, returns an `NSObliqueness` slant on top of
+  the bold font so the user still sees both effects.
+
+### Known limitations (see `SPEC.md` § Versioning roadmap)
+
+- CJK / complex IME composition uses each platform's default editor
+  behaviour
+- Paste from clipboard does not preserve formatting attributes
+- Hardware keyboard shortcuts not bound by default
+- Android: applying `code` (or any other `backgroundColor` mark) over a
+  selected range visually masks the system selection highlight. The
+  selection is still active and toolbar toggles still apply to it; this is
+  a draw-order quirk of `BackgroundColorSpan` in the Android text pipeline.
+- All bridge traffic goes through the standard Expo Modules ABI (no JSI
+  fast path yet)

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-present 650 Industries, Inc. (aka Expo)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,323 @@
+# @eclosion-tech/react-native-yjs-text
+
+Native React Native rich text editor backed by `Y.Text`. **No WebView, no
+`contenteditable`, no DOM.**
+
+Built as an Expo Module — works in any Expo SDK 52+ project (and in bare RN
+projects via `expo-modules-core`).
+
+> **Status:** v0.1.0 — alpha. The TypeScript layer, Swift iOS view, and Kotlin
+> Android view all compile cleanly. Both example apps (Expo-managed in
+> `example/` and bare RN in `example-bare/`) link the library and produce a
+> working `.app` / `.apk`. A 50-case Jest suite covers the bridge, schema,
+> and editor hook. The remaining v0.1 work is on-device behavioural
+> verification (typing, mark toggling, caret stability under remote edits).
+
+---
+
+## Why this exists
+
+Every existing rich-text editor in React Native today wraps a browser editor
+in a `WebView`: `react-native-pell-rich-editor`, `@10play/tentap-editor`,
+`react-native-cn-quill`. They all pay the WebView tax — worse performance,
+broken keyboard behaviour, gesture / scroll conflicts, accessibility
+regressions, platform-specific bugs that don't reproduce in browsers.
+
+`Y.Text` is already a platform-independent rich-text primitive — a sequence of
+characters with arbitrary formatting attributes. That maps cleanly onto
+`contenteditable` (via `y-prosemirror` on the web) **and** onto
+`NSAttributedString` / `Spannable` on native mobile. This library is the
+native-view side of that binding.
+
+See [`SPEC.md`](./SPEC.md) for the full design rationale, non-goals, and
+versioning roadmap.
+
+## What ships in v0.1
+
+- `YTextInput` — editable view backed by `UITextView` (iOS) /
+  `AppCompatEditText` (Android)
+- `YTextRenderer` — read-only renderer that uses RN's native `<Text>` with
+  attributed spans (no `UITextView` instance, much cheaper)
+- `useYTextEditor` — imperative editor hook (`toggleMark`, `setMark`,
+  `removeMark`, `insertText`, `deleteRange`, `focus`, `blur`,
+  `getSelection`, `setSelection`, `marksAtSelection`)
+- `defaultSchema` — `bold`, `italic`, `underline`, `strike`, `code`, `link`
+  (matching the y-prosemirror mark convention so the same `Y.Text` content
+  edits identically on web)
+- Bidirectional sync between user edits and `Y.Text` mutations, with
+  `Y.RelativePosition`-based caret preservation across remote insertions
+
+## Install
+
+### Expo (managed or prebuild)
+
+```sh
+npx expo install @eclosion-tech/react-native-yjs-text yjs isomorphic-webcrypto
+npx expo prebuild         # if you don't already have native projects
+npx expo run:ios          # or run:android
+```
+
+Expo Go can't load the library (native code); you need a dev build.
+
+> **Why `isomorphic-webcrypto`?** yjs's underlying utility lib `lib0`
+> generates random doc / client IDs via `crypto.getRandomValues`. React
+> Native doesn't expose webcrypto by default, so `lib0`'s RN entry-point
+> hard-requires `isomorphic-webcrypto` and expects the consumer to install
+> it. (You can alternatively install `react-native-get-random-values` and
+> `import 'react-native-get-random-values'` *before* the first yjs import —
+> then `lib0` skips its webcrypto shim and uses the polyfilled native one.
+> Either works; pick whichever your app already has.)
+
+### Bare React Native (RNCLI scaffold, brownfield, etc.)
+
+The library uses the Expo Modules API for its native side, so a bare RN host
+needs Expo Modules autolinking. **This does not turn your app into "an Expo
+app"** — no app shell, no Expo Go runtime, no expo-router. You're only
+opting into native autolinking.
+
+```sh
+npm install @eclosion-tech/react-native-yjs-text yjs expo isomorphic-webcrypto
+# expo brings in expo-modules-core + the autolinking scripts; nothing else
+# isomorphic-webcrypto is required by yjs's lib0 dep — see the Expo section
+# above for the alternative `react-native-get-random-values` route
+```
+
+Then three small wiring changes:
+
+1.  **`ios/Podfile`** — load Expo's autolinking + call `use_expo_modules!`:
+
+    ```ruby
+    require File.join(
+      File.dirname(`node --print "require.resolve('expo/package.json')"`),
+      "scripts/autolinking"
+    )
+
+    platform :ios, '16.4'   # expo-modules-core requires 16.4+
+
+    target 'YourApp' do
+      use_expo_modules!
+      config = use_native_modules!
+      # ...rest of the standard RN Podfile target...
+    end
+    ```
+
+2.  **`ios/YourApp/AppDelegate.swift`** — subclass Expo's app-delegate /
+    factory wrappers so Expo Modules register at boot:
+
+    ```swift
+    internal import Expo   // matches the access level of the generated
+                           // ExpoModulesProvider.swift
+    import React
+    import ReactAppDependencyProvider
+
+    @main
+    class AppDelegate: ExpoAppDelegate {
+      var window: UIWindow?
+      var reactNativeDelegate: ExpoReactNativeFactoryDelegate?
+      var reactNativeFactory: RCTReactNativeFactory?
+
+      public override func application(/* ... */) -> Bool {
+        let delegate = ReactNativeDelegate()
+        let factory = ExpoReactNativeFactory(delegate: delegate)
+        delegate.dependencyProvider = RCTAppDependencyProvider()
+        reactNativeDelegate = delegate
+        reactNativeFactory = factory
+        window = UIWindow(frame: UIScreen.main.bounds)
+        factory.startReactNative(withModuleName: "YourApp",
+                                  in: window, launchOptions: launchOptions)
+        return super.application(application,
+                                 didFinishLaunchingWithOptions: launchOptions)
+      }
+    }
+
+    class ReactNativeDelegate: ExpoReactNativeFactoryDelegate { /* ... */ }
+    ```
+
+3.  **`android/settings.gradle`** — pull in the Expo autolinking gradle
+    plugin and call `expoAutolinking.useExpoModules()`. **`android/app/
+    src/main/java/.../MainApplication.kt`** — replace
+    `DefaultReactHost.getDefaultReactHost(...)` with
+    `ExpoReactHostFactory.getDefaultReactHost(...)` and add
+    `ApplicationLifecycleDispatcher.onApplicationCreate(this)` /
+    `onConfigurationChanged(this, newConfig)`.
+
+The complete working set of changes for a fresh `@react-native-community/
+cli init` project lives in [`example-bare/`](./example-bare/) — copy from
+there if you'd rather diff against a known-good reference than apply the
+snippets above by hand.
+
+## Usage
+
+```tsx
+import {
+  YTextInput,
+  YTextRenderer,
+  defaultSchema,
+  useYTextEditor,
+} from '@eclosion-tech/react-native-yjs-text';
+import * as Y from 'yjs';
+
+const doc = new Y.Doc();
+const yText = doc.getText('content');
+
+function Editor() {
+  const editor = useYTextEditor(yText, defaultSchema);
+  return (
+    <>
+      <Toolbar editor={editor} />
+      <YTextInput
+        yText={yText}
+        schema={defaultSchema}
+        style={{ fontSize: 16, color: '#111' }}
+        placeholder="Start typing…"
+      />
+      <YTextRenderer yText={yText} schema={defaultSchema} />
+    </>
+  );
+}
+
+function Toolbar({ editor }) {
+  return (
+    <View>
+      <Button onPress={() => editor.toggleMark('bold')} title="B" />
+      <Button onPress={() => editor.toggleMark('italic')} title="I" />
+      <Button
+        onPress={() => editor.setMark('link', { href: 'https://yjs.dev' })}
+        title="Link"
+      />
+    </View>
+  );
+}
+```
+
+The library **does not own the `Y.Doc` / `Y.Text`** — the consumer creates,
+syncs (via `y-websocket`, `y-indexeddb`, a custom provider, whatever), and
+disposes of them. The component subscribes to a passed-in `Y.Text` and edits
+it in place.
+
+See [`example/App.tsx`](./example/App.tsx) for a full demo that exercises
+every default mark, programmatic mutations, and `YTextRenderer`.
+
+## Schemas
+
+A schema declares which marks the editor accepts. Marks not in the schema
+are dropped on insert — this is what makes the editor safe for AI-generated
+content. Custom marks are declared by extending `defaultSchema`:
+
+```ts
+import { defaultSchema, type Schema } from '@eclosion-tech/react-native-yjs-text';
+
+const schema: Schema = {
+  marks: {
+    ...defaultSchema.marks,
+    'pear.mention': {
+      attrs: { userId: { type: 'string', required: true } },
+      renderStyle: { color: '#0066cc', backgroundColor: '#e6f0ff' },
+      onTap: (attrs) => console.log('mention tapped', attrs.userId),
+    },
+  },
+};
+```
+
+Only a subset of RN's `TextStyle` survives the bridge into native rendering:
+`fontWeight`, `fontStyle`, `fontFamily`, `fontSize`, `color`,
+`backgroundColor`, `textDecorationLine`. Keys outside that list are silently
+dropped (a deliberate cross-platform-safety choice — see
+`RENDERABLE_TEXT_STYLE_KEYS` in `src/schema.ts`).
+
+## Building & running
+
+This repo is a pnpm workspace with three members:
+
+- `.` — the library
+- `example/` — Expo SDK 56 demo (uses `expo run:ios` / `expo run:android`)
+- `example-bare/` — vanilla `@react-native-community/cli` demo (no Expo
+  runtime around the host app, only Expo Modules autolinking on the native
+  side)
+
+```sh
+# From the repo root
+pnpm install              # installs all three workspace members
+pnpm prepare              # builds the library's TS into `build/`
+pnpm test                 # runs the Jest suite (50 tests, ~1s)
+
+# Expo example
+cd example
+npx pod-install           # or: cd ios && pod install
+npx expo run:ios          # or: npx expo run:android
+
+# Bare RN example
+cd example-bare
+(cd ios && pod install)
+npx react-native run-ios  # or: npx react-native run-android
+```
+
+The bare example doubles as the canonical integration test for non-Expo
+hosts; if it boots, your `@react-native-community/cli init`-shaped project
+will too.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│ Consumer application                    │
+│   - manages the Y.Doc / Y.Text          │
+│   - builds toolbar / slash menu UI      │
+│   - composes multiple YTextInputs into  │
+│     its own block model                 │
+└──────────────┬──────────────────────────┘
+               │ <YTextInput yText={...} schema={...} />
+               │
+┌──────────────▼──────────────────────────┐
+│ react-native-yjs-text (TS layer)        │
+│   - YTextInput / YTextRenderer          │
+│   - useYTextEditor command API          │
+│   - schema definitions / mark validation│
+│   - Y.Text ↔ runs ↔ native event bridge │
+└──────────────┬──────────────────────────┘
+               │ Expo Modules (Fabric / TurboModules)
+               │
+┌──────────────▼──────────┬───────────────┐
+│ iOS native              │ Android native│
+│ - YjsTextView (ExpoView │ - YjsTextView │
+│   + UITextView subview) │   (ExpoView + │
+│ - NSAttributedString    │   AppCompatEditText)
+│ - UITextViewDelegate    │ - SpannableStringBuilder
+│   shouldChangeTextIn    │ - TextWatcher │
+└─────────────────────────┴───────────────┘
+```
+
+## Known gaps in v0.1
+
+Per the spec ([`SPEC.md` § Versioning roadmap](./SPEC.md#versioning-roadmap)):
+
+- **IME composition for CJK / Korean / IMEs with multi-stage input.** We
+  hand the composition string straight through to `Y.Text` on every keystroke
+  in the composition session, which collaborators see as a flurry of
+  character-by-character inserts and deletes instead of one atomic
+  composition commit. A "compose locally, transact on commit" path lands in
+  v0.2 once we add `UITextInput.markedTextRange` / Android
+  `InputConnection.setComposingText` handling.
+- **Paste from system clipboard** loses formatting — content is inserted as
+  plain runs.
+- **Hardware-keyboard shortcuts** (⌘B / Ctrl+B etc.) are not bound by
+  default; consumers can wire their own via the imperative editor API.
+- **Bridge traffic** goes through the standard Expo Modules ABI on every
+  edit. v0.2 will move the typing-hot-path event (`onContentChange`) to a
+  JSI direct call to skip JSON ser/de per keystroke.
+- **No first-party block model.** Each `YTextInput` edits one inline
+  region; the consumer composes them into paragraphs / headings / lists.
+  See `SPEC.md` for why this is by design.
+- **Selection highlight is visually masked by `backgroundColor` marks.**
+  Both `UITextView` (iOS) and `EditText` (Android) draw `NSAttributedString.
+  backgroundColor` / `BackgroundColorSpan` on top of the system selection
+  highlight, so selecting text that already has, e.g., the default `code`
+  mark applied makes the selection rectangle invisible inside the marked
+  range. The selection is still active functionally — toolbar toggles and
+  keyboard actions work as normal — only the visual rectangle is occluded.
+  iOS users still see the two grab-handle circles. Mirrors how Mobile
+  Safari, iOS Notes, and most platform editors render the same situation.
+
+## License
+
+MIT. See [`LICENSE`](./LICENSE).