@mywallpaper/addon-sdk 2.11.1 → 2.13.0

package/README.md

@@ -48,7 +48,7 @@ my-addon/
 {
   "name": "My Awesome Addon",
   "version": "1.0.0",
-  "sdkVersion": "2.7.0",
+  "sdkVersion": "2.13.0",
   "description": "A cool widget for your desktop",
   "author": "Your Name",
   "capabilities": {
@@ -226,6 +226,34 @@ api.onSettingsChange((settings, changedKeys) => {
 })
 ```
 
+##### `onButtonClick(settingKey, callback)` / `offButtonClick(settingKey)`
+
+Handle button setting clicks.
+
+```typescript
+// Register a handler for a button setting
+api.onButtonClick('resetButton', () => {
+  resetToDefaults()
+  console.log('Reset clicked!')
+})
+
+// Remove the handler when no longer needed
+api.offButtonClick('resetButton')
+```
+
+With manifest:
+
+```json
+{
+  "settings": {
+    "resetButton": {
+      "type": "button",
+      "buttonLabel": "Reset to Defaults"
+    }
+  }
+}
+```
+
 ##### `onEvent(event, callback)` / `offEvent(event, callback)`
 
 Subscribe/unsubscribe to system events.

package/dist/index.d.mts

@@ -476,6 +476,30 @@ interface MyWallpaperAPI {
      * @param callback - Function called with new settings and changed keys
      */
     onSettingsChange(callback: SettingsCallback): void;
+    /**
+     * Register a callback for when a button setting is clicked.
+     * Buttons are defined in manifest.json with `type: "button"`.
+     *
+     * @param settingKey - The button's setting key from manifest
+     * @param callback - Function called when the button is clicked
+     *
+     * @example
+     * ```typescript
+     * // manifest.json:
+     * // "refreshButton": { "type": "button", "label": "Refresh", "buttonLabel": "Refresh Now" }
+     *
+     * api.onButtonClick('refreshButton', () => {
+     *   console.log('Refresh button clicked!')
+     *   fetchLatestData()
+     * })
+     * ```
+     */
+    onButtonClick(settingKey: string, callback: () => void): void;
+    /**
+     * Unregister a button click callback.
+     * @param settingKey - The button's setting key
+     */
+    offButtonClick(settingKey: string): void;
     /**
      * Subscribe to a system event.
      * @param event - Event type to subscribe to
@@ -931,6 +955,37 @@ interface SettingOption {
  * ```
  */
 interface SettingsAPI {
+    /**
+     * Update a single setting value from the addon.
+     * This syncs the value back to the host UI and persists it.
+     *
+     * @param settingKey - The setting key to update
+     * @param value - The new value
+     *
+     * @example
+     * ```typescript
+     * // Update a color setting after randomization
+     * api.settings.setValue('primaryColor', '#ff0000')
+     * ```
+     */
+    setValue(settingKey: string, value: unknown): void;
+    /**
+     * Update multiple setting values at once.
+     * This syncs all values back to the host UI and persists them.
+     *
+     * @param values - Object with settingKey -> value pairs
+     *
+     * @example
+     * ```typescript
+     * // Update multiple colors after randomization
+     * api.settings.setValues({
+     *   primaryColor: '#ff0000',
+     *   secondaryColor: '#00ff00',
+     *   backgroundColor: '#0000ff'
+     * })
+     * ```
+     */
+    setValues(values: Record<string, unknown>): void;
     /**
      * Update the options for a select-type setting.
      * The new options replace existing ones from the manifest.

package/dist/index.d.ts

@@ -476,6 +476,30 @@ interface MyWallpaperAPI {
      * @param callback - Function called with new settings and changed keys
      */
     onSettingsChange(callback: SettingsCallback): void;
+    /**
+     * Register a callback for when a button setting is clicked.
+     * Buttons are defined in manifest.json with `type: "button"`.
+     *
+     * @param settingKey - The button's setting key from manifest
+     * @param callback - Function called when the button is clicked
+     *
+     * @example
+     * ```typescript
+     * // manifest.json:
+     * // "refreshButton": { "type": "button", "label": "Refresh", "buttonLabel": "Refresh Now" }
+     *
+     * api.onButtonClick('refreshButton', () => {
+     *   console.log('Refresh button clicked!')
+     *   fetchLatestData()
+     * })
+     * ```
+     */
+    onButtonClick(settingKey: string, callback: () => void): void;
+    /**
+     * Unregister a button click callback.
+     * @param settingKey - The button's setting key
+     */
+    offButtonClick(settingKey: string): void;
     /**
      * Subscribe to a system event.
      * @param event - Event type to subscribe to
@@ -931,6 +955,37 @@ interface SettingOption {
  * ```
  */
 interface SettingsAPI {
+    /**
+     * Update a single setting value from the addon.
+     * This syncs the value back to the host UI and persists it.
+     *
+     * @param settingKey - The setting key to update
+     * @param value - The new value
+     *
+     * @example
+     * ```typescript
+     * // Update a color setting after randomization
+     * api.settings.setValue('primaryColor', '#ff0000')
+     * ```
+     */
+    setValue(settingKey: string, value: unknown): void;
+    /**
+     * Update multiple setting values at once.
+     * This syncs all values back to the host UI and persists them.
+     *
+     * @param values - Object with settingKey -> value pairs
+     *
+     * @example
+     * ```typescript
+     * // Update multiple colors after randomization
+     * api.settings.setValues({
+     *   primaryColor: '#ff0000',
+     *   secondaryColor: '#00ff00',
+     *   backgroundColor: '#0000ff'
+     * })
+     * ```
+     */
+    setValues(values: Record<string, unknown>): void;
     /**
      * Update the options for a select-type setting.
      * The new options replace existing ones from the manifest.

package/dist/manifest.d.mts

@@ -461,6 +461,30 @@ interface MyWallpaperAPI {
      * @param callback - Function called with new settings and changed keys
      */
     onSettingsChange(callback: SettingsCallback): void;
+    /**
+     * Register a callback for when a button setting is clicked.
+     * Buttons are defined in manifest.json with `type: "button"`.
+     *
+     * @param settingKey - The button's setting key from manifest
+     * @param callback - Function called when the button is clicked
+     *
+     * @example
+     * ```typescript
+     * // manifest.json:
+     * // "refreshButton": { "type": "button", "label": "Refresh", "buttonLabel": "Refresh Now" }
+     *
+     * api.onButtonClick('refreshButton', () => {
+     *   console.log('Refresh button clicked!')
+     *   fetchLatestData()
+     * })
+     * ```
+     */
+    onButtonClick(settingKey: string, callback: () => void): void;
+    /**
+     * Unregister a button click callback.
+     * @param settingKey - The button's setting key
+     */
+    offButtonClick(settingKey: string): void;
     /**
      * Subscribe to a system event.
      * @param event - Event type to subscribe to
@@ -912,6 +936,37 @@ interface SettingOption {
  * ```
  */
 interface SettingsAPI {
+    /**
+     * Update a single setting value from the addon.
+     * This syncs the value back to the host UI and persists it.
+     *
+     * @param settingKey - The setting key to update
+     * @param value - The new value
+     *
+     * @example
+     * ```typescript
+     * // Update a color setting after randomization
+     * api.settings.setValue('primaryColor', '#ff0000')
+     * ```
+     */
+    setValue(settingKey: string, value: unknown): void;
+    /**
+     * Update multiple setting values at once.
+     * This syncs all values back to the host UI and persists them.
+     *
+     * @param values - Object with settingKey -> value pairs
+     *
+     * @example
+     * ```typescript
+     * // Update multiple colors after randomization
+     * api.settings.setValues({
+     *   primaryColor: '#ff0000',
+     *   secondaryColor: '#00ff00',
+     *   backgroundColor: '#0000ff'
+     * })
+     * ```
+     */
+    setValues(values: Record<string, unknown>): void;
     /**
      * Update the options for a select-type setting.
      * The new options replace existing ones from the manifest.

package/dist/manifest.d.ts

@@ -461,6 +461,30 @@ interface MyWallpaperAPI {
      * @param callback - Function called with new settings and changed keys
      */
     onSettingsChange(callback: SettingsCallback): void;
+    /**
+     * Register a callback for when a button setting is clicked.
+     * Buttons are defined in manifest.json with `type: "button"`.
+     *
+     * @param settingKey - The button's setting key from manifest
+     * @param callback - Function called when the button is clicked
+     *
+     * @example
+     * ```typescript
+     * // manifest.json:
+     * // "refreshButton": { "type": "button", "label": "Refresh", "buttonLabel": "Refresh Now" }
+     *
+     * api.onButtonClick('refreshButton', () => {
+     *   console.log('Refresh button clicked!')
+     *   fetchLatestData()
+     * })
+     * ```
+     */
+    onButtonClick(settingKey: string, callback: () => void): void;
+    /**
+     * Unregister a button click callback.
+     * @param settingKey - The button's setting key
+     */
+    offButtonClick(settingKey: string): void;
     /**
      * Subscribe to a system event.
      * @param event - Event type to subscribe to
@@ -912,6 +936,37 @@ interface SettingOption {
  * ```
  */
 interface SettingsAPI {
+    /**
+     * Update a single setting value from the addon.
+     * This syncs the value back to the host UI and persists it.
+     *
+     * @param settingKey - The setting key to update
+     * @param value - The new value
+     *
+     * @example
+     * ```typescript
+     * // Update a color setting after randomization
+     * api.settings.setValue('primaryColor', '#ff0000')
+     * ```
+     */
+    setValue(settingKey: string, value: unknown): void;
+    /**
+     * Update multiple setting values at once.
+     * This syncs all values back to the host UI and persists them.
+     *
+     * @param values - Object with settingKey -> value pairs
+     *
+     * @example
+     * ```typescript
+     * // Update multiple colors after randomization
+     * api.settings.setValues({
+     *   primaryColor: '#ff0000',
+     *   secondaryColor: '#00ff00',
+     *   backgroundColor: '#0000ff'
+     * })
+     * ```
+     */
+    setValues(values: Record<string, unknown>): void;
     /**
      * Update the options for a select-type setting.
      * The new options replace existing ones from the manifest.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mywallpaper/addon-sdk",
-  "version": "2.11.1",
+  "version": "2.13.0",
   "description": "SDK for building MyWallpaper addons - TypeScript types, manifest validation, and utilities",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/runtime/addon-client.js

@@ -32,6 +32,7 @@
   var pendingNetworkAccess = new Map()  // For on-demand domain permission requests
   var grantedBlobUrls = new Map() // settingKey -> blobUrl
   var dynamicSettingsOptions = new Map() // settingKey -> options[] (dynamic options from widget)
+  var buttonCallbacks = new Map() // settingKey -> callback function for button clicks
 
   // Audio state (synced from host)
   var audioState = {
@@ -250,6 +251,15 @@
           try { cb(audioState) } catch (err) { console.error('[MyWallpaper] Audio callback error:', err) }
         })
         break
+
+      case 'BUTTON_CLICK':
+        // Handle button click from settings panel
+        var btnKey = d.payload.settingKey
+        var btnCb = buttonCallbacks.get(btnKey)
+        if (btnCb) {
+          try { btnCb() } catch (err) { console.error('[MyWallpaper] Button callback error:', err) }
+        }
+        break
     }
   }
 
@@ -416,10 +426,29 @@
   window.MyWallpaper = {
     get config() { return config },
     layerId: layerId,
-    version: '2.11.0',
+    version: '2.13.0',
 
     onSettingsChange: function (fn) { if (typeof fn === 'function') settingsCallbacks.push(fn) },
 
+    /**
+     * Register a callback for a button click in settings panel
+     * @param {string} settingKey - The button's setting key from manifest
+     * @param {function} callback - Function called when button is clicked
+     */
+    onButtonClick: function (settingKey, callback) {
+      if (typeof settingKey === 'string' && typeof callback === 'function') {
+        buttonCallbacks.set(settingKey, callback)
+      }
+    },
+
+    /**
+     * Unregister a button click callback
+     * @param {string} settingKey - The button's setting key
+     */
+    offButtonClick: function (settingKey) {
+      buttonCallbacks.delete(settingKey)
+    },
+
     onEvent: function (event, fn) {
       if (typeof fn !== 'function') return
       if (!eventCallbacks.has(event)) eventCallbacks.set(event, new Set())
@@ -441,7 +470,7 @@
       isReady = true
       opts = opts || {}
       send('ADDON_READY', {
-        version: '2.11.0',
+        version: '2.13.0',
         capabilities: opts.capabilities || [],
         subscribedEvents: opts.subscribedEvents || []
       })
@@ -732,6 +761,42 @@
      * })))
      */
     settings: {
+      /**
+       * Update a setting value from the addon
+       * This syncs the value back to the host UI and persists it
+       * @param {string} settingKey - The setting key to update
+       * @param {*} value - The new value
+       */
+      setValue: function (settingKey, value) {
+        if (!settingKey || typeof settingKey !== 'string') {
+          console.error('[MyWallpaper] settings.setValue: settingKey is required')
+          return
+        }
+        // Update local config immediately
+        config[settingKey] = value
+        // Send to host to update UI and persist
+        send('SETTINGS_VALUE_UPDATE', { settingKey: settingKey, value: value })
+      },
+
+      /**
+       * Update multiple setting values at once
+       * @param {Record<string, *>} values - Object with settingKey -> value pairs
+       */
+      setValues: function (values) {
+        if (!values || typeof values !== 'object') {
+          console.error('[MyWallpaper] settings.setValues: values object is required')
+          return
+        }
+        // Update local config immediately
+        for (var key in values) {
+          if (Object.prototype.hasOwnProperty.call(values, key)) {
+            config[key] = values[key]
+          }
+        }
+        // Send to host to update UI and persist
+        send('SETTINGS_VALUES_UPDATE', { values: values })
+      },
+
       /**
        * Update the options for a select-type setting
        * @param {string} settingKey - The setting key to update
@@ -790,5 +855,5 @@
     }
   }
 
-  console.warn('[MyWallpaper] SDK v2.11.0 ready:', layerId)
+  console.warn('[MyWallpaper] SDK v2.13.0 ready:', layerId)
 })()