@iobroker/dm-utils 1.0.0 → 1.0.2

package/README.md

@@ -114,7 +114,7 @@ In most cases, you will get all states of your instance and fill the array with
 
 Every array entry is an object of type `DeviceInfo` which has the following properties:
 
-- `id` (string): a unique (human readable) identifier of the device (it must be unique for your adapter instance only)
+- `id` (string): a unique (human-readable) identifier of the device (it must be unique for your adapter instance only)
 - `name` (string or translations): the human-readable name of this device
 - `status` (optional): the current status of the device, which can be one of:
   - `"disconnected"`
@@ -197,8 +197,8 @@ This method is called when the user clicks on a control (i.e., slider) in the de
 
 The parameters of this method are:
 - `deviceId` (string): the `id` that was given in `listDevices()` --> `[].id`
-- `controlId` (string): the `id` that was given in `listDevices()` --> `[].controls[].id`
-- `state` (string | number | boolean): new state for the control, that will be sent to real device
+- `controlId` (string): the `id` that was given in `listDevices()` --> `[].controls[].id`. There are some reserved control names, you can find the list below.
+- `state` (string | number | boolean): new state for the control, that will be sent to a real device
 - `context` (object): object containing helper methods that can be used when executing the action
 
 The returned object must contain:
@@ -226,7 +226,13 @@ To allow your adapter to interact with the user, you can use "actions".
 
 As described above, there are actions on the instance and on devices. The behavior of both methods is similar.
 
-Inside an action method (`handleInstanceAction()` or `handleDeviceAction()`) you can perform arbitrary actions, like talking to a device or API, and you can interact with the user. For interactions, there are methods you can call on `context`:
+Inside an action method (`handleInstanceAction()` or `handleDeviceAction()`) you can perform arbitrary actions, like talking to a device or API, and you can interact with the user.
+For interactions, there are methods you can call on `context`:
+
+There are some reserved action names, you can find the list below:
+- `status` - This action is called when the user clicks on the status icon. So to implement the "click-on-status" functionality, the developer has to implement this action.
+- `disable` - This action will be called when the user clicks on the `enabled` icon. `disable` and `enable` actions cannot be together.
+- `enable` - This action will be called when the user clicks on the `disabled` icon. `disable` and `enable` actions cannot be together.
 
 ### `showMessage(text: ioBroker.StringOrTranslated)`
 
@@ -295,6 +301,10 @@ This method returns a promise that resolves to a `ProgressDialog` object.
 	### **WORK IN PROGRESS**
 -->
 ## Changelog
+### 1.0.2 (2025-01-09)
+
+* (@GermanBluefox) Added description for `disabled` control and `status` action.
+
 ### 1.0.0 (2025-01-08)
 
 * (@GermanBluefox) Added `disabled` options for a device

package/build/types/base.d.ts

@@ -3,7 +3,16 @@ import type { ApiVersion, DeviceRefresh, DeviceStatus, RetVal } from './common';
 type ActionType = 'api' | 'adapter';
 export type Color = 'primary' | 'secondary' | (string & {});
 export type ControlState = string | number | boolean | null;
+/** Reserved action names */
+export declare const ACTIONS: {
+    /** This action will be called when user clicks on connection icon */
+    STATUS: string;
+    /** This action will be called when user clicks on connection icon */
+    DISABLE: string;
+    ENABLE: string;
+};
 export interface ActionBase<T extends ActionType> {
+    /** Unique (for this adapter) action ID. It could be the name from ACTIONS too, but in this case some predefined appearance will be applied */
     id: string;
     /**
      * This can either be base64 or the URL to an icon.
@@ -101,8 +110,7 @@ export interface DeviceInfo<T extends ActionType = 'api'> {
     actions?: DeviceAction<T>[];
     controls?: DeviceControl<T>[];
     hasDetails?: boolean;
-    /** undefined means, no "disabled" possibility, true means disabled, false means enabled */
-    disabled?: boolean;
+    /** Device type for grouping */
     group?: {
         key: string;
         name?: ioBroker.StringOrTranslated;

package/build/types/base.js

@@ -1,2 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACTIONS = void 0;
+/** Reserved action names */
+exports.ACTIONS = {
+    /** This action will be called when user clicks on connection icon */
+    STATUS: 'status',
+    /** This action will be called when user clicks on connection icon */
+    DISABLE: 'disable',
+    ENABLE: 'enable',
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iobroker/dm-utils",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "ioBroker Device Manager utilities for backend",
   "main": "build/index.js",
   "publishConfig": {