@sprucelabs/spruce-heartwood-utils 38.17.1 → 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,
@@ -576,26 +603,43 @@ import {
 
 ### Required CSS
 
+> **⚠ Silent failure warning:** If CSS transitions are missing, animations will not play and no error will be thrown. Elements will simply snap instantly between states with no visual feedback. Every class listed below requires its own `transition` declaration — the system provides none.
+
 **Inside a Heartwood skill view:** all required CSS is already provided by Heartwood's stylesheet. No extra setup needed.
 
-**Outside Heartwood (standalone use):** supply the following rules yourself.
+**Outside Heartwood (standalone use):** supply every rule below yourself. Missing any one of them causes that animation to silently skip.
 
-The `queueShow` system toggles a `hidden` CSS class. Elements must start with `hidden` in their `className` and define their own transition:
+---
+
+#### `queueShow` / `queueHide` — fade + slide transitions
+
+`queueShow` removes the `hidden` class; `queueHide` adds it back. The `hidden` class sets the hidden state (opacity, position offset, pointer-events). **The transition must be declared on the element itself, not on `.hidden`** — if the transition is on `.hidden` it is removed at the same moment the class is removed and the browser never interpolates.
 
 ```css
+/* Hidden state — sets opacity, nudge, and pointer-events */
 .hidden {
     opacity: 0;
     transform: translateY(4px);
     pointer-events: none;
 }
 
-/* Transition goes on the element, not .hidden */
+/* Transition on the element — this is what the browser animates */
 .your-element {
     transition: opacity 200ms ease, transform 200ms ease;
 }
 ```
 
-`Sizer` uses `.sizer` and `.sizer__inner`:
+Elements must also start with `hidden` in their `className` so they are invisible until `queueShow` fires:
+
+```tsx
+<div className="your-element hidden" ref={(ref) => { ref && queueShow(ref) }} />
+```
+
+---
+
+#### `Sizer` — animated height
+
+`Sizer` measures its content and writes `style.height` directly. The CSS `transition` on `.sizer` is what makes the height change animate smoothly. Without it the height jumps instantly.
 
 ```css
 .sizer {
@@ -604,7 +648,11 @@ The `queueShow` system toggles a `hidden` CSS class. Elements must start with `h
 }
 ```
 
-`DelayedPlacer` uses `.placer`. Its child must be `position: absolute`:
+---
+
+#### `DelayedPlacer` — absolute positioning
+
+`DelayedPlacer` writes `style.left` / `style.top` on the child. The `.placer` wrapper must be `position: relative` so the child's absolute coordinates are relative to it.
 
 ```css
 .placer {
@@ -615,6 +663,8 @@ The `queueShow` system toggles a `hidden` CSS class. Elements must start with `h
 }
 ```
 
+No transition is needed on `.placer` itself — placement jumps immediately to the measured position.
+
 ---
 
 ### System Architecture
@@ -639,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 {
@@ -811,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.
 
 ---
@@ -819,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.
 
 ---
@@ -851,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
@@ -883,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
@@ -893,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
@@ -991,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.
 
 ---
@@ -1075,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'
@@ -1116,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.1",
+	"version": "38.17.3",
 	"skill": {
 		"namespace": "heartwood"
 	},