docks_theme_api 1.0.2

data/assets/styles/sass/pattern-library-helpers.sass

@@ -0,0 +1,90 @@
+//*
+// @pattern Pattern Library Helpers
+// @author Chris Sauve (github: lemonmade)
+//
+// This file provides a set of helpers that allow you to provide custom style
+// overrides for components in demos. Please use these helpers in place of
+// custom selectors whenever possible — if the internal mechanisms the generator
+// uses to create these demos is ever changed, these helpers will be updated to
+// reflect the new selectors that are needed.
+
+//*
+// Forces the height of the passed `$component` demo to be at least `$height`.
+// Demos of some components may not respond properly to automatically
+// calculating their height. For example, absolutely-positioned dropdowns do
+// not cause the height of their container to increase, but we may want some
+// extra vertical space for them to appear into. This mixin allows you to
+// force a particular demo to have at least the passed height.
+//
+// @param {String} $component - The exact name of the component you wish to
+// forcibly size (in most cases, this is the component's class name, without
+// the leading `"."`).
+//
+// @param {Number} $height - The height you wish to force the component demo
+// to be. This number should have some units, the choice of which is left to
+// you.
+//
+// @example
+// +docks-demo-height(dropdown, 10em)
+
+=docks-demo-height($component, $height)
+  #demo__section--#{$component} > .demo__content
+    min-height: #{$height} !important
+
+//*
+// Forces the background of the demo for `$component` to be `$color`. You may
+// wish to use this in cases where an element typically appears on a background
+// color that is not the default for the way they are presented in demos (the
+// default theme displays these on a pure white background).
+//
+// @param {String} $component - The exact name of the component you wish to
+// forcibly set the background color for (in most cases, this is the component's
+// class name, without the leading `"."`).
+//
+// @param {Color} $color - The background color you want.
+//
+// @example
+// +docks-demo-background(button--light, rgb(50, 50, 50))
+
+=docks-demo-background($component, $color)
+  #demo__section--#{$component}
+    background-color: #{$color} !important
+
+//*
+// Forces the demo container for `$component` to have no horizontal padding.
+// The default theme provides this padding since, in general, it is more
+// aesthetically pleasing to do so. This may not, however, work for all your
+// components, in which case you can use this mixin.
+//
+// @param {String} $component - The exact name of the component you wish to
+// remove padding for (in most cases, this is the component's class name,
+// without the leading `"."`).
+//
+// @example
+// +docks-demo-no-padding(grid)
+
+=docks-demo-no-padding($component)
+  #demo__section--#{$component}
+    padding-left: 0
+    padding-right: 0
+
+//*
+// Allows you to specify a block of styles that will apply only to the demo
+// container for `$component`. If you are simply trying to force a particular
+// height, use [`docks-demo-height`](@link). If you are trying to set a custom
+// background color, use [`docks-demo-background`](@link). If you are trying to
+// remove the horizontal padding on a component's demo, use
+// [`docks-demo-no-padding`](@link). Use this mixin only for more advanced
+// styling concerns.
+//
+// @param {String} $component - The exact name of the component you wish to
+// add custom styling for (in most cases, this is the component's class name,
+// without the leading `"."`).
+//
+// @example
+// +docks-demo-styles(button)
+//   text-align: center
+
+=docks-demo-styles($component)
+  #demo__section--#{$component}
+    @content

data/assets/styles/scss/pattern-library-helpers.scss

@@ -0,0 +1,99 @@
+//*
+// @pattern Pattern Library Helpers
+// @author Chris Sauve (github: lemonmade)
+//
+// This file provides a set of helpers that allow you to provide custom style
+// overrides for components in demos. Please use these helpers in place of
+// custom selectors whenever possible — if the internal mechanisms the generator
+// uses to create these demos is ever changed, these helpers will be updated to
+// reflect the new selectors that are needed.
+
+//*
+// Forces the height of the passed `$component` demo to be at least `$height`.
+// Demos of some components may not respond properly to automatically
+// calculating their height. For example, absolutely-positioned dropdowns do
+// not cause the height of their container to increase, but we may want some
+// extra vertical space for them to appear into. This mixin allows you to
+// force a particular demo to have at least the passed height.
+//
+// @param {String} $component - The exact name of the component you wish to
+// forcibly size (in most cases, this is the component's class name, without
+// the leading `"."`).
+//
+// @param {Number} $height - The height you wish to force the component demo
+// to be. This number should have some units, the choice of which is left to
+// you.
+//
+// @example
+// @include docks-demo-height(dropdown, 10em);
+
+@mixin docks-demo-height($component, $height) {
+  #demo__section--#{$component} > .demo__content {
+    min-height: #{$height} !important;
+  }
+}
+
+//*
+// Forces the background of the demo for `$component` to be `$color`. You may
+// wish to use this in cases where an element typically appears on a background
+// color that is not the default for the way they are presented in demos (the
+// default theme displays these on a pure white background).
+//
+// @param {String} $component - The exact name of the component you wish to
+// forcibly set the background color for (in most cases, this is the component's
+// class name, without the leading `"."`).
+//
+// @param {Color} $color - The background color you want.
+//
+// @example
+// @include docks-demo-background(button--light, rgb(50, 50, 50));
+
+@mixin docks-demo-background($component, $color) {
+  #demo__section--#{$component} {
+    background-color: #{$color} !important;
+  }
+}
+
+//*
+// Forces the demo container for `$component` to have no horizontal padding.
+// The default theme provides this padding since, in general, it is more
+// aesthetically pleasing to do so. This may not, however, work for all your
+// components, in which case you can use this mixin.
+//
+// @param {String} $component - The exact name of the component you wish to
+// remove padding for (in most cases, this is the component's class name,
+// without the leading `"."`).
+//
+// @example
+// @include docks-demo-no-padding(grid);
+
+@mixin docks-demo-no-padding($component) {
+  #demo__section--#{$component} {
+    padding-left: 0;
+    padding-right: 0;
+  }
+}
+
+//*
+// Allows you to specify a block of styles that will apply only to the demo
+// container for `$component`. If you are simply trying to force a particular
+// height, use [`docks-demo-height`](@link). If you are trying to set a custom
+// background color, use [`docks-demo-background`](@link). If you are trying to
+// remove the horizontal padding on a component's demo, use
+// [`docks-demo-no-padding`](@link). Use this mixin only for more advanced
+// styling concerns.
+//
+// @param {String} $component - The exact name of the component you wish to
+// add custom styling for (in most cases, this is the component's class name,
+// without the leading `"."`).
+//
+// @example
+// @include docks-demo-styles(button) {
+//   text-align: center;
+// }
+
+@mixin docks-demo-styles($component) {
+  #demo__section--#{$component} {
+    @content;
+  }
+}

data/assets/styles/stylus/pattern-library-helpers.styl

@@ -0,0 +1,90 @@
+//*
+// @pattern Pattern Library Helpers
+// @author Chris Sauve (github: lemonmade)
+//
+// This file provides a set of helpers that allow you to provide custom style
+// overrides for components in demos. Please use these helpers in place of
+// custom selectors whenever possible — if the internal mechanisms the generator
+// uses to create these demos is ever changed, these helpers will be updated to
+// reflect the new selectors that are needed.
+
+//*
+// Forces the height of the passed `component` demo to be at least `height`.
+// Demos of some components may not respond properly to automatically
+// calculating their height. For example, absolutely-positioned dropdowns do
+// not cause the height of their container to increase, but we may want some
+// extra vertical space for them to appear into. This mixin allows you to
+// force a particular demo to have at least the passed height.
+//
+// @param {String} component - The exact name of the component you wish to
+// forcibly size (in most cases, this is the component's class name, without
+// the leading `"."`).
+//
+// @param {Number} height - The height you wish to force the component demo
+// to be. This number should have some units, the choice of which is left to
+// you.
+//
+// @example
+// docks-demo-height(dropdown, 10em)
+
+docks-demo-height(component, height)
+  #demo__section--{component} > .demo__content
+    min-height height !important
+
+//*
+// Forces the background of the demo for `component` to be `color`. You may
+// wish to use this in cases where an element typically appears on a background
+// color that is not the default for the way they are presented in demos (the
+// default theme displays these on a pure white background).
+//
+// @param {String} component - The exact name of the component you wish to
+// forcibly set the background color for (in most cases, this is the component's
+// class name, without the leading `"."`).
+//
+// @param {Color} color - The background color you want.
+//
+// @example
+// docks-demo-background(button--light, rgb(50, 50, 50))
+
+docks-demo-background(component, color)
+  #demo__section--{component}
+    background-color color !important
+
+//*
+// Forces the demo container for `component` to have no horizontal padding.
+// The default theme provides this padding since, in general, it is more
+// aesthetically pleasing to do so. This may not, however, work for all your
+// components, in which case you can use this mixin.
+//
+// @param {String} component - The exact name of the component you wish to
+// remove padding for (in most cases, this is the component's class name,
+// without the leading `"."`).
+//
+// @example
+// docks-demo-no-padding(grid)
+
+docks-demo-no-padding(component)
+  #demo__section--{component}
+    padding-left 0
+    padding-right 0
+
+//*
+// Allows you to specify a block of styles that will apply only to the demo
+// container for `component`. If you are simply trying to force a particular
+// height, use [`docks-demo-height`](@link). If you are trying to set a custom
+// background color, use [`docks-demo-background`](@link). If you are trying to
+// remove the horizontal padding on a component's demo, use
+// [`docks-demo-no-padding`](@link). Use this mixin only for more advanced
+// styling concerns.
+//
+// @param {String} component - The exact name of the component you wish to
+// add custom styling for (in most cases, this is the component's class name,
+// without the leading `"."`).
+//
+// @example
+// +docks-demo-styles(button)
+//   text-align: center
+
+docks-demo-styles(component)
+  #demo__section--{component}
+    {block}

data/assets/templates/erb/demo.erb

@@ -0,0 +1,26 @@
+<div class="iframe" data-iframe-id="<%= id %>">
+  <div class="demo" data-iframe-id="<%= id %>">
+
+    <% if demo.kind_of?(Docks::Containers::Demo) %>
+      <% demo_variations = [demo.component] + demo.joint_variations %>
+      <% demo_variations.each do |variation| %>
+        <% name = variation.name %>
+
+        <section class="demo__section" data-name="<%= name %>" id="demo__section--<%= name %>">
+          <% unless demo_variations.length == 1 %>
+            <header class="demo__header">
+              <h2 class="badge badge--code"><%= name %></h2>
+            </header>
+          <% end %>
+
+          <div class="content"><%= variation.markup %></div>
+        </section>
+      <% end %>
+
+    <% else %>
+      <section class="demo__section">
+        <div class="content"><%= demo %></div>
+      </section>
+    <% end %>
+  </div>
+</div>

data/assets/templates/erb/layouts/demo.erb

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <%= docks_stylesheet(:demo) %>
+    <%= compiled_style_tags %>
+    <script src="https://code.jquery.com/jquery-1.11.2.min.js"></script>
+  </head>
+
+  <body>
+    <%= docks_icons %>
+
+    <div class="wrapper"><%= yield %></div>
+
+    <%= docks_javascript(:demo) %>
+    <%= compiled_script_tags %>
+  </body>
+</html>

data/assets/templates/erb/layouts/pattern.erb

@@ -0,0 +1,76 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <%= docks_stylesheet %>
+    <%= compiled_style_tags %>
+    <script src="https://code.jquery.com/jquery-1.11.2.min.js"></script>
+  </head>
+
+  <body>
+    <%= docks_icons %>
+
+    <div class="page">
+      <div class="page__sidebar">
+        <%= render "sidebar" %>
+      </div>
+
+      <div class="page__content">
+        <div class="vertical-stack">
+          <div class="vertical-stack__item vertical-stack__item--fixed">
+            <div class="page-header">
+              <div class="grid grid--vertically-centered">
+                <div class="grid__item grid__item--no-flex">
+                  <button class="sidebar__toggler">
+                    <span class="helper--visually-hidden">Toggle Sidebar</span>
+                    <div class="icon icon--action icon--hamburger">
+                      <div class="icon--hamburger__slice"></div>
+                    </div>
+                  </button>
+                </div>
+
+                <div class="grid__item">
+                  <h1 class="type type--heading type--heading-1"><%= @pattern.title %></h1>
+                </div>
+
+                <% if has_github? %>
+                  <div class="popover__container">
+                    <button class="docks-button docks-button--dark">
+                      Github
+                      <i class="icon icon--disclosure"></i>
+                    </button>
+
+                    <% docks_popover do %>
+                      <div class="list">
+                        <a href="<%= "#{github_root_url}/issues/new?body=#{url_encode(github_issue_message)}" %>" target="_blank" class="list__item">File an issue</a>
+
+                        <div class="list__group">
+                          <h4 class="type type--heading type--heading-4">View source</h4>
+                          <% relative_pattern_files.each do |file| %>
+                            <a href="<%= github_url(file) %>" target="_blank" class="list__item type--code"><%= File.basename(file) %></a>
+                          <% end %>
+                        </div>
+                      </div>
+                    <% end %>
+                  </div>
+                <% end %>
+              </div>
+            </div>
+          </div>
+
+          <div class="vertical-stack__item">
+            <main class="scroll-container"><%= yield %></main>
+          </div>
+        </div>
+
+        <%= docks_xray %>
+      </div>
+    </div>
+
+    <script type="text/javascript">
+      window.pattern = <%= json_escape(@pattern.to_json) %>;
+    </script>
+
+    <%= docks_javascript %>
+    <%= compiled_script_tags %>
+  </body>
+</html>

data/assets/templates/erb/partials/sidebar.erb

@@ -0,0 +1,124 @@
+<nav class="sidebar">
+  <div class="vertical-stack">
+    <div class="vertical-stack__item vertical-stack__item--fixed">
+      <header class="page-header">
+        <div class="grid grid--vertically-centered">
+          <div class="grid__item">
+            <label class="label helper--visually-hidden" for="search">Search</label>
+            <div class="field field--text">
+              <div class="field__icon">
+                <%= docks_icon(:search, size: :medium) %>
+              </div>
+              <input id="search" type="search" class="field__input" data-filters="#list--patterns, #list--this-pattern" data-filter-attribute="contents" placeholder="Search">
+            </div>
+          </div>
+
+          <div class="grid__item grid__item--no-flex">
+            <div class="popover__container">
+              <%= docks_icon :eye, size: :large, color: :gray_darker %>
+
+              <% docks_popover do |popover| %>
+                <% popover.pane do %>
+                  <div class="field field--switch">
+                    <input class="field__switch" type="checkbox" id="private-toggle" data-filters="#list--this-pattern, #symbols--structure, #symbols--behavior" data-filter-attribute="data-private" data-checked-value="true|false">
+                    <label class="label" for="private-toggle">Show private symbols</label>
+                  </div>
+                <% end %>
+              <% end %>
+            </div>
+          </div>
+        </div>
+      </header>
+    </div>
+
+    <div class="vertical-stack__item">
+      <% unless @pattern.symbols.empty? %>
+        <div class="list" id="list--this-pattern" data-filter-items=".list__item">
+          <%
+            symbol_contents = { "structure" => @pattern.has_structure?, "behavior" => @pattern.has_behavior? }
+            has_both = symbol_contents["structure"] && symbol_contents["behavior"]
+          %>
+
+          <h3 class="type type--heading type--heading-3">This Pattern</h3>
+          <% %w(structure behavior).each do |group| %>
+            <% if symbol_contents[group] %>
+              <% if group == "structure" && !(demos = @pattern.demos).empty? %>
+                <div class="list__group">
+                  <h4 class="type type--heading type--heading-4">Components</h4>
+                  <% demos.each do |demo| %>
+                    <a class="list__item type--code" href="#<%= demo.component.symbol_id %>" data-private="<%= demo.component.private? %>"><%= demo.name %></a>
+                  <% end %>
+                </div>
+              <% end %>
+
+              <% if group == "behavior" && !(factories = @pattern.factories).empty? %>
+                <div class="list__group">
+                  <h4 class="type type--heading type--heading-4">Factories</h4>
+                  <% factories.each do |factory| %>
+                    <a class="list__item type--code" href="#<%= factory.symbol_id %>" data-private="<%= factory.private? %>"><%= factory.name %></a>
+
+                    <% factory.static_properties.each do |prop| %>
+                      <a href="#<%= prop.symbol_id %>" class="list__item list__item--indented type--code" data-private="<%= prop.private? %>">.<%= prop.name %></a>
+                    <% end %>
+
+                    <% factory.static_methods.each do |meth| %>
+                      <a href="#<%= meth.symbol_id %>" class="list__item list__item--indented type--code" data-private="<%= meth.private? %>">.<%= meth.name %>()</a>
+                    <% end %>
+
+                    <% factory.instance_properties.each do |prop| %>
+                      <a href="#<%= prop.symbol_id %>" class="list__item list__item--indented type--code" data-private="<%= prop.private? %>">#<%= prop.name %></a>
+                    <% end %>
+
+                    <% factory.instance_methods.each do |meth| %>
+                      <a href="#<%= meth.symbol_id %>" class="list__item list__item--indented type--code" data-private="<%= meth.private? %>">#<%= meth.name %>()</a>
+                    <% end %>
+                  <% end %>
+                </div>
+              <% end %>
+
+              <% %w(variable function mixin).each do |type| %>
+                <%
+                  symbol_options = {}
+                  symbol_options[group == "behavior" ? :include : :exclude] = Docks::Types::Languages::SCRIPT
+                  symbols = @pattern.send(type.pluralize.to_sym, symbol_options)
+                  unless symbols.empty?
+                %>
+                  <div class="list__group">
+                    <h4 class="type type--heading type--heading-4"><%= type.pluralize.capitalize %></h4>
+                    <% symbols.each do |symbol| %>
+                      <a class="list__item type--code" href="#<%= symbol.symbol_id %>" data-private="<%= symbol.private? %>"><%= symbol.name %></a>
+
+                      <% symbol.methods.each do |meth| %>
+                        <a href="#<%= meth.symbol_id %>" class="list__item list__item--indented type--code" data-private="<%= meth.private? %>">.<%= meth.name %>()</a>
+                      <% end %>
+
+                      <% symbol.properties.each do |prop| %>
+                        <a href="#<%= prop.symbol_id %>" class="list__item list__item--indented type--code" data-private="<%= prop.private? %>">.<%= prop.name %></a>
+                      <% end %>
+                    <% end %>
+                  </div>
+                <% end %>
+              <% end %>
+            <% end %>
+          <% end %>
+        </div>
+      <% end %>
+
+      <div class="list" id="list--patterns" data-filter-items=".list__item">
+        <h3 class="type type--heading type--heading-3">Library</h3>
+        <% @pattern_library.groups do |group, patterns| %>
+          <div class="list__group">
+            <h4 class="type type--heading type--heading-4"><%= group.pluralize %></h4>
+
+            <% patterns.sort { |one, two| one.name <=> two.name  }.each do |pattern| %>
+              <% active_pattern = pattern.name == @pattern.name %>
+              <a class="list__item<%= " list__item--is-active" if active_pattern %>" href="<%= active_pattern ? "javascript:" : docks_path(pattern.name) %>">
+                <%= pattern.title %>
+              </a>
+            <% end %>
+          </div>
+        <% end %>
+      </div>
+    </div>
+  </div>
+</nav>

data/assets/templates/erb/partials/symbols/class.erb

@@ -0,0 +1 @@
+<%= render(partial: "symbols/factory", locals: { factory: klass }) %>

data/assets/templates/erb/partials/symbols/demo.erb

@@ -0,0 +1,40 @@
+<section class="section" id="<%= demo.component.symbol_id %>" data-private="<%= demo.component.private? %>">
+  <header class="content">
+    <div class="grid">
+      <div class="grid__item">
+        <h3 class="type type--heading type--heading-2">
+          <% if title = demo.component.title %>
+            <%= title %>
+          <% else %>
+            <span class="type--code"><%= demo.component.name %></span>
+          <% end %>
+        </h3>
+      </div>
+
+      <div class="grid__item grid__item--no-flex">
+        <div class="docks-button__container">
+          <div class="docks-button" data-xray-trigger="<%= demo.name %>">x-ray</div>
+        </div>
+      </div>
+    </div>
+  </header>
+
+    <%
+      markup = render(inline: (demo.component.markup || demo.component.helper), layout: false)
+      code_details = []
+      code_details << { code: demo.component.helper, language: "erb", label: "Helper" } unless demo.component.helper.nil?
+      code_details << { code: markup, language: "html", label: "Markup" }
+      options = [demo.name].concat demo.joint_variations.map { |variant| variant.name }
+    %>
+
+    <%= docks_code_block(code: code_details, hideable?: true, full_width?: true, hidden?: true, options: options, id: demo.name, demo: demo) %>
+    <%#= docks_toggle_container variations: demo.select_variations(group_by_component: true), base_class: demo.component.name %>
+
+    <% if demo.component.description %>
+      <div class="content">
+        <div class="type-container">
+          <%= demo.component.description %>
+        </div>
+      </div>
+    <% end %>
+  </section>

data/assets/templates/erb/partials/symbols/factory.erb

@@ -0,0 +1,70 @@
+<div class="content content--extra-vertical-spacing">
+  <div class="section" id="<%= factory.symbol_id %>" data-private="<%= factory.private? %>">
+    <h2 class="type type--heading type--heading-2 type--heading-bordered">
+      <span class="type--code"><%= factory.name %></span>
+    </h2>
+
+    <div class="type-container"><%= factory.description %></div>
+
+    <%= docks_code_block(code: factory.signature, language: factory.source.language_code) %>
+
+    <% unless (params = factory.fetch(:params, [])).empty? %>
+      <h4 class="type type--heading type--heading-4">Parameters</h4>
+
+      <% params.each do |param| %>
+        <h5 class="type type--heading type--heading-5">
+          <span class="type--code"><%= param.name %></span>
+          <span class="badge"><%= param.types.first.name %><%= "[]" if param.types.first.array %></span>
+
+          <% if param.multiple %>
+            <span class="badge">Multiple</span>
+          <% end %>
+        </h5>
+
+        <div class="type-container type-container--small"><%= param.description %></div>
+
+        <% unless (properties = param.properties || []).empty? %>
+          <% docks_table do %>
+            <thead class="table__header">
+              <tr class="table__row">
+                <th class="table__cell">Name</th>
+                <th class="table__cell">Description</th>
+                <th class="table__cell">Types</th>
+                <th class="table__cell table__cell--centered">Default</th>
+              </tr>
+            </thead>
+
+            <tbody class="table__body">
+              <% properties.each do |property| %>
+                <tr class="table__row">
+                  <td class="table__cell"><code class="type--code"><%= property.name %></code></td>
+                  <td class="table__cell">
+                    <div class="type-container type-container--small"><%= property.description %></div>
+                  </td>
+                  <td class="table__cell"><%= (type = property.types.try(:first)) ? "<span class='type--code'>#{type}</span>".html_safe : "Anything" %></td>
+                  <td class="table__cell table__cell--centered"><%= (default = property.default) ? "<span class='type--code'>#{default}</span>".html_safe : "&mdash;".html_safe %></td>
+                </tr>
+              <% end %>
+            </tbody>
+          <% end %>
+        <% end %>
+      <% end %>
+    <% end %>
+
+    <% unless (examples = factory.fetch(:examples, [])).empty? %>
+      <h4 class="type type--heading type--heading-4"><%= "Example".pluralize(examples.length) %></h4>
+
+      <% examples.each do |example| %>
+        <%= docks_code_block(code: example.code, language: example.language, condensed?: true) %>
+      <% end %>
+    <% end %>
+  </div>
+
+  <% factory.properties.each do |property| %>
+    <%= render partial: "symbols/variable", locals: { variable: property } %>
+  <% end %>
+
+  <% factory.methods.each do |method| %>
+    <%= render partial: "symbols/function", locals: { function: method } %>
+  <% end %>
+</div>