@3sln/deck 0.0.6 → 0.0.8

package/README.md

@@ -1,18 +1,18 @@
-# @3sln/deck
-
-A Vite plugin for building scalable, zero-config, Markdown-based component playgrounds and documentation sites.
+# Deck
 
 > [!WARNING]
 > This is a work-in-progress project.
 
-## Features
+Deck is a Vite-based tool for creating scalable, zero-config, Markdown-based component playgrounds and documentation sites.
+
+It uses a client-side database to index your documentation, enabling a fast initial load and powerful full-text search, even for very large projects.
+
+[deck.webm](https://github.com/user-attachments/assets/cc127ba6-202c-47f0-a982-560e05f7574d)
+
+## Documentation & Live Examples
 
-- **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`.
+For a complete guide, API reference, and to see Deck in action, you can check out Deck's own
+[card Deck here](https://deck.3sln.com).
 
 ## Quick Start
 
@@ -24,6 +24,7 @@ A Vite plugin for building scalable, zero-config, Markdown-based component playg
 2.  **Configure:** In your `package.json`, add a build script and your project's configuration:
     ```json
     {
+      ...
       "scripts": {
         "dev": "vite",
         "build": "deck-build"
@@ -31,6 +32,7 @@ A Vite plugin for building scalable, zero-config, Markdown-based component playg
       "@3sln/deck": {
         "title": "My Awesome Docs"
       }
+      ...
     }
     ```
 

package/bin/build.js

@@ -10,8 +10,7 @@ const require = createRequire(import.meta.url);
 
 // --- Path Resolution ---
 const userRoot = process.cwd();
-const outDir = path.resolve(userRoot, 'out');
-const assetsDir = path.resolve(outDir, 'assets');
+// outDir is now resolved inside build()
 const deckPluginPath = require.resolve('@3sln/deck/vite-plugin');
 const deckRoot = path.dirname(deckPluginPath);
 
@@ -21,7 +20,10 @@ async function build() {
     console.log('Starting Deck build...');
 
     const config = await loadDeckConfig(userRoot);
-    const buildConfig = config.build;
+    const buildConfig = config.build || {};
+
+    const outDir = path.resolve(userRoot, buildConfig.outDir || 'out');
+    const assetsDir = path.resolve(outDir, 'assets');
 
     // Clean output directory
     await fs.emptyDir(outDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3sln/deck",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "A Vite plugin for building scalable, zero-config, Markdown-based component playgrounds and documentation sites.",
   "type": "module",
   "author": "Ray Stubbs",
@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "@3sln/bones": "^0.0.4",
-    "@3sln/dodo": "^0.0.4",
+    "@3sln/dodo": "^0.0.5",
     "@3sln/ngin": "^0.0.1",
     "fs-extra": "^11.3.2",
     "glob": "^10.3.10",

package/src/deck-demo.js

@@ -59,7 +59,7 @@ const propertiesStyle = css`
   }
 `;
 
-function getEngine(rootNode, key, src) {
+function getEngine(rootNode, key, src, canonicalSrc) {
   if (!rootNodeCaches.has(rootNode)) {
     rootNodeCaches.set(rootNode, new Map());
   }
@@ -72,7 +72,7 @@ function getEngine(rootNode, key, src) {
     return entry.engine;
   }
 
-  const {engine, abortController} = createEngine(src);
+  const {engine, abortController} = createEngine(src, canonicalSrc);
   const entry = {
     engine,
     refCount: 1,
@@ -129,7 +129,7 @@ function propertyControl(engine, name) {
   });
 }
 
-function createEngine(src) {
+function createEngine(src, canonicalSrc) {
   const abortController = new AbortController();
   const sourceCode$ = new ObservableSubject('Loading...');
 
@@ -210,35 +210,35 @@ function createEngine(src) {
       engine.dispatch(new UpsertProperty(name, options));
       return engine.query(new PropertyValue(name));
     },
-    setActivePanel: name => {
-      engine.dispatch(new ActivatePanel(name));
-    },
     get signal() {
       return abortController.signal;
     },
   };
 
   (async () => {
-    if (!src) {
-      return;
-    }
+    const esmSrc = src;
+    const textSrc = canonicalSrc || src;
+    if (!esmSrc || !textSrc) return;
 
     try {
       if (HOT) {
-        const m = await import(/* @vite-ignore */ `/@deck-dev-hmr/${encodeURIComponent(src)}`);
-        const sub = m.moduleText$.subscribe(text => {
+        const esm = await import(/* @vite-ignore */ `/@deck-dev-esm/${encodeURIComponent(esmSrc)}`);
+        const txt = await import(/* @vite-ignore */ `/@deck-dev-src/${encodeURIComponent(textSrc)}.js`);
+
+        const sub = txt.moduleText$.subscribe(text => {
           sourceCode$.next(text);
         });
         abortController.signal.addEventListener('abort', () => {
           sub.unsubscribe();
         });
-        m.default(driver);
+        esm.default(driver);
       } else {
-        const url = new URL(src, location.href);
-        const m = await import(/* @vite-ignore */ url.href);
+        const esmUrl = new URL(esmSrc, location.href);
+        const textUrl = new URL(textSrc, location.href);
+        const m = await import(/* @vite-ignore */ esmUrl.href);
         m.default(driver);
 
-        const text = await fetch(url).then(r => r.text());
+        const text = await fetch(textUrl).then(r => r.text());
         sourceCode$.next(text);
       }
     } catch (err) {
@@ -736,7 +736,7 @@ class DeckDemo extends HTMLElement {
     }
 
     this.#id = this.id;
-    this.#engine = getEngine(this.getRootNode(), this.id, this.getAttribute('src'));
+    this.#engine = getEngine(this.getRootNode(), this.id, this.getAttribute('src'), this.getAttribute('canonical-src'));
     this.#render();
   }
 
@@ -856,4 +856,4 @@ class DeckDemo extends HTMLElement {
   }
 }
 
-customElements.define('deck-demo', DeckDemo);
+customElements.define('deck-demo', DeckDemo);

package/src/highlight.js

@@ -1,6 +1,7 @@
 import hljs from 'highlight.js/lib/core';
 import javascript from 'highlight.js/lib/languages/javascript';
 import xml from 'highlight.js/lib/languages/xml';
+import clojure from 'highlight.js/lib/languages/clojure';
 import css from 'highlight.js/lib/languages/css';
 import githubStyle from 'highlight.js/styles/github.css?inline';
 import githubDarkStyle from 'highlight.js/styles/github-dark.css?inline';
@@ -9,6 +10,7 @@ import {css as createSheet} from '@3sln/bones/style';
 hljs.registerLanguage('javascript', javascript);
 hljs.registerLanguage('xml', xml); // For HTML
 hljs.registerLanguage('css', css);
+hljs.registerLanguage('clojure', clojure);
 
 export const stylesheet = createSheet`
   /* Light Theme */

package/src/history.js

@@ -0,0 +1,45 @@
+const history = window.history;
+
+// Function to get the current query parameters as an object
+export function getQueryParams() {
+  const params = new URLSearchParams(window.location.search);
+  return {
+    q: params.get('q') ?? '',
+    c: params.get('c') ?? null,
+  };
+}
+
+// Function to update the URL with new state
+// Uses replaceState to avoid polluting the history for rapid changes
+export function replaceState(params) {
+  const url = new URL(window.location);
+  if (params.hasOwnProperty('q')) {
+    if (params.q) url.searchParams.set('q', params.q);
+    else url.searchParams.delete('q');
+  }
+  if (params.hasOwnProperty('c')) {
+    if (params.c) url.searchParams.set('c', params.c);
+    else url.searchParams.delete('c');
+  }
+  history.replaceState({}, '', url.toString());
+}
+
+// Function to push a new state to the history
+// Use this for significant changes, like selecting a new card
+export function pushState(params) {
+  const url = new URL(window.location);
+  if (params.hasOwnProperty('q')) {
+    if (params.q) url.searchParams.set('q', params.q);
+    else url.searchParams.delete('q');
+  }
+  if (params.hasOwnProperty('c')) {
+    if (params.c) url.searchParams.set('c', params.c);
+    else url.searchParams.delete('c');
+  }
+  history.pushState({}, '', url.toString());
+}
+
+// Wrapper for popstate event
+export function onPopState(callback) {
+  window.addEventListener('popstate', callback);
+}

package/src/main.js

@@ -5,6 +5,7 @@ import {Engine, Provider} from '@3sln/ngin';
 import * as db from './db.js';
 import { ThrottledFetcher } from './fetcher.js';
 import {highlight, stylesheet as highlightStylesheet} from './highlight.js';
+import * as history from './history.js';
 import {
   uiStateProvider,
   FilteredCards,
@@ -16,6 +17,7 @@ import {
   RemoveCard,
   PruneCards,
   SetPinnedCards,
+  SearchQuery
 } from './state.js';
 import './deck-demo.js';
 
@@ -43,27 +45,32 @@ const closeIcon = () =>
   );
 
 const searchBar = alias(engine => {
-  return div(
-    {className: 'search-bar'},
-    input({
-      type: 'search',
-      placeholder: 'Search cards...',
-      $styling: {
-        width: '100%',
-        padding: '0.75em 1em',
-        'font-size': '1.1em',
-        border: '1px solid var(--input-border)',
-        'background-color': 'var(--input-bg)',
-        color: 'var(--text-color)',
-        'border-radius': '2em',
-        outline: 'none',
-        transition: 'box-shadow 0.2s',
-      },
-    }).on({
-      focus: e => (e.target.style.boxShadow = '0 0 5px rgba(81, 203, 238, 1)'),
-      blur: e => (e.target.style.boxShadow = 'none'),
-      input: e => engine.dispatch(new SetSearchQuery(e.target.value)),
-    }),
+  const query$ = engine.query(new SearchQuery());
+
+  return watch(query$, query =>
+    div(
+      {className: 'search-bar'},
+      input({
+        type: 'search',
+        placeholder: 'Search cards...',
+        value: query,
+        $styling: {
+          width: '100%',
+          padding: '0.75em 1em',
+          'font-size': '1.1em',
+          border: '1px solid var(--input-border)',
+          'background-color': 'var(--input-bg)',
+          color: 'var(--text-color)',
+          'border-radius': '2em',
+          outline: 'none',
+          transition: 'box-shadow 0.2s',
+        },
+      }).on({
+        focus: e => (e.target.style.boxShadow = '0 0 5px rgba(81, 203, 238, 1)'),
+        blur: e => (e.target.style.boxShadow = 'none'),
+        input: e => engine.dispatch(new SetSearchQuery(e.target.value)),
+      }),
+    ),
   );
 });
 
@@ -301,6 +308,7 @@ export async function renderDeck({target, initialCardsData, pinnedCardPaths}) {
     providers: {
       state: uiStateProvider(),
       fetcher: Provider.fromSingleton(new ThrottledFetcher()),
+      history: Provider.fromSingleton(history),
     },
   });
 
@@ -311,6 +319,16 @@ export async function renderDeck({target, initialCardsData, pinnedCardPaths}) {
   });
   engine.dispatch(new PruneCards(initialCardsData.map(c => c.path)));
 
+  const syncNav = () => {
+    const {q, c} = history.getQueryParams();
+    console.log('q', q);
+    engine.dispatch(new SelectCard(c));
+    engine.dispatch(new SetSearchQuery(q));
+  };
+
+  history.onPopState(syncNav);
+  syncNav();
+
   // Handle HMR
   if (import.meta.hot) {
     import.meta.hot.on('deck:card-changed', ({path}) => {
@@ -323,4 +341,4 @@ export async function renderDeck({target, initialCardsData, pinnedCardPaths}) {
   }
 
   reconcile(target, [app(engine)]);
-}
+}

package/src/state.js

@@ -186,31 +186,57 @@ export class RemoveCard extends Action {
 }
 
 export class SetSearchQuery extends Action {
-  static deps = ['state'];
+  static deps = ['state', 'history'];
   constructor(query) {
     super();
     this.query = query;
   }
-  execute({state}) {
+  execute({state, history}) {
+    if (this.query !== state.state$.value.query) {
+      history.replaceState({q: this.query});
+    }
     state.update(s => ({...s, query: this.query}));
   }
 }
 
 export class SelectCard extends Action {
-  static deps = ['state'];
+  static deps = ['state', 'history'];
   constructor(cardPath) {
     super();
     this.cardPath = cardPath;
   }
-  async execute({state}) {
-    await db.touchCard(this.cardPath);
-    state.update(s => ({...s, selectedCardPath: this.cardPath}));
+  async execute({state, history}) {
+    if (!this.cardPath) {
+      if (state.state$.value.selectedCardPath !== null) {
+        history.pushState({c: null});
+        state.update(s => ({...s, selectedCardPath: null}));
+      }
+      return;
+    }
+
+    const card = await db.getCard(this.cardPath);
+
+    if (card) {
+      if (this.cardPath !== state.state$.value.selectedCardPath) {
+        history.pushState({c: this.cardPath});
+      }
+      await db.touchCard(this.cardPath);
+      state.update(s => ({...s, selectedCardPath: this.cardPath}));
+    } else {
+      if (state.state$.value.selectedCardPath !== null) {
+        history.pushState({c: null});
+      }
+      state.update(s => ({...s, selectedCardPath: null}));
+    }
   }
 }
 
 export class ClearSelection extends Action {
-  static deps = ['state'];
-  execute({state}) {
+  static deps = ['state', 'history'];
+  execute({state, history}) {
+    if (state.state$.value.selectedCardPath !== null) {
+      history.pushState({c: null});
+    }
     state.update(s => ({...s, selectedCardPath: null}));
   }
 }

package/vite-plugin.js

@@ -9,7 +9,7 @@ export default function deckPlugin() {
     name: 'vite-plugin-deck',
 
     resolveId(id) {
-      if (id.startsWith('/@deck-dev-hmr/')) {
+      if (id.startsWith('/@deck-dev-esm/') || id.startsWith('/@deck-dev-src/')) {
         return id;
       }
       return null;
@@ -29,12 +29,10 @@ export default function deckPlugin() {
     },
 
     load(id) {
-      if (id.startsWith('/@deck-dev-hmr/')) {
-        const realPath = decodeURIComponent(id.slice('/@deck-dev-hmr/'.length));
-        const rawPath = realPath + '?raw';
+      if (id.startsWith('/@deck-dev-esm/')) {
+        const realPath = decodeURIComponent(id.slice('/@deck-dev-esm/'.length));
         return `
           import realDefault from '${realPath}';
-          import moduleText from '${rawPath}';
 
           let lastArgs;
           let abortController = new AbortController();
@@ -43,6 +41,36 @@ export default function deckPlugin() {
             lastArgs = import.meta.hot.data.lastArgs;
           }
 
+          export default (...args) => {
+            lastArgs = args;
+            const thisContext = { signal: abortController.signal };
+            realDefault.call(thisContext, ...args);
+          };
+
+          if (import.meta.hot) {
+            import.meta.hot.dispose(data => {
+              data.lastArgs = lastArgs;
+              abortController.abort();
+            });
+
+            import.meta.hot.accept(newModule => {
+              if (newModule && newModule.default && lastArgs) {
+                newModule.default(...lastArgs);
+              }
+            });
+          }
+        `;
+      } 
+      
+      if (id.startsWith('/@deck-dev-src/')) {
+        let realPath = decodeURIComponent(id.slice('/@deck-dev-src/'.length));
+        if (realPath.endsWith('.js')) {
+          realPath = realPath.slice(0, -3);
+        }
+        const rawPath = realPath + '?raw';
+        return `
+          import moduleText from '${rawPath}';
+
           const textObservers = import.meta.hot?.data.textObservers ?? [];
           export const moduleText$ = {
             subscribe: observer => {
@@ -58,24 +86,12 @@ export default function deckPlugin() {
             }
           };
 
-          export default (...args) => {
-            lastArgs = args;
-            const thisContext = { signal: abortController.signal };
-            realDefault.call(thisContext, ...args);
-          };
-
           if (import.meta.hot) {
+            import.meta.hot.accept();
             import.meta.hot.dispose(data => {
-              data.lastArgs = lastArgs;
               data.textObservers = textObservers;
-              abortController.abort();
             });
 
-            import.meta.hot.accept(newModule => {
-              if (newModule && newModule.default && lastArgs) {
-                newModule.default(...lastArgs);
-              }
-            });
             import.meta.hot.on('deck-raw-update', ({urls, text}) => {
               if (!urls.includes('${rawPath}')) {
                 return;
@@ -88,6 +104,7 @@ export default function deckPlugin() {
           }
         `;
       }
+
       return null;
     },
 
@@ -106,7 +123,7 @@ export default function deckPlugin() {
       server.watcher.on('all', (eventName, eventPath) => {
         const projPath = path.relative(resolvedConfig.root, eventPath);
         const webPath = '/' + projPath.replace(/\\/g, '/');
-        const files = getProjectFiles(resolvedConfig.root, devConfig).map(p => `/${p}`);
+        const files = getCardFiles(resolvedConfig.root, devConfig).map(p => `/${p}`);
         if (!files.includes(webPath)) return;
 
         switch (eventName) {
@@ -121,7 +138,7 @@ export default function deckPlugin() {
       });
 
       server.middlewares.use(async (req, res, next) => {
-        if (req.url.endsWith('/')) {
+        if (new URL(req.url, "https://localhost").pathname === '/') {
           const cardPaths = getCardFiles(resolvedConfig.root, devConfig).map(p => `/${p}`);
           const initialCardsData = await Promise.all(cardPaths.map(async (p) => {
             const content = await fs.readFile(path.join(resolvedConfig.root, p), 'utf-8');