@autumnsgrove/groveengine 0.6.2 → 0.6.3

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

@@ -3,13 +3,50 @@
  * Manages the command palette (Cmd+K) functionality
  */
 
+/**
+ * @typedef {Object} PaletteAction
+ * @property {string} id
+ * @property {string} label
+ * @property {string} shortcut
+ * @property {() => void} action
+ * @property {string} [themeKey]
+ * @property {boolean} [isTheme]
+ */
+
+/**
+ * @typedef {Object} CommandPaletteState
+ * @property {boolean} open
+ * @property {string} query
+ * @property {number} selectedIndex
+ */
+
+/**
+ * @typedef {Object} CommandPaletteOptions
+ * @property {() => PaletteAction[]} [getActions] - Function to get available actions
+ * @property {() => Record<string, any>} [getThemes] - Function to get available themes
+ * @property {() => string} [getCurrentTheme] - Function to get current theme
+ */
+
+/**
+ * @typedef {Object} CommandPaletteManager
+ * @property {CommandPaletteState} state
+ * @property {boolean} isOpen
+ * @property {string} query
+ * @property {number} selectedIndex
+ * @property {() => PaletteAction[]} getAllCommands
+ * @property {() => PaletteAction[]} getFilteredCommands
+ * @property {() => void} open
+ * @property {() => void} close
+ * @property {() => void} toggle
+ * @property {(direction: 'up' | 'down') => void} navigate
+ * @property {(index: number) => PaletteAction | undefined} execute
+ * @property {(query: string) => void} setQuery
+ */
+
 /**
  * Creates a command palette manager with Svelte 5 runes
- * @param {object} options - Configuration options
- * @param {Function} options.getActions - Function to get available actions
- * @param {Function} options.getThemes - Function to get available themes
- * @param {Function} options.getCurrentTheme - Function to get current theme
- * @returns {object} Command palette state and controls
+ * @param {CommandPaletteOptions} options - Configuration options
+ * @returns {CommandPaletteManager} Command palette state and controls
  */
 export function useCommandPalette(options = {}) {
   const { getActions, getThemes, getCurrentTheme } = options;
@@ -66,6 +103,7 @@ export function useCommandPalette(options = {}) {
     }
   }
 
+  /** @param {'up' | 'down'} direction */
   function navigate(direction) {
     const filtered = getFilteredCommands();
     const count = filtered.length;
@@ -78,6 +116,7 @@ export function useCommandPalette(options = {}) {
     }
   }
 
+  /** @param {number} index */
   function execute(index) {
     const filtered = getFilteredCommands();
     const cmd = filtered[index];
@@ -88,6 +127,7 @@ export function useCommandPalette(options = {}) {
     return cmd;
   }
 
+  /** @param {string} query */
   function setQuery(query) {
     state.query = query;
     state.selectedIndex = 0;

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

@@ -1,17 +1,79 @@
+/**
+ * @typedef {Object} StoredDraft
+ * @property {string} content
+ * @property {string} savedAt
+ */
+/**
+ * @typedef {Object} DraftManagerOptions
+ * @property {string|null} [draftKey] - Unique key for localStorage
+ * @property {() => string} [getContent] - Function to get current content
+ * @property {(content: string) => void} [setContent] - Function to set content
+ * @property {(draft: StoredDraft) => void} [onDraftRestored] - Callback when draft is restored
+ * @property {boolean} [readonly] - Whether editor is readonly
+ */
+/**
+ * @typedef {Object} DraftManager
+ * @property {boolean} hasDraft
+ * @property {boolean} draftRestorePrompt
+ * @property {StoredDraft|null} storedDraft
+ * @property {string} lastSavedContent
+ * @property {(initialContent: string) => void} init
+ * @property {(content: string) => void} scheduleSave
+ * @property {() => void} saveDraft
+ * @property {() => void} clearDraft
+ * @property {() => void} restoreDraft
+ * @property {() => void} discardDraft
+ * @property {() => {hasDraft: boolean, storedDraft: StoredDraft|null}} getStatus
+ * @property {(content: string) => boolean} hasUnsavedChanges
+ * @property {() => void} cleanup
+ */
 /**
  * Creates a draft manager with Svelte 5 runes
- * @param {object} options - Configuration options
- * @param {string} options.draftKey - Unique key for localStorage
- * @param {Function} options.getContent - Function to get current content
- * @param {Function} options.setContent - Function to set content
- * @param {Function} options.onDraftRestored - Callback when draft is restored
- * @param {boolean} options.readonly - Whether editor is readonly
- * @returns {object} Draft state and controls
+ * @param {DraftManagerOptions} options - Configuration options
+ * @returns {DraftManager} Draft state and controls
  */
-export function useDraftManager(options?: {
-    draftKey: string;
-    getContent: Function;
-    setContent: Function;
-    onDraftRestored: Function;
-    readonly: boolean;
-}): object;
+export function useDraftManager(options?: DraftManagerOptions): DraftManager;
+export type StoredDraft = {
+    content: string;
+    savedAt: string;
+};
+export type DraftManagerOptions = {
+    /**
+     * - Unique key for localStorage
+     */
+    draftKey?: string | null | undefined;
+    /**
+     * - Function to get current content
+     */
+    getContent?: (() => string) | undefined;
+    /**
+     * - Function to set content
+     */
+    setContent?: ((content: string) => void) | undefined;
+    /**
+     * - Callback when draft is restored
+     */
+    onDraftRestored?: ((draft: StoredDraft) => void) | undefined;
+    /**
+     * - Whether editor is readonly
+     */
+    readonly?: boolean | undefined;
+};
+export type DraftManager = {
+    hasDraft: boolean;
+    draftRestorePrompt: boolean;
+    storedDraft: StoredDraft | null;
+    lastSavedContent: string;
+    init: (initialContent: string) => void;
+    scheduleSave: (content: string) => void;
+    saveDraft: () => void;
+    clearDraft: () => void;
+    restoreDraft: () => void;
+    discardDraft: () => void;
+    getStatus: () => {
+        hasDraft: boolean;
+        storedDraft: StoredDraft | null;
+    };
+    hasUnsavedChanges: (content: string) => boolean;
+    cleanup: () => void;
+};

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

@@ -5,27 +5,56 @@
 
 const AUTO_SAVE_DELAY = 2000; // 2 seconds
 
+/**
+ * @typedef {Object} StoredDraft
+ * @property {string} content
+ * @property {string} savedAt
+ */
+
+/**
+ * @typedef {Object} DraftManagerOptions
+ * @property {string|null} [draftKey] - Unique key for localStorage
+ * @property {() => string} [getContent] - Function to get current content
+ * @property {(content: string) => void} [setContent] - Function to set content
+ * @property {(draft: StoredDraft) => void} [onDraftRestored] - Callback when draft is restored
+ * @property {boolean} [readonly] - Whether editor is readonly
+ */
+
+/**
+ * @typedef {Object} DraftManager
+ * @property {boolean} hasDraft
+ * @property {boolean} draftRestorePrompt
+ * @property {StoredDraft|null} storedDraft
+ * @property {string} lastSavedContent
+ * @property {(initialContent: string) => void} init
+ * @property {(content: string) => void} scheduleSave
+ * @property {() => void} saveDraft
+ * @property {() => void} clearDraft
+ * @property {() => void} restoreDraft
+ * @property {() => void} discardDraft
+ * @property {() => {hasDraft: boolean, storedDraft: StoredDraft|null}} getStatus
+ * @property {(content: string) => boolean} hasUnsavedChanges
+ * @property {() => void} cleanup
+ */
+
 /**
  * Creates a draft manager with Svelte 5 runes
- * @param {object} options - Configuration options
- * @param {string} options.draftKey - Unique key for localStorage
- * @param {Function} options.getContent - Function to get current content
- * @param {Function} options.setContent - Function to set content
- * @param {Function} options.onDraftRestored - Callback when draft is restored
- * @param {boolean} options.readonly - Whether editor is readonly
- * @returns {object} Draft state and controls
+ * @param {DraftManagerOptions} options - Configuration options
+ * @returns {DraftManager} Draft state and controls
  */
-export function useDraftManager(options = {}) {
+export function useDraftManager(options = /** @type {DraftManagerOptions} */ ({})) {
   const { draftKey, getContent, setContent, onDraftRestored, readonly } = options;
 
   let lastSavedContent = $state("");
+  /** @type {ReturnType<typeof setTimeout> | null} */
   let draftSaveTimer = $state(null);
   let hasDraft = $state(false);
   let draftRestorePrompt = $state(false);
+  /** @type {StoredDraft | null} */
   let storedDraft = $state(null);
 
   function saveDraft() {
-    if (!draftKey || readonly) return;
+    if (!draftKey || readonly || !getContent) return;
 
     const content = getContent();
     try {
@@ -81,9 +110,12 @@ export function useDraftManager(options = {}) {
 
   function discardDraft() {
     clearDraft();
-    lastSavedContent = getContent();
+    if (getContent) {
+      lastSavedContent = getContent();
+    }
   }
 
+  /** @param {string} content */
   function scheduleSave(content) {
     if (!draftKey || readonly) return;
 
@@ -101,6 +133,7 @@ export function useDraftManager(options = {}) {
     }, AUTO_SAVE_DELAY);
   }
 
+  /** @param {string} initialContent */
   function init(initialContent) {
     // Check for existing draft on mount
     if (draftKey) {
@@ -124,6 +157,7 @@ export function useDraftManager(options = {}) {
     return { hasDraft, storedDraft };
   }
 
+  /** @param {string} content */
   function hasUnsavedChanges(content) {
     return content !== lastSavedContent;
   }

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

@@ -1,8 +1,149 @@
+/**
+ * @typedef {Object} Theme
+ * @property {string} name
+ * @property {string} label
+ * @property {string} desc
+ * @property {string} accent
+ * @property {string} accentDim
+ * @property {string} accentBright
+ * @property {string} accentGlow
+ * @property {string} bg
+ * @property {string} bgSecondary
+ * @property {string} bgTertiary
+ * @property {string} border
+ * @property {string} borderAccent
+ * @property {string} text
+ * @property {string} textDim
+ * @property {string} statusBg
+ * @property {string} statusBorder
+ */
+/**
+ * @typedef {Object} EditorThemeManager
+ * @property {string} currentTheme
+ * @property {Record<string, Theme>} themes
+ * @property {() => void} loadTheme
+ * @property {(themeName: string) => void} setTheme
+ */
 /**
  * Creates an editor theme manager with Svelte 5 runes
- * @returns {object} Theme state and controls
+ * @returns {EditorThemeManager} Theme state and controls
  */
-export function useEditorTheme(): object;
+/** @typedef {keyof typeof themes} ThemeName */
+export function useEditorTheme(): {
+    readonly currentTheme: "grove" | "amber" | "matrix" | "dracula" | "nord" | "rose";
+    themes: {
+        grove: {
+            name: string;
+            label: string;
+            desc: string;
+            accent: string;
+            accentDim: string;
+            accentBright: string;
+            accentGlow: string;
+            bg: string;
+            bgSecondary: string;
+            bgTertiary: string;
+            border: string;
+            borderAccent: string;
+            text: string;
+            textDim: string;
+            statusBg: string;
+            statusBorder: string;
+        };
+        amber: {
+            name: string;
+            label: string;
+            desc: string;
+            accent: string;
+            accentDim: string;
+            accentBright: string;
+            accentGlow: string;
+            bg: string;
+            bgSecondary: string;
+            bgTertiary: string;
+            border: string;
+            borderAccent: string;
+            text: string;
+            textDim: string;
+            statusBg: string;
+            statusBorder: string;
+        };
+        matrix: {
+            name: string;
+            label: string;
+            desc: string;
+            accent: string;
+            accentDim: string;
+            accentBright: string;
+            accentGlow: string;
+            bg: string;
+            bgSecondary: string;
+            bgTertiary: string;
+            border: string;
+            borderAccent: string;
+            text: string;
+            textDim: string;
+            statusBg: string;
+            statusBorder: string;
+        };
+        dracula: {
+            name: string;
+            label: string;
+            desc: string;
+            accent: string;
+            accentDim: string;
+            accentBright: string;
+            accentGlow: string;
+            bg: string;
+            bgSecondary: string;
+            bgTertiary: string;
+            border: string;
+            borderAccent: string;
+            text: string;
+            textDim: string;
+            statusBg: string;
+            statusBorder: string;
+        };
+        nord: {
+            name: string;
+            label: string;
+            desc: string;
+            accent: string;
+            accentDim: string;
+            accentBright: string;
+            accentGlow: string;
+            bg: string;
+            bgSecondary: string;
+            bgTertiary: string;
+            border: string;
+            borderAccent: string;
+            text: string;
+            textDim: string;
+            statusBg: string;
+            statusBorder: string;
+        };
+        rose: {
+            name: string;
+            label: string;
+            desc: string;
+            accent: string;
+            accentDim: string;
+            accentBright: string;
+            accentGlow: string;
+            bg: string;
+            bgSecondary: string;
+            bgTertiary: string;
+            border: string;
+            borderAccent: string;
+            text: string;
+            textDim: string;
+            statusBg: string;
+            statusBorder: string;
+        };
+    };
+    loadTheme: () => void;
+    setTheme: (themeName: string) => void;
+};
 export namespace themes {
     namespace grove {
         let name: string;
@@ -193,3 +334,28 @@ export namespace themes {
         export { statusBorder_5 as statusBorder };
     }
 }
+export type Theme = {
+    name: string;
+    label: string;
+    desc: string;
+    accent: string;
+    accentDim: string;
+    accentBright: string;
+    accentGlow: string;
+    bg: string;
+    bgSecondary: string;
+    bgTertiary: string;
+    border: string;
+    borderAccent: string;
+    text: string;
+    textDim: string;
+    statusBg: string;
+    statusBorder: string;
+};
+export type EditorThemeManager = {
+    currentTheme: string;
+    themes: Record<string, Theme>;
+    loadTheme: () => void;
+    setTheme: (themeName: string) => void;
+};
+export type ThemeName = keyof typeof themes;

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

@@ -117,15 +117,46 @@ export const themes = {
   },
 };
 
+/**
+ * @typedef {Object} Theme
+ * @property {string} name
+ * @property {string} label
+ * @property {string} desc
+ * @property {string} accent
+ * @property {string} accentDim
+ * @property {string} accentBright
+ * @property {string} accentGlow
+ * @property {string} bg
+ * @property {string} bgSecondary
+ * @property {string} bgTertiary
+ * @property {string} border
+ * @property {string} borderAccent
+ * @property {string} text
+ * @property {string} textDim
+ * @property {string} statusBg
+ * @property {string} statusBorder
+ */
+
+/**
+ * @typedef {Object} EditorThemeManager
+ * @property {string} currentTheme
+ * @property {Record<string, Theme>} themes
+ * @property {() => void} loadTheme
+ * @property {(themeName: string) => void} setTheme
+ */
+
 /**
  * Creates an editor theme manager with Svelte 5 runes
- * @returns {object} Theme state and controls
+ * @returns {EditorThemeManager} Theme state and controls
  */
+/** @typedef {keyof typeof themes} ThemeName */
+
 export function useEditorTheme() {
-  let currentTheme = $state("grove");
+  let currentTheme = $state(/** @type {ThemeName} */ ("grove"));
 
+  /** @param {string} themeName */
   function applyTheme(themeName) {
-    const theme = themes[themeName];
+    const theme = themes[/** @type {ThemeName} */ (themeName)];
     if (!theme) return;
 
     const root = document.documentElement;
@@ -147,8 +178,8 @@ export function useEditorTheme() {
   function loadTheme() {
     try {
       const stored = localStorage.getItem(THEME_STORAGE_KEY);
-      if (stored && themes[stored]) {
-        currentTheme = stored;
+      if (stored && themes[/** @type {ThemeName} */ (stored)]) {
+        currentTheme = /** @type {ThemeName} */ (stored);
         applyTheme(stored);
       }
     } catch (e) {
@@ -156,6 +187,7 @@ export function useEditorTheme() {
     }
   }
 
+  /** @param {string} themeName */
   function saveTheme(themeName) {
     try {
       localStorage.setItem(THEME_STORAGE_KEY, themeName);
@@ -164,9 +196,10 @@ export function useEditorTheme() {
     }
   }
 
+  /** @param {string} themeName */
   function setTheme(themeName) {
-    if (!themes[themeName]) return;
-    currentTheme = themeName;
+    if (!themes[/** @type {ThemeName} */ (themeName)]) return;
+    currentTheme = /** @type {ThemeName} */ (themeName);
     applyTheme(themeName);
     saveTheme(themeName);
   }

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

@@ -1,32 +1,104 @@
 /**
  * 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?: {
-    getTextareaRef: Function;
-    getContent: Function;
-    setContent: Function;
-    getSnippets: Function;
-    onOpenSnippetsModal: Function;
-}): object;
+export function useSlashCommands(options?: SlashCommandsOptions): SlashCommandsManager;
 /**
  * Slash Commands Composable
  * Manages the slash command menu and execution
  */
-export const baseSlashCommands: ({
-    id: string;
-    label: string;
-    insert: string;
-    cursorOffset?: undefined;
-} | {
+/**
+ * @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
+ */
+/** @type {SlashCommand[]} */
+export const baseSlashCommands: SlashCommand[];
+export type SlashCommand = {
     id: string;
     label: string;
     insert: string;
-    cursorOffset: number;
-})[];
+    cursorOffset?: number | undefined;
+    isSnippet?: boolean | undefined;
+    isAction?: boolean | undefined;
+    action?: (() => void) | undefined;
+};
+export type SlashMenuState = {
+    open: boolean;
+    query: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    selectedIndex: number;
+};
+export type SlashCommandsOptions = {
+    /**
+     * - Function to get textarea reference
+     */
+    getTextareaRef?: (() => HTMLTextAreaElement | null) | undefined;
+    /**
+     * - Function to get content
+     */
+    getContent?: (() => string) | undefined;
+    /**
+     * - Function to set content
+     */
+    setContent?: ((content: string) => void) | undefined;
+    /**
+     * - Function to get user snippets
+     */
+    getSnippets?: (() => Array<{
+        id: string;
+        name: string;
+        content: string;
+    }>) | undefined;
+    /**
+     * - Callback to open snippets modal
+     */
+    onOpenSnippetsModal?: (() => void) | undefined;
+};
+export type SlashCommandsManager = {
+    menu: SlashMenuState;
+    isOpen: boolean;
+    getAllCommands: () => SlashCommand[];
+    getFilteredCommands: () => SlashCommand[];
+    open: () => void;
+    close: () => void;
+    navigate: (direction: "up" | "down") => void;
+    execute: (index: number) => void;
+    shouldTrigger: (key: string, cursorPos: number, content: string) => boolean;
+};