docks_theme_api 1.0.2

data/source/components/avatar/avatar.scss

@@ -0,0 +1,200 @@
+//        ___                     ___                 ___          ___
+//       /  /\        ___        /  /\        ___    /  /\        /  /\
+//      /  /::\      /__/\      /  /::\      /  /\  /  /::\      /  /::\
+//     /  /:/\:\     \  \:\    /  /:/\:\    /  /:/ /  /:/\:\    /  /:/\:\
+//    /  /:/~/::\     \  \:\  /  /:/~/::\  /  /:/ /  /:/~/::\  /  /:/~/:/
+//   /__/:/ /:/\:\___  \__\:\/__/:/ /:/\:\/  /::\/__/:/ /:/\:\/__/:/ /:/___
+//   \  \:\/:/__\/__/\ |  |:|\  \:\/:/__\/__/:/\:\  \:\/:/__\/\  \:\/:::::/
+//    \  \::/    \  \:\|  |:| \  \::/    \__\/  \:\  \::/      \  \::/~~~~
+//     \  \:\     \  \:\__|:|  \  \:\         \  \:\  \:\       \  \:\
+//      \  \:\     \__\::::/    \  \:\         \__\/\  \:\       \  \:\
+//       \__\/         ~~~~      \__\/               \__\/        \__\/
+
+//*
+// @pattern Avatar
+//
+// A small image representing someone associated with this project. The script
+// part of this component allows it to fetch avatar images from Github, Twitter,
+// or Gravatar, depending on the information provided. If no images are found
+// for the avatar, it will fall back to displaying their initials.
+//
+// @since 1.0.0
+
+//*
+// The size (height and width) of an `avatar`.
+// @type Length
+
+$avatar--size: 3rem;
+
+//*
+// The margin that should appear between two `avatar`s (including those on a
+// new line).
+// @type Length
+
+$avatar--spacing: half(default(spacing));
+
+//*
+// The core container for a single avatar. An avatar supports fetching of the
+// background image through either a [Github](http://github.com) profile name,
+// a [Twitter](http://twitter.com) username, or an email address that is
+// associated with a [Gravatar](http://gravatar.com) account. If any of the
+// above are given, clicking on the avatar will open a tab with the relevant
+// profile page open (or, compose a new email if email was the provided
+// identifier). If none of the above are given, the initials of the user's name
+// will be shown.
+//
+// @helper
+// <% docks_component("avatar:container") do %>
+//   <%= docks_component("avatar", author: OpenStruct.new(name: "Chris Sauve", github: "lemonmade")) %>
+// <% end %>
+
+.avatar {
+  // position
+  @include z-index(avatar, page);
+  position: relative;
+
+  // box model
+  flex: 0 0 auto;
+  display: inline-block;
+
+  // backdrop
+  background-color: color(gray-light);
+  border-radius: default(border-radius);
+  overflow: hidden;
+
+  // type
+  @include font-size(avatar);
+}
+
+//*
+// A container that shows the initals of the user. This will always be present
+// so that it is visible immediately on page load. The avatar image, which is
+// fetched by JavaScript, will be faded in over top of this subcomponent, if
+// available.
+//
+// Every initial of the passed name will be shown. There is enough space for
+// 2–3 initials, but any more than this will overflow the avatar. As such,
+// please restrict names to first and last or first, middle, and last.
+
+.avatar__initials {
+  // position
+  @include z-index(initials, avatar);
+  position: absolute;
+  top: 50%; left: 0;
+
+  // box model
+  width: 100%;
+  transform: translateY(-50%);
+
+  // backdrop
+  color: color(gray);
+
+  // type
+  font-size: 1em;
+  line-height: 1;
+  text-align: center;
+  text-transform: uppercase;
+}
+
+//*
+// The container for the avatar image. The image will be set by JavaScript as
+// a background image on this subcomponent, so if no image is provided this
+// container will effectively be invisible. Once the background image is
+// fetched (which will be done with a slight delay to prevent too much from
+// happening on page load), it is faded into place using the
+// `avatar__image--is-visible` state.
+
+.avatar__image {
+  // position
+  @include z-index(image, avatar);
+  position: relative;
+
+  // box model
+  height: $avatar--size;
+  width: $avatar--size;
+
+  // backdrop
+  opacity: 0;
+  transition: opacity 0.3s ease;
+  background-size: cover;
+  background-position: center center;
+  background-repeat: no-repeat;
+  overflow: hidden;
+}
+
+//*
+// The variation that causes the image to be faded into view.
+//
+// @demo_type none
+// @set_by Avatar#show_image
+
+.avatar__image--is-visible {
+  opacity: 1;
+}
+
+//*
+// Creates the rules that are required to restrict an `avatar__container` to
+// a particular number of `avatar`s per line.
+//
+// @param {Number} $n - The maximum number of `avatar`s allowed per line.
+
+@mixin avatar--restrict-to-n-avatars($n) {
+  max-width: (($n * $avatar--size) + ($n * $avatar--spacing));
+}
+
+//*
+// The container around a set of avatars. This container is important because it
+// eliminates the excess margin below and to the right of `avatar`s on the
+// outside edges of the container, but still allows them to be properly spaced
+// out horizontally and vertically. This is accomplished using negative margin
+// on the bottom and right to offset the margin of the contained `avatar`s.
+//
+// This container allows three avatars side-by-side, with additional avatars
+// breaking onto a new line. If you only need a single avatar, this container
+// is not necessary.
+//
+// You can create this component using the `"avatar:container"` helper. this
+// helper allows you to specify the size of the container:
+//
+// ```erb_demo
+// <div>
+//   <% docks_component("avatar:container") do %>
+//     <% 4.times do %>
+//       <%= docks_component("avatar", author: OpenStruct.new(name: "Chris Sauve", github: "lemonmade")) %>
+//     <% end %>
+//   <% end %>
+// </div>
+//
+// <div>
+//   <% docks_component("avatar:container", size: :large) do %>
+//     <% 4.times do %>
+//       <%= docks_component("avatar", author: OpenStruct.new(name: "Chris Sauve", github: "lemonmade")) %>
+//     <% end %>
+//   <% end %>
+// </div>
+// ```
+
+.avatar__container {
+  display: inline-flex;
+  flex-wrap: wrap;
+  overflow: hidden;
+  margin-right: negative($avatar--spacing) !important;
+  margin-bottom: negative($avatar--spacing) !important;
+  @include avatar--restrict-to-n-avatars(3);
+
+  > .avatar {
+    margin-right: $avatar--spacing;
+    margin-bottom: $avatar--spacing;
+  }
+}
+
+//*
+// A container that can hold more `avatar`s on a single line (four, instead of
+// the base three). Use this for situations in which you have more room
+// available for ancillary information like contributor information.
+//
+// @set_by :size (:large)
+
+.avatar__container--large {
+  @include avatar--restrict-to-n-avatars(4);
+}

data/source/components/avatar/avatar_container.erb

@@ -0,0 +1,13 @@
+<%
+  component.configure do |config|
+    config.defaults(size: :medium)
+    config.classes(container: "avatar__container")
+    config.conditional_classes(with: :size) do |size|
+      size == :medium ? {} : { container: "avatar__container--#{size}" }
+    end
+  end
+%>
+
+<div class="<%= component.classes_for(:container) %>">
+  <%= capture(&component.block) %>
+</div>

data/source/components/avatar/package.json

@@ -0,0 +1,3 @@
+{
+  "main": "avatar.js"
+}

data/source/components/avatar/spec/avatar_spec.js

@@ -0,0 +1,81 @@
+import "spec_helper";
+import Avatar, { classes, states, attrs } from "~components/avatar";
+
+var urlFromOptions, makeFixture, loadAndInit;
+
+urlFromOptions = (options = {}) => {
+  var url;
+
+  switch(options.name) {
+    case "github":
+      url = `https://github.com/${options.name}`;
+      break;
+    case "twitter":
+      url = `https://twitter.com/${options.name}`;
+      break;
+    case "email":
+      url = `mailto:${options.name}`;
+      break;
+  }
+
+  return url;
+};
+
+makeFixture = (options = {}) => {
+  var data = `${attrs.service}=${options.service} ${attrs.profile_name}=${options.name}`;
+
+  return `
+    <div class="${classes.root}" href="${urlFromOptions(options)}" ${data}>
+      <span class="${classes.initials}">CS</span>
+      <div class="${classes.image}"></div>
+    </div>
+  `;
+};
+
+loadAndInit = (...args) => {
+  Fixture.load(makeFixture(...args));
+  Avatar.init(Fixture.node);
+  return Fixture.node.querySelector(`.${classes.root}`);
+};
+
+describe("Avatar", () => {
+  describe(".init", () => {
+    beforeEach(function() {
+      sandbox.useFakeServer();
+      sandbox.useFakeTimers(Date.now());
+    });
+
+    it("has an init method", function() {
+      expect(Avatar.init).to.be.a.function;
+    });
+
+    it("loads email avatars", function() {
+      var avatar_node = loadAndInit({ service: "email", name: "chrismsauve@gmail.com" }),
+          image = avatar_node.querySelector(`.${classes.image}`);
+
+      sandbox.clock.tick(1000);
+      expect(image.classList.contains(states.image.visible)).to.be.true;
+      expect(image.style.backgroundImage).to.equal("url(http://avatars.io/email/chrismsauve@gmail.com)");
+    });
+
+    it("loads twitter avatars", function() {
+      var avatar_node = loadAndInit({ service: "twitter", name: "_lemonmade" }),
+          image = avatar_node.querySelector(`.${classes.image}`);
+
+      sandbox.clock.tick(1000);
+      expect(image.classList.contains(states.image.visible)).to.be.true;
+      expect(image.style.backgroundImage).to.equal("url(http://avatars.io/twitter/_lemonmade)");
+    });
+
+    // it("loads github avatars", function() {
+    //   var avatar_node = loadAndInit({ service: "github", name: "lemonmade" }),
+    //       image = avatar_node.querySelector(`.${classes.image}`);
+    //
+    //   sandbox.server.requests[0].respond(200, { "Content-Type": "application/json" }, "{'avatar_url': 'foo.png'}");
+    //   sandbox.clock.tick(1000);
+    //
+    //   expect(image.classList.contains(states.image.visible)).to.be.true;
+    //   expect(image.style.backgroundImage).to.equal("foo.png");
+    // });
+  });
+});

data/source/components/badge/badge.scss

@@ -0,0 +1,158 @@
+//                    ___        _____        ___          ___
+//       _____       /  /\      /  /::\      /  /\        /  /\
+//      /  /::\     /  /::\    /  /:/\:\    /  /:/_      /  /:/_
+//     /  /:/\:\   /  /:/\:\  /  /:/  \:\  /  /:/ /\    /  /:/ /\
+//    /  /:/~/::\ /  /:/~/::\/__/:/ \__\:|/  /:/_/::\  /  /:/ /:/_
+//   /__/:/ /:/\:/__/:/ /:/\:\  \:\ /  /:/__/:/__\/\:\/__/:/ /:/ /\
+//   \  \:\/:/~/:|  \:\/:/__\/\  \:\  /:/\  \:\ /~~/:/\  \:\/:/ /:/
+//    \  \::/ /:/ \  \::/      \  \:\/:/  \  \:\  /:/  \  \::/ /:/
+//     \  \:\/:/   \  \:\       \  \::/    \  \:\/:/    \  \:\/:/
+//      \  \::/     \  \:\       \__\/      \  \::/      \  \::/
+//       \__\/       \__\/                   \__\/        \__\/
+
+//*
+// @pattern Badge
+//
+// A badge is a small chunk of text in a colored box that denotes a particular
+// attribute about the interface element to which it is attached. When
+// additional explanatory text is required, use a `notice` instead — badges
+// should only ever be one word in length. It is appropriate to have multiple
+// badges attached to a single element if additional details about that
+// element need to be indicated.
+//
+// @since 1.0.0
+
+
+$badge--spacing: half(default(spacing));
+
+
+
+//*
+// The actual badge. Each badge provides spacing between itself and badges it
+// is next to, so they must be wrapped in a `badge__container` to remove any
+// excess outside spacing if you include more than a single badge.
+//
+// Because badges most often sit allongside other text, they are designed to
+// scale with the size of whatever container they are in. They will always be
+// slightly smaller than the text size of the content to which they are
+// attached such that the top and bottom of the badge approximately match the
+// ascenders/ descenders of the text.
+//
+// @markup
+// <div class="badge__container">
+//   <% 5.times do |i| %>
+//     <div class="badge">Badge <%= i + 1 %></div>
+//   <% end %>
+// </div>
+
+.badge {
+  // position
+  position: relative;
+
+  // box model
+  flex: 0 0 auto;
+  display: inline-block;
+  // A little extra bottom padding to make it look centered.
+  padding: 0.15em 0.5em 0.25em;
+
+  // backdrop
+  @include default(border-radius);
+  background-color: ui-color(gray, light);
+
+  // type
+  @include font-size(badge);
+  line-height: default(line-height);
+  vertical-align: middle;
+  color: ui-color(gray, darker);
+}
+
+//*
+// Use this badge variation when you are trying to indicate some sort of
+// warning to the user — for example, when the content to which this badge is
+// attached has been deprecated or has a common pitfall.
+//
+// @demo_type joint
+
+.badge--warning {
+  background-color: ui-color(yellow);
+  color: ui-color(yellow, dark);
+}
+
+//*
+// Use this badge variation when you are trying to indicate a new or updated
+// status for the attached content. For example, this badge might be used to
+// indicate something is in beta or has recently been upgraded or released.
+//
+// @demo_type joint
+
+.badge--new {
+  background-color: ui-color(blue);
+  color: ui-color(blue, darker);
+}
+
+//*
+// Use this badge variation when the attached content is meant to be
+// concealed, secret, or in some other way not intended to be used in the
+// average case. For example, this badge can be used to indicate that
+// something is private/ for internal use only.
+//
+// @demo_type joint
+
+.badge--secret {
+  background-color: ui-color(gray, darkest);
+  color: ui-color(gray);
+}
+
+//*
+// This variation is used to fix the vertical padding on badges that are meant
+// to contain content styled as code. Because the monospace font family has
+// different font properties, leaving the existing `padding`/ `line-height`
+// along results in the text sitting too closely to the top of the badge. This
+// fixes the problem using a very un-scientific redistribution of the
+// available padding.
+//
+// Note that, because the monospace font has more space allocated for each
+// character, a badge with this variant will be wider than one without it,
+// even if they have the same content.
+//
+// @demo_type select
+
+.badge--code {
+  // @include type--monospace-font-family;
+  padding-bottom: 0;
+  padding-top: 0.2em;
+}
+
+//*
+// A badge that is used on its own (that is, not beside other text, but may be
+// beside other buttons).
+//
+// @demo_type select
+
+.badge--standalone {
+  @include font-size(badge--standalone);
+}
+
+
+
+//*
+// This container should always be wrapped around a set of badges. It removes
+// any excess right and bottom margin (which every contained badge has to
+// allow for spacing between rows and columns of badges), while still allowing
+// the badges to break onto a new line if there is not enough space to contain
+// them all on a single line.
+//
+// If only a single badge exists, this container can be omitted.
+
+.badge__container {
+  display: inline-flex;
+  flex-wrap: wrap;
+  overflow: hidden;
+  margin-right: negative($badge--spacing) !important;
+  margin-bottom: negative($badge--spacing) !important;
+
+  > .badge {
+    margin-right: $badge--spacing;
+    margin-bottom: $badge--spacing;
+  }
+}

data/source/components/button/button.scss

@@ -0,0 +1,213 @@
+//                     ___                             ___          ___
+//       _____        /__/\         ___       ___     /  /\        /__/\
+//      /  /::\       \  \:\       /  /\     /  /\   /  /::\       \  \:\
+//     /  /:/\:\       \  \:\     /  /:/    /  /:/  /  /:/\:\       \  \:\
+//    /  /:/~/::\  ___  \  \:\   /  /:/    /  /:/  /  /:/  \:\  _____\__\:\
+//   /__/:/ /:/\:|/__/\  \__\:\ /  /::\   /  /::\ /__/:/ \__\:\/__/::::::::\
+//   \  \:\/:/~/:/\  \:\ /  /://__/:/\:\ /__/:/\:\\  \:\ /  /:/\  \:\~~\~~\/
+//    \  \::/ /:/  \  \:\  /:/ \__\/  \:\\__\/  \:\\  \:\  /:/  \  \:\  ~~~
+//     \  \:\/:/    \  \:\/:/       \  \:\    \  \:\\  \:\/:/    \  \:\
+//      \  \::/      \  \::/         \__\/     \__\/ \  \::/      \  \:\
+//       \__\/        \__\/                           \__\/        \__\/
+//
+//*
+// @pattern Buttons
+// @tagline Capture all the clicks.
+//
+// Buttons are what the user should press to initiate most actions. Actions
+// may take place on the page (for example, by activating a popover or x-ray
+// mode) or may send the user to another site to perform an action (the most
+// notable example of this are the buttons that send the user to Github). The
+// element on which to apply these classes will depend on whether the action
+// is internal or external to the page.
+//
+// @since 1.0.0
+
+
+
+$button--spacing: half(default(spacing));
+
+
+
+//*
+// @title Standard Buttons
+//
+// A standard button. This component normalizes the styles of both `button` and
+// `a` elements so that these classes can be placed on either one. If the action
+// is internal (i.e., doesn't require a `GET` request), use a `button`. If the
+// action does require a `GET`, use a URL. Never use an `a` tag with a blank
+// (or `"#"`) `href` attribute.
+//
+// Any variations on this button should ensure that they design and implement
+// designs for the `:focus` state, `:active` state, `:hover` state (optional),
+// and for icons with buttons (using a child selector to the `icon` component),
+// if adjustments to the contained icons are required.
+//
+// A single button can be included on its own, without any container. If
+// multiple buttons have to be placed beside each other, wrap all of the buttons
+// in a `docks-button__container`.
+//
+// @markup
+// <div class="docks-button__container">
+//   <button class="docks-button">button!</button>
+//
+//   <button class="docks-button">
+//     <%= docks_icon :github, size: :medium %>
+//     <span class="docks-button__text">icon + text</span>
+//   </button>
+//
+//   <button class="docks-button">
+//     <span class="docks-button__text">text + icon</span>
+//     <%= docks_icon :github, size: :medium %>
+//   </button>
+//
+//   <div class="docks-button__segmented-container">
+//     <button class="docks-button">Segment 1</button>
+//     <button class="docks-button">Segment 2</button>
+//   </div>
+// </div>
+
+.docks-button {
+  // box model
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0 default(control-padding);
+
+  // backdrop
+  @include default(border-radius);
+  background-color: ui-color(gray, light);
+  border: none;
+  cursor: pointer;
+  opacity: 1;
+  transition: opacity 0.3s ease;
+
+  // type
+  // @include type--default-font-family;
+  @include font-size(control);
+  line-height: default(control-size);
+  color: ui-color(gray, darker);
+  vertical-align: middle;
+  text-decoration: none;
+  white-space: nowrap;
+
+  &:focus,
+  &:active {
+    background-color: ui-color(gray);
+    outline: none;
+  }
+
+  > *:first-child { margin-right: $button--spacing; }
+}
+
+//*
+// A slighter dark variation.
+
+.docks-button--dark {
+  background-color: ui-color(gray, dark);
+  color: ui-color(gray, darkest);
+
+  &:focus,
+  &:active {
+    background-color: ui-color(gray, dark);
+    color: ui-color(gray, darkest);
+  }
+}
+
+//*
+// A button that can no longer be pressed. Make sure to always also include the
+// `disabled` attribute on the actual `button` — this improves usability by
+// preventing the button from being tabbed to, and prevents any event handlers
+// on the `button` from running.
+//
+// @javascript_action this.classList.add("docks-button--is-disabled"); this.disabled = true
+
+.docks-button--is-disabled {
+  opacity: 0.3;
+}
+
+
+
+//*
+// A container for a collection of buttons that normalizes the margin on the
+// outside. This is necessary because each button inside the container has
+// right and bottom margin so that there is vertical and horizontal space
+// between each of any number of buttons.
+
+.docks-button__container {
+  display: inline-flex;
+  flex-wrap: wrap;
+  margin-right: negative($button--spacing) !important;
+  margin-bottom: negative($button--spacing) !important;
+
+  // Prevents margin from collapsing while still allowing overflow/
+
+  &:after { content: ""; display: table; }
+
+  // Allow for anything inside the container — this is useful for, for example,
+  // contained buttons that activate popovers and thus have popover containers
+  // around them.
+
+  > * {
+    flex: 0 0 auto;
+    margin-right: $button--spacing;
+    margin-bottom: $button--spacing;
+  }
+}
+
+//*
+// Use this container variation when you want all of the buttons inside the
+// container to consume an equal part of the total width available to the
+// container. Note that potentially-unexpected behavior may occur when the
+// buttons in this button group have a total intrinsic minimum width greater
+// than that of the container — buttons with smaller intrinsic widths in the
+// group will shrink as much as possible, and then buttons will start, one-by-one
+// as required, breaking onto additional lines (and filling them completely,
+// resulting in some buttons likely being larger than others).
+//
+// For the best results, try to have only two buttons side-by-side in a
+// container using this variant.
+
+.docks-button__container--fill-width {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-start;
+
+  // For both buttons and non-button-ey things in button groups, like popover
+  // containers.
+
+  .docks-button,
+  > *:not(.docks-button) {
+    display: flex;
+    flex: 1 0 0%;
+    min-width: -webkit-min-content;
+    min-width: -moz-min-content;
+    min-width: min-content;
+  }
+}
+
+
+
+//*
+// The text for a button. This container is not necessary unless there is also
+// an icon in the button.
+
+.docks-button__text {}
+
+
+
+//*
+// A wrapper around buttons that causes them to look like one button segmented
+// into pieces.
+
+.docks-button__segmented-container {
+  display: inline-flex;
+
+  > .docks-button {
+    border-radius: 0;
+
+    &:not(:first-child) { border-left: none; }
+    &:first-child { border-radius: default(border-radius) 0 0 default(border-radius); }
+    &:last-child { border-radius: 0 default(border-radius) default(border-radius) 0; }
+  }
+}