inline_svg 0.11.0 → 1.7.2

data/CHANGELOG.md

@@ -3,8 +3,130 @@ All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased][unreleased]
+
 - Nothing
 
+## [1.7.2] - 2020-12-07
+### Fixed
+- Improve performance of `CachedAssetFile`. [#118](https://github.com/jamesmartin/inline_svg/pull/118). Thanks [@stevendaniels](https://github.com/stevendaniels)
+- Avoid XSS by preventing malicious input of filenames. [#117](https://github.com/jamesmartin/inline_svg/pull/117). Thanks [@pbyrne](https://github.com/pbyrne).
+
+## [1.7.1] - 2020-03-17
+### Fixed
+- Static Asset Finder uses pathname for compatibility with Sprockets 4+. [#106](https://github.com/jamesmartin/inline_svg/pull/106). Thanks [@subdigital](https://github.com/subdigital)
+
+## [1.7.0] - 2020-02-13
+### Added
+- WebpackAssetFinder serves files from dev server if one is running. [#111](https://github.com/jamesmartin/inline_svg/pull/111). Thanks, [@connorshea](https://github.com/connorshea)
+
+### Fixed
+- Using Webpacker and Asset Pipeline in a single App could result in SVGs not being found because the wrong `AssetFinder` was used. [#114](https://github.com/jamesmartin/inline_svg/pull/114). Thanks, [@kylefox](https://github.com/kylefox)
+- Prevent "EOFError error" when using webpack dev server over HTTPS [#113](https://github.com/jamesmartin/inline_svg/pull/113). Thanks, [@kylefox](https://github.com/kylefox)
+
+
+## [1.6.0] - 2019-11-13
+### Added
+- Support Webpack via the new `inline_svg_pack_tag` helper and deprecate `inline_svg` helper in preparation for v2.0.
+[#103](https://github.com/jamesmartin/inline_svg/pull/103)
+Thanks, [@kylefox](https://github.com/kylefox)
+
+## [1.5.2] - 2019-06-20
+### Fixed
+- Revert automatic Webpack asset finder behavior. Make Webpack "opt-in".
+  [#98](https://github.com/jamesmartin/inline_svg/issues/98)
+
+## [1.5.1] - 2019-06-18
+### Fixed
+- Prevent nil asset finder when neither Sprockets or Webpacker are available
+  [#97](https://github.com/jamesmartin/inline_svg/issues/97)
+
+## [1.5.0] - 2019-06-17
+### Added
+- Support for finding assets bundled by Webpacker
+  [#96](https://github.com/jamesmartin/inline_svg/pull/96)
+
+## [1.4.0] - 2019-04-19
+### Fixed
+- Prevent invalid XML names being generated via IdGenerator
+  [#87](https://github.com/jamesmartin/inline_svg/issues/87)
+  Thanks, [@endorfin](https://github.com/endorfin)
+
+### Added
+- Raise error on file not found (if configured)
+  [#93](https://github.com/jamesmartin/inline_svg/issues/93)
+
+## [1.3.1] - 2017-12-14
+### Fixed
+- Allow Ruby < 2.1 to work with `CachedAssetFile`
+  [#80](https://github.com/jamesmartin/inline_svg/pull/80)
+
+## [1.3.0] - 2017-10-30
+### Added
+- Aria hidden attribute
+  [#78](https://github.com/jamesmartin/inline_svg/pull/78)
+  and [#79](https://github.com/jamesmartin/inline_svg/pull/79)
+- In-line CSS style attribute
+  [#71](https://github.com/jamesmartin/inline_svg/pull/71)
+
+### Fixed
+- Make aria ID attributes unique
+  [#77](https://github.com/jamesmartin/inline_svg/pull/77)
+
+## [1.2.3] - 2017-08-17
+### Fixed
+- Handle UTF-8 characters in SVG documents
+  [#60](https://github.com/jamesmartin/inline_svg/pull/69)
+
+## [1.2.2] - 2017-07-06
+### Fixed
+- Handle malformed documents that don't contain a root SVG element
+  [#60](https://github.com/jamesmartin/inline_svg/pull/65)
+### Added
+- Add configurable CSS class to empty SVG document
+  [#67](https://github.com/jamesmartin/inline_svg/pull/67)
+
+## [1.2.1] - 2017-05-02
+### Fixed
+- Select most exactly matching cached asset file when multiple files match
+  given asset name [#64](https://github.com/jamesmartin/inline_svg/pull/64)
+
+## [1.2.0] - 2017-04-20
+### Added
+- Cached asset file (load assets into memory at boot time)
+  [#62](https://github.com/jamesmartin/inline_svg/pull/62)
+
+## [1.1.0] - 2017-04-12
+### Added
+- Allow configurable asset file implementations
+  [#61](https://github.com/jamesmartin/inline_svg/pull/61)
+
+## [1.0.1] - 2017-04-10
+### Fixed
+- Don't override custom asset finders in Railtie
+
+## [1.0.0] - 2017-04-7
+### Added
+- Remove dependency on `Loofah` while maintaining basic `nocomment` transform
+
+## [0.12.1] - 2017-03-24
+### Added
+- Relax dependency on `Nokogiri` to allow users to upgrade to v1.7x, preventing
+  exposure to
+  [CVE-2016-4658](https://github.com/sparklemotion/nokogiri/issues/1615):
+  [#59](https://github.com/jamesmartin/inline_svg/issues/59)
+
+## [0.12.0] - 2017-03-16
+### Added
+- Relax dependency on `ActiveSupport` to allow Rails 3 applications to use the
+  gem: [#54](https://github.com/jamesmartin/inline_svg/issues/54)
+
+## [0.11.1] - 2016-11-22
+### Fixed
+- Dasherize data attribute names:
+  [#51](https://github.com/jamesmartin/inline_svg/issues/51)
+- Prevent ID collisions between `desc` and `title` attrs:
+  [#52](https://github.com/jamesmartin/inline_svg/pull/52)
+
 ## [0.11.0] - 2016-07-24
 ### Added
 - Priority ordering for transformations
@@ -76,7 +198,7 @@ transformations](https://github.com/jamesmartin/inline_svg/blob/master/README.md
 
 ## [0.5.1] - 2015-03-30
 ### Warning
-*** This version is NOT comaptible with Sprockets >= 3.***
+** This version is NOT comaptible with Sprockets >= 3. **
 
 ### Fixed
 - Support for ActiveSupport (and hence, Rails) 4.2.x. Thanks, @jmarceli.
@@ -117,7 +239,27 @@ transformations](https://github.com/jamesmartin/inline_svg/blob/master/README.md
 ### Added
 - Basic Railtie and view helper to inline SVG documents to Rails views.
 
-[unreleased]: https://github.com/jamesmartin/inline_svg/compare/v0.11.0...HEAD
+[unreleased]: https://github.com/jamesmartin/inline_svg/compare/v1.7.2...HEAD
+[1.7.2]: https://github.com/jamesmartin/inline_svg/compare/v1.7.1...v1.7.2
+[1.7.1]: https://github.com/jamesmartin/inline_svg/compare/v1.7.0...v1.7.1
+[1.7.0]: https://github.com/jamesmartin/inline_svg/compare/v1.6.0...v1.7.0
+[1.6.0]: https://github.com/jamesmartin/inline_svg/compare/v1.5.2...v1.6.0
+[1.5.2]: https://github.com/jamesmartin/inline_svg/compare/v1.5.1...v1.5.2
+[1.5.1]: https://github.com/jamesmartin/inline_svg/compare/v1.5.0...v1.5.1
+[1.5.0]: https://github.com/jamesmartin/inline_svg/compare/v1.4.0...v1.5.0
+[1.4.0]: https://github.com/jamesmartin/inline_svg/compare/v1.3.1...v1.4.0
+[1.3.1]: https://github.com/jamesmartin/inline_svg/compare/v1.3.0...v1.3.1
+[1.3.0]: https://github.com/jamesmartin/inline_svg/compare/v1.2.3...v1.3.0
+[1.2.3]: https://github.com/jamesmartin/inline_svg/compare/v1.2.2...v1.2.3
+[1.2.2]: https://github.com/jamesmartin/inline_svg/compare/v1.2.1...v1.2.2
+[1.2.1]: https://github.com/jamesmartin/inline_svg/compare/v1.2.0...v1.2.1
+[1.2.0]: https://github.com/jamesmartin/inline_svg/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/jamesmartin/inline_svg/compare/v1.0.1...v1.1.0
+[1.0.1]: https://github.com/jamesmartin/inline_svg/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/jamesmartin/inline_svg/compare/v0.12.1...v1.0.0
+[0.12.1]: https://github.com/jamesmartin/inline_svg/compare/v0.12.0...v0.12.1
+[0.12.0]: https://github.com/jamesmartin/inline_svg/compare/v0.11.1...v0.12.0
+[0.11.1]: https://github.com/jamesmartin/inline_svg/compare/v0.11.0...v0.11.1
 [0.11.0]: https://github.com/jamesmartin/inline_svg/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/jamesmartin/inline_svg/compare/v0.9.1...v0.10.0
 [0.9.1]: https://github.com/jamesmartin/inline_svg/compare/v0.9.0...v0.9.1

data/README.md

@@ -1,19 +1,25 @@
 # Inline SVG
 
+![Unit tests](https://github.com/jamesmartin/inline_svg/workflows/Ruby/badge.svg)
+![Integration Tests](https://github.com/jamesmartin/inline_svg/workflows/Integration%20Tests/badge.svg)
+
 Styling a SVG document with CSS for use on the web is most reliably achieved by
 [adding classes to the document and
 embedding](http://css-tricks.com/using-svg/) it inline in the HTML.
 
-This gem is a little Rails helper method (`inline_svg`) that reads an SVG document (via Sprockets, so works with the Rails Asset Pipeline), applies a CSS class attribute to the root of the document and
+This gem adds Rails helper methods (`inline_svg_tag` and `inline_svg_pack_tag`) that read an SVG document (via Sprockets or Webpacker, so works with the Rails Asset Pipeline), applies a CSS class attribute to the root of the document and
 then embeds it into a view.
 
-Inline SVG (from [v0.10.0](https://github.com/jamesmartin/inline_svg/releases/tag/v0.10.0)) supports both [Rails 4](http://weblog.rubyonrails.org/2013/6/25/Rails-4-0-final/) and [Rails 5](http://weblog.rubyonrails.org/2016/6/30/Rails-5-0-final/).
+Inline SVG supports:
 
-Want to embed SVGs with Javascript? You might like [RemoteSvg](https://github.com/jamesmartin/remote-svg), which features similar transforms but can also load SVGs from remote URLs (like S3 etc.).
+- [Rails 3](http://weblog.rubyonrails.org/2010/8/29/rails-3-0-it-s-done/) (from [v0.12.0](https://github.com/jamesmartin/inline_svg/releases/tag/v0.12.0))
+- [Rails 4](http://weblog.rubyonrails.org/2013/6/25/Rails-4-0-final/)
+- [Rails 5](http://weblog.rubyonrails.org/2016/6/30/Rails-5-0-final/) (from [v0.10.0](https://github.com/jamesmartin/inline_svg/releases/tag/v0.10.0))
+- [Rails 6](https://weblog.rubyonrails.org/2019/4/24/Rails-6-0-rc1-released/) with Sprockets or Webpacker (from [v1.5.2](https://github.com/jamesmartin/inline_svg/releases/tag/v1.5.2)).
 
 ## Changelog
 
-This project adheres to [Semantic Versioning](http://sermver.org). All notable changes are documented in the
+This project adheres to [Semantic Versioning](http://semver.org). All notable changes are documented in the
 [CHANGELOG](https://github.com/jamesmartin/inline_svg/blob/master/CHANGELOG.md).
 
 ## Installation
@@ -32,9 +38,15 @@ Or install it yourself as:
 
 ## Usage
 
+```ruby
+# Sprockets
+inline_svg_tag(file_name, options={})
+
+# Webpacker
+inline_svg_pack_tag(file_name, options={})
 ```
-inline_svg(file_name, options={})
-```
+
+_**Note:** The remainder of this README uses `inline_svg_tag` for examples, but the exact same principles work for `inline_svg_pack_tag`._
 
 The `file_name` can be a full path to a file, the file's basename or an `IO`
 object. The
@@ -42,18 +54,20 @@ actual path of the file on disk is resolved using
 [Sprockets](://github.com/sstephenson/sprockets) (when available), a naive file finder (`/public/assets/...`) or in the case of `IO` objects the SVG data is read from the object.
 This means you can pre-process and fingerprint your SVG files like other Rails assets, or choose to find SVG data yourself.
 
-Here's an example of embedding an SVG document and applying a 'class' attribute in
-HAML:
+Here's an example of embedding an SVG document and applying a 'class' attribute:
 
-```haml
- !!! 5 
-  %html
-    %head
-      %title Embedded SVG Documents
-    %body
-      %h1 Embedded SVG Documents
-      %div
-        = inline_svg "some-document.svg", class: 'some-class'
+```erb
+<html>
+  <head>
+    <title>Embedded SVG Documents<title>
+  </head>
+  <body>
+    <h1>Embedded SVG Documents</h1>
+    <div>
+      <%= inline_svg_tag "some-document.svg", class: 'some-class' %>
+    </div>
+  </body>
+</html>
 ```
 
 Here's some CSS to target the SVG, resize it and turn it an attractive shade of
@@ -69,30 +83,45 @@ blue:
 }
 ```
 
-## Options 
+## Options
 
 key                     | description
-:---------------------- | :---------- 
+:---------------------- | :----------
 `id`                    | set a ID attribute on the SVG
 `class`                 | set a CSS class attribute on the SVG
+`style`                 | set a CSS style attribute on the SVG
 `data`                  | add data attributes to the SVG (supply as a hash)
-`size`                  | set width and height attributes on the SVG <br/> Can also be set using `height` and/or `width` attributes, which take precedence over `size` <br/> Supplied as "{Width} * {Height}" or "{Number}", so "30px*45px" becomes `width="30px"` and `height="45px"`, and "50%" becomes `width="50%"` and `height="50%"`
+`size`                  | set width and height attributes on the SVG <br/> Can also be set using `height` and/or `width` attributes, which take precedence over `size` <br/> Supplied as "{Width} * {Height}" or "{Number}", so "30px\*45px" becomes `width="30px"` and `height="45px"`, and "50%" becomes `width="50%"` and `height="50%"`
 `title`                 | add a \<title\> node inside the top level of the SVG document
 `desc`                  | add a \<desc\> node inside the top level of the SVG document
-`nocomment`             | remove comment tags (and other unsafe/unknown tags) from svg (uses the [Loofah](https://github.com/flavorjones/loofah) gem)
+`nocomment`             | remove comment tags from the SVG document
 `preserve_aspect_ratio` | adds a `preserveAspectRatio` attribute to the SVG
 `aria`                  | adds common accessibility attributes to the SVG (see [PR #34](https://github.com/jamesmartin/inline_svg/pull/34#issue-152062674) for details)
+`aria_hidden`           | adds the `aria-hidden=true` attribute to the SVG
+`fallback`              | set fallback SVG document
 
 Example:
 
 ```ruby
-inline_svg("some-document.svg", id: 'some-id', class: 'some-class', data: {some: "value"}, size: '30% * 20%', title: 'Some Title', desc:
-'Some description', nocomment: true, preserve_aspect_ratio: 'xMaxYMax meet', aria: true)
+inline_svg_tag(
+  "some-document.svg",
+  id: 'some-id',
+  class: 'some-class',
+  data: {some: "value"},
+  size: '30% * 20%',
+  title: 'Some Title',
+  desc: 'Some description',
+  nocomment: true,
+  preserve_aspect_ratio: 'xMaxYMax meet',
+  aria: true,
+  aria_hidden: true,
+  fallback: 'fallback-document.svg'
+)
 ```
 
 ## Accessibility
 
-Use the `aria: true` option to make `inline_svg` add the following
+Use the `aria: true` option to make `inline_svg_tag` add the following
 accessibility (a11y) attributes to your embedded SVG:
 
 * Adds a `role="img"` attribute to the root SVG element
@@ -103,7 +132,7 @@ Here's an example:
 
 ```erb
 <%=
-  inline_svg('iconmonstr-glasses-12-icon.svg',
+  inline_svg_tag('iconmonstr-glasses-12-icon.svg',
     aria: true, title: 'An SVG',
     desc: 'This is my SVG. There are many like it. You get the picture')
 %>
@@ -117,11 +146,11 @@ Here's an example:
 </svg>
 ```
 
-***Note:*** The title and desc `id` attributes generated for, and referenced by, `aria-labelled-by` are one-way digests based on the value of the title and desc elements and an optional "salt" value using the SHA1 algorithm. This reduces the chance of `inline_svg` embedding elements inside the SVG with `id` attributes that clash with other elements elsewhere on the page.
+***Note:*** The title and desc `id` attributes generated for, and referenced by, `aria-labelled-by` are one-way digests based on the value of the title and desc elements and an optional "salt" value using the SHA1 algorithm. This reduces the chance of `inline_svg_tag` embedding elements inside the SVG with `id` attributes that clash with other elements elsewhere on the page.
 
 ## Custom Transformations
 
-The transformation behavior of `inline_svg` can be customized by creating custom transformation classes.
+The transformation behavior of `inline_svg_tag` can be customized by creating custom transformation classes.
 
 For example, inherit from `InlineSvg::CustomTransformation` and implement the `#transform` method:
 
@@ -131,10 +160,9 @@ For example, inherit from `InlineSvg::CustomTransformation` and implement the `#
 
 class MyCustomTransform < InlineSvg::CustomTransformation
   def transform(doc)
-    doc = Nokogiri::XML::Document.parse(doc.to_html)
-    svg = doc.at_css 'svg'
-    svg['custom'] = value
-    doc
+    with_svg(doc) do |svg|
+      svg["custom"] = value
+    end
   end
 end
 ```
@@ -151,7 +179,7 @@ end
 The custom transformation can then be called like so:
 ```haml
 %div
-  = inline_svg "some-document.svg", my_custom_attribute: 'some value'
+  = inline_svg_tag "some-document.svg", my_custom_attribute: 'some value'
 ```
 
 In this example, the following transformation would be applied to a SVG document:
@@ -172,8 +200,8 @@ end
 The custom transformation will be triggered even if you don't pass any attribute value
 ```haml
 %div
-  = inline_svg "some-document.svg"
-  = inline_svg "some-document.svg", my_custom_attribute: 'some value'
+  = inline_svg_tag "some-document.svg"
+  = inline_svg_tag "some-document.svg", my_custom_attribute: 'some value'
 ```
 
 In this example, the following transformation would be applied to a SVG document:
@@ -203,6 +231,92 @@ Transforms are applied in ascending order (lowest number first).
 ***Note***: Custom transformations are always applied *after* all built-in
 transformations, regardless of priority.
 
+## Custom asset file loader
+
+An asset file loader returns a `String` representing a SVG document given a
+filename. Custom asset loaders should be a Ruby object that responds to a
+method called `named`, that takes one argument (a string representing the
+filename of the SVG document).
+
+A simple example might look like this:
+
+```ruby
+class MyAssetFileLoader
+  def self.named(filename)
+    # ... load SVG document however you like
+    return "<svg>some document</svg>"
+  end
+end
+```
+
+Configure your custom asset file loader in an initializer like so:
+
+```ruby
+InlineSvg.configure do |config|
+  config.asset_file = MyAssetFileLoader
+end
+```
+
+## Caching all assets at boot time
+
+When your deployment strategy prevents dynamic asset file loading from disk it
+can be helpful to cache all possible SVG assets in memory at application boot
+time. In this case, you can configure the `InlineSvg::CachedAssetFile` to scan
+any number of paths on disks and load all the assets it finds into memory.
+
+For example, in this configuration we load every `*.svg` file found beneath the
+configured paths into memory:
+
+```ruby
+InlineSvg.configure do |config|
+  config.asset_file = InlineSvg::CachedAssetFile.new(
+    paths: [
+      "#{Rails.root}/public/path/to/assets",
+      "#{Rails.root}/public/other/path/to/assets"
+    ],
+    filters: /\.svg/
+  )
+end
+```
+
+**Note:** Paths are read recursively, so think about keeping your SVG assets
+restricted to as few paths as possible, and using the filter option to further
+restrict assets to only those likely to be used by `inline_svg_tag`.
+
+## Missing SVG Files
+
+If the specified SVG file cannot be found a helpful, empty SVG document is
+embedded into the page instead. The embedded document contains a single comment
+displaying the filename of the SVG image the helper tried to render:
+
+```html
+<svg><!-- SVG file not found: 'some-missing-file.svg' --></svg>
+```
+
+You may apply a class to this empty SVG document by specifying the following
+configuration:
+
+```rb
+InlineSvg.configure do |config|
+  config.svg_not_found_css_class = 'svg-not-found'
+end
+```
+
+Which would instead render:
+
+```html
+<svg class='svg-not-found'><!-- SVG file not found: 'some-missing-file.svg' --></svg>
+```
+
+Alternatively, `inline_svg_tag` can be configured to raise an exception when a file
+is not found:
+
+```ruby
+InlineSvg.configure do |config|
+  config.raise_on_file_not_found = true
+end
+```
+
 ## Contributing
 
 1. Fork it ( [http://github.com/jamesmartin/inline_svg/fork](http://github.com/jamesmartin/inline_svg/fork) )

data/Rakefile

@@ -1 +1,8 @@
 require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.pattern = Dir.glob("spec/**/*_spec.rb")
+  #t.rspec_opts = "--format documentation"
+end
+task :default => :spec