docks_theme_api 1.0.2

data/source/components/table/table.scss

@@ -0,0 +1,236 @@
+//                ___                                  ___
+//        ___    /  /\        _____                   /  /\
+//       /  /\  /  /::\      /  /::\                 /  /:/_
+//      /  /:/ /  /:/\:\    /  /:/\:\  ___     ___  /  /:/ /\
+//     /  /:/ /  /:/~/::\  /  /:/~/::\/__/\   /  /\/  /:/ /:/_
+//    /  /::\/__/:/ /:/\:\/__/:/ /:/\:\  \:\ /  /:/__/:/ /:/ /\
+//   /__/:/\:\  \:\/:/__\/\  \:\/:/~/:/\  \:\  /:/\  \:\/:/ /:/
+//   \__\/  \:\  \::/      \  \::/ /:/  \  \:\/:/  \  \::/ /:/
+//        \  \:\  \:\       \  \:\/:/    \  \::/    \  \:\/:/
+//         \__\/\  \:\       \  \::/      \__\/      \  \::/
+//               \__\/        \__\/                   \__\/
+
+//*
+// @pattern Table
+//
+// Tables are used to present tabular data only — never for layout! These tables
+// are smarter than the average table, however. They will determine their
+// intrinsic size (up to a stylesheet-specified maximum) and, when the space
+// available to them is less than that size, they will begin to scroll.
+//
+// As you scroll, the first column will stay fixed, so you always have context,
+// and the any given column will always be small enough to be fully visible. Not
+// only that, but the table provides both keyboard input and interface elements
+// that allow you to quickly shift to overscrolled columns.
+//
+// @since 1.0.0
+
+
+
+$table--border: 1px solid color(gray-light);
+$table--border-radius: double(default(border-radius));
+$table--box-shadow-size: 3px 0 4px -1px;
+
+
+
+//*
+// A smarter `table` element. The `min-width` placed here will not actually
+// be the minimum width of the rendered table; the provided minimum width will
+// instead be used as the maximum width allowed in determining the preferred/
+// intrinsic size of the table cells. That is, a table whose natural size is
+// less than this amount will not overflow until the space it has is less than
+// its intrinsic size, where a table with large cells will overflow at the
+// provided `min-width` breakpoint.
+//
+// Visually, all tables will be 100% width. As noted above, tables will overflow
+// once the lesser of the `min-width` below or the intrisic size of the table
+// is reached. This overflowing is managed by the JavaScript component.
+//
+// @helper docks_table
+
+.table {
+  width: 100%;
+  min-width: rem(500);
+
+  border-collapse: separate;
+  border-spacing: 0;
+}
+
+
+
+//*
+// The outermost wrapper around a table. This wrapper is used to signal to the
+// entire component when the table is in overflow (via the
+// `table__container--is-overflowing` state). Doing so on the outmost container
+// allows adjustments to both the table itself and the `table__actions`.
+//
+// In addition, `table__containers` will automatically create the required
+// space between themselves and other content.
+
+.table__container {
+  margin: default(spacing) auto;
+}
+
+//*
+// Signals to the `table` that it should force the first cell in each row
+// to float about the rest of the rows (the required left padding on the
+// second cell in each row to account for the absolutely-positioned first cell
+// is done automatically by the JavaScript side of things, as is the
+// equalization of all of the first cells' widths). Additionally, this
+// state causes the `table__actions` to be made visible.
+//
+// @set_by Table#check_for_overflow
+// @demo_type none
+
+.table__container--is-overflowing {
+  .table__cell:first-child {
+    position: absolute;
+    @include z-index(cell-persistant, table);
+    left: 0;
+
+    height: 100%;
+
+    // Start box shadow as transparent so it can be animated into view when
+    // the table is actually being scrolled.
+    box-shadow: $table--box-shadow-size rgba(color(black), 0);
+    transition: box-shadow 0.2s ease;
+  }
+
+  .table__actions {
+    transform: translateY(0);
+    max-height: 3rem;
+    padding-bottom: half(default(spacing));
+  }
+}
+
+
+
+//*
+// A wrapper around the `table` that allows it to scroll when the minimum
+// width of its columns (their intrinsic width or their width when the table
+// is larger than the `min-width` set on `table`) is larger than the space
+// available to this container.
+
+.table__scroller {
+  max-width: 100%;
+  overflow-x: auto;
+  overflow-y: hidden;
+  -webkit-overflow-scrolling: touch;
+}
+
+//*
+// The state that is added by the JavaScript component when the table is
+// overflowed **and** the scroll position of this subcomponent is not fully
+// pinned to the left.
+//
+// @set_by Table#handle_scroll, Table#shift_table
+
+.table__scroller--is-scrolled {
+  .table__cell:first-child {
+    box-shadow: $table--box-shadow-size rgba(color(black), 0.1);
+  }
+}
+
+
+
+//*
+// The wrapper around a `table` that provides a few visual pieces. Most
+// noticeably, this adds the border and border radius on the outside of the
+// table. These pieces must be on this container rather than the
+// `table__container` subcomponent because it should only wrap around the
+// `table`, and not the `table__actions`. These rules can't be on the
+// `table__scroller` subcomponent, either, because it must be `overflow: hidden`
+// (to hide the parts outside the rounded corners), where the scroller must
+// be allowed to scroll.
+//
+// More importantly, however, this container is `position: relative` and, as
+// such, acts as the element against which the persistant cells are
+// positioned. These rules can't be on the `table__scroller` because it scrolls,
+// where the persistant cells should be fixed even as the rest of the table
+// scrolls.
+
+.table__backdrop {
+  // position
+  position: relative;
+  @include z-index(backdrop, table);
+
+  // box model
+  max-width: 100%;
+  clear: both;
+
+  // backdrop
+  overflow: hidden;
+  border: $table--border;
+  border-radius: $table--border-radius;
+}
+
+
+
+//*
+// A container around the actions that can be performed on the `table`. For now,
+// this includes only the segmented button to shift the table right/ left by
+// one column.
+
+.table__actions {
+  transform: translateY(140%);
+  max-height: 0;
+  float: right;
+
+  transition: transform 0.3s $bouncy-transition,
+              max-height 0.3s ease,
+              padding-bottom 0.3s ease;
+}
+
+
+
+//*
+// The header row of the table.
+
+.table__header {
+  font-weight: 400;
+  padding: 0;
+  text-align: left;
+}
+
+
+
+//*
+// The container around the rows that make up the body of the table.
+
+.table__body {
+  // Striped rows!
+  > .table__row:nth-child(odd) > .table__cell {
+    background-color: color(gray-lighter);
+  }
+}
+
+
+
+//*
+// A row of table cells.
+
+.table__row {
+  // Hide the overflow so that box shadows on persistant cells don't bleed
+  // between rows.
+  overflow: hidden;
+}
+
+
+
+//*
+// An individual table cell.
+
+.table__cell {
+  position: relative;
+  @include z-index(cell, table);
+  vertical-align: top;
+  padding: half(default(spacing));
+  background-color: color(white);
+}
+
+//*
+// A table cell with center-aligned text.
+
+.table__cell--centered {
+  text-align: center;
+}

data/source/components/tablist/package.json

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

data/source/components/tablist/tablist.erb

@@ -0,0 +1,13 @@
+<%
+  tablist.configure do |config|
+    config.defaults(manage_url?: false, size: :regular)
+    config.classes(base: "tablist")
+
+    config.conditional_classes(from: :size, large: { base: "tablist--large" })
+    config.conditional_classes(if: :manage_url?, base: "tablist--manages-url")
+  end
+%>
+
+<div class="<%= tablist.classes_for(:base) %>" role="tablist">
+  <%= capture(tablist, &tablist.block) %>
+</div>

data/source/components/tablist/tablist.js

@@ -0,0 +1,246 @@
+import QueryString from "~utilities/query_string";
+import Builder from "~utilities/builder";
+import Cache from "~utilities/dom_cache";
+
+const classes = {
+  root: "tablist",
+  tab: "tablist__tab",
+  panel: "tablist__panel"
+};
+
+const variants = {
+  root: { manages_url: "tablist--manages-url" }
+};
+
+const states = {
+  tab: { active: "tablist__tab--is-active" },
+  panel: { active: "tablist__panel--is-active" }
+};
+
+var Tablist, tab_click, panel_for_tab, tab_for_panel, tablist_for_node, a11y,
+    apply_activation_markup, remove_activation_markup, panel_containing_node;
+
+//*
+// Manages a click on a tab by finding the associated `Tablist` and activating
+// the tab that was clicked on.
+//
+// @param {Object} event - The `click` event.
+// @private
+
+tab_click = (event) => {
+  var tablist;
+
+  event.preventDefault();
+
+  tablist = Tablist.for(event.target);
+  if(!tablist) { return; }
+  tablist.activate_tab($(event.currentTarget).closest(`.${classes.tab}`)[0]);
+};
+
+//*
+// Finds the tab panel associated with the passed tab. The association is based
+// on the ID of the tab panel matching the `href` of the tab.
+//
+// @param {HTMLElement} tab - The tab for which you want the associated panel.
+// @private
+//
+// @returns {HTMLElement | null} The associated tab panel or, if no matching
+// panel was found, `null`.
+
+panel_for_tab = (tab) => {
+  return tab && document.getElementById(tab.getAttribute("href").replace("#", ""));
+};
+
+//*
+// Finds the tab associated with the passed panel. The association is based
+// on the ID of the tab panel matching the `href` of the tab.
+//
+// @param {HTMLElement} tab - The tab for which you want the associated panel.
+// @private
+//
+// @returns {HTMLElement | null} The associated tab or, if no matching panel
+// was found, `null`.
+
+tab_for_panel = (panel) => {
+  return panel && document.querySelector(`.${classes.tab}[href='#${panel.id}']`);
+};
+
+//*
+// Writes all of the required accessibility markup to the tablist and its
+// subcomponents. This includes IDs for the tablist and its tabs/ panels,
+// roles for the same, and the `aria-` associations between tabs and their
+// corresponding panels.
+//
+// @param {HTMLElement} tablist - The root node of the tablist.
+// @private
+
+a11y = (() => {
+  var current_ids, id_for;
+
+  current_ids = {
+    [classes.root]: 1,
+    [classes.tab]: 1,
+    [classes.panel]: 1
+  };
+
+  id_for = (node) => {
+    var type = node.className.split(" ")[0];
+    return `${type}--${current_ids[type]++}`;
+  };
+
+  return (tablist) => {
+    var panel, tab_id, panel_id, tab;
+
+    tablist.id = tablist.id || id_for(tablist);
+    tablist.setAttribute("role", "tablist");
+
+    for(tab of Array.from(tablist.querySelectorAll(`.${classes.tab}`))) {
+      panel = panel_for_tab(tab);
+      if(!panel) { continue; }
+
+      tab_id = tab.id || id_for(tab);
+      panel_id = panel.id || id_for(panel);
+
+      tab.id = tab_id;
+      tab.setAttribute("role", "tab");
+      tab.setAttribute("aria-controls", panel_id);
+      tab.setAttribute("href", `#${panel_id}`);
+
+      panel.id = panel_id;
+      panel.setAttribute("role", "tab-panel");
+      panel.setAttribute("aria-labelledby", tab_id);
+      panel.setAttribute("aria-hidden", !panel.classList.contains(states.panel.active));
+    }
+  };
+})();
+
+apply_activation_markup = (node) => {
+  if(!node) { return; }
+
+  if(node.classList.contains(classes.tab)) {
+    node.classList.add(states.tab.active);
+  } else {
+    node.classList.add(states.panel.active);
+  }
+};
+
+remove_activation_markup = (node) => {
+  if(!node) { return; }
+
+  if(node.classList.contains(classes.tab)) {
+    node.classList.remove(states.tab.active);
+  } else {
+    node.classList.remove(states.panel.active);
+  }
+};
+
+panel_containing_node = (node) => {
+  return $(node).closest(`.${classes.panel}`)[0];
+};
+
+tablist_for_node = (node) => {
+  if(node.classList.contains(classes.panel)) {
+    node = tab_for_panel(node);
+  }
+
+  return $(node).closest(`.${classes.root}`)[0];
+};
+
+//*
+// The constructor around a `Tablist` component. This constructor returns a very
+// small API: only an `activate_tab` method is exposed, which will activate the
+// passed tab in the tablist. This constructor will also ensure that all the
+// aria properties and associations are hooked up correctly.
+
+Tablist = (root) => {
+  var active_tab = root.querySelector(`.${states.tab.active}`),
+      active_panel = panel_for_tab(active_tab),
+      saved_tab, api, self;
+
+  a11y(root);
+
+  self = {
+    root,
+    id: root.id,
+    active_panel: panel_for_tab(active_tab),
+    manages_url: root.classList.contains(variants.root.manages_url)
+  };
+
+  api = {
+    //*
+    // Activates the passed tab, deactivating the currently-active tab, if there
+    // is one (and it is not the passed tab).
+    //
+    // @param {HTMLElement} tab - The tab to activate.
+
+    activate_tab(tab) { this.active_tab = tab; },
+
+    get active_tab() { return active_tab; },
+    set active_tab(tab) {
+      var panel = panel_for_tab(tab);
+
+      apply_activation_markup(tab);
+      apply_activation_markup(panel);
+
+      if(!tab || tab === active_tab) { return; }
+
+      remove_activation_markup(active_tab);
+      remove_activation_markup(active_panel);
+
+      active_tab = tab;
+      active_panel = panel;
+
+      if(this.manages_url && QueryString.get(this.id) !== tab.id) {
+        QueryString.set(this.id, tab.id);
+      }
+    },
+
+    get active_panel() { return active_panel; },
+    set active_panel(panel) {
+      this.active_tab = panel_for_tab(panel);
+    }
+  };
+
+  if(self.manages_url) {
+    saved_tab = QueryString.get(self.id);
+    if(saved_tab) { api.active_tab = document.getElementById(saved_tab); }
+  } else {
+    api.active_tab = active_tab;
+  }
+
+  return api;
+};
+
+Tablist.for = (node) => {
+  var tablist_node = $(node).closest(`.${classes.root}`)[0],
+      containing_panel;
+
+  if(!tablist_node) {
+    containing_panel = node.classList.contains(classes.panel) ? node : panel_containing_node(node);
+    if(!containing_panel) { return false; }
+    tablist_node = tablist_for_node(containing_panel);
+  }
+
+  if(!tablist_node) { return false; }
+  return Cache(tablist_node).get(classes.root);
+};
+
+Tablist.init = () => {
+  Builder.build_and_cache(Tablist, { name: classes.root });
+  $(document).on("click", `.${classes.tab}`, tab_click);
+};
+
+Tablist.activate_panel_containing = (node) => {
+  var panel = $(node).closest(`.${classes.panel}`)[0],
+      tablist = Tablist.for(panel);
+
+  if(tablist) { tablist.active_tab = tab_for_panel(panel); }
+  return !!tablist;
+};
+
+Tablist.is_in_active_panel = (node) => {
+  var panel = panel_containing_node(node);
+  return !!panel && panel.classList.contains(states.panel.active);
+};
+
+export default Tablist;

data/source/components/tablist/tablist.scss

@@ -0,0 +1,191 @@
+//                ___                                             ___
+//        ___    /  /\        _____                   ___        /  /\        ___
+//       /  /\  /  /::\      /  /::\                 /  /\      /  /:/_      /  /\
+//      /  /:/ /  /:/\:\    /  /:/\:\  ___     ___  /  /:/     /  /:/ /\    /  /:/
+//     /  /:/ /  /:/~/::\  /  /:/~/::\/__/\   /  /\/__/::\    /  /:/ /::\  /  /:/
+//    /  /::\/__/:/ /:/\:\/__/:/ /:/\:\  \:\ /  /:/\__\/\:\__/__/:/ /:/\:\/  /::\
+//   /__/:/\:\  \:\/:/__\/\  \:\/:/~/:/\  \:\  /:/    \  \:\/\  \:\/:/~/:/__/:/\:\
+//   \__\/  \:\  \::/      \  \::/ /:/  \  \:\/:/      \__\::/\  \::/ /:/\__\/  \:\
+//        \  \:\  \:\       \  \:\/:/    \  \::/       /__/:/  \__\/ /:/      \  \:\
+//         \__\/\  \:\       \  \::/      \__\/        \__\/     /__/:/        \__\/
+//               \__\/        \__\/                              \__\/
+
+//*
+// @pattern Tablist
+//
+// Tablists are used to create groups of related content that is conditionally
+// shown or hidden based on the selected tab. The JavaScript part of this
+// components ensures that the required accessibility-related markup is added
+// to the tabs, and a number of different styles are available depending on
+// the context in which the tabs are being used.
+//
+// @since 1.0.0
+
+//*
+// The container for a set of tabs. While panels and tabs both use `tablist`
+// as their base component, only `tablist__tab`s are child nodes of this
+// component; `tablist__panel`s (and their container) are separate from the
+// document to allow tabs to move around the page independently of the content
+// they actually activate.
+//
+// The `tablist--manages-url` variant is unique in that it has no visual
+// differences, but will preserve the selected tab via a query string parameter
+// and restore the selected tab on subsequent page loads. To add this
+// functionality, simply pass `true` for the `:manage_url` option of the
+// `docks_tablist` view helper.
+//
+// @helper docks_tablist
+
+.tablist {
+  // box model
+  margin: 0;
+  padding: 0;
+  display: flex;
+  justify-content: center;
+  padding: half(default(spacing));
+  margin-right: negative(half(default(spacing)));
+
+  // backdrop
+  list-style: none;
+}
+
+//*
+// A larger set of tabs (both in terms of the font size of the tabs and the
+// padding within each tab).
+//
+// @set_by :size (:large)
+
+.tablist--large {
+  margin: double(default(spacing)) 0;
+
+  > .tablist__tab {
+    @include font-size(tablist--large);
+    line-height: 1;
+    padding: default(spacing) multiply(default(spacing), 2.5) multiply(default(spacing), 1.2);
+    border: none !important;
+    opacity: 1 !important;
+  }
+
+  > .tablist__tab--is-active {
+    background-color: ui-color(gray, light);
+  }
+}
+
+//*
+// A variation of the tablist that forces the JavaScript to preserve the
+// selected tab and reload that tab on subsequent page loads.
+//
+// @demo_type none
+// @set_by :manage_url
+
+.tablist--manages-url {}
+
+
+
+
+//*
+// A single tab in the tablist. Tabs will be a relatively light color by
+// default with progressively darker shades used on `:focus`/`:hover` and when
+// `:active`.
+//
+// Tabs should still work even when there is no JavaScript or CSS. To make this
+// work, ensure that each `tablist__tab` is an `a` tag with an `href` that
+// points to the `id` of the relevant `tablist__panel`. Likewise, the `id`s of
+// the tab and panel should match up vai the `aria-controls` and
+// `aria-labelledby` properties. The JavaScript component, if run, will
+// guarantee all of these associations.
+//
+// @helper docks_tablist_tab
+
+.tablist__tab {
+  // box model
+  display: inline-block;
+  padding: 0 default(control-padding);
+
+  // backdrop
+  opacity: 0.3;
+  overflow: hidden;
+  border: 1px solid transparent;
+  border-radius: default(border-radius);
+  transition: opacity 0.3s ease, border-color 0.3s ease;
+
+  // type
+  @include font-size(control);
+  line-height: default(control-size);
+  color: ui-color(gray, darker);
+  text-align: center;
+  text-decoration: none;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+
+  &:focus,
+  &:hover {
+    outline: none;
+    opacity: 0.5;
+  }
+
+  > .icon {
+    height: double(default(spacing));
+    width: double(default(spacing));
+    @include icon--recolor(gray, dark);
+    stroke-width: 3px;
+  }
+}
+
+//*
+// The variation added to the tab whose corresponding tab is currently
+// visible. This class can either be applied manually by setting the `:active?`
+// argument to the helper method to `true` or by clicking on the correct tab
+// (which does all the required attribute manipulations through the JavaScript
+// component).
+//
+// @demo_type none
+// @set_by :active?
+
+.tablist__tab--is-active {
+  &, &:hover, &:focus {
+    border-color: ui-color(gray, darker);
+    opacity: 1;
+  }
+}
+
+//*
+// The text within a tab. This container is required in order for the text and
+// (optional) icon to be above one another.
+
+.tablist__tab__text {
+  display: block;
+}
+
+
+
+//*
+// A panel that contains the content that should be shown when the associated
+// tab is active.
+//
+// @helper docks_tablist_panel
+
+.tablist__panel {
+  display: none;
+}
+
+//*
+// A state indicating that the associated tab is active and the contents of
+// this panel should be made visible. There is no animation when switching
+// between tabs — they simply pop in and out of view.
+//
+// @demo_type none
+// @set_by :active?
+
+.tablist__panel--is-active {
+  display: block;
+}
+
+
+
+//*
+// A container around all of the panels for a tablist. This container
+// technically does nothing, but is a nice way to isolate a set of tab panels
+// from the surrounding content.
+
+.tablist__panel-container {}

data/source/components/tablist/tablist_panel.erb

@@ -0,0 +1,14 @@
+<%
+  panel.configure do |config|
+    config.defaults active?: false,
+                    id: "panel",
+                    tab_id: "tab"
+
+    config.classes(base: "tablist__panel")
+    config.conditional_classes(if: :active?, base: "tablist__panel--is-active")
+  end
+%>
+
+<div class="<%= panel.classes_for(:base) %>" role="tab-panel" id="<%= panel.id %>" aria-hidden="<%= !panel.active? %>" aria-labelledby="<%= panel.tab_id %>">
+  <%= capture(panel, &panel.block) %>
+</div>