From 9ef2a74c3939b8112de06581aacee7eb4d2c8e06 Mon Sep 17 00:00:00 2001
From: Taha <98838967+Taha-Hassan-Git@users.noreply.github.com>
Date: Wed, 10 Jan 2024 15:00:43 +0000
Subject: [PATCH] annotate external sources example (#2414)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Annotates the external sources example with extra info

### Change Type

- [ ] `patch` — Bug fix
- [ ] `minor` — New feature
- [ ] `major` — Breaking change
- [ ] `dependencies` — Changes to package dependencies[^1]
- [x] `documentation` — Changes to the documentation only[^2]
- [ ] `tests` — Changes to any test code only[^2]
- [ ] `internal` — Any other changes that don't affect the published
package[^2]
- [ ] I don't know

[^1]: publishes a `patch` release, for devDependencies use `internal`
[^2]: will not publish a new version

### Test Plan

1. Add a step-by-step description of how to test your PR here.
2.

- [ ] Unit Tests
- [ ] End to end tests

### Release Notes

- Adds annotation to the external sources example.

---------

Co-authored-by: Steve Ruiz <steveruizok@gmail.com>
---
 .../ExternalContentSourcesExample.tsx         | 29 +++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/apps/examples/src/examples/external-content-sources/ExternalContentSourcesExample.tsx b/apps/examples/src/examples/external-content-sources/ExternalContentSourcesExample.tsx
index 8c0323b89..633a52320 100644
--- a/apps/examples/src/examples/external-content-sources/ExternalContentSourcesExample.tsx
+++ b/apps/examples/src/examples/external-content-sources/ExternalContentSourcesExample.tsx
@@ -2,6 +2,9 @@ import { BaseBoxShapeUtil, Editor, HTMLContainer, TLBaseShape, Tldraw } from '@t
 import '@tldraw/tldraw/tldraw.css'
 import { useCallback } from 'react'
 
+// There's a guide at the bottom of this page!
+
+// [1]
 export type IDangerousHtmlShape = TLBaseShape<
 	'html',
 	{
@@ -11,6 +14,7 @@ export type IDangerousHtmlShape = TLBaseShape<
 	}
 >
 
+// [2]
 class DangerousHtmlExample extends BaseBoxShapeUtil<IDangerousHtmlShape> {
 	static override type = 'html' as const
 
@@ -36,6 +40,8 @@ class DangerousHtmlExample extends BaseBoxShapeUtil<IDangerousHtmlShape> {
 	}
 }
 
+// [3]
+
 export default function ExternalContentSourcesExample() {
 	const handleMount = useCallback((editor: Editor) => {
 		// We will register a new handler for text content. When a user pastes `text/html` content into the editor,
@@ -65,3 +71,26 @@ export default function ExternalContentSourcesExample() {
 		</div>
 	)
 }
+
+/* 
+Introduction:
+This example shows how to handle content pasted from external sources, this could be
+embeds, files, svgs, text, images, or urls. In this case we will handle text/html content.
+
+[1]
+We want to render our html on the canvas, the best way to do that is to create a new shape util.
+Here's where we define the type for our shape.
+
+[2]
+This is our shape util. It's a class that extends BaseBoxShapeUtil. For a more detailed
+example of how to create a custom shape, see the custom config example.
+
+[3]
+We use the onMount prop to get access to the editor instance via 
+the handleMount callback (check out the API example for a more detailed look at this). Then we 
+call the registerExternalContentHandler method, we could choose to handle embeds, files, svgs, 
+text, images, or urls. For this example we will handle text/html content. The handler is called
+with the point where the user pasted the content and an array of sources. We will find and 
+return the html source, then create a new shape with that html content.
+
+*/