Shallow wrapper

CONTRIBUTING.md

@@ -81,6 +81,9 @@ When submitting a new feature, add tests for all functionality.
 
 We use [LuaCov](https://keplerproject.github.io/luacov) for keeping track of code coverage. We'd like it to be as close to 100% as possible, but it's not always possible. Adding tests just for the purpose of getting coverage isn't useful; we should strive to make only useful tests!
 
+### Snapshots
+As part of the test suite, there are tests that generates snapshot files (located under `./RoactSnapshots`). To sync back the generated StringValues produce by these on the file system, we suggest using a tool like [`run-in-roblox`](https://github.com/LPGhatguy/run-in-roblox) to make the workflow as simple as possible. In the case where you only need to sync a few files, you can use the plugin to automatically copy back the generated string values from the run mode into module scripts when going back to edit mode. Then simply copy-paste into the new snapshots into the file-system.
+
 ## Release Checklist
 When releasing a new version of Roact, do these things:
 

SnapshotsPlugin/EditModeMain.lua

@@ -0,0 +1,41 @@
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+
+local Settings = require(script.Parent.Settings)
+
+local function SyncSnapshots(newSnapshots)
+	local snapshotsFolder = ReplicatedStorage:FindFirstChild(Settings.SnapshotFolderName)
+
+	if not snapshotsFolder then
+		snapshotsFolder = Instance.new("Folder")
+		snapshotsFolder.Name = Settings.SnapshotFolderName
+		snapshotsFolder.Parent = ReplicatedStorage
+	end
+
+	for name, value in pairs(newSnapshots) do
+		local snapshot = Instance.new("ModuleScript")
+		snapshot.Name = name
+		snapshot.Source = value
+		snapshot.Parent = snapshotsFolder
+	end
+end
+
+local function PluginEditMode(plugin)
+	local isPluginDeactivated = false
+
+	plugin.Deactivation:Connect(function()
+		isPluginDeactivated = true
+	end)
+
+	while not isPluginDeactivated do
+		local newSnapshots = plugin:GetSetting(Settings.PluginSettingName)
+
+		if newSnapshots then
+			SyncSnapshots(newSnapshots)
+			plugin:SetSetting(Settings.PluginSettingName, false)
+		end
+
+		wait(Settings.SyncDelay)
+	end
+end
+
+return PluginEditMode

SnapshotsPlugin/RunModeMain.lua

@@ -0,0 +1,25 @@
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+
+local Settings = require(script.Parent.Settings)
+
+local function PluginRunMode(plugin)
+	plugin.Unloading:Connect(function()
+		local snapshotsFolder = ReplicatedStorage:FindFirstChild(Settings.SnapshotFolderName)
+
+		local newSnapshots = {}
+
+		if not snapshotsFolder then
+			return
+		end
+
+		for _, snapshot in pairs(snapshotsFolder:GetChildren()) do
+			if snapshot:IsA("StringValue") then
+				newSnapshots[snapshot.Name] = snapshot.Value
+			end
+		end
+
+		plugin:SetSetting(Settings.PluginSettingName, newSnapshots)
+	end)
+end
+
+return PluginRunMode

SnapshotsPlugin/Settings.lua

@@ -0,0 +1,17 @@
+local function IndexError(_, key)
+	local message = ("%q (%s) is not a valid member of Settings"):format(
+		tostring(key),
+		typeof(key)
+	)
+
+	error(message, 2)
+end
+
+return setmetatable({
+	SnapshotFolderName = "RoactSnapshots",
+	PluginSettingName = "NewRoactSnapshots",
+	SyncDelay = 1,
+}, {
+	__index = IndexError,
+	__newindex = IndexError,
+})

SnapshotsPlugin/init.server.lua

@@ -0,0 +1,12 @@
+local RunService = game:GetService("RunService")
+
+local EditModeMain = require(script.EditModeMain)
+local RunModeMain = require(script.RunModeMain)
+
+if RunService:IsEdit() then
+	EditModeMain(plugin)
+else
+	if RunService:IsClient() then
+		RunModeMain(plugin)
+	end
+end

docs/api-reference.md

@@ -32,21 +32,21 @@ Creates a new Roact fragment with the provided table of elements. Fragments allo
 
 ### Roact.mount
 ```
-Roact.mount(element, [parent, [key]]) -> RoactTree
+Roact.mount(element, [parent, [key]]) -> VirtualTree
 ```
 
 !!! info
 	`Roact.mount` is also available via the deprecated alias `Roact.reify`. It will be removed in a future release.
 
 Creates a Roblox Instance given a Roact element, and optionally a `parent` to put it in, and a `key` to use as the instance's `Name`.
 
-The result is a `RoactTree`, which is an opaque handle that represents a tree of components owned by Roact. You can pass this to APIs like `Roact.unmount`. It'll also be used for future debugging APIs.
+The result is a `VirtualTree`, which is an opaque handle that represents a tree of components owned by Roact. You can pass this to APIs like `Roact.unmount`. It'll also be used for future debugging APIs.
 
 ---
 
 ### Roact.update
 ```
-Roact.update(tree, element) -> RoactTree
+Roact.update(tree, element) -> VirtualTree
 ```
 
 !!! info
@@ -56,7 +56,7 @@ Updates an existing instance handle with a new element, returning a new handle.
 
 `update` can be used to change the props of a component instance created with `mount` and is useful for putting Roact content into non-Roact applications.
 
-As of Roact 1.0, the returned `RoactTree` object will always be the same value as the one passed in.
+As of Roact 1.0, the returned `VirtualTree` object will always be the same value as the one passed in.
 
 ---
 
@@ -68,7 +68,7 @@ Roact.unmount(tree) -> void
 !!! info
 	`Roact.unmount` is also available via the deprecated alias `Roact.teardown`. It will be removed in a future release.
 
-Destroys the given `RoactTree` and all of its descendants. Does not operate on a Roblox Instance -- this must be given a handle that was returned by `Roact.mount`.
+Destroys the given `VirtualTree` and all of its descendants. Does not operate on a Roblox Instance -- this must be given a handle that was returned by `Roact.mount`.
 
 ---
 
@@ -608,4 +608,159 @@ end
 As with `setState`, you can set use the constant `Roact.None` to remove a field from the state.
 
 !!! note
-	`getDerivedStateFromProps` is a *static* lifecycle method. It does not have access to `self`, and must be a pure function.
+	`getDerivedStateFromProps` is a *static* lifecycle method. It does not have access to `self`, and must be a pure function.
+
+---
+
+## ShallowWrapper
+
+### Fields
+
+#### type
+```
+type: {
+	kind: ElementKind
+}
+```
+
+The type dictionary always has the `kind` field that tell the component type. Additionally, depending of the kind of component, other information can be included.
+
+| kind | fields | description |
+| --- | --- | --- |
+| Host | className: string | the ClassName of the instance |
+| Function | functionComponent: function | the function that renders the element |
+| Stateful | component: table | the class-like table used to render the element |
+
+---
+
+#### props
+The props of the ShallowWrapper.
+
+!!! note
+	This dictionary will not contain the `Roact.Children` prop. To obtain the children elements wrapped into a ShallowWrapper, use the method `getChildren()`
+
+---
+
+#### hostKey
+The `hostKey` that is used to map the element to it's parent.
+
+---
+
+### Methods
+
+#### childrenCount
+```
+childrenCount() -> number
+```
+Returns the amount of children that the current ShallowWrapper contains.
+
+---
+
+#### find
+```
+find([constraints]) -> list[ShallowWrapper]
+```
+When a dictionary of constraints is provided, the function will filter the children that do not satisfy all given constraints. Otherwise, as `getChildren` do, it returns a list of all children wrapped into ShallowWrappers.
+
+---
+
+#### findUnique
+```
+findUnique([constraints]) -> ShallowWrapper
+```
+Similar to `find`, this method will assert that only one child satisfies the given constraints, or in the case where none is provided, will assert that there is simply only one child.
+
+---
+
+#### getChildren
+```
+getChildren() -> list[ShallowWrapper]
+```
+Returns a list of all children wrapped into ShallowWrappers.
+
+---
+
+#### getInstance
+```
+getInstance() -> Instance or nil
+```
+Returns the instance object associated with the ShallowWrapper. It can return `nil` if the component wrapped by the ShallowWrapper does not render an instance, but rather another component. Here is an example:
+
+```lua
+local function CoolComponent(props)
+	return Roact.createElement("TextLabel")
+end
+
+local function MainComponent(props)
+	return Roact.createElement("Frame", {}, {
+		Cool = Roact.createElement(CoolComponent),
+	})
+end
+```
+
+If we shallow-render the `MainComponent`, the default depth will not render the CoolComponent.
+
+```lua
+local element = Roact.createElement(MainComponent)
+
+local tree = Roact.mount(element)
+
+local wrapper = tree:getShallowWrapper()
+
+print(wrapper:getInstance() == nil) -- prints false
+
+local coolWrapper = wrapper:findUnique()
+
+print(coolWrapper:getInstance() == nil) -- prints true
+```
+
+---
+
+#### matchSnapshot
+```
+matchSnapshot(identifier)
+```
+If no previous snapshot with the given identifier exists, it will create a new StringValue instance that will contain Lua code representing the current ShallowWrapper. When an existing snapshot is found (a ModuleScript named as the provided identifier), it will require the ModuleScript and load the data from it. Then, if the loaded data is different from the current ShallowWrapper, an error will be thrown.
+
+!!! note
+	As mentionned, `matchSnapshot` will create a StringValue, named like the given identifier, in which the generated lua code will be assigned to the Value property. When these values are generated in Studio during run mode, it's important to copy back the values and convert them into ModuleScripts.
+
+---
+
+#### snapshotToString
+```
+snapshotToString() -> string
+```
+Returns the string source of the snapshot. Useful for debugging purposes.
+
+---
+
+##### Constraints
+Constraints are passed through a dictionary that maps a constraint name to it's value.
+
+| name | value type | description |
+| --- | --- | --- |
+| kind | ElementKind | Filters with the ElementKind of the rendered elements |
+| className | string | Filters children that renders to host instance of the given class name |
+| component | string, function or table | Filter children from their components, by finding the functional component original function, the sub-class table of Roact.Component or from the class name of the instance rendered |
+| props | dictionary | Filters elements that contains at least the given set of props |
+| hostKey | string | Filters elements by the host key used |
+
+---
+
+## VirtualTree
+
+### Methods
+
+#### getShallowWrapper
+```
+getShallowWrapper(options) -> ShallowWrapper
+```
+Options:
+```lua
+{
+	depth: number -- default to 1
+}
+```
+
+Wraps the current tree into a ShallowWrapper.

snapshots-plugin.project.json

@@ -0,0 +1,6 @@
+{
+	"name": "Snapshots Plugin",
+	"tree": {
+		"$path": "SnapshotsPlugin"
+	}
+  }