feat(doc): add doc about how to use popover

frontend/app_flowy/packages/appflowy_popover/README.md

@@ -1,38 +1,107 @@
-<!--
-This README describes the package. If you publish this package to pub.dev,
-this README's contents appear on the landing page for your package.
-
-For information about how to write a good package README, see the guide for
-[writing package pages](https://dart.dev/guides/libraries/writing-package-pages).
-
-For general information about developing packages, see the Dart guide for
-[creating packages](https://dart.dev/guides/libraries/create-library-packages)
-and the Flutter guide for
-[developing packages and plugins](https://flutter.dev/developing-packages).
--->
-
 # AppFlowy Popover
 
 A Popover can be used to display some content on top of another.
 
-## Features
+It can be used to display a dropdown menu.
 
 > A popover is a transient view that appears above other content onscreen when you tap a control or in an area. Typically, a popover includes an arrow pointing to the location from which it emerged. Popovers can be nonmodal or modal. A nonmodal popover is dismissed by tapping another part of the screen or a button on the popover. A modal popover is dismissed by tapping a Cancel or other button on the popover.
 
 Source: [Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/ios/views/popovers/).
 
+## Features
+
 - Basic popover style
+- Follow the target automatically
 - Nested popover support
-- Exclusive popover API
+- Exclusive API
+
+![](./screenshot.png)
 
 ## Example
 
 ```dart
 Popover(
+  // Define how to trigger the popover
   triggerActions: PopoverTriggerActionFlags.click,
   child: TextButton(child: Text("Popover"), onPressed: () {}),
+  // Define the direction of the popover
+  direction: PopoverDirection.bottomWithLeftAligned,
   popupBuilder(BuildContext context) {
     return PopoverMenu();
   },
 );
 ```
+
+### Trigger the popover manually
+
+Sometimes, if you want to trigger the popover manually, you can use a `PopoverController`.
+
+```dart
+class MyWidgetState extends State<GridDateCell> {
+  late PopoverController _popover;
+
+  @override
+  void initState() {
+    _popover = PopoverController();
+    super.initState();
+  }
+
+  // triggered by another widget
+  _onClick() {
+    _popover.show();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Popover(
+      controller: _popover,
+      ...
+    )
+  }
+}
+```
+
+### Make several popovers exclusive
+
+The popover has a mechanism to make sure there are only one popover is shown in a group of popovers.
+It's called `PopoverMutex`.
+
+If you pass the same mutex object to the popovers, there will be only one popover is triggered.
+
+```dart
+class MyWidgetState extends State<GridDateCell> {
+  final _popoverMutex = PopoverMutex();
+
+  @override
+  Widget build(BuildContext context) {
+    return Row(
+      children: [
+        Popover(
+          mutex: _popoverMutex,
+          ...
+        ),
+        Popover(
+          mutex: _popoverMutex,
+          ...
+        ),
+        Popover(
+          mutex: _popoverMutex,
+          ...
+        ),
+      ]
+    )
+  }
+}
+```
+
+## API
+
+| Param          | Description                                                      | Type                                    |
+| -------------- | ---------------------------------------------------------------- | --------------------------------------- |
+| offset         | The offset between the popover and the child                     | `Offset`                                |
+| popupBuilder   | The function used to build the popover                           | `Widget Function(BuildContext context)` |
+| triggerActions | Define the actions about how to trigger the popover              | `int`                                   |
+| mutex          | If multiple popovers are exclusive, pass the same mutex to them. | `PopoverMutex`                          |
+| direction      | The direction where the popover should be placed                 | `PopoverDirection`                      |
+| onClose        | The callback will be called after the popover is closed          | `void Function()`                       |
+| child          | The child to trigger the popover                                 | `Widget`                                |

frontend/app_flowy/packages/appflowy_popover/example/lib/example_button.dart

@@ -13,40 +13,61 @@ class _PopoverMenuState extends State<PopoverMenu> {
 
   @override
   Widget build(BuildContext context) {
-    return Container(
+    return Material(
-      width: 200,
+        type: MaterialType.transparency,
-      height: 200,
+        child: Container(
-      decoration: const BoxDecoration(color: Colors.yellow),
+          width: 200,
-      child: ListView(children: [
+          height: 200,
-        const Text("App"),
+          decoration: BoxDecoration(
-        Popover(
+            color: Colors.white,
-          triggerActions:
+            borderRadius: const BorderRadius.all(Radius.circular(8)),
-              PopoverTriggerActionFlags.hover | PopoverTriggerActionFlags.click,
+            boxShadow: [
-          mutex: popOverMutex,
+              BoxShadow(
-          offset: const Offset(10, 0),
+                color: Colors.grey.withOpacity(0.5),
-          popupBuilder: (BuildContext context) {
+                spreadRadius: 5,
-            return const PopoverMenu();
+                blurRadius: 7,
-          },
+                offset: const Offset(0, 3), // changes position of shadow
-          child: TextButton(
+              ),
-            onPressed: () {},
+            ],
-            child: const Text("First"),
           ),
-        ),
+          child: ListView(children: [
-        Popover(
+            Container(
-          triggerActions:
+              margin: const EdgeInsets.all(8),
-              PopoverTriggerActionFlags.hover | PopoverTriggerActionFlags.click,
+              child: const Text("Popover",
-          mutex: popOverMutex,
+                  style: TextStyle(
-          offset: const Offset(10, 0),
+                      fontSize: 14,
-          popupBuilder: (BuildContext context) {
+                      color: Colors.black,
-            return const PopoverMenu();
+                      fontStyle: null,
-          },
+                      decoration: null)),
-          child: TextButton(
+            ),
-            onPressed: () {},
+            Popover(
-            child: const Text("Second"),
+              triggerActions: PopoverTriggerActionFlags.hover |
-          ),
+                  PopoverTriggerActionFlags.click,
-        ),
+              mutex: popOverMutex,
-      ]),
+              offset: const Offset(10, 0),
-    );
+              popupBuilder: (BuildContext context) {
+                return const PopoverMenu();
+              },
+              child: TextButton(
+                onPressed: () {},
+                child: const Text("First"),
+              ),
+            ),
+            Popover(
+              triggerActions: PopoverTriggerActionFlags.hover |
+                  PopoverTriggerActionFlags.click,
+              mutex: popOverMutex,
+              offset: const Offset(10, 0),
+              popupBuilder: (BuildContext context) {
+                return const PopoverMenu();
+              },
+              child: TextButton(
+                onPressed: () {},
+                child: const Text("Second"),
+              ),
+            ),
+          ]),
+        ));
   }
 }