darkroom 0.0.2 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 518b5ff3d82631d41125029a7292c2bfdd8942990a7e92e2be08f99217fe8d02
-  data.tar.gz: 388cf8db580df8de6d85a9d196786ef7400a97a096dfbbb316de4b0dbca8e295
+  metadata.gz: 3c212cd979a1c11e4eb93a920a0b88bb20aae573fc8a0d290431203b77528eb3
+  data.tar.gz: a20ba0476f0508f574924e5d3d848a29f4adb550b4b5a1dd9e1ae16812c67a4e
 SHA512:
-  metadata.gz: 439b783c5d7afcb20c6a5bde715f686e42236bd70251af909938784f3c4e855f3e22b8fa779b1de19478e64e17462dc4fe37d28f043c0a62f95d13cc8e40829a
-  data.tar.gz: 3bb350472717b4a656e71ef3c7c1b8c200b88c7414c3f7feecfee46b19327e7d7bb5bb061878474d584c65afa84777cdf784fe76fd0cada86cecfbb20485fd13
+  metadata.gz: b8b038fe72b9e644eb323d3b2d8afecd3d525e7796687827cc621d556c1e593ffb1b95529e4336070819f837031b8b1ad45d1241465365336ec59f51d494367e
+  data.tar.gz: fc3407836eb5a01317fb20177dc52ac1ea1e8a114cf955c136e46de2cf8d800ed344219e558f2baa5bb3ef1d3bce960d0b34d38f0574d00288de1fbef0fcd7f0

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

@@ -6,6 +6,24 @@ performed for upload to a CDN or proxy server in production environments); this
 simple and performant in development. Darkroom also supports asset bundling for CSS and JavaScript using
 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     | 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
 
 Add this line to your Gemfile:
@@ -20,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('uglifier') # JavaScript and HTX minification
+```
+
 ## Usage
 
 To create and start using a Darkroom instance, specify one or more load paths (all other arguments are
@@ -27,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
 )
+```
 
-# Refreshe 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 existance 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
@@ -129,6 +178,77 @@ 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
+# 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
+)
+
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/npickens/darkroom.

data/VERSION

@@ -1 +1 @@
-0.0.2
+0.0.5