@dwelle/excalidraw 0.4.0-904c06a → 0.4.0-952b0c1

package/CHANGELOG.md

@@ -15,6 +15,8 @@ Please add the latest change on the top under the correct section.
 
 ### Features
 
+- Expose component API for the Excalidraw main menu [#6034](https://github.com/excalidraw/excalidraw/pull/6034), You can read more about its usage [here](https://github.com/excalidraw/excalidraw/blob/master/src/packages/excalidraw/README.md#MainMenu)
+
 - Render Footer as a component instead of render prop [#5970](https://github.com/excalidraw/excalidraw/pull/5970). You can read more about its usage [here](https://github.com/excalidraw/excalidraw/blob/master/src/packages/excalidraw/README.md#Footer)
 
 #### BREAKING CHANGE

package/README.md

@@ -405,6 +405,195 @@ const App = () => {
 };
 ```
 
+This will only for `Desktop` devices.
+
+For `mobile` you will need to render it inside the [MainMenu](#mainmenu). You can use the [`useDevice`](#useDevice) hook to check the type of device, this will be available only inside the `children` of `Excalidraw` component.
+
+```js
+import { useDevice, Footer } from "@excalidraw/excalidraw";
+
+const MobileFooter = ({
+}) => {
+  const device = useDevice();
+  if (device.isMobile) {
+    return (
+      <Footer>
+       <button
+        className="custom-footer"
+        onClick={() => alert("This is custom footer in mobile menu")}
+      >
+        {" "}
+        custom footer{" "}
+      </button>
+      </Footer>
+    );
+  }
+  return null;
+
+};
+const App = () => {
+  <Excalidraw>
+    <MainMenu>
+      <MainMenu.Item onSelect={() => window.alert("Item1")}> Item1 </MainMenu.Item>
+      <MainMenu.Item onSelect={() => window.alert("Item2")}> Item 2 </>
+      <MobileFooter/>
+    </MainMenu>
+  </Excalidraw>
+}
+
+```
+
+You can visit the[ example](https://ehlz3.csb.app/) for working demo.
+
+#### MainMenu
+
+By default Excalidraw will render the `MainMenu` with default options. If you want to customise the `MainMenu`, you can pass the `MainMenu` component with the list options. You can visit [codesandbox example](https://ehlz3.csb.app/) for a working demo.
+
+**Usage**
+
+```js
+import { MainMenu } from "@excalidraw/excalidraw";
+const App = () => {
+  <Excalidraw>
+    <MainMenu>
+      <MainMenu.Item onSelect={() => window.alert("Item1")}> Item1 </MainMenu.Item>
+      <MainMenu.Item onSelect={() => window.alert("Item2")}> Item 2 </>
+    </MainMenu>
+  </Excalidraw>
+}
+```
+
+**MainMenu**
+
+This is the `MainMenu` component which you need to import to render the menu with custom options.
+
+**MainMenu.Item**
+
+To render an item, its recommended to use `MainMenu.Item`.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `onSelect` | `Function` | Yes | `undefined` | The handler is triggered when the item is selected. |
+| `children` | `React.ReactNode` | Yes | `undefined` | The content of the menu item |
+| `icon` | `JSX.Element` | No | `undefined` | The icon used in the menu item |
+| `shortcut` | `string` | No | `undefined` | The shortcut to be shown for the menu item |
+| `className` | `string` | No | "" | The class names to be added to the menu item |
+| `style` | `React.CSSProperties` | No | `undefined` | The inline styles to be added to the menu item |
+| `ariaLabel` | `string` | `undefined` | No | The `aria-label` to be added to the item for accessibility |
+| `dataTestId` | `string` | `undefined` | No | The `data-testid` to be added to the item. |
+
+**MainMenu.ItemLink**
+
+To render an item as a link, its recommended to use `MainMenu.ItemLink`.
+
+**Usage**
+
+```js
+import { MainMenu } from "@excalidraw/excalidraw";
+const App = () => {
+  <Excalidraw>
+    <MainMenu>
+      <MainMenu.ItemLink href="https://google.com">Google</MainMenu.ItemLink>
+      <MainMenu.ItemLink href="https://excalidraw.com">
+        Excalidraw
+      </MainMenu.ItemLink>
+    </MainMenu>
+  </Excalidraw>;
+};
+```
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `href` | `string` | Yes | `undefined` | The `href` attribute to be added to the `anchor` element. |
+| `children` | `React.ReactNode` | Yes | `undefined` | The content of the menu item |
+| `icon` | `JSX.Element` | No | `undefined` | The icon used in the menu item |
+| `shortcut` | `string` | No | `undefined` | The shortcut to be shown for the menu item |
+| `className` | `string` | No | "" | The class names to be added to the menu item |
+| `style` | `React.CSSProperties` | No | `undefined` | The inline styles to be added to the menu item |
+| `ariaLabel` | `string` | No | `undefined` | The `aria-label` to be added to the item for accessibility |
+| `dataTestId` | `string` | No | `undefined` | The `data-testid` to be added to the item. |
+
+**MainMenu.ItemCustom**
+
+To render a custom item, you can use `MainMenu.ItemCustom`.
+
+**Usage**
+
+```js
+import { MainMenu } from "@excalidraw/excalidraw";
+const App = () => {
+  <Excalidraw>
+    <MainMenu>
+      <MainMenu.ItemCustom>
+        <button
+          style={{ height: "2rem" }}
+          onClick={() => window.alert("custom menu item")}
+        >
+          {" "}
+          custom item
+        </button>
+      </MainMenu.ItemCustom>
+    </MainMenu>
+  </Excalidraw>;
+};
+```
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `children` | `React.ReactNode` | Yes | `undefined` | The content of the menu item |
+| `className` | `string` | No | "" | The class names to be added to the menu item |
+| `style` | `React.CSSProperties` | No | `undefined` | The inline styles to be added to the menu item |
+| `dataTestId` | `string` | No | `undefined` | The `data-testid` to be added to the item. |
+
+**MainMenu.DefaultItems**
+
+For the items which are shown in the menu in [excalidraw.com](https://excalidraw.com), you can use `MainMenu.DefaultItems`
+
+```js
+import { MainMenu } from "@excalidraw/excalidraw";
+const App = () => {
+  <Excalidraw>
+    <MainMenu>
+      <MainMenu.DefaultItems.Socials/>
+      <MainMenu.DefaultItems.Export/>
+      <MainMenu.Item onSelect={() => window.alert("Item1")}> Item1 </MainMenu.Item>
+      <MainMenu.Item onSelect={() => window.alert("Item2")}> Item 2 </>
+    </MainMenu>
+  </Excalidraw>
+}
+```
+
+Here is a [complete list](https://github.com/excalidraw/excalidraw/blob/master/src/components/mainMenu/DefaultItems.tsx) of the default items.
+
+**MainMenu.Group**
+
+To Group item in the main menu, you can use `MainMenu.Group`
+
+```js
+import { MainMenu } from "@excalidraw/excalidraw";
+const App = () => {
+  <Excalidraw>
+    <MainMenu>
+      <MainMenu.Group title="Excalidraw items">
+        <MainMenu.DefaultItems.Socials/>
+        <MainMenu.DefaultItems.Export/>
+      </MainMenu.Group>
+      <MainMenu.Group title="custom items">
+        <MainMenu.Item onSelect={() => window.alert("Item1")}> Item1 </MainMenu.Item>
+        <MainMenu.Item onSelect={() => window.alert("Item2")}> Item 2 </>
+      </MainMenu.Group>
+    </MainMenu>
+  </Excalidraw>
+}
+```
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `children ` | `React.ReactNode` | Yes | `undefined` | The content of the `Menu Group` |
+| `title` | `string` | No | `undefined` | The `title` for the grouped items |
+| `className` | `string` | No | "" | The `classname` to be added to the group |
+| `style` | `React.CSsSProperties` | No | `undefined` | The inline `styles` to be added to the group |
+
 ### Props
 
 | Name | Type | Default | Description |
@@ -1369,6 +1558,53 @@ viewportCoordsToSceneCoords({clientX: number, clientY: number}, appState: <a hre
 
 This function returns equivalent scene coords for the provided viewport coords in params.
 
+#### useDevice
+
+This hook can be used to check the type of device which is being used. It can only be used inside the `children` of `Excalidraw` component
+
+```js
+import { useDevice, Footer } from "@excalidraw/excalidraw";
+
+const MobileFooter = ({
+}) => {
+  const device = useDevice();
+  if (device.isMobile) {
+    return (
+      <Footer>
+       <button
+        className="custom-footer"
+        onClick={() => alert("This is custom footer in mobile menu")}
+      >
+        {" "}
+        custom footer{" "}
+      </button>
+      </Footer>
+    );
+  }
+  return null;
+
+};
+const App = () => {
+  <Excalidraw>
+    <MainMenu>
+      <MainMenu.Item> Item1 </MainMenu.Item>
+      <MainMenu.Item> Item 2 </>
+      <MobileFooter/>
+    </MainMenu>
+  </Excalidraw>
+}
+
+```
+
+The `device` has the following `attributes`
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `isSmScreen` | `boolean` | Set to `true` when the device small screen is small (Width < `640px` ) |
+| `isMobile` | `boolean` | Set to `true` when the device is `mobile` |
+| `isTouchScreen` | `boolean` | Set to `true` for `touch` devices |
+| `canDeviceFitSidebar` | `boolean` | Implies whether there is enough space to fit the `sidebar` |
+
 ### Exported constants
 
 #### `FONT_FAMILY`