@sprucelabs/spruce-heartwood-utils 38.17.1 → 38.17.2

package/README.md

@@ -576,26 +576,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.
+
+---
+
+#### `queueShow` / `queueHide` — fade + slide transitions
 
-The `queueShow` system toggles a `hidden` CSS class. Elements must start with `hidden` in their `className` and define their own transition:
+`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 +621,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 +636,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

package/package.json

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