@sprucelabs/spruce-heartwood-utils 38.16.2 → 38.17.0

package/build/esm/index-module.d.ts

@@ -13,3 +13,5 @@ export { default as AutoLogoutPlugin } from './plugins/AutoLogoutViewPlugin';
 export type { AutoLogoutViewPlugin } from './plugins/AutoLogoutViewPlugin';
 export { default as SpyAutoLogoutPlugin } from './plugins/SpyAutoLogoutViewPlugin';
 export * from './components/animation';
+export { default as SkillViewEmitter } from './app/SkillViewEmitter';
+export type { SkillViewEventContract, SkillViewEvents, SkillViewEmitPayloads, SkillViewEmitter as SkillViewEmitterType, } from './app/SkillViewEmitter';

package/build/esm/index-module.js

@@ -9,3 +9,4 @@ export { default as loadActiveThemeForOrg } from './theming/loadActiveThemeForOr
 export { default as AutoLogoutPlugin } from './plugins/AutoLogoutViewPlugin.js';
 export { default as SpyAutoLogoutPlugin } from './plugins/SpyAutoLogoutViewPlugin.js';
 export * from './components/animation/index.js';
+export { default as SkillViewEmitter } from './app/SkillViewEmitter.js';

package/build/index-module.d.ts

@@ -13,3 +13,5 @@ export { default as AutoLogoutPlugin } from './plugins/AutoLogoutViewPlugin';
 export type { AutoLogoutViewPlugin } from './plugins/AutoLogoutViewPlugin';
 export { default as SpyAutoLogoutPlugin } from './plugins/SpyAutoLogoutViewPlugin';
 export * from './components/animation';
+export { default as SkillViewEmitter } from './app/SkillViewEmitter';
+export type { SkillViewEventContract, SkillViewEvents, SkillViewEmitPayloads, SkillViewEmitter as SkillViewEmitterType, } from './app/SkillViewEmitter';

package/build/index-module.js

@@ -17,7 +17,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SpyAutoLogoutPlugin = exports.AutoLogoutPlugin = exports.loadActiveThemeForOrg = exports.MockRemoteViewControllerFactory = exports.fakeGetViews = exports.remoteVcAssert = exports.CardRegistrar = exports.RemoteViewControllerFactoryImpl = void 0;
+exports.SkillViewEmitter = exports.SpyAutoLogoutPlugin = exports.AutoLogoutPlugin = exports.loadActiveThemeForOrg = exports.MockRemoteViewControllerFactory = exports.fakeGetViews = exports.remoteVcAssert = exports.CardRegistrar = exports.RemoteViewControllerFactoryImpl = void 0;
 var RemoteViewControllerFactory_1 = require("./views/RemoteViewControllerFactory");
 Object.defineProperty(exports, "RemoteViewControllerFactoryImpl", { enumerable: true, get: function () { return __importDefault(RemoteViewControllerFactory_1).default; } });
 __exportStar(require("./views/RemoteViewControllerFactory"), exports);
@@ -37,4 +37,6 @@ Object.defineProperty(exports, "AutoLogoutPlugin", { enumerable: true, get: func
 var SpyAutoLogoutViewPlugin_1 = require("./plugins/SpyAutoLogoutViewPlugin");
 Object.defineProperty(exports, "SpyAutoLogoutPlugin", { enumerable: true, get: function () { return __importDefault(SpyAutoLogoutViewPlugin_1).default; } });
 __exportStar(require("./components/animation"), exports);
+var SkillViewEmitter_1 = require("./app/SkillViewEmitter");
+Object.defineProperty(exports, "SkillViewEmitter", { enumerable: true, get: function () { return __importDefault(SkillViewEmitter_1).default; } });
 //# sourceMappingURL=index-module.js.map

package/docs/animation/README.md

@@ -1,8 +1,6 @@
 # Animation Utilities — Complete Reference
 
-Exported from `@sprucelabs/spruce-heartwood-utils` via `src/index-module.ts → src/components/animation/index.ts`.
-
-These utilities let third-party consumers use Heartwood's animation and layout primitives without depending on internal Spruce types (`AppEngine`, `SkillViewEmitter`).
+These utilities let third-party consumers use Heartwood's animation and layout primitives. Both `SkillViewEmitter` and `SimpleEmitter` are exported from the package — no need to build your own event bus.
 
 ---
 
@@ -34,6 +32,8 @@ import {
     stopQueue,
     // Components
     Sizer, DelayedPlacer,
+    // Emitters — pick one (see AnimationEmitter section)
+    SkillViewEmitter, SimpleEmitter,
     // Utilities
     sizeUtil, Settings,
     // Types
@@ -45,7 +45,37 @@ import {
 
 ## Required CSS
 
-**All of this CSS is provided by Heartwood's stylesheet** (`public/stylesheets/main.css`). If you are consuming these utilities inside a Heartwood skill view, no extra CSS setup is needed. If you are using them in a standalone project, you must supply the rules below yourself.
+You must include the rules below in your stylesheet. They are **not bundled with the package** — they come from Heartwood's `public/stylesheets/main.css`, which is not shipped as part of this module.
+
+### Copy-paste starter block
+
+```css
+/* Hidden state — required for queueShow / showRightAway / hideRightAway */
+.hidden {
+  opacity: 0 !important;
+  transform: translate(0, 10px);
+}
+
+/* Transition on your animated elements — required for smooth animation */
+.my-animated-element {
+  transition: opacity 0.5s ease, transform 0.5s ease;
+}
+
+/* Sizer height transitions — required for the Sizer component */
+.sizer {
+  transition: all 0.5s;
+}
+body.portrait .sizer {
+  transition: all 1s;
+}
+
+/* Absolute positioning for DelayedPlacer children — required */
+.being_placed {
+  position: absolute;
+}
+```
+
+Replace `.my-animated-element` with your own class name(s). The remaining rules must appear verbatim.
 
 ---
 
@@ -53,13 +83,12 @@ import {
 
 Every element you pass to `queueShow`, `showRightAway`, or `hideRightAway` must start with `class="... hidden"`. The queue works by toggling this class on and off.
 
-**Compiled rule from Heartwood:**
+**Rule from Heartwood (`public/stylesheets/main.css`):**
 
 ```css
 .hidden {
   opacity: 0 !important;
   transform: translate(0, 10px);
-  transition: all 0.5s
 }
 ```
 
@@ -274,35 +303,6 @@ The `.message.hide` state is separate:
 
 ---
 
-### Minimal CSS for standalone use
-
-If you are using these utilities completely outside of a Heartwood skill view, here is the minimum CSS needed:
-
-```css
-/* 1. Hidden state — required for queueShow to work */
-.hidden {
-  opacity: 0 !important;
-  transform: translate(0, 10px);
-}
-
-/* 2. Transition on your elements — required for animation (not just snap) */
-.my-animated-element {
-  transition: opacity 0.5s ease, transform 0.5s ease;
-}
-
-/* 3. Sizer height transitions — required for Sizer component */
-.sizer {
-  transition: all 0.5s;
-}
-
-/* 4. Absolute positioning for DelayedPlacer children — required */
-.being_placed {
-  position: absolute;
-}
-```
-
----
-
 ## System Architecture
 
 Three independent systems coordinate through a shared `AnimationEmitter`:
@@ -355,28 +355,28 @@ interface AnimationEmitter {
 | `did-change-orientation` | your app | DelayedPlacer | Portrait ↔ landscape switch |
 | `did-place-cards` | DelayedPlacer | your app (optional) | Placement complete |
 
-### Minimal implementation
+### Getting an emitter instance
+
+Two emitters are exported from the package — choose based on your needs:
+
+**`SkillViewEmitter`** — full-featured mercury-style emitter, recommended when integrating with a Heartwood skill view:
 
 ```ts
-class SimpleEmitter implements AnimationEmitter {
-    private listeners: Record<string, Array<() => void>> = {}
+import { SkillViewEmitter } from '@sprucelabs/spruce-heartwood-utils'
 
-    on(event: string, handler: () => void): void {
-        (this.listeners[event] ??= []).push(handler)
-    }
+const emitter = SkillViewEmitter.getInstance()
+```
 
-    off(event: string, handler: () => void): void {
-        this.listeners[event] = (this.listeners[event] ?? []).filter(h => h !== handler)
-    }
+**`SimpleEmitter`** — lightweight in-memory emitter, suitable for standalone components, isolated tests, or any context that doesn't need the full mercury stack:
 
-    emit(event: string): void {
-        for (const h of this.listeners[event] ?? []) h()
-    }
-}
+```ts
+import { SimpleEmitter } from '@sprucelabs/spruce-heartwood-utils'
 
 const emitter = new SimpleEmitter()
 ```
 
+Either way, use a single instance shared across all components that need to coordinate (Sizer, DelayedPlacer, your resize/render wiring).
+
 ### Wiring the emitter to window resize
 
 ```ts
@@ -416,7 +416,7 @@ emitter.off('did-resize', () => this.doSomething())  // does nothing
 ```tsx
 // They MUST share an emitter instance to coordinate.
 // Sizer emits 'did-resize-content' → DelayedPlacer re-places.
-const [emitter] = useState(() => new SimpleEmitter())
+const emitter = SkillViewEmitter.getInstance()
 
 <Sizer emitter={emitter}>
     <DelayedPlacer emitter={emitter} isEnabled={true} className="placer__card" isFocused={() => true}>
@@ -437,15 +437,13 @@ Controls whether animations run and what their duration is. **Always call `Setti
 Settings.disableAnimations()          // sets animationDuration to 0, queue runs synchronously
 Settings.getIsAnimationEnabled()      // → boolean
 Settings.animationDuration            // → 0 | 500 | 1000 (landscape / portrait)
-Settings.shouldExportSwiper           // → boolean (reads process.env.EXPORT_SWIPER)
 ```
 
 ### Disabling animations in tests
 
-Both Heartwood test base classes do this. Without it, tests rely on real timers and become flaky.
+Call this in your test setup. Without it, tests rely on real timers and become flaky.
 
 ```ts
-// AbstractHeartwoodTest.ts — base class for all Heartwood tests
 protected async beforeEach() {
     await super.beforeEach()
     Settings.disableAnimations()
@@ -458,22 +456,6 @@ protected async afterEach() {
 }
 ```
 
-```ts
-// ButtonGroup.test.tsx — standalone test file
-protected async beforeEach() {
-    await super.beforeEach()
-    Settings.disableAnimations()
-    this.engine = AppEngine.getInstance()
-    await this.engine.reset()
-    // ...
-}
-
-protected async afterEach() {
-    await super.afterEach()
-    stopQueue()
-}
-```
-
 ### Effect on the queue
 
 ```ts
@@ -507,6 +489,8 @@ queueShow(someRef)  // fires instantly, no setTimeout
 
 A singleton FIFO queue. All consumers share one queue. Items are dequeued every 40ms (default) by toggling the `hidden` CSS class on DOM elements.
 
+> **Elements need a CSS `transition` to animate.** The queue only toggles the `hidden` class — the browser's CSS engine drives the visual animation. Without a `transition` on the element, show and hide operations still work but snap instantly with no fade or movement. See the [Required CSS](#required-css) section for the rules to include.
+
 ### When to use which function
 
 | Situation | Use |
@@ -1055,15 +1039,6 @@ hideRightAway(this.panelRef)
 Clears the interval and marks the queue as stopped. Does **not** drain the queue — pending items are abandoned. Always call this in test teardown.
 
 ```ts
-// AbstractHeartwoodTest.ts — every Heartwood test calls this in afterEach
-protected async afterEach() {
-    await super.afterEach()
-    await this.components.afterEach()
-    await AppEngine.reset()
-    stopQueue()
-}
-
-// ButtonGroup.test.tsx — standalone test teardown
 protected async afterEach() {
     await super.afterEach()
     stopQueue()
@@ -1282,7 +1257,7 @@ async function handleSizeChange(props: any) {
 
 ```tsx
 // When the parent tells Sizer the layout changed, Sizer re-measures:
-const [emitter] = useState(() => new SimpleEmitter())
+const emitter = SkillViewEmitter.getInstance()
 
 useEffect(() => {
     // After every React render, notify Sizer to re-check its height
@@ -1393,39 +1368,32 @@ placeRightAway()
   6. setTimeout(() => emitter.emit('did-place-cards'), 100)
 ```
 
-### Pattern 1 — Card with optional absolute positioning
-
-The only usage in Heartwood. `isDelayedPlacerEnabled` comes from the card's view controller.
+### Pattern 1 — Component with optional absolute positioning
 
 ```tsx
-// Card.tsx — wraps every card; isEnabled defaults to false
 private delayedPlacerRef = React.createRef<React.ElementRef<typeof DelayedPlacer>>()
+private emitter = SkillViewEmitter.getInstance()
 
 private handleRender() {
-    this.setRenderingClass(true)
-
     clearTimeout(this.renderTimeout)
     this.renderTimeout = setTimeout(() => {
         // Force re-placement after content changes
         this.delayedPlacerRef.current?.placeRightAway()
         this.props.onRender?.()
-        this.renderingClassTimeout = setTimeout(() => {
-            this.setRenderingClass(false)
-            this.setupClassNames()
-        }, Settings.animationDuration)
     }, 50)
 }
 
 render() {
+    const { isFloating } = this.props
     return (
         <DelayedPlacer
             className="placer__card"
-            isEnabled={isDelayedPlacerEnabled ?? false}
-            emitter={this.emitter}          // engine.getEmitter()
+            isEnabled={isFloating ?? false}
+            emitter={this.emitter}
             ref={this.delayedPlacerRef}
-            isFocused={this.props.isFocusedHandler ?? (() => true)}
+            isFocused={this.props.isFocused ?? (() => true)}
         >
-            {card}
+            {this.props.children}
         </DelayedPlacer>
     )
 }
@@ -1594,11 +1562,8 @@ private sizeMyselfToCorrectHeight() {
 Since `sizeUtil` is a plain object, methods can be replaced directly:
 
 ```ts
-// ToolBelt.test.ts — stub viewport width for layout-dependent logic
+// Stub viewport width for layout-dependent logic:
 sizeUtil.bodyWidth = () => 1200
-this.setApp(AppRenderingToolBelt)
-await this.pushSvcWithNoToolBeltDeclared()
-this.assertRenderingTool(activeApp.toolId)
 ```
 
 Restore after test if needed (or rely on test module isolation).
@@ -1670,21 +1635,14 @@ DelayedPlacer.sizeEverything() fires
 ### Setting up all three systems together
 
 ```tsx
-import React, { useEffect, useRef, useState } from 'react'
+import React, { useEffect, useRef } from 'react'
 import {
-    Sizer, DelayedPlacer, AnimationEmitter,
+    Sizer, DelayedPlacer, SkillViewEmitter,
     queueShow, stopQueue, Settings
 } from '@sprucelabs/spruce-heartwood-utils'
 
-class SimpleEmitter implements AnimationEmitter {
-    private listeners: Record<string, Array<() => void>> = {}
-    on(event: string, h: () => void) { (this.listeners[event] ??= []).push(h) }
-    off(event: string, h: () => void) { this.listeners[event] = (this.listeners[event] ?? []).filter(x => x !== h) }
-    emit(event: string) { for (const h of this.listeners[event] ?? []) h() }
-}
-
 function MyPanel({ isFloating }: { isFloating: boolean }) {
-    const [emitter] = useState(() => new SimpleEmitter())
+    const emitter = SkillViewEmitter.getInstance()
     const delayedPlacerRef = useRef<any>(null)
 
     // Wire React renders → emitter

package/package.json

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