From 05413cb2bb008ef27cddce99fb6ddbb4daf2321f Mon Sep 17 00:00:00 2001
From: Jan Andrle <andrle.jan@centrum.cz>
Date: Wed, 5 Mar 2025 18:59:37 +0100
Subject: [PATCH] :abc:

---
 docs/components/examples/scopes/mixed.js | 20 +++++---
 docs/p05-scopes.html.js                  | 65 ++++++++++++++++++++++++
 index.d.ts                               |  2 +-
 3 files changed, 78 insertions(+), 9 deletions(-)

diff --git a/docs/components/examples/scopes/mixed.js b/docs/components/examples/scopes/mixed.js
index e1d4c56..f2b606c 100644
--- a/docs/components/examples/scopes/mixed.js
+++ b/docs/components/examples/scopes/mixed.js
@@ -13,16 +13,20 @@ function Counter() {
 		count.set(count.get() + 1);
 		// NEVER EVER
 		// count = S(count.get() + 1);
+		// THE HOST IS PROBABLY DIFFERENT THAN
+		// YOU EXPECT AND SIGNAL MAY BE
+		// UNEXPECTEDLY REMOVED!!!
 		host().querySelector("button").disabled = count.get() >= 10;
 	};
-	// NEVER EVER
-	// setTimeout(()=> {
-	//	const wrong= S(0);
-	//  // THE HOST IS PROBABLY DIFFERENT THAN
-	//  // YOU EXPECT AND OBSERVABLES MAY BE
-	//  // UNEXPECTEDLY REMOVED!!!
-	//	counterText.textContent= "Count: " + wrong.get();
-	// }, 1000);
+	setTimeout(()=> {
+		// ok, BUT consider extract to separate function
+		// see section below for more info
+		scope.push();
+		const ok= S(0);
+		scope.pop();
+		S.on(ok, console.log);
+		setInterval(()=> ok.set(ok.get() + 1), 100);
+	}, 100);
 
 	return el("div").append(
 		counterText,
diff --git a/docs/p05-scopes.html.js b/docs/p05-scopes.html.js
index 4735f9f..88be318 100644
--- a/docs/p05-scopes.html.js
+++ b/docs/p05-scopes.html.js
@@ -157,6 +157,71 @@ function MyComponent() {
 			),
 		),
 
+		el(h3, t`Advanced: Custom Scoping Control`),
+		el("p").append(...T`
+			In more complex applications, you may need finer control over scopes. DDE provides
+			manual scope control mechanisms through ${el("code", "scope.push()")} and ${el("code", "scope.pop()")}.
+		`),
+		el("div", { className: "function-table" }).append(
+			el("h4", t`Manual Scope Control API`),
+			el("dl").append(
+				el("dt", t`scope.push()`),
+				el("dd", t`Creates a new scope and makes it the current active scope. All signals and subscriptions
+					created after this call will be associated with this new scope.`),
+
+				el("dt", t`scope.pop()`),
+				el("dd", t`Restores the previous scope that was active before the matching push() call.`),
+
+				el("dt", t`scope.current()`),
+				el("dd", t`Returns the currently active scope object.`),
+
+				el("dt", t`scope.withScope(callback)`),
+				el("dd", t`Executes the callback function within a temporary scope, then automatically restores the previous scope.
+					Safer than manual push/pop for most use cases.`)
+			)
+		),
+		el("p").append(...T`
+			Custom scoping is particularly useful for:
+		`),
+		el("ul").append(
+			el("li", t`Isolating signal dependencies in async operations`),
+			el("li", t`Creating detached reactive logic that shouldn't be tied to a component's lifecycle`),
+			el("li", t`Building utilities that work with signals but need scope isolation`)
+		),
+		el(code, { content: `// Inside a component
+function SomeComponent() {
+  // Create an isolated scope for a specific operation
+  scope.push(); // Start new scope
+
+  // These signals are in the new scope
+  const isolatedCount = S(0);
+  const isolatedDerived = S(() => isolatedCount.get() * 2);
+
+  // Clean up by returning to previous scope
+  scope.pop();
+
+  // Alternative: Use withScope for automatic scope management
+  scope.withScope(() => {
+    // This code runs in an isolated scope
+    const tempSignal = S("temporary");
+
+    // No need for pop() - scope is restored automatically
+  });
+
+  // Rest of component remains in the original scope
+  return el("div");
+}`, page_id }),
+		el("div", { className: "warning" }).append(
+			el("p").append(...T`
+				${el("strong", "Be careful with manual scope control!")} Always ensure you have matching push() and pop() calls,
+				preferably in the same function. Unbalanced scope management can lead to memory leaks or unexpected behavior.
+			`),
+			el("p").append(...T`
+				For most use cases, prefer using the automatic scope management provided by components.
+				Manual scope control should be considered an advanced feature.
+			`)
+		),
+
 		el(h3, t`Best Practices for Scopes and Components`),
 		el("ol").append(
 			el("li").append(...T`
diff --git a/index.d.ts b/index.d.ts
index 5344bbb..d1fdeed 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -232,7 +232,7 @@ export const scope: {
 
 	state: Scope[],
 	/** Adds new child scope. All attributes are inherited by default. */
-	push(scope: Partial<Scope>): ReturnType<Array<Scope>["push"]>,
+	push(scope?: Partial<Scope>): ReturnType<Array<Scope>["push"]>,
 	/** Adds root scope as a child of the current scope. */
 	pushRoot(): ReturnType<Array<Scope>["push"]>,
 	/** Removes last/current child scope. */