@techstream/quark-create-app 1.8.0 → 1.10.0

package/templates/ui/src/table.test.js

@@ -0,0 +1,69 @@
+import assert from "node:assert";
+import { test } from "node:test";
+import {
+	Table,
+	TableBody,
+	TableCell,
+	TableHead,
+	TableHeader,
+	TableRow,
+} from "./table.js";
+
+test("Table - exports correctly", () => {
+	assert(typeof Table === "function");
+});
+
+test("TableHeader - exports correctly", () => {
+	assert(typeof TableHeader === "function");
+});
+
+test("TableBody - exports correctly", () => {
+	assert(typeof TableBody === "function");
+});
+
+test("TableRow - exports correctly", () => {
+	assert(typeof TableRow === "function");
+});
+
+test("TableHead - exports correctly", () => {
+	assert(typeof TableHead === "function");
+});
+
+test("TableCell - exports correctly", () => {
+	assert(typeof TableCell === "function");
+});
+
+test("Table - renders with default props", () => {
+	const result = Table({});
+	assert.ok(result);
+});
+
+test("TableHeader - renders with default props", () => {
+	const result = TableHeader({});
+	assert.ok(result);
+});
+
+test("TableBody - renders with default props", () => {
+	const result = TableBody({});
+	assert.ok(result);
+});
+
+test("TableRow - renders with default props", () => {
+	const result = TableRow({});
+	assert.ok(result);
+});
+
+test("TableHead - renders with default props", () => {
+	const result = TableHead({});
+	assert.ok(result);
+});
+
+test("TableCell - renders with default props", () => {
+	const result = TableCell({});
+	assert.ok(result);
+});
+
+test("Table - accepts className override", () => {
+	const result = Table({ className: "custom" });
+	assert.ok(result);
+});

package/templates/ui/src/textarea.js

@@ -0,0 +1,15 @@
+import React from "react";
+
+const THEMES = {
+	light:
+		"block w-full rounded-sm border border-gray-300 bg-white px-3 py-2 text-sm text-gray-900 placeholder-gray-400 shadow-sm transition-all duration-200 hover:border-gray-400 focus-visible:border-blue-500 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500/30 disabled:bg-gray-100 disabled:text-gray-500 disabled:cursor-not-allowed resize-y",
+	dark: "block w-full rounded-sm border border-[#1e2535] bg-[#090d14] px-3 py-2 text-sm text-[#e0e0e0] placeholder-[#2d3a52] font-mono transition-all duration-200 hover:border-[#377dff]/30 focus-visible:border-[#377dff]/60 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#377dff]/15 disabled:opacity-30 disabled:cursor-not-allowed resize-y",
+};
+
+export function Textarea({ theme = "light", className = "", ...props }) {
+	const base = THEMES[theme] ?? THEMES.light;
+	return React.createElement("textarea", {
+		className: `${base} ${className}`.trim(),
+		...props,
+	});
+}

package/templates/ui/src/textarea.test.js

@@ -0,0 +1,27 @@
+import assert from "node:assert";
+import { test } from "node:test";
+import { Textarea } from "./textarea.js";
+
+test("Textarea - exports correctly", () => {
+	assert(typeof Textarea === "function");
+});
+
+test("Textarea - renders with default props", () => {
+	const result = Textarea({});
+	assert.ok(result);
+});
+
+test("Textarea - accepts className override", () => {
+	const result = Textarea({ className: "h-32" });
+	assert.ok(result);
+});
+
+test("Textarea - accepts rows prop", () => {
+	const result = Textarea({ rows: 4, placeholder: "Enter text..." });
+	assert.ok(result);
+});
+
+test("Textarea - accepts disabled prop", () => {
+	const result = Textarea({ disabled: true });
+	assert.ok(result);
+});

package/templates/ui/src/theme-constants.js

@@ -0,0 +1,24 @@
+/**
+ * Theme system constants for @techstream/quark-ui.
+ *
+ * These three values form the contract between ThemeProvider and any
+ * out-of-tree component (e.g. HomeThemeToggle in apps/web) that interoperates
+ * with it via the shared localStorage key, HTML attribute, and DOM event.
+ *
+ * An identical copy lives in apps/web/src/lib/theme.js — each package owns
+ * its own copy so there is no cross-package import. If you rename any of
+ * these, update both files and the CSS selectors in globals.css.
+ */
+
+/** Key used to persist the user's explicit theme choice in localStorage. */
+export const THEME_STORAGE_KEY = "quark-theme";
+
+/**
+ * Attribute set on <html> so CSS custom properties can react to JS state.
+ * Use via element.setAttribute(THEME_ATTR, value) / element.getAttribute(THEME_ATTR).
+ * Referenced in globals.css as [data-theme="light"] / [data-theme="dark"].
+ */
+export const THEME_ATTR = "data-theme";
+
+/** CustomEvent name dispatched when the theme changes outside a ThemeProvider. */
+export const THEME_CHANGE_EVENT = "quark-theme-change";

package/templates/ui/src/theme.js

@@ -0,0 +1,132 @@
+"use client";
+import React, { createContext, useContext, useEffect, useState } from "react";
+import {
+	THEME_ATTR,
+	THEME_CHANGE_EVENT,
+	THEME_STORAGE_KEY,
+} from "./theme-constants.js";
+
+const ThemeCtx = createContext({ theme: "dark", setTheme: () => {} });
+
+/**
+ * Wraps a subtree with a shared theme value.
+ *
+ * Behaviour:
+ * - If `defaultTheme` is provided it is used as the initial value (good for
+ *   pages that have a deliberate starting theme, e.g. the playground).
+ * - If `defaultTheme` is omitted, the initial value is derived from the OS
+ *   `prefers-color-scheme` media query on first mount.
+ * - In both cases the user's explicit toggle choice is persisted to
+ *   `localStorage` under the key `quark-theme` and restored on subsequent
+ *   visits so their preference is remembered across sessions.
+ *
+ * @param {{ defaultTheme?: 'light' | 'dark', children: React.ReactNode }} props
+ */
+export function ThemeProvider({ defaultTheme, children }) {
+	// Lazy initialiser — runs synchronously on the client before first paint,
+	// so the correct theme is in place from frame 0 (no flash).
+	// On the server `window` is undefined, so we fall back to defaultTheme ?? 'dark'.
+	const [theme, setTheme] = useState(() => {
+		if (typeof window === "undefined") return defaultTheme ?? "dark";
+		const stored = localStorage.getItem(THEME_STORAGE_KEY);
+		if (stored === "light" || stored === "dark") return stored;
+		if (defaultTheme != null) return defaultTheme;
+		return window.matchMedia("(prefers-color-scheme: dark)").matches
+			? "dark"
+			: "light";
+	});
+
+	// Keep state in sync when the OS colour scheme changes (only relevant when
+	// no defaultTheme was provided and the user has no stored preference).
+	useEffect(() => {
+		const stored = localStorage.getItem(THEME_STORAGE_KEY);
+		if (stored || defaultTheme != null) return;
+		const mq = window.matchMedia("(prefers-color-scheme: dark)");
+		const onChange = (e) => setTheme(e.matches ? "dark" : "light");
+		mq.addEventListener("change", onChange);
+		return () => mq.removeEventListener("change", onChange);
+	}, [defaultTheme]);
+
+	// Listen for toggles fired by HomeThemeToggle (or any other out-of-tree
+	// component) so React context stays in sync without any import coupling.
+	useEffect(() => {
+		function onExternalChange(e) {
+			const t = e.detail?.theme;
+			if (t === "light" || t === "dark") setTheme(t);
+		}
+		document.addEventListener(THEME_CHANGE_EVENT, onExternalChange);
+		return () =>
+			document.removeEventListener(THEME_CHANGE_EVENT, onExternalChange);
+	}, []);
+
+	function persistSetTheme(t) {
+		localStorage.setItem(THEME_STORAGE_KEY, t);
+		document.documentElement.setAttribute(THEME_ATTR, t);
+		setTheme(t);
+	}
+
+	return React.createElement(
+		ThemeCtx.Provider,
+		{ value: { theme, setTheme: persistSetTheme } },
+		children,
+	);
+}
+
+/**
+ * Returns the current theme and a setter from the nearest ThemeProvider.
+ * Falls back to `{ theme: 'light' }` when used outside a provider.
+ *
+ * @returns {{ theme: 'light' | 'dark', setTheme: (t: string) => void }}
+ */
+export function useTheme() {
+	return useContext(ThemeCtx);
+}
+
+/**
+ * Slide-pill toggle that switches between light and dark themes.
+ * 32×18 px track with a 12 px sliding knob. Pure inline styles — no
+ * Tailwind dependency. Must be rendered inside a ThemeProvider.
+ */
+export function ThemeToggle({ className = "", style = {} }) {
+	const { theme, setTheme } = useTheme();
+	const isDark = theme === "dark";
+
+	return React.createElement(
+		"button",
+		{
+			type: "button",
+			onClick: () => setTheme(isDark ? "light" : "dark"),
+			"aria-label": `Switch to ${isDark ? "light" : "dark"} theme`,
+			"aria-pressed": isDark,
+			className: className || undefined,
+			style: {
+				display: "inline-flex",
+				alignItems: "center",
+				width: "32px",
+				height: "18px",
+				borderRadius: "9px",
+				border: `1px solid ${isDark ? "#1e2d45" : "#d1d5db"}`,
+				background: isDark ? "#0d1420" : "#e5e7eb",
+				cursor: "pointer",
+				padding: "2px",
+				transition: "background 0.2s ease, border-color 0.2s ease",
+				outline: "none",
+				flexShrink: 0,
+				...style,
+			},
+		},
+		React.createElement("span", {
+			"aria-hidden": "true",
+			style: {
+				display: "block",
+				width: "12px",
+				height: "12px",
+				borderRadius: "50%",
+				background: isDark ? "#377dff" : "#9ca3af",
+				transform: isDark ? "translateX(14px)" : "translateX(0)",
+				transition: "transform 0.2s ease, background 0.2s ease",
+				flexShrink: 0,
+			},
+		}),
+	);
+}

package/templates/ui/src/toast.js

@@ -0,0 +1,229 @@
+"use client";
+import React, { useCallback, useEffect, useRef, useState } from "react";
+
+/**
+ * Toast — fixed bottom-right notification with auto-dismiss countdown.
+ *
+ * Props:
+ *   message   (string)                        — notification text
+ *   variant   ('default'|'success'|'error')   — colour scheme
+ *   onClose   (fn)                            — called when dismissed / expired
+ *   visible   (bool)                          — controlled visibility
+ *   duration  (number)                        — ms before auto-dismiss (default 4000)
+ *   theme     (string)                        — 'light' (default) | 'dark'
+ *   toastId   (number)                        — incremented by useToast on each show()
+ *                                               so the timer resets correctly
+ *
+ * Features:
+ *   • SVG circle progress shows remaining time
+ *   • Hovering pauses the timer and replaces the circle with a × close button
+ */
+
+const RADIUS = 9;
+const CIRC = 2 * Math.PI * RADIUS; // ≈ 56.55
+
+const THEMES = {
+	light: {
+		default: {
+			cls: "border border-gray-700 bg-gray-900 text-white",
+			track: "rgba(255,255,255,0.2)",
+			progress: "rgba(255,255,255,0.85)",
+		},
+		success: {
+			cls: "border border-green-500 bg-green-600 text-white",
+			track: "rgba(255,255,255,0.2)",
+			progress: "rgba(255,255,255,0.85)",
+		},
+		error: {
+			cls: "border border-red-500 bg-red-600 text-white",
+			track: "rgba(255,255,255,0.2)",
+			progress: "rgba(255,255,255,0.85)",
+		},
+	},
+	dark: {
+		default: {
+			cls: "border border-[#1e2535] bg-[#090d14] text-[#e0e0e0]",
+			track: "rgba(55,125,255,0.12)",
+			progress: "rgba(55,125,255,0.7)",
+		},
+		success: {
+			cls: "border border-emerald-800/50 bg-[#090d14] text-emerald-400",
+			track: "rgba(52,211,153,0.12)",
+			progress: "rgba(52,211,153,0.7)",
+		},
+		error: {
+			cls: "border border-[#ff4757]/40 bg-[#090d14] text-[#ff4757]",
+			track: "rgba(255,71,87,0.12)",
+			progress: "rgba(255,71,87,0.7)",
+		},
+	},
+};
+
+export function Toast({
+	message,
+	variant = "default",
+	onClose,
+	visible = true,
+	duration = 4000,
+	theme = "light",
+	_toastId,
+}) {
+	const [progress, setProgress] = useState(100); // 100 → 0 as time elapses
+	const [hovered, setHovered] = useState(false);
+
+	const themeMap = THEMES[theme] ?? THEMES.light;
+	const v = themeMap[variant] ?? themeMap.default;
+
+	// Mutable refs so the interval callback always reads fresh values
+	const remainingRef = useRef(duration);
+	const startRef = useRef(null);
+	const intervalRef = useRef(null);
+
+	const stop = useCallback(() => clearInterval(intervalRef.current), []);
+
+	const start = useCallback(() => {
+		stop();
+		startRef.current = Date.now();
+		intervalRef.current = setInterval(() => {
+			const elapsed = Date.now() - startRef.current;
+			const pct = Math.max(0, 100 - (elapsed / remainingRef.current) * 100);
+			setProgress(pct);
+			if (pct <= 0) {
+				stop();
+				onClose?.();
+			}
+		}, 16);
+	}, [stop, onClose]);
+
+	// Reset when toast becomes visible or a new toast is shown (toastId changes)
+	useEffect(() => {
+		if (!visible) {
+			stop();
+			setProgress(100);
+			return;
+		}
+		remainingRef.current = duration;
+		setProgress(100);
+		setHovered(false);
+		start();
+		return stop;
+	}, [visible, duration, start, stop]); // eslint-disable-line react-hooks/exhaustive-deps
+
+	// Pause on hover, RESET on leave (restart from full duration)
+	useEffect(() => {
+		if (!visible) return;
+		if (hovered) {
+			stop();
+		} else {
+			// Reset to full duration on every mouse-leave
+			remainingRef.current = duration;
+			start();
+		}
+	}, [hovered, duration, start, stop, visible]); // eslint-disable-line react-hooks/exhaustive-deps
+
+	if (!visible) return null;
+
+	const dashOffset = CIRC * (1 - progress / 100);
+
+	return React.createElement(
+		"div",
+		{
+			role: "alert",
+			"aria-live": "assertive",
+			onMouseEnter: () => setHovered(true),
+			onMouseLeave: () => setHovered(false),
+			className: `fixed bottom-4 right-4 z-50 flex items-center gap-3 rounded px-4 py-3 text-sm shadow-xl transition-all duration-200 ${v.cls}`,
+		},
+		React.createElement("span", null, message),
+		// Trailing indicator: × when hovered, progress circle otherwise
+		React.createElement(
+			"div",
+			{
+				className:
+					"relative ml-2 flex h-6 w-6 shrink-0 items-center justify-center",
+			},
+			hovered
+				? React.createElement(
+						"button",
+						{
+							type: "button",
+							"aria-label": "Dismiss notification",
+							onClick: onClose,
+							className:
+								"flex h-6 w-6 cursor-pointer items-center justify-center rounded-sm text-base leading-none opacity-80 transition-all hover:bg-white/15 hover:opacity-100 active:bg-white/20 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-white/60",
+						},
+						"\u00d7",
+					)
+				: React.createElement(
+						"svg",
+						{
+							width: 24,
+							height: 24,
+							viewBox: "0 0 24 24",
+							"aria-hidden": "true",
+						},
+						// Track ring
+						React.createElement("circle", {
+							cx: 12,
+							cy: 12,
+							r: RADIUS,
+							fill: "none",
+							stroke: v.track,
+							strokeWidth: 2,
+						}),
+						// Progress arc
+						React.createElement("circle", {
+							cx: 12,
+							cy: 12,
+							r: RADIUS,
+							fill: "none",
+							stroke: v.progress,
+							strokeWidth: 2,
+							strokeLinecap: "round",
+							strokeDasharray: CIRC,
+							strokeDashoffset: dashOffset,
+							style: { transform: "rotate(-90deg)", transformOrigin: "center" },
+						}),
+					),
+		),
+	);
+}
+
+/**
+ * useToast — manages toast state and exposes a stable show() / hide() API.
+ *
+ * Usage:
+ *   const { show, hide, toastProps } = useToast();
+ *   <Toast {...toastProps} />
+ *
+ *   show("Saved!", "success");
+ *   show("Oops", "error", 6000);  // custom duration
+ */
+export function useToast() {
+	const [state, setState] = useState({
+		visible: false,
+		message: "",
+		variant: "default",
+		duration: 4000,
+		toastId: 0,
+	});
+
+	const show = useCallback(
+		(message, variant = "default", duration = 4000) =>
+			setState((s) => ({
+				visible: true,
+				message,
+				variant,
+				duration,
+				toastId: s.toastId + 1,
+			})),
+		[],
+	);
+
+	const hide = useCallback(
+		() => setState((s) => ({ ...s, visible: false })),
+		[],
+	);
+
+	return { show, hide, toastProps: { ...state, onClose: hide } };
+}

package/templates/ui/src/toast.test.js

@@ -0,0 +1,23 @@
+import assert from "node:assert";
+import { test } from "node:test";
+import { Toast, useToast } from "./toast.js";
+
+// Toast uses React hooks (useState, useEffect, useRef) and must be rendered
+// via a React renderer. Direct invocation in node --test is not supported.
+// Tests here verify the module exports correct types only.
+
+test("Toast - exports correctly", () => {
+	assert.strictEqual(typeof Toast, "function");
+});
+
+test("Toast - has expected function name", () => {
+	assert.strictEqual(Toast.name, "Toast");
+});
+
+test("useToast - exports correctly", () => {
+	assert.strictEqual(typeof useToast, "function");
+});
+
+test("useToast - has expected function name", () => {
+	assert.strictEqual(useToast.name, "useToast");
+});

package/templates/{base-project/apps/worker → worker}/package.json

@@ -20,10 +20,10 @@
 		"@techstream/quark-core": "^1.0.0",
 		"@techstream/quark-db": "workspace:*",
 		"@techstream/quark-jobs": "workspace:*",
-		"bullmq": "^5.69.3"
+		"bullmq": "^5.70.4"
 	},
 	"devDependencies": {
-		"@types/node": "^25.2.3",
+		"@types/node": "^25.3.5",
 		"tsx": "^4.21.0"
 	}
 }

package/templates/{base-project/apps/worker → worker}/src/index.js

@@ -9,15 +9,20 @@ import {
 	createLogger,
 	createQueue,
 	createWorker,
+	getRedisUrl,
 } from "@techstream/quark-core";
 import { prisma } from "@techstream/quark-db";
 import { JOB_NAMES, JOB_QUEUES } from "@techstream/quark-jobs";
 import { jobHandlers } from "./handlers/index.js";
 
 const logger = createLogger("worker");
+const isDevMode =
+	process.env.NODE_ENV !== "production" &&
+	process.env.npm_lifecycle_event === "dev";
 
 // Store workers for graceful shutdown
 const workers = [];
+let devDisabledKeepAlive = null;
 let isShuttingDown = false;
 
 // ============================================================================
@@ -40,6 +45,7 @@ export function isConnectionError(error) {
 		"EHOSTUNREACH", // Host unreachable
 		"ENETUNREACH", // Network unreachable
 		"Error: Redis connection failed", // Generic redis failure
+		"Redis unavailable at", // Final wrapped startup error
 		"Ready status is false", // BullMQ readiness
 	];
 	return connectionErrors.some((err) => message.includes(err));
@@ -62,10 +68,8 @@ export function throttledError(logger, windowMs = 5000) {
 
 		// Log if new error type or window expired
 		if (msg !== lastErrorMsg || now - lastErrorTime > windowMs) {
-			logger.error(`Connection error (will retry)`, {
-				error: msg,
-				code: error.code,
-				timestamp: new Date().toISOString(),
+			logger.warn("Waiting for Redis", {
+				reason: msg,
 			});
 			lastErrorTime = now;
 			lastErrorMsg = msg;
@@ -73,6 +77,14 @@ export function throttledError(logger, windowMs = 5000) {
 	};
 }
 
+function disableWorkerInDev() {
+	if (!devDisabledKeepAlive) {
+		// Keep the process alive so the dev session stays healthy even when the
+		// worker is intentionally disabled due to missing Redis.
+		devDisabledKeepAlive = setInterval(() => {}, 60_000);
+	}
+}
+
 /**
  * Waits for Redis to be ready with retries
  * @param {Function} healthCheck - Async function that returns boolean or throws
@@ -91,7 +103,6 @@ export async function waitForRedis(
 	} = config;
 
 	const reportThrottledError = throttledError(logger, 3000);
-	let lastError;
 
 	for (let attempt = 1; attempt <= maxRetries; attempt++) {
 		try {
@@ -103,30 +114,20 @@ export async function waitForRedis(
 				return true;
 			}
 		} catch (error) {
-			lastError = error;
 			if (isConnectionError(error)) {
 				reportThrottledError(error);
 				if (attempt < maxRetries) {
-					// Wait before retrying
 					await new Promise((resolve) => setTimeout(resolve, intervalMs));
 				}
 			} else {
-				// Non-connection error; don't retry
-				logger.error("Health check failed with non-network error", {
-					error: error.message,
-				});
-				throw error;
+				throw new Error(`Redis health check failed: ${error.message}`);
 			}
 		}
 	}
 
 	// All retries exhausted
-	logger.error("Redis health check failed after all retries", {
-		attempts: maxRetries,
-		lastError: lastError?.message,
-	});
 	throw new Error(
-		`Failed to connect to Redis after ${maxRetries} attempts: ${lastError?.message}`,
+		`Redis unavailable at ${getRedisUrl()} after ${maxRetries} attempts. Start Redis or check REDIS_URL/REDIS_HOST/REDIS_PORT.`,
 	);
 }
 
@@ -148,10 +149,7 @@ async function preflight() {
 	try {
 		// Check Redis
 		logger.info("Checking Redis connectivity...");
-		const redisReady = await checkQueueHealth();
-		if (!redisReady) {
-			throw new Error("Redis health check returned false");
-		}
+		await checkQueueHealth();
 		logger.info("✓ Redis connected");
 
 		// Check Database
@@ -256,8 +254,12 @@ async function startWorker() {
 	try {
 		// Pre-flight: Wait for Redis with health checks and retries
 		logger.info("Performing health checks...");
-		await waitForRedis();
+		await waitForRedis(
+			checkQueueHealth,
+			isDevMode ? { maxRetries: 3, intervalMs: 500 } : {},
+		);
 
+		logger.info("Redis connected", { address: getRedisUrl() });
 		// Register a worker for each queue
 		for (const queueName of Object.values(JOB_QUEUES)) {
 			createQueueWorker(queueName);
@@ -276,9 +278,17 @@ async function startWorker() {
 
 		logger.info("Worker service ready");
 	} catch (error) {
+		if (isDevMode && isConnectionError(error)) {
+			logger.warn("Redis unavailable — worker disabled in dev", {
+				action:
+					"Start Redis and restart the worker when background jobs are needed.",
+			});
+			disableWorkerInDev();
+			return;
+		}
+
 		logger.error("Failed to start worker service", {
 			error: error.message,
-			stack: error.stack,
 		});
 		process.exit(1);
 	}
@@ -297,6 +307,11 @@ async function shutdown(signal = "unknown") {
 	logger.info("Shutting down worker service", { signal });
 
 	try {
+		if (devDisabledKeepAlive) {
+			clearInterval(devDisabledKeepAlive);
+			devDisabledKeepAlive = null;
+		}
+
 		for (const worker of workers) {
 			await worker.close();
 		}