@autumnsgrove/groveengine 0.1.0

package/dist/utils/api.js

@@ -0,0 +1,109 @@
+/**
+ * Client-side API utility with automatic CSRF token injection
+ * Provides fetch wrapper with security headers and error handling
+ */
+
+/**
+ * Fetch wrapper with automatic CSRF token injection
+ * @param {string} url - API endpoint URL
+ * @param {RequestInit} options - Fetch options
+ * @returns {Promise<any>} Response JSON
+ * @throws {Error} If request fails
+ */
+export async function apiRequest(url, options = {}) {
+	const csrfToken = document.querySelector('meta[name="csrf-token"]')?.content;
+
+	// Build headers - don't set Content-Type for FormData (browser sets it with boundary)
+	const headers = {
+		...(csrfToken && { 'X-CSRF-Token': csrfToken }),
+		...options.headers
+	};
+
+	// Only add Content-Type if not FormData
+	if (!(options.body instanceof FormData)) {
+		headers['Content-Type'] = 'application/json';
+	}
+
+	const response = await fetch(url, {
+		...options,
+		headers
+	});
+
+	if (!response.ok) {
+		let errorMessage = 'Request failed';
+		try {
+			const error = await response.json();
+			errorMessage = error.message || errorMessage;
+		} catch {
+			errorMessage = `${response.status} ${response.statusText}`;
+		}
+		throw new Error(errorMessage);
+	}
+
+	// Handle empty responses (204 No Content)
+	if (response.status === 204) {
+		return null;
+	}
+
+	return response.json();
+}
+
+/**
+ * Convenience methods for common HTTP verbs
+ */
+export const api = {
+	/**
+	 * GET request
+	 * @param {string} url - API endpoint
+	 * @param {RequestInit} options - Additional fetch options
+	 */
+	get: (url, options = {}) =>
+		apiRequest(url, { ...options, method: 'GET' }),
+
+	/**
+	 * POST request
+	 * @param {string} url - API endpoint
+	 * @param {any} body - Request body (will be JSON stringified)
+	 * @param {RequestInit} options - Additional fetch options
+	 */
+	post: (url, body, options = {}) =>
+		apiRequest(url, {
+			...options,
+			method: 'POST',
+			body: JSON.stringify(body)
+		}),
+
+	/**
+	 * PUT request
+	 * @param {string} url - API endpoint
+	 * @param {any} body - Request body (will be JSON stringified)
+	 * @param {RequestInit} options - Additional fetch options
+	 */
+	put: (url, body, options = {}) =>
+		apiRequest(url, {
+			...options,
+			method: 'PUT',
+			body: JSON.stringify(body)
+		}),
+
+	/**
+	 * DELETE request
+	 * @param {string} url - API endpoint
+	 * @param {RequestInit} options - Additional fetch options
+	 */
+	delete: (url, options = {}) =>
+		apiRequest(url, { ...options, method: 'DELETE' }),
+
+	/**
+	 * PATCH request
+	 * @param {string} url - API endpoint
+	 * @param {any} body - Request body (will be JSON stringified)
+	 * @param {RequestInit} options - Additional fetch options
+	 */
+	patch: (url, body, options = {}) =>
+		apiRequest(url, {
+			...options,
+			method: 'PATCH',
+			body: JSON.stringify(body)
+		})
+};

package/dist/utils/cn.d.ts

@@ -0,0 +1,15 @@
+import { type ClassValue } from "clsx";
+/**
+ * Utility function for merging Tailwind CSS classes
+ *
+ * Combines clsx for conditional class logic and tailwind-merge to
+ * handle Tailwind class conflicts intelligently.
+ *
+ * @param inputs - Class values to merge (strings, objects, arrays)
+ * @returns Merged class string
+ *
+ * @example
+ * cn('px-2 py-1', className)
+ * cn('text-blue-500', { 'text-red-500': isError })
+ */
+export declare function cn(...inputs: ClassValue[]): string;

package/dist/utils/cn.js

@@ -0,0 +1,18 @@
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+/**
+ * Utility function for merging Tailwind CSS classes
+ *
+ * Combines clsx for conditional class logic and tailwind-merge to
+ * handle Tailwind class conflicts intelligently.
+ *
+ * @param inputs - Class values to merge (strings, objects, arrays)
+ * @returns Merged class string
+ *
+ * @example
+ * cn('px-2 py-1', className)
+ * cn('text-blue-500', { 'text-red-500': isError })
+ */
+export function cn(...inputs) {
+    return twMerge(clsx(inputs));
+}

package/dist/utils/csrf.d.ts

@@ -0,0 +1,22 @@
+/**
+ * CSRF Protection Utilities
+ * Validates requests come from same origin
+ */
+/**
+ * Generate cryptographically secure CSRF token
+ * @returns {string} UUID v4 token
+ */
+export function generateCSRFToken(): string;
+/**
+ * Validate CSRF token from request against session token
+ * @param {Request} request - The incoming request
+ * @param {string} sessionToken - The token stored in the session
+ * @returns {boolean}
+ */
+export function validateCSRFToken(request: Request, sessionToken: string): boolean;
+/**
+ * Validate CSRF token from request headers (origin-based fallback)
+ * @param {Request} request
+ * @returns {boolean}
+ */
+export function validateCSRF(request: Request): boolean;

package/dist/utils/csrf.js

@@ -0,0 +1,72 @@
+/**
+ * CSRF Protection Utilities
+ * Validates requests come from same origin
+ */
+
+/**
+ * Generate cryptographically secure CSRF token
+ * @returns {string} UUID v4 token
+ */
+export function generateCSRFToken() {
+	return crypto.randomUUID();
+}
+
+/**
+ * Validate CSRF token from request against session token
+ * @param {Request} request - The incoming request
+ * @param {string} sessionToken - The token stored in the session
+ * @returns {boolean}
+ */
+export function validateCSRFToken(request, sessionToken) {
+	if (!sessionToken) return false;
+
+	const headerToken = request.headers.get('x-csrf-token');
+	const bodyToken = request.headers.get('csrf-token'); // fallback
+
+	if (!headerToken && !bodyToken) return false;
+
+	return (headerToken === sessionToken) || (bodyToken === sessionToken);
+}
+
+/**
+ * Validate CSRF token from request headers (origin-based fallback)
+ * @param {Request} request
+ * @returns {boolean}
+ */
+export function validateCSRF(request) {
+	// Handle edge cases
+	if (!request || typeof request !== 'object') {
+		return false;
+	}
+
+	if (!request.headers || typeof request.headers.get !== 'function') {
+		return false;
+	}
+
+	const origin = request.headers.get('origin');
+	const host = request.headers.get('host');
+
+	// Allow same-origin requests
+	if (origin) {
+		try {
+			const originUrl = new URL(origin);
+
+			// Validate protocol (must be http or https)
+			if (!['http:', 'https:'].includes(originUrl.protocol)) {
+				return false;
+			}
+
+			const isLocalhost = originUrl.hostname === 'localhost' ||
+			                   originUrl.hostname === '127.0.0.1';
+			const hostMatches = host && originUrl.host === host;
+
+			if (!isLocalhost && !hostMatches) {
+				return false;
+			}
+		} catch {
+			return false;
+		}
+	}
+
+	return true;
+}

package/dist/utils/debounce.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Debounce function calls
+ * @param {Function} fn - Function to debounce
+ * @param {number} delay - Delay in milliseconds
+ * @returns {Function} Debounced function
+ */
+export function debounce(fn: Function, delay?: number): Function;

package/dist/utils/debounce.js

@@ -0,0 +1,14 @@
+/**
+ * Debounce function calls
+ * @param {Function} fn - Function to debounce
+ * @param {number} delay - Delay in milliseconds
+ * @returns {Function} Debounced function
+ */
+export function debounce(fn, delay = 300) {
+	let timeoutId;
+
+	return function (...args) {
+		clearTimeout(timeoutId);
+		timeoutId = setTimeout(() => fn.apply(this, args), delay);
+	};
+}

package/dist/utils/gallery.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Gallery utilities for filename parsing and filtering
+ * Extracts metadata from smart filenames like:
+ * - 2025-01-15_forest-walk.jpg → date: 2025-01-15, slug: forest-walk
+ * - minecraft/build_2024-12-01.png → category: minecraft, date: 2024-12-01
+ * - selfies/2024-summer.jpg → category: selfies, slug: 2024-summer
+ */
+/**
+ * Parse a filename to extract metadata
+ * @param {string} r2Key - R2 object key (e.g., 'minecraft/build.png' or '2025-01-15_photo.jpg')
+ * @returns {Object} Parsed metadata: { category, date, slug, filename, extension }
+ */
+export function parseImageFilename(r2Key: string): Object;
+/**
+ * Get display title for an image (uses custom title or parsed slug)
+ * @param {Object} image - Gallery image object
+ * @returns {string} Human-readable title
+ */
+export function getImageTitle(image: Object): string;
+/**
+ * Get display date for an image (uses custom date or parsed date)
+ * @param {Object} image - Gallery image object
+ * @returns {string|null} YYYY-MM-DD date string or null
+ */
+export function getImageDate(image: Object): string | null;
+/**
+ * Filter images by search query (searches title, slug, filename)
+ * @param {Array} images - Array of gallery images
+ * @param {string} query - Search query
+ * @returns {Array} Filtered images
+ */
+export function searchImages(images: any[], query: string): any[];
+/**
+ * Filter images by date range
+ * @param {Array} images - Array of gallery images
+ * @param {string|null} startDate - YYYY-MM-DD start date (inclusive)
+ * @param {string|null} endDate - YYYY-MM-DD end date (inclusive)
+ * @returns {Array} Filtered images
+ */
+export function filterImagesByDateRange(images: any[], startDate: string | null, endDate: string | null): any[];
+/**
+ * Filter images by tags
+ * @param {Array} images - Array of gallery images (must include 'tags' array)
+ * @param {Array} tagSlugs - Array of tag slugs to filter by
+ * @returns {Array} Filtered images
+ */
+export function filterImagesByTags(images: any[], tagSlugs: any[]): any[];
+/**
+ * Filter images by category (parsed from path)
+ * @param {Array} images - Array of gallery images
+ * @param {string|null} category - Category to filter by
+ * @returns {Array} Filtered images
+ */
+export function filterImagesByCategory(images: any[], category: string | null): any[];
+/**
+ * Extract unique years from image dates
+ * @param {Array} images - Array of gallery images
+ * @returns {Array} Sorted array of years (descending)
+ */
+export function getAvailableYears(images: any[]): any[];
+/**
+ * Extract unique categories from images
+ * @param {Array} images - Array of gallery images
+ * @returns {Array} Sorted array of categories
+ */
+export function getAvailableCategories(images: any[]): any[];

package/dist/utils/gallery.js

@@ -0,0 +1,181 @@
+/**
+ * Gallery utilities for filename parsing and filtering
+ * Extracts metadata from smart filenames like:
+ * - 2025-01-15_forest-walk.jpg → date: 2025-01-15, slug: forest-walk
+ * - minecraft/build_2024-12-01.png → category: minecraft, date: 2024-12-01
+ * - selfies/2024-summer.jpg → category: selfies, slug: 2024-summer
+ */
+
+/**
+ * Parse a filename to extract metadata
+ * @param {string} r2Key - R2 object key (e.g., 'minecraft/build.png' or '2025-01-15_photo.jpg')
+ * @returns {Object} Parsed metadata: { category, date, slug, filename, extension }
+ */
+export function parseImageFilename(r2Key) {
+	const parts = r2Key.split('/');
+	const filename = parts[parts.length - 1];
+	const category = parts.length > 1 ? parts[0] : null;
+
+	// Extract extension
+	const extMatch = filename.match(/\.([^.]+)$/);
+	const extension = extMatch ? extMatch[1] : null;
+	const nameWithoutExt = filename.replace(/\.[^.]+$/, '');
+
+	// Try to extract date (YYYY-MM-DD or YYYY_MM_DD)
+	const dateMatch = nameWithoutExt.match(/(\d{4}[-_]\d{2}[-_]\d{2})/);
+	const date = dateMatch ? dateMatch[1].replace(/_/g, '-') : null;
+
+	// Extract slug (remove date prefix if present)
+	let slug = nameWithoutExt;
+	if (date) {
+		slug = slug.replace(date, '').replace(/^[-_]+/, '').replace(/[-_]+$/, '');
+	}
+
+	// Clean up slug (convert underscores to hyphens)
+	slug = slug.replace(/_/g, '-').toLowerCase();
+
+	return {
+		category,
+		date,
+		slug: slug || 'untitled',
+		filename,
+		extension,
+		r2Key
+	};
+}
+
+/**
+ * Get display title for an image (uses custom title or parsed slug)
+ * @param {Object} image - Gallery image object
+ * @returns {string} Human-readable title
+ */
+export function getImageTitle(image) {
+	if (image.custom_title) return image.custom_title;
+	if (image.parsed_slug) {
+		// Convert slug to Title Case
+		return image.parsed_slug
+			.split('-')
+			.map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+			.join(' ');
+	}
+	return image.r2_key?.split('/').pop() || image.key?.split('/').pop() || 'Untitled';
+}
+
+/**
+ * Get display date for an image (uses custom date or parsed date)
+ * @param {Object} image - Gallery image object
+ * @returns {string|null} YYYY-MM-DD date string or null
+ */
+export function getImageDate(image) {
+	return image.custom_date || image.parsed_date || null;
+}
+
+/**
+ * Filter images by search query (searches title, slug, filename)
+ * @param {Array} images - Array of gallery images
+ * @param {string} query - Search query
+ * @returns {Array} Filtered images
+ */
+export function searchImages(images, query) {
+	if (!query) return images;
+
+	const lowerQuery = query.toLowerCase();
+
+	return images.filter((img) => {
+		const title = getImageTitle(img).toLowerCase();
+		const slug = (img.parsed_slug || '').toLowerCase();
+		const filename = (img.r2_key || img.key || '').toLowerCase();
+		const description = (img.custom_description || '').toLowerCase();
+
+		return (
+			title.includes(lowerQuery) ||
+			slug.includes(lowerQuery) ||
+			filename.includes(lowerQuery) ||
+			description.includes(lowerQuery)
+		);
+	});
+}
+
+/**
+ * Filter images by date range
+ * @param {Array} images - Array of gallery images
+ * @param {string|null} startDate - YYYY-MM-DD start date (inclusive)
+ * @param {string|null} endDate - YYYY-MM-DD end date (inclusive)
+ * @returns {Array} Filtered images
+ */
+export function filterImagesByDateRange(images, startDate, endDate) {
+	if (!startDate && !endDate) return images;
+
+	return images.filter((img) => {
+		const imgDate = getImageDate(img);
+		if (!imgDate) return false;
+
+		if (startDate && imgDate < startDate) return false;
+		if (endDate && imgDate > endDate) return false;
+
+		return true;
+	});
+}
+
+/**
+ * Filter images by tags
+ * @param {Array} images - Array of gallery images (must include 'tags' array)
+ * @param {Array} tagSlugs - Array of tag slugs to filter by
+ * @returns {Array} Filtered images
+ */
+export function filterImagesByTags(images, tagSlugs) {
+	if (!tagSlugs || tagSlugs.length === 0) return images;
+
+	return images.filter((img) => {
+		if (!img.tags || img.tags.length === 0) return false;
+		const imgTagSlugs = img.tags.map((t) => t.slug);
+		return tagSlugs.every((slug) => imgTagSlugs.includes(slug));
+	});
+}
+
+/**
+ * Filter images by category (parsed from path)
+ * @param {Array} images - Array of gallery images
+ * @param {string|null} category - Category to filter by
+ * @returns {Array} Filtered images
+ */
+export function filterImagesByCategory(images, category) {
+	if (!category) return images;
+	return images.filter((img) => img.parsed_category === category);
+}
+
+/**
+ * Extract unique years from image dates
+ * @param {Array} images - Array of gallery images
+ * @returns {Array} Sorted array of years (descending)
+ */
+export function getAvailableYears(images) {
+	const years = new Set();
+
+	images.forEach((img) => {
+		const date = getImageDate(img);
+		if (date) {
+			const year = date.substring(0, 4);
+			years.add(year);
+		}
+	});
+
+	return Array.from(years).sort((a, b) => b.localeCompare(a));
+}
+
+/**
+ * Extract unique categories from images
+ * @param {Array} images - Array of gallery images
+ * @returns {Array} Sorted array of categories
+ */
+export function getAvailableCategories(images) {
+	const categories = new Set();
+
+	images.forEach((img) => {
+		if (img.parsed_category) {
+			categories.add(img.parsed_category);
+		}
+	});
+
+	return Array.from(categories).sort();
+}

package/dist/utils/gutter.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared Gutter Utilities
+ *
+ * This module provides common utilities for gutter content positioning
+ * and anchor resolution. Used by ContentWithGutter component and related
+ * functionality across the site.
+ */
+/**
+ * Parse anchor string to determine anchor type and value
+ * @param {string} anchor - The anchor string from manifest
+ * @returns {Object} Object with type and value properties
+ */
+export function parseAnchor(anchor: string): Object;
+/**
+ * Generate a unique key for an anchor (used for grouping and positioning)
+ * @param {string} anchor - The anchor string
+ * @param {Array} headers - Array of header objects with id and text
+ * @returns {string} A unique key for the anchor
+ */
+export function getAnchorKey(anchor: string, headers?: any[]): string;
+/**
+ * Get all unique anchors from items (preserving order)
+ * @param {Array} items - Array of gutter items
+ * @returns {Array} Array of unique anchor strings
+ */
+export function getUniqueAnchors(items: any[]): any[];
+/**
+ * Get display label for an anchor (used in overflow section)
+ * @param {string} anchor - The anchor string
+ * @returns {string} Human-readable label for the anchor
+ */
+export function getAnchorLabel(anchor: string): string;
+/**
+ * Get items that match a specific anchor
+ * @param {Array} items - Array of gutter items
+ * @param {string} anchor - The anchor to match
+ * @returns {Array} Items matching the anchor
+ */
+export function getItemsForAnchor(items: any[], anchor: string): any[];
+/**
+ * Get items that don't have a valid anchor (orphan items shown at top)
+ * @param {Array} items - Array of gutter items
+ * @param {Array} headers - Array of header objects
+ * @returns {Array} Items without valid anchors
+ */
+export function getOrphanItems(items: any[], headers?: any[]): any[];
+/**
+ * Find the DOM element for an anchor within a content element
+ * @param {string} anchor - The anchor string
+ * @param {HTMLElement} contentEl - The content container element
+ * @param {Array} headers - Array of header objects
+ * @returns {HTMLElement|null} The DOM element or null if not found
+ */
+export function findAnchorElement(anchor: string, contentEl: HTMLElement, headers?: any[]): HTMLElement | null;