From dc90a90b8cb1e26b12b494bb3843c89b8c839ebb Mon Sep 17 00:00:00 2001 From: roi ben shoham Date: Tue, 17 Sep 2024 09:54:35 +0300 Subject: [PATCH] fix: docs v2 --- website/docs/api/BridgeExtensions.md | 140 ++++--------- website/docs/api/BridgeState.md | 249 +++++++----------------- website/docs/api/Components.md | 74 ------- website/docs/api/CustomKeyboardUtils.md | 64 ++---- website/docs/api/EditorBridge.md | 203 ++++++------------- website/docs/api/RichText.md | 15 ++ website/docs/api/Toolbar.md | 135 +++++++++++++ website/docs/api/useEditorBridge.md | 92 +++------ website/docs/api/useEditorContent.md | 34 ++-- website/docs/examples/CustomContext.md | 247 +++++++++++++++++++++++ website/docs/examples/comments.md | 47 ++++- website/docs/examples/fonts.md | 43 +++- website/docs/examples/mentions.md | 58 +++++- website/docs/examples/realtimeCollab.md | 49 ++++- website/docs/examples/search.md | 47 ++++- website/docs/mainConcepts.md | 2 +- website/sidebars.ts | 4 +- 17 files changed, 852 insertions(+), 651 deletions(-) delete mode 100644 website/docs/api/Components.md create mode 100644 website/docs/api/RichText.md create mode 100644 website/docs/api/Toolbar.md create mode 100644 website/docs/examples/CustomContext.md diff --git a/website/docs/api/BridgeExtensions.md b/website/docs/api/BridgeExtensions.md index 7b11725d..212b0602 100644 --- a/website/docs/api/BridgeExtensions.md +++ b/website/docs/api/BridgeExtensions.md @@ -4,101 +4,45 @@ sidebar_position: 6 # Built-in BridgeExtensions -tentap comes with multiple bridges extensions out of the box, in this page we will show all of them and show their relevant configurations, which can be configured with `BridgeExtension.configureExtension`: - -### CoreExtension - -uses `@tiptap/extension-document` `@tiptap/extension-paragraph` `@tiptap/extension-text` - -This bridge extension includes fundamental logic that is needed to interact with the editor - -### BlockquoteBridge - -uses `@tiptap/extension-blockquote` -relevant configuration: https://tiptap.dev/docs/editor/api/nodes/blockquote#settings - -### CodeBridge - -uses `@tiptap/extension-code` -relevant configuration: https://tiptap.dev/docs/editor/api/marks/code#settings - -### ItalicBridge - -uses `@tiptap/extension-italic` -relevant configuration: https://tiptap.dev/docs/editor/api/marks/italic#settings - -### BoldBridge - -uses `@tiptap/extension-bold` -relevant configuration: https://tiptap.dev/docs/editor/api/marks/bold#settings - -### StrikeBridge - -uses `@tiptap/extension-strike` -relevant configuration: https://tiptap.dev/docs/editor/api/marks/strike#settings - -### BulletListBridge - -uses `@tiptap/extension-bullet-list` `@tiptap/extension-list-item` -relevant configuration: https://tiptap.dev/docs/editor/api/nodes/bullet-list#settings - -### OrderedListBridge - -uses `@tiptap/extension-ordered-list` `@tiptap/extension-list-item` -relevant configuration: https://tiptap.dev/docs/editor/api/nodes/ordered-list#settings - -### HeadingBridge - -uses `@tiptap/extension-heading` -relevant configuration: https://tiptap.dev/docs/editor/api/nodes/heading#settings - -### ListItemBridge - -You can use only OrderedListBridge/BulletListBridge for lists, use ListItemBridge in case you want to control lift/sink of lists -uses `@tiptap/extension-list-item` -relevant configuration: https://tiptap.dev/docs/editor/api/nodes/list-item#settings - -### HistoryBridge - -uses `@tiptap/extension-history` -relevant configuration: https://tiptap.dev/docs/editor/api/extensions/history#settings - -### ColorBridge - -uses `@tiptap/extension-color` `@tiptap/extension-text-style` -no relevant configuration - -### HighlightBridge - -uses `@tiptap/extension-highlight` `@tiptap/extension-text-style` -no relevant configuration - -### ImageBridge - -uses `@tiptap/extension-image` -relevant configuration: https://tiptap.dev/docs/editor/api/nodes/image#settings - -### LinkBridge - -uses `@tiptap/extension-link` -relevant configuration: https://tiptap.dev/docs/editor/api/marks/link#settings - -### TaskListBridge - -uses `@tiptap/extension-task-list` `@tiptap/extension-list-item` -relevant configuration: https://tiptap.dev/docs/editor/api/nodes/task-list#settings - -### UnderlineBridge - -uses `@tiptap/extension-underline` -relevant configuration: https://tiptap.dev/docs/editor/api/marks/underline#settings - -### PlaceholderBridge - -uses `@tiptap/extension-placeholder` -relevant configuration: https://tiptap.dev/docs/editor/api/extensions/placeholder#settings - -### DropCursorBridge - -uses `@tiptap/extension-dropcursor` -relevant configuration: https://tiptap.dev/docs/editor/api/extensions/dropcursor#settings +tentap includes several bridge extensions out of the box. This page lists all of them along with their relevant configurations, which can be set using `BridgeExtension.configureExtension`. + +## Core Extensions + +| Extension | Uses | Description | Configuration | +| ------------- | ------------------------------------------------------------------------------------- | ---------------------------------------- | ------------- | +| CoreExtension | `@tiptap/extension-document`, `@tiptap/extension-paragraph`, `@tiptap/extension-text` | Fundamental logic for editor interaction | N/A | + +## Text Formatting Extensions + +| Extension | Uses | Configuration | +| ---------------- | ------------------------------ | ----------------------------------------------------------------------------------- | +| BlockquoteBridge | `@tiptap/extension-blockquote` | [Blockquote settings](https://tiptap.dev/docs/editor/api/nodes/blockquote#settings) | +| CodeBridge | `@tiptap/extension-code` | [Code settings](https://tiptap.dev/docs/editor/api/marks/code#settings) | +| ItalicBridge | `@tiptap/extension-italic` | [Italic settings](https://tiptap.dev/docs/editor/api/marks/italic#settings) | +| BoldBridge | `@tiptap/extension-bold` | [Bold settings](https://tiptap.dev/docs/editor/api/marks/bold#settings) | +| StrikeBridge | `@tiptap/extension-strike` | [Strike settings](https://tiptap.dev/docs/editor/api/marks/strike#settings) | +| UnderlineBridge | `@tiptap/extension-underline` | [Underline settings](https://tiptap.dev/docs/editor/api/marks/underline#settings) | + +## List Extensions + +| Extension | Uses | Configuration | +| ----------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------- | +| BulletListBridge | `@tiptap/extension-bullet-list`, `@tiptap/extension-list-item` | [Bullet list settings](https://tiptap.dev/docs/editor/api/nodes/bullet-list#settings) | +| OrderedListBridge | `@tiptap/extension-ordered-list`, `@tiptap/extension-list-item` | [Ordered list settings](https://tiptap.dev/docs/editor/api/nodes/ordered-list#settings) | +| TaskListBridge | `@tiptap/extension-task-list`, `@tiptap/extension-list-item` | [Task list settings](https://tiptap.dev/docs/editor/api/nodes/task-list#settings) | +| ListItemBridge | `@tiptap/extension-list-item` | [List item settings](https://tiptap.dev/docs/editor/api/nodes/list-item#settings) | + +## Other Extensions + +| Extension | Uses | Configuration | +| ----------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | +| HeadingBridge | `@tiptap/extension-heading` | [Heading settings](https://tiptap.dev/docs/editor/api/nodes/heading#settings) | +| HistoryBridge | `@tiptap/extension-history` | [History settings](https://tiptap.dev/docs/editor/api/extensions/history#settings) | +| ColorBridge | `@tiptap/extension-color`, `@tiptap/extension-text-style` | No relevant configuration | +| HighlightBridge | `@tiptap/extension-highlight`, `@tiptap/extension-text-style` | No relevant configuration | +| ImageBridge | `@tiptap/extension-image` | [Image settings](https://tiptap.dev/docs/editor/api/nodes/image#settings) | +| LinkBridge | `@tiptap/extension-link` | [Link settings](https://tiptap.dev/docs/editor/api/marks/link#settings) | +| PlaceholderBridge | `@tiptap/extension-placeholder` | [Placeholder settings](https://tiptap.dev/docs/editor/api/extensions/placeholder#settings) | +| DropCursorBridge | `@tiptap/extension-dropcursor` | [Dropcursor settings](https://tiptap.dev/docs/editor/api/extensions/dropcursor#settings) | + +Note: Use ListItemBridge only if you need to control lift/sink of lists. Otherwise, OrderedListBridge/BulletListBridge are sufficient. diff --git a/website/docs/api/BridgeState.md b/website/docs/api/BridgeState.md index 6e8b4e03..927db189 100644 --- a/website/docs/api/BridgeState.md +++ b/website/docs/api/BridgeState.md @@ -4,177 +4,78 @@ sidebar_position: 3 # BridgeState -The BridgeState is the latest state of the editor webview on the native side, it's extendable by BridgeExtensions and is generally used with [useBridgeState](#usebridgestate) - -The list above is the interface of BridgeState in case you use `TenTapStarterkit` or using all the BridgeExtensions the lib exports, on each prop we specify what bridgeExtension adds it - -### BridgeState properties - -#### editable - -`boolean` -
Is the editor editable or not
extended by [CoreBridge](./BridgeExtensions#coreextension) - -#### selection - -`{ from: number; to: number }` -
The selection on the editor-web
extended by [CoreBridge](./BridgeExtensions#coreextension) - -#### isFocused - -`boolean` -
true when the editor is focused
extended by [CoreBridge](./BridgeExtensions#coreextension) - -#### isReady - -`boolean` -
true when the editor is fully loaded
extended by [CoreBridge](./BridgeExtensions#coreextension) - -#### isBlockquoteActive - -`boolean` -
true when the cursor is where blockquote is active
extended by [BlockquoteBridge](./BridgeExtensions#blockquotebridge) - -#### canToggleBlockquote - -`boolean` -
true when it's possible to toggle blockquote
extended by [BlockquoteBridge](./BridgeExtensions#blockquotebridge) - -#### isCodeActive - -`boolean` -
true when the cursor is where code is active
extended by [CodeBridge](./BridgeExtensions#codebridge) - -#### canToggleCode - -`boolean` -
true when it's possible to toggle code
extended by [CodeBridge](./BridgeExtensions#codebridge) - -#### isBoldActive - -`boolean` -
true when the cursor is where bold is active
extended by [BoldBridge](./BridgeExtensions#boldbridge) - -#### canToggleBold - -`boolean` -
true when it's possible to toggle bold
extended by [BoldBridge](./BridgeExtensions#boldbridge) - -#### isItalicActive - -`boolean` -
true when the cursor is where italic is active
extended by [ItalicBridge](./BridgeExtensions#italicbridge) - -#### canToggleItalic - -`boolean` -
true when it's possible to toggle italic
extended by [ItalicBridge](./BridgeExtensions#italicbridge) - -#### isUnderlineActive - -`boolean` -
true when the cursor is where underline is active
extended by [UnderlineBridge](./BridgeExtensions#underlinebridge) - -#### canToggleUnderline - -`boolean` -
true when it's possible to toggle underline
extended by [UnderlineBridge](./BridgeExtensions#underlinebridge) - -#### isStrikeActive - -`boolean` -
true when the cursor is where Strike is active
extended by [StrikeBridge](./BridgeExtensions#strikebridge) - -#### canToggleStrike - -`boolean` -
true when it's possible to toggle Strike
extended by [StrikeBridge](./BridgeExtensions#strikebridge) - -#### isBulletListActive - -`boolean` -
true when the cursor is where bullet list is active
extended by [BulletListBridge](./BridgeExtensions#bulletlistbridge) - -#### canToggleBulletList - -`boolean` -
true when it's possible to toggle bullet list
extended by [BulletListBridge](./BridgeExtensions#bulletlistbridge) - -#### isOrderedListActive - -`boolean` -
true when the cursor is where ordered list is active
extended by [OrderedListBridge](./BridgeExtensions#orderedlistbridge) - -#### canToggleOrderedList - -`boolean` -
true when it's possible to toggle ordered list
extended by [OrderedListBridge](./BridgeExtensions#orderedlistbridge) - -#### isTaskListActive - -`boolean` -
true when the cursor is where task list is active
extended by [TaskListBridge](./BridgeExtensions#tasklistbridge) - -#### canToggleTaskList - -`boolean` -
true when it's possible to toggle task list
extended by [TaskListBridge](./BridgeExtensions#tasklistbridge) - -#### headingLevel - -`number | undefined` -
undefined when no heading is applied, number of the heading level
extended by [HeadingBridge](./BridgeExtensions#headingbridge) - -#### canToggleHeading - -`boolean` -
true when it's possible to toggle heading
extended by [HeadingBridge](./BridgeExtensions#headingbridge) - -#### canLift - -`boolean` -
true when it's possible to lift list item
extended by [ListItemBridge](./BridgeExtensions#listitembridge) - -#### canSink - -`boolean` -
true when it's possible to sink a list item
extended by [ListItemBridge](./BridgeExtensions#listitembridge) - -#### canUndo - -`boolean` -
true when it's possible to undo the doc history stack
extended by [HistoryBridge](./BridgeExtensions#historybridge) - -#### canRedo - -`boolean` -
true when it's possible to redo the doc history stack
extended by [HistoryBridge](./BridgeExtensions#historybridge) - -#### activeColor - -`string | undefined` -
undefined when no color is applied, string of the color that is active on the selection
extended by [ColorBridge](./BridgeExtensions#colorbridge) - -#### activeHighlight - -`string | undefined` -
undefined when no highlight is applied, string of the highlight that active on the selection
extended by [HighlightBridge](./BridgeExtensions#highlightbridge) - -#### isLinkActive - -`boolean` -
true when the link is in the selection
extended by [LinkBridge](./BridgeExtensions#linkbridge) - -#### canSetLink - -`boolean` -
true when it's possible to add link, for example when there is no selection it not possible
extended by [LinkBridge](./BridgeExtensions#linkbridge) - -#### activeLink - -`string | undefined` -
undefined when there is no link, string of the link that active on the selection position
extended by [LinkBridge](./BridgeExtensions#linkbridge) - -### useBridgeState - -a react hook to subscribe to changes on the BridgeState, get EditorBridge +The BridgeState represents the latest state of the editor webview on the native side. It's extendable by BridgeExtensions and is typically used with [useBridgeState](#usebridgestate). + +The following properties are available when using `TenTapStarterkit` or all the BridgeExtensions exported by the library. Each property specifies which BridgeExtension adds it. + +## Core Properties + +| Property | Type | Description | Extended By | +| --------- | ------------------------------ | ------------------------------------ | ---------------------------------------------- | +| editable | `boolean` | Indicates if the editor is editable | [CoreBridge](./BridgeExtensions#coreextension) | +| selection | `{ from: number; to: number }` | The current selection in the editor | [CoreBridge](./BridgeExtensions#coreextension) | +| isFocused | `boolean` | True when the editor is focused | [CoreBridge](./BridgeExtensions#coreextension) | +| isReady | `boolean` | True when the editor is fully loaded | [CoreBridge](./BridgeExtensions#coreextension) | + +## Formatting Properties + +| Property | Type | Description | Extended By | +| ------------------- | --------- | ---------------------------------------------------- | ------------------------------------------------------- | +| isBlockquoteActive | `boolean` | True when the cursor is in an active blockquote | [BlockquoteBridge](./BridgeExtensions#blockquotebridge) | +| canToggleBlockquote | `boolean` | True when it's possible to toggle blockquote | [BlockquoteBridge](./BridgeExtensions#blockquotebridge) | +| isCodeActive | `boolean` | True when the cursor is in active code | [CodeBridge](./BridgeExtensions#codebridge) | +| canToggleCode | `boolean` | True when it's possible to toggle code | [CodeBridge](./BridgeExtensions#codebridge) | +| isBoldActive | `boolean` | True when the cursor is in active bold text | [BoldBridge](./BridgeExtensions#boldbridge) | +| canToggleBold | `boolean` | True when it's possible to toggle bold | [BoldBridge](./BridgeExtensions#boldbridge) | +| isItalicActive | `boolean` | True when the cursor is in active italic text | [ItalicBridge](./BridgeExtensions#italicbridge) | +| canToggleItalic | `boolean` | True when it's possible to toggle italic | [ItalicBridge](./BridgeExtensions#italicbridge) | +| isUnderlineActive | `boolean` | True when the cursor is in active underlined text | [UnderlineBridge](./BridgeExtensions#underlinebridge) | +| canToggleUnderline | `boolean` | True when it's possible to toggle underline | [UnderlineBridge](./BridgeExtensions#underlinebridge) | +| isStrikeActive | `boolean` | True when the cursor is in active strikethrough text | [StrikeBridge](./BridgeExtensions#strikebridge) | +| canToggleStrike | `boolean` | True when it's possible to toggle strikethrough | [StrikeBridge](./BridgeExtensions#strikebridge) | + +## List Properties + +| Property | Type | Description | Extended By | +| -------------------- | --------- | ------------------------------------------------- | --------------------------------------------------------- | +| isBulletListActive | `boolean` | True when the cursor is in an active bullet list | [BulletListBridge](./BridgeExtensions#bulletlistbridge) | +| canToggleBulletList | `boolean` | True when it's possible to toggle bullet list | [BulletListBridge](./BridgeExtensions#bulletlistbridge) | +| isOrderedListActive | `boolean` | True when the cursor is in an active ordered list | [OrderedListBridge](./BridgeExtensions#orderedlistbridge) | +| canToggleOrderedList | `boolean` | True when it's possible to toggle ordered list | [OrderedListBridge](./BridgeExtensions#orderedlistbridge) | +| isTaskListActive | `boolean` | True when the cursor is in an active task list | [TaskListBridge](./BridgeExtensions#tasklistbridge) | +| canToggleTaskList | `boolean` | True when it's possible to toggle task list | [TaskListBridge](./BridgeExtensions#tasklistbridge) | +| canLift | `boolean` | True when it's possible to lift a list item | [ListItemBridge](./BridgeExtensions#listitembridge) | +| canSink | `boolean` | True when it's possible to sink a list item | [ListItemBridge](./BridgeExtensions#listitembridge) | + +## Heading Properties + +| Property | Type | Description | Extended By | +| ---------------- | --------------------- | -------------------------------------------------------- | ------------------------------------------------- | +| headingLevel | `number \| undefined` | The current heading level, or undefined if not a heading | [HeadingBridge](./BridgeExtensions#headingbridge) | +| canToggleHeading | `boolean` | True when it's possible to toggle heading | [HeadingBridge](./BridgeExtensions#headingbridge) | + +## History Properties + +| Property | Type | Description | Extended By | +| -------- | --------- | ------------------------------- | ------------------------------------------------- | +| canUndo | `boolean` | True when it's possible to undo | [HistoryBridge](./BridgeExtensions#historybridge) | +| canRedo | `boolean` | True when it's possible to redo | [HistoryBridge](./BridgeExtensions#historybridge) | + +## Color and Highlight Properties + +| Property | Type | Description | Extended By | +| --------------- | --------------------- | ------------------------------------------------------------------- | ----------------------------------------------------- | +| activeColor | `string \| undefined` | The active text color, or undefined if no color is applied | [ColorBridge](./BridgeExtensions#colorbridge) | +| activeHighlight | `string \| undefined` | The active highlight color, or undefined if no highlight is applied | [HighlightBridge](./BridgeExtensions#highlightbridge) | + +## Link Properties + +| Property | Type | Description | Extended By | +| ------------ | --------------------- | ------------------------------------------------------ | ------------------------------------------- | +| isLinkActive | `boolean` | True when a link is in the selection | [LinkBridge](./BridgeExtensions#linkbridge) | +| canSetLink | `boolean` | True when it's possible to add a link | [LinkBridge](./BridgeExtensions#linkbridge) | +| activeLink | `string \| undefined` | The active link URL, or undefined if no link is active | [LinkBridge](./BridgeExtensions#linkbridge) | + +## useBridgeState + +`useBridgeState` is a React hook used to subscribe to changes in the BridgeState. It provides access to the EditorBridge. diff --git a/website/docs/api/Components.md b/website/docs/api/Components.md deleted file mode 100644 index 163cf13f..00000000 --- a/website/docs/api/Components.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -sidebar_position: 4 ---- - -# Components - -## RichText - -a components that wraps the webview that renders the editor - -props: - -| name | type | default | description | -| ------ | -------------- | ------- | ----------------------------------------------------------------------- | -| editor | `EditorBridge` | | The bridge instance that created with [useEditorBridge](./EditorBridge) | - -you can also override any of the regular [WebView props](https://github.com/react-native-webview/react-native-webview/blob/HEAD/docs/Reference.md) although this is not recommended - -## Toolbar - -A react component of a basic Toolbar that include these features: - -- Add link context Alt text -- Change headling context Alt text - -- A lot of pre made toolbar items: - - link - - quote - - code - - bold - - italic - - checkList - - underline - - strikethrough - - h1 - - h2 - - h3 - - h4 - - h5 - - h6 - - orderedList - - bulletList - - sync - - lift - - undo - - redo - -props: - -| name | type | default | description | -| ------ | --------------- | --------------------- | ----------------------------------------------------------------------- | -| editor | `EditorBridge` | | The bridge instance that created with [useEditorBridge](./EditorBridge) | -| hidden | `boolean` | | a prop to control if toolbar shown | -| items | `ToolbarItem[]` | DEFAULT_TOOLBAR_ITEMS | array of ToolbarItem's that will be shown on the toolbar | - -See how we add a custom toolbar item in the [color keyboard example](../examples/colorKeyboard.md) - -### ToolbarItem - -The item rendered by the toolbar component - -```ts -export interface ToolbarItem { - onPress: ({ editor, editorState }: ArgsToolbarCB) => () => void; - active: ({ editor, editorState }: ArgsToolbarCB) => boolean; - disabled: ({ editor, editorState }: ArgsToolbarCB) => boolean; - image: ({ editor, editorState }: ArgsToolbarCB) => any; -} - -type ArgsToolbarCB = { - editor: EditorBridge; - editorState: BridgeState; -}; -``` diff --git a/website/docs/api/CustomKeyboardUtils.md b/website/docs/api/CustomKeyboardUtils.md index c6db5168..e9dbaf9a 100644 --- a/website/docs/api/CustomKeyboardUtils.md +++ b/website/docs/api/CustomKeyboardUtils.md @@ -4,55 +4,33 @@ sidebar_position: 5 # Custom Keyboard Utils -We believe that custom keyboard can be a game changer when it comes to editing experience, that's why we decided that this ability should be part of this lib, in this page we will show the APIs of the custom keyboard utils. -For examples please see: [Create custom keyboard](../examples/customKeyboard) or [Using the ColorKeyboard](../examples/colorKeyboard) +Custom keyboards can significantly enhance the editing experience. This page outlines the APIs for custom keyboard utilities. -### CustomKeyboard +For practical examples, see: -A react component that need to render so we will register the custom keyboard and show them properly +- [Create custom keyboard](../examples/customKeyboard) +- [Using the ColorKeyboard](../examples/colorKeyboard) -#### rootRef +## CustomKeyboard Component -`React.RefObject` -Important for iOS where ref of some View is needed for keyboard manipulation +A React component used to register and display custom keyboards. -#### keyboards +| Prop | Type | Description | +| ------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------- | +| rootRef | `React.RefObject` | Reference to a View, crucial for iOS keyboard manipulation | +| keyboards | `CustomKeyboardExtension[]` | List of [CustomKeyboardExtension](#customkeyboardextension) instances | +| setActiveKeyboardID | `(id: string \| undefined) => void` | Function to change or unset the active keyboard | +| activeKeyboardID | `string` | ID of the currently active custom keyboard | +| editor | `EditorBridge` | Instance of the editor's `EditorBridge` | +| rootBackground | `string` | (iOS only) Background of the `RCTRootView` rendering the custom keyboard. Useful for custom themes | -`CustomKeyboardExtension[]` -list of [CustomKeyboardExtension's](#customkeyboardextension) +## CustomKeyboardExtension -#### setActiveKeyboardID +A class for registering new components with a custom keyboard ID. -`(id: string | undefined) => void` -a function that changes or unsets the active keyboard +**Note:** The custom keyboard component is rendered in a separate `RCTRootView` on iOS and doesn't function as a regular React component in your app. -#### activeKeyboardID - -`string` -the active custom keyboard id - -#### editor - -`EditorBridge` -the editors `EditorBridge` instance - -#### rootBackground - `IOS ONLY` - -The background of the `RCTRootView` used to render the custom keyboard -This is helpful when you are using a custom theme - -### CustomKeyboardExtension - -A class that will register a new component with the customkeyboard id - -> It's important to note that the custom keyboard component does not work as a regular react component in your app, and is rendered on IOS in a separate RCTRootView. - -#### id - -`string` -a unique key for the custom keyboard - -#### comp - -`ComponentType` -The custom keyboard component +| Property | Type | Description | +| -------- | -------------------- | ----------------------------------------- | +| id | `string` | Unique identifier for the custom keyboard | +| comp | `ComponentType` | The custom keyboard component | diff --git a/website/docs/api/EditorBridge.md b/website/docs/api/EditorBridge.md index 60828dc2..4340beb1 100644 --- a/website/docs/api/EditorBridge.md +++ b/website/docs/api/EditorBridge.md @@ -4,150 +4,59 @@ sidebar_position: 2 # EditorBridge -An Interface of all the commands you can do with the editor on the react native side, can be extended with a [BrideExtension](./BridgeExtensions.md). With all of the bridges included in `tentapStarterKit` the EditorBridge will have: - -#### focus - -`(pos?: 'start' \| 'end' \| 'all' \| number \| boolean \| null) => void`
-a function that will focus the editor and open the keyboard
extended by [CoreBridge](./BridgeExtensions#coreextension) - -#### blur - -a function that will blur the editor and close the keyboard
extended by [CoreBridge](./BridgeExtensions#coreextension) - -#### webviewRef - -`RefObject\`
-a ref for the webview that renders the editor
extended by [CoreBridge](./BridgeExtensions#coreextension) - -#### getEditorState - -`() => BridgeState`
-a function that will return the most up to date BridgeState
extended by [CoreBridge](./BridgeExtensions#coreextension) - -#### getHTML - -`() => Promise\`
-an async function that will return the content of the editor in html format
extended by [CoreBridge](./BridgeExtensions#coreextension) - -#### getText - -`() => Promise\`
-an async function that will return the content of the editor in text format
extended by [CoreBridge](./BridgeExtensions#coreextension) - -#### getJSON - -`() => Promise\`
-an async function that will return the content of the editor in json format
extended by [CoreBridge](./BridgeExtensions#coreextension) - -#### setContent - -`(content: string) => void`
-a function that get's html as string and set set's it as the editors content
extended by [CoreBridge](./BridgeExtensions#coreextension) - -#### setEditable - -`(editable: boolean) => void`
-a function that sets the editable state
extended by [CoreBridge](./BridgeExtensions#coreextension) - -#### setSelection - -`(from: number, to: number) => void`
-sets the selection of the editor
extended by [CoreBridge](./BridgeExtensions#coreextension) - -#### injectCSS - -`(css: string, tag?: string) => void`
-creates or updates the stylesheet with the given tag, see [Dynamically Updating CSS](../examples/customCss/#dynamically-updating-css)
default `tag`: `custom-css`
extended by [CoreBridge](./BridgeExtensions#coreextension) - -#### injectJS - -`(js: string) => void`
-inject custom javascript into the editor's webview
extended by [CoreBridge](./BridgeExtensions#coreextension) - -#### updateScrollThresholdAndMargin - -`(offset: number) => void`
-a function that gets offset in px and changes [scrollThreshold](https://prosemirror.net/docs/ref/#view.EditorProps.scrollThreshold) [scrollMargin](https://prosemirror.net/docs/ref/#view.EditorProps.scrollMargin)
extended by [CoreBridge](./BridgeExtensions#coreextension) - -#### toggleBlockquote - -`() => void`
will toggle bold on the editor if possible
extended by [BlockquoteBridge](./BridgeExtensions#blockquotebridge) - -#### toggleCode - -`() => void`
will toggle code block on the editor if possible
extended by [CodeBridge](./BridgeExtensions#codebridge) - -#### toggleItalic - -`() => void`
will toggle italic on the editor if possible
extended by [ItalicBridge](./BridgeExtensions#italicbridge) - -#### toggleStrikethrough - -`() => void`
will toggle strikethrough on the editor if possible
extended by [StrikeBridge](./BridgeExtensions#strikebridge) - -#### toggleBulletList - -`() => void`
will toggle bullet list on the editor if possible
extended by [BulletListBridge](./BridgeExtensions#bulletlistbridge) - -#### toggleOrderedList - -`() => void`
will toggle order list on the editor if possible
extended by [OrderedListBridge](./BridgeExtensions#orderedlistbridge) - -#### toggleHeading - -`(level: number) => void`
gets level and toggles heading on the editor if possible
extended by [HeadingBridge](./BridgeExtensions#headingbridge) - -#### lift - -`() => void`
will lift p on the editor if possible
extended by [ListItemBridge](./BridgeExtensions#listitembridge) - -#### sink - -`() => void`
will sink p on the editor if possible
extended by [ListItemBridge](./BridgeExtensions#listitembridge) - -#### undo - -`() => void`
will undo the last history transaction if possible
extended by [HistoryBridge](./BridgeExtensions#historybridge) - -#### redo - -`() => void`
will redo the last undo transaction if possible
extended by [HistoryBridge](./BridgeExtensions#historybridge) - -#### setColor - -`(color: string) => void`
sets text color
extended by [ColorBridge](./BridgeExtensions#colorbridge) - -#### unsetColor - -`() => void`
un-sets text color
extended by [ColorBridge](./BridgeExtensions#colorbridge) - -#### setHighlight - -`(color: string) => void`
sets text highlight
extended by [HighlightBridge](./BridgeExtensions#highlightbridge) - -#### toggleHighlight - -`(color: string) => void`
toggles text highlight
extended by [HighlightBridge](./BridgeExtensions#highlightbridge) - -#### unsetHighlight - -`(color: string) => void`
un-sets text highlight
extended by [HighlightBridge](./BridgeExtensions#highlightbridge) - -#### setImage - -`(src: string) => void`
gets image url string and sets image
extended by [ImageBridge](./BridgeExtensions#imagebridge) - -#### setLink - -`(link: string \| null) => void`
gets link url as string and sets link, in case of null it will remove the link
extended by [LinkBridge](./BridgeExtensions#linkbridge) - -#### toggleTaskList - -`() => void`
will toggle task list on the editor if possible
extended by [TaskListBridge](./BridgeExtensions#tasklistbridge) - -#### toggleUnderline - -`() => void`
will toggle underline on the editor if possible
extended by [UnderlineBridge](./BridgeExtensions#underlinebridge) - - +An interface for all commands available on the React Native side of the editor. It can be extended with a [BridgeExtension](./BridgeExtensions.md). + +When using `tentapStarterKit`, the EditorBridge includes the following methods: + +## Core Functions + +| Method | Signature | Description | Extended By | +| ------------------------------ | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | +| focus | `(pos?: 'start' \| 'end' \| 'all' \| number \| boolean \| null) => void` | Focuses the editor and opens the keyboard | [CoreBridge](./BridgeExtensions#coreextension) | +| blur | `() => void` | Blurs the editor and closes the keyboard | [CoreBridge](./BridgeExtensions#coreextension) | +| webviewRef | `RefObject` | A ref for the webview that renders the editor | [CoreBridge](./BridgeExtensions#coreextension) | +| getEditorState | `() => BridgeState` | Returns the most up-to-date BridgeState | [CoreBridge](./BridgeExtensions#coreextension) | +| getHTML | `() => Promise` | Returns the editor content in HTML format | [CoreBridge](./BridgeExtensions#coreextension) | +| getText | `() => Promise` | Returns the editor content in text format | [CoreBridge](./BridgeExtensions#coreextension) | +| getJSON | `() => Promise` | Returns the editor content in JSON format | [CoreBridge](./BridgeExtensions#coreextension) | +| setContent | `(content: string) => void` | Sets the editor content from an HTML string | [CoreBridge](./BridgeExtensions#coreextension) | +| setEditable | `(editable: boolean) => void` | Sets the editable state of the editor | [CoreBridge](./BridgeExtensions#coreextension) | +| setSelection | `(from: number, to: number) => void` | Sets the selection range in the editor | [CoreBridge](./BridgeExtensions#coreextension) | +| injectCSS | `(css: string, tag?: string) => void` | Creates or updates a stylesheet. Default tag: `custom-css`. See [Dynamically Updating CSS](../examples/customCss/#dynamically-updating-css) | [CoreBridge](./BridgeExtensions#coreextension) | +| injectJS | `(js: string) => void` | Injects custom JavaScript into the editor's webview | [CoreBridge](./BridgeExtensions#coreextension) | +| updateScrollThresholdAndMargin | `(offset: number) => void` | Updates [scrollThreshold](https://prosemirror.net/docs/ref/#view.EditorProps.scrollThreshold) and [scrollMargin](https://prosemirror.net/docs/ref/#view.EditorProps.scrollMargin) | [CoreBridge](./BridgeExtensions#coreextension) | + +## Formatting Functions + +| Method | Signature | Description | Extended By | +| ------------------- | ------------------------- | --------------------------------- | ------------------------------------------------------- | +| toggleBlockquote | `() => void` | Toggles blockquote if possible | [BlockquoteBridge](./BridgeExtensions#blockquotebridge) | +| toggleCode | `() => void` | Toggles code block if possible | [CodeBridge](./BridgeExtensions#codebridge) | +| toggleItalic | `() => void` | Toggles italic if possible | [ItalicBridge](./BridgeExtensions#italicbridge) | +| toggleStrikethrough | `() => void` | Toggles strikethrough if possible | [StrikeBridge](./BridgeExtensions#strikebridge) | +| toggleUnderline | `() => void` | Toggles underline if possible | [UnderlineBridge](./BridgeExtensions#underlinebridge) | +| setColor | `(color: string) => void` | Sets text color | [ColorBridge](./BridgeExtensions#colorbridge) | +| unsetColor | `() => void` | Removes text color | [ColorBridge](./BridgeExtensions#colorbridge) | +| setHighlight | `(color: string) => void` | Sets text highlight | [HighlightBridge](./BridgeExtensions#highlightbridge) | +| toggleHighlight | `(color: string) => void` | Toggles text highlight | [HighlightBridge](./BridgeExtensions#highlightbridge) | +| unsetHighlight | `() => void` | Removes text highlight | [HighlightBridge](./BridgeExtensions#highlightbridge) | + +## List Functions + +| Method | Signature | Description | Extended By | +| ----------------- | ------------ | -------------------------------- | --------------------------------------------------------- | +| toggleBulletList | `() => void` | Toggles bullet list if possible | [BulletListBridge](./BridgeExtensions#bulletlistbridge) | +| toggleOrderedList | `() => void` | Toggles ordered list if possible | [OrderedListBridge](./BridgeExtensions#orderedlistbridge) | +| toggleTaskList | `() => void` | Toggles task list if possible | [TaskListBridge](./BridgeExtensions#tasklistbridge) | +| lift | `() => void` | Lifts list item if possible | [ListItemBridge](./BridgeExtensions#listitembridge) | +| sink | `() => void` | Sinks list item if possible | [ListItemBridge](./BridgeExtensions#listitembridge) | + +## Other Functions + +| Method | Signature | Description | Extended By | +| ------------- | -------------------------------- | ----------------------------------------------- | ------------------------------------------------- | +| toggleHeading | `(level: number) => void` | Toggles heading at specified level if possible | [HeadingBridge](./BridgeExtensions#headingbridge) | +| undo | `() => void` | Undoes the last history transaction if possible | [HistoryBridge](./BridgeExtensions#historybridge) | +| redo | `() => void` | Redoes the last undone transaction if possible | [HistoryBridge](./BridgeExtensions#historybridge) | +| setImage | `(src: string) => void` | Sets an image from the given URL | [ImageBridge](./BridgeExtensions#imagebridge) | +| setLink | `(link: string \| null) => void` | Sets a link or removes it if null is passed | [LinkBridge](./BridgeExtensions#linkbridge) | diff --git a/website/docs/api/RichText.md b/website/docs/api/RichText.md new file mode 100644 index 00000000..fd0efede --- /dev/null +++ b/website/docs/api/RichText.md @@ -0,0 +1,15 @@ +--- +sidebar_position: 4 +--- + +# RichText + +A component that wraps the WebView that renders the editor. + +### Props: + +| Name | Type | Default | Description | +| ------ | -------------- | ------- | ------------------------------------------------------------------ | +| editor | `EditorBridge` | | The bridge instance created with [useEditorBridge](./EditorBridge) | + +You can also override any of the regular [WebView props](https://github.com/react-native-webview/react-native-webview/blob/HEAD/docs/Reference.md) (although this is not recommended). diff --git a/website/docs/api/Toolbar.md b/website/docs/api/Toolbar.md new file mode 100644 index 00000000..dc448ece --- /dev/null +++ b/website/docs/api/Toolbar.md @@ -0,0 +1,135 @@ +--- +sidebar_position: 8 +--- + +# Toolbar + +A React component of a basic Toolbar that includes these features: + +- Add link context Alt text +- Change heading context Alt text + +- A variety of pre-made toolbar items: + - link + - quote + - code + - bold + - italic + - checkList + - underline + - strikethrough + - h1, h2, h3, h4, h5, h6 (Headings) + - orderedList + - bulletList + - sync + - lift + - undo + - redo + +### Props: + +| Name | Type | Default | Description | +| ---------------------- | -------------------------------------- | --------------------- | --------------------------------------------------------------------------------- | +| editor | `EditorBridge` | | The bridge instance created with [useEditorBridge](./EditorBridge). | +| hidden | `boolean` | | A prop to control whether the toolbar is shown. | +| items | `ToolbarItem[]` | DEFAULT_TOOLBAR_ITEMS | Array of `ToolbarItem`s that will be shown on the toolbar. | +| sections | `ToolbarSection[]` | TOOLBAR_SECTIONS | A set of sections organizing the toolbar items into groups. | +| contexts | `Record` | {} | Context configurations to define custom behaviors for different toolbar contexts. | +| showStickyKeyboard | `boolean` | `false` | Whether to show the sticky keyboard toggle button on the toolbar. | +| stickyKeyboardPosition | `string` | `right` | Position of the sticky keyboard button (`left` or `right`). | +| showWatermark | `boolean` | `true` | Whether to show the watermark button in the toolbar. | + +See how we add a custom toolbar item in the [color keyboard example](../examples/colorKeyboard.md). + +### ToolbarItem + +The item rendered by the toolbar component. + +```ts +export interface ToolbarItem { + onPress: ({ editor, editorState }: ArgsToolbarCB) => () => void; + active: ({ editor, editorState }: ArgsToolbarCB) => boolean; + disabled: ({ editor, editorState }: ArgsToolbarCB) => boolean; + image: ({ editor, editorState }: ArgsToolbarCB) => any; +} + +type ArgsToolbarCB = { + editor: EditorBridge; + editorState: BridgeState; +}; +``` + +## Watermark + +
+
+ ℹī¸ About the 10tap-editor Watermark +
+ +The 10tap-editor includes a watermark by default. Here's what you need to know: + +- **For Commercial Use**: If you're using 10tap-editor in a commercial project or making money from it, we rely on your support to keep 10tap-editor developed and maintained. Before removing the watermark consider ways to support 10tap-editor. + +- **For Personal Projects**: Feel free to remove the watermark! We appreciate your support through: + + - Reporting bugs + - Sharing screenshots of your projects + - Starring us on GitHub + +Thank you for being part of the 10tap-editor community! 🚀 + +-The 10tap Team + +
+ +To remove the watermark, use the `showWatermark` prop on the `Toolbar` component: + +```jsx + +``` + +### Usage + +```tsx + +``` + +### Props + +| Name | Type | Default | Description | +| ------------- | --------- | ------- | -------------------------------------------------- | +| showWatermark | `boolean` | `true` | Controls whether the watermark is shown or hidden. | + +## Sticky Keyboard + +The **Sticky Keyboard** feature allows users to toggle the keyboard visibility within the editor's toolbar. You can control whether the sticky keyboard toggle is shown and adjust its position to either the right or left of the toolbar. + +### Usage + +To enable the sticky keyboard toggle, you can pass the `showStickyKeyboard` prop to the `Toolbar` component. By default, the sticky keyboard toggle will be positioned on the right side of the toolbar, but you can change its position using the `stickyKeyboardPosition` prop. + +### Example (Right Side) + +```tsx + +``` + + + +### Props + +| Name | Type | Default | Description | +| ---------------------- | --------- | ------- | --------------------------------------------------------------------------- | +| showStickyKeyboard | `boolean` | `false` | Controls whether the sticky keyboard toggle button is shown in the toolbar. | +| stickyKeyboardPosition | `string` | `right` | Position of the sticky keyboard button (`left` or `right`). | diff --git a/website/docs/api/useEditorBridge.md b/website/docs/api/useEditorBridge.md index 285ca18d..10d77170 100644 --- a/website/docs/api/useEditorBridge.md +++ b/website/docs/api/useEditorBridge.md @@ -4,79 +4,37 @@ sidebar_position: 1 # useEditorBridge -a react hook that will return [EditorBridge](./EditorBridge) +A React hook that returns an [EditorBridge](./EditorBridge) instance. -#### bridgeExtensions +## Parameters -`BridgeExtension[]` -default: `undefined`
-A list of BridgeExtensions that will be added to the editor on the native side +| Parameter | Type | Default | Description | +| --------------------- | ------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| bridgeExtensions | `BridgeExtension[]` | `undefined` | A list of BridgeExtensions to be added to the editor on the native side. | +| initialContent | `string \| json` | `undefined` | Initial content to be loaded first in the editor. | +| autofocus | `boolean` | `false` | When true, the editor will auto-focus. | +| avoidIosKeyboard | `boolean` | `false` | **(iOS only)** Helps keep the cursor above the keyboard when the editor is full-screen and the virtual keyboard hides the bottom portion. | +| dynamicHeight | `boolean` | `false` | When true, the editor's webview will maintain the same height as the content. | +| disableColorHighlight | `boolean` | `undefined` | When true, the selection highlight will be off. When false, it will be on. On Android, this is off by default. [See issue #184](https://github.com/10play/10tap-editor/issues/184#issuecomment-2304826219) | +| theme | `EditorTheme` | `defaultEditorTheme` | Customizes default styles. See [theme example](../examples/customTheme.md). | +| editable | `boolean` | `true` | When set to false, the editor will be read-only. | +| customSource | `string` | `SimpleEditorBundleString` | Used in advanced setup. An HTML string that replaces the default simple editor. | +| onChange | `() => void` | `undefined` | Callback triggered when editor content changes. | +| DEV | `boolean` | `false` | Used in advanced setup. When true, the webview will load DEV_SERVER_URL instead of the HTML string. | +| DEV_SERVER_URL | `string` | `'http://localhost:3000'` | Used in advanced setup. URL pointing to the editor dev server. | -#### initialContent +## Usage Notes -`string | json` -default: `undefined`
-initial content that will be loaded first on the editor +### onChange Callback -#### autofocus +The `onChange` callback is called each time the editor's content changes. Within this function, you can call: -`boolean` -default: `false`
-when true the editor will auto focus +- `editor.getHTML()` +- `editor.getJSON()` +- `editor.getText()` -#### avoidIosKeyboard `IOS ONLY` +to retrieve the content. The content is not directly provided to reduce traffic between the webview and native. It's recommended to request the content in a debounced function rather than on each change. -`boolean` -default: `false`
-This helps us keep the cursor right above the keyboard when the editor is full-screen and the virtual keyboard hides the bottom portion of the editor. +### Advanced Setup -#### dynamicHeight - -`boolean` -default: `false`
-when true the editor's webview will keep the same height as the content height - -#### disableColorHighlight - -`boolean` -default: `undefined`
-when true the selection highlight will be off and when false will be on, on android this will be off by default, please see: -https://github.com/10play/10tap-editor/issues/184#issuecomment-2304826219 - -#### theme - -`EditorTheme` -default: `defaultEditorTheme` (light theme)
-this prop can be used to customize default styles, see [theme example](../examples/customTheme.md) - -#### editable - -`boolean` -default: `true`
-When set to false the editor will be `readonly` - -#### customSource - -`string` -default: `SimpleEditorBundleString`
-used in advance setup, an HTML string that will replace the default simple editor - -#### onChange - -`() => void` -you can assign a callback that will be called each time the editors content has changed. Inside this function you can call -`editor.getHTML`, `editor.getJSON` or `editor.getText` to get the content. The content is not directly provided as to not -create allot of traffic between the webview and native. It is recommended to request the content in some debounced function -and not each change. - -#### DEV - -`boolean` -default: `false`
-prop used in advance setup, when true the webview will load DEV_SERVER_URL instead of the html string - -#### DEV_SERVER_URL - -`string` -default: `http://localhost:3000`
-prop used in advanced setup, a url string that points to the editor dev server +The `customSource`, `DEV`, and `DEV_SERVER_URL` parameters are used in advanced setups. They allow for custom HTML content and development server configurations. diff --git a/website/docs/api/useEditorContent.md b/website/docs/api/useEditorContent.md index 4a4aa54a..022c2258 100644 --- a/website/docs/api/useEditorContent.md +++ b/website/docs/api/useEditorContent.md @@ -4,35 +4,29 @@ sidebar_position: 7 # useEditorContent -The useEditorContent hook is designed to efficiently retrieve the content. It monitors changes to the editor's content, and reduces unnecessary data exchanges between web and native, optimizing performance and minimizing message traffic. +The `useEditorContent` hook efficiently retrieves editor content, monitoring changes and optimizing performance by reducing unnecessary data exchanges between web and native. -#### editor +## Parameters -`EditorBridge` (required) +| Parameter | Type | Required | Description | +| --------- | -------------- | -------- | --------------------- | +| editor | `EditorBridge` | Yes | The editor instance | +| options | `Object` | No | Configuration options | -### options +### Options -#### type +| Option | Type | Default | Description | +| ---------------- | ------------------- | ------- | ------------------------------------------------------- | +| type | `EditorContentType` | - | Content type to return: `'html'`, `'text'`, or `'json'` | +| debounceInterval | `number` | `10` | Debounce interval in milliseconds | -`EditorContentType` -The type of content to return, `html` and `text` return strings, `json` returns an object. - -#### debounceInterval - -`number` -default: `10`
- -### Usage +## Usage ```tsx const content = useEditorContent(editor, { type: 'html' }); + useEffect(() => { - // Will render each time content is updated and call onSave + // Triggers each time content is updated content && onSave(content); }, [content]); ``` - -Internally `useEditorContent` will get the content by calling `editor.getHTML` (or text/json depending on the `type` option). To reduce -traffic it is called within a `debounce` with a default interval of `10`ms. This can be modified changing the `debounceInterval` option. - -In addition we can also get the content as text or as a json. diff --git a/website/docs/examples/CustomContext.md b/website/docs/examples/CustomContext.md new file mode 100644 index 00000000..49cdf189 --- /dev/null +++ b/website/docs/examples/CustomContext.md @@ -0,0 +1,247 @@ +--- +sidebar_position: 3 +--- + +# Basic Example With Custom Context + +This guide will walk you through adding a **custom context** to the toolbar in the editor. We will create a new toolbar item to switch to the custom context, define a custom section in the toolbar, and display a custom component when the context is active. + +## Step 1: Setup Your Editor + +First, we need to set up the **basic editor** using the `RichText` and `Toolbar` components from `@10play/tentap-editor`. + +```tsx +import React from 'react'; +import { SafeAreaView, KeyboardAvoidingView, StyleSheet } from 'react-native'; +import { RichText, Toolbar, useEditorBridge } from '@10play/tentap-editor'; + +export const Basic = () => { + const editor = useEditorBridge({ + autofocus: true, + avoidIosKeyboard: true, + initialContent, + }); + + return ( + + + + + + + ); +}; + +const styles = StyleSheet.create({ + fullScreen: { + flex: 1, + }, + keyboardAvoidingView: { + position: 'absolute', + width: '100%', + bottom: 0, + }, +}); + +const initialContent = `

Welcome to the basic editor!

`; +``` + +## Step 2: Create a Custom Context Component + +Now We'll create a simple custom context component that allows switching back to the main toolbar context. + +```tsx +import React from 'react'; +import { View, Text } from 'react-native'; +import type { ArgsToolbarCB } from '@10play/tentap-editor'; + +// Define the custom context component +const CustomContextComponent: React.FC = ({ + setToolbarContext, +}) => ( + + setToolbarContext('Main')}> + Switch to Main Context + + +); +``` + +## Step 3: Define a Custom Toolbar Item + +Next, we'll create a **toolbar item** that switches to the custom context when clicked. + +```tsx +import { Images } from './path to your Images'; // Import custom icon + +// Toolbar item to switch to the custom context +const customContextItem = { + onPress: + ({ setToolbarContext }: ArgsToolbarCB) => + () => + setToolbarContext('CustomContext'), + active: () => false, // No active state needed + disabled: () => false, // Always enabled + image: () => Images.customIcon, // Use an icon for the toolbar item +}; +``` + +## Step 4: Add Custom Context and Sections to the Toolbar + +Now, we'll integrate the custom context and toolbar item into the toolbar by defining custom contexts and sections. + +```tsx +import { TOOLBAR_SECTIONS } from '@10play/tentap-editor'; // Import default toolbar sections + +// Define custom contexts and sections +const customContexts: Record = { + CustomContext: { + component: CustomContextComponent, // Use your custom context component + }, +}; + +// Add your custom section to the default toolbar sections +const customSections = { + customSection: { + items: [customContextItem], // Include your custom toolbar item + }, + ...TOOLBAR_SECTIONS, // Merge with default sections +}; +``` + +## Step 5: Update the Editor with Custom Toolbar + +Finally, we will add the custom contexts and sections to the toolbar, and integrate everything into the editor. + +```tsx +export const Basic = () => { + const editor = useEditorBridge({ + autofocus: true, + avoidIosKeyboard: true, + initialContent, + }); + + return ( + + + + + + + ); +}; +``` + +## Full Example + +```tsx +import type { NativeStackScreenProps } from '@react-navigation/native-stack'; +import React from 'react'; +import { + SafeAreaView, + KeyboardAvoidingView, + Platform, + StyleSheet, + Text, + View, +} from 'react-native'; +import { RichText, Toolbar, useEditorBridge } from '@10play/tentap-editor'; +import type { + ArgsToolbarCB, + ToolbarContextConfig, +} from '../../../src/RichText/Toolbar/ToolbarTypes'; +import { TOOLBAR_SECTIONS } from '../../../src/RichText/Toolbar/actions'; +import { Images } from '../../../src/assets'; + +// Define a custom context component that will be displayed in the toolbar +const CustomContextComponent: React.FC = ({ + setToolbarContext, +}) => ( + + setToolbarContext('Main')}>Custom Context + +); +export const Basic = ({}: NativeStackScreenProps) => { + const editor = useEditorBridge({ + autofocus: true, + avoidIosKeyboard: true, + initialContent, + }); + + // Define the custom context configuration + const customContexts: Record = { + CustomContext: { + // Use the custom context component defined above + component: CustomContextComponent, + }, + }; + + // Define a custom toolbar item that switches to the CustomContext + const customContextItem = { + onPress: + ({ setToolbarContext }: ArgsToolbarCB) => + () => + setToolbarContext('CustomContext'), + active: () => false, + disabled: () => false, + image: () => Images.close, + }; + + // Create custom toolbar sections by adding the custom item to existing sections + const customSections = { + customSection: { + // Include the custom context switch item in the toolbar + items: [customContextItem], + }, + // Spread the existing default toolbar sections + ...TOOLBAR_SECTIONS, + }; + + return ( + + + + + + + ); +}; + +const exampleStyles = StyleSheet.create({ + fullScreen: { + flex: 1, + }, + keyboardAvoidingView: { + position: 'absolute', + width: '100%', + bottom: 0, + }, +}); + +const initialContent = `

This is a basic example with custom context!

`; +``` diff --git a/website/docs/examples/comments.md b/website/docs/examples/comments.md index 7ad1f9cb..16b4a9b9 100644 --- a/website/docs/examples/comments.md +++ b/website/docs/examples/comments.md @@ -4,12 +4,51 @@ sidebar_position: 8 # Comments -:::info +
+
+ ⭐ī¸ +

Pro Feature

+
+

+ The Comments Feature is part of our Pro subscription, which includes: +

+
    +
  • Access to all Pro examples
    • +
  • 1:1 support from the 10tap team
    • +
  • Prioritized GitHub issues
    • +
  • MIT License for 10tap
    • +
+ + Learn more about Pro → + +
-This is a Pro example. Get all pro examples, 1:1 support from the 10tap team, prioritized Github issues and keep 10tap under an MIT License with a 10tap Pro subscription. See plans +## Overview -::: +The Comments Feature allows users to add, view, and respond to comments within the document, facilitating discussion and feedback directly in the context of the content.
- +
+ +### Key Benefits + +- **Contextual Feedback**: Add comments directly to specific parts of the document. +- **Collaborative Editing**: Engage in discussions about content without altering the main text. +- **Track Changes**: Keep a record of suggestions and revisions. +- **Improved Communication**: Enhance team collaboration with clear, targeted feedback. + +## Implementation + +Detailed implementation instructions, including code examples and best practices, are available in our comprehensive Pro documentation. With our Pro subscription, you'll have access to step-by-step guides on integrating and customizing the Comments Feature for your specific use case. diff --git a/website/docs/examples/fonts.md b/website/docs/examples/fonts.md index 0ff09aa5..a7148ff5 100644 --- a/website/docs/examples/fonts.md +++ b/website/docs/examples/fonts.md @@ -2,14 +2,41 @@ sidebar_position: 6 --- -# Formatting keyboard - -:::info - -This is a Pro example. Get all pro examples, 1:1 support from the 10tap team, prioritized Github issues and keep 10tap under an MIT License with a 10tap Pro subscription. See plans - -::: +# Formatting Keyboard +
+
+ ⭐ī¸ +

Pro Feature

+
+

+ The Formatting Keyboard is part of our Pro subscription, which includes: +

+
    +
  • Access to all Pro examples
    • +
  • 1:1 support from the 10tap team
    • +
  • Prioritized GitHub issues
    • +
  • MIT License for 10tap
    • +
+ + Learn more about Pro → + +
- +
+ +## Implementation + +For detailed implementation instructions and code examples, please refer to our comprehensive documentation available with the Pro subscription. diff --git a/website/docs/examples/mentions.md b/website/docs/examples/mentions.md index e6a812a0..1b256052 100644 --- a/website/docs/examples/mentions.md +++ b/website/docs/examples/mentions.md @@ -4,12 +4,60 @@ sidebar_position: 6 # Mentions -:::info +
+
+ ⭐ī¸ +

Pro Feature

+
+

+ The Mentions feature is part of our Pro subscription, which includes: +

+
    +
  • Access to all Pro examples
    • +
  • 1:1 support from the 10tap team
    • +
  • Prioritized GitHub issues
    • +
  • MIT License for 10tap
    • +
+ + Learn more about Pro → + +
-This is a Pro example. Get all pro examples, 1:1 support from the 10tap team, prioritized Github issues and keep 10tap under an MIT License with a 10tap Pro subscription. See plans +## Feature Overview -::: +The Mentions feature allows users to easily tag or reference other users, topics, or entities within the editor. This functionality enhances collaboration and content organization in various applications such as team communication tools, social media platforms, and collaborative document editing. -
- +
+ Mentions Feature Demo
+ +### Key Benefits + +- **Enhanced Collaboration**: Easily mention team members or relevant topics. +- **Improved Navigation**: Quick links to referenced users or content. +- **Customizable Suggestions**: Tailor the mention suggestions to your application's needs. +- **Seamless Integration**: Works smoothly within the 10tap editor ecosystem. + +## Implementation + +Detailed implementation instructions, including code examples and best practices, are available in our comprehensive Pro documentation. With our Pro subscription, you'll have access to step-by-step guides on integrating and customizing the Mentions feature for your specific use case. diff --git a/website/docs/examples/realtimeCollab.md b/website/docs/examples/realtimeCollab.md index 3277cac4..4790076b 100644 --- a/website/docs/examples/realtimeCollab.md +++ b/website/docs/examples/realtimeCollab.md @@ -2,12 +2,51 @@ sidebar_position: 8 --- -# Real-time collaboration +# Real-time Collaboration -:::info +
+
+ ⭐ī¸ +

Pro Feature

+
+

+ Real-time Collaboration is part of our Pro subscription, which includes: +

+
    +
  • Access to all Pro examples
    • +
  • 1:1 support from the 10tap team
    • +
  • Prioritized GitHub issues
    • +
  • MIT License for 10tap
    • +
+ + Learn more about Pro → + +
-This is a Pro example. Get all pro examples, 1:1 support from the 10tap team, prioritized Github issues and keep 10tap under an MIT License with a 10tap Pro subscription. See plans +## Overview -::: +Real-time Collaboration allows multiple users to work on the same document simultaneously, seeing each other's changes in real-time. This feature is essential for team productivity and seamless cooperation. -Video: TBD +Video demonstration: TBD + +### Key Benefits + +- **Simultaneous Editing**: Multiple users can edit the document at the same time. +- **Instant Updates**: Changes are reflected immediately for all collaborators. +- **Increased Productivity**: Streamline teamwork and reduce back-and-forth communication. +- **Version Control**: Keep track of changes and easily revert if needed. + +## Implementation + +Detailed implementation instructions, including code examples and best practices, are available in our comprehensive Pro documentation. With our Pro subscription, you'll have access to step-by-step guides on integrating and customizing Real-time Collaboration for your specific use case. diff --git a/website/docs/examples/search.md b/website/docs/examples/search.md index 9e3ea3fb..7e019eba 100644 --- a/website/docs/examples/search.md +++ b/website/docs/examples/search.md @@ -4,12 +4,51 @@ sidebar_position: 6 # Search -:::info +
+
+ ⭐ī¸ +

Pro Feature

+
+

+ The Search Feature is part of our Pro subscription, which includes: +

+
    +
  • Access to all Pro examples
    • +
  • 1:1 support from the 10tap team
    • +
  • Prioritized GitHub issues
    • +
  • MIT License for 10tap
    • +
+ + Learn more about Pro → + +
-This is a Pro example. Get all pro examples, 1:1 support from the 10tap team, prioritized Github issues and keep 10tap under an MIT License with a 10tap Pro subscription. See plans +## Overview -::: +The Search Feature allows users to quickly find and navigate to specific content within the editor. This powerful tool enhances the user experience by making large documents easily manageable.
- + Search Feature Demo
+ +### Key Benefits + +- **Quick Content Location**: Rapidly find specific text or elements within documents. +- **Enhanced Navigation**: Jump to search results effortlessly. +- **Improved Productivity**: Save time when working with large or complex documents. +- **Customizable Search Options**: Fine-tune your search with various filters and options. + +## Implementation + +Detailed implementation instructions, including code examples and best practices, are available in our comprehensive Pro documentation. With our Pro subscription, you'll have access to step-by-step guides on integrating and customizing the Search Feature for your specific use case. diff --git a/website/docs/mainConcepts.md b/website/docs/mainConcepts.md index bf4b551b..2a27c8c5 100644 --- a/website/docs/mainConcepts.md +++ b/website/docs/mainConcepts.md @@ -8,7 +8,7 @@ sidebar_position: 1 `bridgeExtension` - a typed class that helps us communicate between the native part and the webview part -There are two different ways to work with this lib: [simple](./mainConcepts#simple-usage) and [advanced](./mainConcepts#advance-usage), simple should be good enough for most of the cases, we tried to make the API as simple as possible so people will be able to plug and play, on the other hand advanced usage requires a longer setup. +There are two different ways to work with this lib: [simple](./mainConcepts#simple-usage) and [advanced](./mainConcepts#advanced-usage), simple should be good enough for most of the cases, we tried to make the API as simple as possible so people will be able to plug and play, on the other hand advanced usage requires a longer setup. ## Simple usage diff --git a/website/sidebars.ts b/website/sidebars.ts index 5bafc176..e53a28ea 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -19,10 +19,11 @@ const sidebars: SidebarsConfig = { 'api/useEditorBridge', 'api/EditorBridge', 'api/BridgeState', - 'api/Components', + 'api/RichText', 'api/CustomKeyboardUtils', 'api/BridgeExtensions', 'api/useEditorContent', + 'api/Toolbar', ], }, { @@ -31,6 +32,7 @@ const sidebars: SidebarsConfig = { collapsed: false, // Ensure the Examples category is open by default items: [ 'examples/basic', + 'examples/CustomContext', 'examples/customCss', { type: 'doc',