@quenty/transitionmodel 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.2.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/transitionmodel@1.1.0...@quenty/transitionmodel@1.2.0) (2023-03-06)
+
+
+### Features
+
+* Add additional methods to transition model and documentation ([8466e0b](https://github.com/Quenty/NevermoreEngine/commit/8466e0bc4726c15070438bfa251992b04c5b0c15))
+
+
+
+
+
 # 1.1.0 (2023-03-05)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/transitionmodel",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Helps with Gui visiblity showing and hiding",
   "keywords": [
     "Roblox",
@@ -26,15 +26,17 @@
   ],
   "dependencies": {
     "@quenty/baseobject": "^6.2.0",
-    "@quenty/basicpane": "^7.7.0",
-    "@quenty/blend": "^6.10.0",
+    "@quenty/basicpane": "^7.8.0",
+    "@quenty/blend": "^6.11.0",
+    "@quenty/instanceutils": "^7.8.0",
     "@quenty/loader": "^6.2.0",
     "@quenty/maid": "^2.5.0",
     "@quenty/promise": "^6.3.0",
+    "@quenty/rx": "^7.7.0",
     "@quenty/signal": "^2.3.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "e62b5eac2e5d9084ab9083f128452dd2d98b6f1a"
+  "gitHead": "ce54e6f72519719e6155643418f2496f30a55f8e"
 }

package/src/Shared/SpringTransitionModel.lua

@@ -14,6 +14,14 @@ local SpringTransitionModel = setmetatable({}, BasicPane)
 SpringTransitionModel.ClassName = "SpringTransitionModel"
 SpringTransitionModel.__index = SpringTransitionModel
 
+--[=[
+	A transition model that has a spring underlying it. Very useful
+	for animations on tracks that need to be on a spring.
+
+	@param showTarget T? -- Defaults to 1
+	@param hideTarget T? -- Defaults to 0*showTarget
+	@return SpringTransitionModel<T>
+]=]
 function SpringTransitionModel.new(showTarget, hideTarget)
 	local self = setmetatable(BasicPane.new(), SpringTransitionModel)
 
@@ -42,12 +50,53 @@ function SpringTransitionModel.new(showTarget, hideTarget)
 	return self
 end
 
+--[=[
+	Returns true if showing is complete
+	@return boolean
+]=]
+function SpringTransitionModel:IsShowingComplete()
+	return self._transitionModel:IsShowingComplete()
+end
+
+--[=[
+	Returns true if hiding is complete
+	@return boolean
+]=]
+function SpringTransitionModel:IsHidingComplete()
+	return self._transitionModel:IsHidingComplete()
+end
+
+--[=[
+	Observe is showing is complete
+	@return Observable<boolean>
+]=]
+function SpringTransitionModel:ObserveIsShowingComplete()
+	return self._transitionModel:ObserveIsShowingComplete()
+end
+
+--[=[
+	Observe is hiding is complete
+	@return Observable<boolean>
+]=]
+function SpringTransitionModel:ObserveIsHidingComplete()
+	return self._transitionModel:ObserveIsHidingComplete()
+end
+
+--[=[
+	Binds the transition model to the actual visiblity of the pane
+
+	@param pane BasicPane
+	@return function -- Cleanup function
+]=]
 function SpringTransitionModel:BindToPaneVisbility(pane)
 	local maid = Maid.new()
 
 	maid:GiveTask(pane.VisibleChanged:Connect(function(isVisible, doNotAnimate)
 		self:SetVisible(isVisible, doNotAnimate)
 	end))
+	maid:GiveTask(self.VisibleChanged:Connect(function(isVisible, doNotAnimate)
+		pane:SetVisible(isVisible, doNotAnimate)
+	end))
 
 	self:SetVisible(pane:IsVisible())
 
@@ -60,46 +109,105 @@ function SpringTransitionModel:BindToPaneVisbility(pane)
 	end
 end
 
+--[=[
+	Returns the spring's velocity
+
+	@return T
+]=]
+function SpringTransitionModel:GetVelocity()
+	return self._springObject.Velocity
+end
+
+--[=[
+	Sets the springs epsilon. This can affect how long the spring takes
+	to finish.
+
+	@param epsilon number
+]=]
+function SpringTransitionModel:SetEpsilon(epsilon)
+	assert(type(epsilon) == "number", "Bad epsilon")
+
+	self._springObject.Epsilon = epsilon
+end
+
+--[=[
+	Sets the springs speed
+
+	@param speed number
+]=]
 function SpringTransitionModel:SetSpeed(speed)
+	assert(type(speed) == "number", "Bad speed")
+
 	self._springObject.Speed = speed
 end
 
+--[=[
+	Sets the springs damper
+
+	@param damper number
+]=]
 function SpringTransitionModel:SetDamper(damper)
+	assert(type(damper) == "number", "Bad damper")
+
 	self._springObject.Damper = damper
 end
 
+--[=[
+	Observes the spring animating
+	@return Observable<T>
+]=]
 function SpringTransitionModel:ObserveRenderStepped()
 	return self._springObject:ObserveRenderStepped()
 end
 
+--[=[
+	Shows the model and promises when the showing is complete.
+
+	@param doNotAnimate boolean
+	@return Promise
+]=]
 function SpringTransitionModel:PromiseShow(doNotAnimate)
 	return self._transitionModel:PromiseShow(doNotAnimate)
 end
 
+--[=[
+	Hides the model and promises when the showing is complete.
+
+	@param doNotAnimate boolean
+	@return Promise
+]=]
 function SpringTransitionModel:PromiseHide(doNotAnimate)
 	return self._transitionModel:PromiseHide(doNotAnimate)
 end
 
+--[=[
+	Toggles the model and promises when the transition is complete.
+
+	@param doNotAnimate boolean
+	@return Promise
+]=]
 function SpringTransitionModel:PromiseToggle(doNotAnimate)
 	return self._transitionModel:PromiseToggle(doNotAnimate)
 end
 
-function SpringTransitionModel:_promiseShow(maid)
-	local promise = Promise.new()
-	maid:GiveTask(promise)
-
-	self._springObject.t = self._showTarget
+function SpringTransitionModel:_promiseShow(maid, doNotAnimate)
+	self._springObject:SetTarget(self._showTarget, doNotAnimate)
 
-	return maid:GivePromise(self._springObject:PromiseFinished())
+	if doNotAnimate then
+		return Promise.resolved()
+	else
+		return maid:GivePromise(self._springObject:PromiseFinished())
+	end
 end
 
-function SpringTransitionModel:_promiseHide(maid)
-	local promise = Promise.new()
-	maid:GiveTask(promise)
+function SpringTransitionModel:_promiseHide(maid, doNotAnimate)
+	self._springObject:SetTarget(self._hideTarget, doNotAnimate)
 
-	self._springObject.t = self._hideTarget
-
-	return maid:GivePromise(self._springObject:PromiseFinished())
+	if doNotAnimate then
+		return Promise.resolved()
+	else
+		return maid:GivePromise(self._springObject:PromiseFinished())
+	end
 end
 
 return SpringTransitionModel

package/src/Shared/Sustain/SustainModel.lua

@@ -0,0 +1,145 @@
+--[=[
+	A sustain model is much like a [TransitionModel] but is responsible for
+	sustaining some animation or state. Useful to represent the sustained state
+	of an animation or something.
+
+	@class SustainModel
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local BaseObject = require("BaseObject")
+local Maid = require("Maid")
+local Promise = require("Promise")
+local Signal = require("Signal")
+
+local SustainModel = setmetatable({}, BaseObject)
+SustainModel.ClassName = "SustainModel"
+SustainModel.__index = SustainModel
+
+function SustainModel.new()
+	local self = setmetatable(BaseObject.new(), SustainModel)
+
+	self._isSustained = false
+	self._sustainCallback = nil
+
+	self.SustainChanged = Signal.new() -- :Fire(isSustained, doNotAnimate)
+	self._maid:GiveTask(self.SustainChanged)
+
+	self._maid:GiveTask(self.SustainChanged:Connect(function(isSustained, doNotAnimate)
+		if isSustained then
+			self:_executeSustain(doNotAnimate)
+		else
+			self._maid._sustaining = nil
+		end
+	end))
+
+	return self
+end
+
+--[=[
+	Sets the callback which will handle sustaining the animation.
+
+	@param sustainCallback function? -- Callback which should return a promise
+]=]
+function SustainModel:SetPromiseSustain(sustainCallback)
+	assert(type(sustainCallback) == "function" or sustainCallback == nil, "Bad sustainCallback")
+
+	self._sustainCallback = sustainCallback
+end
+
+--[=[
+	Sets whether we should be sustaining or not
+
+	@param isSustained boolean
+	@param doNotAnimate boolean? -- True if animation should be skipped
+]=]
+function SustainModel:SetIsSustained(isSustained, doNotAnimate)
+	assert(type(isSustained) == "boolean", "Bad isSustained")
+
+	if self._isSustained ~= isSustained then
+		self._isSustained = isSustained
+		self.SustainChanged:Fire(self._isSustained, doNotAnimate)
+	end
+end
+
+--[=[
+	Starts sustaining
+
+	@param doNotAnimate boolean? -- True if animation should be skipped
+]=]
+function SustainModel:Sustain(doNotAnimate)
+	self:SetIsSustained(true, doNotAnimate)
+end
+
+--[=[
+	Stops sustaining
+
+	@param doNotAnimate boolean? -- True if animation should be skipped
+]=]
+function SustainModel:Stop(doNotAnimate)
+	self:SetIsSustained(false, doNotAnimate)
+end
+
+--[=[
+	Starts sustaining. The promise will resolve when sustaining is done.
+	If sustaining is already happening, it will not start, but will continue
+	to sustain until the promise is done.
+
+	@param doNotAnimate boolean? -- True if animation should be skipped
+	@return Promise
+]=]
+function SustainModel:PromiseSustain(doNotAnimate)
+	self:Sustain(doNotAnimate)
+
+	return self:_promiseSustained()
+end
+
+function SustainModel:_promiseSustained()
+	if not self._isSustained then
+		return Promise.resolved()
+	end
+
+	local promise = Promise.new()
+
+	local maid = Maid.new()
+	self._maid[promise] = maid
+
+	maid:GiveTask(self.SustainChanged:Connect(function(isSustained)
+		if not isSustained then
+			promise:Resolve()
+		end
+	end))
+
+	promise:Finally(function()
+		self._maid[promise] = nil
+	end)
+
+	return promise
+end
+
+function SustainModel:_executeSustain(doNotAnimate)
+	local maid = Maid.new()
+
+	local promise = Promise.new()
+	maid:GiveTask(promise)
+
+	if self._sustainCallback then
+		local result = self._sustainCallback(maid, doNotAnimate)
+		if Promise.isPromise(result) then
+			promise:Resolve(result)
+		else
+			promise:Reject()
+			error(string.format("[SustainModel] - Expected promise to be returned from sustainCallback, got %q", tostring(result)))
+		end
+	end
+
+	promise:Then(function()
+		self:SetIsSustained(false, doNotAnimate)
+	end)
+
+	self._maid._sustaining = maid
+end
+
+
+return SustainModel

package/src/Shared/TransitionModel.lua

@@ -1,6 +1,6 @@
 --[=[
 	This model deduplicates and handles transitions for showing, hiding, and
-	toggling.
+	toggling. Inherits from [BasicPane]. See for more API.
 
 	@class TransitionModel
 ]=]
@@ -10,11 +10,20 @@ local require = require(script.Parent.loader).load(script)
 local BasicPane = require("BasicPane")
 local Promise = require("Promise")
 local Maid = require("Maid")
+local RxInstanceUtils = require("RxInstanceUtils")
 
 local TransitionModel = setmetatable({}, BasicPane)
 TransitionModel.ClassName = "TransitionModel"
 TransitionModel.__index = TransitionModel
 
+--[=[
+	A transition model that takes a set amount of time to show
+	and hide. Can be used just like a [BasicPane] (in fact, it
+	inherits from it), but additionally allows for variable length
+	show and hide calls.
+
+	@return TransitionModel
+]=]
 function TransitionModel.new()
 	local self = setmetatable(BasicPane.new(), TransitionModel)
 
@@ -23,9 +32,12 @@ function TransitionModel.new()
 	self._maid:GiveTask(self._isShowingComplete)
 
 	self._isHidingComplete = Instance.new("BoolValue")
-	self._isHidingComplete.Value = false
+	self._isHidingComplete.Value = true
 	self._maid:GiveTask(self._isHidingComplete)
 
+	self._showCallback = nil
+	self._hideCallback = nil
+
 	self._maid:GiveTask(self.VisibleChanged:Connect(function(visible, doNotAnimate)
 		if visible then
 			self:_executeShow(doNotAnimate)
@@ -37,18 +49,36 @@ function TransitionModel.new()
 	return self
 end
 
+--[=[
+	Shows the model and promises when the showing is complete.
+
+	@param doNotAnimate boolean
+	@return Promise
+]=]
 function TransitionModel:PromiseShow(doNotAnimate)
 	self:Show(doNotAnimate)
 
 	return self:_promiseIsShown()
 end
 
+--[=[
+	Hides the model and promises when the showing is complete.
+
+	@param doNotAnimate boolean
+	@return Promise
+]=]
 function TransitionModel:PromiseHide(doNotAnimate)
 	self:Hide(doNotAnimate)
 
 	return self:_promiseIsHidden()
 end
 
+--[=[
+	Toggles the model and promises when the transition is complete.
+
+	@param doNotAnimate boolean
+	@return Promise
+]=]
 function TransitionModel:PromiseToggle(doNotAnimate)
 	if self:IsVisible() then
 		return self:PromiseShow(doNotAnimate)
@@ -57,12 +87,53 @@ function TransitionModel:PromiseToggle(doNotAnimate)
 	end
 end
 
+--[=[
+	Returns true if showing is complete
+	@return boolean
+]=]
+function TransitionModel:IsShowingComplete()
+	return self._isShowingComplete.Value
+end
+
+--[=[
+	Returns true if hiding is complete
+	@return boolean
+]=]
+function TransitionModel:IsHidingComplete()
+	return self._isHidingComplete.Value
+end
+
+--[=[
+	Observe is showing is complete
+	@return Observable<boolean>
+]=]
+function TransitionModel:ObserveIsShowingComplete()
+	return RxInstanceUtils.observeProperty(self._isShowingComplete, "Value")
+end
+
+--[=[
+	Observe is hiding is complete
+	@return Observable<boolean>
+]=]
+function TransitionModel:ObserveIsHidingComplete()
+	return RxInstanceUtils.observeProperty(self._isHidingComplete, "Value")
+end
+
+--[=[
+	Binds the transition model to the actual visiblity of the pane
+
+	@param pane BasicPane
+	@return function -- Cleanup function
+]=]
 function TransitionModel:BindToPaneVisbility(pane)
 	local maid = Maid.new()
 
 	maid:GiveTask(pane.VisibleChanged:Connect(function(isVisible, doNotAnimate)
 		self:SetVisible(isVisible, doNotAnimate)
 	end))
+	maid:GiveTask(self.VisibleChanged:Connect(function(isVisible, doNotAnimate)
+		pane:SetVisible(isVisible, doNotAnimate)
+	end))
 
 	self:SetVisible(pane:IsVisible())
 
@@ -75,14 +146,24 @@ function TransitionModel:BindToPaneVisbility(pane)
 	end
 end
 
+--[=[
+	Sets the callback which will handle showing the transition
+
+	@param showCallback function? -- Callback which should return a promise
+]=]
 function TransitionModel:SetPromiseShow(showCallback)
-	assert(type(showCallback) == "function", "Bad showCallback")
+	assert(type(showCallback) == "function" or showCallback == nil, "Bad showCallback")
 
 	self._showCallback = showCallback
 end
 
+--[=[
+	Sets the callback which will handle hiding the transition
+
+	@param hideCallback function? -- Callback which should return a promise
+]=]
 function TransitionModel:SetPromiseHide(hideCallback)
-	assert(type(hideCallback) == "function", "Bad hideCallback")
+	assert(type(hideCallback) == "function" or hideCallback == nil, "Bad hideCallback")
 
 	self._hideCallback = hideCallback
 end
@@ -116,6 +197,7 @@ function TransitionModel:_promiseIsShown()
 	return promise
 end
 
+
 function TransitionModel:_promiseIsHidden()
 	if self._isHidingComplete.Value then
 		return Promise.resolved()
@@ -186,7 +268,7 @@ function TransitionModel:_executeHide(doNotAnimate)
 			promise:Resolve(result)
 		else
 			promise:Reject()
-			error(string.format("[TransitionModel] - Expected promise to be returned from showCallback, got %q", tostring(result)))
+			error(string.format("[TransitionModel] - Expected promise to be returned from hideCallback, got %q", tostring(result)))
 		end
 	end
 
@@ -197,5 +279,4 @@ function TransitionModel:_executeHide(doNotAnimate)
 	self._maid._transition = maid
 end
 
-
 return TransitionModel

package/src/Shared/TransitionUtils.lua

@@ -8,6 +8,17 @@ local BasicPane = require("BasicPane")
 
 local TransitionUtils = {}
 
+--[=[
+	Returns true if the value is a transition, that is, it implements the following
+	methods:
+
+	* PromiseShow
+	* PromiseHide
+	* PromiseToggle
+
+	@param value any
+	@return boolean
+]=]
 function TransitionUtils.isTransition(value)
 	return BasicPane.isBasicPane(value)
 		and type(value.PromiseShow) == "function"