sambruk/excalidraw
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: support WelcomeScreen customization API (#6048)

Browse Source
This commit is contained in:
David Luzar 2023-01-12 15:49:28 +01:00 committed by GitHub
parent 0982da38fe
commit 599a8f3c6f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
20 changed files with 715 additions and 379 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
src/components/App.tsx
View File

@ -283,15 +283,12 @@ const deviceContextInitialValue = {
}; };
const DeviceContext = React.createContext<Device>(deviceContextInitialValue); const DeviceContext = React.createContext<Device>(deviceContextInitialValue);
DeviceContext.displayName = "DeviceContext"; DeviceContext.displayName = "DeviceContext";
export const useDevice = () => useContext<Device>(DeviceContext);
export const ExcalidrawContainerContext = React.createContext<{ export const ExcalidrawContainerContext = React.createContext<{
container: HTMLDivElement | null; container: HTMLDivElement | null;
id: string | null; id: string | null;
}>({ container: null, id: null }); }>({ container: null, id: null });
ExcalidrawContainerContext.displayName = "ExcalidrawContainerContext"; ExcalidrawContainerContext.displayName = "ExcalidrawContainerContext";
export const useExcalidrawContainer = () =>
useContext(ExcalidrawContainerContext);
const ExcalidrawElementsContext = React.createContext< const ExcalidrawElementsContext = React.createContext<
readonly NonDeletedExcalidrawElement[] readonly NonDeletedExcalidrawElement[]
@ -309,7 +306,9 @@ ExcalidrawAppStateContext.displayName = "ExcalidrawAppStateContext";
const ExcalidrawSetAppStateContext = React.createContext< const ExcalidrawSetAppStateContext = React.createContext<
React.Component<any, AppState>["setState"] React.Component<any, AppState>["setState"]
>(() => {}); >(() => {
console.warn("unitialized ExcalidrawSetAppStateContext context!");
});
ExcalidrawSetAppStateContext.displayName = "ExcalidrawSetAppStateContext"; ExcalidrawSetAppStateContext.displayName = "ExcalidrawSetAppStateContext";
const ExcalidrawActionManagerContext = React.createContext<ActionManager>( const ExcalidrawActionManagerContext = React.createContext<ActionManager>(
@ -317,6 +316,9 @@ const ExcalidrawActionManagerContext = React.createContext<ActionManager>(
); );
ExcalidrawActionManagerContext.displayName = "ExcalidrawActionManagerContext"; ExcalidrawActionManagerContext.displayName = "ExcalidrawActionManagerContext";
export const useDevice = () => useContext<Device>(DeviceContext);
export const useExcalidrawContainer = () =>
useContext(ExcalidrawContainerContext);
export const useExcalidrawElements = () => export const useExcalidrawElements = () =>
useContext(ExcalidrawElementsContext); useContext(ExcalidrawElementsContext);
export const useExcalidrawAppState = () => export const useExcalidrawAppState = () =>
@ -598,6 +600,8 @@ class App extends React.Component<AppProps, AppState> {
id={this.id} id={this.id}
onImageAction={this.onImageAction} onImageAction={this.onImageAction}
renderWelcomeScreen={ renderWelcomeScreen={
!this.state.isLoading &&
this.props.UIOptions.welcomeScreen &&
this.state.showWelcomeScreen && this.state.showWelcomeScreen &&
this.state.activeTool.type === "selection" && this.state.activeTool.type === "selection" &&
!this.scene.getElementsIncludingDeleted().length !this.scene.getElementsIncludingDeleted().length

57
src/components/LayerUI.tsx
View File

@ -14,6 +14,7 @@ import {
ExcalidrawProps, ExcalidrawProps,
BinaryFiles, BinaryFiles,
UIChildrenComponents, UIChildrenComponents,
UIWelcomeScreenComponents,
} from "../types"; } from "../types";
import { isShallowEqual, muteFSAbortError, getReactChildren } from "../utils"; import { isShallowEqual, muteFSAbortError, getReactChildren } from "../utils";
import { SelectedShapeActions, ShapesSwitcher } from "./Actions"; import { SelectedShapeActions, ShapesSwitcher } from "./Actions";
@ -45,12 +46,10 @@ import { useDevice } from "../components/App";
import { Stats } from "./Stats"; import { Stats } from "./Stats";
import { actionToggleStats } from "../actions/actionToggleStats"; import { actionToggleStats } from "../actions/actionToggleStats";
import Footer from "./footer/Footer"; import Footer from "./footer/Footer";
import { WelcomeScreenMenuArrow, WelcomeScreenTopToolbarArrow } from "./icons"; import WelcomeScreen from "./welcome-screen/WelcomeScreen";
import WelcomeScreen from "./WelcomeScreen";
import { hostSidebarCountersAtom } from "./Sidebar/Sidebar"; import { hostSidebarCountersAtom } from "./Sidebar/Sidebar";
import { jotaiScope } from "../jotai"; import { jotaiScope } from "../jotai";
import { useAtom } from "jotai"; import { useAtom } from "jotai";
import WelcomeScreenDecor from "./WelcomeScreenDecor";
import MainMenu from "./mainMenu/MainMenu"; import MainMenu from "./mainMenu/MainMenu";
interface LayerUIProps { interface LayerUIProps {
@ -111,8 +110,24 @@ const LayerUI = ({
getReactChildren<UIChildrenComponents>(children, { getReactChildren<UIChildrenComponents>(children, {
Menu: true, Menu: true,
FooterCenter: true, FooterCenter: true,
WelcomeScreen: true,
}); });
const [WelcomeScreenComponents] = getReactChildren<UIWelcomeScreenComponents>(
renderWelcomeScreen
? (
childrenComponents?.WelcomeScreen ?? (
<WelcomeScreen>
<WelcomeScreen.Center />
<WelcomeScreen.Hints.MenuHint />
<WelcomeScreen.Hints.ToolbarHint />
<WelcomeScreen.Hints.HelpHint />
</WelcomeScreen>
)
)?.props?.children
: null,
);
const renderJSONExportDialog = () => { const renderJSONExportDialog = () => {
if (!UIOptions.canvasActions.export) { if (!UIOptions.canvasActions.export) {
return null; return null;
@ -213,15 +228,10 @@ const LayerUI = ({
}; };
const renderCanvasActions = () => ( const renderCanvasActions = () => (
<div style={{ position: "relative" }}> <div style={{ position: "relative" }}>
<WelcomeScreenDecor {WelcomeScreenComponents.MenuHint}
shouldRender={renderWelcomeScreen && !appState.isLoading} {/* wrapping to Fragment stops React from occasionally complaining
> about identical Keys */}
<div className="virgil WelcomeScreen-decor WelcomeScreen-decor--menu-pointer"> <>{renderMenu()}</>
{WelcomeScreenMenuArrow}
<div>{t("welcomeScreen.menuHints")}</div>
</div>
</WelcomeScreenDecor>
{renderMenu()}
</div> </div>
); );
@ -258,9 +268,7 @@ const LayerUI = ({
return ( return (
<FixedSideContainer side="top"> <FixedSideContainer side="top">
{renderWelcomeScreen && !appState.isLoading && ( {WelcomeScreenComponents.Center}
<WelcomeScreen appState={appState} actionManager={actionManager} />
)}
<div className="App-menu App-menu_top"> <div className="App-menu App-menu_top">
<Stack.Col <Stack.Col
gap={6} gap={6}
@ -275,17 +283,7 @@ const LayerUI = ({
<Section heading="shapes" className="shapes-section"> <Section heading="shapes" className="shapes-section">
{(heading: React.ReactNode) => ( {(heading: React.ReactNode) => (
<div style={{ position: "relative" }}> <div style={{ position: "relative" }}>
<WelcomeScreenDecor {WelcomeScreenComponents.ToolbarHint}
shouldRender={renderWelcomeScreen && !appState.isLoading}
>
<div className="virgil WelcomeScreen-decor WelcomeScreen-decor--top-toolbar-pointer">
<div className="WelcomeScreen-decor--top-toolbar-pointer__label">
{t("welcomeScreen.toolbarHints")}
</div>
{WelcomeScreenTopToolbarArrow}
</div>
</WelcomeScreenDecor>
<Stack.Col gap={4} align="start"> <Stack.Col gap={4} align="start">
<Stack.Row <Stack.Row
gap={1} gap={1}
@ -420,24 +418,22 @@ const LayerUI = ({
)} )}
{device.isMobile && ( {device.isMobile && (
<MobileMenu <MobileMenu
renderWelcomeScreen={renderWelcomeScreen}
appState={appState} appState={appState}
elements={elements} elements={elements}
actionManager={actionManager} actionManager={actionManager}
renderJSONExportDialog={renderJSONExportDialog} renderJSONExportDialog={renderJSONExportDialog}
renderImageExportDialog={renderImageExportDialog} renderImageExportDialog={renderImageExportDialog}
setAppState={setAppState} setAppState={setAppState}
onCollabButtonClick={onCollabButtonClick}
onLockToggle={() => onLockToggle()} onLockToggle={() => onLockToggle()}
onPenModeToggle={onPenModeToggle} onPenModeToggle={onPenModeToggle}
canvas={canvas} canvas={canvas}
isCollaborating={isCollaborating}
onImageAction={onImageAction} onImageAction={onImageAction}
renderTopRightUI={renderTopRightUI} renderTopRightUI={renderTopRightUI}
renderCustomStats={renderCustomStats} renderCustomStats={renderCustomStats}
renderSidebars={renderSidebars} renderSidebars={renderSidebars}
device={device} device={device}
renderMenu={renderMenu} renderMenu={renderMenu}
welcomeScreenCenter={WelcomeScreenComponents.Center}
/> />
)} )}
@ -462,13 +458,12 @@ const LayerUI = ({
> >
{renderFixedSideContainer()} {renderFixedSideContainer()}
<Footer <Footer
renderWelcomeScreen={renderWelcomeScreen}
appState={appState} appState={appState}
actionManager={actionManager} actionManager={actionManager}
showExitZenModeBtn={showExitZenModeBtn} showExitZenModeBtn={showExitZenModeBtn}
footerCenter={childrenComponents.FooterCenter} footerCenter={childrenComponents.FooterCenter}
welcomeScreenHelp={WelcomeScreenComponents.HelpHint}
/> />
{appState.showStats && ( {appState.showStats && (
<Stats <Stats
appState={appState} appState={appState}

34
src/components/MobileMenu.tsx
View File

@ -1,5 +1,10 @@
import React from "react"; import React from "react";
import { AppState, Device, ExcalidrawProps } from "../types"; import {
AppState,
Device,
ExcalidrawProps,
UIWelcomeScreenComponents,
} from "../types";
import { ActionManager } from "../actions/manager"; import { ActionManager } from "../actions/manager";
import { t } from "../i18n"; import { t } from "../i18n";
import Stack from "./Stack"; import Stack from "./Stack";
@ -17,7 +22,6 @@ import { LibraryButton } from "./LibraryButton";
import { PenModeButton } from "./PenModeButton"; import { PenModeButton } from "./PenModeButton";
import { Stats } from "./Stats"; import { Stats } from "./Stats";
import { actionToggleStats } from "../actions"; import { actionToggleStats } from "../actions";
import WelcomeScreen from "./WelcomeScreen";
type MobileMenuProps = { type MobileMenuProps = {
appState: AppState; appState: AppState;
@ -26,11 +30,9 @@ type MobileMenuProps = {
renderImageExportDialog: () => React.ReactNode; renderImageExportDialog: () => React.ReactNode;
setAppState: React.Component<any, AppState>["setState"]; setAppState: React.Component<any, AppState>["setState"];
elements: readonly NonDeletedExcalidrawElement[]; elements: readonly NonDeletedExcalidrawElement[];
onCollabButtonClick?: () => void;
onLockToggle: () => void; onLockToggle: () => void;
onPenModeToggle: () => void; onPenModeToggle: () => void;
canvas: HTMLCanvasElement | null; canvas: HTMLCanvasElement | null;
isCollaborating: boolean;
onImageAction: (data: { insertOnCanvasDirectly: boolean }) => void; onImageAction: (data: { insertOnCanvasDirectly: boolean }) => void;
renderTopRightUI?: ( renderTopRightUI?: (
@ -40,8 +42,8 @@ type MobileMenuProps = {
renderCustomStats?: ExcalidrawProps["renderCustomStats"]; renderCustomStats?: ExcalidrawProps["renderCustomStats"];
renderSidebars: () => JSX.Element | null; renderSidebars: () => JSX.Element | null;
device: Device; device: Device;
renderWelcomeScreen?: boolean;
renderMenu: () => React.ReactNode; renderMenu: () => React.ReactNode;
welcomeScreenCenter: UIWelcomeScreenComponents["Center"];
}; };
export const MobileMenu = ({ export const MobileMenu = ({
@ -52,21 +54,18 @@ export const MobileMenu = ({
onLockToggle, onLockToggle,
onPenModeToggle, onPenModeToggle,
canvas, canvas,
isCollaborating,
onImageAction, onImageAction,
renderTopRightUI, renderTopRightUI,
renderCustomStats, renderCustomStats,
renderSidebars, renderSidebars,
device, device,
renderWelcomeScreen,
renderMenu, renderMenu,
welcomeScreenCenter,
}: MobileMenuProps) => { }: MobileMenuProps) => {
const renderToolbar = () => { const renderToolbar = () => {
return ( return (
<FixedSideContainer side="top" className="App-top-bar"> <FixedSideContainer side="top" className="App-top-bar">
{renderWelcomeScreen && !appState.isLoading && ( {welcomeScreenCenter}
<WelcomeScreen appState={appState} actionManager={actionManager} />
)}
<Section heading="shapes"> <Section heading="shapes">
{(heading: React.ReactNode) => ( {(heading: React.ReactNode) => (
<Stack.Col gap={4} align="center"> <Stack.Col gap={4} align="center">
@ -74,20 +73,6 @@ export const MobileMenu = ({
<Island padding={1} className="App-toolbar App-toolbar--mobile"> <Island padding={1} className="App-toolbar App-toolbar--mobile">
{heading} {heading}
<Stack.Row gap={1}> <Stack.Row gap={1}>
{/* <PenModeButton
checked={appState.penMode}
onChange={onPenModeToggle}
title={t("toolBar.penMode")}
isMobile
penDetected={appState.penDetected}
/>
<LockButton
checked={appState.activeTool.locked}
onChange={onLockToggle}
title={t("toolBar.lock")}
isMobile
/>
<div className="App-toolbar__divider"></div> */}
<ShapesSwitcher <ShapesSwitcher
appState={appState} appState={appState}
canvas={canvas} canvas={canvas}
@ -109,7 +94,6 @@ export const MobileMenu = ({
title={t("toolBar.penMode")} title={t("toolBar.penMode")}
isMobile isMobile
penDetected={appState.penDetected} penDetected={appState.penDetected}
// penDetected={true}
/> />
<LockButton <LockButton
checked={appState.activeTool.locked} checked={appState.activeTool.locked}

121
src/components/WelcomeScreen.tsx
View File

@ -1,121 +0,0 @@
import { actionLoadScene, actionShortcuts } from "../actions";
import { ActionManager } from "../actions/manager";
import { getShortcutFromShortcutName } from "../actions/shortcuts";
import { isExcalidrawPlusSignedUser } from "../constants";
import { t } from "../i18n";
import { AppState } from "../types";
import { ExcalLogo, HelpIcon, LoadIcon, PlusPromoIcon } from "./icons";
import "./WelcomeScreen.scss";
const WelcomeScreenItem = ({
label,
shortcut,
onClick,
icon,
link,
}: {
label: string;
shortcut: string | null;
onClick?: () => void;
icon: JSX.Element;
link?: string;
}) => {
if (link) {
return (
<a
className="WelcomeScreen-item"
href={link}
target="_blank"
rel="noreferrer"
>
<div className="WelcomeScreen-item__label">
{icon}
{label}
</div>
</a>
);
}
return (
<button className="WelcomeScreen-item" type="button" onClick={onClick}>
<div className="WelcomeScreen-item__label">
{icon}
{label}
</div>
{shortcut && (
<div className="WelcomeScreen-item__shortcut">{shortcut}</div>
)}
</button>
);
};
const WelcomeScreen = ({
appState,
actionManager,
}: {
appState: AppState;
actionManager: ActionManager;
}) => {
let subheadingJSX;
if (isExcalidrawPlusSignedUser) {
subheadingJSX = t("welcomeScreen.switchToPlusApp")
.split(/(Excalidraw\+)/)
.map((bit, idx) => {
if (bit === "Excalidraw+") {
return (
<a
style={{ pointerEvents: "all" }}
href={`${process.env.REACT_APP_PLUS_APP}?utm_source=excalidraw&utm_medium=app&utm_content=welcomeScreenSignedInUser`}
key={idx}
>
Excalidraw+
</a>
);
}
return bit;
});
} else {
subheadingJSX = t("welcomeScreen.data");
}
return (
<div className="WelcomeScreen-container">
<div className="WelcomeScreen-logo virgil WelcomeScreen-decor">
{ExcalLogo} Excalidraw
</div>
<div className="virgil WelcomeScreen-decor WelcomeScreen-decor--subheading">
{subheadingJSX}
</div>
<div className="WelcomeScreen-items">
{!appState.viewModeEnabled && (
<WelcomeScreenItem
// TODO barnabasmolnar/editor-redesign
// do we want the internationalized labels here that are currently
// in use elsewhere or new ones?
label={t("buttons.load")}
onClick={() => actionManager.executeAction(actionLoadScene)}
shortcut={getShortcutFromShortcutName("loadScene")}
icon={LoadIcon}
/>
)}
<WelcomeScreenItem
onClick={() => actionManager.executeAction(actionShortcuts)}
label={t("helpDialog.title")}
shortcut="?"
icon={HelpIcon}
/>
{!isExcalidrawPlusSignedUser && (
<WelcomeScreenItem
link="https://plus.excalidraw.com/plus?utm_source=excalidraw&utm_medium=app&utm_content=welcomeScreenGuest"
label="Try Excalidraw Plus!"
shortcut={null}
icon={PlusPromoIcon}
/>
)}
</div>
</div>
);
};
export default WelcomeScreen;

11
src/components/WelcomeScreenDecor.tsx
View File

@ -1,11 +0,0 @@
import { ReactNode } from "react";
const WelcomeScreenDecor = ({
children,
shouldRender,
}: {
children: ReactNode;
shouldRender: boolean;
}) => (shouldRender ? <>{children}</> : null);
export default WelcomeScreenDecor;

24
src/components/footer/Footer.tsx
View File

@ -1,8 +1,11 @@
import clsx from "clsx"; import clsx from "clsx";
import { actionShortcuts } from "../../actions"; import { actionShortcuts } from "../../actions";
import { ActionManager } from "../../actions/manager"; import { ActionManager } from "../../actions/manager";
import { t } from "../../i18n"; import {
import { AppState, UIChildrenComponents } from "../../types"; AppState,
UIChildrenComponents,
UIWelcomeScreenComponents,
} from "../../types";
import { import {
ExitZenModeAction, ExitZenModeAction,
FinalizeAction, FinalizeAction,
@ -11,23 +14,21 @@ import {
} from "../Actions"; } from "../Actions";
import { useDevice } from "../App"; import { useDevice } from "../App";
import { HelpButton } from "../HelpButton"; import { HelpButton } from "../HelpButton";
import { WelcomeScreenHelpArrow } from "../icons";
import { Section } from "../Section"; import { Section } from "../Section";
import Stack from "../Stack"; import Stack from "../Stack";
import WelcomeScreenDecor from "../WelcomeScreenDecor";
const Footer = ({ const Footer = ({
appState, appState,
actionManager, actionManager,
showExitZenModeBtn, showExitZenModeBtn,
renderWelcomeScreen,
footerCenter, footerCenter,
welcomeScreenHelp,
}: { }: {
appState: AppState; appState: AppState;
actionManager: ActionManager; actionManager: ActionManager;
showExitZenModeBtn: boolean; showExitZenModeBtn: boolean;
renderWelcomeScreen: boolean;
footerCenter: UIChildrenComponents["FooterCenter"]; footerCenter: UIChildrenComponents["FooterCenter"];
welcomeScreenHelp: UIWelcomeScreenComponents["HelpHint"];
}) => { }) => {
const device = useDevice(); const device = useDevice();
const showFinalize = const showFinalize =
@ -79,17 +80,8 @@ const Footer = ({
})} })}
> >
<div style={{ position: "relative" }}> <div style={{ position: "relative" }}>
<WelcomeScreenDecor {welcomeScreenHelp}
shouldRender={renderWelcomeScreen && !appState.isLoading}
>
<div className="virgil WelcomeScreen-decor WelcomeScreen-decor--help-pointer">
<div>{t("welcomeScreen.helpHints")}</div>
{WelcomeScreenHelpArrow}
</div>
</WelcomeScreenDecor>
<HelpButton <HelpButton
title={t("helpDialog.title")}
onClick={() => actionManager.executeAction(actionShortcuts)} onClick={() => actionManager.executeAction(actionShortcuts)}
/> />
</div> </div>

176
src/components/welcome-screen/WelcomeScreen.Center.tsx Normal file
View File

@ -0,0 +1,176 @@
import { actionLoadScene, actionShortcuts } from "../../actions";
import { getShortcutFromShortcutName } from "../../actions/shortcuts";
import { t } from "../../i18n";
import {
useDevice,
useExcalidrawActionManager,
useExcalidrawAppState,
} from "../App";
import { ExcalLogo, HelpIcon, LoadIcon } from "../icons";
const WelcomeScreenMenuItemContent = ({
icon,
shortcut,
children,
}: {
icon?: JSX.Element;
shortcut?: string | null;
children: React.ReactNode;
}) => {
const device = useDevice();
return (
<>
<div className="welcome-screen-menu-item__icon">{icon}</div>
<div className="welcome-screen-menu-item__text">{children}</div>
{shortcut && !device.isMobile && (
<div className="welcome-screen-menu-item__shortcut">{shortcut}</div>
)}
</>
);
};
WelcomeScreenMenuItemContent.displayName = "WelcomeScreenMenuItemContent";
const WelcomeScreenMenuItem = ({
onSelect,
children,
icon,
shortcut,
className = "",
...props
}: {
onSelect: () => void;
children: React.ReactNode;
icon?: JSX.Element;
shortcut?: string | null;
} & React.ButtonHTMLAttributes<HTMLButtonElement>) => {
return (
<button
{...props}
type="button"
className={`welcome-screen-menu-item ${className}`}
onClick={onSelect}
>
<WelcomeScreenMenuItemContent icon={icon} shortcut={shortcut}>
{children}
</WelcomeScreenMenuItemContent>
</button>
);
};
WelcomeScreenMenuItem.displayName = "WelcomeScreenMenuItem";
const WelcomeScreenMenuItemLink = ({
children,
href,
icon,
shortcut,
className = "",
...props
}: {
children: React.ReactNode;
href: string;
icon?: JSX.Element;
shortcut?: string | null;
} & React.AnchorHTMLAttributes<HTMLAnchorElement>) => {
return (
<a
{...props}
className={`welcome-screen-menu-item ${className}`}
href={href}
target="_blank"
rel="noreferrer"
>
<WelcomeScreenMenuItemContent icon={icon} shortcut={shortcut}>
{children}
</WelcomeScreenMenuItemContent>
</a>
);
};
WelcomeScreenMenuItemLink.displayName = "WelcomeScreenMenuItemLink";
const Center = ({ children }: { children?: React.ReactNode }) => {
return (
<div className="welcome-screen-center">
{children || (
<>
<Logo />
<Heading>{t("welcomeScreen.defaults.center_heading")}</Heading>
<Menu>
<MenuItemLoadScene />
<MenuItemHelp />
</Menu>
</>
)}
</div>
);
};
Center.displayName = "Center";
const Logo = ({ children }: { children?: React.ReactNode }) => {
return (
<div className="welcome-screen-center__logo virgil welcome-screen-decor">
{children || <>{ExcalLogo} Excalidraw</>}
</div>
);
};
Logo.displayName = "Logo";
const Heading = ({ children }: { children: React.ReactNode }) => {
return (
<div className="welcome-screen-center__heading welcome-screen-decor virgil">
{children}
</div>
);
};
Heading.displayName = "Heading";
const Menu = ({ children }: { children?: React.ReactNode }) => {
return <div className="welcome-screen-menu">{children}</div>;
};
Menu.displayName = "Menu";
const MenuItemHelp = () => {
const actionManager = useExcalidrawActionManager();
return (
<WelcomeScreenMenuItem
onSelect={() => actionManager.executeAction(actionShortcuts)}
shortcut="?"
icon={HelpIcon}
>
{t("helpDialog.title")}
</WelcomeScreenMenuItem>
);
};
MenuItemHelp.displayName = "MenuItemHelp";
const MenuItemLoadScene = () => {
const appState = useExcalidrawAppState();
const actionManager = useExcalidrawActionManager();
if (appState.viewModeEnabled) {
return null;
}
return (
<WelcomeScreenMenuItem
onSelect={() => actionManager.executeAction(actionLoadScene)}
shortcut={getShortcutFromShortcutName("loadScene")}
icon={LoadIcon}
>
{t("buttons.load")}
</WelcomeScreenMenuItem>
);
};
MenuItemLoadScene.displayName = "MenuItemLoadScene";
// -----------------------------------------------------------------------------
Center.Logo = Logo;
Center.Heading = Heading;
Center.Menu = Menu;
Center.MenuItem = WelcomeScreenMenuItem;
Center.MenuItemLink = WelcomeScreenMenuItemLink;
Center.MenuItemHelp = MenuItemHelp;
Center.MenuItemLoadScene = MenuItemLoadScene;
export { Center };

42
src/components/welcome-screen/WelcomeScreen.Hints.tsx Normal file
View File

@ -0,0 +1,42 @@
import { t } from "../../i18n";
import {
WelcomeScreenHelpArrow,
WelcomeScreenMenuArrow,
WelcomeScreenTopToolbarArrow,
} from "../icons";
const MenuHint = ({ children }: { children?: React.ReactNode }) => {
return (
<div className="virgil welcome-screen-decor welcome-screen-decor-hint welcome-screen-decor-hint--menu">
{WelcomeScreenMenuArrow}
<div className="welcome-screen-decor-hint__label">
{children || t("welcomeScreen.defaults.menuHint")}
</div>
</div>
);
};
MenuHint.displayName = "MenuHint";
const ToolbarHint = ({ children }: { children?: React.ReactNode }) => {
return (
<div className="virgil welcome-screen-decor welcome-screen-decor-hint welcome-screen-decor-hint--toolbar">
<div className="welcome-screen-decor-hint__label">
{children || t("welcomeScreen.defaults.toolbarHint")}
</div>
{WelcomeScreenTopToolbarArrow}
</div>
);
};
ToolbarHint.displayName = "ToolbarHint";
const HelpHint = ({ children }: { children?: React.ReactNode }) => {
return (
<div className="virgil welcome-screen-decor welcome-screen-decor-hint welcome-screen-decor-hint--help">
<div>{children || t("welcomeScreen.defaults.helpHint")}</div>
{WelcomeScreenHelpArrow}
</div>
);
};
HelpHint.displayName = "HelpHint";
export { HelpHint, MenuHint, ToolbarHint };

165
src/components/WelcomeScreen.scss → src/components/welcome-screen/WelcomeScreen.scss
View File

@ -3,29 +3,39 @@
font-family: "Virgil"; font-family: "Virgil";
} }
.WelcomeScreen-logo { // WelcomeSreen common
display: flex; // ---------------------------------------------------------------------------
align-items: center;
column-gap: 0.75rem;
font-size: 2.25rem;
svg { .welcome-screen-decor {
width: 1.625rem;
height: auto;
}
}
.WelcomeScreen-decor {
pointer-events: none; pointer-events: none;
color: var(--color-gray-40); color: var(--color-gray-40);
&--subheading {
font-size: 1.125rem;
text-align: center;
} }
&--help-pointer { &.theme--dark {
.welcome-screen-decor {
color: var(--color-gray-60);
}
}
// WelcomeScreen.Hints
// ---------------------------------------------------------------------------
.welcome-screen-decor-hint {
@media (max-height: 599px) {
display: none !important;
}
@media (max-width: 1024px), (max-width: 800px) {
.welcome-screen-decor {
&--help,
&--menu {
display: none;
}
}
}
&--help {
display: flex; display: flex;
position: absolute; position: absolute;
right: 0; right: 0;
@ -49,7 +59,7 @@
} }
} }
&--top-toolbar-pointer { &--toolbar {
position: absolute; position: absolute;
top: 100%; top: 100%;
left: 50%; left: 50%;
@ -58,7 +68,7 @@
display: flex; display: flex;
align-items: baseline; align-items: baseline;
&__label { .welcome-screen-decor-hint__label {
width: 120px; width: 120px;
position: relative; position: relative;
top: -0.5rem; top: -0.5rem;
@ -74,7 +84,7 @@
} }
} }
&--menu-pointer { &--menu {
position: absolute; position: absolute;
width: 320px; width: 320px;
font-size: 1rem; font-size: 1rem;
@ -95,10 +105,19 @@
transform: scaleX(-1); transform: scaleX(-1);
} }
} }
@media (max-width: 860px) {
.welcome-screen-decor-hint__label {
max-width: 160px;
}
}
} }
} }
.WelcomeScreen-container { // WelcomeSreen.Center
// ---------------------------------------------------------------------------
.welcome-screen-center {
display: flex; display: flex;
flex-direction: column; flex-direction: column;
gap: 2rem; gap: 2rem;
@ -112,7 +131,24 @@
bottom: 1rem; bottom: 1rem;
} }
.WelcomeScreen-items { .welcome-screen-center__logo {
display: flex;
align-items: center;
column-gap: 0.75rem;
font-size: 2.25rem;
svg {
width: 1.625rem;
height: auto;
}
}
.welcome-screen-center__heading {
font-size: 1.125rem;
text-align: center;
}
.welcome-screen-menu {
display: flex; display: flex;
flex-direction: column; flex-direction: column;
gap: 2px; gap: 2px;
@ -120,7 +156,7 @@
align-items: center; align-items: center;
} }
.WelcomeScreen-item { .welcome-screen-menu-item {
box-sizing: border-box; box-sizing: border-box;
pointer-events: all; pointer-events: all;
@ -128,8 +164,10 @@
color: var(--color-gray-50); color: var(--color-gray-50);
font-size: 0.875rem; font-size: 0.875rem;
width: 100%;
min-width: 300px; min-width: 300px;
display: flex; max-width: 400px;
display: grid;
align-items: center; align-items: center;
justify-content: space-between; justify-content: space-between;
@ -140,44 +178,49 @@
border-radius: var(--border-radius-md); border-radius: var(--border-radius-md);
&__label { grid-template-columns: calc(var(--default-icon-size) + 0.5rem) 1fr 3rem;
&__text {
display: flex; display: flex;
align-items: center; align-items: center;
margin-right: auto;
text-align: left;
column-gap: 0.5rem; column-gap: 0.5rem;
}
svg { &__icon {
width: var(--default-icon-size); width: var(--default-icon-size);
height: var(--default-icon-size); height: var(--default-icon-size);
} }
}
&__shortcut { &__shortcut {
margin-left: auto;
color: var(--color-gray-40); color: var(--color-gray-40);
font-size: 0.75rem; font-size: 0.75rem;
} }
} }
&:not(:active) .WelcomeScreen-item:hover { &:not(:active) .welcome-screen-menu-item:hover {
text-decoration: none; text-decoration: none;
background: var(--color-gray-10); background: var(--color-gray-10);
.WelcomeScreen-item__shortcut { .welcome-screen-menu-item__shortcut {
color: var(--color-gray-50); color: var(--color-gray-50);
} }
.WelcomeScreen-item__label { .welcome-screen-menu-item__text {
color: var(--color-gray-100); color: var(--color-gray-100);
} }
} }
.WelcomeScreen-item:active { .welcome-screen-menu-item:active {
background: var(--color-gray-20); background: var(--color-gray-20);
.WelcomeScreen-item__shortcut { .welcome-screen-menu-item__shortcut {
color: var(--color-gray-50); color: var(--color-gray-50);
} }
.WelcomeScreen-item__label { .welcome-screen-menu-item__text {
color: var(--color-gray-100); color: var(--color-gray-100);
} }
@ -185,7 +228,7 @@
color: var(--color-promo) !important; color: var(--color-promo) !important;
&:hover { &:hover {
.WelcomeScreen-item__label { .welcome-screen-menu-item__text {
color: var(--color-promo) !important; color: var(--color-promo) !important;
} }
} }
@ -193,11 +236,7 @@
} }
&.theme--dark { &.theme--dark {
.WelcomeScreen-decor { .welcome-screen-menu-item {
color: var(--color-gray-60);
}
.WelcomeScreen-item {
color: var(--color-gray-60); color: var(--color-gray-60);
&__shortcut { &__shortcut {
@ -205,69 +244,41 @@
} }
} }
&:not(:active) .WelcomeScreen-item:hover { &:not(:active) .welcome-screen-menu-item:hover {
background: var(--color-gray-85); background: var(--color-gray-85);
.WelcomeScreen-item__shortcut { .welcome-screen-menu-item__shortcut {
color: var(--color-gray-50); color: var(--color-gray-50);
} }
.WelcomeScreen-item__label { .welcome-screen-menu-item__text {
color: var(--color-gray-10); color: var(--color-gray-10);
} }
} }
.WelcomeScreen-item:active { .welcome-screen-menu-item:active {
background-color: var(--color-gray-90); background-color: var(--color-gray-90);
.WelcomeScreen-item__label { .welcome-screen-menu-item__text {
color: var(--color-gray-10); color: var(--color-gray-10);
} }
} }
} }
// Can tweak these values but for an initial effort, it looks OK to me
@media (max-width: 1024px) {
.WelcomeScreen-decor {
&--help-pointer,
&--menu-pointer {
display: none;
}
}
}
// @media (max-height: 400px) {
// .WelcomeScreen-container {
// margin-top: 0;
// }
// }
@media (max-height: 599px) { @media (max-height: 599px) {
.WelcomeScreen-container { .welcome-screen-center {
margin-top: 4rem; margin-top: 4rem;
} }
} }
@media (min-height: 600px) and (max-height: 900px) { @media (min-height: 600px) and (max-height: 900px) {
.WelcomeScreen-container { .welcome-screen-center {
margin-top: 8rem; margin-top: 8rem;
} }
} }
@media (max-height: 630px) { @media (max-height: 500px), (max-width: 320px) {
.WelcomeScreen-decor--top-toolbar-pointer { .welcome-screen-center {
display: none;
}
}
@media (max-height: 500px) {
.WelcomeScreen-container {
display: none; display: none;
} }
} }
// @media (max-height: 740px) { // ---------------------------------------------------------------------------
// .WelcomeScreen-decor {
// &--help-pointer,
// &--top-toolbar-pointer,
// &--menu-pointer {
// display: none;
// }
// }
// }
} }

17
src/components/welcome-screen/WelcomeScreen.tsx Normal file
View File

@ -0,0 +1,17 @@
import { Center } from "./WelcomeScreen.Center";
import { MenuHint, ToolbarHint, HelpHint } from "./WelcomeScreen.Hints";
import "./WelcomeScreen.scss";
const WelcomeScreen = (props: { children: React.ReactNode }) => {
// NOTE this component is used as a dummy wrapper to retrieve child props
// from, and will never be rendered to DOM directly. As such, we can't
// do anything here (use hooks and such)
return null;
};
WelcomeScreen.displayName = "WelcomeScreen";
WelcomeScreen.Center = Center;
WelcomeScreen.Hints = { MenuHint, ToolbarHint, HelpHint };
export default WelcomeScreen;

9
src/constants.ts
View File

@ -150,6 +150,7 @@ export const DEFAULT_UI_OPTIONS: AppProps["UIOptions"] = {
toggleTheme: null, toggleTheme: null,
saveAsImage: true, saveAsImage: true,
}, },
welcomeScreen: true,
}; };
// breakpoints // breakpoints
@ -236,14 +237,6 @@ export const ROUNDNESS = {
ADAPTIVE_RADIUS: 3, ADAPTIVE_RADIUS: 3,
} as const; } as const;
export const COOKIES = {
AUTH_STATE_COOKIE: "excplus-auth",
} as const;
/** key containt id of precedeing elemnt id we use in reconciliation during /** key containt id of precedeing elemnt id we use in reconciliation during
* collaboration */ * collaboration */
export const PRECEDING_ELEMENT_KEY = "__precedingElement__"; export const PRECEDING_ELEMENT_KEY = "__precedingElement__";
export const isExcalidrawPlusSignedUser = document.cookie.includes(
COOKIES.AUTH_STATE_COOKIE,
);

8
src/excalidraw-app/app_constants.ts
View File

@ -38,3 +38,11 @@ export const STORAGE_KEYS = {
VERSION_DATA_STATE: "version-dataState", VERSION_DATA_STATE: "version-dataState",
VERSION_FILES: "version-files", VERSION_FILES: "version-files",
} as const; } as const;
export const COOKIES = {
AUTH_STATE_COOKIE: "excplus-auth",
} as const;
export const isExcalidrawPlusSignedUser = document.cookie.includes(
COOKIES.AUTH_STATE_COOKIE,
);

2
src/excalidraw-app/components/ExcalidrawPlusAppLink.tsx
View File

@ -1,4 +1,4 @@
import { isExcalidrawPlusSignedUser } from "../../constants"; import { isExcalidrawPlusSignedUser } from "../app_constants";
export const ExcalidrawPlusAppLink = () => { export const ExcalidrawPlusAppLink = () => {
if (!isExcalidrawPlusSignedUser) { if (!isExcalidrawPlusSignedUser) {

70
src/excalidraw-app/index.tsx
View File

@ -1,6 +1,6 @@
import polyfill from "../polyfill"; import polyfill from "../polyfill";
import LanguageDetector from "i18next-browser-languagedetector"; import LanguageDetector from "i18next-browser-languagedetector";
import { useEffect, useRef, useState } from "react"; import { useEffect, useMemo, useRef, useState } from "react";
import { trackEvent } from "../analytics"; import { trackEvent } from "../analytics";
import { getDefaultAppState } from "../appState"; import { getDefaultAppState } from "../appState";
import { ErrorDialog } from "../components/ErrorDialog"; import { ErrorDialog } from "../components/ErrorDialog";
@ -26,6 +26,7 @@ import {
defaultLang, defaultLang,
Footer, Footer,
MainMenu, MainMenu,
WelcomeScreen,
} from "../packages/excalidraw/index"; } from "../packages/excalidraw/index";
import { import {
AppState, AppState,
@ -45,6 +46,7 @@ import {
} from "../utils"; } from "../utils";
import { import {
FIREBASE_STORAGE_PREFIXES, FIREBASE_STORAGE_PREFIXES,
isExcalidrawPlusSignedUser,
STORAGE_KEYS, STORAGE_KEYS,
SYNC_BROWSER_TABS_TIMEOUT, SYNC_BROWSER_TABS_TIMEOUT,
} from "./app_constants"; } from "./app_constants";
@ -85,7 +87,7 @@ import { parseLibraryTokensFromUrl, useHandleLibrary } from "../data/library";
import { EncryptedIcon } from "./components/EncryptedIcon"; import { EncryptedIcon } from "./components/EncryptedIcon";
import { ExcalidrawPlusAppLink } from "./components/ExcalidrawPlusAppLink"; import { ExcalidrawPlusAppLink } from "./components/ExcalidrawPlusAppLink";
import { LanguageList } from "./components/LanguageList"; import { LanguageList } from "./components/LanguageList";
import { PlusPromoIcon } from "../components/icons"; import { PlusPromoIcon, UsersIcon } from "../components/icons";
polyfill(); polyfill();
@ -634,6 +636,69 @@ const ExcalidrawWrapper = () => {
); );
}; };
const welcomeScreenJSX = useMemo(() => {
let headingContent;
if (isExcalidrawPlusSignedUser) {
headingContent = t("welcomeScreen.app.center_heading_plus")
.split(/(Excalidraw\+)/)
.map((bit, idx) => {
if (bit === "Excalidraw+") {
return (
<a
style={{ pointerEvents: "all" }}
href={`${process.env.REACT_APP_PLUS_APP}?utm_source=excalidraw&utm_medium=app&utm_content=welcomeScreenSignedInUser`}
key={idx}
>
Excalidraw+
</a>
);
}
return bit;
});
} else {
headingContent = t("welcomeScreen.app.center_heading");
}
return (
<WelcomeScreen>
<WelcomeScreen.Hints.MenuHint>
{t("welcomeScreen.app.menuHint")}
</WelcomeScreen.Hints.MenuHint>
<WelcomeScreen.Hints.ToolbarHint />
<WelcomeScreen.Hints.HelpHint />
<WelcomeScreen.Center>
<WelcomeScreen.Center.Logo />
<WelcomeScreen.Center.Heading>
{headingContent}
</WelcomeScreen.Center.Heading>
<WelcomeScreen.Center.Menu>
<WelcomeScreen.Center.MenuItemLoadScene />
<WelcomeScreen.Center.MenuItemHelp />
<WelcomeScreen.Center.MenuItem
shortcut={null}
onSelect={() => setCollabDialogShown(true)}
icon={UsersIcon}
>
{t("labels.liveCollaboration")}
</WelcomeScreen.Center.MenuItem>
{!isExcalidrawPlusSignedUser && (
<WelcomeScreen.Center.MenuItemLink
href="https://plus.excalidraw.com/plus?utm_source=excalidraw&utm_medium=app&utm_content=welcomeScreenGuest"
shortcut={null}
icon={PlusPromoIcon}
>
Try Excalidraw Plus!
</WelcomeScreen.Center.MenuItemLink>
)}
</WelcomeScreen.Center.Menu>
</WelcomeScreen.Center>
</WelcomeScreen>
);
}, [setCollabDialogShown]);
return ( return (
<div <div
style={{ height: "100%" }} style={{ height: "100%" }}
@ -687,6 +752,7 @@ const ExcalidrawWrapper = () => {
<EncryptedIcon /> <EncryptedIcon />
</div> </div>
</Footer> </Footer>
{welcomeScreenJSX}
</Excalidraw> </Excalidraw>
{excalidrawAPI && <Collab excalidrawAPI={excalidrawAPI} />} {excalidrawAPI && <Collab excalidrawAPI={excalidrawAPI} />}
{errorMessage && ( {errorMessage && (

16
src/locales/en.json
View File

@ -448,10 +448,16 @@
"d9480f": "Orange 9" "d9480f": "Orange 9"
}, },
"welcomeScreen": { "welcomeScreen": {
"data": "All your data is saved locally in your browser.", "app": {
"switchToPlusApp": "Did you want to go to the Excalidraw+ instead?", "center_heading": "All your data is saved locally in your browser.",
"menuHints": "Export, preferences, languages, ...", "center_heading_plus": "Did you want to go to the Excalidraw+ instead?",
"toolbarHints": "Pick a tool & Start drawing!", "menuHint": "Export, preferences, languages, ..."
"helpHints": "Shortcuts & help" },
"defaults": {
"menuHint": "Export, preferences, and more...",
"center_heading": "Diagrams. Made. Simple.",
"toolbarHint": "Pick a tool & Start drawing!",
"helpHint": "Shortcuts & help"
}
} }
} }

10
src/packages/excalidraw/CHANGELOG.md
View File

@ -15,15 +15,19 @@ Please add the latest change on the top under the correct section.
### Features ### Features
- Any top-level children passed to the `<Excalidraw/>` component that do not belong to one of the officially supported Excalidraw children components are now rendered directly inside the Excalidraw container (previously, they weren't rendered at all) [#6096](https://github.com/excalidraw/excalidraw/pull/6096). - Support customization for the editor [welcome screen](https://github.com/excalidraw/excalidraw/blob/master/src/packages/excalidraw/README.md#WelcomeScreen) [#6048](https://github.com/excalidraw/excalidraw/pull/6048).
- 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) - 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) - Support customization for the Excalidraw [main menu](https://github.com/excalidraw/excalidraw/blob/master/src/packages/excalidraw/README.md#MainMenu) [#6034](https://github.com/excalidraw/excalidraw/pull/6034).
- [Footer](https://github.com/excalidraw/excalidraw/blob/master/src/packages/excalidraw/README.md#Footer) is now rendered as child component instead of passed as a render prop [#5970](https://github.com/excalidraw/excalidraw/pull/5970).
- Any top-level children passed to the `<Excalidraw/>` component that do not belong to one of the officially supported Excalidraw children components are now rendered directly inside the Excalidraw container (previously, they weren't rendered at all) [#6096](https://github.com/excalidraw/excalidraw/pull/6096).
#### BREAKING CHANGE #### BREAKING CHANGE
- With this change, the prop `renderFooter` is now removed. - The prop `renderFooter` is now removed in favor of rendering as a child component.
### Excalidraw schema ### Excalidraw schema

222
src/packages/excalidraw/README.md
View File

@ -405,15 +405,14 @@ const App = () => {
}; };
``` ```
This will only for `Desktop` devices. Footer is only rendered in the desktop view.
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. In the mobile view you can render it inside the [MainMenu](#mainmenu) (later we will expose other ways to customize the UI). 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 ```js
import { useDevice, Footer } from "@excalidraw/excalidraw"; import { useDevice, Footer } from "@excalidraw/excalidraw";
const MobileFooter = ({ const MobileFooter = () => {
}) => {
const device = useDevice(); const device = useDevice();
if (device.isMobile) { if (device.isMobile) {
return ( return (
@ -429,18 +428,21 @@ const MobileFooter = ({
); );
} }
return null; return null;
}; };
const App = () => { const App = () => {
<Excalidraw> <Excalidraw>
<MainMenu> <MainMenu>
<MainMenu.Item onSelect={() => window.alert("Item1")}> Item1 </MainMenu.Item> <MainMenu.Item onSelect={() => window.alert("Item1")}>
<MainMenu.Item onSelect={() => window.alert("Item2")}> Item 2 </> Item1
</MainMenu.Item>
<MainMenu.Item onSelect={() => window.alert("Item2")}>
Item2
</MainMenu.Item>
<MobileFooter /> <MobileFooter />
</MainMenu> </MainMenu>
</Excalidraw> </Excalidraw>;
} };
``` ```
You can visit the [example](https://ehlz3.csb.app/) for working demo. You can visit the [example](https://ehlz3.csb.app/) for working demo.
@ -456,11 +458,15 @@ import { MainMenu } from "@excalidraw/excalidraw";
const App = () => { const App = () => {
<Excalidraw> <Excalidraw>
<MainMenu> <MainMenu>
<MainMenu.Item onSelect={() => window.alert("Item1")}> Item1 </MainMenu.Item> <MainMenu.Item onSelect={() => window.alert("Item1")}>
<MainMenu.Item onSelect={() => window.alert("Item2")}> Item 2 </> Item1
</MainMenu.Item>
<MainMenu.Item onSelect={() => window.alert("Item2")}>
Item2
</MainMenu.Item>
</MainMenu> </MainMenu>
</Excalidraw> </Excalidraw>;
} };
``` ```
**MainMenu** **MainMenu**
@ -469,28 +475,28 @@ This is the `MainMenu` component which you need to import to render the menu wit
**MainMenu.Item** **MainMenu.Item**
To render an item, its recommended to use `MainMenu.Item`. Use this component to render a menu item.
| Prop | Type | Required | Default | Description | | Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- |
| `onSelect` | `Function` | Yes | `undefined` | The handler is triggered when the item is selected. | | `onSelect` | `Function` | Yes | | The handler is triggered when the item is selected. |
| `children` | `React.ReactNode` | Yes | `undefined` | The content of the menu item | | `children` | `React.ReactNode` | Yes | | The content of the menu item |
| `icon` | `JSX.Element` | No | `undefined` | The icon used in the menu item | | `icon` | `JSX.Element` | No | | The icon used in the menu item |
| `shortcut` | `string` | No | `undefined` | The shortcut to be shown for the menu item | | `shortcut` | `string` | No | | The keyboard shortcut (label-only, does not affect behavior) |
| `className` | `string` | No | "" | The class names to be added to 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 | | `style` | `React.CSSProperties` | No | | 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 | | `ariaLabel` | `string` | | 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. | | `dataTestId` | `string` | | No | The `data-testid` to be added to the item. |
**MainMenu.ItemLink** **MainMenu.ItemLink**
To render an item as a link, its recommended to use `MainMenu.ItemLink`. To render an external link in a menu item, you can use this component.
**Usage** **Usage**
```js ```js
import { MainMenu } from "@excalidraw/excalidraw"; import { MainMenu } from "@excalidraw/excalidraw";
const App = () => { const App = () => (
<Excalidraw> <Excalidraw>
<MainMenu> <MainMenu>
<MainMenu.ItemLink href="https://google.com">Google</MainMenu.ItemLink> <MainMenu.ItemLink href="https://google.com">Google</MainMenu.ItemLink>
@ -499,19 +505,19 @@ const App = () => {
</MainMenu.ItemLink> </MainMenu.ItemLink>
</MainMenu> </MainMenu>
</Excalidraw>; </Excalidraw>;
}; );
``` ```
| Prop | Type | Required | Default | Description | | Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- |
| `href` | `string` | Yes | `undefined` | The `href` attribute to be added to the `anchor` element. | | `href` | `string` | Yes | | The `href` attribute to be added to the `anchor` element. |
| `children` | `React.ReactNode` | Yes | `undefined` | The content of the menu item | | `children` | `React.ReactNode` | Yes | | The content of the menu item |
| `icon` | `JSX.Element` | No | `undefined` | The icon used in the menu item | | `icon` | `JSX.Element` | No | | The icon used in the menu item |
| `shortcut` | `string` | No | `undefined` | The shortcut to be shown for the menu item | | `shortcut` | `string` | No | | The keyboard shortcut (label-only, does not affect behavior) |
| `className` | `string` | No | "" | The class names to be added to 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 | | `style` | `React.CSSProperties` | No | | 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 | | `ariaLabel` | `string` | No | | The `aria-label` to be added to the item for accessibility |
| `dataTestId` | `string` | No | `undefined` | The `data-testid` to be added to the item. | | `dataTestId` | `string` | No | | The `data-testid` to be added to the item. |
**MainMenu.ItemCustom** **MainMenu.ItemCustom**
@ -521,7 +527,7 @@ To render a custom item, you can use `MainMenu.ItemCustom`.
```js ```js
import { MainMenu } from "@excalidraw/excalidraw"; import { MainMenu } from "@excalidraw/excalidraw";
const App = () => { const App = () => (
<Excalidraw> <Excalidraw>
<MainMenu> <MainMenu>
<MainMenu.ItemCustom> <MainMenu.ItemCustom>
@ -535,7 +541,7 @@ const App = () => {
</MainMenu.ItemCustom> </MainMenu.ItemCustom>
</MainMenu> </MainMenu>
</Excalidraw>; </Excalidraw>;
}; );
``` ```
| Prop | Type | Required | Default | Description | | Prop | Type | Required | Default | Description |
@ -551,7 +557,7 @@ For the items which are shown in the menu in [excalidraw.com](https://excalidraw
```js ```js
import { MainMenu } from "@excalidraw/excalidraw"; import { MainMenu } from "@excalidraw/excalidraw";
const App = () => { const App = () => (
<Excalidraw> <Excalidraw>
<MainMenu> <MainMenu>
<MainMenu.DefaultItems.Socials/> <MainMenu.DefaultItems.Socials/>
@ -560,7 +566,7 @@ const App = () => {
<MainMenu.Item onSelect={() => window.alert("Item2")}> Item 2 </> <MainMenu.Item onSelect={() => window.alert("Item2")}> Item 2 </>
</MainMenu> </MainMenu>
</Excalidraw> </Excalidraw>
} )
``` ```
Here is a [complete list](https://github.com/excalidraw/excalidraw/blob/master/src/components/mainMenu/DefaultItems.tsx) of the default items. Here is a [complete list](https://github.com/excalidraw/excalidraw/blob/master/src/components/mainMenu/DefaultItems.tsx) of the default items.
@ -571,7 +577,7 @@ To Group item in the main menu, you can use `MainMenu.Group`
```js ```js
import { MainMenu } from "@excalidraw/excalidraw"; import { MainMenu } from "@excalidraw/excalidraw";
const App = () => { const App = () => (
<Excalidraw> <Excalidraw>
<MainMenu> <MainMenu>
<MainMenu.Group title="Excalidraw items"> <MainMenu.Group title="Excalidraw items">
@ -584,16 +590,149 @@ const App = () => {
</MainMenu.Group> </MainMenu.Group>
</MainMenu> </MainMenu>
</Excalidraw> </Excalidraw>
} )
``` ```
| Prop | Type | Required | Default | Description | | Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- |
| `children ` | `React.ReactNode` | Yes | `undefined` | The content of the `Menu Group` | | `children ` | `React.ReactNode` | Yes | `undefined` | The content of the `MenuItem Group` |
| `title` | `string` | No | `undefined` | The `title` for the grouped items | | `title` | `string` | No | `undefined` | The `title` for the grouped items |
| `className` | `string` | No | "" | The `classname` to be added to the group | | `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 | | `style` | `React.CSsSProperties` | No | `undefined` | The inline `styles` to be added to the group |
### WelcomeScreen
When the canvas is empty, Excalidraw shows a welcome "splash" screen with a logo, a few quick action items, and hints explaining what some of the UI buttons do. You can customize the welcome screen by rendering the `WelcomeScreen` component inside your Excalidraw instance.
You can also disable the welcome screen altogether by setting `UIOptions.welcomeScreen` to `false`.
**Usage**
```jsx
import { WelcomScreen } from "@excalidraw/excalidraw";
const App = () => (
<Excalidraw>
<WelcomeScreen>
<WelcomeScreen.Center>
<WelcomeScreen.Center.Heading>
Your data are autosaved to the cloud.
</WelcomeScreen.Center.Heading>
<WelcomeScreen.Center.Menu>
<WelcomeScreen.Center.MenuItem
onClick={() => console.log("clicked!")}
>
Click me!
</WelcomeScreen.Center.MenuItem>
<WelcomeScreen.Center.MenuItemLink href="https://github.com/excalidraw/excalidraw">
Excalidraw GitHub
</WelcomeScreen.Center.MenuItemLink>
<WelcomeScreen.Center.MenuItemHelp />
</WelcomeScreen.Center.Menu>
</WelcomeScreen.Center>
</WelcomeScreen>
</Excalidraw>
);
```
To disable the WelcomeScreen:
```jsx
import { WelcomScreen } from "@excalidraw/excalidraw";
const App = () => <Excalidraw UIOptions={{ welcomeScreen: false }} />;
```
**WelcomeScreen**
If you render the `<WelcomeScreen>` component, you are responsible for rendering the content.
There are 2 main parts: 1) welcome screen center component, and 2) welcome screen hints.
![WelcomeScreen overview](./welcome-screen-overview.png)
**WelcomeScreen.Center**
This is the center piece of the welcome screen, containing the logo, heading, and menu. All three sub-components are optional, and you can render whatever you wish into the center component.
**WelcomeScreen.Center.Logo**
By default renders the Excalidraw logo and name. Supply `children` to customize.
**WelcomeScreen.Center.Heading**
Supply `children` to change the default message.
**WelcomeScreen.Center.Menu**
Wrapper component for the menu items. You can build your menu using the `<WelcomeScreen.Center.MenuItem>` and `<WelcomeScreen.Center.MenuItemLink>` components, render your own, or render one of the default menu items.
The default menu items are:
- `<WelcomeScreen.Center.MenuItemHelp/>` - opens the help dialog.
- `<WelcomeScreen.Center.MenuItemLoadScene/>` - open the load file dialog.
**Usage**
```jsx
import { WelcomScreen } from "@excalidraw/excalidraw";
const App = () => (
<Excalidraw>
<WelcomeScreen>
<WelcomeScreen.Center>
<WelcomeScreen.Center.Menu>
<WelcomeScreen.Center.MenuItem
onClick={() => console.log("clicked!")}
>
Click me!
</WelcomeScreen.Center.MenuItem>
<WelcomeScreen.Center.MenuItemLink href="https://github.com/excalidraw/excalidraw">
Excalidraw GitHub
</WelcomeScreen.Center.MenuItemLink>
<WelcomeScreen.Center.MenuItemHelp />
</WelcomeScreen.Center.Menu>
</WelcomeScreen.Center>
</WelcomeScreen>
</Excalidraw>
);
```
**WelcomeScreen.Center.MenuItem**
Use this component to render a menu item.
| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `onSelect` | `Function` | Yes | | The handler is triggered when the item is selected. |
| `children` | `React.ReactNode` | Yes | | The content of the menu item |
| `icon` | `JSX.Element` | No | | The icon used in the menu item |
| `shortcut` | `string` | No | | The keyboard shortcut (label-only, does not affect behavior) |
**WelcomeScreen.Center.MenuItemLink**
To render an external link in a menu item, you can use this component.
| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `href` | `string` | Yes | | The `href` attribute to be added to the `anchor` element. |
| `children` | `React.ReactNode` | Yes | | The content of the menu item |
| `icon` | `JSX.Element` | No | | The icon used in the menu item |
| `shortcut` | `string` | No | | The keyboard shortcut (label-only, does not affect behavior) |
**WelcomeScreen.Hints**
These subcomponents render the UI hints. Text of each hint can be customized by supplying `children`.
**WelcomeScreen.Hints.Menu**
Hint for the main menu. Supply `children` to customize the hint text.
**WelcomeScreen.Hints.Toolbar**
Hint for the toolbar. Supply `children` to customize the hint text.
**WelcomeScreen.Hints.Help**
Hint for the help dialog. Supply `children` to customize the hint text.
### Props ### Props
| Name | Type | Default | Description | | Name | Type | Default | Description |
@ -1565,8 +1704,7 @@ This hook can be used to check the type of device which is being used. It can on
```js ```js
import { useDevice, Footer } from "@excalidraw/excalidraw"; import { useDevice, Footer } from "@excalidraw/excalidraw";
const MobileFooter = ({ const MobileFooter = () => {
}) => {
const device = useDevice(); const device = useDevice();
if (device.isMobile) { if (device.isMobile) {
return ( return (

7
src/packages/excalidraw/index.tsx
View File

@ -13,6 +13,7 @@ import { Provider } from "jotai";
import { jotaiScope, jotaiStore } from "../../jotai"; import { jotaiScope, jotaiStore } from "../../jotai";
import Footer from "../../components/footer/FooterCenter"; import Footer from "../../components/footer/FooterCenter";
import MainMenu from "../../components/mainMenu/MainMenu"; import MainMenu from "../../components/mainMenu/MainMenu";
import WelcomeScreen from "../../components/welcome-screen/WelcomeScreen";
const ExcalidrawBase = (props: ExcalidrawProps) => { const ExcalidrawBase = (props: ExcalidrawProps) => {
const { const {
@ -52,6 +53,7 @@ const ExcalidrawBase = (props: ExcalidrawProps) => {
...DEFAULT_UI_OPTIONS.canvasActions, ...DEFAULT_UI_OPTIONS.canvasActions,
...canvasActions, ...canvasActions,
}, },
welcomeScreen: props.UIOptions?.welcomeScreen ?? true,
}; };
if (canvasActions?.export) { if (canvasActions?.export) {
@ -162,7 +164,7 @@ const areEqual = (
const canvasOptionKeys = Object.keys( const canvasOptionKeys = Object.keys(
prevUIOptions.canvasActions!, prevUIOptions.canvasActions!,
) as (keyof Partial<typeof DEFAULT_UI_OPTIONS.canvasActions>)[]; ) as (keyof Partial<typeof DEFAULT_UI_OPTIONS.canvasActions>)[];
canvasOptionKeys.every((key) => { return canvasOptionKeys.every((key) => {
if ( if (
key === "export" && key === "export" &&
prevUIOptions?.canvasActions?.export && prevUIOptions?.canvasActions?.export &&
@ -179,7 +181,7 @@ const areEqual = (
); );
}); });
} }
return true; return prevUIOptions[key] === nextUIOptions[key];
}); });
return isUIOptionsSame && isShallowEqual(prev, next); return isUIOptionsSame && isShallowEqual(prev, next);
@ -243,3 +245,4 @@ export { Button } from "../../components/Button";
export { Footer }; export { Footer };
export { MainMenu }; export { MainMenu };
export { useDevice } from "../../components/App"; export { useDevice } from "../../components/App";
export { WelcomeScreen };

BIN
src/packages/excalidraw/welcome-screen-overview.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 101 KiB

67
src/types.ts
View File

@ -313,10 +313,7 @@ export interface ExcalidrawProps {
elements: readonly NonDeletedExcalidrawElement[], elements: readonly NonDeletedExcalidrawElement[],
appState: AppState, appState: AppState,
) => JSX.Element; ) => JSX.Element;
UIOptions?: { UIOptions?: Partial<UIOptions>;
dockedSidebarBreakpoint?: number;
canvasActions?: CanvasActions;
};
detectScroll?: boolean; detectScroll?: boolean;
handleKeyboardGlobally?: boolean; handleKeyboardGlobally?: boolean;
onLibraryChange?: (libraryItems: LibraryItems) => void | Promise<any>; onLibraryChange?: (libraryItems: LibraryItems) => void | Promise<any>;
@ -373,23 +370,31 @@ export type ExportOpts = {
// truthiness value will determine whether the action is rendered or not // truthiness value will determine whether the action is rendered or not
// (see manager renderAction). We also override canvasAction values in // (see manager renderAction). We also override canvasAction values in
// excalidraw package index.tsx. // excalidraw package index.tsx.
type CanvasActions = { type CanvasActions = Partial<{
changeViewBackgroundColor?: boolean; changeViewBackgroundColor: boolean;
clearCanvas?: boolean; clearCanvas: boolean;
export?: false | ExportOpts; export: false | ExportOpts;
loadScene?: boolean; loadScene: boolean;
saveToActiveFile?: boolean; saveToActiveFile: boolean;
toggleTheme?: boolean | null; toggleTheme: boolean | null;
saveAsImage?: boolean; saveAsImage: boolean;
}; }>;
type UIOptions = Partial<{
dockedSidebarBreakpoint: number;
welcomeScreen: boolean;
canvasActions: CanvasActions;
}>;
export type AppProps = Merge< export type AppProps = Merge<
ExcalidrawProps, ExcalidrawProps,
{ {
UIOptions: { UIOptions: Merge<
MarkRequired<UIOptions, "welcomeScreen">,
{
canvasActions: Required<CanvasActions> & { export: ExportOpts }; canvasActions: Required<CanvasActions> & { export: ExportOpts };
dockedSidebarBreakpoint?: number; }
}; >;
detectScroll: boolean; detectScroll: boolean;
handleKeyboardGlobally: boolean; handleKeyboardGlobally: boolean;
isCollaborating: boolean; isCollaborating: boolean;
@ -517,7 +522,31 @@ export type Device = Readonly<{
}>; }>;
export type UIChildrenComponents = { export type UIChildrenComponents = {
[k in "FooterCenter" | "Menu"]?: [k in "FooterCenter" | "Menu" | "WelcomeScreen"]?: React.ReactElement<
| React.ReactPortal { children?: React.ReactNode },
| React.ReactElement<unknown, string | React.JSXElementConstructor<any>>; React.JSXElementConstructor<any>
>;
};
export type UIWelcomeScreenComponents = {
[k in
| "Center"
| "MenuHint"
| "ToolbarHint"
| "HelpHint"]?: React.ReactElement<
{ children?: React.ReactNode },
React.JSXElementConstructor<any>
>;
};
export type UIWelcomeScreenCenterComponents = {
[k in
| "Logo"
| "Heading"
| "Menu"
| "MenuItemLoadScene"
| "MenuItemHelp"]?: React.ReactElement<
{ children?: React.ReactNode },
React.JSXElementConstructor<any>
>;
}; };