litestar-vite-plugin 0.15.0-alpha.3 → 0.15.0-alpha.5

package/dist/js/helpers/htmx.js

@@ -0,0 +1,494 @@
+/**
+ * Litestar HTMX Extension
+ *
+ * Lightweight JSON templating for HTMX with CSRF support.
+ *
+ * Features:
+ * - `hx-swap="json"` - Client-side JSON templating
+ * - Automatic CSRF token injection
+ * - Template syntax: `ls-for`, `ls-if`, `:attr`, `@event`, `${expr}`
+ *
+ * For typed routes, import from your generated routes file:
+ * ```ts
+ * import { route } from '@/generated/routes'
+ * ```
+ *
+ * @example
+ * ```html
+ * <div hx-get="/api/books" hx-swap="json" hx-ext="litestar">
+ *   <template ls-for="book in $data">
+ *     <article :id="`book-${book.id}`">
+ *       <h3>${book.title}</h3>
+ *       <p>${book.author} • ${book.year}</p>
+ *     </article>
+ *   </template>
+ * </div>
+ * ```
+ *
+ * @module
+ */
+import { getCsrfToken } from "./csrf.js";
+const DEBUG = typeof process !== "undefined" && process.env?.NODE_ENV !== "production";
+const cache = new Map();
+const memoStore = new WeakMap();
+// =============================================================================
+// Registration
+// =============================================================================
+export function registerHtmxExtension() {
+    if (typeof window === "undefined" || !window.htmx)
+        return;
+    window.htmx.defineExtension("litestar", {
+        onEvent(name, evt) {
+            if (name === "htmx:configRequest") {
+                const token = getCsrfToken();
+                if (token)
+                    evt.detail.headers["X-CSRF-Token"] = token;
+            }
+            return true;
+        },
+        transformResponse(text, xhr) {
+            if (xhr.getResponseHeader("content-type")?.includes("application/json")) {
+                const d = document.createElement("div");
+                d.textContent = text;
+                return d.innerHTML;
+            }
+            return text;
+        },
+        isInlineSwap: (s) => s === "json",
+        handleSwap(style, target, frag) {
+            if (style === "json") {
+                try {
+                    swapJson(target, JSON.parse(frag.textContent ?? ""));
+                }
+                catch (e) {
+                    target.innerHTML = `<div style="color:red;padding:1rem">${e}</div>`;
+                }
+                return [target];
+            }
+            return [];
+        },
+    });
+    if (DEBUG)
+        console.log("[litestar] htmx extension registered");
+}
+// =============================================================================
+// Note: hx-route functionality removed - use generated routes directly
+// Import route from your generated routes.ts file instead:
+//   import { route } from '@/generated/routes'
+//   element.setAttribute('hx-get', route('my_route', { id: 123 }))
+// =============================================================================
+// =============================================================================
+// JSON Swap Entry Point
+// =============================================================================
+export function swapJson(el, data) {
+    swap(el, rootCtx(data));
+}
+// =============================================================================
+// Core Swap Logic
+// =============================================================================
+function swap(node, ctx, end, parse = false) {
+    // Text nodes: interpolate ${expr}
+    if (node.nodeType === 3) {
+        const g = memo(node, "t", () => {
+            const t = node.textContent ?? "";
+            return compileTextExpr(t);
+        });
+        if (!g)
+            return null;
+        if (!parse)
+            node.textContent = String(g(ctx) ?? "");
+        return node;
+    }
+    // Elements
+    if (node.nodeType === 1) {
+        const el = node;
+        // Template: structural directives
+        if (el.nodeName === "TEMPLATE") {
+            return forDir(el, ctx, end, parse) ?? ifDir(el, ctx, end, parse);
+        }
+        // Process attribute directives
+        let c = ctx;
+        const handlers = memo(el, "a", () => {
+            const h = [];
+            for (const attr of Array.from(el.attributes)) {
+                const d = directives.find((x) => x.match(attr));
+                if (d) {
+                    const handler = d.create(el, attr);
+                    if (handler)
+                        h.push(handler);
+                }
+            }
+            return h;
+        });
+        for (const h of handlers) {
+            if (!parse && c) {
+                const r = h(c, el);
+                if (r !== undefined)
+                    c = r;
+            }
+            if (!c)
+                break;
+        }
+        if (c === false)
+            return el;
+        if (!c)
+            return null;
+        // Recurse children
+        swapKids(el.firstChild, undefined, c, parse);
+        return el;
+    }
+    return null;
+}
+function swapKids(start, end, ctx, parse = false) {
+    let current = start;
+    while (current && current !== end) {
+        const r = swap(current, ctx, end, parse);
+        current = (r ?? current).nextSibling;
+    }
+}
+const directives = [
+    // :attr="expr" - attribute binding
+    {
+        match: (a) => a.name.startsWith(":"),
+        create(_el, a) {
+            const name = a.name.slice(1);
+            const g = expr(a.value);
+            if (!g)
+                return null;
+            return (ctx, el) => {
+                const v = g(ctx);
+                if (name === "class" && typeof v === "object" && v) {
+                    for (const [k, on] of Object.entries(v))
+                        el.classList.toggle(k, Boolean(on));
+                }
+                else if (v == null || v === false) {
+                    el.removeAttribute(name);
+                }
+                else {
+                    el.setAttribute(name, v === true ? "" : String(v));
+                }
+            };
+        },
+    },
+    // @event="expr" - event binding
+    {
+        match: (a) => a.name.startsWith("@"),
+        create(_el, a) {
+            const name = a.name.slice(1);
+            const g = expr(a.value);
+            if (!g)
+                return null;
+            let bound = false;
+            return (ctx, el) => {
+                if (!bound) {
+                    bound = true;
+                    el.addEventListener(name, (e) => g({ ...ctx, $event: e }));
+                }
+            };
+        },
+    },
+    // ls-scope="expr" - change context
+    {
+        match: (a) => a.name === "ls-scope",
+        create(_, a) {
+            const g = expr(a.value);
+            if (!g)
+                return null;
+            return (ctx) => {
+                const d = g(ctx);
+                return d ? childCtx(ctx, d) : false;
+            };
+        },
+    },
+    // ls-text="expr" - text content
+    {
+        match: (a) => a.name === "ls-text",
+        create(_, a) {
+            const g = expr(a.value);
+            if (!g)
+                return null;
+            return (ctx, el) => {
+                el.textContent = String(g(ctx) ?? "");
+            };
+        },
+    },
+    // ls-html="expr" - innerHTML (use carefully)
+    {
+        match: (a) => a.name === "ls-html",
+        create(_, a) {
+            const g = expr(a.value);
+            if (!g)
+                return null;
+            return (ctx, el) => {
+                el.innerHTML = String(g(ctx) ?? "");
+            };
+        },
+    },
+    // ls-show/ls-hide
+    {
+        match: (a) => a.name === "ls-show",
+        create(_, a) {
+            const g = expr(a.value);
+            if (!g)
+                return null;
+            return (ctx, el) => {
+                ;
+                el.style.display = g(ctx) ? "" : "none";
+            };
+        },
+    },
+    {
+        match: (a) => a.name === "ls-hide",
+        create(_, a) {
+            const g = expr(a.value);
+            if (!g)
+                return null;
+            return (ctx, el) => {
+                ;
+                el.style.display = g(ctx) ? "none" : "";
+            };
+        },
+    },
+    // name attr on inputs - auto-bind from context
+    {
+        match: (a) => a.name === "name",
+        create(el, a) {
+            if (!(el instanceof HTMLInputElement || el instanceof HTMLSelectElement || el instanceof HTMLTextAreaElement))
+                return null;
+            const key = a.value;
+            return (ctx, el) => {
+                const v = ctx[key];
+                if (v === undefined)
+                    return;
+                const inp = el;
+                if (inp.type === "checkbox")
+                    inp.checked = Boolean(v);
+                else if (inp.type === "radio")
+                    inp.checked = v === inp.value;
+                else
+                    inp.value = String(v ?? "");
+            };
+        },
+    },
+];
+// =============================================================================
+// Structural: ls-for
+// =============================================================================
+function forDir(tpl, ctx, _parentEnd, parse = false) {
+    const raw = tpl.getAttribute("ls-for") ?? tpl.getAttribute("ls-each");
+    if (!raw)
+        return null;
+    preparseTpl(tpl);
+    if (parse)
+        return tpl;
+    // Parse "item in items" or just "items"
+    const m = raw.match(/^\s*(\w+)\s+in\s+(.+)$/);
+    const [alias, listExpr] = m ? [m[1], m[2]] : [null, raw];
+    const g = memo(tpl, "g", () => expr(listExpr));
+    if (!g)
+        return null;
+    const items = toList(g(ctx), tpl, ctx, alias);
+    const end = memo(tpl, "end", () => insertComment(tpl, "/ls-for"));
+    const old = memo(tpl, "list", () => collectComments(tpl, end));
+    let i = 0;
+    for (; i < items.length; i++) {
+        const [key, item] = items[i];
+        const c = childCtx(ctx, item, i, key);
+        if (alias)
+            c[alias] = item;
+        if (i < old.length && old[i][0] === key) {
+            // Same key: update in place
+            swapKids(old[i][1].nextSibling, old[i + 1]?.[1] ?? end, c);
+        }
+        else {
+            // Insert new
+            const clone = tpl.content.cloneNode(true);
+            const comment = document.createComment(key);
+            const ref = old[i]?.[1] ?? end;
+            ref.parentNode?.insertBefore(comment, ref);
+            ref.parentNode?.insertBefore(clone, ref);
+            swapKids(comment.nextSibling, ref, c);
+            // Remove old if exists
+            if (i < old.length) {
+                removeBetween(old[i][1], old[i + 1]?.[1] ?? end);
+                old[i][1].remove();
+            }
+            old[i] = [key, comment];
+        }
+    }
+    // Remove excess
+    while (old.length > items.length) {
+        const popped = old.pop();
+        if (!popped)
+            break;
+        const [, c] = popped;
+        removeBetween(c, old[old.length]?.[1] ?? end);
+        c.remove();
+    }
+    return end;
+}
+// =============================================================================
+// Structural: ls-if
+// =============================================================================
+function ifDir(tpl, ctx, _parentEnd, parse = false) {
+    const raw = tpl.getAttribute("ls-if");
+    if (!raw)
+        return null;
+    preparseTpl(tpl);
+    // Find else template
+    const elseTpl = tpl.nextElementSibling?.nodeName === "TEMPLATE" && tpl.nextElementSibling.hasAttribute("ls-else") ? tpl.nextElementSibling : null;
+    if (elseTpl)
+        preparseTpl(elseTpl);
+    if (parse)
+        return elseTpl ?? tpl;
+    const g = memo(tpl, "g", () => expr(raw));
+    const anchor = memo(tpl, "anchor", () => insertComment(tpl, ""));
+    const end = memo(tpl, "end", () => insertComment(anchor, "/ls-if"));
+    const show = g?.(ctx);
+    if (show) {
+        if (anchor.data !== "if") {
+            anchor.data = "if";
+            removeBetween(anchor.nextSibling, end);
+            end.parentNode?.insertBefore(tpl.content.cloneNode(true), end);
+        }
+        swapKids(anchor.nextSibling, end, ctx);
+    }
+    else if (elseTpl) {
+        if (anchor.data !== "else") {
+            anchor.data = "else";
+            removeBetween(anchor.nextSibling, end);
+            end.parentNode?.insertBefore(elseTpl.content.cloneNode(true), end);
+        }
+        swapKids(anchor.nextSibling, end, ctx);
+    }
+    else {
+        anchor.data = "";
+        removeBetween(anchor.nextSibling, end);
+    }
+    return end;
+}
+// =============================================================================
+// Context
+// =============================================================================
+function rootCtx(data) {
+    const ctx = {
+        $data: data,
+        // Note: route and navigate are optional - users can provide their own
+        // by importing from their generated routes.ts file
+    };
+    if (data && typeof data === "object")
+        Object.setPrototypeOf(ctx, data);
+    return ctx;
+}
+function childCtx(parent, data, index, key) {
+    const ctx = Object.create(data && typeof data === "object" ? data : null);
+    ctx.$data = data;
+    ctx.$parent = parent;
+    ctx.$index = index;
+    ctx.$key = key;
+    ctx.route = parent.route;
+    ctx.navigate = parent.navigate;
+    return ctx;
+}
+// =============================================================================
+// Expression Compiler
+// =============================================================================
+function expr(s) {
+    if (!s)
+        return null;
+    const cached = cache.get(s);
+    if (cached !== undefined)
+        return cached;
+    try {
+        const fn = new Function("ctx", `with(ctx){return(${s})}`);
+        cache.set(s, fn);
+        return fn;
+    }
+    catch {
+        cache.set(s, null);
+        return null;
+    }
+}
+/** Compile text with ${expr} interpolation - escapes backticks and backslashes */
+function compileTextExpr(t) {
+    if (!t.includes("${"))
+        return null;
+    // Escape backticks and backslashes for safe template literal compilation
+    const escaped = t.replace(/[`\\]/g, "\\$&");
+    return expr(`\`${escaped}\``);
+}
+// =============================================================================
+// Utilities
+// =============================================================================
+function memo(node, key, fn) {
+    let store = memoStore.get(node);
+    if (!store) {
+        store = {};
+        memoStore.set(node, store);
+    }
+    if (!(key in store)) {
+        store[key] = fn();
+    }
+    return store[key];
+}
+function preparseTpl(t) {
+    memo(t, "p", () => {
+        swapKids(t.content.firstChild, undefined, {}, true);
+        return true;
+    });
+}
+function toList(items, tpl, ctx, alias) {
+    const keyAttr = tpl.getAttribute("ls-key");
+    const keyFn = keyAttr ? expr(keyAttr) : null;
+    if (Array.isArray(items)) {
+        return items.map((item, i) => {
+            if (!keyFn)
+                return [String(i), item];
+            // Create a child context with the alias so key expressions like "item.id" work
+            const keyCtx = childCtx(ctx, item, i);
+            if (alias)
+                keyCtx[alias] = item;
+            return [String(keyFn(keyCtx)), item];
+        });
+    }
+    if (items && typeof items === "object") {
+        return Object.entries(items);
+    }
+    return [];
+}
+function insertComment(after, text) {
+    const c = document.createComment(text);
+    after.parentNode?.insertBefore(c, after.nextSibling);
+    return c;
+}
+function collectComments(tpl, end) {
+    const list = [];
+    let n = tpl.nextSibling;
+    while (n && n !== end) {
+        if (n.nodeType === 8 && !n.data.startsWith("/")) {
+            list.push([n.data, n]);
+        }
+        n = n.nextSibling;
+    }
+    return list;
+}
+function removeBetween(start, end) {
+    let current = start;
+    while (current && current !== end) {
+        const next = current.nextSibling;
+        current.parentNode?.removeChild(current);
+        current = next;
+    }
+}
+// =============================================================================
+// Public API
+// =============================================================================
+export function setDebug(_on) {
+    // Debug flag is const, this is a no-op placeholder
+}
+export function addDirective(dir) {
+    directives.push(dir);
+}
+// Auto-register
+if (typeof window !== "undefined" && window.htmx)
+    registerHtmxExtension();

package/dist/js/helpers/index.d.ts

@@ -6,10 +6,10 @@
  *
  * @example
  * ```ts
- * import { route, getCsrfToken, csrfFetch } from 'litestar-vite-plugin/helpers'
+ * import { getCsrfToken, csrfFetch } from 'litestar-vite-plugin/helpers'
  *
- * // Generate a URL for a named route
- * const url = route('user:detail', { user_id: 123 })
+ * // Get CSRF token
+ * const token = getCsrfToken()
  *
  * // Make a fetch request with CSRF token
  * await csrfFetch('/api/submit', {
@@ -18,7 +18,15 @@
  * })
  * ```
  *
+ * For type-safe routing, import from your generated routes file:
+ * ```ts
+ * import { route, routes, type RouteName } from '@/generated/routes'
+ *
+ * // Type-safe URL generation
+ * const url = route('user_detail', { user_id: 123 })  // Compile-time checked!
+ * ```
+ *
  * @module
  */
-export { getCsrfToken, csrfHeaders, csrfFetch } from "./csrf.js";
-export { route, getRoutes, toRoute, currentRoute, isRoute, isCurrentRoute, getRelativeUrlPath, LITESTAR, type RouteDefinition, type RoutesMap, type LitestarHelpers, } from "./routes.js";
+export { csrfFetch, csrfHeaders, getCsrfToken } from "./csrf.js";
+export { addDirective, registerHtmxExtension, setDebug as setHtmxDebug, swapJson } from "./htmx.js";

package/dist/js/helpers/index.js

@@ -6,10 +6,10 @@
  *
  * @example
  * ```ts
- * import { route, getCsrfToken, csrfFetch } from 'litestar-vite-plugin/helpers'
+ * import { getCsrfToken, csrfFetch } from 'litestar-vite-plugin/helpers'
  *
- * // Generate a URL for a named route
- * const url = route('user:detail', { user_id: 123 })
+ * // Get CSRF token
+ * const token = getCsrfToken()
  *
  * // Make a fetch request with CSRF token
  * await csrfFetch('/api/submit', {
@@ -18,9 +18,17 @@
  * })
  * ```
  *
+ * For type-safe routing, import from your generated routes file:
+ * ```ts
+ * import { route, routes, type RouteName } from '@/generated/routes'
+ *
+ * // Type-safe URL generation
+ * const url = route('user_detail', { user_id: 123 })  // Compile-time checked!
+ * ```
+ *
  * @module
  */
 // CSRF utilities
-export { getCsrfToken, csrfHeaders, csrfFetch } from "./csrf.js";
-// Route utilities
-export { route, getRoutes, toRoute, currentRoute, isRoute, isCurrentRoute, getRelativeUrlPath, LITESTAR, } from "./routes.js";
+export { csrfFetch, csrfHeaders, getCsrfToken } from "./csrf.js";
+// HTMX utilities
+export { addDirective, registerHtmxExtension, setDebug as setHtmxDebug, swapJson } from "./htmx.js";

package/dist/js/index.d.ts

@@ -1,4 +1,3 @@
-import { type ConfigEnv, type Plugin, type UserConfig } from "vite";
 import { type Config as FullReloadConfig } from "vite-plugin-full-reload";
 /**
  * Configuration for TypeScript type generation.
@@ -74,6 +73,13 @@ export interface PluginConfig {
      * @default 'public/dist'
      */
     bundleDirectory?: string;
+    /**
+     * Vite's public directory for static, unprocessed assets.
+     * Mirrors Vite's `publicDir` option.
+     *
+     * @default 'public'
+     */
+    publicDir?: string;
     /**
      * Litestar's public assets directory.  These are the assets that Vite will serve when developing.
      *
@@ -122,18 +128,36 @@ export interface PluginConfig {
     /**
      * Enable and configure TypeScript type generation.
      *
-     * When set to `true`, enables type generation with default settings.
-     * When set to a TypesConfig object, enables type generation with custom settings.
+     * Configuration priority (highest to lowest):
+     * 1. Explicit vite.config.ts value - ALWAYS wins
+     * 2. .litestar.json value - used if no explicit config
+     * 3. Hardcoded defaults - fallback if nothing else
+     *
+     * When set to `"auto"` (recommended): reads all config from `.litestar.json`.
+     * If `.litestar.json` is missing, type generation is disabled.
+     *
+     * When set to `true`: enables type generation with hardcoded defaults.
+     * When set to `false`: disables type generation entirely.
+     * When set to a TypesConfig object: uses your explicit settings.
      *
-     * Type generation creates TypeScript types from your Litestar OpenAPI schema
-     * and route metadata using @hey-api/openapi-ts.
+     * When not specified (undefined): behaves like `"auto"` - reads from
+     * `.litestar.json` if present, otherwise disabled.
      *
      * @example
      * ```ts
-     * // Simple enable
+     * // Recommended: auto-read from .litestar.json (simplest)
+     * litestar({ input: 'src/main.ts' })
+     *
+     * // Explicit auto mode
+     * litestar({ input: 'src/main.ts', types: 'auto' })
+     *
+     * // Force enable with hardcoded defaults (ignores .litestar.json)
      * litestar({ input: 'src/main.ts', types: true })
      *
-     * // With custom config
+     * // Force disable
+     * litestar({ input: 'src/main.ts', types: false })
+     *
+     * // Manual override (ignores .litestar.json for types)
      * litestar({
      *   input: 'src/main.ts',
      *   types: {
@@ -144,9 +168,9 @@ export interface PluginConfig {
      * })
      * ```
      *
-     * @default false
+     * @default undefined (auto-detect from .litestar.json)
      */
-    types?: boolean | TypesConfig;
+    types?: boolean | "auto" | TypesConfig;
     /**
      * JavaScript runtime executor for package commands.
      * Used when running tools like @hey-api/openapi-ts.
@@ -162,15 +186,13 @@ interface RefreshConfig {
     paths: string[];
     config?: FullReloadConfig;
 }
-interface LitestarPlugin extends Plugin {
-    config: (config: UserConfig, env: ConfigEnv) => UserConfig;
-}
 type DevServerUrl = `${"http" | "https"}://${string}:${number}`;
 export declare const refreshPaths: string[];
 /**
  * Litestar plugin for Vite.
  *
  * @param config - A config object or relative path(s) of the scripts to be compiled.
+ * @returns An array of Vite plugins. Return type is `any[]` to avoid cross-version type conflicts.
  */
-export default function litestar(config: string | string[] | PluginConfig): [LitestarPlugin, ...Plugin[]];
+export default function litestar(config: string | string[] | PluginConfig): any[];
 export {};