FusionTags.luau

--!strict
--!nolint LocalUnused
--!nolint LocalShadow
local task = nil -- Disable usage of Roblox's task scheduler

--[[
	A special key for property tables, which applies any given tags onto
	an instance.
]]

local Package = script.Parent.Parent
local Types = require(Package.Types)
local External = require(Package.External)
local Observer = require(Package.Graph.Observer)
local peek = require(Package.State.peek)
local castToState = require(Package.State.castToState)
local doCleanup = require(Package.Memory.doCleanup)

type Set<T> = {[T]: unknown}

export type Tags = { Types.UsedAs<string> }

return {
	type = "SpecialKey",
	kind = "Tags",
	stage = "self",
	apply = function(
		self: Types.SpecialKey,
		scope: Types.Scope<unknown>,
		value: unknown,
		applyTo: Instance
	)
		local newTags: Set<string> = {}
		local oldTags: Set<string> = {}
	
		-- save scopes for state object observers
		local newScopes: {[Types.StateObject<unknown>]: Types.Scope<unknown>} = {}
		local oldScopes: {[Types.StateObject<unknown>]: Types.Scope<unknown>} = {}
	
		-- Rescans this key's value to find new instances to parent and state objects
		-- to observe for changes; then unparents instances no longer found and
		-- disconnects observers for state objects no longer present.
		local function updateTags()
			oldTags, newTags = newTags, oldTags
			oldScopes, newScopes = newScopes, oldScopes
	
			local function processTag(
				tag: unknown,
				autoName: string?
			)
				local tagType = typeof(tag)
	
				if tagType == "string" then
					-- case 1; string
					local tag = tag :: string
	
					newTags[tag] = true
					if oldTags[tag] == nil then
						-- wasn't previously present
	
						applyTo:AddTag(tag)
					else
						-- previously here; we want to reuse, so remove from old
						-- set so we don't encounter it during unparenting
						oldTags[tag] = nil
					end
	
				elseif castToState(tag) then
					-- case 2; state object
					local tag = tag :: Types.StateObject<unknown>
	
					local value = peek(tag)
					-- allow nil to represent the absence of a tag
					if value ~= nil then
						processTag(value, autoName)
					end
	
					local tagScope = oldScopes[tag]
					if tagScope == nil then
						-- wasn't previously present
						tagScope = {}
						Observer(tagScope, tag):onChange(updateTags)
					else
						-- previously here; we want to reuse, so remove from old
						-- set so we don't encounter it during unparenting
						oldScopes[tag] = nil
					end
	
					newScopes[tag] = tagScope
	
				elseif tagType == "table" then
					-- case 3; table of objects
					local tag = tag :: {[unknown]: unknown}
	
					for key, subTag in pairs(tag) do
						local keyType = typeof(key)
						local subAutoName: string? = nil
	
						if keyType == "string" then
							local key = key :: string
							subAutoName = key
						elseif keyType == "number" and autoName ~= nil then
							local key = key :: number
							subAutoName = autoName .. "_" .. key
						end
	
						processTag(subTag, subAutoName)
					end
	
				else
					External.logWarn("unrecognisedTagType", tagType)
				end
			end
	
			if value ~= nil then
				-- `propValue` is set to nil on cleanup, so we don't process tags
				-- in that case
				processTag(value)
			end
	
			-- unparent any tags that are no longer present
			for oldInstance in pairs(oldTags) do
				applyTo:RemoveTag(oldInstance)
			end
			table.clear(oldTags)
	
			-- disconnect observers which weren't reused
			for oldState, tagScope in pairs(oldScopes) do
				doCleanup(tagScope)
			end
			table.clear(oldScopes)
		end
	
		table.insert(scope, function()
			value = nil
			updateTags()
		end)
	
		-- perform initial tag parenting
		updateTags()
	end
} :: Types.SpecialKey

--[[
Modified from Fusion's src/Instances/Children file.
Fusion's License below:
MIT License
Copyright (c) 2024 Daniel P H Fox
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
]]

replace the Package variable in the source code above with the path to the Fusion module.

Tag behaves identically to the Children special key except it adds and removes tags from the target instance.

Example usage:

local Fusion = require(Path.To.Fusion)
local Tags = require(Path.To.FusionTags)

local Scope = Fusion.scoped(Fusion)

Scope:New "Frame" {
    [Tags] = "MyTag"
}