@quenty/blend 2.0.0-canary.236.5597d0a.0 → 2.0.1

package/CHANGELOG.md

@@ -3,7 +3,23 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-# [2.0.0-canary.236.5597d0a.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/blend@1.1.0...@quenty/blend@2.0.0-canary.236.5597d0a.0) (2021-12-18)
+## [2.0.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/blend@2.0.0...@quenty/blend@2.0.1) (2021-12-30)
+
+**Note:** Version bump only for package @quenty/blend
+
+
+
+
+
+# [2.0.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/blend@1.2.0...@quenty/blend@2.0.0) (2021-12-22)
+
+**Note:** Version bump only for package @quenty/blend
+
+
+
+
+
+# [1.2.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/blend@1.1.0...@quenty/blend@1.2.0) (2021-12-18)
 
 
 ### Features

package/README.md

@@ -1,10 +1,10 @@
 ## Blend
 <div align="center">
-  <a href="http://quenty.github.io/api/">
-    <img src="https://img.shields.io/badge/docs-website-green.svg" alt="Documentation" />
+  <a href="http://quenty.github.io/NevermoreEngine/">
+    <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/docs.yml/badge.svg" alt="Documentation status" />
   </a>
   <a href="https://discord.gg/mhtGUS8">
-    <img src="https://img.shields.io/badge/discord-nevermore-blue.svg" alt="Discord" />
+    <img src="https://img.shields.io/discord/385151591524597761?color=5865F2&label=discord&logo=discord&logoColor=white" alt="Discord" />
   </a>
   <a href="https://github.com/Quenty/NevermoreEngine/actions">
     <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/build.yml/badge.svg" alt="Build and release status" />
@@ -13,6 +13,8 @@
 
 Declarative UI system inspired by Fusion
 
+<div align="center"><a href="https://quenty.github.io/NevermoreEngine/api/Blend">View docs →</a></div>
+
 ## Installation
 ```
 npm install @quenty/blend --save
@@ -24,49 +26,4 @@ This system is designed to be very similar to fusion, except that we do not havi
 
 * No global state
 * Extensible
-* No implicit reliance upon GC
-
-## Usage
-
-See files in src/Client/Test that are stories. Blend returns an observable that will create/return one instance.
-
-Note that subscribe function anchors everything into a maid/cleanup function that can be used to disconnect the whole tree.
-
-```lua
-local require = ... -- Nevermore import here
-local Blend = require("Blend")
-local Maid = require("Maid")
-
-local maid = Maid.new()
-
-local isVisible = Instance.new("BoolValue")
-isVisible.Value = false
-
-local percentVisible = Blend.Spring(Blend.Computed(isVisible, function(visible)
-  return visible and 1 or 0
-end), 35)
-
-local transparency = Blend.Computed(percentVisible, function(percent)
-  return 1 - percent
-end)
-
-maid:GiveTask((Blend.New "Frame" {
-  Size = UDim2.new(0.5, 0, 0.5, 0);
-  BackgroundColor3 = Color3.new(0.9, 0.9, 0.9);
-  AnchorPoint = Vector2.new(0.5, 0.5);
-  Position = UDim2.new(0.5, 0, 0.5, 0);
-  BackgroundTransparency = transparency;
-  Parent = parent; -- TODO: Assign parent
-
-  [Blend.Children] = {
-    Blend.New "UIScale" {
-      Scale = Blend.Computed(percentVisible, function(percent)
-        return 0.8 + 0.2*percent
-      end);
-    };
-    Blend.New "UICorner" {
-      CornerRadius = UDim.new(0.05, 0);
-    };
-  };
-}):Subscribe())
-```
+* No implicit reliance upon GC

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/blend",
-  "version": "2.0.0-canary.236.5597d0a.0",
+  "version": "2.0.1",
   "description": "Declarative UI system.",
   "keywords": [
     "Roblox",
@@ -27,23 +27,23 @@
     "access": "public"
   },
   "dependencies": {
-    "@quenty/acceltween": "2.0.0",
-    "@quenty/brio": "4.0.0-canary.236.5597d0a.0",
-    "@quenty/instanceutils": "4.0.0-canary.236.5597d0a.0",
-    "@quenty/loader": "3.1.1",
-    "@quenty/maid": "2.0.1",
-    "@quenty/promise": "4.0.0-canary.236.5597d0a.0",
-    "@quenty/rx": "4.0.0-canary.236.5597d0a.0",
-    "@quenty/spring": "3.0.0-canary.236.5597d0a.0",
-    "@quenty/steputils": "3.0.0",
-    "@quenty/string": "2.2.0",
-    "@quenty/symbol": "2.0.0",
-    "@quenty/valuebaseutils": "4.0.0-canary.236.5597d0a.0",
-    "@quenty/valueobject": "4.0.0-canary.236.5597d0a.0"
+    "@quenty/acceltween": "^2.0.1",
+    "@quenty/brio": "^3.5.1",
+    "@quenty/instanceutils": "^3.5.1",
+    "@quenty/loader": "^3.1.2",
+    "@quenty/maid": "^2.0.2",
+    "@quenty/promise": "^3.3.1",
+    "@quenty/rx": "^3.5.1",
+    "@quenty/spring": "^3.0.1",
+    "@quenty/steputils": "^3.0.1",
+    "@quenty/string": "^2.2.1",
+    "@quenty/symbol": "^2.0.1",
+    "@quenty/valuebaseutils": "^3.5.1",
+    "@quenty/valueobject": "^3.5.1"
   },
   "devDependencies": {
-    "@quenty/contentproviderutils": "4.0.0-canary.236.5597d0a.0",
-    "@quenty/playerthumbnailutils": "4.0.0-canary.236.5597d0a.0"
+    "@quenty/contentproviderutils": "^3.3.1",
+    "@quenty/playerthumbnailutils": "^3.4.1"
   },
-  "gitHead": "5597d0abdadd88f369f1401a558a8d6d1a1c5aab"
+  "gitHead": "d146c77d0a8e452824de0ab0b4b03ba0370bcc1b"
 }

package/src/Client/Blend/Blend.lua

@@ -1,6 +1,7 @@
----
--- @module Blend
--- @author Quenty
+--[=[
+	Declarative UI system inspired by Fusion
+	@class Blend
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -25,6 +26,26 @@ local Blend = {}
 
 Blend.Children = Symbol.named("children")
 
+--[=[
+	Creates a new function which will return an observable that, given the props
+	in question, will construct a new instance and assign all props. This is the
+	equivalent of a pipe-able Rx command.
+
+	```lua
+	Blend.New "ScreenGui" {
+		Parent = game.Players.LocalPlayer.PlayerGui;
+		[Blend.Children] = {
+			Blend.New "Frame" {
+				Size = UDim2.new(1, 0, 1, 0);
+				BackgroundTransparency = 0.5;
+			};
+		};
+	};
+
+	@param className string
+	@return (props: { [string]: any; }) -> Observable<Instance>
+	```
+]=]
 function Blend.New(className)
 	assert(type(className) == "string", "Bad className")
 
@@ -51,6 +72,12 @@ function Blend.New(className)
 	end
 end
 
+--[=[
+	Creates a new Blend State which is actually just a ValueObject underneath.
+
+	@param defaultValue T
+	@return ValueObject<T>
+]=]
 function Blend.State(defaultValue)
 	return ValueObject.new(defaultValue)
 end
@@ -72,6 +99,32 @@ function Blend.Dynamic(...)
 		})
 end
 
+--[=[
+	Takes a list of variables and uses them to compute an observable that
+	will combine into any value. These variables can be any value, and if they
+	can be converted into an Observable, they will be, which will be used to compute
+	the value.
+
+	```lua
+	local verbState = Blend.State("hi")
+	local nameState = Blend.State("alice")
+
+	local computed = Blend.Computed(verbState, nameState, function(verb, name)
+		return verb .. " " .. name
+	end)
+
+	computed:Subscribe(function(sentence)
+		print(sentence)
+	end) --> "hi alice"
+
+	nameState.Value = "bob" --> "hi bob"
+	verbState.Value = "bye" --> "bye bob"
+	nameState.Value = "alice" --> "bye alice"
+	```
+
+	@param ... A series of convertable states, followed by a function at the end.
+	@return Observable<T>
+]=]
 function Blend.Computed(...)
 	local values = {...}
 	local n = select("#", ...)
@@ -106,6 +159,22 @@ function Blend.Computed(...)
 	end
 end
 
+--[=[
+	Short hand to register a propertyEvent changing
+
+	```lua
+	Blend.mount(workspace, {
+		[Blend.OnChange "Name"] = function(name)
+			print(name)
+		end;
+	}) --> Immediately will print "Workspace"
+
+	workspace.Name = "Hello" --> Prints "Hello"
+	```
+
+	@param propertyName string
+	@return (instance: Instance) -> Observable
+]=]
 function Blend.OnChange(propertyName)
 	assert(type(propertyName) == "string", "Bad propertyName")
 
@@ -114,6 +183,24 @@ function Blend.OnChange(propertyName)
 	end
 end
 
+--[=[
+	Short hand to register an event from the instance
+
+	```lua
+		Blend.mount(workspace, {
+			[Blend.OnEvent "ChildAdded"] = function(child)
+				print("Child added", child)
+			end;
+		})
+
+		local folder = Instance.new("Folder")
+		folder.Name = "Hi"
+		folder.Parent = workspace --> prints "Child added Hi"
+	```
+
+	@param eventName string
+	@return (instance: Instance) -> Observable
+]=]
 function Blend.OnEvent(eventName)
 	assert(type(eventName) == "string", "Bad eventName")
 
@@ -153,7 +240,7 @@ function Blend.ComputedPairs(source, compute)
 					local brio = Brio.new(result)
 					innerMaid:GiveTask(brio)
 
-					local cleanup = Blend.addChildren(parent, brio)
+					local cleanup = Blend.mountChildren(parent, brio)
 					if cleanup then
 						innerMaid:GiveTask(cleanup)
 					end
@@ -173,6 +260,13 @@ function Blend.ComputedPairs(source, compute)
 	end
 end
 
+--[=[
+	Like Blend.Spring, but for AccelTween
+
+	@param source any -- Source observable (or convertable)
+	@param acceleration any -- Source acceleration (or convertable)
+	@return Observable
+]=]
 function Blend.AccelTween(source, acceleration)
 	local sourceObservable = Blend.toPropertyObservable(source) or Rx.of(source)
 	local accelerationObservable = Blend.toNumberObservable(acceleration)
@@ -211,7 +305,27 @@ function Blend.AccelTween(source, acceleration)
 	end)
 end
 
-
+--[=[
+	Converts this arbitrary value into an observable that will initialize a spring
+	and interpolate it between values upon subscription.
+
+	```lua
+	local percentVisible = Blend.State(0)
+	local visibleSpring = Blend.Spring(percentVisible, 30)
+	local transparency = Blend.Computed(visibleSpring, function(percent)
+		return 1 - percent
+	end);
+
+	Blend.mount(frame, {
+		BackgroundTransparency = visibleSpring;
+	})
+	```
+
+	@param source any
+	@param speed any
+	@param damper any
+	@return Observable?
+]=]
 function Blend.Spring(source, speed, damper)
 	local sourceObservable = Blend.toPropertyObservable(source) or Rx.of(source)
 	local speedObservable = Blend.toNumberObservable(speed)
@@ -261,6 +375,12 @@ function Blend.Spring(source, speed, damper)
 	end)
 end
 
+--[=[
+	Converts this arbitrary value into an observable suitable for use in properties.
+
+	@param value any
+	@return Observable?
+]=]
 function Blend.toPropertyObservable(value)
 	if Observable.isObservable(value) then
 		return value
@@ -280,6 +400,12 @@ function Blend.toPropertyObservable(value)
 	return nil
 end
 
+--[=[
+	Converts this arbitrary value into an observable that emits numbers.
+
+	@param value number | any
+	@return Observable<number>?
+]=]
 function Blend.toNumberObservable(value)
 	if type(value) == "number" then
 		return Rx.of(value)
@@ -288,6 +414,12 @@ function Blend.toNumberObservable(value)
 	end
 end
 
+--[=[
+	Converts this arbitrary value into an observable that can be used to emit events.
+
+	@param value any
+	@return Observable?
+]=]
 function Blend.toEventObservable(value)
 	if Observable.isObservable(value) then
 		return value
@@ -298,6 +430,12 @@ function Blend.toEventObservable(value)
 	end
 end
 
+--[=[
+	Converts this arbitrary value into an event handler, which can be subscribed to
+
+	@param value any
+	@return function?
+]=]
 function Blend.toEventHandler(value)
 	if type(value) == "function" then
 		return value
@@ -319,7 +457,18 @@ function Blend.toEventHandler(value)
 	return nil
 end
 
-function Blend.addChildren(parent, value)
+--[=[
+	Mounts children to the parent and returns an object which will cleanup and delete
+	all children when removed.
+
+	Note that this effectively recursively mounts children and their values, which is
+	the heart of the reactive tree.
+
+	@param parent Instance
+	@param value any
+	@return MaidTask
+]=]
+function Blend.mountChildren(parent, value)
 	if typeof(value) == "Instance" then
 		value.Parent = parent
 
@@ -336,7 +485,7 @@ function Blend.addChildren(parent, value)
 			local maid = Maid.new()
 
 			-- Add for lifetime
-			local cleanup = Blend.addChildren(parent, value:GetValue())
+			local cleanup = Blend.mountChildren(parent, value:GetValue())
 			if cleanup then
 				maid:GiveTask(cleanup)
 			end
@@ -355,7 +504,7 @@ function Blend.addChildren(parent, value)
 				local maid = Maid.new()
 
 				maid:GiveTask(observable:Subscribe(function(result)
-					maid._current = Blend.addChildren(parent, result)
+					maid._current = Blend.mountChildren(parent, result)
 				end))
 
 				return maid
@@ -365,7 +514,7 @@ function Blend.addChildren(parent, value)
 				-- hope we're actually recursing over a nested table.
 				-- this allows us to add arrays into the blend.
 				for _, item in pairs(value) do
-					local cleanup = Blend.addChildren(parent, item)
+					local cleanup = Blend.mountChildren(parent, item)
 					if cleanup then
 						maid:GiveTask(cleanup)
 					end
@@ -384,6 +533,22 @@ function Blend.addChildren(parent, value)
 	return nil
 end
 
+--[=[
+	Mounts the instance to the props. This handles mounting children, and events.
+
+	The contract is that the props table is turned into observables. Note the following.
+
+	* Keys of strings are turned into properties
+		* If this can be turned into an observable, it will be used to subscribe to this event
+		* Otherwise, we assign directly
+	* Keys of functions are invoked on the instance in question
+		* If this returns an observable (or can be turned into one), we subscribe the event immediately
+	* If the key is [Blend.Children] then we invoke mountChildren on it
+
+	@param instance Instance
+	@param props table
+	@return Maid
+]=]
 function Blend.mount(instance, props)
 	local maid = Maid.new()
 
@@ -432,7 +597,7 @@ function Blend.mount(instance, props)
 
 	local childProp = props[Blend.Children]
 	if childProp then
-		local cleanup = Blend.addChildren(instance, childProp)
+		local cleanup = Blend.mountChildren(instance, childProp)
 		if cleanup then
 			maid:GiveTask(cleanup)
 		end

package/src/Client/Test/BlendChildren.story.lua

@@ -1,6 +1,6 @@
----
--- @module Blend.story
--- @author Quenty
+--[[
+	@class Blend.story
+]]
 
 local require = require(game:GetService("ServerScriptService"):FindFirstChild("LoaderUtils", true).Parent).load(script)
 

package/src/Client/Test/BlendComputePairs.story.lua

@@ -1,6 +1,6 @@
----
--- @module Blend.story
--- @author Quenty
+--[[
+	@class Blend.story
+]]
 
 local require = require(game:GetService("ServerScriptService"):FindFirstChild("LoaderUtils", true).Parent).load(script)
 

package/src/Client/Test/BlendPromise.story.lua

@@ -1,6 +1,6 @@
----
--- @module BlendTextbox.story
--- @author Quenty
+--[[
+	@class BlendTextbox.story
+]]
 
 local require = require(game:GetService("ServerScriptService"):FindFirstChild("LoaderUtils", true).Parent).load(script)
 

package/src/Client/Test/BlendSpring.story.lua

@@ -1,6 +1,6 @@
----
--- @module Blend.story
--- @author Quenty
+--[[
+	@class Blend.story
+]]
 
 local require = require(game:GetService("ServerScriptService"):FindFirstChild("LoaderUtils", true).Parent).load(script)
 

package/src/Client/Test/BlendTextbox.story.lua

@@ -1,6 +1,6 @@
----
--- @module BlendTextbox.story
--- @author Quenty
+--[[
+	@class BlendTextbox.story
+]]
 
 local require = require(game:GetService("ServerScriptService"):FindFirstChild("LoaderUtils", true).Parent).load(script)
 

package/test/scripts/Client/ClientMain.client.lua

@@ -1,6 +1,4 @@
---- Main injection point
--- @script ClientMain
--- @author Quenty
+-- Main injection point
 
 local packages = game:GetService("ReplicatedStorage"):WaitForChild("Packages")
 

package/test/scripts/Server/ServerMain.server.lua

@@ -1,6 +1,5 @@
---- Main injection point
+-- Main injection point
 -- @script ServerMain
--- @author Quenty
 
 local ServerScriptService = game:GetService("ServerScriptService")