annotate meta onchange (#2430)

annotate meta onchange

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

apps/examples/src/examples/meta-on-change/OnChangeShapeMetaExample.tsx

@@ -1,23 +1,22 @@
 import { TLShape, Tldraw, track, useEditor } from '@tldraw/tldraw'
 import '@tldraw/tldraw/tldraw.css'
 
+// There's a guide at the bottom of this file!
+
 export default function OnChangeShapeMetaExample() {
 	return (
 		<div className="tldraw__editor">
 			<Tldraw
 				persistenceKey="tldraw_change_meta_example"
 				onMount={(editor) => {
-					// See the "meta-on-create" example for more about setting the
-					// initial meta for a shape.
+					// [1]
 					editor.getInitialMetaForShape = (_shape) => {
 						return {
 							updatedBy: editor.user.getId(),
 							updatedAt: Date.now(),
 						}
 					}
-					// We can also use the sideEffects API to modify a shape before
-					// its change is committed to the database. This will run for
-					// all shapes whenever they are updated.
+					// [2]
 					editor.sideEffects.registerBeforeChangeHandler('shape', (_prev, next, source) => {
 						if (source !== 'user') return next
 						return {
@@ -36,8 +35,10 @@ export default function OnChangeShapeMetaExample() {
 	)
 }
 
+// [3]
 type ShapeWithMyMeta = TLShape & { meta: { updatedBy: string; updatedAt: string } }
 
+// [4]
 export const MetaUiHelper = track(function MetaUiHelper() {
 	const editor = useEditor()
 	const onlySelectedShape = editor.getOnlySelectedShape() as ShapeWithMyMeta | null
@@ -50,3 +51,29 @@ export const MetaUiHelper = track(function MetaUiHelper() {
 		</pre>
 	)
 })
+
+/* 
+This example shows how to add meta data to shapes when they are created and
+updated. In this case we are adding `updatedBy` and `updatedAt` fields.
+
+[1]
+getInitialMetaForShape is a method you can replace at runtime. Here we use 
+a callback on the onMount prop to replace the default implementation with 
+our own.
+
+[2]
+Here we're using the side effects API to add meta data to shapes when they are
+updated. You can use the side effects API to do something on create, update or
+delete, and you can target many things including: shapes, pages, the camera, 
+the pointer etc.
+
+[3]
+All tldraw shapes have a meta property with a type of unknown. To type your 
+meta data you can use a union like this.
+
+[4]
+A minimal ui component that displays the meta data of the selected shape. We 
+use track to make sure that the component is re-rendered when the signals it's 
+tracking change. Check out the signia docs for more info: 
+https://signia.tldraw.dev/docs/API/signia_react/functions/track
+*/