@autumnsgrove/groveengine 0.1.0

package/dist/utils/gutter.js

@@ -0,0 +1,169 @@
+/**
+ * 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) {
+  if (!anchor) {
+    return { type: 'none', value: null };
+  }
+
+  // Check for paragraph anchor: "paragraph:N"
+  const paragraphMatch = anchor.match(/^paragraph:(\d+)$/);
+  if (paragraphMatch) {
+    return { type: 'paragraph', value: parseInt(paragraphMatch[1], 10) };
+  }
+
+  // Check for tag anchor: "anchor:tagname" (supports alphanumeric, underscores, and hyphens)
+  const tagMatch = anchor.match(/^anchor:([\w-]+)$/);
+  if (tagMatch) {
+    return { type: 'tag', value: tagMatch[1] };
+  }
+
+  // Check for header anchor: "## Header Text"
+  const headerMatch = anchor.match(/^(#{1,6})\s+(.+)$/);
+  if (headerMatch) {
+    return { type: 'header', value: anchor };
+  }
+
+  // Unknown format - treat as header for backwards compatibility
+  return { type: 'header', value: anchor };
+}
+
+/**
+ * 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, headers = []) {
+  const parsed = parseAnchor(anchor);
+  switch (parsed.type) {
+    case 'header': {
+      const headerText = anchor.replace(/^#+\s*/, '');
+      const header = headers.find(h => h.text === headerText);
+      return header ? `header:${header.id}` : `header:${anchor}`;
+    }
+    case 'paragraph':
+      return `paragraph:${parsed.value}`;
+    case 'tag':
+      return `tag:${parsed.value}`;
+    default:
+      return `unknown:${anchor}`;
+  }
+}
+
+/**
+ * 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) {
+  if (!items) return [];
+  const seen = new Set();
+  const anchors = [];
+  for (const item of items) {
+    if (item.anchor && !seen.has(item.anchor)) {
+      seen.add(item.anchor);
+      anchors.push(item.anchor);
+    }
+  }
+  return anchors;
+}
+
+/**
+ * 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) {
+  const parsed = parseAnchor(anchor);
+  switch (parsed.type) {
+    case 'header':
+      return anchor.replace(/^#+\s*/, '');
+    case 'paragraph':
+      return `Paragraph ${parsed.value}`;
+    case 'tag':
+      return `Tag: ${parsed.value}`;
+    default:
+      return anchor;
+  }
+}
+
+/**
+ * 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, anchor) {
+  if (!items) return [];
+  return items.filter(item => item.anchor === anchor);
+}
+
+/**
+ * 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, headers = []) {
+  if (!items) return [];
+  return items.filter(item => {
+    if (!item.anchor) return true;
+    const parsed = parseAnchor(item.anchor);
+    if (parsed.type === 'header') {
+      const headerText = item.anchor.replace(/^#+\s*/, '');
+      return !headers.find(h => h.text === headerText);
+    }
+    // Paragraph and tag anchors are valid if they have values
+    return parsed.type === 'none';
+  });
+}
+
+/**
+ * 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, contentEl, headers = []) {
+  if (!contentEl) return null;
+
+  const parsed = parseAnchor(anchor);
+
+  switch (parsed.type) {
+    case 'header': {
+      const headerText = anchor.replace(/^#+\s*/, '');
+      const header = headers.find(h => h.text === headerText);
+      if (header) {
+        return document.getElementById(header.id);
+      }
+      return null;
+    }
+    case 'paragraph': {
+      // Select only direct child paragraphs to avoid counting paragraphs
+      // inside blockquotes, list items, etc.
+      const paragraphs = contentEl.querySelectorAll(':scope > p');
+      const index = parsed.value - 1; // Convert to 0-based index
+      if (index >= 0 && index < paragraphs.length) {
+        return paragraphs[index];
+      }
+      return null;
+    }
+    case 'tag': {
+      return contentEl.querySelector(`[data-anchor="${parsed.value}"]`);
+    }
+    default:
+      return null;
+  }
+}

package/dist/utils/imageProcessor.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Client-side image processing utility
+ * Handles WebP conversion, quality adjustment, EXIF stripping, and hash generation
+ */
+/**
+ * Calculate SHA-256 hash of file for duplicate detection
+ * @param {File|Blob} file - The file to hash
+ * @returns {Promise<string>} Hex string of the hash
+ */
+export function calculateFileHash(file: File | Blob): Promise<string>;
+/**
+ * Process an image: convert to WebP, adjust quality, strip EXIF
+ * Drawing to canvas automatically strips EXIF data including GPS
+ *
+ * @param {File} file - Original image file
+ * @param {Object} options - Processing options
+ * @param {number} options.quality - Quality 0-100 (default 80)
+ * @param {boolean} options.convertToWebP - Convert to WebP format (default true)
+ * @param {boolean} options.fullResolution - Skip resizing (default false)
+ * @returns {Promise<{ blob: Blob, width: number, height: number, originalSize: number, processedSize: number }>}
+ */
+export function processImage(file: File, options?: {
+    quality: number;
+    convertToWebP: boolean;
+    fullResolution: boolean;
+}): Promise<{
+    blob: Blob;
+    width: number;
+    height: number;
+    originalSize: number;
+    processedSize: number;
+}>;
+/**
+ * Generate a date-based path for organizing uploads
+ * Format: photos/YYYY/MM/DD/
+ * @returns {string} Date-based folder path
+ */
+export function generateDatePath(): string;
+/**
+ * Generate a clean filename from original name
+ * @param {string} originalName - Original filename
+ * @param {boolean} useWebP - Whether to use .webp extension
+ * @returns {string} Sanitized filename
+ */
+export function sanitizeFilename(originalName: string, useWebP?: boolean): string;
+/**
+ * Format bytes to human-readable string
+ * @param {number} bytes - Size in bytes
+ * @returns {string} Formatted size
+ */
+export function formatBytes(bytes: number): string;
+/**
+ * Calculate compression ratio
+ * @param {number} original - Original size in bytes
+ * @param {number} processed - Processed size in bytes
+ * @returns {string} Percentage saved
+ */
+export function compressionRatio(original: number, processed: number): string;

package/dist/utils/imageProcessor.js

@@ -0,0 +1,205 @@
+/**
+ * Client-side image processing utility
+ * Handles WebP conversion, quality adjustment, EXIF stripping, and hash generation
+ */
+
+/**
+ * Calculate SHA-256 hash of file for duplicate detection
+ * @param {File|Blob} file - The file to hash
+ * @returns {Promise<string>} Hex string of the hash
+ */
+export async function calculateFileHash(file) {
+  const buffer = await file.arrayBuffer();
+  const hashBuffer = await crypto.subtle.digest('SHA-256', buffer);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Load an image from a File object
+ * @param {File} file - Image file
+ * @returns {Promise<HTMLImageElement>}
+ */
+function loadImage(file) {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    img.onload = () => {
+      URL.revokeObjectURL(img.src);
+      resolve(img);
+    };
+    img.onerror = () => {
+      URL.revokeObjectURL(img.src);
+      reject(new Error('Failed to load image'));
+    };
+    img.src = URL.createObjectURL(file);
+  });
+}
+
+/**
+ * Calculate dimensions maintaining aspect ratio
+ * @param {number} width - Original width
+ * @param {number} height - Original height
+ * @param {number} maxDimension - Maximum dimension (width or height)
+ * @returns {{ width: number, height: number }}
+ */
+function calculateDimensions(width, height, maxDimension) {
+  if (width <= maxDimension && height <= maxDimension) {
+    return { width, height };
+  }
+
+  const ratio = Math.min(maxDimension / width, maxDimension / height);
+  return {
+    width: Math.round(width * ratio),
+    height: Math.round(height * ratio)
+  };
+}
+
+/**
+ * Get max dimension based on quality setting
+ * Higher quality = larger max dimension
+ * @param {number} quality - Quality 0-100
+ * @returns {number} Max dimension in pixels
+ */
+function getMaxDimensionForQuality(quality) {
+  if (quality >= 90) return 4096;
+  if (quality >= 70) return 2560;
+  if (quality >= 50) return 1920;
+  if (quality >= 30) return 1280;
+  return 960;
+}
+
+/**
+ * Process an image: convert to WebP, adjust quality, strip EXIF
+ * Drawing to canvas automatically strips EXIF data including GPS
+ *
+ * @param {File} file - Original image file
+ * @param {Object} options - Processing options
+ * @param {number} options.quality - Quality 0-100 (default 80)
+ * @param {boolean} options.convertToWebP - Convert to WebP format (default true)
+ * @param {boolean} options.fullResolution - Skip resizing (default false)
+ * @returns {Promise<{ blob: Blob, width: number, height: number, originalSize: number, processedSize: number }>}
+ */
+export async function processImage(file, options = {}) {
+  const {
+    quality = 80,
+    convertToWebP = true,
+    fullResolution = false
+  } = options;
+
+  // For GIFs, return original to preserve animation
+  if (file.type === 'image/gif') {
+    return {
+      blob: file,
+      width: 0,
+      height: 0,
+      originalSize: file.size,
+      processedSize: file.size,
+      skipped: true,
+      reason: 'GIF preserved for animation'
+    };
+  }
+
+  const img = await loadImage(file);
+  const originalSize = file.size;
+
+  // Calculate target dimensions
+  let targetWidth = img.naturalWidth;
+  let targetHeight = img.naturalHeight;
+
+  if (!fullResolution) {
+    const maxDim = getMaxDimensionForQuality(quality);
+    const dims = calculateDimensions(img.naturalWidth, img.naturalHeight, maxDim);
+    targetWidth = dims.width;
+    targetHeight = dims.height;
+  }
+
+  // Create canvas and draw image (this strips EXIF data)
+  const canvas = document.createElement('canvas');
+  canvas.width = targetWidth;
+  canvas.height = targetHeight;
+
+  const ctx = canvas.getContext('2d');
+  ctx.drawImage(img, 0, 0, targetWidth, targetHeight);
+
+  // Convert to blob
+  const mimeType = convertToWebP ? 'image/webp' : file.type;
+  const qualityDecimal = quality / 100;
+
+  const blob = await new Promise((resolve) => {
+    canvas.toBlob(resolve, mimeType, qualityDecimal);
+  });
+
+  return {
+    blob,
+    width: targetWidth,
+    height: targetHeight,
+    originalSize,
+    processedSize: blob.size,
+    skipped: false
+  };
+}
+
+/**
+ * Generate a date-based path for organizing uploads
+ * Format: photos/YYYY/MM/DD/
+ * @returns {string} Date-based folder path
+ */
+export function generateDatePath() {
+  const now = new Date();
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, '0');
+  const day = String(now.getDate()).padStart(2, '0');
+  return `photos/${year}/${month}/${day}`;
+}
+
+/**
+ * Generate a clean filename from original name
+ * @param {string} originalName - Original filename
+ * @param {boolean} useWebP - Whether to use .webp extension
+ * @returns {string} Sanitized filename
+ */
+export function sanitizeFilename(originalName, useWebP = true) {
+  // Get base name without extension
+  const lastDot = originalName.lastIndexOf('.');
+  const baseName = lastDot > 0 ? originalName.substring(0, lastDot) : originalName;
+  const originalExt = lastDot > 0 ? originalName.substring(lastDot + 1).toLowerCase() : '';
+
+  // Sanitize the base name
+  const sanitized = baseName
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+    .substring(0, 100); // Limit length
+
+  // Add timestamp for uniqueness
+  const timestamp = Date.now().toString(36);
+
+  // Determine extension
+  const ext = useWebP && originalExt !== 'gif' ? 'webp' : originalExt;
+
+  return `${sanitized}-${timestamp}.${ext}`;
+}
+
+/**
+ * Format bytes to human-readable string
+ * @param {number} bytes - Size in bytes
+ * @returns {string} Formatted size
+ */
+export function formatBytes(bytes) {
+  if (bytes < 1024) return bytes + ' B';
+  if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(1) + ' KB';
+  return (bytes / (1024 * 1024)).toFixed(1) + ' MB';
+}
+
+/**
+ * Calculate compression ratio
+ * @param {number} original - Original size in bytes
+ * @param {number} processed - Processed size in bytes
+ * @returns {string} Percentage saved
+ */
+export function compressionRatio(original, processed) {
+  if (original <= 0) return '0%';
+  const saved = ((original - processed) / original) * 100;
+  return saved > 0 ? `-${saved.toFixed(0)}%` : `+${Math.abs(saved).toFixed(0)}%`;
+}

package/dist/utils/json.d.ts

@@ -0,0 +1,17 @@
+/**
+ * JSON utility functions
+ */
+/**
+ * Safely parse JSON with fallback for corrupted or missing data.
+ * Prevents crashes when parsing malformed JSON from external sources.
+ *
+ * @param {string|null|undefined} str - JSON string to parse
+ * @param {*} fallback - Fallback value if parsing fails (default: [])
+ * @returns {*} Parsed value or fallback
+ *
+ * @example
+ * safeJsonParse('["a","b"]', [])  // Returns ['a', 'b']
+ * safeJsonParse('invalid', [])    // Returns []
+ * safeJsonParse(null, {})         // Returns {}
+ */
+export function safeJsonParse(str: string | null | undefined, fallback?: any): any;

package/dist/utils/json.js

@@ -0,0 +1,26 @@
+/**
+ * JSON utility functions
+ */
+
+/**
+ * Safely parse JSON with fallback for corrupted or missing data.
+ * Prevents crashes when parsing malformed JSON from external sources.
+ *
+ * @param {string|null|undefined} str - JSON string to parse
+ * @param {*} fallback - Fallback value if parsing fails (default: [])
+ * @returns {*} Parsed value or fallback
+ *
+ * @example
+ * safeJsonParse('["a","b"]', [])  // Returns ['a', 'b']
+ * safeJsonParse('invalid', [])    // Returns []
+ * safeJsonParse(null, {})         // Returns {}
+ */
+export function safeJsonParse(str, fallback = []) {
+  if (!str) return fallback;
+  try {
+    return JSON.parse(str);
+  } catch (e) {
+    console.warn('Failed to parse JSON:', e.message);
+    return fallback;
+  }
+}

package/dist/utils/markdown.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Get the site configuration
+ * @returns {Object} Site configuration object
+ */
+export function getSiteConfig(): Object;
+/**
+ * Get all markdown posts from the posts directory
+ * @returns {Array} Array of post objects with metadata and slug
+ */
+export function getAllPosts(): any[];
+/**
+ * Get the latest (most recent) post with full content
+ * @returns {Object|null} The latest post object with content, or null if no posts exist
+ */
+export function getLatestPost(): Object | null;
+/**
+ * Get all recipes from the recipes directory
+ * @returns {Array} Array of recipe objects with metadata and slug
+ */
+export function getAllRecipes(): any[];
+/**
+ * Get a single post by slug
+ * @param {string} slug - The post slug
+ * @returns {Object|null} Post object with content and metadata
+ */
+export function getPostBySlug(slug: string): Object | null;
+/**
+ * Extract headers from markdown content for table of contents
+ * @param {string} markdown - The raw markdown content
+ * @returns {Array} Array of header objects with level, text, and id
+ */
+export function extractHeaders(markdown: string): any[];
+/**
+ * Process anchor tags in HTML content
+ * Converts <!-- anchor:tagname --> comments to identifiable span elements
+ * @param {string} html - The HTML content
+ * @returns {string} HTML with anchor markers converted to spans
+ */
+export function processAnchorTags(html: string): string;
+/**
+ * Get gutter content for a recipe by slug
+ * @param {string} slug - The recipe slug
+ * @returns {Array} Array of gutter items with content and position info
+ */
+export function getRecipeGutterContent(slug: string): any[];
+/**
+ * Get gutter content for a blog post by slug
+ * @param {string} slug - The post slug
+ * @returns {Array} Array of gutter items with content and position info
+ */
+export function getGutterContent(slug: string): any[];
+/**
+ * Get gutter content for the home page
+ * @param {string} slug - The page slug (e.g., 'home')
+ * @returns {Array} Array of gutter items with content and position info
+ */
+export function getHomeGutterContent(slug: string): any[];
+/**
+ * Get gutter content for the contact page
+ * @param {string} slug - The page slug (e.g., 'contact')
+ * @returns {Array} Array of gutter items with content and position info
+ */
+export function getContactGutterContent(slug: string): any[];
+/**
+ * Get the home page content
+ * @returns {Object|null} Home page object with content, metadata, and galleries
+ */
+export function getHomePage(): Object | null;
+/**
+ * Get the contact page content
+ * @returns {Object|null} Contact page object with content and metadata
+ */
+export function getContactPage(): Object | null;
+/**
+ * Get the about page content
+ * @returns {Object|null} About page object with content and metadata
+ */
+export function getAboutPage(): Object | null;
+/**
+ * Get gutter content for the about page
+ * @param {string} slug - The page slug (e.g., 'about')
+ * @returns {Array} Array of gutter items with content and position info
+ */
+export function getAboutGutterContent(slug: string): any[];
+/**
+ * Get recipe metadata (step icons, etc.) for a recipe by slug
+ * @param {string} slug - The recipe slug
+ * @returns {Object|null} Recipe metadata with instruction icons
+ */
+export function getRecipeSidecar(slug: string): Object | null;
+/**
+ * Get a single recipe by slug
+ * @param {string} slug - The recipe slug
+ * @returns {Object|null} Recipe object with content and metadata
+ */
+export function getRecipeBySlug(slug: string): Object | null;
+/**
+ * Render Mermaid diagrams in the DOM
+ * This should be called after the content is mounted
+ */
+export function renderMermaidDiagrams(): Promise<void>;