@dwelle/excalidraw 0.4.0-532db6e → 0.4.0-5b8c704

package/CHANGELOG.md

@@ -13,6 +13,16 @@ Please add the latest change on the top under the correct section.
 
 ## Unreleased
 
+### 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
+
+- With this change, the prop `renderFooter` is now removed.
+
 ### Excalidraw schema
 
 - Merged `appState.currentItemStrokeSharpness` and `appState.currentItemLinearStrokeSharpness` into `appState.currentItemRoundness`. Renamed `changeSharpness` action to `changeRoundness`. Excalidraw element's `strokeSharpness` was changed to `roundness`. Check the PR for types and more details [#5553](https://github.com/excalidraw/excalidraw/pull/5553).

package/README.md

@@ -380,6 +380,156 @@ For a complete list of variables, check [theme.scss](https://github.com/excalidr
 
 No, Excalidraw package doesn't come with collaboration built in, since the implementation is specific to each host app. We expose APIs which you can use to communicate with Excalidraw which you can use to implement it. You can check our own implementation [here](https://github.com/excalidraw/excalidraw/blob/master/src/excalidraw-app/index.tsx).
 
+### Component API
+
+#### Footer
+
+Earlier we were using `renderFooter` prop to render custom footer which was removed in [#5970](https://github.com/excalidraw/excalidraw/pull/5970). Now you can pass a `Footer` component instead to render the custom UI for footer.
+
+You will need to import the `Footer` component from the package and wrap your component with the Footer component. The `Footer` should a valid React Node.
+
+**Usage**
+
+```js
+import { Footer } from "@excalidraw/excalidraw";
+
+const CustomFooter = () => <button> custom button</button>;
+const App = () => {
+  return (
+    <Excalidraw>
+      <Footer>
+        <CustomFooter />
+      </Footer>
+    </Excalidraw>
+  );
+};
+```
+
+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> Item1 </MainMenu.Item>
+      <MainMenu.Item> 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> Item1 </MainMenu.Item>
+      <MainMenu.Item> 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 | Default | Description |
+| --- | --- | --- | --- |
+| `icon` | `JSX.Element` | `undefined` | The icon used in the menu item |
+| `shortcut` | `string` | `undefined` | The shortcut to be shown for the menu item |
+| `children` | `React.ReactNode` | `undefined` | The content of the menu item |
+| `onClick` | `Function` | `undefined` | The click handler will be triggered when clicked on menu item. If passed the item is rendered as a button. |
+| `className` | `string` | "" | The class names to be added to the menu item |
+| `link` | `string` | `undefined` | If `link` is passed the item is rendered as an anchor element. |
+| `style` | `React.CSSProperties` | `undefined` | The inline styles to be added to the menu 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> Item1 </MainMenu.Item>
+      <MainMenu.Item> 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> Item1 </MainMenu.Item>
+        <MainMenu.Item> Item 2 </>
+      </MainMenu.Group>
+    </MainMenu>
+  </Excalidraw>
+}
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` | `undefined` | The `title` for the grouped items |
+| `className` | `string` | "" | The `classname` to be added to the group |
+| `style` | `React.CSsSProperties` | `undefined` | The inline `styles` to be added to the group |
+| `children ` | `React.ReactNode` | `undefined` | The content of the `Menu Group` |
+
 ### Props
 
 | Name | Type | Default | Description |
@@ -392,7 +542,6 @@ No, Excalidraw package doesn't come with collaboration built in, since the imple
 | [`onPointerUpdate`](#onPointerUpdate) | Function |  | Callback triggered when mouse pointer is updated. |
 | [`langCode`](#langCode) | string | `en` | Language code string |
 | [`renderTopRightUI`](#renderTopRightUI) | Function |  | Function that renders custom UI in top right corner |
-| [`renderFooter `](#renderFooter) | Function |  | Function that renders custom UI footer |
 | [`renderCustomStats`](#renderCustomStats) | Function |  | Function that can be used to render custom stats on the stats dialog. |
 | [`renderSIdebar`](#renderSIdebar) | Function |  | Render function that renders custom sidebar. |
 | [`viewModeEnabled`](#viewModeEnabled) | boolean |  | This implies if the app is in view mode. |
@@ -613,14 +762,6 @@ import { defaultLang, languages } from "@excalidraw/excalidraw";
 
 A function returning JSX to render custom UI in the top right corner of the app.
 
-#### `renderFooter`
-
-<pre>
-(isMobile: boolean, appState: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L79">AppState</a>) => JSX | null
-</pre>
-
-A function returning JSX to render custom UI footer. For example, you can use this to render a language picker that was previously being rendered by Excalidraw itself (for now, you'll need to implement your own language picker).
-
 #### `renderCustomStats`
 
 A function that can be used to render custom stats (returns JSX) in the nerd stats dialog. For example you can use this prop to render the size of the elements in the storage.
@@ -1353,6 +1494,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`