Merge pull request #15 from bholmesdev/refactor/migrate-simple-scope

Migrate vite-plugin-simple-scope to the stack

Author: bholmesdev

README.md

@@ -8,7 +8,8 @@ Simple stack is a suite of tools built for [Astro](https://astro.build) to simpl
 
 Simple stack offers a growing collection of packages:
 
-- **[Simple form](https://github.com/bholmesdev/simple-stack/tree/main/packages/form):** A full stack solution to validate forms with your client framework of choice.
+- **[🧘‍♂️ Simple form](https://github.com/bholmesdev/simple-stack/tree/main/packages/form):** A full stack solution to validate forms with your client framework of choice.
+- **[🔎 Simple scope](https://github.com/bholmesdev/simple-stack/tree/main/packages/scope):** Get a scoped ID for any file you're in. Perfect for form label IDs and query selectors.
 - **[⏳ WIP: Simple partial](https://github.com/bholmesdev/simple-stack/tree/main/packages/partial):** Re-render just the parts that change in your Astro app.
 
 ## Get involved

package.json

@@ -15,7 +15,7 @@
 		"format:write": "biome format --write"
 	},
 	"keywords": ["withastro"],
-	"author": "@bholmesdev",
+	"author": "bholmesdev",
 	"license": "MIT",
 	"devDependencies": {
 		"@biomejs/biome": "^1.4.1",

packages/scope/README.md

@@ -0,0 +1,86 @@
+# simple scope 🔎
+
+Get a scoped ID for whatever file you're in. Resolved at build-time with zero client JS.
+
+```jsx
+import { scope } from 'simple:scope';
+
+function Form() {
+  return (
+    <form>
+      <label htmlFor={scope('email')}>Email</label>
+      <input id={scope('email')} name="email" />
+    </form>
+  );
+}
+
+/*
+Output:
+
+<form>
+  <label for="email-dj23i_ka">Email</label>
+  <input id="email-dj23i_ka" name="email">
+</form>
+*/
+```
+
+## Installation
+
+Simple scope is a vite plugin compatible with any vite-based framework (Astro, Nuxt, SvelteKit, etc). First install the dependency from npm:
+
+```bash
+npm i vite-plugin-simple-scope
+```
+
+Then, set up type inferencing for the `simple:scope` module with an `env.d.ts` file. You can create this file at the base of your project, or add to the provided `src/env.d.ts` file for frameworks like Astro:
+
+```ts
+// env.d.ts
+/// <reference types="vite-plugin-simple-scope/types" />
+```
+
+Finally, apply as a vite plugin in your framework of choice:
+
+```js
+import simpleScope from 'vite-plugin-simple-scope';
+
+// apply `simpleScope()` to your vite plugin config
+```
+
+- [Astro vite plugin configuration](https://docs.astro.build/en/recipes/add-yaml-support/)
+- [Nuxt vite plugin configuration](https://nuxt.com/docs/getting-started/configuration#external-configuration-files)
+- [SvelteKit vite plugin configuration](https://kit.svelte.dev/docs/project-structure#project-files-vite-config-js)
+
+## Usage
+
+You can import the `scope()` utility from `simple:scope` in any JavaScript-based file. This function accepts an optional prefix string for naming different scoped identifiers.
+
+Since `scope()` uses the file path to generate IDs, multiple calls to `scope()` will append the same value:
+
+```js
+// example.js
+
+scope(); // JYZeLezU
+scope('first'); // first-JYZeLezU
+scope('second'); // second-JYZeLezU
+```
+
+Simple scope will also generate the same ID when called server-side or client-side. This prevents hydration mismatches when using component frameworks like React or Vue, and is helpful when querying scoped element `id`s from the DOM.
+
+This example uses [Astro](https://astro.build) to add a scoped `id` to a `<canvas>` element, and queries that `id` from a client-side `<script>`:
+
+```astro
+---
+// Server-side template
+import { scope } from 'simple:scope';
+---
+
+<canvas id={scope('canvas')}></canvas>
+
+<script>
+// Client-side script
+import { scope } from 'simple:scope';
+
+const canvas = document.getElementById(scope('canvas'));
+</script>
+```

packages/scope/index.js

@@ -0,0 +1,44 @@
+import { nanoid } from "nanoid";
+
+const virtualMod = "simple:scope";
+
+/** @returns {import('vite').Plugin} */
+export default function simpleScope() {
+	/** @type {Record<string, string>} */
+	const scopeIdByImporter = {};
+
+	return {
+		name: "vite-plugin-simple-scope",
+		resolveId(id, rawImporter) {
+			if (id !== virtualMod || !rawImporter) return;
+
+			const importer = getBaseFilePath(rawImporter);
+			if (!scopeIdByImporter[importer]) {
+				scopeIdByImporter[importer] = nanoid(8);
+			}
+			return `${virtualMod}/${scopeIdByImporter[importer]}`;
+		},
+		async load(id) {
+			const [maybeVirtualMod, scopeId] = id.split("/");
+			if (maybeVirtualMod !== virtualMod || !scopeId) return;
+
+			return `const scopeId = ${JSON.stringify(scopeId)};
+export function scope(id) {
+    if (!id) return scopeId;
+
+    return id + '-' + scopeId;
+}`;
+		},
+	};
+}
+
+/**
+ * Vite supports file search params with `?`.
+ * Trim these off to get the base file path.
+ *
+ * @param {string} filePath
+ * @returns {string}
+ */
+function getBaseFilePath(filePath) {
+	return filePath.replace(/\?.*$/, "");
+}

packages/scope/package.json

@@ -0,0 +1,29 @@
+{
+	"name": "vite-plugin-simple-scope",
+	"version": "1.0.3",
+	"description": "Get a scoped ID for whatever file you're in. Zero client-side JS.",
+	"type": "module",
+	"exports": {
+		".": "./index.js",
+		"./types": "./types.d.ts"
+	},
+	"files": ["types.d.ts", "index.js"],
+
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/bholmesdev/simple-stack.git",
+		"directory": "packages/scope"
+	},
+	"scripts": {},
+	"dependencies": {
+		"nanoid": "^5.0.3"
+	},
+	"devDependencies": {
+		"vite": "^4.5.0"
+	},
+	"author": "bholmesdev",
+	"license": "MIT",
+	"engines": {
+		"node": ">=18.14.1"
+	}
+}

packages/scope/tsconfig.json

@@ -0,0 +1,10 @@
+{
+	"compilerOptions": {
+		"checkJs": true,
+		"module": "ESNext",
+		"moduleResolution": "Node",
+		"target": "ESNext",
+		"noEmit": true,
+		"strict": true
+	}
+}

packages/scope/types.d.ts

@@ -0,0 +1,3 @@
+declare module "simple:scope" {
+	export function scope(prefix?: string): string;
+}