@sprucelabs/spruce-heartwood-utils 38.17.3 → 38.17.5

package/README.md

@@ -709,6 +709,32 @@ interface AnimationEmitter {
 }
 ```
 
+#### Quick Setup
+
+1. **Install**
+
+   ```sh
+   npm install @sprucelabs/spruce-heartwood-utils
+   ```
+
+2. **Create an emitter** — one per component tree, stable across renders:
+
+   ```ts
+   import { SimpleEmitter } from '@sprucelabs/spruce-heartwood-utils'
+
+   const emitter = useMemo(() => new SimpleEmitter(), [])
+   ```
+
+3. **Wire to components and emit events** — pass the emitter to `Sizer` and/or `DelayedPlacer`, then signal layout changes:
+
+   ```ts
+   // After a React render cycle completes:
+   await emitter.emit('did-render')
+
+   // After a viewport resize:
+   await emitter.emit('did-resize')
+   ```
+
 **Events:**
 
 | Event | Who listens | Who emits | Meaning |
@@ -944,6 +970,44 @@ return <h1 ref={ref} className="your-heading hidden">Title</h1>
 
 Wraps children in a div whose `height` is set via inline style to match the measured height of its content. Listens to `did-render` and `did-resize` events so it resizes whenever layout changes — enabling smooth CSS height transitions on content that would otherwise be `height: auto`. Emits `did-resize-content` so `DelayedPlacer` can re-place after a height change.
 
+#### Quick Setup
+
+1. **Install and add the required CSS**
+
+   ```sh
+   npm install @sprucelabs/spruce-heartwood-utils
+   ```
+
+   ```css
+   .sizer {
+       transition: height 500ms ease;
+       overflow: hidden;
+   }
+   ```
+
+   > Inside a Heartwood skill view this CSS is already provided — skip this step.
+
+2. **Wrap your content** — `shouldHideOverflow` clips children during the height transition:
+
+   ```tsx
+   import { Sizer, SimpleEmitter } from '@sprucelabs/spruce-heartwood-utils'
+
+   const emitter = useMemo(() => new SimpleEmitter(), [])
+
+   <Sizer emitter={emitter} shouldHideOverflow>
+       <YourContent />
+   </Sizer>
+   ```
+
+3. **Signal layout changes** — emit after renders and on viewport resize; Sizer measures content and updates `style.height` automatically:
+
+   ```ts
+   await emitter.emit('did-render')
+   await emitter.emit('did-resize')
+   ```
+
+   In tests, call `Settings.disableAnimations()` in `beforeEach` so height changes apply synchronously.
+
 #### Props (`SizerProps`)
 
 ```ts
@@ -1038,6 +1102,52 @@ Positions a child element to match the location of its in-flow placeholder. Wrap
 
 When `isEnabled={false}`, children render inline with no wrapper.
 
+#### Quick Setup
+
+1. **Install and add the required CSS**
+
+   ```sh
+   npm install @sprucelabs/spruce-heartwood-utils
+   ```
+
+   ```css
+   .placer { position: relative; }
+   .placer > * { position: absolute; }
+   ```
+
+   > Inside a Heartwood skill view this CSS is already provided — skip this step.
+
+2. **Wrap your content** — `isEnabled`, `className`, and `isFocused` are all required:
+
+   ```tsx
+   import { DelayedPlacer, SimpleEmitter } from '@sprucelabs/spruce-heartwood-utils'
+
+   const emitter = useMemo(() => new SimpleEmitter(), [])
+
+   <DelayedPlacer
+       className="placer__card"
+       isEnabled={true}
+       emitter={emitter}
+       isFocused={() => true}
+   >
+       <YourCard />
+   </DelayedPlacer>
+   ```
+
+   Pass `() => true` for `isFocused` when using outside Heartwood — placement is skipped when this returns false.
+
+3. **Share the emitter with `Sizer`** when they are siblings so height changes automatically trigger re-placement:
+
+   ```tsx
+   <DelayedPlacer className="placer__card" isEnabled emitter={emitter} isFocused={isFocused}>
+       <Sizer emitter={emitter} shouldHideOverflow>
+           <YourContent />
+       </Sizer>
+   </DelayedPlacer>
+   ```
+
+   `DelayedPlacer` emits `did-place-cards` when placement is complete. Listen for it if you need to react after cards settle.
+
 #### Props (`DelayedPlacerProps`)
 
 ```ts

package/build/app/SkillViewEmitter.d.ts

@@ -0,0 +1,167 @@
+import { AbstractEventEmitter } from '@sprucelabs/mercury-event-emitter';
+import { EventContract, EventContractEmitPayloads, MercuryEventEmitter } from '@sprucelabs/mercury-types';
+declare const contract: {
+    eventSignatures: {
+        'did-change-orientation': {};
+        'did-resize': {};
+        'did-render': {};
+        'did-resize-content': {};
+        'did-place-cards': {};
+        'will-change-route': {};
+        'did-render-dialog': {};
+        'did-keydown': {
+            emitPayloadSchema: {
+                id: string;
+                fields: {
+                    e: {
+                        type: "raw";
+                        isRequired: true;
+                        options: {
+                            valueType: string;
+                        };
+                    };
+                };
+            };
+        };
+        'did-scroll': {
+            emitPayloadSchema: {
+                id: string;
+                fields: {
+                    scrollTop: {
+                        type: "number";
+                        isRequired: true;
+                    };
+                    skillViewNode: {
+                        type: "raw";
+                        isRequired: true;
+                        options: {
+                            valueType: string;
+                        };
+                    };
+                };
+            };
+        };
+        'connection-status-change': {
+            emitPayloadSchema: {
+                id: string;
+                fields: {
+                    payload: {
+                        type: "schema";
+                        isRequired: true;
+                        options: {
+                            schema: {
+                                id: string;
+                                fields: {
+                                    status: {
+                                        type: "select";
+                                        isRequired: true;
+                                        options: {
+                                            choices: ({
+                                                readonly label: "Connecting";
+                                                readonly value: "connecting";
+                                            } | {
+                                                readonly label: "Connected";
+                                                readonly value: "connected";
+                                            } | {
+                                                readonly label: "Disconnected";
+                                                readonly value: "disconnected";
+                                            })[];
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
+};
+export type SkillViewEventContract = typeof contract;
+export type SkillViewEvents = SkillViewEventContract['eventSignatures'];
+export type SkillViewEmitPayloads = EventContractEmitPayloads<SkillViewEventContract>;
+export type SkillViewEmitter = MercuryEventEmitter<SkillViewEventContract>;
+export default class SkillViewEmitterImpl<Contract extends EventContract = SkillViewEventContract> extends AbstractEventEmitter<Contract> implements MercuryEventEmitter<Contract> {
+    private static instance;
+    private constructor();
+    static Emitter(): SkillViewEmitterImpl<{
+        eventSignatures: {
+            'did-change-orientation': {};
+            'did-resize': {};
+            'did-render': {};
+            'did-resize-content': {};
+            'did-place-cards': {};
+            'will-change-route': {};
+            'did-render-dialog': {};
+            'did-keydown': {
+                emitPayloadSchema: {
+                    id: string;
+                    fields: {
+                        e: {
+                            type: "raw";
+                            isRequired: true;
+                            options: {
+                                valueType: string;
+                            };
+                        };
+                    };
+                };
+            };
+            'did-scroll': {
+                emitPayloadSchema: {
+                    id: string;
+                    fields: {
+                        scrollTop: {
+                            type: "number";
+                            isRequired: true;
+                        };
+                        skillViewNode: {
+                            type: "raw";
+                            isRequired: true;
+                            options: {
+                                valueType: string;
+                            };
+                        };
+                    };
+                };
+            };
+            'connection-status-change': {
+                emitPayloadSchema: {
+                    id: string;
+                    fields: {
+                        payload: {
+                            type: "schema";
+                            isRequired: true;
+                            options: {
+                                schema: {
+                                    id: string;
+                                    fields: {
+                                        status: {
+                                            type: "select";
+                                            isRequired: true;
+                                            options: {
+                                                choices: ({
+                                                    readonly label: "Connecting";
+                                                    readonly value: "connecting";
+                                                } | {
+                                                    readonly label: "Connected";
+                                                    readonly value: "connected";
+                                                } | {
+                                                    readonly label: "Disconnected";
+                                                    readonly value: "disconnected";
+                                                })[];
+                                            };
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    }>;
+    static reset(): void;
+    static getInstance(): SkillViewEmitter;
+}
+export {};

package/build/app/SkillViewEmitter.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const mercury_client_1 = require("@sprucelabs/mercury-client");
+const mercury_event_emitter_1 = require("@sprucelabs/mercury-event-emitter");
+const mercury_types_1 = require("@sprucelabs/mercury-types");
+const schema_1 = require("@sprucelabs/schema");
+const contract = (0, mercury_types_1.buildEventContract)({
+    eventSignatures: {
+        ...mercury_client_1.connectionStatusContract.eventSignatures,
+        'did-change-orientation': {},
+        'did-resize': {},
+        'did-render': {},
+        'did-resize-content': {},
+        'did-place-cards': {},
+        'will-change-route': {},
+        'did-render-dialog': {},
+        'did-keydown': {
+            emitPayloadSchema: (0, schema_1.buildSchema)({
+                id: 'didKeydownEmitPayload',
+                fields: {
+                    e: {
+                        type: 'raw',
+                        isRequired: true,
+                        options: {
+                            valueType: 'KeyboardEvent',
+                        },
+                    },
+                },
+            }),
+        },
+        'did-scroll': {
+            emitPayloadSchema: (0, schema_1.buildSchema)({
+                id: 'didScrollEmitPayload',
+                fields: {
+                    scrollTop: {
+                        type: 'number',
+                        isRequired: true,
+                    },
+                    skillViewNode: {
+                        type: 'raw',
+                        isRequired: true,
+                        options: {
+                            valueType: 'HTMLDivElement',
+                        },
+                    },
+                },
+            }),
+        },
+    },
+});
+class SkillViewEmitterImpl extends mercury_event_emitter_1.AbstractEventEmitter {
+    constructor(contract) {
+        super(contract);
+    }
+    static Emitter() {
+        return new this(contract);
+    }
+    static reset() {
+        this.instance = null;
+    }
+    static getInstance() {
+        if (!this.instance) {
+            this.instance = this.Emitter();
+        }
+        return this.instance;
+    }
+}
+exports.default = SkillViewEmitterImpl;
+//# sourceMappingURL=SkillViewEmitter.js.map

package/build/esm/__tests__/support/MockRemoteViewControllerFactory.js

@@ -1,12 +1,3 @@
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
 import { vcAssert, } from '@sprucelabs/heartwood-view-controllers';
 import { assert } from '@sprucelabs/test-utils';
 class MockRemoteViewControllerFactory {
@@ -45,8 +36,7 @@ class MockRemoteViewControllerFactory {
         }
     }
     assertSkillViewRendersRemoteCard(vc, name, id) {
-        var _a;
-        const Class = (_a = MockRemoteViewControllerFactory.controllers) === null || _a === void 0 ? void 0 : _a[name];
+        const Class = MockRemoteViewControllerFactory.controllers?.[name];
         assert.isTruthy(Class, `You did not drop in a remote card with the name '${name}'! Try MockRemoteViewControllerFactory.dropInRemoteController('${name}', Class) in your beforeEach().`);
         const cards = vcAssert.assertSkillViewRendersCards(vc);
         const cardsWithNoControllers = cards.filter((c) => !c);
@@ -92,7 +82,7 @@ class MockRemoteViewControllerFactory {
         try {
             this.assertFetchedRemoteController(id);
         }
-        catch (_a) {
+        catch {
             return;
         }
         assert.fail(`You fetched the controller with the id '${id}' but you should not have.`);
@@ -107,23 +97,17 @@ class MockRemoteViewControllerFactory {
         assert.isEqualDeep(this.constructorOptionsById[id], expected, `The constructor options for the remote card with id '${id}' do not match the expected options. Make sure the card you are rendering has an id using this.views.Controller('card', { id })`);
     }
     hasController(name) {
-        var _a;
-        return (_a = this.loadedControllers[name]) !== null && _a !== void 0 ? _a : false;
-    }
-    RemoteController(id, options) {
-        return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b;
-            assert.isTruthy((_a = MockRemoteViewControllerFactory.controllers) === null || _a === void 0 ? void 0 : _a[id], `Could not find a remote card with the id '${id}'! Try MockRemoteViewControllerFactory.dropInRemoteController('${id}', Class) in your beforeEach().`);
-            this.loadedControllers[id] = true;
-            this.constructorOptionsById[(_b = options.id) !== null && _b !== void 0 ? _b : id] = options;
-            this.lastRemoteCostructorOptions = options;
-            return this.views.Controller(id, options);
-        });
-    }
-    loadViewsForNamespace(namespace) {
-        return __awaiter(this, void 0, void 0, function* () {
-            this.loadedNamespaces[namespace] = true;
-        });
+        return this.loadedControllers[name] ?? false;
+    }
+    async RemoteController(id, options) {
+        assert.isTruthy(MockRemoteViewControllerFactory.controllers?.[id], `Could not find a remote card with the id '${id}'! Try MockRemoteViewControllerFactory.dropInRemoteController('${id}', Class) in your beforeEach().`);
+        this.loadedControllers[id] = true;
+        this.constructorOptionsById[options.id ?? id] = options;
+        this.lastRemoteCostructorOptions = options;
+        return this.views.Controller(id, options);
+    }
+    async loadViewsForNamespace(namespace) {
+        this.loadedNamespaces[namespace] = true;
     }
     assertLoadedViewsForNamespace(namespace) {
         assert.isTrue(this.loadedNamespaces[namespace], `You did not load views for the namespace '${namespace}'. Try removeVc.loadViewsForNamespace('${namespace}').`);

package/build/esm/__tests__/support/heartwoodEventFaker.js

@@ -1,36 +1,25 @@
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
 import { eventFaker } from '@sprucelabs/spruce-test-fixtures';
 import { generateId } from '@sprucelabs/test-utils';
 const heartwoodEventFaker = {
-    fakeGetViews(svcIds, stubMethodToImplement) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const vcs = svcIds.map((id) => ({
-                id,
-                stubMethod: stubMethodToImplement,
-            }));
-            const source = [
-                ...vcs.map((vc, idx) => generateVcSource({
-                    vcId: vc.id,
-                    count: idx + 1,
-                    stubMethod: vc.stubMethod,
-                })),
-                `heartwood({ ${vcs.map((vc, idx) => `TestEventViewController${idx + 1}`)} })`,
-            ];
-            yield eventFaker.on('heartwood.get-skill-views::v2021_02_11', () => {
-                return {
-                    id: generateId(),
-                    ids: svcIds,
-                    source: source.join('\n'),
-                };
-            });
+    async fakeGetViews(svcIds, stubMethodToImplement) {
+        const vcs = svcIds.map((id) => ({
+            id,
+            stubMethod: stubMethodToImplement,
+        }));
+        const source = [
+            ...vcs.map((vc, idx) => generateVcSource({
+                vcId: vc.id,
+                count: idx + 1,
+                stubMethod: vc.stubMethod,
+            })),
+            `heartwood({ ${vcs.map((vc, idx) => `TestEventViewController${idx + 1}`)} })`,
+        ];
+        await eventFaker.on('heartwood.get-skill-views::v2021_02_11', () => {
+            return {
+                id: generateId(),
+                ids: svcIds,
+                source: source.join('\n'),
+            };
         });
     },
 };
@@ -40,7 +29,7 @@ function generateVcSource(options) {
     return [
         `class TestEventViewController${count} {
 			alert = function() {}
-			${stubMethod !== null && stubMethod !== void 0 ? stubMethod : 'noop'} = function () {
+			${stubMethod ?? 'noop'} = function () {
 				this.wasHit = true
 				this.passedParams = Array.prototype.slice.call(arguments)
 			}

package/build/esm/__tests__/support/remoteVcAssert.js

@@ -1,12 +1,3 @@
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
 import { AbstractViewController, vcAssert, } from '@sprucelabs/heartwood-view-controllers';
 import { assertOptions } from '@sprucelabs/schema';
 import { eventFaker, } from '@sprucelabs/spruce-test-fixtures';
@@ -14,48 +5,46 @@ import { assert } from '@sprucelabs/test-utils';
 import { generateId } from '@sprucelabs/test-utils';
 import heartwoodEventFaker from './heartwoodEventFaker.js';
 const remoteVcAssert = {
-    assertSkillViewRendersRemoteCards(options) {
-        return __awaiter(this, void 0, void 0, function* () {
-            var _a;
-            const { views, svc: svc, expectedTarget, expectedPayload, fqen, shouldInvoke, loadArgs, } = assertOptions(options, [
-                'svc',
-                'fqen',
-                'views',
-            ]);
-            const factory = views.getFactory();
-            factory.setController('heartwood.error-card', ThrowingErrorCardVc);
-            const vc1Id = generateId();
-            const vc2Id = generateId();
-            let wasHit = false;
-            let passedTarget;
-            let passedPayload;
-            yield eventFaker.on(fqen, 
-            //@ts-ignore
-            (...args_1) => __awaiter(this, [...args_1], void 0, function* ({ target, payload } = {}) {
-                passedTarget = target;
-                passedPayload = payload;
-                wasHit = true;
-                return {
-                    vcIds: ['assert.' + vc1Id, 'assert.' + vc2Id],
-                };
-            }));
-            const stubMethodName = shouldInvoke === null || shouldInvoke === void 0 ? void 0 : shouldInvoke.methodName;
-            const ids = [vc1Id, vc2Id];
-            yield heartwoodEventFaker.fakeGetViews(ids, stubMethodName);
-            yield views.load(svc, loadArgs);
-            assert.isTrue(wasHit, `You did not load any remote cards. Next step is to add the following to your skill view's load():\n\nconst registrar = new CardRegistrar(...)\nconst cards = await registrar.fetch(...)\n\nAlso, make sure you create the new event that you'll emit when trying to fetch remote cards, something like 'my-skill.register-cards::v2020_02_02'\n\n`);
-            if (expectedTarget) {
-                assert.isEqualDeep(passedTarget, expectedTarget, 'The target you passed did not match!');
-            }
-            if (expectedPayload) {
-                assert.isEqualDeep(passedPayload, expectedPayload, 'The payload you passed did not match!');
-            }
-            let cards = [];
-            try {
-                cards = vcAssert.assertSkillViewRendersCards(svc, [vc1Id, vc2Id]);
-            }
-            catch (err) {
-                assert.fail(`You didn't drop in the cards to your skill view! Make sure your vcIdsTransformer looks something like:
+    async assertSkillViewRendersRemoteCards(options) {
+        const { views, svc: svc, expectedTarget, expectedPayload, fqen, shouldInvoke, loadArgs, } = assertOptions(options, [
+            'svc',
+            'fqen',
+            'views',
+        ]);
+        const factory = views.getFactory();
+        factory.setController('heartwood.error-card', ThrowingErrorCardVc);
+        const vc1Id = generateId();
+        const vc2Id = generateId();
+        let wasHit = false;
+        let passedTarget;
+        let passedPayload;
+        await eventFaker.on(fqen, 
+        //@ts-ignore
+        async ({ target, payload } = {}) => {
+            passedTarget = target;
+            passedPayload = payload;
+            wasHit = true;
+            return {
+                vcIds: ['assert.' + vc1Id, 'assert.' + vc2Id],
+            };
+        });
+        const stubMethodName = shouldInvoke?.methodName;
+        const ids = [vc1Id, vc2Id];
+        await heartwoodEventFaker.fakeGetViews(ids, stubMethodName);
+        await views.load(svc, loadArgs);
+        assert.isTrue(wasHit, `You did not load any remote cards. Next step is to add the following to your skill view's load():\n\nconst registrar = new CardRegistrar(...)\nconst cards = await registrar.fetch(...)\n\nAlso, make sure you create the new event that you'll emit when trying to fetch remote cards, something like 'my-skill.register-cards::v2020_02_02'\n\n`);
+        if (expectedTarget) {
+            assert.isEqualDeep(passedTarget, expectedTarget, 'The target you passed did not match!');
+        }
+        if (expectedPayload) {
+            assert.isEqualDeep(passedPayload, expectedPayload, 'The payload you passed did not match!');
+        }
+        let cards = [];
+        try {
+            cards = vcAssert.assertSkillViewRendersCards(svc, [vc1Id, vc2Id]);
+        }
+        catch (err) {
+            assert.fail(`You didn't drop in the cards to your skill view! Make sure your vcIdsTransformer looks something like:
 
 vcIdsTransformer: (payload) => {
 	return payload.vcIds
@@ -73,21 +62,20 @@ public render() {
 	}
 }
 
-The original error is: ${(_a = err.stack) !== null && _a !== void 0 ? _a : err.message}
+The original error is: ${err.stack ?? err.message}
 `);
-            }
-            if (shouldInvoke) {
-                const { methodName, expectedParams } = shouldInvoke;
-                assert.isTrue(
+        }
+        if (shouldInvoke) {
+            const { methodName, expectedParams } = shouldInvoke;
+            assert.isTrue(
+            //@ts-ignore
+            cards.filter((c) => c.wasHit).length === cards.length, `You gotta call cardVc.${methodName}(...) on all the cards you get back!`);
+            if (expectedParams) {
                 //@ts-ignore
-                cards.filter((c) => c.wasHit).length === cards.length, `You gotta call cardVc.${methodName}(...) on all the cards you get back!`);
-                if (expectedParams) {
-                    //@ts-ignore
-                    const passed = cards[0].passedParams;
-                    assert.isEqualDeep(passed, expectedParams, `You didn't pass the expected params to ${methodName}!`);
-                }
+                const passed = cards[0].passedParams;
+                assert.isEqualDeep(passed, expectedParams, `You didn't pass the expected params to ${methodName}!`);
             }
-        });
+        }
     },
 };
 class ThrowingErrorCardVc extends AbstractViewController {