refactor: ready -> $.ready

.changeset/neat-chefs-provide.md

@@ -0,0 +1,5 @@
+---
+"simple-stack-query": minor
+---
+
+Change from a global `ready()` block from client scripts to a namespaced `$.ready()` block. Should be safer to avoid collisions with any local variables called `ready`.

packages/query/README.md

@@ -6,7 +6,7 @@ A simple library to query the DOM from your Astro components.
 <button data-target={$('btn')}>Click me</button>
 
 <script>
-  ready(() => {
+  $.ready(() => {
     $('btn').addEventListener('click', () => {
       console.log("It's like JQuery but not!");
     });
@@ -41,15 +41,15 @@ From your client script, the query result will be a plain HTML element. No, it's
 $('btn').addEventListener(() => { /* ... */ });
 ```
 
-You can also pass an `HTMLElement` or `SVGElement` type to access specific properties. For example, use `$<HTMLInputElement>` to access `.value`:
+You can also pass an `HTMLElement` or `SVGElement` type to access specific properties. For example, use `$<HTMLInputElement>()` to access `.value`:
 
 ```ts
 $<HTMLInputElement>('input').value = '';
 ```
 
-### `$.optional` selector
+### `$.optional()` selector
 
-`$` throws when no matching element is found. To avoid this behavior, use `$.optional`:
+`$()` throws when no matching element is found. To avoid this behavior, use `$.optional()`:
 
 ```astro
 ---
@@ -67,9 +67,9 @@ ready(() => {
 </script>
 ```
 
-### `$.all` selector
+### `$.all()` selector
 
-You may want to select multiple targets with the same name. You can use `$.all` to query for an array of results:
+You may want to select multiple targets with the same name. You can use `$.all()` to query for an array of results:
 
 ```astro
 ---
@@ -87,13 +87,13 @@ ready(() => {
 </script>
 ```
 
-## Global `ready()` function
+## Global `$.ready()` function
 
-All `$` queries must be nested in a `ready()` block. This opts in to using the global `$` from client scripts. `ready()` also ensures your code reruns on every page [when view transitions are enabled.](https://docs.astro.build/en/guides/view-transitions/)
+All `$` queries must be nested in a `$.ready()` block. This opts in to using the global `$` from client scripts. `$.ready()` also ensures your code reruns on every page [when view transitions are enabled.](https://docs.astro.build/en/guides/view-transitions/)
 
 ```astro
 <script>
-  ready(() => {
+  $.ready(() => {
     // ✅ Allowed
     $('element').textContent = 'hey';
   })

packages/query/ambient.d.ts

@@ -5,6 +5,5 @@ declare namespace $ {
 	function optional<T extends Element = HTMLElement>(
 		selector: string,
 	): T | undefined;
+	function ready(callback: () => void): void;
 }
-
-declare function ready(callback: () => void): void;

packages/query/fixtures/basic/src/pages/index.astro

@@ -5,4 +5,10 @@ import WithContext from "./WithContext.astro";
 
 <h1 data-target={$('test')}>Hey</h1>
 <Nested />
-<WithContext $context={$} />
+<WithContext $context={$} />
+
+<script>
+  $.ready(() => {
+    $('test').textContent = 'Hello';
+  });
+</script>

packages/query/src/index.ts

@@ -42,8 +42,7 @@ function vitePlugin(): VitePlugin {
     import { scope as __scope } from 'simple:scope';
     import * as __queryInternals from "simple-stack-query/internal";
 
-    const $ = __queryInternals.create$(__scope);
-    const ready = __queryInternals.createReady(__scope);\n${code}`;
+    const $ = __queryInternals.create$(__scope);\n${code}`;
 		},
 	};
 }

packages/query/src/internal.ts

@@ -2,6 +2,10 @@ import type { scope as scopeFn } from "simple:scope";
 import { transitionEnabledOnThisPage } from "astro/virtual-modules/transitions-router.js";
 
 export function create$(scope: typeof scopeFn) {
+	const anyMatchSelector = `[data-target$=${JSON.stringify(scope())}`;
+	function hasScopeElement() {
+		return Boolean(document.querySelector(anyMatchSelector));
+	}
 	function getSelector(scopeId: string) {
 		return `[data-target=${JSON.stringify(scope(scopeId))}]`;
 	}
@@ -20,33 +24,23 @@ export function create$(scope: typeof scopeFn) {
 			const selector = getSelector(scopeId);
 			return [...document.querySelectorAll(selector)];
 		},
+		ready(callback: () => MaybePromise<undefined | (() => void)>) {
+			if (transitionEnabledOnThisPage()) {
+				let cleanup: (() => void) | undefined;
+
+				document.addEventListener("astro:page-load", async () => {
+					if (cleanup) cleanup();
+					if (!hasScopeElement()) return;
+
+					cleanup = await callback();
+				});
+			} else {
+				if (!hasScopeElement()) return;
+				callback();
+			}
+		},
 	});
 	return $;
 }
 
 type MaybePromise<T> = T | Promise<T>;
-
-export function createReady(scope: typeof scopeFn) {
-	const selector = `[data-target$=${JSON.stringify(scope())}`;
-	function hasScopeElement() {
-		return Boolean(document.querySelector(selector));
-	}
-
-	return function ready(
-		callback: () => MaybePromise<undefined | (() => void)>,
-	) {
-		if (transitionEnabledOnThisPage()) {
-			let cleanup: (() => void) | undefined;
-
-			document.addEventListener("astro:page-load", async () => {
-				if (cleanup) cleanup();
-				if (!hasScopeElement()) return;
-
-				cleanup = await callback();
-			});
-		} else {
-			if (!hasScopeElement()) return;
-			callback();
-		}
-	};
-}

www/src/content/docs/query.md

@@ -9,7 +9,7 @@ A simple library to query the DOM from your Astro components.
 <button data-target={$('btn')}>Click me</button>
 
 <script>
-  ready(() => {
+  $.ready(() => {
     $('btn').addEventListener('click', () => {
       console.log("It's like JQuery but not!");
     });
@@ -44,15 +44,15 @@ From your client script, the query result will be a plain HTML element. No, it's
 $('btn').addEventListener(() => { /* ... */ });
 ```
 
-You can also pass an `HTMLElement` or `SVGElement` type to access specific properties. For example, use `$<HTMLInputElement>` to access `.value`:
+You can also pass an `HTMLElement` or `SVGElement` type to access specific properties. For example, use `$<HTMLInputElement>()` to access `.value`:
 
 ```ts
 $<HTMLInputElement>('input').value = '';
 ```
 
-### `$.optional` selector
+### `$.optional()` selector
 
-`$` throws when no matching element is found. To avoid this behavior, use `$.optional`:
+`$()` throws when no matching element is found. To avoid this behavior, use `$.optional()`:
 
 ```astro
 ---
@@ -70,9 +70,9 @@ ready(() => {
 </script>
 ```
 
-### `$.all` selector
+### `$.all()` selector
 
-You may want to select multiple targets with the same name. You can use `$.all` to query for an array of results:
+You may want to select multiple targets with the same name. You can use `$.all()` to query for an array of results:
 
 ```astro
 ---
@@ -90,13 +90,13 @@ ready(() => {
 </script>
 ```
 
-## Global `ready()` function
+## Global `$.ready()` function
 
-All `$` queries must be nested in a `ready()` block. This opts in to using the global `$` from client scripts. `ready()` also ensures your code reruns on every page [when view transitions are enabled.](https://docs.astro.build/en/guides/view-transitions/)
+All `$` queries must be nested in a `$.ready()` block. This opts in to using the global `$` from client scripts. `$.ready()` also ensures your code reruns on every page [when view transitions are enabled.](https://docs.astro.build/en/guides/view-transitions/)
 
 ```astro
 <script>
-  ready(() => {
+  $.ready(() => {
     // ✅ Allowed
     $('element').textContent = 'hey';
   })