darkroom 0.0.3 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a77051a57dc9a5b32fe1ea1e96c831884183729058f1336139e15142d55a43f
-  data.tar.gz: 11ee7f486da94bf7c5dadf9af8e14fd9c1ab41a9620cc72c604885d9474d9150
+  metadata.gz: bfceb46e778a627cdd5fb64a51224ce2fdbfabb27dc4020e625d470fd80050a5
+  data.tar.gz: 38478af8de2fb0c42f46857e204b05ba76fa5f18415e0ae7d66baaefb04a5d8f
 SHA512:
-  metadata.gz: c4a4bb0e7cb9845154951aa703197be875b7777bba1f824d0bbba6ccfed609cebc9460a3c32db60ca846e819a0ac4b4a9c4024ba2b882a498108ef83230757d8
-  data.tar.gz: 83a14e41099925ae3ea44c23a18a044c1db1b1ca8fc10c15dabecf725270c32ec559165ef6e596852f5c7b22f2354ab92a0cdfadd654c1c8d22a6d9d2f5ae9f1
+  metadata.gz: 513abc20887e655aa9ecbcdfb706ae9c75d0e97907de7cd72e42aec6544839c4e96596f576b551b3e06dbc8d0fcd1edacbb212a662a017c6edbf0ed6c3111b58
+  data.tar.gz: e93f811868982d3ede4e64c848f9479a8564959845d0a1dea3a1bce980961d9fb8278513f969bfef45ac258fc39bce486c1915129ed69c914ffdce75ad0060ed

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2021 Nate Pickens
+Copyright 2021-2022 Nate Pickens
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
 documentation files (the "Software"), to deal in the Software without restriction, including without

data/README.md

@@ -9,19 +9,20 @@ each language's native import statement syntax.
 The following file types are supported out of the box, though support for others can be added (see the
 [Extending](#extending) section):
 
-| Name       | Content Type           | Exension(s) |
-| ---------- |----------------------- |-------------|
-| CSS        | text/css               | .css        |
-| JavaScript | application/javascript | .js         |
-| HTML       | text/html              | .htm, .html |
-| HTX        | application/javascript | .htx        |
-| ICO        | image/x-icon           | .ico        |
-| JPEG       | image/jpeg             | .jpg, .jpeg |
-| PNG        | image/png              | .png        |
-| SVG        | image/svg+xml          | .svg        |
-| Text       | text/plain             | .txt        |
-| WOFF       | font/woff              | .woff       |
-| WOFF2      | font/woff2             | .woff2      |
+| Name       | Content Type     | Extension(s) |
+|------------|------------------|--------------|
+| CSS        | text/css         | .css         |
+| HTML       | text/html        | .htm, .html  |
+| HTX        | text/javascript  | .htx         |
+| ICO        | image/x-icon     | .ico         |
+| JavaScript | text/javascript  | .js          |
+| JPEG       | image/jpeg       | .jpg, .jpeg  |
+| JSON       | application/json | .json        |
+| PNG        | image/png        | .png         |
+| SVG        | image/svg+xml    | .svg         |
+| Text       | text/plain       | .txt         |
+| WOFF       | font/woff        | .woff        |
+| WOFF2      | font/woff2       | .woff2       |
 
 ## Installation
 
@@ -37,6 +38,17 @@ Or install manually on the command line:
 gem install darkroom
 ```
 
+Darkroom depends on a few other gems for compilation and minification of certain asset types, but does not
+explicitly include them as dependencies since need for them varies from project to project. As such, if your
+project includes HTX templates or you wish to minify CSS and/or JavaScript assets, the following will need
+to be added to your Gemfile:
+
+```ruby
+gem('htx')    # HTX compilation
+gem('sassc')  # CSS minification
+gem('terser') # JavaScript and HTX minification
+```
+
 ## Usage
 
 To create and start using a Darkroom instance, specify one or more load paths (all other arguments are
@@ -44,50 +56,70 @@ optional):
 
 ```ruby
 darkroom = Darkroom.new('app/assets', 'vendor/assets', '...',
-  hosts: ['https://cdn1.com', '...']   # Hosts to prepend to asset paths (useful in production)
+  hosts: [                             # Hosts to prepend to asset paths (useful in production
+    'https://cname1.cdn.com',          # when assets are served from a CDN with multiple
+    'https://cname2.cdn.com',          # cnames); hosts are chosen round-robin per thread
+    '...',
+  ],
   prefix: '/static',                   # Prefix to add to all asset paths
-  pristine: ['/google-verify.html'],   # Paths with no prefix or versioning (e.g. /favicon.ico)
+  pristine: ['/google-verify.html'],   # Paths with no prefix or versioning (/favicon.ico,
+                                       # /mask-icon.svg, /humans.txt, and /robots.txt are
+                                       # included automatically)
   minify: true,                        # Minify assets that can be minified
-  minified_pattern: /(\.|-)min\.\w+$/, # Files that should not be minified
-  internal_pattern: /^\/components\//, # Files that cannot be accessed directly
+  minified_pattern: /(\.|-)min\.\w+$/, # Files to skip minification on when minify: true
+  internal_pattern: /^\/components\//, # Files to disallow direct external access to (they can
+                                       # still be imported into other assets)
   min_process_interval: 1,             # Minimum time that must elapse between process calls
 )
+```
 
-# Refresh any assets that have been modified (in development, this should be called at the
-# beginning of each web request).
+Note that assets paths across all load path directories must be globally unique (e.g. the existence of both
+`app/assets/app.js` and `vendor/assets/app.js` will result in an error).
+
+Darkroom will never update assets without explicitly being told to do so. The following call should be made
+once when the app is started and additionally at the beginning of each web request in development to refresh
+any modified assets:
+
+```ruby
 darkroom.process
+```
+
+Alternatively, assets can be dumped to disk when deploying to a production environment where assets will be
+uploaded to and served from a CDN or proxy server:
 
-# Dump assets to disk. Useful when deploying to a production environment where assets will be
-# uploaded to and served from a CDN or proxy server.
+```ruby
 darkroom.dump('output/dir',
   clear: true,            # Delete contents of output/dir before dumping
   include_pristine: true, # Include pristine assets (if preparing for CDN upload, files like
 )                         # /favicon.ico or /robots.txt should be left out)
 ```
 
-Note that assets paths across all load path directories must be globally unique (e.g. the existence of both
-`app/assets/app.js` and `vendor/assets/app.js` will result in an error).
-
 To work with assets:
 
 ```ruby
-# Get the external path that will be used by HTTP requests.
-path = darkroom.asset_path('/js/app.js') # => '/static/js/app-<fingerprint>.js'
+# A Darkroom instance has a few convenience helper methods.
+path = darkroom.asset_path('/js/app.js')           # => '/static/js/app-[fingerprint].js'
+integrity = darkroom.asset_integrity('/js/app.js') # => 'sha384-[hash]'
 
 # Retrieve the Asset object associated with a path.
 asset = darkroom.asset(path)
 
-# Getting paths directly from an Asset object will not include any host or prefix.
-assest.path           # => '/js/app.js'
-assest.path_versioned # => '/js/app-<fingerprint>.js'
+# Prefix (if set on the Darkroom instance) is included in the unversioned and versioned paths.
+assest.path                     # => '/js/app.js'
+assest.path_unversioned         # => '/static/js/app.js'
+assest.path_versioned           # => '/static/js/app-[fingerprint].js'
 
-asset.content_type # => 'application/javascript'
-asset.content      # Content of processed /js/app.js file
+asset.content_type              # => 'text/javascript'
+asset.content                   # Content of processed /js/app.js file
 
-asset.headers                   # => {'Content-Type' => 'application/javascript',
+asset.headers                   # => {'Content-Type' => 'text/javascript',
                                 #     'Cache-Control' => 'public, max-age=31536000'}
-asset.headers(versioned: false) # => {'Content-Type' => 'application/javascript',
-                                #     'ETag' => '<fingerprint>'}
+asset.headers(versioned: false) # => {'Content-Type' => 'text/javascript',
+                                #     'ETag' => '[fingerprint]'}
+
+asset.integrity                 # => 'sha384-[hash]'
+asset.integrity(:sha256)        # => 'sha256-[hash]'
+asset.integrity(:sha512)        # => 'sha512-[hash]'
 ```
 
 ## Asset Bundling
@@ -146,19 +178,73 @@ Imports can even be cyclical. If `asset-a.css` imports `asset-b.css` and vice-ve
 contain the content of both of those assets (though order will be different as an asset's own content always
 comes after any imported assets' contents).
 
+## Asset References
+
+Asset paths and content can be inserted into an asset by referencing an asset's path and including a query
+parameter.
+
+| String                           | Result                            |
+|----------------------------------|-----------------------------------|
+| /logo.svg?asset-path             | /prefix/logo-[fingerprint].svg    |
+| /logo.svg?asset-path=versioned   | /prefix/logo-[fingerprint].svg    |
+| /logo.svg?asset-path=unversioned | /prefix/logo.svg                  |
+| /logo.svg?asset-content          | data:image/svg+xml;base64,[data]  |
+| /logo.svg?asset-content=base64   | data:image/svg+xml;base64,[data]  |
+| /logo.svg?asset-content=utf8     | data:image/svg+xml;utf8,\<svg>... |
+
+Where these get recognized is specific to each asset type.
+
+* **CSS** - Within `url(...)`, which may be unquoted or quoted with single or double quotes.
+* **HTML** - Values of `href` and `src` attributes on `a`, `area`, `audio`, `base`, `embed`, `iframe`,
+  `img`, `input`, `link`, `script`, `source`, `track`, and `video` tags.
+* **HTX** - Same behavior as HTML.
+
+HTML assets additionally support the `?asset-content=displace` query parameter for use with `<link>`,
+`<script>`, and `<img>` tags with CSS, JavaScript, and SVG asset references, respectively. The entire tag is
+replaced appropriately.
+
+```html
+<!-- Source -->
+<head>
+  <title>My App</title>
+  <link href='/app.css?asset-content=displace' type='text/css'>
+  <script src='/app.js?asset-content=displace'></script>
+</head>
+
+<body>
+  <img src='/logo.svg?asset-content-displace'>
+</body>
+
+<!-- Result -->
+<head>
+  <title>My App</title>
+  <style>/* Content of /app.css */</style>
+  <script>/* Content of /app.js */</script>
+</head>
+
+<body>
+  <svg><!-- ... --></svg>
+</body>
+```
+
 ## Extending
 
 Darkroom is extensible. Support for arbitrary file types can be added as follows (all named parameters are
 optional):
 
 ```ruby
-Darkroom::Asset.add_spec('.extension1', 'extension2', '...', 'content/type',
-  dependency_regex: /import (?<path>.*)/, # Regex for identifying dependencies for bundling;
-                                          # must include `path` named capture group
-  compile_lib: 'some-compile-lib',        # Name of library required for compilation
-  compile: -> (path, content) { '...' },  # Proc that returns compiled content
-  minify_lib: 'some-minify-lib',          # Name of library required for minification
-  minify: -> (content) { '...' },         # Proc that returns minified content
+# Simple type with no special behavior.
+Darkroom.register('.extension1', 'extension2', '...', 'content/type')
+
+# Complex type with special behavior.
+Darkroom.register('.extension1', 'extension2', '...',
+  content_type: 'content/type',         # HTTP MIME type string
+  import_regex: /import (?<path>.*)/,   # Regex for identifying imports for bundling
+  reference_regex: /ref=(?<path>.*)/,   # Regex for identifying references to other assets
+  compile_lib: 'some-compile-lib',      # Name of library required for compilation
+  compile: ->(path, content) { '...' }, # Lambda that returns compiled content
+  minify_lib: 'some-minify-lib',        # Name of library required for minification
+  minify: ->(content) { '...' },        # Lambda that returns minified content
 )
 
 ```

data/VERSION

@@ -1 +1 @@
-0.0.3
+0.0.6