@sprucelabs/spruce-heartwood-utils 38.17.2 → 38.17.4

package/README.md

@@ -4,6 +4,16 @@ Tools for building Spruce skills that integrate with Heartwood — remote card l
 
 ---
 
+## Installation
+
+```sh
+npm install @sprucelabs/spruce-heartwood-utils
+```
+
+This package is designed for use inside a Spruce skill. It expects `@sprucelabs/heartwood-view-controllers`, `@sprucelabs/mercury-client`, and React to already be present in your project — they are pulled in transitively when you scaffold a Heartwood skill.
+
+---
+
 ## Table of Contents
 
 1. [Remote View Controllers](#remote-view-controllers)
@@ -269,8 +279,15 @@ plugin.disableAutoLogout()     // cancel a pending auto-logout
 Use this type when you want to reference the plugin without coupling to the concrete class — for example, when declaring a field that holds either the real plugin or a spy:
 
 ```ts
-import { AutoLogoutViewPlugin } from '@sprucelabs/spruce-heartwood-utils'
+import type { AutoLogoutViewPlugin } from '@sprucelabs/spruce-heartwood-utils'
+
+// Field declaration — works with both AutoLogoutPlugin and SpyAutoLogoutPlugin:
+private autoLogoutPlugin: AutoLogoutViewPlugin
+```
 
+The interface shape:
+
+```ts
 interface AutoLogoutViewPlugin extends ViewControllerPlugin {
     enableAutoLogout(durationSec: number): void
     disableAutoLogout(): void
@@ -397,9 +414,17 @@ import { fakeGetViews } from '@sprucelabs/spruce-heartwood-utils'
 
 // Stub two remote views:
 await fakeGetViews.fakeGetViews(['your-skill.card-a', 'your-skill.card-b'])
+```
+
+The optional second argument is the name of a method to instrument on each stub VC. When provided, each stub controller gets a function at that name that records whether it was called and what arguments it received:
 
-// Stub a view with a tracked method — stub exposes wasHit and passedParams:
+```ts
 await fakeGetViews.fakeGetViews(['your-skill.card'], 'load')
+
+// After your code triggers the stub:
+const stub = /* get rendered card controller from your vc */
+assert.isTrue(stub.wasHit)
+assert.isEqualDeep(stub.passedParams, [expectedArgs])
 ```
 
 > **Note:** The export is the `heartwoodEventFaker` object. Call it as `fakeGetViews.fakeGetViews(...)`.
@@ -565,6 +590,8 @@ import {
     Sizer, DelayedPlacer,
     // Utilities
     sizeUtil, Settings,
+    // Emitter — pass to Sizer and DelayedPlacer to coordinate layout events
+    SimpleEmitter,
     // Types
     AnimationEmitter,
     SizerProps,
@@ -662,7 +689,17 @@ Pass the **same emitter instance** to `Sizer` and `DelayedPlacer` when they are
 
 ### AnimationEmitter
 
-The interface `Sizer` and `DelayedPlacer` use to communicate layout-change events. You implement this and pass it as the `emitter` prop to coordinate components.
+The interface `Sizer` and `DelayedPlacer` use to communicate layout-change events. Pass an instance as the `emitter` prop to coordinate components. The package exports `SimpleEmitter` — a lightweight in-memory implementation you can use directly:
+
+```ts
+import { SimpleEmitter } from '@sprucelabs/spruce-heartwood-utils'
+
+const emitter = new SimpleEmitter()
+```
+
+`SimpleEmitter` implements all three methods (`on`, `off`, `emit`) with a plain listener map. Use it for standalone components, isolated tests, or any context where a full Heartwood emitter is not available.
+
+The `AnimationEmitter` interface, for reference:
 
 ```ts
 interface AnimationEmitter {
@@ -672,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 |
@@ -834,6 +897,13 @@ enqueue(() => this.handleReady())
 
 Cancels a pending hide and queues a show for elements toggled back before their hide ran.
 
+```ts
+function clearPendingHideAndQueueShow(
+    refOrNode: React.RefObject<HTMLElement> | HTMLElement,
+    delay?: number   // default: 40ms
+): void
+```
+
 > Prefer `showRightAway()` for most toggle cases.
 
 ---
@@ -842,6 +912,13 @@ Cancels a pending hide and queues a show for elements toggled back before their
 
 Cancels a pending show and queues a hide.
 
+```ts
+function clearPendingShowAndQueueHide(
+    refOrNode: React.RefObject<HTMLElement> | HTMLElement,
+    delay?: number   // default: 40ms
+): void
+```
+
 > Prefer `hideRightAway()` for most toggle cases.
 
 ---
@@ -874,18 +951,63 @@ return <div ref={ref} className="your-panel hidden">...</div>
 
 #### `useShowNow(ref, delay?)` — React Hook
 
-Like `useQueueShow` but places itself at the front of the queue on every render.
+Like `useQueueShow` but places itself at the front of the queue on every render. Use for elements that must appear before any other queued items — such as a primary heading that should always be visible before supporting content fades in.
 
 ```ts
 function useShowNow(ref: React.RefObject<HTMLElement>, delay?: number): void
 ```
 
+```tsx
+const ref = useRef<HTMLHeadingElement>(null)
+useShowNow(ref)
+
+return <h1 ref={ref} className="your-heading hidden">Title</h1>
+```
+
 ---
 
 ### Sizer — Animated Height Container
 
 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
@@ -906,6 +1028,11 @@ interface SizerProps {
     // overflow is always visible (adds force-show-overflow class).
     shouldHideOverflow?: boolean
 
+    // Debounce delay in ms before each resize measurement fires. Default: 250ms.
+    // Lower values make Sizer react faster to content changes; useful when
+    // content updates quickly and you want tighter animation timing.
+    sizerDelayMs?: number
+
     // Event emitter. Without one, Sizer only resizes on React re-renders,
     // not in response to external layout events.
     emitter?: AnimationEmitter
@@ -916,6 +1043,8 @@ interface SizerProps {
 
 ```ts
 sizer.current?.resize(): boolean    // measure and apply new height; returns true if it changed
+sizer.current?.showOverflow(): void // temporarily allow overflow (e.g. while a dropdown inside is open)
+sizer.current?.hideOverflow(): void // re-apply overflow: hidden
 ```
 
 #### Emitter Events
@@ -973,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
@@ -1014,28 +1189,34 @@ delayedPlacer.current?.placeRightAway(): void  // re-measure and re-place immedi
 #### Usage
 
 ```tsx
-const placerRef = React.createRef<DelayedPlacer>()
+import React, { useRef, useMemo } from 'react'
+import { DelayedPlacer, SimpleEmitter } from '@sprucelabs/spruce-heartwood-utils'
 
-// Re-place after content changes:
-private onContentChange() {
-    setTimeout(() => { placerRef.current?.placeRightAway() }, 50)
-}
+function YourPanel({ isFocused }: { isFocused: () => boolean }) {
+    const placerRef = useRef<React.ElementRef<typeof DelayedPlacer>>(null)
+    const emitter = useMemo(() => new SimpleEmitter(), [])
 
-render() {
     return (
         <DelayedPlacer
-            className="placer__card"
-            isEnabled={this.isPlacementEnabled}
-            emitter={this.emitter}
+            className="placer__panel"
+            isEnabled={true}
+            emitter={emitter}
             ref={placerRef}
-            isFocused={() => true}
+            isFocused={isFocused}
         >
-            {yourCard}
+            {yourContent}
         </DelayedPlacer>
     )
 }
 ```
 
+When you need to re-place after a content change that happens outside React state:
+
+```ts
+// Trigger placement immediately, bypassing the debounce:
+placerRef.current?.placeRightAway()
+```
+
 > `isEnabled`, `className`, and `isFocused` are all required. The child must be `position: absolute` in CSS for placement to have visual effect.
 
 ---
@@ -1098,6 +1279,7 @@ sizeUtil.bodyWidth = () => 1200
 A complete example showing all three systems working together in a card component:
 
 ```tsx
+import React, { useMemo } from 'react'
 import {
     Sizer, DelayedPlacer, queueShow, Settings, SimpleEmitter,
 } from '@sprucelabs/spruce-heartwood-utils'
@@ -1139,6 +1321,9 @@ queueShow removes .hidden from each element with a 40ms stagger
 **Test setup for animation components:**
 
 ```ts
+import { Settings, stopQueue } from '@sprucelabs/spruce-heartwood-utils'
+import { skillViewState } from '@sprucelabs/spruce-heartwood-utils/build/components/skillViews/skillViewState'
+
 protected async beforeEach() {
     Settings.disableAnimations()
     skillViewState.isFullScreen = false

package/package.json

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