From 83cd6abd619e66429f0915466088083e323fcd18 Mon Sep 17 00:00:00 2001 From: Neil Dorin Date: Thu, 11 Jul 2024 08:08:33 -0600 Subject: [PATCH] docs: Updates readme and adds jdoc comments for all interface hooks --- README.md | 1 + src/lib/shared/hooks/interfaces/index.ts | 7 +++--- .../shared/hooks/interfaces/useAvrControl.ts | 6 +++++ .../shared/hooks/interfaces/useCameraBase.ts | 5 ++++- .../shared/hooks/interfaces/useEndpoint.ts | 6 ++++- .../interfaces/useIBasicVolumeWithFeedback.ts | 7 ++++++ ...useIChannelMessenger.ts => useIChannel.ts} | 5 +++++ src/lib/shared/hooks/interfaces/useIColor.ts | 5 +++++ .../interfaces/useICommunicationMonitor.ts | 6 +++++ src/lib/shared/hooks/interfaces/useIDPad.ts | 5 +++++ .../interfaces/useIDeviceInfoMessenger.ts | 6 ++++- .../shared/hooks/interfaces/useIDspPresets.ts | 5 +++++ src/lib/shared/hooks/interfaces/useIDvr.ts | 5 +++++ .../interfaces/useIEssentialsRoomCombiner.ts | 5 +++++ .../hooks/interfaces/useIHasPowerControl.ts | 5 +++++ .../interfaces/useIHasSelectableItems.ts | 3 +++ .../interfaces/useIHasSurroundChannels.ts | 6 ++++- .../hooks/interfaces/useILevelControls.ts | 6 ++++- .../hooks/interfaces/useILightingScenes.ts | 5 +++++ ...useIMcCiscoCodecUserInterfaceAppControl.ts | 5 +++++ .../shared/hooks/interfaces/useINumeric.ts | 2 +- .../useIProjectorScreenLiftControl.ts | 6 ++++- .../hooks/interfaces/useIRoomEventSchedule.ts | 6 +++++ .../interfaces/useIRunDefaultPresentRoute.ts | 9 ++++++-- .../interfaces/useIRunDirectRouteAction.ts | 5 +++++ .../hooks/interfaces/useIRunRouteAction.ts | 11 +++++++--- .../hooks/interfaces/useISetTopBoxcontrols.ts | 5 +++++ .../interfaces/useIShadesOpenCloseStop.ts | 6 ++++- .../interfaces/useIShutdownPromptTimer.ts | 17 +++++++++----- .../interfaces/useISurroundSoundModes.ts | 22 ------------------- .../hooks/interfaces/useISwitchedOutput.ts | 6 ++++- .../hooks/interfaces/useITechPassword.ts | 14 +++++++----- src/lib/shared/hooks/interfaces/useITheme.ts | 5 +++++ .../shared/hooks/interfaces/useITransport.ts | 5 +++++ .../useMobileControlTouchpanelController.ts | 5 +++++ .../hooks/interfaces/useTwoWayDisplayBase.ts | 6 ++++- src/lib/utils/WebsocketProvider.tsx | 2 +- src/lib/utils/useWebsocketContext.ts | 5 +++++ 38 files changed, 189 insertions(+), 52 deletions(-) rename src/lib/shared/hooks/interfaces/{useIChannelMessenger.ts => useIChannel.ts} (86%) delete mode 100644 src/lib/shared/hooks/interfaces/useISurroundSoundModes.ts diff --git a/README.md b/README.md index 7aa7278..3ef291d 100644 --- a/README.md +++ b/README.md @@ -24,3 +24,4 @@ From that point forward, room and device state messages from the control system ## How this Library is Intended to be Used +The intent is to use the various hooks provided in this library to easily link up to buttons and other elements on an HTML5 UI in a React App to handle the heavy lifting of integrating with the Mobile Control API. This library will provide hooks for the messengers in the Mobile Control plugin, but you will also be able to write hooks in the React App for custom API that can integrate directly with a messenger defined in any Essentials room or device plugin. This allows consistency with the core communication that most systems will rely on, while also providing easy customization and extensibility for more esoteric or application specific needs that may not see wide use and justify inclusion in this library. \ No newline at end of file diff --git a/src/lib/shared/hooks/interfaces/index.ts b/src/lib/shared/hooks/interfaces/index.ts index 3598162..1f6f8a6 100644 --- a/src/lib/shared/hooks/interfaces/index.ts +++ b/src/lib/shared/hooks/interfaces/index.ts @@ -2,7 +2,7 @@ export * from "./interfaceNames"; export * from "./useAvrControl"; export * from "./useEndpoint"; export * from "./useIBasicVolumeWithFeedback"; -export * from "./useIChannelMessenger"; +export * from "./useIChannel"; export * from "./useIColor"; export * from "./useICommunicationMonitor"; export * from "./useIDPad"; @@ -19,6 +19,7 @@ export * from "./useIMcCiscoCodecUserInterfaceAppControl"; export * from "./useINumeric"; export * from "./useIProjectorScreenLiftControl"; export * from "./useIRoomEventSchedule"; +export * from "./useIRunDefaultPresentRoute"; export * from "./useIRunDirectRouteAction"; export * from "./useIRunRouteAction"; export * from "./useISetTopBoxcontrols"; @@ -26,8 +27,8 @@ export * from "./useIShadesOpenCloseStop"; export * from "./useIShutdownPromptTimer"; export * from "./useISwitchedOutput"; export * from "./useITechPassword"; +export * from "./useITheme"; export * from "./useITransport"; export * from "./useMobileControlTouchpanelController"; export * from "./useTwoWayDisplayBase"; -export * from "./useIRunDefaultPresentRoute"; -export * from "./useITheme"; + diff --git a/src/lib/shared/hooks/interfaces/useAvrControl.ts b/src/lib/shared/hooks/interfaces/useAvrControl.ts index f69529b..6ec1e96 100644 --- a/src/lib/shared/hooks/interfaces/useAvrControl.ts +++ b/src/lib/shared/hooks/interfaces/useAvrControl.ts @@ -8,6 +8,12 @@ import { IHasPowerWithFeedbackProps, useIHasPowerControl } from './useIHasPowerC import { IHasSelectableItemsReturn, useIHasSelectableItems } from './useIHasSelectableItems'; import { IHasSurroundChannelsReturn, useIHasSurroundChannels } from './useIHasSurroundChannels'; + +/** + * Provides a set of hooks to control an AVR device + * @param key key of the device + * @returns + */ export function useAvrControl(key: string): AvrReturn | undefined { const avrState = useGetDevice(key); const powerControl = useIHasPowerControl(key); diff --git a/src/lib/shared/hooks/interfaces/useCameraBase.ts b/src/lib/shared/hooks/interfaces/useCameraBase.ts index dc05c18..9cc1213 100644 --- a/src/lib/shared/hooks/interfaces/useCameraBase.ts +++ b/src/lib/shared/hooks/interfaces/useCameraBase.ts @@ -1,7 +1,10 @@ import { CameraState, PressHoldReleaseReturn, useGetDevice, useWebsocketContext } from 'src/lib'; import { useButtonHeldHeartbeat } from '../useHeldButtonAction'; - +/** + * Provides a set of hooks to control a device that extends the CameraBase class + * @param key key of the device + */ export function useCameraBase(key: string): CameraBaseProps | undefined{ const { sendMessage } = useWebsocketContext(); const path = `/device/${key}`; diff --git a/src/lib/shared/hooks/interfaces/useEndpoint.ts b/src/lib/shared/hooks/interfaces/useEndpoint.ts index de1ccc2..120a5b1 100644 --- a/src/lib/shared/hooks/interfaces/useEndpoint.ts +++ b/src/lib/shared/hooks/interfaces/useEndpoint.ts @@ -1,7 +1,11 @@ import { useGetDevice } from 'src/lib'; import { EndpointState } from 'src/lib/types/state/state/endpointState/endpointState'; - +/** + * A hook that provides access to the endpoint state + * @param key the key of the endpoint + * @returns + */ export function useEndpoint(key: string): IEndpointReturn | undefined { const endpointState = useGetDevice(key); diff --git a/src/lib/shared/hooks/interfaces/useIBasicVolumeWithFeedback.ts b/src/lib/shared/hooks/interfaces/useIBasicVolumeWithFeedback.ts index ef00171..a5c1b30 100644 --- a/src/lib/shared/hooks/interfaces/useIBasicVolumeWithFeedback.ts +++ b/src/lib/shared/hooks/interfaces/useIBasicVolumeWithFeedback.ts @@ -3,6 +3,12 @@ import { useWebsocketContext } from "src/lib/utils/useWebsocketContext"; import { useButtonHeldHeartbeat } from "../useHeldButtonAction"; import { PressHoldReleaseReturn } from "../usePressHoldRelease"; +/** + * hook to control a volume device that implements the IBasicVolumeWithFeedback interface + * @param path path prefix to for the device. i.e. /device/{key} or /room/{key} + * @param volumeState + * @returns + */ export function useIBasicVolumeWithFeedback( path: string, volumeState: Volume | undefined ): IBasicVolumeWithFeedbackReturn | undefined { @@ -43,6 +49,7 @@ export interface IBasicVolumeWithFeedbackReturn { muteOff: () => void; } + export function useGetIBasicVolumeWithFeedback( path: string, volumeState: Volume | undefined ): IBasicVolumeWithFeedbackReturn | undefined { diff --git a/src/lib/shared/hooks/interfaces/useIChannelMessenger.ts b/src/lib/shared/hooks/interfaces/useIChannel.ts similarity index 86% rename from src/lib/shared/hooks/interfaces/useIChannelMessenger.ts rename to src/lib/shared/hooks/interfaces/useIChannel.ts index 56b467e..b6bcc97 100644 --- a/src/lib/shared/hooks/interfaces/useIChannelMessenger.ts +++ b/src/lib/shared/hooks/interfaces/useIChannel.ts @@ -1,6 +1,11 @@ import { useButtonHeldHeartbeat } from '../useHeldButtonAction'; import { PressHoldReleaseReturn } from '../usePressHoldRelease'; +/** + * hook to control a channel messenger device that implements the IChannelMessenger interface + * @param key the key of the device + * @returns + */ export function useIChannelMessenger(key: string): IChannelMessengerProps | undefined { const path = `/device/${key}`; diff --git a/src/lib/shared/hooks/interfaces/useIColor.ts b/src/lib/shared/hooks/interfaces/useIColor.ts index 6a40f4e..b137e79 100644 --- a/src/lib/shared/hooks/interfaces/useIColor.ts +++ b/src/lib/shared/hooks/interfaces/useIColor.ts @@ -1,6 +1,11 @@ import { useButtonHeldHeartbeat } from '../useHeldButtonAction'; import { PressHoldReleaseReturn } from '../usePressHoldRelease'; +/** + * hook to control a device that implements the IColor interface + * @param key + * @returns + */ export function useIColor(key: string): IColorProps | undefined { const path = `/device/${key}`; diff --git a/src/lib/shared/hooks/interfaces/useICommunicationMonitor.ts b/src/lib/shared/hooks/interfaces/useICommunicationMonitor.ts index 4e02bf1..7f2d818 100644 --- a/src/lib/shared/hooks/interfaces/useICommunicationMonitor.ts +++ b/src/lib/shared/hooks/interfaces/useICommunicationMonitor.ts @@ -1,5 +1,11 @@ import { CommunicationMonitorState, useGetDevice } from 'src/lib'; + +/** + * hook to control a device that implements the ICommunicationMonitor interface + * @param key key of the device + * @returns + */ export function useICommunicationMonitor(key: string): ICommunicationMonitorReturn | undefined { const device = useGetDevice(key); diff --git a/src/lib/shared/hooks/interfaces/useIDPad.ts b/src/lib/shared/hooks/interfaces/useIDPad.ts index 7ff655e..ae1d08b 100644 --- a/src/lib/shared/hooks/interfaces/useIDPad.ts +++ b/src/lib/shared/hooks/interfaces/useIDPad.ts @@ -1,6 +1,11 @@ import { useButtonHeldHeartbeat } from "../useHeldButtonAction"; import { PressHoldReleaseReturn } from "../usePressHoldRelease"; +/** + * hook to control a device that implements the IDPad interface + * @param key key of the device + * @returns + */ export function useIDPad(key: string): IDPadProps | undefined { const path = `/device/${key}`; diff --git a/src/lib/shared/hooks/interfaces/useIDeviceInfoMessenger.ts b/src/lib/shared/hooks/interfaces/useIDeviceInfoMessenger.ts index 2f1cb63..bc0916b 100644 --- a/src/lib/shared/hooks/interfaces/useIDeviceInfoMessenger.ts +++ b/src/lib/shared/hooks/interfaces/useIDeviceInfoMessenger.ts @@ -1,6 +1,10 @@ import { DeviceInfo, DeviceInfoState, useGetDevice } from 'src/lib'; - +/** + * hook that returns the info for a device that implements the IDeviceInfo interface + * @param key key of the device + * @returns + */ export function useIDeviceInfoMessenger(key: string): DeviceInfo | undefined { const device = useGetDevice(key); diff --git a/src/lib/shared/hooks/interfaces/useIDspPresets.ts b/src/lib/shared/hooks/interfaces/useIDspPresets.ts index f92a527..2a7aa36 100644 --- a/src/lib/shared/hooks/interfaces/useIDspPresets.ts +++ b/src/lib/shared/hooks/interfaces/useIDspPresets.ts @@ -1,5 +1,10 @@ import { IKeyName, useWebsocketContext } from 'src/lib'; +/** + * hook to control a device that implements the IDspPresets interface + * @param key key of the device + * @returns + */ export function useIDspPresets(key: string) { const { sendMessage } = useWebsocketContext(); diff --git a/src/lib/shared/hooks/interfaces/useIDvr.ts b/src/lib/shared/hooks/interfaces/useIDvr.ts index 67c11dd..b7fe398 100644 --- a/src/lib/shared/hooks/interfaces/useIDvr.ts +++ b/src/lib/shared/hooks/interfaces/useIDvr.ts @@ -1,6 +1,11 @@ import { useButtonHeldHeartbeat } from '../useHeldButtonAction'; import { PressHoldReleaseReturn } from '../usePressHoldRelease'; +/** + * hook to control a device that implements the IDvr interface + * @param key key of the device + * @returns + */ export function useIDvr(key: string): IDvrProps | undefined { const path = `/device/${key}`; diff --git a/src/lib/shared/hooks/interfaces/useIEssentialsRoomCombiner.ts b/src/lib/shared/hooks/interfaces/useIEssentialsRoomCombiner.ts index 45341cb..07b6d7b 100644 --- a/src/lib/shared/hooks/interfaces/useIEssentialsRoomCombiner.ts +++ b/src/lib/shared/hooks/interfaces/useIEssentialsRoomCombiner.ts @@ -2,6 +2,11 @@ import { useGetDevice } from 'src/lib/store'; import { IEssentialsRoomCombinerState } from 'src/lib/types/state/state/IEssentialsRoomCombinerState'; import { useWebsocketContext } from 'src/lib/utils'; +/** + * hook to control a device that implements the IEssentialsRoomCombiner interface + * @param key key of the device + * @returns + */ export function useIEssentialsRoomCombiner(key: string): IEssentialsRoomCombinerReturn | undefined { const { sendMessage } = useWebsocketContext(); const roomCombinerState = useGetDevice(key) as IEssentialsRoomCombinerState | undefined; diff --git a/src/lib/shared/hooks/interfaces/useIHasPowerControl.ts b/src/lib/shared/hooks/interfaces/useIHasPowerControl.ts index c93389d..6e8ef6b 100644 --- a/src/lib/shared/hooks/interfaces/useIHasPowerControl.ts +++ b/src/lib/shared/hooks/interfaces/useIHasPowerControl.ts @@ -1,5 +1,10 @@ import { useWebsocketContext } from 'src/lib/utils/useWebsocketContext'; +/** + * hook to control a device that implements the IHasPowerControl interface + * @param key key of the device + * @returns + */ export function useIHasPowerControl(key: string): IHasPowerWithFeedbackProps { const { sendMessage } = useWebsocketContext(); diff --git a/src/lib/shared/hooks/interfaces/useIHasSelectableItems.ts b/src/lib/shared/hooks/interfaces/useIHasSelectableItems.ts index b5d8fd3..23730f5 100644 --- a/src/lib/shared/hooks/interfaces/useIHasSelectableItems.ts +++ b/src/lib/shared/hooks/interfaces/useIHasSelectableItems.ts @@ -1,9 +1,12 @@ import { useGetDevice } from 'src/lib/store'; import { useWebsocketContext } from 'src/lib/utils/useWebsocketContext'; + /** * Hook for devices that have selectable items * TState is the type of the expected state of the device + * @param key key of the device + * @returns */ export function useIHasSelectableItems(key: string): IHasSelectableItemsReturn | undefined { const { sendMessage } = useWebsocketContext(); diff --git a/src/lib/shared/hooks/interfaces/useIHasSurroundChannels.ts b/src/lib/shared/hooks/interfaces/useIHasSurroundChannels.ts index 98001f4..3d5bfc4 100644 --- a/src/lib/shared/hooks/interfaces/useIHasSurroundChannels.ts +++ b/src/lib/shared/hooks/interfaces/useIHasSurroundChannels.ts @@ -1,7 +1,11 @@ import { LevelControlsState, Volume, useGetDevice } from 'src/lib'; import { useWebsocketContext } from 'src/lib/utils/useWebsocketContext'; - +/** + * hook to control a device that implements the IHasSurroundChannels interface + * @param key key of the device + * @returns + */ export function useIHasSurroundChannels(key: string): IHasSurroundChannelsReturn | undefined { const { sendMessage } = useWebsocketContext(); diff --git a/src/lib/shared/hooks/interfaces/useILevelControls.ts b/src/lib/shared/hooks/interfaces/useILevelControls.ts index b8e829e..3e80a25 100644 --- a/src/lib/shared/hooks/interfaces/useILevelControls.ts +++ b/src/lib/shared/hooks/interfaces/useILevelControls.ts @@ -2,7 +2,11 @@ import { useGetDevice, useRoomLevelControls } from 'src/lib/store'; import { LevelControlsState } from 'src/lib/types/state/state/LevelControlsState'; import { useWebsocketContext } from 'src/lib/utils/useWebsocketContext'; - +/** + * hook that controls a device that implements the ILevelControls interface + * @param key key of the device + * @returns + */ export function useILevelControls(key: string): ILevelControlsReturn | undefined { const { sendMessage, sendSimpleMessage } = useWebsocketContext(); const device = useGetDevice(key); diff --git a/src/lib/shared/hooks/interfaces/useILightingScenes.ts b/src/lib/shared/hooks/interfaces/useILightingScenes.ts index 7fa806e..11915bc 100644 --- a/src/lib/shared/hooks/interfaces/useILightingScenes.ts +++ b/src/lib/shared/hooks/interfaces/useILightingScenes.ts @@ -2,6 +2,11 @@ import { useGetDevice } from 'src/lib/store'; import { LightingScene, LightingState } from 'src/lib/types'; import { useWebsocketContext } from 'src/lib/utils/useWebsocketContext'; +/** + * hook to control a device that implements the ILightingScenes interface + * @param key key of the device + * @returns + */ export function useILightingScenes(key: string): ILightingScenesReturn | undefined { const { sendMessage } = useWebsocketContext(); const state = useGetDevice(key); diff --git a/src/lib/shared/hooks/interfaces/useIMcCiscoCodecUserInterfaceAppControl.ts b/src/lib/shared/hooks/interfaces/useIMcCiscoCodecUserInterfaceAppControl.ts index 4c68758..5e53bd0 100644 --- a/src/lib/shared/hooks/interfaces/useIMcCiscoCodecUserInterfaceAppControl.ts +++ b/src/lib/shared/hooks/interfaces/useIMcCiscoCodecUserInterfaceAppControl.ts @@ -1,5 +1,10 @@ import { useWebsocketContext } from 'src/lib/utils'; +/** + * hook to control a device that implements the IMcCiscoCodecUserInterfaceAppControl interface + * @param key key of the device + * @returns + */ export function useIMcCiscoCodecUserInterfaceAppControl(key: string) { const { sendMessage } = useWebsocketContext(); diff --git a/src/lib/shared/hooks/interfaces/useINumeric.ts b/src/lib/shared/hooks/interfaces/useINumeric.ts index cc081fb..4c02b89 100644 --- a/src/lib/shared/hooks/interfaces/useINumeric.ts +++ b/src/lib/shared/hooks/interfaces/useINumeric.ts @@ -2,7 +2,7 @@ import { useButtonHeldHeartbeat } from '../useHeldButtonAction'; import { PressHoldReleaseReturn } from '../usePressHoldRelease'; /** - * hook to return the functions to trigger for a numeric keypad + * hook to return the functions to trigger for a numeric keypad for a device that implements the INumeric interface * @param key device key * @returns */ diff --git a/src/lib/shared/hooks/interfaces/useIProjectorScreenLiftControl.ts b/src/lib/shared/hooks/interfaces/useIProjectorScreenLiftControl.ts index f79ecf8..98eeb02 100644 --- a/src/lib/shared/hooks/interfaces/useIProjectorScreenLiftControl.ts +++ b/src/lib/shared/hooks/interfaces/useIProjectorScreenLiftControl.ts @@ -1,6 +1,10 @@ import { IProjectorScreenLiftControlState, useGetDevice, useWebsocketContext } from 'src/lib'; - +/** + * hook to control a device that implements the IProjectorScreenLiftControl interface + * @param key key of the device + * @returns + */ export function useIProjectorScreenLiftControl(key: string): IProjectorScreenLiftControlReturn | undefined { const { sendMessage } = useWebsocketContext(); const projectorScreenLiftControlState = useGetDevice(key) as IProjectorScreenLiftControlState | undefined; diff --git a/src/lib/shared/hooks/interfaces/useIRoomEventSchedule.ts b/src/lib/shared/hooks/interfaces/useIRoomEventSchedule.ts index d1576bb..62c0553 100644 --- a/src/lib/shared/hooks/interfaces/useIRoomEventSchedule.ts +++ b/src/lib/shared/hooks/interfaces/useIRoomEventSchedule.ts @@ -1,6 +1,12 @@ import { ScheduleEvent, ScheduleState, useRoomState } from 'src/lib'; import { useWebsocketContext } from 'src/lib/utils/useWebsocketContext'; + +/** + * hook to control a device that implements the IRoomEventSchedule interface + * @param key key of the device + * @returns + */ export function useIRoomEventSchedule(key: string): IRoomEventScheduleReturn | undefined { const { sendMessage } = useWebsocketContext(); const roomEventScheduleState = useRoomState(key) as ScheduleState | undefined; diff --git a/src/lib/shared/hooks/interfaces/useIRunDefaultPresentRoute.ts b/src/lib/shared/hooks/interfaces/useIRunDefaultPresentRoute.ts index e7d8dfe..f5a8f44 100644 --- a/src/lib/shared/hooks/interfaces/useIRunDefaultPresentRoute.ts +++ b/src/lib/shared/hooks/interfaces/useIRunDefaultPresentRoute.ts @@ -1,10 +1,15 @@ import { useWebsocketContext } from "src/lib/utils"; -export function useIRunDefaultPresentRoute(key: string):IRunDefaultPresentRouteProps { +/** + * hook to control a room that implements the IRunDefaultPresentRoute interface + * @param roomKey key of the room + * @returns + */ +export function useIRunDefaultPresentRoute(roomKey: string):IRunDefaultPresentRouteProps { const { sendMessage } = useWebsocketContext(); const runDefaultPresentRoute = () => { - sendMessage(`/room/${key}/defaultsource`, {}); + sendMessage(`/room/${roomKey}/defaultsource`, {}); }; return {runDefaultPresentRoute} diff --git a/src/lib/shared/hooks/interfaces/useIRunDirectRouteAction.ts b/src/lib/shared/hooks/interfaces/useIRunDirectRouteAction.ts index 8891512..634f80f 100644 --- a/src/lib/shared/hooks/interfaces/useIRunDirectRouteAction.ts +++ b/src/lib/shared/hooks/interfaces/useIRunDirectRouteAction.ts @@ -1,5 +1,10 @@ import { useWebsocketContext } from 'src/lib/utils/useWebsocketContext'; +/** + * + * @param roomKey key of the room + * @returns + */ export function useIRunDirectRouteAction(roomKey: string): IRunDirectRouteActionProps { const { sendMessage } = useWebsocketContext(); diff --git a/src/lib/shared/hooks/interfaces/useIRunRouteAction.ts b/src/lib/shared/hooks/interfaces/useIRunRouteAction.ts index 670e831..5b08f2f 100644 --- a/src/lib/shared/hooks/interfaces/useIRunRouteAction.ts +++ b/src/lib/shared/hooks/interfaces/useIRunRouteAction.ts @@ -2,12 +2,17 @@ import { useGetDevice } from 'src/lib/store'; import { RoutingState } from 'src/lib/types'; import { useWebsocketContext } from 'src/lib/utils/useWebsocketContext'; -export function useIRunRouteAction(key: string): IRunRouteActionProps | undefined { +/** + * hook to control a room that implements the IRunRouteAction interface + * @param roomKey key of the room + * @returns + */ +export function useIRunRouteAction(roomKey: string): IRunRouteActionProps | undefined { const { sendMessage } = useWebsocketContext(); - const routingState = useGetDevice(key); + const routingState = useGetDevice(roomKey); const runRoute = (request: RouteRequest) => { - sendMessage(`/room/${key}/source`, request); + sendMessage(`/room/${roomKey}/source`, request); }; return { routingState, runRoute }; diff --git a/src/lib/shared/hooks/interfaces/useISetTopBoxcontrols.ts b/src/lib/shared/hooks/interfaces/useISetTopBoxcontrols.ts index 9fc153a..15ca29d 100644 --- a/src/lib/shared/hooks/interfaces/useISetTopBoxcontrols.ts +++ b/src/lib/shared/hooks/interfaces/useISetTopBoxcontrols.ts @@ -1,6 +1,11 @@ import { useButtonHeldHeartbeat } from '../useHeldButtonAction'; import { PressHoldReleaseReturn } from '../usePressHoldRelease'; +/** + * hook to control a device that implements the ISetTopBoxControls interface + * @param key key of the device + * @returns + */ export function useISetTopBoxControls(key: string): ISetTopBoxControlsProps { const path = `/device/${key}`; diff --git a/src/lib/shared/hooks/interfaces/useIShadesOpenCloseStop.ts b/src/lib/shared/hooks/interfaces/useIShadesOpenCloseStop.ts index 4ca71ea..3ebc6fd 100644 --- a/src/lib/shared/hooks/interfaces/useIShadesOpenCloseStop.ts +++ b/src/lib/shared/hooks/interfaces/useIShadesOpenCloseStop.ts @@ -2,7 +2,11 @@ import { useGetDevice } from 'src/lib/store'; import { ShadeState } from 'src/lib/types'; import { useWebsocketContext } from 'src/lib/utils/useWebsocketContext'; - +/** + * hook that controls a device that implements the IShadesOpenCloseStop interface + * @param key key of the device + * @returns + */ export function useIShadesOpenCloseStop(key: string): IShadesOpenCloseStopProps | undefined { const { sendMessage } = useWebsocketContext(); const shadeState = useGetDevice(key); diff --git a/src/lib/shared/hooks/interfaces/useIShutdownPromptTimer.ts b/src/lib/shared/hooks/interfaces/useIShutdownPromptTimer.ts index 3950312..4832083 100644 --- a/src/lib/shared/hooks/interfaces/useIShutdownPromptTimer.ts +++ b/src/lib/shared/hooks/interfaces/useIShutdownPromptTimer.ts @@ -3,26 +3,31 @@ import { useRoomState } from 'src/lib'; import { IShutdownPromptTimerState } from 'src/lib/types/state/state/IShutdownPromptTimerState'; import { useWebsocketContext } from 'src/lib/utils/useWebsocketContext'; -export function useIShutdownPromptTimer(key: string): IShutdownPromptTimerReturn | undefined { +/** + * hook that controls a room that implements the IShutdownPromptTimer interface + * @param roomKey key of the room + * @returns + */ +export function useIShutdownPromptTimer(roomKey: string): IShutdownPromptTimerReturn | undefined { const { sendMessage } = useWebsocketContext(); - const shutdownPromptTimerState = useRoomState(key) as IShutdownPromptTimerState | undefined; + const shutdownPromptTimerState = useRoomState(roomKey) as IShutdownPromptTimerState | undefined; if (!shutdownPromptTimerState) return undefined; const setShutdownPromptSeconds = (seconds: number) => { - sendMessage(`/room/${key}/setShutdownPromptSeconds`, seconds); + sendMessage(`/room/${roomKey}/setShutdownPromptSeconds`, seconds); }; const shutdownStart = () => { - sendMessage(`/room/${key}/shutdownStart`, null); + sendMessage(`/room/${roomKey}/shutdownStart`, null); }; const shutdownEnd = () => { - sendMessage(`/room/${key}/shutdownEnd`, null); + sendMessage(`/room/${roomKey}/shutdownEnd`, null); }; const shutdownCancel = () => { - sendMessage(`/room/${key}/shutdownCancel`, null); + sendMessage(`/room/${roomKey}/shutdownCancel`, null); }; return { shutdownPromptTimerState, setShutdownPromptSeconds, shutdownStart, shutdownEnd, shutdownCancel}; diff --git a/src/lib/shared/hooks/interfaces/useISurroundSoundModes.ts b/src/lib/shared/hooks/interfaces/useISurroundSoundModes.ts deleted file mode 100644 index 5e7d3cc..0000000 --- a/src/lib/shared/hooks/interfaces/useISurroundSoundModes.ts +++ /dev/null @@ -1,22 +0,0 @@ -// import { useGetDevice } from 'src/lib/store'; -// import { SurroundSoundModeState } from 'src/lib/types'; -// import { useWebsocketContext } from 'src/lib/utils/useWebsocketContext'; - - -// export function useISurroundSoundModes(key: string): ISurroundSoundModesReturn | undefined { -// const { sendMessage } = useWebsocketContext(); -// const device = useGetDevice(key); - -// if (!device) return undefined; - -// const setMode = (mode: string) => { -// sendMessage(`/device/${key}/${mode}`, null); -// }; - -// return { modeState: device, setMode }; -// } - -// export interface ISurroundSoundModesReturn { -// modeState: SurroundSoundModeState; -// setMode: (inputKey: string) => void; -// } \ No newline at end of file diff --git a/src/lib/shared/hooks/interfaces/useISwitchedOutput.ts b/src/lib/shared/hooks/interfaces/useISwitchedOutput.ts index 749ada1..ee86e87 100644 --- a/src/lib/shared/hooks/interfaces/useISwitchedOutput.ts +++ b/src/lib/shared/hooks/interfaces/useISwitchedOutput.ts @@ -2,7 +2,11 @@ import { useGetDevice } from 'src/lib/store'; import { SwitchedOutputState } from 'src/lib/types'; import { useWebsocketContext } from 'src/lib/utils/useWebsocketContext'; - +/** + * hook that controls a device that implements the ISwitchedOutput interface + * @param key key of the device + * @returns + */ export function useISwitchedOutput(key: string): ISwitchedOutputReturn | undefined { const { sendMessage } = useWebsocketContext(); const device = useGetDevice(key); diff --git a/src/lib/shared/hooks/interfaces/useITechPassword.ts b/src/lib/shared/hooks/interfaces/useITechPassword.ts index 9b07cdb..0cea505 100644 --- a/src/lib/shared/hooks/interfaces/useITechPassword.ts +++ b/src/lib/shared/hooks/interfaces/useITechPassword.ts @@ -2,19 +2,23 @@ import { useRoomState } from 'src/lib'; import { ITechPasswordState } from 'src/lib/types/state/state/ITechPasswordState'; import { useWebsocketContext } from 'src/lib/utils'; - -export function useITechPassword(key: string): ITechPasswordReturn | undefined { +/** + * hook that controls a room that implements the ITechPassword interface + * @param roomKey key of the room + * @returns + */ +export function useITechPassword(roomKey: string): ITechPasswordReturn | undefined { const { sendMessage } = useWebsocketContext(); - const techPasswordState = useRoomState(key) as ITechPasswordState | undefined; + const techPasswordState = useRoomState(roomKey) as ITechPasswordState | undefined; if(!techPasswordState) return undefined; const validatePassword = (password: string) => { - sendMessage(`/room/${key}/validateTechPassword`, {password}); + sendMessage(`/room/${roomKey}/validateTechPassword`, {password}); }; const setPassword = (oldPassword: string, newPassword: string) => { - sendMessage(`/room/${key}/setTechPassword`, {oldPassword, newPassword}); + sendMessage(`/room/${roomKey}/setTechPassword`, {oldPassword, newPassword}); }; return { techPasswordState, validatePassword, setPassword }; diff --git a/src/lib/shared/hooks/interfaces/useITheme.ts b/src/lib/shared/hooks/interfaces/useITheme.ts index 2996751..5ae97eb 100644 --- a/src/lib/shared/hooks/interfaces/useITheme.ts +++ b/src/lib/shared/hooks/interfaces/useITheme.ts @@ -2,6 +2,11 @@ import { useGetDevice } from "src/lib"; import { MobileControlTouchpanelState } from "src/lib/types/state/state/MobileControlTouchpanelState"; import { useWebsocketContext } from "src/lib/utils"; +/** + * hook that controls a device that implements the ITheme interface + * @param touchpanelKey key of the touchpanel + * @returns + */ export function useITheme(touchpanelKey: string):IThemeReturn { const { sendMessage } = useWebsocketContext(); const tpState = useGetDevice(touchpanelKey); diff --git a/src/lib/shared/hooks/interfaces/useITransport.ts b/src/lib/shared/hooks/interfaces/useITransport.ts index acfa7d6..1c901e5 100644 --- a/src/lib/shared/hooks/interfaces/useITransport.ts +++ b/src/lib/shared/hooks/interfaces/useITransport.ts @@ -1,6 +1,11 @@ import { useButtonHeldHeartbeat } from '../useHeldButtonAction'; import { PressHoldReleaseReturn } from '../usePressHoldRelease'; +/** + * hook that controls a device that implements the ITransport interface + * @param key key of the device + * @returns + */ export function useITransport(key: string): ITransportProps | undefined { const path = `/device/${key}`; diff --git a/src/lib/shared/hooks/interfaces/useMobileControlTouchpanelController.ts b/src/lib/shared/hooks/interfaces/useMobileControlTouchpanelController.ts index d531410..35a804d 100644 --- a/src/lib/shared/hooks/interfaces/useMobileControlTouchpanelController.ts +++ b/src/lib/shared/hooks/interfaces/useMobileControlTouchpanelController.ts @@ -2,6 +2,11 @@ import { useGetDevice } from "src/lib/store"; import { MobileControlTouchpanelState } from "src/lib/types/state/state/MobileControlTouchpanelState"; import { useWebsocketContext } from "src/lib/utils/useWebsocketContext"; +/** + * hook that controls a device that implements the MobileControlTouchpanelController interface + * @param key key of the device + * @returns + */ export function useMobileControlTouchpanelController( key: string ): MobileControlTouchpanelControllerReturn | undefined { diff --git a/src/lib/shared/hooks/interfaces/useTwoWayDisplayBase.ts b/src/lib/shared/hooks/interfaces/useTwoWayDisplayBase.ts index 2b36b82..f393ea4 100644 --- a/src/lib/shared/hooks/interfaces/useTwoWayDisplayBase.ts +++ b/src/lib/shared/hooks/interfaces/useTwoWayDisplayBase.ts @@ -7,7 +7,11 @@ import { } from "./useIHasPowerControl"; import { IHasSelectableItemsReturn, useIHasSelectableItems } from './useIHasSelectableItems'; - +/** + * Provides a set of hooks to control a device that extends the TwoWayDisplayBase class + * @param key key of the device + * @returns + */ export function useTwoWayDisplayBase( key: string ): TwoWayDisplayBaseReturn | undefined { diff --git a/src/lib/utils/WebsocketProvider.tsx b/src/lib/utils/WebsocketProvider.tsx index c61c55c..ca14f5c 100644 --- a/src/lib/utils/WebsocketProvider.tsx +++ b/src/lib/utils/WebsocketProvider.tsx @@ -23,7 +23,7 @@ import WebsocketContext from "./WebsocketContext"; import { loadValue, saveValue } from "./joinParamsService"; /** - * The context component that contains the websocket connection and provides the sendMessage function + * The context component that contains the websocket connection and provides the functions to send messages * Must wrap all other components * @param children the child components. First child should be a room buseness logic component */ diff --git a/src/lib/utils/useWebsocketContext.ts b/src/lib/utils/useWebsocketContext.ts index 963964e..1262dd5 100644 --- a/src/lib/utils/useWebsocketContext.ts +++ b/src/lib/utils/useWebsocketContext.ts @@ -1,6 +1,11 @@ import { useContext } from "react"; import WebsocketContext from "./WebsocketContext"; + +/** + * A hook that provides access to the websocket for the purposes of sending messages as well as adding and removing event handlers + * @returns The websocket context + */ export function useWebsocketContext() { return useContext(WebsocketContext); }