@sprucelabs/spruce-heartwood-utils 38.17.7 → 38.17.9

package/README.md

@@ -10,16 +10,20 @@ Heartwood integration toolkit for Spruce skills. Use this package to load remote
 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.
+```
+yarn add @sprucelabs/spruce-heartwood-utils
+```
+
+This package is designed for use inside a Spruce skill or a React application. 
 
 ---
 
 ## Project Pitch
 
-Building a Spruce experience usually means combining:
-- browser/runtime view infrastructure
-- test utilities for remote card/event flows
-- animation and layout primitives used in Heartwood views
+This module supports development in 2 ways.
+
+1. It provides first-party utilities for common tasks in Skill development — remote view controllers, card registration, theming, plugins, and test helpers.
+2. It offers animation and layout primitives for use in React.
 
 `@sprucelabs/spruce-heartwood-utils` packages those into one module with explicit entrypoints so you can keep browser bundles clean while still getting first-class testing helpers.
 
@@ -59,7 +63,6 @@ import {
     AutoLogoutPlugin,
     loadActiveThemeForOrg,
     Sizer,
-    SimpleEmitter,
 } from '@sprucelabs/spruce-heartwood-utils/web'
 ```
 
@@ -84,8 +87,6 @@ Use split imports so runtime code stays browser-safe while tests get all mocks/h
 import {
     CardRegistrar,
     RemoteViewControllerFactoryImpl,
-} from '@sprucelabs/spruce-heartwood-utils/web'
-import {
     remoteVcAssert,
     MockRemoteViewControllerFactory,
 } from '@sprucelabs/spruce-heartwood-utils/testing'
@@ -93,33 +94,6 @@ import {
 
 ---
 
-## Table of Contents
-
-1. [Project Pitch](#project-pitch)
-2. [What You Get](#what-you-get)
-3. [Import Paths](#import-paths)
-4. [Get Started](#get-started)
-5. [Remote View Controllers](#remote-view-controllers)
-6. [CardRegistrar](#cardregistrar)
-7. [Types](#types)
-8. [Theming](#theming)
-9. [Plugins](#plugins)
-10. [Test Utilities](#test-utilities)
-11. [Device & Layout Utilities](#device--layout-utilities)
-12. [Animation](#animation)
-   - [Quick Start](#quick-start)
-   - [Required CSS](#required-css)
-   - [System Architecture](#system-architecture)
-   - [AnimationEmitter](#animationemitter)
-   - [Settings](#settings)
-   - [queueShow — Show/Hide Queue](#queueshow--showhide-queue)
-   - [Sizer — Animated Height Container](#sizer--animated-height-container)
-   - [DelayedPlacer — Absolute Positioning](#delayedplacer--absolute-positioning)
-   - [sizeUtil — DOM Measurement](#sizeutil--dom-measurement)
-   - [How the Three Systems Coordinate](#how-the-three-systems-coordinate)
-
----
-
 ## Remote View Controllers
 
 When your skill needs to load and render cards that come from other skills at runtime, these are the types you work with. In tests, you swap in `MockRemoteViewControllerFactory` to control which cards appear without making real network calls.
@@ -675,7 +649,6 @@ import {
     // Utilities
     sizeUtil, Settings,
     // Emitter — pass to Sizer and DelayedPlacer to coordinate layout events
-    SimpleEmitter,
     // Types
     AnimationEmitter,
     SizerProps,
@@ -773,15 +746,15 @@ Pass the **same emitter instance** to `Sizer` and `DelayedPlacer` when they are
 
 ### AnimationEmitter
 
-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:
+The interface `Sizer` and `DelayedPlacer` use to communicate layout-change events. Pass an instance as the `emitter` prop to coordinate components. The package exports `SkillViewEmitter` for this:
 
 ```ts
-import { SimpleEmitter } from '@sprucelabs/spruce-heartwood-utils/web'
+import { SkillViewEmitter } from '@sprucelabs/spruce-heartwood-utils/web'
 
-const emitter = new SimpleEmitter()
+const emitter = SkillViewEmitter.getInstance()
 ```
 
-`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.
+`SkillViewEmitter` implements all three methods (`on`, `off`, `emit`) needed by `AnimationEmitter`.
 
 The `AnimationEmitter` interface, for reference:
 
@@ -804,9 +777,9 @@ interface AnimationEmitter {
 2. **Create an emitter** — one per component tree, stable across renders:
 
    ```ts
-   import { SimpleEmitter } from '@sprucelabs/spruce-heartwood-utils/web'
+   import { SkillViewEmitter } from '@sprucelabs/spruce-heartwood-utils/web'
 
-   const emitter = useMemo(() => new SimpleEmitter(), [])
+   const emitter = useMemo(() => SkillViewEmitter.getInstance(), [])
    ```
 
 3. **Wire to components and emit events** — pass the emitter to `Sizer` and/or `DelayedPlacer`, then signal layout changes:
@@ -1071,14 +1044,14 @@ Wraps children in a div whose `height` is set via inline style to match the meas
 
    > Inside a Heartwood skill view this CSS is already provided — skip this step.
 
-2. **Wrap your content** — `shouldHideOverflow` clips children during the height transition:
+2. **Wrap your content**
 
    ```tsx
-   import { Sizer, SimpleEmitter } from '@sprucelabs/spruce-heartwood-utils/web'
+   import { Sizer } from '@sprucelabs/spruce-heartwood-utils/web'
 
-   const emitter = useMemo(() => new SimpleEmitter(), [])
+   const emitter = useMemo(() => SkillViewEmitter.getInstance(), [])
 
-   <Sizer emitter={emitter} shouldHideOverflow>
+   <Sizer emitter={emitter}>
        <YourContent />
    </Sizer>
    ```
@@ -1104,20 +1077,6 @@ interface SizerProps {
     // CSS class on the outer .sizer div.
     className?: string
 
-    // When true, starts at height 0 and defers first measurement by 100ms.
-    // Use for content that should animate in from nothing.
-    shouldStartAtZero?: boolean
-
-    // When true, keeps overflow hidden throughout. When explicitly false,
-    // 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
 }
@@ -1142,23 +1101,23 @@ sizer.current?.hideOverflow(): void // re-apply overflow: hidden
 #### Usage
 
 ```tsx
-import { Sizer, SimpleEmitter } from '@sprucelabs/spruce-heartwood-utils/web'
+import { Sizer } from '@sprucelabs/spruce-heartwood-utils/web'
 
-// Simplest — just clip overflow during height transition:
-<Sizer shouldHideOverflow>
+// Simplest 
+<Sizer>
     {isExpanded && <YourExpandableContent />}
 </Sizer>
 
 // Animate in from zero height:
-<Sizer emitter={emitter} shouldStartAtZero>
+<Sizer emitter={emitter}>
     <YourCard />
 </Sizer>
 
 // Manually trigger resize when content changes outside React state:
-const emitter = useMemo(() => new SimpleEmitter(), [])
+const emitter = useMemo(() => SkillViewEmitter.getInstance(), [])
 const sizer = useRef<React.ElementRef<typeof Sizer>>(null)
 
-<Sizer shouldHideOverflow ref={sizer} emitter={emitter}>
+<Sizer ref={sizer} emitter={emitter}>
     <YourDynamicContent
         onContentChange={async () => {
             if (sizer.current?.resize()) {
@@ -1169,7 +1128,7 @@ const sizer = useRef<React.ElementRef<typeof Sizer>>(null)
 </Sizer>
 
 // Staggered entrance with queueShow:
-<Sizer emitter={emitter} shouldHideOverflow shouldStartAtZero>
+<Sizer emitter={emitter}>
     <div className="your-item hidden" ref={(ref) => { ref && queueShow(ref) }}>
         content
     </div>
@@ -1204,9 +1163,9 @@ When `isEnabled={false}`, children render inline with no wrapper.
 2. **Wrap your content** — `isEnabled`, `className`, and `isFocused` are all required:
 
    ```tsx
-   import { DelayedPlacer, SimpleEmitter } from '@sprucelabs/spruce-heartwood-utils/web'
+   import { DelayedPlacer } from '@sprucelabs/spruce-heartwood-utils/web'
 
-   const emitter = useMemo(() => new SimpleEmitter(), [])
+   const emitter = useMemo(() => SkillViewEmitter.getInstance(), [])
 
    <DelayedPlacer
        className="placer__card"
@@ -1224,7 +1183,7 @@ When `isEnabled={false}`, children render inline with no wrapper.
 
    ```tsx
    <DelayedPlacer className="placer__card" isEnabled emitter={emitter} isFocused={isFocused}>
-       <Sizer emitter={emitter} shouldHideOverflow>
+       <Sizer emitter={emitter}>
            <YourContent />
        </Sizer>
    </DelayedPlacer>
@@ -1246,11 +1205,6 @@ interface DelayedPlacerProps {
 
     // Event emitter. Listens for layout changes to re-measure and re-place.
     emitter?: AnimationEmitter
-
-    // Required. Return true when this skill view is focused and in the foreground.
-    // Placement is skipped when false to avoid measuring off-screen content.
-    // Pass () => true for standalone use outside Heartwood.
-    isFocused: () => boolean
 }
 ```
 
@@ -1260,6 +1214,18 @@ interface DelayedPlacerProps {
 delayedPlacer.current?.placeRightAway(): void  // re-measure and re-place immediately
 ```
 
+#### Placer & Sizer Together For Card Placement
+
+When using `DelayedPlacer` and `Sizer` together, the typical pattern is to place `Sizer` inside `DelayedPlacer` so that height changes trigger placement updates:
+
+```tsx
+<DelayedPlacer className="placer" isEnabled emitter={emitter} isFocused={isFocused}>
+	<Sizer emitter={emitter}>
+		<YourCard />
+	</Sizer>
+</DelayedPlacer>
+```
+
 #### Emitter Events
 
 | Event | Direction | Meaning |
@@ -1274,11 +1240,11 @@ delayedPlacer.current?.placeRightAway(): void  // re-measure and re-place immedi
 
 ```tsx
 import React, { useRef, useMemo } from 'react'
-import { DelayedPlacer, SimpleEmitter } from '@sprucelabs/spruce-heartwood-utils/web'
+import { DelayedPlacer } from '@sprucelabs/spruce-heartwood-utils/web'
 
 function YourPanel({ isFocused }: { isFocused: () => boolean }) {
     const placerRef = useRef<React.ElementRef<typeof DelayedPlacer>>(null)
-    const emitter = useMemo(() => new SimpleEmitter(), [])
+    const emitter = useMemo(() => SkillViewEmitter.getInstance(), [])
 
     return (
         <DelayedPlacer
@@ -1365,11 +1331,11 @@ A complete example showing all three systems working together in a card componen
 ```tsx
 import React, { useMemo } from 'react'
 import {
-    Sizer, DelayedPlacer, queueShow, Settings, SimpleEmitter,
+    Sizer, DelayedPlacer, queueShow, Settings,
 } from '@sprucelabs/spruce-heartwood-utils/web'
 
 function YourCard({ isPlaced, isFocused }: { isPlaced: boolean; isFocused: () => boolean }) {
-    const emitter = useMemo(() => new SimpleEmitter(), [])
+    const emitter = useMemo(() => SkillViewEmitter.getInstance(), [])
 
     return (
         <DelayedPlacer
@@ -1378,7 +1344,7 @@ function YourCard({ isPlaced, isFocused }: { isPlaced: boolean; isFocused: () =>
             emitter={emitter}
             isFocused={isFocused}
         >
-            <Sizer emitter={emitter} shouldHideOverflow shouldStartAtZero>
+            <Sizer emitter={emitter}>
                 <div
                     className="card hidden"
                     ref={(ref) => { ref && queueShow(ref) }}

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

@@ -6,4 +6,3 @@ 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.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;
+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,6 +27,4 @@ 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/index.d.ts

@@ -6,4 +6,3 @@ 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,4 +6,3 @@ 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/package.json

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