@bobfrankston/msgapidefs 0.1.0

package/README.md

@@ -0,0 +1,132 @@
+# @bobfrankston/msgapidefs
+
+TypeScript definitions for the **msgapi** JavaScript API used in msgview and msger.
+
+## Installation
+
+```bash
+npm install @bobfrankston/msgapidefs
+```
+
+## Usage
+
+### TypeScript
+
+```typescript
+import type { MsgAPI } from '@bobfrankston/msgapidefs';
+import { isMsgAPI, getMsgAPI } from '@bobfrankston/msgapidefs';
+
+// Option 1: Type the global window.msgapi
+declare global {
+    interface Window {
+        msgapi?: MsgAPI;
+    }
+}
+
+// Check if running in msgview/msger
+if (isMsgAPI()) {
+    window.msgapi!.setTitle('My Application');
+    window.msgapi!.saveData('lastOpened', new Date().toISOString());
+}
+
+// Option 2: Use getMsgAPI() for cross-platform compatibility
+const msgapi = getMsgAPI();
+msgapi.saveData('userPrefs', { theme: 'dark' });  // Works in both msgview/msger and browser!
+msgapi.setTitle('My App');  // Only works in msgview/msger, no-op in browser
+```
+
+### JavaScript
+
+```javascript
+import { isMsgAPI, getMsgAPI } from '@bobfrankston/msgapidefs';
+
+const msgapi = getMsgAPI();
+
+// Data persistence (works in both msgview/msger and browser)
+msgapi.saveData('userSettings', { fontSize: 14, theme: 'dark' });
+const settings = msgapi.loadData('userSettings', { fontSize: 12 });
+
+// Window control (msgview/msger only, gracefully degrades in browser)
+if (isMsgAPI()) {
+    msgapi.toggleFullscreen();
+    msgapi.setAlwaysOnTop(true);
+}
+```
+
+## API Reference
+
+### Window Control
+
+- `toggleFullscreen()` - Toggle fullscreen mode
+- `setFullscreen(enabled: boolean)` - Set fullscreen state
+- `minimize()` - Minimize window
+- `maximize()` - Toggle maximize/restore
+- `setSize(width, height)` - Set window size
+- `setPosition(x, y)` - Set window position
+- `setAlwaysOnTop(enabled: boolean)` - Keep window on top
+- `setTitle(title: string)` - Set window title
+- `close(result?)` - Close window with optional result
+
+### Data Persistence
+
+- `saveData(key, value)` - Save data to localStorage
+- `loadData(key, defaultValue?)` - Load data from localStorage
+- `removeData(key)` - Remove data
+- `clearData()` - Clear all msgapi data
+
+### File System (Coming Soon)
+
+- `fs.selectFile(options?)` - Open file picker
+- `fs.selectFiles(options?)` - Open multi-file picker
+- `fs.saveFileAs(content, filename?, options?)` - Save file dialog
+- `fs.selectFolder(options?)` - Folder picker
+- `fs.read(path)` - Read file (requires allowFs flag)
+- `fs.write(path, content)` - Write file (requires allowFs flag)
+- `fs.list(path)` - List directory (requires allowFs flag)
+- `fs.exists(path)` - Check if file exists (requires allowFs flag)
+- `fs.delete(path)` - Delete file (requires allowFs flag)
+
+## Examples
+
+See [samples.html](samples.html) for interactive examples and demos of all API features!
+
+**Test in msgview:**
+```bash
+msgview -url "file:///path/to/node_modules/@bobfrankston/msgapidefs/samples.html"
+```
+
+**Test in msger:**
+```bash
+msger -url "file:///path/to/node_modules/@bobfrankston/msgapidefs/samples.html"
+```
+
+**Test in browser:**
+```bash
+# Open samples.html in your browser to test browser compatibility
+```
+
+The samples demonstrate:
+- Window control (fullscreen, minimize, maximize, resize, position)
+- Data persistence (save/load user preferences, session data, recent files)
+- Presentation mode example
+- Session management
+- And more!
+
+## Browser Compatibility
+
+The `getMsgAPI()` function returns a browser-compatible implementation:
+
+- **Data persistence**: Uses localStorage in both msgview/msger and browser
+- **Window control**: No-op in browser (except `setTitle` updates document.title)
+- **File system**: Not available in browser (`fs` is undefined)
+
+This allows you to write code once that works in both environments!
+
+## Related Packages
+
+- [@bobfrankston/msgview](https://www.npmjs.com/package/@bobfrankston/msgview) - Electron-based message box (slower, works on Pi)
+- [@bobfrankston/msger](https://www.npmjs.com/package/@bobfrankston/msger) - Rust/wry-based message box (fast, lightweight)
+
+## License
+
+ISC

package/msgapidefs.d.ts

@@ -0,0 +1,322 @@
+/**
+ * TypeScript definitions for the msgapi JavaScript API
+ *
+ * This module provides type-safe access to msgapi's window control,
+ * data persistence, and file system features (used by msgview and msger).
+ *
+ * Usage:
+ * ```typescript
+ * import type { MsgAPI } from '@bobfrankston/msgapidefs';
+ *
+ * declare global {
+ *     interface Window {
+ *         msgapi?: MsgAPI;
+ *     }
+ * }
+ *
+ * // Check if running in msgview/msger
+ * if (window.msgapi) {
+ *     window.msgapi.setTitle('My App');
+ * }
+ * ```
+ */
+/**
+ * Result object returned when the window closes
+ */
+export interface MsgResult {
+    /** Button that was clicked */
+    button: string;
+    /** Optional input field value */
+    value?: string;
+    /** Optional form data */
+    form?: Record<string, any>;
+    /** True if window was closed via close button */
+    closed?: boolean;
+    /** True if window was dismissed via Escape key */
+    dismissed?: boolean;
+    /** True if window was closed due to timeout */
+    timeout?: boolean;
+}
+/**
+ * File information returned by file system operations
+ */
+export interface FileInfo {
+    /** File name */
+    name: string;
+    /** Full file path */
+    path: string;
+    /** True if this is a directory */
+    isDir: boolean;
+    /** File size in bytes (0 for directories) */
+    size: number;
+    /** Last modified timestamp (ISO 8601 string) */
+    modified?: string;
+}
+/**
+ * Options for file selection dialogs
+ */
+export interface FileDialogOptions {
+    /** Dialog title */
+    title?: string;
+    /** Default filename for save dialogs */
+    defaultFilename?: string;
+    /** File filters (e.g., [{name: "Text", extensions: ["txt", "md"]}]) */
+    filters?: Array<{
+        name: string;
+        extensions: string[];
+    }>;
+    /** Default directory to open */
+    defaultPath?: string;
+}
+/**
+ * Selected file with content
+ */
+export interface SelectedFile {
+    /** File name */
+    name: string;
+    /** Full file path */
+    path: string;
+    /** File content as string */
+    content: string;
+}
+/**
+ * msgapi JavaScript API
+ *
+ * Available when running inside msgview/msger via window.msgapi
+ */
+export interface MsgAPI {
+    /**
+     * Toggle fullscreen mode on/off
+     * @example
+     * msgapi.toggleFullscreen();
+     */
+    toggleFullscreen(): void;
+    /**
+     * Set fullscreen mode
+     * @param enabled - true to enter fullscreen, false to exit
+     * @example
+     * msgapi.setFullscreen(true);
+     */
+    setFullscreen(enabled: boolean): void;
+    /**
+     * Minimize the window
+     * @example
+     * msgapi.minimize();
+     */
+    minimize(): void;
+    /**
+     * Toggle maximize/restore window
+     * @example
+     * msgapi.maximize();
+     */
+    maximize(): void;
+    /**
+     * Set window size
+     * @param width - Window width in pixels
+     * @param height - Window height in pixels
+     * @example
+     * msgapi.setSize(800, 600);
+     */
+    setSize(width: number, height: number): void;
+    /**
+     * Set window position
+     * @param x - X coordinate in pixels
+     * @param y - Y coordinate in pixels
+     * @example
+     * msgapi.setPosition(100, 100);
+     */
+    setPosition(x: number, y: number): void;
+    /**
+     * Set always-on-top behavior
+     * @param enabled - true to keep window on top
+     * @example
+     * msgapi.setAlwaysOnTop(true);
+     */
+    setAlwaysOnTop(enabled: boolean): void;
+    /**
+     * Set window title
+     * @param title - New window title
+     * @example
+     * msgapi.setTitle("My Application");
+     */
+    setTitle(title: string): void;
+    /**
+     * Close the window
+     * @param result - Optional result to return to parent process
+     * @example
+     * // Close with default dismissed result
+     * msgapi.close();
+     *
+     * // Close with custom result
+     * msgapi.close({button: 'OK', value: 'user data'});
+     */
+    close(result?: Partial<MsgResult>): void;
+    /**
+     * Send result and close window (legacy compatibility)
+     * @param result - Result to return to parent process
+     * @example
+     * msgapi.sendResult({button: 'Submit', value: 'form data'});
+     */
+    sendResult(result: Partial<MsgResult>): void;
+    /**
+     * Save data to persistent storage
+     * Data is stored with 'msgapi_' prefix in localStorage
+     * @param key - Storage key
+     * @param value - Value to store (will be JSON.stringify'd)
+     * @returns true on success, false on failure
+     * @example
+     * msgapi.saveData('userPrefs', {theme: 'dark', fontSize: 14});
+     */
+    saveData(key: string, value: any): boolean;
+    /**
+     * Load data from persistent storage
+     * @param key - Storage key
+     * @param defaultValue - Default value if key not found
+     * @returns Stored value or defaultValue
+     * @example
+     * const prefs = msgapi.loadData('userPrefs', {theme: 'light'});
+     */
+    loadData<T = any>(key: string, defaultValue?: T): T;
+    /**
+     * Remove data from persistent storage
+     * @param key - Storage key to remove
+     * @returns true on success, false on failure
+     * @example
+     * msgapi.removeData('tempData');
+     */
+    removeData(key: string): boolean;
+    /**
+     * Clear all msgapi data from persistent storage
+     * Only removes items with 'msgapi_' prefix
+     * @returns true on success, false on failure
+     * @example
+     * msgapi.clearData();
+     */
+    clearData(): boolean;
+    /**
+     * File system operations namespace
+     */
+    fs?: {
+        /**
+         * Select a file using native file picker
+         * @param options - File dialog options
+         * @returns Selected file with content, or null if cancelled
+         * @example
+         * const file = await msgapi.fs.selectFile({
+         *     title: 'Open File',
+         *     filters: [{name: 'Text', extensions: ['txt', 'md']}]
+         * });
+         * if (file) {
+         *     console.log(file.content);
+         * }
+         */
+        selectFile(options?: FileDialogOptions): Promise<SelectedFile | null>;
+        /**
+         * Select multiple files using native file picker
+         * @param options - File dialog options
+         * @returns Array of selected files with content
+         * @example
+         * const files = await msgapi.fs.selectFiles({
+         *     title: 'Open Files'
+         * });
+         */
+        selectFiles(options?: FileDialogOptions): Promise<SelectedFile[]>;
+        /**
+         * Save file using native save dialog
+         * @param content - File content to save
+         * @param defaultFilename - Default filename
+         * @param options - Additional dialog options
+         * @returns Path where file was saved, or null if cancelled
+         * @example
+         * const path = await msgapi.fs.saveFileAs('Hello World', 'greeting.txt');
+         */
+        saveFileAs(content: string, defaultFilename?: string, options?: FileDialogOptions): Promise<string | null>;
+        /**
+         * Select a directory using native folder picker
+         * @param options - Dialog options
+         * @returns Selected directory path, or null if cancelled
+         * @example
+         * const dir = await msgapi.fs.selectFolder({
+         *     title: 'Select Output Folder'
+         * });
+         */
+        selectFolder(options?: FileDialogOptions): Promise<string | null>;
+        /**
+         * Read file contents
+         * Note: Requires allowFs: true flag when launching msgview/msger
+         * @param path - File path to read
+         * @returns File content as string
+         * @example
+         * const content = await msgapi.fs.read('/path/to/file.txt');
+         */
+        read(path: string): Promise<string>;
+        /**
+         * Write file contents
+         * Note: Requires allowFs: true flag when launching msgview/msger
+         * @param path - File path to write
+         * @param content - Content to write
+         * @example
+         * await msgapi.fs.write('/path/to/file.txt', 'Hello World');
+         */
+        write(path: string, content: string): Promise<void>;
+        /**
+         * List directory contents
+         * Note: Requires allowFs: true flag when launching msgview/msger
+         * @param path - Directory path to list
+         * @returns Array of file information
+         * @example
+         * const files = await msgapi.fs.list('/path/to/dir');
+         */
+        list(path: string): Promise<FileInfo[]>;
+        /**
+         * Check if file or directory exists
+         * Note: Requires allowFs: true flag when launching msgview/msger
+         * @param path - Path to check
+         * @returns true if exists
+         * @example
+         * const exists = await msgapi.fs.exists('/path/to/file.txt');
+         */
+        exists(path: string): Promise<boolean>;
+        /**
+         * Delete file or directory
+         * Note: Requires allowFs: true flag when launching msgview/msger
+         * @param path - Path to delete
+         * @example
+         * await msgapi.fs.delete('/path/to/file.txt');
+         */
+        delete(path: string): Promise<void>;
+    };
+}
+/**
+ * Helper to check if code is running in msgview/msger
+ * @returns true if running in msgapi environment
+ * @example
+ * if (isMsgAPI()) {
+ *     msgapi.setTitle('Running in msgview/msger!');
+ * } else {
+ *     console.log('Running in browser');
+ * }
+ */
+export declare function isMsgAPI(): boolean;
+/**
+ * Get msgapi API with fallback for browser compatibility
+ * @returns msgapi API if available, or stub implementation for browser
+ * @example
+ * const api = getMsgAPI();
+ * api.saveData('key', 'value'); // Works in both msgview/msger and browser
+ */
+export declare function getMsgAPI(): MsgAPI;
+/**
+ * Declare global window.msgapi
+ */
+declare global {
+    interface Window {
+        msgapi?: MsgAPI;
+    }
+}
+declare const _default: {
+    isMsgAPI: typeof isMsgAPI;
+    getMsgAPI: typeof getMsgAPI;
+};
+export default _default;
+//# sourceMappingURL=msgapidefs.d.ts.map

package/msgapidefs.js

@@ -0,0 +1,110 @@
+/**
+ * TypeScript definitions for the msgapi JavaScript API
+ *
+ * This module provides type-safe access to msgapi's window control,
+ * data persistence, and file system features (used by msgview and msger).
+ *
+ * Usage:
+ * ```typescript
+ * import type { MsgAPI } from '@bobfrankston/msgapidefs';
+ *
+ * declare global {
+ *     interface Window {
+ *         msgapi?: MsgAPI;
+ *     }
+ * }
+ *
+ * // Check if running in msgview/msger
+ * if (window.msgapi) {
+ *     window.msgapi.setTitle('My App');
+ * }
+ * ```
+ */
+/**
+ * Helper to check if code is running in msgview/msger
+ * @returns true if running in msgapi environment
+ * @example
+ * if (isMsgAPI()) {
+ *     msgapi.setTitle('Running in msgview/msger!');
+ * } else {
+ *     console.log('Running in browser');
+ * }
+ */
+export function isMsgAPI() {
+    return typeof window !== 'undefined' && typeof window.msgapi !== 'undefined';
+}
+/**
+ * Get msgapi API with fallback for browser compatibility
+ * @returns msgapi API if available, or stub implementation for browser
+ * @example
+ * const api = getMsgAPI();
+ * api.saveData('key', 'value'); // Works in both msgview/msger and browser
+ */
+export function getMsgAPI() {
+    if (isMsgAPI()) {
+        return window.msgapi;
+    }
+    // Return browser-compatible stub
+    return {
+        // Window control - no-op in browser
+        toggleFullscreen: () => { },
+        setFullscreen: () => { },
+        minimize: () => { },
+        maximize: () => { },
+        setSize: () => { },
+        setPosition: () => { },
+        setAlwaysOnTop: () => { },
+        setTitle: (title) => { document.title = title; },
+        close: () => { window.close(); },
+        sendResult: () => { window.close(); },
+        // Data persistence - use localStorage in browser
+        saveData: (key, value) => {
+            try {
+                localStorage.setItem('msgapi_' + key, JSON.stringify(value));
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        loadData: (key, defaultValue) => {
+            try {
+                const item = localStorage.getItem('msgapi_' + key);
+                return item ? JSON.parse(item) : defaultValue;
+            }
+            catch {
+                return defaultValue;
+            }
+        },
+        removeData: (key) => {
+            try {
+                localStorage.removeItem('msgapi_' + key);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        clearData: () => {
+            try {
+                const keys = Object.keys(localStorage);
+                for (const key of keys) {
+                    if (key.startsWith('msgapi_')) {
+                        localStorage.removeItem(key);
+                    }
+                }
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        // File system - not available in browser
+        fs: undefined
+    };
+}
+export default {
+    isMsgAPI,
+    getMsgAPI
+};
+//# sourceMappingURL=msgapidefs.js.map