@sprucelabs/spruce-heartwood-utils 38.17.2 → 38.17.3

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 {
@@ -834,6 +871,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 +886,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,12 +925,19 @@ 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
@@ -906,6 +964,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 +979,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
@@ -1014,28 +1079,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 +1169,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 +1211,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.3",
 	"skill": {
 		"namespace": "heartwood"
 	},