@3sln/deck 0.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Ray Stubbs
+
+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,50 @@
+# @3sln/deck
+
+A Vite plugin for building scalable, zero-config, Markdown-based component playgrounds and documentation sites.
+
+> [!WARNING]
+> This is a work-in-progress project.
+
+## Features
+
+- **Scalable Backend:** Uses **IndexedDB** to index and store all documentation content on the client-side. This allows `deck` to handle hundreds or thousands of documents without a slow initial load time.
+- **Vite Plugin:** A simple Vite plugin provides a zero-config development server with hot-reloading.
+- **Static Site Generation:** A `deck-build` command generates a fully static, production-ready site from your project files.
+- **`<deck-demo>`:** A powerful custom element for embedding live, stateful, and hot-reloading component demos directly in your documentation.
+- **Reactive UI:** A modern, responsive UI with a powerful search feature and a split-screen layout for easy viewing.
+- **Configurable:** The project title and import maps for dynamic demos can be configured in your project's `package.json`.
+
+## Quick Start
+
+1.  **Install:**
+    ```bash
+    npm install @3sln/deck
+    ```
+
+2.  **Configure:** In your `package.json`, add a build script and your project's configuration:
+    ```json
+    {
+      "scripts": {
+        "dev": "vite",
+        "build": "deck-build"
+      },
+      "@3sln/deck": {
+        "title": "My Awesome Docs"
+      }
+    }
+    ```
+
+3.  **Create a `vite.config.js`:**
+    ```javascript
+    import { defineConfig } from 'vite';
+    import deckPlugin from '@3sln/deck/vite-plugin';
+
+    export default defineConfig({
+      plugins: [deckPlugin()],
+    });
+    ```
+
+4.  **Run:**
+    ```bash
+    npm run dev
+    ```

package/bin/build.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+
+import {build as viteBuild} from 'vite';
+import fs from 'fs-extra';
+import path from 'path';
+import {createRequire} from 'module';
+import { sha256, loadDeckConfig, getProjectFiles, getHtmlTemplate } from '../src/config.js';
+
+const require = createRequire(import.meta.url);
+
+// --- Path Resolution ---
+const userRoot = process.cwd();
+const outDir = path.resolve(userRoot, 'out');
+const assetsDir = path.resolve(outDir, 'assets');
+const deckPluginPath = require.resolve('@3sln/deck/vite-plugin');
+const deckRoot = path.dirname(deckPluginPath);
+
+// --- Main Build Function ---
+async function build() {
+  try {
+    console.log('Starting Deck build...');
+
+    const config = await loadDeckConfig(userRoot);
+    const buildConfig = config.build;
+
+    // Clean output directory
+    await fs.emptyDir(outDir);
+    console.log(`Cleaned ${outDir}`);
+
+    // Bundle the deck application using Vite's JS API
+    console.log('Bundling application assets...');
+    const viteManifest = await viteBuild({
+      configFile: false,
+      root: deckRoot,
+      build: {
+        outDir: assetsDir,
+        manifest: true,
+        lib: {
+          entry: path.resolve(deckRoot, 'src/main.js'),
+          name: 'DeckApp',
+          fileName: 'deck-app',
+          formats: ['es'],
+        },
+      },
+    });
+    console.log('Application assets bundled.');
+
+    // Find and copy all project files
+    console.log('Copying project files...');
+    const filesToCopy = getProjectFiles(userRoot, buildConfig);
+    for (const file of filesToCopy) {
+      const source = path.resolve(userRoot, file);
+      const dest = path.resolve(outDir, file);
+      await fs.ensureDir(path.dirname(dest));
+      await fs.copy(source, dest);
+    }
+    console.log(`Copied ${filesToCopy.length} files.`);
+
+    // Copy picked static assets
+    console.log('Copying picked assets...');
+    if (buildConfig.pick) {
+        for (const [source, dest] of Object.entries(buildConfig.pick)) {
+            const sourcePath = path.resolve(userRoot, source);
+            const destPath = path.resolve(outDir, dest);
+            if (fs.existsSync(sourcePath)) {
+                console.log(`Picking '${source}' to '${dest}'...`);
+                await fs.copy(sourcePath, destPath, { dereference: true });
+            } else {
+                console.warn(`Source path for 'pick' not found: ${sourcePath}`);
+            }
+        }
+    }
+
+    // Find card paths and hash content for the index
+    const cardFiles = filesToCopy.filter(file => file.endsWith('.md') || file.endsWith('.html'));
+    const initialCardsData = await Promise.all(cardFiles.map(async (file) => {
+        const content = await fs.readFile(path.resolve(outDir, file), 'utf-8');
+        const hash = await sha256(content);
+        return { path: `/${file}`, hash };
+    }));
+    console.log(`Found and processed ${initialCardsData.length} cards.`);
+
+    // Generate asset manifest for service worker
+    console.log('Generating asset manifest...');
+    const manifest = await fs.readJson(path.resolve(assetsDir, '.vite/manifest.json'));
+    const bundledAssets = Object.values(manifest).flatMap(chunk => [chunk.file, ...(chunk.css || [])]).map(file => `/assets/${file}`);
+    const assetManifest = {
+        files: [...filesToCopy.map(f => `/${f}`), ...bundledAssets]
+    };
+    await fs.writeJson(path.resolve(outDir, 'asset-manifest.json'), assetManifest);
+    console.log('Asset manifest generated.');
+
+    // Copy service worker
+    await fs.copy(path.resolve(deckRoot, 'src/sw.js'), path.resolve(outDir, 'sw.js'));
+
+    // Generate the final index.html
+    console.log('Generating production index.html...');
+    const entryFile = manifest['src/main.js']?.file;
+    const cssFiles = manifest['src/main.js']?.css || [];
+
+    if (!entryFile) {
+      throw new Error('Could not find entry file in Vite manifest.');
+    }
+
+    const html = getHtmlTemplate({
+        title: buildConfig.title,
+        importMap: buildConfig.importMap,
+        initialCardsData,
+        pinnedCardPaths: buildConfig.pinned,
+        entryFile: `/assets/${entryFile}`,
+        cssFiles,
+    });
+
+    await fs.writeFile(path.resolve(outDir, 'index.html'), html);
+    console.log('Production index.html generated.');
+    console.log('Build complete!');
+  } catch (e) {
+    console.error('Deck build failed:', e);
+    process.exit(1);
+  }
+}
+
+build();

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@3sln/deck",
+  "version": "0.0.5",
+  "description": "A Vite plugin for building scalable, zero-config, Markdown-based component playgrounds and documentation sites.",
+  "type": "module",
+  "author": "Ray Stubbs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/3sln/deck.git"
+  },
+  "scripts": {
+    "format": "prettier -w \"**/*.js\""
+  },
+  "license": "MIT",
+  "keywords": [
+    "vite",
+    "plugin",
+    "documentation",
+    "markdown",
+    "component",
+    "playground"
+  ],
+  "exports": {
+    ".": "./src/main.js",
+    "./vite-plugin": "./vite-plugin.js"
+  },
+  "bin": {
+    "deck-build": "./bin/build.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "vite-plugin.js"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@3sln/bones": "^0.0.4",
+    "@3sln/dodo": "^0.0.4",
+    "@3sln/ngin": "^0.0.1",
+    "fs-extra": "^11.3.2",
+    "glob": "^10.3.10",
+    "highlight.js": "^11.9.0",
+    "marked": "^16.3.0",
+    "vite": "^5.1.0"
+  },
+  "devDependencies": {
+    "prettier": "^3.6.2"
+  }
+}

package/src/config.js

@@ -0,0 +1,96 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { globSync } from 'glob';
+import { subtle } from 'crypto';
+
+export async function sha256(str) {
+  const textAsBuffer = new TextEncoder().encode(str);
+  const hashBuffer = await subtle.digest('SHA-256', textAsBuffer);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+export async function loadDeckConfig(root) {
+    const userPkgJsonPath = path.resolve(root, 'package.json');
+    const userPkgJson = fs.existsSync(userPkgJsonPath) ? await fs.readJson(userPkgJsonPath) : {};
+    const options = userPkgJson['@3sln/deck'] || {};
+
+    const defaultConfig = {
+        title: 'Deck',
+        pinned: [],
+        pick: {},
+        include: ['**/*'],
+        exclude: [
+            '**/node_modules/**',
+            'out/**',
+            `**/${path.basename(path.resolve(root, 'out'))}/**`,
+            '**/package.json',
+            '**/package-lock.json',
+            '**/vite.config.js',
+            '**/.git/**',
+        ],
+    };
+
+    const baseConfig = { ...defaultConfig, ...options };
+
+    return {
+        ...baseConfig,
+        dev: { ...baseConfig, ...(options.dev || {}) },
+        build: { ...baseConfig, ...(options.build || {}) },
+    };
+}
+
+export function getProjectFiles(root, config) {
+    return globSync(config.include, {
+        cwd: root,
+        ignore: config.exclude,
+        nodir: true,
+        dot: true,
+    });
+}
+
+export function getHtmlTemplate({ title, importMap, initialCardsData, pinnedCardPaths, entryFile, cssFiles = [] }) {
+  return `
+        <!doctype html>
+        <html lang="en">
+          <head>
+            <meta charset="utf-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1">
+            <title>${title}</title>
+            ${importMap ? `<script type="importmap">${JSON.stringify(importMap)}</script>` : ''}
+            <script>
+              window.__INITIAL_CARDS_DATA__ = ${JSON.stringify(initialCardsData)};
+              window.__PINNED_CARD_PATHS__ = ${JSON.stringify(pinnedCardPaths)};
+            </script>
+            <style>
+              :root { --bg-color: #fff; --text-color: #222; --border-color: #eee; --card-bg: #fff;
+                --card-hover-bg: #f9f9f9; --input-bg: #fff; --input-border: #ddd; --link-color: #007aff;
+              }
+              @media (prefers-color-scheme: dark) {
+                :root {
+                  --bg-color: #121212; --text-color: #eee; --border-color: #333; --card-bg: #1e1e1e;
+                  --card-hover-bg: #2a2a2a; --input-bg: #2a2a2a; --input-border: #444; --link-color: #09f;
+                }
+              }
+              body {
+                background-color: var(--bg-color); color: var(--text-color);
+                font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+                margin: 0; padding: 0;
+              }
+            </style>
+            ${cssFiles.map(file => `<link rel="stylesheet" href="/assets/${file}">`).join('\n')}
+          </head>
+          <body>
+            <div id="root"></div>
+            <script type="module">
+              import { renderDeck } from '${entryFile}';
+              renderDeck({
+                target: document.getElementById('root'),
+                initialCardsData: window.__INITIAL_CARDS_DATA__,
+                pinnedCardPaths: window.__PINNED_CARD_PATHS__,
+              });
+            </script>
+          </body>
+        </html>
+    `;
+}

package/src/db.js

@@ -0,0 +1,302 @@
+const DB_NAME = 'deck-db';
+const DB_VERSION = 3; // Bump version for schema change
+const CARDS_STORE = 'cards';
+const INDEX_STORE = 'searchIndex';
+
+let dbPromise = null;
+
+function promisifyRequest(request) {
+  return new Promise((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+}
+
+function initDB() {
+  if (dbPromise) return dbPromise;
+
+  dbPromise = new Promise((resolve, reject) => {
+    const openRequest = indexedDB.open(DB_NAME, DB_VERSION);
+
+    openRequest.onupgradeneeded = event => {
+      const db = event.target.result;
+      let cardsStore;
+      if (!db.objectStoreNames.contains(CARDS_STORE)) {
+        cardsStore = db.createObjectStore(CARDS_STORE, {keyPath: 'path'});
+      } else {
+        cardsStore = event.target.transaction.objectStore(CARDS_STORE);
+      }
+
+      if (!cardsStore.indexNames.contains('by-updatedAt')) {
+        cardsStore.createIndex('by-updatedAt', 'updatedAt');
+      }
+      if (!cardsStore.indexNames.contains('by-usedAt')) {
+        cardsStore.createIndex('by-usedAt', 'usedAt');
+      }
+
+      if (!db.objectStoreNames.contains(INDEX_STORE)) {
+        const store = db.createObjectStore(INDEX_STORE, {keyPath: ['word', 'path']});
+        store.createIndex('by-word', 'word');
+        store.createIndex('by-path', 'path');
+      }
+    };
+
+    openRequest.onsuccess = event => resolve(event.target.result);
+    openRequest.onerror = event => reject(event.target.error);
+  });
+
+  return dbPromise;
+}
+
+function tokenize(text) {
+  if (!text) return [];
+  return text.toLowerCase().match(/\w+/g) || [];
+}
+
+function getTextContent(html) {
+  if (!html) return '';
+  return new DOMParser().parseFromString(html, 'text/html').body.textContent || '';
+}
+
+async function upsertCard(card) {
+  const db = await initDB();
+  const tx = db.transaction([CARDS_STORE, INDEX_STORE], 'readwrite');
+  const cardsStore = tx.objectStore(CARDS_STORE);
+  const indexStore = tx.objectStore(INDEX_STORE);
+
+  const existing = await promisifyRequest(cardsStore.get(card.path));
+
+  if (existing) {
+    const pathIndex = indexStore.index('by-path');
+    const oldIndexKeys = await promisifyRequest(pathIndex.getAllKeys(IDBKeyRange.only(card.path)));
+    await Promise.all(oldIndexKeys.map(key => promisifyRequest(indexStore.delete(key))));
+  }
+
+  const now = Date.now();
+  const newCard = {...card, updatedAt: now, usedAt: existing?.usedAt || now};
+  const titleTokens = tokenize(newCard.title);
+  const summaryTokens = tokenize(newCard.summary);
+  const bodyText = getTextContent(newCard.body);
+  const bodyTokens = tokenize(bodyText);
+
+  const wordScores = new Map();
+  const uniqueBodyWords = new Set(bodyTokens);
+  const uniqueTitleWords = new Set(titleTokens);
+  const uniqueSummaryWords = new Set(summaryTokens);
+
+  uniqueBodyWords.forEach(word => {
+    const tf = bodyTokens.filter(t => t === word).length;
+    let score = tf;
+    if (uniqueTitleWords.has(word)) score += 1;
+    if (uniqueSummaryWords.has(word)) score += 1;
+    wordScores.set(word, score);
+  });
+
+  await Promise.all(
+    Array.from(wordScores.entries()).map(([word, score]) => {
+      return promisifyRequest(indexStore.put({word, path: newCard.path, score}));
+    }),
+  );
+
+  await promisifyRequest(cardsStore.put(newCard));
+  return newCard;
+}
+
+async function removeCard(path) {
+  const db = await initDB();
+  const tx = db.transaction([CARDS_STORE, INDEX_STORE], 'readwrite');
+  const cardsStore = tx.objectStore(CARDS_STORE);
+  const indexStore = tx.objectStore(INDEX_STORE);
+
+  const pathIndex = indexStore.index('by-path');
+  const indexKeysToDelete = await promisifyRequest(pathIndex.getAllKeys(IDBKeyRange.only(path)));
+  await Promise.all(indexKeysToDelete.map(key => promisifyRequest(indexStore.delete(key))));
+
+  await promisifyRequest(cardsStore.delete(path));
+}
+
+function levenshtein(a, b) {
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  const matrix = [];
+
+  for (let i = 0; i <= b.length; i++) {
+    matrix[i] = [i];
+  }
+  for (let j = 0; j <= a.length; j++) {
+    matrix[0][j] = j;
+  }
+
+  for (let i = 1; i <= b.length; i++) {
+    for (let j = 1; j <= a.length; j++) {
+      if (b.charAt(i - 1) === a.charAt(j - 1)) {
+        matrix[i][j] = matrix[i - 1][j - 1];
+      } else {
+        matrix[i][j] = Math.min(
+          matrix[i - 1][j - 1] + 1, // substitution
+          matrix[i][j - 1] + 1, // insertion
+          matrix[i - 1][j] + 1, // deletion
+        );
+      }
+    }
+  }
+  return matrix[b.length][a.length];
+}
+
+async function findCardsByQuery(query, limit = 100) {
+  const db = await initDB();
+  const searchTokens = tokenize(query);
+  if (searchTokens.length === 0) return [];
+
+  const tx = db.transaction([CARDS_STORE, INDEX_STORE], 'readonly');
+  const indexStore = tx.objectStore(INDEX_STORE);
+  const cardsStore = tx.objectStore(CARDS_STORE);
+  const wordIndex = indexStore.index('by-word');
+
+  const pathScores = new Map();
+
+  await Promise.all(
+    searchTokens.map(async word => {
+      const request = wordIndex.getAll(IDBKeyRange.only(word));
+      const results = await promisifyRequest(request);
+      results.forEach(({path, score}) => {
+        pathScores.set(path, (pathScores.get(path) || 0) + score);
+      });
+    }),
+  );
+
+  if (pathScores.size > 0) {
+    const sortedPaths = Array.from(pathScores.entries())
+      .sort((a, b) => b[1] - a[1])
+      .map(entry => entry[0])
+      .slice(0, limit);
+
+    const cards = await Promise.all(
+      sortedPaths.map(path => promisifyRequest(cardsStore.get(path))),
+    );
+    return cards.filter(Boolean).sort((a, b) => b.usedAt - a.usedAt);
+  }
+
+  // Fallback to aggregated word-by-word distance search
+  console.log('No index match, falling back to word-distance search...');
+  const allCards = await promisifyRequest(cardsStore.getAll());
+  const cardScores = allCards.map(card => {
+    const titleTokens = tokenize(card.title);
+    const summaryTokens = tokenize(card.summary);
+    const searchableTokens = [...new Set([...titleTokens, ...summaryTokens])];
+    let totalScore = 0;
+
+    searchTokens.forEach(queryWord => {
+      let bestWordScore = 0;
+      searchableTokens.forEach(searchableWord => {
+        let currentScore = 0;
+        if (searchableWord.startsWith(queryWord)) {
+          currentScore = 10 + queryWord.length; // High score for prefix
+        } else {
+          const longWord = queryWord.length > searchableWord.length ? queryWord : searchableWord;
+          const shortWord = queryWord.length > searchableWord.length ? searchableWord : queryWord;
+
+          if (longWord.length > 7 && shortWord.length < longWord.length / 2) {
+            currentScore = 0; // Skip this match
+          } else {
+            const distance = levenshtein(queryWord, searchableWord);
+            if (distance <= 2) {
+              currentScore = 1 / (distance + 1); // Score between 0 and 1
+            }
+          }
+        }
+        if (currentScore > bestWordScore) {
+          bestWordScore = currentScore;
+        }
+      });
+      totalScore += bestWordScore;
+    });
+
+    return {card, score: totalScore};
+  });
+
+  return cardScores
+    .filter(item => item.score > 0)
+    .sort((a, b) => {
+      if (b.score !== a.score) {
+        return b.score - a.score;
+      }
+      return b.card.usedAt - a.card.usedAt;
+    })
+    .slice(0, 20)
+    .map(item => item.card);
+}
+
+async function getRecentCards(limit = 100) {
+  const db = await initDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(CARDS_STORE, 'readonly');
+    const index = tx.objectStore(CARDS_STORE).index('by-usedAt');
+    const request = index.openCursor(null, 'prev');
+
+    const results = [];
+
+    request.onsuccess = () => {
+      const cursor = request.result;
+      if (cursor && results.length < limit) {
+        results.push(cursor.value);
+        cursor.continue();
+      } else {
+        resolve(results);
+      }
+    };
+
+    request.onerror = () => {
+      reject(request.error);
+    };
+  });
+}
+
+async function getCard(path) {
+  const db = await initDB();
+  return await promisifyRequest(db.transaction(CARDS_STORE).objectStore(CARDS_STORE).get(path));
+}
+
+async function touchCard(path) {
+  const db = await initDB();
+  const tx = db.transaction(CARDS_STORE, 'readwrite');
+  const store = tx.objectStore(CARDS_STORE);
+  const card = await promisifyRequest(store.get(path));
+  if (card) {
+    card.usedAt = Date.now();
+    await promisifyRequest(store.put(card));
+  }
+}
+
+async function pruneCards(livePaths) {
+  const db = await initDB();
+  const tx = db.transaction([CARDS_STORE, INDEX_STORE], 'readwrite');
+  const cardsStore = tx.objectStore(CARDS_STORE);
+  const indexStore = tx.objectStore(INDEX_STORE);
+  const pathIndex = indexStore.index('by-path');
+
+  const dbPaths = await promisifyRequest(cardsStore.getAllKeys());
+  const livePathsSet = new Set(livePaths);
+
+  const stalePaths = dbPaths.filter(path => !livePathsSet.has(path));
+  if (stalePaths.length === 0) return;
+
+  console.log(`Pruning ${stalePaths.length} stale cards...`);
+
+  for (const path of stalePaths) {
+    const indexKeysToDelete = await promisifyRequest(pathIndex.getAllKeys(IDBKeyRange.only(path)));
+    await Promise.all(indexKeysToDelete.map(key => promisifyRequest(indexStore.delete(key))));
+    await promisifyRequest(cardsStore.delete(path));
+  }
+}
+
+export {
+  initDB,
+  upsertCard,
+  removeCard,
+  findCardsByQuery,
+  getRecentCards,
+  getCard,
+  pruneCards,
+  touchCard,
+};