swatchkit 0.0.1 → 0.0.3

package/README.md

@@ -1,57 +1,93 @@
 # SwatchKit
 
-**SwatchKit** is a lightweight, zero-configuration tool for creating HTML pattern libraries. It follows the "Magic Folder" principle: you drop files in, and a documentation site comes out.
+**SwatchKit** is a lightweight tool for generating HTML pattern libraries. It acts as a **Pattern Discovery Engine**: it scans your folders for HTML components and stitches them into a documentation site using a layout you control.
 
-## How it works
+It follows the "Magic Folder" principle: drop files in, and a library comes out.
 
-1.  **Drop Patterns:** Add `.html` files (or folders) to `src/patterns/`.
-2.  **Add Styles:** Add standard CSS to `src/css/styles.css`.
-3.  **Build:** Run `node build.js`.
+## Quick Start
 
-## Features
+Try it instantly in any project:
 
-### 1. The Magic Folder
-*   **Single File:** Drop `button.html` into `src/patterns/`. It automatically appears in the library.
-*   **Component Folder:** Drop a folder like `src/patterns/carousel/` containing `index.html`. It works exactly the same way.
+```bash
+# 1. Initialize the layout
+npx swatchkit init
 
-### 2. Automatic JS Bundling
-If your component needs client-side JavaScript, just add a `.js` file to its folder.
-*   Example: `src/patterns/carousel/script.js`
-*   **SwatchKit** will automatically find it, wrap it in an IIFE (to protect scope), and bundle it into the final site. You can have multiple JS files per pattern.
+# 2. Build the library
+npx swatchkit
+```
 
-### 3. Zero Config
-No config files. No build pipelines. No complex templating engines. Just HTML, CSS, and JS.
+This will create a `swatches/` folder and build your site to `public/swatchkit/`.
 
-## Usage
+---
 
-### Using npx (Recommended)
+## Project Setup (Recommended)
 
-Run directly without installing:
-```bash
-npx swatchkit
-```
-
-### Installing locally
+For real projects, install SwatchKit as a development dependency to lock the version.
 
-Install as a dev dependency:
 ```bash
 npm install -D swatchkit
 ```
 
-Then add to your `package.json` scripts:
+Then add it to your `package.json` scripts:
+
 ```json
 "scripts": {
-  "build:patterns": "swatchkit"
+  "patterns": "swatchkit"
 }
 ```
 
-And run:
+## How It Works
+
+### 1. The Magic Folder
+By default, SwatchKit looks for a `swatches/` folder in your project root.
+*   **Single File:** Drop `card.html` into `swatches/`. It appears in the library.
+*   **Component Folder:** Drop a folder like `swatches/carousel/` containing `index.html`. It works the same way.
+
+### 2. Custom Layouts
+When you run `swatchkit init`, we create `swatches/_layout.html`.
+**You own this file.**
+*   Add your own `<link rel="stylesheet" href="/css/app.css">`.
+*   Add custom fonts, scripts, or meta tags.
+*   Change the HTML structure, logo, or classes.
+
+SwatchKit simply injects the content into the `<!-- PATTERNS -->` and `<!-- SIDEBAR_LINKS -->` placeholders.
+
+### 3. JavaScript Bundling
+If your component needs client-side JS:
+1.  Create a folder: `swatches/carousel/`.
+2.  Add `index.html` (Markup).
+3.  Add `script.js` (Logic).
+
+SwatchKit automatically bundles your JS files, wraps them in a safety scope (IIFE), and injects them into the final build.
+
+## CLI Reference
+
 ```bash
-npm run build:patterns
+swatchkit [command] [options]
 ```
 
-### View the library
-After building, open the generated file:
-```bash
-open dist/index.html
+### Commands
+*   `swatchkit` (Default): Builds the library.
+*   `swatchkit init`: Scaffolds the `_layout.html` file.
+
+### Flags
+| Flag | Short | Description |
+| :--- | :--- | :--- |
+| `--watch` | `-w` | Watch mode (coming soon). |
+| `--config` | `-c` | Path to config file. |
+| `--input` | `-i` | Pattern directory (Default: `swatches/`). |
+| `--outDir` | `-o` | Output directory (Default: `public/swatchkit`). |
+| `--force` | `-f` | Overwrite layout file during init. |
+
+## Configuration
+Optional. Create `swatchkit.config.js` in your root for persistent settings.
+
+```javascript
+module.exports = {
+  // Override default pattern directory
+  input: './src/patterns',
+
+  // Override default output directory
+  outDir: './dist/docs'
+};
 ```

package/build.js

@@ -1,132 +1,422 @@
 #!/usr/bin/env node
-const fs = require('fs');
-const path = require('path');
-
-const config = {
-  srcDir: path.join(process.cwd(), 'src'),
-  cssDir: path.join(process.cwd(), 'src/css'),
-  patternsDir: path.join(process.cwd(), 'src/patterns'),
-  layoutFile: path.join(__dirname, 'src/layout.html'),
-  distDir: path.join(process.cwd(), 'dist'),
-  distCssDir: path.join(process.cwd(), 'dist/css'),
-  distJsDir: path.join(process.cwd(), 'dist/js'),
-  outputFile: path.join(process.cwd(), 'dist/index.html'),
-  outputJsFile: path.join(process.cwd(), 'dist/js/patterns.js')
-};
-
-function build() {
-  console.log('[SwatchKit] Starting build...');
+const fs = require("fs");
+const path = require("path");
+const { processTokens } = require("./src/tokens");
+
+/**
+ * SwatchKit Build Script
+ * Refactored for Phase 1 Expansion
+ */
+
+// --- 1. CLI Argument Parsing ---
+function parseArgs(args) {
+  const options = {
+    command: null,
+    watch: false,
+    config: null,
+    input: null,
+    outDir: null,
+    force: false,
+  };
+
+  for (let i = 2; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "init") {
+      options.command = "init";
+    } else if (arg === "-w" || arg === "--watch") {
+      options.watch = true;
+    } else if (arg === "-f" || arg === "--force") {
+      options.force = true;
+    } else if (arg === "-c" || arg === "--config") {
+      // Handle case where flag is last arg
+      if (i + 1 < args.length) {
+        options.config = args[++i];
+      }
+    } else if (arg === "-i" || arg === "--input") {
+      if (i + 1 < args.length) {
+        options.input = args[++i];
+      }
+    } else if (arg === "-o" || arg === "--outDir") {
+      if (i + 1 < args.length) {
+        options.outDir = args[++i];
+      }
+    }
+  }
+  return options;
+}
+
+// --- 2. Config Loading ---
+function loadConfig(configPath) {
+  let finalPath;
+  if (configPath) {
+    finalPath = path.resolve(process.cwd(), configPath);
+  } else {
+    finalPath = path.join(process.cwd(), "swatchkit.config.js");
+  }
+
+  if (fs.existsSync(finalPath)) {
+    try {
+      console.log(`[SwatchKit] Loading config from ${finalPath}`);
+      return require(finalPath);
+    } catch (e) {
+      console.error("[SwatchKit] Error loading config file:", e.message);
+      return {};
+    }
+  }
+  return {};
+}
+
+// --- 3. Smart Defaults & Path Resolution ---
+function resolveSettings(cliOptions, fileConfig) {
+  const cwd = process.cwd();
+
+  // Helper to find patterns dir
+  function findPatternsDir() {
+    // 1. Explicit input
+    if (cliOptions.input) return path.resolve(cwd, cliOptions.input);
+    if (fileConfig.input) return path.resolve(cwd, fileConfig.input);
+
+    // 2. Search candidates
+    const candidates = ["swatches", "src/swatches", "src/patterns"];
+    for (const cand of candidates) {
+      const absPath = path.join(cwd, cand);
+      if (fs.existsSync(absPath)) return absPath;
+    }
+
+    // 3. Fallback default (swatches)
+    return path.join(cwd, "swatches");
+  }
+
+  const patternsDir = findPatternsDir();
+
+  // Output Dir
+  // Default: public/swatchkit
+  const outDir = cliOptions.outDir
+    ? path.resolve(cwd, cliOptions.outDir)
+    : fileConfig.outDir
+      ? path.resolve(cwd, fileConfig.outDir)
+      : path.join(cwd, "public/swatchkit");
+
+  // CSS Dir (Legacy support: src/css)
+  const cssDir = path.join(cwd, "src/css");
+
+  return {
+    patternsDir,
+    outDir,
+    cssDir,
+    // Internal layout template (relative to this script)
+    internalLayout: path.join(__dirname, "src/layout.html"),
+    // Project specific layout override
+    projectLayout: path.join(patternsDir, "_layout.html"),
+
+    // Derived paths
+    distCssDir: path.join(outDir, "css"),
+    distTokensCssFile: path.join(outDir, "css", "tokens.css"),
+    distJsDir: path.join(outDir, "js"),
+    outputFile: path.join(outDir, "index.html"),
+    outputJsFile: path.join(outDir, "js/patterns.js"),
+    tokensCssFile: path.join(cssDir, "tokens.css"),
+  };
+}
+
+// --- 4. Init Command Logic ---
+function runInit(settings, options) {
+  console.log("[SwatchKit] Initializing...");
+
+  // Ensure patterns directory exists
+  if (!fs.existsSync(settings.patternsDir)) {
+    console.log(`Creating patterns directory: ${settings.patternsDir}`);
+    fs.mkdirSync(settings.patternsDir, { recursive: true });
+  }
+
+  // Create src/tokens directory and sample colors.json
+  const tokensDir = path.join(process.cwd(), "src/tokens");
+  if (!fs.existsSync(tokensDir)) {
+    console.log(`Creating tokens directory: ${tokensDir}`);
+    fs.mkdirSync(tokensDir, { recursive: true });
+  }
+
+  const colorsFile = path.join(tokensDir, "colors.json");
+  if (!fs.existsSync(colorsFile)) {
+    const sampleColors = {
+      title: "Colors",
+      description:
+        "Hex color codes that can be shared, cross-platform. They can be converted at point of usage, such as HSL for web or CMYK for print.",
+      items: [
+        { name: "Dark", value: "#171406" },
+        { name: "Dark Glare", value: "#2d2816" },
+        { name: "Mid", value: "#ABA9A2" },
+        { name: "Light", value: "#ffffff" },
+        { name: "Primary", value: "#fcad26" },
+      ],
+    };
+    fs.writeFileSync(colorsFile, JSON.stringify(sampleColors, null, 2));
+    console.log(`Created sample tokens file at ${colorsFile}`);
+  }
+
+  // Create sample colors.html pattern
+  const colorsPatternFile = path.join(settings.patternsDir, "colors.html");
+  if (!fs.existsSync(colorsPatternFile)) {
+    const colorsHtml = `
+<style>
+  .swatch-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(150px, 1fr));
+    gap: 1rem;
+    padding: 1rem;
+  }
+  .swatch {
+    border: 1px solid #ddd;
+    border-radius: 8px;
+    overflow: hidden;
+  }
+  .swatch-color {
+    height: 100px;
+    width: 100%;
+  }
+  .swatch-info {
+    padding: 0.5rem;
+    font-family: monospace;
+    font-size: 0.9rem;
+    background: #f9f9f9;
+  }
+</style>
+
+<div class="swatch-grid">
+  <div class="swatch">
+    <div class="swatch-color" style="background-color: var(--color-dark);"></div>
+    <div class="swatch-info">
+      <strong>Dark</strong><br>
+      var(--color-dark)
+    </div>
+  </div>
+  <div class="swatch">
+    <div class="swatch-color" style="background-color: var(--color-dark-glare);"></div>
+    <div class="swatch-info">
+      <strong>Dark Glare</strong><br>
+      var(--color-dark-glare)
+    </div>
+  </div>
+  <div class="swatch">
+    <div class="swatch-color" style="background-color: var(--color-mid);"></div>
+    <div class="swatch-info">
+      <strong>Mid</strong><br>
+      var(--color-mid)
+    </div>
+  </div>
+  <div class="swatch">
+    <div class="swatch-color" style="background-color: var(--color-light);"></div>
+    <div class="swatch-info">
+      <strong>Light</strong><br>
+      var(--color-light)
+    </div>
+  </div>
+  <div class="swatch">
+    <div class="swatch-color" style="background-color: var(--color-primary);"></div>
+    <div class="swatch-info">
+      <strong>Primary</strong><br>
+      var(--color-primary)
+    </div>
+  </div>
+</div>
+`;
+    fs.writeFileSync(colorsPatternFile, colorsHtml.trim());
+    console.log(`Created sample pattern at ${colorsPatternFile}`);
+  }
+
+  // Generate initial CSS
+  processTokens(process.cwd(), settings.cssDir);
+
+  const targetLayout = settings.projectLayout;
+
+  if (fs.existsSync(targetLayout) && !options.force) {
+    console.warn(`Warning: Layout file already exists at ${targetLayout}`);
+    console.warn("Use --force to overwrite.");
+    return;
+  }
+
+  if (fs.existsSync(settings.internalLayout)) {
+    const layoutContent = fs.readFileSync(settings.internalLayout, "utf-8");
+    fs.writeFileSync(targetLayout, layoutContent);
+    console.log(`Created layout file at ${targetLayout}`);
+  } else {
+    console.error(
+      `Error: Internal layout file not found at ${settings.internalLayout}`,
+    );
+    process.exit(1);
+  }
+}
+
+// --- 5. Build Logic ---
+function build(settings) {
+  console.log(`[SwatchKit] Starting build...`);
+  console.log(`  Patterns: ${settings.patternsDir}`);
+  console.log(`  Output:   ${settings.outDir}`);
 
   // 1. Check if patterns directory exists
-  if (!fs.existsSync(config.patternsDir)) {
-    console.error('Error: No patterns found. Create src/patterns to get started.');
+  if (!fs.existsSync(settings.patternsDir)) {
+    console.error(
+      `Error: Patterns directory not found at ${settings.patternsDir}`,
+    );
+    console.error('Run "swatchkit init" to get started.');
     process.exit(1);
   }
 
   // 2. Ensure dist directories exist
-  [config.distDir, config.distCssDir, config.distJsDir].forEach(dir => {
+  [settings.outDir, settings.distCssDir, settings.distJsDir].forEach((dir) => {
     if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
   });
 
+  // 2.5 Process Tokens
+  processTokens(process.cwd(), settings.cssDir);
+
   // 3. Copy CSS files
-  console.log('Copying CSS...');
-  if (fs.existsSync(config.cssDir)) {
-      const cssFiles = fs.readdirSync(config.cssDir).filter(file => file.endsWith('.css'));
-      cssFiles.forEach(file => {
-          fs.copyFileSync(path.join(config.cssDir, file), path.join(config.distCssDir, file));
-      });
+  if (fs.existsSync(settings.cssDir)) {
+    console.log("Copying CSS...");
+    const cssFiles = fs
+      .readdirSync(settings.cssDir)
+      .filter((file) => file.endsWith(".css"));
+    cssFiles.forEach((file) => {
+      fs.copyFileSync(
+        path.join(settings.cssDir, file),
+        path.join(settings.distCssDir, file),
+      );
+    });
   }
 
   // 4. Read patterns & JS
-  console.log('Processing patterns...');
+  console.log("Processing patterns...");
   const patterns = [];
   const scripts = [];
 
-  const items = fs.readdirSync(config.patternsDir);
-
-  items.forEach(item => {
-      const itemPath = path.join(config.patternsDir, item);
-      const stat = fs.statSync(itemPath);
-      
-      let name, content, id;
-
-      // Handle Directory Pattern (Folder with index.html + optional JS files)
-      if (stat.isDirectory()) {
-        const indexFile = path.join(itemPath, 'index.html');
-        
-        if (fs.existsSync(indexFile)) {
-          name = item;
-          id = item;
-          content = fs.readFileSync(indexFile, 'utf-8');
-
-          // Find all .js files in this directory
-          const jsFiles = fs.readdirSync(itemPath).filter(file => file.endsWith('.js'));
-          
-          jsFiles.forEach(jsFile => {
-             const scriptContent = fs.readFileSync(path.join(itemPath, jsFile), 'utf-8');
-             scripts.push(`
+  const items = fs.readdirSync(settings.patternsDir);
+
+  items.forEach((item) => {
+    // Skip _layout.html or hidden files
+    if (item.startsWith("_") || item.startsWith(".")) return;
+
+    const itemPath = path.join(settings.patternsDir, item);
+    const stat = fs.statSync(itemPath);
+
+    let name, content, id;
+
+    // Handle Directory Pattern
+    if (stat.isDirectory()) {
+      const indexFile = path.join(itemPath, "index.html");
+
+      if (fs.existsSync(indexFile)) {
+        name = item;
+        id = item;
+        content = fs.readFileSync(indexFile, "utf-8");
+
+        // Find all .js files
+        const jsFiles = fs
+          .readdirSync(itemPath)
+          .filter((file) => file.endsWith(".js"));
+
+        jsFiles.forEach((jsFile) => {
+          const scriptContent = fs.readFileSync(
+            path.join(itemPath, jsFile),
+            "utf-8",
+          );
+          scripts.push(`
 /* --- Pattern: ${name} / File: ${jsFile} --- */
 (function() {
 ${scriptContent}
 })();
 `);
-          });
-        }
-      } 
-      // Handle Single File Pattern (.html)
-      else if (item.endsWith('.html')) {
-        name = path.basename(item, '.html');
-        id = name;
-        content = fs.readFileSync(itemPath, 'utf-8');
+        });
       }
+    }
+    // Handle Single File Pattern
+    else if (item.endsWith(".html")) {
+      name = path.basename(item, ".html");
+      id = name;
+      content = fs.readFileSync(itemPath, "utf-8");
+    }
 
-      if (name && content) {
-        patterns.push({ name, id, content });
-      }
-    });
+    if (name && content) {
+      patterns.push({ name, id, content });
+    }
+  });
 
   // 5. Generate HTML fragments
-  const sidebarLinks = patterns.map(p => 
-    `<a href="#${p.id}">${p.name}</a>`
-  ).join('\n');
-
-  const patternBlocks = patterns.map(p => {
-    const escapedContent = p.content
-      .replace(/&/g, "&amp;")
-      .replace(/</g, "&lt;")
-      .replace(/>/g, "&gt;")
-      .replace(/"/g, "&quot;")
-      .replace(/'/g, "&#039;");
-
-    return `
+  const sidebarLinks = patterns
+    .map((p) => `<a href="#${p.id}">${p.name}</a>`)
+    .join("\n");
+
+  const patternBlocks = patterns
+    .map((p) => {
+      const escapedContent = p.content
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#039;");
+
+      return `
       <section id="${p.id}">
         <h2>${p.name}</h2>
         <div class="preview">${p.content}</div>
         <pre><code>${escapedContent}</code></pre>
       </section>
     `;
-  }).join('\n');
+    })
+    .join("\n");
 
   // 6. Write JS Bundle
   if (scripts.length > 0) {
-    fs.writeFileSync(config.outputJsFile, scripts.join('\n'));
-    console.log(`Bundled ${scripts.length} scripts to ${config.outputJsFile}`);
+    fs.writeFileSync(settings.outputJsFile, scripts.join("\n"));
+    console.log(
+      `Bundled ${scripts.length} scripts to ${settings.outputJsFile}`,
+    );
+  } else {
+    fs.writeFileSync(settings.outputJsFile, "// No pattern scripts found");
+  }
+
+  // 7. Load Layout
+  let layoutContent;
+  if (fs.existsSync(settings.projectLayout)) {
+    console.log(`Using custom layout: ${settings.projectLayout}`);
+    layoutContent = fs.readFileSync(settings.projectLayout, "utf-8");
   } else {
-    // Write empty file if no scripts so browser doesn't 404
-    fs.writeFileSync(config.outputJsFile, '// No pattern scripts found');
+    // console.log(`Using internal layout`);
+    layoutContent = fs.readFileSync(settings.internalLayout, "utf-8");
+  }
+
+  let headExtras = "";
+  // Check if the tokens file exists in the *output* directory (where we copied it to)
+  if (fs.existsSync(settings.distTokensCssFile)) {
+    headExtras = '<link rel="stylesheet" href="css/tokens.css">';
   }
 
-  // 7. Read layout and replace placeholders
-  let layout = fs.readFileSync(config.layoutFile, 'utf-8');
-  
-  const finalHtml = layout
-    .replace('<!-- SIDEBAR_LINKS -->', sidebarLinks)
-    .replace('<!-- PATTERNS -->', patternBlocks);
+  const finalHtml = layoutContent
+    .replace("<!-- SIDEBAR_LINKS -->", sidebarLinks)
+    .replace("<!-- PATTERNS -->", patternBlocks)
+    .replace("<!-- HEAD_EXTRAS -->", headExtras);
 
   // 8. Write output
-  fs.writeFileSync(config.outputFile, finalHtml);
-  
-  console.log(`Build complete! Generated ${config.outputFile}`);
+  fs.writeFileSync(settings.outputFile, finalHtml);
+
+  console.log(`Build complete! Generated ${settings.outputFile}`);
+}
+
+// --- Main Execution ---
+try {
+  const cliOptions = parseArgs(process.argv);
+  const fileConfig = loadConfig(cliOptions.config);
+  const settings = resolveSettings(cliOptions, fileConfig);
+
+  if (cliOptions.command === "init") {
+    runInit(settings, cliOptions);
+  } else {
+    build(settings);
+    if (cliOptions.watch) {
+      console.log("[SwatchKit] Watch mode is not yet fully implemented.");
+    }
+  }
+} catch (error) {
+  console.error("[SwatchKit] Error:", error.message);
+  process.exit(1);
 }
 
-build();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swatchkit",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "A lightweight tool for creating HTML pattern libraries.",
   "main": "build.js",
   "bin": {

package/src/layout.html

@@ -5,6 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>SwatchKit</title>
     <link rel="stylesheet" href="/css/global.css" />
+    <!-- HEAD_EXTRAS -->
     <style>
         body {
             display: flex;
@@ -86,4 +87,4 @@
     </main>
     <script src="js/patterns.js"></script>
 </body>
-</html>
+</html>