Skip to content

Commit 21a5692

Browse files
dominicstopdominicstop
committed
📝 Docs: Update README
1 parent 1d67bc7 commit 21a5692

File tree

3 files changed

+13
-73
lines changed

3 files changed

+13
-73
lines changed

‎README.md‎

Lines changed: 7 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
11
# react-native-ios-context-menu
22

3-
<p>
4-
<img src="https://github.com/dominicstop/react-native-ios-context-menu/workflows/Build%20Example/badge.svg" />
5-
</p>
6-
<br>
3+
A small component for using context menu's on iOS.
4+
5+
<br><br>
76

87
## 🚧⚠️ Documentation WIP ⚠️🚧
98

@@ -34,8 +33,6 @@
3433
| `1.4` | iOS 10 to iOS 15<br>Xcode 13+ |
3534
| `1.3` and Below | iOS 10 to 14<br>Xcode 12+ |
3635

37-
📝 **Note**: Supports projects targeting iOS 10 but will use the action sheet fallback when running on iOS 12 and older.
38-
3936
<br><br>
4037

4138
## Table of Contents
@@ -117,8 +114,6 @@ Very special thanks to: [junzhengca](https://github.com/junzhengca), [brentvatne
117114

118115
<br><br>
119116

120-
<br><br>
121-
122117
## A. Introduction
123118

124119
A react native component to use [`UIMenu`](https://developer.apple.com/documentation/uikit/uimenu) on iOS 13 and later.
@@ -159,7 +154,7 @@ A react native component to use [`UIMenu`](https://developer.apple.com/documenta
159154
`ContextMenuView` `ActionSheetIOS` fallback for simple example 1 to 9
160155
![Action Sheet Fallback for Simple Example 1 to 9 Gifs](./assets/montage-ContextMenuView-ActionSheetFallback-Example-old-1-to-9.gif)
161156

162-
`ContextMenuView` `ActionSheetIOS` fallback for context menu view test 1 to 6
157+
`ContextMenuView` `ActionSheetIOS` fallback for context menu view test 1 to 6 (removed in `v3.x`+).
163158
![Action Sheet Fallback for Context Menu View Test 1 to 6 Gifs](./assets/montage-ContextMenuView-ActionSheetFallback-Test-old-1-to-6.gif)
164159

165160
`ContextMenuButton` examples, **Left**: [Example 1](#ContextMenuButton-Example-01), and **Right**: [Example 2](#ContextMenuButton-Example-02)
@@ -174,7 +169,7 @@ A react native component to use [`UIMenu`](https://developer.apple.com/documenta
174169
* Extensive support for SF Symbols configuration (e.g. `pointSize`, `weight`, `scale`, `hierarchicalColor`, `paletteColors`).
175170
* Support for iOS 14 functionality (like the `UIButton` context menu, dynamically updating the menu while it's visible, etc).
176171
* Support for setting (almost) all of the native [`UIMenu`](https://developer.apple.com/documentation/uikit/uimenu) and [`UIAction`](https://developer.apple.com/documentation/uikit/uiaction) properties (e.g. `UIMenuElementState`, `MenuElementAtrributes`, `discoverabilityTitle`, etc.)
177-
* Basic `ActionSheetIOS` menu fallback for iOS 12 and below.
172+
* Basic `ActionSheetIOS` menu fallback for iOS 12 and below (removed in `v3.x`+).
178173
* Support for creating custom context menu previews (with support for dynamic or fixed preview sizes, setting the [`UIPreviewParameters`](https://developer.apple.com/documentation/uikit/uipreviewparameters), specifying a [`UITargetedPreview`](https://developer.apple.com/documentation/uikit/uitargetedpreview), etc).
179174
* Support for custom auxiliary previews (experimental).
180175
* Support for deferred context menu items.
@@ -253,7 +248,7 @@ pod update
253248

254249
### Troubleshooting
255250

256-
If you encounter any errors/bugs while using this library, or want a particular feature implemented, please create an issue! (my inbox is a mess, please feel free to tag me). ✨
251+
If you encounter any errors/bugs while using this library, or want a particular feature implemented, please create an issue (my inbox is a mess, please feel free to tag me). ✨
257252

258253
<br>
259254

@@ -389,15 +384,10 @@ const styles = StyleSheet.create({
389384
| 🔤 `shouldWaitForMenuToHide`<br/>`BeforeFiringOnPressMenuItem`<br/><br/>⚛️ `boolean`<br/><br/>✳️ **Default**: `true` | If set to `true` (which it is by default), the `onPressMenuItem` event will be triggered after the context menu has been hidden (i.e. after `onMenuDidHide` event is triggered).<br><br>Set this to `false` if you want `onPressMenuItem` to trigger as soon as an item has been pressed in the context menu.<br><br>📝 **Note**: Layout updates while the context menu is transitioning from it's open to hidden state might cause layout flickering (e.g. [Issue #43](https://github.com/dominicstop/react-native-ios-context-menu/issues/43)). |
390385
| 🔤 `isContextMenuEnabled`<br/><br/>⚛️ `boolean`<br/><br/>✳️ **Default**: `true` | Enables or disables the context menu. Useful if you want to temporarily disable the context menu. |
391386
| 🔤 `lazyPreview`<br/><br/>⚛️ `boolean`<br><br>✳️ **Default**: `true` | If set to `true` (which it is by default), the custom context menu preview (i.e. the component returned from the `ContextMenuView.renderPreview` prop) and the auxiliary preview (i.e. the component returned from the `ContextMenuView.renderAuxillaryPreview` prop) are only mounted/rendered when the context menu is visible.<br><br>Set this to `false` if you want the preview content to be always mounted. |
392-
| 🔤 `shouldEnable`<br>`AggressiveCleanup`<br/><br/>⚛️ `boolean`<br/><br/>✳️ **Default**: `true` | Deprecated. This prop no longer does anything (see `shouldCleanupOnComponentWillUnmount`<br>`ForMenuPreview`, and `shouldCleanup`<br/>`OnComponentWillUnmountForAuxPreview`<br/>). |
393-
| 🔤 `useActionSheetFallback`<br><br/>⚛️ `boolean`<br/><br/>✳️ **Default**: `true` | Context menus are only supported on iOS 13+ (i.e context menus are not supported on iOS 12, and below).<br><br>On iOS 12 and below, a long press on a `ContextMenuView` will show a [`ActionSheetIOS`](https://reactnative.dev/docs/actionsheetios#docsNav) menu based on the current `menuConfig` prop.<br><br> If you want to disable this behavior, set this prop to false.<br><br>📝 **Note**: Default value is `false` on iOS 13+, and `true` on iOS 12 and below. |
394387
| 🔤 `renderPreview`<br/><br/>⚛️ [`() => React.ReactElement`](PLACE_HOLDER_LINK) | This prop is a "render" prop, i.e it accepts a function that returns a react component.<br><br>The returned component will displayed in the context menu preview. |
395388
| 🔤 `isAuxiliaryPreviewEnabled`<br/><br/>⚛️ `boolean`<br/><br/>✳️ **Default**: `false` | ⚠️ **Experimental**: Please see [Auxiliary Preview](#contextmenuview-component-experimental---auxiliary-preview) section.<br/><br/>TBA |
396389
| 🔤 `auxiliaryPreviewConfig`<br/><br/>⚛️ `MenuAuxiliaryPreviewConfig` | ⚠️ **Experimental**: Please see [Auxiliary Preview](#contextmenuview-component-experimental---auxiliary-preview) section.<br/><br/>TBA |
397390
| 🔤 `renderAuxillaryPreview`<br/><br/>⚛️ `() => React.ReactElement` | ⚠️ **Experimental**: Please see [Auxiliary Preview](#contextmenuview-component-experimental---auxiliary-preview) section.<br/><br/>TBA |
398-
| 🔤 `internalCleanupMode`<br/><br/>⚛️ `RNICleanupMode`<br/><br/>✳️ **Default**: `automatic` | Internally, a clean up routine is triggered whenever a component is unmounted.<br><br>However, if the clean up routine is triggered too early, this will lead to the context menu component disappearing (E.g. [issue #34](https://github.com/dominicstop/react-native-ios-context-menu/issues/34)).<br><br>If you are experiencing this issue, you can disable the clean up routine from triggering altogether by setting this prop to `disabled`.<br><br>Additionally, you can also try setting this prop to either to `viewController`, `didMoveToWindowNil`, or `reactComponentWillUnmount`.<br/><br/>`viewController` mode will trigger the clean up routine via the `UIViewController.viewWillDisappear` lifecycle method, and `didMoveToWindowNil` will trigger the cleanup routine during the `UIView.didMoveToWindow` lifecycle method, while the `reactComponentWillUnmount` mode on the other hand, will trigger the clean up routine via the `componentWillUnmount` react lifecycle event. |
399-
| 🔤 `shouldCleanupOnComponent`<br>`WillUnmountForMenuPreview`<br/><br/>⚛️ `boolean`<br/><br/>✳️ **Default**: `false` | If set to `true`, the custom preview is immediately freed from memory once the context menu is closed.<br/><br/>📝 **Note**: For the immediately cleanup to take effect, the `lazyPreview` prop also needs to be enabled. |
400-
| 🔤 `shouldCleanupOnComponent`<br/>`WillUnmountForAuxPreview`<br/><br/>⚛️ `boolean`<br/><br/>✳️ **Default**: `false` | If set to `true`, the aux. preview is immediately freed from memory once the context menu is closed.<br/><br/>📝 **Note**: For the immediately cleanup to take effect, the `lazyPreview` prop also needs to be enabled. |
401391

402392
<br><br>
403393

@@ -445,7 +435,7 @@ For basic usage, please see [Example 1](#contextmenubutton-example-01) section.
445435

446436
* The only difference between them is that the `ContextMenuButton` component does not have a preview, and it can be immediately shown when its tapped instead of having to do a long press. See [Example 2](#422-contextmenubutton-simple-example-2) for more details.<br>
447437

448-
* Note that `ContextMenuButton` is only available on iOS 14 and above. On iOS 13, it will use a `ContextMenuButton`, and on iOS 12 and below, it will use the `ActionSheetFallback` module to present a `ActionSheetIOS` menu.<br>
438+
* Note that `ContextMenuButton` is only available on iOS 14 and above. On iOS 13, it will use a `ContextMenuButton`,<br>
449439

450440
* If you want to add additional touch events, you can wrap this component inside a button component (e.g. `TouchableOpacity`). <br>
451441
* When wrapping this component inside a button, please make sure to set the `useActionSheetFallback` prop to `false`.
@@ -488,27 +478,6 @@ For basic usage, please see [Example 1](#contextmenubutton-example-01) section.
488478

489479
<br>
490480

491-
#### `ActionSheetFallback` Module
492-
493-
A module to show a `ActionSheetIOS` menu based on a `MenuConfig` object.
494-
495-
This module attempts to approximate `UIMenu` behavior using `ActionSheetIOS`, so it's very limited (i.e. it does not support menu/action icons, etc.), but it does support things like submenu's, destructive actions/menu's, inline submenu's, and hidden actions.
496-
497-
<br>
498-
499-
* Import the module like this: `import { ActionSheetFallback } from "react-native-ios-context-menu";`<br><br>
500-
501-
* To present a `ActionSheetIOS` menu, call `const selectedAction = await ActionSheetFallback.show(menuConfig)`
502-
503-
<br>
504-
505-
506-
| Function | Description |
507-
| ------------------------------------------------------------ | ------------------------------------------------------------ |
508-
| 🔤 `show` <br/><br/>⚛️ `(menuConfig: MenuConfig):`<br/>`Promise<MenuAction ¦ null>` | This function accepts a `MenuConfig` object and returns the selected `MenuAction` object or null if cancelled. |
509-
510-
<br>
511-
512481
### D.2. Context
513482

514483
#### `ContextMenuViewContext` Context

‎docs/README-01-Pre.md‎

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
11
# react-native-ios-context-menu
22

3-
<p>
4-
<img src="https://github.com/dominicstop/react-native-ios-context-menu/workflows/Build%20Example/badge.svg" />
5-
</p>
6-
<br>
3+
A small component for using context menu's on iOS.
4+
5+
<br><br>
76

87
## 🚧⚠️ Documentation WIP ⚠️🚧
98

@@ -115,8 +114,6 @@ Very special thanks to: [junzhengca](https://github.com/junzhengca), [brentvatne
115114

116115
<br><br>
117116

118-
<br><br>
119-
120117
## A. Introduction
121118

122119
A react native component to use [`UIMenu`](https://developer.apple.com/documentation/uikit/uimenu) on iOS 13 and later.
@@ -157,7 +154,7 @@ A react native component to use [`UIMenu`](https://developer.apple.com/documenta
157154
`ContextMenuView` `ActionSheetIOS` fallback for simple example 1 to 9
158155
![Action Sheet Fallback for Simple Example 1 to 9 Gifs](../assets/montage-ContextMenuView-ActionSheetFallback-Example-old-1-to-9.gif)
159156

160-
`ContextMenuView` `ActionSheetIOS` fallback for context menu view test 1 to 6
157+
`ContextMenuView` `ActionSheetIOS` fallback for context menu view test 1 to 6 (removed in `v3.x`+).
161158
![Action Sheet Fallback for Context Menu View Test 1 to 6 Gifs](../assets/montage-ContextMenuView-ActionSheetFallback-Test-old-1-to-6.gif)
162159

163160
`ContextMenuButton` examples, **Left**: [Example 1](#ContextMenuButton-Example-01), and **Right**: [Example 2](#ContextMenuButton-Example-02)
@@ -172,7 +169,7 @@ A react native component to use [`UIMenu`](https://developer.apple.com/documenta
172169
* Extensive support for SF Symbols configuration (e.g. `pointSize`, `weight`, `scale`, `hierarchicalColor`, `paletteColors`).
173170
* Support for iOS 14 functionality (like the `UIButton` context menu, dynamically updating the menu while it's visible, etc).
174171
* Support for setting (almost) all of the native [`UIMenu`](https://developer.apple.com/documentation/uikit/uimenu) and [`UIAction`](https://developer.apple.com/documentation/uikit/uiaction) properties (e.g. `UIMenuElementState`, `MenuElementAtrributes`, `discoverabilityTitle`, etc.)
175-
* Basic `ActionSheetIOS` menu fallback for iOS 12 and below.
172+
* Basic `ActionSheetIOS` menu fallback for iOS 12 and below (removed in `v3.x`+).
176173
* Support for creating custom context menu previews (with support for dynamic or fixed preview sizes, setting the [`UIPreviewParameters`](https://developer.apple.com/documentation/uikit/uipreviewparameters), specifying a [`UITargetedPreview`](https://developer.apple.com/documentation/uikit/uitargetedpreview), etc).
177174
* Support for custom auxiliary previews (experimental).
178175
* Support for deferred context menu items.

‎docs/README-02-Docs.md‎

Lines changed: 1 addition & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -19,15 +19,10 @@
1919
| 🔤 `shouldWaitForMenuToHide`<br/>`BeforeFiringOnPressMenuItem`<br/><br/>⚛️ `boolean`<br/><br/>✳️ **Default**: `true` | If set to `true` (which it is by default), the `onPressMenuItem` event will be triggered after the context menu has been hidden (i.e. after `onMenuDidHide` event is triggered).<br><br>Set this to `false` if you want `onPressMenuItem` to trigger as soon as an item has been pressed in the context menu.<br><br>📝 **Note**: Layout updates while the context menu is transitioning from it's open to hidden state might cause layout flickering (e.g. [Issue #43](https://github.com/dominicstop/react-native-ios-context-menu/issues/43)). |
2020
| 🔤 `isContextMenuEnabled`<br/><br/>⚛️ `boolean`<br/><br/>✳️ **Default**: `true` | Enables or disables the context menu. Useful if you want to temporarily disable the context menu. |
2121
| 🔤 `lazyPreview`<br/><br/>⚛️ `boolean`<br><br>✳️ **Default**: `true` | If set to `true` (which it is by default), the custom context menu preview (i.e. the component returned from the `ContextMenuView.renderPreview` prop) and the auxiliary preview (i.e. the component returned from the `ContextMenuView.renderAuxillaryPreview` prop) are only mounted/rendered when the context menu is visible.<br><br>Set this to `false` if you want the preview content to be always mounted. |
22-
| 🔤 `shouldEnable`<br>`AggressiveCleanup`<br/><br/>⚛️ `boolean`<br/><br/>✳️ **Default**: `true` | Deprecated. This prop no longer does anything (see `shouldCleanupOnComponentWillUnmount`<br>`ForMenuPreview`, and `shouldCleanup`<br/>`OnComponentWillUnmountForAuxPreview`<br/>). |
23-
| 🔤 `useActionSheetFallback`<br><br/>⚛️ `boolean`<br/><br/>✳️ **Default**: `true` | Context menus are only supported on iOS 13+ (i.e context menus are not supported on iOS 12, and below).<br><br>On iOS 12 and below, a long press on a `ContextMenuView` will show a [`ActionSheetIOS`](https://reactnative.dev/docs/actionsheetios#docsNav) menu based on the current `menuConfig` prop.<br><br> If you want to disable this behavior, set this prop to false.<br><br>📝 **Note**: Default value is `false` on iOS 13+, and `true` on iOS 12 and below. |
2422
| 🔤 `renderPreview`<br/><br/>⚛️ [`() => React.ReactElement`](PLACE_HOLDER_LINK) | This prop is a "render" prop, i.e it accepts a function that returns a react component.<br><br>The returned component will displayed in the context menu preview. |
2523
| 🔤 `isAuxiliaryPreviewEnabled`<br/><br/>⚛️ `boolean`<br/><br/>✳️ **Default**: `false` | ⚠️ **Experimental**: Please see [Auxiliary Preview](#contextmenuview-component-experimental---auxiliary-preview) section.<br/><br/>TBA |
2624
| 🔤 `auxiliaryPreviewConfig`<br/><br/>⚛️ `MenuAuxiliaryPreviewConfig` | ⚠️ **Experimental**: Please see [Auxiliary Preview](#contextmenuview-component-experimental---auxiliary-preview) section.<br/><br/>TBA |
2725
| 🔤 `renderAuxillaryPreview`<br/><br/>⚛️ `() => React.ReactElement` | ⚠️ **Experimental**: Please see [Auxiliary Preview](#contextmenuview-component-experimental---auxiliary-preview) section.<br/><br/>TBA |
28-
| 🔤 `internalCleanupMode`<br/><br/>⚛️ `RNICleanupMode`<br/><br/>✳️ **Default**: `automatic` | Internally, a clean up routine is triggered whenever a component is unmounted.<br><br>However, if the clean up routine is triggered too early, this will lead to the context menu component disappearing (E.g. [issue #34](https://github.com/dominicstop/react-native-ios-context-menu/issues/34)).<br><br>If you are experiencing this issue, you can disable the clean up routine from triggering altogether by setting this prop to `disabled`.<br><br>Additionally, you can also try setting this prop to either to `viewController`, `didMoveToWindowNil`, or `reactComponentWillUnmount`.<br/><br/>`viewController` mode will trigger the clean up routine via the `UIViewController.viewWillDisappear` lifecycle method, and `didMoveToWindowNil` will trigger the cleanup routine during the `UIView.didMoveToWindow` lifecycle method, while the `reactComponentWillUnmount` mode on the other hand, will trigger the clean up routine via the `componentWillUnmount` react lifecycle event. |
29-
| 🔤 `shouldCleanupOnComponent`<br>`WillUnmountForMenuPreview`<br/><br/>⚛️ `boolean`<br/><br/>✳️ **Default**: `false` | If set to `true`, the custom preview is immediately freed from memory once the context menu is closed.<br/><br/>📝 **Note**: For the immediately cleanup to take effect, the `lazyPreview` prop also needs to be enabled. |
30-
| 🔤 `shouldCleanupOnComponent`<br/>`WillUnmountForAuxPreview`<br/><br/>⚛️ `boolean`<br/><br/>✳️ **Default**: `false` | If set to `true`, the aux. preview is immediately freed from memory once the context menu is closed.<br/><br/>📝 **Note**: For the immediately cleanup to take effect, the `lazyPreview` prop also needs to be enabled. |
3126

3227
<br><br>
3328

@@ -75,7 +70,7 @@ For basic usage, please see [Example 1](#contextmenubutton-example-01) section.
7570

7671
* The only difference between them is that the `ContextMenuButton` component does not have a preview, and it can be immediately shown when its tapped instead of having to do a long press. See [Example 2](#422-contextmenubutton-simple-example-2) for more details.<br>
7772

78-
* Note that `ContextMenuButton` is only available on iOS 14 and above. On iOS 13, it will use a `ContextMenuButton`, and on iOS 12 and below, it will use the `ActionSheetFallback` module to present a `ActionSheetIOS` menu.<br>
73+
* Note that `ContextMenuButton` is only available on iOS 14 and above. On iOS 13, it will use a `ContextMenuButton`,<br>
7974

8075
* If you want to add additional touch events, you can wrap this component inside a button component (e.g. `TouchableOpacity`). <br>
8176
* When wrapping this component inside a button, please make sure to set the `useActionSheetFallback` prop to `false`.
@@ -118,27 +113,6 @@ For basic usage, please see [Example 1](#contextmenubutton-example-01) section.
118113

119114
<br>
120115

121-
#### `ActionSheetFallback` Module
122-
123-
A module to show a `ActionSheetIOS` menu based on a `MenuConfig` object.
124-
125-
This module attempts to approximate `UIMenu` behavior using `ActionSheetIOS`, so it's very limited (i.e. it does not support menu/action icons, etc.), but it does support things like submenu's, destructive actions/menu's, inline submenu's, and hidden actions.
126-
127-
<br>
128-
129-
* Import the module like this: `import { ActionSheetFallback } from "react-native-ios-context-menu";`<br><br>
130-
131-
* To present a `ActionSheetIOS` menu, call `const selectedAction = await ActionSheetFallback.show(menuConfig)`
132-
133-
<br>
134-
135-
136-
| Function | Description |
137-
| ------------------------------------------------------------ | ------------------------------------------------------------ |
138-
| 🔤 `show` <br/><br/>⚛️ `(menuConfig: MenuConfig):`<br/>`Promise<MenuAction ¦ null>` | This function accepts a `MenuConfig` object and returns the selected `MenuAction` object or null if cancelled. |
139-
140-
<br>
141-
142116
### D.2. Context
143117

144118
#### `ContextMenuViewContext` Context

0 commit comments

Comments
 (0)