@talex-touch/utils 1.0.31 → 1.0.33

package/plugin/sdk/division-box.ts

@@ -0,0 +1,266 @@
+/**
+ * DivisionBox SDK for Plugin Development
+ * 
+ * Provides a simple API for plugins to create and manage DivisionBox instances.
+ * DivisionBox is a lightweight floating window container for plugin UIs and tools.
+ */
+
+import type {
+  CloseOptions,
+  DivisionBoxConfig,
+  DivisionBoxState,
+  SessionInfo,
+} from '../../types/division-box'
+
+/**
+ * State change event handler
+ */
+export type StateChangeHandler = (data: {
+  sessionId: string
+  state: DivisionBoxState
+}) => void
+
+/**
+ * DivisionBox SDK interface for plugins
+ * 
+ * @example
+ * ```typescript
+ * // Open a DivisionBox
+ * const { sessionId } = await plugin.divisionBox.open({
+ *   url: 'https://example.com/tool',
+ *   title: 'My Tool',
+ *   size: 'medium',
+ *   keepAlive: true
+ * })
+ * 
+ * // Listen for state changes
+ * plugin.divisionBox.onStateChange((data) => {
+ *   console.log(`Session ${data.sessionId} is now ${data.state}`)
+ * })
+ * 
+ * // Close the DivisionBox
+ * await plugin.divisionBox.close(sessionId)
+ * ```
+ */
+export interface DivisionBoxSDK {
+  /**
+   * Opens a new DivisionBox instance
+   * 
+   * @param config - Configuration for the DivisionBox
+   * @returns Promise resolving to session information
+   * 
+   * @example
+   * ```typescript
+   * const { sessionId } = await plugin.divisionBox.open({
+   *   url: 'https://example.com',
+   *   title: 'Web Tool',
+   *   icon: 'ri:tools-line',
+   *   size: 'medium',
+   *   keepAlive: true,
+   *   header: {
+   *     show: true,
+   *     title: 'Custom Title',
+   *     actions: [
+   *       { label: 'Refresh', icon: 'ri:refresh-line', onClick: () => {} }
+   *     ]
+   *   }
+   * })
+   * ```
+   */
+  open(config: DivisionBoxConfig): Promise<SessionInfo>
+
+  /**
+   * Closes a DivisionBox instance
+   * 
+   * @param sessionId - The session ID to close
+   * @param options - Optional close options
+   * @returns Promise that resolves when closed
+   * 
+   * @example
+   * ```typescript
+   * // Simple close
+   * await plugin.divisionBox.close(sessionId)
+   * 
+   * // Close with delay and animation
+   * await plugin.divisionBox.close(sessionId, {
+   *   delay: 1000,
+   *   animation: true
+   * })
+   * 
+   * // Force close (ignore keepAlive)
+   * await plugin.divisionBox.close(sessionId, {
+   *   force: true
+   * })
+   * ```
+   */
+  close(sessionId: string, options?: CloseOptions): Promise<void>
+
+  /**
+   * Registers a state change listener
+   * 
+   * @param handler - Callback function for state changes
+   * @returns Unsubscribe function
+   * 
+   * @example
+   * ```typescript
+   * const unsubscribe = plugin.divisionBox.onStateChange((data) => {
+   *   console.log(`Session ${data.sessionId} changed to ${data.state}`)
+   * })
+   * 
+   * // Later, unsubscribe
+   * unsubscribe()
+   * ```
+   */
+  onStateChange(handler: StateChangeHandler): () => void
+
+  /**
+   * Updates session state data
+   * 
+   * @param sessionId - The session ID
+   * @param key - State key
+   * @param value - State value
+   * @returns Promise that resolves when updated
+   * 
+   * @example
+   * ```typescript
+   * // Save scroll position
+   * await plugin.divisionBox.updateState(sessionId, 'scrollY', 150)
+   * 
+   * // Save draft content
+   * await plugin.divisionBox.updateState(sessionId, 'draft', {
+   *   text: 'Hello world',
+   *   timestamp: Date.now()
+   * })
+   * ```
+   */
+  updateState(sessionId: string, key: string, value: any): Promise<void>
+
+  /**
+   * Gets session state data
+   * 
+   * @param sessionId - The session ID
+   * @param key - State key
+   * @returns Promise resolving to the state value
+   * 
+   * @example
+   * ```typescript
+   * const scrollY = await plugin.divisionBox.getState(sessionId, 'scrollY')
+   * const draft = await plugin.divisionBox.getState(sessionId, 'draft')
+   * ```
+   */
+  getState(sessionId: string, key: string): Promise<any>
+}
+
+/**
+ * Creates a DivisionBox SDK instance for plugin use
+ * 
+ * @param channel - The plugin channel bridge for IPC communication
+ * @returns Configured DivisionBox SDK instance
+ * 
+ * @internal
+ */
+export function createDivisionBoxSDK(channel: any): DivisionBoxSDK {
+  const stateChangeHandlers: Set<StateChangeHandler> = new Set()
+
+  // Register listener for state change events from main process
+  // The channel can be either IPluginChannelBridge (main process) or window.$channel (renderer)
+  const registerListener = () => {
+    if (channel.onMain) {
+      // Main process plugin context
+      channel.onMain('division-box:state-changed', (event: any) => {
+        stateChangeHandlers.forEach(handler => handler(event.data || event))
+      })
+    } else if (channel.on) {
+      // Renderer process context
+      channel.on('division-box:state-changed', (data: any) => {
+        stateChangeHandlers.forEach(handler => handler(data))
+      })
+    }
+  }
+
+  registerListener()
+
+  return {
+    async open(config: DivisionBoxConfig): Promise<SessionInfo> {
+      // Send to main process
+      const sendFn = channel.sendToMain || channel.send
+      const result = await sendFn('division-box:open', config)
+      
+      if (!result.success) {
+        throw new Error(result.error?.message || 'Failed to open DivisionBox')
+      }
+      
+      return result.data
+    },
+
+    async close(sessionId: string, options?: CloseOptions): Promise<void> {
+      const sendFn = channel.sendToMain || channel.send
+      const result = await sendFn('division-box:close', { sessionId, options })
+      
+      if (!result.success) {
+        throw new Error(result.error?.message || 'Failed to close DivisionBox')
+      }
+    },
+
+    onStateChange(handler: StateChangeHandler): () => void {
+      stateChangeHandlers.add(handler)
+      
+      return () => {
+        stateChangeHandlers.delete(handler)
+      }
+    },
+
+    async updateState(sessionId: string, key: string, value: any): Promise<void> {
+      const sendFn = channel.sendToMain || channel.send
+      const result = await sendFn('division-box:update-state', {
+        sessionId,
+        key,
+        value
+      })
+      
+      if (!result.success) {
+        throw new Error(result.error?.message || 'Failed to update state')
+      }
+    },
+
+    async getState(sessionId: string, key: string): Promise<any> {
+      const sendFn = channel.sendToMain || channel.send
+      const result = await sendFn('division-box:get-state', {
+        sessionId,
+        key
+      })
+      
+      if (!result.success) {
+        throw new Error(result.error?.message || 'Failed to get state')
+      }
+      
+      return result.data
+    }
+  }
+}
+
+/**
+ * Hook for using DivisionBox SDK in plugin context
+ * 
+ * @returns DivisionBox SDK instance
+ * 
+ * @example
+ * ```typescript
+ * const divisionBox = useDivisionBox()
+ * 
+ * const { sessionId } = await divisionBox.open({
+ *   url: 'https://example.com',
+ *   title: 'My Tool'
+ * })
+ * ```
+ */
+export function useDivisionBox(): DivisionBoxSDK {
+  // @ts-ignore - window.$channel is injected by the plugin system
+  const channel = window.$channel
+  
+  if (!channel) {
+    throw new Error('[DivisionBox SDK] Channel not available. Make sure this is called in a plugin context.')
+  }
+  
+  return createDivisionBoxSDK(channel)
+}

package/plugin/sdk/enum/bridge-event.ts

@@ -1,4 +1,4 @@
 export enum BridgeEventForCoreBox {
   CORE_BOX_INPUT_CHANGE = 'core-box:input-change',
- CORE_BOX_CLIPBOARD_CHANGE = 'core-box:clipboard-change'
+  CORE_BOX_CLIPBOARD_CHANGE = 'core-box:clipboard-change',
 }

package/plugin/sdk/examples/storage-onDidChange-example.js

@@ -185,7 +185,7 @@ window.storageOnDidChangeExample = {
   setupMultipleFileListeners,
   setupDynamicListener,
   setupConditionalListener,
-  setupBatchOperationListener
+  setupBatchOperationListener,
 }
 
 // 自动运行示例（可选）

package/plugin/sdk/feature-sdk.ts

@@ -0,0 +1,235 @@
+/**
+ * Feature SDK for Plugin Development
+ * 
+ * Provides a unified API for plugins to manage search result items (TuffItems)
+ * in the CoreBox interface. This SDK handles item lifecycle, updates, and
+ * input change notifications.
+ */
+
+import type { TuffItem } from '../../core-box/tuff'
+
+/**
+ * Input change event handler
+ */
+export type InputChangeHandler = (input: string) => void
+
+/**
+ * Feature SDK interface for plugins
+ * 
+ * @example
+ * ```typescript
+ * // Push items to CoreBox
+ * plugin.feature.pushItems([
+ *   { id: 'item-1', title: 'Result 1', ... },
+ *   { id: 'item-2', title: 'Result 2', ... }
+ * ])
+ * 
+ * // Update a specific item
+ * plugin.feature.updateItem('item-1', { title: 'Updated Title' })
+ * 
+ * // Listen for input changes
+ * plugin.feature.onInputChange((input) => {
+ *   console.log('User typed:', input)
+ * })
+ * ```
+ */
+export interface FeatureSDK {
+  /**
+   * Pushes multiple items to the CoreBox search results
+   * 
+   * @param items - Array of TuffItem objects to display
+   * 
+   * @example
+   * ```typescript
+   * plugin.feature.pushItems([
+   *   {
+   *     id: 'calc-result',
+   *     title: { text: '42' },
+   *     subtitle: { text: 'Calculation result' },
+   *     source: { id: 'calculator', name: 'Calculator' }
+   *   }
+   * ])
+   * ```
+   */
+  pushItems(items: TuffItem[]): void
+
+  /**
+   * Updates a specific item by ID
+   * 
+   * @param id - The unique ID of the item to update
+   * @param updates - Partial TuffItem with fields to update
+   * 
+   * @example
+   * ```typescript
+   * // Update title and subtitle
+   * plugin.feature.updateItem('item-1', {
+   *   title: { text: 'New Title' },
+   *   subtitle: { text: 'Updated subtitle' }
+   * })
+   * ```
+   */
+  updateItem(id: string, updates: Partial<TuffItem>): void
+
+  /**
+   * Removes a specific item by ID
+   * 
+   * @param id - The unique ID of the item to remove
+   * 
+   * @example
+   * ```typescript
+   * plugin.feature.removeItem('item-1')
+   * ```
+   */
+  removeItem(id: string): void
+
+  /**
+   * Clears all items pushed by this plugin
+   * 
+   * @example
+   * ```typescript
+   * plugin.feature.clearItems()
+   * ```
+   */
+  clearItems(): void
+
+  /**
+   * Gets all items currently pushed by this plugin
+   * 
+   * @returns Array of TuffItem objects
+   * 
+   * @example
+   * ```typescript
+   * const items = plugin.feature.getItems()
+   * console.log(`Currently showing ${items.length} items`)
+   * ```
+   */
+  getItems(): TuffItem[]
+
+  /**
+   * Registers a listener for input changes in the CoreBox search field
+   * 
+   * @param handler - Callback function invoked when input changes
+   * @returns Unsubscribe function
+   * 
+   * @example
+   * ```typescript
+   * const unsubscribe = plugin.feature.onInputChange((input) => {
+   *   console.log('User typed:', input)
+   *   // Perform real-time search
+   *   performSearch(input)
+   * })
+   * 
+   * // Later, unsubscribe
+   * unsubscribe()
+   * ```
+   */
+  onInputChange(handler: InputChangeHandler): () => void
+}
+
+/**
+ * Creates a Feature SDK instance for plugin use
+ * 
+ * @param boxItemsAPI - The boxItems API object from plugin context
+ * @param channel - The plugin channel bridge for IPC communication
+ * @returns Configured Feature SDK instance
+ * 
+ * @internal
+ */
+export function createFeatureSDK(boxItemsAPI: any, channel: any): FeatureSDK {
+  const inputChangeHandlers: Set<InputChangeHandler> = new Set()
+
+  // Register listener for input change events from main process
+  const registerListener = () => {
+    if (channel.onMain) {
+      // Main process plugin context
+      channel.onMain('core-box:input-changed', (event: any) => {
+        const input = event.data?.input || event.input || ''
+        inputChangeHandlers.forEach(handler => handler(input))
+      })
+    } else if (channel.on) {
+      // Renderer process context
+      channel.on('core-box:input-changed', (data: any) => {
+        const input = data?.input || data || ''
+        inputChangeHandlers.forEach(handler => handler(input))
+      })
+    }
+  }
+
+  registerListener()
+
+  return {
+    pushItems(items: TuffItem[]): void {
+      if (!boxItemsAPI || !boxItemsAPI.pushItems) {
+        throw new Error('[Feature SDK] boxItems API not available')
+      }
+      boxItemsAPI.pushItems(items)
+    },
+
+    updateItem(id: string, updates: Partial<TuffItem>): void {
+      if (!boxItemsAPI || !boxItemsAPI.update) {
+        throw new Error('[Feature SDK] boxItems API not available')
+      }
+      boxItemsAPI.update(id, updates)
+    },
+
+    removeItem(id: string): void {
+      if (!boxItemsAPI || !boxItemsAPI.remove) {
+        throw new Error('[Feature SDK] boxItems API not available')
+      }
+      boxItemsAPI.remove(id)
+    },
+
+    clearItems(): void {
+      if (!boxItemsAPI || !boxItemsAPI.clear) {
+        throw new Error('[Feature SDK] boxItems API not available')
+      }
+      boxItemsAPI.clear()
+    },
+
+    getItems(): TuffItem[] {
+      if (!boxItemsAPI || !boxItemsAPI.getItems) {
+        throw new Error('[Feature SDK] boxItems API not available')
+      }
+      return boxItemsAPI.getItems()
+    },
+
+    onInputChange(handler: InputChangeHandler): () => void {
+      inputChangeHandlers.add(handler)
+      
+      return () => {
+        inputChangeHandlers.delete(handler)
+      }
+    }
+  }
+}
+
+/**
+ * Hook for using Feature SDK in plugin context
+ * 
+ * @returns Feature SDK instance
+ * 
+ * @example
+ * ```typescript
+ * const feature = useFeature()
+ * 
+ * feature.pushItems([
+ *   { id: '1', title: { text: 'Item 1' }, ... }
+ * ])
+ * ```
+ */
+export function useFeature(): FeatureSDK {
+  // @ts-ignore - window.$boxItems and window.$channel are injected by the plugin system
+  const boxItemsAPI = window.$boxItems
+  // @ts-ignore
+  const channel = window.$channel
+  
+  if (!boxItemsAPI) {
+    throw new Error('[Feature SDK] boxItems API not available. Make sure this is called in a plugin context.')
+  }
+  
+  if (!channel) {
+    throw new Error('[Feature SDK] Channel not available. Make sure this is called in a plugin context.')
+  }
+  
+  return createFeatureSDK(boxItemsAPI, channel)
+}