@sprucelabs/spruce-heartwood-utils 38.17.3 → 38.17.4

package/README.md

@@ -709,6 +709,32 @@ interface AnimationEmitter {
 }
 ```
 
+#### Quick Setup
+
+1. **Install**
+
+   ```sh
+   npm install @sprucelabs/spruce-heartwood-utils
+   ```
+
+2. **Create an emitter** — one per component tree, stable across renders:
+
+   ```ts
+   import { SimpleEmitter } from '@sprucelabs/spruce-heartwood-utils'
+
+   const emitter = useMemo(() => new SimpleEmitter(), [])
+   ```
+
+3. **Wire to components and emit events** — pass the emitter to `Sizer` and/or `DelayedPlacer`, then signal layout changes:
+
+   ```ts
+   // After a React render cycle completes:
+   await emitter.emit('did-render')
+
+   // After a viewport resize:
+   await emitter.emit('did-resize')
+   ```
+
 **Events:**
 
 | Event | Who listens | Who emits | Meaning |
@@ -944,6 +970,44 @@ return <h1 ref={ref} className="your-heading hidden">Title</h1>
 
 Wraps children in a div whose `height` is set via inline style to match the measured height of its content. Listens to `did-render` and `did-resize` events so it resizes whenever layout changes — enabling smooth CSS height transitions on content that would otherwise be `height: auto`. Emits `did-resize-content` so `DelayedPlacer` can re-place after a height change.
 
+#### Quick Setup
+
+1. **Install and add the required CSS**
+
+   ```sh
+   npm install @sprucelabs/spruce-heartwood-utils
+   ```
+
+   ```css
+   .sizer {
+       transition: height 500ms ease;
+       overflow: hidden;
+   }
+   ```
+
+   > Inside a Heartwood skill view this CSS is already provided — skip this step.
+
+2. **Wrap your content** — `shouldHideOverflow` clips children during the height transition:
+
+   ```tsx
+   import { Sizer, SimpleEmitter } from '@sprucelabs/spruce-heartwood-utils'
+
+   const emitter = useMemo(() => new SimpleEmitter(), [])
+
+   <Sizer emitter={emitter} shouldHideOverflow>
+       <YourContent />
+   </Sizer>
+   ```
+
+3. **Signal layout changes** — emit after renders and on viewport resize; Sizer measures content and updates `style.height` automatically:
+
+   ```ts
+   await emitter.emit('did-render')
+   await emitter.emit('did-resize')
+   ```
+
+   In tests, call `Settings.disableAnimations()` in `beforeEach` so height changes apply synchronously.
+
 #### Props (`SizerProps`)
 
 ```ts
@@ -1038,6 +1102,52 @@ Positions a child element to match the location of its in-flow placeholder. Wrap
 
 When `isEnabled={false}`, children render inline with no wrapper.
 
+#### Quick Setup
+
+1. **Install and add the required CSS**
+
+   ```sh
+   npm install @sprucelabs/spruce-heartwood-utils
+   ```
+
+   ```css
+   .placer { position: relative; }
+   .placer > * { position: absolute; }
+   ```
+
+   > Inside a Heartwood skill view this CSS is already provided — skip this step.
+
+2. **Wrap your content** — `isEnabled`, `className`, and `isFocused` are all required:
+
+   ```tsx
+   import { DelayedPlacer, SimpleEmitter } from '@sprucelabs/spruce-heartwood-utils'
+
+   const emitter = useMemo(() => new SimpleEmitter(), [])
+
+   <DelayedPlacer
+       className="placer__card"
+       isEnabled={true}
+       emitter={emitter}
+       isFocused={() => true}
+   >
+       <YourCard />
+   </DelayedPlacer>
+   ```
+
+   Pass `() => true` for `isFocused` when using outside Heartwood — placement is skipped when this returns false.
+
+3. **Share the emitter with `Sizer`** when they are siblings so height changes automatically trigger re-placement:
+
+   ```tsx
+   <DelayedPlacer className="placer__card" isEnabled emitter={emitter} isFocused={isFocused}>
+       <Sizer emitter={emitter} shouldHideOverflow>
+           <YourContent />
+       </Sizer>
+   </DelayedPlacer>
+   ```
+
+   `DelayedPlacer` emits `did-place-cards` when placement is complete. Listen for it if you need to react after cards settle.
+
 #### Props (`DelayedPlacerProps`)
 
 ```ts

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@sprucelabs/spruce-heartwood-utils",
 	"description": "Heartwood Utilities",
-	"version": "38.17.3",
+	"version": "38.17.4",
 	"skill": {
 		"namespace": "heartwood"
 	},