@sprucelabs/spruce-heartwood-utils 38.17.0 → 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
@@ -659,28 +682,6 @@ interface AnimationEmitter {
 | `did-change-orientation` | DelayedPlacer | your code | Portrait ↔ landscape switch |
 | `did-place-cards` | your listeners | DelayedPlacer | Placement calculation finished |
 
-**Minimal implementation:**
-
-```ts
-class SimpleEmitter implements AnimationEmitter {
-    private listeners: Record<string, Array<() => void>> = {}
-
-    on(event: string, handler: () => void): void {
-        ;(this.listeners[event] ??= []).push(handler)
-    }
-
-    off(event: string, handler: () => void): void {
-        this.listeners[event] = (this.listeners[event] ?? []).filter(
-            (h) => h !== handler
-        )
-    }
-
-    emit(event: string): void {
-        for (const h of this.listeners[event] ?? []) h()
-    }
-}
-```
-
 > Pass the **same function reference** to `on` and `off`. Inline arrow functions cannot be removed with `off`.
 
 ---
@@ -928,6 +929,8 @@ sizer.current?.resize(): boolean    // measure and apply new height; returns tru
 #### Usage
 
 ```tsx
+import { Sizer, SimpleEmitter } from '@sprucelabs/spruce-heartwood-utils'
+
 // Simplest — just clip overflow during height transition:
 <Sizer shouldHideOverflow>
     {isExpanded && <YourExpandableContent />}
@@ -1096,18 +1099,9 @@ A complete example showing all three systems working together in a card componen
 
 ```tsx
 import {
-    Sizer, DelayedPlacer, queueShow, Settings, AnimationEmitter,
+    Sizer, DelayedPlacer, queueShow, Settings, SimpleEmitter,
 } from '@sprucelabs/spruce-heartwood-utils'
 
-class SimpleEmitter implements AnimationEmitter {
-    private listeners: Record<string, Array<() => void>> = {}
-    on(event: string, handler: () => void) { (this.listeners[event] ??= []).push(handler) }
-    off(event: string, handler: () => void) {
-        this.listeners[event] = (this.listeners[event] ?? []).filter(h => h !== handler)
-    }
-    emit(event: string) { for (const h of this.listeners[event] ?? []) h() }
-}
-
 function YourCard({ isPlaced, isFocused }: { isPlaced: boolean; isFocused: () => boolean }) {
     const emitter = useMemo(() => new SimpleEmitter(), [])
 

package/build/components/animation/SimpleEmitter.d.ts

@@ -0,0 +1,7 @@
+import { AnimationEmitter } from './types';
+export default class SimpleEmitter implements AnimationEmitter {
+    private listeners;
+    on(event: string, handler: () => void): void;
+    off(event: string, handler: () => void): void;
+    emit(event: string): void;
+}

package/build/components/animation/SimpleEmitter.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+class SimpleEmitter {
+    constructor() {
+        this.listeners = {};
+    }
+    on(event, handler) {
+        var _a;
+        ;
+        ((_a = this.listeners)[event] ?? (_a[event] = [])).push(handler);
+    }
+    off(event, handler) {
+        this.listeners[event] = (this.listeners[event] ?? []).filter((h) => h !== handler);
+    }
+    emit(event) {
+        for (const h of this.listeners[event] ?? []) {
+            h();
+        }
+    }
+}
+exports.default = SimpleEmitter;
+//# sourceMappingURL=SimpleEmitter.js.map

package/build/components/animation/index.d.ts

@@ -6,3 +6,4 @@ export type { DelayedPlacerProps } from './DelayedPlacerExport';
 export { default as sizeUtil } from '../calendars/utils/size.utility';
 export { default as Settings } from '../Settings';
 export type { AnimationEmitter } from './types';
+export { default as SimpleEmitter } from './SimpleEmitter';

package/build/components/animation/index.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Settings = exports.sizeUtil = exports.DelayedPlacer = exports.Sizer = exports.stopQueue = exports.clearPendingShowAndQueueHide = exports.clearPendingHideAndQueueShow = exports.callbackImmediately = exports.queueCallback = exports.queueHide = exports.queueShow = exports.hideRightAway = exports.showRightAway = exports.useShowNow = exports.useQueueShow = void 0;
+exports.SimpleEmitter = exports.Settings = exports.sizeUtil = exports.DelayedPlacer = exports.Sizer = exports.stopQueue = exports.clearPendingShowAndQueueHide = exports.clearPendingHideAndQueueShow = exports.callbackImmediately = exports.queueCallback = exports.queueHide = exports.queueShow = exports.hideRightAway = exports.showRightAway = exports.useShowNow = exports.useQueueShow = void 0;
 // Queue system — all functions and hooks
 var queueShow_1 = require("../../hooks/queueShow");
 Object.defineProperty(exports, "useQueueShow", { enumerable: true, get: function () { return queueShow_1.useQueueShow; } });
@@ -27,4 +27,6 @@ var size_utility_1 = require("../calendars/utils/size.utility");
 Object.defineProperty(exports, "sizeUtil", { enumerable: true, get: function () { return __importDefault(size_utility_1).default; } });
 var Settings_1 = require("../Settings");
 Object.defineProperty(exports, "Settings", { enumerable: true, get: function () { return __importDefault(Settings_1).default; } });
+var SimpleEmitter_1 = require("./SimpleEmitter");
+Object.defineProperty(exports, "SimpleEmitter", { enumerable: true, get: function () { return __importDefault(SimpleEmitter_1).default; } });
 //# sourceMappingURL=index.js.map

package/build/esm/components/animation/SimpleEmitter.d.ts

@@ -0,0 +1,7 @@
+import { AnimationEmitter } from './types';
+export default class SimpleEmitter implements AnimationEmitter {
+    private listeners;
+    on(event: string, handler: () => void): void;
+    off(event: string, handler: () => void): void;
+    emit(event: string): void;
+}

package/build/esm/components/animation/SimpleEmitter.js

@@ -0,0 +1,21 @@
+export default class SimpleEmitter {
+    constructor() {
+        this.listeners = {};
+    }
+    on(event, handler) {
+        var _a;
+        var _b;
+        ;
+        ((_a = (_b = this.listeners)[event]) !== null && _a !== void 0 ? _a : (_b[event] = [])).push(handler);
+    }
+    off(event, handler) {
+        var _a;
+        this.listeners[event] = ((_a = this.listeners[event]) !== null && _a !== void 0 ? _a : []).filter((h) => h !== handler);
+    }
+    emit(event) {
+        var _a;
+        for (const h of (_a = this.listeners[event]) !== null && _a !== void 0 ? _a : []) {
+            h();
+        }
+    }
+}

package/build/esm/components/animation/index.d.ts

@@ -6,3 +6,4 @@ export type { DelayedPlacerProps } from './DelayedPlacerExport';
 export { default as sizeUtil } from '../calendars/utils/size.utility';
 export { default as Settings } from '../Settings';
 export type { AnimationEmitter } from './types';
+export { default as SimpleEmitter } from './SimpleEmitter';

package/build/esm/components/animation/index.js

@@ -6,3 +6,4 @@ export { default as DelayedPlacer } from './DelayedPlacerExport.js';
 // Utilities (useful for consumers who want to measure DOM nodes)
 export { default as sizeUtil } from '../calendars/utils/size.utility.js';
 export { default as Settings } from '../Settings.js';
+export { default as SimpleEmitter } from './SimpleEmitter.js';

package/docs/animation/animation-emitter.md

@@ -29,33 +29,18 @@ All three methods accept a plain string event name and return either `void` or `
 | `did-change-orientation` | DelayedPlacer | Device orientation handler | Portrait ↔ landscape switch |
 | `did-place-cards` | (external listeners) | DelayedPlacer | Placement calculation complete |
 
-## Implementing a Compatible Emitter
+## Using SimpleEmitter
 
-The interface is intentionally simple. Any Node-style EventEmitter or custom implementation works if it matches the signature:
+`SimpleEmitter` is exported from the package — import it directly instead of building your own:
 
 ```ts
-// Minimal implementation for standalone use:
-class SimpleEmitter implements AnimationEmitter {
-    private listeners: Record<string, Array<() => void>> = {}
-
-    on(event: string, handler: () => void): void {
-        ;(this.listeners[event] ??= []).push(handler)
-    }
-
-    off(event: string, handler: () => void): void {
-        this.listeners[event] = (this.listeners[event] ?? []).filter(
-            (h) => h !== handler
-        )
-    }
-
-    emit(event: string): void {
-        for (const h of this.listeners[event] ?? []) {
-            h()
-        }
-    }
-}
+import { SimpleEmitter } from '@sprucelabs/spruce-heartwood-utils'
+
+const emitter = new SimpleEmitter()
 ```
 
+It implements `AnimationEmitter` with a plain in-memory listener map. Use it for standalone components, isolated tests, or any context where the full `SkillViewEmitter` is unnecessary.
+
 ## Noop Emitter
 
 `SizerExport.tsx` defines and uses a noop emitter as the default when no emitter is passed:

package/docs/animation/sizer.md

@@ -104,7 +104,9 @@ handleSizing() (debounced at sizerDelayMs, default 250ms)
 ### With emitter — responds to external layout events
 
 ```tsx
-const [emitter] = useState(() => createMyEmitter())
+import { SimpleEmitter } from '@sprucelabs/spruce-heartwood-utils'
+
+const [emitter] = useState(() => new SimpleEmitter())
 
 <Sizer emitter={emitter} shouldStartAtZero>
     <MyContent />
@@ -114,6 +116,8 @@ const [emitter] = useState(() => createMyEmitter())
 ### With ref — manually drive resize on content change
 
 ```tsx
+import { SimpleEmitter } from '@sprucelabs/spruce-heartwood-utils'
+
 const emitter = useMemo(() => new SimpleEmitter(), [])
 const sizer = useRef<React.ElementRef<typeof Sizer>>(null)
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@sprucelabs/spruce-heartwood-utils",
 	"description": "Heartwood Utilities",
-	"version": "38.17.0",
+	"version": "38.17.2",
 	"skill": {
 		"namespace": "heartwood"
 	},
@@ -86,6 +86,10 @@
 		"build/components/animation/types.d.ts",
 		"build/esm/components/animation/types.js",
 		"build/esm/components/animation/types.d.ts",
+		"build/components/animation/SimpleEmitter.js",
+		"build/components/animation/SimpleEmitter.d.ts",
+		"build/esm/components/animation/SimpleEmitter.js",
+		"build/esm/components/animation/SimpleEmitter.d.ts",
 		"build/hooks/queueShow.js",
 		"build/hooks/queueShow.d.ts",
 		"build/esm/hooks/queueShow.js",