From f54ae965c0874ef0cea82957be2c55a7e280042a Mon Sep 17 00:00:00 2001 From: fazi-gondal Date: Sun, 25 Oct 2026 13:10:38 +0500 Subject: [PATCH 1/3] docs: update README with comprehensive props, methods, and usage guides --- README.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 61 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 899344c..719e665 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,8 @@ Requirements: - Expo: a development build or `npx expo prebuild` (Expo Go isn't supported) - One `react-native-codepad-lang-*` package for each language you highlight +After adding the package or changing native configuration, rebuild your native application. Installing the JavaScript package alone does not update an already-installed native app. + ## Usage ```tsx @@ -47,6 +49,7 @@ const INITIAL = 'export const answer = 42;\n'; export function Screen() { const editor = useRef(null); + return ( void` | | Called after every edit with the replaced range, the new text and its origin. | -| `onSelectionChange` | `(selection) => void` | | Called when the caret or the selection moves. | +| `suggestions` | `Suggestions` | — | Controls native keyboard suggestions. See the reference for platform-specific behavior. | +| `autoFocus` | `boolean` | `false` | Requests focus when the editor is initialized. | +| `onChange` | `(event) => void` | — | Called after every edit with the replaced range, new text and its origin. | +| `onChangeText` | `(text) => void` | — | Called with the complete document text after a change. | +| `onSelectionChange` | `(selection) => void` | — | Called when the caret or selection moves. | +| `onReady` | `() => void` | — | Called when the editor is ready. | +| `onFocus` / `onBlur` | `() => void` | — | Report focus changes. | +| `onScroll` | `(...) => void` | — | Reports editor scrolling. | +| `onContentSizeChange` | `(...) => void` | — | Reports content-size changes. | ### Methods | Method | Description | | --- | --- | -| `getText()`, `getSelection()`, `getLineCount()` | Read the document synchronously on the JS thread. | +| `getText()`, `getSelection()`, `getLineCount()` | Read the document or current selection. | +| `getTextInRange()`, `getLength()`, `getLine()`, `getRevision()` | Read a range, document length, a line, or the current revision. | | `setText(text)`, `replaceRange(range, text)`, `insertText(text)` | Change the document. Each resolves once the edit is applied. | | `setSelection(selection)`, `selectAll()`, `scrollToLine(line)`, `revealSelection()` | Move the selection and the viewport. | -| `undo()`, `redo()`, `indent()`, `outdent()`, `cut()`, `copy()`, `paste()` | The edit menu, from JavaScript. | -| `moveCaret(direction)`, `typeText(text)`, `deleteBackward()`, `deleteForward()` | The toolbar API. Each goes through the same path as the keyboard. | -| `setSearch(query)`, `findNext()`, `findPrevious()`, `replaceCurrent(text)`, `replaceAll(text)` | Search, with the match count and the painted matches. | -| `focus()`, `blur()` | Show or hide the keyboard. | +| `offsetToPosition()`, `positionToOffset()`, `getCursorRect()`, `getVisibleLines()` | Convert positions or inspect the caret and visible lines. | +| `undo()`, `redo()`, `canUndo()`, `canRedo()` | Undo or redo edits and check whether those actions are available. | +| `indent()`, `outdent()`, `cut()`, `copy()`, `paste()` | Editing and clipboard operations. | +| `moveCaret(direction)`, `typeText(text)`, `deleteBackward()`, `deleteForward()` | The toolbar API. These use the editor's editing path. | +| `setSearch(query)`, `findNext()`, `findPrevious()`, `replaceCurrent(text)`, `replaceAll(text)`, `clearSearch()` | Search, replace matches, and clear the search state. | +| `focus()`, `blur()`, `isFocused()` | Control or inspect focus. | + +See the [complete API reference](https://reactnativecodepad.pages.dev/reference/props/) for exact signatures, options, event types, and return values. + +### Important API Behavior + +- **`initialValue` is not a controlled value.** It is read when the editor is initialized. Use `setText()` to replace the document after initialization. +- **Choose the change callback for your use case.** `onChange` provides edit details, including the replaced range and origin. `onChangeText` provides the full document after each change, which can be more expensive for large files. +- **Offsets and ranges have specific conventions.** Offsets use UTF-16 code units; ranges are half-open (`[start, end)`), with the start included and the end excluded. Line and column positions are zero-based. +- **Search supports literal and regular-expression queries.** Regex queries use the ICU dialect. Invalid expressions are rejected, and replacement text is treated literally. + +## Keyboard and Scrolling + +For editors that share a screen with other scrollable content, review `scrollEnabled` and the layout of the parent scroll container. To manage keyboard overlap, check `avoidKeyboard` and `contentInsets`; the right setup depends on your screen layout. + +See the [props reference](https://reactnativecodepad.pages.dev/reference/props/) for the available options and behavior. -## Coding agents +## Coding Agents The CodePad skill gives coding agents such as Claude Code, Codex and Cursor the API and its pitfalls: From 49a0f61382617c9c3f021f3fea4b0ab4692c28c5 Mon Sep 17 00:00:00 2001 From: fazi-gondal Date: Sun, 25 Oct 2026 13:16:14 +0500 Subject: [PATCH 2/3] docs: update README with detailed prop defaults and event types --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 719e665..e83cad8 100644 --- a/README.md +++ b/README.md @@ -92,7 +92,7 @@ const languages = Codepad.availableLanguages(); | `language` | `string` | undefined | The id of an installed language package. Without it the editor shows plain text. | | `theme` | `Theme` | `githubLight` | The colors. `githubDark` and `oneDark` ship too, and a theme is a plain object you can write yourself. | | `fontSize` | `number` | `14` | In dp on Android and points on iOS. | -| `fontFamily` | `string` | Platform default | Sets the editor font family. | +| `fontFamily` | `string` | `monospace` (Android), `Menlo` (iOS) | Sets the editor font family. | | `lineHeight` | `number` | `1.4` | Controls line height. | | `softWrap` | `boolean` | `false` | Wraps long lines. Off means horizontal scrolling. | | `lineNumbers` | `boolean` | `true` | Shows the line number gutter. | @@ -105,17 +105,17 @@ const languages = Codepad.availableLanguages(); | `tabSize` | `number` | `4` | The width of one indentation level. | | `placeholder` | `string` | — | Sets placeholder text. | | `scrollEnabled` | `boolean` | `true` | Enables or disables editor scrolling. | -| `contentInsets` | `ContentInsets` | — | Configures the editor's content insets. | +| `contentInsets` | `ContentInsets` | All insets 0 | Configures the editor's content insets. | | `avoidKeyboard` | `boolean` | `false` | Adds the keyboard overlap to the bottom inset on every frame of the keyboard animation. | -| `suggestions` | `Suggestions` | — | Controls native keyboard suggestions. See the reference for platform-specific behavior. | +| `suggestions` | `Suggestions` | `'off'` | Controls keyboard suggestions: `'off'` (disables suggestions), `'forceOff'` (also disables composition on Android), and `'on'` (allows autocorrect). | | `autoFocus` | `boolean` | `false` | Requests focus when the editor is initialized. | -| `onChange` | `(event) => void` | — | Called after every edit with the replaced range, new text and its origin. | -| `onChangeText` | `(text) => void` | — | Called with the complete document text after a change. | -| `onSelectionChange` | `(selection) => void` | — | Called when the caret or selection moves. | +| `onChange` | `(event: ChangeEvent) => void` | — | Called after every edit with the replaced range, new text and its origin. | +| `onChangeText` | `(text: string) => void` | — | Called with the complete document text after a change. | +| `onSelectionChange` | `(selection: SelectionChangeEvent) => void` | — | Called when the caret or selection moves. | | `onReady` | `() => void` | — | Called when the editor is ready. | | `onFocus` / `onBlur` | `() => void` | — | Report focus changes. | -| `onScroll` | `(...) => void` | — | Reports editor scrolling. | -| `onContentSizeChange` | `(...) => void` | — | Reports content-size changes. | +| `onScroll` | `(event: ScrollEvent) => void` | — | Reports editor scrolling. | +| `onContentSizeChange` | `(event: ContentSizeEvent) => void` | — | Reports content-size changes. | ### Methods @@ -132,7 +132,7 @@ const languages = Codepad.availableLanguages(); | `setSearch(query)`, `findNext()`, `findPrevious()`, `replaceCurrent(text)`, `replaceAll(text)`, `clearSearch()` | Search, replace matches, and clear the search state. | | `focus()`, `blur()`, `isFocused()` | Control or inspect focus. | -See the [complete API reference](https://reactnativecodepad.pages.dev/reference/props/) for exact signatures, options, event types, and return values. +See the [methods reference](https://reactnativecodepad.pages.dev/reference/methods/) for detailed argument types, options, and return values, and the [complete API reference](https://reactnativecodepad.pages.dev/reference/props/) for all props and types. ### Important API Behavior From 56c40f6c4cc3dbb01dc72bfc69a2f50083c78d48 Mon Sep 17 00:00:00 2001 From: Rayen Sbai Date: Mon, 26 Oct 2026 21:14:14 +0100 Subject: [PATCH 3/3] docs: keep the new API rows and drop the extra sections --- README.md | 88 +++++++++++++++++-------------------------------------- 1 file changed, 27 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index e83cad8..6dbeeb6 100644 --- a/README.md +++ b/README.md @@ -37,8 +37,6 @@ Requirements: - Expo: a development build or `npx expo prebuild` (Expo Go isn't supported) - One `react-native-codepad-lang-*` package for each language you highlight -After adding the package or changing native configuration, rebuild your native application. Installing the JavaScript package alone does not update an already-installed native app. - ## Usage ```tsx @@ -49,7 +47,6 @@ const INITIAL = 'export const answer = 42;\n'; export function Screen() { const editor = useRef(null); - return ( void` | — | Called after every edit with the replaced range, new text and its origin. | -| `onChangeText` | `(text: string) => void` | — | Called with the complete document text after a change. | -| `onSelectionChange` | `(selection: SelectionChangeEvent) => void` | — | Called when the caret or selection moves. | -| `onReady` | `() => void` | — | Called when the editor is ready. | -| `onFocus` / `onBlur` | `() => void` | — | Report focus changes. | -| `onScroll` | `(event: ScrollEvent) => void` | — | Reports editor scrolling. | -| `onContentSizeChange` | `(event: ContentSizeEvent) => void` | — | Reports content-size changes. | +| `onReady` | `() => void` | | Called once after the first draw. Ref methods are valid from here. | +| `onChange` | `(event) => void` | | Called after every edit with the replaced range, the new text and its origin. | +| `onChangeText` | `(text) => void` | | Called with the full text after every change. Prefer `onChange` on large documents. | +| `onSelectionChange` | `(selection) => void` | | Called when the caret or the selection moves. | +| `onFocus`, `onBlur` | `() => void` | | Called when the editor gains or loses focus. | +| `onScroll` | `(event) => void` | | Called with the scroll offset and the content size, at most once per frame. | +| `onContentSizeChange` | `(event) => void` | | Called when the content size changes, insets included. | ### Methods | Method | Description | | --- | --- | -| `getText()`, `getSelection()`, `getLineCount()` | Read the document or current selection. | -| `getTextInRange()`, `getLength()`, `getLine()`, `getRevision()` | Read a range, document length, a line, or the current revision. | +| `getText()`, `getTextInRange(range)`, `getLine(index)`, `getLength()`, `getLineCount()` | Read the document synchronously on the JS thread. | +| `getSelection()`, `getRevision()`, `getCursorRect()`, `getVisibleLines()` | Read the selection, the revision, the caret rectangle and the lines on screen. | +| `offsetToPosition(offset)`, `positionToOffset(position)` | Convert between UTF-16 offsets and 0-based lines and columns. | +| `canUndo()`, `canRedo()`, `isFocused()` | Report whether there is an edit to undo or redo and whether the editor has focus. | | `setText(text)`, `replaceRange(range, text)`, `insertText(text)` | Change the document. Each resolves once the edit is applied. | | `setSelection(selection)`, `selectAll()`, `scrollToLine(line)`, `revealSelection()` | Move the selection and the viewport. | -| `offsetToPosition()`, `positionToOffset()`, `getCursorRect()`, `getVisibleLines()` | Convert positions or inspect the caret and visible lines. | -| `undo()`, `redo()`, `canUndo()`, `canRedo()` | Undo or redo edits and check whether those actions are available. | -| `indent()`, `outdent()`, `cut()`, `copy()`, `paste()` | Editing and clipboard operations. | -| `moveCaret(direction)`, `typeText(text)`, `deleteBackward()`, `deleteForward()` | The toolbar API. These use the editor's editing path. | -| `setSearch(query)`, `findNext()`, `findPrevious()`, `replaceCurrent(text)`, `replaceAll(text)`, `clearSearch()` | Search, replace matches, and clear the search state. | -| `focus()`, `blur()`, `isFocused()` | Control or inspect focus. | - -See the [methods reference](https://reactnativecodepad.pages.dev/reference/methods/) for detailed argument types, options, and return values, and the [complete API reference](https://reactnativecodepad.pages.dev/reference/props/) for all props and types. - -### Important API Behavior - -- **`initialValue` is not a controlled value.** It is read when the editor is initialized. Use `setText()` to replace the document after initialization. -- **Choose the change callback for your use case.** `onChange` provides edit details, including the replaced range and origin. `onChangeText` provides the full document after each change, which can be more expensive for large files. -- **Offsets and ranges have specific conventions.** Offsets use UTF-16 code units; ranges are half-open (`[start, end)`), with the start included and the end excluded. Line and column positions are zero-based. -- **Search supports literal and regular-expression queries.** Regex queries use the ICU dialect. Invalid expressions are rejected, and replacement text is treated literally. - -## Keyboard and Scrolling - -For editors that share a screen with other scrollable content, review `scrollEnabled` and the layout of the parent scroll container. To manage keyboard overlap, check `avoidKeyboard` and `contentInsets`; the right setup depends on your screen layout. - -See the [props reference](https://reactnativecodepad.pages.dev/reference/props/) for the available options and behavior. +| `undo()`, `redo()`, `indent()`, `outdent()`, `cut()`, `copy()`, `paste()` | The edit menu, from JavaScript. | +| `moveCaret(direction)`, `typeText(text)`, `deleteBackward()`, `deleteForward()` | The toolbar API. Each goes through the same path as the keyboard. | +| `setSearch(query)`, `findNext()`, `findPrevious()`, `replaceCurrent(text)`, `replaceAll(text)`, `clearSearch()` | Search, with the match count and the painted matches. | +| `focus()`, `blur()` | Show or hide the keyboard. | -## Coding Agents +## Coding agents The CodePad skill gives coding agents such as Claude Code, Codex and Cursor the API and its pitfalls: