@autumnsgrove/groveengine 0.6.2 → 0.6.4

package/dist/utils/gutter.js

@@ -5,165 +5,157 @@
  * 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
+ * @param anchor - The anchor string from manifest
+ * @returns 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 };
+    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
+ * @param anchor - The anchor string
+ * @param headers - Array of header objects with id and text
+ * @returns 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}`;
+    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}`;
     }
-    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
+ * @param items - Array of gutter items
+ * @returns 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);
+    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;
+    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
+ * @param anchor - The anchor string
+ * @returns 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;
-  }
+    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
+ * @param items - Array of gutter items
+ * @param anchor - The anchor to match
+ * @returns Items matching the anchor
  */
 export function getItemsForAnchor(items, anchor) {
-  if (!items) return [];
-  return items.filter(item => item.anchor === 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
+ * @param items - Array of gutter items
+ * @param headers - Array of header objects
+ * @returns 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';
-  });
+    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
+ * @param anchor - The anchor string
+ * @param contentEl - The content container element
+ * @param headers - Array of header objects
+ * @returns 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}"]`);
+    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;
     }
-    default:
-      return null;
-  }
 }

package/dist/utils/imageProcessor.d.ts

@@ -8,28 +8,31 @@
  * @returns {Promise<string>} Hex string of the hash
  */
 export function calculateFileHash(file: File | Blob): Promise<string>;
+/**
+ * @typedef {Object} ProcessedImageResult
+ * @property {Blob} blob - Processed image blob
+ * @property {number} width - Image width
+ * @property {number} height - Image height
+ * @property {number} originalSize - Original file size
+ * @property {number} processedSize - Processed file size
+ * @property {boolean} [skipped] - Whether processing was skipped
+ * @property {string} [reason] - Reason for skipping
+ */
+/**
+ * @typedef {Object} ProcessImageOptions
+ * @property {number} [quality] - Quality 0-100 (default 80)
+ * @property {boolean} [convertToWebP] - Convert to WebP format (default true)
+ * @property {boolean} [fullResolution] - Skip resizing (default false)
+ */
 /**
  * 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;
-}>;
+ * @param {ProcessImageOptions} options - Processing options
+ * @returns {Promise<ProcessedImageResult>}
+ */
+export function processImage(file: File, options?: ProcessImageOptions): Promise<ProcessedImageResult>;
 /**
  * Generate a date-based path for organizing uploads
  * Format: photos/YYYY/MM/DD/
@@ -37,12 +40,12 @@ export function processImage(file: File, options?: {
  */
 export function generateDatePath(): string;
 /**
- * Generate a clean filename from original name
+ * Generate a clean filename from original name for image files
  * @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;
+export function sanitizeImageFilename(originalName: string, useWebP?: boolean): string;
 /**
  * Format bytes to human-readable string
  * @param {number} bytes - Size in bytes
@@ -56,3 +59,47 @@ export function formatBytes(bytes: number): string;
  * @returns {string} Percentage saved
  */
 export function compressionRatio(original: number, processed: number): string;
+export type ProcessedImageResult = {
+    /**
+     * - Processed image blob
+     */
+    blob: Blob;
+    /**
+     * - Image width
+     */
+    width: number;
+    /**
+     * - Image height
+     */
+    height: number;
+    /**
+     * - Original file size
+     */
+    originalSize: number;
+    /**
+     * - Processed file size
+     */
+    processedSize: number;
+    /**
+     * - Whether processing was skipped
+     */
+    skipped?: boolean | undefined;
+    /**
+     * - Reason for skipping
+     */
+    reason?: string | undefined;
+};
+export type ProcessImageOptions = {
+    /**
+     * - Quality 0-100 (default 80)
+     */
+    quality?: number | undefined;
+    /**
+     * - Convert to WebP format (default true)
+     */
+    convertToWebP?: boolean | undefined;
+    /**
+     * - Skip resizing (default false)
+     */
+    fullResolution?: boolean | undefined;
+};

package/dist/utils/imageProcessor.js

@@ -68,16 +68,31 @@ function getMaxDimensionForQuality(quality) {
   return 960;
 }
 
+/**
+ * @typedef {Object} ProcessedImageResult
+ * @property {Blob} blob - Processed image blob
+ * @property {number} width - Image width
+ * @property {number} height - Image height
+ * @property {number} originalSize - Original file size
+ * @property {number} processedSize - Processed file size
+ * @property {boolean} [skipped] - Whether processing was skipped
+ * @property {string} [reason] - Reason for skipping
+ */
+
+/**
+ * @typedef {Object} ProcessImageOptions
+ * @property {number} [quality] - Quality 0-100 (default 80)
+ * @property {boolean} [convertToWebP] - Convert to WebP format (default true)
+ * @property {boolean} [fullResolution] - Skip resizing (default false)
+ */
+
 /**
  * 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 }>}
+ * @param {ProcessImageOptions} options - Processing options
+ * @returns {Promise<ProcessedImageResult>}
  */
 export async function processImage(file, options = {}) {
   const {
@@ -119,14 +134,20 @@ export async function processImage(file, options = {}) {
   canvas.height = targetHeight;
 
   const ctx = canvas.getContext('2d');
+  if (!ctx) {
+    throw new Error('Failed to get canvas 2d context');
+  }
   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);
+  const blob = await new Promise((resolve, reject) => {
+    canvas.toBlob((b) => {
+      if (b) resolve(b);
+      else reject(new Error('Failed to create blob'));
+    }, mimeType, qualityDecimal);
   });
 
   return {
@@ -134,7 +155,7 @@ export async function processImage(file, options = {}) {
     width: targetWidth,
     height: targetHeight,
     originalSize,
-    processedSize: blob.size,
+    processedSize: /** @type {Blob} */ (blob).size,
     skipped: false
   };
 }
@@ -153,12 +174,12 @@ export function generateDatePath() {
 }
 
 /**
- * Generate a clean filename from original name
+ * Generate a clean filename from original name for image files
  * @param {string} originalName - Original filename
  * @param {boolean} useWebP - Whether to use .webp extension
  * @returns {string} Sanitized filename
  */
-export function sanitizeFilename(originalName, useWebP = true) {
+export function sanitizeImageFilename(originalName, useWebP = true) {
   // Get base name without extension
   const lastDot = originalName.lastIndexOf('.');
   const baseName = lastDot > 0 ? originalName.substring(0, lastDot) : originalName;

package/dist/utils/index.d.ts

@@ -1,11 +1,11 @@
-export * from "./api.js";
-export * from "./cn.js";
-export * from "./csrf.js";
-export * from "./debounce.js";
-export * from "./gallery.js";
-export * from "./gutter.js";
-export * from "./imageProcessor.js";
-export * from "./json.js";
-export * from "./markdown.js";
-export * from "./sanitize.js";
-export * from "./validation.js";
+export * from './api.js';
+export * from './cn.js';
+export * from './csrf.js';
+export * from './debounce.js';
+export { parseImageFilename, getImageTitle, getImageDate, searchImages, filterImagesByDateRange, filterImagesByTags, filterImagesByCategory, getAvailableYears, getAvailableCategories, type GalleryImage, type ImageTag, type ParsedImageMetadata } from './gallery.js';
+export { parseAnchor, getAnchorKey, getUniqueAnchors, getAnchorLabel, getItemsForAnchor, getOrphanItems, findAnchorElement, type AnchorType, type ParsedAnchor, type Header, type GutterItem } from './gutter.js';
+export * from './imageProcessor.js';
+export * from './json.js';
+export * from './markdown.js';
+export * from './sanitize.js';
+export * from './validation.js';

package/dist/utils/index.js

@@ -1,12 +1,13 @@
 // Utils barrel export
 // Re-exports all utility functions from the utils module
-
 export * from './api.js';
 export * from './cn.js';
 export * from './csrf.js';
 export * from './debounce.js';
-export * from './gallery.js';
-export * from './gutter.js';
+// Gallery - explicit exports to avoid ambiguity
+export { parseImageFilename, getImageTitle, getImageDate, searchImages, filterImagesByDateRange, filterImagesByTags, filterImagesByCategory, getAvailableYears, getAvailableCategories } from './gallery.js';
+// Gutter - explicit exports to avoid ambiguity
+export { parseAnchor, getAnchorKey, getUniqueAnchors, getAnchorLabel, getItemsForAnchor, getOrphanItems, findAnchorElement } from './gutter.js';
 export * from './imageProcessor.js';
 export * from './json.js';
 export * from './markdown.js';

package/dist/utils/json.js

@@ -20,7 +20,7 @@ export function safeJsonParse(str, fallback = []) {
   try {
     return JSON.parse(str);
   } catch (e) {
-    console.warn('Failed to parse JSON:', e.message);
+    console.warn('Failed to parse JSON:', e instanceof Error ? e.message : String(e));
     return fallback;
   }
 }