Virtual whiteboard for sketching hand-drawn like diagrams
docs: new Sidebar API (#6976)
David Luzara34216f9fcb0
diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/children-components/children-components-intro.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/children-components/children-components-intro.mdxindex 706adb594c..06bb1cbaf6 100644--- a/dev-docs/docs/@excalidraw/excalidraw/api/children-components/children-components-intro.mdx+++ b/dev-docs/docs/@excalidraw/excalidraw/api/children-components/children-components-intro.mdx@@ -17,5 +17,6 @@ Below are the currently supported components:- [MainMenu](/docs/@excalidraw/excalidraw/api/children-components/main-menu)- [WelcomeScreen](/docs/@excalidraw/excalidraw/api/children-components/welcome-screen)+- [Sidebar](/docs/@excalidraw/excalidraw/api/children-components/sidebar)- [Footer](/docs/@excalidraw/excalidraw/api/children-components/footer)- [LiveCollaborationTrigger](/docs/@excalidraw/excalidraw/api/children-components/live-collaboration-trigger)diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/children-components/sidebar.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/children-components/sidebar.mdxnew file mode 100644index 0000000000..08445a1c34--- /dev/null+++ b/dev-docs/docs/@excalidraw/excalidraw/api/children-components/sidebar.mdx@@ -0,0 +1,129 @@+# Sidebar++The editor comes with a default sidebar on the right in LTR (Left to Right) mode which contains the library. You can also add your own custom sidebar(s) by rendering this component as a child of `<Excalidraw>`.++## Props++| Prop | Type | Required | Description |+| --- | --- | --- | --- |+| `name` | `string` | Yes | Sidebar name that uniquely identifies it. |+| `children` | `React.ReactNode` | Yes | Content you want to render inside the sidebar. |+| `onStateChange` | `(state: AppState["openSidebar"]) => void` | No | Invoked on open/close or tab change. No need to act on this event, as the editor manages the sidebar open state on its own. |+| `onDock` | `(docked: boolean) => void` | No | Invoked when the user toggles the `dock` button. Passed the current docked state. |+| `docked` | `boolean` | No | Indicates whether the sidebar is `docked`. By default, the sidebar is `undocked`. If passed, the docking becomes controlled. |+| `className` | `string` | No | |+| `style` | `React.CSSProperties` | No | |++At minimum, each sidebar needs to have a unique `name` prop, and render some content inside it, which can be either composed from the exported sidebar sub-components, or custom elements.++Unless `docked={true}` is passed, the sidebar will close when the user clicks outside of it. It can also be closed using the close button in the header, if you render the `<Sidebar.Header>` component.++Further, if the sidebader doesn't comfortably fit in the editor, it won't be dockable. To decide the breakpoint for docking you can use [UIOptions.dockedSidebarBreakpoint](/docs/@excalidraw/excalidraw/api/props/ui-options#dockedsidebarbreakpoint).++To make your sidebar user-dockable, you need to supply `props.docked` (current docked state) alongside `props.onDock` callback (to listen for and handle docked state changes). The component doesn't track local state for the `docked` prop, so you need to manage it yourself.++## Sidebar.Header++| Prop | Type | Required | Description |+| --- | --- | --- | --- |+| `children` | `React.ReactNode` | No | Content you want to render inside the sidebar header next to the `close` / `dock` buttons. |+| `className` | `string` | No | |++Renders a sidebar header which contains a close button, and a dock button (when applicable). You can also render custom content in addition.++Can be nested inside specific tabs, or rendered as direct child of `<Sidebar>` for the whole sidebar component.++## Sidebar.Tabs++| Prop | Type | Required | Description |+| ---------- | ----------------- | -------- | ------------------------------ |+| `children` | `React.ReactNode` | No | Container for individual tabs. |++Sidebar may contain inner tabs. Each `<Sidebar.Tab>` must be rendered inside this `<Sidebar.Tabs>` container component.++## Sidebar.Tab++| Prop | Type | Required | Description |+| ---------- | ----------------- | -------- | ---------------- |+| `tab` | `string` | Yes | Unique tab name. |+| `children` | `React.ReactNode` | No | Tab content. |++Content of a given sidebar tab. It must be rendered inside `<Sidebar.Tabs>`.++## Sidebar.TabTriggers++| Prop | Type | Required | Description |+| --- | --- | --- | --- |+| `children` | `React.ReactNode` | No | Container for individual tab triggers. |++Container component for tab trigger buttons to switch between tabs.++## Sidebar.TabTrigger++| Prop | Type | Required | Description |+| --- | --- | --- | --- |+| `tab` | `string` | Yes | Tab name to toggle. |+| `children` | `React.ReactNode` | No | Tab trigger content, such as a label. |++A given tab trigger button that switches to a given sidebar tab. It must be rendered inside `<Sidebar.TabTriggers>`.++## Sidebar.Trigger++| Prop | Type | Required | Description |+| --- | --- | --- | --- |+| `name` | `string` | Yes | Sidebar name the trigger will control. |+| `tab` | `string` | No | Optional tab to open. |+| `onToggle` | `(open: boolean) => void` | No | Callback invoked on toggle. |+| `title` | `string` | No | A11y title. |+| `children` | `React.ReactNode` | No | Content (usually label) you want to render inside the button. |+| `icon` | `JSX.Element` | No | Trigger icon if any. |+| `className` | `string` | No | |+| `style` | `React.CSSProperties` | No | |++You can use the [`ref.toggleSidebar({ name: "custom" })`](/docs/@excalidraw/excalidraw/api/props/ref#toggleSidebar) api to control the sidebar, but we export a trigger button to make UI use cases easier.++## Example++```tsx live+function App() {+ const [docked, setDocked] = useState(false);++ return (+ <div style={{ height: "580px" }}>+ <Excalidraw+ UIOptions={{+ // this effectively makes the sidebar dockable on any screen size,+ // ignoring if it fits or not+ dockedSidebarBreakpoint: 0,+ }}+ >+ <Sidebar name="custom" docked={docked} onDock={setDocked}>+ <Sidebar.Header />+ <Sidebar.Tabs style={{ padding: "0.5rem" }}>+ <Sidebar.Tab tab="one">Tab one!</Sidebar.Tab>+ <Sidebar.Tab tab="two">Tab two!</Sidebar.Tab>+ <Sidebar.TabTriggers>+ <Sidebar.TabTrigger tab="one">One</Sidebar.TabTrigger>+ <Sidebar.TabTrigger tab="two">Two</Sidebar.TabTrigger>+ </Sidebar.TabTriggers>+ </Sidebar.Tabs>+ </Sidebar>++ <Footer>+ <Sidebar.Trigger+ name="custom"+ tab="one"+ style={{+ marginLeft: "0.5rem",+ background: "#70b1ec",+ color: "white",+ }}+ >+ Toggle Custom Sidebar+ </Sidebar.Trigger>+ </Footer>+ </Excalidraw>+ </div>+ );+}+```diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/props/props.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/props/props.mdxindex 104d9dccd4..5764528b61 100644--- a/dev-docs/docs/@excalidraw/excalidraw/api/props/props.mdx+++ b/dev-docs/docs/@excalidraw/excalidraw/api/props/props.mdx@@ -17,7 +17,6 @@ All `props` are *optional*.| [`langCode`](#langcode) | `string` | `en` | Language code string to be used in Excalidraw || [`renderTopRightUI`](/docs/@excalidraw/excalidraw/api/props/render-props#rendertoprightui) | `function` | _ | Render function that renders custom UI in top right corner || [`renderCustomStats`](/docs/@excalidraw/excalidraw/api/props/render-props#rendercustomstats) | `function` | _ | Render function that can be used to render custom stats on the stats dialog. |-| [`renderSidebar`](/docs/@excalidraw/excalidraw/api/props/render-props#rendersidebar) | `function` | _ | Render function that renders custom sidebar. || [`viewModeEnabled`](#viewmodeenabled) | `boolean` | _ | This indicates if the app is in `view` mode. || [`zenModeEnabled`](#zenmodeenabled) | `boolean` | _ | This indicates if the `zen` mode is enabled || [`gridModeEnabled`](#gridmodeenabled) | `boolean` | _ | This indicates if the `grid` mode is enabled |diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/props/ref.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/props/ref.mdxindex eaf58f758e..6edcc9b9e9 100644--- a/dev-docs/docs/@excalidraw/excalidraw/api/props/ref.mdx+++ b/dev-docs/docs/@excalidraw/excalidraw/api/props/ref.mdx@@ -404,15 +404,15 @@ This API can be used to customise the mouse cursor on the canvas and has the bel(cursor: string) => void```-## toggleMenu+## toggleSidebar```tsx-(type: "library" | "customSidebar", force?: boolean) => boolean;+(opts: { name: string; tab?: string; force?: boolean }) => boolean;```-This API can be used to toggle a specific menu (currently only the sidebars), and returns whether the menu was toggled on or off. If the `force` flag passed, it will force the menu to be toggled either on/off based on the `boolean` passed.+This API can be used to toggle sidebar, optionally opening a specific sidebar tab. It returns whether the sidebar was toggled on or off. If the `force` flag passed, it will force the sidebar to be toggled either on/off.-This API is especially useful when you render a custom sidebar using [`renderSidebar`](#rendersidebar) prop, and you want to toggle it from your app based on a user action.+This API is especially useful when you render a custom [`<Sidebar/>`](/docs/@excalidraw/excalidraw/api/children-components/sidebar), and you want to toggle it from your app based on a user action.## resetCursordiff --git a/dev-docs/docs/@excalidraw/excalidraw/api/props/render-props.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/props/render-props.mdxindex 5256704c20..f0f4adc449 100644--- a/dev-docs/docs/@excalidraw/excalidraw/api/props/render-props.mdx+++ b/dev-docs/docs/@excalidraw/excalidraw/api/props/render-props.mdx@@ -6,8 +6,7 @@(isMobile: boolean, appState:<a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L95">AppState- </a>- ) => JSX | null+ </a>) => JSX | null</pre>A function returning `JSX` to render `custom` UI in the top right corner of the app.@@ -63,69 +62,14 @@ function App() {}```-## renderSidebar--```tsx-() => JSX | null;-```--You can render `custom sidebar` using this prop. This sidebar is the same that the library menu sidebar is using, and can be used for any purposes your app needs.--You need to import the `Sidebar` component from `excalidraw` package and pass your content as its `children`. The function `renderSidebar` should return the `Sidebar` instance.--### Sidebar-The `<Sidebar>` component takes these props (all are optional except `children`):--| Prop | Type | Description |-| --- | --- | --- |-| `children` | `React.ReactNode` | Content you want to render inside the `sidebar`. |-| `onClose` | `function` | Invoked when the component is closed (by user, or the editor). No need to act on this event, as the editor manages the sidebar open state on its own. |-| `onDock` | `function` | Invoked when the user toggles the `dock` button. The callback receives a `boolean` parameter `isDocked` which indicates whether the sidebar is `docked` |-| `docked` | `boolean` | Indicates whether the sidebar is`docked`. By default, the sidebar is `undocked`. If passed, the docking becomes controlled, and you are responsible for updating the `docked` state by listening on `onDock` callback. To decide the breakpoint for docking you can use [UIOptions.dockedSidebarBreakpoint](/docs/@excalidraw/excalidraw/api/props/ui-options#dockedsidebarbreakpoint) for more info on docking. |-| `dockable` | `boolean` | Indicates whether to show the `dock` button so that user can `dock` the sidebar. If `false`, you can still dock programmatically by passing `docked` as `true`. |--The sidebar will always include a header with `close / dock` buttons (when applicable).-You can also add custom content to the header, by rendering `<Sidebar.Header>` as a child of the `<Sidebar>` component. Note that the custom header will still include the default buttons.---### Sidebar.Header--| name | type | description |-| --- | --- | --- |-| children | `React.ReactNode` | Content you want to render inside the sidebar header as a sibling of `close` / `dock` buttons. |--To control the visibility of the sidebar you can use [`toggleMenu("customSidebar")`](/docs/@excalidraw/excalidraw/api/props/ref#togglemenu) api available via `ref`.--```tsx live-function App() {- const [excalidrawAPI, setExcalidrawAPI] = useState(null);-- return (- <div style={{ height: "500px" }}>- <button className="custom-button" onClick={() => excalidrawAPI.toggleMenu("customSidebar")}>- Toggle Custom Sidebar- </button>- <Excalidraw- UIOptions={{ dockedSidebarBreakpoint: 100 }}- ref={(api) => setExcalidrawAPI(api)}- renderSidebar={() => {- return (- <Sidebar dockable={true}>- <Sidebar.Header>Custom Sidebar Header </Sidebar.Header>- <p style={{ padding: "1rem" }}> custom Sidebar Content </p>- </Sidebar>- );- }}- />- </div>- );-}-```-## renderEmbeddable<pre>- (element: NonDeleted<ExcalidrawEmbeddableElement>, appState: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L95">AppState</a>) => JSX.Element | null+ (element: NonDeleted<ExcalidrawEmbeddableElement>, appState:{" "}+ <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L95">+ AppState+ </a>+ ) => JSX.Element | null</pre>Allows you to replace the renderer for embeddable elements (which renders `<iframe>` elements).diff --git a/dev-docs/package.json b/dev-docs/package.jsonindex cbf0d4334f..bef57d76e7 100644--- a/dev-docs/package.json+++ b/dev-docs/package.json@@ -18,7 +18,7 @@"@docusaurus/core": "2.2.0","@docusaurus/preset-classic": "2.2.0","@docusaurus/theme-live-codeblock": "2.2.0",- "@excalidraw/excalidraw": "0.15.3",+ "@excalidraw/excalidraw": "0.15.2-6546-3398d86","@mdx-js/react": "^1.6.22","clsx": "^1.2.1","docusaurus-plugin-sass": "0.2.3",diff --git a/dev-docs/sidebars.js b/dev-docs/sidebars.jsindex 4ff33746b7..86356aeff5 100644--- a/dev-docs/sidebars.js+++ b/dev-docs/sidebars.js@@ -64,6 +64,7 @@ const sidebars = {items: ["@excalidraw/excalidraw/api/children-components/main-menu","@excalidraw/excalidraw/api/children-components/welcome-screen",+ "@excalidraw/excalidraw/api/children-components/sidebar","@excalidraw/excalidraw/api/children-components/footer","@excalidraw/excalidraw/api/children-components/live-collaboration-trigger",],diff --git a/dev-docs/yarn.lock b/dev-docs/yarn.lockindex a2b61d255f..3ef8a91904 100644--- a/dev-docs/yarn.lock+++ b/dev-docs/yarn.lock@@ -1631,10 +1631,10 @@url-loader "^4.1.1"webpack "^5.73.0"-"@excalidraw/[email protected]":- version "0.15.3"- resolved "https://registry.yarnpkg.com/@excalidraw/excalidraw/-/excalidraw-0.15.3.tgz#5dea570f76451adf68bc24d4bfdd67a375cfeab1"- integrity sha512-/gpY7fgMO/AEaFLWnPqzbY8H7ly+/zocFf7D0Is5sWNMD2mhult5tana12lXKLSJ6EAz7ubo1A7LajXzvJXJDA==+"@excalidraw/[email protected]":+ version "0.15.2-6546-3398d86"+ resolved "https://registry.yarnpkg.com/@excalidraw/excalidraw/-/excalidraw-0.15.2-6546-3398d86.tgz#e74d5ad944b8b414924d27ee91469a32b4f08dbf"+ integrity sha512-Tzq6qighJUytXRA8iMzQ8onoGclo9CuvPSw7DMvPxME8nxAxn5CeK/gsxIs3zwooj9CC6XF42BSrx0+n+fPxaQ=="@hapi/hoek@^9.0.0":version "9.3.0"