utopia 3.0.2 → 3.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b209f640f2956c9d656cbac537793f828bb7dd398b9e7a2df41f3591aedd2aa6
-  data.tar.gz: 3d4ad85f0e311e7ec907e51bc837fad936658648f718986d2049c05b8e9391a3
+  metadata.gz: 3e9f5a6eb41a075cebcde2daf0e8811e1af414776f7807a14e07e9ed228c7657
+  data.tar.gz: 1d566c0e5b68123699f6f33185857ce00e6eb3b1659eae5c0f0b896443a36527
 SHA512:
-  metadata.gz: 93c77c5abbef5ed5436b00220acdaeec1a774d23ea6e3418ebe0c29b5511b7da4439902bccbc264c4111ba5f5bb529e30e0215a93bc94cd6607f4ee89445ec2e
-  data.tar.gz: 59463ee050dec081e27b81829c79515e3845a7f15cab56cfbca7763a317ce11a864f4b019dca9ac276f95068ed7f5bb2ab21ad7923a5c40535faf79c033639ff
+  metadata.gz: dc90dd50e914c27b28463992bbe33b0ef52eb077bd666519b876575202cee39babfed39720e2c22b66f3c456460bdcd16446876bb2827714b9665ed72c655ce0
+  data.tar.gz: 18b31ba92269e3340cc385e2a8b953bbe7b75b0db1f7323dd4e00d55faa03ebf71a097a940de69c84183a5115d2e982ba0a8aa2f480ca495a8d2119a93d2aa4f

data/bake/utopia/components.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+NPM = ENV["NPM"] || "npm"
+
+# Update public components from production JavaScript packages.
+#
+# Packages are copied from their `dist` directory when present, or otherwise
+# from the package root. The `utopia.components` section of `package.json` can
+# specify per-package `include` patterns to select only required files.
+#
+# @parameter root [String] The project root directory.
+def update(root: context.root)
+	require "json"
+	require "open3"
+	require "utopia/components"
+	
+	components = Utopia::Components.new(root)
+	production_packages = fetch_production_packages(components.package_root)
+	
+	components.update(production_packages)
+end
+
+private
+
+def fetch_production_packages(package_root)
+	stdout, _status = Open3.capture2(NPM, "ls", "--production", "--json", chdir: package_root.to_s)
+	json = JSON.parse(stdout)
+	
+	flatten_package_dependencies(json).sort.uniq
+end
+
+def flatten_package_dependencies(json, into = [])
+	if json["dependencies"]
+		json["dependencies"].each do |name, details|
+			into << name
+			flatten_package_dependencies(details, into)
+		end
+	end
+	
+	return into
+end

data/context/integrating-with-javascript.md

@@ -17,7 +17,7 @@ $ npm install jquery
 Copy the distribution files to `public/_components`:
 
 ```bash
-$ bundle exec bake utopia:node:update
+$ bundle exec bake utopia:components:update
 ```
 
 This will copy the library's distribution files (typically from `node_modules/*/dist/`) to your `public/_components/` directory, making them available for local serving.

data/lib/utopia/components.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "fileutils"
+require "json"
+require "pathname"
+
+module Utopia
+	# Installs JavaScript packages into the public components directory. Package contents are copied from `dist` when it exists, otherwise from the package root.
+	#
+	# By default, the complete source directory is installed. Projects can limit an individual package to a set of files using `utopia.components` in their `package.json` file.
+	class Components
+		# Initialize a component installer for the given project root.
+		#
+		# @parameter root [String | Pathname] The project root directory.
+		def initialize(root)
+			@root = Pathname.new(root)
+			@package_root = @root + "node_modules"
+			
+			# This is a legacy path:
+			unless @package_root.directory?
+				@package_root = @root + "lib/components"
+			end
+			
+			@install_root = @root + "public/_components"
+			@configuration = load_configuration
+		end
+		
+		# @attribute [Pathname] The directory containing the installed JavaScript packages.
+		attr :package_root
+		
+		# Update the specified packages in the public components directory.
+		#
+		# @parameter package_names [Array(String)] The production package names to install.
+		def update(package_names)
+			expand_package_paths(@package_root).each do |package_path|
+				package_name = package_path.relative_path_from(@package_root).to_s
+				
+				if package_names.include?(package_name)
+					install(package_name, package_path)
+				end
+			end
+		end
+		
+		private
+		
+		# Load the optional per-package installation rules. A missing `package.json`, or a file without `utopia.components`, preserves the default behaviour of copying complete packages.
+		# @returns [Hash] The per-package installation rules.
+		def load_configuration
+			package_path = @root + "package.json"
+			
+			unless package_path.file?
+				return {}
+			end
+			
+			configuration = JSON.parse(package_path.read).dig("utopia", "components") || {}
+			
+			unless configuration.is_a?(Hash)
+				raise ArgumentError, "utopia.components must be an object!"
+			end
+			
+			return configuration
+		end
+		
+		# Install one package. Distribution directories are preferred because they generally contain the browser-ready form of a package.
+		# @parameter package_name [String] The package name relative to `node_modules`.
+		# @parameter package_path [Pathname] The package source directory.
+		def install(package_name, package_path)
+			install_path = @install_root + package_name
+			dist_path = package_path + "dist"
+			
+			if dist_path.directory?
+				source_path = dist_path
+			else
+				source_path = package_path
+			end
+			
+			configuration = @configuration[package_name]
+			
+			if configuration
+				install_selected(package_name, source_path, install_path, configuration)
+			else
+				FileUtils::Verbose.rm_rf(install_path)
+				FileUtils::Verbose.mkpath(install_path.dirname)
+				FileUtils::Verbose.cp_r(source_path, install_path)
+			end
+		end
+		
+		# Install only the files matched by the configured include patterns. Every pattern is resolved before removing the existing installation, so an invalid configuration cannot leave a package partially installed or remove a previously working copy.
+		# @parameter package_name [String] The package name relative to `node_modules`.
+		# @parameter source_path [Pathname] The package source directory.
+		# @parameter install_path [Pathname] The destination directory.
+		# @parameter configuration [Hash] The package installation rules.
+		def install_selected(package_name, source_path, install_path, configuration)
+			unless configuration.is_a?(Hash)
+				raise ArgumentError, "utopia.components.#{package_name}.include must be a non-empty array!"
+			end
+			
+			include_patterns = configuration["include"]
+			
+			unless include_patterns.is_a?(Array) && include_patterns.any?
+				raise ArgumentError, "utopia.components.#{package_name}.include must be a non-empty array!"
+			end
+			
+			paths = include_patterns.flat_map do |pattern|
+				included_paths(package_name, source_path, pattern)
+			end.uniq.sort
+			
+			FileUtils::Verbose.rm_rf(install_path)
+			
+			paths.each do |relative_path|
+				source_file = source_path + relative_path
+				install_file = install_path + relative_path
+				
+				FileUtils::Verbose.mkpath(install_file.dirname)
+				FileUtils::Verbose.cp(source_file, install_file)
+			end
+		end
+		
+		# Expand one include pattern into files relative to the package source. Directories are excluded so each result can be copied independently.
+		# @parameter package_name [String] The package name used in validation errors.
+		# @parameter source_path [Pathname] The package source directory.
+		# @parameter pattern [String] The include pattern to expand.
+		# @returns [Array(String)] The matching file paths relative to the package source.
+		def included_paths(package_name, source_path, pattern)
+			unless pattern.is_a?(String) && relative_pattern?(pattern)
+				raise ArgumentError, "Invalid include pattern for #{package_name}: #{pattern.inspect}"
+			end
+			
+			paths = Dir.glob(pattern, base: source_path.to_s).select do |relative_path|
+				(source_path + relative_path).file?
+			end
+			
+			if paths.empty?
+				raise ArgumentError, "Include pattern for #{package_name} matched no files: #{pattern.inspect}"
+			end
+			
+			return paths
+		end
+		
+		# Determine whether the pattern is contained within the package source. Absolute paths and parent traversal are rejected because they could otherwise copy arbitrary files from outside the package.
+		# @parameter pattern [String] The include pattern to validate.
+		# @returns [Boolean] Whether the pattern is relative and does not contain parent traversal.
+		def relative_pattern?(pattern)
+			path = Pathname.new(pattern)
+			
+			if path.absolute?
+				return false
+			end
+			
+			if path.each_filename.any?{|component| component == ".."}
+				return false
+			end
+			
+			return true
+		end
+		
+		# Enumerate packages in `node_modules`, descending through scoped package directories such as `@socketry` while preserving their scoped names.
+		# @parameter root [Pathname] The directory to enumerate.
+		# @parameter into [Array(Pathname)] The array into which package paths are appended.
+		# @returns [Array(Pathname)] The discovered package directories.
+		def expand_package_paths(root, into = [])
+			root.children.select(&:directory?).each do |path|
+				basename = path.basename.to_s
+				
+				# Handle organisation sub-directories which start with an '@' symbol:
+				if basename.start_with?("@")
+					expand_package_paths(path, into)
+				else
+					into << path
+				end
+			end
+			
+			return into
+		end
+	end
+end

data/lib/utopia/import_map.rb

@@ -268,13 +268,7 @@ module Utopia
 		# 	page_map = import_map.relative_to("/foo/bar/")
 		# 	# Base becomes: "../../_components/"
 		def relative_to(path)
-			if @base
-				# Calculate the relative path from the page to the base
-				relative_path = @base.path.relative(path)
-				resolved_base = Protocol::URL::Relative.new(relative_path)
-			else
-				resolved_base = nil
-			end
+			resolved_base = @base&.relative_to(path)
 			
 			instance = self.class.new(@imports.dup, @integrity.dup, @scopes.dup, base: resolved_base)
 			
@@ -285,10 +279,12 @@ module Utopia
 		#
 		# @parameter value [String] The import URL or path value.
 		# @parameter base [Protocol::URL | Nil] The base URL context for resolving relative paths.
-		# @returns [Protocol::URL | String] The resolved URL object or original string.
+		# @returns [Protocol::URL] The resolved URL.
 		private def resolve_value(value, base)
+			value = Protocol::URL[value]
+			
 			if base
-				base + Protocol::URL[value]
+				base + value
 			else
 				value
 			end
@@ -303,7 +299,7 @@ module Utopia
 			result = {}
 			
 			imports.each do |specifier, value|
-				result[specifier] = resolve_value(value, base).to_s
+				result[specifier] = resolve_value(value, base).to_s(explicit: true)
 			end
 			
 			result

data/lib/utopia/version.rb

@@ -5,5 +5,5 @@
 
 # @namespace
 module Utopia
-	VERSION = "3.0.2"
+	VERSION = "3.0.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: utopia
 version: !ruby/object:Gem::Version
-  version: 3.0.2
+  version: 3.0.4
 platform: ruby
 authors:
 - Samuel Williams
@@ -203,14 +203,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.16'
+        version: '0.18'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.16'
+        version: '0.18'
 - !ruby/object:Gem::Dependency
   name: samovar
   requirement: !ruby/object:Gem::Requirement
@@ -272,8 +272,8 @@ extensions: []
 extra_rdoc_files: []
 files:
 - bake/utopia.rb
+- bake/utopia/components.rb
 - bake/utopia/environment.rb
-- bake/utopia/node.rb
 - bake/utopia/server.rb
 - bake/utopia/shell.rb
 - bake/utopia/site.rb
@@ -287,6 +287,7 @@ files:
 - context/what-is-xnode.md
 - lib/utopia.rb
 - lib/utopia/application.rb
+- lib/utopia/components.rb
 - lib/utopia/content.rb
 - lib/utopia/content/builder.rb
 - lib/utopia/content/document.rb

data/bake/utopia/node.rb

@@ -1,87 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2016-2025, by Samuel Williams.
-
-NPM = ENV["NPM"] || "npm"
-
-def update
-	require "fileutils"
-	require "utopia/path"
-	
-	root = Pathname.new(context.root)
-	package_root = root + "node_modules"
-	
-	# This is a legacy path:
-	unless package_root.directory?
-		package_root = root + "lib/components"
-	end
-	
-	install_root = root + "public/_components"
-	
-	# Fetch only production dependencies using `npm ls --production`
-	production_packages = fetch_production_packages(package_root)
-	package_paths = expand_package_paths(package_root).select do |path|
-		package_name = path.relative_path_from(package_root).to_s
-		production_packages.include?(package_name)
-	end
-	
-	package_paths.each do |package_path|
-		package_directory = package_path.relative_path_from(package_root)
-		install_path = install_root + package_directory
-		
-		dist_path = package_path + "dist"
-		
-		FileUtils::Verbose.rm_rf(install_path)
-		FileUtils::Verbose.mkpath(install_path.dirname)
-		
-		# If a package has a dist directory, we only symlink that... otherwise we have to do the entire package, and hope that bower's ignore was setup correctly:
-		if dist_path.exist?
-			link_path = Utopia::Path.shortest_path(dist_path, install_path)
-		else
-			link_path = Utopia::Path.shortest_path(package_path, install_path)
-		end
-		
-		FileUtils::Verbose.cp_r File.expand_path(link_path, install_path), install_path
-	end
-end
-
-private
-
-def fetch_production_packages(package_root)
-	require "json"
-	require "open3"
-	
-	stdout, _status = Open3.capture2(NPM, "ls", "--production", "--json", chdir: package_root.to_s)
-	
-	json = JSON.parse(stdout)
-	
-	flatten_package_dependencies(json).sort.uniq
-end
-
-def flatten_package_dependencies(json, into = [])
-	if json["dependencies"]
-		json["dependencies"].each do |name, details|
-			into << name
-			flatten_package_dependencies(details, into)
-		end
-	end
-	
-	return into
-end
-
-def expand_package_paths(root, into = [])
-	paths = root.children.select(&:directory?)
-	
-	paths.each do |path|
-		basename = path.basename.to_s
-		# Handle organisation sub-directories which start with an '@' symbol:
-		if basename.start_with?("@")
-			expand_package_paths(path, into)
-		else
-			into << path
-		end
-	end
-	
-	return into
-end