htmx-router 1.0.0-alpha.4 → 1.0.0-alpha.6

package/shell.d.ts

@@ -0,0 +1,120 @@
+export type ShellOptions<D = {}> = D & MetaDescriptor;
+export declare function ApplyMetaDescriptorDefaults(options: ShellOptions, defaults: Readonly<Partial<ShellOptions>>): void;
+export type InferShellOptions<F> = F extends (jsx: any, options: infer U) => any ? U : never;
+export type MetaDescriptor = {
+    title?: string;
+    description?: string;
+    meta?: Record<string, string>;
+    og?: OpenGraph<string>;
+    jsonLD?: LdJsonObject[];
+};
+export declare function RenderMetaDescriptor<T>(options: ShellOptions<T>): string;
+export type LdJsonObject = {
+    [Key in string]?: LdJsonValue | undefined;
+};
+type LdJsonArray = LdJsonValue[] | readonly LdJsonValue[];
+type LdJsonPrimitive = string | number | boolean | null;
+type LdJsonValue = LdJsonPrimitive | LdJsonObject | LdJsonArray;
+export type OpenGraphType = "website" | "article" | "book" | "profile" | "music.song" | "music.album" | "music.playlist" | "music.radio_station" | "video.movie" | "video.episode" | "video.tv_show" | "video.other" | string;
+export type OpenGraph<T extends OpenGraphType = string> = {
+    type?: T;
+    title?: string;
+    description?: string;
+    determiner?: string;
+    url?: string;
+    secure_url?: string;
+    locale?: string | {
+        base: string;
+        alternative: string[];
+    };
+    image?: OpenGraphImage[];
+    video?: OpenGraphVideo[];
+    audio?: OpenGraphAudio[];
+} & (T extends "music.song" ? OpenGraphSong : T extends "music.album" ? OpenGraphAlbum : T extends "music.playlist" ? OpenGraphPlaylist : T extends "music.radio_station" ? OpenGraphRadioStation : T extends "video.movie" ? OpenGraphMovie : T extends "video.episode" ? OpenGraphEpisode : T extends "video.tv_show" ? OpenGraphTvShow : T extends "video.other" ? OpenGraphVideoOther : T extends "article" ? OpenGraphArticle : T extends "book" ? OpenGraphBook : T extends "profile" ? OpenGraphProfile : {});
+export type OpenGraphImage = {
+    url: string;
+    secure_url?: string;
+    type?: string;
+    width?: number;
+    height?: number;
+    alt?: string;
+};
+export type OpenGraphVideo = {
+    url: string;
+    type?: string;
+    secure_url?: string;
+    width?: number;
+    height?: number;
+    alt?: string;
+};
+export type OpenGraphAudio = {
+    url: string;
+    type?: string;
+    secure_url?: string;
+};
+type OpenGraphSong = {
+    duration?: number;
+    album?: Array<string | {
+        url: string;
+        disc?: number;
+        track?: number;
+    }>;
+    musician?: string[];
+};
+type OpenGraphAlbum = {
+    songs?: Array<string | {
+        url: string;
+        disc?: number;
+        track?: number;
+    }>;
+    musician?: string[];
+    release_date?: Date;
+};
+type OpenGraphPlaylist = {
+    songs?: Array<string | {
+        url: string;
+        disc?: number;
+        track?: number;
+    }>;
+    creator?: string[];
+};
+type OpenGraphRadioStation = {
+    creator?: string[];
+};
+type OpenGraphMovie = {
+    actors?: Array<string | {
+        url: string;
+        role: string;
+    }>;
+    directors?: string[];
+    writers?: string[];
+    duration?: number;
+    release_date?: Date;
+    tag: string[];
+};
+type OpenGraphEpisode = OpenGraphMovie & {
+    series?: string;
+};
+type OpenGraphTvShow = OpenGraphMovie;
+type OpenGraphVideoOther = OpenGraphMovie;
+type OpenGraphArticle = {
+    published_time?: Date;
+    modified_time?: Date;
+    expiration_time?: Date;
+    authors?: string[];
+    section?: string;
+    tag?: string;
+};
+type OpenGraphBook = {
+    authors?: string[];
+    isbn?: string;
+    release_date?: Date;
+    tag?: string;
+};
+type OpenGraphProfile = {
+    first_name?: string;
+    last_name?: string;
+    username?: string;
+    gender?: "male" | "female";
+};
+export {};

package/shell.js

@@ -0,0 +1,253 @@
+import { ServerOnlyWarning } from "./internal/util.js";
+ServerOnlyWarning("shell");
+export function ApplyMetaDescriptorDefaults(options, defaults) {
+    if (defaults.title && !options.title)
+        options.title = defaults.title;
+    if (defaults.description && !options.description)
+        options.description = defaults.description;
+    if (defaults.meta && !options.meta)
+        options.meta = defaults.meta;
+    if (defaults.og && !options.og)
+        options.og = defaults.og;
+    if (defaults.jsonLD && !options.jsonLD)
+        options.jsonLD = defaults.jsonLD;
+}
+export function RenderMetaDescriptor(options) {
+    let out = "";
+    if (options.title)
+        out += `<title>${EscapeHTML(options.title)}</title>`;
+    if (options.description)
+        out += `<meta name="description" content="${EscapeHTML(options.description)}">\n`;
+    if (options.meta)
+        for (const key in options.meta) {
+            out += `<meta name="${EscapeHTML(key)}" content="${EscapeHTML(options.meta[key])}">\n`;
+        }
+    if (options.jsonLD)
+        for (const json of options.jsonLD) {
+            out += `<script type="application/ld+json">${JSON.stringify(json)}</script>\n`;
+        }
+    // Auto apply og:title + og:description if not present
+    if (options.title && !options.og?.title)
+        out += `<meta property="og:title" content="${EscapeHTML(options.title)}">\n`;
+    if (options.description && !options.og?.description)
+        out += `<meta property="og:description" content="${EscapeHTML(options.description)}">\n`;
+    // Apply open graphs
+    if (options.og)
+        out += RenderOpenGraph(options.og);
+    return out;
+}
+function RenderOpenGraph(og) {
+    // Manually encoding everything rather than using a loop to ensure they are in the correct order
+    // And to ensure extra values can't leak in creating unsafe og tags
+    const type = og.type || "website";
+    let out = RenderProperty("og:type", type);
+    if (og.title)
+        out += RenderProperty("og:title", og.title);
+    if (og.description)
+        out += RenderProperty("og:description", og.description);
+    if (og.determiner)
+        out += RenderProperty("og:determiner", og.determiner);
+    if (og.url)
+        out += RenderProperty("og:url", og.url);
+    if (og.secure_url)
+        out += RenderProperty("og:secure_url", og.secure_url);
+    if (og.locale) {
+        if (typeof og.locale === "string")
+            out += RenderProperty("og:locale", og.locale);
+        else {
+            out += RenderProperty("og:locale", og.locale.base);
+            for (const l of og.locale.alternative)
+                out += RenderProperty("og:locale:alternative", l);
+        }
+    }
+    if (og.image)
+        for (const img of og.image) {
+            out += RenderProperty("og:image", img.url);
+            if (img.secure_url)
+                out += RenderProperty("og:image:secure_url", img.secure_url);
+            if (img.type)
+                out += RenderProperty("og:image:type", img.type);
+            if (img.width)
+                out += RenderProperty("og:image:width", img.width.toString());
+            if (img.height)
+                out += RenderProperty("og:image:height", img.height.toString());
+            if (img.alt)
+                out += RenderProperty("og:image:alt", img.alt);
+        }
+    if (og.video)
+        for (const vid of og.video) {
+            out += RenderProperty("og:video", vid.url);
+            if (vid.secure_url)
+                out += RenderProperty("og:video:secure_url", vid.secure_url);
+            if (vid.type)
+                out += RenderProperty("og:video:type", vid.type);
+            if (vid.width)
+                out += RenderProperty("og:video:width", vid.width.toString());
+            if (vid.height)
+                out += RenderProperty("og:video:height", vid.height.toString());
+            if (vid.alt)
+                out += RenderProperty("og:video:alt", vid.alt);
+        }
+    if (og.audio)
+        for (const audio of og.audio) {
+            out += RenderProperty("og:audio", audio.url);
+            if (audio.secure_url)
+                out += RenderProperty("og:audio:secure_url", audio.secure_url);
+            if (audio.type)
+                out += RenderProperty("og:audio:type", audio.type);
+        }
+    return out + RenderOpenGraphExtras(og);
+}
+function RenderProperty(name, value) {
+    return `<meta property="${name}" content="${EscapeHTML(value)}">\n`;
+}
+function RenderOpenGraphExtras(og) {
+    let out = "";
+    if (og.type === "music.song") {
+        const g = og;
+        if (g.duration)
+            out += RenderProperty("og:music:duration", g.duration.toString());
+        if (g.album)
+            for (const album of g.album) {
+                if (typeof album === "string")
+                    out += RenderProperty("og:music:album", album);
+                else {
+                    out += RenderProperty("og:music:album", album.url);
+                    if (album.disc)
+                        out += RenderProperty("og:music:album:disc", album.disc.toString());
+                    if (album.track)
+                        out += RenderProperty("og:music:album:track", album.track.toString());
+                }
+            }
+        if (g.musician)
+            for (const profile of g.musician)
+                out += RenderProperty("og:music:musician", profile);
+        return out;
+    }
+    if (og.type === "music.album") {
+        const g = og;
+        if (g.songs)
+            for (const song of g.songs) {
+                if (typeof song === "string")
+                    out += RenderProperty("og:music:song", song);
+                else {
+                    out += RenderProperty("og:music:song", song.url);
+                    if (song.disc)
+                        out += RenderProperty("og:music:song:disc", song.disc.toString());
+                    if (song.track)
+                        out += RenderProperty("og:music:song:track", song.track.toString());
+                }
+            }
+        if (g.musician)
+            for (const profile of g.musician)
+                out += RenderProperty("og:music:musician", profile);
+        if (g.release_date)
+            out += RenderProperty("og:music:release_date", g.release_date.toISOString());
+        return out;
+    }
+    if (og.type === "music.playlist") {
+        const g = og;
+        if (g.songs)
+            for (const song of g.songs) {
+                if (typeof song === "string")
+                    out += RenderProperty("og:music:song", song);
+                else {
+                    out += RenderProperty("og:music:song", song.url);
+                    if (song.disc)
+                        out += RenderProperty("og:music:song:disc", song.disc.toString());
+                    if (song.track)
+                        out += RenderProperty("og:music:song:track", song.track.toString());
+                }
+            }
+        if (g.creator)
+            for (const profile of g.creator)
+                out += RenderProperty("og:music:creator", profile);
+        return out;
+    }
+    if (og.type === "music.radio_station") {
+        const g = og;
+        if (g.creator)
+            for (const profile of g.creator)
+                out += RenderProperty("og:music:creator", profile);
+        return out;
+    }
+    if (og.type === "video.movie" || og.type === "video.episode" || og.type === "video.tv_show" || og.type === "video.other") {
+        const g = og;
+        if (g.actors)
+            for (const actor of g.actors) {
+                if (typeof actor === "string")
+                    out += RenderProperty("og:video:actor", actor);
+                else {
+                    out += RenderProperty("og:video:actor", actor.url);
+                    out += RenderProperty("og:video:actor:role", actor.role);
+                }
+            }
+        if (g.directors)
+            for (const profile of g.directors)
+                out += RenderProperty("og:video:director", profile);
+        if (g.writers)
+            for (const profile of g.writers)
+                out += RenderProperty("og:video:writer", profile);
+        if (g.duration)
+            out += RenderProperty("og:video:duration", g.duration.toString());
+        if (g.release_date)
+            out += RenderProperty("og:video:release_date", g.release_date.toISOString());
+        if (g.tag)
+            for (const tag of g.tag)
+                out += RenderProperty("og:video:tag", tag);
+        if (g.series)
+            out += RenderProperty("og:video:series", g.series);
+    }
+    if (og.type === "article") {
+        const g = og;
+        if (g.published_time)
+            out += RenderProperty("og:article:published_time", g.published_time.toISOString());
+        if (g.modified_time)
+            out += RenderProperty("og:article:modified_time", g.modified_time.toISOString());
+        if (g.expiration_time)
+            out += RenderProperty("og:article:expiration_time", g.expiration_time.toISOString());
+        if (g.authors)
+            for (const profile of g.authors)
+                out += RenderProperty("og:article:author", profile);
+        if (g.section)
+            out += RenderProperty("og:article:section", g.section);
+        if (g.tag)
+            for (const tag of g.tag)
+                out += RenderProperty("og:video:tag", tag);
+    }
+    if (og.type === "book") {
+        const g = og;
+        if (g.authors)
+            for (const profile of g.authors)
+                out += RenderProperty("og:article:author", profile);
+        if (g.isbn)
+            out += RenderProperty("og:book:isbn", g.isbn);
+        if (g.release_date)
+            out += RenderProperty("og:book:release_date", g.release_date.toISOString());
+        if (g.tag)
+            for (const tag of g.tag)
+                out += RenderProperty("og:video:tag", tag);
+    }
+    if (og.type === "profile") {
+        const g = og;
+        if (g.first_name)
+            out += RenderProperty("og:profile:first_name", g.first_name);
+        if (g.last_name)
+            out += RenderProperty("og:profile:last_name", g.last_name);
+        if (g.username)
+            out += RenderProperty("og:profile:username", g.username);
+        if (g.gender)
+            out += RenderProperty("og:profile:gender", g.gender);
+    }
+    return "";
+}
+const escapeTo = {
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    "\"": "&quot;",
+    "'": "&#39;",
+};
+function EscapeHTML(str) {
+    return str.replace(/[&<>"']/g, (match) => escapeTo[match] || match);
+}

package/{bin/util → util}/parameters.d.ts

@@ -1,6 +1,3 @@
-/**
- * This is used by GenericContext to convert itself to a RouteContext<T>
- */
 export type Parameterized<T extends ParameterShaper> = {
     [K in keyof T]: ReturnType<T[K]>;
 };

package/{bin/util → util}/parameters.js

@@ -1,6 +1,3 @@
-/**
- * This is used by GenericContext to convert itself to a RouteContext<T>
- */
 export function Parameterize(params, shape) {
     const out = {};
     for (const key in shape) {

package/{bin/util → util}/path-builder.js

@@ -1,3 +1,5 @@
+import { ServerOnlyWarning } from "../internal/util.js";
+ServerOnlyWarning("path-builder");
 import { relative } from "path";
 /*
 // This feature is disabled because vite doesn't compile import.meta.url to the original url when making the SSR build

package/util/route.d.ts

@@ -0,0 +1,2 @@
+import { ParameterShaper } from "./parameters.js";
+export declare function RoutePath<T extends ParameterShaper>(): (params: { [K in keyof T]: string; }) => string;

package/util/route.js

@@ -0,0 +1,58 @@
+import { ServerOnlyWarning } from "../internal/util.js";
+ServerOnlyWarning("route-path");
+export function RoutePath() {
+    const frags = new Array();
+    return (params) => {
+        const t = params;
+        if (typeof t === "string") {
+            Compile("/" + t, frags);
+            return "";
+        }
+        return Parse(frags, params);
+    };
+}
+const indexRoute = "/_index";
+function Compile(url, into) {
+    let cursor = 0;
+    let i = 1;
+    for (; i < url.length; i++) {
+        if (url[i] !== "$")
+            continue;
+        if (url[i - 1] !== "/")
+            continue;
+        let e = url.indexOf("/", i + 1);
+        if (e === -1)
+            e = url.length;
+        into.push(url.slice(cursor, i));
+        into.push(url.slice(i, e));
+        cursor = e;
+        i = e - 1;
+    }
+    // remainder
+    if (cursor != i)
+        into.push(url.slice(cursor));
+    // remove _index from end if present
+    const lastI = into.length - 1;
+    const last = into[lastI];
+    if (last && last.endsWith(indexRoute)) {
+        if (last.length === indexRoute.length)
+            into.length--;
+        else
+            into[lastI] = last.slice(0, -indexRoute.length);
+    }
+}
+function Parse(fragments, params) {
+    let out = "";
+    for (const frag of fragments) {
+        if (!frag.startsWith("$")) {
+            out += frag;
+            continue;
+        }
+        const key = frag.slice(1);
+        const param = params[key];
+        if (!param)
+            throw new Error(`Missing ${key} parameter required for route`);
+        out += param;
+    }
+    return out;
+}

package/vite/bundle-splitter.d.ts

@@ -0,0 +1,4 @@
+import type { UserConfig } from "vite";
+type Plugin = NonNullable<UserConfig["plugins"]>[number];
+export declare function BundleSplitter(): Plugin;
+export {};

package/vite/bundle-splitter.js

@@ -0,0 +1,26 @@
+import { ServerOnlyWarning } from "../internal/util.js";
+ServerOnlyWarning("bundle-splitter");
+const serverPattern = /\.server\.[tj]s(x)?/;
+const clientPattern = /\.client\.[tj]s(x)?/;
+const BLANK_MODULE = "export {};";
+export function BundleSplitter() {
+    return {
+        name: "htmx-bundle-splitter",
+        enforce: "pre",
+        transform: (code, id, options) => {
+            const ssr = options?.ssr || false;
+            const pattern = ssr ? clientPattern : serverPattern;
+            if (pattern.test(id))
+                return BLANK_MODULE;
+            if (ssr) {
+                if (code.startsWith('"use client"'))
+                    return BLANK_MODULE;
+            }
+            else {
+                if (code.startsWith('"use server"'))
+                    return BLANK_MODULE;
+            }
+            return code;
+        }
+    };
+}

package/vite/client-island.d.ts

@@ -0,0 +1,4 @@
+import type { Plugin } from "vite";
+type SupportedFramework = "react";
+export declare function ClientIsland(framework: SupportedFramework): Plugin;
+export {};

package/vite/client-island.js

@@ -0,0 +1,14 @@
+import { resolve } from "path";
+import { CompileManifest } from "../internal/compile/manifest.js";
+export function ClientIsland(framework) {
+    const file = resolve("./app/manifest.tsx").replaceAll("\\", "/");
+    return {
+        name: "vite-plugin-htmx-client-island",
+        enforce: "pre",
+        transform: (code, id, options) => {
+            if (id !== file)
+                return code;
+            return CompileManifest(framework, code, options?.ssr || false);
+        }
+    };
+}

package/vite/code-splitting.d.ts

@@ -0,0 +1,4 @@
+import type { UserConfig } from "vite";
+type Plugin = NonNullable<UserConfig["plugins"]>[number];
+export declare function BundleSplitting(): Plugin;
+export {};

package/vite/code-splitting.js

@@ -0,0 +1,14 @@
+const serverPattern = /\.server\.[tj]s(x)?/;
+const clientPattern = /\.client\.[tj]s(x)?/;
+export function BundleSplitting() {
+    return {
+        name: "htmx-bundle-splitter",
+        enforce: "pre",
+        transform: (code, id, options) => {
+            const pattern = options?.ssr ? clientPattern : serverPattern;
+            if (pattern.test(id))
+                return "export {};";
+            return code;
+        }
+    };
+}

package/vite/index.d.ts

@@ -0,0 +1,3 @@
+import { BundleSplitter } from "./bundle-splitter.js";
+import { ClientIsland } from "./client-island.js";
+export { BundleSplitter, ClientIsland };

package/vite/index.js

@@ -0,0 +1,3 @@
+import { BundleSplitter } from "./bundle-splitter.js";
+import { ClientIsland } from "./client-island.js";
+export { BundleSplitter, ClientIsland };

package/vite/router.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin } from "vite";
+export declare function Router(): Plugin;

package/vite/router.js

@@ -0,0 +1,29 @@
+export function Router() {
+    const virtualModuleId = "virtual:htmx-router/dynamic.tsx";
+    const resolvedVirtualModuleId = '\0' + virtualModuleId;
+    return {
+        name: "vite-plugin-htmx-router",
+        resolveId(id) {
+            if (id === virtualModuleId)
+                return resolvedVirtualModuleId;
+        },
+        load(id) {
+            if (id !== resolvedVirtualModuleId)
+                return;
+            return source;
+        }
+    };
+}
+const source = `export function Scripts() {
+	if (headCache) return headCache;
+
+	const res = <>
+		<link href={GetSheetUrl()} rel="stylesheet"></link>
+		{ isProduction ? "" : <script type="module" src="/@vite/client"></script> }
+		<script type="module" src={clientEntry}></script>
+		<script src={GetMountUrl()}></script>
+	</>;
+
+	if (isProduction) headCache = res;
+	return res;
+}`;

package/bin/cli/config.d.ts

@@ -1,10 +0,0 @@
-export declare function ReadConfig(): Promise<{
-    client?: {
-        adapter: string;
-        source: string;
-    };
-    router: {
-        folder: string;
-        output: string;
-    };
-}>;

package/bin/cli/config.js

@@ -1,4 +0,0 @@
-import { readFile } from "fs/promises";
-export async function ReadConfig() {
-    return JSON.parse(await readFile(process.argv[2] || "./htmx-router.json", "utf-8"));
-}

package/bin/cli/index.js

@@ -1,72 +0,0 @@
-#!/usr/bin/env node
-"use strict";
-import { writeFile } from "fs/promises";
-import { relative } from "path";
-import { GenerateClient } from "../client/index.js";
-import { ReadConfig } from "../cli/config.js";
-const config = await ReadConfig();
-console.info("Building router");
-const routes = relative(config.router.output, config.router.folder).replaceAll("\\", "/").slice(1);
-await writeFile(config.router.output, `/*------------------------------------------
- * Generated by htmx-router                *
- * Warn: Any changes will be overwritten   *
--------------------------------------------*/
-/* eslint-disable @typescript-eslint/no-explicit-any */
-
-import { GenericContext, RouteTree } from "htmx-router/bin/router";
-import { RegisterDynamic } from "htmx-router/bin/util/dynamic";
-import { GetClientEntryURL } from 'htmx-router/bin/client/entry';
-import { GetMountUrl } from 'htmx-router/bin/client/mount';
-import { GetSheetUrl } from 'htmx-router/bin/util/css';
-import { RouteModule } from "htmx-router";
-import { resolve } from "path";
-
-(globalThis as any).HTMX_ROUTER_ROOT = resolve('${config.router.folder.replaceAll("\\", "/")}');
-const modules = import.meta.glob('${routes}/**/*.{ts,tsx}', { eager: true });
-
-export const tree = new RouteTree();
-for (const path in modules) {
-	const tail = path.lastIndexOf(".");
-	const url = path.slice(${routes.length + 1}, tail);
-	tree.ingest(url, modules[path] as RouteModule<any>);
-}
-
-export function Dynamic<T extends Record<string, string>>(props: {
-	params: T,
-	loader: (params: T, ctx: GenericContext) => Promise<JSX.Element>
-	children?: JSX.Element
-}): JSX.Element {
-	const path = RegisterDynamic(props.loader);
-
-	const query = new URLSearchParams();
-	for (const key in props.params) query.set(key, props.params[key]);
-	const url = path + query.toString();
-
-	return <div
-		hx-get={url}
-		hx-trigger="load"
-		hx-swap="outerHTML transition:true"
-		style={{ display: "contents" }}
-	>{props.children ? props.children : ""}</div>
-}
-
-let headCache: JSX.Element | null = null;
-const isProduction = process.env.NODE_ENV === "production";
-const clientEntry = await GetClientEntryURL();
-export function Scripts() {
-	if (headCache) return headCache;
-
-	const res = <>
-		<link href={GetSheetUrl()} rel="stylesheet"></link>
-		{ isProduction ? "" : <script type="module" src="/@vite/client"></script> }
-		<script type="module" src={clientEntry}></script>
-		<script src={GetMountUrl()}></script>
-	</>;
-
-	if (isProduction) headCache = res;
-	return res;
-}`);
-if (config.client) {
-    console.info("Building client islands");
-    await GenerateClient(config.client, true);
-}

package/bin/client/entry.d.ts

@@ -1 +0,0 @@
-export declare function GetClientEntryURL(): Promise<any>;