@stacksjs/desktop 0.2.3

package/dist/modals.d.ts

@@ -0,0 +1,201 @@
+import type { ModalOptions, ModalResult } from './types';
+/**
+ * Show a native modal dialog
+ *
+ * @param options - Modal configuration options
+ * @returns Promise resolving to the modal result
+ *
+ * @example
+ * ```typescript
+ * const result = await showModal({
+ *   title: 'Confirm Action',
+ *   message: 'Are you sure you want to proceed?',
+ *   type: 'question',
+ *   buttons: [
+ *     { label: 'Cancel', style: 'default' },
+ *     { label: 'Confirm', style: 'primary' },
+ *   ],
+ * })
+ *
+ * if (result.buttonIndex === 1) {
+ *   // User clicked Confirm
+ * }
+ * ```
+ */
+export declare function showModal(options: ModalOptions): Promise<ModalResult>;
+/**
+ * Show an info modal
+ */
+export declare function showInfoModal(title: string, message: string): Promise<ModalResult>;
+/**
+ * Show a warning modal
+ */
+export declare function showWarningModal(title: string, message: string): Promise<ModalResult>;
+/**
+ * Show an error modal
+ */
+export declare function showErrorModal(title: string, message: string): Promise<ModalResult>;
+/**
+ * Show a success modal
+ */
+export declare function showSuccessModal(title: string, message: string): Promise<ModalResult>;
+/**
+ * Show a question/confirmation modal
+ */
+export declare function showQuestionModal(title: string, message: string): Promise<ModalResult>;
+/**
+ * Show a confirm dialog (alias for showQuestionModal)
+ */
+export declare function confirm(message: string, title?: string): Promise<boolean>;
+/**
+ * Show an alert dialog (single OK button)
+ */
+export declare function alert(message: string, title?: string): Promise<void>;
+/**
+ * Show a prompt dialog with input field
+ */
+export declare function prompt(message: string, defaultValue?: string, title?: string): Promise<string | null>;
+/**
+ * Get number of active modals
+ */
+export declare function getActiveModalCount(): number;
+/**
+ * Close all active modals
+ */
+export declare function closeAllModals(): void;
+/**
+ * CSS styles for web-based modals
+ */
+export declare const MODAL_STYLES: `
+.stx-modal-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.5);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 10000;
+  animation: stx-modal-fade-in 0.15s ease-out;
+}
+
+@keyframes stx-modal-fade-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+.stx-modal {
+  background: #fff;
+  border-radius: 12px;
+  padding: 24px;
+  max-width: 400px;
+  width: 90%;
+  box-shadow: 0 20px 40px rgba(0, 0, 0, 0.2);
+  animation: stx-modal-slide-up 0.2s ease-out;
+}
+
+@keyframes stx-modal-slide-up {
+  from { transform: translateY(20px); opacity: 0; }
+  to { transform: translateY(0); opacity: 1; }
+}
+
+@media (prefers-color-scheme: dark) {
+  .stx-modal {
+    background: #2d2d2d;
+    color: #fff;
+  }
+}
+
+.stx-modal-icon {
+  font-size: 48px;
+  text-align: center;
+  margin-bottom: 16px;
+}
+
+.stx-modal.info .stx-modal-icon { color: #3498db; }
+.stx-modal.warning .stx-modal-icon { color: #f39c12; }
+.stx-modal.error .stx-modal-icon { color: #e74c3c; }
+.stx-modal.success .stx-modal-icon { color: #27ae60; }
+.stx-modal.question .stx-modal-icon { color: #9b59b6; }
+
+.stx-modal-content {
+  text-align: center;
+  margin-bottom: 24px;
+}
+
+.stx-modal-title {
+  margin: 0 0 8px;
+  font-size: 20px;
+  font-weight: 600;
+}
+
+.stx-modal-message {
+  margin: 0;
+  color: #666;
+  line-height: 1.5;
+}
+
+@media (prefers-color-scheme: dark) {
+  .stx-modal-message { color: #aaa; }
+}
+
+.stx-modal-buttons {
+  display: flex;
+  gap: 8px;
+  justify-content: center;
+}
+
+.stx-modal-btn {
+  padding: 10px 24px;
+  border-radius: 6px;
+  font-size: 14px;
+  font-weight: 500;
+  cursor: pointer;
+  border: none;
+  transition: background 0.15s, transform 0.1s;
+}
+
+.stx-modal-btn:hover {
+  transform: translateY(-1px);
+}
+
+.stx-modal-btn:active {
+  transform: translateY(0);
+}
+
+.stx-modal-btn.default {
+  background: #e0e0e0;
+  color: #333;
+}
+
+.stx-modal-btn.default:hover {
+  background: #d0d0d0;
+}
+
+.stx-modal-btn.primary {
+  background: #3498db;
+  color: #fff;
+}
+
+.stx-modal-btn.primary:hover {
+  background: #2980b9;
+}
+
+.stx-modal-btn.destructive {
+  background: #e74c3c;
+  color: #fff;
+}
+
+.stx-modal-btn.destructive:hover {
+  background: #c0392b;
+}
+
+@media (prefers-color-scheme: dark) {
+  .stx-modal-btn.default {
+    background: #444;
+    color: #fff;
+  }
+  .stx-modal-btn.default:hover {
+    background: #555;
+  }
+}
+`;

package/dist/system-tray.d.ts

@@ -0,0 +1,121 @@
+import type { SystemTrayInstance, SystemTrayOptions } from './types';
+/**
+ * Create a system tray/menubar application
+ *
+ * When running inside a Craft native window, this creates a real native tray.
+ * Otherwise, it creates a simulated tray for development purposes.
+ *
+ * @param options - Tray configuration options
+ * @returns System tray instance
+ *
+ * @example
+ * ```typescript
+ * const tray = await createSystemTray({
+ *   icon: './icon.png',
+ *   tooltip: 'My App',
+ *   menu: [
+ *     { label: 'Show Window', onClick: () => stxWindow.show() },
+ *     { type: 'separator' },
+ *     { label: 'Quit', onClick: () => stxWindow.quit() },
+ *   ],
+ * })
+ * ```
+ */
+export declare function createSystemTray(options?: SystemTrayOptions): Promise<SystemTrayInstance>;
+/**
+ * Get all active tray instances
+ */
+export declare function getActiveTrayInstances(): string[];
+/**
+ * Get a tray instance by ID
+ */
+export declare function getTrayInstance(id: string): SystemTrayInstance | null;
+/**
+ * Trigger a menu item action by label
+ * Useful for testing and programmatic control
+ */
+export declare function triggerTrayAction(trayId: string, actionLabel: string): boolean;
+/**
+ * Get the HTML for a simulated tray menu
+ * Useful for web-based testing and development
+ */
+export declare function getSimulatedTrayHTML(trayId: string): string | null;
+/**
+ * Generate a JavaScript snippet for tray control from inside a webview.
+ * This provides convenient wrappers around the Craft tray bridge.
+ */
+export declare function getTrayBridgeScript(): string;
+/**
+ * Create a menubar application (alias for createSystemTray)
+ */
+export declare const createMenubar: typeof createSystemTray;
+/**
+ * CSS styles for the simulated tray menu
+ */
+export declare const TRAY_MENU_STYLES: `
+.stx-tray-menu {
+  background: #2d2d2d;
+  border-radius: 8px;
+  padding: 4px 0;
+  min-width: 200px;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  font-size: 13px;
+  color: #fff;
+}
+
+.stx-tray-item {
+  padding: 6px 12px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  cursor: pointer;
+  position: relative;
+}
+
+.stx-tray-item:hover {
+  background: #3d3d3d;
+}
+
+.stx-tray-item.disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.stx-tray-item .label {
+  flex: 1;
+}
+
+.stx-tray-item .accelerator {
+  margin-left: 20px;
+  opacity: 0.6;
+  font-size: 12px;
+}
+
+.stx-tray-item .arrow {
+  margin-left: 8px;
+  font-size: 10px;
+}
+
+.stx-tray-separator {
+  margin: 4px 0;
+  border: none;
+  border-top: 1px solid #444;
+}
+
+.stx-tray-submenu {
+  position: absolute;
+  left: 100%;
+  top: 0;
+  background: #2d2d2d;
+  border-radius: 8px;
+  padding: 4px 0;
+  min-width: 150px;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);
+  display: none;
+}
+
+.stx-tray-item:hover > .stx-tray-submenu {
+  display: block;
+}
+`;

package/dist/types.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Desktop Application Types
+ */
+/**
+ * Sidebar item configuration
+ */
+export declare interface SidebarItem {
+  id: string
+  label: string
+  icon?: string
+  badge?: string | number
+  tintColor?: string
+  selected?: boolean
+  disabled?: boolean
+  children?: SidebarItem[]
+  data?: Record<string, unknown>
+}
+/**
+ * Sidebar section with header
+ */
+export declare interface SidebarSection {
+  id: string
+  title: string
+  collapsible?: boolean
+  collapsed?: boolean
+  items: SidebarItem[]
+}
+/**
+ * Native sidebar configuration
+ */
+export declare interface SidebarConfig {
+  sections: SidebarSection[]
+  minWidth?: number
+  maxWidth?: number
+  canCollapse?: boolean
+  searchPlaceholder?: string
+  header?: {
+    title?: string
+    subtitle?: string
+    icon?: string
+  }
+}
+/**
+ * Window configuration options
+ */
+export declare interface WindowOptions {
+  title?: string
+  width?: number
+  height?: number
+  darkMode?: boolean
+  hotReload?: boolean
+  resizable?: boolean
+  minimizable?: boolean
+  maximizable?: boolean
+  closable?: boolean
+  alwaysOnTop?: boolean
+  frameless?: boolean
+  backgroundColor?: string
+  nativeSidebar?: boolean
+  sidebarWidth?: number
+  sidebarConfig?: SidebarConfig
+}
+/**
+ * System tray/menubar configuration options
+ */
+export declare interface SystemTrayOptions {
+  icon?: string
+  tooltip?: string
+  menu?: SystemTrayMenuItem[]
+}
+/**
+ * Modal dialog options
+ */
+export declare interface ModalOptions {
+  title?: string
+  message: string
+  type?: 'info' | 'warning' | 'error' | 'success' | 'question'
+  buttons?: ModalButton[]
+  defaultButton?: number
+  cancelButton?: number
+}
+/**
+ * Modal button configuration
+ */
+export declare interface ModalButton {
+  label: string
+  action?: () => void
+  style?: 'default' | 'primary' | 'destructive'
+}
+/**
+ * Alert/notification options
+ */
+export declare interface AlertOptions {
+  title?: string
+  message: string
+  type?: 'info' | 'success' | 'warning' | 'error'
+  duration?: number
+  position?: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'
+  theme?: 'light' | 'dark' | 'auto'
+  onClick?: () => void
+}
+/**
+ * Component base properties
+ */
+export declare interface ComponentProps {
+  id?: string
+  className?: string
+  style?: Record<string, string>
+  visible?: boolean
+  enabled?: boolean
+}
+/**
+ * Window instance
+ */
+export declare interface WindowInstance {
+  id: string
+  show: () => void
+  hide: () => void
+  close: () => void
+  focus: () => void
+  minimize: () => void
+  maximize: () => void
+  restore: () => void
+  setTitle: (title: string) => void
+  loadURL: (url: string) => void
+  reload: () => void
+}
+/**
+ * System tray instance
+ */
+export declare interface SystemTrayInstance {
+  id: string
+  setIcon: (icon: string) => void
+  setTooltip: (tooltip: string) => void
+  setMenu: (menu: SystemTrayMenuItem[]) => void
+  destroy: () => void
+}
+/**
+ * Result of modal dialog
+ */
+export declare interface ModalResult {
+  buttonIndex: number
+  cancelled: boolean
+}
+/**
+ * System tray menu item
+ */
+export type SystemTrayMenuItem = | {
+    /** Menu item label */
+    label: string
+    /** Click handler */
+    onClick?: () => void
+    /** Keyboard shortcut */
+    accelerator?: string
+    /** Menu item type */
+    type?: 'normal' | 'checkbox' | 'submenu'
+    /** Submenu items (if type is 'submenu') */
+    submenu?: SystemTrayMenuItem[]
+    /** Is checkbox checked (if type is 'checkbox') */
+    checked?: boolean
+    /** Is menu item enabled */
+    enabled?: boolean
+  }
+  | {
+    /** Menu item type */
+    type: 'separator'
+  }
+/**
+ * Toast notification options (alias for AlertOptions)
+ */
+export type ToastOptions = AlertOptions

package/dist/window.d.ts

@@ -0,0 +1,111 @@
+import type { WindowInstance, WindowOptions } from './types';
+/**
+ * Configure desktop window settings
+ *
+ * @example
+ * ```typescript
+ * setDesktopConfig({
+ *   craftBinaryPath: '/custom/path/to/craft',
+ *   maxRetries: 3,
+ *   retryDelay: 2000
+ * })
+ * ```
+ */
+export declare function setDesktopConfig(config: Partial<DesktopConfig>): void;
+/**
+ * Get current desktop configuration
+ */
+export declare function getDesktopConfig(): DesktopConfig;
+/**
+ * Reset desktop configuration to defaults
+ */
+export declare function resetDesktopConfig(): void;
+/**
+ * Get all active window IDs
+ */
+export declare function getActiveWindowIds(): string[];
+/**
+ * Get a window by ID
+ */
+export declare function getWindow(id: string): WindowInstance | null;
+/**
+ * Close all active windows
+ */
+export declare function closeAllWindows(): void;
+/**
+ * Create a native window with URL
+ *
+ * Uses ts-craft to create native desktop windows. Falls back to returning null
+ * if ts-craft is not available.
+ *
+ * ## Window Control
+ *
+ * The CraftApp spawns a native webview process. Window control methods like
+ * hide(), minimize(), setTitle() etc. are available via the `window.craft`
+ * bridge **inside** the webview context:
+ *
+ * ```javascript
+ * // Inside your HTML/JS running in the webview:
+ * window.craft.window.hide()
+ * window.craft.window.minimize()
+ * window.craft.window.setTitle({ title: 'New Title' })
+ * window.craft.window.center()
+ * ```
+ *
+ * The returned WindowInstance provides the `close()` method which terminates
+ * the native process from the Node.js side.
+ *
+ * @param url - URL to load in the window
+ * @param options - Window configuration options
+ * @returns WindowInstance if successful, null if ts-craft unavailable
+ */
+export declare function createWindow(url: string, options?: WindowOptions): Promise<WindowInstance | null>;
+/**
+ * Open a development server window
+ * This is specifically for the stx dev server --native flag
+ *
+ * Uses ts-craft to create a native window, falls back to browser if unavailable.
+ */
+export declare function openDevWindow(port: number, options?: WindowOptions): Promise<boolean>;
+/**
+ * Create a window with HTML content
+ *
+ * Uses ts-craft to display HTML content in a native window.
+ */
+export declare function createWindowWithHTML(html: string, options?: WindowOptions): Promise<WindowInstance | null>;
+/**
+ * Helper to check if webview implementation is available
+ */
+export declare function isWebviewAvailable(): boolean;
+/**
+ * Generate a JavaScript snippet to inject into HTML that provides
+ * helper functions for common window operations.
+ *
+ * This can be injected into your HTML to provide easier access to Craft APIs.
+ *
+ * @example
+ * ```typescript
+ * const html = `
+ *   <html>
+ *     <head>
+ *       <script>${getWindowBridgeScript()}</script>
+ *     </head>
+ *     <body>
+ *       <button onclick="stxWindow.minimize()">Minimize</button>
+ *     </body>
+ *   </html>
+ * `
+ * await createWindowWithHTML(html)
+ * ```
+ */
+export declare function getWindowBridgeScript(): string;
+/**
+ * Desktop window configuration.
+ * Can be set via environment variables or setDesktopConfig().
+ */
+export declare interface DesktopConfig {
+  craftBinaryPath?: string
+  additionalSearchPaths?: string[]
+  maxRetries?: number
+  retryDelay?: number
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@stacksjs/desktop",
+  "type": "module",
+  "version": "0.2.3",
+  "description": "Native desktop application framework for stx (powered by Craft)",
+  "author": "Chris Breuer <chris@stacksjs.org>",
+  "license": "MIT",
+  "homepage": "https://github.com/stacksjs/stx#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stacksjs/stx.git"
+  },
+  "bugs": {
+    "url": "https://github.com/stacksjs/stx/issues"
+  },
+  "keywords": [
+    "desktop",
+    "native",
+    "window",
+    "craft",
+    "electron-alternative",
+    "webview",
+    "cross-platform",
+    "stx"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./*": {
+      "import": "./dist/*"
+    }
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "LICENSE.md",
+    "README.md",
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun --bun build.ts",
+    "lint": "bunx --bun pickier lint",
+    "lint:fix": "bunx --bun pickier lint --fix",
+    "fresh": "bunx rimraf node_modules/ bun.lock && bun i",
+    "prepublishOnly": "bun run build",
+    "test": "bun test --preload ../../test-utils/happy-dom.ts",
+    "test:watch": "bun test --watch --preload ../../test-utils/happy-dom.ts",
+    "test:coverage": "bun test --coverage --preload ../../test-utils/happy-dom.ts",
+    "typecheck": "bun tsc --noEmit"
+  },
+  "peerDependencies": {
+    "craft": "*"
+  },
+  "peerDependenciesMeta": {
+    "craft": {
+      "optional": true
+    }
+  },
+  "dependencies": {},
+  "devDependencies": {}
+}