@usequark/quark-create-app 1.23.11

package/templates/pwa/app/_components/PWARegister.js

@@ -0,0 +1,15 @@
+"use client";
+
+import { useEffect } from "react";
+
+export default function PWARegister() {
+	useEffect(() => {
+		if ("serviceWorker" in navigator && process.env.NODE_ENV === "production") {
+			navigator.serviceWorker
+				.register("/sw.js")
+				.catch(() => {});
+		}
+	}, []);
+
+	return null;
+}

package/templates/pwa/app/manifest.js

@@ -0,0 +1,32 @@
+import { config, getAppUrl } from "@__QUARK_SCOPE__/config";
+
+/**
+ * PWA app manifest.
+ *
+ * This deliberately replaces the base project's `manifest.js` rather than
+ * adding a second manifest file: Next.js serves `app/manifest.js` at
+ * `/manifest.webmanifest`, and a sibling `app/manifest.json` makes the build
+ * fail with "Cannot find module for page: /manifest.webmanifest".
+ */
+export default function manifest() {
+	return {
+		name: config.appName,
+		short_name: config.appName,
+		description: config.appDescription,
+		theme_color: "#000000",
+		background_color: "#000000",
+		display: "standalone",
+		orientation: "portrait-primary",
+		start_url: "/",
+		scope: "/",
+		id: getAppUrl(),
+		icons: [
+			{
+				src: "/quark.svg",
+				sizes: "any",
+				type: "image/svg+xml",
+				purpose: "any maskable",
+			},
+		],
+	};
+}

package/templates/pwa/public/sw.js

@@ -0,0 +1,72 @@
+const CACHE_NAME = "quark-v1";
+
+self.addEventListener("install", () => {
+	self.skipWaiting();
+});
+
+self.addEventListener("activate", (event) => {
+	event.waitUntil(
+		caches.keys().then((keys) =>
+			Promise.all(
+				keys.filter((key) => key !== CACHE_NAME).map((key) => caches.delete(key)),
+			),
+		),
+	);
+	self.clients.claim();
+});
+
+self.addEventListener("fetch", (event) => {
+	const { request } = event;
+
+	// Never cache API routes, auth, or non-GET requests
+	if (
+		request.method !== "GET" ||
+		request.url.includes("/api/") ||
+		request.url.includes("/auth/")
+	) {
+		return;
+	}
+
+	// Navigation requests: network first, fall back to cache
+	if (request.mode === "navigate") {
+		event.respondWith(
+			fetch(request)
+				.then((response) => {
+					const clone = response.clone();
+					caches.open(CACHE_NAME).then((cache) => cache.put(request, clone));
+					return response;
+				})
+				.catch(() => caches.match(request)),
+		);
+		return;
+	}
+
+	// Static assets (Next.js chunks, images, fonts): cache first
+	if (
+		request.url.includes("/_next/static/") ||
+		/\.(png|jpg|jpeg|svg|gif|webp|avif|woff|woff2|ico)$/.test(request.url)
+	) {
+		event.respondWith(
+			caches.match(request).then((cached) => {
+				if (cached) return cached;
+				return fetch(request).then((response) => {
+					const clone = response.clone();
+					caches.open(CACHE_NAME).then((cache) => cache.put(request, clone));
+					return response;
+				});
+			}),
+		);
+		return;
+	}
+
+	// Everything else: network first
+	event.respondWith(
+		fetch(request)
+			.then((response) => {
+				const clone = response.clone();
+				caches.open(CACHE_NAME).then((cache) => cache.put(request, clone));
+				return response;
+			})
+			.catch(() => caches.match(request)),
+	);
+});

package/templates/ui/README.md

@@ -0,0 +1,44 @@
+# @yourscope/ui
+
+Scaffolded UI primitives for your Quark project.
+
+> This package is scaffolded via `quark-create-app`. There is no version sync back to Quark after scaffolding.
+
+## Import
+
+```javascript
+import { Button, Card, Badge } from '@yourscope/ui';
+```
+
+## Available Components
+
+| Component | Type | Notes |
+|---|---|---|
+| `Button` | server | `variant`, `size`, `icon`, `href` props |
+| `Input` | server | Native input attributes |
+| `Label` | server | Native label attributes |
+| `Textarea` | server | Native textarea attributes |
+| `Select` | server | `children`, `value`, `onChange` |
+| `Checkbox` | server | Native checkbox attributes |
+| `Badge` | server | `variant`: default/primary/success/warning/danger/info |
+| `Card` / `CardHeader` / `CardTitle` / `CardContent` / `CardFooter` | server | Composition primitives |
+| `Table` / `TableHeader` / `TableBody` / `TableRow` / `TableHead` / `TableCell` | server | Data tables |
+| `Skeleton` | server | Loading placeholders |
+| `ErrorBanner` | server | Inline error feedback |
+| `Footer` | server | Public site footer |
+| `Navbar` / `MobileNavbar` | server | Public navigation shells |
+| `RichText` | client | Rich text editor |
+| `Dialog` | client | Modal dialogs |
+| `Toast` / `useToast` | client | Notifications |
+| `ThemeProvider` / `useTheme` | client | Dark/light mode context |
+
+## Rules
+
+- All styling via Tailwind CSS utility classes.
+- Import from `@yourscope/ui` — never from `@/components/ui/*`.
+- Every component accepts `className` for Tailwind overrides.
+- Server Components are the default — add `"use client"` only when using hooks or browser APIs.
+
+## Theming
+
+CSS variables in `globals.css` drive all component styles. Override tokens to retheme without editing component source. See `globals.css` in your web app for the full token reference.

package/templates/ui/package.json

@@ -0,0 +1,21 @@
+{
+	"name": "@myquark/ui",
+	"version": "1.0.0",
+	"type": "module",
+	"main": "src/index.js",
+	"exports": {
+		".": "./src/index.js",
+		"./theme-constants": "./src/theme-constants.js"
+	},
+	"dependencies": {
+		"lucide-react": "^1.48.0",
+		"next": "16.3.6"
+	},
+	"devDependencies": {
+		"@types/react": "^19.3.0",
+		"@types/react-dom": "^19.3.0",
+		"jsdom": "^30.1.1",
+		"react": "19.3.0",
+		"react-dom": "19.3.0"
+	}
+}

package/templates/ui/src/badge.js

@@ -0,0 +1,23 @@
+import React from "react";
+
+const base =
+	"inline-flex items-center justify-center border font-medium bg-[--badge-bg] border-[--badge-border] text-[--badge-text]";
+
+export function Badge({ variant = "default", className = "", ...props }) {
+	const cls = `${base} rounded-[--radius-default] ${className}`.trim();
+	return React.createElement("span", {
+		"data-badge-variant": variant,
+		className: cls,
+		style: {
+			minWidth: "var(--badge-min-width)",
+			paddingLeft: "var(--badge-padding-x)",
+			paddingRight: "var(--badge-padding-x)",
+			paddingTop: "var(--badge-padding-y)",
+			paddingBottom: "var(--badge-padding-y)",
+			fontSize: "var(--badge-font-size)",
+			textTransform: "var(--badge-text-transform)",
+			letterSpacing: "var(--badge-text-tracking)",
+		},
+		...props,
+	});
+}

package/templates/ui/src/button.js

@@ -0,0 +1,111 @@
+import Link from "next/link.js";
+import React from "react";
+import { Spinner } from "./spinner.js";
+
+const base =
+	"inline-flex items-center justify-center font-medium tracking-wide transition-all duration-200 linear cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-1 disabled:opacity-40 disabled:cursor-not-allowed active:opacity-80";
+
+const variantCls =
+	"bg-[--btn-bg] border border-[--btn-border] text-[--btn-text] rounded-[--btn-radius] hover:brightness-[var(--btn-hover-brightness)] hover:shadow-[var(--btn-hover-shadow)] hover:bg-[var(--btn-hover-bg)] hover:text-[var(--btn-hover-text)] hover:opacity-[var(--btn-hover-opacity)] focus-visible:ring-[var(--btn-ring)]";
+
+const sizes = {
+	sm: "h-8 px-3 text-sm",
+	md: "h-10 px-4 text-sm",
+	lg: "h-11 px-6 text-base",
+};
+
+const iconSizes = {
+	sm: "var(--btn-icon-sm)",
+	md: "var(--btn-icon-md)",
+	lg: "var(--btn-icon-lg)",
+};
+
+function buildIcon(icon, size) {
+	if (!icon) return null;
+
+	const iconSize = iconSizes[size] ?? iconSizes.md;
+	const iconStyle = { width: iconSize, height: iconSize, flexShrink: 0 };
+
+	if (React.isValidElement(icon)) {
+		const existingClassName = icon.props.className ?? "";
+		return React.cloneElement(icon, {
+			"aria-hidden": true,
+			focusable: false,
+			className: `${existingClassName}`.trim(),
+			style: { ...iconStyle, ...icon.props.style },
+		});
+	}
+
+	return React.createElement(
+		"span",
+		{
+			"aria-hidden": true,
+			style: iconStyle,
+		},
+		icon,
+	);
+}
+
+export function Button({
+	variant = "default",
+	size = "md",
+	className = "",
+	href,
+	target,
+	rel,
+	type = "button",
+	icon,
+	loading = false,
+	children,
+	...props
+}) {
+	const hasLabel =
+		children !== null && children !== undefined && children !== false;
+	const hasIcon = Boolean(icon);
+	const spacing = hasIcon && hasLabel ? "gap-2" : "";
+	const cls =
+		`${base} ${variantCls} ${sizes[size] ?? sizes.md} ${spacing} ${className}`.trim();
+	const buttonType =
+		type === "submit" || type === "reset" || type === "button"
+			? type
+			: "button";
+
+	const buttonChildren = [];
+
+	if (loading)
+		buttonChildren.push(
+			React.createElement(Spinner, { key: "spinner", className: "h-4 w-4" }),
+		);
+	if (hasIcon) buttonChildren.push(buildIcon(icon, size));
+	if (hasLabel) buttonChildren.push(children);
+
+	if (href) {
+		const anchorRel =
+			target === "_blank" ? (rel ?? "noopener noreferrer") : rel;
+		return React.createElement(
+			Link,
+			{
+				href: loading ? undefined : href,
+				target,
+				rel: anchorRel,
+				className: cls,
+				"data-btn-variant": variant,
+				"aria-disabled": loading || undefined,
+				...props,
+			},
+			...buttonChildren,
+		);
+	}
+
+	return React.createElement(
+		"button",
+		{
+			type: buttonType,
+			className: cls,
+			"data-btn-variant": variant,
+			disabled: loading || props.disabled,
+			...props,
+		},
+		...buttonChildren,
+	);
+}

package/templates/ui/src/card.js

@@ -0,0 +1,128 @@
+"use client";
+
+import { ChevronDown } from "lucide-react";
+import React, { useState } from "react";
+
+const cardCls =
+	"border border-[--card-border] bg-[--card-bg] transition-colors duration-200 linear";
+
+const headerCls = "flex flex-col space-y-1.5 p-6";
+
+const titleCls =
+	"text-lg font-bold leading-none tracking-tight text-[--card-title-text]";
+
+const contentCls = "p-6 pt-0";
+
+const footerCls = "flex items-center p-6 pt-0";
+
+const collapsibleTriggerCls =
+	"flex w-full cursor-pointer items-center justify-between p-6 text-[--card-title-text] transition-colors duration-200 hover:bg-[--card-trigger-hover-bg] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--card-trigger-ring)]";
+
+function CollapsibleCard({
+	className = "",
+	collapsibleLabel = "Card Details",
+	defaultOpen = false,
+	children,
+	...props
+}) {
+	const [isOpen, setIsOpen] = useState(defaultOpen);
+
+	return React.createElement(
+		"div",
+		{
+			className:
+				`${cardCls} h-fit self-start rounded-[--radius-default] ${className}`.trim(),
+			...props,
+		},
+		React.createElement(
+			"button",
+			{
+				type: "button",
+				className: collapsibleTriggerCls,
+				onClick: () => setIsOpen((prev) => !prev),
+				"aria-expanded": isOpen,
+			},
+			React.createElement(
+				"div",
+				{ className: "text-base font-bold tracking-tight flex" },
+				React.createElement("span", null, collapsibleLabel),
+			),
+			React.createElement(
+				"span",
+				{
+					"aria-hidden": "true",
+					className: `pointer-events-none ml-3 shrink-0 text-[--card-text-muted] transition-transform duration-300 ease-[cubic-bezier(0.4,0,0.2,1)] ${isOpen ? "rotate-180" : "rotate-0"}`,
+				},
+				React.createElement(ChevronDown, { size: 16 }),
+			),
+		),
+		React.createElement(
+			"div",
+			{
+				className: `border-t border-[--card-border] text-[--card-text-muted] grid transition-[grid-template-rows,opacity,transform] duration-300 ease-[cubic-bezier(0.4,0,0.2,1)] motion-reduce:transition-none ${isOpen ? "translate-y-0 opacity-100" : "-translate-y-2 opacity-0"}`,
+				style: { gridTemplateRows: isOpen ? "1fr" : "0fr" },
+			},
+			React.createElement(
+				"div",
+				{ className: "overflow-hidden min-h-0" },
+				React.createElement("div", { className: "p-6" }, children),
+			),
+		),
+	);
+}
+
+export function Card({
+	className = "",
+	variant = "default",
+	collapsibleLabel = "Card Details",
+	defaultOpen = false,
+	children,
+	...props
+}) {
+	if (variant === "collapsible") {
+		return React.createElement(CollapsibleCard, {
+			className,
+			collapsibleLabel,
+			defaultOpen,
+			children,
+			...props,
+		});
+	}
+
+	return React.createElement(
+		"div",
+		{
+			className: `${cardCls} rounded-[--radius-default] ${className}`.trim(),
+			...props,
+		},
+		children,
+	);
+}
+
+export function CardHeader({ className = "", ...props }) {
+	return React.createElement("div", {
+		className: `${headerCls} ${className}`.trim(),
+		...props,
+	});
+}
+
+export function CardTitle({ className = "", ...props }) {
+	return React.createElement("h3", {
+		className: `${titleCls} ${className}`.trim(),
+		...props,
+	});
+}
+
+export function CardContent({ className = "", ...props }) {
+	return React.createElement("div", {
+		className: `${contentCls} ${className}`.trim(),
+		...props,
+	});
+}
+
+export function CardFooter({ className = "", ...props }) {
+	return React.createElement("div", {
+		className: `${footerCls} ${className}`.trim(),
+		...props,
+	});
+}

package/templates/ui/src/checkbox.js

@@ -0,0 +1,20 @@
+import React from "react";
+
+const inputCls =
+	"h-4 w-4 rounded border-[--checkbox-border] bg-[--checkbox-bg] accent-[--checkbox-accent] transition-colors cursor-pointer focus-visible:ring-2 focus-visible:ring-[var(--checkbox-ring)] disabled:cursor-not-allowed disabled:opacity-[var(--checkbox-disabled-opacity)]";
+
+const labelCls = "text-sm text-[--checkbox-label-text] select-none";
+
+export function Checkbox({ id, label, className = "", ...props }) {
+	return React.createElement(
+		"div",
+		{ className: "flex items-center gap-2" },
+		React.createElement("input", {
+			id,
+			type: "checkbox",
+			className: `${inputCls} ${className}`.trim(),
+			...props,
+		}),
+		React.createElement("label", { htmlFor: id, className: labelCls }, label),
+	);
+}

package/templates/ui/src/container.js

@@ -0,0 +1,13 @@
+import React from "react";
+
+export function Container({ className = "", children, ...props }) {
+	return React.createElement(
+		"section",
+		{
+			className:
+				`relative overflow-hidden rounded-[--radius-default] border border-[--container-border] bg-[--container-bg] ${className}`.trim(),
+			...props,
+		},
+		children,
+	);
+}

package/templates/ui/src/dialog.js

@@ -0,0 +1,137 @@
+"use client";
+import React, {
+	useCallback,
+	useEffect,
+	useLayoutEffect,
+	useRef,
+	useState,
+} from "react";
+
+/**
+ * Dialog - centered modal built on the native <dialog> element.
+ *
+ * Props:
+ *   open      (bool)    - controlled open state
+ *   onClose   (fn)      - called when the dialog should close
+ *   title     (string)  - header text
+ *   children            - dialog body content
+ *   className (string)  - merged onto the <dialog> element
+ *
+ * Architecture:
+ *   • ALL close paths (header ×, backdrop click, Escape, external button)
+ *     flow through the `open` prop → effects, which own the animation +
+ *     el.open/close calls. handleClose() just calls onClose().
+ *   • showModal() runs in useLayoutEffect (before browser paint) to prevent
+ *     the first-load flash where the dialog appears at full opacity before
+ *     the CSS entry animation can set opacity: 0.
+ *   • isClosingRef (ref, not state) prevents the close effect from double-firing.
+ */
+
+const dialogCls =
+	"backdrop:bg-[var(--dialog-backdrop)] border border-[--dialog-border] bg-[--dialog-bg] p-0 w-full max-w-lg rounded-[--radius-default]";
+
+const headerCls =
+	"flex items-center justify-between border-b border-[--dialog-border] px-5 py-4";
+
+const titleCls =
+	"text-base font-bold tracking-tight text-[--dialog-title-text]";
+
+const closeCls =
+	"flex h-8 w-8 cursor-pointer items-center justify-center text-lg text-[--dialog-text-muted] transition-colors duration-200 linear hover:text-[--dialog-title-text] hover:bg-[--dialog-close-hover-bg] active:bg-[--dialog-close-hover-bg] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--dialog-close-ring)] rounded-[--radius-default]";
+
+const bodyCls = "px-5 py-4 text-[--dialog-text-muted]";
+
+export function Dialog({ open, onClose, title, children, className = "" }) {
+	const ref = useRef(null);
+	const [isClosing, setIsClosing] = useState(false);
+	const isClosingRef = useRef(false);
+
+	// Call showModal() before the browser paints so the CSS entry animation
+	// starts from opacity: 0 on the very first open (useEffect fires too late).
+	useLayoutEffect(() => {
+		const el = ref.current;
+		if (!el) return;
+		if (open && !el.open && typeof el.showModal === "function") el.showModal();
+	}, [open]);
+
+	// Manage state resets (open) and the exit animation (close).
+	useEffect(() => {
+		const el = ref.current;
+		if (!el) return;
+
+		if (open) {
+			isClosingRef.current = false;
+			setIsClosing(false);
+		} else {
+			// Play exit animation then close native element - regardless of who triggered close
+			if (isClosingRef.current) return; // already animating out, don't double-trigger
+			isClosingRef.current = true;
+			setIsClosing(true);
+			const t = setTimeout(() => {
+				if (el.open && typeof el.close === "function") el.close();
+				setIsClosing(false);
+				isClosingRef.current = false;
+			}, 180);
+			return () => clearTimeout(t);
+		}
+	}, [open]);
+
+	// All close-trigger sources just call onClose() - parent sets open=false,
+	// which re-runs the effect above and plays the animation.
+	const handleClose = useCallback(() => {
+		if (!isClosingRef.current) onClose?.();
+	}, [onClose]);
+
+	// Backdrop click (target is the <dialog> element itself)
+	const handleDialogClick = useCallback(
+		(e) => {
+			if (e.target === ref.current) handleClose();
+		},
+		[handleClose],
+	);
+
+	// Intercept Escape so we can animate before the native dialog closes
+	const handleCancel = useCallback(
+		(e) => {
+			e.preventDefault();
+			handleClose();
+		},
+		[handleClose],
+	);
+
+	const animStyle =
+		open || isClosing
+			? isClosing
+				? { animation: "quark-dialog-out 0.18s ease-in forwards" }
+				: { animation: "quark-dialog-in 0.2s ease-out forwards" }
+			: {};
+
+	return React.createElement(
+		"dialog",
+		{
+			ref,
+			onClick: handleDialogClick,
+			onCancel: handleCancel,
+			style: animStyle,
+			className: `${dialogCls} ${className}`.trim(),
+		},
+		// Header
+		React.createElement(
+			"div",
+			{ className: headerCls },
+			React.createElement("h2", { className: titleCls }, title),
+			React.createElement(
+				"button",
+				{
+					type: "button",
+					"aria-label": "Close dialog",
+					onClick: handleClose,
+					className: closeCls,
+				},
+				"\u00d7",
+			),
+		),
+		// Body
+		React.createElement("div", { className: bodyCls }, children),
+	);
+}

package/templates/ui/src/error-banner.js

@@ -0,0 +1,15 @@
+import React from "react";
+
+export function ErrorBanner({ message, className = "" }) {
+	if (!message) return null;
+	return React.createElement(
+		"div",
+		{
+			role: "alert",
+			"aria-live": "polite",
+			className:
+				`mb-4 border border-[--error-border] bg-[--error-bg] px-3 py-2 text-sm text-[--error-text] rounded-[--radius-default] ${className}`.trim(),
+		},
+		message,
+	);
+}