slicejs-web-framework 3.4.3 → 3.5.0

package/Slice/tests/context-patch-use.test.js

@@ -1,95 +1,95 @@
-import test from 'node:test';
-import assert from 'node:assert/strict';
-
-globalThis.alert = () => {};
-
-// Minimal global `slice` so ContextManager's slice.logger / slice.events work in
-// isolation (a tiny in-memory event bus drives the watch notifications).
-const subscribers = new Map(); // eventName -> Set<fn>
-let subId = 0;
-globalThis.slice = {
-   logger: { logError() {}, logInfo() {}, logWarning() {} },
-   events: {
-      subscribe(name, cb) {
-         if (!subscribers.has(name)) subscribers.set(name, new Set());
-         subscribers.get(name).add(cb);
-         return `sub-${++subId}`;
-      },
-      emit(name, ...args) {
-         for (const cb of subscribers.get(name) ?? []) cb(...args);
-      },
-   },
-};
-
-const { default: ContextManager } = await import(
-   '../Components/Structural/ContextManager/ContextManager.js'
-);
-
-function freshContext(name, initial) {
-   const ctx = new ContextManager();
-   ctx.create(name, initial);
-   return ctx;
-}
-
-test('patch merges into existing state (does not replace)', () => {
-   const ctx = freshContext('cart', { items: 2, total: 47, discount: 0 });
-   ctx.patch('cart', { discount: 0.1 });
-   assert.deepEqual(ctx.getState('cart'), { items: 2, total: 47, discount: 0.1 });
-});
-
-test('setState replaces, patch keeps the rest', () => {
-   const ctx = freshContext('s', { a: 1, b: 2 });
-   ctx.setState('s', { a: 9 }); // replace → drops b
-   assert.deepEqual(ctx.getState('s'), { a: 9 });
-   ctx.patch('s', { b: 5 }); // merge onto { a: 9 }
-   assert.deepEqual(ctx.getState('s'), { a: 9, b: 5 });
-});
-
-test('patch rejects non-object partials and missing contexts (no throw)', () => {
-   const ctx = freshContext('s', { a: 1 });
-   ctx.patch('s', null);
-   ctx.patch('s', [1, 2]);
-   ctx.patch('nope', { x: 1 });
-   assert.deepEqual(ctx.getState('s'), { a: 1 });
-   assert.equal(ctx.has('nope'), false);
-});
-
-test('use(name) returns a handle bound to that context', () => {
-   const ctx = freshContext('settings', { model: 'a' });
-   const settings = ctx.use('settings');
-
-   assert.equal(settings.get().model, 'a');
-   settings.set({ model: 'b' });
-   assert.equal(ctx.getState('settings').model, 'b');
-   settings.patch({ theme: 'dark' });
-   assert.deepEqual(ctx.getState('settings'), { model: 'b', theme: 'dark' });
-   assert.equal(settings.has(), true);
-   settings.destroy();
-   assert.equal(ctx.has('settings'), false);
-});
-
-test('use(name).bind calls back immediately and on every change', () => {
-   const ctx = freshContext('cart', { items: [], n: 0 });
-   const calls = [];
-   ctx.use('cart').bind({ sliceId: 'c1' }, (state) => calls.push(state.n));
-
-   assert.deepEqual(calls, [0]); // immediate initial call
-   ctx.patch('cart', { n: 1 });
-   assert.deepEqual(calls, [0, 1]); // fired on change
-});
-
-test('use(name).bind with a selector only fires when the selected value changes', () => {
-   const ctx = freshContext('cart', { items: ['x'], note: 'a' });
-   const counts = [];
-   ctx.use('cart').bind(
-      { sliceId: 'c2' },
-      (count) => counts.push(count),
-      (s) => s.items.length
-   );
-
-   assert.deepEqual(counts, [1]); // immediate, selected value = length
-   ctx.patch('cart', { note: 'b' }); // length unchanged → no fire
-   assert.deepEqual(counts, [1]);
-   ctx.patch('cart', { items: ['x', 'y'] }); // length changed → fire
-   assert.deepEqual(counts, [1, 2]);
-});
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+globalThis.alert = () => {};
+
+// Minimal global `slice` so ContextManager's slice.logger / slice.events work in
+// isolation (a tiny in-memory event bus drives the watch notifications).
+const subscribers = new Map(); // eventName -> Set<fn>
+let subId = 0;
+globalThis.slice = {
+   logger: { logError() {}, logInfo() {}, logWarning() {} },
+   events: {
+      subscribe(name, cb) {
+         if (!subscribers.has(name)) subscribers.set(name, new Set());
+         subscribers.get(name).add(cb);
+         return `sub-${++subId}`;
+      },
+      emit(name, ...args) {
+         for (const cb of subscribers.get(name) ?? []) cb(...args);
+      },
+   },
+};
+
+const { default: ContextManager } = await import(
+   '../Components/Structural/ContextManager/ContextManager.js'
+);
+
+function freshContext(name, initial) {
+   const ctx = new ContextManager();
+   ctx.create(name, initial);
+   return ctx;
+}
+
+test('patch merges into existing state (does not replace)', () => {
+   const ctx = freshContext('cart', { items: 2, total: 47, discount: 0 });
+   ctx.patch('cart', { discount: 0.1 });
+   assert.deepEqual(ctx.getState('cart'), { items: 2, total: 47, discount: 0.1 });
+});
+
+test('setState replaces, patch keeps the rest', () => {
+   const ctx = freshContext('s', { a: 1, b: 2 });
+   ctx.setState('s', { a: 9 }); // replace → drops b
+   assert.deepEqual(ctx.getState('s'), { a: 9 });
+   ctx.patch('s', { b: 5 }); // merge onto { a: 9 }
+   assert.deepEqual(ctx.getState('s'), { a: 9, b: 5 });
+});
+
+test('patch rejects non-object partials and missing contexts (no throw)', () => {
+   const ctx = freshContext('s', { a: 1 });
+   ctx.patch('s', null);
+   ctx.patch('s', [1, 2]);
+   ctx.patch('nope', { x: 1 });
+   assert.deepEqual(ctx.getState('s'), { a: 1 });
+   assert.equal(ctx.has('nope'), false);
+});
+
+test('use(name) returns a handle bound to that context', () => {
+   const ctx = freshContext('settings', { model: 'a' });
+   const settings = ctx.use('settings');
+
+   assert.equal(settings.get().model, 'a');
+   settings.set({ model: 'b' });
+   assert.equal(ctx.getState('settings').model, 'b');
+   settings.patch({ theme: 'dark' });
+   assert.deepEqual(ctx.getState('settings'), { model: 'b', theme: 'dark' });
+   assert.equal(settings.has(), true);
+   settings.destroy();
+   assert.equal(ctx.has('settings'), false);
+});
+
+test('use(name).bind calls back immediately and on every change', () => {
+   const ctx = freshContext('cart', { items: [], n: 0 });
+   const calls = [];
+   ctx.use('cart').bind({ sliceId: 'c1' }, (state) => calls.push(state.n));
+
+   assert.deepEqual(calls, [0]); // immediate initial call
+   ctx.patch('cart', { n: 1 });
+   assert.deepEqual(calls, [0, 1]); // fired on change
+});
+
+test('use(name).bind with a selector only fires when the selected value changes', () => {
+   const ctx = freshContext('cart', { items: ['x'], note: 'a' });
+   const counts = [];
+   ctx.use('cart').bind(
+      { sliceId: 'c2' },
+      (count) => counts.push(count),
+      (s) => s.items.length
+   );
+
+   assert.deepEqual(counts, [1]); // immediate, selected value = length
+   ctx.patch('cart', { note: 'b' }); // length unchanged → no fire
+   assert.deepEqual(counts, [1]);
+   ctx.patch('cart', { items: ['x', 'y'] }); // length changed → fire
+   assert.deepEqual(counts, [1, 2]);
+});

package/Slice/tests/event-emitters.test.js

@@ -0,0 +1,79 @@
+// Tests for emitter tracing: who emits each event (bind attribution + dev
+// stack-trace fallback), recorded only while a debugger is "open" (recording).
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+globalThis.slice = {
+   isProduction: () => false,
+   controller: { activeComponents: new Map() },
+   logger: { logError() {}, logInfo() {}, logWarning() {}, info() {}, error() {} },
+};
+
+const { default: EventManager } = await import('../Components/Structural/EventManager/EventManager.js');
+
+test('bound emit is attributed to its component', () => {
+   const em = new EventManager();
+   em.startRecording();
+   const comp = { sliceId: 'card-1', constructor: { name: 'Card' } };
+   em.bind(comp).emit('user:login', { id: 1 });
+
+   const bucket = em.emitters.get('user:login');
+   assert.ok(bucket, 'event has emitters bucket');
+   const entry = bucket.get('card-1');
+   assert.equal(entry.name, 'Card');
+   assert.equal(entry.sliceId, 'card-1');
+   assert.equal(entry.count, 1);
+
+   const hist = em.emitHistory.find((e) => e.eventName === 'user:login');
+   assert.equal(hist.emitter.sliceId, 'card-1', 'history entry carries the emitter');
+});
+
+test('global emit falls back to a dev stack-trace source', () => {
+   const em = new EventManager();
+   em.startRecording();
+   em.emit('router:change');
+
+   const hist = em.emitHistory.find((e) => e.eventName === 'router:change');
+   assert.ok(hist.emitter, 'emitter captured for global emit');
+   assert.ok(hist.emitter.source && hist.emitter.source.includes('.js'), 'source is file:line');
+   assert.ok(!hist.emitter.source.includes('EventManager.js'), 'attributes the caller, not the manager');
+});
+
+test('emitter counts accumulate per distinct source', () => {
+   const em = new EventManager();
+   em.startRecording();
+   em.bind({ sliceId: 'a-1', constructor: { name: 'A' } }).emit('x:y');
+   em.bind({ sliceId: 'a-1', constructor: { name: 'A' } }).emit('x:y');
+   em.bind({ sliceId: 'b-2', constructor: { name: 'B' } }).emit('x:y');
+
+   const bucket = em.emitters.get('x:y');
+   assert.equal(bucket.get('a-1').count, 2);
+   assert.equal(bucket.get('b-2').count, 1);
+});
+
+test('no recording (debugger closed) => no emitter tracking, zero overhead', () => {
+   const em = new EventManager();
+   em.emit('a:b');
+   em.bind({ sliceId: 'z-1', constructor: { name: 'Z' } }).emit('a:b');
+   assert.equal(em.emitters.size, 0);
+   assert.equal(em.emitHistory.length, 0);
+});
+
+test('production: no stack-trace source captured', () => {
+   globalThis.slice.isProduction = () => true;
+   const em = new EventManager();
+   em.startRecording();
+   em.emit('p:q');
+   const hist = em.emitHistory.find((e) => e.eventName === 'p:q');
+   assert.equal(hist.emitter, null, 'no source attribution in production');
+   globalThis.slice.isProduction = () => false;
+});
+
+test('startRecording resets the emitters map', () => {
+   const em = new EventManager();
+   em.startRecording();
+   em.bind({ sliceId: 'a-1', constructor: { name: 'A' } }).emit('x:y');
+   assert.equal(em.emitters.size, 1);
+   em.startRecording();
+   assert.equal(em.emitters.size, 0, 'fresh session clears prior emitters');
+});

package/Slice/tests/event-registry.test.js

@@ -0,0 +1,141 @@
+// Unit tests for the EventManager typed-event registry (register/validate/warn).
+// EventManager only depends on the `slice` global for logging + isProduction +
+// controller.activeComponents, so we stub a minimal one and drive the real class.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+const warnings = [];
+globalThis.slice = {
+   isProduction: () => false,
+   controller: { activeComponents: new Map() },
+   logger: {
+      logError() {},
+      logInfo() {},
+      logWarning(_c, message) { warnings.push(message); },
+      info() {}, error() {}, warn() {},
+   },
+};
+
+const { default: EventManager } = await import('../Components/Structural/EventManager/EventManager.js');
+
+const undeclaredWarns = (name) => warnings.filter((w) => w.includes('Undeclared') && (!name || w.includes(name)));
+
+test('loose mode: with no registry, nothing warns', () => {
+   warnings.length = 0;
+   const em = new EventManager();
+   em.emit('anything:happens');
+   em.subscribe('whatever:event', () => {});
+   assert.equal(undeclaredWarns().length, 0);
+});
+
+test('declared event emits and subscribes without warning', () => {
+   warnings.length = 0;
+   const em = new EventManager();
+   em.register({ 'user:login': { payload: { id: 'number' } } });
+   em.subscribe('user:login', () => {});
+   em.emit('user:login', { id: 1 });
+   assert.equal(undeclaredWarns().length, 0);
+});
+
+test('undeclared event warns exactly once but still delivers', () => {
+   warnings.length = 0;
+   const em = new EventManager();
+   em.register({ 'user:login': { payload: null } });
+
+   let calls = 0;
+   em.subscribe('ghost:event', () => { calls += 1; });   // subscribe (undeclared) -> warns
+   em.emit('ghost:event');                                 // emit (undeclared, already warned)
+   em.emit('ghost:event');
+
+   assert.equal(undeclaredWarns('ghost:event').length, 1, 'warned exactly once');
+   assert.equal(calls, 2, 'delivery still happened both emits');
+});
+
+test('framework events (router:*/context:*) never warn', () => {
+   warnings.length = 0;
+   const em = new EventManager();
+   em.register({ 'user:login': { payload: null } });
+   em.emit('router:change');
+   em.emit('context:user', {});
+   em.subscribe('context:cart', () => {});
+   assert.equal(undeclaredWarns().length, 0);
+});
+
+test('production: undeclared events do not warn', () => {
+   warnings.length = 0;
+   globalThis.slice.isProduction = () => true;
+   const em = new EventManager();
+   em.register({ 'a:b': { payload: null } });
+   em.emit('zzz:undeclared');
+   assert.equal(undeclaredWarns().length, 0);
+   globalThis.slice.isProduction = () => false;
+});
+
+test('register() merges catalogs and is chainable', () => {
+   const em = new EventManager();
+   const ret = em.register({ 'a:1': { payload: null } }).register({ 'b:2': { payload: { x: 'string' } } });
+   assert.equal(ret, em, 'returns the manager for chaining');
+   assert.ok(em.registry.has('a:1') && em.registry.has('b:2'), 'both catalogs merged');
+   assert.equal(em.isDeclared('a:1'), true);
+   assert.equal(em.isDeclared('nope:nope'), false);
+});
+
+test('register(namespace, catalog) prefixes keys', () => {
+   const em = new EventManager();
+   em.register('user', { login: { payload: { id: 'number' } }, logout: { payload: null } });
+   assert.ok(em.registry.has('user:login'), 'user:login declared');
+   assert.ok(em.registry.has('user:logout'), 'user:logout declared');
+   assert.equal(em.namespaceOf('user:login'), 'user');
+   assert.equal(em.namespaceOf('ready'), null);
+});
+
+test('event without namespace warns once in dev', () => {
+   warnings.length = 0;
+   const em = new EventManager();
+   em.register({ 'ready': { payload: null } });       // declared but no namespace -> warns
+   em.emit('ready');
+   em.emit('ready');
+   const nsWarns = warnings.filter((w) => w.includes('no namespace'));
+   assert.equal(nsWarns.length, 1, 'namespace warning fired exactly once');
+});
+
+test('no-namespace warning is silent in loose mode (no registry)', () => {
+   warnings.length = 0;
+   const em = new EventManager();
+   em.emit('ready'); // nobody registered -> loose mode, no warnings at all
+   assert.equal(warnings.length, 0);
+});
+
+test('loadGraph stores the static graph and exposes emitters/listeners', () => {
+   const em = new EventManager();
+   assert.deepEqual(em.staticEmittersOf('user:login'), [], 'empty before loadGraph');
+   em.loadGraph({
+      events: {
+         'user:login': {
+            payload: { id: 'number' },
+            emitters: [{ file: 'src/Login.js', line: 12, component: 'Login' }],
+            listeners: [{ file: 'src/Header.js', line: 5, component: 'Header' }],
+         },
+      },
+      dynamic: { emitters: [], listeners: [] },
+   });
+   assert.equal(em.staticEmittersOf('user:login')[0].component, 'Login');
+   assert.equal(em.staticListenersOf('user:login')[0].component, 'Header');
+   assert.deepEqual(em.staticEmittersOf('unknown:event'), []);
+});
+
+test('loadGraph ignores malformed input', () => {
+   const em = new EventManager();
+   em.loadGraph(null);
+   em.loadGraph({ nope: true });
+   assert.equal(em.graph, null);
+});
+
+test('undeclared usage is tracked for the debugger drift view', () => {
+   warnings.length = 0;
+   const em = new EventManager();
+   em.register({ 'declared:ok': { payload: null } });
+   em.emit('drifted:event');
+   assert.ok(em.undeclared.has('drifted:event'), 'drift set records undeclared usage');
+   assert.ok(!em.undeclared.has('declared:ok'), 'declared events are not drift');
+});

package/Slice/tests/fixtures/real-runtime-loader.mjs

@@ -1,21 +1,21 @@
-// Node ESM resolve hook so the REAL Controller can load under `node --test`.
-//
-// Controller.js does `import components from '/Components/components.js'` — a
-// browser-absolute path that the dev server serves but node can't resolve. We
-// map only that exact specifier to a small fixture components map (just data,
-// the same shape the real components.js exports). Everything else resolves
-// normally, so the tests exercise the real Slice + Controller code, not mocks.
-// AppProbe lives in a CUSTOM category ('AppServices') whose type is 'Service' —
-// it must be allowed as a singleton (the type, not the category name, decides).
-const COMPONENTS = { Probe: 'Service', ModalProbe: 'Visual', AppProbe: 'AppServices' };
-const STUB = `export default ${JSON.stringify(COMPONENTS)};`;
-
-export async function resolve(specifier, context, nextResolve) {
-   if (specifier === '/Components/components.js') {
-      return {
-         url: `data:text/javascript,${encodeURIComponent(STUB)}`,
-         shortCircuit: true
-      };
-   }
-   return nextResolve(specifier, context);
-}
+// Node ESM resolve hook so the REAL Controller can load under `node --test`.
+//
+// Controller.js does `import components from '/Components/components.js'` — a
+// browser-absolute path that the dev server serves but node can't resolve. We
+// map only that exact specifier to a small fixture components map (just data,
+// the same shape the real components.js exports). Everything else resolves
+// normally, so the tests exercise the real Slice + Controller code, not mocks.
+// AppProbe lives in a CUSTOM category ('AppServices') whose type is 'Service' —
+// it must be allowed as a singleton (the type, not the category name, decides).
+const COMPONENTS = { Probe: 'Service', ModalProbe: 'Visual', AppProbe: 'AppServices' };
+const STUB = `export default ${JSON.stringify(COMPONENTS)};`;
+
+export async function resolve(specifier, context, nextResolve) {
+   if (specifier === '/Components/components.js') {
+      return {
+         url: `data:text/javascript,${encodeURIComponent(STUB)}`,
+         shortCircuit: true
+      };
+   }
+   return nextResolve(specifier, context);
+}

package/Slice/tests/leak-orphans.test.js

@@ -0,0 +1,131 @@
+// Real-Controller tests for the dev-mode leak detector (findOrphans + criteria).
+// Loads the REAL Controller via the resolve hook (same pattern as
+// destroy-cascade.test.js) and drives it with a minimal fake DOM. Fake nodes are
+// made `instanceof HTMLElement` because findOrphans filters on that.
+import { register } from 'node:module';
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+globalThis.alert = () => {};
+register(new URL('./fixtures/real-runtime-loader.mjs', import.meta.url));
+
+globalThis.HTMLElement = class HTMLElement {};
+globalThis.slice = {
+   logger: { logError() {}, logWarning() {}, logInfo() {} },
+   events: null,
+};
+
+const { default: Controller } = await import('../Components/Structural/Controller/Controller.js');
+
+function mkEl(sliceId, children = []) {
+   return Object.assign(Object.create(HTMLElement.prototype), {
+      sliceId,
+      tagName: 'SLICE-X',
+      isConnected: true,
+      parentComponent: null,
+      _children: children,
+      querySelectorAll() {
+         const out = [];
+         const walk = (n) => { for (const c of n._children) { out.push(c); walk(c); } };
+         walk(this);
+         return out;
+      },
+      setAttribute() {},
+      remove() { this.isConnected = false; },
+   });
+}
+
+function flatten(root) {
+   const out = [root];
+   for (const c of root._children) out.push(...flatten(c));
+   return out;
+}
+
+function buildTree(controller, root) {
+   for (const node of flatten(root)) controller.registerComponent(node);
+   controller.registerComponentsRecursively(root);
+}
+
+test('a built-then-detached component (no destroy) IS flagged', () => {
+   const c = new Controller();
+   const comp = mkEl('leaky');
+   buildTree(c, comp);
+   comp.isConnected = false; // simulate innerHTML='' / remove() without destroyComponent
+
+   const orphans = c.findOrphans();
+   assert.equal(orphans.length, 1, 'one orphan');
+   assert.equal(orphans[0].sliceId, 'leaky');
+   assert.ok(orphans[0].retainPath.includes('Object(leaky)') || orphans[0].retainPath.length >= 1);
+});
+
+test('a connected component is NOT flagged', () => {
+   const c = new Controller();
+   const comp = mkEl('alive');
+   buildTree(c, comp);
+   assert.equal(c.findOrphans().length, 0);
+});
+
+test('__sliceCached components are excluded (Route/MultiRoute cache)', () => {
+   const c = new Controller();
+   const comp = mkEl('cachedView');
+   buildTree(c, comp);
+   comp.isConnected = false;
+   comp.__sliceCached = true;
+   assert.equal(c.findOrphans().length, 0);
+});
+
+test('router-managed route-* sliceIds are excluded', () => {
+   const c = new Controller();
+   const comp = mkEl('route-Home');
+   buildTree(c, comp);
+   comp.isConnected = false;
+   assert.equal(c.findOrphans().length, 0);
+});
+
+test('ancestor de-dup: only the detached root is reported', () => {
+   const c = new Controller();
+   const child = mkEl('child');
+   const parent = mkEl('parent', [child]);
+   buildTree(c, parent);
+   parent.isConnected = false;
+   child.isConnected = false;
+
+   const orphans = c.findOrphans();
+   assert.equal(orphans.length, 1, 'only the root, not the descendant');
+   assert.equal(orphans[0].sliceId, 'parent');
+});
+
+test('descendants of a cached subtree are NOT flagged', () => {
+   const c = new Controller();
+   const child = mkEl('child');
+   const parent = mkEl('parent', [child]);
+   buildTree(c, parent);
+   parent.__sliceCached = true; // cached route root
+   parent.isConnected = false;
+   child.isConnected = false;
+   assert.equal(c.findOrphans().length, 0);
+});
+
+test('app-registered exclusion predicate is honored', () => {
+   const c = new Controller();
+   const comp = mkEl('special');
+   buildTree(c, comp);
+   comp.isConnected = false;
+   c.registerLeakExclusion((node) => node.sliceId === 'special');
+   assert.equal(c.findOrphans().length, 0);
+});
+
+test('growth heuristic trips on monotonic increase and resets on shrink', () => {
+   const c = new Controller();
+   assert.equal(c.isGrowthMonotonic(), false, 'needs >= 5 samples');
+
+   for (let i = 0; i < 5; i++) {
+      c.registerComponent(mkEl(`g${i}`));
+      c.sampleComponentGrowth();
+   }
+   assert.equal(c.isGrowthMonotonic(), true, 'sizes 1..5 are monotonic growth');
+
+   c.destroyComponent('g4');
+   c.sampleComponentGrowth(); // size dips
+   assert.equal(c.isGrowthMonotonic(), false, 'a shrink breaks the monotonic signal');
+});