docks_theme_api 1.0.2

data/source/components/resizable/resizable.scss

@@ -0,0 +1,245 @@
+//        ___          ___          ___                     ___          ___
+//       /  /\        /  /\        /  /\       ___         /  /\        /  /\
+//      /  /::\      /  /:/_      /  /:/_     /  /\       /  /::|      /  /:/_
+//     /  /:/\:\    /  /:/ /\    /  /:/ /\   /  /:/      /  /:/:|     /  /:/ /\
+//    /  /:/~/:/   /  /:/ /:/_  /  /:/ /::\ /__/::\     /  /:/|:|__  /  /:/ /:/_
+//   /__/:/ /:/___/__/:/ /:/ /\/__/:/ /:/\:\\__\/\:\__ /__/:/ |:| /\/__/:/ /:/ /\
+//   \  \:\/:::::/\  \:\/:/ /:/\  \:\/:/~/:/   \  \:\/\\__\/  |:|/:/\  \:\/:/ /:/
+//    \  \::/~~~~  \  \::/ /:/  \  \::/ /:/     \__\::/    |  |:/:/  \  \::/ /:/
+//     \  \:\       \  \:\/:/    \__\/ /:/      /__/:/     |  |::/    \  \:\/:/
+//      \  \:\       \  \::/       /__/:/       \__\/      |  |:/      \  \::/
+//       \__\/        \__\/        \__\/                   |__|/        \__\/
+
+//*
+// @pattern Resizable
+//
+// A container that can be resized by dragging on a handle
+// (`.resizable__handle`) with a contained iframe that shows the actual demo
+// content. This allows the user to see how the design would actually behave
+// at different viewport widths, and allows for fixed and absolute positioned
+// elements to be displayed in a reasonable way.
+//
+// The JavaScript portion of this component manages the communication of
+// height changes from the `iframe` to make sure that the demo is entirely
+// visible and shows the current width and allows the user to see a small
+// number of preset widths.
+//
+// @since 1.0.0
+
+
+
+$resizable--min-width: 18rem;
+$resizable--border: 1px solid ui-color(gray, darker);
+$resizable--default-transition-timing: 0.3s ease;
+
+$resizable__handle--width: 1.25rem;
+$resizable__handle--groove-height: double(default(spacing));
+$resizable__handle--groove-percentage-width: 0.35;
+
+$resizable__size-button__icon--size: 1.8rem;
+
+
+
+//*
+// The core component of a `Resizable`. This part of the component contains
+// the handle and `iframe`, and is the part of the component that is actually
+// resized when dragging the handle/ using the size buttons. The `min-width`
+// specified here should account for both the `min-width` of the content *and*
+// the width of the handle (which will be positioned absolutely over the right
+// side).
+//
+// @helper docks_resizable
+
+.resizable {
+  // position
+  position: relative;
+
+  // box model
+  margin: 0 auto;
+  width: 100%;
+  min-width: ($resizable--min-width + $resizable__handle--width);
+
+  // backdrop
+  @include default(border-radius);
+
+  // type
+  line-height: 0;
+
+  > .card {
+    position: relative;
+    padding-right: $resizable__handle--width;
+  }
+
+  .iframe {
+    width: 100%;
+    min-height: 10rem;
+    transition: height $resizable--default-transition-timing;
+    overflow: hidden;
+  }
+}
+
+//*
+// Provides a transition that smoothly moves the resizable container from one
+// width to the next. This is not done by default as dragging the handle would
+// appear broken.
+
+.resizable--is-transitioning-width {
+  transition: width $resizable--default-transition-timing;
+}
+
+
+
+//*
+// The handle by which to resize the container. Default style gives two small
+// grooves in the middle of the handle that affords its draggability.
+
+.resizable__handle {
+  // position
+  position: absolute;
+  top: 0; right: 0;
+
+  // box model
+  width: $resizable__handle--width;
+  height: 100%;
+
+  // backdrop
+  cursor: col-resize;
+  background: ui-color(gray, dark);
+  border-radius: 0 default(border-radius) default(border-radius) 0;
+
+  &:hover,
+  &:focus {
+    outline: none;
+  }
+
+  &:after {
+    $resizable__handle--groove-width: $resizable__handle--groove-percentage-width * $resizable__handle--width;
+
+    content: "";
+
+    // position
+    position: absolute;
+    top: 50%; left: 50%;
+
+    // box model
+    display: block;
+    height: $resizable__handle--groove-height;
+    width: $resizable__handle--groove-width;
+    margin-top: negative(half($resizable__handle--groove-height));
+    margin-left: negative(half($resizable__handle--groove-width));
+
+    // backdrop
+    border-right: $resizable--border;
+    border-left: $resizable--border;
+  }
+}
+
+
+
+//*
+// A container for all of the information and acions available for the
+// component.
+
+.resizable__actions {
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-end;
+  margin-bottom: half(default(spacing));
+}
+
+
+
+
+//*
+// A small notice that shows the current width of the (content of the) resizable
+// module. This indicator slides in when the size changes (through the use of
+// the `resizable__width-indicator--is-visible` variant).
+//
+// The indicator shows the width in both `px` and `em` values which are
+// contained in the submodules `resizable__width-indicator__px` and
+// `resizable__width-indicator__em`, respectively.
+//
+// @state --is-visible - The indicator is currently being shown.
+
+.resizable__width-indicator {
+  // type
+  color: color(gray-dark);
+  font: 300 1rem/1 Consolas, monospace;;
+
+  // backdrop
+  opacity: 0.4;
+  transition: opacity $resizable--default-transition-timing;
+}
+
+.resizable__width-indicator--is-visible { opacity: 1; }
+
+
+
+//*
+// A vertically-oriented set of buttons that resize the resizable module to
+// predetermined widths. These widths have been set in the Javascript part of
+// this module.
+
+.resizable__size-buttons {
+  display: flex;
+}
+
+
+
+//*
+// A single button that resizes the module.
+//
+// @state --is-active (select)
+// Indicates that this button has been pressed and that the user has not
+// subsequently resized the module in some other way.
+//
+// @state --is-hidden (none)
+// Indicates that the button should be hidden because not enough screen space
+// exists for its resize.
+//
+// @variant --small  (none) - Resizes to a roughly smartphone-sized width.
+// @variant --medium (none) - Resizes to a roughly tablet-sized width.
+// @variant --large  (none) - Resizes to a roughly desktop-sized width.
+
+.resizable__size-button {
+  position: relative;
+  margin-left: half(default(spacing));
+  cursor: pointer;
+
+  opacity: 0.5;
+  transition: opacity $resizable--default-transition-timing;
+
+  > .icon {
+    height: $resizable__size-button__icon--size;
+    width: $resizable__size-button__icon--size;
+
+    @include icon--recolor(gray);
+    transition: fill $resizable--default-transition-timing;
+  }
+
+  &:hover,
+  &:focus,
+  &:active,
+  &.resizable__size-button--is-active {
+    outline: none;
+  }
+
+  &:hover,
+  &:focus {
+    opacity: 0.8;
+  }
+
+  &.resizable__size-button--is-active,
+  &:active {
+    opacity: 1;
+
+    > .icon {
+      fill: color(blue);
+      stroke: color(blue);
+    }
+  }
+}
+
+.resizable__size-button--is-hidden {
+  display: none;
+}

data/source/components/resizable/size_buttons.js

@@ -0,0 +1,249 @@
+import Resizable from "./resizable";
+import Builder from "~utilities/builder";
+import Keycodes from "~utilities/keycodes";
+
+var SizeButtons,
+    SizeRelationships, click_size_button, next_unhidden_size_button,
+    previous_unhidden_size_button, key_on_size_button;
+
+const classes = {
+  root: "resizable__size-button",
+  container: "resizable__size-buttons"
+};
+
+const states = {
+  root: {
+    hidden: "resizable__size-button--is-hidden",
+    active: "resizable__size-button--is-active"
+  }
+};
+
+const attrs = {
+  button_size: "data-resizable-size-button-size",
+  size_to: "data-resizable-size-to"
+};
+
+SizeRelationships = {
+  SMALL: 320,
+  MEDIUM: 768,
+  LARGE: 960
+};
+
+// Attaches media queries for each of the size buttons to conditionally hide/
+// show them depending on whether or not the size they want to generate is within
+// the available space.
+//
+// @param {HTMLElement} button - The size button. It should have an
+//                              `attrs.button_size` attribute, which determines
+//                              what size they should make the component.
+// @param {Number} size_adjustment - The difference in width between the viewport
+//                                   and the space available to the component.
+//
+// @private
+
+// attach_media_listener_to_size_button = (button, size_adjustment = 0) => {
+//   var size = button.getAttribute(attrs.button_size),
+//       respond_width = SizeRelationships[size.toUpperCase()],
+//       listener, media_query;
+
+//   if(!respond_width) { return; }
+//   button.setAttribute(attrs.size_to, respond_width);
+
+//   listener = (mq) => {
+//     button.classList[mq.matches ? "remove" : "add"](states.size_button.hidden);
+//   };
+
+//   media_query = window.matchMedia(`(min-width: ${respond_width + size_adjustment}px)`);
+//   media_query.addListener(listener);
+//   listener(media_query);
+// };
+
+//*
+// Captures a click even on a size button and sends the appropriate `set_width`
+// method call to the associated `Resizable` component.
+//
+// @param {Object} event - The click event.
+// @private
+
+click_size_button = (event) => {
+  var button = $(event.target).closest(`.${classes.root}`);
+  SizeButtons.for(button).active_button = button;
+};
+
+//*
+// Finds the next visible size button after the passed `button`. This is used
+// for cycling through these buttons with the keyboard. This will cycle through
+// all buttons in the list, wrapping around to the first buttons if no following
+// buttons are visible. As a result, this method might return the same `button`
+// that was passed (if it is the only visible size button).
+//
+// @param {HTMLElement} button - The current button (that the user is moving off
+//                              of with the keyboard).
+//
+// @private
+// @returns HTMLElement - The next visible size button within the `button`'s set.
+
+next_unhidden_size_button = (button) => {
+  var sibling = button.nextElementSibling;
+
+  while(sibling) {
+    if(!sibling.classList.contains(states.size_button.hidden)) { return sibling; }
+    sibling = sibling.nextElementSibling;
+  }
+
+  for(sibling of Array.from(button.parentNode.children)) {
+    if(sibling === button) { break; }
+    if(!sibling.classList.contains(states.size_button.hidden)) { return sibling; }
+  }
+
+  return null;
+};
+
+//*
+// Finds the previous visible size button after the passed `button`. This is used
+// for cycling through these buttons with the keyboard. This will cycle through
+// all buttons in the list, wrapping around to the last buttons if no previous
+// buttons are visible. As a result, this method might return the same `button`
+// that was passed (if it is the only visible size button).
+//
+// @param {HTMLElement} button - The current button (that the user is moving off
+//                              of with the keyboard).
+//
+// @private
+// @returns HTMLElement - The previous visible size button within the `button`'s
+//                       set.
+
+previous_unhidden_size_button = (button) => {
+  var sibling = button.previousElementSibling;
+
+  while(sibling) {
+    if(!sibling.classList.contains(states.size_button.hidden)) { return sibling; }
+    sibling = sibling.previousElementSibling;
+  }
+
+  for(sibling of Array.from(button.parentNode.children).reverse()) {
+    if(sibling === button) { break; }
+    if(!sibling.classList.contains(states.size_button.hidden)) { return sibling; }
+  }
+
+  return null;
+};
+
+//*
+// Handles key presses on a size button. If the key is enter or space, the
+// size button will be activated. If the key is an arrow key, this function will
+// move focus to the correct sibling size button.
+//
+// @param {Object} event - The `keypress` event.
+// @private
+
+key_on_size_button = (event) => {
+  var button, new_button;
+
+  if(Keycodes.ACTIVATE.includes(event.which)) {
+    event.preventDefault();
+    click_size_button(event);
+  }
+
+  if(Keycodes.ARROWS.includes(event.which)) {
+    event.preventDefault();
+    button = $(event.target).closest(`.${classes.size_button}`)[0];
+    new_button = Keycodes.NEXT.includes(event.which) ?
+      next_unhidden_size_button(button) :
+      previous_unhidden_size_button(button);
+
+    if(new_button) {
+      SizeButtons.for(button).focused_button = new_button;
+    }
+  }
+};
+
+//*
+// @factory
+
+SizeButtons = (buttons) => {
+  var api,
+      associations, active_button, a11y, activate_button, focus_button,
+      activate_active_button, deactivate_active_button, size, a_button;
+
+  buttons = Array.from(buttons.children);
+  associations = {};
+  for(a_button of buttons) {
+    size = SizeRelationships[a_button.getAttribute(attrs.button_size)];
+    associations[size] = a_button;
+  }
+
+  a11y = {
+    focus(button) {
+      button.setAttribute("tabindex", "0");
+      button.focus();
+    },
+
+    blur(button) {
+      button.setAttribute("tabindex", "-1");
+    },
+
+    select(button) {
+      this.focus(button);
+      button.setAttribute("aria-selected", "true");
+    },
+
+    deselect(button) {
+      this.blur(button);
+      button.setAttribute("aria-selected", "false");
+    }
+  };
+
+  deactivate_active_button = () => {
+    if(!active_button) { return; }
+
+    a11y.deslect(active_button);
+    active_button.classList.remove(states.root.active);
+  };
+
+  activate_button = (button) => {
+    if(!buttons.includes(button) || active_button === button) { return active_button; }
+
+    deactivate_active_button();
+    active_button = button;
+    Resizable.for(button).set_width(parseInt(button.getAttribute(attrs.size_button), 10), { animated: true });
+    activate_active_button();
+    return active_button;
+  };
+
+  focus_button = (button) => {
+    a11y.focus(button);
+    return button;
+  };
+
+  activate_active_button = () => {
+    if(!active_button) { return; }
+
+    a11y.select(active_button);
+    active_button.classList.add(states.root.active);
+  };
+
+  api = {
+    set active_button(button) { return activate_button(button); },
+    get active_button() { return active_button; },
+    set focused_button(button) { return focus_button(button); },
+
+    try_size(new_size) {
+      deactivate_active_button();
+      active_button = associations[new_size];
+      activate_active_button();
+    }
+  };
+
+  return api;
+};
+
+SizeButtons.init = () => {
+  Builder.build_and_cache(SizeButtons, { name: classes.container });
+
+  $(document)
+    .on("click", `.${classes.root}`, click_size_button)
+    .on("keydown", `.${classes.root}`, key_on_size_button);
+};
+
+export default SizeButtons;

data/source/components/scroll_container/package.json

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

data/source/components/scroll_container/scroll-container.scss

@@ -0,0 +1,4 @@
+.scroll-container {
+  // Contain any interior margins
+  overflow: hidden;
+}

data/source/components/scroll_container/scroll_container.js

@@ -0,0 +1,24 @@
+import Builder from "~utilities/builder";
+
+const classes = {
+  root: "scroll-container"
+};
+
+var ScrollContainer;
+
+ScrollContainer = (node) => {
+  var force_height = (height) => { node.style.minHeight = `${height}px`; };
+
+  return {
+    maintain_current_height() { force_height(node.offsetHeight); },
+    restore_height() { node.style.minHeight = null; },
+
+    scroll_to(contained_node) {
+      node.parentNode.scrollTop = contained_node.getBoundingClientRect().top - node.getBoundingClientRect().top;
+    }
+  };
+};
+
+ScrollContainer.init = Builder.initialize_once(ScrollContainer, { name: classes.root, cache: true });
+
+export default ScrollContainer;

data/source/components/section/section.scss

@@ -0,0 +1,99 @@
+//        ___          ___          ___                          ___          ___
+//       /  /\        /  /\        /  /\        ___  ___        /  /\        /__/\
+//      /  /:/_      /  /:/_      /  /:/       /  /\/  /\      /  /::\       \  \:\
+//     /  /:/ /\    /  /:/ /\    /  /:/       /  /:/  /:/     /  /:/\:\       \  \:\
+//    /  /:/ /::\  /  /:/ /:/_  /  /:/  ___  /  /:/__/::\    /  /:/  \:\  _____\__\:\
+//   /__/:/ /:/\:\/__/:/ /:/ /\/__/:/  /  /\/  /::\__\/\:\__/__/:/ \__\:\/__/::::::::\
+//   \  \:\/:/~/:/\  \:\/:/ /:/\  \:\ /  /:/__/:/\:\ \  \:\/\  \:\ /  /:/\  \:\~~\~~\/
+//    \  \::/ /:/  \  \::/ /:/  \  \:\  /:/\__\/  \:\ \__\::/\  \:\  /:/  \  \:\  ~~~
+//     \__\/ /:/    \  \:\/:/    \  \:\/:/      \  \:\/__/:/  \  \:\/:/    \  \:\
+//       /__/:/      \  \::/      \  \::/        \__\/\__\/    \  \::/      \  \:\
+//       \__\/        \__\/        \__\/                        \__\/        \__\/
+
+//*
+// @pattern Section
+//
+// Sections are simply ways of grouping related content and provising
+// separation between that contained content and "sibling" content.
+//
+// Smaller variations are available for more condensed content, like content
+// inside of a popover.
+//
+// @since 1.0.0
+
+
+
+//*
+// A container around some content that provides the vertical separation from
+// other `section`s. This will also remove any top/ bottom padding from the
+// first/ last child, respectively, to avoid more vertical padding than
+// necessary.
+
+.section {
+  margin: double(default(spacing)) 0;
+  padding: default(spacing) 0;
+
+  > *:first-child {
+    &,
+    & > *:first-child {
+      margin-top: 0;
+    }
+  }
+
+  > *:last-child {
+    &,
+    & > *:last-child {
+      margin-bottom: 0;
+    }
+  }
+}
+
+//*
+// A smaller section with no border separating content. Use this variant for
+// places where the base amount of vertical padding is excessive (for example,
+// in popovers or other limited-width containers).
+
+.section--small {
+  border: none;
+  padding: 0;
+  margin: default(spacing) 0;
+}
+
+//*
+// A section with a light gray background that separates it visually from the
+// other sections. Use this to differentiate between significantly different
+// groups of content. It is best to only use this with `section--small` —
+// regular `section`s already have sufficient separation in most cases.
+
+.section--subdued {
+  background: color(gray-light);
+  overflow: hidden;
+
+  &.section--small {
+    padding: default(spacing) 0;
+    margin: 0;
+  }
+}
+
+
+
+//*
+// Use this container for when you want a group of sections to have additional
+// vertical separation from the content around it. The amount of additional
+// space depends on whether the container contains regular or `--small`
+// `section`s.
+//
+// This container is not necessary — for example, sections can sit on their own
+// inside a popover.
+
+.section__container {
+  > .section {
+    &:first-child { margin-top: double(default(spacing)); }
+    &:last-child { margin-bottom: double(default(spacing)); }
+  }
+
+  > .section--small {
+    &:first-child { margin-top: default(spacing); }
+    &:last-child { margin-bottom: default(spacing); }
+  }
+}

data/source/components/select/package.json

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

data/source/components/select/select.erb

@@ -0,0 +1,21 @@
+<%
+  component.configure do |config|
+    config.defaults options: [],
+                    name: "select",
+                    id: "select",
+                    code?: false
+
+    config.classes  base: "select",
+                    input: "select__input"
+
+    config.conditional_classes if: :code?, base: "select--code"
+  end
+%>
+
+<div class="<%= component.classes_for(:base) %>">
+  <select class="<%= component.classes_for(:input) %>" id="<%= component.id %>" name="<%= component.name %>">
+    <% component.options.each do |option| %>
+      <option><%= option %></option>
+    <% end %>
+  </select>
+</div>

data/source/components/select/select.js

@@ -0,0 +1,35 @@
+const classes = {
+  root: "select",
+  input: "select__input"
+};
+
+const states = {
+  root: { focused: `${classes.root}--is-focused` }
+};
+
+var Select, focus_or_blur_select;
+
+//*
+// Translates the `focus`/ `blur` events on the actual `select` node into the
+// appropriate addition/ removal of the focused state on the base node of the
+// component. This has to be done because most of the visual styling for the
+// component is placed on the container, so any adjustments to those styles on
+// focus require that container to be aware of the state of its contained
+// `select`.
+//
+// @param {Object} event - The `focus`/ `blur` event on the `select`.
+// @private
+
+focus_or_blur_select = (event) => {
+  var method = event.type === "focusin" ? "add" : "remove";
+  $(event.target).closest(".#{CLASSES.BASE}")[0].classList[method](states.root.focused);
+};
+
+Select = {
+  init() {
+    $(document).on("focus blur", `.${classes.input}`, focus_or_blur_select);
+  }
+};
+
+export { classes };
+export default Select;