createRef API

docs/api-reference.md

@@ -61,6 +61,13 @@ If `children` contains more than one child, `oneChild` function will throw an er
 
 If `children` is `nil` or contains no children, `oneChild` will return `nil`.
 
+### Roact.createRef
+```
+Roact.createRef() -> Ref
+```
+
+Creates a new reference object that can be used with [Roact.Ref](#roactref).
+
 ## Constants
 
 ### Roact.Children
@@ -71,14 +78,38 @@ If you're writing a new functional or stateful element that needs to be used lik
 ### Roact.Ref
 Use `Roact.Ref` as a key into the props of a primitive element to receive a handle to the underlying Roblox Instance.
 
+`Ref` may either be a function:
 ```lua
 Roact.createElement("Frame", {
+	-- The function given will be called whenever the rendered instance changes.
 	[Roact.Ref] = function(rbx)
 		print("Roblox Instance", rbx)
 	end,
 })
 ```
 
+Or a reference object created with [createRef](#roactcreateref):
+```lua
+local ExampleComponent = Roact.Component:extend("ExampleComponent")
+
+function ExampleComponent:init()
+	-- Create a reference object.
+	self.ref = Roact.createRef()
+end
+
+function ExampleComponent:render()
+	return Roact.createElement("Frame", {
+		-- Use the reference object to point to this rendered instance.
+		[Roact.Ref] = ref,
+	})
+end
+
+function ExampleComponent:didMount()
+	-- Access the current value of a reference object using its current property.
+	print("Roblox Instance", self.ref.current)
+end
+```
+
 !!! warning
 	`Roact.Ref` will be called with `nil` when the component instance is destroyed!
 

lib/Reconciler.lua

@@ -44,6 +44,22 @@ local function isPortal(element)
 	return element.component == Core.Portal
 end
 
+--[[
+	Sets the value of a reference to a new rendered object.
+	Correctly handles both function-style and object-style refs.
+]]
+local function applyRef(ref, newRbx)
+	if ref == nil then
+		return
+	end
+
+	if type(ref) == "table" then
+		ref.current = newRbx
+	else
+		ref(newRbx)
+	end
+end
+
 local Reconciler = {}
 
 Reconciler._singleEventManager = SingleEventManager.new()
@@ -93,9 +109,7 @@ function Reconciler.unmount(instanceHandle)
 
 		-- Kill refs before we make changes, since any mutations past this point
 		-- aren't relevant to components.
-		if element.props[Core.Ref] then
-			element.props[Core.Ref](nil)
-		end
+		applyRef(element.props[Core.Ref], nil)
 
 		for _, child in pairs(instanceHandle._children) do
 			Reconciler.unmount(child)
@@ -173,9 +187,7 @@ function Reconciler._mountInternal(element, parent, key, context)
 		rbx.Parent = parent
 
 		-- Attach ref values, since the instance is initialized now.
-		if element.props[Core.Ref] then
-			element.props[Core.Ref](rbx)
-		end
+		applyRef(element.props[Core.Ref], rbx)
 
 		return {
 			[isInstanceHandle] = true,
@@ -323,7 +335,7 @@ function Reconciler._reconcileInternal(instanceHandle, newElement)
 
 		-- Cancel the old ref before we make changes. Apply the new one after.
 		if refChanged and oldRef then
-			oldRef(nil)
+			applyRef(oldRef, nil)
 		end
 
 		-- Update properties and children of the Roblox object.

lib/Reconciler.spec.lua

@@ -1,8 +1,39 @@
 return function()
+	local Core = require(script.Parent.Core)
 	local Reconciler = require(script.Parent.Reconciler)
+	local createRef = require(script.Parent.createRef)
 
 	it("should mount booleans as nil", function()
 		local booleanReified = Reconciler.mount(false)
 		expect(booleanReified).to.never.be.ok()
 	end)
+
+	it("should handle object references properly", function()
+		local objectRef = createRef()
+		local element = Core.createElement("StringValue", {
+			[Core.Ref] = objectRef,
+		})
+
+		local handle = Reconciler.mount(element)
+		expect(objectRef.current).to.be.ok()
+		Reconciler.unmount(handle)
+		expect(objectRef.current).to.never.be.ok()
+	end)
+
+	it("should handle function references properly", function()
+		local currentRbx
+
+		local function ref(rbx)
+			currentRbx = rbx
+		end
+
+		local element = Core.createElement("StringValue", {
+			[Core.Ref] = ref,
+		})
+
+		local handle = Reconciler.mount(element)
+		expect(currentRbx).to.be.ok()
+		Reconciler.unmount(handle)
+		expect(currentRbx).to.never.be.ok()
+	end)
 end

lib/createRef.lua

@@ -0,0 +1,20 @@
+--[[
+	Provides an API for acquiring a reference to a reified object. This
+	API is designed to mimic React 16.3's createRef API.
+
+	See:
+	* https://reactjs.org/docs/refs-and-the-dom.html
+	* https://reactjs.org/blog/2018/03/29/react-v-16-3.html#createref-api
+]]
+
+local refMetatable = {
+	__tostring = function(self)
+		return ("RoactReference(%s)"):format(tostring(self.current))
+	end,
+}
+
+return function()
+	return setmetatable({
+		current = nil,
+	}, refMetatable)
+end

lib/createRef.spec.lua

@@ -0,0 +1,15 @@
+return function()
+	local createRef = require(script.Parent.createRef)
+
+	it("should create refs", function()
+		expect(createRef()).to.be.ok()
+	end)
+
+	it("should support tostring on refs", function()
+		local ref = createRef()
+		expect(tostring(ref)).to.equal("RoactReference(nil)")
+
+		ref.current = "foo"
+		expect(tostring(ref)).to.equal("RoactReference(foo)")
+	end)
+end

lib/init.lua

@@ -4,6 +4,7 @@
 
 local Component = require(script.Component)
 local Core = require(script.Core)
+local createRef = require(script.createRef)
 local Event = require(script.Event)
 local Change = require(script.Change)
 local GlobalConfig = require(script.GlobalConfig)
@@ -39,6 +40,7 @@ apply(Roact, ReconcilerCompat)
 
 apply(Roact, {
 	Component = Component,
+	createRef = createRef,
 	PureComponent = PureComponent,
 	Event = Event,
 	Change = Change,

lib/init.spec.lua

@@ -4,6 +4,7 @@ return function()
 	it("should load with all public APIs", function()
 		local publicApi = {
 			createElement = "function",
+			createRef = "function",
 			mount = "function",
 			unmount = "function",
 			reconcile = "function",