annotate local images example (#2423)

annotate local 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 local images example

apps/examples/src/examples/local-images/LocalImagesExample.tsx

@@ -1,20 +1,16 @@
 import { AssetRecordType, Editor, Tldraw } from '@tldraw/tldraw'
 import '@tldraw/tldraw/tldraw.css'
 import { useCallback } from 'react'
+// There's a guide at the bottom of this file!
 
-// This is an example of how you can add an image to the editor. The image is already
-// present in the `public` folder, so we can just use it directly.
-// If you want to allow users to upload the images please take a look at the `HostedImagesExample.tsx`
 export default function LocalImagesExample() {
+	// [1]
 	const handleMount = useCallback((editor: Editor) => {
-		// Assets are records that store data about shared assets like images, videos, etc.
+		//[2]
-		// Each image has an associated asset record, so we'll create that first.
-
-		// We need an `assetId` so that we can later associate it with the image.
 		const assetId = AssetRecordType.createId()
 		const imageWidth = 1200
 		const imageHeight = 675
-
+		//[2]
 		editor.createAssets([
 			{
 				id: assetId,
@@ -31,6 +27,7 @@ export default function LocalImagesExample() {
 				meta: {},
 			},
 		])
+		//[3]
 		editor.createShape({
 			type: 'image',
 			// Let's center the image in the editor
@@ -38,11 +35,6 @@ export default function LocalImagesExample() {
 			y: (window.innerHeight - imageHeight) / 2,
 			props: {
 				assetId,
-				// We are using the full image size here, but as the user resizes the image
-				// these values will get updated.
-				// This shows why it's important to have a separate assets entity. Resizing an image
-				// does not change the dimensions of the file itself, it just updates the dimensions
-				// of the displayed image.
 				w: imageWidth,
 				h: imageHeight,
 			},
@@ -58,3 +50,32 @@ export default function LocalImagesExample() {
 		</div>
 	)
 }
+
+/* 
+This is an example of how you can add a locally hosted image to the editor.
+We need to first create an asset that holds the source image [2], and then 
+create the Image shape itself [3].
+
+Because this is a Next.js app, we can use the `public` folder to store the 
+image locally, your framework may have a different way of serving statis
+assets. 
+
+If you want to allow users to upload the images please take a look at the 
+hosted images example.
+
+[1] 
+We'll access the editor instance via the `onMount` callback. Check out the API 
+example for another way to do this.
+
+[2]
+Assets are records that store data about shared assets like images, videos, etc. 
+Each image has an associated asset record, so we'll create that first. We need an 
+`assetId` so that we can later associate it with the image.
+
+[3]
+We create the image sgape and pass in the `assetId` that we created earlier. This
+will link our image shape to the asset record. Notice that we create the shape with
+the same dimensions as the image, later on the user may resize the image, but we 
+don't want to resize our asset, this is one of the reasons why it's important to 
+keep assets and shapes separate.
+*/