From 346be6d505a26f45708d32a5c12652c94032f91c Mon Sep 17 00:00:00 2001
From: Taha <98838967+Taha-Hassan-Git@users.noreply.github.com>
Date: Wed, 10 Jan 2024 14:41:34 +0000
Subject: [PATCH] annotate hosted images example (#2422)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

annotate hosted images example

### 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

- annotate hosted images example
---
 .../hosted-images/HostedImagesExample.tsx     | 46 +++++++++++++++++--
 1 file changed, 43 insertions(+), 3 deletions(-)

diff --git a/apps/examples/src/examples/hosted-images/HostedImagesExample.tsx b/apps/examples/src/examples/hosted-images/HostedImagesExample.tsx
index a06ab289b..efc019776 100644
--- a/apps/examples/src/examples/hosted-images/HostedImagesExample.tsx
+++ b/apps/examples/src/examples/hosted-images/HostedImagesExample.tsx
@@ -12,11 +12,13 @@ import {
 import '@tldraw/tldraw/tldraw.css'
 import { useCallback } from 'react'
 
+// [1]
 const UPLOAD_URL = '/SOME_ENDPOINT'
 
+// [2]
 export default function HostedImagesExample() {
 	const handleMount = useCallback((editor: Editor) => {
-		// When a user uploads a file, create an asset from it
+		//[a]
 		editor.registerExternalAssetHandler('file', async ({ file }: { type: 'file'; file: File }) => {
 			const id = uniqueId()
 
@@ -27,7 +29,7 @@ export default function HostedImagesExample() {
 				method: 'POST',
 				body: file,
 			})
-
+			//[b]
 			const assetId: TLAssetId = AssetRecordType.createId(getHashForString(url))
 
 			let size: {
@@ -37,6 +39,7 @@ export default function HostedImagesExample() {
 			let isAnimated: boolean
 			let shapeType: 'image' | 'video'
 
+			//[c]
 			if (['image/jpeg', 'image/png', 'image/gif', 'image/svg+xml'].includes(file.type)) {
 				shapeType = 'image'
 				size = await MediaHelpers.getImageSize(file)
@@ -46,7 +49,7 @@ export default function HostedImagesExample() {
 				isAnimated = true
 				size = await MediaHelpers.getVideoSize(file)
 			}
-
+			//[d]
 			const asset: TLAsset = AssetRecordType.create({
 				id: assetId,
 				type: shapeType,
@@ -71,3 +74,40 @@ export default function HostedImagesExample() {
 		</div>
 	)
 }
+/* 
+Introduction:
+This example shows how to handle images uploaded by the user. to do this we'll
+need to register an external asset handler, which is called when the user uploads
+a file. We'll then upload the file to our server and create an asset from it.
+
+[1]
+You'll want to have an endpoint on your server that accepts a file and returns 
+a url.
+
+[2]
+We use the onMount prop to get access to the editor instance and register our 
+handler. Check out the API example for more details. 
+
+	[a]
+	We then register a handler for the 'file' type.
+	You could also use this method to handle other types of external assets, 
+	like embeds or pasted text, check out the external content sources example 
+	for more. 
+
+	[b]
+	After uploading the file to our server, we create an asset fror it. We'll 
+	need to create a record for the asset, which is an object that contains 
+	the asset's id, type, and props. We'll start by creating the id with the 
+	AssetRecordType.createId method.
+
+	[c]
+	Now it's time to figure out the dimensions of the media is using our 
+	MediaHelpers, and whether it's a gif, image or video.
+
+	[d]
+	Finally we create the asset record using the AssetRecordType.create method
+	and return it. Note that we don't create a shape on the canvas here, if you
+	want to see an example that does this, check out the local images example.
+
+
+*/