Merge pull request #12993 from twbs/mixin-table-of-contents

Mixin table of contents

less/mixins.less

@@ -3,8 +3,78 @@
 // --------------------------------------------------
 
 
+// Table of Contents
+//
 // Utilities
-// -------------------------
+// - Clearfix
+// - WebKit-style focus
+// - Center-align a block level element
+// - Sizing shortcuts
+// - Placeholder text
+// - Text overflow
+// - Requires inline-block or block for proper styling
+// - CSS image replacement
+//
+// CSS3 properties
+// - Single side border-radius
+// - Drop shadows
+// - Transitions
+// - Transformations
+// - Animations
+// - Backface visibility
+// - Prevent browsers from flickering when using CSS 3D transforms.
+// - Box sizing
+// - User select
+// - For selecting text on the page
+// - Resize anything
+// - CSS3 Content Columns
+// - Optional hyphenation
+// - Opacity
+//
+// Gradients
+// - Reset filters for IE
+// - Retina images
+// - Responsive image
+//
+// Component mixins
+// - Horizontal dividers
+// - Dividers (basically an hr) within dropdowns and nav lists
+// - Panels
+// - Alerts
+// - Tables
+// - List Groups
+// - Button variants
+// - Button sizes
+// - Pagination
+// - Labels
+// - Contextual backgrounds
+// - Typography
+// - Navbar vertical align
+// - Vertically center elements in the navbar
+// - Progress bars
+//
+// Responsive utilities
+//
+// Forms
+// - Form control focus state
+// - Form control sizing
+//
+// Grid system
+// - Centered container element
+// - Generate the extra small columns
+// - Generate the small columns
+// - Generate the medium columns
+// - Generate the large columns
+//
+// Framework grid generation
+// - Loop to generate grid all grid classes
+// - Form validation states
+// - Form control focus state
+
+
+
+// Utilities
+// --------------------------------------------------
 
 // Clearfix
 // Source: http://nicolasgallagher.com/micro-clearfix-hack/
@@ -91,7 +161,7 @@
 
 
 
-// CSS3 PROPERTIES
+// CSS3 properties
 // --------------------------------------------------
 
 // Single side border-radius
@@ -378,7 +448,7 @@
 
 
 
-// GRADIENTS
+// Gradients
 // --------------------------------------------------
 
 #gradient {
@@ -450,10 +520,10 @@
 
 
 // Retina images
-//
+// --------------------------------------------------
+
 // Short retina mixin for setting background-image and -size. Note that the
 // spelling of `min--moz-device-pixel-ratio` is intentional.
-
 .img-retina(@file-1x; @file-2x; @width-1x; @height-1x) {
   background-image: url("@{file-1x}");
 
@@ -470,10 +540,11 @@
 }
 
 
-// Responsive image
-//
-// Keep images from scaling beyond the width of their parents.
 
+// Responsive image
+// --------------------------------------------------
+
+// Keep images from scaling beyond the width of their parents.
 .img-responsive(@display: block) {
   display: @display;
   max-width: 100%; // Part 1: Set a maximum relative to the parent
@@ -481,11 +552,12 @@
 }
 
 
-// COMPONENT MIXINS
+
+// Component mixins
 // --------------------------------------------------
 
 // Horizontal dividers
-// -------------------------
+//
 // Dividers (basically an hr) within dropdowns and nav lists
 .nav-divider(@color: #e5e5e5) {
   height: 1px;
@@ -495,7 +567,6 @@
 }
 
 // Panels
-// -------------------------
 .panel-variant(@border; @heading-text-color; @heading-bg-color; @heading-border) {
   border-color: @border;
 
@@ -516,7 +587,6 @@
 }
 
 // Alerts
-// -------------------------
 .alert-variant(@background; @border; @text-color) {
   background-color: @background;
   border-color: @border;
@@ -531,7 +601,6 @@
 }
 
 // Tables
-// -------------------------
 .table-row-variant(@state; @background) {
   // Exact selectors below required to override `.table-striped` and prevent
   // inheritance to nested tables.
@@ -559,7 +628,6 @@
 }
 
 // List Groups
-// -------------------------
 .list-group-item-variant(@state; @background; @color) {
   .list-group-item-@{state} {
     color: @color;
@@ -587,7 +655,7 @@
 }
 
 // Button variants
-// -------------------------
+//
 // Easily pump out default styles, as well as :hover, :focus, :active,
 // and disabled options for all buttons
 .button-variant(@color; @background; @border) {
@@ -629,7 +697,6 @@
 }
 
 // Button sizes
-// -------------------------
 .button-size(@padding-vertical; @padding-horizontal; @font-size; @line-height; @border-radius) {
   padding: @padding-vertical @padding-horizontal;
   font-size: @font-size;
@@ -638,7 +705,6 @@
 }
 
 // Pagination
-// -------------------------
 .pagination-size(@padding-vertical; @padding-horizontal; @font-size; @border-radius) {
   > li {
     > a,
@@ -662,7 +728,6 @@
 }
 
 // Labels
-// -------------------------
 .label-variant(@color) {
   background-color: @color;
   &[href] {
@@ -674,7 +739,6 @@
 }
 
 // Contextual backgrounds
-// -------------------------
 .bg-variant(@color) {
   background-color: @color;
   a&:hover {
@@ -683,7 +747,6 @@
 }
 
 // Typography
-// -------------------------
 .text-emphasis-variant(@color) {
   color: @color;
   a&:hover {
@@ -692,7 +755,7 @@
 }
 
 // Navbar vertical align
-// -------------------------
+//
 // Vertically center elements in the navbar.
 // Example: an element has a height of 30px, so write out `.navbar-vertical-align(30px);` to calculate the appropriate top margin.
 .navbar-vertical-align(@element-height) {
@@ -701,7 +764,6 @@
 }
 
 // Progress bars
-// -------------------------
 .progress-bar-variant(@color) {
   background-color: @color;
   .progress-striped & {
@@ -710,7 +772,7 @@
 }
 
 // Responsive utilities
-// -------------------------
+//
 // More easily include all the states for responsive-utilities.less.
 .responsive-visibility() {
   display: block !important;
@@ -725,8 +787,97 @@
 }
 
 
-// Grid System
+
-// -----------
+// Form validation states
+//
+// Used in forms.less to generate the form validation CSS for warnings, errors,
+// and successes.
+
+.form-control-validation(@text-color: #555; @border-color: #ccc; @background-color: #f5f5f5) {
+  // Color the label and help text
+  .help-block,
+  .control-label,
+  .radio,
+  .checkbox,
+  .radio-inline,
+  .checkbox-inline  {
+    color: @text-color;
+  }
+  // Set the border and box shadow on specific inputs to match
+  .form-control {
+    border-color: @border-color;
+    .box-shadow(inset 0 1px 1px rgba(0,0,0,.075)); // Redeclare so transitions work
+    &:focus {
+      border-color: darken(@border-color, 10%);
+      @shadow: inset 0 1px 1px rgba(0,0,0,.075), 0 0 6px lighten(@border-color, 20%);
+      .box-shadow(@shadow);
+    }
+  }
+  // Set validation states also for addons
+  .input-group-addon {
+    color: @text-color;
+    border-color: @border-color;
+    background-color: @background-color;
+  }
+  // Optional feedback icon
+  .form-control-feedback {
+    color: @text-color;
+  }
+}
+
+
+
+// Forms
+// --------------------------------------------------
+
+// Form control focus state
+//
+// Generate a customized focus state and for any input with the specified color,
+// which defaults to the `@input-focus-border` variable.
+//
+// We highly encourage you to not customize the default value, but instead use
+// this to tweak colors on an as-needed basis. This aesthetic change is based on
+// WebKit's default styles, but applicable to a wider range of browsers. Its
+// usability and accessibility should be taken into account with any change.
+//
+// Example usage: change the default blue border and shadow to white for better
+// contrast against a dark gray background.
+.form-control-focus(@color: @input-border-focus) {
+  @color-rgba: rgba(red(@color), green(@color), blue(@color), .6);
+  &:focus {
+    border-color: @color;
+    outline: 0;
+    .box-shadow(~"inset 0 1px 1px rgba(0,0,0,.075), 0 0 8px @{color-rgba}");
+  }
+}
+
+// Form control sizing
+//
+// Relative text size, padding, and border-radii changes for form controls. For
+// horizontal sizing, wrap controls in the predefined grid classes. `<select>`
+// element gets special love because it's special, and that's a fact!
+.input-size(@input-height; @padding-vertical; @padding-horizontal; @font-size; @line-height; @border-radius) {
+  height: @input-height;
+  padding: @padding-vertical @padding-horizontal;
+  font-size: @font-size;
+  line-height: @line-height;
+  border-radius: @border-radius;
+
+  select& {
+    height: @input-height;
+    line-height: @input-height;
+  }
+
+  textarea&,
+  select[multiple]& {
+    height: auto;
+  }
+}
+
+
+
+// Grid system
+// --------------------------------------------------
 
 // Centered container element
 .container-fixed() {
@@ -763,7 +914,6 @@
   right: percentage((@columns / @grid-columns));
 }
 
-
 // Generate the small columns
 .make-sm-column(@columns; @gutter: @grid-gutter-width) {
   position: relative;
@@ -792,7 +942,6 @@
   }
 }
 
-
 // Generate the medium columns
 .make-md-column(@columns; @gutter: @grid-gutter-width) {
   position: relative;
@@ -821,7 +970,6 @@
   }
 }
 
-
 // Generate the large columns
 .make-lg-column(@columns; @gutter: @grid-gutter-width) {
   position: relative;
@@ -851,11 +999,12 @@
 }
 
 
+
 // Framework grid generation
-//
+// --------------------------------------------------
+
 // Used only by Bootstrap to generate the correct number of grid classes given
 // any value of `@grid-columns`.
-
 .make-grid-columns() {
   // Common styles for all sizes of grid columns, widths 1-12
   .col(@index) when (@index = 1) { // initial
@@ -942,86 +1091,3 @@
   .loop-grid-columns(@grid-columns, @class, push);
   .loop-grid-columns(@grid-columns, @class, offset);
 }
-
-// Form validation states
-//
-// Used in forms.less to generate the form validation CSS for warnings, errors,
-// and successes.
-
-.form-control-validation(@text-color: #555; @border-color: #ccc; @background-color: #f5f5f5) {
-  // Color the label and help text
-  .help-block,
-  .control-label,
-  .radio,
-  .checkbox,
-  .radio-inline,
-  .checkbox-inline  {
-    color: @text-color;
-  }
-  // Set the border and box shadow on specific inputs to match
-  .form-control {
-    border-color: @border-color;
-    .box-shadow(inset 0 1px 1px rgba(0,0,0,.075)); // Redeclare so transitions work
-    &:focus {
-      border-color: darken(@border-color, 10%);
-      @shadow: inset 0 1px 1px rgba(0,0,0,.075), 0 0 6px lighten(@border-color, 20%);
-      .box-shadow(@shadow);
-    }
-  }
-  // Set validation states also for addons
-  .input-group-addon {
-    color: @text-color;
-    border-color: @border-color;
-    background-color: @background-color;
-  }
-  // Optional feedback icon
-  .form-control-feedback {
-    color: @text-color;
-  }
-}
-
-// Form control focus state
-//
-// Generate a customized focus state and for any input with the specified color,
-// which defaults to the `@input-focus-border` variable.
-//
-// We highly encourage you to not customize the default value, but instead use
-// this to tweak colors on an as-needed basis. This aesthetic change is based on
-// WebKit's default styles, but applicable to a wider range of browsers. Its
-// usability and accessibility should be taken into account with any change.
-//
-// Example usage: change the default blue border and shadow to white for better
-// contrast against a dark gray background.
-
-.form-control-focus(@color: @input-border-focus) {
-  @color-rgba: rgba(red(@color), green(@color), blue(@color), .6);
-  &:focus {
-    border-color: @color;
-    outline: 0;
-    .box-shadow(~"inset 0 1px 1px rgba(0,0,0,.075), 0 0 8px @{color-rgba}");
-  }
-}
-
-// Form control sizing
-//
-// Relative text size, padding, and border-radii changes for form controls. For
-// horizontal sizing, wrap controls in the predefined grid classes. `<select>`
-// element gets special love because it's special, and that's a fact!
-
-.input-size(@input-height; @padding-vertical; @padding-horizontal; @font-size; @line-height; @border-radius) {
-  height: @input-height;
-  padding: @padding-vertical @padding-horizontal;
-  font-size: @font-size;
-  line-height: @line-height;
-  border-radius: @border-radius;
-
-  select& {
-    height: @input-height;
-    line-height: @input-height;
-  }
-
-  textarea&,
-  select[multiple]& {
-    height: auto;
-  }
-}