feat: boolean feedback invert (#59)

src/host-api/api.ts

@@ -77,6 +77,7 @@ export interface UpgradedDataResponseMessage {
 			| (FeedbackInstanceBase & {
 					controlId: string
 					style?: Partial<CompanionFeedbackButtonStyleResult>
+					isInverted: boolean
 			  })
 			| undefined
 	}
@@ -117,6 +118,7 @@ export interface SetFeedbackDefinitionsMessage {
 		type: 'boolean' | 'advanced'
 		defaultStyle?: Partial<CompanionFeedbackButtonStyleResult>
 		hasLearn: boolean
+		showInvert: boolean | undefined
 	}>
 }
 
@@ -170,6 +172,8 @@ export interface FeedbackInstanceBase {
 export interface FeedbackInstance extends FeedbackInstanceBase {
 	controlId: string
 
+	isInverted: boolean
+
 	/** If control supports an imageBuffer, the dimensions the buffer must be */
 	image?: {
 		width: number

src/internal/__tests__/feedback.spec.ts

@@ -21,6 +21,7 @@ const feedback: FeedbackInstance = {
 
 	feedbackId: mockDefinitionId,
 	options: { a: 1, b: 4 },
+	isInverted: false,
 
 	controlId: 'control0',
 	image: undefined,
@@ -37,6 +38,7 @@ const feedback2: FeedbackInstance = {
 
 	feedbackId: mockDefinitionId2,
 	options: { a: 1, b: 4 },
+	isInverted: false,
 
 	controlId: 'control1',
 	image: undefined,

src/internal/feedback.ts

@@ -4,6 +4,7 @@ import {
 	CompanionFeedbackDefinition,
 	CompanionFeedbackDefinitions,
 	CompanionFeedbackInfo,
+	SomeCompanionFeedbackInputField,
 } from '../module-api/feedback'
 import {
 	FeedbackInstance,
@@ -390,8 +391,9 @@ export class FeedbackManager {
 					description: feedback.description,
 					options: serializeIsVisibleFn(feedback.options),
 					type: feedback.type,
-					defaultStyle: 'defaultStyle' in feedback ? feedback.defaultStyle : undefined,
+					defaultStyle: feedback.type === 'boolean' ? feedback.defaultStyle : undefined,
 					hasLearn: !!feedback.learn,
+					showInvert: feedback.type === 'boolean' ? feedback.showInvert : false,
 				})
 
 				// Remember the definition locally

src/internal/upgrade.ts

@@ -131,6 +131,8 @@ export function runThroughUpgradeScripts(
 									feedbackId: inst.feedbackId,
 									options: inst.options !== undefined ? clone(inst.options) : {},
 									// TODO - style?
+
+									isInverted: inst.isInverted,
 								})
 							}
 						})
@@ -165,6 +167,8 @@ export function runThroughUpgradeScripts(
 						updatedFeedbacks[feedback.id] = {
 							...instance,
 							style: updatedFeedbacks[feedback.id]?.style ?? feedback.style,
+
+							isInverted: feedback.isInverted ?? false,
 						}
 					}
 				}

src/module-api/feedback.ts

@@ -127,6 +127,12 @@ export interface CompanionBooleanFeedbackDefinition extends CompanionFeedbackDef
 	defaultStyle: Partial<CompanionFeedbackButtonStyleResult>
 	/** Called to get the feedback value */
 	callback: (feedback: CompanionFeedbackBooleanEvent, context: CompanionFeedbackContext) => boolean | Promise<boolean>
+
+	/**
+	 * If `undefined` or true, Companion will add an 'Inverted' checkbox for your feedback, and handle the logic for you.
+	 * By setting this to false, you can disable this for your feedback. You should do this if it does not make sense for your feedback.
+	 */
+	showInvert?: boolean
 }
 
 /**

src/module-api/preset.ts

@@ -26,6 +26,10 @@ export interface CompanionPresetFeedback {
 	 * If a boolean feedback, the style effect of the feedback
 	 */
 	style?: CompanionFeedbackButtonStyleResult
+	/**
+	 * If a boolean feedback, invert the value of the feedback
+	 */
+	isInverted?: boolean
 }
 
 /**
@@ -50,10 +54,10 @@ export interface CompanionButtonPresetDefinition {
 	category: string
 	/** The name of this preset */
 	name: string
-    /** The base style of this preset, this will be copied to the button */
-    style: CompanionButtonStyleProps;
+	/** The base style of this preset, this will be copied to the button */
+	style: CompanionButtonStyleProps
 	/** Preview style for preset, will be used in GUI for preview */
-	previewStyle?: CompanionButtonStyleProps;
+	previewStyle?: CompanionButtonStyleProps
 	/** Options for this preset */
 	options?: CompanionButtonPresetOptions
 	/** The feedbacks on the button */

src/module-api/upgrade.ts

@@ -88,6 +88,12 @@ export interface CompanionMigrationFeedback {
 	 * If it is already a boolean feedback or is a different type of feedback, this will be ignored.
 	 */
 	style?: Partial<CompanionFeedbackButtonStyleResult>
+
+	/**
+	 * Only valid for a boolean feedback.
+	 * True if this feedback has been inverted inside Companion, you do not have access to this when the feedback is executed.
+	 */
+	isInverted: boolean
 }
 
 /**
@@ -160,3 +166,38 @@ export function CreateConvertToBooleanFeedbackUpgradeScript<TConfig = unknown>(
 		}
 	}
 }
+
+/**
+ * A helper script to automate the bulk of the process to upgrade feedbacks from having a module defined 'invert' field, to use the builtin one.
+ * The feedback definitions must be updated manually, this can only help update existing usages of the feedback.
+ * @param upgradeMap The feedbacks to upgrade and the id of the option to convert
+ */
+export function CreateUseBuiltinInvertForFeedbacksUpgradeScript<TConfig = unknown>(
+	upgradeMap: Record<string, string>
+): CompanionStaticUpgradeScript<TConfig> {
+	// Warning: the unused parameters will often be null
+	return (_context, props) => {
+		const changedFeedbacks: CompanionStaticUpgradeResult<unknown>['updatedFeedbacks'] = []
+
+		for (const feedback of props.feedbacks) {
+			let propertyName = upgradeMap[feedback.feedbackId]
+			if (typeof propertyName !== 'string') continue
+
+			// Retrieve and delete the old value
+			const rawValue = feedback.options[propertyName]
+			if (rawValue === undefined) continue
+			delete feedback.options[propertyName]
+
+			// Interpret it to a boolean, it could be stored in a few ways
+			feedback.isInverted = rawValue === 'true' || rawValue === true || Number(rawValue) > 0
+
+			changedFeedbacks.push(feedback)
+		}
+
+		return {
+			updatedConfig: null,
+			updatedActions: [],
+			updatedFeedbacks: changedFeedbacks,
+		}
+	}
+}