[DM] KSS for CSS examples

gulp/docs.js

@@ -26,41 +26,43 @@ module.exports = (blueprint, gulp, plugins) => {
     };
 
     gulp.task("docs-json", () => {
-        const docs = new dm.Documentalist({ renderer: text.renderer });
-        const contents = docs.documentGlobs("packages/core/src/**/*");
+        return dm.Documentalist.create({ renderer: text.renderer })
+            .use(".scss", new dm.KssPlugin())
+            .documentGlobs("packages/core/src/**/*")
+            .then((contents) => {
+                function nestChildPage(child, parent) {
+                    const originalRef = child.reference;
 
-        function nestChildPage(child, parent) {
-            const originalRef = child.reference;
+                    // update entry reference to include parent reference
+                    const nestedRef = dm.slugify(parent.reference, originalRef);
+                    child.reference = nestedRef;
 
-            // update entry reference to include parent reference
-            const nestedRef = dm.slugify(parent.reference, originalRef);
-            child.reference = nestedRef;
-
-            if (dm.isPageNode(child)) {
-                // rename nested pages to be <parent>.<child> and remove old <child> entry
-                contents.docs[nestedRef] = contents.docs[originalRef];
-                contents.docs[nestedRef].reference = nestedRef;
-                delete contents.docs[originalRef];
-                // recurse through page children
-                child.children.forEach((innerchild) => nestChildPage(innerchild, child));
-            }
-        }
+                    if (dm.isPageNode(child)) {
+                        // rename nested pages to be <parent>.<child> and remove old <child> entry
+                        contents.docs[nestedRef] = contents.docs[originalRef];
+                        contents.docs[nestedRef].reference = nestedRef;
+                        delete contents.docs[originalRef];
+                        // recurse through page children
+                        child.children.forEach((innerchild) => nestChildPage(innerchild, child));
+                    }
+                }
 
-        // navPage is used to construct the sidebar menu
-        const roots = dm.createNavigableTree(contents.docs, contents.docs[config.navPage]).children;
-        // nav page is not a real docs page so we can remove it from output
-        delete contents.docs[config.navPage];
-        roots.forEach((page) => {
-            if (dm.isPageNode(page)) {
-                page.children.forEach((child) => nestChildPage(child, page));
-            }
-        });
+                // navPage is used to construct the sidebar menu
+                const roots = dm.createNavigableTree(contents.docs, contents.docs[config.navPage]).children;
+                // nav page is not a real docs page so we can remove it from output
+                delete contents.docs[config.navPage];
+                roots.forEach((page) => {
+                    if (dm.isPageNode(page)) {
+                        page.children.forEach((child) => nestChildPage(child, page));
+                    }
+                });
 
-        // add a new field to data file with pre-processed layout tree
-        contents.layout = roots;
+                // add a new field to data file with pre-processed layout tree
+                contents.layout = roots;
 
-        return text.fileStream(filenames.data, JSON.stringify(contents, null, 2))
-            .pipe(gulp.dest(config.data));
+                return text.fileStream(filenames.data, JSON.stringify(contents, null, 2))
+                    .pipe(gulp.dest(config.data));
+            });
     });
 
     // create a JSON file containing latest released version of each project

package.json

@@ -34,7 +34,7 @@
     "better-handlebars": "github:wmeldon/better-handlebars",
     "chai": "3.5.0",
     "del": "2.2.2",
-    "documentalist": "0.0.2",
+    "documentalist": "0.0.3",
     "enzyme": "2.6.0",
     "gulp": "3.9.1",
     "gulp-concat": "2.6.0",

packages/core/src/components/breadcrumbs/_breadcrumbs.scss

@@ -8,6 +8,8 @@
 @import "../../common/variables";
 
 /*
+Breadcrumbs
+
 Markup:
 <ul class="pt-breadcrumbs">
   <li><a class="pt-breadcrumbs-collapsed" href="#"></a></li>
@@ -16,6 +18,8 @@ Markup:
   <li><a class="pt-breadcrumb" href="#">Folder three</a></li>
   <li><span class="pt-breadcrumb pt-breadcrumb-current">File</span></li>
 </ul>
+
+Styleguide pt-breadcrumbs
 */
 
 // shaving off 1px for perfect centering (... icon is 5px high)

packages/core/src/components/breadcrumbs/breadcrumbs.md

@@ -18,6 +18,8 @@ containing breadcrumbs that are collapsed due to layout constraints.
 * When adding another element (such as a [tooltip](#components.tooltip) or
 [popover](#components.popover)) to a breadcrumb, wrap it around the contents of the `li`.
 
+@css pt-breadcrumbs
+
 @## JavaScript API
 
 The `Breadcrumb` component is available in the __@blueprintjs/core__ package.

packages/core/src/components/button/_button-group.scss

@@ -9,6 +9,8 @@
 @import "./common";
 
 /*
+Button groups
+
 Markup:
 <div class="pt-button-group {{.modifier}}">
   <a class="pt-button pt-icon-database" tabindex="0" role="button">Queries</a>
@@ -38,6 +40,8 @@ Markup:
 .pt-large - Use large buttons
 .pt-minimal - Use minimal buttons. Note that these minimal buttons will not automatically
               truncate text in an ellipsis because of the divider line added in CSS.
+
+Styleguide pt-button-group
 */
 
 .pt-button-group {
@@ -150,6 +154,8 @@ Markup:
   }
 
   /*
+  Responsive
+
   Markup:
   <div class="pt-button-group pt-large pt-fill">
     <a class="pt-button pt-intent-primary pt-fixed" tabindex="0" role="button">Start</a>
@@ -164,6 +170,8 @@ Markup:
     <button class="pt-button pt-fill">Middle</button>
     <button class="pt-button pt-icon-arrow-right"></button>
   </div>
+
+  Styleguide pt-button-group.pt-fill
   */
 
   &.pt-fill {
@@ -176,6 +184,8 @@ Markup:
   }
 
   /*
+  Vertical button groups
+
   Markup:
   <div class="pt-button-group pt-vertical">
     <a class="pt-button pt-icon-search-template" role="button" tabindex="0"></a>
@@ -194,6 +204,8 @@ Markup:
     <button type="button" class="pt-button pt-intent-primary pt-icon-media pt-active">Media</button>
     <button type="button" class="pt-button pt-intent-primary pt-icon-link">Sources</button>
   </div>
+
+  Styleguide pt-button-group.pt-vertical
   */
 
   &.pt-vertical {

packages/core/src/components/button/_button.scss

@@ -8,6 +8,8 @@
 @import "./common";
 
 /*
+Button
+
 Markup:
 <a role="button" class="pt-button {{.modifier}}" {{:modifier}} tabindex="0">Anchor</a>
 <button type="button" class="pt-button pt-icon-add {{.modifier}}" {{:modifier}}>Button</button>
@@ -21,8 +23,9 @@ Markup:
 .pt-active - Active appearance
 .pt-large - Larger size
 .pt-fill - Fill parent container
-*/
 
+Styleguide pt-button
+*/
 .pt-button {
   @include pt-button-base();
   @include pt-button-height($pt-button-height);
@@ -70,13 +73,16 @@ Markup:
   }
 
   /*
+  Buttons with icons
+
   Markup:
   <button type="button" class="pt-button pt-icon-add">Default button</button>
   <button type="button" class="pt-button pt-icon-refresh"></button>
   <button type="button" class="pt-button pt-large pt-icon-add">Large button</button>
   <button type="button" class="pt-button pt-large pt-icon-refresh"></button>
-  */
 
+  Styleguide pt-button.pt-icon
+  */
   &[class*="pt-icon-"]::before {
     @include pt-icon();
 
@@ -85,6 +91,8 @@ Markup:
   }
 
   /*
+  Advanced icon usage
+
   Markup:
   <button type="button" class="pt-button pt-intent-success">
     Next step
@@ -104,6 +112,8 @@ Markup:
     upload.txt
     <span class="pt-icon-standard pt-icon-cross pt-align-right"></span>
   </button>
+
+  Styleguide pt-button.pt-icon-advanced
   */
 
   #{$icon-classes} {
@@ -154,6 +164,8 @@ Markup:
   }
 
   /*
+  Minimal buttons
+
   Markup:
   <a role="button" class="pt-button pt-minimal {{.modifier}}" {{:modifier}} tabindex="0">Anchor</a>
   <button type="button" class="pt-button pt-minimal pt-icon-add {{.modifier}}" {{:modifier}}>Button</button>
@@ -163,6 +175,8 @@ Markup:
   .pt-intent-success - Success intent
   .pt-intent-warning - Warning intent
   .pt-intent-danger - Danger intent
+
+  Styleguide pt-button.pt-minimal
   */
 
   &.pt-minimal {

packages/core/src/components/button/button-group.md

@@ -9,6 +9,8 @@ You can apply sizing directly on the button group container element.
 
 You should implement interactive segmented controls as button groups.
 
+@css pt-button-group
+
 @### Responsive button groups
 
 Add the class `pt-fill` to a button group to make all buttons expand equally to fill the
@@ -20,6 +22,8 @@ to expand it to fill the available space while other buttons retain their origin
 
 You can adjust the specific size of a button with the `flex-basis` CSS property.
 
+@css pt-button-group.pt-fill
+
 @### Vertical button groups
 
 Add the class `pt-vertical` to create a vertical button group. The buttons in a vertical
@@ -28,3 +32,5 @@ group all have the same size as the widest button in the group.
 Add the modifier class `pt-align-left` to left-align all button text and icons.
 
 You can also combine vertical groups with the `pt-fill` and `pt-minimal` class modifiers.
+
+@css pt-button-group.pt-vertical

packages/core/src/components/button/button.md

@@ -15,11 +15,15 @@ focusable by default.
 user from focusing them by pressing <kbd class="pt-key">tab</kbd> on the keyboard.
 - Note that `<a>` tags do not respond to the `:disabled` attribute; use `.pt-disabled` instead.
 
+@css pt-button
+
 @### Buttons with icons
 
 Add an icon before the button text with `pt-icon-*` classes.
 You _do not_ need to include an icon sizing class.
 
+@css pt-button.pt-icon
+
 @### Advanced icon layout
 
 You can use a `pt-icon-*` class on a button to add a single icon before the button
@@ -28,6 +32,8 @@ Add multiple icons to the same button, or move icons after the text.
 
 To adjust margins on right-aligned icons, add the class `pt-align-right` to the icon.
 
+@css pt-button.pt-icon-advanced
+
 @### Minimal buttons
 
 For a subtler button that appears to fade into the UI, add the `.pt-minimal` modifier
@@ -36,6 +42,8 @@ except for `.pt-fill` (due to lack of visual affordances).
 
 Note that minimal buttons are _not supported_ in button groups at this time.
 
+@css pt-button.pt-minimal
+
 @## JavaScript API
 
 The `Button` and `AnchorButton` components are available in the __@blueprintjs/core__ package.

packages/core/src/components/callout/_callout.scss

@@ -7,6 +7,8 @@
 @import "../../common/variables";
 
 /*
+Callout
+
 Markup:
 <div class="pt-callout {{.modifier}}">
   <h5>Callout Heading</h5>
@@ -18,6 +20,8 @@ Markup:
 .pt-intent-warning - Warning intent
 .pt-intent-danger  - Danger intent
 .pt-icon-info-sign - With an icon
+
+Styleguide pt-callout
 */
 
 .pt-callout {

packages/core/src/components/callout/callout.md

@@ -10,3 +10,5 @@ heading, use the `<h5>` element.
 <div class="pt-callout pt-intent-primary pt-icon-info-sign">
     Note that the `<h5>` heading is entirely optional.
 </div>
+
+@css pt-callout

packages/core/src/components/card/_card.scss

@@ -6,6 +6,8 @@
 @import "../../common/variables";
 
 /*
+Cards
+
 Markup:
 <div class="pt-card {{.modifier}}">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus nec dapibus et mauris,
@@ -17,6 +19,8 @@ Markup:
 .pt-elevation-2 - Second. An even stronger shadow, moving on up.
 .pt-elevation-3 - Third. For containers overlaying content temporarily.
 .pt-elevation-4 - Fourth. The strongest shadow, usually for overlay containers on top of backdrops.
+
+Styleguide pt-card
 */
 
 $card-padding: $pt-grid-size * 2 !default;
@@ -66,6 +70,8 @@ $dark-elevation-shadows: (
 }
 
 /*
+Interactive cards
+
 Markup:
 <div class="docs-card-example">
   <div class="pt-card pt-elevation-0 pt-interactive">
@@ -81,6 +87,8 @@ Markup:
     <p>Stats of dataset completeness and reference data join percentages.</p>
   </div>
 </div>
+
+Styleguide pt-card.pt-interactive
 */
 
 .pt-card.pt-interactive {

packages/core/src/components/card/card.md

@@ -10,10 +10,14 @@ height in the UI.
 You can also use the `.pt-elevation-*` classes by themselves to apply shadows to any arbitrary
 element.
 
+@css pt-card
+
 @### Interactive cards
 
 Add the `.pt-interactive` modifier class to make a `.pt-card` respond to user interactions. When you
 hover over cards with this class applied, the mouse changes to a pointer and the elevation shadow on
 the card increases by two levels.
 
 Users expect an interactive card to be a single clickable unit.
+
+@css pt-card.pt-interactive

packages/core/src/components/components.md

@@ -173,12 +173,12 @@ Check out the [React API docs](https://facebook.github.io/react/docs/react-api.h
 @page alert
 @page breadcrumbs
 @page button
+@page button-group
 @page callout
 @page card
 @page collapse
 @page collapsible-list
 @page context-menu
-<!--@page datetime-->
 @page dialog
 @page editable-text
 @page forms