From 776548bfd382d90e0604d16c542e347bebf52aab Mon Sep 17 00:00:00 2001 From: Gilad Gray Date: Tue, 14 Mar 2017 17:28:55 -0700 Subject: [PATCH] [DM] KSS for CSS examples (#813) * update scss & md docs files - **scss files:** make them all valid KSS blocks again by adding header and reference. references are now reflective of the CSS class being documented. - **md files:** add `@css reference` tags in all the CSS API sections * documentalist@0.0.3 * css tag handler brings back markup & modifiers! * :recycle: major refactor to sections.scss a new function `reference()` to target these new KSS examples. refactored as many selectors as I could, and removed a bunch of obsolete ones. docs changes: * move checkbox "Inline controls" section * bring back button-group page, unwrap control-group markup * update typography docs for kss --- gulp/docs.js | 62 +++-- package.json | 2 +- packages/core/src/_typography.scss | 75 ++--- .../components/breadcrumbs/_breadcrumbs.scss | 4 + .../src/components/breadcrumbs/breadcrumbs.md | 2 + .../src/components/button/_button-group.scss | 12 + .../core/src/components/button/_button.scss | 18 +- .../src/components/button/button-group.md | 6 + packages/core/src/components/button/button.md | 8 + .../core/src/components/callout/_callout.scss | 4 + .../core/src/components/callout/callout.md | 2 + packages/core/src/components/card/_card.scss | 8 + packages/core/src/components/card/card.md | 4 + packages/core/src/components/components.md | 2 +- .../core/src/components/dialog/_dialog.scss | 4 + packages/core/src/components/dialog/dialog.md | 2 + .../src/components/forms/_control-group.scss | 86 +++--- .../core/src/components/forms/_controls.scss | 16 ++ .../src/components/forms/_file-upload.scss | 4 + .../src/components/forms/_form-group.scss | 4 + .../src/components/forms/_input-group.scss | 4 + .../core/src/components/forms/_input.scss | 12 + .../core/src/components/forms/_label.scss | 8 + .../core/src/components/forms/_select.scss | 8 + .../core/src/components/forms/checkbox.md | 13 + .../src/components/forms/control-group.md | 6 + .../core/src/components/forms/file-upload.md | 2 + .../core/src/components/forms/form-group.md | 2 + .../core/src/components/forms/input-group.md | 2 + packages/core/src/components/forms/input.md | 4 + packages/core/src/components/forms/label.md | 4 + packages/core/src/components/forms/radio.md | 2 + packages/core/src/components/forms/select.md | 4 + packages/core/src/components/forms/switch.md | 11 +- .../core/src/components/forms/text-area.md | 2 + packages/core/src/components/menu/_menu.scss | 8 + packages/core/src/components/menu/menu.md | 4 + .../core/src/components/navbar/_navbar.scss | 8 + packages/core/src/components/navbar/navbar.md | 4 + .../non-ideal-state/_non-ideal-state.scss | 4 + .../non-ideal-state/non-ideal-state.md | 2 + .../components/progress/_progress-bar.scss | 4 + .../src/components/progress/progress-bar.md | 2 + .../src/components/skeleton/_skeleton.scss | 6 + .../core/src/components/skeleton/skeleton.md | 2 + .../core/src/components/spinner/_spinner.scss | 4 + .../core/src/components/spinner/spinner.md | 2 + .../core/src/components/table/_table.scss | 4 + packages/core/src/components/table/table.md | 2 + packages/core/src/components/tabs/_tabs.scss | 4 + packages/core/src/components/tabs/tabs.md | 2 + packages/core/src/components/tabs2/tabs2.md | 2 + packages/core/src/components/tag/_tag.scss | 8 + packages/core/src/components/tag/tag.md | 4 + packages/core/src/components/tree/_tree.scss | 4 + packages/core/src/components/tree/tree.md | 2 + packages/core/src/docs/typography.md | 126 ++------- packages/docs/src/common/cssExample.tsx | 39 +++ packages/docs/src/common/propsStore.tsx | 10 +- .../docs/src/components/modifierTable.tsx | 8 +- packages/docs/src/components/page.tsx | 2 +- packages/docs/src/components/styleguide.tsx | 2 +- packages/docs/src/index.tsx | 15 +- packages/docs/src/styles/_sections.scss | 262 +++++++----------- 64 files changed, 534 insertions(+), 421 deletions(-) create mode 100644 packages/docs/src/common/cssExample.tsx diff --git a/gulp/docs.js b/gulp/docs.js index ffdf57c9cb..ce77edd198 100644 --- a/gulp/docs.js +++ b/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 . and remove old 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 . and remove old 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 diff --git a/package.json b/package.json index b4e0b9e87d..06e85aae2f 100644 --- a/package.json +++ b/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", diff --git a/packages/core/src/_typography.scss b/packages/core/src/_typography.scss index d5633f9595..a86be5815b 100644 --- a/packages/core/src/_typography.scss +++ b/packages/core/src/_typography.scss @@ -37,15 +37,12 @@ small { /* Fonts -Blueprint does not include any fonts of its own; it will use the default sans-serif operating system -font. We provide a class to use the default monospace font instead. - Markup:
Blueprint components react overlay date picker.
.pt-monospace-text - Use a monospace font (ideal for code) -Styleguide typography.fonts +Styleguide fonts */ .pt-monospace-text { @@ -63,7 +60,7 @@ Markup:
H5 heading
H6 heading
-Styleguide typography.headings +Styleguide headings */ $headers: ( @@ -89,18 +86,13 @@ $headers: ( /* UI text -The base font size for Blueprint web applications is 14px. This should be the default type size -for most short strings of text which are not headings or titles. If you wish to reset some -element's font size and line height to the default base styles, use the `.pt-ui-text` class. -For longer running text, see [running text styles](#typography.running-text). - Markup:
Blueprint components react overlay date picker.
.pt-ui-text - Default UI text. This is applied to the document body as part of core styles. .pt-ui-text-large - Larger UI text. -Styleguide typography.ui-text +Styleguide pt-ui-text */ .pt-ui-text { @@ -115,33 +107,21 @@ Styleguide typography.ui-text /* Running text -Large blocks of _running text_ should use `.pt-running-text` styles. - -Note that `

` elements by default don't add any styles; they just inherit the base typography. -This is a conservative design; `

` elements are so ubiquitous that they're more often used for UI -text than long form text. It's up to the user to decide which blocks of text in an application -should get running text styles. - Markup: -

- Default paragraphs have base typography styles. -

-

- Running text is larger and more spaced out. -
- Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut - labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris - nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit - esse cillum dolore eu fugiat nulla pariatur. -
- Excepteur sint occaecat cupidatat non proident. -

-
- Includes support for strong, emphasized, and underlined text. - Also links! +
+

Longform text, such as rendered Markdown documents, benefit from additional spacing and slightly +large font size. Apply .pt-running-text to the parent element to adjust spacing for the following +elements:

+
    +
  • <p> tags have increased line-height and font size.
    • +
  • <h*> tag margins are adjusted to provide clear separation between sections in a document.
    • +
  • <ul> and <ol> tags receive [`.pt-list`](#typography.lists) styles for legibility.
    • +
+

New section

+

And another paragraph.

-Styleguide typography.running-text +Styleguide pt-running-text */ .pt-running-text { @@ -207,9 +187,6 @@ a { /* Preformatted text -Use `
` for code blocks, and `` for inline code. Note that `
` blocks will
-retain _all_ whitespace so you'll have to format the content accordingly.
-
 Markup:
 $ npm install
 
@@ -230,7 +207,7 @@ Markup:
     });
 }

 
-Styleguide typography.preformatted
+Styleguide preformatted
 */
 
 pre,
@@ -290,8 +267,6 @@ pre {
 /*
 Block quotes
 
-Block quotes are treated as running text.
-
 Markup:
 

   

@@ -308,7 +283,7 @@ Markup:
   

 

 
-Styleguide typography.blockquotes
+Styleguide blockquote
 */
 
 blockquote {
@@ -329,11 +304,6 @@ blockquote {
 /*
 Lists
 
-Blueprint provides a small amount of global styling and a few modifier classes for list elements.
-
-`