utopia 3.0.5 → 3.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0314485e770b9085839422a7484c179a39e447d81b15b211d70fbb4361fdc8b2'
-  data.tar.gz: 6e583362bc02ce48424f8e3adf7b9528bfd0990ea4ff946879d4bfbc95a52624
+  metadata.gz: 29332f03b21ff72e75b4f372deb3b317469ff3a5f2991ad363214b144d68ee4d
+  data.tar.gz: 3e3405b9bc409eeaf96e575bbb4f61fceb16298630b63f6069c2f443c2264025
 SHA512:
-  metadata.gz: 4a81a495790a61faea6d2ab3873fd4043807134a4dec40b50177318802eefc14484e8dc218373fbf32b8bfe441ff96038ccaa21093acda9610d1ebc3ad6e87bb
-  data.tar.gz: 35d548a73022d0307b8a631d3a8c755b1eef9fcb0edb3f7b224ac2ef57b2334018928f3c8a47e4fea6812882ce794973a639af563b5a941627f3cafcce8ca971
+  metadata.gz: 4f376ca1d057b6a91002e1abcab1ef98c0754772203c8d44392eca14e41df72b59e79bdb37a81e29624a6e0dd696e71ae63623a3ede9afec76b400825a8063fd
+  data.tar.gz: 4c20f0613d97496fd0fe1c4584384a1022677378b84504173817cdb6f6eb1a5405c440319ee482222e7c1fe7c8eea9401e1f7df89871607be8eeb023c9bf6487

data/context/integrating-with-javascript.md

@@ -8,20 +8,45 @@ Import maps provide a modern way to manage JavaScript module dependencies. Utopi
 
 ### Installing JavaScript Libraries
 
-First, install the library using npm:
+Declare browser libraries as production dependencies in `package.json`. The `bake-node.packages` section selects the files that should be served and assigns their browser import names:
+
+```json
+{
+  "private": true,
+  "dependencies": {
+    "@socketry/syntax": "^0.6.1"
+  },
+  "bake-node": {
+    "packages": {
+      "@socketry/syntax": {
+        "include": [
+          "Syntax.js"
+        ],
+        "imports": {
+          "@socketry/syntax": "Syntax.js"
+        }
+      }
+    }
+  }
+}
+```
+
+Install the dependencies using the configured package manager, then generate the browser-facing package projection:
 
 ```bash
-$ npm install jquery
+$ bundle exec bake node:install
+$ bundle exec bake node:packages:static
 ```
 
-Copy the distribution files to `public/_components`:
+This installs dependencies into `node_modules/` and copies only the selected browser files into `public/_components/`. Treat both directories as generated projections rather than authored source.
+
+Use an immutable installation and verify the checked-in projection in CI:
 
 ```bash
-$ bundle exec bake utopia:components:update
+$ bundle exec bake node:install frozen=true
+$ bundle exec bake node:packages:check
 ```
 
-This will copy the library's distribution files (typically from `node_modules/*/dist/`) to your `public/_components/` directory, making them available for local serving.
-
 ### Creating the Import Map
 
 Create a global import map in `lib/my_website/import_map.rb`:
@@ -30,12 +55,12 @@ Create a global import map in `lib/my_website/import_map.rb`:
 require "utopia/import_map"
 
 module MyWebsite
-	IMPORT_MAP = Utopia::ImportMap.build(base: "/_components/") do |map|
-		map.import("jquery", "./jquery/jquery.js")
-	end
+	IMPORT_MAP = Utopia::ImportMap.load_manifest("public/_components")
 end
 ```
 
+This loads the generated package mappings directly, so the browser import map remains synchronized with `package.json`.
+
 Then load this in `lib/my_website.rb`:
 
 ```ruby
@@ -64,15 +89,16 @@ Once the import map is set up, you can import and use the library in your script
 ```xrb
 <script type="module">
 	// <![CDATA[
-	import $ from 'jquery';
+	import Syntax from '@socketry/syntax';
 	
-	$(document).ready(function() {
-		console.log("jQuery is ready!");
-	});
+	await Syntax.highlight();
 	// ]]>
 </script>
 ```
 
+Inspect the generated import map with `bundle exec bake node:importmap:show` when debugging package resolution.
+
+See the [Bake Node documentation](https://socketry.github.io/bake-node/) for workspace packages, package selection, and alternative package managers.
 
 ### Advanced Import Map Features
 

data/lib/utopia/import_map.rb

@@ -6,6 +6,7 @@
 require "json"
 require "xrb"
 require "protocol/url"
+require "bake/node/manifest"
 
 module Utopia
 	# Represents an import map for JavaScript modules with support for URI and relative path resolution.
@@ -55,6 +56,19 @@ module Utopia
 	# 	
 	# 	puts page_map.to_html
 	class ImportMap
+		# Load the import mappings from a Bake Node static package manifest.
+		# @parameter root [String | Pathname] The static package output directory.
+		# @returns [ImportMap] A frozen import map using the manifest's public base URL.
+		def self.load_manifest(root)
+			manifest = Bake::Node::Manifest.load(root)
+			base = Protocol::URL[manifest.data.fetch("base")]
+			imports = manifest.import_map.fetch("imports").transform_values do |value|
+				Protocol::URL[value].relative_to(base).to_s
+			end
+			
+			return self.new(imports, base: base).freeze
+		end
+		
 		# Builder class for constructing import maps with scoped base URIs.
 		#
 		# The builder supports nested `with(base:)` blocks where each base is resolved

data/lib/utopia/version.rb

@@ -5,5 +5,5 @@
 
 # @namespace
 module Utopia
-	VERSION = "3.0.5"
+	VERSION = "3.0.6"
 end

data/readme.md

@@ -31,6 +31,10 @@ Please see the [project documentation](https://socketry.github.io/utopia/) for m
 
 Please see the [project releases](https://socketry.github.io/utopia/releases/index) for all releases.
 
+### v3.0.6
+
+  - [JavaScript Packages](https://socketry.github.io/utopia/releases/index#javascript-packages)
+
 ### v3.0.5
 
   - **Breaking** Remove support for JavaScript packages installed in `lib/components`; use `node_modules` instead.

data/releases.md

@@ -1,5 +1,13 @@
 # Releases
 
+## v3.0.6
+
+### JavaScript Packages
+
+Utopia now depends on `bake-node` for JavaScript dependency installation and static package projection. `Utopia::Components` and `utopia:components:update` have been removed. Replace the old task with `bundle exec bake node:packages:static`, and migrate package selection from `utopia.components` to `bake-node.packages` in `package.json`.
+
+Use `Utopia::ImportMap.load_manifest("public/_components")` to load the generated browser import mappings directly from the Bake Node manifest.
+
 ## v3.0.5
 
   - **Breaking** Remove support for JavaScript packages installed in `lib/components`; use `node_modules` instead.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: utopia
 version: !ruby/object:Gem::Version
-  version: 3.0.5
+  version: 3.0.6
 platform: ruby
 authors:
 - Samuel Williams
@@ -57,6 +57,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.20'
+- !ruby/object:Gem::Dependency
+  name: bake-node
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -272,7 +286,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - bake/utopia.rb
-- bake/utopia/components.rb
 - bake/utopia/environment.rb
 - bake/utopia/server.rb
 - bake/utopia/shell.rb
@@ -290,7 +303,6 @@ files:
 - lib/traces/provider/utopia/static/middleware.rb
 - 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/components.rb

@@ -1,44 +0,0 @@
-# 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/lib/utopia/components.rb

@@ -1,174 +0,0 @@
-# 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 from `node_modules` 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"
-			
-			@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