apropos 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 108512a68128ab79c042acc053dfdbaa25acbd0a
+  data.tar.gz: 992deab384d11673b20ae55c10e783f78c8d03d6
+SHA512:
+  metadata.gz: 87339533a21983bf2ef19b408f18864fe3ef345cf3319f39e0097b232b7c703b728e260eef746e3de5e23767812af5523f45f204aa21c7b1cf3c43e80e8ae253
+  data.tar.gz: 7d6f80d6f12b3d425c307582750e928df2e932534b6cfcfb8ad6dc7efadae6e0737387016393d159c5d1a8e1e31efacbb914aeffa3f726df927f38c7dd137a8b

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.sass-cache

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 (2013-08-21)
+
+Initial release.

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in apropos.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,14 @@
+
+   Copyright 2013 Square Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,94 @@
+# Apropos
+
+Apropos helps your site serve up the appropriate image for every visitor. Serving multiple versions of an image in responsive and/or localized web sites can be a chore, but Apropos simplifies and automates this task. Instead of manually writing a lot of CSS rules to swap different images, Apropos generates CSS for you based on a simple file naming convention.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'apropos'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install apropos
+
+## Usage
+
+Apropos depends on [Compass](http://compass-style.org/), so make sure you have that installed and configured in your project.
+
+### Sample configuration
+
+It's easy to get up and running with Apropos' basic configuration. Here's a sample stylesheet:
+
+```sass
+// Put this in a .sass (or .scss) file, such as application.css.sass
+
+// Substitute with your own breakpoint names and sizes
+$apropos-breakpoints: (medium, 768px), (large, 1024px)
+@import "apropos"
+
+.hero
+  // Use hero.jpg as the background of this element, and load any image
+  // variants that exist. If you use $generate-height: true, the function
+  // will also generate height definitions based on the height of each
+  // image (except dpi variants, since you want to display those at the
+  // original dimensions).
+  +apropos-bg-variants('hero.jpg', $generate-height: true)
+
+  // Customize other background styles
+  background-size: auto 100%
+  background-position: 50%
+```
+
+With that configuration set up, you can include any set of variants on your image with a simple file naming convention:
+
+    # File listing e.g. app/assets/images:
+    hero.jpg
+    hero.medium.jpg
+    hero.large.jpg
+    hero.2x.jpg
+    hero.2x.medium.jpg
+    hero.2x.large.jpg
+
+In this example, `hero.jpg` would be your base image, most likely a mobile version. `hero.medium.jpg` would be swapped in at the 768px breakpoint, and `hero.large.jpg` would be swapped in at 1024px. On a high-dpi device, `hero.2x.jpg`, `hero.2x.medium.jpg`, and `hero.2x.large.jpg` would be used instead. Note that the order of the file extensions doesn't matter; `hero.2x.medium.jpg` and `hero.medium.2x.jpg` work exactly the same.
+
+### Customization
+
+You can customize Apropos' breakpoints as shown above, and you can also customize the definition of the "high dpi" variant:
+
+```sass
+// The default extension name is "2x", we're overriding to use "hidpi"
+$apropos-hidpi-extension: "hidpi"
+// The default ratio is 1.75 (or 168 dpi), but here we're overriding that
+$apropos-hidpi-query: "(-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi)"
+@import "apropos"
+```
+
+If you want to do more advanced configuration like adding variants for localization, you can [customize Apropos in Ruby](doc-src/customization.md).
+
+## Why use Apropos?
+
+There are many tools and techniques for using responsive images. What makes Apropos different? A few key principles:
+
+- Let the browser do what it does best. CSS rules are more efficient and reliable than a solution that relies on Javascript or setting cookies for each visitor.
+- Avoid duplicate downloads. Almost all Javascript solutions, including polyfills for things like `srcset`, require unnecessary extra downloads, which CSS classes and media queries avoid.
+- No server logic should be required. Rather than setting a cookie and serving up different assets based on the cookie, we should be able to push compiled CSS and images to a CDN and rely on the browser to request the right images.
+- Take advantage of the "metadata" encoded in file names. We need to create separate assets for high-dpi devices, breakpoints, locales, etc anyway. We can lean on the filesystem with a simple naming convention rather than hand-coding a bunch of CSS.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+Before any changes are merged to master, we need you to sign a very simple
+[Individual Contributor Agreement](https://spreadsheets.google.com/a/squareup.com/spreadsheet/viewform?formkey=dDViT2xzUHAwRkI3X3k5Z0lQM091OGc6MQ&ndplr=1)
+(Google Form).
+
+© 2013 Square, Inc.

data/Rakefile

@@ -0,0 +1,20 @@
+require 'rspec/core/rake_task'
+require 'bundler/gem_tasks'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+begin
+  require 'cane/rake_task'
+
+  desc "Run cane to check quality metrics"
+  Cane::RakeTask.new(:quality) do |cane|
+    cane.abc_max = 10
+    cane.style_glob = 'lib/**/*.rb'
+  end
+
+  task :default => :quality
+rescue LoadError
+  warn "cane not available, quality task not provided."
+end

data/apropos.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'apropos/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "apropos"
+  spec.version       = Apropos::VERSION
+  spec.authors       = ["Gabriel Gilder"]
+  spec.email         = ["gabriel@squareup.com"]
+  spec.description   = %q{Apropos helps your site serve up the appropriate image for every visitor. Serving multiple versions of an image in responsive and/or localized web sites can be a chore, but Apropos simplifies and automates this task. Instead of manually writing a lot of CSS rules to swap different images, Apropos generates CSS for you based on a simple file naming convention.}
+  spec.summary       = %q{Apropos helps your site serve up the appropriate image for every visitor.}
+  spec.homepage      = "https://github.com/square/apropos"
+  spec.license       = "Apache 2.0"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "compass"
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec", "~> 2.13"
+  spec.add_development_dependency "cane"
+  spec.add_development_dependency "simplecov"
+end

data/doc-src/customization.md

@@ -0,0 +1,56 @@
+# Apropos
+
+## Advanced Customization
+
+If you want to go beyond breakpoint and resolution variants, you can use Apropos' Ruby interface to customize it for your app.
+
+Your customization code should go in a initializer file or in your Compass config file.
+
+### Example: localized images
+
+This example creates a variant that will recognize images for different languages. We assume that your app adds a class such as "lang-en" to the body to indicate the language of the page. With this code, you could have a base file "image.jpg" and variants such as "image.fr.jpg" and "image.ja.jpg" for different languages.
+
+And of course, this works in combination with other variants, so if you're using Apropos' hidpi and breakpoints you could have files like "image.medium.2x.fr.jpg" and all the proper rules would be generated.
+
+```ruby
+# This would be in your Compass config.rb or in a Rails initializer.
+# You may need to add `require 'apropos'` depending on load order in your app.
+
+SUPPORTED_LANGUAGES = ['en', 'fr', 'ja']
+
+# Use a broad regex to match the file extension...
+Apropos.add_class_image_variant(/^[a-z]{2}$/) do |match|
+  # ... but validate it against our app's supported languages
+  if SUPPORTED_LANGUAGES.include? match[0]
+    ".lang-#{match[0]}"
+  end
+end
+```
+
+### Example: country + language
+
+Here's a more complex example where we recognize simple locale identifiers that encode country as well as language. We also recognize just the language code, or just the country code. This means you could have images like "image.ca.jpg", "image.fr-ca.jpg", "image.fr.jpg", etc...
+
+```ruby
+SUPPORTED_COUNTRIES = ['us', 'ca', 'fr']
+SUPPORTED_LANGUAGES = ['en', 'fr']
+
+Apropos.add_class_image_variant(/^([a-z]{2})(-[a-z]{2})?$/) do |match|
+  lang_or_country = match[1]
+  # Strip off the dash
+  country = match[2][1..-1] if match[2]
+  if country
+    if SUPPORTED_COUNTRIES.include?(country) && SUPPORTED_LANGUAGES.include?(lang_or_country)
+      # Return a class like ".locale-fr-ca"
+      ".locale-#{lang_or_country}-#{country}"
+    end
+  else
+    # Determine if the two-letter code is a country, language, or both (like "fr")
+    classes = []
+    classes << ".lang-#{lang_or_country}" if SUPPORTED_LANGUAGES.include? lang_or_country
+    classes << ".country-#{lang_or_country}" if SUPPORTED_COUNTRIES.include? lang_or_country
+    # Return nil if the code is not a supported language or country
+    classes unless classes.empty?
+  end
+end
+```

data/lib/apropos.rb

@@ -0,0 +1,16 @@
+require 'compass'
+
+module Apropos
+  SEPARATOR = '.'
+  STYLESHEETS_DIR = File.expand_path('../../stylesheets', __FILE__)
+end
+
+Dir.glob(File.expand_path('../apropos/*.rb', __FILE__), &method(:require))
+
+module Sass::Script::Functions
+  include Apropos::SassFunctions
+end
+
+Compass::Frameworks.register('apropos', {
+  :stylesheets_directory => Apropos::STYLESHEETS_DIR
+})

data/lib/apropos/class_list.rb

@@ -0,0 +1,26 @@
+module Apropos
+  # ClassList wraps a list of CSS class selectors with several abilities:
+  # - Can be combined with other ClassLists
+  # - Can be compared to MediaQuery or ClassList objects via #sort_value, #type
+  # - Can be converted to CSS output
+  class ClassList
+    attr_reader :list, :sort_value
+
+    def initialize(list, sort_value=0)
+      @list = list
+      @sort_value = sort_value
+    end
+
+    def combine(other)
+      self.class.new(list + other.list)
+    end
+
+    def to_css
+      list.join(', ')
+    end
+
+    def type
+      "class"
+    end
+  end
+end

data/lib/apropos/extension_parser.rb

@@ -0,0 +1,35 @@
+module Apropos
+  # ExtensionParser manages registered variant parsers and provides a base
+  # class which new parsers subclass. Parsers are initialized with a pattern
+  # (String or Regexp) and a block that is called to generate ClassList or
+  # MediaQuery objects from the provided match data.
+  class ExtensionParser
+    @parsers = {}
+
+    def self.parsers
+      @parsers
+    end
+
+    def self.add_parser(extension, &block)
+      @parsers[extension] = new(extension, &block)
+    end
+
+    def self.each_parser(&block)
+      parsers.values.each(&block)
+    end
+
+    attr_reader :pattern
+
+    def initialize(pattern, &block)
+      @pattern = pattern
+      @match_block = block
+    end
+
+    def match(extension)
+      matchdata = pattern.match(extension)
+      if matchdata
+        @match_block.call(matchdata)
+      end
+    end
+  end
+end

data/lib/apropos/functions.rb

@@ -0,0 +1,68 @@
+# The Apropos module provides several functions for configuration and for
+# supplying rules to the Sass functions. See the README for configuration
+# examples.
+#
+# It also provides convenience functions used by the Sass functions.
+module Apropos
+  module_function
+
+  def image_variant_rules(path)
+    set = Set.new(path, images_dir)
+    set.variants.select(&:valid?).map do |variant|
+      variant.rule
+    end
+  end
+
+  def add_dpi_image_variant(id, query, order=0)
+    ExtensionParser.add_parser(id) do |match|
+      MediaQuery.new(query, order)
+    end
+  end
+
+  def add_breakpoint_image_variant(id, query, order=0)
+    ExtensionParser.add_parser(id) do |match|
+      MediaQuery.new(query, order)
+    end
+  end
+
+  def add_class_image_variant(id, class_list=[], order=0, &block)
+    parser = if block_given?
+      lambda do |match|
+        result = block.call(match)
+        create_class_rule(result) if result
+      end
+    else
+      lambda do |match|
+        create_class_rule(class_list, order)
+      end
+    end
+
+    ExtensionParser.add_parser(id, &parser)
+  end
+
+  def create_class_rule(class_list, order=0)
+    list = Array(class_list).map {|name| name[0] == '.' ? name : ".#{name}"}
+    ClassList.new(list, order)
+  end
+
+  def clear_image_variants
+    ExtensionParser.parsers.clear
+  end
+
+  def images_dir
+    config = Compass.configuration
+    Pathname.new(config.project_path).join(config.images_dir || '')
+  end
+
+  def convert_to_sass_value(val)
+    case val
+    when String
+      Sass::Script::String.new(val)
+    when Array
+      converted = val.map {|element| convert_to_sass_value(element) }
+      Sass::Script::List.new(converted, :space)
+    else
+      raise "convert_to_sass_value doesn't understand type #{val.class.inspect}"
+    end
+  end
+end

data/lib/apropos/media_query.rb

@@ -0,0 +1,41 @@
+module Apropos
+  # MediaQuery wraps a media query string with several features:
+  # - Parenthesizes queries when necessary
+  # - Can be combined with other MediaQuery objects
+  # - Can be compared to ClassList or MediaQuery objects via #type, #sort_value
+  # - Can be converted to CSS output
+  class MediaQuery
+    attr_reader :query_list, :sort_value
+
+    def initialize(query_string, sort_value=0)
+      @query_list = query_string.split(',').map { |q| parenthesize(q.strip) }
+      @sort_value = sort_value
+    end
+
+    def parenthesize(query)
+      unless query =~ /^\(.+\)$/
+        "(#{query})"
+      else
+        query
+      end
+    end
+
+    def combine(other)
+      other_ql = other.query_list
+      combo = query_list.map do |q|
+        other_ql.map do |q2|
+          "#{q} and #{q2}"
+        end
+      end.flatten
+      self.class.new(combo.join(', '))
+    end
+
+    def to_css
+      query_list.join(", ")
+    end
+
+    def type
+      "media"
+    end
+  end
+end