utopia 3.0.3 → 3.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c16b554d772d132bd1820ec17f402bbdf2d3720a5c6965f8673c0f06054f1c29
-  data.tar.gz: d6d839b6d55e3aff38507b9c4324d2631eb5a6b7f64eaeddb7e6b30185409b0a
+  metadata.gz: 3e9f5a6eb41a075cebcde2daf0e8811e1af414776f7807a14e07e9ed228c7657
+  data.tar.gz: 1d566c0e5b68123699f6f33185857ce00e6eb3b1659eae5c0f0b896443a36527
 SHA512:
-  metadata.gz: ab0202e8f8259c62856341332dcc7f37532535e968e90b75dceb4e8370eee7092ac5e7cdc4e3a2072f0394ba87b39994c18fa2ca1f17864d9f04f5974847a9b2
-  data.tar.gz: 14260960ab36d1cea1cabc02b6c43c29661efefb6e3e1566ef7e61ce87ba9f6525e111f9182e3beeac0a973bf303c147a71d3edc65d1cb75153c3c7377e7f2a8
+  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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: utopia
 version: !ruby/object:Gem::Version
-  version: 3.0.3
+  version: 3.0.4
 platform: ruby
 authors:
 - Samuel Williams
@@ -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