@quenty/blend 6.14.0 → 6.15.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.
 
+# [6.15.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/blend@6.14.0...@quenty/blend@6.15.0) (2023-04-06)
+
+
+### Features
+
+* Add Blend.Find which allows mounting in existing frames, as well as allowing [Blend.Children] to be optional ([9af4998](https://github.com/Quenty/NevermoreEngine/commit/9af4998f5de3287c90f0e6eb279b95d10019bfd2))
+
+
+
+
+
 # [6.14.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/blend@6.13.0...@quenty/blend@6.14.0) (2023-04-03)
 
 **Note:** Version bump only for package @quenty/blend

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/blend",
-  "version": "6.14.0",
+  "version": "6.15.0",
   "description": "Declarative UI system.",
   "keywords": [
     "Roblox",
@@ -28,8 +28,8 @@
   },
   "dependencies": {
     "@quenty/acceltween": "^2.2.1",
-    "@quenty/brio": "^8.9.0",
-    "@quenty/instanceutils": "^7.10.0",
+    "@quenty/brio": "^8.10.0",
+    "@quenty/instanceutils": "^7.11.0",
     "@quenty/loader": "^6.2.0",
     "@quenty/maid": "^2.5.0",
     "@quenty/promise": "^6.4.0",
@@ -38,12 +38,12 @@
     "@quenty/spring": "^6.2.0",
     "@quenty/steputils": "^3.2.0",
     "@quenty/string": "^3.1.0",
-    "@quenty/valuebaseutils": "^7.10.0",
-    "@quenty/valueobject": "^7.10.0"
+    "@quenty/valuebaseutils": "^7.11.0",
+    "@quenty/valueobject": "^7.11.0"
   },
   "devDependencies": {
-    "@quenty/contentproviderutils": "^6.6.0",
+    "@quenty/contentproviderutils": "^6.7.0",
     "@quenty/playerthumbnailutils": "^6.4.0"
   },
-  "gitHead": "fa7c7edfd754cf18fd808466121310f9bfff6271"
+  "gitHead": "d26d804d1f96e9a0f3f5687f8e024ec9d476172d"
 }

package/src/Shared/Blend/Blend.lua

@@ -1,5 +1,5 @@
 --[=[
-	Declarative UI system inspired by Fusion
+	Declarative UI system inspired by Fusion.
 	@class Blend
 ]=]
 
@@ -562,9 +562,23 @@ end
 	};
 	```
 
+	Note since 6.14 you don't need to be explicit about [Blend.Children]. Any number-based
+	index in the mounting process will be automatically inferred as children to mount.
+
+	```lua
+	Blend.New "ScreenGui" {
+		Parent = game.Players.LocalPlayer.PlayerGui;
+
+		Blend.New "Frame" {
+			Size = UDim2.new(1, 0, 1, 0);
+			BackgroundTransparency = 0.5;
+		};
+	};
+	```
+
 	Rules:
 
-	* `{ Instance }` -Tables of instances are all parented to the parent
+	* `{ Instance }` - Tables of instances are all parented to the parent
 	* Brio<Instance> will last for the lifetime of the brio
 	* Brio<Observable<Instance>> will last for the lifetime of the brio
 		* Brio<Signal<Instance>> will also act as above
@@ -579,18 +593,20 @@ end
 		* Observable<Brio<Instance>> will last for the lifetime of the brio, and parent the instance.
 		* Observable<Observable<Instance>> occurs when computed returns a value.
 	* ValueObject<Instance> will switch to the current value
+	* function - Will be invoked as `func(parent)` and then the standard scheme will be applied
 
 	Cleanup:
 	* Instances will be cleaned up on unsubscribe
 
 	@param parent Instance
 	@param value any
-	@return MaidTask
+	@return Observable
 ]=]
 function Blend.Children(parent, value)
 	assert(typeof(parent) == "Instance", "Bad parent")
 
-	local observe = Blend._observeChildren(value)
+	local observe = Blend._observeChildren(value, parent)
+
 	if observe then
 		return observe:Pipe({
 			Rx.tap(function(child)
@@ -602,6 +618,79 @@ function Blend.Children(parent, value)
 	end
 end
 
+--[=[
+	Mounts Blend objects into an existing instance.
+
+	:::tip
+	Normally specifying ClassName as a property breaks mounting, since you
+	can't write to ClassName. However, if you specify ClassName here, it will only
+	listen to changes on children with that class name.
+	:::
+
+	If multiple instances are named the same thing, then this will
+	bind to both.
+
+	:::tip
+	This explicitly listens for any children underneath the mounted
+	instance with the name passed in here. This is fine for small amounts
+	of instances, like in most Gui hierarchies. However, it will be way less
+	performance friendly for large class hierarchies.
+	:::
+
+	```lua
+	maid:GiveTask(Blend.mount(frame, {
+		Size = UDim2.new(0.5, 0, 0.5, 0);
+
+		Blend.Find "MyUIScaleName" {
+			Scale = 2;
+		};
+	}))
+	```
+
+	@param name string
+	@return function
+]=]
+function Blend.Find(name)
+	assert(type(name) == "string", "Bad name")
+
+	return function(props)
+		assert(type(props) == "table", "Bad props")
+
+		local mountProps = props
+		local className
+		if props.ClassName then
+			className = props.ClassName
+			mountProps = table.clone(props)
+			mountProps.ClassName = nil
+		else
+			className = "Instance"
+		end
+
+		return function(parent)
+			return RxInstanceUtils.observeChildrenOfNameBrio(parent, className, name):Pipe({
+				Rx.flatMap(function(brio)
+					if brio:IsDead() then
+						return
+					end
+
+					local maid = brio:ToMaid()
+					local instance = brio:GetValue()
+					maid:GiveTask(Blend.mount(instance, mountProps))
+
+					-- Dead after mounting? Clean up...
+					-- Probably caused by name change.
+					if brio:IsDead() then
+						maid:DoCleaning()
+					end
+
+					-- Avoid emitting anything else so we don't get cleaned up
+					return Rx.EMPTY
+				end);
+			})
+		end
+	end
+end
+
 --[=[
 	An event emitter that emits the instance that was actually created. This is
 	useful for a variety of things.
@@ -622,6 +711,20 @@ end
 	};
 	```
 
+	Note that since 6.14 you should also be able to just use the reification scheme of
+	[Blend.Children] implicitly in [Blend.mount] to get somewhat equivalent behavior.
+
+	```lua
+	Blend.mount(frame, {
+		-- Array indexed methods get treated as children-constructors, which get the parent
+		-- in them;
+
+		function(parent)
+			print("Got parent!", parent)
+		end;
+	})
+	```
+
 	You can also use this to execute code against an instance.
 
 	```lua
@@ -701,9 +804,10 @@ end
 	Observes children and ensures that the value is cleaned up
 	afterwards.
 	@param value any
+	@param parent Instance
 	@return Observable<Instance>
 ]=]
-function Blend._observeChildren(value)
+function Blend._observeChildren(value, parent)
 	if typeof(value) == "Instance" then
 		-- Should be uncommon
 		return Observable.new(function(sub)
@@ -713,6 +817,10 @@ function Blend._observeChildren(value)
 		end)
 	end
 
+	if type(value) == "function" then
+		value = Blend._observeChildren(value(parent), parent)
+	end
+
 	if ValueObject.isValueObject(value) then
 		return Observable.new(function(sub)
 			local maid = Maid.new()
@@ -726,7 +834,7 @@ function Blend._observeChildren(value)
 					return
 				end
 
-				local observe = Blend._observeChildren(result)
+				local observe = Blend._observeChildren(result, parent)
 				if observe then
 					maid._current = nil
 
@@ -783,7 +891,7 @@ function Blend._observeChildren(value)
 				return maid
 			end
 
-			local observe = Blend._observeChildren(result)
+			local observe = Blend._observeChildren(result, parent)
 			if observe then
 				local maid = value:ToMaid()
 
@@ -829,7 +937,7 @@ function Blend._observeChildren(value)
 					return
 				end
 
-				local observe = Blend._observeChildren(result)
+				local observe = Blend._observeChildren(result, parent)
 
 				if observe then
 					local innerMaid = Maid.new()
@@ -864,7 +972,7 @@ function Blend._observeChildren(value)
 	if type(value) == "table" and not getmetatable(value) then
 		local observables = {}
 		for key, item in pairs(value) do
-			local observe = Blend._observeChildren(item)
+			local observe = Blend._observeChildren(item, parent)
 			if observe then
 				table.insert(observables, observe)
 			else
@@ -893,7 +1001,23 @@ end
 	* Keys of functions are invoked on the instance in question
 		* `(instance, value) -> Observable
 		* 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
+	* Keys of numbers (array components) are treated as implicit children
+	* If the key is [Blend.Children] then we invoke mountChildren on it.
+
+	```lua
+	Blend.mount(frame, {
+		BackgroundTransparency = 1;
+
+		-- All items named InventoryItem
+		Blend.Find "InventoryItem" {
+
+			-- Apply the following properties
+			Blend.New "UIScale" {
+				Scale = 0.5;
+			};
+		};
+	})
+	```
 
 	@param instance Instance
 	@param props table
@@ -931,6 +1055,10 @@ function Blend.mount(instance, props)
 			else
 				warn(("Unable to apply event listener %q"):format(tostring(key)))
 			end
+		elseif type(key) == "number" then
+			-- Treat this as an implicit children contract
+			-- Thus, we don't need an explicit [Blend.Children] call.
+			table.insert(dependentObservables, { Blend.Children(instance, value), value })
 		else
 			warn(("Unable to apply property %q"):format(tostring(key)))
 		end

package/src/Shared/Test/BlendFind.story.lua

@@ -0,0 +1,78 @@
+--[[
+	@class Blend.story
+]]
+
+local require = require(game:GetService("ServerScriptService"):FindFirstChild("LoaderUtils", true).Parent).load(script)
+
+local RunService = game:GetService("RunService")
+
+local Blend = require("Blend")
+local Maid = require("Maid")
+
+return function(target)
+	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)
+
+	local frame = Instance.new("Frame")
+	frame.Size = UDim2.new(0.5, 0, 0.5, 0)
+	frame.BackgroundColor3 = Color3.new(0.9, 0.9, 0.9)
+	frame.AnchorPoint = Vector2.new(0.5, 0.5)
+	frame.Position = UDim2.new(0.5, 0, 0.5, 0)
+	frame.BackgroundTransparency = transparency
+	frame.Parent = target
+	maid:GiveTask(frame)
+
+	local subFrame = Instance.new("Frame")
+	subFrame.Name = "CenterFrame";
+	subFrame.Size = UDim2.new(0.5, 0, 0.5, 0)
+	subFrame.BackgroundColor3 = Color3.new(0.5, 0.5, 0.5)
+	subFrame.AnchorPoint = Vector2.new(0.5, 0.5)
+	subFrame.Position = UDim2.new(0.5, 0, 0.5, 0)
+	subFrame.BackgroundTransparency = transparency
+	subFrame.Parent = frame
+
+	local uiScale = Instance.new("UIScale")
+	uiScale.Name = "MyUIScale"
+	uiScale.Parent = subFrame
+
+	maid:GiveTask(Blend.mount(frame, {
+		Size = UDim2.new(0.5, 0, 0.5, 0);
+
+		Blend.New "UICorner" {
+			CornerRadius = UDim.new(0.05, 0);
+		};
+
+		Blend.Find "CenterFrame" {
+			Blend.Find "MyUIScale" {
+				ClassName = "UIScale";
+
+				Scale = Blend.Computed(percentVisible, function(percent)
+					return 0.8 + 0.2*percent
+				end);
+			};
+
+			Blend.New "UICorner" {
+				CornerRadius = UDim.new(0.05, 0);
+			};
+		};
+	}))
+
+	local PERIOD = 2
+	maid:GiveTask(RunService.RenderStepped:Connect(function()
+		isVisible.Value = os.clock()/PERIOD % 1 < 0.5
+	end))
+
+	return function()
+		maid:DoCleaning()
+	end
+end