@autumnsgrove/groveengine 0.6.2 → 0.6.4

package/dist/components/admin/composables/useSlashCommands.svelte.js

@@ -3,7 +3,49 @@
  * Manages the slash command menu and execution
  */
 
+/**
+ * @typedef {Object} SlashCommand
+ * @property {string} id
+ * @property {string} label
+ * @property {string} insert
+ * @property {number} [cursorOffset]
+ * @property {boolean} [isSnippet]
+ * @property {boolean} [isAction]
+ * @property {(() => void)} [action]
+ */
+
+/**
+ * @typedef {Object} SlashMenuState
+ * @property {boolean} open
+ * @property {string} query
+ * @property {{x: number, y: number}} position
+ * @property {number} selectedIndex
+ */
+
+/**
+ * @typedef {Object} SlashCommandsOptions
+ * @property {() => HTMLTextAreaElement|null} [getTextareaRef] - Function to get textarea reference
+ * @property {() => string} [getContent] - Function to get content
+ * @property {(content: string) => void} [setContent] - Function to set content
+ * @property {() => Array<{id: string, name: string, content: string}>} [getSnippets] - Function to get user snippets
+ * @property {() => void} [onOpenSnippetsModal] - Callback to open snippets modal
+ */
+
+/**
+ * @typedef {Object} SlashCommandsManager
+ * @property {SlashMenuState} menu
+ * @property {boolean} isOpen
+ * @property {() => SlashCommand[]} getAllCommands
+ * @property {() => SlashCommand[]} getFilteredCommands
+ * @property {() => void} open
+ * @property {() => void} close
+ * @property {(direction: 'up' | 'down') => void} navigate
+ * @property {(index: number) => void} execute
+ * @property {(key: string, cursorPos: number, content: string) => boolean} shouldTrigger
+ */
+
 // Base slash commands definition
+/** @type {SlashCommand[]} */
 export const baseSlashCommands = [
   { id: "heading1", label: "Heading 1", insert: "# " },
   { id: "heading2", label: "Heading 2", insert: "## " },
@@ -25,13 +67,8 @@ export const baseSlashCommands = [
 
 /**
  * Creates a slash commands manager with Svelte 5 runes
- * @param {object} options - Configuration options
- * @param {Function} options.getTextareaRef - Function to get textarea reference
- * @param {Function} options.getContent - Function to get content
- * @param {Function} options.setContent - Function to set content
- * @param {Function} options.getSnippets - Function to get user snippets
- * @param {Function} options.onOpenSnippetsModal - Callback to open snippets modal
- * @returns {object} Slash commands state and controls
+ * @param {SlashCommandsOptions} options - Configuration options
+ * @returns {SlashCommandsManager} Slash commands state and controls
  */
 export function useSlashCommands(options = {}) {
   const {
@@ -50,8 +87,10 @@ export function useSlashCommands(options = {}) {
   });
 
   // Build full command list including snippets
+  /** @returns {SlashCommand[]} */
   function getAllCommands() {
     const snippets = getSnippets ? getSnippets() : [];
+    /** @type {SlashCommand[]} */
     const snippetCommands = snippets.map((s) => ({
       id: s.id,
       label: `> ${s.name}`,
@@ -59,6 +98,7 @@ export function useSlashCommands(options = {}) {
       isSnippet: true,
     }));
 
+    /** @type {SlashCommand} */
     const newSnippetCommand = {
       id: "newSnippet",
       label: "Create New Snippet...",
@@ -88,6 +128,7 @@ export function useSlashCommands(options = {}) {
     menu.open = false;
   }
 
+  /** @param {'up' | 'down'} direction */
   function navigate(direction) {
     const filtered = getFilteredCommands();
     const count = filtered.length;
@@ -100,13 +141,16 @@ export function useSlashCommands(options = {}) {
     }
   }
 
+  /** @param {number} index */
   function execute(index) {
     const filtered = getFilteredCommands();
     const cmd = filtered[index];
     if (!cmd) return;
 
-    const textareaRef = getTextareaRef();
-    const content = getContent();
+    const textareaRef = getTextareaRef ? getTextareaRef() : null;
+    const content = getContent ? getContent() : '';
+
+    if (!textareaRef || !setContent) return;
 
     // Handle action commands (like "Create New Snippet...")
     if (cmd.isAction && cmd.action) {
@@ -142,6 +186,11 @@ export function useSlashCommands(options = {}) {
     menu.open = false;
   }
 
+  /**
+   * @param {string} key
+   * @param {number} cursorPos
+   * @param {string} content
+   */
   function shouldTrigger(key, cursorPos, content) {
     if (key !== "/" || menu.open) return false;
     // Only trigger at start of line or after whitespace

package/dist/components/admin/composables/useSnippets.svelte.d.ts

@@ -1,5 +1,54 @@
+/**
+ * @typedef {Object} Snippet
+ * @property {string} id
+ * @property {string} name
+ * @property {string} content
+ * @property {string|null} trigger
+ * @property {string} [createdAt]
+ */
+/**
+ * @typedef {Object} SnippetModal
+ * @property {boolean} open
+ * @property {string|null} editingId
+ * @property {string} name
+ * @property {string} content
+ * @property {string} trigger
+ */
+/**
+ * @typedef {Object} SnippetsManager
+ * @property {Snippet[]} snippets
+ * @property {SnippetModal} modal
+ * @property {() => void} load
+ * @property {(editId?: string|null) => void} openModal
+ * @property {() => void} closeModal
+ * @property {() => void} saveSnippet
+ * @property {(id: string) => void} deleteSnippet
+ */
 /**
  * Creates a snippets manager with Svelte 5 runes
- * @returns {object} Snippets state and controls
+ * @returns {SnippetsManager} Snippets state and controls
  */
-export function useSnippets(): object;
+export function useSnippets(): SnippetsManager;
+export type Snippet = {
+    id: string;
+    name: string;
+    content: string;
+    trigger: string | null;
+    createdAt?: string | undefined;
+};
+export type SnippetModal = {
+    open: boolean;
+    editingId: string | null;
+    name: string;
+    content: string;
+    trigger: string;
+};
+export type SnippetsManager = {
+    snippets: Snippet[];
+    modal: SnippetModal;
+    load: () => void;
+    openModal: (editId?: string | null) => void;
+    closeModal: () => void;
+    saveSnippet: () => void;
+    deleteSnippet: (id: string) => void;
+};

package/dist/components/admin/composables/useSnippets.svelte.js

@@ -5,20 +5,50 @@
 
 const SNIPPETS_STORAGE_KEY = "grove-editor-snippets";
 
+/**
+ * @typedef {Object} Snippet
+ * @property {string} id
+ * @property {string} name
+ * @property {string} content
+ * @property {string|null} trigger
+ * @property {string} [createdAt]
+ */
+
+/**
+ * @typedef {Object} SnippetModal
+ * @property {boolean} open
+ * @property {string|null} editingId
+ * @property {string} name
+ * @property {string} content
+ * @property {string} trigger
+ */
+
+/**
+ * @typedef {Object} SnippetsManager
+ * @property {Snippet[]} snippets
+ * @property {SnippetModal} modal
+ * @property {() => void} load
+ * @property {(editId?: string|null) => void} openModal
+ * @property {() => void} closeModal
+ * @property {() => void} saveSnippet
+ * @property {(id: string) => void} deleteSnippet
+ */
+
 /**
  * Creates a snippets manager with Svelte 5 runes
- * @returns {object} Snippets state and controls
+ * @returns {SnippetsManager} Snippets state and controls
  */
 export function useSnippets() {
+  /** @type {Snippet[]} */
   let snippets = $state([]);
 
-  let modal = $state({
+  let modal = $state(/** @type {SnippetModal} */ ({
     open: false,
     editingId: null,
     name: "",
     content: "",
     trigger: "",
-  });
+  }));
 
   function load() {
     try {
@@ -39,6 +69,7 @@ export function useSnippets() {
     }
   }
 
+  /** @param {string | null} [editId] */
   function openModal(editId = null) {
     if (editId) {
       const snippet = snippets.find((s) => s.id === editId);
@@ -96,6 +127,7 @@ export function useSnippets() {
     closeModal();
   }
 
+  /** @param {string} id */
   function deleteSnippet(id) {
     if (confirm("Delete this snippet?")) {
       snippets = snippets.filter((s) => s.id !== id);

package/dist/components/admin/composables/useWritingSession.svelte.d.ts

@@ -2,12 +2,70 @@
  * Writing Session Composable
  * Manages campfire sessions and writing goals
  */
+/**
+ * @typedef {Object} CampfireState
+ * @property {boolean} active
+ * @property {number|null} startTime
+ * @property {number} targetMinutes
+ * @property {number} startWordCount
+ */
+/**
+ * @typedef {Object} GoalState
+ * @property {boolean} enabled
+ * @property {number} targetWords
+ * @property {number} sessionWords
+ */
+/**
+ * @typedef {Object} WritingSessionOptions
+ * @property {() => number} [getWordCount] - Function to get current word count
+ */
+/**
+ * @typedef {Object} WritingSessionManager
+ * @property {CampfireState} campfire
+ * @property {GoalState} goal
+ * @property {boolean} isCampfireActive
+ * @property {boolean} isGoalEnabled
+ * @property {() => string} getCampfireElapsed
+ * @property {(currentWordCount: number) => number} getGoalProgress
+ * @property {(currentWordCount: number) => number} getCampfireWords
+ * @property {() => void} startCampfire
+ * @property {() => void} endCampfire
+ * @property {() => void} promptWritingGoal
+ * @property {() => void} disableGoal
+ */
 /**
  * Creates a writing session manager with Svelte 5 runes
- * @param {object} options - Configuration options
- * @param {Function} options.getWordCount - Function to get current word count
- * @returns {object} Session state and controls
+ * @param {WritingSessionOptions} options - Configuration options
+ * @returns {WritingSessionManager} Session state and controls
  */
-export function useWritingSession(options?: {
-    getWordCount: Function;
-}): object;
+export function useWritingSession(options?: WritingSessionOptions): WritingSessionManager;
+export type CampfireState = {
+    active: boolean;
+    startTime: number | null;
+    targetMinutes: number;
+    startWordCount: number;
+};
+export type GoalState = {
+    enabled: boolean;
+    targetWords: number;
+    sessionWords: number;
+};
+export type WritingSessionOptions = {
+    /**
+     * - Function to get current word count
+     */
+    getWordCount?: (() => number) | undefined;
+};
+export type WritingSessionManager = {
+    campfire: CampfireState;
+    goal: GoalState;
+    isCampfireActive: boolean;
+    isGoalEnabled: boolean;
+    getCampfireElapsed: () => string;
+    getGoalProgress: (currentWordCount: number) => number;
+    getCampfireWords: (currentWordCount: number) => number;
+    startCampfire: () => void;
+    endCampfire: () => void;
+    promptWritingGoal: () => void;
+    disableGoal: () => void;
+};

package/dist/components/admin/composables/useWritingSession.svelte.js

@@ -3,19 +3,54 @@
  * Manages campfire sessions and writing goals
  */
 
+/**
+ * @typedef {Object} CampfireState
+ * @property {boolean} active
+ * @property {number|null} startTime
+ * @property {number} targetMinutes
+ * @property {number} startWordCount
+ */
+
+/**
+ * @typedef {Object} GoalState
+ * @property {boolean} enabled
+ * @property {number} targetWords
+ * @property {number} sessionWords
+ */
+
+/**
+ * @typedef {Object} WritingSessionOptions
+ * @property {() => number} [getWordCount] - Function to get current word count
+ */
+
+/**
+ * @typedef {Object} WritingSessionManager
+ * @property {CampfireState} campfire
+ * @property {GoalState} goal
+ * @property {boolean} isCampfireActive
+ * @property {boolean} isGoalEnabled
+ * @property {() => string} getCampfireElapsed
+ * @property {(currentWordCount: number) => number} getGoalProgress
+ * @property {(currentWordCount: number) => number} getCampfireWords
+ * @property {() => void} startCampfire
+ * @property {() => void} endCampfire
+ * @property {() => void} promptWritingGoal
+ * @property {() => void} disableGoal
+ */
+
 /**
  * Creates a writing session manager with Svelte 5 runes
- * @param {object} options - Configuration options
- * @param {Function} options.getWordCount - Function to get current word count
- * @returns {object} Session state and controls
+ * @param {WritingSessionOptions} options - Configuration options
+ * @returns {WritingSessionManager} Session state and controls
  */
-export function useWritingSession(options = {}) {
+export function useWritingSession(options = /** @type {WritingSessionOptions} */ ({})) {
   const { getWordCount } = options;
 
   // Campfire session state
   let campfire = $state({
     active: false,
-    startTime: null,
+    /** @type {number | null} */
+    startTime: /** @type {number | null} */ (null),
     targetMinutes: 25,
     startWordCount: 0,
   });
@@ -38,6 +73,7 @@ export function useWritingSession(options = {}) {
   }
 
   // Writing goal progress
+  /** @param {number} currentWordCount */
   function getGoalProgress(currentWordCount) {
     if (!goal.enabled) return 0;
     const wordsWritten = currentWordCount - goal.sessionWords;
@@ -45,6 +81,7 @@ export function useWritingSession(options = {}) {
   }
 
   // Words written in campfire session
+  /** @param {number} currentWordCount */
   function getCampfireWords(currentWordCount) {
     return currentWordCount - campfire.startWordCount;
   }

package/dist/components/custom/ContentWithGutter.svelte

@@ -1,4 +1,4 @@
-<script>
+<script lang="ts">
 	import { tick, untrack, onMount } from 'svelte';
 	import { browser } from '$app/environment';
 	import TableOfContents from './TableOfContents.svelte';
@@ -11,8 +11,10 @@
 		getItemsForAnchor,
 		getOrphanItems,
 		findAnchorElement,
-		parseAnchor
-	} from '../../utils/gutter.js';
+		parseAnchor,
+		type GutterItem as GutterItemType,
+		type Header
+	} from '../../utils/gutter';
 	import '../../styles/content.css';
 
 	// Constants for positioning calculations
@@ -23,23 +25,29 @@
 
 	let {
 		content = '',
-		gutterContent = [],
-		headers = [],
+		gutterContent = [] as GutterItemType[],
+		headers = [] as Header[],
 		showTableOfContents = true,
 		children
 	} = $props();
 
 	// References to mobile gutter containers for each anchor
+	/** @type {Record<string, HTMLElement>} */
 	let mobileGutterRefs = $state({});
 
 	// Track content height for overflow detection
+	/** @type {HTMLElement | undefined} */
 	let contentBodyElement = $state();
 	let contentHeight = $state(0);
+	/** @type {string[]} */
 	let overflowingAnchorKeys = $state([]);
 
 	// Gutter positioning state
+	/** @type {HTMLElement | undefined} */
 	let gutterElement = $state();
+	/** @type {Record<string, number>} */
 	let itemPositions = $state({});
+	/** @type {Record<string, HTMLElement>} */
 	let anchorGroupElements = $state({});
 
 	// Compute unique anchors once as a derived value (performance optimization)
@@ -52,17 +60,27 @@
 	let hasGutters = $derived(hasLeftGutter || hasRightGutter);
 	let hasOverflow = $derived(overflowingAnchorKeys.length > 0);
 
-	// Helper to get anchor key with headers context
+	/**
+	 * Helper to get anchor key with headers context
+	 * @param {string} anchor
+	 */
 	function getKey(anchor) {
 		return getAnchorKey(anchor, headers);
 	}
 
-	// Get items for a specific anchor
+	/**
+	 * Get items for a specific anchor
+	 * @param {string} anchor
+	 */
 	function getItems(anchor) {
 		return getItemsForAnchor(gutterContent, anchor);
 	}
 
-	// Generate unique key for a gutter item
+	/**
+	 * Generate unique key for a gutter item
+	 * @param {GutterItem} item
+	 * @param {number} index
+	 */
 	function getItemKey(item, index) {
 		// Combine item properties to create a unique identifier
 		const parts = [
@@ -88,12 +106,13 @@
 		const gutterRect = gutterElement.getBoundingClientRect();
 
 		let lastBottom = 0; // Track the bottom edge of the last positioned item
+		/** @type {string[]} */
 		const newOverflowingAnchors = [];
 		const newPositions = { ...itemPositions };
 
 		// Sort anchors by their position in the document
 		const anchorPositions = uniqueAnchors.map(anchor => {
-			const el = findAnchorElement(anchor, contentBodyElement, headers);
+			const el = findAnchorElement(anchor, contentBodyElement ?? null, headers);
 			if (!el && import.meta.env.DEV) {
 				console.warn(`Anchor element not found for: ${anchor}`);
 			}
@@ -149,6 +168,7 @@
 
 	// Setup resize listener on mount with proper cleanup
 	onMount(() => {
+		/** @type {ReturnType<typeof setTimeout> | undefined} */
 		let resizeTimeoutId;
 		const handleResize = () => {
 			clearTimeout(resizeTimeoutId);
@@ -166,8 +186,9 @@
 
 	// Setup copy button functionality for code blocks
 	onMount(() => {
+		/** @param {Event} event */
 		const handleCopyClick = async (event) => {
-			const button = event.currentTarget;
+			const button = /** @type {HTMLElement} */ (event.currentTarget);
 			const codeText = button.getAttribute('data-code');
 
 			if (!codeText) return;
@@ -182,21 +203,21 @@
 
 				// Update button text and style to show success
 				const copyText = button.querySelector('.copy-text');
-				const originalText = copyText.textContent;
-				copyText.textContent = 'Copied!';
+				const originalText = copyText?.textContent || 'Copy';
+				if (copyText) copyText.textContent = 'Copied!';
 				button.classList.add('copied');
 
 				// Reset after 2 seconds
 				setTimeout(() => {
-					copyText.textContent = originalText;
+					if (copyText) copyText.textContent = originalText;
 					button.classList.remove('copied');
 				}, 2000);
 			} catch (err) {
 				console.error('Failed to copy code:', err);
 				const copyText = button.querySelector('.copy-text');
-				copyText.textContent = 'Failed';
+				if (copyText) copyText.textContent = 'Failed';
 				setTimeout(() => {
-					copyText.textContent = 'Copy';
+					if (copyText) copyText.textContent = 'Copy';
 				}, 2000);
 			}
 		};
@@ -230,6 +251,7 @@
 	// Add IDs to headers and position mobile gutter items
 	$effect(() => {
 		// Track moved elements for cleanup
+		/** @type {Array<{ element: HTMLElement, originalParent: HTMLElement | null, originalNextSibling: Node | null }>} */
 		const movedElements = [];
 
 		untrack(() => {
@@ -239,8 +261,8 @@
 			if (headers && headers.length > 0) {
 				const headerElements = contentBodyElement.querySelectorAll('h1, h2, h3, h4, h5, h6');
 				headerElements.forEach((el) => {
-					const text = el.textContent.trim();
-					const matchingHeader = headers.find(h => h.text === text);
+					const text = el.textContent?.trim() || '';
+					const matchingHeader = headers.find(/** @param {Header} h */ (h) => h.text === text);
 					if (matchingHeader) {
 						el.id = matchingHeader.id;
 					}
@@ -284,6 +306,7 @@
 	$effect(() => {
 		if (contentBodyElement) {
 			const updateHeight = () => {
+				if (!contentBodyElement) return;
 				// Get the bottom of content-body relative to the article
 				const rect = contentBodyElement.getBoundingClientRect();
 				const articleRect = contentBodyElement.closest('.content-article')?.getBoundingClientRect();
@@ -321,6 +344,10 @@
 	}
 
 	// Inject reference markers into content HTML for overflowing items
+	/**
+	 * @param {string} html
+	 * @param {string[]} overflowKeys
+	 */
 	function injectReferenceMarkers(html, overflowKeys) {
 		if (!overflowKeys || overflowKeys.length === 0 || typeof window === 'undefined') {
 			return html;
@@ -343,7 +370,7 @@
 					// Find header by text content
 					const allHeaders = doc.body.querySelectorAll('h1, h2, h3, h4, h5, h6');
 					for (const h of allHeaders) {
-						if (h.textContent.trim() === headerText) {
+						if (h.textContent?.trim() === headerText) {
 							targetEl = h;
 							break;
 						}
@@ -352,9 +379,11 @@
 				}
 				case 'paragraph': {
 					const paragraphs = doc.body.querySelectorAll(':scope > p');
-					const index = parsed.value - 1;
-					if (index >= 0 && index < paragraphs.length) {
-						targetEl = paragraphs[index];
+					if (parsed.value != null && typeof parsed.value === 'number') {
+						const index = parsed.value - 1;
+						if (index >= 0 && index < paragraphs.length) {
+							targetEl = paragraphs[index];
+						}
 					}
 					break;
 				}
@@ -372,7 +401,7 @@
 
 				const link = doc.createElement('a');
 				link.href = `#overflow-${refNum}`;
-				link.textContent = refNum;
+				link.textContent = String(refNum);
 				link.title = `See gutter content for: ${getAnchorLabel(anchor)}`;
 
 				marker.appendChild(link);
@@ -399,6 +428,7 @@
 	let processedContent = $derived(injectReferenceMarkers(content, overflowingAnchorKeys));
 
 	// Sanitize HTML content to prevent XSS attacks (browser-only for SSR compatibility)
+	/** @type {any} */
 	let DOMPurify = $state(null);
 
 	// Load DOMPurify only in browser (avoids jsdom dependency for SSR)
@@ -410,7 +440,7 @@
 	});
 
 	let sanitizedContent = $derived(
-		DOMPurify
+		DOMPurify && typeof DOMPurify.sanitize === 'function'
 			? DOMPurify.sanitize(processedContent, {
 					ALLOWED_TAGS: [
 						// Headings

package/dist/components/custom/ContentWithGutter.svelte.d.ts

@@ -1,19 +1,11 @@
-export default ContentWithGutter;
-type ContentWithGutter = {
-    $on?(type: string, callback: (e: any) => void): () => void;
-    $set?(props: Partial<$$ComponentProps>): void;
-};
+import { type GutterItem as GutterItemType, type Header } from '../../utils/gutter';
+import '../../styles/content.css';
 declare const ContentWithGutter: import("svelte").Component<{
     content?: string;
-    gutterContent?: any[];
-    headers?: any[];
+    gutterContent?: GutterItemType[];
+    headers?: Header[];
     showTableOfContents?: boolean;
     children: any;
 }, {}, "">;
-type $$ComponentProps = {
-    content?: string;
-    gutterContent?: any[];
-    headers?: any[];
-    showTableOfContents?: boolean;
-    children: any;
-};
+type ContentWithGutter = ReturnType<typeof ContentWithGutter>;
+export default ContentWithGutter;

package/dist/components/custom/GutterItem.svelte

@@ -1,7 +1,7 @@
 <script>
 	import Lightbox from '../../ui/components/gallery/Lightbox.svelte';
 	import ImageGallery from '../../ui/components/gallery/ImageGallery.svelte';
-	import { sanitizeHTML } from '../../utils/sanitize.js';
+	import { sanitizeHTML } from '../../utils/sanitize';
 
 	let { item = {} } = $props();