Add Path.relative for relative path computations.

Author: ioquatix

lib/protocol/url/path.rb

@@ -119,6 +119,45 @@ def self.expand(base, relative, pop = true)
 				return join(simplify(components))
 			end
 
+			# Calculate the relative path from one absolute path to another.
+			#
+			# This is useful for generating relative URLs from one location to another,
+			# such as creating page-specific import maps or relative links.
+			#
+			# @parameter target [String] The destination path (where you want to go).
+			# @parameter from [String] The source path (where you are starting from).
+			# @returns [String] The relative path from `from` to `target`.
+			#
+			# @example Calculate relative path between pages.
+			# 	Path.relative("/_components/app.js", "/foo/bar/")
+			# 	# => "../../_components/app.js"
+			#
+			# @example Calculate relative path in same directory.
+			# 	Path.relative("/docs/guide.html", "/docs/index.html")
+			# 	# => "guide.html"
+			def self.relative(target, from)
+				target_components = split(target)
+				from_components = split(from)
+				
+				# Remove the last component from 'from' to get the directory
+				from_components = from_components[0...-1] if from_components.size > 0
+				
+				# Find the common prefix
+				common_length = 0
+				[target_components.size, from_components.size].min.times do |i|
+					break if target_components[i] != from_components[i]
+					common_length = i + 1
+				end
+				
+				# Calculate how many levels to go up
+				up_levels = from_components.size - common_length
+				
+				# Build the relative path components
+				relative_components = [".."] * up_levels + target_components[common_length..-1]
+				
+				return join(relative_components)
+			end
+			
 			# Convert a URL path to a local file system path using the platform's file separator.
 			#
 			# This method splits the URL path on `/` characters, unescapes each component using

releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## Unreleased
+
+  - Add `relative(target, from)` for computing relative paths between URLs.
+
 ## v0.2.0
 
   - Move `Protocol::URL::PATTERN` to `protocol/url/pattern.rb` so it can be shared more easily.

test/protocol/url/path.rb

@@ -396,6 +396,40 @@
 		end
 	end
 
+	with ".relative" do
+		it "calculates relative path between pages" do
+			expect(Protocol::URL::Path.relative("/_components/app.js", "/foo/bar/")).to be == "../../_components/app.js"
+		end
+		
+		it "calculates relative path in same directory" do
+			expect(Protocol::URL::Path.relative("/docs/guide.html", "/docs/index.html")).to be == "guide.html"
+		end
+		
+		it "calculates relative path from root to subdirectory" do
+			expect(Protocol::URL::Path.relative("/foo/bar/", "/")).to be == "foo/bar/"
+		end
+		
+		it "calculates relative path to parent directory" do
+			expect(Protocol::URL::Path.relative("/docs/", "/docs/api/reference.html")).to be == "../"
+		end
+		
+		it "calculates relative path with multiple levels up" do
+			expect(Protocol::URL::Path.relative("/a/file.txt", "/x/y/z/")).to be == "../../../a/file.txt"
+		end
+		
+		it "calculates relative path with common prefix" do
+			expect(Protocol::URL::Path.relative("/projects/alpha/file.txt", "/projects/beta/")).to be == "../alpha/file.txt"
+		end
+		
+		it "preserves trailing slashes in target" do
+			expect(Protocol::URL::Path.relative("/foo/bar/", "/baz/")).to be == "../foo/bar/"
+		end
+		
+		it "handles target without trailing slash" do
+			expect(Protocol::URL::Path.relative("/foo/bar", "/baz/")).to be == "../foo/bar"
+		end
+	end
+	
 	with ".to_local_path" do
 		it "converts simple absolute path" do
 			result = Protocol::URL::Path.to_local_path("/documents/report.pdf")