npm - blumenjs - Versions diffs - 0.2.4 → 0.2.6 - Mend

blumenjs 0.2.4 → 0.2.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/dist/cli/blumen.js +22 -0
package/dist/cli/commands/create.js +22 -0
package/dist/templates/app/shared/BlumenHead.tsx +157 -0
package/dist/templates/app/shared/BlumenImage.tsx +209 -0
package/dist/templates/app/shared/DefaultLoading.tsx +78 -0
package/dist/templates/app/shared/ErrorBoundary.tsx +174 -0
package/dist/templates/app/shared/api.ts +99 -0
package/dist/templates/app/shared/blumenConfig.ts +179 -0
package/dist/templates/app/shared/i18n.ts +281 -0
package/dist/templates/app/shared/prefetchCache.ts +142 -0
package/dist/templates/app/shared/serverAction.ts +84 -0
package/dist/templates/app/shared/types.ts +132 -0
package/dist/templates/app/shared/useServerAction.ts +173 -0
package/dist/templates/app/shared/useWebSocket.ts +237 -0
package/dist/templates/go.mod +8 -0
package/dist/templates/go.sum +4 -0
package/dist/templates/scripts/generate-api-routes.ts +236 -0
package/package.json +1 -1

package/dist/templates/app/shared/api.ts ADDED Viewed

@@ -0,0 +1,99 @@
+/**
+ * Blumen API Route Helpers
+ *
+ * Runtime utilities for API route handlers.
+ * Import these in your app/api/ route.ts files.
+ *
+ * Example usage:
+ *   import { json, notFound } from '../../shared/api';
+ *   export function GET(req) { return json({ message: 'Hello' }); }
+ */
+// ── Request type ──────────────────────────────────────────────
+/**
+ * Request object passed to API route handlers.
+ * Contains the parsed HTTP method, path, params, query, headers, and body.
+ */
+export interface BlumenAPIRequest {
+	/** HTTP method (GET, POST, PUT, DELETE, PATCH) */
+	method: string;
+	/** The request URL path (e.g. "/api/users/42") */
+	path: string;
+	/** Dynamic route parameters (e.g. { id: "42" } for /api/users/[id]) */
+	params: Record<string, string>;
+	/** URL query string parameters */
+	query: Record<string, string[]>;
+	/** A subset of request headers (forwarded from Go) */
+	headers: Record<string, string>;
+	/** Parsed request body (JSON). Undefined for GET/DELETE. */
+	body: any;
+}
+// ── Response type ─────────────────────────────────────────────
+/**
+ * Response object returned from API route handlers.
+ * The framework serialises this and sends it back to the client.
+ */
+export interface BlumenAPIResponse {
+	/** HTTP status code (default 200) */
+	status: number;
+	/** Response headers */
+	headers: Record<string, string>;
+	/** Response body (will be JSON-stringified) */
+	body: any;
+}
+// ── Response helpers ──────────────────────────────────────────
+/**
+ * Return a JSON response.
+ *
+ * Example:
+ *   return json({ users: [] });
+ *   return json({ created: true }, { status: 201 });
+ */
+export function json(
+	data: any,
+	init?: { status?: number; headers?: Record<string, string> },
+): BlumenAPIResponse {
+	return {
+		status: init?.status ?? 200,
+		headers: {
+			"Content-Type": "application/json",
+			...(init?.headers || {}),
+		},
+		body: data,
+	};
+}
+/**
+ * Return a redirect response.
+ *
+ * Example:
+ *   return redirect('/login');
+ *   return redirect('/new-url', 301); // permanent redirect
+ */
+export function redirect(url: string, status: number = 302): BlumenAPIResponse {
+	return {
+		status,
+		headers: { Location: url },
+		body: null,
+	};
+}
+/**
+ * Return a 404 Not Found response.
+ *
+ * Example:
+ *   const user = await findUser(req.params.id);
+ *   if (!user) return notFound();
+ */
+export function notFound(message: string = "Not Found"): BlumenAPIResponse {
+	return {
+		status: 404,
+		headers: { "Content-Type": "application/json" },
+		body: { error: message },
+	};
+}

package/dist/templates/app/shared/blumenConfig.ts ADDED Viewed

@@ -0,0 +1,179 @@
+/**
+ * 🌸 Blumen Configuration
+ *
+ * Central configuration file for your Blumen application.
+ * Controls plugins, i18n, middleware, and framework behavior.
+ *
+ * @example
+ * import { defineConfig } from "@/shared/blumenConfig";
+ *
+ * export default defineConfig({
+ *   plugins: [analyticsPlugin(), sentryPlugin()],
+ *   i18n: { locales: ["en", "fr"], defaultLocale: "en" },
+ * });
+ */
+import React from "react";
+// ── Types ──────────────────────────────────────────────────────
+/**
+ * Blumen Plugin interface.
+ * Plugins can wrap the app with providers, inject head elements,
+ * and hook into lifecycle events.
+ */
+export interface BlumenPlugin {
+	/** Unique plugin name */
+	name: string;
+	/**
+	 * Wrap the entire application with a provider component.
+	 * Called during both SSR and client-side rendering.
+	 *
+	 * @example
+	 * wrapApp: (children) => <ThemeProvider>{children}</ThemeProvider>
+	 */
+	wrapApp?: (children: React.ReactNode) => React.ReactNode;
+	/**
+	 * Inject elements into <head> during SSR.
+	 * Return an array of React elements (meta tags, link tags, scripts).
+	 */
+	head?: () => React.ReactNode[];
+	/**
+	 * Called once on client-side after hydration.
+	 * Use for analytics init, service workers, etc.
+	 */
+	onClientInit?: () => void;
+	/**
+	 * Called on every client-side route change.
+	 */
+	onRouteChange?: (path: string) => void;
+}
+/**
+ * i18n configuration.
+ */
+export interface I18nConfig {
+	/** Supported locale codes (e.g. ["en", "fr", "de"]) */
+	locales: string[];
+	/** Default locale when none is detected */
+	defaultLocale: string;
+	/** Locale detection strategy */
+	detection?: "header" | "path" | "cookie" | "none";
+	/** Path to translation files directory (default: "locales/") */
+	translationsDir?: string;
+}
+/**
+ * Main Blumen configuration.
+ */
+export interface BlumenConfig {
+	/** Application name */
+	appName?: string;
+	/** Plugins to load */
+	plugins?: BlumenPlugin[];
+	/** Internationalization settings */
+	i18n?: I18nConfig;
+	/** Custom webpack config overrides (advanced) */
+	webpack?: (config: any) => any;
+}
+// ── Config Helpers ─────────────────────────────────────────────
+let _config: BlumenConfig | null = null;
+/**
+ * Define a Blumen configuration with type checking.
+ */
+export function defineConfig(config: BlumenConfig): BlumenConfig {
+	_config = config;
+	return config;
+}
+/**
+ * Get the current configuration.
+ */
+export function getConfig(): BlumenConfig {
+	return _config || {};
+}
+/**
+ * Apply all plugin wrappers to children.
+ */
+export function applyPluginWrappers(
+	children: React.ReactNode,
+): React.ReactNode {
+	const config = getConfig();
+	if (!config.plugins) return children;
+	let wrapped = children;
+	// Apply plugins in reverse so the first plugin is the outermost wrapper
+	for (let i = config.plugins.length - 1; i >= 0; i--) {
+		const plugin = config.plugins[i];
+		if (plugin.wrapApp) {
+			wrapped = plugin.wrapApp(wrapped);
+		}
+	}
+	return wrapped;
+}
+/**
+ * Collect all head elements from plugins.
+ */
+export function collectPluginHeadElements(): React.ReactNode[] {
+	const config = getConfig();
+	if (!config.plugins) return [];
+	const elements: React.ReactNode[] = [];
+	for (const plugin of config.plugins) {
+		if (plugin.head) {
+			elements.push(...plugin.head());
+		}
+	}
+	return elements;
+}
+/**
+ * Initialize all plugins on the client side.
+ */
+export function initClientPlugins(): void {
+	const config = getConfig();
+	if (!config.plugins) return;
+	for (const plugin of config.plugins) {
+		if (plugin.onClientInit) {
+			try {
+				plugin.onClientInit();
+			} catch (err) {
+				console.error(`Plugin "${plugin.name}" init error:`, err);
+			}
+		}
+	}
+}
+/**
+ * Notify all plugins of a route change.
+ */
+export function notifyPluginRouteChange(path: string): void {
+	const config = getConfig();
+	if (!config.plugins) return;
+	for (const plugin of config.plugins) {
+		if (plugin.onRouteChange) {
+			try {
+				plugin.onRouteChange(path);
+			} catch (err) {
+				console.error(`Plugin "${plugin.name}" route change error:`, err);
+			}
+		}
+	}
+}

package/dist/templates/app/shared/i18n.ts ADDED Viewed

@@ -0,0 +1,281 @@
+/**
+ * 🌸 Blumen i18n — Internationalization System
+ *
+ * Built-in multi-language support with:
+ * - Automatic locale detection (Accept-Language, path prefix, cookie)
+ * - React context for current locale
+ * - useTranslation hook for translations
+ * - Type-safe translation keys
+ *
+ * @example
+ * // Setup: create locale files
+ * // locales/en.json → { "greeting": "Hello", "nav.home": "Home" }
+ * // locales/fr.json → { "greeting": "Bonjour", "nav.home": "Accueil" }
+ *
+ * // In your component:
+ * import { useTranslation } from "@/shared/i18n";
+ *
+ * function MyPage() {
+ *   const { t, locale, setLocale } = useTranslation();
+ *   return <h1>{t("greeting")}</h1>;
+ * }
+ */
+import React, { createContext, useContext, useState, useCallback, useMemo } from "react";
+// ── Types ──────────────────────────────────────────────────────
+export interface TranslationMap {
+	[key: string]: string | TranslationMap;
+}
+export interface I18nContextValue {
+	/** Current locale code (e.g. "en", "fr") */
+	locale: string;
+	/** All available locales */
+	locales: string[];
+	/** Change the current locale */
+	setLocale: (locale: string) => void;
+	/** Translate a key with optional interpolation */
+	t: (key: string, params?: Record<string, string | number>) => string;
+	/** Get the direction (ltr/rtl) for the current locale */
+	dir: "ltr" | "rtl";
+}
+// RTL language codes
+const RTL_LOCALES = new Set(["ar", "he", "fa", "ur", "ps", "sd", "yi"]);
+// ── Translation Registry ───────────────────────────────────────
+const translations = new Map<string, TranslationMap>();
+/**
+ * Register translations for a locale.
+ */
+export function registerTranslations(locale: string, messages: TranslationMap): void {
+	const existing = translations.get(locale) || {};
+	translations.set(locale, { ...existing, ...flattenMessages(messages) });
+}
+/**
+ * Register multiple locales at once.
+ */
+export function registerAllTranslations(allMessages: Record<string, TranslationMap>): void {
+	for (const [locale, messages] of Object.entries(allMessages)) {
+		registerTranslations(locale, messages);
+	}
+}
+/**
+ * Flatten nested translation objects into dot-notation keys.
+ * { nav: { home: "Home" } } → { "nav.home": "Home" }
+ */
+function flattenMessages(obj: TranslationMap, prefix = ""): Record<string, string> {
+	const result: Record<string, string> = {};
+	for (const [key, value] of Object.entries(obj)) {
+		const fullKey = prefix ? `${prefix}.${key}` : key;
+		if (typeof value === "string") {
+			result[fullKey] = value;
+		} else {
+			Object.assign(result, flattenMessages(value, fullKey));
+		}
+	}
+	return result;
+}
+// ── Locale Detection ───────────────────────────────────────────
+/**
+ * Detect the user's preferred locale.
+ */
+export function detectLocale(
+	supportedLocales: string[],
+	defaultLocale: string,
+	strategy: "header" | "path" | "cookie" | "none" = "header",
+	requestHeaders?: Record<string, string>,
+	path?: string,
+): string {
+	if (strategy === "none") return defaultLocale;
+	// 1. Check path prefix (e.g. /fr/about → fr)
+	if (strategy === "path" && path) {
+		const segments = path.split("/").filter(Boolean);
+		if (segments.length > 0 && supportedLocales.includes(segments[0])) {
+			return segments[0];
+		}
+	}
+	// 2. Check cookie
+	if (typeof document !== "undefined") {
+		const match = document.cookie.match(/(?:^|;\s*)blumen_locale=([^;]*)/);
+		if (match && supportedLocales.includes(match[1])) {
+			return match[1];
+		}
+	}
+	// 3. Check Accept-Language header (server-side)
+	if (strategy === "header" && requestHeaders) {
+		const acceptLang = requestHeaders["accept-language"] || requestHeaders["Accept-Language"];
+		if (acceptLang) {
+			const preferred = parseAcceptLanguage(acceptLang);
+			for (const lang of preferred) {
+				// Exact match
+				if (supportedLocales.includes(lang)) return lang;
+				// Prefix match (en-US → en)
+				const prefix = lang.split("-")[0];
+				if (supportedLocales.includes(prefix)) return prefix;
+			}
+		}
+	}
+	// 4. Check browser language
+	if (typeof navigator !== "undefined") {
+		const browserLang = navigator.language?.split("-")[0];
+		if (browserLang && supportedLocales.includes(browserLang)) {
+			return browserLang;
+		}
+	}
+	return defaultLocale;
+}
+/**
+ * Parse Accept-Language header into ordered locale list.
+ * "en-US,en;q=0.9,fr;q=0.8" → ["en-US", "en", "fr"]
+ */
+function parseAcceptLanguage(header: string): string[] {
+	return header
+		.split(",")
+		.map((part) => {
+			const [lang, q] = part.trim().split(";q=");
+			return { lang: lang.trim(), quality: q ? parseFloat(q) : 1 };
+		})
+		.sort((a, b) => b.quality - a.quality)
+		.map((item) => item.lang);
+}
+// ── React Context ──────────────────────────────────────────────
+const I18nContext = createContext<I18nContextValue | null>(null);
+export interface I18nProviderProps {
+	/** Initial locale */
+	locale: string;
+	/** Supported locales */
+	locales: string[];
+	/** Children */
+	children: React.ReactNode;
+}
+/**
+ * I18n Provider — wraps your app to provide translation context.
+ */
+export function I18nProvider({ locale: initialLocale, locales, children }: I18nProviderProps) {
+	const [locale, setLocaleState] = useState(initialLocale);
+	const setLocale = useCallback((newLocale: string) => {
+		if (!locales.includes(newLocale)) {
+			console.warn(`Locale "${newLocale}" is not supported. Supported: ${locales.join(", ")}`);
+			return;
+		}
+		setLocaleState(newLocale);
+		// Persist in cookie
+		if (typeof document !== "undefined") {
+			document.cookie = `blumen_locale=${newLocale}; path=/; max-age=31536000; SameSite=Lax`;
+		}
+	}, [locales]);
+	const t = useCallback((key: string, params?: Record<string, string | number>): string => {
+		const messages = translations.get(locale);
+		let value = messages?.[key] as string | undefined;
+		if (!value) {
+			// Fallback: try the key itself as the value (useful for simple cases)
+			return interpolate(key, params);
+		}
+		return interpolate(value, params);
+	}, [locale]);
+	const dir = useMemo(() => RTL_LOCALES.has(locale.split("-")[0]) ? "rtl" as const : "ltr" as const, [locale]);
+	const value = useMemo<I18nContextValue>(() => ({
+		locale,
+		locales,
+		setLocale,
+		t,
+		dir,
+	}), [locale, locales, setLocale, t, dir]);
+	return React.createElement(I18nContext.Provider, { value }, children);
+}
+/**
+ * Interpolate {{param}} placeholders in a translation string.
+ */
+function interpolate(str: string, params?: Record<string, string | number>): string {
+	if (!params) return str;
+	return str.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+		return params[key] !== undefined ? String(params[key]) : `{{${key}}}`;
+	});
+}
+// ── Hooks ──────────────────────────────────────────────────────
+/**
+ * Access the i18n context in any component.
+ */
+export function useTranslation(): I18nContextValue {
+	const ctx = useContext(I18nContext);
+	if (!ctx) {
+		// Fallback for apps without i18n configured
+		return {
+			locale: "en",
+			locales: ["en"],
+			setLocale: () => {},
+			t: (key: string) => key,
+			dir: "ltr",
+		};
+	}
+	return ctx;
+}
+/**
+ * Get just the current locale (lighter than useTranslation).
+ */
+export function useLocale(): string {
+	const { locale } = useTranslation();
+	return locale;
+}
+// ── Language Switcher Component ────────────────────────────────
+export interface LanguageSwitcherProps {
+	/** Custom class name */
+	className?: string;
+	/** Custom style */
+	style?: React.CSSProperties;
+}
+/**
+ * Ready-to-use language switcher dropdown.
+ */
+export function LanguageSwitcher({ className, style }: LanguageSwitcherProps) {
+	const { locale, locales, setLocale } = useTranslation();
+	return React.createElement("select", {
+		value: locale,
+		onChange: (e: any) => setLocale(e.target.value),
+		className,
+		style: { ...style },
+		"aria-label": "Select language",
+	},
+		...locales.map((loc) =>
+			React.createElement("option", { key: loc, value: loc }, loc.toUpperCase())
+		),
+	);
+}

package/dist/templates/app/shared/prefetchCache.ts ADDED Viewed

@@ -0,0 +1,142 @@
+/**
+ * Blumen Prefetch Cache
+ *
+ * Stores pre-fetched route data so that SPA navigation is instant.
+ * Entries expire after 30 seconds to ensure freshness.
+ *
+ * Used by:
+ *   - Link component (populates cache on hover)
+ *   - RouterContext navigate() (reads from cache before fetching)
+ */
+interface CacheEntry {
+	data: any;
+	timestamp: number;
+}
+// Cache entries expire after 30 seconds
+const CACHE_TTL = 30_000;
+// Maximum number of cached entries
+const MAX_ENTRIES = 20;
+const cache = new Map<string, CacheEntry>();
+// Track in-flight requests to prevent duplicate fetches
+const inflight = new Map<string, Promise<any>>();
+/**
+ * Get cached data for a path, or undefined if expired/missing.
+ */
+export function getCached(path: string): any | undefined {
+	const entry = cache.get(path);
+	if (!entry) return undefined;
+	// Check if expired
+	if (Date.now() - entry.timestamp > CACHE_TTL) {
+		cache.delete(path);
+		return undefined;
+	}
+	return entry.data;
+}
+/**
+ * Store data in the prefetch cache.
+ */
+export function setCache(path: string, data: any): void {
+	// Evict oldest entries if cache is full
+	if (cache.size >= MAX_ENTRIES) {
+		const firstKey = cache.keys().next().value;
+		if (firstKey) cache.delete(firstKey);
+	}
+	cache.set(path, {
+		data,
+		timestamp: Date.now(),
+	});
+}
+/**
+ * Prefetch the JS chunk for a route by injecting a <link rel="prefetch"> tag.
+ * This tells the browser to download the chunk in idle time so it's cached
+ * when the user actually navigates.
+ */
+const prefetchedChunks = new Set<string>();
+function prefetchChunk(path: string): void {
+	if (typeof document === "undefined") return;
+	try {
+		// Dynamic import to avoid circular dependency in SSR
+		// The routeChunkMap is only available on the client
+		const routeChunkMap = (window as any).__BLUMEN_CHUNK_MAP__;
+		if (!routeChunkMap) return;
+		const chunkName = routeChunkMap[path];
+		if (!chunkName || prefetchedChunks.has(chunkName)) return;
+		prefetchedChunks.add(chunkName);
+		// In dev mode, chunks are served from WDS
+		const isDev = process.env.NODE_ENV === "development";
+		const chunkSrc = isDev
+			? `http://localhost:3100/static/js/chunks/${chunkName}.js`
+			: `/static/js/chunks/${chunkName}.js`;
+		const link = document.createElement("link");
+		link.rel = "prefetch";
+		link.as = "script";
+		link.href = chunkSrc;
+		document.head.appendChild(link);
+	} catch {
+		// Silently ignore — prefetching is best-effort
+	}
+}
+/**
+ * Prefetch route data for a path.
+ * Returns immediately if already cached or in-flight.
+ * Fetches in the background and stores the result.
+ * Also prefetches the page's JS chunk for instant code loading.
+ */
+export function prefetch(path: string): void {
+	// Prefetch the JS chunk (best-effort, non-blocking)
+	prefetchChunk(path);
+	// Already cached and fresh
+	if (getCached(path) !== undefined) return;
+	// Already in-flight
+	if (inflight.has(path)) return;
+	// Start the fetch
+	const promise = fetch(path, {
+		headers: { "X-Blumen-Data": "1" },
+	})
+		.then((res) => (res.ok ? res.json() : null))
+		.then((data) => {
+			if (data) {
+				setCache(path, data);
+			}
+			inflight.delete(path);
+			return data;
+		})
+		.catch(() => {
+			inflight.delete(path);
+		});
+	inflight.set(path, promise);
+}
+/**
+ * Consume cached data for a path (get and remove from cache).
+ * Used by navigate() so data is fetched fresh on next visit.
+ */
+export function consumeCached(path: string): any | undefined {
+	const data = getCached(path);
+	if (data !== undefined) {
+		cache.delete(path);
+	}
+	return data;
+}