feat: support `ExcalidrawElement.customData` (#5592)

Co-authored-by: Aakansha Doshi <aakansha1216@gmail.com>

src/data/restore.ts

@@ -67,13 +67,14 @@ const getFontFamilyByName = (fontFamilyName: string): FontFamilyValues => {
 };
 
 const restoreElementWithProperties = <
-  T extends ExcalidrawElement,
-  K extends Pick<T, keyof Omit<Required<T>, keyof ExcalidrawElement>>,
->(
-  element: Required<T> & {
+  T extends Required<Omit<ExcalidrawElement, "customData">> & {
+    customData?: ExcalidrawElement["customData"];
     /** @deprecated */
     boundElementIds?: readonly ExcalidrawElement["id"][];
   },
+  K extends Pick<T, keyof Omit<Required<T>, keyof ExcalidrawElement>>,
+>(
+  element: T,
   extra: Pick<
     T,
     // This extra Pick<T, keyof K> ensure no excess properties are passed.
@@ -115,6 +116,10 @@ const restoreElementWithProperties = <
     locked: element.locked ?? false,
   };
 
+  if ("customData" in element) {
+    base.customData = element.customData;
+  }
+
   return {
     ...base,
     ...getNormalizedDimensions(base),

src/element/types.ts

@@ -56,6 +56,7 @@ type _ExcalidrawElementBase = Readonly<{
   updated: number;
   link: string | null;
   locked: boolean;
+  customData?: Record<string, any>;
 }>;
 
 export type ExcalidrawSelectionElement = _ExcalidrawElementBase & {

src/packages/excalidraw/CHANGELOG.md

@@ -15,9 +15,11 @@ Please add the latest change on the top under the correct section.
 
 ### Excalidraw API
 
+- Added support for storing [`customData`](https://github.com/excalidraw/excalidraw/blob/master/src/packages/excalidraw/README.md#storing-custom-data-to-excalidraw-elements) on Excalidraw elements [#5592].
+
 #### Breaking Changes
 
-- `setToastMessage` API is now renamed to `setToast` API and the function signature is also updated [#5427](https://github.com/excalidraw/excalidraw/pull/5427). You can also pass `duration` and `closable` attributes along with `message`.
+- `setToastMessage` API is now renamed to `setToas○t` API and the function signature is also updated [#5427](https://github.com/excalidraw/excalidraw/pull/5427). You can also pass `duration` and `closable` attributes along with `message`.
 
 ## 0.12.0 (2022-07-07)
 

src/packages/excalidraw/README.md

@@ -470,6 +470,14 @@ This helps to load Excalidraw with `initialData`. It must be an object or a [pro
 
 You might want to use this when you want to load excalidraw with some initial elements and app state.
 
+#### Storing custom data on Excalidraw elements
+
+Beyond attributes that Excalidraw elements already support, you can store custom data on each element in a `customData` object. The type of the attribute is [`Record<string, any>`](https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L59) and is optional.
+
+You can use this to add any extra information you need to keep track of.
+
+You can add `customData` to elements when passing them as `initialData`, or using [`updateScene`](#updateScene)/[`updateLibrary`](#updateLibrary) afterwards.
+
 #### `ref`
 
 You can pass a `ref` when you want to access some excalidraw APIs. We expose the below APIs: