Packages/Infrastructure/Sources/Public/Enumerations/AssetExtension.swift

@@ -40,8 +40,8 @@ public extension AssetExtension {
         }
     }
 
-    /// The sub-directory within the static root that holds files with this extension, if any.
+    /// The folder within the static root that holds files with this extension, if any.
-    var subdirectory: String? {
+    var folder: String? {
         switch self {
         case .css: "css"
         case .js: "js"

Packages/Infrastructure/Sources/Public/Protocols/Asset.swift

@@ -1,11 +1,15 @@
 /// An asset shipped with a website: a file stored under the static files root and served by Hummingbird's `FileMiddleware` middleware.
 ///
 /// A conforming asset supplies its file name and the extensions it is available with, each resolving to its own file; the protocol derives the paths from them:
-/// the file's path within the static files root and the URL path it is served at, optionally versioned to bust caches.
+/// the file's path within the static files root and the URL path it is served at, optionally versioned to bust caches. Each file lands in its extension's own
+/// folder unless the asset names a ``folder`` of its own.
 public protocol Asset: Sendable {
 
     // MARK: Properties
 
+    /// The folder within the static files root that holds the asset's files, or `nil` (the default) to use each extension's own folder.
+    var folder: String? { get }
+
     /// The file extensions the asset is available with.
     var fileExtensions: [AssetExtension] { get }
 
@@ -18,6 +22,11 @@ public protocol Asset: Sendable {
 
 public extension Asset {
 
+    // MARK: Computed
+
+    /// The asset's files live in each extension's own folder by default.
+    var folder: String? { nil }
+
     // MARK: Methods
 
     /// Resolves the asset's path against the given base directory.
@@ -50,7 +59,7 @@ public extension Asset {
     ) -> String {
         let file = "\(fileName).\(fileExtension.rawValue)"
 
-        return fileExtension.subdirectory
+        return (folder ?? fileExtension.folder)
             .map { "\($0)/\(file)" } ?? file
     }
 

Packages/Infrastructure/Tests/Cases/Public/Enumerations/AssetExtensionTests.swift

@@ -23,13 +23,13 @@ struct AssetExtensionTests {
 
     @Test(arguments: zip(
         Self.extensions,
-        Self.subdirectories
+        Self.folders
     ))
-    func `subdirectory`(
+    func `folder`(
         for fileExtension: AssetExtension,
-        expects subdirectory: String?
+        expects folder: String?
     ) {
-        #expect(fileExtension.subdirectory == subdirectory)
+        #expect(fileExtension.folder == folder)
     }
 
 }
@@ -60,7 +60,7 @@ private extension AssetExtensionTests {
         "application/manifest+json",
         "application/xml"
     ]
-    static let subdirectories: [String?] = [
+    static let folders: [String?] = [
         "css",
         "js",
         nil,

Packages/Infrastructure/Tests/Cases/Public/Protocols/AssetTests.swift

@@ -14,6 +14,11 @@ struct AssetTests {
         fileExtensions: [.png],
         fileName: "icon"
     )
+    private let portrait = StubAsset(
+        folder: "img/organizer",
+        fileExtensions: [.jpg],
+        fileName: "portrait"
+    )
     private let shared = StubAsset(
         fileExtensions: [.css, .js],
         fileName: "shared"
@@ -22,13 +27,18 @@ struct AssetTests {
     // MARK: Method tests
 
     @Test
-    func `relative path nests the file inside its extension's sub-directory`() {
+    func `relative path nests the file inside its extension's folder`() {
         #expect(shared.relativePath(for: .css) == "css/shared.css")
         #expect(shared.relativePath(for: .js) == "js/shared.js")
     }
 
     @Test
-    func `relative path keeps the file at the root without a sub-directory`() {
+    func `relative path prefers the asset's own folder over the extension's`() {
+        #expect(portrait.relativePath(for: .jpg) == "img/organizer/portrait.jpg")
+    }
+
+    @Test
+    func `relative path keeps the file at the root without a folder`() {
         #expect(image.relativePath(for: .png) == "icon.png")
     }
 

Packages/Infrastructure/Tests/Utils/Assets/StubAsset.swift

@@ -1,10 +1,11 @@
 import Infrastructure
 
-/// An ``Asset`` with a fixed file name and set of extensions.
+/// An ``Asset`` with a fixed file name and set of extensions, optionally held in a folder of its own.
 struct StubAsset: Asset {
 
     // MARK: Properties
 
+    var folder: String? = nil
     let fileExtensions: [AssetExtension]
     let fileName: String