🔤

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`