zone5 0.0.0 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Christian Wygoda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,258 @@
+# Zone5
+
+Image gallery system for SvelteKit with optimized image processing, lightbox functionality, and MDX support.
+
+## Features
+
+- 🖼️ Optimized image processing with variants, blurhash, and color extraction
+- 🔍 Lightbox component with keyboard navigation
+- 📝 MDX integration for markdown-based galleries
+- 🎨 Tailwind CSS 4 support
+- ⚡ Vite plugin for automatic image processing
+- 🛠️ CLI tool for quick project scaffolding
+
+## CLI Tool
+
+The `zone5` CLI tool helps you quickly create a new SvelteKit gallery project:
+
+```bash
+npx zone5 create <input-folder> <output-folder> [options]
+```
+
+### Options
+
+- `-m, --mode <type>` - How to handle images: copy, link, or move (default: copy)
+- `-p, --package-manager <pm>` - Package manager: npm, pnpm, yarn, bun, or skip (default: npm)
+- `--no-interactive` - Skip prompts and use defaults
+
+### Example
+
+```bash
+npx zone5 create ./my-photos ./my-gallery --package-manager pnpm
+```
+
+## Usage in SvelteKit Projects
+
+### Installation
+
+```bash
+npm install zone5
+```
+
+### Basic Setup
+
+1. Add the Vite plugin to your `vite.config.ts`:
+
+```typescript
+import { sveltekit } from '@sveltejs/kit/vite';
+import { zone5 } from 'zone5/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+ plugins: [zone5(), sveltekit()],
+});
+```
+
+2. Wrap your layout with `Zone5Provider`:
+
+```svelte
+<script>
+ import { Zone5Provider } from 'zone5/components';
+</script>
+
+<Zone5Provider>
+ <slot />
+</Zone5Provider>
+```
+
+3. Create a `.zone5.toml` config file:
+
+```toml
+[base]
+root = "src/routes"
+cache = ".zone5"
+namespace = "@zone5"
+
+[processor]
+widths = [400, 800, 1200, 1600, 2400]
+```
+
+### Using in Components
+
+```svelte
+<script>
+ import { Zone5 } from 'zone5/components';
+
+ import image1 from './photo1.jpg?z5';
+ import image2 from './photo2.jpg?z5';
+</script>
+
+<Zone5 images={[image1, image2]} />
+```
+
+### Using in Markdown/MDX
+
+Add the remark plugin to your `svelte.config.js`:
+
+```javascript
+import { remarkZ5Images } from 'zone5/remark';
+import { mdsvex } from 'mdsvex';
+
+export default {
+ preprocess: [
+  mdsvex({
+   extensions: ['.md'],
+   remarkPlugins: [remarkZ5Images],
+  }),
+ ],
+};
+```
+
+Then simply reference images with the `?z5` query parameter:
+
+```markdown
+![Mountain view](./mountains.jpg?z5)
+![Beach sunset](./beach.jpg?z5)
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js 18+
+- pnpm (recommended package manager)
+
+### Getting Started
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run development server
+pnpm dev
+
+# Run tests in watch mode
+pnpm test --watch
+
+# Type check
+pnpm check
+```
+
+### Project Structure
+
+```
+src/
+├── lib/                    # Main library code
+│   ├── components/         # Svelte components
+│   ├── processor/          # Image processing pipeline
+│   ├── vite.ts            # Vite plugin
+│   ├── remark.ts          # Remark MDX plugin
+│   └── config.ts          # Configuration loader
+├── cli/                   # CLI tool
+└── routes/                # Demo/documentation site
+```
+
+### Testing
+
+The project uses a comprehensive test suite organized by purpose:
+
+#### `pnpm test` - Unit Tests (⚡ ~2.7s)
+
+Fast unit tests for core functionality:
+
+- Component tests (portal)
+- Processor tests (blurhash, color, variants, exif)
+- Remark plugin tests
+
+**Use this during development** for quick feedback on code changes.
+
+To run a single test file:
+
+```bash
+pnpm vitest src/lib/processor/blurhash.test.ts
+```
+
+#### `pnpm test:ui` - Integration UI Tests
+
+Playwright tests on the local project (currently placeholder for future tests).
+
+#### `pnpm test:cli` - CLI Integration Tests (~47.8s)
+
+Integration tests for CLI functionality:
+
+- Project creation and configuration
+- Package manager support (npm, pnpm, yarn, bun)
+- Template file generation
+- Utility functions
+
+**Run this before committing** CLI-related changes.
+
+#### `pnpm test:e2e` - End-to-End Tests (~24.1s)
+
+Playwright E2E tests that validate the complete workflow:
+
+- Creates a new project using the CLI
+- Builds the generated project
+- Tests the lightbox UI functionality
+- Validates Tailwind CSS integration
+
+**Run this to verify** the complete user experience.
+
+#### `pnpm test:all` - All Tests (~74.6s)
+
+Runs all test suites in sequence: unit → CLI → E2E.
+
+**Run this before releases** to ensure everything works together.
+
+### Build Commands
+
+```bash
+pnpm dev           # Watch mode for development (full demo site)
+pnpm build         # Build the package (runs svelte-package + CLI build + publint)
+pnpm build:cli     # Build just the CLI tool
+pnpm build:watch   # Build the package in watch mode
+pnpm check         # Type checking with svelte-check
+pnpm check:watch   # Type checking in watch mode
+pnpm lint          # Run ESLint
+```
+
+### Architecture Overview
+
+Zone5 consists of four main components:
+
+1. **Image Processor** (`src/lib/processor/`) - Uses Sharp to generate image variants, extract EXIF data, create blurhashes, and determine dominant colors. Results are cached in `.zone5/` directory.
+
+2. **Vite Plugin** (`src/lib/vite.ts`) - Intercepts `.jpg?z5` imports at build time, processes images, and serves them during development.
+
+3. **Remark Plugin** (`src/lib/remark.ts`) - Transforms markdown images with `?z5` query parameters into Zone5 Svelte components.
+
+4. **Component System** (`src/lib/components/`) - Svelte 5 components with a centralized registry for managing lightbox state and navigation across multiple galleries.
+
+See [CLAUDE.md](./CLAUDE.md) for detailed architecture documentation.
+
+### Contributing
+
+1. Make your changes
+2. Run `pnpm test` to ensure unit tests pass
+3. Run `pnpm check` to verify types
+4. Run `pnpm lint` to check code style
+5. If you changed the CLI, run `pnpm test:cli`
+6. Before submitting, run `pnpm test:all` to validate everything
+
+**Commit Messages:**
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/). Commit messages are validated via Husky hooks.
+
+Format: `<type>: <description>`
+
+Valid types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+
+Examples:
+
+- `feat: add lightbox keyboard navigation`
+- `fix: resolve EXIF parsing error`
+- `docs: update installation instructions`
+
+## License
+
+MIT

package/dist/cli/index.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { Command as s } from "commander";
+import { readFileSync as c } from "node:fs";
+import { dirname as l, join as d } from "node:path";
+import { fileURLToPath as g } from "node:url";
+import n from "picocolors";
+import { createProject as f } from "./index2.js";
+const u = l(g(import.meta.url)), k = JSON.parse(c(d(u, "../../package.json"), "utf-8")), t = new s();
+t.name("zone5").description("Image gallery system for SvelteKit").version(k.version);
+t.command("create").description("Create a new SvelteKit project with zone5 image processing").argument("<input-folder>", "Path to folder containing images").argument("<output-folder>", "Path where the new project will be created").option("-m, --mode <type>", "How to handle images: copy, link, or move", "copy").option(
+  "-p, --package-manager <pm>",
+  "Package manager to use: npm, pnpm, yarn, bun, or skip to not install",
+  "npm"
+).option("--no-interactive", "Skip prompts and use defaults").action(async (a, i, p) => {
+  const { mode: e, packageManager: o, interactive: m } = p;
+  ["copy", "link", "move"].includes(e) || (console.error(n.red(`Error: Invalid mode "${e}". Must be one of: copy, link, move`)), process.exit(1)), ["npm", "pnpm", "yarn", "bun", "skip"].includes(o) || (console.error(
+    n.red(
+      `Error: Invalid package manager "${o}". Must be one of: npm, pnpm, yarn, bun, skip`
+    )
+  ), process.exit(1));
+  try {
+    await f({
+      inputFolder: a,
+      outputFolder: i,
+      mode: e,
+      packageManager: o,
+      interactive: m
+    });
+  } catch (r) {
+    console.error(n.red("Error:"), r instanceof Error ? r.message : String(r)), process.exit(1);
+  }
+});
+t.parse();

package/dist/cli/index2.js

@@ -0,0 +1,238 @@
+import f from "fs-extra";
+import { execSync as C } from "node:child_process";
+import { mkdir as h, writeFile as p, copyFile as j, symlink as x, rename as S } from "node:fs/promises";
+import { dirname as $, join as n, resolve as w, basename as u } from "node:path";
+import { fileURLToPath as z } from "node:url";
+import D from "ora";
+import l from "picocolors";
+import I from "prompts";
+import { pathExists as k, isDirectory as b, findImagesRecursive as J } from "./index3.js";
+const T = $(z(import.meta.url)), g = n(T, "templates");
+async function X(e) {
+  const { inputFolder: i, outputFolder: o, mode: s, packageManager: a, interactive: d } = e, c = w(i), r = w(o);
+  console.log(l.bold(`
+🖼️  zone5
+`));
+  const t = D("Validating input folder...").start();
+  if (!await k(c))
+    throw t.fail(`Input folder does not exist: ${c}`), new Error("Input folder not found");
+  if (!await b(c))
+    throw t.fail(`Input path is not a directory: ${c}`), new Error("Input path must be a directory");
+  t.text = "Scanning for images...";
+  const m = await J(c);
+  if (m.length === 0)
+    throw t.fail("No images found in input folder"), new Error("No images found");
+  if (t.succeed(`Found ${l.cyan(m.length.toString())} images`), await k(r))
+    throw t.fail(`Output folder already exists: ${r}`), new Error("Output folder must not exist");
+  if (d) {
+    const { confirmed: y } = await I({
+      type: "confirm",
+      name: "confirmed",
+      message: `Create project at ${l.cyan(r)} with ${l.cyan(m.length.toString())} images (mode: ${l.yellow(s)})?`,
+      initial: !0
+    });
+    y || (console.log(l.dim("Cancelled")), process.exit(0));
+  }
+  t.start("Creating SvelteKit project..."), await P(r), t.succeed("Created SvelteKit project"), t.start("Adding dependencies to package.json..."), await L(r), t.succeed("Added dependencies to package.json"), a === "skip" ? t.info("Skipped dependency installation") : (t.start("Installing dependencies..."), await N(r, a), t.succeed("Installed dependencies")), t.start(
+    `${s === "copy" ? "Copying" : s === "link" ? "Linking" : "Moving"} images...`
+  );
+  const v = n(r, "src", "routes");
+  if (await f.ensureDir(v), await E(m, c, v, s), t.succeed(
+    `${s === "copy" ? "Copied" : s === "link" ? "Linked" : "Moved"} ${m.length} images`
+  ), t.start("Generating gallery page..."), await F(v, m), t.succeed("Generated gallery page"), t.start("Adding template files..."), await A(r), t.succeed("Added template files"), t.start("Configuring Vite..."), await M(r), t.succeed("Configured Vite"), t.start("Configuring Svelte..."), await R(r), t.succeed("Configured Svelte"), t.start("Configuring Tailwind..."), await Z(r), t.succeed("Configured Tailwind"), t.start("Creating zone5 config..."), await _(r), t.succeed("Created zone5 config"), a !== "skip" && (t.start("Running svelte-kit sync..."), await O(r, a), t.succeed("Ran svelte-kit sync")), console.log(l.green(`
+✓ Project created successfully!
+`)), console.log("Next steps:"), console.log(l.cyan(`  cd ${u(r)}`)), a === "skip")
+    console.log(l.cyan("  npm install  # or your preferred package manager")), console.log(l.cyan("  npm run dev"));
+  else {
+    const y = a === "npm" ? "npm run dev" : `${a} dev`;
+    console.log(l.cyan(`  ${y}`));
+  }
+  console.log();
+}
+async function P(e) {
+  await h(e, { recursive: !0 });
+  const i = {
+    name: u(e),
+    version: "0.0.1",
+    private: !0,
+    type: "module",
+    scripts: {
+      dev: "vite dev",
+      build: "vite build",
+      preview: "vite preview"
+    },
+    devDependencies: {},
+    dependencies: {}
+  };
+  await p(n(e, "package.json"), JSON.stringify(i, null, "	")), await f.ensureDir(n(e, "src", "routes")), await f.ensureDir(n(e, "static")), await p(n(e, "src", "app.html"), `<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		%sveltekit.head%
+	</head>
+	<body data-sveltekit-preload-data="hover">
+		<div style="display: contents">%sveltekit.body%</div>
+	</body>
+</html>
+`);
+}
+async function L(e) {
+  const i = n(e, "package.json"), o = JSON.parse(await f.readFile(i, "utf-8"));
+  o.devDependencies = {
+    "@lucide/svelte": "^0.553.0",
+    "@sveltejs/adapter-static": "^3.0.0",
+    "@sveltejs/kit": "^2.0.0",
+    "@sveltejs/vite-plugin-svelte": "^6.0.0",
+    "@tailwindcss/vite": "^4.0.0",
+    zone5: "latest",
+    mdsvex: "^0.12.0",
+    svelte: "^5.0.0",
+    tailwindcss: "^4.0.0",
+    typescript: "^5.0.0",
+    vite: "^7.0.0"
+  };
+  const s = process.env.ZONE5_LOCAL_PATH;
+  if (s) {
+    const a = w(s);
+    o.devDependencies.zone5 = `file:${a}`;
+  }
+  await p(i, JSON.stringify(o, null, "	"));
+}
+async function N(e, i) {
+  C((() => {
+    switch (i) {
+      case "npm":
+        return "npm install";
+      case "pnpm":
+        return "pnpm install";
+      case "yarn":
+        return "yarn install";
+      case "bun":
+        return "bun install";
+    }
+  })(), {
+    cwd: e,
+    stdio: "pipe"
+  }), await p(n(e, "svelte.config.js"), `import adapter from '@sveltejs/adapter-static';
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+	kit: {
+		adapter: adapter()
+	}
+};
+
+export default config;
+`), await p(n(e, "vite.config.ts"), `import { sveltekit } from '@sveltejs/vite-plugin-svelte';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+	plugins: [sveltekit()]
+});
+`);
+  const d = {
+    extends: "./.svelte-kit/tsconfig.json",
+    compilerOptions: {
+      allowJs: !0,
+      checkJs: !0,
+      esModuleInterop: !0,
+      forceConsistentCasingInFileNames: !0,
+      resolveJsonModule: !0,
+      skipLibCheck: !0,
+      sourceMap: !0,
+      strict: !0,
+      moduleResolution: "bundler"
+    }
+  };
+  await p(n(e, "tsconfig.json"), JSON.stringify(d, null, "	"));
+}
+async function O(e, i) {
+  C((() => {
+    switch (i) {
+      case "npm":
+        return "npx svelte-kit sync";
+      case "pnpm":
+        return "pnpm exec svelte-kit sync";
+      case "yarn":
+        return "yarn svelte-kit sync";
+      case "bun":
+        return "bunx svelte-kit sync";
+    }
+  })(), {
+    cwd: e,
+    stdio: "pipe"
+  });
+}
+async function E(e, i, o, s) {
+  for (const { path: a, relativePath: d } of e) {
+    const c = n(o, u(d));
+    s === "copy" ? await j(a, c) : s === "link" ? await x(a, c) : s === "move" && await S(a, c);
+  }
+}
+async function F(e, i) {
+  const s = `# Photo Gallery
+
+${i.map(({ relativePath: a }) => {
+    const d = u(a);
+    return `![${d.replace(/\.[^.]+$/, "")}](./${d}?z5)`;
+  }).join(`
+`)}
+`;
+  await p(n(e, "+page.md"), s);
+}
+async function A(e) {
+  const i = n(g, "layout.svelte"), o = n(e, "src", "routes", "+layout.svelte");
+  await f.copy(i, o);
+  const s = n(g, "app.css"), a = n(e, "src", "app.css");
+  await f.copy(s, a);
+  const d = n(g, "layout.ts"), c = n(e, "src", "routes", "+layout.ts");
+  await f.copy(d, c);
+}
+async function M(e) {
+  const i = n(e, "vite.config.ts");
+  await p(i, `import { sveltekit } from '@sveltejs/kit/vite';
+import tailwindcss from '@tailwindcss/vite';
+import { zone5 } from 'zone5/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+	plugins: [tailwindcss(), zone5(), sveltekit()]
+});
+`);
+}
+async function R(e) {
+  const i = n(e, "svelte.config.js");
+  await p(i, `import adapter from '@sveltejs/adapter-static';
+import { mdsvex } from 'mdsvex';
+import { remarkZ5Images } from 'zone5/remark';
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+	extensions: ['.svelte', '.md'],
+	preprocess: [
+		mdsvex({
+			extensions: ['.md'],
+			remarkPlugins: [remarkZ5Images]
+		})
+	],
+	kit: {
+		adapter: adapter()
+	}
+};
+
+export default config;
+`);
+}
+async function Z(e) {
+  await p(n(e, "tailwind.config.ts"), `/** @type {import('tailwindcss').Config} */
+export default {};
+`);
+}
+async function _(e) {
+  const i = n(g, ".zone5.toml"), o = n(e, ".zone5.toml");
+  await f.copy(i, o);
+}
+export {
+  X as createProject
+};

package/dist/cli/index3.js

@@ -0,0 +1,53 @@
+import { constants as o } from "node:fs";
+import { access as c, stat as f, readdir as u } from "node:fs/promises";
+import { join as p, extname as h } from "node:path";
+const m = /* @__PURE__ */ new Set([
+  ".jpg",
+  ".jpeg",
+  ".png",
+  ".webp",
+  ".avif",
+  ".gif",
+  ".tiff",
+  ".tif",
+  ".heic",
+  ".heif"
+]);
+async function I(t) {
+  try {
+    return await c(t, o.F_OK), !0;
+  } catch {
+    return !1;
+  }
+}
+async function x(t) {
+  try {
+    return (await f(t)).isDirectory();
+  } catch {
+    return !1;
+  }
+}
+function l(t) {
+  const a = h(t).toLowerCase();
+  return m.has(a);
+}
+async function g(t, a = t) {
+  const r = await u(t, { withFileTypes: !0 }), i = [];
+  for (const e of r) {
+    const s = p(t, e.name);
+    if (e.isFile() && l(e.name)) {
+      const n = s.replace(a + "/", "");
+      i.push({ path: s, relativePath: n });
+    } else if (e.isDirectory()) {
+      const n = await g(s, a);
+      i.push(...n);
+    }
+  }
+  return i.sort((e, s) => e.relativePath.localeCompare(s.relativePath));
+}
+export {
+  g as findImagesRecursive,
+  x as isDirectory,
+  l as isImage,
+  I as pathExists
+};

package/dist/cli/templates/.zone5.toml

@@ -0,0 +1,4 @@
+# Zone5 Configuration
+
+[processor]
+variants = [640, 768, 1280, 1920, 2560]

package/dist/cli/templates/app.css

@@ -0,0 +1,3 @@
+@import 'tailwindcss';
+
+@source '../node_modules/zone5/dist';

package/dist/cli/templates/layout.svelte

@@ -0,0 +1,15 @@
+<script lang="ts">
+	import { Zone5Provider } from 'zone5/components';
+
+	import '../app.css';
+
+	const { children } = $props();
+</script>
+
+<Zone5Provider>
+	<div class="min-h-screen bg-gray-50">
+		<main class="container mx-auto px-4 py-8">
+			{@render children()}
+		</main>
+	</div>
+</Zone5Provider>

package/dist/cli/templates/layout.ts

@@ -0,0 +1 @@
+export const prerender = true;